fix(im): remove unsupported feed group shortcuts

Remove the feed group list/query shortcut registration, implementation, tests, and skill references so the im domain no longer exposes unsupported feed group commands.

Keep the remaining im flag validation paths on typed error envelopes.

.golangci.yml

@@ -73,20 +73,20 @@ linters:
           - forbidigo
       # errs-typed-only enforced on paths already migrated to errs.NewXxxError.
       # Add a path when its migration is complete.
-      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/calendar/helpers\.go|shortcuts/drive/)
+      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/)
         text: errs-typed-only
         linters:
           - forbidigo
       # errs-no-bare-wrap enforced on paths fully migrated to typed final
       # errors. Scoped separately from errs-typed-only because cmd/auth/,
       # cmd/config/ still have residual fmt.Errorf and must not be caught.
-      - path-except: (shortcuts/drive/|shortcuts/calendar/helpers\.go|shortcuts/common/mcp_client\.go)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/|shortcuts/common/mcp_client\.go)
         text: errs-no-bare-wrap
         linters:
           - forbidigo
-      # errs-no-legacy-helper is drive-only: the shared helpers it bans are
-      # still used by other domains until their later migration phase.
-      - path-except: (shortcuts/drive/)
+      # errs-no-legacy-helper enforced on domains whose shared validation/save
+      # helpers have migrated to typed final errors.
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo
@@ -115,17 +115,15 @@ linters:
           msg: >-
             [errs-typed-only] use errs.NewXxxError(...) builder
             (see errs/types.go).
-        # ── legacy shared error helpers banned on drive ──
-        # These helpers internally produce legacy output.Err* shapes, so they
-        # are invisible to the errs-typed-only ban above. Drive has migrated its
-        # calls to typed errs.* (drive-local driveInputStatError / driveSaveError);
-        # this prevents reintroduction. Other domains still use the shared
-        # helpers (migrated globally in a later phase), so this is drive-scoped.
-        - pattern: (common\.FlagErrorf|common\.WrapInputStatError|common\.WrapSaveErrorByCategory)\b
+        # ── legacy shared error helpers banned on migrated domains ──
+        # These helpers emit legacy output.Err* / bare error shapes or drop
+        # typed metadata such as Param/Cause. Migrated domains must use typed
+        # common replacements or local typed helpers instead.
+        - pattern: (common\.FlagErrorf|common\.RejectDangerousChars|common\.WrapInputStatError|common\.WrapSaveErrorByCategory)\b
           msg: >-
-            [errs-no-legacy-helper] these shared helpers emit legacy output.Err*
-            shapes. Use the typed errs.NewXxxError builders or the drive-local
-            driveInputStatError / driveSaveError helpers (shortcuts/drive/drive_errors.go).
+            [errs-no-legacy-helper] these shared helpers emit legacy or
+            metadata-poor error shapes. Use typed common replacements, typed
+            errs.NewXxxError builders, or domain-local typed helpers.
         # ── bare error wraps banned on fully-typed paths ──
         - pattern: (fmt\.Errorf|errors\.New)\b
           msg: >-

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.48] - 2026-06-04
+
+### Features
+
+- **mail**: Preserve mailbox context in `+triage` output for public mailboxes (#1238)
+- **contact**: Add contact skill domain guidance (#1144)
+
+### Bug Fixes
+
+- **skills**: Use JSON skills list during update (#1251)
+
+### Documentation
+
+- **drive**: Refine lark-drive knowledge organize workflow (#1253)
+- **vc-agent**: Require explicit leave request (#1260)
+- **slides**: Add whiteboard element documentation and improve slide guidance (#1029)
+
 ## [v1.0.47] - 2026-06-03
 
 ### Features
@@ -1009,6 +1026,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.48]: https://github.com/larksuite/cli/releases/tag/v1.0.48
 [v1.0.47]: https://github.com/larksuite/cli/releases/tag/v1.0.47
 [v1.0.46]: https://github.com/larksuite/cli/releases/tag/v1.0.46
 [v1.0.45]: https://github.com/larksuite/cli/releases/tag/v1.0.45

cmd/cmdexample_catalog_test.go

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"sort"
+	"strings"
+)
+
+// universalFlags are accepted by every command (cobra auto-injects help; the
+// root injects version). They are never reported as unknown.
+var universalFlags = map[string]bool{"--help": true, "-h": true, "--version": true}
+
+// catalog is the source-of-truth command catalog: command path -> accepted flag
+// tokens. A path is the command words WITHOUT the "lark-cli" root prefix, e.g.
+// "contact +search-user". The root command is the empty path "".
+type catalog struct {
+	flagsByPath map[string]map[string]bool
+	group       map[string]bool // paths that are parent groups (have subcommands)
+	sorted      []string        // cached sorted paths for suggestCommand; invalidated on addCommand
+}
+
+func newCatalog() *catalog {
+	return &catalog{
+		flagsByPath: map[string]map[string]bool{},
+		group:       map[string]bool{},
+	}
+}
+
+// setGroup records whether path is a parent group (has subcommands). Leftover
+// words after a group node are unknown subcommands; after a leaf they are
+// positionals (e.g. "api GET /path").
+func (c *catalog) setGroup(path string, isGroup bool) {
+	if isGroup {
+		c.group[path] = true
+	}
+}
+
+func (c *catalog) isGroup(path string) bool { return c.group[path] }
+
+// addCommand registers a command path and the flags it accepts. Repeated calls
+// for the same path union the flag sets. flags are full tokens ("--query", "-q").
+func (c *catalog) addCommand(path string, flags []string) {
+	set := c.flagsByPath[path]
+	if set == nil {
+		set = map[string]bool{}
+		c.flagsByPath[path] = set
+	}
+	for _, f := range flags {
+		set[f] = true
+	}
+	c.sorted = nil // invalidate cached suggestion list
+}
+
+func (c *catalog) hasCommand(path string) bool {
+	_, ok := c.flagsByPath[path]
+	return ok
+}
+
+// hasFlag reports whether flag is accepted by command path (universal flags
+// always pass).
+func (c *catalog) hasFlag(path, flag string) bool {
+	if universalFlags[flag] {
+		return true
+	}
+	set := c.flagsByPath[path]
+	return set[flag]
+}
+
+// longestPrefix returns the longest known command path that is a prefix of
+// words, plus how many words it consumed. This separates real subcommands from
+// trailing positionals (e.g. "api GET /path" resolves to "api"). When words is
+// empty it falls back to the root command. ok=false means not even the first
+// word names a command.
+func (c *catalog) longestPrefix(words []string) (path string, n int, ok bool) {
+	if len(words) == 0 {
+		if c.hasCommand("") {
+			return "", 0, true
+		}
+		return "", 0, false
+	}
+	for i := len(words); i >= 1; i-- {
+		cand := strings.Join(words[:i], " ")
+		if c.hasCommand(cand) {
+			return cand, i, true
+		}
+	}
+	return "", 0, false
+}
+
+// paths returns all known command paths, sorted.
+func (c *catalog) paths() []string {
+	out := make([]string, 0, len(c.flagsByPath))
+	for p := range c.flagsByPath {
+		out = append(out, p)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// suggestCommand returns the known command path closest to want (small edit
+// distance), for error hints. Returns "" when nothing is reasonably close.
+func (c *catalog) suggestCommand(want string) string {
+	if c.sorted == nil {
+		c.sorted = c.paths() // built once after the catalog is fully populated
+	}
+	return closest(want, c.sorted)
+}
+
+// suggestFlag returns the flag of path closest to flag, for error hints.
+func (c *catalog) suggestFlag(path, flag string) string {
+	set := c.flagsByPath[path]
+	cands := make([]string, 0, len(set))
+	for f := range set {
+		cands = append(cands, f)
+	}
+	sort.Strings(cands)
+	return closest(flag, cands)
+}
+
+// closest returns the candidate with the smallest Levenshtein distance to want,
+// but only if that distance is within a tolerance scaled to want's length
+// (avoids absurd suggestions).
+func closest(want string, cands []string) string {
+	best := ""
+	bestD := 1 << 30
+	for _, cand := range cands {
+		d := levenshtein(want, cand)
+		if d < bestD {
+			bestD, best = d, cand
+		}
+	}
+	tol := len(want)/2 + 1
+	if bestD > tol {
+		return ""
+	}
+	return best
+}
+
+func levenshtein(a, b string) int {
+	ra, rb := []rune(a), []rune(b)
+	prev := make([]int, len(rb)+1)
+	for j := range prev {
+		prev[j] = j
+	}
+	for i := 1; i <= len(ra); i++ {
+		cur := make([]int, len(rb)+1)
+		cur[0] = i
+		for j := 1; j <= len(rb); j++ {
+			cost := 1
+			if ra[i-1] == rb[j-1] {
+				cost = 0
+			}
+			cur[j] = min(prev[j]+1, cur[j-1]+1, prev[j-1]+cost)
+		}
+		prev = cur
+	}
+	return prev[len(rb)]
+}

cmd/cmdexample_check_test.go

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import "strings"
+
+// Finding kinds.
+const (
+	unknownCommand = "unknown_command"
+	unknownFlag    = "unknown_flag"
+)
+
+// finding is a single mismatch between an example command reference and the
+// catalog.
+type finding struct {
+	line    int
+	raw     string
+	kind    string // unknownCommand | unknownFlag
+	path    string // resolved command path (unknownFlag) or attempted path (unknownCommand)
+	flag    string // offending flag (unknownFlag only)
+	suggest string // nearest known command/flag, "" if none close
+}
+
+// checkRefs validates refs against cat and returns all mismatches in order.
+func checkRefs(cat *catalog, refs []ref) []finding {
+	var out []finding
+	for _, r := range refs {
+		path, n, ok := cat.longestPrefix(r.words)
+		if !ok {
+			attempted := strings.Join(r.words, " ")
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownCommand,
+				path: attempted, suggest: cat.suggestCommand(attempted),
+			})
+			continue
+		}
+		// Leftover words after a group node are an unknown subcommand (e.g. a
+		// mistyped method like "batch_modify_message"). After a leaf they are
+		// positionals (e.g. "api GET /path"), so only groups trigger this.
+		if n < len(r.words) && cat.isGroup(path) {
+			attempted := strings.Join(r.words, " ")
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownCommand,
+				path: attempted, suggest: cat.suggestCommand(attempted),
+			})
+			continue
+		}
+		for _, f := range r.flags {
+			if cat.hasFlag(path, f) {
+				continue
+			}
+			out = append(out, finding{
+				line: r.line, raw: r.raw, kind: unknownFlag,
+				path: path, flag: f, suggest: cat.suggestFlag(path, f),
+			})
+		}
+	}
+	return out
+}

cmd/cmdexample_parse_test.go

@@ -0,0 +1,222 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"regexp"
+	"strings"
+)
+
+// ref is one lark-cli command reference extracted from a shortcut example.
+type ref struct {
+	line  int      // 1-based line number (the line where the command starts)
+	raw   string   // reconstructed command text, for error display
+	words []string // command words before the first flag (subcommand candidates)
+	flags []string // flag tokens used, e.g. "--query", "-q"
+}
+
+const cliToken = "lark-cli"
+
+// subcommandStart guards against false positives from prose: a real command's
+// first word is ASCII (a service name or a +shortcut). A token starting with
+// CJK / punctuation is treated as narration, not a command.
+var subcommandStart = regexp.MustCompile(`^[A-Za-z+]`)
+
+// shellStops are standalone tokens that terminate a command (pipes, redirects,
+// separators). Separators glued to a token (`get;`, `foo|`) are handled inline.
+var shellStops = map[string]bool{
+	"|": true, "||": true, "&&": true, "&": true, ";": true,
+	">": true, ">>": true, "<": true, "2>": true, "2>&1": true,
+}
+
+// wordTrailPunct is sentence / CJK punctuation that can cling to a command word
+// in prose ("auth login." / "auth login，"); stripped so the word still resolves
+// instead of being dropped as an unknown command or non-ASCII narration.
+const wordTrailPunct = `.,;:!?"')]}，。、；：！？）】」』`
+
+// parseRefs extracts every lark-cli command reference from text (a shortcut's
+// Tips line, which may embed an "Example: lark-cli ..." command). It is
+// deliberately format-agnostic: it keys on the "lark-cli" token whether it sits
+// in a ```bash fence, an inline `code` span, or bare prose. Backslash
+// line-continuations are joined first so a multi-line invocation is parsed as
+// one command; inline-code backticks and trailing # comments terminate it.
+func parseRefs(content string) []ref {
+	var refs []ref
+	lines := strings.Split(content, "\n")
+	for i := 0; i < len(lines); i++ {
+		lineNo := i + 1
+		logical := lines[i]
+		// Shell line continuation: a trailing backslash joins the next physical
+		// line. Without this, flags on the continuation lines of a multi-line
+		// `lark-cli ... \` example are never seen by the checker.
+		for endsWithBackslash(logical) && i+1 < len(lines) {
+			logical = strings.TrimRight(logical, " \t")
+			logical = logical[:len(logical)-1] // drop the trailing backslash
+			i++
+			logical += " " + lines[i]
+		}
+		refs = append(refs, parseLine(logical, lineNo)...)
+	}
+	return refs
+}
+
+func endsWithBackslash(s string) bool {
+	return strings.HasSuffix(strings.TrimRight(s, " \t"), `\`)
+}
+
+func parseLine(line string, lineNo int) []ref {
+	var refs []ref
+	rest := line
+	for {
+		idx := strings.Index(rest, cliToken)
+		if idx < 0 {
+			break
+		}
+		after := rest[idx+len(cliToken):]
+		beforeOK := idx == 0 || isBoundary(rest[idx-1])
+		afterOK := after == "" || isBoundary(after[0])
+		if beforeOK && afterOK {
+			if words, flags, raw, ok := parseCmd(after); ok {
+				refs = append(refs, ref{line: lineNo, raw: cliToken + raw, words: words, flags: flags})
+			}
+		}
+		rest = after
+	}
+	return refs
+}
+
+// parseCmd tokenizes the text following "lark-cli" into leading command words
+// (the subcommand path, up to the first flag) and flag tokens. It stops at a
+// shell separator (standalone or glued), an inline-code backtick, a comment, or
+// a placeholder/prose word. ok=false filters out non-commands.
+func parseCmd(after string) (words, flags []string, raw string, ok bool) {
+	// An inline code span ends at the next backtick; a command never spans one.
+	if i := strings.IndexByte(after, '`'); i >= 0 {
+		after = after[:i]
+	}
+	// Drop $(...) command substitutions so flags belonging to the inner command
+	// (e.g. `--data "$(jq -n --arg x ...)"`) are not mistaken for lark-cli flags.
+	after = stripCmdSubst(after)
+
+	var kept []string
+	inFlags := false
+	for _, orig := range strings.Fields(after) {
+		tok := orig
+		if shellStops[tok] || strings.HasPrefix(tok, "#") {
+			break
+		}
+		// A shell separator glued to a token ends the command mid-token
+		// ("get;", "foo|next"): keep the part before it, handle it, then stop.
+		stop := false
+		if i := strings.IndexAny(tok, ";|"); i >= 0 {
+			tok, stop = tok[:i], true
+		}
+		switch {
+		case tok == "" || tok == "-":
+			// empty (after a glued separator) or a bare stdin marker — skip
+		case strings.HasPrefix(tok, "-"):
+			if f := normalizeFlag(tok); f != "" {
+				inFlags = true
+				flags = append(flags, f)
+				kept = append(kept, tok)
+			}
+		case inFlags:
+			// positional / flag value after the first flag — not a command word
+			kept = append(kept, tok)
+		default:
+			// Command-path word. ASCII placeholder markers (<x>, [x], {x|y},
+			// +<verb>, ...) end the command — checked on the RAW token so the
+			// trailing-punct stripping below cannot erase a "..." ellipsis
+			// ("base +..." must stay a placeholder, not become "+").
+			if strings.ContainsAny(tok, "<>[]{}|") || strings.Contains(tok, "...") {
+				stop = true
+				break
+			}
+			// Strip trailing sentence/CJK punctuation so "login." / "login，"
+			// resolve to "login"; non-ASCII narration ends the command.
+			w := strings.TrimRight(tok, wordTrailPunct)
+			if w == "" || hasNonASCII(w) {
+				stop = true
+				break
+			}
+			words = append(words, w)
+			kept = append(kept, tok)
+		}
+		if stop {
+			break
+		}
+	}
+	if len(kept) > 0 {
+		raw = " " + strings.Join(kept, " ")
+	}
+	// Keep root-only refs ("lark-cli --help") and refs whose first word looks
+	// like a subcommand; drop prose ("lark-cli 就能搞定 ...").
+	if len(words) == 0 {
+		return words, flags, raw, len(flags) > 0
+	}
+	if !subcommandStart.MatchString(words[0]) {
+		return nil, nil, "", false
+	}
+	return words, flags, raw, true
+}
+
+// stripCmdSubst removes $(...) command substitutions (including nested ones)
+// from s, leaving the surrounding text intact. Backtick substitutions are
+// already handled upstream (a command never spans a backtick).
+func stripCmdSubst(s string) string {
+	var b strings.Builder
+	depth := 0
+	for i := 0; i < len(s); i++ {
+		if depth == 0 && i+1 < len(s) && s[i] == '$' && s[i+1] == '(' {
+			depth = 1
+			i++ // skip '('
+			continue
+		}
+		if depth > 0 {
+			switch s[i] {
+			case '(':
+				depth++
+			case ')':
+				depth--
+			}
+			continue
+		}
+		b.WriteByte(s[i])
+	}
+	return b.String()
+}
+
+// isPlaceholderOrProse reports whether a command word is a doc placeholder
+// (<resource>, [flags], {a|b}, +<verb>, ...) or narration (CJK / other
+// non-ASCII), rather than a literal command token.
+func isPlaceholderOrProse(w string) bool {
+	if hasNonASCII(w) {
+		return true
+	}
+	return strings.ContainsAny(w, "<>[]{}|") || strings.Contains(w, "...")
+}
+
+func hasNonASCII(s string) bool {
+	return strings.IndexFunc(s, func(r rune) bool { return r > 127 }) >= 0
+}
+
+// flagShape matches the leading flag token, stripping any trailing junk such as
+// a "=value" suffix or punctuation that bled in from the surrounding markdown
+// ("--help\"", "--help;", "--params={}"). The underscore is allowed because
+// real flags use it ("--input_format", "--output_as"). Returns "" for non-flags.
+var flagShape = regexp.MustCompile(`^--?[A-Za-z][A-Za-z0-9_-]*`)
+
+// normalizeFlag extracts the canonical flag token from tok, or "" if tok is not
+// a real flag (e.g. a shell-string fragment like "-草稿'").
+func normalizeFlag(tok string) string {
+	return flagShape.FindString(tok)
+}
+
+func isBoundary(b byte) bool {
+	switch b {
+	case ' ', '\t', '`', '(', ')', '\'', '"', '*':
+		return true
+	}
+	return false
+}

cmd/cmdexample_test.go

@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// This file and its cmdexample_*_test.go siblings implement a test-only check:
+// the example commands embedded in shortcut definitions (the "Example: lark-cli
+// ..." lines in each shortcut's Tips, shown in --help) must match the real
+// command tree. It lives entirely in _test.go files (package cmd_test) so it
+// ships in no binary and is not importable by product code; the truth source is
+// cmd.Build, the same tree the binary uses, so the check cannot drift.
+//
+// It runs in the standard unit-test CI job (go test ./cmd/...). A mismatch — an
+// example using a renamed command or an unaccepted flag — fails that job.
+
+package cmd_test
+
+import (
+	"context"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/cmd"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/shortcuts"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// TestShortcutExampleCommands checks the example commands embedded in every
+// shortcut's Tips against the live command tree. A shortcut that defines no
+// example is simply skipped.
+//
+// Because the examples and the command definitions live in the same Go code,
+// this is a self-consistency check: any mismatch (an example using a renamed
+// command or a flag the command doesn't accept) is a bug to fix at the source.
+// It runs over all shortcuts — no baseline, no diff — since a wrong example is
+// always a defect, never acceptable "pre-existing drift".
+func TestShortcutExampleCommands(t *testing.T) {
+	// Reproducibility: use the embedded API metadata (not a developer's stale
+	// ~/.lark-cli remote cache, which can miss commands) and an empty config
+	// dir so local strict mode / plugins / policy cannot reshape the tree.
+	// t.Setenv auto-restores after the test, so other cmd tests are unaffected.
+	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	cat := buildCmdExampleCatalog()
+
+	type located struct {
+		shortcut string
+		f        finding
+	}
+	var findings []located
+	for _, sc := range shortcuts.AllShortcuts() {
+		var refs []ref
+		for _, tip := range sc.Tips {
+			refs = append(refs, parseRefs(tip)...)
+		}
+		label := strings.TrimSpace(sc.Service + " " + sc.Command)
+		for _, f := range checkRefs(cat, refs) {
+			findings = append(findings, located{shortcut: label, f: f})
+		}
+	}
+
+	if len(findings) == 0 {
+		return
+	}
+	sort.Slice(findings, func(i, j int) bool { return findings[i].shortcut < findings[j].shortcut })
+	for _, lf := range findings {
+		hint := ""
+		if lf.f.suggest != "" {
+			hint = "  (did you mean " + lf.f.suggest + "?)"
+		}
+		if lf.f.kind == unknownFlag {
+			t.Errorf("shortcut %q example uses unknown flag %s on %q%s\n      %s",
+				lf.shortcut, lf.f.flag, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
+		} else {
+			t.Errorf("shortcut %q example uses unknown command %q%s\n      %s",
+				lf.shortcut, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
+		}
+	}
+	t.Fatalf("%d shortcut example command(s) don't match the real CLI — "+
+		"fix the Example in the shortcut definition.", len(findings))
+}
+
+// buildCmdExampleCatalog walks the live cobra command tree and records every
+// command path (minus the "lark-cli" root prefix) with its accepted flags and
+// whether it is a parent group. This is the same Build() the binary uses, so
+// the catalog can never drift from the real commands.
+func buildCmdExampleCatalog() *catalog {
+	root := cmd.Build(context.Background(), cmdutil.InvocationContext{})
+	cat := newCatalog()
+	var walk func(c *cobra.Command)
+	walk = func(c *cobra.Command) {
+		path := strings.TrimSpace(strings.TrimPrefix(c.CommandPath(), "lark-cli"))
+		var flags []string
+		add := func(fl *pflag.Flag) {
+			flags = append(flags, "--"+fl.Name)
+			if fl.Shorthand != "" {
+				flags = append(flags, "-"+fl.Shorthand)
+			}
+		}
+		c.Flags().VisitAll(add)
+		c.InheritedFlags().VisitAll(add)
+		c.PersistentFlags().VisitAll(add) // root's own persistent flags (e.g. --profile)
+		cat.addCommand(path, flags)
+		cat.setGroup(path, c.HasSubCommands())
+		for _, sub := range c.Commands() {
+			walk(sub)
+		}
+	}
+	walk(root)
+	return cat
+}

cmd/cmdexample_units_test.go

@@ -0,0 +1,233 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd_test
+
+import (
+	"strings"
+	"testing"
+)
+
+func testCatalog() *catalog {
+	c := newCatalog()
+	c.addCommand("", []string{"--profile"}) // root
+	c.setGroup("", true)
+	c.addCommand("contact", []string{"--profile"})
+	c.setGroup("contact", true)
+	c.addCommand("contact +search-user", []string{"--query", "--as", "--format", "-q"})
+	c.addCommand("api", []string{"--params", "--data", "--as"}) // leaf (no subcommands)
+	c.addCommand("mail", nil)
+	c.setGroup("mail", true)
+	c.addCommand("mail user_mailbox.messages", []string{"--profile"})
+	c.setGroup("mail user_mailbox.messages", true)
+	c.addCommand("mail user_mailbox.messages batch_modify", []string{"--params", "--data"})
+	return c
+}
+
+func TestCmdExampleCatalogHasCommandAndFlag(t *testing.T) {
+	c := testCatalog()
+	if !c.hasCommand("contact +search-user") {
+		t.Fatal("expected contact +search-user to exist")
+	}
+	if c.hasCommand("contact +nope") {
+		t.Fatal("did not expect contact +nope")
+	}
+	if !c.hasFlag("contact +search-user", "--query") {
+		t.Fatal("--query should be valid")
+	}
+	if c.hasFlag("contact +search-user", "--nope") {
+		t.Fatal("--nope should be invalid")
+	}
+	// universal flags pass on any command
+	for _, f := range []string{"--help", "-h", "--version"} {
+		if !c.hasFlag("contact +search-user", f) {
+			t.Fatalf("universal flag %s should pass", f)
+		}
+	}
+}
+
+func TestCmdExampleLongestPrefix(t *testing.T) {
+	c := testCatalog()
+	tests := []struct {
+		words  []string
+		want   string
+		wantN  int
+		wantOK bool
+	}{
+		{[]string{"contact", "+search-user"}, "contact +search-user", 2, true},
+		{[]string{"api", "GET", "/open-apis/x"}, "api", 1, true}, // trailing positionals
+		{[]string{"nope"}, "", 0, false},
+		{nil, "", 0, true}, // empty -> root
+	}
+	for _, tt := range tests {
+		got, n, ok := c.longestPrefix(tt.words)
+		if got != tt.want || n != tt.wantN || ok != tt.wantOK {
+			t.Errorf("longestPrefix(%v) = (%q,%d,%v), want (%q,%d,%v)",
+				tt.words, got, n, ok, tt.want, tt.wantN, tt.wantOK)
+		}
+	}
+}
+
+func refWordsOf(refs []ref) [][]string {
+	var out [][]string
+	for _, r := range refs {
+		out = append(out, r.words)
+	}
+	return out
+}
+
+func TestCmdExampleParseRefsExtractsCommands(t *testing.T) {
+	content := strings.Join([]string{
+		"运行 `lark-cli contact +search-user --query 张三` 搜索", // inline code
+		"```bash",
+		"lark-cli api GET /open-apis/x --params '{}'", // bash block
+		"```",
+		"用 lark-cli mail user_mailbox.messages batch_modify 即可", // bare prose command
+		"npx foo | lark-cli api GET /y",                         // after a pipe
+	}, "\n")
+	refs := parseRefs(content)
+	if len(refs) != 4 {
+		t.Fatalf("expected 4 refs, got %d: %v", len(refs), refWordsOf(refs))
+	}
+	if got := refs[0]; strings.Join(got.words, " ") != "contact +search-user" ||
+		len(got.flags) != 1 || got.flags[0] != "--query" {
+		t.Errorf("ref0 = %+v", got)
+	}
+	if got := refs[1]; strings.Join(got.words, " ") != "api GET /open-apis/x" {
+		t.Errorf("ref1 words = %v", got.words)
+	}
+}
+
+func TestCmdExampleParseRefsFiltersPlaceholdersAndProse(t *testing.T) {
+	// A line whose first word is prose yields no command at all.
+	if refs := parseRefs("lark-cli 就能搞定这件事"); len(refs) != 0 {
+		t.Errorf("prose-first line should yield 0 refs, got %v", refWordsOf(refs))
+	}
+	// Syntax templates / trailing prose may leave a real leading word ("mail"),
+	// but no placeholder or CJK token may leak into the command words — that is
+	// what prevents false positives like an "<resource>" unknown-command report.
+	for _, line := range []string{
+		"lark-cli mail <resource> <method> [flags]",
+		"lark-cli apps +<verb> [flags]",
+		"lark-cli base +...",
+		"lark-cli mail 写信场景下的格式说明",
+	} {
+		for _, r := range parseRefs(line) {
+			for _, w := range r.words {
+				if isPlaceholderOrProse(w) {
+					t.Errorf("%q: placeholder/prose token %q leaked into words %v", line, w, r.words)
+				}
+			}
+		}
+	}
+}
+
+func TestCmdExampleParseRefsStripsTrailingJunk(t *testing.T) {
+	// frontmatter-style quoted value: the trailing quote must not bleed into the flag
+	refs := parseRefs(`cliHelp: "lark-cli contact --help"`)
+	if len(refs) != 1 {
+		t.Fatalf("expected 1 ref, got %d", len(refs))
+	}
+	if len(refs[0].flags) != 1 || refs[0].flags[0] != "--help" {
+		t.Errorf("expected flag --help, got %v", refs[0].flags)
+	}
+	// bare "-" (stdin marker) and "=value" suffix
+	refs = parseRefs("lark-cli api GET /x --params={} --data -")
+	if len(refs) != 1 {
+		t.Fatalf("expected 1 ref, got %d", len(refs))
+	}
+	flags := strings.Join(refs[0].flags, " ")
+	if flags != "--params --data" {
+		t.Errorf("expected '--params --data', got %q", flags)
+	}
+}
+
+func TestCmdExampleCheck(t *testing.T) {
+	c := testCatalog()
+	tests := []struct {
+		name     string
+		r        ref
+		wantKind string // "" = no finding
+		wantPath string
+	}{
+		{"valid shortcut", ref{words: []string{"contact", "+search-user"}, flags: []string{"--query"}}, "", ""},
+		{"valid leaf positional", ref{words: []string{"api", "GET", "/x"}}, "", ""},
+		{"unknown top command", ref{words: []string{"nope"}}, unknownCommand, "nope"},
+		{"group leftover = unknown subcommand",
+			ref{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}},
+			unknownCommand, "mail user_mailbox.messages batch_modify_message"},
+		{"unknown flag", ref{words: []string{"contact", "+search-user"}, flags: []string{"--nope"}}, unknownFlag, "contact +search-user"},
+		{"universal flag ok", ref{words: []string{"contact", "+search-user"}, flags: []string{"--help"}}, "", ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			fs := checkRefs(c, []ref{tt.r})
+			if tt.wantKind == "" {
+				if len(fs) != 0 {
+					t.Fatalf("expected no finding, got %+v", fs)
+				}
+				return
+			}
+			if len(fs) != 1 {
+				t.Fatalf("expected 1 finding, got %d: %+v", len(fs), fs)
+			}
+			if fs[0].kind != tt.wantKind || fs[0].path != tt.wantPath {
+				t.Errorf("got kind=%s path=%q, want kind=%s path=%q", fs[0].kind, fs[0].path, tt.wantKind, tt.wantPath)
+			}
+		})
+	}
+}
+
+func TestCmdExampleCheckSuggestsNearest(t *testing.T) {
+	c := testCatalog()
+	fs := checkRefs(c, []ref{{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}}})
+	if len(fs) != 1 || fs[0].suggest != "mail user_mailbox.messages batch_modify" {
+		t.Fatalf("expected suggestion 'mail user_mailbox.messages batch_modify', got %+v", fs)
+	}
+}
+
+// TestCmdExampleParseRefsRobustness covers the parser edge cases hardened after
+// review: backslash continuation, underscore flags, $(...) substitution, glued
+// separators, trailing punctuation, and the "..." placeholder.
+func TestCmdExampleParseRefsRobustness(t *testing.T) {
+	cases := []struct {
+		name, content, wantWords, wantFlags string
+		wantRefs                            int
+	}{
+		{"backslash continuation joins flags",
+			"lark-cli contact +search-user \\\n  --query foo \\\n  --as user",
+			"contact +search-user", "--query --as", 1},
+		{"underscore flag not truncated",
+			"lark-cli whiteboard +update --input_format mermaid",
+			"whiteboard +update", "--input_format", 1},
+		{"command-substitution flags ignored",
+			`lark-cli slides x create --data "$(jq -n --arg c '{}')" --as user`,
+			"slides x create", "--data --as", 1},
+		{"glued separator truncates",
+			"lark-cli auth login; echo done",
+			"auth login", "", 1},
+		{"trailing CJK punctuation stripped",
+			"用 lark-cli auth login。",
+			"auth login", "", 1},
+		{"ellipsis placeholder stays placeholder",
+			"lark-cli base +...",
+			"base", "", 1},
+	}
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			refs := parseRefs(tt.content)
+			if len(refs) != tt.wantRefs {
+				t.Fatalf("refs=%d want %d: %v", len(refs), tt.wantRefs, refWordsOf(refs))
+			}
+			if tt.wantRefs == 0 {
+				return
+			}
+			if got := strings.Join(refs[0].words, " "); got != tt.wantWords {
+				t.Errorf("words=%q want %q", got, tt.wantWords)
+			}
+			if got := strings.Join(refs[0].flags, " "); got != tt.wantFlags {
+				t.Errorf("flags=%q want %q", got, tt.wantFlags)
+			}
+		})
+	}
+}

cmd/root_integration_test.go

@@ -377,9 +377,9 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 		OK:       false,
 		Identity: "bot",
 		Error: &output.ErrDetail{
-			Type:    "api_error",
+			Type:    "api",
 			Code:    230002,
-			Message: "HTTP 400: Bot/User can NOT be out of the chat.",
+			Message: "Bot/User can NOT be out of the chat.",
 		},
 	})
 }

cmd/schema/schema.go

@@ -70,7 +70,7 @@ func printResourceList(w io.Writer, spec map[string]interface{}, mode core.Stric
 		for _, methodName := range sortedKeys(methods) {
 			m, _ := methods[methodName].(map[string]interface{})
 			httpMethod := registry.GetStrFromMap(m, "httpMethod")
-			desc := registry.GetMethodDescription(name, resName, methodName, m)
+			desc := registry.GetStrFromMap(m, "description")
 			danger := ""
 			if d, _ := m["danger"].(bool); d {
 				danger = fmt.Sprintf(" %s[danger]%s", output.Red, output.Reset)
@@ -94,7 +94,7 @@ func printMethodDetail(w io.Writer, spec map[string]interface{}, resName, method
 	methodPath := registry.GetStrFromMap(method, "path")
 	fullPath := servicePath + "/" + methodPath
 	httpMethod := registry.GetStrFromMap(method, "httpMethod")
-	desc := registry.GetMethodDescription(specName, resName, methodName, method)
+	desc := registry.GetStrFromMap(method, "description")
 	isFileUpload, fileFieldNames := hasFileFields(method)
 
 	fmt.Fprintf(w, "%s%s.%s.%s%s\n\n", output.Bold, specName, resName, methodName, output.Reset)
@@ -679,7 +679,7 @@ func runPrettyMode(out io.Writer, parts []string, mode core.StrictMode) error {
 		for _, mName := range sortedKeys(methods) {
 			m, _ := methods[mName].(map[string]interface{})
 			httpMethod := registry.GetStrFromMap(m, "httpMethod")
-			desc := registry.GetMethodDescription(serviceName, resName, mName, m)
+			desc := registry.GetStrFromMap(m, "description")
 			fmt.Fprintf(out, "  %-7s %s%s%s  %s%s%s\n", httpMethod, output.Bold, mName, output.Reset, output.Dim, desc, output.Reset)
 		}
 		fmt.Fprintf(out, "\n%sUsage: lark-cli schema %s.%s.<method>%s\n", output.Dim, serviceName, resName, output.Reset)

cmd/schema/schema_test.go

@@ -196,25 +196,6 @@ func TestSchemaCmd_PrettyUnchanged_KeyTextPresent(t *testing.T) {
 	}
 }
 
-func TestPrintMethodDetail_UsesDescriptionOverrideWhenMetadataIsEmpty(t *testing.T) {
-	spec := map[string]interface{}{
-		"name":        "drive",
-		"servicePath": "/open-apis/drive/v1",
-	}
-	method := map[string]interface{}{
-		"httpMethod":  "PATCH",
-		"path":        "files/{file_token}",
-		"description": "",
-	}
-
-	var out bytes.Buffer
-	printMethodDetail(&out, spec, "files", "patch", method)
-
-	if !strings.Contains(out.String(), "修改文件标题") {
-		t.Fatalf("pretty output = %q, want to contain %q", out.String(), "修改文件标题")
-	}
-}
-
 func TestSchemaCmd_UnknownService(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,

cmd/service/service.go

@@ -140,10 +140,10 @@ func NewCmdServiceMethod(f *cmdutil.Factory, spec, method map[string]interface{}
 }
 
 func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spec, method map[string]interface{}, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
-	specName := registry.GetStrFromMap(spec, "name")
-	desc := registry.GetMethodDescription(specName, resName, name, method)
+	desc := registry.GetStrFromMap(method, "description")
 	httpMethod := registry.GetStrFromMap(method, "httpMethod")
 	risk := registry.GetStrFromMap(method, "risk")
+	specName := registry.GetStrFromMap(spec, "name")
 	schemaPath := fmt.Sprintf("%s.%s.%s", specName, resName, name)
 
 	opts := &ServiceMethodOptions{

cmd/service/service_test.go

@@ -166,19 +166,6 @@ func TestNewCmdServiceMethod_POSTHasDataFlag(t *testing.T) {
 	}
 }
 
-func TestNewCmdServiceMethod_UsesDescriptionOverrideWhenMetadataIsEmpty(t *testing.T) {
-	f := &cmdutil.Factory{}
-	cmd := NewCmdServiceMethod(f, driveSpec(),
-		map[string]interface{}{"description": "", "httpMethod": "PATCH"}, "patch", "files", nil)
-
-	if cmd.Short != "修改文件标题" {
-		t.Fatalf("Short = %q, want %q", cmd.Short, "修改文件标题")
-	}
-	if !strings.Contains(cmd.Long, "修改文件标题") {
-		t.Fatalf("Long = %q, want to contain %q", cmd.Long, "修改文件标题")
-	}
-}
-
 func TestNewCmdServiceMethod_RunFCallback(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
 

cmd/update/update_test.go

@@ -61,6 +61,8 @@ func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
 		switch strings.Join(args, " ") {
 		case "-y skills add https://open.feishu.cn --list":
 			r.Stdout.WriteString("Available Skills\n │    lark-calendar\n │    lark-mail\n")
+		case "-y skills ls -g --json":
+			r.Stdout.WriteString(`[{"name":"lark-calendar","path":"/tmp/lark-calendar","scope":"global","agents":["Codex"]},{"name":"custom-skill","path":"/tmp/custom-skill","scope":"global","agents":["Codex"]}]`)
 		case "-y skills ls -g":
 			r.Stdout.WriteString("Global Skills\nlark-calendar /tmp/lark-calendar\ncustom-skill /tmp/custom-skill\n")
 		default:

events/register.go

@@ -8,6 +8,7 @@ import (
 	"github.com/larksuite/cli/events/im"
 	"github.com/larksuite/cli/events/minutes"
 	"github.com/larksuite/cli/events/vc"
+	"github.com/larksuite/cli/events/whiteboard"
 	"github.com/larksuite/cli/internal/event"
 )
 
@@ -17,6 +18,7 @@ func init() {
 		im.Keys(),
 		minutes.Keys(),
 		vc.Keys(),
+		whiteboard.Keys(),
 	}
 	for _, keys := range all {
 		for _, k := range keys {

events/whiteboard/native.go

@@ -0,0 +1,23 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package whiteboard
+
+// BoardWhiteboardUpdatedV1Data is the flattened whiteboard updated source payload.
+type BoardWhiteboardUpdatedV1Data struct {
+	// WhiteboardID is the id of the whiteboard whose content was updated.
+	WhiteboardID string `json:"whiteboard_id"`
+	// OperatorIDs lists the operators that produced this update batch.
+	OperatorIDs []OperatorID `json:"operator_ids"`
+}
+
+// OperatorID identifies an operator that produced the whiteboard update,
+// expressed in the three Lark identity formats.
+type OperatorID struct {
+	// OpenID is the operator's open_id within the current app.
+	OpenID string `json:"open_id"`
+	// UnionID is the operator's union_id across apps under the same ISV.
+	UnionID string `json:"union_id"`
+	// UserID is the operator's user_id within the tenant.
+	UserID string `json:"user_id"`
+}

events/whiteboard/preconsume.go

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package whiteboard
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/validate"
+)
+
+// cleanupTimeout bounds how long the unsubscribe call has to finish during
+// PreConsume cleanup so a stuck OAPI cannot block process shutdown.
+const cleanupTimeout = 5 * time.Second
+
+// whiteboardSubscriptionPreConsume calls the whiteboard event subscribe OAPI
+// and returns a cleanup that invokes the matching unsubscribe.
+//
+// board.whiteboard.updated_v1 is subscribed per-whiteboard (by whiteboard_id),
+// so the path contains a :whiteboard_id placeholder that must be supplied via params.
+func whiteboardSubscriptionPreConsume(eventType string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
+	return func(ctx context.Context, rt event.APIClient, params map[string]string) (func(), error) {
+		if rt == nil {
+			return nil, fmt.Errorf("runtime API client is required for pre-consume subscription")
+		}
+		whiteboardID := params["whiteboard_id"]
+		if whiteboardID == "" {
+			return nil, fmt.Errorf("param whiteboard_id is required for %s", eventType)
+		}
+		encoded := validate.EncodePathSegment(whiteboardID)
+		subscribePath := fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/subscribe", encoded)
+		unsubscribePath := fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/unsubscribe", encoded)
+
+		body := map[string]string{"event_type": eventType}
+		if _, err := rt.CallAPI(ctx, "POST", subscribePath, body); err != nil {
+			return nil, err
+		}
+
+		return func() {
+			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
+			defer cancel()
+			_, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body)
+		}, nil
+	}
+}

events/whiteboard/preconsume_test.go

@@ -0,0 +1,198 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package whiteboard
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// recordedCall captures a single APIClient invocation for assertion.
+type recordedCall struct {
+	method string
+	path   string
+	body   interface{}
+}
+
+// fakeAPIClient is a minimal event.APIClient stub that records calls and
+// can be configured to fail when the request path matches errOnPath.
+type fakeAPIClient struct {
+	mu        sync.Mutex
+	calls     []recordedCall
+	errOnPath string
+}
+
+// CallAPI records the invocation and optionally returns a simulated error
+// when the path contains the configured errOnPath substring.
+func (f *fakeAPIClient) CallAPI(_ context.Context, method, path string, body interface{}) (json.RawMessage, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.calls = append(f.calls, recordedCall{method: method, path: path, body: body})
+	if f.errOnPath != "" && strings.Contains(path, f.errOnPath) {
+		return nil, errors.New("simulated subscribe failure")
+	}
+	return json.RawMessage(`{}`), nil
+}
+
+// TestWhiteboardSubscriptionPreConsume_MissingWhiteboardID verifies that the
+// PreConsume hook fails fast with an actionable error when whiteboard_id
+// is absent from the params map.
+func TestWhiteboardSubscriptionPreConsume_MissingWhiteboardID(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	cleanup, err := pc(context.Background(), &fakeAPIClient{}, map[string]string{})
+	if err == nil {
+		t.Fatalf("expected error when whiteboard_id missing")
+	}
+	if cleanup != nil {
+		t.Fatalf("expected nil cleanup on error")
+	}
+	if !strings.Contains(err.Error(), "whiteboard_id") {
+		t.Fatalf("error should mention whiteboard_id, got: %v", err)
+	}
+}
+
+// TestWhiteboardSubscriptionPreConsume_NilRuntime verifies that PreConsume
+// returns an error when the runtime APIClient dependency is missing.
+func TestWhiteboardSubscriptionPreConsume_NilRuntime(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	_, err := pc(context.Background(), nil, map[string]string{"whiteboard_id": "wb1"})
+	if err == nil {
+		t.Fatalf("expected error when runtime client is nil")
+	}
+}
+
+// TestWhiteboardSubscriptionPreConsume_SubscribeError verifies that a
+// failed subscribe call surfaces the error and skips registering a cleanup,
+// so no spurious unsubscribe is invoked.
+func TestWhiteboardSubscriptionPreConsume_SubscribeError(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	rt := &fakeAPIClient{errOnPath: "/subscribe"}
+	cleanup, err := pc(context.Background(), rt, map[string]string{"whiteboard_id": "wb1"})
+	if err == nil {
+		t.Fatalf("expected error from subscribe call")
+	}
+	if cleanup != nil {
+		t.Fatalf("expected nil cleanup when subscribe fails")
+	}
+	// only the failed subscribe call should have been made; no unsubscribe.
+	if len(rt.calls) != 1 {
+		t.Fatalf("expected exactly 1 call (subscribe), got %d", len(rt.calls))
+	}
+}
+
+// TestWhiteboardSubscriptionPreConsume_SubscribeAndCleanup verifies the full
+// happy-path: subscribe is called once with the correct method/path/body,
+// and the returned cleanup invokes the matching unsubscribe.
+func TestWhiteboardSubscriptionPreConsume_SubscribeAndCleanup(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	rt := &fakeAPIClient{}
+	cleanup, err := pc(context.Background(), rt, map[string]string{"whiteboard_id": "wb1"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if cleanup == nil {
+		t.Fatalf("expected non-nil cleanup")
+	}
+
+	if len(rt.calls) != 1 {
+		t.Fatalf("expected 1 call after subscribe, got %d", len(rt.calls))
+	}
+	got := rt.calls[0]
+	if got.method != "POST" {
+		t.Errorf("subscribe method: got %q, want POST", got.method)
+	}
+	wantSubPath := "/open-apis/board/v1/whiteboards/wb1/subscribe"
+	if got.path != wantSubPath {
+		t.Errorf("subscribe path: got %q, want %q", got.path, wantSubPath)
+	}
+	body, _ := got.body.(map[string]string)
+	if body["event_type"] != eventTypeWhiteboardUpdated {
+		t.Errorf("subscribe body event_type: got %q, want %q", body["event_type"], eventTypeWhiteboardUpdated)
+	}
+
+	cleanup()
+	if len(rt.calls) != 2 {
+		t.Fatalf("expected 2 calls after cleanup, got %d", len(rt.calls))
+	}
+	got2 := rt.calls[1]
+	if got2.method != "POST" {
+		t.Errorf("unsubscribe method: got %q, want POST", got2.method)
+	}
+	wantUnsubPath := "/open-apis/board/v1/whiteboards/wb1/unsubscribe"
+	if got2.path != wantUnsubPath {
+		t.Errorf("unsubscribe path: got %q, want %q", got2.path, wantUnsubPath)
+	}
+	body2, _ := got2.body.(map[string]string)
+	if body2["event_type"] != eventTypeWhiteboardUpdated {
+		t.Errorf("unsubscribe body event_type: got %q, want %q", body2["event_type"], eventTypeWhiteboardUpdated)
+	}
+}
+
+// TestWhiteboardSubscriptionPreConsume_PathSegmentEncoded verifies that
+// whiteboard_id values containing reserved URL characters are properly
+// path-segment encoded so they cannot escape into adjacent path segments.
+func TestWhiteboardSubscriptionPreConsume_PathSegmentEncoded(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
+	rt := &fakeAPIClient{}
+	// 含特殊字符的 whiteboard_id 应被 path-segment 编码，避免越界到其他 path 段。
+	_, err := pc(context.Background(), rt, map[string]string{"whiteboard_id": "wb/1?evil"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rt.calls) != 1 {
+		t.Fatalf("expected 1 call, got %d", len(rt.calls))
+	}
+	if strings.Contains(rt.calls[0].path, "wb/1?evil") {
+		t.Errorf("whiteboard_id was not encoded; path: %s", rt.calls[0].path)
+	}
+}
+
+// TestWhiteboardUpdatedV1HasPreConsume ensures the registered EventKey for
+// board.whiteboard.updated_v1 wires the PreConsume hook and declares the
+// required whiteboard_id parameter.
+func TestWhiteboardUpdatedV1HasPreConsume(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	keys := Keys()
+	for _, k := range keys {
+		if k.Key == eventTypeWhiteboardUpdated {
+			if k.PreConsume == nil {
+				t.Fatalf("EventKey %s should have PreConsume hook", eventTypeWhiteboardUpdated)
+			}
+			if len(k.Params) == 0 {
+				t.Fatalf("EventKey %s should declare whiteboard_id param", eventTypeWhiteboardUpdated)
+			}
+			var found bool
+			for _, p := range k.Params {
+				if p.Name == "whiteboard_id" && p.Required {
+					found = true
+				}
+			}
+			if !found {
+				t.Fatalf("EventKey %s must declare required whiteboard_id param", eventTypeWhiteboardUpdated)
+			}
+			return
+		}
+	}
+	t.Fatalf("EventKey %s not registered", eventTypeWhiteboardUpdated)
+}
+
+// 确保 event.APIClient 接口与本测试 mock 一致。
+var _ event.APIClient = (*fakeAPIClient)(nil)

events/whiteboard/register.go

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package whiteboard registers Board-domain EventKeys.
+package whiteboard
+
+import (
+	"reflect"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/event/schemas"
+)
+
+// eventTypeWhiteboardUpdated is the OAPI event type for whiteboard content updates.
+const eventTypeWhiteboardUpdated = "board.whiteboard.updated_v1"
+
+// Keys returns all Board-domain EventKey definitions.
+func Keys() []event.KeyDefinition {
+	return []event.KeyDefinition{
+		{
+			Key:         eventTypeWhiteboardUpdated,
+			DisplayName: "Whiteboard updated",
+			Description: "Pushed when the whiteboard content is updated.",
+			EventType:   eventTypeWhiteboardUpdated,
+			Params: []event.ParamDef{
+				{
+					Name:        "whiteboard_id",
+					Type:        event.ParamString,
+					Required:    true,
+					Description: "Whiteboard id to subscribe; subscription is per-whiteboard.",
+				},
+			},
+			Schema: event.SchemaDef{
+				Native: &event.SchemaSpec{Type: reflect.TypeOf(BoardWhiteboardUpdatedV1Data{})},
+				FieldOverrides: map[string]schemas.FieldMeta{
+					"/event/whiteboard_id":           {Kind: "whiteboard_id", Description: "whiteboard id to subscribe"},
+					"/event/operator_ids/*/open_id":  {Kind: "open_id"},
+					"/event/operator_ids/*/union_id": {Kind: "union_id"},
+					"/event/operator_ids/*/user_id":  {Kind: "user_id"},
+				},
+			},
+			PreConsume:            whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated),
+			Scopes:                []string{"board:whiteboard:node:read"},
+			AuthTypes:             []string{"user", "bot"},
+			RequiredConsoleEvents: []string{eventTypeWhiteboardUpdated},
+		},
+	}
+}

internal/errclass/classify.go

@@ -92,6 +92,18 @@ func BuildAPIError(resp map[string]any, cc ClassifyContext) error {
 			base.Troubleshooter = ts
 		}
 	}
+	// Upstream-provided field-level reasons (resp.error.details[].value). Lark
+	// returns these as free-text reason strings with no machine-readable field
+	// name (verified for code 190014:
+	// {"error":{"details":[{"value":"end_time should be later than start_time"}]}}),
+	// so they are lifted into Problem.Hint — the sanctioned free-text recovery
+	// prompt — rather than fabricated structured params. Lifted before the
+	// category switch so any classified arm inherits it; the CategoryAPI arm
+	// below prefers this server detail over the context-free APIHint default.
+	detailHint := liftErrorDetailValues(resp)
+	if detailHint != "" {
+		base.Hint = detailHint
+	}
 
 	switch meta.Category {
 	case errs.CategoryAuthorization:
@@ -129,7 +141,11 @@ func BuildAPIError(resp map[string]any, cc ClassifyContext) error {
 			Action:  action,
 		}
 	case errs.CategoryAPI:
-		base.Hint = APIHint(base.Subtype) // "" for subtypes without a context-free default
+		// A server-supplied detail (lifted into base.Hint above) wins over the
+		// context-free APIHint default; only fall back to APIHint when absent.
+		if base.Hint == "" {
+			base.Hint = APIHint(base.Subtype) // "" for subtypes without a context-free default
+		}
 		return &errs.APIError{Problem: base}
 	default:
 		// Fail closed: an unrecognized Category routes to InternalError
@@ -214,6 +230,10 @@ func stringFromAny(v any) string {
 // per-subtype recovery hint before returning it, so the wire envelope
 // emitted via BuildAPIError always carries a hint for known config subtypes.
 func buildConfigError(p errs.Problem) *errs.ConfigError {
+	// Config categories have authoritative recovery guidance, so the curated
+	// ConfigHint deliberately overrides any server detail lifted into p.Hint
+	// (the opposite precedence from the CategoryAPI arm, where the lifted
+	// detail wins).
 	p.Hint = ConfigHint(p.Subtype)
 	return &errs.ConfigError{Problem: p}
 }
@@ -244,6 +264,8 @@ func APIHint(subtype errs.Subtype) string {
 		return "operate on source and target within the same tenant and region/unit"
 	case errs.SubtypeCrossBrand:
 		return "operate on source and target within the same brand environment"
+	case errs.SubtypeQuotaExceeded:
+		return "reduce the request volume or free quota, then retry after the relevant quota resets"
 	}
 	return ""
 }
@@ -256,6 +278,10 @@ func buildPermissionError(p errs.Problem, resp map[string]any, cc ClassifyContex
 	}
 	consoleURL := ConsoleURL(cc.Brand, cc.AppID, missing)
 	p.Message = CanonicalPermissionMessage(p.Subtype, cc.AppID, missing, p.Message)
+	// Permission categories have authoritative recovery guidance (scopes to
+	// grant, console URL), so the curated PermissionHint deliberately overrides
+	// any server detail lifted into p.Hint (the opposite precedence from the
+	// CategoryAPI arm, where the lifted detail wins).
 	p.Hint = PermissionHint(missing, identity, p.Subtype, consoleURL)
 	permErr := &errs.PermissionError{
 		Problem:       p,
@@ -364,6 +390,32 @@ func PermissionHint(missing []string, identity string, subtype errs.Subtype, con
 	return "check the calling identity has the required scope"
 }
 
+// liftErrorDetailValues collects the non-empty resp.error.details[].value reason
+// strings and joins them with "; ". Returns "" when the structure is absent or
+// carries no non-empty value. The shape (verified for code 190014) is
+// {"error":{"details":[{"value":"<reason>"}]}}.
+func liftErrorDetailValues(resp map[string]any) string {
+	errBlock, ok := resp["error"].(map[string]any)
+	if !ok {
+		return ""
+	}
+	details, ok := errBlock["details"].([]any)
+	if !ok || len(details) == 0 {
+		return ""
+	}
+	var values []string
+	for _, d := range details {
+		m, ok := d.(map[string]any)
+		if !ok {
+			continue
+		}
+		if v, _ := m["value"].(string); v != "" {
+			values = append(values, v)
+		}
+	}
+	return strings.Join(values, "; ")
+}
+
 // extractMissingScopes walks resp["error"]["permission_violations"][].subject.
 // Returns nil when the structure is absent.
 func extractMissingScopes(resp map[string]any) []string {

internal/errclass/classify_test.go

@@ -220,6 +220,111 @@ func TestBuildAPIError_TroubleshooterLiftedOnPermissionArm(t *testing.T) {
 	}
 }
 
+// TestBuildAPIError_DetailsLiftedToHintOnAPIArm pins that BuildAPIError lifts
+// resp.error.details[].value into Problem.Hint when the response routes to the
+// catch-all CategoryAPI arm. The real Lark shape (verified for code 190014) is
+// {"error":{"details":[{"value":"end_time should be later than start_time"}]}}
+// — only a human-readable reason string, no machine-readable field name. It is
+// lifted into Hint (sanctioned free-text recovery prompt) rather than fabricated
+// structured params.
+func TestBuildAPIError_DetailsLiftedToHintOnAPIArm(t *testing.T) {
+	resp := map[string]any{
+		"code": 190014,
+		"msg":  "invalid params",
+		"error": map[string]any{
+			"details": []any{
+				map[string]any{"value": "end_time should be later than start_time"},
+			},
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatal("ProblemOf returned !ok")
+	}
+	if !strings.Contains(p.Hint, "end_time should be later than start_time") {
+		t.Errorf("Hint = %q, want it to contain the server detail value", p.Hint)
+	}
+}
+
+// TestBuildAPIError_MultipleDetailsJoinedIntoHint pins that multiple non-empty
+// detail values are joined with "; " into a single Hint, and empty values are
+// skipped.
+func TestBuildAPIError_MultipleDetailsJoinedIntoHint(t *testing.T) {
+	resp := map[string]any{
+		"code": 190014,
+		"msg":  "invalid params",
+		"error": map[string]any{
+			"details": []any{
+				map[string]any{"value": "first reason"},
+				map[string]any{"value": ""},
+				map[string]any{"value": "second reason"},
+			},
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatal("ProblemOf returned !ok")
+	}
+	if p.Hint != "first reason; second reason" {
+		t.Errorf("Hint = %q, want %q", p.Hint, "first reason; second reason")
+	}
+}
+
+// TestBuildAPIError_DetailsSkipsNonMapEntries pins that malformed entries in
+// the details array (not a JSON object) are skipped rather than panicking, and
+// well-formed siblings still surface in the Hint.
+func TestBuildAPIError_DetailsSkipsNonMapEntries(t *testing.T) {
+	resp := map[string]any{
+		"code": 190014,
+		"msg":  "invalid params",
+		"error": map[string]any{
+			"details": []any{
+				"i am a bare string, not an object",
+				map[string]any{"value": "the real reason"},
+				42,
+			},
+		},
+	}
+	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatal("ProblemOf returned !ok")
+	}
+	if p.Hint != "the real reason" {
+		t.Errorf("Hint = %q, want %q", p.Hint, "the real reason")
+	}
+}
+
+// TestBuildAPIError_DetailsMalformedShapesNoHint pins that a missing error
+// block, a non-array details field, and an empty details array all leave the
+// Hint untouched (no lifted detail) instead of erroring.
+func TestBuildAPIError_DetailsMalformedShapesNoHint(t *testing.T) {
+	cases := []struct {
+		name string
+		resp map[string]any
+	}{
+		{"no error block", map[string]any{"code": 190014, "msg": "invalid params"}},
+		{"details not array", map[string]any{"code": 190014, "msg": "invalid params", "error": map[string]any{"details": "nope"}}},
+		{"empty details", map[string]any{"code": 190014, "msg": "invalid params", "error": map[string]any{"details": []any{}}}},
+		{"detail values all empty", map[string]any{"code": 190014, "msg": "invalid params", "error": map[string]any{"details": []any{map[string]any{"value": ""}}}}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := errclass.BuildAPIError(tc.resp, errclass.ClassifyContext{})
+			p, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatal("ProblemOf returned !ok")
+			}
+			// With no liftable detail, the Hint must not echo a server detail.
+			if strings.Contains(p.Hint, "nope") {
+				t.Errorf("Hint should not lift a non-array details field, got %q", p.Hint)
+			}
+		})
+	}
+}
+
 // TestBuildAPIError_TroubleshooterAbsent pins that Troubleshooter stays empty
 // when the upstream response omits it — wire envelope must omit the field.
 func TestBuildAPIError_TroubleshooterAbsent(t *testing.T) {

internal/errclass/codemeta_calendar.go

@@ -0,0 +1,16 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+// calendarCodeMeta holds calendar-service Lark code → CodeMeta mappings.
+// Only codes whose meaning is verifiable from repo evidence are registered;
+// ambiguous codes fall back to CategoryAPI via BuildAPIError.
+// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
+var calendarCodeMeta = map[int]CodeMeta{
+	190014: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // invalid params (carries a field-level detail lifted into Hint)
+}
+
+func init() { mergeCodeMeta(calendarCodeMeta, "calendar") }

internal/errclass/codemeta_calendar_test.go

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// TestLookupCodeMeta_CalendarCodes pins each calendar-service code registered
+// via the codemeta_calendar.go init() merge to its expected
+// Category/Subtype/Retryable.
+func TestLookupCodeMeta_CalendarCodes(t *testing.T) {
+	cases := []struct {
+		code        int
+		wantCat     errs.Category
+		wantSubtype errs.Subtype
+		wantRetry   bool
+	}{
+		// 190014: calendar "invalid params" with a field-level detail
+		// (error.details[].value) lifted into Hint by BuildAPIError.
+		{190014, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+	}
+	for _, tc := range cases {
+		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {
+			meta, ok := LookupCodeMeta(tc.code)
+			if !ok {
+				t.Fatalf("code %d not registered in codeMeta", tc.code)
+			}
+			if meta.Category != tc.wantCat || meta.Subtype != tc.wantSubtype || meta.Retryable != tc.wantRetry {
+				t.Errorf("code %d: got %+v, want Category=%v Subtype=%v Retryable=%v",
+					tc.code, meta, tc.wantCat, tc.wantSubtype, tc.wantRetry)
+			}
+		})
+	}
+}

internal/errclass/codemeta_mail.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+// mailCodeMeta holds mail-service Lark code -> CodeMeta mappings.
+// Only codes whose meaning is verifiable from repo evidence are registered;
+// ambiguous codes fall back to CategoryAPI via BuildAPIError.
+var mailCodeMeta = map[int]CodeMeta{
+	1234013: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},      // mailbox not found or not active
+	1236007: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // user daily send count exceeded
+	1236008: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // user daily external recipient count exceeded
+	1236009: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // tenant daily external recipient count exceeded
+	1236010: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // mail quota limit
+	1236013: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // tenant storage limit exceeded
+}
+
+func init() { mergeCodeMeta(mailCodeMeta, "mail") }

internal/registry/method_desc.go

@@ -1,19 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package registry
-
-import "strings"
-
-var methodDescriptionOverrides = map[string]string{
-	"drive.files.patch": "修改文件标题",
-}
-
-// GetMethodDescription returns the method description from metadata, falling back
-// to a curated override when the upstream meta has an empty description.
-func GetMethodDescription(service, resource, method string, meta map[string]interface{}) string {
-	if desc := strings.TrimSpace(GetStrFromMap(meta, "description")); desc != "" {
-		return desc
-	}
-	return methodDescriptionOverrides[service+"."+resource+"."+method]
-}

internal/registry/registry_test.go

@@ -223,24 +223,6 @@ func TestFilterScopes_TooFewParts(t *testing.T) {
 	}
 }
 
-func TestGetMethodDescription_UsesOverrideWhenMetadataIsEmpty(t *testing.T) {
-	got := GetMethodDescription("drive", "files", "patch", map[string]interface{}{
-		"description": "   ",
-	})
-	if got != "修改文件标题" {
-		t.Fatalf("GetMethodDescription() = %q, want %q", got, "修改文件标题")
-	}
-}
-
-func TestGetMethodDescription_PrefersMetadataDescription(t *testing.T) {
-	got := GetMethodDescription("drive", "files", "patch", map[string]interface{}{
-		"description": "Rename a file",
-	})
-	if got != "Rename a file" {
-		t.Fatalf("GetMethodDescription() = %q, want %q", got, "Rename a file")
-	}
-}
-
 // --- Auto-approve functions ---
 
 func TestLoadAutoApproveSet(t *testing.T) {
@@ -249,14 +231,9 @@ func TestLoadAutoApproveSet(t *testing.T) {
 		t.Fatal("expected non-empty auto-approve set")
 	}
 
-	// From scope_overrides.json allow list
-	if !aaSet["calendar:calendar.event:create"] {
-		t.Error("expected calendar:calendar.event:create in auto-approve set (from allow list)")
-	}
-
-	// Verify allow list entries are present
+	// From scope_priorities.json recommend=="true"
 	if !aaSet["sheets:spreadsheet:read"] {
-		t.Error("expected sheets:spreadsheet:read in auto-approve set (from allow list)")
+		t.Error("expected sheets:spreadsheet:read in auto-approve set (recommend=true in priorities)")
 	}
 
 	t.Logf("Auto-approve set has %d scopes", len(aaSet))
@@ -275,16 +252,10 @@ func TestLoadPlatformAutoApproveSet(t *testing.T) {
 
 func TestLoadOverrideAutoApproveAllow(t *testing.T) {
 	allowSet := LoadOverrideAutoApproveAllow()
-	if len(allowSet) == 0 {
-		t.Fatal("expected non-empty override allow set")
-	}
-
-	// Known entries from scope_overrides.json
-	if !allowSet["calendar:calendar.event:create"] {
-		t.Error("expected calendar:calendar.event:create in allow set")
-	}
-	if !allowSet["mail:event"] {
-		t.Error("expected mail:event in allow set")
+	// recommend.allow in scope_overrides.json is intentionally empty:
+	// no scopes are special-cased into the auto-approve set anymore.
+	if len(allowSet) != 0 {
+		t.Errorf("expected empty override allow set, got %d entries", len(allowSet))
 	}
 }
 
@@ -295,9 +266,9 @@ func TestLoadOverrideAutoApproveDeny(t *testing.T) {
 }
 
 func TestIsAutoApproveScope(t *testing.T) {
-	// Known auto-approve scope (in allow list)
-	if !IsAutoApproveScope("calendar:calendar.event:create") {
-		t.Error("expected calendar:calendar.event:create to be auto-approve")
+	// Known auto-approve scope (recommend=true in scope_priorities.json)
+	if !IsAutoApproveScope("sheets:spreadsheet:read") {
+		t.Error("expected sheets:spreadsheet:read to be auto-approve")
 	}
 
 	// Completely unknown scope
@@ -308,9 +279,8 @@ func TestIsAutoApproveScope(t *testing.T) {
 
 func TestFilterAutoApproveScopes(t *testing.T) {
 	scopes := []string{
-		"calendar:calendar.event:create", // auto-approve (in allow list)
-		"zzz:unknown:scope",              // not in auto-approve
-		"sheets:spreadsheet:read",        // auto-approve (in allow list)
+		"sheets:spreadsheet:read", // auto-approve (recommend=true in priorities)
+		"zzz:unknown:scope",       // not in auto-approve
 	}
 
 	result := FilterAutoApproveScopes(scopes)
@@ -318,10 +288,10 @@ func TestFilterAutoApproveScopes(t *testing.T) {
 		t.Fatal("expected at least 1 auto-approve scope in result")
 	}
 
-	// Check that calendar:calendar.event:create is included
+	// Check that sheets:spreadsheet:read is included
 	found := false
 	for _, s := range result {
-		if s == "calendar:calendar.event:create" {
+		if s == "sheets:spreadsheet:read" {
 			found = true
 		}
 		// Ensure unknown scopes are not included
@@ -330,7 +300,7 @@ func TestFilterAutoApproveScopes(t *testing.T) {
 		}
 	}
 	if !found {
-		t.Error("expected calendar:calendar.event:create in result")
+		t.Error("expected sheets:spreadsheet:read in result")
 	}
 }
 

internal/registry/scope_overrides.json

@@ -12,25 +12,7 @@
     "vc:meeting.meetingevent:read": 75
   },
   "recommend": {
-    "allow": [
-      "calendar:calendar.event:create",
-      "calendar:calendar.event:delete",
-      "calendar:calendar.event:read",
-      "calendar:calendar.event:update",
-      "calendar:calendar.free_busy:read",
-      "calendar:calendar:create",
-      "calendar:calendar:delete",
-      "calendar:calendar:read",
-      "calendar:calendar:update",
-      "contact:user.basic_profile:readonly",
-      "mail:event",
-      "mail:user_mailbox.mail_contact:read",
-      "mail:user_mailbox.mail_contact:write",
-      "mail:user_mailbox.message.address:read",
-      "mail:user_mailbox.message.body:read",
-      "mail:user_mailbox.message.subject:read",
-      "mail:user_mailbox.message:readonly"
-    ],
+    "allow": [],
     "deny": [
       "im:chat",
       "im:message.send_as_user"

internal/selfupdate/updater.go

@@ -165,6 +165,10 @@ func (u *Updater) ListGlobalSkills() *NpmResult {
 	return u.runSkillsListGlobal()
 }
 
+func (u *Updater) ListGlobalSkillsJSON() *NpmResult {
+	return u.runSkillsCommand("-y", "skills", "ls", "-g", "--json")
+}
+
 func (u *Updater) InstallSkill(nameList []string) *NpmResult {
 	r := u.runSkillsInstall("https://open.feishu.cn", nameList)
 	if r.Err != nil {

internal/selfupdate/updater_test.go

@@ -188,6 +188,13 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 			},
 			want: "-y skills ls -g",
 		},
+		{
+			name: "list global json",
+			run: func(u *Updater) *NpmResult {
+				return u.ListGlobalSkillsJSON()
+			},
+			want: "-y skills ls -g --json",
+		},
 		{
 			name: "install skill primary",
 			run: func(u *Updater) *NpmResult {

internal/skillscheck/sync.go

@@ -4,6 +4,7 @@
 package skillscheck
 
 import (
+	"encoding/json"
 	"fmt"
 	"regexp"
 	"sort"
@@ -57,6 +58,28 @@ func ParseSkillsList(text string) []string {
 	return nil
 }
 
+func ParseGlobalSkillsJSON(text string) []string {
+	type globalSkill struct {
+		Name string `json:"name"`
+	}
+
+	var skills []globalSkill
+	if err := json.Unmarshal([]byte(text), &skills); err != nil {
+		return nil
+	}
+
+	seen := map[string]bool{}
+	for _, skill := range skills {
+		candidate := strings.TrimSpace(skill.Name)
+		if candidate == "" || !skillNamePattern.MatchString(candidate) {
+			continue
+		}
+		seen[candidate] = true
+	}
+
+	return sortedKeys(seen)
+}
+
 // parseGlobalSkillsList parses the output of "npx -y skills ls -g"
 func parseGlobalSkillsList(lines []string) []string {
 	seen := map[string]bool{}
@@ -77,8 +100,11 @@ func parseGlobalSkillsList(lines []string) []string {
 			continue
 		}
 
-		// Skip indented lines (Agents: ...)
-		if strings.HasPrefix(line, "  ") || strings.HasPrefix(line, "\t") {
+		if strings.HasPrefix(trimmed, "Agents:") {
+			continue
+		}
+
+		if isGlobalSkillsSectionHeader(trimmed) {
 			continue
 		}
 
@@ -91,21 +117,24 @@ func parseGlobalSkillsList(lines []string) []string {
 		candidate := parts[0]
 
 		// Validate and add
-		if candidate == "" || strings.Contains(candidate, " ") || strings.HasSuffix(candidate, ":") {
+		if candidate == "" || !skillNamePattern.MatchString(candidate) {
 			continue
 		}
-		if !skillNamePattern.MatchString(candidate) {
-			continue
-		}
-		if at := strings.Index(candidate, "@"); at > 0 {
-			candidate = candidate[:at]
-		}
 		seen[candidate] = true
 	}
 
 	return sortedKeys(seen)
 }
 
+func isGlobalSkillsSectionHeader(line string) bool {
+	switch line {
+	case "General", "Project", "Local":
+		return true
+	default:
+		return false
+	}
+}
+
 // parseOfficialSkillsList parses the output of "npx -y skills add ... --list"
 func parseOfficialSkillsList(lines []string) []string {
 	seen := map[string]bool{}
@@ -195,6 +224,7 @@ func PlanSync(input SyncInput) SyncPlan {
 
 type SkillsRunner interface {
 	ListOfficialSkills() *selfupdate.NpmResult
+	ListGlobalSkillsJSON() *selfupdate.NpmResult
 	ListGlobalSkills() *selfupdate.NpmResult
 	InstallSkill(nameList []string) *selfupdate.NpmResult
 	InstallAllSkills() *selfupdate.NpmResult
@@ -239,10 +269,9 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	}
 
 	// --- Step 2: List local (installed) skills ---
-	local := []string{}
-	localResult := opts.Runner.ListGlobalSkills()
-	if localResult != nil && localResult.Err == nil {
-		local = ParseSkillsList(localResult.Stdout.String())
+	local, ok := listLocalSkills(opts.Runner)
+	if !ok {
+		return fallbackFullInstall(opts, "local skills list failed or parsed as empty", official)
 	}
 
 	// --- Step 3: Read previous state ---
@@ -298,6 +327,24 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	return result
 }
 
+func listLocalSkills(runner SkillsRunner) ([]string, bool) {
+	jsonResult := runner.ListGlobalSkillsJSON()
+	if jsonResult != nil && jsonResult.Err == nil {
+		if local := ParseGlobalSkillsJSON(jsonResult.Stdout.String()); len(local) > 0 {
+			return local, true
+		}
+	}
+
+	textResult := runner.ListGlobalSkills()
+	if textResult != nil && textResult.Err == nil {
+		if local := ParseSkillsList(textResult.Stdout.String()); len(local) > 0 {
+			return local, true
+		}
+	}
+
+	return nil, false
+}
+
 // fallbackFullInstall performs a full skills install (npx -y skills add <source> -g -y)
 // when incremental sync is not possible. On success it writes a state file so that
 // subsequent syncs can use incremental mode. When official is non-nil the state

internal/skillscheck/sync_test.go

@@ -67,6 +67,49 @@ func TestParseGlobalSkillsListWithANSI(t *testing.T) {
 	}
 }
 
+func TestParseGlobalSkillsListWithIndentedGroupedRows(t *testing.T) {
+	input := `Global Skills
+
+General
+  lark-apps ~/.agents/skills/lark-apps
+  lark-base ~/.agents/skills/lark-base
+`
+	got := ParseSkillsList(input)
+	want := []string{"lark-apps", "lark-base"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ParseSkillsList() (indented Global Skills) = %#v, want %#v", got, want)
+	}
+}
+
+func TestParseGlobalSkillsJSON(t *testing.T) {
+	input := `[
+  {"name":"lark-calendar","path":"/Users/example/.agents/skills/lark-calendar","scope":"global","agents":["Codex"]},
+  {"name":"lark-mail@1.2.3","path":"/Users/example/.agents/skills/lark-mail","scope":"global","agents":["Codex"]},
+  {"name":"lark-calendar","path":"/Users/example/.agents/skills/lark-calendar","scope":"global","agents":["Codex"]},
+  {"name":"  lark-base  ","path":"/Users/example/.agents/skills/lark-base","scope":"global","agents":["Codex"]},
+  {"name":""},
+  {"name":"   "},
+  {"name":"bad skill"}
+]`
+	got := ParseGlobalSkillsJSON(input)
+	want := []string{"lark-base", "lark-calendar", "lark-mail@1.2.3"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ParseGlobalSkillsJSON() = %#v, want %#v", got, want)
+	}
+}
+
+func TestParseGlobalSkillsJSONInvalidOrUnsupported(t *testing.T) {
+	for _, input := range []string{
+		`not json`,
+		`{"name":"lark-calendar"}`,
+		`[]`,
+	} {
+		if got := ParseGlobalSkillsJSON(input); len(got) != 0 {
+			t.Fatalf("ParseGlobalSkillsJSON(%q) = %#v, want empty", input, got)
+		}
+	}
+}
+
 func TestPlanNormal_WithReadableStatePreservesDeletedAndAddsNew(t *testing.T) {
 	previous := &SkillsState{OfficialSkills: []string{"lark-calendar", "lark-mail"}}
 	got := PlanSync(SyncInput{
@@ -113,14 +156,18 @@ func TestPlanForceRestoresAllOfficial(t *testing.T) {
 }
 
 type fakeSkillsRunner struct {
-	officialOut   string
-	globalOut     string
-	officialErr   error
-	globalErr     error
-	installErr    error
-	installAllErr error
-	installed     [][]string
-	installedAll  int
+	officialOut      string
+	globalJSONOut    string
+	globalOut        string
+	officialErr      error
+	globalJSONErr    error
+	globalErr        error
+	installErr       error
+	installAllErr    error
+	installed        [][]string
+	installedAll     int
+	listedGlobalJSON int
+	listedGlobalText int
 }
 
 func officialSkillsOutput(names ...string) string {
@@ -146,6 +193,19 @@ func globalSkillsOutput(names ...string) string {
 	return b.String()
 }
 
+func globalSkillsJSONOutput(names ...string) string {
+	var b strings.Builder
+	b.WriteString("[")
+	for i, name := range names {
+		if i > 0 {
+			b.WriteString(",")
+		}
+		fmt.Fprintf(&b, `{"name":%q,"path":"/Users/example/.agents/skills/%s","scope":"global","agents":["Codex"]}`, name, name)
+	}
+	b.WriteString("]")
+	return b.String()
+}
+
 func (f *fakeSkillsRunner) ListOfficialSkills() *selfupdate.NpmResult {
 	r := &selfupdate.NpmResult{}
 	r.Stdout.WriteString(f.officialOut)
@@ -153,7 +213,16 @@ func (f *fakeSkillsRunner) ListOfficialSkills() *selfupdate.NpmResult {
 	return r
 }
 
+func (f *fakeSkillsRunner) ListGlobalSkillsJSON() *selfupdate.NpmResult {
+	f.listedGlobalJSON++
+	r := &selfupdate.NpmResult{}
+	r.Stdout.WriteString(f.globalJSONOut)
+	r.Err = f.globalJSONErr
+	return r
+}
+
 func (f *fakeSkillsRunner) ListGlobalSkills() *selfupdate.NpmResult {
+	f.listedGlobalText++
 	r := &selfupdate.NpmResult{}
 	r.Stdout.WriteString(f.globalOut)
 	r.Err = f.globalErr
@@ -186,8 +255,9 @@ func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	}
 
 	runner := &fakeSkillsRunner{
-		officialOut: officialSkillsOutput("lark-calendar", "lark-mail", "lark-new"),
-		globalOut:   globalSkillsOutput("lark-calendar", "lark-custom"),
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail", "lark-new"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-custom"),
+		globalOut:     globalSkillsOutput("lark-mail"),
 	}
 	result := SyncSkills(SyncOptions{
 		Version: "1.0.33",
@@ -199,6 +269,12 @@ func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
 	}
 	assertStrings(t, runner.installed[0], []string{"lark-calendar", "lark-new"})
+	if runner.listedGlobalJSON != 1 {
+		t.Fatalf("listedGlobalJSON = %d, want 1", runner.listedGlobalJSON)
+	}
+	if runner.listedGlobalText != 0 {
+		t.Fatalf("listedGlobalText = %d, want 0 when JSON list succeeds", runner.listedGlobalText)
+	}
 
 	state, readable, err := ReadState()
 	if err != nil || !readable {
@@ -262,47 +338,73 @@ func TestSyncSkills_ListOfficialFailureAndFullInstallFails(t *testing.T) {
 	}
 }
 
-func TestSyncSkills_GlobalListFailureDegradesToColdStart(t *testing.T) {
+func TestSyncSkills_GlobalJSONFailureFallsBackToTextList(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut: officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalErr:   fmt.Errorf("global list failed"),
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONErr: fmt.Errorf("json list failed"),
+		globalOut:     globalSkillsOutput("lark-calendar"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
 	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil (degraded to cold start)", result.Err)
+		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
 	}
 	if result.Action != "synced" {
 		t.Fatalf("SyncSkills() action = %q, want synced", result.Action)
 	}
 	assertStrings(t, result.Updated, []string{"lark-calendar", "lark-mail"})
-	assertStrings(t, result.SkippedDeleted, []string{})
+	if runner.listedGlobalJSON != 1 || runner.listedGlobalText != 1 {
+		t.Fatalf("listed JSON/text = %d/%d, want 1/1", runner.listedGlobalJSON, runner.listedGlobalText)
+	}
+	if runner.installedAll != 0 {
+		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
+	}
 }
 
-func TestSyncSkills_ParseEmptyGlobalListWithNonEmptyStdoutDegradesToColdStart(t *testing.T) {
+func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut: officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:   "Some unrecognized output format\n",
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONErr: fmt.Errorf("json list failed with /Users/example/.agents/skills/lark-calendar agents Codex"),
+		globalErr:     fmt.Errorf("text list failed with /Users/example/.agents/skills/lark-mail agents Codex"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil (degraded to cold start)", result.Err)
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
 	}
-	if result.Action != "synced" {
-		t.Fatalf("SyncSkills() action = %q, want synced", result.Action)
+	if len(runner.installed) != 0 {
+		t.Fatalf("installed = %#v, want no incremental installs", runner.installed)
 	}
-	assertStrings(t, result.Updated, []string{"lark-calendar", "lark-mail"})
-	assertStrings(t, result.SkippedDeleted, []string{})
-	if runner.installedAll != 0 {
-		t.Fatalf("installedAll = %d, want 0 (no fallback)", runner.installedAll)
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
 	}
-	if len(runner.installed) != 1 {
-		t.Fatalf("installed = %d calls, want 1 (incremental)", len(runner.installed))
+	if strings.Contains(result.Detail, "/Users/example") || strings.Contains(result.Detail, "agents") {
+		t.Fatalf("SyncSkills() detail leaks local command output: %q", result.Detail)
+	}
+}
+
+func TestSyncSkills_ParseEmptyLocalListsFallBackToFullInstall(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	runner := &fakeSkillsRunner{
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: `[]`,
+		globalOut:     "Some unrecognized output format\n",
+	}
+
+	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
+	}
+	if len(runner.installed) != 0 {
+		t.Fatalf("installed = %#v, want no incremental installs", runner.installed)
+	}
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
 	}
 }
 
@@ -344,6 +446,7 @@ func TestSyncSkills_InstallFailureFallsBackToFullInstall(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
 		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
 		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
 		installErr:    fmt.Errorf("incremental boom"),
 		installAllErr: nil,
@@ -375,6 +478,7 @@ func TestSyncSkills_InstallFailureAndFullInstallFails(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
 		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
 		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
 		installErr:    fmt.Errorf("incremental boom"),
 		installAllErr: fmt.Errorf("full install boom"),
@@ -473,6 +577,7 @@ func TestSyncSkills_FallbackWithKnownOfficialWritesFullState(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
 		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
 		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
 		installErr:    fmt.Errorf("incremental boom"),
 		installAllErr: nil,
@@ -497,6 +602,7 @@ func TestSyncSkills_FallbackResultContainsMetadata(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
 		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
 		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
 		installErr:    fmt.Errorf("incremental boom"),
 		installAllErr: nil,
@@ -537,8 +643,9 @@ func TestSyncSkills_FallbackBreaksDegradationLoop(t *testing.T) {
 	}
 
 	runner2 := &fakeSkillsRunner{
-		officialOut: officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:   globalSkillsOutput("lark-calendar", "lark-mail"),
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
 	}
 	result2 := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner2, Now: time.Now})
 	if result2.Action != "synced" {

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -15,7 +15,13 @@ import (
 // legacy validation/save helpers are forbidden; callers must use the typed
 // common replacements or construct an errs.* typed error directly.
 var migratedCommonHelperPaths = []string{
+	"shortcuts/base/",
+	"shortcuts/calendar/",
 	"shortcuts/drive/",
+	"shortcuts/mail/",
+	"shortcuts/okr/",
+	"shortcuts/task/",
+	"shortcuts/whiteboard/",
 }
 
 const commonImportPath = "github.com/larksuite/cli/shortcuts/common"

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -16,7 +16,14 @@ import (
 // call sites must return a typed errs.* error instead. Future domains opt in by
 // appending their path prefix here.
 var migratedEnvelopePaths = []string{
+	"shortcuts/base/",
+	"shortcuts/calendar/",
 	"shortcuts/drive/",
+	"shortcuts/mail/",
+	"shortcuts/okr/",
+	"shortcuts/task/",
+	"shortcuts/whiteboard/",
+	"shortcuts/im/",
 }
 
 // legacyOutputImportPath is the import path of the package that declares the

lint/errscontract/rule_no_legacy_runtime_api_call.go

@@ -18,7 +18,7 @@ import (
 // forbidigo's errs-typed-only ban does not see them because they are method
 // calls, not output.Err* identifiers — this AST rule covers that gap.
 //
-// Migrated code must call a typed API wrapper (e.g. drive's driveCallAPI) or use
+// Migrated code must call the domain's typed API wrapper or use
 // runtime.DoAPI + errclass.BuildAPIError directly, so failures classify into
 // typed errs.* errors.
 //
@@ -53,7 +53,7 @@ func CheckNoLegacyRuntimeAPICall(path, src string) []Violation {
 				File:    path,
 				Line:    fset.Position(call.Pos()).Line,
 				Message: "runtime." + name + " emits a legacy output.ExitError api_error envelope and downgrades typed network/auth boundary errors; it is forbidden on migrated paths",
-				Suggestion: "call the domain's typed API wrapper (e.g. driveCallAPI) or runtime.DoAPI + errclass.BuildAPIError " +
+				Suggestion: "call the domain's typed API wrapper (for example driveCallAPI or callTaskAPITyped) or runtime.DoAPI + errclass.BuildAPIError " +
 					"so failures classify into typed errs.* errors",
 			})
 		}

lint/errscontract/rules_test.go

@@ -618,6 +618,35 @@ func boom() error {
 	}
 }
 
+func TestCheckNoLegacyEnvelopeLiteral_RejectsExitErrorLiteralOnMigratedShortcutPaths(t *testing.T) {
+	for _, path := range []string{
+		"shortcuts/okr/okr_image_upload.go",
+		"shortcuts/task/task_update.go",
+		"shortcuts/whiteboard/whiteboard_update.go",
+	} {
+		t.Run(path, func(t *testing.T) {
+			src := `package migrated
+
+import "github.com/larksuite/cli/internal/output"
+
+func boom() error {
+	return &output.ExitError{Code: 1}
+}
+`
+			v := CheckNoLegacyEnvelopeLiteral(path, src)
+			if len(v) != 1 {
+				t.Fatalf("expected 1 violation, got %d: %+v", len(v), v)
+			}
+			if v[0].Action != ActionReject {
+				t.Errorf("action = %q, want REJECT", v[0].Action)
+			}
+			if !strings.Contains(v[0].Message, "ExitError") {
+				t.Errorf("message should name the legacy type: %s", v[0].Message)
+			}
+		})
+	}
+}
+
 func TestCheckNoLegacyEnvelopeLiteral_RejectsErrDetailLiteralOnDrivePath(t *testing.T) {
 	src := `package drive
 
@@ -662,7 +691,7 @@ func boom() error {
 	return &output.ExitError{Code: 1}
 }
 `
-	v := CheckNoLegacyEnvelopeLiteral("shortcuts/calendar/foo.go", src)
+	v := CheckNoLegacyEnvelopeLiteral("shortcuts/contact/foo.go", src)
 	if len(v) != 0 {
 		t.Errorf("non-migrated path should pass, got: %+v", v)
 	}
@@ -801,6 +830,26 @@ func boom(runtime *common.RuntimeContext) error {
 	}
 }
 
+func TestCheckNoLegacyRuntimeAPICall_RejectsCallAPIOnTaskPath(t *testing.T) {
+	src := `package task
+
+func boom(runtime *common.RuntimeContext) error {
+	_, err := runtime.CallAPI("POST", "/x", nil, nil)
+	return err
+}
+`
+	v := CheckNoLegacyRuntimeAPICall("shortcuts/task/task_update.go", src)
+	if len(v) != 1 {
+		t.Fatalf("expected 1 violation, got %d: %+v", len(v), v)
+	}
+	if v[0].Action != ActionReject {
+		t.Errorf("action = %q, want REJECT", v[0].Action)
+	}
+	if !strings.Contains(v[0].Message, "CallAPI") {
+		t.Errorf("message should name the legacy method: %s", v[0].Message)
+	}
+}
+
 func TestCheckNoLegacyRuntimeAPICall_RejectsDoAPIJSONWithLogIDOnDrivePath(t *testing.T) {
 	src := `package drive
 
@@ -851,14 +900,14 @@ func boom(runtime *common.RuntimeContext) error {
 }
 
 func TestCheckNoLegacyRuntimeAPICall_IgnoresNonMigratedPath(t *testing.T) {
-	src := `package im
+	src := `package contact
 
 func boom(runtime *common.RuntimeContext) error {
 	_, err := runtime.CallAPI("POST", "/x", nil, nil)
 	return err
 }
 `
-	v := CheckNoLegacyRuntimeAPICall("shortcuts/im/im_send.go", src)
+	v := CheckNoLegacyRuntimeAPICall("shortcuts/contact/contact_get.go", src)
 	if len(v) != 0 {
 		t.Errorf("non-migrated path must not fire, got: %+v", v)
 	}
@@ -894,32 +943,62 @@ func TestCheckNoLegacyCommonHelperCall_RejectsLegacyHelpersOnMigratedPath(t *tes
 		"ResolveOpenIDs",
 		"HandleApiResult",
 	}
-	for _, helper := range helpers {
-		t.Run(helper, func(t *testing.T) {
-			src := `package drive
+	paths := []string{
+		"shortcuts/drive/drive_search.go",
+		"shortcuts/mail/mail_send.go",
+		"shortcuts/okr/okr_progress_create.go",
+		"shortcuts/task/task_update.go",
+		"shortcuts/whiteboard/whiteboard_query.go",
+	}
+	for _, path := range paths {
+		for _, helper := range helpers {
+			t.Run(path+"_"+helper, func(t *testing.T) {
+				src := `package migrated
 
 import "github.com/larksuite/cli/shortcuts/common"
 
 func boom() {
-	common.` + helper + `()
+common.` + helper + `()
 }
 `
-			v := CheckNoLegacyCommonHelperCall("shortcuts/drive/drive_search.go", src)
-			if len(v) != 1 {
-				t.Fatalf("expected 1 violation for %s, got %d: %+v", helper, len(v), v)
-			}
-			if v[0].Action != ActionReject {
-				t.Errorf("action = %q, want REJECT", v[0].Action)
-			}
-			if !strings.Contains(v[0].Message, "common."+helper) {
-				t.Errorf("message should name helper %s: %s", helper, v[0].Message)
-			}
-		})
+				v := CheckNoLegacyCommonHelperCall(path, src)
+				if len(v) != 1 {
+					t.Fatalf("expected 1 violation for %s on %s, got %d: %+v", helper, path, len(v), v)
+				}
+				if v[0].Action != ActionReject {
+					t.Errorf("action = %q, want REJECT", v[0].Action)
+				}
+				if !strings.Contains(v[0].Message, "common."+helper) {
+					t.Errorf("message should name helper %s: %s", helper, v[0].Message)
+				}
+			})
+		}
+	}
+}
+
+func TestCheckNoLegacyCommonHelperCall_RejectsDangerousCharsOnCalendarPath(t *testing.T) {
+	src := `package calendar
+
+import "github.com/larksuite/cli/shortcuts/common"
+
+func boom() {
+	common.RejectDangerousChars("--summary", "x")
+}
+`
+	v := CheckNoLegacyCommonHelperCall("shortcuts/calendar/calendar_create.go", src)
+	if len(v) != 1 {
+		t.Fatalf("expected 1 violation, got %d: %+v", len(v), v)
+	}
+	if v[0].Action != ActionReject {
+		t.Errorf("action = %q, want REJECT", v[0].Action)
+	}
+	if !strings.Contains(v[0].Suggestion, "common.RejectDangerousCharsTyped") {
+		t.Errorf("suggestion should name typed replacement, got: %s", v[0].Suggestion)
 	}
 }
 
 func TestCheckNoLegacyCommonHelperCall_AllowsNonMigratedPath(t *testing.T) {
-	src := `package im
+	src := `package contact
 
 import "github.com/larksuite/cli/shortcuts/common"
 
@@ -927,7 +1006,7 @@ func boom() {
 	common.FlagErrorf("legacy allowed until domain migrates")
 }
 `
-	v := CheckNoLegacyCommonHelperCall("shortcuts/im/im_send.go", src)
+	v := CheckNoLegacyCommonHelperCall("shortcuts/contact/contact_get.go", src)
 	if len(v) != 0 {
 		t.Errorf("non-migrated path must pass, got: %+v", v)
 	}

package.json

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

shortcuts/base/base_advperm_disable.go

@@ -31,7 +31,7 @@ var BaseAdvpermDisable = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		return nil
 	},
@@ -55,6 +55,6 @@ var BaseAdvpermDisable = common.Shortcut{
 			return err
 		}
 
-		return handleRoleResponse(runtime, apiResp.RawBody, "disable advanced permissions failed")
+		return handleRoleAPIResponse(runtime, apiResp, "disable advanced permissions failed")
 	},
 }

shortcuts/base/base_advperm_enable.go

@@ -30,7 +30,7 @@ var BaseAdvpermEnable = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		return nil
 	},
@@ -54,6 +54,6 @@ var BaseAdvpermEnable = common.Shortcut{
 			return err
 		}
 
-		return handleRoleResponse(runtime, apiResp.RawBody, "enable advanced permissions failed")
+		return handleRoleAPIResponse(runtime, apiResp, "enable advanced permissions failed")
 	},
 }

shortcuts/base/base_advperm_test.go

@@ -196,9 +196,7 @@ func TestBaseAdvpermEnableExecuteAPIError(t *testing.T) {
 		},
 	})
 	args := []string{"+advperm-enable", "--base-token", "app_x"}
-	if err := runShortcut(t, BaseAdvpermEnable, args, factory, stdout); err == nil || !strings.Contains(err.Error(), "190001") {
-		t.Fatalf("err=%v", err)
-	}
+	assertProblemCode(t, runShortcut(t, BaseAdvpermEnable, args, factory, stdout), 190001, "bad request")
 }
 
 func TestBaseAdvpermDisableExecuteTransportError(t *testing.T) {
@@ -226,7 +224,5 @@ func TestBaseAdvpermDisableExecuteAPIError(t *testing.T) {
 		},
 	})
 	args := []string{"+advperm-disable", "--base-token", "app_x", "--yes"}
-	if err := runShortcut(t, BaseAdvpermDisable, args, factory, stdout); err == nil || !strings.Contains(err.Error(), "190002") {
-		t.Fatalf("err=%v", err)
-	}
+	assertProblemCode(t, runShortcut(t, BaseAdvpermDisable, args, factory, stdout), 190002, "permission denied")
 }

shortcuts/base/base_block_ops.go

@@ -55,24 +55,24 @@ func dryRunBaseBlockDelete(_ context.Context, runtime *common.RuntimeContext) *c
 
 func validateBaseBlockCreate(runtime *common.RuntimeContext) error {
 	if strings.TrimSpace(runtime.Str("name")) == "" {
-		return common.FlagErrorf("--name must not be blank")
+		return baseFlagErrorf("--name must not be blank")
 	}
 	if strings.TrimSpace(runtime.Str("type")) == "" {
-		return common.FlagErrorf("--type must not be blank")
+		return baseFlagErrorf("--type must not be blank")
 	}
 	return nil
 }
 
 func validateBaseBlockMove(runtime *common.RuntimeContext) error {
 	if strings.TrimSpace(runtime.Str("before-id")) != "" && strings.TrimSpace(runtime.Str("after-id")) != "" {
-		return common.FlagErrorf("--before-id and --after-id are mutually exclusive")
+		return baseFlagErrorf("--before-id and --after-id are mutually exclusive")
 	}
 	return nil
 }
 
 func validateBaseBlockRename(runtime *common.RuntimeContext) error {
 	if strings.TrimSpace(runtime.Str("name")) == "" {
-		return common.FlagErrorf("--name must not be blank")
+		return baseFlagErrorf("--name must not be blank")
 	}
 	return nil
 }

shortcuts/base/base_data_query.go

@@ -32,12 +32,12 @@ var BaseDataQuery = common.Shortcut{
 		dec := json.NewDecoder(bytes.NewReader([]byte(runtime.Str("dsl"))))
 		dec.UseNumber()
 		if err := dec.Decode(&dsl); err != nil {
-			return common.FlagErrorf("--dsl invalid JSON: %v", err)
+			return baseFlagErrorf("--dsl invalid JSON: %v", err)
 		}
 		_, hasDim := dsl["dimensions"]
 		_, hasMeas := dsl["measures"]
 		if !hasDim && !hasMeas {
-			return common.FlagErrorf("--dsl must contain at least one of 'dimensions' or 'measures'")
+			return baseFlagErrorf("--dsl must contain at least one of 'dimensions' or 'measures'")
 		}
 		return nil
 	},

shortcuts/base/base_errors.go

@@ -4,9 +4,13 @@
 package base
 
 import (
+	"errors"
+	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/util"
 )
 
@@ -24,76 +28,198 @@ func handleBaseAPIResult(result interface{}, err error, action string) (map[stri
 // structured ErrAPI, with server-provided message/hint promoted to the top level.
 func handleBaseAPIResultAny(result interface{}, err error, action string) (interface{}, error) {
 	if err != nil {
-		return nil, output.Errorf(output.ExitAPI, "api_error", "%s: %s", action, err)
+		return nil, baseAPIBoundaryError(err, action)
 	}
 
-	resultMap, _ := result.(map[string]interface{})
-	code, _ := util.ToFloat64(resultMap["code"])
+	resultMap, ok := result.(map[string]interface{})
+	if !ok || resultMap == nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "%s: API returned a malformed response envelope", action)
+	}
+	if _, exists := resultMap["code"]; !exists {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "%s: API response is missing code", action)
+	}
+	code, numeric := util.ToFloat64(resultMap["code"])
+	if !numeric {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "%s: API response code is not numeric", action)
+	}
 	if code == 0 {
 		return resultMap["data"], nil
 	}
 
-	larkCode := int(code)
-	msg := extractDataErrorMessage(resultMap)
-	if strings.TrimSpace(msg) == "" {
-		msg, _ = resultMap["msg"].(string)
-	}
-
-	detail := extractErrorDetail(resultMap)
-	apiErr := output.ErrAPI(larkCode, msg, detail)
-	hint := extractErrorHint(resultMap)
-	if apiErr.Detail != nil && apiErr.Detail.Hint == "" && hint != "" {
-		apiErr.Detail.Hint = hint
-	}
-	if apiErr.Detail != nil {
-		apiErr.Detail.Detail = cleanEmptyBaseErrorDetail(detail)
-	}
-	return nil, apiErr
+	return nil, baseAPIErrorFromResult(resultMap, errclass.ClassifyContext{})
 }
 
-func cleanEmptyBaseErrorDetail(detail interface{}) interface{} {
-	detailMap, ok := detail.(map[string]interface{})
-	if !ok {
-		return nil
+// baseFlagErrorf marks flag-usage failures; it shares baseValidationErrorf's
+// typed envelope and exists so call sites read as flag rejections.
+func baseFlagErrorf(format string, args ...any) error {
+	return baseValidationErrorf(format, args...)
+}
+
+func baseValidationErrorf(format string, args ...any) error {
+	msg := fmt.Sprintf(format, args...)
+	err := errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", msg)
+	if params := flagParams(msg); len(params) > 0 {
+		err = err.WithParam(params[0].Name).WithParams(params...)
 	}
-	for key, value := range detailMap {
-		if value == nil {
-			delete(detailMap, key)
+	if cause := firstErrorArg(args); cause != nil {
+		err = err.WithCause(cause)
+	}
+	return err
+}
+
+func flagParams(msg string) []errs.InvalidParam {
+	reason := msg
+	seen := map[string]bool{}
+	params := []errs.InvalidParam{}
+	for start := strings.Index(msg, "--"); start >= 0; start = strings.Index(msg, "--") {
+		end := start + 2
+		for end < len(msg) {
+			ch := msg[end]
+			if (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || (ch >= '0' && ch <= '9') || ch == '-' {
+				end++
+				continue
+			}
+			break
 		}
+		if end > start+2 {
+			name := msg[start:end]
+			if !seen[name] {
+				seen[name] = true
+				params = append(params, errs.InvalidParam{Name: name, Reason: reason})
+			}
+		}
+		msg = msg[end:]
 	}
-	if len(detailMap) == 0 {
-		return nil
-	}
-	return detailMap
+	return params
 }
 
-func extractErrorDetail(resultMap map[string]interface{}) interface{} {
-	if detail, ok := nonNilMapValue(resultMap, "error"); ok {
-		return detail
-	}
-	data, _ := resultMap["data"].(map[string]interface{})
-	if detail, ok := nonNilMapValue(data, "error"); ok {
-		return detail
+func firstErrorArg(args []any) error {
+	for _, arg := range args {
+		if err, ok := arg.(error); ok {
+			return err
+		}
 	}
 	return nil
 }
 
-func nonNilMapValue(src map[string]interface{}, key string) (interface{}, bool) {
-	if src == nil {
-		return nil, false
+// baseMissingFileIOError reports a broken runtime wiring: a command that needs
+// local file access was constructed without a FileIO provider. The user cannot
+// fix this by changing flags, so it classifies as internal, not validation.
+func baseMissingFileIOError(format string, args ...any) error {
+	return errs.NewInternalError(errs.SubtypeFileIO, format, args...)
+}
+
+func baseInputStatError(err error) error {
+	if err == nil {
+		return nil
 	}
-	value, ok := src[key]
-	if !ok {
-		return nil, false
+	if errors.Is(err, fileio.ErrPathValidation) {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe file path: %s", err).WithCause(err)
 	}
-	switch value.(type) {
-	case nil:
-		return nil, false
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot read file: %s", err).WithCause(err)
+}
+
+func baseSaveError(err error) error {
+	if err == nil {
+		return nil
+	}
+	var me *fileio.MkdirError
+	switch {
+	case errors.Is(err, fileio.ErrPathValidation):
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithCause(err)
+	case errors.As(err, &me):
+		return errs.NewInternalError(errs.SubtypeFileIO, "cannot create parent directory: %s", err).WithCause(err)
 	default:
-		return value, true
+		return errs.NewInternalError(errs.SubtypeFileIO, "cannot create file: %s", err).WithCause(err)
 	}
 }
 
+func baseAPIBoundaryError(err error, action string) error {
+	if _, ok := errs.ProblemOf(err); ok {
+		return err
+	}
+	return errs.NewNetworkError(errs.SubtypeNetworkTransport, "%s: %s", action, err).WithCause(err)
+}
+
+func baseUploadAttachmentError(filePath string, err error) error {
+	if p, ok := errs.ProblemOf(err); ok {
+		p.Message = fmt.Sprintf("failed to upload attachment %s: %s", filePath, p.Message)
+		return err
+	}
+	return errs.NewInternalError(errs.SubtypeSDKError, "failed to upload attachment %s: %s", filePath, err).WithCause(err)
+}
+
+func baseAPIErrorFromResult(resultMap map[string]interface{}, cc errclass.ClassifyContext) error {
+	if resultMap == nil {
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "API returned a malformed response envelope")
+	}
+	if msg := extractDataErrorMessage(resultMap); msg != "" {
+		resultMap["msg"] = msg
+	}
+	hint := extractErrorHint(resultMap)
+	if logID := extractBaseErrorLogID(resultMap); logID != "" {
+		resultMap["log_id"] = logID
+	}
+	err := errclass.BuildAPIError(resultMap, cc)
+	if err == nil {
+		return nil
+	}
+	if p, ok := errs.ProblemOf(err); ok && hint != "" {
+		p.Hint = hint
+	}
+	return err
+}
+
+func enrichBaseAPIErrorFromBody(err error, body []byte, cc errclass.ClassifyContext) error {
+	if _, ok := errs.ProblemOf(err); !ok {
+		return err
+	}
+	result, parseErr := decodeBaseV3Response(body)
+	if parseErr != nil {
+		return err
+	}
+	enriched := baseAPIErrorFromResult(result, cc)
+	if enriched == nil {
+		return err
+	}
+	src, _ := errs.ProblemOf(enriched)
+	dst, _ := errs.ProblemOf(err)
+	if src != nil && dst != nil {
+		dst.Message = src.Message
+		dst.Hint = src.Hint
+		// A body without log_id must not erase a header-derived LogID
+		// already carried by err.
+		if src.LogID != "" {
+			dst.LogID = src.LogID
+		}
+	}
+	return err
+}
+
+func extractBaseErrorLogID(resultMap map[string]interface{}) string {
+	for _, key := range []string{"log_id", "logid"} {
+		if logID, _ := resultMap[key].(string); strings.TrimSpace(logID) != "" {
+			return strings.TrimSpace(logID)
+		}
+	}
+	if detail, ok := resultMap["error"].(map[string]interface{}); ok {
+		for _, key := range []string{"log_id", "logid"} {
+			if logID, _ := detail[key].(string); strings.TrimSpace(logID) != "" {
+				return strings.TrimSpace(logID)
+			}
+		}
+	}
+	data, _ := resultMap["data"].(map[string]interface{})
+	if detail, ok := data["error"].(map[string]interface{}); ok {
+		for _, key := range []string{"log_id", "logid"} {
+			if logID, _ := detail[key].(string); strings.TrimSpace(logID) != "" {
+				return strings.TrimSpace(logID)
+			}
+		}
+	}
+	return ""
+}
+
 func extractErrorHint(resultMap map[string]interface{}) string {
 	if detail, ok := resultMap["error"].(map[string]interface{}); ok {
 		if hint := consumeStringField(detail, "hint"); hint != "" {

shortcuts/base/base_errors_test.go

@@ -4,30 +4,15 @@
 package base
 
 import (
-	"errors"
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/errclass"
 )
 
 func TestErrorDetailHelpers(t *testing.T) {
-	if value, ok := nonNilMapValue(nil, "error"); ok || value != nil {
-		t.Fatalf("nil map should not return value")
-	}
-	if value, ok := nonNilMapValue(map[string]interface{}{"error": nil}, "error"); ok || value != nil {
-		t.Fatalf("nil entry should not return value")
-	}
 	detail := map[string]interface{}{"message": "boom", "hint": "retry later"}
-	if value, ok := nonNilMapValue(map[string]interface{}{"error": detail}, "error"); !ok || value == nil {
-		t.Fatalf("expected non-nil detail")
-	}
-	if got := extractErrorDetail(map[string]interface{}{"error": detail}); got == nil {
-		t.Fatalf("expected root detail")
-	}
-	if got := extractErrorDetail(map[string]interface{}{"data": map[string]interface{}{"error": detail}}); got == nil {
-		t.Fatalf("expected nested detail")
-	}
 	if got := extractErrorHint(map[string]interface{}{"data": map[string]interface{}{"error": detail}}); got != "retry later" {
 		t.Fatalf("hint=%q", got)
 	}
@@ -53,9 +38,12 @@ func TestHandleBaseAPIResultErrorPaths(t *testing.T) {
 	if _, err := handleBaseAPIResultAny(result, nil, "set filter"); err == nil || !strings.Contains(err.Error(), "invalid filter") {
 		t.Fatalf("err=%v", err)
 	} else {
-		var exitErr *output.ExitError
-		if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Code != 190001 {
-			t.Fatalf("expected structured code 190001, got %v", err)
+		p, ok := errs.ProblemOf(err)
+		if !ok || p.Code != 190001 {
+			t.Fatalf("expected typed code 190001, got %T %v", err, err)
+		}
+		if p.Hint != "check field name" {
+			t.Fatalf("hint=%q", p.Hint)
 		}
 	}
 	if _, err := handleBaseAPIResult(result, nil, "set filter"); err == nil {
@@ -63,7 +51,7 @@ func TestHandleBaseAPIResultErrorPaths(t *testing.T) {
 	}
 }
 
-func TestHandleBaseAPIResultCleansBaseErrorDetail(t *testing.T) {
+func TestHandleBaseAPIResultPromotesBaseErrorFields(t *testing.T) {
 	result := map[string]interface{}{
 		"code": 800010407,
 		"msg":  "cell value invalid",
@@ -87,55 +75,27 @@ func TestHandleBaseAPIResultCleansBaseErrorDetail(t *testing.T) {
 	}
 
 	_, err := handleBaseAPIResultAny(result, nil, "API call failed")
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected structured exit error, got %v", err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T %v", err, err)
 	}
-
-	errDetail := exitErr.Detail
-	if errDetail.Code != 800010407 {
-		t.Fatalf("code=%d", errDetail.Code)
+	if p.Code != 800010407 {
+		t.Fatalf("code=%d", p.Code)
 	}
-	if errDetail.Hint != "Provide a number value." {
-		t.Fatalf("hint=%q", errDetail.Hint)
+	if p.Message != "The cell value does not match the expected input shape." {
+		t.Fatalf("message=%q", p.Message)
 	}
-	detail, _ := errDetail.Detail.(map[string]interface{})
-	if detail == nil {
-		t.Fatalf("expected cleaned detail, got %#v", errDetail.Detail)
+	if p.Hint != "Provide a number value." {
+		t.Fatalf("hint=%q", p.Hint)
 	}
-	if _, exists := detail["message"]; exists {
-		t.Fatalf("detail should not repeat message: %#v", detail)
-	}
-	if _, exists := detail["hint"]; exists {
-		t.Fatalf("detail should not repeat hint: %#v", detail)
-	}
-	if _, exists := detail["docs_url"]; exists {
-		t.Fatalf("detail should omit nil docs_url: %#v", detail)
-	}
-	if detail["level"] != "error" {
-		t.Fatalf("detail should preserve non-duplicate fields: %#v", detail)
-	}
-	if detail["extra_context"] != "future detail field" {
-		t.Fatalf("detail should pass through unknown non-nil fields: %#v", detail)
-	}
-	if detail["path"] != "Amount" || detail["value"] != "abc" {
-		t.Fatalf("cleaned detail mismatch: %#v", detail)
-	}
-	if detail["logid"] != "20260508160000000000000000000000" {
-		t.Fatalf("logid=%q", detail["logid"])
-	}
-	if retryable, ok := detail["retryable"].(bool); !ok || retryable {
-		t.Fatalf("retryable=%v", detail["retryable"])
-	}
-	table, _ := detail["table"].(map[string]interface{})
-	if table["id"] != "tbl_1" || table["name"] != "Orders" {
-		t.Fatalf("table=%#v", detail["table"])
+	if p.LogID != "20260508160000000000000000000000" {
+		t.Fatalf("logID=%q", p.LogID)
 	}
 }
 
-func TestHandleBaseAPIResultAlwaysRemovesMessageAndHintFromDetail(t *testing.T) {
+func TestHandleBaseAPIResultClassifiesKnownPermissionCode(t *testing.T) {
 	result := map[string]interface{}{
-		"code": output.LarkErrTokenNoPermission,
+		"code": 99991676,
 		"msg":  "permission denied",
 		"data": map[string]interface{}{
 			"error": map[string]interface{}{
@@ -146,15 +106,15 @@ func TestHandleBaseAPIResultAlwaysRemovesMessageAndHintFromDetail(t *testing.T)
 	}
 
 	_, err := handleBaseAPIResultAny(result, nil, "API call failed")
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected structured exit error, got %v", err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T %v", err, err)
 	}
-	if exitErr.Detail.Message != "Permission denied [99991676]" {
-		t.Fatalf("message=%q", exitErr.Detail.Message)
+	if p.Code != 99991676 {
+		t.Fatalf("code=%d", p.Code)
 	}
-	if exitErr.Detail.Detail != nil {
-		t.Fatalf("detail should be empty after removing message and hint: %#v", exitErr.Detail.Detail)
+	if p.Category != errs.CategoryAuthorization || p.Subtype != errs.SubtypeTokenScopeInsufficient {
+		t.Fatalf("category/subtype=%s/%s", p.Category, p.Subtype)
 	}
 }
 
@@ -167,16 +127,91 @@ func TestAttachBaseResponseLogIDFromHeader(t *testing.T) {
 	attachBaseErrorLogID(result, "20260508170000000000000000000000")
 
 	_, err := handleBaseAPIResultAny(result, nil, "API call failed")
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected structured exit error, got %v", err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T %v", err, err)
 	}
-	detail, _ := exitErr.Detail.Detail.(map[string]interface{})
-	if detail["logid"] != "20260508170000000000000000000000" {
-		t.Fatalf("logid=%q", detail["logid"])
+	if p.LogID != "20260508170000000000000000000000" {
+		t.Fatalf("logID=%q", p.LogID)
+	}
+}
+
+func TestHandleBaseAPIResultRejectsNonNumericCode(t *testing.T) {
+	for _, code := range []interface{}{"oops", map[string]interface{}{}, nil} {
+		result := map[string]interface{}{"code": code, "msg": "weird envelope"}
+		_, err := handleBaseAPIResultAny(result, nil, "list tables")
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("code=%#v: expected typed error, got %T %v", code, err, err)
+		}
+		if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+			t.Fatalf("code=%#v: category/subtype=%s/%s", code, p.Category, p.Subtype)
+		}
+		if !strings.Contains(p.Message, "list tables") {
+			t.Fatalf("code=%#v: message=%q", code, p.Message)
+		}
+	}
+}
+
+func TestEnrichBaseAPIErrorFromBodyLogIDMerge(t *testing.T) {
+	t.Run("body without log_id keeps header-derived LogID", func(t *testing.T) {
+		outer := errs.NewAPIError(errs.SubtypeUnknown, "outer failure").WithCode(190001).WithLogID("header-log-id")
+		err := enrichBaseAPIErrorFromBody(outer, []byte(`{"code":190001,"msg":"boom"}`), errclass.ClassifyContext{})
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("expected typed error, got %T %v", err, err)
+		}
+		if p.Message != "boom" {
+			t.Fatalf("message=%q", p.Message)
+		}
+		if p.LogID != "header-log-id" {
+			t.Fatalf("logID=%q, want header-log-id", p.LogID)
+		}
+	})
+
+	t.Run("body log_id overrides header-derived LogID", func(t *testing.T) {
+		outer := errs.NewAPIError(errs.SubtypeUnknown, "outer failure").WithCode(190001).WithLogID("header-log-id")
+		body := `{"code":190001,"msg":"boom","data":{"error":{"logid":"body-log-id"}}}`
+		err := enrichBaseAPIErrorFromBody(outer, []byte(body), errclass.ClassifyContext{})
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("expected typed error, got %T %v", err, err)
+		}
+		if p.LogID != "body-log-id" {
+			t.Fatalf("logID=%q, want body-log-id", p.LogID)
+		}
+	})
+}
+
+func TestBaseMissingFileIOErrorIsInternal(t *testing.T) {
+	p, ok := errs.ProblemOf(baseMissingFileIOError("file operations require a FileIO provider"))
+	if !ok {
+		t.Fatal("expected typed error")
+	}
+	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeFileIO {
+		t.Fatalf("category/subtype=%s/%s", p.Category, p.Subtype)
 	}
 }
 
 type assertErr struct{}
 
 func (assertErr) Error() string { return "network timeout" }
+
+func assertProblemCode(t *testing.T, err error, code int, messageParts ...string) {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("expected error with code %d", code)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T %v", err, err)
+	}
+	if p.Code != code {
+		t.Fatalf("code=%d, want %d; err=%v", p.Code, code, err)
+	}
+	for _, part := range messageParts {
+		if !strings.Contains(p.Message, part) {
+			t.Fatalf("message=%q missing %q", p.Message, part)
+		}
+	}
+}

shortcuts/base/base_execute_test.go

@@ -18,6 +18,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -513,6 +514,65 @@ func TestBaseBlockExecuteShortcuts(t *testing.T) {
 	}
 }
 
+func TestBaseBlockValidationReturnsTypedErrors(t *testing.T) {
+	factory, stdout, _ := newExecuteFactory(t)
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		args     []string
+		params   []string
+	}{
+		{
+			name:     "create blank name",
+			shortcut: BaseBaseBlockCreate,
+			args:     []string{"+base-block-create", "--base-token", "app_x", "--type", "docx", "--name", " "},
+			params:   []string{"--name"},
+		},
+		{
+			name:     "move conflicting sibling anchors",
+			shortcut: BaseBaseBlockMove,
+			args:     []string{"+base-block-move", "--base-token", "app_x", "--block-id", "blk_doc", "--before-id", "blk_a", "--after-id", "blk_b"},
+			params:   []string{"--before-id", "--after-id"},
+		},
+		{
+			name:     "rename blank name",
+			shortcut: BaseBaseBlockRename,
+			args:     []string{"+base-block-rename", "--base-token", "app_x", "--block-id", "blk_doc", "--name", " "},
+			params:   []string{"--name"},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := runShortcut(t, tt.shortcut, tt.args, factory, stdout)
+			p, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed problem, got %T %v", err, err)
+			}
+			if p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("category/subtype=%s/%s", p.Category, p.Subtype)
+			}
+			var validationErr *errs.ValidationError
+			if !errors.As(err, &validationErr) {
+				t.Fatalf("expected ValidationError, got %T %v", err, err)
+			}
+			if validationErr.Param != tt.params[0] {
+				t.Fatalf("param=%q, want %q", validationErr.Param, tt.params[0])
+			}
+			if len(validationErr.Params) != len(tt.params) {
+				t.Fatalf("params=%#v, want %v", validationErr.Params, tt.params)
+			}
+			for i, param := range tt.params {
+				if validationErr.Params[i].Name != param {
+					t.Fatalf("params=%#v, want %v", validationErr.Params, tt.params)
+				}
+				if validationErr.Params[i].Reason == "" {
+					t.Fatalf("params[%d] missing reason: %#v", i, validationErr.Params)
+				}
+			}
+		})
+	}
+}
+
 func TestBaseHistoryExecute(t *testing.T) {
 	factory, stdout, reg := newExecuteFactory(t)
 	reg.Register(&httpmock.Stub{
@@ -871,10 +931,10 @@ func TestBaseTableExecuteReadAndDelete(t *testing.T) {
 	t.Run("list-http-404", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables",
-			Status: 404,
-			Body:   "404 page not found",
+			Method:  "GET",
+			URL:     "/open-apis/base/v3/bases/app_x/tables",
+			Status:  404,
+			RawBody: []byte("404 page not found"),
 			Headers: map[string][]string{
 				"Content-Type": {"text/plain"},
 			},
@@ -2093,6 +2153,9 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		if !strings.Contains(err.Error(), "exceeds 2GB limit") {
 			t.Fatalf("err=%v", err)
 		}
+		if !strings.Contains(err.Error(), filepath.Base(tmpFile.Name())) {
+			t.Fatalf("err=%v should name the offending file", err)
+		}
 	})
 
 	t.Run("upload attachment rejects deprecated name flag", func(t *testing.T) {
@@ -2262,6 +2325,23 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
+	t.Run("download surfaces unsafe output path instead of directory hint", func(t *testing.T) {
+		factory, stdout, _ := newExecuteFactory(t)
+		tmpDir := t.TempDir()
+		withBaseWorkingDir(t, tmpDir)
+
+		err := runShortcut(t, BaseRecordDownloadAttachment, []string{
+			"+record-download-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--output", "../escape",
+		}, factory, stdout)
+		if err == nil || !strings.Contains(err.Error(), "unsafe output path") {
+			t.Fatalf("err=%v", err)
+		}
+	})
+
 	t.Run("download all disambiguates duplicate attachment names with file token", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
@@ -2458,21 +2538,37 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			"--record-id", "rec_x",
 			"--output", "downloads",
 		}, factory, stdout)
-		if err == nil || !strings.Contains(err.Error(), "download failed after 1 attachment(s) succeeded and 1 failed") {
+		if err == nil {
 			t.Fatalf("err=%v", err)
 		}
-		var exitErr *output.ExitError
-		if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-			t.Fatalf("expected structured error, got %T %v", err, err)
+		var partialErr *output.PartialFailureError
+		if !errors.As(err, &partialErr) {
+			t.Fatalf("expected partial failure error, got %T %v", err, err)
 		}
-		detail, _ := exitErr.Detail.Detail.(map[string]interface{})
-		downloaded, _ := detail["downloaded"].([]map[string]interface{})
-		failed, _ := detail["failed"].([]map[string]interface{})
-		if len(downloaded) != 1 || downloaded[0]["file_token"] != "box_a" || len(failed) != 1 || failed[0]["file_token"] != "box_b" {
-			t.Fatalf("detail=%#v", exitErr.Detail.Detail)
+
+		var envelope map[string]interface{}
+		if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+			t.Fatalf("failed to decode partial failure output: %v\nraw=%s", err, stdout.String())
 		}
-		if detail["log_id"] != "202605270001" {
-			t.Fatalf("detail=%#v, want log_id", exitErr.Detail.Detail)
+		if envelope["ok"] != false {
+			t.Fatalf("ok=%#v, want false; envelope=%#v", envelope["ok"], envelope)
+		}
+		data, _ := envelope["data"].(map[string]interface{})
+		if msg, _ := data["message"].(string); !strings.Contains(msg, "download failed after 1 attachment(s) succeeded and 1 failed") {
+			t.Fatalf("message=%q", msg)
+		}
+		downloaded, _ := data["downloaded"].([]interface{})
+		failed, _ := data["failed"].([]interface{})
+		if len(downloaded) != 1 || len(failed) != 1 {
+			t.Fatalf("data=%#v", data)
+		}
+		downloadedItem, _ := downloaded[0].(map[string]interface{})
+		failedItem, _ := failed[0].(map[string]interface{})
+		if downloadedItem["file_token"] != "box_a" || failedItem["file_token"] != "box_b" {
+			t.Fatalf("data=%#v", data)
+		}
+		if data["log_id"] != "202605270001" {
+			t.Fatalf("data=%#v, want log_id", data)
 		}
 		if _, err := os.Stat(filepath.Join(tmpDir, "downloads", "a.txt")); err != nil {
 			t.Fatalf("expected first file to remain: %v", err)

shortcuts/base/base_form_questions_create.go

@@ -42,7 +42,7 @@ var BaseFormQuestionsCreate = common.Shortcut{
 
 		var questions []interface{}
 		if err := json.Unmarshal([]byte(questionsJSON), &questions); err != nil {
-			return output.Errorf(output.ExitValidation, "invalid_json", "--questions must be a valid JSON array: %s", err)
+			return baseValidationErrorf("--questions must be a valid JSON array: %s", err)
 		}
 
 		data, err := baseV3Call(runtime, "POST",

shortcuts/base/base_form_questions_delete.go

@@ -7,7 +7,6 @@ import (
 	"context"
 	"encoding/json"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -43,7 +42,7 @@ var BaseFormQuestionsDelete = common.Shortcut{
 
 		var questionIds []string
 		if err := json.Unmarshal([]byte(questionIdsJSON), &questionIds); err != nil {
-			return output.Errorf(output.ExitValidation, "invalid_json", "--question-ids must be a valid JSON array of strings: %s", err)
+			return baseValidationErrorf("--question-ids must be a valid JSON array of strings: %s", err)
 		}
 
 		_, err := baseV3Call(runtime, "DELETE",

shortcuts/base/base_form_questions_update.go

@@ -42,7 +42,7 @@ var BaseFormQuestionsUpdate = common.Shortcut{
 
 		var questions []interface{}
 		if err := json.Unmarshal([]byte(questionsJSON), &questions); err != nil {
-			return output.Errorf(output.ExitValidation, "invalid_json", "--questions must be a valid JSON array: %s", err)
+			return baseValidationErrorf("--questions must be a valid JSON array: %s", err)
 		}
 
 		data, err := baseV3Call(runtime, "PATCH",

shortcuts/base/base_form_submit.go

@@ -14,7 +14,6 @@ import (
 	"golang.org/x/sync/errgroup"
 
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -62,31 +61,31 @@ func validateFormSubmit(runtime *common.RuntimeContext) error {
 	attachments, hasAttachments := raw["attachments"]
 
 	if !hasAttachments && fields == nil {
-		return common.FlagErrorf("--json must contain at least \"fields\" or \"attachments\"")
+		return baseFlagErrorf("--json must contain at least \"fields\" or \"attachments\"")
 	}
 
 	if hasAttachments {
 		// 有附件时 --base-token 必填（上传附件到 Base Drive Media 需要）
 		if runtime.Str("base-token") == "" {
-			return common.FlagErrorf("--base-token is required when --json contains \"attachments\"")
+			return baseFlagErrorf("--base-token is required when --json contains \"attachments\"")
 		}
 
 		attMap, ok := attachments.(map[string]interface{})
 		if !ok {
-			return common.FlagErrorf("--json.attachments must be a JSON object mapping field names to file path arrays")
+			return baseFlagErrorf("--json.attachments must be a JSON object mapping field names to file path arrays")
 		}
 		for fieldName, value := range attMap {
 			paths, ok := value.([]interface{})
 			if !ok {
-				return common.FlagErrorf("--json.attachments.%q must be a file path array, got %T", fieldName, value)
+				return baseFlagErrorf("--json.attachments.%q must be a file path array, got %T", fieldName, value)
 			}
 			for i, item := range paths {
 				if _, ok := item.(string); !ok {
-					return common.FlagErrorf("--json.attachments.%q[%d] must be a file path string, got %T", fieldName, i, item)
+					return baseFlagErrorf("--json.attachments.%q[%d] must be a file path string, got %T", fieldName, i, item)
 				}
 			}
 			if len(paths) == 0 {
-				return common.FlagErrorf("--json.attachments.%q must not be empty; remove it or provide at least one file path", fieldName)
+				return baseFlagErrorf("--json.attachments.%q must not be empty; remove it or provide at least one file path", fieldName)
 			}
 		}
 	}
@@ -111,21 +110,21 @@ func parseFormSubmitJSON(runtime *common.RuntimeContext) (map[string]interface{}
 	if attachments, ok := raw["attachments"]; ok {
 		attObj, ok := attachments.(map[string]interface{})
 		if !ok {
-			return nil, nil, common.FlagErrorf(`--json.attachments must be a JSON object mapping field names to file path arrays`)
+			return nil, nil, baseFlagErrorf(`--json.attachments must be a JSON object mapping field names to file path arrays`)
 		}
 		if len(attObj) > 0 {
 			attMap = make(map[string][]string, len(attObj))
 			for fieldName, value := range attObj {
 				paths, ok := value.([]interface{})
 				if !ok {
-					return nil, nil, common.FlagErrorf("--json.attachments.%q must be a file path array, got %T", fieldName, value)
+					return nil, nil, baseFlagErrorf("--json.attachments.%q must be a file path array, got %T", fieldName, value)
 				}
 				filePaths := make([]string, 0, len(paths))
 				for _, item := range paths {
 					if s, ok := item.(string); ok {
 						filePaths = append(filePaths, s)
 					} else {
-						return nil, nil, common.FlagErrorf("--json.attachments.%q must contain file path strings only, got %T", fieldName, item)
+						return nil, nil, baseFlagErrorf("--json.attachments.%q must contain file path strings only, got %T", fieldName, item)
 					}
 				}
 				if len(filePaths) > 0 {
@@ -195,33 +194,33 @@ func executeFormSubmit(runtime *common.RuntimeContext) error {
 		baseToken := runtime.Str("base-token")
 		fio := runtime.FileIO()
 		if fio == nil {
-			return output.ErrValidation("file operations require a FileIO provider (needed for attachments in --json)")
+			return baseMissingFileIOError("file operations require a FileIO provider (needed for attachments in --json)")
 		}
 
 		// Step 1: 收集所有唯一路径（跨字段去重）
 		allPaths := collectUniquePaths(attachmentMap)
 		if len(allPaths) == 0 {
-			return common.FlagErrorf("attachments in --json contains no valid file paths")
+			return baseFlagErrorf("attachments in --json contains no valid file paths")
 		}
 
 		// Step 2: 前置校验所有文件路径安全性与可访问性，同时收集文件大小供上传使用
 		sizeMap := make(map[string]int64, len(allPaths))
 		for _, filePath := range allPaths {
 			if _, err := validate.SafeInputPath(filePath); err != nil {
-				return output.ErrValidation("unsafe attachment file path: %s: %v", filePath, err)
+				return baseValidationErrorf("unsafe attachment file path: %s: %v", filePath, err)
 			}
 			fileInfo, err := fio.Stat(filePath)
 			if err != nil {
 				if errors.Is(err, fileio.ErrPathValidation) {
-					return output.ErrValidation("unsafe attachment file path: %s: %v", filePath, err)
+					return baseValidationErrorf("unsafe attachment file path: %s: %v", filePath, err)
 				}
-				return output.ErrValidation("attachment file not accessible: %s: %v", filePath, err)
+				return baseValidationErrorf("attachment file not accessible: %s: %v", filePath, err)
 			}
 			if fileInfo.Size() > baseAttachmentUploadMaxFileSize {
-				return output.ErrValidation("attachment file %s exceeds 2GB limit", filePath)
+				return baseValidationErrorf("attachment file %s exceeds 2GB limit", filePath)
 			}
 			if !fileInfo.Mode().IsRegular() {
-				return output.ErrValidation("attachment file %s is not a regular file", filePath)
+				return baseValidationErrorf("attachment file %s is not a regular file", filePath)
 			}
 			sizeMap[filePath] = fileInfo.Size()
 		}
@@ -328,7 +327,7 @@ func uploadAttachmentsParallel(runtime *common.RuntimeContext, paths []string, t
 func uploadSingleAttachment(runtime *common.RuntimeContext, filePath, fileName string, fileSize int64, target baseAttachmentUploadTarget) (interface{}, error) {
 	att, err := uploadAttachmentToBase(runtime, filePath, fileName, fileSize, target)
 	if err != nil {
-		return nil, fmt.Errorf("failed to upload attachment %s: %w", filePath, err)
+		return nil, baseUploadAttachmentError(filePath, err)
 	}
 	return att, nil
 }

shortcuts/base/base_role_common.go

@@ -5,9 +5,10 @@ package base
 
 import (
 	"encoding/json"
-	"fmt"
 
-	"github.com/larksuite/cli/internal/output"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -17,6 +18,14 @@ import (
 //   - Inner: business-level code/message inside the data object
 //
 // The data field may be a JSON object (actual behavior) or a JSON string (per doc).
+func handleRoleAPIResponse(runtime *common.RuntimeContext, apiResp *larkcore.ApiResp, action string) error {
+	if _, err := runtime.ClassifyAPIResponse(apiResp); err != nil {
+		enriched := enrichBaseAPIErrorFromBody(err, apiResp.RawBody, runtime.APIClassifyContext())
+		return prefixRoleActionError(enriched, action)
+	}
+	return handleRoleResponse(runtime, apiResp.RawBody, action)
+}
+
 func handleRoleResponse(runtime *common.RuntimeContext, rawBody []byte, action string) error {
 	var resp struct {
 		Code int             `json:"code"`
@@ -24,23 +33,17 @@ func handleRoleResponse(runtime *common.RuntimeContext, rawBody []byte, action s
 		Data json.RawMessage `json:"data"`
 	}
 	if err := json.Unmarshal(rawBody, &resp); err != nil {
-		return fmt.Errorf("failed to parse response: %v", err)
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "%s: failed to parse response: %v", action, err).WithCause(err)
 	}
 	if resp.Code != 0 {
-		msg := resp.Msg
-		// When outer msg is empty, try to extract error details from data.error.message
-		if msg == "" && len(resp.Data) > 0 {
-			var errData struct {
-				Error struct {
-					Message string `json:"message"`
-					Hint    string `json:"hint"`
-				} `json:"error"`
-			}
-			if json.Unmarshal(resp.Data, &errData) == nil && errData.Error.Message != "" {
-				msg = errData.Error.Message
+		result := map[string]interface{}{"code": resp.Code, "msg": resp.Msg}
+		if len(resp.Data) > 0 {
+			var data interface{}
+			if json.Unmarshal(resp.Data, &data) == nil {
+				result["data"] = data
 			}
 		}
-		return output.ErrAPI(resp.Code, fmt.Sprintf("%s: [%d] %s", action, resp.Code, msg), nil)
+		return baseRoleAPIError(runtime, result, action)
 	}
 
 	if len(resp.Data) == 0 || string(resp.Data) == "null" || string(resp.Data) == `""` {
@@ -75,7 +78,8 @@ func handleRoleResponse(runtime *common.RuntimeContext, rawBody []byte, action s
 			}
 			if codeInt != 0 {
 				msg, _ := m["message"].(string)
-				return output.ErrAPI(codeInt, fmt.Sprintf("%s: [%d] %s", action, codeInt, msg), nil)
+				result := map[string]interface{}{"code": codeInt, "msg": msg, "data": m}
+				return baseRoleAPIError(runtime, result, action)
 			}
 			// code == 0, extract the inner data if present
 			if innerData, hasInner := m["data"]; hasInner {
@@ -98,3 +102,20 @@ func handleRoleResponse(runtime *common.RuntimeContext, rawBody []byte, action s
 	runtime.Out(data, nil)
 	return nil
 }
+
+func baseRoleAPIError(runtime *common.RuntimeContext, result map[string]interface{}, action string) error {
+	return prefixRoleActionError(baseAPIErrorFromResult(result, runtime.APIClassifyContext()), action)
+}
+
+// prefixRoleActionError prepends the failed role action ("create role failed",
+// "get role failed", ...) to a typed error's message so both the classified
+// outer-response path and the parsed-body path carry the same context.
+func prefixRoleActionError(err error, action string) error {
+	if err == nil {
+		return nil
+	}
+	if p, ok := errs.ProblemOf(err); ok && action != "" {
+		p.Message = action + ": " + p.Message
+	}
+	return err
+}

shortcuts/base/base_role_create.go

@@ -34,11 +34,11 @@ var BaseRoleCreate = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		var body map[string]any
 		if err := json.Unmarshal([]byte(runtime.Str("json")), &body); err != nil {
-			return common.FlagErrorf("--json must be valid JSON: %v", err)
+			return baseFlagErrorf("--json must be valid JSON: %v", err)
 		}
 		return nil
 	},
@@ -64,6 +64,6 @@ var BaseRoleCreate = common.Shortcut{
 			return err
 		}
 
-		return handleRoleResponse(runtime, apiResp.RawBody, "create role failed")
+		return handleRoleAPIResponse(runtime, apiResp, "create role failed")
 	},
 }

shortcuts/base/base_role_delete.go

@@ -34,10 +34,10 @@ var BaseRoleDelete = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		if strings.TrimSpace(runtime.Str("role-id")) == "" {
-			return common.FlagErrorf("--role-id must not be blank")
+			return baseFlagErrorf("--role-id must not be blank")
 		}
 		return nil
 	},
@@ -60,6 +60,6 @@ var BaseRoleDelete = common.Shortcut{
 			return err
 		}
 
-		return handleRoleResponse(runtime, apiResp.RawBody, "delete role failed")
+		return handleRoleAPIResponse(runtime, apiResp, "delete role failed")
 	},
 }

shortcuts/base/base_role_get.go

@@ -33,10 +33,10 @@ var BaseRoleGet = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		if strings.TrimSpace(runtime.Str("role-id")) == "" {
-			return common.FlagErrorf("--role-id must not be blank")
+			return baseFlagErrorf("--role-id must not be blank")
 		}
 		return nil
 	},
@@ -58,6 +58,6 @@ var BaseRoleGet = common.Shortcut{
 			return err
 		}
 
-		return handleRoleResponse(runtime, apiResp.RawBody, "get role failed")
+		return handleRoleAPIResponse(runtime, apiResp, "get role failed")
 	},
 }

shortcuts/base/base_role_list.go

@@ -32,7 +32,7 @@ var BaseRoleList = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		return nil
 	},
@@ -52,6 +52,6 @@ var BaseRoleList = common.Shortcut{
 			return err
 		}
 
-		return handleRoleResponse(runtime, apiResp.RawBody, "list roles failed")
+		return handleRoleAPIResponse(runtime, apiResp, "list roles failed")
 	},
 }

shortcuts/base/base_role_test.go

@@ -375,9 +375,7 @@ func TestBaseRoleCreateExecuteAPIError(t *testing.T) {
 		},
 	})
 	args := []string{"+role-create", "--base-token", "app_x", "--json", `{"role_name":"Bad"}`}
-	if err := runShortcut(t, BaseRoleCreate, args, factory, stdout); err == nil || !strings.Contains(err.Error(), "190001") {
-		t.Fatalf("err=%v", err)
-	}
+	assertProblemCode(t, runShortcut(t, BaseRoleCreate, args, factory, stdout), 190001, "create role failed", "bad request")
 }
 
 func TestBaseRoleListExecuteTransportError(t *testing.T) {
@@ -405,9 +403,7 @@ func TestBaseRoleListExecuteAPIError(t *testing.T) {
 		},
 	})
 	args := []string{"+role-list", "--base-token", "app_x"}
-	if err := runShortcut(t, BaseRoleList, args, factory, stdout); err == nil || !strings.Contains(err.Error(), "190002") {
-		t.Fatalf("err=%v", err)
-	}
+	assertProblemCode(t, runShortcut(t, BaseRoleList, args, factory, stdout), 190002, "not found")
 }
 
 func TestBaseRoleDeleteExecuteAPIError(t *testing.T) {
@@ -421,9 +417,7 @@ func TestBaseRoleDeleteExecuteAPIError(t *testing.T) {
 		},
 	})
 	args := []string{"+role-delete", "--base-token", "app_x", "--role-id", "rol_1", "--yes"}
-	if err := runShortcut(t, BaseRoleDelete, args, factory, stdout); err == nil || !strings.Contains(err.Error(), "190003") {
-		t.Fatalf("err=%v", err)
-	}
+	assertProblemCode(t, runShortcut(t, BaseRoleDelete, args, factory, stdout), 190003, "forbidden")
 }
 
 func TestBaseRoleUpdateExecuteAPIError(t *testing.T) {
@@ -437,9 +431,7 @@ func TestBaseRoleUpdateExecuteAPIError(t *testing.T) {
 		},
 	})
 	args := []string{"+role-update", "--base-token", "app_x", "--role-id", "rol_1", "--json", `{"role_name":"X"}`, "--yes"}
-	if err := runShortcut(t, BaseRoleUpdate, args, factory, stdout); err == nil || !strings.Contains(err.Error(), "190004") {
-		t.Fatalf("err=%v", err)
-	}
+	assertProblemCode(t, runShortcut(t, BaseRoleUpdate, args, factory, stdout), 190004, "invalid params")
 }
 
 func TestBaseRoleGetExecuteBusinessError(t *testing.T) {
@@ -457,9 +449,7 @@ func TestBaseRoleGetExecuteBusinessError(t *testing.T) {
 		},
 	})
 	args := []string{"+role-get", "--base-token", "app_x", "--role-id", "rol_bad"}
-	if err := runShortcut(t, BaseRoleGet, args, factory, stdout); err == nil || !strings.Contains(err.Error(), "100001") || !strings.Contains(err.Error(), "role not found") {
-		t.Fatalf("err=%v", err)
-	}
+	assertProblemCode(t, runShortcut(t, BaseRoleGet, args, factory, stdout), 100001, "role not found")
 }
 
 // ---------------------------------------------------------------------------
@@ -487,9 +477,7 @@ func TestHandleRoleResponse(t *testing.T) {
 
 	t.Run("outer error code", func(t *testing.T) {
 		rt := newRoleResponseRuntime(t)
-		if err := handleRoleResponse(rt, []byte(`{"code":999,"msg":"outer error"}`), "test"); err == nil || !strings.Contains(err.Error(), "999") {
-			t.Fatalf("err=%v", err)
-		}
+		assertProblemCode(t, handleRoleResponse(rt, []byte(`{"code":999,"msg":"outer error"}`), "test"), 999, "outer error")
 	})
 
 	t.Run("outer error code with empty msg and data.error.message", func(t *testing.T) {
@@ -574,9 +562,7 @@ func TestHandleRoleResponse(t *testing.T) {
 	t.Run("business code non-zero", func(t *testing.T) {
 		rt := newRoleResponseRuntime(t)
 		body := `{"code":0,"msg":"ok","data":{"code":50001,"message":"permission denied"}}`
-		if err := handleRoleResponse(rt, []byte(body), "test"); err == nil || !strings.Contains(err.Error(), "50001") {
-			t.Fatalf("err=%v", err)
-		}
+		assertProblemCode(t, handleRoleResponse(rt, []byte(body), "test"), 50001, "permission denied")
 	})
 
 	t.Run("data is array", func(t *testing.T) {

shortcuts/base/base_role_update.go

@@ -36,14 +36,14 @@ var BaseRoleUpdate = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		if strings.TrimSpace(runtime.Str("role-id")) == "" {
-			return common.FlagErrorf("--role-id must not be blank")
+			return baseFlagErrorf("--role-id must not be blank")
 		}
 		var body map[string]any
 		if err := json.Unmarshal([]byte(runtime.Str("json")), &body); err != nil {
-			return common.FlagErrorf("--json must be valid JSON: %v", err)
+			return baseFlagErrorf("--json must be valid JSON: %v", err)
 		}
 		return nil
 	},
@@ -72,6 +72,6 @@ var BaseRoleUpdate = common.Shortcut{
 			return err
 		}
 
-		return handleRoleResponse(runtime, apiResp.RawBody, "update role failed")
+		return handleRoleAPIResponse(runtime, apiResp, "update role failed")
 	},
 }

shortcuts/base/base_shortcut_helpers.go

@@ -30,34 +30,34 @@ func baseTableID(runtime *common.RuntimeContext) string {
 func loadJSONInput(pc *parseCtx, raw string, flagName string) (string, error) {
 	raw = strings.TrimSpace(raw)
 	if raw == "" {
-		return "", common.FlagErrorf("--%s cannot be empty", flagName)
+		return "", baseFlagErrorf("--%s cannot be empty", flagName)
 	}
 	if !strings.HasPrefix(raw, "@") {
 		return raw, nil
 	}
 	path := strings.TrimSpace(strings.TrimPrefix(raw, "@"))
 	if path == "" {
-		return "", common.FlagErrorf("--%s file path cannot be empty after @", flagName)
+		return "", baseFlagErrorf("--%s file path cannot be empty after @", flagName)
 	}
 	if pc.fio == nil {
-		return "", common.FlagErrorf("--%s @file inputs require a FileIO provider", flagName)
+		return "", baseMissingFileIOError("--%s @file inputs require a FileIO provider", flagName)
 	}
 	f, err := pc.fio.Open(path)
 	if err != nil {
 		var pathErr *fileio.PathValidationError
 		if errors.As(err, &pathErr) {
-			return "", common.FlagErrorf("--%s invalid JSON file path %q: %v", flagName, path, pathErr.Err)
+			return "", baseFlagErrorf("--%s invalid JSON file path %q: %v", flagName, path, pathErr.Err)
 		}
-		return "", common.FlagErrorf("--%s cannot open JSON file %q: %v", flagName, path, err)
+		return "", baseFlagErrorf("--%s cannot open JSON file %q: %v", flagName, path, err)
 	}
 	defer f.Close()
 	data, err := io.ReadAll(f)
 	if err != nil {
-		return "", common.FlagErrorf("--%s cannot read JSON file %q: %v", flagName, path, err)
+		return "", baseFlagErrorf("--%s cannot read JSON file %q: %v", flagName, path, err)
 	}
 	content := strings.TrimSpace(string(data))
 	if content == "" {
-		return "", common.FlagErrorf("--%s JSON file %q is empty", flagName, path)
+		return "", baseFlagErrorf("--%s JSON file %q is empty", flagName, path)
 	}
 	return content, nil
 }
@@ -68,15 +68,15 @@ func jsonInputTip(flagName string) string {
 
 func formatJSONError(flagName string, target string, err error) error {
 	if syntaxErr, ok := err.(*json.SyntaxError); ok {
-		return common.FlagErrorf("--%s invalid JSON %s near byte %d (%v); %s", flagName, target, syntaxErr.Offset, err, jsonInputTip(flagName))
+		return baseFlagErrorf("--%s invalid JSON %s near byte %d (%v); %s", flagName, target, syntaxErr.Offset, err, jsonInputTip(flagName))
 	}
 	if typeErr, ok := err.(*json.UnmarshalTypeError); ok {
 		if typeErr.Field != "" {
-			return common.FlagErrorf("--%s invalid JSON %s at field %q (%v); %s", flagName, target, typeErr.Field, err, jsonInputTip(flagName))
+			return baseFlagErrorf("--%s invalid JSON %s at field %q (%v); %s", flagName, target, typeErr.Field, err, jsonInputTip(flagName))
 		}
-		return common.FlagErrorf("--%s invalid JSON %s (%v); %s", flagName, target, err, jsonInputTip(flagName))
+		return baseFlagErrorf("--%s invalid JSON %s (%v); %s", flagName, target, err, jsonInputTip(flagName))
 	}
-	return common.FlagErrorf("--%s invalid JSON %s (%v); %s", flagName, target, err, jsonInputTip(flagName))
+	return baseFlagErrorf("--%s invalid JSON %s (%v); %s", flagName, target, err, jsonInputTip(flagName))
 }
 
 func baseAction(runtime *common.RuntimeContext, boolFlags []string, stringFlags []string) (string, error) {
@@ -92,14 +92,14 @@ func baseAction(runtime *common.RuntimeContext, boolFlags []string, stringFlags
 		}
 	}
 	if len(active) == 0 {
-		return "", common.FlagErrorf("specify one action")
+		return "", baseFlagErrorf("specify one action")
 	}
 	if len(active) > 1 {
 		flags := make([]string, 0, len(active))
 		for _, item := range active {
 			flags = append(flags, "--"+item)
 		}
-		return "", common.FlagErrorf("actions are mutually exclusive: %s", strings.Join(flags, ", "))
+		return "", baseFlagErrorf("actions are mutually exclusive: %s", strings.Join(flags, ", "))
 	}
 	return active[0], nil
 }
@@ -123,7 +123,7 @@ func parseObjectList(pc *parseCtx, raw string, flagName string) ([]map[string]in
 		for idx, item := range arr {
 			obj, ok := item.(map[string]interface{})
 			if !ok {
-				return nil, common.FlagErrorf("--%s item %d must be an object", flagName, idx+1)
+				return nil, baseFlagErrorf("--%s item %d must be an object", flagName, idx+1)
 			}
 			items = append(items, obj)
 		}
@@ -150,6 +150,6 @@ func parseJSONValue(pc *parseCtx, raw string, flagName string) (interface{}, err
 	case map[string]interface{}, []interface{}:
 		return value, nil
 	default:
-		return nil, common.FlagErrorf("--%s must be a JSON object or array", flagName)
+		return nil, baseFlagErrorf("--%s must be a JSON object or array", flagName)
 	}
 }

shortcuts/base/dashboard_block_create.go

@@ -6,9 +6,9 @@ package base
 import (
 	"context"
 	"encoding/json"
-	"fmt"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -47,7 +47,7 @@ var BaseDashboardBlockCreate = common.Shortcut{
 		if strings.TrimSpace(raw) == "" {
 			// text 类型必须提供 data-config（含 text 内容）
 			if strings.ToLower(runtime.Str("type")) == "text" {
-				return fmt.Errorf("text 类型组件必须提供 data-config，包含必填字段 text")
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "text 类型组件必须提供 data-config，包含必填字段 text").WithParam("--data-config")
 			}
 			return nil
 		}

shortcuts/base/field_ops.go

@@ -91,7 +91,7 @@ func validateFormulaLookupGuideAck(runtime *common.RuntimeContext, command strin
 		if fieldType == "lookup" {
 			guidePath = "skills/lark-base/references/lookup-field-guide.md"
 		}
-		return common.FlagErrorf("--i-have-read-guide is required for %s when --json.type is %q; read %s first, then retry with --i-have-read-guide", command, fieldType, guidePath)
+		return baseFlagErrorf("--i-have-read-guide is required for %s when --json.type is %q; read %s first, then retry with --i-have-read-guide", command, fieldType, guidePath)
 	}
 	return nil
 }

shortcuts/base/helpers.go

@@ -17,6 +17,7 @@ import (
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -41,10 +42,10 @@ func parseJSONObject(pc *parseCtx, raw string, flagName string) (map[string]inte
 		if errors.As(err, &syntaxErr) {
 			return nil, formatJSONError(flagName, "object", err)
 		}
-		return nil, common.FlagErrorf("--%s must be a JSON object; %s", flagName, jsonInputTip(flagName))
+		return nil, baseFlagErrorf("--%s must be a JSON object; %s", flagName, jsonInputTip(flagName))
 	}
 	if result == nil {
-		return nil, common.FlagErrorf("--%s must be a JSON object; %s", flagName, jsonInputTip(flagName))
+		return nil, baseFlagErrorf("--%s must be a JSON object; %s", flagName, jsonInputTip(flagName))
 	}
 	return result, nil
 }
@@ -152,7 +153,7 @@ func cloneValue(value interface{}) interface{} {
 func resolveFieldTypeSpec(typeName string) (fieldTypeSpec, error) {
 	trimmed := strings.TrimSpace(typeName)
 	if trimmed == "" {
-		return fieldTypeSpec{}, fmt.Errorf("field type cannot be empty")
+		return fieldTypeSpec{}, baseValidationErrorf("field type cannot be empty")
 	}
 	switch strings.ToLower(trimmed) {
 	case "text", "phone", "url", "email", "barcode":
@@ -192,7 +193,7 @@ func resolveFieldTypeSpec(typeName string) (fieldTypeSpec, error) {
 	case "modifiedtime", "modified_time", "modified-time":
 		return fieldTypeSpec{Type: "updated_at", Extra: map[string]interface{}{"style": map[string]interface{}{"format": "yyyy/MM/dd"}}}, nil
 	default:
-		return fieldTypeSpec{}, fmt.Errorf("unsupported field type %q in base/v3", typeName)
+		return fieldTypeSpec{}, baseValidationErrorf("unsupported field type %q in base/v3", typeName)
 	}
 }
 
@@ -252,10 +253,10 @@ func normalizeSelectOptions(raw interface{}) []interface{} {
 
 func buildFieldBody(fieldName string, typeName string, property map[string]interface{}, uiType string, description string, isPrimary bool, isHidden bool) (map[string]interface{}, error) {
 	if isPrimary {
-		return nil, fmt.Errorf("base/v3 does not support setting primary field in field body")
+		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "base/v3 does not support setting primary field in field body")
 	}
 	if isHidden {
-		return nil, fmt.Errorf("base/v3 does not support hidden field creation in field body")
+		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "base/v3 does not support hidden field creation in field body")
 	}
 	spec, err := resolveFieldTypeSpec(typeName)
 	if err != nil {
@@ -354,7 +355,7 @@ func buildTableFieldBodies(rawFields string, rawFieldSpecs string) ([]interface{
 	if rawFields != "" {
 		var fields []interface{}
 		if err := common.ParseJSON([]byte(rawFields), &fields); err != nil {
-			return nil, fmt.Errorf("--fields invalid JSON, must be a field definition array")
+			return nil, baseValidationErrorf("--fields invalid JSON, must be a field definition array")
 		}
 		return fields, nil
 	}
@@ -366,7 +367,7 @@ func buildTableFieldBodies(rawFields string, rawFieldSpecs string) ([]interface{
 	for _, spec := range specs {
 		body, err := buildFieldBody(spec.Name, normalizeFieldTypeName(spec.Type), nil, "", "", false, false)
 		if err != nil {
-			return nil, fmt.Errorf("field %q: %w", spec.Name, err)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "field %q: %s", spec.Name, err).WithCause(err)
 		}
 		fields = append(fields, body)
 	}
@@ -410,20 +411,15 @@ func baseV3Raw(runtime *common.RuntimeContext, method, path string, params map[s
 	h.Set("X-App-Id", runtime.Config.AppID)
 	resp, err := runtime.DoAPI(req, larkcore.WithHeaders(h))
 	if err != nil {
-		return nil, err
+		return nil, baseAPIBoundaryError(err, "API call failed")
+	}
+	if _, err := runtime.ClassifyAPIResponse(resp); err != nil {
+		if statusErr := baseHTTPStatusErrorFromInvalidResponse(resp, err); statusErr != nil {
+			return nil, statusErr
+		}
+		return nil, enrichBaseAPIErrorFromBody(err, resp.RawBody, runtime.APIClassifyContext())
 	}
 	result, parseErr := decodeBaseV3Response(resp.RawBody)
-	if parseErr == nil && baseV3ResultCode(result) != 0 {
-		attachBaseErrorLogID(result, baseResponseLogID(resp))
-		return result, nil
-	}
-	if resp.StatusCode >= http.StatusBadRequest {
-		body := strings.TrimSpace(string(resp.RawBody))
-		if body == "" {
-			return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
-		}
-		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, body)
-	}
 	if parseErr != nil {
 		return nil, parseErr
 	}
@@ -435,18 +431,14 @@ func decodeBaseV3Response(body []byte) (map[string]interface{}, error) {
 	dec := json.NewDecoder(bytes.NewReader(body))
 	dec.UseNumber()
 	if err := dec.Decode(&result); err != nil {
-		return nil, fmt.Errorf("response parse error: %w", err)
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "API returned an invalid JSON response: %v", err).WithCause(err)
+	}
+	if result == nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "API returned a non-object JSON response")
 	}
 	return result, nil
 }
 
-func baseV3ResultCode(result map[string]interface{}) int {
-	if result == nil {
-		return 0
-	}
-	return toInt(result["code"])
-}
-
 func attachBaseErrorLogID(result map[string]interface{}, logID string) {
 	if result == nil || strings.TrimSpace(logID) == "" {
 		return
@@ -480,6 +472,33 @@ func baseResponseLogID(resp *larkcore.ApiResp) string {
 	return strings.TrimSpace(resp.Header.Get("x-tt-logid"))
 }
 
+func baseHTTPStatusErrorFromInvalidResponse(resp *larkcore.ApiResp, classified error) error {
+	if resp == nil || resp.StatusCode < http.StatusBadRequest {
+		return nil
+	}
+	p, ok := errs.ProblemOf(classified)
+	if !ok || p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+		return nil
+	}
+	body := strings.TrimSpace(string(resp.RawBody))
+	if resp.StatusCode >= http.StatusInternalServerError {
+		err := errs.NewNetworkError(errs.SubtypeNetworkServer, "HTTP %d: %s", resp.StatusCode, body).WithCode(resp.StatusCode).WithRetryable()
+		if logID := baseResponseLogID(resp); logID != "" {
+			err = err.WithLogID(logID)
+		}
+		return err
+	}
+	subtype := errs.SubtypeUnknown
+	if resp.StatusCode == http.StatusNotFound {
+		subtype = errs.SubtypeNotFound
+	}
+	err := errs.NewAPIError(subtype, "HTTP %d: %s", resp.StatusCode, body).WithCode(resp.StatusCode)
+	if logID := baseResponseLogID(resp); logID != "" {
+		err = err.WithLogID(logID)
+	}
+	return err
+}
+
 func baseV3Call(runtime *common.RuntimeContext, method, path string, params map[string]interface{}, data interface{}) (map[string]interface{}, error) {
 	result, err := baseV3Raw(runtime, method, path, params, data)
 	return handleBaseAPIResult(result, err, "API call failed")
@@ -525,7 +544,7 @@ func toStringSlice(v interface{}) []string {
 
 func listAllTables(runtime *common.RuntimeContext, baseToken string, offset, limit int) ([]map[string]interface{}, int, error) {
 	if limit <= 0 {
-		return nil, 0, fmt.Errorf("limit must be greater than 0")
+		return nil, 0, errs.NewInternalError(errs.SubtypeSDKError, "limit must be greater than 0")
 	}
 	data, err := baseV3Call(runtime, "GET", baseV3Path("bases", baseToken, "tables"), map[string]interface{}{"offset": offset, "limit": limit}, nil)
 	if err != nil {
@@ -555,7 +574,7 @@ func listAllTables(runtime *common.RuntimeContext, baseToken string, offset, lim
 
 func listAllFields(runtime *common.RuntimeContext, baseToken, tableID string, offset, limit int) ([]map[string]interface{}, int, error) {
 	if limit <= 0 {
-		return nil, 0, fmt.Errorf("limit must be greater than 0")
+		return nil, 0, errs.NewInternalError(errs.SubtypeSDKError, "limit must be greater than 0")
 	}
 	data, err := baseV3Call(runtime, "GET", baseV3Path("bases", baseToken, "tables", tableID, "fields"), map[string]interface{}{"offset": offset, "limit": limit}, nil)
 	if err != nil {
@@ -577,7 +596,7 @@ func listAllFields(runtime *common.RuntimeContext, baseToken, tableID string, of
 
 func listAllViews(runtime *common.RuntimeContext, baseToken, tableID string, offset, limit int) ([]map[string]interface{}, int, error) {
 	if limit <= 0 {
-		return nil, 0, fmt.Errorf("limit must be greater than 0")
+		return nil, 0, errs.NewInternalError(errs.SubtypeSDKError, "limit must be greater than 0")
 	}
 	data, err := baseV3Call(runtime, "GET", baseV3Path("bases", baseToken, "tables", tableID, "views"), map[string]interface{}{"offset": offset, "limit": limit}, nil)
 	if err != nil {
@@ -603,7 +622,7 @@ func resolveFieldRef(fields []map[string]interface{}, ref string) (map[string]in
 			return field, nil
 		}
 	}
-	return nil, fmt.Errorf("field %q not found", ref)
+	return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "field %q not found", ref)
 }
 
 func resolveTableRef(tables []map[string]interface{}, ref string) (map[string]interface{}, error) {
@@ -612,7 +631,7 @@ func resolveTableRef(tables []map[string]interface{}, ref string) (map[string]in
 			return table, nil
 		}
 	}
-	return nil, fmt.Errorf("table %q not found", ref)
+	return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "table %q not found", ref)
 }
 
 func resolveViewRef(views []map[string]interface{}, ref string) (map[string]interface{}, error) {
@@ -621,7 +640,7 @@ func resolveViewRef(views []map[string]interface{}, ref string) (map[string]inte
 			return view, nil
 		}
 	}
-	return nil, fmt.Errorf("view %q not found", ref)
+	return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "view %q not found", ref)
 }
 
 func chunkRecords(records []map[string]interface{}, size int) [][]map[string]interface{} {
@@ -738,18 +757,18 @@ func canonicalValue(v interface{}) string {
 func parseNamedTypeSpecs(raw string, flagName string) ([]namedTypeSpec, error) {
 	var tuples []interface{}
 	if err := common.ParseJSON([]byte(raw), &tuples); err != nil {
-		return nil, fmt.Errorf("--%s invalid JSON array", flagName)
+		return nil, baseValidationErrorf("--%s invalid JSON array", flagName)
 	}
 	result := make([]namedTypeSpec, 0, len(tuples))
 	for idx, item := range tuples {
 		pair, ok := item.([]interface{})
 		if !ok || len(pair) != 2 {
-			return nil, fmt.Errorf("--%s item %d must be [name, type]", flagName, idx+1)
+			return nil, baseValidationErrorf("--%s item %d must be [name, type]", flagName, idx+1)
 		}
 		name, ok1 := pair[0].(string)
 		typeName, ok2 := pair[1].(string)
 		if !ok1 || !ok2 {
-			return nil, fmt.Errorf("--%s item %d must be [string, string]", flagName, idx+1)
+			return nil, baseValidationErrorf("--%s item %d must be [string, string]", flagName, idx+1)
 		}
 		result = append(result, namedTypeSpec{Name: name, Type: typeName})
 	}
@@ -1155,9 +1174,9 @@ func validateBlockDataConfig(blockType string, cfg map[string]interface{}) []str
 	return errs
 }
 
-func formatDataConfigErrors(errs []string) error {
-	if len(errs) == 0 {
+func formatDataConfigErrors(problems []string) error {
+	if len(problems) == 0 {
 		return nil
 	}
-	return fmt.Errorf("data_config 校验失败:\n- %s\n参考: skills/lark-base/references/dashboard-block-data-config.md", strings.Join(errs, "\n- "))
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "data_config 校验失败:\n- %s\n参考: skills/lark-base/references/dashboard-block-data-config.md", strings.Join(problems, "\n- "))
 }

shortcuts/base/record_markdown.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -19,7 +20,7 @@ func validateRecordReadFormat(runtime *common.RuntimeContext) error {
 	case "", "json", "markdown":
 		return nil
 	default:
-		return output.ErrValidation("--format must be json or markdown")
+		return baseValidationErrorf("--format must be json or markdown")
 	}
 }
 
@@ -33,7 +34,7 @@ func outputRecordMarkdownWithRenderer(runtime *common.RuntimeContext, data map[s
 			runtime.Out(data, nil)
 			return nil
 		}
-		return output.ErrValidation("--jq and --format markdown are mutually exclusive")
+		return baseValidationErrorf("--jq and --format markdown are mutually exclusive")
 	}
 	rendered, err := renderer(data)
 	if err != nil {
@@ -43,7 +44,7 @@ func outputRecordMarkdownWithRenderer(runtime *common.RuntimeContext, data map[s
 	}
 	scanResult := output.ScanForSafety(runtime.Cmd.CommandPath(), data, runtime.IO().ErrOut)
 	if scanResult.Blocked {
-		return scanResult.BlockErr
+		return baseContentSafetyBlockError(scanResult)
 	}
 	if scanResult.Alert != nil {
 		output.WriteAlertWarning(runtime.IO().ErrOut, scanResult.Alert)
@@ -52,6 +53,20 @@ func outputRecordMarkdownWithRenderer(runtime *common.RuntimeContext, data map[s
 	return nil
 }
 
+func baseContentSafetyBlockError(scanResult output.ScanResult) error {
+	message := "content safety violation detected"
+	var rules []string
+	if scanResult.Alert != nil {
+		rules = scanResult.Alert.MatchedRules
+	}
+	if len(rules) > 0 {
+		message = fmt.Sprintf("content safety violation detected (rules: %s)", strings.Join(rules, ", "))
+	}
+	return errs.NewContentSafetyError(errs.SubtypeUnknown, "%s", message).
+		WithRules(rules...).
+		WithCause(scanResult.BlockErr)
+}
+
 func outputRecordGetMarkdown(runtime *common.RuntimeContext, data map[string]interface{}) error {
 	return outputRecordMarkdownWithRenderer(runtime, data, renderRecordGetMarkdown)
 }
@@ -61,7 +76,7 @@ func renderRecordGetMarkdown(data map[string]interface{}) (string, error) {
 	recordIDs := stringSliceValue(data["record_id_list"])
 	rows, ok := data["data"].([]interface{})
 	if len(fields) == 0 || !ok {
-		return "", output.ErrValidation("--format markdown requires record matrix response with fields, record_id_list, and data")
+		return "", baseValidationErrorf("--format markdown requires record matrix response with fields, record_id_list, and data")
 	}
 	if len(recordIDs) == 1 && len(rows) == 1 {
 		rowItems, _ := rows[0].([]interface{})
@@ -78,7 +93,7 @@ func renderRecordMarkdown(data map[string]interface{}) (string, error) {
 	recordIDs := stringSliceValue(data["record_id_list"])
 	rows, ok := data["data"].([]interface{})
 	if len(fields) == 0 || !ok {
-		return "", output.ErrValidation("--format markdown requires record matrix response with fields, record_id_list, and data")
+		return "", baseValidationErrorf("--format markdown requires record matrix response with fields, record_id_list, and data")
 	}
 
 	var b strings.Builder

shortcuts/base/record_markdown_test.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	extcs "github.com/larksuite/cli/extension/contentsafety"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -212,9 +213,12 @@ func TestOutputRecordMarkdownContentSafetyBlockDoesNotWriteStdout(t *testing.T)
 		"record_id_list": []interface{}{"rec_1"},
 		"data":           []interface{}{[]interface{}{"Alice"}},
 	})
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Code != output.ExitContentSafety {
-		t.Fatalf("err=%v, want content safety exit error", err)
+	var csErr *errs.ContentSafetyError
+	if !errors.As(err, &csErr) {
+		t.Fatalf("err=%v, want typed content safety error", err)
+	}
+	if len(csErr.Rules) != 1 || csErr.Rules[0] != "r1" {
+		t.Fatalf("rules=%v", csErr.Rules)
 	}
 	if stdout.Len() > 0 {
 		t.Fatalf("block mode should not write stdout, got:\n%s", stdout.String())

shortcuts/base/record_ops.go

@@ -49,7 +49,7 @@ func resolveRecordSelection(runtime *common.RuntimeContext) (recordSelection, er
 	fieldIDs := runtime.StrArray("field-id")
 	jsonRaw := strings.TrimSpace(runtime.Str("json"))
 	if len(recordIDs) > 0 && jsonRaw != "" {
-		return recordSelection{}, common.FlagErrorf("--record-id and --json are mutually exclusive")
+		return recordSelection{}, baseFlagErrorf("--record-id and --json are mutually exclusive")
 	}
 	if jsonRaw != "" {
 		pc := newParseCtx(runtime)
@@ -59,11 +59,11 @@ func resolveRecordSelection(runtime *common.RuntimeContext) (recordSelection, er
 		}
 		recordIDListValue, ok := body["record_id_list"]
 		if !ok {
-			return recordSelection{}, common.FlagErrorf(`--json must include "record_id_list" as a non-empty string array; %s`, jsonInputTip("json"))
+			return recordSelection{}, baseFlagErrorf(`--json must include "record_id_list" as a non-empty string array; %s`, jsonInputTip("json"))
 		}
 		recordIDItems, ok := recordIDListValue.([]interface{})
 		if !ok {
-			return recordSelection{}, common.FlagErrorf(`--json field "record_id_list" must be a string array; %s`, jsonInputTip("json"))
+			return recordSelection{}, baseFlagErrorf(`--json field "record_id_list" must be a string array; %s`, jsonInputTip("json"))
 		}
 		normalized, err := normalizeRecordIDs(recordIDItems)
 		if err != nil {
@@ -117,14 +117,14 @@ func resolveRecordGetSelectFields(flagFields []string, body map[string]interface
 		return fromFlags, nil
 	}
 	if len(fromFlags) > 0 {
-		return nil, common.FlagErrorf(`--field-id and --json field "select_fields" are mutually exclusive`)
+		return nil, baseFlagErrorf(`--field-id and --json field "select_fields" are mutually exclusive`)
 	}
 	items, ok := rawJSONFields.([]interface{})
 	if !ok {
-		return nil, common.FlagErrorf(`--json field "select_fields" must be a string array; %s`, jsonInputTip("json"))
+		return nil, baseFlagErrorf(`--json field "select_fields" must be a string array; %s`, jsonInputTip("json"))
 	}
 	if len(items) == 0 {
-		return nil, common.FlagErrorf(`--json field "select_fields" must not be empty; %s`, jsonInputTip("json"))
+		return nil, baseFlagErrorf(`--json field "select_fields" must not be empty; %s`, jsonInputTip("json"))
 	}
 	normalized, err := normalizeRecordGetSelectFields(items)
 	if err != nil {
@@ -152,7 +152,7 @@ func normalizeStringList(values interface{}, opts stringListNormalizeOptions) ([
 		if opts.allowNil {
 			return nil, nil
 		}
-		return nil, common.FlagErrorf(opts.typeError)
+		return nil, baseFlagErrorf(opts.typeError)
 	case []interface{}:
 		rawItems = typed
 	case []string:
@@ -161,30 +161,30 @@ func normalizeStringList(values interface{}, opts stringListNormalizeOptions) ([
 			rawItems = append(rawItems, item)
 		}
 	default:
-		return nil, common.FlagErrorf(opts.typeError)
+		return nil, baseFlagErrorf(opts.typeError)
 	}
 	if len(rawItems) == 0 {
 		if opts.allowEmpty {
 			return nil, nil
 		}
-		return nil, common.FlagErrorf(opts.emptyError)
+		return nil, baseFlagErrorf(opts.emptyError)
 	}
 	if opts.max > 0 && len(rawItems) > opts.max {
-		return nil, common.FlagErrorf("%s exceeds maximum limit of %d (got %d)", opts.limitName, opts.max, len(rawItems))
+		return nil, baseFlagErrorf("%s exceeds maximum limit of %d (got %d)", opts.limitName, opts.max, len(rawItems))
 	}
 	seen := make(map[string]int, len(rawItems))
 	result := make([]string, 0, len(rawItems))
 	for index, value := range rawItems {
 		item, ok := value.(string)
 		if !ok {
-			return nil, common.FlagErrorf("%s %d must be a string", opts.itemName, index+1)
+			return nil, baseFlagErrorf("%s %d must be a string", opts.itemName, index+1)
 		}
 		item = strings.TrimSpace(item)
 		if item == "" {
-			return nil, common.FlagErrorf("%s %d must not be empty", opts.itemName, index+1)
+			return nil, baseFlagErrorf("%s %d must not be empty", opts.itemName, index+1)
 		}
 		if first, exists := seen[item]; exists {
-			return nil, common.FlagErrorf("duplicate %s %q at positions %d and %d", opts.duplicateName, item, first, index+1)
+			return nil, baseFlagErrorf("duplicate %s %q at positions %d and %d", opts.duplicateName, item, first, index+1)
 		}
 		seen[item] = index + 1
 		result = append(result, item)
@@ -332,10 +332,10 @@ const maxShareBatchSize = 100
 func validateRecordShareBatch(runtime *common.RuntimeContext) error {
 	recordIDs := deduplicateRecordIDs(runtime)
 	if len(recordIDs) == 0 {
-		return common.FlagErrorf("--record-ids is required and must not be empty")
+		return baseFlagErrorf("--record-ids is required and must not be empty")
 	}
 	if len(recordIDs) > maxShareBatchSize {
-		return common.FlagErrorf("--record-ids exceeds maximum limit of %d (got %d)", maxShareBatchSize, len(recordIDs))
+		return baseFlagErrorf("--record-ids exceeds maximum limit of %d (got %d)", maxShareBatchSize, len(recordIDs))
 	}
 	return nil
 }

shortcuts/base/record_query.go

@@ -71,18 +71,18 @@ func normalizeRecordSortValue(value interface{}, label string) ([]interface{}, e
 	} else if obj, ok := value.(map[string]interface{}); ok {
 		rawSortConfig, ok := obj["sort_config"]
 		if !ok {
-			return nil, common.FlagErrorf("%s must be a JSON array or an object with sort_config array", label)
+			return nil, baseFlagErrorf("%s must be a JSON array or an object with sort_config array", label)
 		}
 		parsed, ok := rawSortConfig.([]interface{})
 		if !ok {
-			return nil, common.FlagErrorf("%s.sort_config must be a JSON array", label)
+			return nil, baseFlagErrorf("%s.sort_config must be a JSON array", label)
 		}
 		sortConfig = parsed
 	} else {
-		return nil, common.FlagErrorf("%s must be a JSON array or an object with sort_config array", label)
+		return nil, baseFlagErrorf("%s must be a JSON array or an object with sort_config array", label)
 	}
 	if len(sortConfig) > recordSortMaxCount {
-		return nil, common.FlagErrorf("sort supports at most %d sort conditions; got %d", recordSortMaxCount, len(sortConfig))
+		return nil, baseFlagErrorf("sort supports at most %d sort conditions; got %d", recordSortMaxCount, len(sortConfig))
 	}
 	return sortConfig, nil
 }
@@ -90,7 +90,7 @@ func normalizeRecordSortValue(value interface{}, label string) ([]interface{}, e
 func marshalRecordQueryFlag(flagName string, value interface{}) (string, error) {
 	data, err := json.Marshal(value)
 	if err != nil {
-		return "", common.FlagErrorf("--%s cannot encode JSON: %v", flagName, err)
+		return "", baseFlagErrorf("--%s cannot encode JSON: %v", flagName, err)
 	}
 	return string(data), nil
 }
@@ -220,16 +220,16 @@ func validateRecordSearchFlags(runtime *common.RuntimeContext) error {
 	jsonRaw := strings.TrimSpace(runtime.Str("json"))
 	if jsonRaw != "" {
 		if recordSearchHasJSONExclusiveFlagInputs(runtime) {
-			return common.FlagErrorf("--json is mutually exclusive with keyword/search/projection/pagination flags; put those fields inside --json, or omit --json")
+			return baseFlagErrorf("--json is mutually exclusive with keyword/search/projection/pagination flags; put those fields inside --json, or omit --json")
 		}
 		_, err := recordSearchJSONBody(runtime)
 		return err
 	}
 	if strings.TrimSpace(runtime.Str("keyword")) == "" {
-		return common.FlagErrorf("--keyword is required unless --json is used")
+		return baseFlagErrorf("--keyword is required unless --json is used")
 	}
 	if len(runtime.StrArray("search-field")) == 0 {
-		return common.FlagErrorf("--search-field is required unless --json is used")
+		return baseFlagErrorf("--search-field is required unless --json is used")
 	}
 	return validateRecordQueryOptions(runtime)
 }

shortcuts/base/record_upload_attachment.go

@@ -22,7 +22,6 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/util"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -225,7 +224,7 @@ func dryRunRecordRemoveAttachment(_ context.Context, runtime *common.RuntimeCont
 
 func validateRecordUploadAttachment(runtime *common.RuntimeContext) error {
 	if runtime.Changed("name") {
-		return common.FlagErrorf("--name is no longer supported; uploaded attachment names are derived from local file basenames")
+		return baseFlagErrorf("--name is no longer supported; uploaded attachment names are derived from local file basenames")
 	}
 	files, err := normalizeAttachmentFiles(runtime.StrArray("file"))
 	if err != nil {
@@ -245,9 +244,16 @@ func validateRecordDownloadAttachment(runtime *common.RuntimeContext) error {
 		return err
 	}
 	if len(tokens) != 1 {
+		const outputDirRequired = "--output must be an existing directory when downloading multiple attachments or when --file-token is omitted"
 		info, statErr := runtime.FileIO().Stat(runtime.Str("output"))
-		if statErr != nil || !info.IsDir() {
-			return common.FlagErrorf("--output must be an existing directory when downloading multiple attachments or when --file-token is omitted")
+		if statErr != nil {
+			if errors.Is(statErr, fileio.ErrPathValidation) {
+				return baseValidationErrorf("unsafe output path: %s", statErr)
+			}
+			return baseFlagErrorf(outputDirRequired)
+		}
+		if !info.IsDir() {
+			return baseFlagErrorf(outputDirRequired)
 		}
 	}
 	return nil
@@ -269,7 +275,7 @@ func executeRecordUploadAttachment(runtime *common.RuntimeContext) error {
 		return err
 	}
 	if normalized := normalizeFieldTypeName(fieldTypeName(field)); normalized != "attachment" {
-		return output.ErrValidation("field %q is type %q, expected attachment", fieldName(field), normalized)
+		return baseValidationErrorf("field %q is type %q, expected attachment", fieldName(field), normalized)
 	}
 	resolvedFieldID := fieldID(field)
 	if resolvedFieldID == "" {
@@ -316,7 +322,7 @@ func executeRecordRemoveAttachment(runtime *common.RuntimeContext) error {
 		return err
 	}
 	if normalized := normalizeFieldTypeName(fieldTypeName(field)); normalized != "attachment" {
-		return output.ErrValidation("field %q is type %q, expected attachment", fieldName(field), normalized)
+		return baseValidationErrorf("field %q is type %q, expected attachment", fieldName(field), normalized)
 	}
 	resolvedFieldID := fieldID(field)
 	if resolvedFieldID == "" {
@@ -353,7 +359,7 @@ func executeRecordDownloadAttachment(ctx context.Context, runtime *common.Runtim
 		saved, err := downloadBaseAttachment(ctx, runtime, target.Item, target.TargetPath, runtime.Bool("overwrite"))
 		if err != nil {
 			failed := attachmentDownloadFailure(target, err)
-			return attachmentDownloadProgressError(err, downloaded, []map[string]interface{}{failed})
+			return attachmentDownloadProgressError(runtime, err, downloaded, []map[string]interface{}{failed})
 		}
 		downloaded = append(downloaded, saved)
 	}
@@ -364,20 +370,20 @@ func executeRecordDownloadAttachment(ctx context.Context, runtime *common.Runtim
 func validateAttachmentInputFile(runtime *common.RuntimeContext, filePath string) (fileio.FileInfo, error) {
 	fio := runtime.FileIO()
 	if fio == nil {
-		return nil, output.ErrValidation("file operations require a FileIO provider")
+		return nil, baseValidationErrorf("file operations require a FileIO provider")
 	}
 	fileInfo, err := fio.Stat(filePath)
 	if err != nil {
 		if errors.Is(err, fileio.ErrPathValidation) {
-			return nil, output.ErrValidation("unsafe file path: %s", err)
+			return nil, baseValidationErrorf("unsafe file path: %s", err)
 		}
-		return nil, output.ErrValidation("file not accessible: %s: %v", filePath, err)
+		return nil, baseValidationErrorf("file not accessible: %s: %v", filePath, err)
 	}
 	if fileInfo.IsDir() {
-		return nil, output.ErrValidation("file path is a directory: %s", filePath)
+		return nil, baseValidationErrorf("file path is a directory: %s", filePath)
 	}
 	if fileInfo.Size() > baseAttachmentUploadMaxFileSize {
-		return nil, output.ErrValidation("file %s exceeds 2GB limit", common.FormatSize(fileInfo.Size()))
+		return nil, baseValidationErrorf("file %s exceeds 2GB limit (size: %s)", filePath, common.FormatSize(fileInfo.Size()))
 	}
 	return fileInfo, nil
 }
@@ -412,13 +418,13 @@ func normalizeOptionalDownloadAttachmentFileTokens(tokens []string) ([]string, e
 	for index, token := range tokens {
 		token = strings.TrimSpace(token)
 		if token == "" {
-			return nil, common.FlagErrorf("attachment file token %d must not be empty", index+1)
+			return nil, baseFlagErrorf("attachment file token %d must not be empty", index+1)
 		}
 		normalized = append(normalized, token)
 	}
 	normalized = dedupeStringsPreserveOrder(normalized)
 	if len(normalized) > baseAttachmentMaxBatchSize {
-		return nil, common.FlagErrorf("attachment file token count exceeds maximum limit of %d (got %d)", baseAttachmentMaxBatchSize, len(normalized))
+		return nil, baseFlagErrorf("attachment file token count exceeds maximum limit of %d (got %d)", baseAttachmentMaxBatchSize, len(normalized))
 	}
 	return normalized, nil
 }
@@ -453,10 +459,10 @@ func fetchBaseField(runtime *common.RuntimeContext, baseToken, tableIDValue, fie
 
 func fetchBaseAttachments(runtime *common.RuntimeContext, baseToken, tableIDValue string, recordIDs []string) (map[string]interface{}, error) {
 	if len(recordIDs) == 0 {
-		return nil, output.ErrValidation("provide at least one record id")
+		return nil, baseValidationErrorf("provide at least one record id")
 	}
 	if len(recordIDs) > baseAttachmentGetMaxRecords {
-		return nil, output.ErrValidation("get attachments record selection exceeds maximum limit of %d (got %d)", baseAttachmentGetMaxRecords, len(recordIDs))
+		return nil, baseValidationErrorf("get attachments record selection exceeds maximum limit of %d (got %d)", baseAttachmentGetMaxRecords, len(recordIDs))
 	}
 	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", baseToken, "tables", tableIDValue, "get_attachments"), nil, map[string]interface{}{
 		"record_id_list": recordIDs,
@@ -560,14 +566,14 @@ func detectAttachmentMIMEType(fio fileio.FileIO, filePath, fileName string) (str
 
 	f, err := fio.Open(filePath)
 	if err != nil {
-		return "", common.WrapInputStatError(err)
+		return "", baseInputStatError(err)
 	}
 	defer f.Close()
 
 	buf := make([]byte, 512)
 	n, readErr := f.Read(buf)
 	if readErr != nil && !errors.Is(readErr, io.EOF) {
-		return "", output.ErrValidation("cannot read file: %s", readErr)
+		return "", baseValidationErrorf("cannot read file: %s", readErr)
 	}
 	return detectAttachmentMIMEFromContent(buf[:n]), nil
 }
@@ -617,11 +623,11 @@ type baseAttachmentDownloadTarget struct {
 func selectAttachmentDownloadItems(attachments map[string]interface{}, recordID string, tokens []string) ([]baseAttachmentDownloadItem, error) {
 	recordRaw, ok := attachments[recordID]
 	if !ok {
-		return nil, output.ErrValidation("record %q has no attachment metadata; verify the record-id", recordID)
+		return nil, baseValidationErrorf("record %q has no attachment metadata; verify the record-id", recordID)
 	}
 	fields, ok := recordRaw.(map[string]interface{})
 	if !ok {
-		return nil, output.ErrValidation("record %q attachment metadata has unexpected type %T", recordID, recordRaw)
+		return nil, baseValidationErrorf("record %q attachment metadata has unexpected type %T", recordID, recordRaw)
 	}
 	byToken := map[string]baseAttachmentDownloadItem{}
 	fieldIDs := make([]string, 0, len(fields))
@@ -633,12 +639,12 @@ func selectAttachmentDownloadItems(attachments map[string]interface{}, recordID
 		rawList := fields[currentFieldID]
 		items, ok := rawList.([]interface{})
 		if !ok {
-			return nil, output.ErrValidation("record %q field %q attachment metadata has unexpected type %T", recordID, currentFieldID, rawList)
+			return nil, baseValidationErrorf("record %q field %q attachment metadata has unexpected type %T", recordID, currentFieldID, rawList)
 		}
 		for _, rawItem := range items {
 			item, ok := rawItem.(map[string]interface{})
 			if !ok {
-				return nil, output.ErrValidation("record %q field %q contains unexpected attachment item type %T", recordID, currentFieldID, rawItem)
+				return nil, baseValidationErrorf("record %q field %q contains unexpected attachment item type %T", recordID, currentFieldID, rawItem)
 			}
 			fileToken, _ := item["file_token"].(string)
 			if fileToken == "" {
@@ -668,7 +674,7 @@ func selectAttachmentDownloadItems(attachments map[string]interface{}, recordID
 			result = append(result, item)
 		}
 		if len(result) == 0 {
-			return nil, output.ErrValidation("record %q has no attachments to download", recordID)
+			return nil, baseValidationErrorf("record %q has no attachments to download", recordID)
 		}
 		sort.SliceStable(result, func(i, j int) bool {
 			leftName := strings.ToLower(baseAttachmentDownloadName(result[i]))
@@ -683,7 +689,7 @@ func selectAttachmentDownloadItems(attachments map[string]interface{}, recordID
 	for _, token := range tokens {
 		item, ok := byToken[token]
 		if !ok {
-			return nil, output.ErrValidation("attachment file_token %q not found in record %q; verify the record-id/file-token pair", token, recordID)
+			return nil, baseValidationErrorf("attachment file_token %q not found in record %q; verify the record-id/file-token pair", token, recordID)
 		}
 		result = append(result, item)
 	}
@@ -702,15 +708,15 @@ func planAttachmentDownloadTargets(runtime *common.RuntimeContext, items []baseA
 		}
 		resolved, err := runtime.ResolveSavePath(targetPath)
 		if err != nil {
-			return nil, output.ErrValidation("unsafe output path: %s", err)
+			return nil, baseValidationErrorf("unsafe output path: %s", err)
 		}
 		if previous, exists := seen[resolved]; exists {
-			return nil, output.ErrValidation("multiple attachments resolve to the same output path %q (%s and %s); download them separately or choose a different directory", resolved, previous.FileToken, item.FileToken)
+			return nil, baseValidationErrorf("multiple attachments resolve to the same output path %q (%s and %s); download them separately or choose a different directory", resolved, previous.FileToken, item.FileToken)
 		}
 		seen[resolved] = item
 		if !overwrite {
 			if _, statErr := runtime.FileIO().Stat(targetPath); statErr == nil {
-				return nil, output.ErrValidation("output file already exists: %s (use --overwrite to replace)", targetPath)
+				return nil, baseValidationErrorf("output file already exists: %s (use --overwrite to replace)", targetPath)
 			}
 		}
 		targets = append(targets, baseAttachmentDownloadTarget{
@@ -776,7 +782,7 @@ func safeAttachmentFileTokenSuffix(fileToken string) string {
 
 func downloadBaseAttachment(ctx context.Context, runtime *common.RuntimeContext, item baseAttachmentDownloadItem, targetPath string, overwrite bool) (map[string]interface{}, error) {
 	if _, err := runtime.ResolveSavePath(targetPath); err != nil {
-		return nil, output.ErrValidation("unsafe output path: %s", err)
+		return nil, baseValidationErrorf("unsafe output path: %s", err)
 	}
 
 	query := larkcore.QueryParams{}
@@ -795,7 +801,7 @@ func downloadBaseAttachment(ctx context.Context, runtime *common.RuntimeContext,
 
 	if !overwrite {
 		if _, statErr := runtime.FileIO().Stat(targetPath); statErr == nil {
-			return nil, output.ErrValidation("output file already exists: %s (use --overwrite to replace)", targetPath)
+			return nil, baseValidationErrorf("output file already exists: %s (use --overwrite to replace)", targetPath)
 		}
 	}
 	result, err := runtime.FileIO().Save(targetPath, fileio.SaveOptions{
@@ -803,7 +809,7 @@ func downloadBaseAttachment(ctx context.Context, runtime *common.RuntimeContext,
 		ContentLength: resp.ContentLength,
 	}, resp.Body)
 	if err != nil {
-		return nil, common.WrapSaveErrorByCategory(err, "io")
+		return nil, baseSaveError(err)
 	}
 	savedPath, _ := runtime.ResolveSavePath(targetPath)
 	if savedPath == "" {
@@ -822,7 +828,7 @@ func downloadBaseAttachment(ctx context.Context, runtime *common.RuntimeContext,
 }
 
 func attachmentDownloadFailure(target baseAttachmentDownloadTarget, err error) map[string]interface{} {
-	return map[string]interface{}{
+	failure := map[string]interface{}{
 		"record_id":     target.Item.RecordID,
 		"field_id":      target.Item.FieldID,
 		"file_token":    target.Item.FileToken,
@@ -831,72 +837,45 @@ func attachmentDownloadFailure(target baseAttachmentDownloadTarget, err error) m
 		"resolved_path": target.ResolvedPath,
 		"error":         err.Error(),
 	}
+	if p, ok := errs.ProblemOf(err); ok {
+		failure["type"] = string(p.Category)
+		failure["subtype"] = string(p.Subtype)
+		if p.Code != 0 {
+			failure["code"] = p.Code
+		}
+		if p.LogID != "" {
+			failure["log_id"] = p.LogID
+		}
+	}
+	return failure
 }
 
-func attachmentDownloadProgressError(err error, downloaded []map[string]interface{}, failed []map[string]interface{}) error {
+func attachmentDownloadProgressError(runtime *common.RuntimeContext, err error, downloaded []map[string]interface{}, failed []map[string]interface{}) error {
 	msg := fmt.Sprintf("download failed after %d attachment(s) succeeded and %d failed: %v", len(downloaded), len(failed), err)
-	detail := map[string]interface{}{
+	payload := map[string]interface{}{
+		"message":    msg,
 		"downloaded": downloaded,
 		"failed":     failed,
 	}
+	const hint = "Some files may already have been saved. Inspect downloaded before retrying, or rerun with --overwrite if the failed target now exists."
+	payload["hint"] = hint
+	if p, ok := errs.ProblemOf(err); ok {
+		payload["type"] = string(p.Category)
+		payload["subtype"] = string(p.Subtype)
+		if p.Code != 0 {
+			payload["code"] = p.Code
+		}
+	}
 	if logID := baseAttachmentDownloadLogID(err); logID != "" {
-		detail["log_id"] = logID
-	}
-	const hint = "Some files may already have been saved. Inspect error.detail.downloaded before retrying, or rerun with --overwrite if the failed target now exists."
-
-	var exitErr *output.ExitError
-	if errors.As(err, &exitErr) && exitErr.Detail != nil {
-		return &output.ExitError{
-			Code: exitErr.Code,
-			Detail: &output.ErrDetail{
-				Type:    exitErr.Detail.Type,
-				Code:    exitErr.Detail.Code,
-				Message: msg,
-				Hint:    hint,
-				Detail:  detail,
-			},
-			Err: err,
-		}
-	}
-	var netErr *errs.NetworkError
-	if errors.As(err, &netErr) {
-		return &output.ExitError{
-			Code: output.ExitNetwork,
-			Detail: &output.ErrDetail{
-				Type:    "network",
-				Code:    netErr.Code,
-				Message: msg,
-				Hint:    hint,
-				Detail:  detail,
-			},
-			Err: err,
-		}
-	}
-	return &output.ExitError{
-		Code: output.ExitInternal,
-		Detail: &output.ErrDetail{
-			Type:    "io",
-			Message: msg,
-			Hint:    hint,
-			Detail:  detail,
-		},
-		Err: err,
+		payload["log_id"] = logID
 	}
+	return runtime.OutPartialFailure(payload, nil)
 }
 
 func baseAttachmentDownloadLogID(err error) string {
-	var netErr *errs.NetworkError
-	if errors.As(err, &netErr) {
-		if id := strings.TrimSpace(netErr.LogID); id != "" {
-			return id
-		}
-	}
-	var exitErr *output.ExitError
-	if errors.As(err, &exitErr) && exitErr.Detail != nil {
-		if detail, ok := exitErr.Detail.Detail.(map[string]interface{}); ok {
-			if logID, _ := detail["log_id"].(string); logID != "" {
-				return strings.TrimSpace(logID)
-			}
+	if p, ok := errs.ProblemOf(err); ok {
+		if logID := strings.TrimSpace(p.LogID); logID != "" {
+			return logID
 		}
 	}
 	return ""

shortcuts/base/table_ops.go

@@ -5,7 +5,6 @@ package base
 
 import (
 	"context"
-	"fmt"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -117,7 +116,7 @@ func executeTableCreate(runtime *common.RuntimeContext) error {
 		for idx, item := range fieldItems {
 			body, ok := item.(map[string]interface{})
 			if !ok {
-				return fmt.Errorf("--fields item %d must be an object", idx+1)
+				return baseValidationErrorf("--fields item %d must be an object", idx+1)
 			}
 			if idx == 0 && len(defaultFields) > 0 {
 				fieldData, err := baseV3Call(runtime, "PUT", baseV3Path("bases", baseToken, "tables", tableIDValue, "fields", fieldID(defaultFields[0])), nil, body)

shortcuts/base/workflow_create.go

@@ -31,7 +31,7 @@ var BaseWorkflowCreate = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		pc := newParseCtx(runtime)
 		raw, err := loadJSONInput(pc, runtime.Str("json"), "json")

shortcuts/base/workflow_disable.go

@@ -27,10 +27,10 @@ var BaseWorkflowDisable = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		if strings.TrimSpace(runtime.Str("workflow-id")) == "" {
-			return common.FlagErrorf("--workflow-id must not be blank")
+			return baseFlagErrorf("--workflow-id must not be blank")
 		}
 		return nil
 	},

shortcuts/base/workflow_enable.go

@@ -28,10 +28,10 @@ var BaseWorkflowEnable = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		if strings.TrimSpace(runtime.Str("workflow-id")) == "" {
-			return common.FlagErrorf("--workflow-id must not be blank")
+			return baseFlagErrorf("--workflow-id must not be blank")
 		}
 		return nil
 	},

shortcuts/base/workflow_get.go

@@ -30,10 +30,10 @@ var BaseWorkflowGet = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		if strings.TrimSpace(runtime.Str("workflow-id")) == "" {
-			return common.FlagErrorf("--workflow-id must not be blank")
+			return baseFlagErrorf("--workflow-id must not be blank")
 		}
 		return nil
 	},

shortcuts/base/workflow_list.go

@@ -28,7 +28,7 @@ var BaseWorkflowList = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		return nil
 	},

shortcuts/base/workflow_update.go

@@ -33,10 +33,10 @@ var BaseWorkflowUpdate = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
-			return common.FlagErrorf("--base-token must not be blank")
+			return baseFlagErrorf("--base-token must not be blank")
 		}
 		if strings.TrimSpace(runtime.Str("workflow-id")) == "" {
-			return common.FlagErrorf("--workflow-id must not be blank")
+			return baseFlagErrorf("--workflow-id must not be blank")
 		}
 		pc := newParseCtx(runtime)
 		if _, err := parseJSONObject(pc, runtime.Str("json"), "json"); err != nil {

shortcuts/calendar/calendar_agenda.go

@@ -12,8 +12,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/util"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -29,7 +29,7 @@ const (
 
 func fetchInstanceViewRange(ctx context.Context, runtime *common.RuntimeContext, calendarId string, startTime, endTime int64, depth int) ([]map[string]interface{}, error) {
 	if depth > 10 {
-		return nil, output.Errorf(output.ExitInternal, "recursion_limit", "too many splits for instance_view")
+		return nil, errs.NewInternalError(errs.SubtypeUnknown, "too many splits for instance_view")
 	}
 	if startTime > endTime {
 		return nil, nil
@@ -48,68 +48,67 @@ func fetchInstanceViewRange(ctx context.Context, runtime *common.RuntimeContext,
 		return append(left, right...), nil
 	}
 
-	result, err := runtime.RawAPI("GET",
+	data, err := runtime.CallAPITyped("GET",
 		fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/instance_view", validate.EncodePathSegment(calendarId)),
 		map[string]interface{}{
 			"start_time": fmt.Sprintf("%d", startTime),
 			"end_time":   fmt.Sprintf("%d", endTime),
 		}, nil)
-	err = wrapPredefinedError(err)
 	if err != nil {
-		return nil, output.Errorf(output.ExitAPI, "api_error", "API call failed: %s", err)
-	}
-
-	resultMap, _ := result.(map[string]interface{})
-	code, _ := util.ToFloat64(resultMap["code"])
-
-	if code == 0 {
-		data, _ := resultMap["data"].(map[string]interface{})
-		items, _ := data["items"].([]interface{})
-		var events []map[string]interface{}
-		for _, item := range items {
-			if m, ok := item.(map[string]interface{}); ok {
-				events = append(events, m)
+		// CallAPITyped returns a typed error for any non-zero API code. The two
+		// calendar instance_view limits (193103 time-range, 193104 too-many) are
+		// recoverable by narrowing the window, so inspect the typed code and
+		// recurse instead of treating them as fatal. Any other code falls through
+		// to return the typed error unchanged.
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			return nil, err
+		}
+		switch p.Code {
+		case larkErrCalendarTimeRangeExceeded:
+			mid := startTime + span/2
+			if mid <= startTime {
+				return nil, errs.NewAPIError(errs.SubtypeInvalidParameters,
+					"query failed: time range exceeds 40-day limit, please narrow the range").
+					WithCode(larkErrCalendarTimeRangeExceeded)
 			}
+			return fetchInstanceViewSplit(ctx, runtime, calendarId, startTime, mid, endTime, depth)
+		case larkErrCalendarTooManyInstances:
+			if span <= minSplitWindowSeconds {
+				return nil, errs.NewAPIError(errs.SubtypeInvalidParameters,
+					"query failed: more than 1000 instances in the time range, please narrow the range").
+					WithCode(larkErrCalendarTooManyInstances)
+			}
+			mid := startTime + span/2
+			return fetchInstanceViewSplit(ctx, runtime, calendarId, startTime, mid, endTime, depth)
+		default:
+			return nil, err
 		}
-		return events, nil
 	}
 
-	// Error 193103: time range exceeds limit -> split
-	if int(code) == larkErrCalendarTimeRangeExceeded {
-		mid := startTime + span/2
-		if mid <= startTime {
-			return nil, output.Errorf(output.ExitAPI, "api_error", "query failed: time range exceeds 40-day limit, please narrow the range")
+	items, _ := data["items"].([]interface{})
+	var events []map[string]interface{}
+	for _, item := range items {
+		if m, ok := item.(map[string]interface{}); ok {
+			events = append(events, m)
 		}
-		left, err := fetchInstanceViewRange(ctx, runtime, calendarId, startTime, mid, depth+1)
-		if err != nil {
-			return nil, err
-		}
-		right, err := fetchInstanceViewRange(ctx, runtime, calendarId, mid+1, endTime, depth+1)
-		if err != nil {
-			return nil, err
-		}
-		return append(left, right...), nil
 	}
+	return events, nil
+}
 
-	// Error 193104: too many instances -> split
-	if int(code) == larkErrCalendarTooManyInstances {
-		if span <= minSplitWindowSeconds {
-			return nil, output.Errorf(output.ExitAPI, "api_error", "query failed: more than 1000 instances in the time range, please narrow the range")
-		}
-		mid := startTime + span/2
-		left, err := fetchInstanceViewRange(ctx, runtime, calendarId, startTime, mid, depth+1)
-		if err != nil {
-			return nil, err
-		}
-		right, err := fetchInstanceViewRange(ctx, runtime, calendarId, mid+1, endTime, depth+1)
-		if err != nil {
-			return nil, err
-		}
-		return append(left, right...), nil
+// fetchInstanceViewSplit halves [startTime, endTime] at mid and concatenates the
+// results of the two recursive sub-range queries. Shared by the 193103/193104
+// split paths.
+func fetchInstanceViewSplit(ctx context.Context, runtime *common.RuntimeContext, calendarId string, startTime, mid, endTime int64, depth int) ([]map[string]interface{}, error) {
+	left, err := fetchInstanceViewRange(ctx, runtime, calendarId, startTime, mid, depth+1)
+	if err != nil {
+		return nil, err
 	}
-
-	msg, _ := resultMap["msg"].(string)
-	return nil, output.ErrAPI(int(code), msg, resultMap["error"])
+	right, err := fetchInstanceViewRange(ctx, runtime, calendarId, mid+1, endTime, depth+1)
+	if err != nil {
+		return nil, err
+	}
+	return append(left, right...), nil
 }
 
 func dedupeAndSortItems(items []map[string]interface{}) []map[string]interface{} {
@@ -147,20 +146,20 @@ func parseTimeRange(runtime *common.RuntimeContext) (int64, int64, error) {
 
 	startTime, err := common.ParseTime(startInput)
 	if err != nil {
-		return 0, 0, output.ErrValidation("--start: %v", err)
+		return 0, 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
 	}
 	endTime, err := common.ParseTime(endInput, "end")
 	if err != nil {
-		return 0, 0, output.ErrValidation("--end: %v", err)
+		return 0, 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
 	}
 
 	startInt, err := strconv.ParseInt(startTime, 10, 64)
 	if err != nil {
-		return 0, 0, output.ErrValidation("invalid start time: %v", err)
+		return 0, 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid start time: %v", err).WithParam("--start")
 	}
 	endInt, err := strconv.ParseInt(endTime, 10, 64)
 	if err != nil {
-		return 0, 0, output.ErrValidation("invalid end time: %v", err)
+		return 0, 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid end time: %v", err).WithParam("--end")
 	}
 
 	return startInt, endInt, nil

shortcuts/calendar/calendar_create.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -60,7 +61,7 @@ func parseAttendees(attendeesStr string, currentUserId string) ([]map[string]str
 		case strings.HasPrefix(id, "ou_"):
 			attendees = append(attendees, map[string]string{"type": "user", "user_id": id})
 		default:
-			return nil, fmt.Errorf("unsupported attendee id format: %s", id)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported attendee id format: %s", id)
 		}
 	}
 	return attendees, nil
@@ -89,8 +90,8 @@ var CalendarCreate = common.Shortcut{
 		}
 		for _, flag := range []string{"summary", "description", "rrule", "calendar-id"} {
 			if val := runtime.Str(flag); val != "" {
-				if err := common.RejectDangerousChars("--"+flag, val); err != nil {
-					return output.ErrValidation(err.Error())
+				if err := common.RejectDangerousCharsTyped("--"+flag, val); err != nil {
+					return err
 				}
 			}
 		}
@@ -102,35 +103,35 @@ var CalendarCreate = common.Shortcut{
 					continue
 				}
 				if !strings.HasPrefix(id, "ou_") && !strings.HasPrefix(id, "oc_") && !strings.HasPrefix(id, "omm_") {
-					return output.ErrValidation("invalid attendee id format %q: should start with 'ou_', 'oc_', or 'omm_'", id)
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid attendee id format %q: should start with 'ou_', 'oc_', or 'omm_'", id).WithParam("--attendee-ids")
 				}
 			}
 		}
 
 		if runtime.Str("start") == "" {
-			return common.FlagErrorf("specify --start (e.g. '2026-03-12T14:00+08:00')")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --start (e.g. '2026-03-12T14:00+08:00')").WithParam("--start")
 		}
 		if runtime.Str("end") == "" {
-			return common.FlagErrorf("specify --end (e.g. '2026-03-12T15:00+08:00')")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --end (e.g. '2026-03-12T15:00+08:00')").WithParam("--end")
 		}
 		startTs, err := common.ParseTime(runtime.Str("start"))
 		if err != nil {
-			return common.FlagErrorf("--start: %v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
 		}
 		endTs, err := common.ParseTime(runtime.Str("end"), "end")
 		if err != nil {
-			return common.FlagErrorf("--end: %v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
 		}
 		s, err := strconv.ParseInt(startTs, 10, 64)
 		if err != nil {
-			return common.FlagErrorf("invalid start time: %v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid start time: %v", err).WithParam("--start")
 		}
 		e, err := strconv.ParseInt(endTs, 10, 64)
 		if err != nil {
-			return common.FlagErrorf("invalid end time: %v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid end time: %v", err).WithParam("--end")
 		}
 		if e <= s {
-			return common.FlagErrorf("end time must be after start time")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "end time must be after start time")
 		}
 		return nil
 	},
@@ -183,27 +184,26 @@ var CalendarCreate = common.Shortcut{
 
 		startTs, err := common.ParseTime(runtime.Str("start"))
 		if err != nil {
-			return output.ErrValidation("--start: %v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
 		}
 		endTs, err := common.ParseTime(runtime.Str("end"), "end")
 		if err != nil {
-			return output.ErrValidation("--end: %v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
 		}
 
 		eventData := buildEventData(runtime, startTs, endTs)
 
 		// Create event
-		data, err := runtime.CallAPI("POST",
+		data, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events", validate.EncodePathSegment(calendarId)),
 			nil, eventData)
-		err = wrapPredefinedError(err)
 		if err != nil {
 			return err
 		}
 		event, _ := data["event"].(map[string]interface{})
 		eventId, _ := event["event_id"].(string)
 		if eventId == "" {
-			return output.Errorf(output.ExitAPI, "api_error", "failed to create event: no event_id returned")
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "failed to create event: no event_id returned")
 		}
 
 		// Add attendees if specified
@@ -214,27 +214,25 @@ var CalendarCreate = common.Shortcut{
 			}
 			attendees, err := parseAttendees(attendeesStr, currentUserId)
 			if err != nil {
-				return output.ErrValidation("invalid attendee id: %v", err)
+				return withParam(err, "--attendee-ids")
 			}
 
-			_, err = runtime.CallAPI("POST",
+			_, err = runtime.CallAPITyped("POST",
 				fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s/attendees", validate.EncodePathSegment(calendarId), validate.EncodePathSegment(eventId)),
 				map[string]interface{}{"user_id_type": "open_id"},
 				map[string]interface{}{
 					"attendees":         attendees,
 					"need_notification": true,
 				})
-			err = wrapPredefinedError(err)
 			if err != nil {
 				// Rollback: delete the event
-				_, rollbackErr := runtime.RawAPI("DELETE",
+				_, rollbackErr := runtime.CallAPITyped("DELETE",
 					fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s", validate.EncodePathSegment(calendarId), validate.EncodePathSegment(eventId)),
 					map[string]interface{}{"need_notification": false}, nil)
-				rollbackErr = wrapPredefinedError(rollbackErr)
 				if rollbackErr != nil {
-					return output.Errorf(output.ExitAPI, "api_error", "failed to add attendees: %v; rollback also failed, orphan event_id=%s needs manual cleanup", rollbackErr, eventId)
+					return withStepContext(err, "rollback also failed (%v); orphan event_id=%s needs manual cleanup", rollbackErr, eventId)
 				}
-				return output.Errorf(output.ExitAPI, "api_error", "failed to add attendees: %v; event rolled back successfully", err)
+				return withStepContext(err, "event rolled back successfully")
 			}
 		}
 

shortcuts/calendar/calendar_freebusy.go

@@ -10,6 +10,7 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -20,20 +21,20 @@ func parseFreebusyTimeRange(runtime *common.RuntimeContext) (string, string, err
 
 	startTs, err := common.ParseTime(startInput)
 	if err != nil {
-		return "", "", output.ErrValidation("--start: %v", err)
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
 	}
 	endTs, err := common.ParseTime(endInput, "end")
 	if err != nil {
-		return "", "", output.ErrValidation("--end: %v", err)
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
 	}
 
 	startSec, err := strconv.ParseInt(startTs, 10, 64)
 	if err != nil {
-		return "", "", output.ErrValidation("invalid start timestamp: %v", err)
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid start timestamp: %v", err)
 	}
 	endSec, err := strconv.ParseInt(endTs, 10, 64)
 	if err != nil {
-		return "", "", output.ErrValidation("invalid end timestamp: %v", err)
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid end timestamp: %v", err)
 	}
 
 	timeMin := time.Unix(startSec, 0).Format(time.RFC3339)
@@ -73,13 +74,13 @@ var CalendarFreebusy = common.Shortcut{
 		}
 		userId := runtime.Str("user-id")
 		if userId == "" && runtime.IsBot() {
-			return common.FlagErrorf("--user-id is required for bot identity")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--user-id is required for bot identity").WithParam("--user-id")
 		}
 		if userId == "" && runtime.UserOpenId() == "" {
-			return common.FlagErrorf("cannot determine user ID, specify --user-id or ensure you are logged in")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot determine user ID, specify --user-id or ensure you are logged in").WithParam("--user-id")
 		}
 		if userId != "" {
-			if _, err := common.ValidateUserID(userId); err != nil {
+			if _, err := common.ValidateUserIDTyped("--user-id", userId); err != nil {
 				return err
 			}
 		}
@@ -93,16 +94,17 @@ var CalendarFreebusy = common.Shortcut{
 
 		timeMin, timeMax, err := parseFreebusyTimeRange(runtime)
 		if err != nil {
-			return output.ErrValidation("--start/--end: %v", err)
+			// parseFreebusyTimeRange already returns a typed *errs.ValidationError
+			// carrying the offending flag in .Param; pass it through unchanged.
+			return err
 		}
 
-		data, err := runtime.CallAPI("POST", "/open-apis/calendar/v4/freebusy/list", nil, map[string]interface{}{
+		data, err := runtime.CallAPITyped("POST", "/open-apis/calendar/v4/freebusy/list", nil, map[string]interface{}{
 			"time_min":         timeMin,
 			"time_max":         timeMax,
 			"user_id":          userId,
 			"need_rsvp_status": true,
 		})
-		err = wrapPredefinedError(err)
 		if err != nil {
 			return err
 		}

shortcuts/calendar/calendar_room_find.go

@@ -8,13 +8,13 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
-	"net/http"
 	"sort"
 	"strconv"
 	"strings"
 	"sync"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -126,40 +126,40 @@ func collectRoomFindResults(slots []roomFindSlot, limit int, fetch func(roomFind
 func parseRoomFindSlots(runtime *common.RuntimeContext) ([]roomFindSlot, error) {
 	rawSlots := runtime.StrArray(flagSlot)
 	if len(rawSlots) == 0 {
-		return nil, output.ErrValidation("specify at least one --slot")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "specify at least one --slot").WithParam("--slot")
 	}
 	slots := make([]roomFindSlot, 0, len(rawSlots))
 	for _, raw := range rawSlots {
 		parts := strings.Split(strings.TrimSpace(raw), "~")
 		if len(parts) != 2 {
-			return nil, output.ErrValidation("invalid --slot format %q, expected start~end", raw)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --slot format %q, expected start~end", raw).WithParam("--slot")
 		}
 		startTs, err := common.ParseTime(parts[0])
 		if err != nil {
-			return nil, output.ErrValidation("invalid slot start time %q: %v", parts[0], err)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid slot start time %q: %v", parts[0], err).WithParam("--slot")
 		}
 		endTs, err := common.ParseTime(parts[1])
 		if err != nil {
-			return nil, output.ErrValidation("invalid slot end time %q: %v", parts[1], err)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid slot end time %q: %v", parts[1], err).WithParam("--slot")
 		}
 		startSec, err := strconv.ParseInt(startTs, 10, 64)
 		if err != nil {
-			return nil, output.ErrValidation("invalid slot start timestamp %q: %v", startTs, err)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid slot start timestamp %q: %v", startTs, err).WithParam("--slot")
 		}
 		endSec, err := strconv.ParseInt(endTs, 10, 64)
 		if err != nil {
-			return nil, output.ErrValidation("invalid slot end timestamp %q: %v", endTs, err)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid slot end timestamp %q: %v", endTs, err).WithParam("--slot")
 		}
 		if endSec <= startSec {
-			return nil, output.ErrValidation("--slot end time must be after start time: %q", raw)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--slot end time must be after start time: %q", raw).WithParam("--slot")
 		}
 		startRFC3339, err := unixStringToRFC3339(startTs)
 		if err != nil {
-			return nil, output.ErrValidation("invalid slot start timestamp %q: %v", startTs, err)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid slot start timestamp %q: %v", startTs, err).WithParam("--slot")
 		}
 		endRFC3339, err := unixStringToRFC3339(endTs)
 		if err != nil {
-			return nil, output.ErrValidation("invalid slot end timestamp %q: %v", endTs, err)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid slot end timestamp %q: %v", endTs, err).WithParam("--slot")
 		}
 		slots = append(slots, roomFindSlot{Start: startRFC3339, End: endRFC3339})
 	}
@@ -196,7 +196,7 @@ func parseRoomFindAttendees(attendeesStr string, currentUserID string) ([]string
 				seenChats[id] = true
 			}
 		default:
-			return nil, nil, output.ErrValidation("invalid attendee id format %q: should start with 'ou_' or 'oc_'", id)
+			return nil, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid attendee id format %q: should start with 'ou_' or 'oc_'", id).WithParam("--" + flagAttendees)
 		}
 	}
 	if currentUserID != "" && !seenUsers[currentUserID] {
@@ -249,20 +249,19 @@ func callRoomFind(runtime *common.RuntimeContext, req *roomFindRequest) ([]*room
 		Body:       req,
 	})
 	if err != nil {
-		return nil, err
+		if _, ok := errs.ProblemOf(err); ok {
+			return nil, err
+		}
+		return nil, errs.WrapInternal(err)
 	}
 
-	if apiResp.StatusCode < http.StatusOK || apiResp.StatusCode >= http.StatusMultipleChoices {
-		return nil, output.ErrAPI(apiResp.StatusCode, "", string(apiResp.RawBody))
+	if _, err := runtime.ClassifyAPIResponse(apiResp); err != nil {
+		return nil, err
 	}
 
 	var resp = &OpenAPIResponse[*roomFindData]{}
 	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-		return nil, output.ErrWithHint(output.ExitInternal, "validation", "unmarshal response fail", err.Error())
-	}
-
-	if resp.Code != 0 {
-		return nil, output.ErrAPI(resp.Code, resp.Msg, resp.Data)
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "unmarshal response fail").WithCause(err)
 	}
 
 	if resp.Data != nil {
@@ -317,8 +316,8 @@ var CalendarRoomFind = common.Shortcut{
 		}
 		for _, flag := range []string{flagCity, flagBuilding, flagFloor, flagEventRrule, flagTimezone} {
 			if val := strings.TrimSpace(runtime.Str(flag)); val != "" {
-				if err := common.RejectDangerousChars("--"+flag, val); err != nil {
-					return output.ErrValidation(err.Error())
+				if err := common.RejectDangerousCharsTyped("--"+flag, val); err != nil {
+					return err
 				}
 			}
 		}
@@ -327,8 +326,8 @@ var CalendarRoomFind = common.Shortcut{
 			if name == "" {
 				continue
 			}
-			if err := common.RejectDangerousChars("--"+flagRoomName, name); err != nil {
-				return output.ErrValidation(err.Error())
+			if err := common.RejectDangerousCharsTyped("--"+flagRoomName, name); err != nil {
+				return err
 			}
 		}
 		if _, err := parseRoomFindSlots(runtime); err != nil {
@@ -338,13 +337,13 @@ var CalendarRoomFind = common.Shortcut{
 			return err
 		}
 		if minCapacity := runtime.Int(flagMinCapacity); minCapacity < 0 {
-			return output.ErrValidation("--min-capacity must be >= 0")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--min-capacity must be >= 0").WithParam("--min-capacity")
 		}
 		if maxCapacity := runtime.Int(flagMaxCapacity); maxCapacity < 0 {
-			return output.ErrValidation("--max-capacity must be >= 0")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--max-capacity must be >= 0").WithParam("--max-capacity")
 		}
 		if minCapacity, maxCapacity := runtime.Int(flagMinCapacity), runtime.Int(flagMaxCapacity); minCapacity > 0 && maxCapacity > 0 && minCapacity > maxCapacity {
-			return output.ErrValidation("--min-capacity must be <= --max-capacity")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--min-capacity must be <= --max-capacity").WithParam("--min-capacity")
 		}
 		return nil
 	},

shortcuts/calendar/calendar_rsvp.go

@@ -8,7 +8,7 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -51,15 +51,15 @@ var CalendarRsvp = common.Shortcut{
 		}
 		for _, flag := range []string{"calendar-id", "event-id", "rsvp-status"} {
 			if val := strings.TrimSpace(runtime.Str(flag)); val != "" {
-				if err := common.RejectDangerousChars("--"+flag, val); err != nil {
-					return output.ErrValidation(err.Error())
+				if err := common.RejectDangerousCharsTyped("--"+flag, val); err != nil {
+					return err
 				}
 			}
 		}
 
 		eventId := strings.TrimSpace(runtime.Str("event-id"))
 		if eventId == "" {
-			return output.ErrValidation("event-id cannot be empty")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "event-id cannot be empty").WithParam("--event-id")
 		}
 		return nil
 	},
@@ -71,7 +71,7 @@ var CalendarRsvp = common.Shortcut{
 		eventId := strings.TrimSpace(runtime.Str("event-id"))
 		status := strings.TrimSpace(runtime.Str("rsvp-status"))
 
-		_, err := runtime.DoAPIJSON("POST",
+		_, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s/reply",
 				validate.EncodePathSegment(calendarId),
 				validate.EncodePathSegment(eventId)),

shortcuts/calendar/calendar_suggestion.go

@@ -8,13 +8,13 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
-	"net/http"
 	"strconv"
 	"strings"
 	"time"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -70,11 +70,11 @@ func buildSuggestionRequest(runtime *common.RuntimeContext) (*SuggestionRequest,
 
 	timeMin, err := common.ParseTime(startInput)
 	if err != nil {
-		return nil, output.ErrValidation("invalid --start: %v", err)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --start: %v", err).WithParam("--start")
 	}
 	minSec, err := strconv.ParseInt(timeMin, 10, 64)
 	if err != nil {
-		return nil, output.ErrValidation("invalid start timestamp: %v", err)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid start timestamp: %v", err)
 	}
 	startTime := time.Unix(minSec, 0)
 
@@ -87,12 +87,12 @@ func buildSuggestionRequest(runtime *common.RuntimeContext) (*SuggestionRequest,
 
 	timeMax, err := common.ParseTime(endInput, "end")
 	if err != nil {
-		return nil, output.ErrValidation("invalid --end: %v", err)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --end: %v", err).WithParam("--end")
 	}
 	// Convert Unix timestamp string back to RFC3339 since the API requires RFC3339
 	maxSec, err := strconv.ParseInt(timeMax, 10, 64)
 	if err != nil {
-		return nil, output.ErrValidation("invalid end timestamp: %v", err)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid end timestamp: %v", err)
 	}
 	req.SearchStartTime = startTime.Format(time.RFC3339)
 	req.SearchEndTime = time.Unix(maxSec, 0).Format(time.RFC3339)
@@ -157,23 +157,23 @@ func buildSuggestionRequest(runtime *common.RuntimeContext) (*SuggestionRequest,
 			}
 			parts := strings.Split(r, "~")
 			if len(parts) != 2 {
-				return nil, output.ErrValidation("invalid --exclude format %q, expected 'start~end'", r)
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --exclude format %q, expected 'start~end'", r).WithParam("--exclude")
 			}
 			startTsStr, err := common.ParseTime(parts[0])
 			if err != nil {
-				return nil, output.ErrValidation("invalid start time in --exclude: %q (%v)", parts[0], err)
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid start time in --exclude: %q (%v)", parts[0], err).WithParam("--exclude")
 			}
 			endTsStr, err := common.ParseTime(parts[1], "end")
 			if err != nil {
-				return nil, output.ErrValidation("invalid end time in --exclude: %q (%v)", parts[1], err)
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid end time in --exclude: %q (%v)", parts[1], err).WithParam("--exclude")
 			}
 			startSec, err := strconv.ParseInt(startTsStr, 10, 64)
 			if err != nil {
-				return nil, output.ErrValidation("invalid start timestamp in --exclude: %v", err)
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid start timestamp in --exclude: %v", err).WithParam("--exclude")
 			}
 			endSec, err := strconv.ParseInt(endTsStr, 10, 64)
 			if err != nil {
-				return nil, output.ErrValidation("invalid end timestamp in --exclude: %v", err)
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid end timestamp in --exclude: %v", err).WithParam("--exclude")
 			}
 			excludedTimes = append(excludedTimes, &EventTime{
 				EventStartTime: time.Unix(startSec, 0).Format(time.RFC3339),
@@ -219,13 +219,13 @@ var CalendarSuggestion = common.Shortcut{
 		}
 		durationMinutes := runtime.Int(flagDurationMinutes)
 		if durationMinutes != 0 && (durationMinutes < 1 || durationMinutes > 1440) {
-			return output.ErrValidation("--duration-minutes must be between 1 and 1440")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--duration-minutes must be between 1 and 1440").WithParam("--duration-minutes")
 		}
 
 		for _, flag := range []string{flagEventRrule, flagTimezone} {
 			if val := runtime.Str(flag); val != "" {
-				if err := common.RejectDangerousChars("--"+flag, val); err != nil {
-					return output.ErrValidation(err.Error())
+				if err := common.RejectDangerousCharsTyped("--"+flag, val); err != nil {
+					return err
 				}
 			}
 		}
@@ -237,7 +237,7 @@ var CalendarSuggestion = common.Shortcut{
 					continue
 				}
 				if !strings.HasPrefix(id, "ou_") && !strings.HasPrefix(id, "oc_") {
-					return output.ErrValidation("invalid attendee id format %q: should start with 'ou_' or 'oc_'", id)
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid attendee id format %q: should start with 'ou_' or 'oc_'", id).WithParam("--" + flagAttendees)
 				}
 			}
 		}
@@ -245,14 +245,14 @@ var CalendarSuggestion = common.Shortcut{
 		startInput := runtime.Str(flagStart)
 		if startInput != "" {
 			if _, err := common.ParseTime(startInput); err != nil {
-				return output.ErrValidation("invalid start time: %v", err)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid start time: %v", err).WithParam("--start")
 			}
 		}
 
 		endInput := runtime.Str(flagEnd)
 		if endInput != "" {
 			if _, err := common.ParseTime(endInput, "end"); err != nil {
-				return output.ErrValidation("invalid end time: %v", err)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid end time: %v", err).WithParam("--end")
 			}
 		}
 
@@ -267,13 +267,13 @@ var CalendarSuggestion = common.Shortcut{
 				}
 				parts := strings.Split(r, "~")
 				if len(parts) != 2 {
-					return output.ErrValidation("invalid range format in --exclude: %q, expect start~end", r)
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid range format in --exclude: %q, expect start~end", r).WithParam("--exclude")
 				}
 				if _, err := common.ParseTime(parts[0]); err != nil {
-					return output.ErrValidation("invalid start time in --exclude: %q (%v)", parts[0], err)
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid start time in --exclude: %q (%v)", parts[0], err).WithParam("--exclude")
 				}
 				if _, err := common.ParseTime(parts[1], "end"); err != nil {
-					return output.ErrValidation("invalid end time in --exclude: %q (%v)", parts[1], err)
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid end time in --exclude: %q (%v)", parts[1], err).WithParam("--exclude")
 				}
 			}
 		}
@@ -292,20 +292,19 @@ var CalendarSuggestion = common.Shortcut{
 			Body:       req,
 		})
 		if err != nil {
-			return err
+			if _, ok := errs.ProblemOf(err); ok {
+				return err
+			}
+			return errs.WrapInternal(err)
 		}
 
-		if apiResp.StatusCode < http.StatusOK || apiResp.StatusCode >= http.StatusMultipleChoices {
-			return output.ErrAPI(apiResp.StatusCode, "", string(apiResp.RawBody))
+		if _, err := runtime.ClassifyAPIResponse(apiResp); err != nil {
+			return err
 		}
 
 		var resp = &OpenAPIResponse[*SuggestionResponse]{}
 		if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-			return output.ErrWithHint(output.ExitInternal, "validation", "unmarshal response fail", err.Error())
-		}
-
-		if resp.Code != 0 {
-			return output.ErrAPI(resp.Code, resp.Msg, resp.Data)
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "unmarshal response fail").WithCause(err)
 		}
 
 		data := resp.Data

shortcuts/calendar/calendar_update.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -53,14 +54,14 @@ func validateCalendarUpdate(runtime *common.RuntimeContext) error {
 	}
 	for _, flag := range []string{"event-id", "summary", "description", "rrule", "calendar-id", "start", "end", "add-attendee-ids", "remove-attendee-ids"} {
 		if val := runtime.Str(flag); val != "" {
-			if err := common.RejectDangerousChars("--"+flag, val); err != nil {
-				return output.ErrValidation(err.Error())
+			if err := common.RejectDangerousCharsTyped("--"+flag, val); err != nil {
+				return err
 			}
 		}
 	}
 
 	if strings.TrimSpace(runtime.Str("event-id")) == "" {
-		return common.FlagErrorf("specify --event-id")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --event-id").WithParam("--event-id")
 	}
 	if _, _, err := buildCalendarUpdateEventData(runtime); err != nil {
 		return err
@@ -69,7 +70,7 @@ func validateCalendarUpdate(runtime *common.RuntimeContext) error {
 		return err
 	}
 	if !hasCalendarUpdateOperation(runtime) {
-		return common.FlagErrorf("nothing to update: specify at least one of --summary, --description, --start/--end, --rrule, --add-attendee-ids, or --remove-attendee-ids")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "nothing to update: specify at least one of --summary, --description, --start/--end, --rrule, --add-attendee-ids, or --remove-attendee-ids")
 	}
 	return nil
 }
@@ -77,11 +78,11 @@ func validateCalendarUpdate(runtime *common.RuntimeContext) error {
 func validateCalendarUpdateAttendees(runtime *common.RuntimeContext) error {
 	addIDs, err := parseCalendarAttendeeIDs(runtime.Str("add-attendee-ids"))
 	if err != nil {
-		return err
+		return withParam(err, "--add-attendee-ids")
 	}
 	removeIDs, err := parseCalendarAttendeeIDs(runtime.Str("remove-attendee-ids"))
 	if err != nil {
-		return err
+		return withParam(err, "--remove-attendee-ids")
 	}
 	removeSet := make(map[string]struct{}, len(removeIDs))
 	for _, id := range removeIDs {
@@ -89,7 +90,7 @@ func validateCalendarUpdateAttendees(runtime *common.RuntimeContext) error {
 	}
 	for _, id := range addIDs {
 		if _, ok := removeSet[id]; ok {
-			return output.ErrValidation("attendee id %q appears in both --add-attendee-ids and --remove-attendee-ids", id)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "attendee id %q appears in both --add-attendee-ids and --remove-attendee-ids", id)
 		}
 	}
 	return nil
@@ -124,27 +125,27 @@ func buildCalendarUpdateEventData(runtime *common.RuntimeContext) (map[string]in
 	startChanged := runtime.Cmd.Flags().Changed("start")
 	endChanged := runtime.Cmd.Flags().Changed("end")
 	if startChanged != endChanged {
-		return nil, false, common.FlagErrorf("--start and --end must be specified together when updating event time")
+		return nil, false, errs.NewValidationError(errs.SubtypeInvalidArgument, "--start and --end must be specified together when updating event time")
 	}
 	if startChanged {
 		startTs, err := common.ParseTime(runtime.Str("start"))
 		if err != nil {
-			return nil, false, common.FlagErrorf("--start: %v", err)
+			return nil, false, errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
 		}
 		endTs, err := common.ParseTime(runtime.Str("end"), "end")
 		if err != nil {
-			return nil, false, common.FlagErrorf("--end: %v", err)
+			return nil, false, errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
 		}
 		s, err := strconv.ParseInt(startTs, 10, 64)
 		if err != nil {
-			return nil, false, common.FlagErrorf("invalid start time: %v", err)
+			return nil, false, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid start time: %v", err).WithParam("--start")
 		}
 		e, err := strconv.ParseInt(endTs, 10, 64)
 		if err != nil {
-			return nil, false, common.FlagErrorf("invalid end time: %v", err)
+			return nil, false, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid end time: %v", err).WithParam("--end")
 		}
 		if e <= s {
-			return nil, false, common.FlagErrorf("end time must be after start time")
+			return nil, false, errs.NewValidationError(errs.SubtypeInvalidArgument, "end time must be after start time")
 		}
 		body["start_time"] = map[string]string{"timestamp": startTs}
 		body["end_time"] = map[string]string{"timestamp": endTs}
@@ -169,7 +170,7 @@ func parseCalendarAttendeeIDs(attendeesStr string) ([]string, error) {
 			continue
 		}
 		if !strings.HasPrefix(id, "ou_") && !strings.HasPrefix(id, "oc_") && !strings.HasPrefix(id, "omm_") {
-			return nil, output.ErrValidation("invalid attendee id format %q: should start with 'ou_', 'oc_', or 'omm_'", id)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid attendee id format %q: should start with 'ou_', 'oc_', or 'omm_'", id)
 		}
 		if _, ok := seen[id]; ok {
 			continue
@@ -195,7 +196,7 @@ func attendeeDeleteIDs(attendeesStr string) ([]map[string]string, error) {
 		case strings.HasPrefix(id, "ou_"):
 			deleteIDs = append(deleteIDs, map[string]string{"type": "user", "user_id": id})
 		default:
-			return nil, output.ErrValidation("invalid attendee id format %q: should start with 'ou_', 'oc_', or 'omm_'", id)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid attendee id format %q: should start with 'ou_', 'oc_', or 'omm_'", id).WithParam("--remove-attendee-ids")
 		}
 	}
 	return deleteIDs, nil
@@ -280,7 +281,7 @@ func dryRunCalendarUpdate(runtime *common.RuntimeContext) *common.DryRunAPI {
 func executeCalendarUpdate(_ context.Context, runtime *common.RuntimeContext) error {
 	calendarID, eventID := calendarUpdateIDs(runtime)
 	if eventID == "" {
-		return output.ErrValidation("specify --event-id")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --event-id").WithParam("--event-id")
 	}
 
 	body, hasEventFields, err := buildCalendarUpdateEventData(runtime)
@@ -291,10 +292,9 @@ func executeCalendarUpdate(_ context.Context, runtime *common.RuntimeContext) er
 	completed := []string{}
 	event := map[string]interface{}{}
 	if hasEventFields {
-		data, err := runtime.CallAPI("PATCH", calendarUpdateEventPath(calendarID, eventID), map[string]interface{}{"user_id_type": "open_id"}, body)
-		err = wrapPredefinedError(err)
+		data, err := runtime.CallAPITyped("PATCH", calendarUpdateEventPath(calendarID, eventID), map[string]interface{}{"user_id_type": "open_id"}, body)
 		if err != nil {
-			return output.Errorf(output.ExitAPI, "api_error", "failed to update event %s: %v", eventID, err)
+			return withStepContext(err, "failed to update event %s after completed steps %v", eventID, completed)
 		}
 		if v, _ := data["event"].(map[string]interface{}); v != nil {
 			event = v
@@ -308,12 +308,11 @@ func executeCalendarUpdate(_ context.Context, runtime *common.RuntimeContext) er
 		if err != nil {
 			return err
 		}
-		_, err = runtime.CallAPI("POST", calendarUpdateAttendeesPath(calendarID, eventID)+"/batch_delete",
+		_, err = runtime.CallAPITyped("POST", calendarUpdateAttendeesPath(calendarID, eventID)+"/batch_delete",
 			map[string]interface{}{"user_id_type": "open_id"},
 			map[string]interface{}{"delete_ids": deleteIDs, "need_notification": runtime.Bool("notify")})
-		err = wrapPredefinedError(err)
 		if err != nil {
-			return output.Errorf(output.ExitAPI, "api_error", "failed to remove attendees from event %s after completed steps %v: %v", eventID, completed, err)
+			return withStepContext(err, "failed to remove attendees from event %s after completed steps %v", eventID, completed)
 		}
 		removedCount = len(deleteIDs)
 		completed = append(completed, "remove_attendees")
@@ -323,14 +322,13 @@ func executeCalendarUpdate(_ context.Context, runtime *common.RuntimeContext) er
 	if addStr := runtime.Str("add-attendee-ids"); strings.TrimSpace(addStr) != "" {
 		attendees, err := parseAttendees(addStr, "")
 		if err != nil {
-			return output.ErrValidation("invalid attendee id: %v", err)
+			return withParam(err, "--add-attendee-ids")
 		}
-		_, err = runtime.CallAPI("POST", calendarUpdateAttendeesPath(calendarID, eventID),
+		_, err = runtime.CallAPITyped("POST", calendarUpdateAttendeesPath(calendarID, eventID),
 			map[string]interface{}{"user_id_type": "open_id"},
 			map[string]interface{}{"attendees": attendees, "need_notification": runtime.Bool("notify")})
-		err = wrapPredefinedError(err)
 		if err != nil {
-			return output.Errorf(output.ExitAPI, "api_error", "failed to add attendees to event %s after completed steps %v: %v", eventID, completed, err)
+			return withStepContext(err, "failed to add attendees to event %s after completed steps %v", eventID, completed)
 		}
 		addedCount = len(attendees)
 	}

shortcuts/calendar/errors.go

@@ -6,68 +6,39 @@ package calendar
 import (
 	"errors"
 	"fmt"
+	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 )
 
-const (
-	errCodeInvalidParamsWithDetail = 190014
-)
-
-// getErrorDetailValue extracts the first detail value from the output.ErrDetail.
-// It assumes Detail is a map containing a "details" array of objects with "value" string fields.
-// For example: {"details": [{"value": "error message 1"}, {"value": "error message 2"}]}
-// Returns an empty string if the structure doesn't match or the array is empty.
-//
-// Deprecated: getErrorDetailValue reads from the legacy *output.ErrDetail
-// that predates the typed error contract introduced by errs/. New code MUST
-// NOT use it — typed errs.* errors expose Message, Hint, and extension
-// fields directly on the typed struct via errors.As / errs.ProblemOf. This
-// helper is retained only while existing call sites are migrated; it will
-// be removed once they have moved to the typed surface.
-func getErrorDetailValue(e *output.ErrDetail) string {
-	if e == nil || e.Detail == nil {
-		return ""
-	}
-
-	errMap, ok := e.Detail.(map[string]interface{})
-	if !ok {
-		return ""
-	}
-
-	details, ok := errMap["details"].([]interface{})
-	if !ok || len(details) == 0 {
-		return ""
-	}
-
-	detailObj, ok := details[0].(map[string]interface{})
-	if !ok {
-		return ""
-	}
-
-	val, _ := detailObj["value"].(string)
-	return val
-}
-
-// wrapPredefinedError wraps an error into *output.ExitError if it matches predefined error codes.
-// Currently handles error code 190014 (invalid params with detail), extracting the detail value into the message.
-// If the error is nil or doesn't match predefined codes, returns the original error.
-func wrapPredefinedError(err error) error {
+// withStepContext annotates err with multi-step context (e.g. which steps
+// already completed, or that a rollback ran) while preserving the underlying
+// failure's classification. An already-typed error keeps its own
+// category/subtype/code/log_id; we only append the formatted context to its
+// Hint so the top-level envelope still tells the truth about what failed.
+// Only an unclassified error falls back to a typed internal wrap.
+func withStepContext(err error, format string, args ...any) error {
 	if err == nil {
 		return nil
 	}
-
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+	extra := fmt.Sprintf(format, args...)
+	if p, ok := errs.ProblemOf(err); ok {
+		if strings.TrimSpace(p.Hint) != "" {
+			p.Hint = p.Hint + "\n" + extra
+		} else {
+			p.Hint = extra
+		}
 		return err
 	}
+	return errs.NewInternalError(errs.SubtypeSDKError, "%s", err.Error()).WithHint(extra).WithCause(err)
+}
 
-	if exitErr.Detail.Code == errCodeInvalidParamsWithDetail {
-		if val := getErrorDetailValue(exitErr.Detail); val != "" {
-			fullMsg := fmt.Sprintf("%s: %s", exitErr.Detail.Message, val)
-			return output.ErrAPI(exitErr.Detail.Code, fullMsg, exitErr.Detail.Detail)
-		}
+// withParam attaches the offending flag to a typed validation error, preserving
+// the original error instead of re-wrapping it. Non-validation errors pass through.
+func withParam(err error, flag string) error {
+	var ve *errs.ValidationError
+	if errors.As(err, &ve) {
+		return ve.WithParam(flag)
 	}
-
 	return err
 }

shortcuts/calendar/errors_attribution_test.go

@@ -0,0 +1,242 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+// newAttendeeValidateRuntime builds a RuntimeContext with the add/remove
+// attendee-id flags set, for exercising validateCalendarUpdateAttendees.
+func newAttendeeValidateRuntime(t *testing.T, add, remove string) *common.RuntimeContext {
+	t.Helper()
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("add-attendee-ids", "", "")
+	cmd.Flags().String("remove-attendee-ids", "", "")
+	if err := cmd.ParseFlags(nil); err != nil {
+		t.Fatalf("ParseFlags: %v", err)
+	}
+	if add != "" {
+		_ = cmd.Flags().Set("add-attendee-ids", add)
+	}
+	if remove != "" {
+		_ = cmd.Flags().Set("remove-attendee-ids", remove)
+	}
+	return &common.RuntimeContext{Cmd: cmd}
+}
+
+// assertValidationParam asserts err is a *errs.ValidationError whose Param
+// equals wantParam, and returns it for any further message assertions.
+func assertValidationParam(t *testing.T, err error, wantParam string) *errs.ValidationError {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("expected error, got nil")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T (%v)", err, err)
+	}
+	if ve.Param != wantParam {
+		t.Errorf("Param = %q, want %q", ve.Param, wantParam)
+	}
+	return ve
+}
+
+// ---------------------------------------------------------------------------
+// withStepContext helper
+// ---------------------------------------------------------------------------
+
+func TestWithStepContext_Nil(t *testing.T) {
+	if got := withStepContext(nil, "step %d", 1); got != nil {
+		t.Fatalf("withStepContext(nil) = %v, want nil", got)
+	}
+}
+
+func TestWithStepContext_AppendsToTypedHint(t *testing.T) {
+	// A typed error keeps its classification; the context is appended to Hint.
+	inner := errs.NewAPIError(errs.SubtypeUnknown, "boom").WithHint("first")
+	got := withStepContext(inner, "after steps %v", []string{"event"})
+	var ae *errs.APIError
+	if !errors.As(got, &ae) {
+		t.Fatalf("want *errs.APIError, got %T", got)
+	}
+	if ae.Hint == "" || !strings.Contains(ae.Hint, "first") || !strings.Contains(ae.Hint, "after steps") {
+		t.Errorf("hint should append context, got %q", ae.Hint)
+	}
+}
+
+func TestWithStepContext_SetsHintWhenEmpty(t *testing.T) {
+	inner := errs.NewAPIError(errs.SubtypeUnknown, "boom")
+	got := withStepContext(inner, "after steps %v", []string{"event"})
+	var ae *errs.APIError
+	if !errors.As(got, &ae) {
+		t.Fatalf("want *errs.APIError, got %T", got)
+	}
+	if !strings.Contains(ae.Hint, "after steps") {
+		t.Errorf("hint should be set, got %q", ae.Hint)
+	}
+}
+
+func TestWithStepContext_UnclassifiedFallsBackToInternal(t *testing.T) {
+	// A plain, unclassified error is wrapped into a typed internal error so the
+	// envelope still tells the truth.
+	got := withStepContext(errors.New("raw failure"), "after steps %v", []string{"event"})
+	var ie *errs.InternalError
+	if !errors.As(got, &ie) {
+		t.Fatalf("want *errs.InternalError, got %T", got)
+	}
+	if ie.Subtype != errs.SubtypeSDKError {
+		t.Errorf("subtype=%q, want sdk_error", ie.Subtype)
+	}
+	if !strings.Contains(ie.Message, "raw failure") {
+		t.Errorf("message should preserve original, got %q", ie.Message)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// withParam helper
+// ---------------------------------------------------------------------------
+
+func TestWithParam_AttachesToValidationError(t *testing.T) {
+	inner := errs.NewValidationError(errs.SubtypeInvalidArgument, "boom")
+	got := withParam(inner, "--attendee-ids")
+	ve := assertValidationParam(t, got, "--attendee-ids")
+	if ve != inner {
+		t.Errorf("withParam should return the same underlying error, got a different pointer")
+	}
+	if ve.Message != "boom" {
+		t.Errorf("message mutated: got %q, want %q", ve.Message, "boom")
+	}
+}
+
+func TestWithParam_NonValidationPassesThrough(t *testing.T) {
+	inner := errs.NewInternalError(errs.SubtypeSDKError, "io failure")
+	got := withParam(inner, "--attendee-ids")
+	if got != inner {
+		t.Fatalf("non-validation error should pass through unchanged, got %v", got)
+	}
+	var ve *errs.ValidationError
+	if errors.As(got, &ve) {
+		t.Fatalf("non-validation error must not become a ValidationError")
+	}
+}
+
+func TestWithParam_NilPassesThrough(t *testing.T) {
+	if got := withParam(nil, "--attendee-ids"); got != nil {
+		t.Fatalf("withParam(nil) = %v, want nil", got)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Part A — re-wrap sites: the parseAttendees error, attributed by the caller's
+// flag, must be the inner typed error (not a re-wrapped nesting).
+// ---------------------------------------------------------------------------
+
+func TestParseAttendees_AttributedToCreateFlag(t *testing.T) {
+	_, err := parseAttendees("bad-id", "")
+	// create's add path: withParam(err, "--attendee-ids")
+	got := withParam(err, "--attendee-ids")
+	assertValidationParam(t, got, "--attendee-ids")
+}
+
+func TestParseAttendees_AttributedToAddFlag(t *testing.T) {
+	_, err := parseAttendees("bad-id", "")
+	// update's add path: withParam(err, "--add-attendee-ids")
+	got := withParam(err, "--add-attendee-ids")
+	assertValidationParam(t, got, "--add-attendee-ids")
+}
+
+func TestParseAttendees_InnerStaysFlagAgnostic(t *testing.T) {
+	// The shared inner parser must not pre-attribute a flag; callers do.
+	_, err := parseAttendees("bad-id", "")
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if ve.Param != "" {
+		t.Errorf("inner parseAttendees should stay flag-agnostic, got Param = %q", ve.Param)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Part B — direct attendee-id format validations carry their flag.
+// ---------------------------------------------------------------------------
+
+func TestParseRoomFindAttendees_FormatErrorParam(t *testing.T) {
+	_, _, err := parseRoomFindAttendees("bad-id", "")
+	assertValidationParam(t, err, "--"+flagAttendees)
+}
+
+func TestParseRoomFindAttendees_RejectsRoomID(t *testing.T) {
+	// room find only supports ou_/oc_; omm_ rooms are not valid attendees.
+	_, _, err := parseRoomFindAttendees("omm_room", "")
+	assertValidationParam(t, err, "--"+flagAttendees)
+}
+
+func TestParseCalendarAttendeeIDs_StaysFlagAgnostic(t *testing.T) {
+	// parseCalendarAttendeeIDs serves BOTH --add-attendee-ids and
+	// --remove-attendee-ids, so it must not pre-attribute a flag.
+	_, err := parseCalendarAttendeeIDs("bad-id")
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if ve.Param != "" {
+		t.Errorf("shared parser should stay flag-agnostic, got Param = %q", ve.Param)
+	}
+}
+
+func TestValidateCalendarUpdateAttendees_RemoveFormatParam(t *testing.T) {
+	// The remove path attributes its parser error to --remove-attendee-ids.
+	rt := newAttendeeValidateRuntime(t, "", "bad-id")
+	err := validateCalendarUpdateAttendees(rt)
+	assertValidationParam(t, err, "--remove-attendee-ids")
+}
+
+func TestValidateCalendarUpdateAttendees_AddFormatParam(t *testing.T) {
+	// The add path attributes its parser error to --add-attendee-ids.
+	rt := newAttendeeValidateRuntime(t, "bad-id", "")
+	err := validateCalendarUpdateAttendees(rt)
+	assertValidationParam(t, err, "--add-attendee-ids")
+}
+
+// attendeeDeleteIDs's switch default is defensive: parseCalendarAttendeeIDs
+// already rejects any non-ou_/oc_/omm_ id, so only a well-formed id reaches the
+// switch and the valid branches map it. This asserts the happy path maps types.
+func TestAttendeeDeleteIDs_MapsKnownTypes(t *testing.T) {
+	got, err := attendeeDeleteIDs("ou_a,oc_b,omm_c")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(got) != 3 {
+		t.Fatalf("expected 3 delete ids, got %d: %v", len(got), got)
+	}
+	wantTypes := map[string]string{"user": "user_id", "chat": "chat_id", "resource": "room_id"}
+	for _, m := range got {
+		key, ok := wantTypes[m["type"]]
+		if !ok {
+			t.Errorf("unexpected type %q in %v", m["type"], m)
+			continue
+		}
+		if m[key] == "" {
+			t.Errorf("missing %s for type %q in %v", key, m["type"], m)
+		}
+	}
+}
+
+func TestParseCalendarAttendeeIDs_Valid(t *testing.T) {
+	ids, err := parseCalendarAttendeeIDs(" ou_a , oc_b , ou_a ")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(ids) != 2 || ids[0] != "ou_a" || ids[1] != "oc_b" {
+		t.Errorf("dedup/trim failed: got %v", ids)
+	}
+}

shortcuts/common/call_api_typed_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -198,3 +199,58 @@ func TestCallAPITyped_NonObjectJSON(t *testing.T) {
 		t.Errorf("subtype = %q, want %q", intErr.Subtype, errs.SubtypeInvalidResponse)
 	}
 }
+
+// TestDoAPIJSONTyped_Success returns the data object on code 0, confirming the
+// typed DoAPIJSON replacement preserves the success contract of DoAPIJSON.
+func TestDoAPIJSONTyped_Success(t *testing.T) {
+	rt, reg := newCallAPITypedRuntime(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/x/z",
+		Body:   map[string]interface{}{"code": float64(0), "data": map[string]interface{}{"id": "z1"}},
+	})
+
+	data, err := rt.DoAPIJSONTyped("GET", "/open-apis/x/z", nil, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if data["id"] != "z1" {
+		t.Errorf("data[id] = %v, want z1", data["id"])
+	}
+}
+
+func TestDoAPIJSONTyped_RawClientErrorBecomesTypedInternal(t *testing.T) {
+	rt := TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+x"}, &core.CliConfig{}, nil, core.AsUser)
+	rt.apiClientFunc = func() (*client.APIClient, error) {
+		return nil, errors.New("raw client construction error")
+	}
+
+	_, err := rt.DoAPIJSONTyped("GET", "/open-apis/x/z", nil, nil)
+	var internalErr *errs.InternalError
+	if !errors.As(err, &internalErr) {
+		t.Fatalf("expected raw client errors to be lifted to typed internal errors, got %T: %v", err, err)
+	}
+	if internalErr.Subtype != errs.SubtypeUnknown {
+		t.Errorf("subtype = %q, want %q", internalErr.Subtype, errs.SubtypeUnknown)
+	}
+}
+
+// TestDoAPIJSONTyped_NonZeroCode classifies a non-zero API code into a typed
+// errs.* error (carrying log_id), never a legacy output.ExitError envelope.
+func TestDoAPIJSONTyped_NonZeroCode(t *testing.T) {
+	rt, reg := newCallAPITypedRuntime(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/x/z",
+		Body:   map[string]interface{}{"code": float64(1061044), "msg": "boom", "log_id": "lz"},
+	})
+
+	_, err := rt.DoAPIJSONTyped("POST", "/open-apis/x/z", nil, map[string]any{})
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected a typed errs.* error, got %T: %v", err, err)
+	}
+	if p.LogID != "lz" {
+		t.Errorf("LogID = %q, want lz", p.LogID)
+	}
+}

shortcuts/common/drive_media_upload.go

@@ -15,6 +15,7 @@ import (
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -57,6 +58,7 @@ type DriveMediaMultipartUploadConfig struct {
 	Reader io.Reader
 }
 
+// Deprecated: use UploadDriveMediaAllTyped for typed error envelopes.
 func UploadDriveMediaAll(runtime *RuntimeContext, cfg DriveMediaUploadAllConfig) (string, error) {
 	var fileReader io.Reader
 	if cfg.Reader != nil {
@@ -98,6 +100,52 @@ func UploadDriveMediaAll(runtime *RuntimeContext, cfg DriveMediaUploadAllConfig)
 	return ExtractDriveMediaUploadFileToken(data, driveMediaUploadAllAction)
 }
 
+// UploadDriveMediaAllTyped is the typed-error counterpart of
+// UploadDriveMediaAll: file-open failures surface as typed validation errors,
+// transport failures as typed network errors, and API failures are classified
+// via ClassifyAPIResponse so subtype / code / log_id survive on the error.
+func UploadDriveMediaAllTyped(runtime *RuntimeContext, cfg DriveMediaUploadAllConfig) (string, error) {
+	var fileReader io.Reader
+	if cfg.Reader != nil {
+		fileReader = cfg.Reader
+	} else {
+		f, err := runtime.FileIO().Open(cfg.FilePath)
+		if err != nil {
+			return "", WrapInputStatErrorTyped(err)
+		}
+		defer f.Close()
+		fileReader = f
+	}
+
+	fd := larkcore.NewFormdata()
+	fd.AddField("file_name", cfg.FileName)
+	fd.AddField("parent_type", cfg.ParentType)
+	fd.AddField("size", fmt.Sprintf("%d", cfg.FileSize))
+	if cfg.ParentNode != nil {
+		fd.AddField("parent_node", *cfg.ParentNode)
+	}
+	if cfg.Extra != "" {
+		fd.AddField("extra", cfg.Extra)
+	}
+	fd.AddFile("file", fileReader)
+
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod: http.MethodPost,
+		ApiPath:    "/open-apis/drive/v1/medias/upload_all",
+		Body:       fd,
+	}, larkcore.WithFileUpload())
+	if err != nil {
+		return "", prefixDriveMediaUploadProblem(client.WrapDoAPIError(err), driveMediaUploadAllAction)
+	}
+
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return "", prefixDriveMediaUploadProblem(err, driveMediaUploadAllAction)
+	}
+	return extractDriveMediaUploadFileTokenTyped(data, driveMediaUploadAllAction)
+}
+
+// Deprecated: use UploadDriveMediaMultipartTyped for typed error envelopes.
 func UploadDriveMediaMultipart(runtime *RuntimeContext, cfg DriveMediaMultipartUploadConfig) (string, error) {
 	// upload_prepare expects parent_node to be present even when the caller wants
 	// the service default/root behavior, so multipart callers pass an explicit
@@ -130,6 +178,43 @@ func UploadDriveMediaMultipart(runtime *RuntimeContext, cfg DriveMediaMultipartU
 	return finishDriveMediaMultipartUpload(runtime, session.UploadID, session.BlockNum)
 }
 
+// UploadDriveMediaMultipartTyped is the typed-error counterpart of
+// UploadDriveMediaMultipart: prepare/finish failures come back typed from
+// CallAPITyped, malformed session plans surface as invalid-response internal
+// errors, and per-part transport/API failures are classified the same way as
+// UploadDriveMediaAllTyped.
+func UploadDriveMediaMultipartTyped(runtime *RuntimeContext, cfg DriveMediaMultipartUploadConfig) (string, error) {
+	// upload_prepare expects parent_node to be present even when the caller wants
+	// the service default/root behavior, so multipart callers pass an explicit
+	// string instead of relying on field omission like upload_all does.
+	prepareBody := map[string]interface{}{
+		"file_name":   cfg.FileName,
+		"parent_type": cfg.ParentType,
+		"parent_node": cfg.ParentNode,
+		"size":        cfg.FileSize,
+	}
+	if cfg.Extra != "" {
+		prepareBody["extra"] = cfg.Extra
+	}
+
+	data, err := runtime.CallAPITyped("POST", "/open-apis/drive/v1/medias/upload_prepare", nil, prepareBody)
+	if err != nil {
+		return "", err
+	}
+
+	session, err := parseDriveMediaMultipartUploadSessionTyped(data)
+	if err != nil {
+		return "", err
+	}
+	fmt.Fprintf(runtime.IO().ErrOut, "Multipart upload initialized: %d chunks x %s\n", session.BlockNum, FormatSize(session.BlockSize))
+
+	if err = uploadDriveMediaMultipartPartsTyped(runtime, cfg, session); err != nil {
+		return "", err
+	}
+
+	return finishDriveMediaMultipartUploadTyped(runtime, session.UploadID, session.BlockNum)
+}
+
 func ParseDriveMediaMultipartUploadSession(data map[string]interface{}) (DriveMediaMultipartUploadSession, error) {
 	// The backend chooses both chunk size and chunk count. Validate them once so
 	// the streaming loop can follow the returned plan without re-checking shape.
@@ -280,3 +365,122 @@ func finishDriveMediaMultipartUpload(runtime *RuntimeContext, uploadID string, b
 	}
 	return ExtractDriveMediaUploadFileToken(data, driveMediaUploadFinishAction)
 }
+
+// prefixDriveMediaUploadProblem prepends the upload action to a typed error's
+// message so callers see which upload step failed. Non-typed errors are
+// returned unchanged.
+func prefixDriveMediaUploadProblem(err error, action string) error {
+	if p, ok := errs.ProblemOf(err); ok {
+		p.Message = action + ": " + p.Message
+	}
+	return err
+}
+
+// parseDriveMediaMultipartUploadSessionTyped validates the upload_prepare
+// session plan like ParseDriveMediaMultipartUploadSession, but reports a
+// malformed plan as a typed invalid-response internal error.
+func parseDriveMediaMultipartUploadSessionTyped(data map[string]interface{}) (DriveMediaMultipartUploadSession, error) {
+	session := DriveMediaMultipartUploadSession{
+		UploadID:  GetString(data, "upload_id"),
+		BlockSize: int64(GetFloat(data, "block_size")),
+		BlockNum:  int(GetFloat(data, "block_num")),
+	}
+	if session.UploadID == "" {
+		return DriveMediaMultipartUploadSession{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "upload prepare failed: no upload_id returned")
+	}
+	if session.BlockSize <= 0 {
+		return DriveMediaMultipartUploadSession{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "upload prepare failed: invalid block_size returned")
+	}
+	if session.BlockNum <= 0 {
+		return DriveMediaMultipartUploadSession{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "upload prepare failed: invalid block_num returned")
+	}
+	return session, nil
+}
+
+// extractDriveMediaUploadFileTokenTyped mirrors ExtractDriveMediaUploadFileToken
+// with a typed invalid-response internal error for a missing file_token.
+func extractDriveMediaUploadFileTokenTyped(data map[string]interface{}, action string) (string, error) {
+	fileToken := GetString(data, "file_token")
+	if fileToken == "" {
+		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "%s: no file_token returned", action)
+	}
+	return fileToken, nil
+}
+
+// uploadDriveMediaMultipartPartsTyped mirrors uploadDriveMediaMultipartParts
+// with typed errors for file-open, file-read, and per-part upload failures.
+func uploadDriveMediaMultipartPartsTyped(runtime *RuntimeContext, cfg DriveMediaMultipartUploadConfig, session DriveMediaMultipartUploadSession) error {
+	var r io.Reader
+	if cfg.Reader != nil {
+		r = cfg.Reader
+	} else {
+		f, err := runtime.FileIO().Open(cfg.FilePath)
+		if err != nil {
+			return WrapInputStatErrorTyped(err)
+		}
+		defer f.Close()
+		r = f
+	}
+
+	maxInt := int64(^uint(0) >> 1)
+	bufferSize := session.BlockSize
+	if bufferSize <= 0 || bufferSize > maxInt {
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "upload prepare failed: invalid block_size returned")
+	}
+	buffer := make([]byte, int(bufferSize))
+	remaining := cfg.FileSize
+	// Follow the server-declared block plan exactly; upload_finish expects the
+	// same block count returned by upload_prepare.
+	for seq := 0; seq < session.BlockNum; seq++ {
+		chunkSize := session.BlockSize
+		if remaining > 0 && chunkSize > remaining {
+			chunkSize = remaining
+		}
+
+		n, readErr := io.ReadFull(r, buffer[:int(chunkSize)])
+		if readErr != nil {
+			return WrapInputStatErrorTyped(readErr)
+		}
+
+		if err := uploadDriveMediaMultipartPartTyped(runtime, session.UploadID, seq, buffer[:n]); err != nil {
+			return err
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "  Block %d/%d uploaded (%s)\n", seq+1, session.BlockNum, FormatSize(int64(n)))
+		remaining -= int64(n)
+	}
+
+	return nil
+}
+
+func uploadDriveMediaMultipartPartTyped(runtime *RuntimeContext, uploadID string, seq int, chunk []byte) error {
+	fd := larkcore.NewFormdata()
+	fd.AddField("upload_id", uploadID)
+	fd.AddField("seq", fmt.Sprintf("%d", seq))
+	fd.AddField("size", fmt.Sprintf("%d", len(chunk)))
+	fd.AddFile("file", bytes.NewReader(chunk))
+
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod: http.MethodPost,
+		ApiPath:    "/open-apis/drive/v1/medias/upload_part",
+		Body:       fd,
+	}, larkcore.WithFileUpload())
+	if err != nil {
+		return prefixDriveMediaUploadProblem(client.WrapDoAPIError(err), driveMediaUploadPartAction)
+	}
+
+	if _, err := runtime.ClassifyAPIResponse(apiResp); err != nil {
+		return prefixDriveMediaUploadProblem(err, driveMediaUploadPartAction)
+	}
+	return nil
+}
+
+func finishDriveMediaMultipartUploadTyped(runtime *RuntimeContext, uploadID string, blockNum int) (string, error) {
+	data, err := runtime.CallAPITyped("POST", "/open-apis/drive/v1/medias/upload_finish", nil, map[string]interface{}{
+		"upload_id": uploadID,
+		"block_num": blockNum,
+	})
+	if err != nil {
+		return "", err
+	}
+	return extractDriveMediaUploadFileTokenTyped(data, driveMediaUploadFinishAction)
+}

shortcuts/common/drive_media_upload_typed_test.go

@@ -0,0 +1,305 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"bytes"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestUploadDriveMediaAllTypedWithInMemoryContent(t *testing.T) {
+	runtime, reg := newDriveMediaUploadTestRuntime(t)
+	withDriveMediaUploadWorkingDir(t, t.TempDir())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"file_token": "file_typed_123"},
+		},
+	})
+
+	payload := []byte{0x89, 0x50, 0x4e, 0x47}
+	fileToken, err := UploadDriveMediaAllTyped(runtime, DriveMediaUploadAllConfig{
+		Reader:     bytes.NewReader(payload),
+		FileName:   "clipboard.png",
+		FileSize:   int64(len(payload)),
+		ParentType: "docx_image",
+		ParentNode: strPtr("blk_parent"),
+	})
+	if err != nil {
+		t.Fatalf("UploadDriveMediaAllTyped() error: %v", err)
+	}
+	if fileToken != "file_typed_123" {
+		t.Fatalf("fileToken = %q, want %q", fileToken, "file_typed_123")
+	}
+}
+
+func TestUploadDriveMediaAllTypedClassifiesAPIFailure(t *testing.T) {
+	runtime, reg := newDriveMediaUploadTestRuntime(t)
+	withDriveMediaUploadWorkingDir(t, t.TempDir())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body: map[string]interface{}{
+			"code": 999,
+			"msg":  "upload rejected",
+		},
+	})
+
+	payload := []byte{0x01}
+	_, err := UploadDriveMediaAllTyped(runtime, DriveMediaUploadAllConfig{
+		Reader:     bytes.NewReader(payload),
+		FileName:   "clipboard.png",
+		FileSize:   int64(len(payload)),
+		ParentType: "docx_image",
+		ParentNode: strPtr("blk_parent"),
+	})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T (%v)", err, err)
+	}
+	if p.Category != errs.CategoryAPI {
+		t.Fatalf("category = %s, want api", p.Category)
+	}
+	if p.Code != 999 {
+		t.Fatalf("code = %d, want 999", p.Code)
+	}
+	if !strings.HasPrefix(p.Message, "upload media failed: ") || !strings.Contains(p.Message, "upload rejected") {
+		t.Fatalf("message = %q, want action prefix and server msg", p.Message)
+	}
+}
+
+func TestUploadDriveMediaAllTypedFileOpenFailure(t *testing.T) {
+	runtime, _ := newDriveMediaUploadTestRuntime(t)
+	withDriveMediaUploadWorkingDir(t, t.TempDir())
+
+	_, err := UploadDriveMediaAllTyped(runtime, DriveMediaUploadAllConfig{
+		FilePath:   "missing.bin",
+		FileName:   "missing.bin",
+		FileSize:   1,
+		ParentType: "docx_image",
+		ParentNode: strPtr("blk_parent"),
+	})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected typed validation error, got %T (%v)", err, err)
+	}
+}
+
+func TestUploadDriveMediaMultipartTypedBuildsPreparePartsAndFinish(t *testing.T) {
+	runtime, reg := newDriveMediaUploadTestRuntime(t)
+	withDriveMediaUploadWorkingDir(t, t.TempDir())
+
+	size := MaxDriveMediaUploadSinglePartSize + 1
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_prepare",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"upload_id":  "upload_typed_1",
+				"block_size": float64(4 * 1024 * 1024),
+				"block_num":  float64(6),
+			},
+		},
+	})
+	for i := 0; i < 6; i++ {
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/medias/upload_part",
+			Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+		})
+	}
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_finish",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"file_token": "file_typed_multi"},
+		},
+	})
+
+	payload := bytes.Repeat([]byte{0xCD}, int(size))
+	fileToken, err := UploadDriveMediaMultipartTyped(runtime, DriveMediaMultipartUploadConfig{
+		Reader:     bytes.NewReader(payload),
+		FileName:   "clipboard.png",
+		FileSize:   size,
+		ParentType: "docx_image",
+		ParentNode: "",
+	})
+	if err != nil {
+		t.Fatalf("UploadDriveMediaMultipartTyped() error: %v", err)
+	}
+	if fileToken != "file_typed_multi" {
+		t.Fatalf("fileToken = %q, want %q", fileToken, "file_typed_multi")
+	}
+}
+
+func TestParseDriveMediaMultipartUploadSessionTypedValidatesResponseFields(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		data     map[string]interface{}
+		wantText string
+	}{
+		{
+			name: "missing upload id",
+			data: map[string]interface{}{
+				"block_size": 4 * 1024 * 1024,
+				"block_num":  6,
+			},
+			wantText: "upload prepare failed: no upload_id returned",
+		},
+		{
+			name: "missing block size",
+			data: map[string]interface{}{
+				"upload_id": "upload_123",
+				"block_num": 6,
+			},
+			wantText: "upload prepare failed: invalid block_size returned",
+		},
+		{
+			name: "missing block num",
+			data: map[string]interface{}{
+				"upload_id":  "upload_123",
+				"block_size": 4 * 1024 * 1024,
+			},
+			wantText: "upload prepare failed: invalid block_num returned",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := parseDriveMediaMultipartUploadSessionTyped(tt.data)
+			if err == nil || !strings.Contains(err.Error(), tt.wantText) {
+				t.Fatalf("err = %v, want substring %q", err, tt.wantText)
+			}
+			p, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed problem, got %T (%v)", err, err)
+			}
+			if p.Subtype != errs.SubtypeInvalidResponse {
+				t.Fatalf("subtype = %s, want invalid_response", p.Subtype)
+			}
+		})
+	}
+}
+
+func TestUploadDriveMediaMultipartTypedPartAPIFailure(t *testing.T) {
+	runtime, reg := newDriveMediaUploadTestRuntime(t)
+	withDriveMediaUploadWorkingDir(t, t.TempDir())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_prepare",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"upload_id":  "upload_123",
+				"block_size": float64(4 * 1024 * 1024),
+				"block_num":  float64(6),
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_part",
+		Body: map[string]interface{}{
+			"code": 999,
+			"msg":  "chunk rejected",
+		},
+	})
+
+	filePath := writeDriveMediaUploadSizedFile(t, "large.bin", MaxDriveMediaUploadSinglePartSize+1)
+	_, err := UploadDriveMediaMultipartTyped(runtime, DriveMediaMultipartUploadConfig{
+		FilePath:   filePath,
+		FileName:   "large.bin",
+		FileSize:   MaxDriveMediaUploadSinglePartSize + 1,
+		ParentType: "ccm_import_open",
+		ParentNode: "",
+	})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T (%v)", err, err)
+	}
+	if p.Category != errs.CategoryAPI || p.Code != 999 {
+		t.Fatalf("category/code = %s/%d, want api/999", p.Category, p.Code)
+	}
+	if !strings.HasPrefix(p.Message, "upload media part failed: ") || !strings.Contains(p.Message, "chunk rejected") {
+		t.Fatalf("message = %q, want action prefix and server msg", p.Message)
+	}
+}
+
+func TestUploadDriveMediaMultipartTypedFinishRequiresFileToken(t *testing.T) {
+	runtime, reg := newDriveMediaUploadTestRuntime(t)
+	withDriveMediaUploadWorkingDir(t, t.TempDir())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_prepare",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"upload_id":  "upload_123",
+				"block_size": float64(4 * 1024 * 1024),
+				"block_num":  float64(6),
+			},
+		},
+	})
+	for i := 0; i < 6; i++ {
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/medias/upload_part",
+			Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+		})
+	}
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_finish",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{},
+		},
+	})
+
+	filePath := writeDriveMediaUploadSizedFile(t, "large.bin", MaxDriveMediaUploadSinglePartSize+1)
+	_, err := UploadDriveMediaMultipartTyped(runtime, DriveMediaMultipartUploadConfig{
+		FilePath:   filePath,
+		FileName:   "large.bin",
+		FileSize:   MaxDriveMediaUploadSinglePartSize + 1,
+		ParentType: "ccm_import_open",
+		ParentNode: "",
+	})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T (%v)", err, err)
+	}
+	if p.Subtype != errs.SubtypeInvalidResponse {
+		t.Fatalf("subtype = %s, want invalid_response", p.Subtype)
+	}
+	if !strings.Contains(p.Message, "upload media finish failed: no file_token returned") {
+		t.Fatalf("message = %q", p.Message)
+	}
+}

shortcuts/common/runner.go

@@ -492,6 +492,28 @@ func (ctx *RuntimeContext) DoAPIJSONWithLogID(method, apiPath string, query lark
 	return ctx.doAPIJSON(method, apiPath, query, body, true)
 }
 
+// DoAPIJSONTyped is the typed-only replacement for DoAPIJSON: it issues the same
+// larkcore.ApiReq request (identical method / path / query / body model) but
+// classifies failures into typed errs.* errors via ClassifyAPIResponse instead
+// of emitting a legacy output.ExitError "api_error" envelope. A transport / auth
+// error from the client boundary is already typed and passes through unchanged;
+// a non-zero API code is classified with subtype / code / log_id.
+func (ctx *RuntimeContext) DoAPIJSONTyped(method, apiPath string, query larkcore.QueryParams, body any) (map[string]any, error) {
+	req := &larkcore.ApiReq{
+		HttpMethod:  method,
+		ApiPath:     apiPath,
+		QueryParams: query,
+	}
+	if body != nil {
+		req.Body = body
+	}
+	resp, err := ctx.DoAPI(req)
+	if err != nil {
+		return nil, typedOrInternal(err)
+	}
+	return ctx.ClassifyAPIResponse(resp)
+}
+
 func (ctx *RuntimeContext) doAPIJSON(method, apiPath string, query larkcore.QueryParams, body any, includeLogID bool) (map[string]any, error) {
 	req := &larkcore.ApiReq{
 		HttpMethod:  method,
@@ -603,27 +625,6 @@ func (ctx *RuntimeContext) ResolveSavePath(path string) (string, error) {
 	return resolved, nil
 }
 
-// WrapSaveError matches a FileIO.Save error against known categories and wraps
-// it with the caller-provided message prefix, preserving backward-compatible
-// error text per shortcut.
-func WrapSaveError(err error, pathMsg, mkdirMsg, writeMsg string) error {
-	if err == nil {
-		return nil
-	}
-	var me *fileio.MkdirError
-	var we *fileio.WriteError
-	switch {
-	case errors.Is(err, fileio.ErrPathValidation):
-		return fmt.Errorf("%s: %w", pathMsg, err)
-	case errors.As(err, &me):
-		return fmt.Errorf("%s: %w", mkdirMsg, err)
-	case errors.As(err, &we):
-		return fmt.Errorf("%s: %w", writeMsg, err)
-	default:
-		return fmt.Errorf("%s: %w", writeMsg, err)
-	}
-}
-
 // WrapOpenError matches a FileIO.Open/Stat error and wraps it with the
 // caller-provided message prefix.
 func WrapOpenError(err error, pathMsg, readMsg string) error {
@@ -703,6 +704,9 @@ func WrapSaveErrorTyped(err error) error {
 	if err == nil {
 		return nil
 	}
+	if _, ok := errs.ProblemOf(err); ok {
+		return err
+	}
 	var me *fileio.MkdirError
 	switch {
 	case errors.Is(err, fileio.ErrPathValidation):

shortcuts/common/validate.go

@@ -4,7 +4,6 @@
 package common
 
 import (
-	"fmt"
 	"strconv"
 	"strings"
 
@@ -177,25 +176,6 @@ func ValidateSafePathTyped(fio fileio.FileIO, path string) error {
 	return nil
 }
 
-// RejectDangerousChars returns an error if value contains ASCII control
-// characters or dangerous Unicode code points.
-//
-// Deprecated: use RejectDangerousCharsTyped for typed error envelopes.
-func RejectDangerousChars(paramName, value string) error {
-	for _, r := range value {
-		if r < 0x20 && r != '\t' && r != '\n' {
-			return fmt.Errorf("parameter %q contains control character U+%04X", paramName, r)
-		}
-		if r == 0x7F {
-			return fmt.Errorf("parameter %q contains DEL character", paramName)
-		}
-		if IsDangerousUnicode(r) {
-			return fmt.Errorf("parameter %q contains dangerous Unicode character U+%04X", paramName, r)
-		}
-	}
-	return nil
-}
-
 // RejectDangerousCharsTyped returns an error if value contains ASCII control
 // characters or dangerous Unicode code points.
 func RejectDangerousCharsTyped(paramName, value string) error {

shortcuts/common/validate_ids.go

@@ -9,18 +9,6 @@ import (
 	"github.com/larksuite/cli/internal/output"
 )
 
-// ValidateChatID checks if a chat ID has valid format (oc_ prefix).
-// Also extracts token from URL if provided.
-//
-// Deprecated: use ValidateChatIDTyped for typed error envelopes.
-func ValidateChatID(input string) (string, error) {
-	chatID, msg := normalizeChatID(input)
-	if msg != "" {
-		return "", output.ErrValidation("%s", msg)
-	}
-	return chatID, nil
-}
-
 // ValidateChatIDTyped checks if a chat ID has valid format (oc_ prefix).
 // Also extracts token from URL if provided. param names the flag being
 // validated (e.g. "--chat-ids") and is recorded on the typed error.

shortcuts/common/validate_test.go

@@ -194,6 +194,21 @@ func TestWrapSaveErrorTyped_ClassifiesPathAndFileIO(t *testing.T) {
 	}
 }
 
+func TestWrapSaveErrorTyped_PreservesTypedWriteCause(t *testing.T) {
+	typed := errs.NewNetworkError(errs.SubtypeNetworkServer, "HTTP 500: chunk failed").
+		WithCode(500)
+	err := WrapSaveErrorTyped(&fileio.WriteError{Err: typed})
+
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryNetwork || p.Subtype != errs.SubtypeNetworkServer || p.Code != 500 {
+		t.Fatalf("problem = category %q subtype %q code %d, want network/%s/500",
+			p.Category, p.Subtype, p.Code, errs.SubtypeNetworkServer)
+	}
+}
+
 func TestAtLeastOne(t *testing.T) {
 	tests := []struct {
 		name    string

shortcuts/drive/drive_cover.go

@@ -0,0 +1,122 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var DriveCover = common.Shortcut{
+	Service:     "drive",
+	Command:     "+cover",
+	Description: "List or download stable cover presets for a Drive file",
+	Risk:        "read",
+	Scopes:      []string{"drive:file:download"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "file-token", Desc: "Drive file token", Required: true},
+		{Name: "spec", Desc: "cover preset: default | icon | grid | small | middle | big | square"},
+		{Name: "version", Desc: "optional file version"},
+		{Name: "list-only", Type: "bool", Desc: "list built-in cover specs without downloading"},
+		{Name: "output", Desc: "local output path for downloaded cover"},
+		{Name: "if-exists", Desc: "output conflict policy: error | overwrite | rename", Default: drivePreviewIfExistsError, Enum: []string{drivePreviewIfExistsError, drivePreviewIfExistsOverwrite, drivePreviewIfExistsRename}},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := validate.ResourceName(runtime.Str("file-token"), "--file-token"); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--file-token")
+		}
+		if err := validateDrivePreviewMode(runtime.Str("spec"), runtime.Bool("list-only"), runtime.Str("output"), "spec"); err != nil {
+			return err
+		}
+		if err := validateDrivePreviewIfExists(runtime.Str("if-exists")); err != nil {
+			return err
+		}
+		if spec := strings.TrimSpace(runtime.Str("spec")); spec != "" {
+			if _, ok := findDriveCoverSpec(spec); !ok {
+				return wrapDriveCoverUnavailable(spec)
+			}
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		fileToken := runtime.Str("file-token")
+		if runtime.Bool("list-only") {
+			return common.NewDryRunAPI().
+				Desc("List built-in cover specs (no API call)").
+				Set("mode", "list").
+				Set("file_token", fileToken).
+				Set("candidates", buildDriveCoverListOutput(fileToken)["candidates"])
+		}
+
+		spec, _ := findDriveCoverSpec(runtime.Str("spec"))
+		params := buildDriveCoverDownloadParams(strings.TrimSpace(runtime.Str("version")), spec)
+		dry := common.NewDryRunAPI().
+			GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+			Desc("Download selected cover preset directly via preview_download").
+			Params(params).
+			Set("file_token", fileToken).
+			Set("selected_spec", spec.Name).
+			Set("output", runtime.Str("output"))
+		return dry
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		fileToken := runtime.Str("file-token")
+		version := strings.TrimSpace(runtime.Str("version"))
+		requestedSpec := strings.TrimSpace(runtime.Str("spec"))
+		outputPath := runtime.Str("output")
+		ifExists := runtime.Str("if-exists")
+
+		if runtime.Bool("list-only") {
+			runtime.Out(buildDriveCoverListOutput(fileToken), nil)
+			return nil
+		}
+
+		spec, ok := findDriveCoverSpec(requestedSpec)
+		if !ok {
+			return wrapDriveCoverUnavailable(requestedSpec)
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Downloading cover %s for file %s\n", spec.Name, common.MaskToken(fileToken))
+		result, err := downloadDrivePreviewArtifactWithParams(ctx, runtime, fileToken, buildDriveCoverDownloadParams(version, spec), outputPath, ifExists, spec.FallbackExt)
+		if err != nil {
+			return wrapDriveCoverDownloadError(err, spec.Name)
+		}
+		result["mode"] = "download"
+		result["file_token"] = fileToken
+		result["selected_spec"] = spec.Name
+		runtime.Out(result, nil)
+		return nil
+	},
+}
+
+// wrapDriveCoverDownloadError reclassifies preview_download HTTP 404 responses
+// on the +cover path as a failed precondition on --spec, because the Drive
+// shortcut contract documents 404 as "this file has no artifact for that cover
+// preset" rather than a transient transport failure.
+func wrapDriveCoverDownloadError(err error, requestedSpec string) error {
+	if err == nil {
+		return nil
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Code != http.StatusNotFound {
+		return err
+	}
+	hint := fmt.Sprintf(
+		"This may mean no artifact exists for --spec %q, or that the file token/version is invalid. Verify the inputs, or rerun with `lark-cli drive +cover --file-token <file-token> --list-only`. Available cover specs: %s",
+		requestedSpec,
+		strings.Join(availableDriveCoverSpecs(), ", "),
+	)
+	return errs.NewValidationError(
+		errs.SubtypeFailedPrecondition,
+		"preview_download returned HTTP 404 for --spec %q",
+		requestedSpec,
+	).WithParam("--spec").WithCode(problem.Code).WithLogID(problem.LogID).WithHint(hint).WithCause(err)
+}

shortcuts/drive/drive_preview.go

@@ -0,0 +1,118 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var DrivePreview = common.Shortcut{
+	Service:     "drive",
+	Command:     "+preview",
+	Description: "List or download available preview artifacts for a Drive file",
+	Risk:        "read",
+	Scopes:      []string{"drive:file:download"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "file-token", Desc: "Drive file token", Required: true},
+		{Name: "type", Desc: "preview type to download: pdf | html | text | image | source"},
+		{Name: "version", Desc: "optional file version"},
+		{Name: "list-only", Type: "bool", Desc: "list preview candidates without downloading"},
+		{Name: "output", Desc: "local output path for downloaded preview"},
+		{Name: "if-exists", Desc: "output conflict policy: error | overwrite | rename", Default: drivePreviewIfExistsError, Enum: []string{drivePreviewIfExistsError, drivePreviewIfExistsOverwrite, drivePreviewIfExistsRename}},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := validate.ResourceName(runtime.Str("file-token"), "--file-token"); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--file-token")
+		}
+		if err := validateDrivePreviewMode(runtime.Str("type"), runtime.Bool("list-only"), runtime.Str("output"), "type"); err != nil {
+			return err
+		}
+		return validateDrivePreviewIfExists(runtime.Str("if-exists"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		fileToken := runtime.Str("file-token")
+		version := strings.TrimSpace(runtime.Str("version"))
+		body := map[string]interface{}{}
+		if version != "" {
+			body["version"] = version
+		}
+		dry := common.NewDryRunAPI().
+			POST("/open-apis/drive/v1/medias/:file_token/preview_result").
+			Desc("[1] Fetch preview candidates for a Drive file").
+			Set("file_token", fileToken)
+		if len(body) > 0 {
+			dry.Body(body)
+		}
+		if runtime.Bool("list-only") {
+			return dry.Set("mode", "list")
+		}
+		downloadParams := map[string]interface{}{
+			"preview_type": "<selected type_code from preview_result>",
+		}
+		if version != "" {
+			downloadParams["version"] = version
+		} else {
+			downloadParams["version"] = "<resolved version from preview_result>"
+		}
+		return dry.
+			GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+			Desc("[2] Download the requested preview after selecting a matching candidate from preview_result").
+			Params(downloadParams).
+			Set("mode", "download").
+			Set("requested_type", runtime.Str("type")).
+			Set("output", runtime.Str("output"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		fileToken := runtime.Str("file-token")
+		version := strings.TrimSpace(runtime.Str("version"))
+		requestedType := strings.TrimSpace(runtime.Str("type"))
+		outputPath := runtime.Str("output")
+		ifExists := runtime.Str("if-exists")
+
+		body := map[string]interface{}{}
+		if version != "" {
+			body["version"] = version
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Fetching preview candidates: %s\n", common.MaskToken(fileToken))
+		data, candidates, err := fetchDrivePreviewCandidates(runtime, fileToken, body)
+		if err != nil {
+			return err
+		}
+		if runtime.Bool("list-only") {
+			runtime.Out(buildDrivePreviewListOutput(fileToken, candidates), nil)
+			return nil
+		}
+
+		candidate, ok := selectDrivePreviewCandidate(candidates, requestedType)
+		if !ok {
+			return wrapDrivePreviewUnavailable(fileToken, requestedType, candidates, "")
+		}
+		if !candidate.Downloadable {
+			return wrapDrivePreviewNotReady(fileToken, requestedType, candidate)
+		}
+
+		downloadVersion := version
+		if downloadVersion == "" {
+			downloadVersion = versionString(data["version"])
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "Downloading preview %s for file %s\n", candidate.Type, common.MaskToken(fileToken))
+		result, err := downloadDrivePreviewArtifact(ctx, runtime, fileToken, candidate.TypeCode, downloadVersion, outputPath, ifExists, drivePreviewFallbackExt(candidate.Type))
+		if err != nil {
+			return err
+		}
+		result["mode"] = "download"
+		result["file_token"] = fileToken
+		result["selected_type"] = candidate.Type
+		runtime.Out(result, nil)
+		return nil
+	},
+}

shortcuts/drive/drive_preview_common.go

@@ -0,0 +1,813 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io/fs"
+	"mime"
+	"net/http"
+	"path/filepath"
+	"slices"
+	"strconv"
+	"strings"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	drivePreviewIfExistsError     = "error"
+	drivePreviewIfExistsOverwrite = "overwrite"
+	drivePreviewIfExistsRename    = "rename"
+)
+
+type drivePreviewCandidate struct {
+	Type         string
+	TypeCode     string
+	TypeName     string
+	Label        string
+	Status       string
+	StatusCode   string
+	Downloadable bool
+	Reason       string
+}
+
+type driveCoverSpec struct {
+	Name        string
+	Label       string
+	Description string
+	PreviewType string
+	BusType     string
+	Platform    string
+	Width       int
+	Height      int
+	Policy      string
+	FallbackExt string
+}
+
+type driveExtensionResolution struct {
+	Ext    string
+	Source string
+	Detail string
+}
+
+type drivePreviewTypeMeta struct {
+	Code    string
+	Name    string
+	Type    string
+	Label   string
+	Aliases []string
+}
+
+type drivePreviewStatusMeta struct {
+	Code         string
+	Name         string
+	Reason       string
+	Downloadable bool
+}
+
+var drivePreviewMimeToExt = map[string]string{
+	"application/json":         ".json",
+	"application/msword":       ".doc",
+	"application/pdf":          ".pdf",
+	"application/xml":          ".xml",
+	"application/zip":          ".zip",
+	"image/bmp":                ".bmp",
+	"image/gif":                ".gif",
+	"image/jpeg":               ".jpg",
+	"image/png":                ".png",
+	"image/svg+xml":            ".svg",
+	"image/webp":               ".webp",
+	"text/csv":                 ".csv",
+	"text/html":                ".html",
+	"text/plain":               ".txt",
+	"text/xml":                 ".xml",
+	"video/mp4":                ".mp4",
+	"application/octet-stream": "",
+}
+
+var drivePreviewTypes = []drivePreviewTypeMeta{
+	{Code: "0", Name: "PDF", Type: "pdf", Label: "PDF Preview"},
+	{Code: "1", Name: "PNG", Type: "png", Label: "PNG Preview", Aliases: []string{"image"}},
+	{Code: "2", Name: "PAGES", Type: "pages", Label: "Paged Preview"},
+	{Code: "3", Name: "VIDEO", Type: "video", Label: "Video Preview"},
+	{Code: "4", Name: "MP4_360P", Type: "mp4_360p", Label: "MP4 360P Preview"},
+	{Code: "5", Name: "MP4_480P", Type: "mp4_480p", Label: "MP4 480P Preview"},
+	{Code: "6", Name: "MP4_720P", Type: "mp4_720p", Label: "MP4 720P Preview"},
+	{Code: "7", Name: "JPG", Type: "jpg", Label: "JPG Preview", Aliases: []string{"image"}},
+	{Code: "8", Name: "HTML", Type: "html", Label: "HTML Preview"},
+	{Code: "9", Name: "PDF_LIN", Type: "pdf_lin", Label: "Linearized PDF Preview"},
+	{Code: "10", Name: "XOD", Type: "xod", Label: "XOD Preview"},
+	{Code: "11", Name: "JPG_LIN", Type: "jpg_lin", Label: "Linearized JPG Preview", Aliases: []string{"image"}},
+	{Code: "12", Name: "PNG_LIN", Type: "png_lin", Label: "Linearized PNG Preview", Aliases: []string{"image"}},
+	{Code: "13", Name: "ARCHIVE", Type: "archive", Label: "Archive Preview"},
+	{Code: "14", Name: "TEXT", Type: "text", Label: "Text Preview"},
+	{Code: "15", Name: "PDF_PART", Type: "pdf_part", Label: "Partial PDF Preview"},
+	{Code: "16", Name: "SOURCE_FILE", Type: "source_file", Label: "Source File", Aliases: []string{"source"}},
+	{Code: "17", Name: "VIDEO_META", Type: "video_meta", Label: "Video Metadata"},
+	{Code: "18", Name: "WPS", Type: "wps", Label: "WPS Preview"},
+	{Code: "19", Name: "SPLIT_PNG", Type: "split_png", Label: "Split PNG Preview", Aliases: []string{"image"}},
+	{Code: "20", Name: "MEDIA_RESULT", Type: "media_result", Label: "Media Result"},
+	{Code: "21", Name: "MIME", Type: "mime", Label: "MIME Type"},
+	{Code: "22", Name: "SPILT_IMG_TXT", Type: "spilt_img_txt", Label: "Split Image Text"},
+	{Code: "23", Name: "MP4_1080P", Type: "mp4_1080p", Label: "MP4 1080P Preview"},
+	{Code: "24", Name: "IMAGE_META", Type: "image_meta", Label: "Image Metadata"},
+	{Code: "25", Name: "DOC_PART", Type: "doc_part", Label: "Document Part"},
+	{Code: "26", Name: "WATERMARK_PDF", Type: "watermark_pdf", Label: "Watermarked PDF Preview"},
+	{Code: "27", Name: "FILE_WATERMARK", Type: "file_watermark", Label: "File Watermark"},
+}
+
+var drivePreviewStatuses = []drivePreviewStatusMeta{
+	{Code: "0", Name: "READY", Downloadable: true},
+	{Code: "1", Name: "PROCESSING", Reason: "Preview is still processing."},
+	{Code: "2", Name: "FAILED", Reason: "Preview generation failed."},
+	{Code: "3", Name: "FAILED_NOT_RETRY", Reason: "Preview generation failed and will not retry."},
+	{Code: "4", Name: "INVALID_EXTENTION", Reason: "File extension is invalid for this preview type."},
+	{Code: "5", Name: "FILE_TOO_LARGE", Reason: "File is too large for preview generation."},
+	{Code: "6", Name: "EMPTY_FILE", Reason: "File is empty."},
+	{Code: "7", Name: "NO_SUPPORT", Reason: "Preview is not supported for this file."},
+	{Code: "8", Name: "INVALID_PREVIEW_TYPE", Reason: "Preview type is invalid."},
+	{Code: "9", Name: "NEED_PASSWORD", Reason: "Preview requires a password."},
+	{Code: "10", Name: "FILE_INVALID", Reason: "File is invalid."},
+	{Code: "11", Name: "TOO_MANY_PAGES", Reason: "File has too many pages for preview."},
+	{Code: "1001", Name: "ARCHIVE_INVALID_FORMAT", Reason: "Archive format is invalid."},
+	{Code: "1002", Name: "ARCHIVE_TOO_MANY_NODES", Reason: "Archive contains too many nodes."},
+	{Code: "1003", Name: "ARCHIVE_TOO_MANY_NODES_PER_DIR", Reason: "Archive directory contains too many nodes."},
+	{Code: "1004", Name: "THIRD_ENC_NO_PERMISSION", Reason: "No permission for third-party encrypted file."},
+	{Code: "1006", Name: "NOT_SUPPORT_DECRYPT_THIRD_ENC_FILE", Reason: "Third-party encrypted file cannot be decrypted for preview."},
+}
+
+var drivePreviewTypeByCode = func() map[string]drivePreviewTypeMeta {
+	out := make(map[string]drivePreviewTypeMeta, len(drivePreviewTypes))
+	for _, meta := range drivePreviewTypes {
+		out[meta.Code] = meta
+	}
+	return out
+}()
+
+var drivePreviewStatusByCode = func() map[string]drivePreviewStatusMeta {
+	out := make(map[string]drivePreviewStatusMeta, len(drivePreviewStatuses))
+	for _, meta := range drivePreviewStatuses {
+		out[meta.Code] = meta
+	}
+	return out
+}()
+
+var driveCoverSpecs = []driveCoverSpec{
+	{
+		Name:        "default",
+		Label:       "Default Cover",
+		Description: "Standard large cover (1280x1280).",
+		PreviewType: "1",
+		BusType:     "cover",
+		Platform:    "pc",
+		FallbackExt: ".png",
+	},
+	{
+		Name:        "icon",
+		Label:       "Icon",
+		Description: "Small list icon (120x120).",
+		PreviewType: "1",
+		BusType:     "icon",
+		FallbackExt: ".png",
+	},
+	{
+		Name:        "grid",
+		Label:       "Grid Cover",
+		Description: "Grid/card stream cover (360x360).",
+		PreviewType: "1",
+		BusType:     "grid",
+		FallbackExt: ".png",
+	},
+	{
+		Name:        "small",
+		Label:       "Small Graph",
+		Description: "PC small graph cover (480x480).",
+		PreviewType: "1",
+		BusType:     "small_graph",
+		Platform:    "pc",
+		FallbackExt: ".png",
+	},
+	{
+		Name:        "middle",
+		Label:       "Middle Cover",
+		Description: "Medium-sized cover (720x720).",
+		PreviewType: "1",
+		BusType:     "middle",
+		FallbackExt: ".png",
+	},
+	{
+		Name:        "big",
+		Label:       "Big Cover",
+		Description: "Large mobile-oriented cover (850x850).",
+		PreviewType: "1",
+		BusType:     "big",
+		Platform:    "mobile",
+		FallbackExt: ".png",
+	},
+	{
+		Name:        "square",
+		Label:       "Square Cover",
+		Description: "Square-cropped grid cover (360x360).",
+		PreviewType: "1",
+		Width:       360,
+		Height:      360,
+		Policy:      "near",
+		FallbackExt: ".png",
+	},
+}
+
+// validateDrivePreviewMode checks the required flag combinations for list and
+// download modes.
+func validateDrivePreviewMode(selected string, listOnly bool, outputPath, flagName string) error {
+	selected = strings.TrimSpace(selected)
+	outputPath = strings.TrimSpace(outputPath)
+	selectedFlag := "--" + flagName
+	if listOnly {
+		if selected != "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s cannot be combined with --list-only", selectedFlag).WithParam(selectedFlag)
+		}
+		if outputPath != "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output cannot be combined with --list-only").WithParam("--output")
+		}
+		return nil
+	}
+	if selected == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "either --list-only or %s is required", selectedFlag).WithParam(selectedFlag)
+	}
+	if outputPath == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output is required when %s is set", selectedFlag).WithParam("--output")
+	}
+	return nil
+}
+
+// validateDrivePreviewIfExists validates the accepted overwrite policy values.
+func validateDrivePreviewIfExists(policy string) error {
+	switch strings.TrimSpace(policy) {
+	case "", drivePreviewIfExistsError, drivePreviewIfExistsOverwrite, drivePreviewIfExistsRename:
+		return nil
+	default:
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --if-exists %q: allowed values are error, overwrite, rename", policy).WithParam("--if-exists")
+	}
+}
+
+// fetchDrivePreviewCandidates loads preview_result data and normalizes the
+// returned candidate list.
+func fetchDrivePreviewCandidates(runtime *common.RuntimeContext, fileToken string, body map[string]interface{}) (map[string]interface{}, []drivePreviewCandidate, error) {
+	data, err := runtime.CallAPITyped(
+		"POST",
+		fmt.Sprintf("/open-apis/drive/v1/medias/%s/preview_result", validate.EncodePathSegment(fileToken)),
+		nil,
+		body,
+	)
+	if err != nil {
+		return nil, nil, err
+	}
+	return data, normalizeDrivePreviewCandidates(data), nil
+}
+
+// normalizeDrivePreviewCandidates converts preview_result items into internal
+// candidate records with stable type and status metadata.
+func normalizeDrivePreviewCandidates(data map[string]interface{}) []drivePreviewCandidate {
+	items := common.GetSlice(data, "preview_results")
+	candidates := make([]drivePreviewCandidate, 0, len(items))
+	for _, item := range items {
+		raw, ok := item.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		typeCode := firstString(raw, "preview_type", "type_code", "type")
+		statusCode := firstString(raw, "preview_status", "status_code", "status")
+		candidate := drivePreviewCandidate{
+			TypeCode:   typeCode,
+			StatusCode: statusCode,
+			Reason:     strings.TrimSpace(firstString(raw, "reason", "status_msg", "message", "msg", "detail")),
+		}
+		applyDrivePreviewTypeMeta(&candidate)
+		applyDrivePreviewStatusMeta(&candidate)
+		candidates = append(candidates, candidate)
+	}
+	return candidates
+}
+
+// selectDrivePreviewCandidate matches a requested preview type or alias against
+// the available candidates.
+func selectDrivePreviewCandidate(candidates []drivePreviewCandidate, requested string) (drivePreviewCandidate, bool) {
+	requested = normalizeDrivePreviewRequest(requested)
+	if requested == "" {
+		return drivePreviewCandidate{}, false
+	}
+
+	for _, candidate := range candidates {
+		if requested == candidate.Type || requested == strings.ToLower(candidate.TypeName) || requested == strings.ToLower(strings.TrimSpace(candidate.TypeCode)) {
+			return candidate, true
+		}
+	}
+
+	var firstAliasMatch drivePreviewCandidate
+	hasAliasMatch := false
+	for _, candidate := range candidates {
+		if !slices.Contains(previewAliasesForCandidate(candidate), requested) {
+			continue
+		}
+		if candidate.Downloadable {
+			return candidate, true
+		}
+		if !hasAliasMatch {
+			firstAliasMatch = candidate
+			hasAliasMatch = true
+		}
+	}
+	if hasAliasMatch {
+		return firstAliasMatch, true
+	}
+	return drivePreviewCandidate{}, false
+}
+
+// buildDrivePreviewListOutput formats preview candidates for --list-only
+// responses.
+func buildDrivePreviewListOutput(fileToken string, candidates []drivePreviewCandidate) map[string]interface{} {
+	items := make([]map[string]interface{}, 0, len(candidates))
+	for _, candidate := range candidates {
+		item := map[string]interface{}{
+			"type":         candidate.Type,
+			"type_code":    candidate.TypeCode,
+			"label":        candidate.Label,
+			"status":       candidate.Status,
+			"status_code":  candidate.StatusCode,
+			"downloadable": candidate.Downloadable,
+		}
+		if candidate.Reason != "" {
+			item["reason"] = candidate.Reason
+		}
+		items = append(items, item)
+	}
+	out := map[string]interface{}{
+		"mode":       "list",
+		"file_token": fileToken,
+		"candidates": items,
+	}
+	if len(items) > 0 {
+		out["next_action"] = "select one candidate and rerun with --type plus --output"
+	}
+	return out
+}
+
+// buildDriveCoverListOutput formats the built-in cover specs for --list-only
+// responses.
+func buildDriveCoverListOutput(fileToken string) map[string]interface{} {
+	items := make([]map[string]interface{}, 0, len(driveCoverSpecs))
+	for _, spec := range driveCoverSpecs {
+		item := map[string]interface{}{
+			"spec":  spec.Name,
+			"label": spec.Label,
+		}
+		if spec.Description != "" {
+			item["description"] = spec.Description
+		}
+		items = append(items, item)
+	}
+	return map[string]interface{}{
+		"mode":        "list",
+		"file_token":  fileToken,
+		"candidates":  items,
+		"next_action": "select one spec and rerun with --spec plus --output",
+	}
+}
+
+// findDriveCoverSpec resolves a cover spec by its user-facing name.
+func findDriveCoverSpec(name string) (driveCoverSpec, bool) {
+	name = strings.ToLower(strings.TrimSpace(name))
+	for _, spec := range driveCoverSpecs {
+		if spec.Name == name {
+			return spec, true
+		}
+	}
+	return driveCoverSpec{}, false
+}
+
+// buildDriveCoverDownloadParams translates a cover spec into preview_download
+// query parameters.
+func buildDriveCoverDownloadParams(version string, spec driveCoverSpec) map[string]interface{} {
+	params := map[string]interface{}{
+		"preview_type": spec.PreviewType,
+	}
+	if strings.TrimSpace(spec.BusType) != "" {
+		params["bus_type"] = spec.BusType
+	}
+	if strings.TrimSpace(spec.Platform) != "" {
+		params["platform"] = spec.Platform
+	}
+	if spec.Width > 0 {
+		params["width"] = spec.Width
+	}
+	if spec.Height > 0 {
+		params["height"] = spec.Height
+	}
+	if strings.TrimSpace(spec.Policy) != "" {
+		params["policy"] = spec.Policy
+	}
+	if strings.TrimSpace(version) != "" {
+		params["version"] = version
+	}
+	return params
+}
+
+// downloadDrivePreviewArtifact downloads a preview artifact for a single
+// preview_type value.
+func downloadDrivePreviewArtifact(ctx context.Context, runtime *common.RuntimeContext, fileToken, previewType, version, outputPath, ifExists, fallbackExt string) (map[string]interface{}, error) {
+	query := map[string]interface{}{
+		"preview_type": previewType,
+	}
+	if strings.TrimSpace(version) != "" {
+		query["version"] = version
+	}
+	return downloadDrivePreviewArtifactWithParams(ctx, runtime, fileToken, query, outputPath, ifExists, fallbackExt)
+}
+
+// downloadDrivePreviewArtifactWithParams downloads a preview artifact using the
+// provided preview_download query parameters and writes it to the local path.
+func downloadDrivePreviewArtifactWithParams(ctx context.Context, runtime *common.RuntimeContext, fileToken string, query map[string]interface{}, outputPath, ifExists, fallbackExt string) (map[string]interface{}, error) {
+	if err := validate.ResourceName(fileToken, "--file-token"); err != nil {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--file-token")
+	}
+	if _, err := runtime.ResolveSavePath(outputPath); err != nil {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output")
+	}
+
+	queryParams := make(larkcore.QueryParams, len(query))
+	for key, value := range query {
+		text := strings.TrimSpace(fmt.Sprint(value))
+		if text == "" {
+			continue
+		}
+		queryParams[key] = []string{text}
+	}
+
+	apiReq := &larkcore.ApiReq{
+		HttpMethod:  http.MethodGet,
+		ApiPath:     fmt.Sprintf("/open-apis/drive/v1/medias/%s/preview_download", validate.EncodePathSegment(fileToken)),
+		QueryParams: queryParams,
+	}
+
+	resp, err := runtime.DoAPIStream(ctx, apiReq)
+	if err != nil {
+		return nil, wrapDriveNetworkErr(err, "preview download failed: %s", err)
+	}
+	defer resp.Body.Close()
+
+	finalPath, _, err := resolveDrivePreviewOutputPath(runtime, outputPath, resp.Header, fallbackExt, ifExists)
+	if err != nil {
+		return nil, err
+	}
+
+	result, err := runtime.FileIO().Save(finalPath, fileio.SaveOptions{
+		ContentType:   resp.Header.Get("Content-Type"),
+		ContentLength: resp.ContentLength,
+	}, resp.Body)
+	if err != nil {
+		return nil, driveSaveError(err)
+	}
+
+	savedPath, _ := runtime.ResolveSavePath(finalPath)
+	if savedPath == "" {
+		savedPath = finalPath
+	}
+
+	return map[string]interface{}{
+		"output_path":  savedPath,
+		"size_bytes":   result.Size(),
+		"content_type": resp.Header.Get("Content-Type"),
+		"status":       "READY",
+	}, nil
+}
+
+// resolveDrivePreviewOutputPath finalizes the save path, applying extension
+// inference and the selected collision policy.
+func resolveDrivePreviewOutputPath(runtime *common.RuntimeContext, outputPath string, header http.Header, fallbackExt, ifExists string) (string, *driveExtensionResolution, error) {
+	finalPath, resolution := autoAppendDrivePreviewExtension(outputPath, header, fallbackExt)
+	if _, err := runtime.ResolveSavePath(finalPath); err != nil {
+		return "", nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output")
+	}
+
+	switch ifExists {
+	case "", drivePreviewIfExistsError:
+		if _, statErr := runtime.FileIO().Stat(finalPath); statErr == nil {
+			return "", nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "output file already exists: %s (use --if-exists overwrite or rename)", finalPath).WithParam("--output")
+		} else if !errors.Is(statErr, fs.ErrNotExist) {
+			return "", nil, errs.NewInternalError(errs.SubtypeFileIO, "cannot access output path %s: %s", finalPath, statErr).WithCause(statErr)
+		}
+		return finalPath, resolution, nil
+	case drivePreviewIfExistsOverwrite:
+		return finalPath, resolution, nil
+	case drivePreviewIfExistsRename:
+		renamed, err := nextAvailableDrivePreviewPath(runtime.FileIO(), finalPath)
+		if err != nil {
+			return "", nil, err
+		}
+		if _, err := runtime.ResolveSavePath(renamed); err != nil {
+			return "", nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output")
+		}
+		return renamed, resolution, nil
+	default:
+		return "", nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --if-exists %q: allowed values are error, overwrite, rename", ifExists).WithParam("--if-exists")
+	}
+}
+
+// nextAvailableDrivePreviewPath finds the first unused "name (n)" variant for a
+// target output path.
+func nextAvailableDrivePreviewPath(fio fileio.FileIO, path string) (string, error) {
+	if _, err := fio.Stat(path); err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			return path, nil
+		}
+		return "", errs.NewInternalError(errs.SubtypeFileIO, "cannot access output path %s: %s", path, err).WithCause(err)
+	}
+	dir := filepath.Dir(path)
+	ext := filepath.Ext(path)
+	base := strings.TrimSuffix(filepath.Base(path), ext)
+	for i := 1; i < 10000; i++ {
+		candidate := filepath.Join(dir, fmt.Sprintf("%s (%d)%s", base, i, ext))
+		if _, err := fio.Stat(candidate); err != nil {
+			if errors.Is(err, fs.ErrNotExist) {
+				return candidate, nil
+			}
+			return "", errs.NewInternalError(errs.SubtypeFileIO, "cannot access candidate output path %s: %s", candidate, err).WithCause(err)
+		}
+	}
+	return "", errs.NewInternalError(errs.SubtypeFileIO, "cannot allocate a unique output path for %s", path)
+}
+
+// autoAppendDrivePreviewExtension appends an inferred extension when the user
+// did not provide one explicitly.
+func autoAppendDrivePreviewExtension(outputPath string, header http.Header, fallbackExt string) (string, *driveExtensionResolution) {
+	if drivePreviewHasExplicitExtension(outputPath) {
+		return outputPath, nil
+	}
+	normalizedPath := outputPath
+	if filepath.Ext(outputPath) == "." {
+		normalizedPath = strings.TrimSuffix(outputPath, ".")
+	}
+	if resolution := drivePreviewExtensionByContentType(header.Get("Content-Type")); resolution != nil {
+		return normalizedPath + resolution.Ext, resolution
+	}
+	if resolution := drivePreviewExtensionByContentDisposition(header); resolution != nil {
+		return normalizedPath + resolution.Ext, resolution
+	}
+	if fallbackExt != "" {
+		return normalizedPath + fallbackExt, &driveExtensionResolution{
+			Ext:    fallbackExt,
+			Source: "fallback",
+			Detail: "default fallback",
+		}
+	}
+	return outputPath, nil
+}
+
+// drivePreviewHasExplicitExtension reports whether the path already ends with a
+// usable filename extension.
+func drivePreviewHasExplicitExtension(path string) bool {
+	ext := filepath.Ext(path)
+	return ext != "" && ext != "."
+}
+
+// drivePreviewExtensionByContentType maps a response Content-Type header to a
+// file extension when possible.
+func drivePreviewExtensionByContentType(contentType string) *driveExtensionResolution {
+	if contentType == "" {
+		return nil
+	}
+	mediaType, _, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		mediaType = strings.TrimSpace(strings.Split(contentType, ";")[0])
+	}
+	if ext, ok := drivePreviewMimeToExt[strings.ToLower(mediaType)]; ok && ext != "" {
+		return &driveExtensionResolution{
+			Ext:    ext,
+			Source: "Content-Type",
+			Detail: contentType,
+		}
+	}
+	return nil
+}
+
+// drivePreviewExtensionByContentDisposition extracts an extension from the
+// response filename metadata.
+func drivePreviewExtensionByContentDisposition(header http.Header) *driveExtensionResolution {
+	filename := strings.TrimSpace(larkcore.FileNameByHeader(header))
+	if filename == "" {
+		return nil
+	}
+	ext := filepath.Ext(filename)
+	if ext == "" || ext == "." {
+		return nil
+	}
+	return &driveExtensionResolution{
+		Ext:    ext,
+		Source: "Content-Disposition",
+		Detail: filename,
+	}
+}
+
+// drivePreviewFallbackExt returns the default extension for known preview type
+// aliases when headers do not provide one.
+func drivePreviewFallbackExt(alias string) string {
+	switch normalizeDrivePreviewRequest(alias) {
+	case "pdf":
+		return ".pdf"
+	case "html":
+		return ".html"
+	case "text":
+		return ".txt"
+	case "png", "png_lin", "split_png":
+		return ".png"
+	case "jpg", "jpg_lin":
+		return ".jpg"
+	case "source", "source_file":
+		return ""
+	default:
+		return ""
+	}
+}
+
+// applyDrivePreviewTypeMeta fills normalized type metadata from the preview
+// type code.
+func applyDrivePreviewTypeMeta(candidate *drivePreviewCandidate) {
+	if candidate == nil {
+		return
+	}
+	if meta, ok := drivePreviewTypeByCode[candidate.TypeCode]; ok {
+		candidate.Type = meta.Type
+		candidate.TypeName = meta.Name
+		candidate.Label = meta.Label
+		return
+	}
+	code := strings.TrimSpace(candidate.TypeCode)
+	if code == "" {
+		candidate.Type = "unknown"
+		candidate.TypeName = "UNKNOWN"
+		candidate.Label = "Unknown Preview Type"
+		return
+	}
+	candidate.Type = "unknown_" + code
+	candidate.TypeName = "UNKNOWN"
+	candidate.Label = fmt.Sprintf("Unknown Preview Type %s", code)
+}
+
+// applyDrivePreviewStatusMeta fills normalized status metadata from the preview
+// status code.
+func applyDrivePreviewStatusMeta(candidate *drivePreviewCandidate) {
+	if candidate == nil {
+		return
+	}
+	if meta, ok := drivePreviewStatusByCode[candidate.StatusCode]; ok {
+		candidate.Status = meta.Name
+		candidate.Downloadable = meta.Downloadable
+		if candidate.Reason == "" && !meta.Downloadable {
+			candidate.Reason = meta.Reason
+		}
+		if meta.Downloadable {
+			candidate.Reason = ""
+		}
+		return
+	}
+	candidate.Status = "UNKNOWN"
+	candidate.Downloadable = false
+	if candidate.Reason == "" {
+		if strings.TrimSpace(candidate.StatusCode) == "" {
+			candidate.Reason = "Preview status is missing."
+		} else {
+			candidate.Reason = fmt.Sprintf("Unknown preview status %s.", candidate.StatusCode)
+		}
+	}
+}
+
+// normalizeDrivePreviewRequest canonicalizes user input for preview type
+// matching.
+func normalizeDrivePreviewRequest(requested string) string {
+	requested = strings.ToLower(strings.TrimSpace(requested))
+	requested = strings.ReplaceAll(requested, "-", "_")
+	requested = strings.ReplaceAll(requested, " ", "_")
+	return requested
+}
+
+// previewAliasesForCandidate returns configured aliases for a preview
+// candidate's type code.
+func previewAliasesForCandidate(candidate drivePreviewCandidate) []string {
+	if meta, ok := drivePreviewTypeByCode[candidate.TypeCode]; ok {
+		return meta.Aliases
+	}
+	return nil
+}
+
+// firstString returns the first non-empty string-like value from the provided
+// keys.
+func firstString(m map[string]interface{}, keys ...string) string {
+	for _, key := range keys {
+		v, ok := m[key]
+		if !ok || v == nil {
+			continue
+		}
+		switch t := v.(type) {
+		case string:
+			if strings.TrimSpace(t) != "" {
+				return t
+			}
+		case fmt.Stringer:
+			if s := strings.TrimSpace(t.String()); s != "" {
+				return s
+			}
+		case float64:
+			return strconv.FormatInt(int64(t), 10)
+		case int:
+			return strconv.Itoa(t)
+		case int64:
+			return strconv.FormatInt(t, 10)
+		case bool:
+			return strconv.FormatBool(t)
+		}
+	}
+	return ""
+}
+
+// versionString normalizes version fields from heterogeneous API payload types.
+func versionString(v interface{}) string {
+	switch t := v.(type) {
+	case string:
+		return strings.TrimSpace(t)
+	case float64:
+		return strconv.FormatInt(int64(t), 10)
+	case int:
+		return strconv.Itoa(t)
+	case int64:
+		return strconv.FormatInt(t, 10)
+	default:
+		return ""
+	}
+}
+
+// availableDrivePreviewTypes lists unique normalized preview type names from
+// the candidate set.
+func availableDrivePreviewTypes(candidates []drivePreviewCandidate) []string {
+	seen := map[string]bool{}
+	out := make([]string, 0, len(candidates))
+	for _, candidate := range candidates {
+		name := strings.TrimSpace(candidate.Type)
+		if name == "" || seen[name] {
+			continue
+		}
+		seen[name] = true
+		out = append(out, name)
+	}
+	return out
+}
+
+// availableDriveCoverSpecs lists the supported built-in cover spec names.
+func availableDriveCoverSpecs() []string {
+	out := make([]string, 0, len(driveCoverSpecs))
+	for _, spec := range driveCoverSpecs {
+		out = append(out, spec.Name)
+	}
+	return out
+}
+
+// wrapDrivePreviewUnavailable builds a validation error for an unsupported
+// preview selection.
+func wrapDrivePreviewUnavailable(fileToken, requested string, candidates []drivePreviewCandidate, reason string) error {
+	available := availableDrivePreviewTypes(candidates)
+	if reason == "" {
+		reason = fmt.Sprintf("requested preview type %q is not available for file %s", requested, fileToken)
+	}
+	hint := "rerun with --list-only to inspect available preview types"
+	if len(available) > 0 {
+		hint = fmt.Sprintf("available preview types: %s", strings.Join(available, ", "))
+	}
+	return errs.NewValidationError(errs.SubtypeFailedPrecondition, reason).WithHint(hint).WithParam("--type")
+}
+
+// wrapDrivePreviewNotReady builds an actionable error for a preview candidate
+// that exists but is not yet downloadable.
+func wrapDrivePreviewNotReady(fileToken, requested string, candidate drivePreviewCandidate) error {
+	reason := candidate.Reason
+	if reason == "" {
+		reason = fmt.Sprintf("preview type %q is not downloadable yet (status=%s)", requested, candidate.Status)
+	}
+	hint := fmt.Sprintf("rerun `lark-cli drive +preview --file-token %s --list-only` to inspect current candidate status", fileToken)
+	return errs.NewValidationError(errs.SubtypeFailedPrecondition, reason).WithHint(hint).WithParam("--type")
+}
+
+// wrapDriveCoverUnavailable builds a validation error for an unknown cover
+// spec.
+func wrapDriveCoverUnavailable(requested string) error {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --spec %q", requested).
+		WithHint("available cover specs: %s", strings.Join(availableDriveCoverSpecs(), ", ")).
+		WithParam("--spec")
+}

shortcuts/drive/drive_preview_test.go

@@ -0,0 +1,926 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// TestDrivePreviewListOnlyNormalizesCandidates verifies list mode output is
+// normalized from preview_result payloads.
+func TestDrivePreviewListOnlyNormalizesCandidates(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/file_preview/preview_result",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"preview_results": []map[string]interface{}{
+					{"preview_type": 0, "preview_status": 0},
+					{"preview_type": 14, "preview_status": 1},
+					{"preview_type": 16, "preview_status": 7},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePreview, []string{
+		"+preview",
+		"--file-token", "file_preview",
+		"--list-only",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if got := data["mode"]; got != "list" {
+		t.Fatalf("mode=%v, want list", got)
+	}
+	candidates, _ := data["candidates"].([]interface{})
+	if len(candidates) != 3 {
+		t.Fatalf("len(candidates)=%d, want 3", len(candidates))
+	}
+	first, _ := candidates[0].(map[string]interface{})
+	if got := first["type"]; got != "pdf" {
+		t.Fatalf("candidate[0].type=%v, want pdf", got)
+	}
+	if got := first["type_code"]; got != "0" {
+		t.Fatalf("candidate[0].type_code=%v, want 0", got)
+	}
+	if got := first["status"]; got != "READY" {
+		t.Fatalf("candidate[0].status=%v, want READY", got)
+	}
+	if got := first["downloadable"]; got != true {
+		t.Fatalf("candidate[0].downloadable=%v, want true", got)
+	}
+	second, _ := candidates[1].(map[string]interface{})
+	if got := second["status_code"]; got != "1" {
+		t.Fatalf("candidate[1].status_code=%v, want 1", got)
+	}
+	if got := second["reason"]; got != "Preview is still processing." {
+		t.Fatalf("candidate[1].reason=%v, want processing reason", got)
+	}
+}
+
+// TestDrivePreviewDownloadUsesResolvedTypeCodeAndRenamePolicy verifies preview
+// downloads use the resolved type and rename collision handling.
+func TestDrivePreviewDownloadUsesResolvedTypeCodeAndRenamePolicy(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/file_preview/preview_result",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"version": 7,
+				"preview_results": []map[string]interface{}{
+					{"preview_type": 0, "preview_status": 0},
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/medias/file_preview/preview_download?preview_type=0",
+		Status: 200,
+		Body:   []byte("%PDF-1.7"),
+		Headers: http.Header{
+			"Content-Type": []string{"application/pdf"},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.WriteFile(filepath.Join(tmpDir, "report.pdf"), []byte("old"), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	err := mountAndRunDrive(t, DrivePreview, []string{
+		"+preview",
+		"--file-token", "file_preview",
+		"--type", "pdf",
+		"--output", "report",
+		"--if-exists", "rename",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if got := data["selected_type"]; got != "pdf" {
+		t.Fatalf("selected_type=%v, want pdf", got)
+	}
+	resolvedTmpDir, err := filepath.EvalSymlinks(tmpDir)
+	if err != nil {
+		t.Fatalf("EvalSymlinks() error: %v", err)
+	}
+	wantPath := filepath.Join(resolvedTmpDir, "report (1).pdf")
+	if got := data["output_path"]; got != wantPath {
+		t.Fatalf("output_path=%v, want %s", got, wantPath)
+	}
+	if _, err := os.Stat(wantPath); err != nil {
+		t.Fatalf("expected preview artifact at %q: %v", wantPath, err)
+	}
+}
+
+// TestDrivePreviewRejectsUnavailableType verifies unavailable preview types
+// return an actionable validation error.
+func TestDrivePreviewRejectsUnavailableType(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/file_preview/preview_result",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"preview_results": []map[string]interface{}{
+					{"preview_type": 8, "preview_status": 0},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePreview, []string{
+		"+preview",
+		"--file-token", "file_preview",
+		"--type", "pdf",
+		"--output", "report",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected unavailable type error, got nil")
+	}
+	if !strings.Contains(err.Error(), `requested preview type "pdf" is not available`) {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// TestSelectDrivePreviewCandidatePrefersDownloadableAliasMatch verifies alias
+// selection prefers a downloadable candidate over an earlier unavailable one.
+func TestSelectDrivePreviewCandidatePrefersDownloadableAliasMatch(t *testing.T) {
+	candidate, ok := selectDrivePreviewCandidate([]drivePreviewCandidate{
+		{Type: "png", TypeCode: "1", Downloadable: false, Status: "PROCESSING"},
+		{Type: "jpg", TypeCode: "7", Downloadable: true, Status: "READY"},
+	}, "image")
+	if !ok {
+		t.Fatal("expected alias match, got none")
+	}
+	if candidate.Type != "jpg" {
+		t.Fatalf("selected candidate=%q, want jpg", candidate.Type)
+	}
+	if !candidate.Downloadable {
+		t.Fatalf("selected candidate should be downloadable: %+v", candidate)
+	}
+}
+
+// TestDriveCoverListOnlyUsesStaticSpecs verifies cover list mode returns the
+// built-in spec catalog without calling APIs.
+func TestDriveCoverListOnlyUsesStaticSpecs(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+
+	err := mountAndRunDrive(t, DriveCover, []string{
+		"+cover",
+		"--file-token", "file_cover",
+		"--list-only",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	candidates, _ := data["candidates"].([]interface{})
+	if len(candidates) != len(driveCoverSpecs) {
+		t.Fatalf("len(candidates)=%d, want %d", len(candidates), len(driveCoverSpecs))
+	}
+	last, _ := candidates[len(candidates)-1].(map[string]interface{})
+	if got := last["spec"]; got != "square" {
+		t.Fatalf("last spec=%v, want square", got)
+	}
+}
+
+// TestDriveCoverDownloadUsesMappedCoverOptionAndPreviewType verifies cover
+// downloads send the expected preview_download query mapping.
+func TestDriveCoverDownloadUsesMappedCoverOptionAndPreviewType(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	var capturedQuery url.Values
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/medias/file_cover/preview_download",
+		Status: 200,
+		Body:   []byte("png-data"),
+		Headers: http.Header{
+			"Content-Type": []string{"image/png"},
+		},
+		OnMatch: func(req *http.Request) {
+			capturedQuery = req.URL.Query()
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	err := mountAndRunDrive(t, DriveCover, []string{
+		"+cover",
+		"--file-token", "file_cover",
+		"--spec", "square",
+		"--output", "cover",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if got := data["selected_spec"]; got != "square" {
+		t.Fatalf("selected_spec=%v, want square", got)
+	}
+	resolvedTmpDir, err := filepath.EvalSymlinks(tmpDir)
+	if err != nil {
+		t.Fatalf("EvalSymlinks() error: %v", err)
+	}
+	wantPath := filepath.Join(resolvedTmpDir, "cover.png")
+	if got := data["output_path"]; got != wantPath {
+		t.Fatalf("output_path=%v, want %s", got, wantPath)
+	}
+	if _, err := os.Stat(wantPath); err != nil {
+		t.Fatalf("expected cover file at %q: %v", wantPath, err)
+	}
+	if got := capturedQuery.Get("preview_type"); got != "1" {
+		t.Fatalf("preview_type=%q, want 1", got)
+	}
+	if got := capturedQuery.Get("bus_type"); got != "" {
+		t.Fatalf("bus_type=%q, want empty for square crop flow", got)
+	}
+	if got := capturedQuery.Get("platform"); got != "" {
+		t.Fatalf("platform=%q, want empty when using default platform", got)
+	}
+	if got := capturedQuery.Get("width"); got != "360" {
+		t.Fatalf("width=%q, want 360", got)
+	}
+	if got := capturedQuery.Get("height"); got != "360" {
+		t.Fatalf("height=%q, want 360", got)
+	}
+	if got := capturedQuery.Get("policy"); got != "near" {
+		t.Fatalf("policy=%q, want near", got)
+	}
+}
+
+// TestDriveCoverDownload404ReturnsFailedPrecondition verifies the +cover path
+// reclassifies preview_download HTTP 404 as a non-retryable spec/state issue.
+func TestDriveCoverDownload404ReturnsFailedPrecondition(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/medias/file_cover/preview_download",
+		Status: http.StatusNotFound,
+		Body:   []byte(`{"code":404,"msg":"no artifact"}`),
+		Headers: http.Header{
+			"Content-Type": []string{"application/json"},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveCover, []string{
+		"+cover",
+		"--file-token", "file_cover",
+		"--spec", "square",
+		"--output", "cover",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected cover 404 error, got nil")
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if validationErr.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("subtype=%q, want %q", validationErr.Subtype, errs.SubtypeFailedPrecondition)
+	}
+	if validationErr.Param != "--spec" {
+		t.Fatalf("param=%q, want --spec", validationErr.Param)
+	}
+	if validationErr.Code != http.StatusNotFound {
+		t.Fatalf("code=%d, want %d", validationErr.Code, http.StatusNotFound)
+	}
+	if !strings.Contains(validationErr.Hint, "--list-only") {
+		t.Fatalf("hint=%q, want --list-only guidance", validationErr.Hint)
+	}
+	if !strings.Contains(validationErr.Hint, "file token/version is invalid") {
+		t.Fatalf("hint=%q, want invalid file token/version guidance", validationErr.Hint)
+	}
+	if !strings.Contains(validationErr.Hint, "available cover specs") && !strings.Contains(validationErr.Hint, "default, icon, grid") {
+		t.Fatalf("hint=%q, want available cover specs guidance", validationErr.Hint)
+	}
+	if !strings.Contains(validationErr.Error(), `preview_download returned HTTP 404 for --spec "square"`) {
+		t.Fatalf("message=%q, want neutral 404 message", validationErr.Error())
+	}
+}
+
+// newDrivePreviewRuntime builds a shortcut runtime with preconfigured preview
+// and cover flags for DryRun and helper tests.
+func newDrivePreviewRuntime(t *testing.T, use string, stringFlags map[string]string, boolFlags map[string]bool) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: use}
+	cmd.Flags().String("file-token", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("spec", "", "")
+	cmd.Flags().String("version", "", "")
+	cmd.Flags().String("output", "", "")
+	cmd.Flags().String("if-exists", drivePreviewIfExistsError, "")
+	cmd.Flags().Bool("list-only", false, "")
+	for name, value := range stringFlags {
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set --%s: %v", name, err)
+		}
+	}
+	for name, value := range boolFlags {
+		if !value {
+			continue
+		}
+		if err := cmd.Flags().Set(name, "true"); err != nil {
+			t.Fatalf("set --%s: %v", name, err)
+		}
+	}
+	return common.TestNewRuntimeContextWithCtx(context.Background(), cmd, driveTestConfig())
+}
+
+// decodeDryRunOutput marshals a DryRunAPI helper into a generic map for test
+// assertions.
+func decodeDryRunOutput(t *testing.T, dry *common.DryRunAPI) map[string]interface{} {
+	t.Helper()
+
+	raw, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+	var out map[string]interface{}
+	if err := json.Unmarshal(raw, &out); err != nil {
+		t.Fatalf("unmarshal dry run: %v", err)
+	}
+	return out
+}
+
+// TestDrivePreviewDryRunIncludesVersionAndMode verifies preview DryRun records
+// versioned request metadata in download mode.
+func TestDrivePreviewDryRunIncludesVersionAndMode(t *testing.T) {
+	runtime := newDrivePreviewRuntime(t, "drive +preview", map[string]string{
+		"file-token": "file_preview",
+		"type":       "image",
+		"version":    "7",
+		"output":     "preview",
+	}, nil)
+
+	data := decodeDryRunOutput(t, DrivePreview.DryRun(context.Background(), runtime))
+	if got := data["mode"]; got != "download" {
+		t.Fatalf("mode=%v, want download", got)
+	}
+	if got := data["requested_type"]; got != "image" {
+		t.Fatalf("requested_type=%v, want image", got)
+	}
+	api, _ := data["api"].([]interface{})
+	if len(api) != 2 {
+		t.Fatalf("len(api)=%d, want 2", len(api))
+	}
+	call, _ := api[0].(map[string]interface{})
+	if got := call["method"]; got != "POST" {
+		t.Fatalf("method=%v, want POST", got)
+	}
+	if got := call["url"]; got != "/open-apis/drive/v1/medias/file_preview/preview_result" {
+		t.Fatalf("url=%v, want preview_result", got)
+	}
+	body, _ := call["body"].(map[string]interface{})
+	if got := body["version"]; got != "7" {
+		t.Fatalf("body.version=%v, want 7", got)
+	}
+	downloadCall, _ := api[1].(map[string]interface{})
+	if got := downloadCall["method"]; got != "GET" {
+		t.Fatalf("download method=%v, want GET", got)
+	}
+	if got := downloadCall["url"]; got != "/open-apis/drive/v1/medias/file_preview/preview_download" {
+		t.Fatalf("download url=%v, want preview_download", got)
+	}
+	params, _ := downloadCall["params"].(map[string]interface{})
+	if got := params["preview_type"]; got != "<selected type_code from preview_result>" {
+		t.Fatalf("download params.preview_type=%v, want placeholder", got)
+	}
+	if got := params["version"]; got != "7" {
+		t.Fatalf("download params.version=%v, want 7", got)
+	}
+}
+
+// TestDrivePreviewDryRunListOmitsBodyWithoutVersion verifies list-mode DryRun
+// omits the request body when no version is supplied.
+func TestDrivePreviewDryRunListOmitsBodyWithoutVersion(t *testing.T) {
+	runtime := newDrivePreviewRuntime(t, "drive +preview", map[string]string{
+		"file-token": "file_preview",
+	}, map[string]bool{"list-only": true})
+
+	data := decodeDryRunOutput(t, DrivePreview.DryRun(context.Background(), runtime))
+	if got := data["mode"]; got != "list" {
+		t.Fatalf("mode=%v, want list", got)
+	}
+	api, _ := data["api"].([]interface{})
+	call, _ := api[0].(map[string]interface{})
+	if _, ok := call["body"]; ok {
+		t.Fatalf("dry-run body should be omitted when version is empty: %#v", call)
+	}
+}
+
+// TestDrivePreviewDryRunDownloadWithoutVersionShowsResolvedVersion verifies
+// download-mode DryRun documents the second preview_download step even when the
+// final version is only known after preview_result resolves candidates.
+func TestDrivePreviewDryRunDownloadWithoutVersionShowsResolvedVersion(t *testing.T) {
+	runtime := newDrivePreviewRuntime(t, "drive +preview", map[string]string{
+		"file-token": "file_preview",
+		"type":       "pdf",
+		"output":     "preview",
+	}, nil)
+
+	data := decodeDryRunOutput(t, DrivePreview.DryRun(context.Background(), runtime))
+	api, _ := data["api"].([]interface{})
+	if len(api) != 2 {
+		t.Fatalf("len(api)=%d, want 2", len(api))
+	}
+	downloadCall, _ := api[1].(map[string]interface{})
+	params, _ := downloadCall["params"].(map[string]interface{})
+	if got := params["version"]; got != "<resolved version from preview_result>" {
+		t.Fatalf("download params.version=%v, want resolved-version placeholder", got)
+	}
+}
+
+// TestDriveCoverDryRunListAndDownload verifies cover DryRun output for both
+// list and download modes.
+func TestDriveCoverDryRunListAndDownload(t *testing.T) {
+	listRuntime := newDrivePreviewRuntime(t, "drive +cover", map[string]string{
+		"file-token": "file_cover",
+	}, map[string]bool{"list-only": true})
+	listData := decodeDryRunOutput(t, DriveCover.DryRun(context.Background(), listRuntime))
+	if got := listData["mode"]; got != "list" {
+		t.Fatalf("list mode=%v, want list", got)
+	}
+	if _, ok := listData["candidates"].([]interface{}); !ok {
+		t.Fatalf("list candidates missing: %#v", listData)
+	}
+
+	downloadRuntime := newDrivePreviewRuntime(t, "drive +cover", map[string]string{
+		"file-token": "file_cover",
+		"spec":       "square",
+		"version":    "3",
+		"output":     "cover",
+	}, nil)
+	downloadData := decodeDryRunOutput(t, DriveCover.DryRun(context.Background(), downloadRuntime))
+	if got := downloadData["selected_spec"]; got != "square" {
+		t.Fatalf("selected_spec=%v, want square", got)
+	}
+	api, _ := downloadData["api"].([]interface{})
+	call, _ := api[0].(map[string]interface{})
+	params, _ := call["params"].(map[string]interface{})
+	if got := params["width"]; got != float64(360) {
+		t.Fatalf("params.width=%v, want 360", got)
+	}
+	if got := params["policy"]; got != "near" {
+		t.Fatalf("params.policy=%v, want near", got)
+	}
+}
+
+// TestDriveCoverDryRunDefaultSpecIncludesVersionAndPlatform verifies DryRun
+// params include version and built-in platform metadata for default covers.
+func TestDriveCoverDryRunDefaultSpecIncludesVersionAndPlatform(t *testing.T) {
+	runtime := newDrivePreviewRuntime(t, "drive +cover", map[string]string{
+		"file-token": "file_cover",
+		"spec":       "default",
+		"version":    "5",
+		"output":     "cover",
+	}, nil)
+
+	data := decodeDryRunOutput(t, DriveCover.DryRun(context.Background(), runtime))
+	api, _ := data["api"].([]interface{})
+	call, _ := api[0].(map[string]interface{})
+	params, _ := call["params"].(map[string]interface{})
+	if got := params["bus_type"]; got != "cover" {
+		t.Fatalf("params.bus_type=%v, want cover", got)
+	}
+	if got := params["platform"]; got != "pc" {
+		t.Fatalf("params.platform=%v, want pc", got)
+	}
+	if got := params["version"]; got != "5" {
+		t.Fatalf("params.version=%v, want 5", got)
+	}
+}
+
+// TestDrivePreviewValidationErrors verifies preview flag validation rejects
+// incomplete and conflicting argument combinations.
+func TestDrivePreviewValidationErrors(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+
+	err := mountAndRunDrive(t, DrivePreview, []string{
+		"+preview",
+		"--file-token", "file_preview",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil || !strings.Contains(err.Error(), "either --list-only or --type is required") {
+		t.Fatalf("unexpected missing type error: %v", err)
+	}
+
+	err = mountAndRunDrive(t, DrivePreview, []string{
+		"+preview",
+		"--file-token", "file_preview",
+		"--list-only",
+		"--type", "pdf",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil || !strings.Contains(err.Error(), "--type cannot be combined with --list-only") {
+		t.Fatalf("unexpected list-only conflict: %v", err)
+	}
+
+	err = mountAndRunDrive(t, DrivePreview, []string{
+		"+preview",
+		"--file-token", "file_preview",
+		"--type", "pdf",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil || !strings.Contains(err.Error(), "--output is required when --type is set") {
+		t.Fatalf("unexpected missing output error: %v", err)
+	}
+}
+
+// TestDrivePreviewNotReadyReturnsFailedPrecondition verifies a known but
+// unready preview candidate returns a failed-precondition error.
+func TestDrivePreviewNotReadyReturnsFailedPrecondition(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/file_preview/preview_result",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"preview_results": []map[string]interface{}{
+					{"preview_type": 1, "preview_status": 1},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePreview, []string{
+		"+preview",
+		"--file-token", "file_preview",
+		"--type", "image",
+		"--output", "preview",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected not-ready error, got nil")
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if validationErr.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("subtype=%q, want %q", validationErr.Subtype, errs.SubtypeFailedPrecondition)
+	}
+	if validationErr.Param != "--type" {
+		t.Fatalf("param=%q, want --type", validationErr.Param)
+	}
+	if !strings.Contains(validationErr.Hint, "--list-only") {
+		t.Fatalf("hint=%q, want list-only guidance", validationErr.Hint)
+	}
+}
+
+// TestDriveCoverRejectsUnknownSpec verifies unsupported cover specs produce a
+// validation error with available alternatives.
+func TestDriveCoverRejectsUnknownSpec(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+
+	err := mountAndRunDrive(t, DriveCover, []string{
+		"+cover",
+		"--file-token", "file_cover",
+		"--spec", "poster",
+		"--output", "cover",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected invalid spec error, got nil")
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if validationErr.Param != "--spec" {
+		t.Fatalf("param=%q, want --spec", validationErr.Param)
+	}
+	if !strings.Contains(validationErr.Hint, "available cover specs") {
+		t.Fatalf("hint=%q, want available specs", validationErr.Hint)
+	}
+}
+
+// TestDriveCoverValidationErrors verifies cover flag validation rejects
+// incomplete and conflicting argument combinations.
+func TestDriveCoverValidationErrors(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+
+	err := mountAndRunDrive(t, DriveCover, []string{
+		"+cover",
+		"--file-token", "file_cover",
+		"--spec", "default",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil || !strings.Contains(err.Error(), "--output is required when --spec is set") {
+		t.Fatalf("unexpected missing output error: %v", err)
+	}
+
+	err = mountAndRunDrive(t, DriveCover, []string{
+		"+cover",
+		"--file-token", "file_cover",
+		"--list-only",
+		"--spec", "default",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil || !strings.Contains(err.Error(), "--spec cannot be combined with --list-only") {
+		t.Fatalf("unexpected list-only conflict: %v", err)
+	}
+}
+
+// TestDrivePreviewCommonHelpers exercises helper branches for extension
+// inference and fallback extension mapping.
+func TestDrivePreviewCommonHelpers(t *testing.T) {
+	if got := drivePreviewFallbackExt("pdf"); got != ".pdf" {
+		t.Fatalf("fallbackExt(pdf)=%q, want .pdf", got)
+	}
+	if got := drivePreviewFallbackExt("html"); got != ".html" {
+		t.Fatalf("fallbackExt(html)=%q, want .html", got)
+	}
+	if got := drivePreviewFallbackExt("text"); got != ".txt" {
+		t.Fatalf("fallbackExt(text)=%q, want .txt", got)
+	}
+	if got := drivePreviewFallbackExt("jpg"); got != ".jpg" {
+		t.Fatalf("fallbackExt(jpg)=%q, want .jpg", got)
+	}
+	if got := drivePreviewFallbackExt("jpg_lin"); got != ".jpg" {
+		t.Fatalf("fallbackExt(jpg_lin)=%q, want .jpg", got)
+	}
+	if got := drivePreviewFallbackExt("split_png"); got != ".png" {
+		t.Fatalf("fallbackExt(split_png)=%q, want .png", got)
+	}
+	if got := drivePreviewFallbackExt("source"); got != "" {
+		t.Fatalf("fallbackExt(source)=%q, want empty", got)
+	}
+	if got := drivePreviewFallbackExt("unknown"); got != "" {
+		t.Fatalf("fallbackExt(unknown)=%q, want empty", got)
+	}
+	specs := availableDriveCoverSpecs()
+	if len(specs) == 0 || specs[len(specs)-1] != "square" {
+		t.Fatalf("availableDriveCoverSpecs()=%v, want square included", specs)
+	}
+
+	header := http.Header{}
+	header.Set("Content-Disposition", `attachment; filename="preview.pdf"`)
+	resolution := drivePreviewExtensionByContentDisposition(header)
+	if resolution == nil || resolution.Ext != ".pdf" {
+		t.Fatalf("content disposition resolution=%+v, want .pdf", resolution)
+	}
+	header.Set("Content-Disposition", `attachment; filename="preview"`)
+	if resolution := drivePreviewExtensionByContentDisposition(header); resolution != nil {
+		t.Fatalf("content disposition without ext should be nil: %+v", resolution)
+	}
+
+	path, fallback := autoAppendDrivePreviewExtension("cover", http.Header{}, ".png")
+	if path != "cover.png" || fallback == nil || fallback.Source != "fallback" {
+		t.Fatalf("fallback append = (%q, %+v), want cover.png with fallback source", path, fallback)
+	}
+	path, fallback = autoAppendDrivePreviewExtension("cover.", http.Header{}, ".png")
+	if path != "cover.png" || fallback == nil {
+		t.Fatalf("trailing-dot append = (%q, %+v), want cover.png", path, fallback)
+	}
+	path, fallback = autoAppendDrivePreviewExtension("cover.pdf", http.Header{}, ".png")
+	if path != "cover.pdf" || fallback != nil {
+		t.Fatalf("explicit ext append = (%q, %+v), want unchanged path", path, fallback)
+	}
+}
+
+// TestDrivePreviewMetadataAndPathResolution verifies metadata normalization
+// and output path resolution helpers across rename and overwrite flows.
+func TestDrivePreviewMetadataAndPathResolution(t *testing.T) {
+	candidate := drivePreviewCandidate{TypeCode: "999", StatusCode: "", Reason: ""}
+	applyDrivePreviewTypeMeta(&candidate)
+	applyDrivePreviewStatusMeta(&candidate)
+	if candidate.Type != "unknown_999" {
+		t.Fatalf("candidate.Type=%q, want unknown_999", candidate.Type)
+	}
+	if candidate.Reason != "Preview status is missing." {
+		t.Fatalf("candidate.Reason=%q, want missing-status reason", candidate.Reason)
+	}
+
+	ready := drivePreviewCandidate{TypeCode: "1", StatusCode: "0"}
+	applyDrivePreviewTypeMeta(&ready)
+	applyDrivePreviewStatusMeta(&ready)
+	if ready.Type != "png" || !ready.Downloadable {
+		t.Fatalf("ready candidate=%+v, want downloadable png", ready)
+	}
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.WriteFile(filepath.Join(tmpDir, "preview.pdf"), []byte("old"), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+	runtime := newDrivePreviewRuntime(t, "drive +preview", nil, nil)
+	header := http.Header{}
+	header.Set("Content-Type", "application/pdf")
+	renamed, _, err := resolveDrivePreviewOutputPath(runtime, "preview", header, ".pdf", drivePreviewIfExistsRename)
+	if err != nil {
+		t.Fatalf("resolveDrivePreviewOutputPath(rename) error: %v", err)
+	}
+	if !strings.HasSuffix(renamed, "preview (1).pdf") {
+		t.Fatalf("renamed=%q, want preview (1).pdf suffix", renamed)
+	}
+
+	_, _, err = resolveDrivePreviewOutputPath(runtime, "preview", header, ".pdf", "keep")
+	if err == nil {
+		t.Fatal("expected invalid if-exists error, got nil")
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if validationErr.Param != "--if-exists" {
+		t.Fatalf("param=%q, want --if-exists", validationErr.Param)
+	}
+
+	unusedPath, err := nextAvailableDrivePreviewPath(runtime.FileIO(), "fresh.pdf")
+	if err != nil {
+		t.Fatalf("nextAvailableDrivePreviewPath(unused) error: %v", err)
+	}
+	if unusedPath != "fresh.pdf" {
+		t.Fatalf("unusedPath=%q, want fresh.pdf", unusedPath)
+	}
+
+	overwritten, _, err := resolveDrivePreviewOutputPath(runtime, "preview.pdf", header, ".pdf", drivePreviewIfExistsOverwrite)
+	if err != nil {
+		t.Fatalf("resolveDrivePreviewOutputPath(overwrite) error: %v", err)
+	}
+	if !strings.HasSuffix(overwritten, "preview.pdf") {
+		t.Fatalf("overwritten=%q, want preview.pdf suffix", overwritten)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+	f.FileIOProvider = &statErrorProvider{inner: f.FileIOProvider, err: fs.ErrPermission}
+	runtimeWithStatErr := newDrivePreviewRuntime(t, "drive +preview", nil, nil)
+	runtimeWithStatErr.Factory = f
+	_, _, err = resolveDrivePreviewOutputPath(runtimeWithStatErr, "blocked.pdf", header, ".pdf", drivePreviewIfExistsError)
+	if err == nil {
+		t.Fatal("expected stat permission error, got nil")
+	}
+	var internalErr *errs.InternalError
+	if !errors.As(err, &internalErr) {
+		t.Fatalf("expected *errs.InternalError, got %T: %v", err, err)
+	}
+	if internalErr.Subtype != errs.SubtypeFileIO {
+		t.Fatalf("Subtype=%q, want %q", internalErr.Subtype, errs.SubtypeFileIO)
+	}
+}
+
+type drivePreviewTestStringer string
+
+type statErrorProvider struct {
+	inner fileio.Provider
+	err   error
+}
+
+func (p *statErrorProvider) Name() string { return "stat-error" }
+
+func (p *statErrorProvider) ResolveFileIO(ctx context.Context) fileio.FileIO {
+	return &statErrorFileIO{inner: p.inner.ResolveFileIO(ctx), err: p.err}
+}
+
+type statErrorFileIO struct {
+	inner fileio.FileIO
+	err   error
+}
+
+func (f *statErrorFileIO) Open(name string) (fileio.File, error) { return f.inner.Open(name) }
+
+func (f *statErrorFileIO) Stat(string) (fileio.FileInfo, error) { return nil, f.err }
+
+func (f *statErrorFileIO) ResolvePath(path string) (string, error) { return f.inner.ResolvePath(path) }
+
+func (f *statErrorFileIO) Save(path string, opts fileio.SaveOptions, body io.Reader) (fileio.SaveResult, error) {
+	return f.inner.Save(path, opts, body)
+}
+
+// String implements fmt.Stringer for scalar helper tests.
+func (s drivePreviewTestStringer) String() string { return string(s) }
+
+// TestDrivePreviewScalarHelpers verifies scalar coercion helpers normalize
+// mixed API field types into strings.
+func TestDrivePreviewScalarHelpers(t *testing.T) {
+	got := firstString(map[string]interface{}{
+		"blank":   "   ",
+		"number":  float64(7),
+		"flag":    true,
+		"named":   drivePreviewTestStringer(" named "),
+		"integer": int64(9),
+	}, "blank", "named", "number")
+	if got != "named" {
+		t.Fatalf("firstString()=%q, want named", got)
+	}
+
+	if got := firstString(map[string]interface{}{"flag": true}, "flag"); got != "true" {
+		t.Fatalf("firstString(bool)=%q, want true", got)
+	}
+	if got := firstString(map[string]interface{}{"integer": int64(9)}, "integer"); got != "9" {
+		t.Fatalf("firstString(int64)=%q, want 9", got)
+	}
+
+	if got := versionString(" 42 "); got != "42" {
+		t.Fatalf("versionString(string)=%q, want 42", got)
+	}
+	if got := versionString(float64(8)); got != "8" {
+		t.Fatalf("versionString(float64)=%q, want 8", got)
+	}
+	if got := versionString(int64(11)); got != "11" {
+		t.Fatalf("versionString(int64)=%q, want 11", got)
+	}
+	if got := versionString(struct{}{}); got != "" {
+		t.Fatalf("versionString(struct)=%q, want empty", got)
+	}
+}
+
+// TestDrivePreviewAliasAndAvailabilityHelpers verifies alias lookup,
+// normalization, and available-type de-duplication helpers.
+func TestDrivePreviewAliasAndAvailabilityHelpers(t *testing.T) {
+	if got := normalizeDrivePreviewRequest(" Source File "); got != "source_file" {
+		t.Fatalf("normalizeDrivePreviewRequest()=%q, want source_file", got)
+	}
+
+	aliases := previewAliasesForCandidate(drivePreviewCandidate{TypeCode: "1"})
+	if len(aliases) == 0 || aliases[0] != "image" {
+		t.Fatalf("previewAliasesForCandidate()=%v, want image alias", aliases)
+	}
+	if got := previewAliasesForCandidate(drivePreviewCandidate{TypeCode: "999"}); got != nil {
+		t.Fatalf("previewAliasesForCandidate(unknown)=%v, want nil", got)
+	}
+
+	types := availableDrivePreviewTypes([]drivePreviewCandidate{
+		{Type: "pdf"},
+		{Type: "pdf"},
+		{Type: " jpg "},
+		{Type: ""},
+	})
+	if len(types) != 2 || types[0] != "pdf" || types[1] != "jpg" {
+		t.Fatalf("availableDrivePreviewTypes()=%v, want [pdf jpg]", types)
+	}
+}
+
+// TestDrivePreviewUnavailableHintAndContentTypeFallback verifies unavailable
+// preview errors and content-type fallback extension inference.
+func TestDrivePreviewUnavailableHintAndContentTypeFallback(t *testing.T) {
+	err := wrapDrivePreviewUnavailable("file_preview", "html", []drivePreviewCandidate{
+		{Type: "pdf"},
+		{Type: "jpg"},
+	}, "")
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if !strings.Contains(validationErr.Hint, "available preview types: pdf, jpg") {
+		t.Fatalf("hint=%q, want available preview types", validationErr.Hint)
+	}
+
+	err = wrapDrivePreviewUnavailable("file_preview", "html", nil, fmt.Sprintf("custom reason for %s", "html"))
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if !strings.Contains(validationErr.Hint, "--list-only") {
+		t.Fatalf("hint=%q, want list-only guidance", validationErr.Hint)
+	}
+
+	resolution := drivePreviewExtensionByContentType("text/plain; charset=utf-8")
+	if resolution == nil || resolution.Ext != ".txt" {
+		t.Fatalf("drivePreviewExtensionByContentType()=%+v, want .txt", resolution)
+	}
+}

shortcuts/drive/drive_secure_label.go

@@ -13,7 +13,7 @@ import (
 )
 
 const (
-	secureLabelReadScope   = "drive:file.meta.sec_label.read_only"
+	secureLabelReadScope   = "docs:secure_label:readonly"
 	secureLabelUpdateScope = "docs:secure_label:write_only"
 )
 

shortcuts/drive/drive_secure_label_test.go

@@ -12,6 +12,17 @@ import (
 	"github.com/larksuite/cli/internal/httpmock"
 )
 
+func TestDriveSecureLabelScopes(t *testing.T) {
+	t.Parallel()
+
+	if len(DriveSecureLabelList.Scopes) != 1 || DriveSecureLabelList.Scopes[0] != "docs:secure_label:readonly" {
+		t.Fatalf("list scopes = %v, want docs:secure_label:readonly", DriveSecureLabelList.Scopes)
+	}
+	if len(DriveSecureLabelUpdate.Scopes) != 1 || DriveSecureLabelUpdate.Scopes[0] != "docs:secure_label:write_only" {
+		t.Fatalf("update scopes = %v, want docs:secure_label:write_only", DriveSecureLabelUpdate.Scopes)
+	}
+}
+
 func TestDriveSecureLabelList_DryRun(t *testing.T) {
 	t.Parallel()
 	f, stdout, _, _ := cmdutil.TestFactory(t, driveTestConfig())

shortcuts/drive/shortcuts.go

@@ -12,6 +12,8 @@ func Shortcuts() []common.Shortcut {
 		DriveCreateFolder,
 		DriveCreateShortcut,
 		DriveDownload,
+		DrivePreview,
+		DriveCover,
 		DriveAddComment,
 		DriveExport,
 		DriveExportDownload,

shortcuts/drive/shortcuts_test.go

@@ -15,6 +15,8 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+create-folder",
 		"+create-shortcut",
 		"+download",
+		"+preview",
+		"+cover",
 		"+version-history",
 		"+version-get",
 		"+version-revert",

shortcuts/im/convert_lib/helpers.go

@@ -162,7 +162,7 @@ func batchResolveByBasicContact(runtime *common.RuntimeContext, missingIDs []str
 		}
 		batch := missingIDs[i:end]
 
-		data, err := runtime.DoAPIJSON(http.MethodPost,
+		data, err := runtime.DoAPIJSONTyped(http.MethodPost,
 			"/open-apis/contact/v3/users/basic_batch",
 			larkcore.QueryParams{"user_id_type": []string{"open_id"}},
 			map[string]interface{}{"user_ids": batch},
@@ -198,7 +198,7 @@ func batchResolveUsers(runtime *common.RuntimeContext, missingIDs []string, name
 		}
 		apiURL := "/open-apis/contact/v3/users/batch?" + strings.Join(parts, "&")
 
-		data, err := runtime.DoAPIJSON(http.MethodGet, apiURL, nil, nil)
+		data, err := runtime.DoAPIJSONTyped(http.MethodGet, apiURL, nil, nil)
 		if err != nil {
 			break
 		}

shortcuts/im/convert_lib/merge.go

@@ -200,20 +200,20 @@ func batchResolveMergeForwardSenders(runtime *common.RuntimeContext, prefetch ma
 // container via a single API call. Returns a flat list of raw message items
 // with upper_message_id for tree reconstruction.
 //
-// Uses DoAPIJSON so the response envelope's code/msg are checked and surfaced
+// Uses DoAPIJSONTyped so the response envelope's code/msg are checked and surfaced
 // — earlier this used the low-level DoAPI and reported every non-zero code
 // as a generic "empty data" error, hiding the real failure (e.g. a server
 // "code: 2200 Internal Error" with its log_id would show up as just "empty
 // data" in the output).
 func fetchMergeForwardSubMessages(messageID string, runtime *common.RuntimeContext) ([]map[string]interface{}, error) {
-	data, err := runtime.DoAPIJSON(http.MethodGet, mergeForwardMessagesPath(messageID), larkcore.QueryParams{
+	data, err := runtime.DoAPIJSONTyped(http.MethodGet, mergeForwardMessagesPath(messageID), larkcore.QueryParams{
 		"user_id_type":          []string{"open_id"},
 		"card_msg_content_type": []string{"raw_card_content"},
 	}, nil)
 	if err != nil {
 		return nil, err
 	}
-	// DoAPIJSON returns the envelope's `data` field; when the server's JSON
+	// DoAPIJSONTyped returns the envelope's `data` field; when the server's JSON
 	// has `code: 0` but omits `data` entirely, that field comes back as nil.
 	// Reading from a nil map in Go is safe (returns the zero value, never
 	// panics), but guarding explicitly makes the "successful empty

shortcuts/im/convert_lib/reactions.go

@@ -156,7 +156,7 @@ func fetchReactionsBatch(runtime *common.RuntimeContext, batchIDs []string, idIn
 		queries = append(queries, map[string]interface{}{"message_id": id})
 	}
 
-	data, err := runtime.DoAPIJSON(http.MethodPost,
+	data, err := runtime.DoAPIJSONTyped(http.MethodPost,
 		"/open-apis/im/v1/messages/reactions/batch_query",
 		nil,
 		map[string]interface{}{"queries": queries},

shortcuts/im/convert_lib/thread.go

@@ -243,7 +243,7 @@ func ExpandThreadReplies(runtime *common.RuntimeContext, messages []map[string]i
 // Returns the raw message items, whether more replies exist beyond the limit,
 // and a non-nil error when the API call fails.
 func fetchThreadReplies(runtime *common.RuntimeContext, threadID string, limit int) ([]map[string]interface{}, bool, error) {
-	data, err := runtime.DoAPIJSON(http.MethodGet, "/open-apis/im/v1/messages", larkcore.QueryParams{
+	data, err := runtime.DoAPIJSONTyped(http.MethodGet, "/open-apis/im/v1/messages", larkcore.QueryParams{
 		"container_id_type":     []string{"thread"},
 		"container_id":          []string{threadID},
 		"sort_type":             []string{"ByCreateTimeAsc"},
@@ -251,7 +251,7 @@ func fetchThreadReplies(runtime *common.RuntimeContext, threadID string, limit i
 		"card_msg_content_type": []string{"raw_card_content"},
 	}, nil)
 	if err != nil {
-		return nil, false, fmt.Errorf("fetch thread replies for %s: %w", threadID, err)
+		return nil, false, fmt.Errorf("fetch thread replies for %s: %w", threadID, err) //nolint:forbidigo // best-effort internal thread fetch; never surfaced as a final shortcut error (ExpandThreadReplies is void)
 	}
 	hasMore, _ := data["has_more"].(bool)
 	rawItems, _ := data["items"].([]interface{})

shortcuts/im/helpers.go

@@ -19,10 +19,10 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -37,11 +37,11 @@ var messageIDRe = regexp.MustCompile(`^om_`)
 func flagMessageID(rt *common.RuntimeContext) (string, error) {
 	id := strings.TrimSpace(rt.Str("message-id"))
 	if id == "" {
-		return "", output.ErrValidation("--message-id is required")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--message-id is required").WithParam("--message-id")
 	}
 	if strings.HasPrefix(id, "omt_") {
-		return "", output.ErrValidation(
-			"invalid message ID %q: omt_ prefix is a thread ID, not a message ID; flag operations require om_ message IDs", id)
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"invalid message ID %q: omt_ prefix is a thread ID, not a message ID; flag operations require om_ message IDs", id).WithParam("--message-id")
 	}
 	return validateMessageID(id)
 }
@@ -65,10 +65,10 @@ func buildMGetURL(ids []string) string {
 func validateMessageID(input string) (string, error) {
 	input = strings.TrimSpace(input)
 	if input == "" {
-		return "", output.ErrValidation("message ID cannot be empty")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "message ID cannot be empty").WithParam("--message-id")
 	}
 	if !strings.HasPrefix(input, "om_") {
-		return "", output.ErrValidation("invalid message ID %q: must start with om_", input)
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid message ID %q: must start with om_", input).WithParam("--message-id")
 	}
 	return input, nil
 }
@@ -173,14 +173,16 @@ func sanitizeURLForDisplay(rawURL string) string {
 // startURLDownload performs URL validation, creates an HTTP client, and sends a
 // GET request. It returns the response (with Body still open) and the file
 // extension inferred from the URL. The caller must close resp.Body.
-func startURLDownload(ctx context.Context, runtime *common.RuntimeContext, rawURL string) (*http.Response, string, error) {
+func startURLDownload(ctx context.Context, runtime *common.RuntimeContext, rawURL, param string) (*http.Response, string, error) {
 	if err := validate.ValidateDownloadSourceURL(ctx, rawURL); err != nil {
-		return nil, "", fmt.Errorf("blocked URL: %w", err)
+		return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument, "blocked URL: %v", err).
+			WithParam(param).
+			WithCause(err)
 	}
 
 	httpClient, err := runtime.Factory.HttpClient()
 	if err != nil {
-		return nil, "", fmt.Errorf("http client: %w", err)
+		return nil, "", errs.NewInternalError(errs.SubtypeSDKError, "http client: %v", err).WithCause(err)
 	}
 	httpClient = validate.NewDownloadHTTPClient(httpClient, validate.DownloadHTTPClientOptions{
 		AllowHTTP: true,
@@ -188,17 +190,19 @@ func startURLDownload(ctx context.Context, runtime *common.RuntimeContext, rawUR
 
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
 	if err != nil {
-		return nil, "", fmt.Errorf("invalid URL: %w", err)
+		return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid URL: %v", err).
+			WithParam(param).
+			WithCause(err)
 	}
 
 	resp, err := httpClient.Do(req)
 	if err != nil {
-		return nil, "", fmt.Errorf("download failed: %w", err)
+		return nil, "", wrapIMNetworkErr(err, "download failed")
 	}
 
 	if resp.StatusCode != http.StatusOK {
 		resp.Body.Close()
-		return nil, "", fmt.Errorf("download failed: HTTP %d", resp.StatusCode)
+		return nil, "", errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: HTTP %d", resp.StatusCode)
 	}
 
 	ext := filepath.Ext(fileNameFromURL(rawURL))
@@ -208,8 +212,8 @@ func startURLDownload(ctx context.Context, runtime *common.RuntimeContext, rawUR
 // downloadURLToReader returns a size-limited io.ReadCloser for the URL content
 // and the file extension inferred from the URL. The caller must close the
 // returned ReadCloser. No temp file is created and the content is not buffered.
-func downloadURLToReader(ctx context.Context, runtime *common.RuntimeContext, rawURL string, maxSize int64) (io.ReadCloser, string, error) {
-	resp, ext, err := startURLDownload(ctx, runtime, rawURL) //nolint:bodyclose // resp.Body is closed by the returned limitedReadCloser
+func downloadURLToReader(ctx context.Context, runtime *common.RuntimeContext, rawURL string, maxSize int64, param string) (io.ReadCloser, string, error) {
+	resp, ext, err := startURLDownload(ctx, runtime, rawURL, param) //nolint:bodyclose // resp.Body is closed by the returned limitedReadCloser
 	if err != nil {
 		return nil, "", err
 	}
@@ -233,7 +237,7 @@ func (l *limitedReadCloser) Read(p []byte) (int, error) {
 	n, err := l.r.Read(p)
 	l.n += int64(n)
 	if l.n > l.max {
-		return n, fmt.Errorf("download exceeds size limit (max %s)", common.FormatSize(l.max))
+		return n, fmt.Errorf("download exceeds size limit (max %s)", common.FormatSize(l.max)) //nolint:forbidigo // io.Reader.Read contract returns a plain error; classified by the download caller
 	}
 	return n, err
 }
@@ -314,7 +318,7 @@ func resolveURLMedia(ctx context.Context, runtime *common.RuntimeContext, s medi
 	fmt.Fprintf(runtime.IO().ErrOut, "downloading %s: %s\n", s.flagName, sanitizeURLForDisplay(s.value))
 
 	if s.kind == mediaKindImage {
-		rc, _, err := downloadURLToReader(ctx, runtime, s.value, s.maxSize)
+		rc, _, err := downloadURLToReader(ctx, runtime, s.value, s.maxSize, s.flagName)
 		if err != nil {
 			return "", err
 		}
@@ -324,7 +328,7 @@ func resolveURLMedia(ctx context.Context, runtime *common.RuntimeContext, s medi
 	}
 
 	// File-kind: buffer in memory for possible duration parsing.
-	mb, err := newMediaBuffer(ctx, runtime, s.value, s.maxSize)
+	mb, err := newMediaBuffer(ctx, runtime, s.value, s.maxSize, s.flagName)
 	if err != nil {
 		return "", err
 	}
@@ -341,7 +345,7 @@ func resolveLocalMedia(ctx context.Context, runtime *common.RuntimeContext, s me
 	fmt.Fprintf(runtime.IO().ErrOut, "uploading %s: %s\n", s.mediaType, filepath.Base(s.value))
 
 	if s.kind == mediaKindImage {
-		return uploadImageToIM(ctx, runtime, s.value, "message")
+		return uploadImageToIM(ctx, runtime, s.value, "message", s.flagName)
 	}
 
 	ft := detectIMFileType(s.value)
@@ -349,7 +353,7 @@ func resolveLocalMedia(ctx context.Context, runtime *common.RuntimeContext, s me
 	if s.withDuration {
 		dur = parseMediaDuration(runtime, s.value, ft)
 	}
-	return uploadFileToIM(ctx, runtime, s.value, ft, dur)
+	return uploadFileToIM(ctx, runtime, s.value, ft, dur, s.flagName)
 }
 
 // resolveVideoContent handles the video case which needs both a file_key and
@@ -370,7 +374,7 @@ func resolveVideoContent(ctx context.Context, runtime *common.RuntimeContext, vi
 	}
 	coverKey, err := resolveOneMedia(ctx, runtime, coverSpec)
 	if err != nil {
-		return "", "", fmt.Errorf("cover image upload failed: %w", err)
+		return "", "", wrapIMNetworkErr(err, "cover image upload failed")
 	}
 
 	jsonBytes, _ := json.Marshal(map[string]string{"file_key": fKey, "image_key": coverKey})
@@ -386,13 +390,13 @@ func mediaFallbackOrError(originalValue, mediaType string, uploadErr error) (str
 		jsonBytes, _ := json.Marshal(map[string]string{"text": fallbackText})
 		return "text", string(jsonBytes), nil
 	}
-	return "", "", fmt.Errorf("%s upload failed: %w", mediaType, uploadErr)
+	return "", "", wrapIMNetworkErr(uploadErr, "%s upload failed", mediaType)
 }
 
 // resolveP2PChatID resolves user open_id to P2P chat_id.
 func resolveP2PChatID(runtime *common.RuntimeContext, openID string) (string, error) {
 	if runtime.IsBot() {
-		return "", output.Errorf(output.ExitValidation, "validation", "--user-id requires user identity (--as user); use --chat-id when calling with bot identity")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--user-id requires user identity (--as user); use --chat-id when calling with bot identity").WithParam("--user-id")
 	}
 	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
 		HttpMethod: http.MethodPost,
@@ -405,11 +409,10 @@ func resolveP2PChatID(runtime *common.RuntimeContext, openID string) (string, er
 	if err != nil {
 		return "", err
 	}
-	var result map[string]interface{}
-	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-		return "", fmt.Errorf("failed to parse chat_p2p response: %w", err)
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return "", err
 	}
-	data, _ := result["data"].(map[string]interface{})
 
 	chats, _ := data["p2p_chats"].([]interface{})
 	for _, item := range chats {
@@ -420,7 +423,7 @@ func resolveP2PChatID(runtime *common.RuntimeContext, openID string) (string, er
 		}
 	}
 
-	return "", output.Errorf(output.ExitAPI, "not_found", "P2P chat not found for this user")
+	return "", errs.NewAPIError(errs.SubtypeNotFound, "P2P chat not found for this user")
 }
 
 // resolveThreadID normalizes a message ID to its thread ID when possible.
@@ -429,7 +432,7 @@ func resolveThreadID(runtime *common.RuntimeContext, id string) (string, error)
 		return id, nil
 	}
 	if !messageIDRe.MatchString(id) {
-		return "", output.Errorf(output.ExitValidation, "validation", "invalid thread ID format: must start with om_ or omt_")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid thread ID format: must start with om_ or omt_").WithParam("--thread")
 	}
 
 	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
@@ -439,11 +442,10 @@ func resolveThreadID(runtime *common.RuntimeContext, id string) (string, error)
 	if err != nil {
 		return "", err
 	}
-	var result map[string]interface{}
-	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-		return "", fmt.Errorf("failed to parse message response: %w", err)
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return "", err
 	}
-	data, _ := result["data"].(map[string]interface{})
 
 	items, _ := data["items"].([]interface{})
 	for _, item := range items {
@@ -454,7 +456,7 @@ func resolveThreadID(runtime *common.RuntimeContext, id string) (string, error)
 		}
 	}
 
-	return "", output.Errorf(output.ExitAPI, "not_found", "thread ID not found for this message")
+	return "", errs.NewAPIError(errs.SubtypeNotFound, "thread ID not found for this message")
 }
 
 // parseOggOpusDuration parses the duration in milliseconds from an OGG/Opus
@@ -612,8 +614,8 @@ type mediaBuffer struct {
 }
 
 // newMediaBuffer downloads URL content into memory via downloadURLToReader.
-func newMediaBuffer(ctx context.Context, runtime *common.RuntimeContext, rawURL string, maxSize int64) (*mediaBuffer, error) {
-	rc, ext, err := downloadURLToReader(ctx, runtime, rawURL, maxSize)
+func newMediaBuffer(ctx context.Context, runtime *common.RuntimeContext, rawURL string, maxSize int64, param string) (*mediaBuffer, error) {
+	rc, ext, err := downloadURLToReader(ctx, runtime, rawURL, maxSize, param)
 	if err != nil {
 		return nil, err
 	}
@@ -621,7 +623,7 @@ func newMediaBuffer(ctx context.Context, runtime *common.RuntimeContext, rawURL
 
 	data, err := io.ReadAll(rc)
 	if err != nil {
-		return nil, fmt.Errorf("download failed: %w", err)
+		return nil, wrapIMNetworkErr(err, "download failed")
 	}
 	return newMediaBufferFromBytes(data, ext, rawURL), nil
 }
@@ -927,7 +929,7 @@ func resolveMarkdownImageURLs(ctx context.Context, runtime *common.RuntimeContex
 		}
 		imgURL := sub[1]
 
-		rc, _, err := downloadURLToReader(ctx, runtime, imgURL, maxImageUploadSize)
+		rc, _, err := downloadURLToReader(ctx, runtime, imgURL, maxImageUploadSize, "--markdown")
 		if err != nil {
 			fmt.Fprintf(runtime.IO().ErrOut, "warning: failed to download image %s: %v\n", sanitizeURLForDisplay(imgURL), err)
 			return ""
@@ -1049,14 +1051,14 @@ func detectIMFileType(filePath string) string {
 const maxImageUploadSize = 5 * 1024 * 1024  // 5MB — Lark API limit for images
 const maxFileUploadSize = 100 * 1024 * 1024 // 100MB — Lark API limit for files
 
-func uploadImageToIM(ctx context.Context, runtime *common.RuntimeContext, filePath, imageType string) (string, error) {
+func uploadImageToIM(ctx context.Context, runtime *common.RuntimeContext, filePath, imageType, param string) (string, error) {
 	if info, err := runtime.FileIO().Stat(filePath); err == nil && info.Size() > maxImageUploadSize {
-		return "", fmt.Errorf("image size %s exceeds limit (max 5MB)", common.FormatSize(info.Size()))
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "image size %s exceeds limit (max 5MB)", common.FormatSize(info.Size())).WithParam(param)
 	}
 
 	f, err := runtime.FileIO().Open(filePath)
 	if err != nil {
-		return "", err
+		return "", withIMValidationParam(common.WrapInputStatErrorTyped(err), param)
 	}
 	defer f.Close()
 
@@ -1073,27 +1075,25 @@ func uploadImageToIM(ctx context.Context, runtime *common.RuntimeContext, filePa
 		return "", err
 	}
 
-	var result map[string]interface{}
-	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-		return "", fmt.Errorf("parse error: %w", err)
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return "", err
 	}
-
-	data, _ := result["data"].(map[string]interface{})
 	imageKey, _ := data["image_key"].(string)
 	if imageKey == "" {
-		return "", fmt.Errorf("image_key not found in response (code: %v, msg: %v)", result["code"], result["msg"])
+		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "image_key missing from a successful upload response")
 	}
 	return imageKey, nil
 }
 
-func uploadFileToIM(ctx context.Context, runtime *common.RuntimeContext, filePath, fileType, duration string) (string, error) {
+func uploadFileToIM(ctx context.Context, runtime *common.RuntimeContext, filePath, fileType, duration, param string) (string, error) {
 	if info, err := runtime.FileIO().Stat(filePath); err == nil && info.Size() > maxFileUploadSize {
-		return "", fmt.Errorf("file size %s exceeds limit (max 100MB)", common.FormatSize(info.Size()))
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "file size %s exceeds limit (max 100MB)", common.FormatSize(info.Size())).WithParam(param)
 	}
 
 	f, err := runtime.FileIO().Open(filePath)
 	if err != nil {
-		return "", err
+		return "", withIMValidationParam(common.WrapInputStatErrorTyped(err), param)
 	}
 	defer f.Close()
 
@@ -1114,15 +1114,13 @@ func uploadFileToIM(ctx context.Context, runtime *common.RuntimeContext, filePat
 		return "", err
 	}
 
-	var result map[string]interface{}
-	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-		return "", fmt.Errorf("parse error: %w", err)
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return "", err
 	}
-
-	data, _ := result["data"].(map[string]interface{})
 	fileKey, _ := data["file_key"].(string)
 	if fileKey == "" {
-		return "", fmt.Errorf("file_key not found in response (code: %v, msg: %v)", result["code"], result["msg"])
+		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "file_key missing from a successful upload response")
 	}
 	return fileKey, nil
 }
@@ -1142,15 +1140,13 @@ func uploadImageFromReader(ctx context.Context, runtime *common.RuntimeContext,
 		return "", err
 	}
 
-	var result map[string]interface{}
-	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-		return "", fmt.Errorf("parse error: %w", err)
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return "", err
 	}
-
-	data, _ := result["data"].(map[string]interface{})
 	imageKey, _ := data["image_key"].(string)
 	if imageKey == "" {
-		return "", fmt.Errorf("image_key not found in response (code: %v, msg: %v)", result["code"], result["msg"])
+		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "image_key missing from a successful upload response")
 	}
 	return imageKey, nil
 }
@@ -1174,15 +1170,13 @@ func uploadFileFromReader(ctx context.Context, runtime *common.RuntimeContext, r
 		return "", err
 	}
 
-	var result map[string]interface{}
-	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-		return "", fmt.Errorf("parse error: %w", err)
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return "", err
 	}
-
-	data, _ := result["data"].(map[string]interface{})
 	fileKey, _ := data["file_key"].(string)
 	if fileKey == "" {
-		return "", fmt.Errorf("file_key not found in response (code: %v, msg: %v)", result["code"], result["msg"])
+		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "file_key missing from a successful upload response")
 	}
 	return fileKey, nil
 }
@@ -1237,9 +1231,9 @@ func checkFlagRequiredScopes(ctx context.Context, rt *common.RuntimeContext, req
 	}
 	result, err := rt.Factory.Credential.ResolveToken(ctx, credential.NewTokenSpec(rt.As(), rt.Config.AppID))
 	if err != nil {
-		return output.ErrWithHint(output.ExitAuth, "auth",
-			fmt.Sprintf("cannot verify required scope(s): %v", err),
-			flagScopeLoginHint(required))
+		return errs.NewAuthenticationError(errs.SubtypeTokenMissing, "cannot verify required scope(s): %v", err).
+			WithHint("%s", flagScopeLoginHint(required)).
+			WithCause(err)
 	}
 	if result == nil || result.Scopes == "" {
 		fmt.Fprintf(rt.IO().ErrOut,
@@ -1248,9 +1242,9 @@ func checkFlagRequiredScopes(ctx context.Context, rt *common.RuntimeContext, req
 		return nil
 	}
 	if missing := auth.MissingScopes(result.Scopes, required); len(missing) > 0 {
-		return output.ErrWithHint(output.ExitAuth, "missing_scope",
-			fmt.Sprintf("missing required scope(s): %s", strings.Join(missing, ", ")),
-			flagScopeLoginHint(missing))
+		return errs.NewPermissionError(errs.SubtypeMissingScope, "missing required scope(s): %s", strings.Join(missing, ", ")).
+			WithMissingScopes(missing...).
+			WithHint("%s", flagScopeLoginHint(missing))
 	}
 	return nil
 }
@@ -1276,11 +1270,11 @@ func parseItemID(id string) (ItemType, FlagType, error) {
 	case strings.HasPrefix(id, "om_"):
 		return ItemTypeDefault, FlagTypeMessage, nil
 	case id == "":
-		return 0, 0, output.ErrValidation("--message-id cannot be empty")
+		return 0, 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "--message-id cannot be empty").WithParam("--message-id")
 	default:
-		return 0, 0, output.ErrValidation(
+		return 0, 0, errs.NewValidationError(errs.SubtypeInvalidArgument,
 			"cannot infer item type from id %q: expected om_ (message) prefix; "+
-				"pass --item-type and --flag-type explicitly if you are using a different id format", id)
+				"pass --item-type and --flag-type explicitly if you are using a different id format", id).WithParam("--message-id")
 	}
 }
 
@@ -1294,7 +1288,7 @@ func parseItemType(s string) (ItemType, error) {
 	case "msg_thread":
 		return ItemTypeMsgThread, nil
 	}
-	return 0, output.ErrValidation("invalid --item-type %q: expected one of default|thread|msg_thread", s)
+	return 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --item-type %q: expected one of default|thread|msg_thread", s).WithParam("--item-type")
 }
 
 // parseFlagType converts a user-facing string to the server enum.
@@ -1305,7 +1299,7 @@ func parseFlagType(s string) (FlagType, error) {
 	case "feed":
 		return FlagTypeFeed, nil
 	}
-	return 0, output.ErrValidation("invalid --flag-type %q: expected one of message|feed", s)
+	return 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --flag-type %q: expected one of message|feed", s).WithParam("--flag-type")
 }
 
 // isValidCombo checks if the (ItemType, FlagType) pair is accepted by the server.
@@ -1363,24 +1357,24 @@ func newFlagItem(itemID string, it ItemType, ft FlagType) flagItem {
 // getMessageChatID queries the message API to get the chat_id.
 // Used by flag-create to determine the chat type for feed-layer flags.
 func getMessageChatID(rt *common.RuntimeContext, messageID string) (string, error) {
-	data, err := rt.DoAPIJSON("GET", "/open-apis/im/v1/messages/"+validate.EncodePathSegment(messageID), nil, nil)
+	data, err := rt.DoAPIJSONTyped("GET", "/open-apis/im/v1/messages/"+validate.EncodePathSegment(messageID), nil, nil)
 	if err != nil {
 		return "", err
 	}
 
 	items, ok := data["items"].([]any)
 	if !ok || len(items) == 0 {
-		return "", output.ErrValidation("message not found or unexpected API response format")
+		return "", errs.NewAPIError(errs.SubtypeNotFound, "message not found")
 	}
 
 	msg, ok := items[0].(map[string]any)
 	if !ok {
-		return "", output.ErrValidation("unexpected message format in API response")
+		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "unexpected message format in API response")
 	}
 
 	chatID, ok := msg["chat_id"].(string)
 	if !ok {
-		return "", output.ErrValidation("message response missing chat_id field")
+		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "message response missing chat_id field")
 	}
 	return chatID, nil
 }
@@ -1393,15 +1387,324 @@ func getMessageChatID(rt *common.RuntimeContext, messageID string) (string, erro
 // Returns an error if the chat query fails, since guessing the wrong item_type
 // can cause silent failures in flag operations.
 func resolveThreadFeedItemType(rt *common.RuntimeContext, chatID string) (ItemType, error) {
-	data, err := rt.DoAPIJSON("GET", "/open-apis/im/v1/chats/"+validate.EncodePathSegment(chatID), nil, nil)
+	data, err := rt.DoAPIJSONTyped("GET", "/open-apis/im/v1/chats/"+validate.EncodePathSegment(chatID), nil, nil)
 	if err != nil {
-		return ItemTypeDefault, fmt.Errorf("failed to query chat_mode for chat %s: %w", chatID, err)
+		return ItemTypeDefault, wrapIMNetworkErr(err, "failed to query chat_mode for chat %s", chatID)
 	}
 
-	// DoAPIJSON returns envelope.Data, so chat_mode is at the top level
+	// DoAPIJSONTyped returns envelope.Data, so chat_mode is at the top level
 	chatMode, _ := data["chat_mode"].(string)
 	if chatMode == "topic" {
 		return ItemTypeThread, nil
 	}
 	return ItemTypeMsgThread, nil
 }
+
+// ShortcutType enumerates the OpenAPI feed-shortcut types.
+// Currently the server only opens CHAT (1) externally; other internal values
+// (DOC, OPENAPP, etc.) are not yet whitelisted on the OAPI gateway.
+type ShortcutType int
+
+const (
+	ShortcutTypeUnknown ShortcutType = 0
+	ShortcutTypeChat    ShortcutType = 1
+)
+
+const (
+	feedShortcutBatchLimit = 10
+	feedShortcutWriteScope = "im:feed.shortcut:write"
+	feedShortcutReadScope  = "im:feed.shortcut:read"
+)
+
+// shortcutItem is one entry in the feed_shortcuts API body.
+type shortcutItem struct {
+	FeedCardID string `json:"feed_card_id"`
+	Type       int    `json:"type"`
+}
+
+// collectChatIDs reads --chat-id values (repeatable + comma-split) and
+// returns deduped, validated oc_ IDs. The server batch limit is 10.
+func collectChatIDs(rt *common.RuntimeContext) ([]string, error) {
+	raw := rt.StrSlice("chat-id")
+	if len(raw) == 0 {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--chat-id is required (oc_xxx); repeat the flag or pass comma-separated values").WithParam("--chat-id")
+	}
+
+	seen := make(map[string]struct{}, len(raw))
+	out := make([]string, 0, len(raw))
+	for _, v := range raw {
+		v = strings.TrimSpace(v)
+		if v == "" {
+			continue
+		}
+		if !strings.HasPrefix(v, "oc_") {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"invalid --chat-id %q: must be an open_chat_id starting with oc_", v).WithParam("--chat-id")
+		}
+		if _, ok := seen[v]; ok {
+			continue
+		}
+		seen[v] = struct{}{}
+		out = append(out, v)
+	}
+	if len(out) == 0 {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--chat-id is required (oc_xxx)").WithParam("--chat-id")
+	}
+	if len(out) > feedShortcutBatchLimit {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"too many --chat-id values (%d); the server accepts up to %d per request",
+			len(out), feedShortcutBatchLimit).WithParam("--chat-id")
+	}
+	return out, nil
+}
+
+// buildShortcutItems converts chat IDs to API payload entries (type=CHAT).
+func buildShortcutItems(ids []string) []shortcutItem {
+	items := make([]shortcutItem, 0, len(ids))
+	for _, id := range ids {
+		items = append(items, shortcutItem{FeedCardID: id, Type: int(ShortcutTypeChat)})
+	}
+	return items
+}
+
+// shortcutFailedReasonString converts the numeric failed-reason enum returned
+// by the server into a human-readable label. Used to enrich the response
+// when the API reports per-item failures.
+func shortcutFailedReasonString(reason int) string {
+	switch reason {
+	case 0:
+		return "unknown"
+	case 1:
+		return "no_permission"
+	case 2:
+		return "invalid_item"
+	case 3:
+		return "has_pending_delete"
+	case 4:
+		return "type_not_support"
+	case 5:
+		return "internal_error"
+	}
+	return "unknown"
+}
+
+// chatBatchQueryScope is the scope required by im.chats.batch_query, which
+// the CHAT detail resolver depends on. Surfaced as a conditional scope on
+// +feed-shortcut-list so the framework's scope diagnostics know about it.
+const chatBatchQueryScope = "im:chat:read"
+
+// chatBatchQuerySize matches the server-side limit on /im/v1/chats/batch_query.
+const chatBatchQuerySize = 50
+
+// shortcutTypeFromValue parses the type field as returned by the v2
+// feed_shortcuts API. JSON numbers come back as float64 after generic
+// unmarshal; we also tolerate the int form for forward-compat.
+func shortcutTypeFromValue(v any) ShortcutType {
+	switch n := v.(type) {
+	case float64:
+		return ShortcutType(int(n))
+	case int:
+		return ShortcutType(n)
+	case json.Number:
+		i, err := n.Int64()
+		if err == nil {
+			return ShortcutType(i)
+		}
+	}
+	return ShortcutTypeUnknown
+}
+
+// queryChatBatch fetches one im.chats.batch_query page (at most
+// chatBatchQuerySize ids) and merges the full chat objects into dst keyed by
+// chat_id. Shared by feed-shortcut detail enrichment and message-search chat
+// context lookup, which apply their own per-chunk error policies.
+func queryChatBatch(rt *common.RuntimeContext, batch []string, dst map[string]map[string]any) error {
+	res, err := rt.DoAPIJSONTyped(http.MethodPost, "/open-apis/im/v1/chats/batch_query",
+		larkcore.QueryParams{"user_id_type": []string{"open_id"}},
+		map[string]any{"chat_ids": batch})
+	if err != nil {
+		return err
+	}
+	items, _ := res["items"].([]any)
+	for _, ci := range items {
+		cm, _ := ci.(map[string]any)
+		if cm == nil {
+			continue
+		}
+		if id := asString(cm["chat_id"]); id != "" {
+			dst[id] = cm
+		}
+	}
+	return nil
+}
+
+// resolveChatDetail batch-fetches the full chat object via
+// im.chats.batch_query (50 ids per request — server limit) and returns the
+// objects keyed by chat_id, verbatim, so the caller can decide which fields
+// to surface. The server's `name` field is empty for p2p chats (client UI
+// shows the partner's display name there), but the full object still carries
+// `chat_mode`, `p2p_target_id`, `description`, etc., so callers can render
+// p2p entries however they want.
+func resolveChatDetail(rt *common.RuntimeContext, ids []string) (map[string]map[string]any, error) {
+	out := map[string]map[string]any{}
+	if len(ids) == 0 {
+		return out, nil
+	}
+	if err := checkFlagRequiredScopes(rt.Ctx(), rt, []string{chatBatchQueryScope}); err != nil {
+		return nil, err
+	}
+	for _, batch := range chunkStrings(ids, chatBatchQuerySize) {
+		if err := queryChatBatch(rt, batch, out); err != nil {
+			return nil, err
+		}
+	}
+	return out, nil
+}
+
+// enrichFeedShortcutDetail walks the list response and attaches the full chat
+// object under `detail` for CHAT-type entries — the only type the OpenAPI
+// gateway exposes today. Mutates data in place.
+//
+// Failures are returned to the caller so it can decide whether to hard-fail
+// the command or downgrade to a warning. Listing the shortcuts succeeds even
+// if enrichment is unavailable (missing scope, network error, etc.).
+func enrichFeedShortcutDetail(rt *common.RuntimeContext, data map[string]any) error {
+	items, _ := data["shortcuts"].([]any)
+	if len(items) == 0 {
+		return nil
+	}
+
+	seen := map[string]struct{}{}
+	ids := make([]string, 0, len(items))
+	for _, it := range items {
+		m, _ := it.(map[string]any)
+		if m == nil || shortcutTypeFromValue(m["type"]) != ShortcutTypeChat {
+			continue
+		}
+		id := asString(m["feed_card_id"])
+		if id == "" {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	if len(ids) == 0 {
+		return nil
+	}
+
+	details, err := resolveChatDetail(rt, ids)
+	if err != nil {
+		return err
+	}
+
+	// Missing items (server didn't return one for an id we asked about) are
+	// left untouched, so the presence of `detail` signals a successful lookup.
+	for _, it := range items {
+		m, _ := it.(map[string]any)
+		if m == nil || shortcutTypeFromValue(m["type"]) != ShortcutTypeChat {
+			continue
+		}
+		if info, ok := details[asString(m["feed_card_id"])]; ok {
+			m["detail"] = info
+		}
+	}
+	return nil
+}
+
+// annotateFailedShortcuts walks the API response and attaches a
+// reason_label string next to each numeric reason. Mutates data in place.
+func annotateFailedShortcuts(data map[string]any) {
+	items, ok := data["failed_shortcuts"].([]any)
+	if !ok {
+		return
+	}
+	for _, it := range items {
+		m, _ := it.(map[string]any)
+		if m == nil {
+			continue
+		}
+		// reason is serialized as a JSON number → float64 after generic unmarshal.
+		switch r := m["reason"].(type) {
+		case float64:
+			m["reason_label"] = shortcutFailedReasonString(int(r))
+		case int:
+			m["reason_label"] = shortcutFailedReasonString(r)
+		case json.Number:
+			i, err := r.Int64()
+			if err == nil {
+				m["reason_label"] = shortcutFailedReasonString(int(i))
+			}
+		}
+	}
+}
+
+// emitFeedShortcutWriteResult preserves the server payload while adding a
+// batch ledger. A feed-shortcut write can return HTTP/API success with
+// failed_shortcuts populated; callers still need a complete account of which
+// requested entries succeeded and which failed.
+func emitFeedShortcutWriteResult(rt *common.RuntimeContext, requested []shortcutItem, data map[string]any) error {
+	// A fully-successful write can come back as code:0 with data:null, in
+	// which case DoAPIJSON hands us a nil map; the caller is still owed a
+	// ledger, so start from an empty object instead of panicking on write.
+	if data == nil {
+		data = map[string]any{}
+	}
+	annotateFailedShortcuts(data)
+	addFeedShortcutWriteLedger(data, requested)
+	if hasFailedShortcuts(data) {
+		return rt.OutPartialFailure(data, nil)
+	}
+	rt.Out(data, nil)
+	return nil
+}
+
+func addFeedShortcutWriteLedger(data map[string]any, requested []shortcutItem) {
+	failed := failedShortcutItems(data)
+	// Failed entries are matched back to requested items by feed_card_id
+	// alone: every requested item is CHAT-type, so the id is the identity,
+	// and a failed echo with a missing or zero type still excludes its item
+	// from the success list.
+	failedIDs := map[string]struct{}{}
+	for _, it := range failed {
+		m, _ := it.(map[string]any)
+		if m == nil {
+			continue
+		}
+		shortcut, _ := m["shortcut"].(map[string]any)
+		if shortcut == nil {
+			continue
+		}
+		if id := asString(shortcut["feed_card_id"]); id != "" {
+			failedIDs[id] = struct{}{}
+		}
+	}
+
+	succeeded := make([]shortcutItem, 0, len(requested))
+	for _, it := range requested {
+		if _, isFailed := failedIDs[it.FeedCardID]; isFailed {
+			continue
+		}
+		succeeded = append(succeeded, it)
+	}
+
+	// Counts are derived from the requested-item accounting alone so the
+	// success+failure==total invariant holds even if the server echoes a
+	// failed entry twice or reports one we never asked about;
+	// failed_shortcuts still carries the raw server report.
+	data["total"] = len(requested)
+	data["success_count"] = len(succeeded)
+	data["failure_count"] = len(requested) - len(succeeded)
+	data["succeeded_shortcuts"] = succeeded
+}
+
+func hasFailedShortcuts(data map[string]any) bool {
+	return len(failedShortcutItems(data)) > 0
+}
+
+func failedShortcutItems(data map[string]any) []any {
+	items, _ := data["failed_shortcuts"].([]any)
+	return items
+}