docs: tighten lark-sheets skill guidance

Validate the example commands embedded in shortcut definitions (the
"Example: lark-cli ..." lines in each shortcut's Tips, shown in --help)
against the real command tree built by cmd.Build. Implemented entirely as
test-only code in cmd/ (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 renamed command or unaccepted flag
in an example fails that job.

.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/calendar/helpers\.go|shortcuts/drive/|shortcuts/mail/)
         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/drive/|shortcuts/mail/|shortcuts/calendar/helpers\.go|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 is scoped to migrated domains: the shared helpers
+      # it bans are still used by other domains until their later migration phase.
+      - path-except: (shortcuts/drive/|shortcuts/mail/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo
@@ -115,17 +115,17 @@ linters:
           msg: >-
             [errs-typed-only] use errs.NewXxxError(...) builder
             (see errs/types.go).
-        # ── legacy shared error helpers banned on drive ──
+        # ── legacy shared error helpers banned on migrated domains ──
         # 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.
+        # are invisible to the errs-typed-only ban above. Migrated domains use
+        # typed errs.* builders or domain-local file-I/O helpers instead; this
+        # prevents reintroduction while unmigrated domains continue to use the
+        # shared helpers until their later migration phase.
         - pattern: (common\.FlagErrorf|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).
+            shapes. Use typed errs.NewXxxError builders or a domain-local
+            file-I/O helper.
         # ── 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/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:

internal/errclass/classify.go

@@ -244,6 +244,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 ""
 }

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/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

@@ -16,6 +16,7 @@ import (
 // common replacements or construct an errs.* typed error directly.
 var migratedCommonHelperPaths = []string{
 	"shortcuts/drive/",
+	"shortcuts/mail/",
 }
 
 const commonImportPath = "github.com/larksuite/cli/shortcuts/common"

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -17,6 +17,7 @@ import (
 // appending their path prefix here.
 var migratedEnvelopePaths = []string{
 	"shortcuts/drive/",
+	"shortcuts/mail/",
 }
 
 // legacyOutputImportPath is the import path of the package that declares the

lint/errscontract/rules_test.go

@@ -894,27 +894,33 @@ 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",
+	}
+	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)
+				}
+			})
+		}
 	}
 }
 

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/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/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/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/mail/body_file.go

@@ -8,7 +8,6 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -51,11 +50,15 @@ const maxBodyFileSize = 32 * 1024 * 1024 // 32 MB
 func validateBodyFileMutex(bodyFlag, bodyFile string, validatePath func(string) error) error {
 	bodyEmpty := strings.TrimSpace(bodyFlag) == ""
 	if !bodyEmpty && bodyFile != "" {
-		return output.ErrValidation("--body and --body-file are mutually exclusive; pass exactly one")
+		return mailValidationError("--body and --body-file are mutually exclusive; pass exactly one").
+			WithParams(
+				mailInvalidParam("--body", "mutually exclusive with --body-file"),
+				mailInvalidParam("--body-file", "mutually exclusive with --body"),
+			)
 	}
 	if bodyFile != "" {
 		if err := validatePath(bodyFile); err != nil {
-			return output.ErrValidation("--body-file: %v", err)
+			return mailValidationParamError("--body-file", "--body-file: %v", err).WithCause(err)
 		}
 	}
 	return nil
@@ -79,7 +82,7 @@ func resolveBodyFromFlags(runtime *common.RuntimeContext) (string, error) {
 
 func validateRequiredResolvedBody(body string, hasTemplate bool, message string) error {
 	if !hasTemplate && strings.TrimSpace(body) == "" {
-		return output.ErrValidation(message)
+		return mailValidationError("%s", message)
 	}
 	return nil
 }
@@ -95,15 +98,15 @@ func validateRequiredResolvedBody(body string, hasTemplate bool, message string)
 func readBodyFile(fio fileio.FileIO, path string) (string, error) {
 	f, err := fio.Open(path)
 	if err != nil {
-		return "", output.ErrValidation("open --body-file %s: %v", path, err)
+		return "", mailValidationParamError("--body-file", "open --body-file %s: %v", path, err).WithCause(mailInputStatError(err))
 	}
 	defer f.Close()
 	buf, err := io.ReadAll(io.LimitReader(f, maxBodyFileSize+1))
 	if err != nil {
-		return "", output.ErrValidation("read --body-file %s: %v", path, err)
+		return "", mailValidationParamError("--body-file", "read --body-file %s: %v", path, err).WithCause(err)
 	}
 	if len(buf) > maxBodyFileSize {
-		return "", output.ErrValidation("--body-file: file exceeds %d MB limit", maxBodyFileSize/1024/1024)
+		return "", mailValidationParamError("--body-file", "--body-file: file exceeds %d MB limit", maxBodyFileSize/1024/1024)
 	}
 	return string(buf), nil
 }

shortcuts/mail/draft/charset.go

@@ -49,7 +49,7 @@ func encodeTextCharset(body []byte, label string) ([]byte, error) {
 	}
 	enc, _ := htmlcharset.Lookup(label)
 	if enc == nil {
-		return nil, fmt.Errorf("unsupported charset %q", label)
+		return nil, fmt.Errorf("unsupported charset %q", label) //nolint:forbidigo // intermediate draft charset error; mail command layer wraps into typed ValidationError.
 	}
 	var buf bytes.Buffer
 	writer := transform.NewWriter(&buf, enc.NewEncoder())

shortcuts/mail/draft/large_attachment_parse.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//nolint:forbidigo // intermediate draft large-attachment parser errors; mail command layer wraps into typed ValidationError.
 package draft
 
 import (

shortcuts/mail/draft/limits.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//nolint:forbidigo // intermediate draft attachment limit errors; mail command layer wraps into typed ValidationError.
 package draft
 
 import (

shortcuts/mail/draft/model.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//nolint:forbidigo // intermediate draft patch model errors; mail command layer wraps into typed ValidationError.
 package draft
 
 import (

shortcuts/mail/draft/parse.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//nolint:forbidigo // intermediate draft EML parser errors; mail command layer wraps into typed ValidationError.
 package draft
 
 import (

shortcuts/mail/draft/patch.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//nolint:forbidigo // intermediate draft patch application errors; mail command layer wraps into typed ValidationError.
 package draft
 
 import (

shortcuts/mail/draft/patch_calendar.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//nolint:forbidigo // intermediate draft calendar patch errors; mail command layer wraps into typed ValidationError.
 package draft
 
 import (

shortcuts/mail/draft/serialize.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//nolint:forbidigo // intermediate draft serializer errors; mail command layer wraps into typed ValidationError.
 package draft
 
 import (

shortcuts/mail/draft/service.go

@@ -4,10 +4,10 @@
 package draft
 
 import (
-	"fmt"
 	"net/url"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -31,13 +31,13 @@ func mailboxPath(mailboxID string, segments ...string) string {
 // draft_id, the input draftID is echoed back so callers always have a
 // non-empty identifier to round-trip.
 func GetRaw(runtime *common.RuntimeContext, mailboxID, draftID string) (DraftRaw, error) {
-	data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "drafts", draftID), map[string]interface{}{"format": "raw"}, nil)
+	data, err := runtime.CallAPITyped("GET", mailboxPath(mailboxID, "drafts", draftID), map[string]interface{}{"format": "raw"}, nil)
 	if err != nil {
 		return DraftRaw{}, err
 	}
 	raw := extractRawEML(data)
 	if raw == "" {
-		return DraftRaw{}, fmt.Errorf("API response missing draft raw EML; the backend returned an empty raw body for this draft")
+		return DraftRaw{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "API response missing draft raw EML; the backend returned an empty raw body for this draft")
 	}
 	gotDraftID := extractDraftID(data)
 	if gotDraftID == "" {
@@ -55,13 +55,13 @@ func GetRaw(runtime *common.RuntimeContext, mailboxID, draftID string) (DraftRaw
 // assembled the EML with emlbuilder; for high-level compose paths use the
 // MailDraftCreate shortcut instead.
 func CreateWithRaw(runtime *common.RuntimeContext, mailboxID, rawEML string) (DraftResult, error) {
-	data, err := runtime.CallAPI("POST", mailboxPath(mailboxID, "drafts"), nil, map[string]interface{}{"raw": rawEML})
+	data, err := runtime.CallAPITyped("POST", mailboxPath(mailboxID, "drafts"), nil, map[string]interface{}{"raw": rawEML})
 	if err != nil {
 		return DraftResult{}, err
 	}
 	draftID := extractDraftID(data)
 	if draftID == "" {
-		return DraftResult{}, fmt.Errorf("API response missing draft_id")
+		return DraftResult{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "API response missing draft_id")
 	}
 	return DraftResult{
 		DraftID:   draftID,
@@ -76,7 +76,7 @@ func CreateWithRaw(runtime *common.RuntimeContext, mailboxID, rawEML string) (Dr
 // carries the (possibly re-issued) draft ID and the preview reference URL
 // when the backend provides one.
 func UpdateWithRaw(runtime *common.RuntimeContext, mailboxID, draftID, rawEML string) (DraftResult, error) {
-	data, err := runtime.CallAPI("PUT", mailboxPath(mailboxID, "drafts", draftID), nil, map[string]interface{}{"raw": rawEML})
+	data, err := runtime.CallAPITyped("PUT", mailboxPath(mailboxID, "drafts", draftID), nil, map[string]interface{}{"raw": rawEML})
 	if err != nil {
 		return DraftResult{}, err
 	}
@@ -99,7 +99,7 @@ func Send(runtime *common.RuntimeContext, mailboxID, draftID, sendTime string) (
 	if sendTime != "" {
 		bodyParams = map[string]interface{}{"send_time": sendTime}
 	}
-	return runtime.CallAPI("POST", mailboxPath(mailboxID, "drafts", draftID, "send"), nil, bodyParams)
+	return runtime.CallAPITyped("POST", mailboxPath(mailboxID, "drafts", draftID, "send"), nil, bodyParams)
 }
 
 // extractDraftID returns the first non-empty draft identifier found in the

shortcuts/mail/emlbuilder/builder.go

@@ -53,6 +53,7 @@ import (
 	"time"
 
 	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/mail/filecheck"
 )
 
@@ -61,9 +62,12 @@ const MaxEMLSize = 25 * 1024 * 1024 // 25 MB
 
 // readFile reads the named file and returns its contents via FileIO.
 func readFile(fio fileio.FileIO, path string) ([]byte, error) {
+	if _, err := validate.SafeInputPath(path); err != nil {
+		return nil, fmt.Errorf("attachment %q: %w", path, err) //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
+	}
 	f, err := fio.Open(path)
 	if err != nil {
-		return nil, fmt.Errorf("attachment %q: %w", path, err)
+		return nil, fmt.Errorf("attachment %q: %w", path, err) //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 	}
 	defer f.Close()
 	return io.ReadAll(f)
@@ -133,10 +137,10 @@ func New() Builder {
 func validateHeaderValue(v string) error {
 	for _, r := range v {
 		if r != '\t' && (r < 0x20 || r == 0x7f) {
-			return fmt.Errorf("emlbuilder: header value contains control character: %q", v)
+			return fmt.Errorf("emlbuilder: header value contains control character: %q", v) //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 		}
 		if isHeaderDangerousUnicode(r) {
-			return fmt.Errorf("emlbuilder: header value contains dangerous Unicode character: %q", v)
+			return fmt.Errorf("emlbuilder: header value contains dangerous Unicode character: %q", v) //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 		}
 	}
 	return nil
@@ -165,11 +169,11 @@ func isHeaderDangerousUnicode(r rune) bool {
 // or non-printable ASCII characters, as required by RFC 5322 field-name syntax.
 func validateHeaderName(n string) error {
 	if strings.ContainsAny(n, ":\r\n") {
-		return fmt.Errorf("emlbuilder: header name contains ':', CR, or LF: %q", n)
+		return fmt.Errorf("emlbuilder: header name contains ':', CR, or LF: %q", n) //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 	}
 	for _, r := range n {
 		if r < 0x21 || r > 0x7e {
-			return fmt.Errorf("emlbuilder: header name contains non-printable character: %q", n)
+			return fmt.Errorf("emlbuilder: header name contains non-printable character: %q", n) //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 		}
 	}
 	return nil
@@ -179,7 +183,7 @@ func validateHeaderName(n string) error {
 // escape the quoted-string encoding used by mail.Address.String() and inject headers.
 func validateDisplayName(name string) error {
 	if strings.ContainsAny(name, "\r\n") {
-		return fmt.Errorf("emlbuilder: display name contains CR or LF: %q", name)
+		return fmt.Errorf("emlbuilder: display name contains CR or LF: %q", name) //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 	}
 	return nil
 }
@@ -189,7 +193,7 @@ func validateDisplayName(name string) error {
 func validateCID(cid string) error {
 	for _, r := range cid {
 		if r < 0x20 || r == 0x7f {
-			return fmt.Errorf("emlbuilder: content ID contains control character: %q", cid)
+			return fmt.Errorf("emlbuilder: content ID contains control character: %q", cid) //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 		}
 	}
 	return nil
@@ -672,10 +676,10 @@ func (b Builder) Build() ([]byte, error) {
 		return nil, b.err
 	}
 	if b.from.Address == "" {
-		return nil, fmt.Errorf("emlbuilder: From address is required")
+		return nil, fmt.Errorf("emlbuilder: From address is required") //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 	}
 	if !b.allowNoRecipients && len(b.to)+len(b.cc)+len(b.bcc) == 0 {
-		return nil, fmt.Errorf("emlbuilder: at least one recipient (To/CC/BCC) is required")
+		return nil, fmt.Errorf("emlbuilder: at least one recipient (To/CC/BCC) is required") //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 	}
 
 	date := b.date
@@ -754,7 +758,7 @@ func (b Builder) Build() ([]byte, error) {
 
 	raw := buf.Bytes()
 	if len(raw) > MaxEMLSize {
-		return nil, fmt.Errorf("emlbuilder: EML size %.1f MB exceeds the %.0f MB limit",
+		return nil, fmt.Errorf("emlbuilder: EML size %.1f MB exceeds the %.0f MB limit", //nolint:forbidigo // intermediate EML builder error; mail command layer wraps into typed ValidationError.
 			float64(len(raw))/1024/1024, float64(MaxEMLSize)/1024/1024)
 	}
 	return raw, nil

shortcuts/mail/filecheck/filecheck.go

@@ -124,7 +124,7 @@ func CheckBlockedExtension(filename string) error {
 		return nil
 	}
 	if _, ok := blockedExtensions[ext]; ok {
-		return fmt.Errorf("file extension %q is not allowed as a mail attachment", "."+ext)
+		return fmt.Errorf("file extension %q is not allowed as a mail attachment", "."+ext) //nolint:forbidigo // intermediate mail file-format check; mail command layer wraps into typed ValidationError.
 	}
 	return nil
 }
@@ -156,7 +156,7 @@ var allowedInlineMIMETypes = map[string]struct{}{
 func CheckInlineImageFormat(filename string, content []byte) (string, error) {
 	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(filename), "."))
 	if _, ok := allowedInlineExtensions[ext]; !ok {
-		return "", fmt.Errorf("inline image extension %q is not allowed; supported formats: jpg, jpeg, png, gif, webp", ext)
+		return "", fmt.Errorf("inline image extension %q is not allowed; supported formats: jpg, jpeg, png, gif, webp", ext) //nolint:forbidigo // intermediate mail file-format check; mail command layer wraps into typed ValidationError.
 	}
 	detected := http.DetectContentType(content)
 	// DetectContentType may return params (e.g. "text/plain; charset=utf-8"),
@@ -165,7 +165,7 @@ func CheckInlineImageFormat(filename string, content []byte) (string, error) {
 		detected = strings.TrimSpace(detected[:i])
 	}
 	if _, ok := allowedInlineMIMETypes[detected]; !ok {
-		return "", fmt.Errorf("inline image content type %q does not match an allowed image format; supported: image/jpeg, image/png, image/gif, image/webp", detected)
+		return "", fmt.Errorf("inline image content type %q does not match an allowed image format; supported: image/jpeg, image/png, image/gif, image/webp", detected) //nolint:forbidigo // intermediate mail file-format check; mail command layer wraps into typed ValidationError.
 	}
 	return detected, nil
 }

shortcuts/mail/flag_suggest.go

@@ -11,7 +11,7 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 )
 
 // flagName is a package-private snapshot of a pflag.Flag's identity.
@@ -21,8 +21,7 @@ type flagName struct {
 }
 
 // Candidate is a single suggested flag returned to the user when an
-// unknown flag is detected. It is serialised into the ErrorEnvelope's
-// error.detail.candidates[] array.
+// unknown flag is detected.
 type Candidate struct {
 	// Flag is the long-form spelling of the suggested flag, e.g. "--to".
 	Flag string `json:"flag"`
@@ -56,9 +55,9 @@ func InstallOnMail(svc *cobra.Command) {
 	svc.SetFlagErrorFunc(flagSuggestErrorFunc)
 }
 
-// flagSuggestErrorFunc converts pflag's unknown-flag errors into a
-// structured *output.ExitError carrying candidate suggestions. Any other
-// error is passed through unchanged so cobra's existing handling kicks in.
+// flagSuggestErrorFunc converts pflag's unknown-flag errors into a typed
+// validation error carrying candidate suggestions. Any other error is passed
+// through unchanged so cobra's existing handling kicks in.
 func flagSuggestErrorFunc(c *cobra.Command, err error) error {
 	if err == nil {
 		return nil
@@ -83,22 +82,21 @@ func flagSuggestErrorFunc(c *cobra.Command, err error) error {
 		matches = []Candidate{}
 	}
 	hint := buildHint(c, matches)
-	detail := map[string]any{
-		"unknown":      rawUnknownToken(token, isShorthand),
-		"command_path": c.CommandPath(),
-		"candidates":   matches,
-	}
-	// Code is ExitAPI (=1), matching cobra's default unknown-flag exit
-	// code. The structured type discrimination lives in error.type.
-	return &output.ExitError{
-		Code: output.ExitAPI,
-		Detail: &output.ErrDetail{
-			Type:    "unknown_flag",
-			Message: err.Error(),
-			Hint:    hint,
-			Detail:  detail,
-		},
+	params := []errs.InvalidParam{{
+		Name:   rawUnknownToken(token, isShorthand),
+		Reason: "unknown flag",
+	}}
+	for _, match := range matches {
+		reason := fmt.Sprintf("candidate (%s, distance=%d)", match.Reason, match.Distance)
+		if match.Shorthand != "" {
+			reason += fmt.Sprintf(", shorthand=-%s", match.Shorthand)
+		}
+		params = append(params, errs.InvalidParam{Name: match.Flag, Reason: reason})
 	}
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, err.Error()).
+		WithHint("%s", hint).
+		WithParam(rawUnknownToken(token, isShorthand)).
+		WithParams(params...)
 }
 
 // parseUnknownToken extracts the offending flag name from a pflag error

shortcuts/mail/flag_suggest_test.go

@@ -11,7 +11,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 )
 
 // --- suggest (long-flag) ---
@@ -175,35 +175,41 @@ func newFakeMailCmd() *cobra.Command {
 	return c
 }
 
-func TestFlagSuggestErrorFunc_LongUnknown_ReturnsExitError(t *testing.T) {
+func requireFlagSuggestValidation(t *testing.T, got error) *errs.ValidationError {
+	t.Helper()
+	var validationErr *errs.ValidationError
+	require.True(t, errors.As(got, &validationErr), "expected *errs.ValidationError, got %T", got)
+	p, ok := errs.ProblemOf(got)
+	require.True(t, ok, "expected typed Problem")
+	assert.Equal(t, errs.CategoryValidation, p.Category)
+	assert.Equal(t, errs.SubtypeInvalidArgument, p.Subtype)
+	return validationErr
+}
+
+func paramReason(params []errs.InvalidParam, name string) (string, bool) {
+	for _, p := range params {
+		if p.Name == name {
+			return p.Reason, true
+		}
+	}
+	return "", false
+}
+
+func TestFlagSuggestErrorFunc_LongUnknown_ReturnsTypedValidation(t *testing.T) {
 	cmd := newFakeMailCmd()
 	got := flagSuggestErrorFunc(cmd, errors.New("unknown flag: --tos"))
 
-	var exitErr *output.ExitError
-	require.True(t, errors.As(got, &exitErr), "expected *output.ExitError, got %T", got)
-	require.NotNil(t, exitErr.Detail)
-	assert.Equal(t, "unknown_flag", exitErr.Detail.Type)
-	assert.Equal(t, "unknown flag: --tos", exitErr.Detail.Message)
-	assert.Contains(t, exitErr.Detail.Hint, "--to")
+	validationErr := requireFlagSuggestValidation(t, got)
+	assert.Equal(t, "unknown flag: --tos", validationErr.Message)
+	assert.Equal(t, "--tos", validationErr.Param)
+	assert.Contains(t, validationErr.Hint, "--to")
 
-	detail, ok := exitErr.Detail.Detail.(map[string]any)
-	require.True(t, ok, "Detail.Detail should be map[string]any")
-	assert.Equal(t, "--tos", detail["unknown"])
-	assert.Equal(t, cmd.CommandPath(), detail["command_path"])
-
-	cands, ok := detail["candidates"].([]Candidate)
-	require.True(t, ok, "candidates should be []Candidate")
-	require.NotEmpty(t, cands)
-
-	var foundTo bool
-	for _, c := range cands {
-		if c.Flag == "--to" {
-			foundTo = true
-			assert.Equal(t, "prefix", c.Reason)
-			break
-		}
-	}
-	assert.True(t, foundTo, "expected --to in candidates")
+	reason, ok := paramReason(validationErr.Params, "--tos")
+	require.True(t, ok, "unknown flag should be included in params")
+	assert.Equal(t, "unknown flag", reason)
+	reason, ok = paramReason(validationErr.Params, "--to")
+	require.True(t, ok, "expected --to in candidate params")
+	assert.Contains(t, reason, "candidate (prefix")
 }
 
 func TestFlagSuggestErrorFunc_NotUnknownFlag_PassesThrough(t *testing.T) {
@@ -214,14 +220,13 @@ func TestFlagSuggestErrorFunc_NotUnknownFlag_PassesThrough(t *testing.T) {
 	assert.Same(t, in, got, "non-unknown-flag errors must be returned unchanged")
 }
 
-func TestFlagSuggestErrorFunc_ExitCodeIsOne(t *testing.T) {
+func TestFlagSuggestErrorFunc_TypedCategoryAndSubtype(t *testing.T) {
 	cmd := newFakeMailCmd()
 	got := flagSuggestErrorFunc(cmd, errors.New("unknown flag: --tos"))
-	var exitErr *output.ExitError
-	require.True(t, errors.As(got, &exitErr))
-	// Hard contract — both compile-time and runtime guards:
-	assert.Equal(t, output.ExitAPI, exitErr.Code, "unknown_flag must use ExitAPI, not ExitValidation")
-	assert.Equal(t, 1, output.ExitAPI, "ExitAPI constant must remain 1")
+	p, ok := errs.ProblemOf(got)
+	require.True(t, ok)
+	assert.Equal(t, errs.CategoryValidation, p.Category)
+	assert.Equal(t, errs.SubtypeInvalidArgument, p.Subtype)
 }
 
 // --- edge-case coverage ---
@@ -236,9 +241,8 @@ func TestInstallOnMail_InstallsHook(t *testing.T) {
 	InstallOnMail(c)
 	require.NotNil(t, c.FlagErrorFunc())
 	got := c.FlagErrorFunc()(c, errors.New("unknown flag: --tos"))
-	var exitErr *output.ExitError
-	require.True(t, errors.As(got, &exitErr), "installed hook must produce *output.ExitError")
-	assert.Equal(t, "unknown_flag", exitErr.Detail.Type)
+	validationErr := requireFlagSuggestValidation(t, got)
+	assert.Equal(t, "--tos", validationErr.Param)
 }
 
 func TestFlagSuggestErrorFunc_NilError(t *testing.T) {
@@ -249,50 +253,47 @@ func TestFlagSuggestErrorFunc_NilError(t *testing.T) {
 func TestFlagSuggestErrorFunc_LongUnknown_StripsValueTail(t *testing.T) {
 	cmd := newFakeMailCmd()
 	got := flagSuggestErrorFunc(cmd, errors.New("unknown flag: --tos=alice@example.com"))
-	var exitErr *output.ExitError
-	require.True(t, errors.As(got, &exitErr))
-	detail := exitErr.Detail.Detail.(map[string]any)
-	assert.Equal(t, "--tos", detail["unknown"], "value tail must be stripped before echoing")
+	validationErr := requireFlagSuggestValidation(t, got)
+	assert.Equal(t, "--tos", validationErr.Param, "value tail must be stripped before echoing")
+	reason, ok := paramReason(validationErr.Params, "--tos")
+	require.True(t, ok)
+	assert.Equal(t, "unknown flag", reason)
 }
 
 func TestFlagSuggestErrorFunc_ShorthandUnknown(t *testing.T) {
 	cmd := newFakeMailCmd()
 	got := flagSuggestErrorFunc(cmd, errors.New("unknown shorthand flag: 'b' in -bXY"))
-	var exitErr *output.ExitError
-	require.True(t, errors.As(got, &exitErr))
-	detail := exitErr.Detail.Detail.(map[string]any)
-	assert.Equal(t, "-b", detail["unknown"])
-	cands, ok := detail["candidates"].([]Candidate)
+	validationErr := requireFlagSuggestValidation(t, got)
+	assert.Equal(t, "-b", validationErr.Param)
+	reason, ok := paramReason(validationErr.Params, "-b")
 	require.True(t, ok)
+	assert.Equal(t, "unknown flag", reason)
 	// newFakeMailCmd has --body/-b; exact shorthand hit expected.
-	require.NotEmpty(t, cands)
-	assert.Equal(t, "--body", cands[0].Flag)
-	assert.Equal(t, "b", cands[0].Shorthand)
+	reason, ok = paramReason(validationErr.Params, "--body")
+	require.True(t, ok)
+	assert.Contains(t, reason, "candidate (prefix")
+	assert.Contains(t, reason, "shorthand=-b")
 }
 
-func TestFlagSuggestErrorFunc_CandidatesAlwaysArray(t *testing.T) {
+func TestFlagSuggestErrorFunc_ParamsAlwaysPresent(t *testing.T) {
 	// A cobra command with no flags forces collectFlags → empty names →
-	// suggest → nil. The envelope must still expose candidates as a
-	// non-nil []Candidate so the JSON wire shape is "candidates: []"
-	// rather than "candidates: null".
+	// suggest → nil. The typed validation error must still expose the unknown
+	// flag in Params so downstream parsers have a stable structured field.
 	bare := &cobra.Command{Use: "mail"}
 	got := flagSuggestErrorFunc(bare, errors.New("unknown flag: --bogus"))
-	var exitErr *output.ExitError
-	require.True(t, errors.As(got, &exitErr))
-	detail := exitErr.Detail.Detail.(map[string]any)
-	cands, ok := detail["candidates"].([]Candidate)
-	require.True(t, ok, "candidates must be []Candidate even when empty")
-	assert.NotNil(t, cands, "candidates must be non-nil empty slice, not nil")
-	assert.Empty(t, cands)
+	validationErr := requireFlagSuggestValidation(t, got)
+	assert.NotNil(t, validationErr.Params)
+	require.Len(t, validationErr.Params, 1)
+	assert.Equal(t, "--bogus", validationErr.Params[0].Name)
+	assert.Equal(t, "unknown flag", validationErr.Params[0].Reason)
 }
 
 func TestFlagSuggestErrorFunc_NoCandidatesUsesHelpHint(t *testing.T) {
 	cmd := newFakeMailCmd()
 	// Token with no plausible neighbor in {to, cc, subject, body}.
 	got := flagSuggestErrorFunc(cmd, errors.New("unknown flag: --zzzzzzz"))
-	var exitErr *output.ExitError
-	require.True(t, errors.As(got, &exitErr))
-	assert.Contains(t, exitErr.Detail.Hint, "--help")
+	validationErr := requireFlagSuggestValidation(t, got)
+	assert.Contains(t, validationErr.Hint, "--help")
 }
 
 func TestParseUnknownToken_EmptyAndMalformed(t *testing.T) {

shortcuts/mail/helpers.go

@@ -6,6 +6,7 @@ package mail
 import (
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"mime"
@@ -21,7 +22,6 @@ import (
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
@@ -111,7 +111,7 @@ func requireSenderForRequestReceipt(runtime *common.RuntimeContext, senderEmail
 		return nil
 	}
 	if strings.TrimSpace(senderEmail) == "" {
-		return output.ErrValidation(
+		return mailValidationError(
 			"--request-receipt requires a resolvable sender address; specify a sender address where supported, or ensure the draft has a From address")
 	}
 	return nil
@@ -130,10 +130,10 @@ func requireSenderForRequestReceipt(runtime *common.RuntimeContext, senderEmail
 func validateHeaderAddress(addr string) error {
 	for _, r := range addr {
 		if r != '\t' && (r < 0x20 || r == 0x7f) {
-			return fmt.Errorf("address contains control character: %q", addr)
+			return mailValidationError("address contains control character: %q", addr)
 		}
 		if common.IsDangerousUnicode(r) {
-			return fmt.Errorf("address contains dangerous Unicode code point: %q", addr)
+			return mailValidationError("address contains dangerous Unicode code point: %q", addr)
 		}
 	}
 	return nil
@@ -324,7 +324,7 @@ func fetchMailboxPrimaryEmail(runtime *common.RuntimeContext, mailboxID string)
 	if mailboxID == "" {
 		mailboxID = "me"
 	}
-	data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "profile"), nil, nil)
+	data, err := runtime.CallAPITyped("GET", mailboxPath(mailboxID, "profile"), nil, nil)
 	if err != nil {
 		return "", err
 	}
@@ -336,7 +336,7 @@ func fetchMailboxPrimaryEmail(runtime *common.RuntimeContext, mailboxID string)
 			return email, nil
 		}
 	}
-	return "", fmt.Errorf("profile API returned no primary_email_address")
+	return "", mailInvalidResponseError("profile API returned no primary_email_address")
 }
 
 // extractPrimaryEmail returns the user's primary email address from a
@@ -503,12 +503,14 @@ func resolveFolderID(runtime *common.RuntimeContext, mailboxID, input string) (s
 	if err != nil {
 		return "", err
 	}
-	return resolveByID("folder", value, mailboxID, folders, func(item folderInfo) string { return item.ID })
+	return resolveByName("folder", value, mailboxID, folders,
+		func(item folderInfo) string { return item.ID },
+		func(item folderInfo) string { return item.Name },
+	)
 }
 
 // resolveFolderName accepts either a folder ID or a folder name and returns
-// the human-readable folder name. Used for output rendering where the user
-// wants to see the name they originally chose, not the opaque ID.
+// the canonical folder ID.
 func resolveFolderName(runtime *common.RuntimeContext, mailboxID, input string) (string, error) {
 	value := strings.TrimSpace(input)
 	if value == "" {
@@ -542,11 +544,14 @@ func resolveLabelID(runtime *common.RuntimeContext, mailboxID, input string) (st
 	if err != nil {
 		return "", err
 	}
-	return resolveByID("label", value, mailboxID, labels, func(item labelInfo) string { return item.ID })
+	return resolveByName("label", value, mailboxID, labels,
+		func(item labelInfo) string { return item.ID },
+		func(item labelInfo) string { return item.Name },
+	)
 }
 
 // resolveLabelName accepts either a label ID or a label name and returns
-// the human-readable label name (mirror of resolveFolderName for labels).
+// the canonical label ID (mirror of resolveFolderName for labels).
 func resolveLabelName(runtime *common.RuntimeContext, mailboxID, input string) (string, error) {
 	value := strings.TrimSpace(input)
 	if value == "" {
@@ -846,9 +851,11 @@ func listMailboxFolders(runtime *common.RuntimeContext, mailboxID string) ([]fol
 	if err := validateFolderReadScope(runtime); err != nil {
 		return nil, err
 	}
-	data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "folders"), nil, nil)
+	data, err := runtime.CallAPITyped("GET", mailboxPath(mailboxID, "folders"), nil, nil)
 	if err != nil {
-		return nil, output.ErrValidation("unable to resolve --folder: failed to list folders (%v). %s", err, resolveLookupHint("folder", mailboxID))
+		return nil, mailAppendProblemHint(
+			mailDecorateProblemMessage(err, "unable to resolve --folder: failed to list folders"),
+			resolveLookupHint("folder", mailboxID))
 	}
 	items, _ := data["items"].([]interface{})
 	folders := make([]folderInfo, 0, len(items))
@@ -871,9 +878,11 @@ func listMailboxLabels(runtime *common.RuntimeContext, mailboxID string) ([]labe
 	if err := validateLabelReadScope(runtime); err != nil {
 		return nil, err
 	}
-	data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "labels"), nil, nil)
+	data, err := runtime.CallAPITyped("GET", mailboxPath(mailboxID, "labels"), nil, nil)
 	if err != nil {
-		return nil, output.ErrValidation("unable to resolve --label: failed to list labels (%v). %s", err, resolveLookupHint("label", mailboxID))
+		return nil, mailAppendProblemHint(
+			mailDecorateProblemMessage(err, "unable to resolve --label: failed to list labels"),
+			resolveLookupHint("label", mailboxID))
 	}
 	items, _ := data["items"].([]interface{})
 	labels := make([]labelInfo, 0, len(items))
@@ -891,26 +900,9 @@ func listMailboxLabels(runtime *common.RuntimeContext, mailboxID string) ([]labe
 	return labels, nil
 }
 
-// resolveByID looks up input as an ID in items, returning input itself when
-// found. kind ("folder" / "label") and mailboxID are used to construct the
-// not-found hint. Generic over T so the same logic serves both folder and
-// label tables.
-func resolveByID[T any](kind, input, mailboxID string, items []T, idFn func(T) string) (string, error) {
-	value := strings.TrimSpace(input)
-	if value == "" {
-		return "", nil
-	}
-	for _, item := range items {
-		if id := idFn(item); id != "" && id == value {
-			return id, nil
-		}
-	}
-	return "", output.ErrValidation("%s %q not_exists. %s", kind, value, resolveLookupHint(kind, mailboxID))
-}
-
-// resolveByName looks up input as a name in items and returns the matching
-// ID. Errors out on duplicates so callers get a clear "ambiguous name"
-// signal rather than silently picking one match.
+// resolveByName looks up input as an exact ID first, then as a name, and
+// returns the matching ID. Errors out on duplicate names so callers get a clear
+// "ambiguous name" signal rather than silently picking one match.
 func resolveByName[T any](kind, input, mailboxID string, items []T, idFn func(T) string, nameFn func(T) string) (string, error) {
 	value := strings.TrimSpace(input)
 	if value == "" {
@@ -919,7 +911,7 @@ func resolveByName[T any](kind, input, mailboxID string, items []T, idFn func(T)
 
 	for _, item := range items {
 		if id := idFn(item); id != "" && id == value {
-			return "", output.ErrValidation("%s %q looks like an ID; please use %s_id", kind, value, kind)
+			return id, nil
 		}
 	}
 
@@ -943,9 +935,9 @@ func resolveByName[T any](kind, input, mailboxID string, items []T, idFn func(T)
 		return matches[0], nil
 	}
 	if len(matches) > 1 {
-		return "", output.ErrValidation("%s name %q matches multiple IDs (%s); please use an ID", kind, value, strings.Join(matches, ","))
+		return "", mailValidationError("%s name %q matches multiple IDs (%s); please use an ID", kind, value, strings.Join(matches, ","))
 	}
-	return "", output.ErrValidation("%s %q not_exists. %s", kind, value, resolveLookupHint(kind, mailboxID))
+	return "", mailValidationError("%s %q not_exists. %s", kind, value, resolveLookupHint(kind, mailboxID))
 }
 
 // resolveNameValueByID is the inverse of resolveByID: it looks up an ID
@@ -959,18 +951,18 @@ func resolveNameValueByID[T any](kind, input, mailboxID string, items []T, idFn
 		if id := idFn(item); id != "" && id == value {
 			name := strings.TrimSpace(nameFn(item))
 			if name == "" {
-				return "", output.ErrValidation("%s %q has empty name; cannot use it with query filters", kind, value)
+				return "", mailValidationError("%s %q has empty name; cannot use it with query filters", kind, value)
 			}
 			return name, nil
 		}
 	}
-	return "", output.ErrValidation("%s %q not_exists. %s", kind, value, resolveLookupHint(kind, mailboxID))
+	return "", mailValidationError("%s %q not_exists. %s", kind, value, resolveLookupHint(kind, mailboxID))
 }
 
-// resolveNameValueByNameAllowDuplicates is like resolveByName but tolerates
-// duplicate names — returning the first match. Used in query-style contexts
-// where ambiguity is acceptable because the API itself disambiguates server-
-// side.
+// resolveNameValueByNameAllowDuplicates looks up input as an exact ID first,
+// then as a name, and returns the matching name. Duplicate names are tolerated
+// by returning the first match. Used in query-style contexts where ambiguity is
+// acceptable because the API itself disambiguates server-side.
 func resolveNameValueByNameAllowDuplicates[T any](kind, input, mailboxID string, items []T, idFn func(T) string, nameFn func(T) string) (string, error) {
 	value := strings.TrimSpace(input)
 	if value == "" {
@@ -978,7 +970,11 @@ func resolveNameValueByNameAllowDuplicates[T any](kind, input, mailboxID string,
 	}
 	for _, item := range items {
 		if id := idFn(item); id != "" && id == value {
-			return "", output.ErrValidation("%s %q looks like an ID; please use %s_id", kind, value, kind)
+			name := strings.TrimSpace(nameFn(item))
+			if name == "" {
+				return "", mailValidationError("%s %q has empty name; cannot use it with query filters", kind, value)
+			}
+			return name, nil
 		}
 	}
 	lower := strings.ToLower(value)
@@ -989,7 +985,7 @@ func resolveNameValueByNameAllowDuplicates[T any](kind, input, mailboxID string,
 		}
 		return name, nil
 	}
-	return "", output.ErrValidation("%s %q not_exists. %s", kind, value, resolveLookupHint(kind, mailboxID))
+	return "", mailValidationError("%s %q not_exists. %s", kind, value, resolveLookupHint(kind, mailboxID))
 }
 
 // resolveLookupHint returns the CLI command a user should run to list
@@ -1015,13 +1011,13 @@ func resolveLookupHint(kind, mailboxID string) string {
 // html=false -> format=plain_text_full (server omits body_html)
 func fetchFullMessage(runtime *common.RuntimeContext, mailboxID, messageID string, html bool) (map[string]interface{}, error) {
 	params := map[string]interface{}{"format": messageGetFormat(html)}
-	data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "messages", messageID), params, nil)
+	data, err := runtime.CallAPITyped("GET", mailboxPath(mailboxID, "messages", messageID), params, nil)
 	if err != nil {
 		return nil, err
 	}
 	msg, _ := data["message"].(map[string]interface{})
 	if msg == nil {
-		return nil, fmt.Errorf("API response missing message field")
+		return nil, mailInvalidResponseError("API response missing message field")
 	}
 	return msg, nil
 }
@@ -1039,7 +1035,7 @@ func fetchFullMessages(runtime *common.RuntimeContext, mailboxID string, message
 		if end > len(messageIDs) {
 			end = len(messageIDs)
 		}
-		data, err := runtime.CallAPI("POST", mailboxPath(mailboxID, "messages", "batch_get"), nil, map[string]interface{}{
+		data, err := runtime.CallAPITyped("POST", mailboxPath(mailboxID, "messages", "batch_get"), nil, map[string]interface{}{
 			"format":      messageGetFormat(html),
 			"message_ids": messageIDs[start:end],
 		})
@@ -1232,7 +1228,7 @@ type calendarEventOutput struct {
 // It never returns an error: failed batches/IDs are converted to structured warnings so caller can continue.
 func fetchAttachmentURLs(runtime *common.RuntimeContext, mailboxID, messageID string, ids []string) (map[string]string, []warningEntry) {
 	callAPI := func(url string) (map[string]interface{}, error) {
-		return runtime.CallAPI("GET", url, nil, nil)
+		return runtime.CallAPITyped("GET", url, nil, nil)
 	}
 	emitWarning := func(w warningEntry) {
 		fmt.Fprintf(runtime.IO().ErrOut, "warning: code=%s message_id=%s attachment_id=%s retryable=%t detail=%s\n", w.Code, w.MessageID, w.AttachmentID, w.Retryable, w.Detail)
@@ -1668,7 +1664,7 @@ func validateForwardAttachmentURLs(src composeSourceMessage) error {
 		}
 	}
 	if len(missing) > 0 {
-		return fmt.Errorf("failed to fetch download URLs for: %s", strings.Join(missing, ", "))
+		return mailInvalidResponseError("failed to fetch download URLs for: %s", strings.Join(missing, ", "))
 	}
 	return nil
 }
@@ -1683,7 +1679,7 @@ func validateInlineImageURLs(src composeSourceMessage) error {
 		}
 	}
 	if len(missing) > 0 {
-		return fmt.Errorf("failed to fetch download URLs for: %s", strings.Join(missing, ", "))
+		return mailInvalidResponseError("failed to fetch download URLs for: %s", strings.Join(missing, ", "))
 	}
 	return nil
 }
@@ -1786,41 +1782,51 @@ func toInlineSourceParts(out normalizedMessageForCompose) []inlineSourcePart {
 func downloadAttachmentContent(runtime *common.RuntimeContext, downloadURL string) ([]byte, error) {
 	u, err := url.Parse(downloadURL)
 	if err != nil {
-		return nil, fmt.Errorf("invalid attachment download URL: %w", err)
+		return nil, mailInvalidResponseError("invalid attachment download URL: %v", err).WithCause(err)
 	}
 	if u.Scheme != "https" {
-		return nil, fmt.Errorf("attachment download URL must use https (got %q)", u.Scheme)
+		return nil, mailInvalidResponseError("attachment download URL must use https (got %q)", u.Scheme)
 	}
 	if u.Host == "" {
-		return nil, fmt.Errorf("attachment download URL has no host")
+		return nil, mailInvalidResponseError("attachment download URL has no host")
 	}
 
 	httpClient, err := runtime.Factory.HttpClient()
 	if err != nil {
-		return nil, fmt.Errorf("failed to get HTTP client: %w", err)
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "failed to get HTTP client: %v", err).WithCause(err)
 	}
 	req, err := http.NewRequestWithContext(runtime.Ctx(), http.MethodGet, downloadURL, nil)
 	if err != nil {
-		return nil, fmt.Errorf("failed to build attachment download request: %w", err)
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "failed to build attachment download request: %v", err).WithCause(err)
 	}
 	// Do NOT send Authorization: the download_url is a pre-signed URL with an
 	// authcode embedded in the query string. Attaching the Bearer token would
 	// leak it to whatever host the URL points at (SSRF / token exfiltration).
 	resp, err := httpClient.Do(req)
 	if err != nil {
-		return nil, fmt.Errorf("failed to download attachment: %w", err)
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "failed to download attachment: %v", err).WithCause(err)
 	}
 	defer resp.Body.Close()
 	if resp.StatusCode >= 400 {
-		return nil, fmt.Errorf("failed to download attachment: HTTP %d", resp.StatusCode)
+		if resp.StatusCode >= 500 {
+			return nil, errs.NewNetworkError(errs.SubtypeNetworkServer, "failed to download attachment: HTTP %d", resp.StatusCode).
+				WithCode(resp.StatusCode).
+				WithRetryable()
+		}
+		subtype := errs.SubtypeUnknown
+		if resp.StatusCode == http.StatusNotFound {
+			subtype = errs.SubtypeNotFound
+		}
+		return nil, errs.NewAPIError(subtype, "failed to download attachment: HTTP %d", resp.StatusCode).WithCode(resp.StatusCode)
 	}
 	limitedReader := io.LimitReader(resp.Body, int64(MaxAttachmentDownloadBytes)+1)
 	data, err := io.ReadAll(limitedReader)
 	if err != nil {
-		return nil, fmt.Errorf("failed to read attachment content: %w", err)
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "failed to read attachment content: %v", err).WithCause(err)
 	}
 	if len(data) > MaxAttachmentDownloadBytes {
-		return nil, fmt.Errorf("attachment download exceeds %d MB size limit", MaxAttachmentDownloadBytes/1024/1024)
+		return nil, mailFailedPreconditionError("attachment download exceeds %d MB size limit", MaxAttachmentDownloadBytes/1024/1024).
+			WithHint("download or forward this large attachment outside the inline/small-attachment path")
 	}
 	return data, nil
 }
@@ -2062,7 +2068,7 @@ func parsePriority(value string) (string, error) {
 	case "low":
 		return "5", nil
 	default:
-		return "", fmt.Errorf("invalid --priority value %q: expected high, normal, or low", value)
+		return "", mailValidationParamError("--priority", "invalid --priority value %q: expected high, normal, or low", value)
 	}
 }
 
@@ -2232,7 +2238,7 @@ func validateInlineCIDs(html string, userCIDs, extraCIDs []string) error {
 	if len(userCIDs) > 0 {
 		orphaned := draftpkg.FindOrphanedCIDs(html, userCIDs)
 		if len(orphaned) > 0 {
-			return fmt.Errorf("inline images with cids %v are not referenced by any <img src=\"cid:...\"> in the HTML body and will appear as unexpected attachments; remove unused --inline entries or add matching <img> tags", orphaned)
+			return mailValidationParamError("--inline", "inline images with cids %v are not referenced by any <img src=\"cid:...\"> in the HTML body and will appear as unexpected attachments; remove unused --inline entries or add matching <img> tags", orphaned)
 		}
 	}
 	return nil
@@ -2251,7 +2257,7 @@ func addInlineImagesToBuilder(runtime *common.RuntimeContext, bld emlbuilder.Bui
 	for _, img := range images {
 		content, err := downloadAttachmentContent(runtime, img.DownloadURL)
 		if err != nil {
-			return bld, nil, 0, fmt.Errorf("failed to download inline resource %s: %w", img.Filename, err)
+			return bld, nil, 0, mailDecorateProblemMessage(err, "failed to download inline resource %s", img.Filename)
 		}
 		cid := normalizeInlineCID(img.CID)
 		if cid == "" {
@@ -2284,14 +2290,14 @@ func parseInlineSpecs(raw string) ([]InlineSpec, error) {
 	}
 	var specs []InlineSpec
 	if err := json.Unmarshal([]byte(raw), &specs); err != nil {
-		return nil, fmt.Errorf("--inline must be a JSON array, e.g. '[{\"cid\":\"a1b2c3d4e5f6a7b8c9d0\",\"file_path\":\"./banner.png\"}]': %w", err)
+		return nil, mailValidationParamError("--inline", "--inline must be a JSON array, e.g. '[{\"cid\":\"a1b2c3d4e5f6a7b8c9d0\",\"file_path\":\"./banner.png\"}]': %v", err).WithCause(err)
 	}
 	for i, s := range specs {
 		if strings.TrimSpace(s.CID) == "" {
-			return nil, fmt.Errorf("--inline entry %d: \"cid\" must not be empty", i)
+			return nil, mailValidationParamError("--inline", "--inline entry %d: \"cid\" must not be empty", i)
 		}
 		if strings.TrimSpace(s.FilePath) == "" {
-			return nil, fmt.Errorf("--inline entry %d: \"file_path\" must not be empty", i)
+			return nil, mailValidationParamError("--inline", "--inline entry %d: \"file_path\" must not be empty", i)
 		}
 	}
 	return specs, nil
@@ -2318,7 +2324,11 @@ func validateEventSendTimeExclusion(runtime *common.RuntimeContext) error {
 	}
 	for _, f := range []string{"event-summary", "event-start", "event-end", "event-location"} {
 		if runtime.Str(f) != "" {
-			return common.FlagErrorf("--send-time and --event-* are mutually exclusive: a calendar invitation must be sent immediately so recipients can respond before the event")
+			return mailValidationError("--send-time and --event-* are mutually exclusive: a calendar invitation must be sent immediately so recipients can respond before the event").
+				WithParams(
+					mailInvalidParam("--send-time", "mutually exclusive with --event-*"),
+					mailInvalidParam("--event-*", "mutually exclusive with --send-time"),
+				)
 		}
 	}
 	return nil
@@ -2332,15 +2342,15 @@ func validateSendTime(runtime *common.RuntimeContext) error {
 		return nil
 	}
 	if !runtime.Bool("confirm-send") {
-		return output.ErrValidation("--send-time requires --confirm-send to be set")
+		return mailValidationParamError("--send-time", "--send-time requires --confirm-send to be set")
 	}
 	ts, err := strconv.ParseInt(sendTime, 10, 64)
 	if err != nil {
-		return output.ErrValidation("--send-time must be a valid Unix timestamp in seconds, got %q", sendTime)
+		return mailValidationParamError("--send-time", "--send-time must be a valid Unix timestamp in seconds, got %q", sendTime).WithCause(err)
 	}
 	minTime := time.Now().Unix() + 5*60
 	if ts < minTime {
-		return output.ErrValidation("--send-time must be at least 5 minutes in the future (minimum: %d, got: %d)", minTime, ts)
+		return mailValidationParamError("--send-time", "--send-time must be at least 5 minutes in the future (minimum: %d, got: %d)", minTime, ts)
 	}
 	return nil
 }
@@ -2429,7 +2439,12 @@ func validateLabelReadScope(runtime *common.RuntimeContext) error {
 // all three (to/cc/bcc) are empty or whitespace-only.
 func validateComposeHasAtLeastOneRecipient(to, cc, bcc string) error {
 	if strings.TrimSpace(to) == "" && strings.TrimSpace(cc) == "" && strings.TrimSpace(bcc) == "" {
-		return fmt.Errorf("at least one recipient (--to, --cc, or --bcc) is required")
+		return mailValidationError("at least one recipient (--to, --cc, or --bcc) is required").
+			WithParams(
+				mailInvalidParam("--to", "at least one recipient is required"),
+				mailInvalidParam("--cc", "at least one recipient is required"),
+				mailInvalidParam("--bcc", "at least one recipient is required"),
+			)
 	}
 	return validateRecipientCount(to, cc, bcc)
 }
@@ -2439,7 +2454,12 @@ func validateComposeHasAtLeastOneRecipient(to, cc, bcc string) error {
 func validateRecipientCount(to, cc, bcc string) error {
 	count := len(ParseMailboxList(to)) + len(ParseMailboxList(cc)) + len(ParseMailboxList(bcc))
 	if count > MaxRecipientCount {
-		return fmt.Errorf("total recipient count %d exceeds the limit of %d (To + CC + BCC combined)", count, MaxRecipientCount)
+		return mailValidationError("total recipient count %d exceeds the limit of %d (To + CC + BCC combined)", count, MaxRecipientCount).
+			WithParams(
+				mailInvalidParam("--to", "recipient count contributes to combined limit"),
+				mailInvalidParam("--cc", "recipient count contributes to combined limit"),
+				mailInvalidParam("--bcc", "recipient count contributes to combined limit"),
+			)
 	}
 	return nil
 }
@@ -2451,10 +2471,14 @@ func validateRecipientCount(to, cc, bcc string) error {
 func validateComposeInlineAndAttachments(fio fileio.FileIO, attachFlag, inlineFlag string, plainText bool, body string) error {
 	if strings.TrimSpace(inlineFlag) != "" {
 		if plainText {
-			return output.ErrValidation("--inline is not supported with --plain-text (inline images require HTML body)")
+			return mailValidationError("--inline is not supported with --plain-text (inline images require HTML body)").
+				WithParams(
+					mailInvalidParam("--inline", "requires HTML body"),
+					mailInvalidParam("--plain-text", "mutually exclusive with --inline"),
+				)
 		}
 		if body != "" && !bodyIsHTML(body) {
-			return output.ErrValidation("--inline requires an HTML body (the provided body appears to be plain text; add HTML tags or remove --inline)")
+			return mailValidationParamError("--inline", "--inline requires an HTML body (the provided body appears to be plain text; add HTML tags or remove --inline)")
 		}
 	}
 	inlineSpecs, err := parseInlineSpecs(inlineFlag)
@@ -2536,7 +2560,12 @@ func validateEventFlags(runtime *common.RuntimeContext) error {
 	hasAll := summary != "" && start != "" && end != ""
 
 	if hasAny && !hasAll {
-		return output.ErrValidation("--event-summary, --event-start, and --event-end must all be provided together")
+		return mailValidationError("--event-summary, --event-start, and --event-end must all be provided together").
+			WithParams(
+				mailInvalidParam("--event-summary", "required with --event-start/--event-end"),
+				mailInvalidParam("--event-start", "required with --event-summary/--event-end"),
+				mailInvalidParam("--event-end", "required with --event-summary/--event-start"),
+			)
 	}
 	if summary == "" {
 		return nil
@@ -2553,14 +2582,14 @@ func validateEventFlags(runtime *common.RuntimeContext) error {
 func parseEventTimeRange(start, end string) (time.Time, time.Time, error) {
 	startT, err := parseISO8601(start)
 	if err != nil {
-		return time.Time{}, time.Time{}, fmt.Errorf("start: invalid ISO 8601 time %q", start)
+		return time.Time{}, time.Time{}, mailValidationError("start: invalid ISO 8601 time %q", start).WithCause(err)
 	}
 	endT, err := parseISO8601(end)
 	if err != nil {
-		return time.Time{}, time.Time{}, fmt.Errorf("end: invalid ISO 8601 time %q", end)
+		return time.Time{}, time.Time{}, mailValidationError("end: invalid ISO 8601 time %q", end).WithCause(err)
 	}
 	if !endT.After(startT) {
-		return time.Time{}, time.Time{}, fmt.Errorf("end time must be after start time")
+		return time.Time{}, time.Time{}, mailValidationError("end time must be after start time")
 	}
 	return startT, endT, nil
 }
@@ -2569,12 +2598,27 @@ func parseEventTimeRange(start, end string) (time.Time, time.Time, error) {
 // error with the caller's flag-name prefix so users see the exact flag
 // that caused the failure.
 func prefixEventRangeError(flagPrefix string, err error) error {
-	msg := err.Error()
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		return err
+	}
+	var validationErr *errs.ValidationError
+	msg := p.Message
 	switch {
 	case strings.HasPrefix(msg, "start: "):
-		return fmt.Errorf("%sstart: %s", flagPrefix, strings.TrimPrefix(msg, "start: "))
+		p.Message = fmt.Sprintf("%sstart: %s", flagPrefix, strings.TrimPrefix(msg, "start: "))
+		p.Subtype = errs.SubtypeInvalidArgument
+		if strings.HasPrefix(flagPrefix, "--") && errors.As(err, &validationErr) {
+			validationErr.Param = flagPrefix + "start"
+		}
+		return err
 	case strings.HasPrefix(msg, "end: "):
-		return fmt.Errorf("%send: %s", flagPrefix, strings.TrimPrefix(msg, "end: "))
+		p.Message = fmt.Sprintf("%send: %s", flagPrefix, strings.TrimPrefix(msg, "end: "))
+		p.Subtype = errs.SubtypeInvalidArgument
+		if strings.HasPrefix(flagPrefix, "--") && errors.As(err, &validationErr) {
+			validationErr.Param = flagPrefix + "end"
+		}
+		return err
 	default:
 		return err
 	}
@@ -2595,7 +2639,7 @@ func parseISO8601(s string) (time.Time, error) {
 			return t, nil
 		}
 	}
-	return time.Time{}, fmt.Errorf("cannot parse %q as ISO 8601", s)
+	return time.Time{}, mailValidationError("cannot parse %q as ISO 8601", s)
 }
 
 // buildCalendarBody generates an ICS VCALENDAR from compose flags and returns the bytes.
@@ -2614,8 +2658,8 @@ func buildCalendarBody(runtime *common.RuntimeContext, senderEmail string, toAdd
 // bot uses tenant access token; "me" cannot be resolved to a user mailbox under TAT.
 func validateBotMailboxNotMe(runtime *common.RuntimeContext) error {
 	if runtime.IsBot() && runtime.Str("mailbox") == "me" {
-		return output.ErrValidation(
-			"--as bot does not support --mailbox me: bot identity uses a tenant token and cannot resolve \"me\" to a user mailbox; " +
+		return mailValidationParamError("--mailbox",
+			"--as bot does not support --mailbox me: bot identity uses a tenant token and cannot resolve \"me\" to a user mailbox; "+
 				"pass an explicit email address, e.g. --mailbox alice@example.com")
 	}
 	return nil
@@ -2627,7 +2671,7 @@ func validateBotMailboxNotMe(runtime *common.RuntimeContext) error {
 // fetchFullMessages chunks backend requests into batches of 20.
 func validateMessageIDs(raw string) ([]string, error) {
 	if strings.TrimSpace(raw) == "" {
-		return nil, output.ErrValidation("--message-ids is required; provide one or more message IDs separated by commas")
+		return nil, mailValidationParamError("--message-ids", "--message-ids is required; provide one or more message IDs separated by commas")
 	}
 	parts := strings.Split(raw, ",")
 	ids := make([]string, 0, len(parts))
@@ -2635,16 +2679,16 @@ func validateMessageIDs(raw string) ([]string, error) {
 	for i, part := range parts {
 		id := strings.TrimSpace(part)
 		if id == "" {
-			return nil, output.ErrValidation("--message-ids entry %d is empty; remove extra commas or provide valid message IDs", i+1)
+			return nil, mailValidationParamError("--message-ids", "--message-ids entry %d is empty; remove extra commas or provide valid message IDs", i+1)
 		}
 		if part != id {
-			return nil, output.ErrValidation("--message-ids entry %d (%q): must not contain leading or trailing whitespace", i+1, part)
+			return nil, mailValidationParamError("--message-ids", "--message-ids entry %d (%q): must not contain leading or trailing whitespace", i+1, part)
 		}
 		if err := validateBatchGetMessageID(id, i); err != nil {
 			return nil, err
 		}
 		if _, ok := seen[id]; ok {
-			return nil, output.ErrValidation("--message-ids entry %d (%q): duplicate message ID is not allowed", i+1, id)
+			return nil, mailValidationParamError("--message-ids", "--message-ids entry %d (%q): duplicate message ID is not allowed", i+1, id)
 		}
 		seen[id] = struct{}{}
 		ids = append(ids, id)
@@ -2654,11 +2698,14 @@ func validateMessageIDs(raw string) ([]string, error) {
 
 func validateBatchGetMessageID(id string, index int) error {
 	if strings.Trim(id, "0123456789") == "" {
-		return output.ErrValidation("--message-ids entry %d (%q): numeric primary IDs are not supported by mail +messages; pass the Open API message_id from mail output", index+1, id)
+		return mailValidationParamError("--message-ids", "--message-ids entry %d (%q): numeric primary IDs are not supported by mail +messages; pass the Open API message_id from mail output", index+1, id)
 	}
-	decoded, err := base64.URLEncoding.DecodeString(id)
-	if err != nil || len(decoded) == 0 {
-		return output.ErrValidation("--message-ids entry %d (%q): expected a base64url Open API mail message_id from mail output", index+1, id)
+	decoded, rawErr := base64.RawURLEncoding.DecodeString(id)
+	if rawErr != nil {
+		decoded, rawErr = base64.URLEncoding.DecodeString(id)
+	}
+	if rawErr != nil || len(decoded) == 0 {
+		return mailValidationParamError("--message-ids", "--message-ids entry %d (%q): expected a base64url Open API mail message_id from mail output", index+1, id)
 	}
 	return nil
 }

shortcuts/mail/helpers_test.go

@@ -1353,6 +1353,34 @@ func TestValidateComposeInlineAndAttachments(t *testing.T) {
 	})
 }
 
+func TestResolveByNameAcceptsExactID(t *testing.T) {
+	folders := []folderInfo{{ID: "fld_custom", Name: "Team"}}
+	got, err := resolveByName("folder", "fld_custom", "me", folders,
+		func(item folderInfo) string { return item.ID },
+		func(item folderInfo) string { return item.Name },
+	)
+	if err != nil {
+		t.Fatalf("resolveByName returned error: %v", err)
+	}
+	if got != "fld_custom" {
+		t.Fatalf("resolveByName exact ID = %q, want fld_custom", got)
+	}
+}
+
+func TestResolveNameValueByNameAllowDuplicatesAcceptsExactID(t *testing.T) {
+	folders := []folderInfo{{ID: "fld_custom", Name: "Parent/Team"}}
+	got, err := resolveNameValueByNameAllowDuplicates("folder", "fld_custom", "me", folders,
+		func(item folderInfo) string { return item.ID },
+		func(item folderInfo) string { return item.Name },
+	)
+	if err != nil {
+		t.Fatalf("resolveNameValueByNameAllowDuplicates returned error: %v", err)
+	}
+	if got != "Parent/Team" {
+		t.Fatalf("query name for exact ID = %q, want Parent/Team", got)
+	}
+}
+
 // newRequestReceiptRuntime registers the --request-receipt bool flag alone
 // (no --from), so requireSenderForRequestReceipt tests can drive the flag
 // directly without pulling in unrelated compose plumbing.
@@ -1522,16 +1550,16 @@ func TestParseEventTimeRange_InvalidEnd(t *testing.T) {
 }
 
 func TestPrefixEventRangeError(t *testing.T) {
-	start := fmt.Errorf("start: invalid ISO 8601 time %q", "x")
+	start := mailValidationError("start: invalid ISO 8601 time %q", "x")
 	if got := prefixEventRangeError("--event-", start).Error(); got != `--event-start: invalid ISO 8601 time "x"` {
 		t.Errorf("got %q", got)
 	}
-	end := fmt.Errorf("end: invalid ISO 8601 time %q", "x")
+	end := mailValidationError("end: invalid ISO 8601 time %q", "x")
 	if got := prefixEventRangeError("--set-event-", end).Error(); got != `--set-event-end: invalid ISO 8601 time "x"` {
 		t.Errorf("got %q", got)
 	}
 	// Non-prefixed error passes through unchanged.
-	other := fmt.Errorf("end time must be after start time")
+	other := mailValidationError("end time must be after start time")
 	if got := prefixEventRangeError("--event-", other).Error(); got != "end time must be after start time" {
 		t.Errorf("got %q", got)
 	}

shortcuts/mail/large_attachment.go

@@ -14,6 +14,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -121,11 +122,11 @@ func statAttachmentFiles(fio fileio.FileIO, paths []string) ([]attachmentFile, e
 		}
 		name := filepath.Base(p)
 		if err := filecheck.CheckBlockedExtension(name); err != nil {
-			return nil, err
+			return nil, mailValidationError("%v", err).WithCause(err)
 		}
 		info, err := fio.Stat(p)
 		if err != nil {
-			return nil, fmt.Errorf("failed to stat attachment %s: %w", p, err)
+			return nil, mailInputStatError(err)
 		}
 		files = append(files, attachmentFile{
 			Path:     p,
@@ -144,7 +145,7 @@ func uploadLargeAttachments(ctx context.Context, runtime *common.RuntimeContext,
 	}
 	userOpenId := runtime.UserOpenId()
 	if userOpenId == "" {
-		return nil, fmt.Errorf("large attachment upload requires user identity (user open_id not available)")
+		return nil, mailFailedPreconditionError("large attachment upload requires user identity (user open_id not available)")
 	}
 
 	results := make([]largeAttachmentResult, 0, len(files))
@@ -156,7 +157,7 @@ func uploadLargeAttachments(ctx context.Context, runtime *common.RuntimeContext,
 			err       error
 		)
 		if f.Data != nil {
-			fileToken, err = common.UploadDriveMediaAll(runtime, common.DriveMediaUploadAllConfig{
+			fileToken, err = common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
 				FileName:   f.FileName,
 				FileSize:   f.Size,
 				ParentType: "email",
@@ -164,7 +165,7 @@ func uploadLargeAttachments(ctx context.Context, runtime *common.RuntimeContext,
 				Reader:     bytes.NewReader(f.Data),
 			})
 		} else if f.Size <= common.MaxDriveMediaUploadSinglePartSize {
-			fileToken, err = common.UploadDriveMediaAll(runtime, common.DriveMediaUploadAllConfig{
+			fileToken, err = common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
 				FilePath:   f.Path,
 				FileName:   f.FileName,
 				FileSize:   f.Size,
@@ -172,7 +173,7 @@ func uploadLargeAttachments(ctx context.Context, runtime *common.RuntimeContext,
 				ParentNode: &userOpenId,
 			})
 		} else {
-			fileToken, err = common.UploadDriveMediaMultipart(runtime, common.DriveMediaMultipartUploadConfig{
+			fileToken, err = common.UploadDriveMediaMultipartTyped(runtime, common.DriveMediaMultipartUploadConfig{
 				FilePath:   f.Path,
 				FileName:   f.FileName,
 				FileSize:   f.Size,
@@ -181,7 +182,7 @@ func uploadLargeAttachments(ctx context.Context, runtime *common.RuntimeContext,
 			})
 		}
 		if err != nil {
-			return nil, fmt.Errorf("failed to upload large attachment %s: %w", f.FileName, err)
+			return nil, mailDecorateProblemMessage(err, "failed to upload large attachment %s", f.FileName)
 		}
 
 		results = append(results, largeAttachmentResult{
@@ -397,7 +398,7 @@ func processLargeAttachments(
 ) (emlbuilder.Builder, error) {
 	totalCount := extraAttachCount + len(attachPaths)
 	if totalCount > MaxAttachmentCount {
-		return bld, fmt.Errorf("attachment count %d exceeds the limit of %d", totalCount, MaxAttachmentCount)
+		return bld, mailFailedPreconditionError("attachment count %d exceeds the limit of %d", totalCount, MaxAttachmentCount)
 	}
 
 	files, err := statAttachmentFiles(runtime.FileIO(), attachPaths)
@@ -407,7 +408,7 @@ func processLargeAttachments(
 
 	for _, f := range files {
 		if f.Size > MaxLargeAttachmentSize {
-			return bld, fmt.Errorf("attachment %s (%.1f GB) exceeds the %.0f GB single file limit",
+			return bld, mailFailedPreconditionError("attachment %s (%.1f GB) exceeds the %.0f GB single file limit",
 				f.FileName, float64(f.Size)/1024/1024/1024, float64(MaxLargeAttachmentSize)/1024/1024/1024)
 		}
 	}
@@ -422,7 +423,7 @@ func processLargeAttachments(
 	}
 
 	if htmlBody == "" && textBody == "" {
-		return bld, fmt.Errorf("large attachments require a body; " +
+		return bld, mailFailedPreconditionError("large attachments require a body; " +
 			"empty messages cannot include the download link")
 	}
 
@@ -431,7 +432,7 @@ func processLargeAttachments(
 		for _, f := range files {
 			totalBytes += f.Size
 		}
-		return bld, fmt.Errorf("total attachment size %.1f MB exceeds the 25 MB EML limit; "+
+		return bld, mailFailedPreconditionError("total attachment size %.1f MB exceeds the 25 MB EML limit; "+
 			"large attachment upload requires user identity (--as user)",
 			float64(totalBytes)/1024/1024)
 	}
@@ -455,7 +456,7 @@ func processLargeAttachments(
 	}
 	idsJSON, err := json.Marshal(ids)
 	if err != nil {
-		return bld, fmt.Errorf("failed to encode large attachment IDs: %w", err)
+		return bld, errs.NewInternalError(errs.SubtypeSDKError, "failed to encode large attachment IDs: %v", err).WithCause(err)
 	}
 	bld = bld.Header(draftpkg.LargeAttachmentIDsHeader, base64.StdEncoding.EncodeToString(idsJSON))
 
@@ -588,7 +589,7 @@ func preprocessLargeAttachmentsForDraftEdit(
 	// Check 3GB single file limit.
 	for _, f := range files {
 		if f.Size > MaxLargeAttachmentSize {
-			return patch, fmt.Errorf("attachment %s (%.1f GB) exceeds the %.0f GB single file limit",
+			return patch, mailFailedPreconditionError("attachment %s (%.1f GB) exceeds the %.0f GB single file limit",
 				f.FileName, float64(f.Size)/1024/1024/1024, float64(MaxLargeAttachmentSize)/1024/1024/1024)
 		}
 	}
@@ -606,7 +607,7 @@ func preprocessLargeAttachmentsForDraftEdit(
 	hasHTML := draftpkg.FindHTMLBodyPart(snapshot.Body) != nil
 	hasText := draftpkg.FindTextBodyPart(snapshot.Body) != nil
 	if !hasHTML && !hasText {
-		return patch, fmt.Errorf("large attachments require a body; " +
+		return patch, mailFailedPreconditionError("large attachments require a body; " +
 			"empty drafts cannot include the download link")
 	}
 
@@ -616,7 +617,7 @@ func preprocessLargeAttachmentsForDraftEdit(
 		for _, f := range files {
 			totalBytes += f.Size
 		}
-		return patch, fmt.Errorf("total attachment size %.1f MB exceeds the 25 MB EML limit; "+
+		return patch, mailFailedPreconditionError("total attachment size %.1f MB exceeds the 25 MB EML limit; "+
 			"large attachment upload requires user identity (--as user)",
 			float64(totalBytes)/1024/1024)
 	}
@@ -672,7 +673,7 @@ func preprocessLargeAttachmentsForDraftEdit(
 	}
 	idsJSON, err := json.Marshal(merged)
 	if err != nil {
-		return patch, fmt.Errorf("failed to encode large attachment IDs: %w", err)
+		return patch, errs.NewInternalError(errs.SubtypeSDKError, "failed to encode large attachment IDs: %v", err).WithCause(err)
 	}
 	headerValue := base64.StdEncoding.EncodeToString(idsJSON)
 	if existingIdx >= 0 {

shortcuts/mail/large_attachment_test.go

@@ -974,7 +974,7 @@ func TestStatAttachmentFiles_FileNotFound(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for missing file")
 	}
-	if !strings.Contains(err.Error(), "failed to stat") {
+	if !strings.Contains(err.Error(), "cannot read file") {
 		t.Errorf("unexpected error: %v", err)
 	}
 }

shortcuts/mail/lint/linter.go

@@ -395,8 +395,7 @@ func sanitiseStyleAttr(raw string) (cleaned string, dropped []string) {
 	return cleaned, dropped
 }
 
-// hintForBlockedTag returns a hint for an error-blocked tag (matching
-// the `output.ErrWithHint` convention used elsewhere in the cli).
+// hintForBlockedTag returns a hint for an error-blocked tag.
 func hintForBlockedTag(tag string) string {
 	switch tag {
 	case "script":

shortcuts/mail/mail_decline_receipt.go

@@ -59,7 +59,7 @@ var MailDeclineReceipt = common.Shortcut{
 
 		msg, err := fetchFullMessage(runtime, mailboxID, messageID, false)
 		if err != nil {
-			return fmt.Errorf("failed to fetch original message: %w", err)
+			return mailDecorateProblemMessage(err, "failed to fetch original message")
 		}
 
 		out := map[string]interface{}{
@@ -77,14 +77,14 @@ var MailDeclineReceipt = common.Shortcut{
 			return nil
 		}
 
-		if _, err := runtime.CallAPI("PUT",
+		if _, err := runtime.CallAPITyped("PUT",
 			mailboxPath(mailboxID, "messages", messageID, "modify"),
 			nil,
 			map[string]interface{}{
 				"remove_label_ids": []string{readReceiptRequestLabel},
 			},
 		); err != nil {
-			return fmt.Errorf("failed to clear READ_RECEIPT_REQUEST label: %w", err)
+			return mailDecorateProblemMessage(err, "failed to clear READ_RECEIPT_REQUEST label")
 		}
 
 		out["declined"] = true

shortcuts/mail/mail_draft_create.go

@@ -9,7 +9,6 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
 	"github.com/larksuite/cli/shortcuts/mail/emlbuilder"
@@ -91,7 +90,7 @@ var MailDraftCreate = common.Shortcut{
 			return err
 		}
 		if !hasTemplate && strings.TrimSpace(runtime.Str("subject")) == "" {
-			return output.ErrValidation("--subject is required; pass the final email subject (or use --template-id)")
+			return mailValidationParamError("--subject", "--subject is required; pass the final email subject (or use --template-id)")
 		}
 		if err := validateSignatureWithPlainText(runtime.Bool("plain-text"), runtime.Str("signature-id")); err != nil {
 			return err
@@ -176,10 +175,10 @@ var MailDraftCreate = common.Shortcut{
 			})
 		}
 		if strings.TrimSpace(input.Subject) == "" {
-			return output.ErrValidation("effective subject is empty after applying template; pass --subject explicitly")
+			return mailValidationParamError("--subject", "effective subject is empty after applying template; pass --subject explicitly")
 		}
 		if strings.TrimSpace(input.Body) == "" {
-			return output.ErrValidation("effective body is empty after applying template; pass --body explicitly")
+			return mailValidationParamError("--body", "effective body is empty after applying template; pass --body explicitly")
 		}
 		sigResult, err := resolveSignature(ctx, runtime, mailboxID, runtime.Str("signature-id"), runtime.Str("from"))
 		if err != nil {
@@ -192,7 +191,7 @@ var MailDraftCreate = common.Shortcut{
 		}
 		draftResult, err := draftpkg.CreateWithRaw(runtime, mailboxID, rawEML)
 		if err != nil {
-			return fmt.Errorf("create draft failed: %w", err)
+			return mailDecorateProblemMessage(err, "create draft failed")
 		}
 		out := map[string]interface{}{"draft_id": draftResult.DraftID}
 		if draftResult.Reference != "" {
@@ -250,7 +249,7 @@ func buildRawEMLForDraftCreate(
 
 	senderEmail := resolveComposeSenderEmail(runtime)
 	if senderEmail == "" {
-		return "", lintApplied, lintBlocked, fmt.Errorf("unable to determine sender email; please specify --from explicitly")
+		return "", lintApplied, lintBlocked, mailValidationParamError("--from", "unable to determine sender email; please specify --from explicitly")
 	}
 
 	if err := validateRecipientCount(input.To, input.CC, input.BCC); err != nil {
@@ -285,7 +284,7 @@ func buildRawEMLForDraftCreate(
 	}
 	inlineSpecs, parseErr := parseInlineSpecs(input.Inline)
 	if parseErr != nil {
-		return "", lintApplied, lintBlocked, output.ErrValidation("%v", parseErr)
+		return "", lintApplied, lintBlocked, parseErr
 	}
 	var autoResolvedPaths []string
 	var composedHTMLBody string
@@ -300,7 +299,7 @@ func buildRawEMLForDraftCreate(
 		}
 		resolved, refs, resolveErr := draftpkg.ResolveLocalImagePaths(htmlBody)
 		if resolveErr != nil {
-			return "", lintApplied, lintBlocked, resolveErr
+			return "", lintApplied, lintBlocked, mailValidationError("failed to resolve local image paths: %v", resolveErr).WithCause(resolveErr)
 		}
 		resolved = injectSignatureIntoBody(resolved, sigResult)
 		// Writing-path lint: AutoFix=true / Strict=false — the writing-path
@@ -365,7 +364,7 @@ func buildRawEMLForDraftCreate(
 	}
 	rawEML, buildErr := bld.BuildBase64URL()
 	if buildErr != nil {
-		return "", lintApplied, lintBlocked, output.ErrValidation("build EML failed: %v", buildErr)
+		return "", lintApplied, lintBlocked, mailValidationError("build EML failed: %v", buildErr).WithCause(buildErr)
 	}
 	return rawEML, lintApplied, lintBlocked, nil
 }

shortcuts/mail/mail_draft_edit.go

@@ -10,7 +10,6 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
 	"github.com/larksuite/cli/shortcuts/mail/ics"
@@ -88,7 +87,7 @@ var MailDraftEdit = common.Shortcut{
 		}
 		draftID := runtime.Str("draft-id")
 		if draftID == "" {
-			return output.ErrValidation("--draft-id is required for real draft edits; if you only need a patch template, run with --print-patch-template")
+			return mailValidationParamError("--draft-id", "--draft-id is required for real draft edits; if you only need a patch template, run with --print-patch-template")
 		}
 		mailboxID := resolveComposeMailboxID(runtime)
 		if runtime.Bool("inspect") {
@@ -100,11 +99,11 @@ var MailDraftEdit = common.Shortcut{
 		}
 		rawDraft, err := draftpkg.GetRaw(runtime, mailboxID, draftID)
 		if err != nil {
-			return fmt.Errorf("read draft raw EML failed: %w", err)
+			return mailDecorateProblemMessage(err, "read draft raw EML failed")
 		}
 		snapshot, err := draftpkg.Parse(rawDraft)
 		if err != nil {
-			return output.ErrValidation("parse draft raw EML failed: %v", err)
+			return mailFailedPreconditionError("parse draft raw EML failed: %v", err).WithCause(err)
 		}
 		// Pre-process ops that need snapshot context: resolve signature using
 		// the draft's From address, and build ICS for set_calendar using the
@@ -123,8 +122,8 @@ var MailDraftEdit = common.Shortcut{
 			// Going straight into PatchOp.Value would bypass emlbuilder's
 			// validateHeaderValue gate, so repeat the check here explicitly.
 			if err := validateHeaderAddress(draftFromEmail); err != nil {
-				return output.ErrValidation(
-					"cannot set --request-receipt: draft From address is unsafe for a header (%v)", err)
+				return mailFailedPreconditionError(
+					"cannot set --request-receipt: draft From address is unsafe for a header (%v)", err).WithCause(err)
 			}
 			patch.Ops = append(patch.Ops, draftpkg.PatchOp{
 				Op:    "set_header",
@@ -147,11 +146,11 @@ var MailDraftEdit = common.Shortcut{
 				if calPart := draftpkg.FindPartByMediaType(snapshot.Body, "text/calendar"); calPart != nil {
 					parsed := ics.ParseEvent(string(calPart.Body))
 					if parsed == nil || !parsed.IsLarkDraft {
-						return output.ErrValidation("set_calendar: calendar event has already been created and is read-only; use --remove-event to remove it, then --set-event-* to create a new one")
+						return mailFailedPreconditionError("set_calendar: calendar event has already been created and is read-only; use --remove-event to remove it, then --set-event-* to create a new one")
 					}
 				}
 				if _, _, err := parseEventTimeRange(patch.Ops[i].EventStart, patch.Ops[i].EventEnd); err != nil {
-					return output.ErrValidation("set_calendar: %v", err)
+					return prefixEventRangeError("set_calendar: ", err)
 				}
 				// Derive effective To/Cc by replaying all pending recipient ops so
 				// the ICS ATTENDEE list matches the final post-edit recipients.
@@ -166,7 +165,7 @@ var MailDraftEdit = common.Shortcut{
 					joinAddresses(ccAddrs),
 				)
 				if calData == nil {
-					return output.ErrValidation("set_calendar: failed to build ICS from event fields")
+					return mailValidationError("set_calendar: failed to build ICS from event fields")
 				}
 				patch.Ops[i].CalendarICS = calData
 			}
@@ -206,16 +205,16 @@ var MailDraftEdit = common.Shortcut{
 		dctx := &draftpkg.DraftCtx{FIO: runtime.FileIO()}
 		if len(patch.Ops) > 0 {
 			if err := draftpkg.Apply(dctx, snapshot, patch); err != nil {
-				return output.ErrValidation("apply draft patch failed: %v", err)
+				return mailValidationError("apply draft patch failed: %v", err).WithCause(err)
 			}
 		}
 		serialized, err := draftpkg.Serialize(snapshot)
 		if err != nil {
-			return output.ErrValidation("serialize draft failed: %v", err)
+			return mailValidationError("serialize draft failed: %v", err).WithCause(err)
 		}
 		updateResult, err := draftpkg.UpdateWithRaw(runtime, mailboxID, draftID, serialized)
 		if err != nil {
-			return fmt.Errorf("update draft failed: %w", err)
+			return mailDecorateProblemMessage(err, "update draft failed")
 		}
 		projection := draftpkg.Project(snapshot)
 		out := map[string]interface{}{
@@ -270,11 +269,11 @@ var MailDraftEdit = common.Shortcut{
 func executeDraftInspect(runtime *common.RuntimeContext, mailboxID, draftID string) error {
 	rawDraft, err := draftpkg.GetRaw(runtime, mailboxID, draftID)
 	if err != nil {
-		return fmt.Errorf("read draft raw EML failed: %w", err)
+		return mailDecorateProblemMessage(err, "read draft raw EML failed")
 	}
 	snapshot, err := draftpkg.Parse(rawDraft)
 	if err != nil {
-		return output.ErrValidation("parse draft raw EML failed: %v", err)
+		return mailFailedPreconditionError("parse draft raw EML failed: %v", err).WithCause(err)
 	}
 	projection := draftpkg.Project(snapshot)
 	out := map[string]interface{}{
@@ -422,7 +421,12 @@ func buildDraftEditPatch(runtime *common.RuntimeContext) (draftpkg.Patch, error)
 	if bodyVal != "" {
 		for _, op := range patch.Ops {
 			if op.Op == "set_body" || op.Op == "set_reply_body" {
-				return patch, output.ErrValidation("--body / --body-file and --patch-file body ops (set_body/set_reply_body) are mutually exclusive; use one or the other")
+				return patch, mailValidationError("--body / --body-file and --patch-file body ops (set_body/set_reply_body) are mutually exclusive; use one or the other").
+					WithParams(
+						mailInvalidParam("--body", "mutually exclusive with --patch-file body ops"),
+						mailInvalidParam("--body-file", "mutually exclusive with --patch-file body ops"),
+						mailInvalidParam("--patch-file", "mutually exclusive with direct body flags"),
+					)
 			}
 		}
 		patch.Ops = append(patch.Ops, draftpkg.PatchOp{Op: "set_body", Value: bodyVal})
@@ -448,20 +452,29 @@ func buildDraftEditPatch(runtime *common.RuntimeContext) (draftpkg.Patch, error)
 	hasEventSet := runtime.Str("set-event-summary") != ""
 	hasEventRemove := runtime.Bool("remove-event")
 	if !hasEventSet && (runtime.Str("set-event-start") != "" || runtime.Str("set-event-end") != "" || runtime.Str("set-event-location") != "") {
-		return patch, output.ErrValidation("--set-event-start, --set-event-end, and --set-event-location require --set-event-summary")
+		return patch, mailValidationParamError("--set-event-summary", "--set-event-start, --set-event-end, and --set-event-location require --set-event-summary")
 	}
 	if hasEventSet && hasEventRemove {
-		return patch, output.ErrValidation("--set-event-summary and --remove-event are mutually exclusive")
+		return patch, mailValidationError("--set-event-summary and --remove-event are mutually exclusive").
+			WithParams(
+				mailInvalidParam("--set-event-summary", "mutually exclusive with --remove-event"),
+				mailInvalidParam("--remove-event", "mutually exclusive with --set-event-summary"),
+			)
 	}
 	if hasEventSet {
 		summary := runtime.Str("set-event-summary")
 		start := runtime.Str("set-event-start")
 		end := runtime.Str("set-event-end")
 		if summary == "" || start == "" || end == "" {
-			return patch, output.ErrValidation("--set-event-summary, --set-event-start, and --set-event-end must all be provided together")
+			return patch, mailValidationError("--set-event-summary, --set-event-start, and --set-event-end must all be provided together").
+				WithParams(
+					mailInvalidParam("--set-event-summary", "required with --set-event-start/--set-event-end"),
+					mailInvalidParam("--set-event-start", "required with --set-event-summary/--set-event-end"),
+					mailInvalidParam("--set-event-end", "required with --set-event-summary/--set-event-start"),
+				)
 		}
 		if _, _, err := parseEventTimeRange(start, end); err != nil {
-			return patch, output.ErrValidation("%s", prefixEventRangeError("--set-event-", err).Error())
+			return patch, prefixEventRangeError("--set-event-", err)
 		}
 		patch.Ops = append(patch.Ops, draftpkg.PatchOp{
 			Op:            "set_calendar",
@@ -475,7 +488,7 @@ func buildDraftEditPatch(runtime *common.RuntimeContext) (draftpkg.Patch, error)
 	}
 
 	if len(patch.Ops) == 0 && !runtime.Bool("request-receipt") {
-		return patch, output.ErrValidation("at least one edit operation is required; use direct flags such as --set-subject/--set-to, or use --patch-file for body edits and other advanced operations (run --print-patch-template first)")
+		return patch, mailValidationError("at least one edit operation is required; use direct flags such as --set-subject/--set-to, or use --patch-file for body edits and other advanced operations (run --print-patch-template first)")
 	}
 	if len(patch.Ops) == 0 {
 		// --request-receipt only: Validate() would reject empty Ops, so skip it
@@ -483,7 +496,10 @@ func buildDraftEditPatch(runtime *common.RuntimeContext) (draftpkg.Patch, error)
 		// the draft's From address is known.
 		return patch, nil
 	}
-	return patch, patch.Validate()
+	if err := patch.Validate(); err != nil {
+		return patch, mailValidationError("%v", err).WithCause(err)
+	}
+	return patch, nil
 }
 
 // loadPatchFile reads and JSON-decodes a patch file from a relative path
@@ -492,19 +508,25 @@ func buildDraftEditPatch(runtime *common.RuntimeContext) (draftpkg.Patch, error)
 // internal stack traces.
 func loadPatchFile(runtime *common.RuntimeContext, path string) (draftpkg.Patch, error) {
 	var patch draftpkg.Patch
+	if err := runtime.ValidatePath(path); err != nil {
+		return patch, mailValidationParamError("--patch-file", "--patch-file %q: %v", path, err).WithCause(mailInputStatError(err))
+	}
 	f, err := runtime.FileIO().Open(path)
 	if err != nil {
-		return patch, fmt.Errorf("--patch-file %q: %w", path, err)
+		return patch, mailValidationParamError("--patch-file", "--patch-file %q: %v", path, err).WithCause(mailInputStatError(err))
 	}
 	defer f.Close()
 	data, err := io.ReadAll(f)
 	if err != nil {
-		return patch, err
+		return patch, mailValidationParamError("--patch-file", "read --patch-file %q: %v", path, err).WithCause(err)
 	}
 	if err := json.Unmarshal(data, &patch); err != nil {
-		return patch, fmt.Errorf("parse patch file: %w", err)
+		return patch, mailValidationParamError("--patch-file", "parse patch file: %v", err).WithCause(err)
 	}
-	return patch, patch.Validate()
+	if err := patch.Validate(); err != nil {
+		return patch, mailValidationParamError("--patch-file", "validate patch file: %v", err).WithCause(err)
+	}
+	return patch, nil
 }
 
 // buildDraftEditPatchTemplate returns the JSON template emitted by

shortcuts/mail/mail_draft_edit_test.go

@@ -4,8 +4,11 @@
 package mail
 
 import (
+	"errors"
+	"os"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
 	"github.com/spf13/cobra"
@@ -82,6 +85,43 @@ func TestBuildDraftEditPatch_InvalidPriority(t *testing.T) {
 	}
 }
 
+func TestLoadPatchFileRejectsUnsafePathWithTypedParam(t *testing.T) {
+	chdirTemp(t)
+	f, _, _, _ := mailShortcutTestFactory(t)
+	rt := &common.RuntimeContext{Cmd: &cobra.Command{Use: "test"}, Factory: f, Config: mailTestConfig()}
+	_, err := loadPatchFile(rt, "../patch.json")
+	if err == nil {
+		t.Fatal("expected unsafe patch path to fail")
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected ValidationError, got %T: %v", err, err)
+	}
+	if validationErr.Param != "--patch-file" {
+		t.Fatalf("param = %q, want --patch-file", validationErr.Param)
+	}
+}
+
+func TestLoadPatchFileValidateFailureKeepsPatchFileParam(t *testing.T) {
+	chdirTemp(t)
+	if err := os.WriteFile("patch.json", []byte(`{"ops":[]}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	f, _, _, _ := mailShortcutTestFactory(t)
+	rt := &common.RuntimeContext{Cmd: &cobra.Command{Use: "test"}, Factory: f, Config: mailTestConfig()}
+	_, err := loadPatchFile(rt, "patch.json")
+	if err == nil {
+		t.Fatal("expected invalid patch file to fail")
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected ValidationError, got %T: %v", err, err)
+	}
+	if validationErr.Param != "--patch-file" {
+		t.Fatalf("param = %q, want --patch-file", validationErr.Param)
+	}
+}
+
 func TestBuildDraftEditPatch_NoPriority(t *testing.T) {
 	rt := newDraftEditRuntime(map[string]string{"set-subject": "hello"})
 	patch, err := buildDraftEditPatch(rt)

shortcuts/mail/mail_draft_send.go

@@ -5,11 +5,10 @@ package mail
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -46,11 +45,21 @@ type failedDraft struct {
 //	  "success_count":  2,
 //	  "failure_count":  1,
 //	  "sent":  [{"draft_id":..., "message_id":..., "thread_id":...}, ...],
-//	  "failed":[{"draft_id":..., "error":...}]
+//	  "failed":[{"draft_id":..., "error":...}],
+//	  "aborted":     true,
+//	  "abort_error": {"type":..., "subtype":..., "code":..., "message":..., "hint":...}
 //	}
 //
 // failed is marked omitempty so a fully successful batch returns a clean shape
 // without an empty array.
+//
+// aborted reports an account-level abort: the failure repeats identically for
+// every draft, so the remaining drafts were not attempted and retrying the
+// batch as-is fails the same way. abort_error carries the typed error that
+// triggered the abort (same wire shape as a stderr error envelope's error
+// object) so callers can route recovery from stdout alone. A --stop-on-error
+// stop does NOT set aborted: there the failure is draft-level and the caller
+// chose to stop early.
 type batchSendOutput struct {
 	MailboxID    string        `json:"mailbox_id"`
 	Total        int           `json:"total"`
@@ -58,6 +67,8 @@ type batchSendOutput struct {
 	FailureCount int           `json:"failure_count"`
 	Sent         []sentDraft   `json:"sent"`
 	Failed       []failedDraft `json:"failed,omitempty"`
+	Aborted      bool          `json:"aborted,omitempty"`
+	AbortError   interface{}   `json:"abort_error,omitempty"`
 }
 
 // MailDraftSend is the `+draft-send` shortcut: send N existing drafts
@@ -66,9 +77,9 @@ type batchSendOutput struct {
 // drafts are user-owned resources and bot has no coherent semantics here.
 //
 // Output schema is the batchSendOutput type above. Partial failures (any
-// failed[]) return exit 1 with envelope.error.type="partial_failure" so that
-// agents can distinguish "all sent" from "some sent" without parsing the
-// success_count field.
+// failed[]) emit an ok:false multi-status envelope so that agents can
+// distinguish "all sent" from "some sent" without parsing the success_count
+// field.
 var MailDraftSend = common.Shortcut{
 	Service: "mail",
 	Command: "+draft-send",
@@ -101,14 +112,16 @@ var MailDraftSend = common.Shortcut{
 //  2. Validate the draft-id slice (non-empty, under MaxBatchSendDrafts cap,
 //     no empty elements).
 //  3. Loop over each draft ID, calling POST .../drafts/:id/send directly via
-//     runtime.CallAPI. Per-draft outcomes:
-//     - fatal err (isFatalSendErr) → return immediately (bypasses --stop-on-error).
+//     runtime.CallAPITyped. Per-draft outcomes:
+//     - fatal err (isFatalSendErr) → abort immediately (bypasses
+//     --stop-on-error): with earlier progress, emit the aborted ledger as the
+//     single failure result; with none, return the typed error directly.
 //     - recoverable err → append to failed[]; honor --stop-on-error.
-//     - success + automation_send_disable signal → return immediately with
-//     ExitAPI/"automation_send_disabled".
+//     - success + automation_send_disable signal → abort the same way with a
+//     failed-precondition error.
 //     - success → append to sent[].
 //  4. Emit batchSendOutput via runtime.Out.
-//  5. If any draft failed, return ExitAPI/"partial_failure" so exit code = 1.
+//  5. If any draft failed, emit ok:false via runtime.OutPartialFailure.
 func executeDraftSend(ctx context.Context, rt *common.RuntimeContext) error {
 	mailboxID := resolveComposeMailboxID(rt)
 	draftIDs, err := normalizedDraftSendIDs(rt)
@@ -122,9 +135,9 @@ func executeDraftSend(ctx context.Context, rt *common.RuntimeContext) error {
 		idx := i + 1
 		writeDraftSendProgressf(rt, "[%d/%d] sending draft %s",
 			idx, len(draftIDs), sanitizeForSingleLine(id))
-		// Direct CallAPI rather than draftpkg.Send: this shortcut never sends
+		// Direct CallAPITyped rather than draftpkg.Send: this shortcut never sends
 		// a body, so the helper's send_time-aware envelope would add no value.
-		data, err := rt.CallAPI("POST",
+		data, err := rt.CallAPITyped("POST",
 			mailboxPath(mailboxID, "drafts", id, "send"), nil, nil)
 		if err != nil {
 			if isFatalSendErr(err) {
@@ -132,13 +145,15 @@ func executeDraftSend(ctx context.Context, rt *common.RuntimeContext) error {
 					idx, len(draftIDs), sanitizeForSingleLine(id), sanitizeForSingleLine(err.Error()))
 				hadProgress := out.hasProgress()
 				out.Failed = append(out.Failed, failedDraft{DraftID: id, Error: err.Error()})
-				if hadProgress {
-					emitDraftSendOutput(rt, &out)
-				}
 				// Account- / mailbox-level failures (auth, permission, network,
 				// quota) will repeat identically for every remaining draft —
 				// abort immediately so the caller sees a single clear error
-				// instead of 100 redundant failed[] entries.
+				// instead of 100 redundant failed[] entries. With earlier
+				// progress the aborted ledger is the single failure result;
+				// with none, stdout stays empty and the typed error envelope is.
+				if hadProgress {
+					return emitDraftSendAborted(rt, &out, err)
+				}
 				return err
 			}
 			writeDraftSendProgressf(rt, "[%d/%d] failed draft %s: %s",
@@ -150,17 +165,19 @@ func executeDraftSend(ctx context.Context, rt *common.RuntimeContext) error {
 			continue
 		}
 		if reason := extractAutomationDisabledReason(data); reason != "" {
-			err := output.Errorf(output.ExitAPI, "automation_send_disabled",
-				"automation send is disabled for this mailbox: %s", reason)
+			err := mailFailedPreconditionError(
+				"automation send is disabled for this mailbox: %s", reason).
+				WithHint("enable automation send for this mailbox, or send the draft from the Lark client")
 			writeDraftSendProgressf(rt, "[%d/%d] aborting after draft %s: %s",
 				idx, len(draftIDs), sanitizeForSingleLine(id), sanitizeForSingleLine(err.Error()))
-			if out.hasProgress() {
-				out.Failed = append(out.Failed, failedDraft{DraftID: id, Error: err.Error()})
-				emitDraftSendOutput(rt, &out)
-			}
 			// HTTP success (code: 0) but the backend signaled automation send
 			// is disabled — every subsequent send will fail the same way, so
-			// abort the batch with a single descriptive error.
+			// abort the batch with a single failure result: the aborted ledger
+			// when earlier drafts made progress, the typed error otherwise.
+			if out.hasProgress() {
+				out.Failed = append(out.Failed, failedDraft{DraftID: id, Error: err.Error()})
+				return emitDraftSendAborted(rt, &out, err)
+			}
 			return err
 		}
 		s := sentDraft{DraftID: id}
@@ -179,13 +196,11 @@ func executeDraftSend(ctx context.Context, rt *common.RuntimeContext) error {
 				idx, len(draftIDs), sanitizeForSingleLine(id))
 		}
 	}
-	emitDraftSendOutput(rt, &out)
-
-	if out.FailureCount == 0 {
+	if len(out.Failed) == 0 {
+		emitDraftSendOutput(rt, &out)
 		return nil
 	}
-	return output.Errorf(output.ExitAPI, "partial_failure",
-		"%d of %d drafts failed to send", out.FailureCount, out.Total)
+	return emitDraftSendPartialFailure(rt, &out)
 }
 
 // dryRunDraftSend builds the --dry-run preview: one POST call per draft ID,
@@ -212,7 +227,7 @@ func normalizedDraftSendIDs(rt *common.RuntimeContext) ([]string, error) {
 
 func normalizeDraftSendIDs(draftIDs []string) ([]string, error) {
 	if len(draftIDs) == 0 {
-		return nil, output.ErrValidation("--draft-id is required")
+		return nil, mailValidationParamError("--draft-id", "--draft-id is required")
 	}
 
 	normalized := make([]string, 0, len(draftIDs))
@@ -220,16 +235,16 @@ func normalizeDraftSendIDs(draftIDs []string) ([]string, error) {
 	for _, id := range draftIDs {
 		trimmed := strings.TrimSpace(id)
 		if trimmed == "" {
-			return nil, output.ErrValidation("--draft-id contains empty value")
+			return nil, mailValidationParamError("--draft-id", "--draft-id contains empty value")
 		}
 		if _, ok := seen[trimmed]; ok {
-			return nil, output.ErrValidation("--draft-id contains duplicate value: %s", trimmed)
+			return nil, mailValidationParamError("--draft-id", "--draft-id contains duplicate value: %s", trimmed)
 		}
 		seen[trimmed] = struct{}{}
 		normalized = append(normalized, trimmed)
 	}
 	if len(normalized) > MaxBatchSendDrafts {
-		return nil, output.ErrValidation(
+		return nil, mailValidationParamError("--draft-id",
 			"too many drafts: %d > %d (split into multiple batches)",
 			len(normalized), MaxBatchSendDrafts)
 	}
@@ -246,6 +261,24 @@ func emitDraftSendOutput(rt *common.RuntimeContext, out *batchSendOutput) {
 	rt.Out(*out, nil)
 }
 
+func emitDraftSendPartialFailure(rt *common.RuntimeContext, out *batchSendOutput) error {
+	out.SuccessCount = len(out.Sent)
+	out.FailureCount = len(out.Failed)
+	return rt.OutPartialFailure(*out, nil)
+}
+
+// emitDraftSendAborted emits the batch ledger as the single failure result for
+// an account-level abort: the ledger carries aborted/abort_error and the
+// returned partial-failure signal sets the exit code without a second error
+// envelope on stderr.
+func emitDraftSendAborted(rt *common.RuntimeContext, out *batchSendOutput, cause error) error {
+	out.Aborted = true
+	if typed, ok := errs.UnwrapTypedError(errs.WrapInternal(cause)); ok {
+		out.AbortError = typed
+	}
+	return emitDraftSendPartialFailure(rt, out)
+}
+
 func writeDraftSendProgressf(rt *common.RuntimeContext, format string, args ...interface{}) {
 	if rt == nil || rt.Factory == nil || rt.Factory.IOStreams == nil || rt.Factory.IOStreams.ErrOut == nil {
 		return
@@ -259,52 +292,38 @@ func writeDraftSendProgressf(rt *common.RuntimeContext, format string, args ...i
 //
 // Trigger conditions:
 //
-//   - err does not unwrap to an *output.ExitError, or its Detail is missing:
+//   - err does not expose a typed Problem:
 //     unknown shapes are treated as fatal so they cannot accidentally
 //     accumulate into failed[] for every remaining draft.
-//   - Detail.Type ∈ {"auth", "app_status", "config", "permission",
-//     "rate_limit", "network"}: token, scope, app-installation problems,
-//     throttling, and connectivity are account-level.
-//   - Code == output.ExitNetwork: connectivity loss is account-level.
-//   - Detail.Code ∈ {LarkErrMailboxNotFound, LarkErrMailSendQuotaUser,
-//     LarkErrMailSendQuotaUserExt, LarkErrMailSendQuotaTenantExt,
-//     LarkErrMailQuota, LarkErrTenantStorageLimit}: mailbox / quota
-//     exhaustion is account-level.
+//   - Problem.Category ∈ {authentication, authorization, config, network,
+//     internal}: token, scope, app-installation problems, throttling,
+//     connectivity, SDK, and invalid-response failures are account-level.
+//   - Problem.Subtype ∈ {rate_limit, quota_exceeded}: throttling and quota
+//     exhaustion are account-level.
+//   - Problem.Code ∈ {1234013, 1236007, 1236008, 1236009, 1236010, 1236013}:
+//     mailbox missing / quota exhaustion is account-level. Mailbox-not-found
+//     stays code-scoped (1234013) rather than matching subtype not_found, so
+//     an unrelated not_found — e.g. a single bad draft ID — remains a
+//     per-draft recoverable failure.
 func isFatalSendErr(err error) bool {
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+	p, ok := errs.ProblemOf(err)
+	if !ok {
 		return true
 	}
-	switch exitErr.Detail.Type {
-	case "auth", "app_status", "config":
-		return true
-	case "permission", "rate_limit", "network":
+	switch p.Category {
+	case errs.CategoryAuthentication, errs.CategoryAuthorization, errs.CategoryConfig, errs.CategoryNetwork, errs.CategoryInternal:
 		return true
 	}
-	if exitErr.Code == output.ExitNetwork || wrapsExitCode(err, output.ExitNetwork) {
+	if p.Subtype == errs.SubtypeRateLimit || p.Subtype == errs.SubtypeQuotaExceeded {
 		return true
 	}
-	switch exitErr.Detail.Code {
-	case output.LarkErrMailboxNotFound,
-		output.LarkErrMailSendQuotaUser,
-		output.LarkErrMailSendQuotaUserExt,
-		output.LarkErrMailSendQuotaTenantExt,
-		output.LarkErrMailQuota,
-		output.LarkErrTenantStorageLimit:
+	switch p.Code {
+	case 1234013, 1236007, 1236008, 1236009, 1236010, 1236013:
 		return true
 	}
 	return false
 }
 
-func wrapsExitCode(err error, code int) bool {
-	for unwrapped := errors.Unwrap(err); unwrapped != nil; unwrapped = errors.Unwrap(unwrapped) {
-		if exitErr, ok := unwrapped.(*output.ExitError); ok && exitErr.Code == code {
-			return true
-		}
-	}
-	return false
-}
-
 // extractAutomationDisabledReason returns the human-readable reason when the
 // send succeeded at HTTP level (code: 0) but the backend reports that
 // automation send is disabled for this mailbox. An empty return value means

shortcuts/mail/mail_draft_send_test.go

@@ -4,6 +4,7 @@
 package mail
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
@@ -12,6 +13,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -91,6 +93,32 @@ func stubDraftSend(reg *httpmock.Registry, draftID string, body map[string]inter
 	return stub
 }
 
+func decodeDraftSendPartialEnvelopeData(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
+	t.Helper()
+	var envelope struct {
+		OK   bool                   `json:"ok"`
+		Data map[string]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("Unmarshal(stdout) error = %v, stdout=%s", err, stdout.String())
+	}
+	if envelope.OK {
+		t.Fatalf("expected ok:false partial-failure output, stdout=%s", stdout.String())
+	}
+	return envelope.Data
+}
+
+func assertPartialFailureSignal(t *testing.T, err error) {
+	t.Helper()
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	if pfErr.Code != output.ExitAPI {
+		t.Errorf("PartialFailureError.Code = %d, want ExitAPI=%d", pfErr.Code, output.ExitAPI)
+	}
+}
+
 // TestMailDraftSend_AllSuccess verifies the happy path: every draft sends
 // successfully, sent[] is fully populated, failed[] is omitted from the JSON,
 // and exit code = 0 (err == nil).
@@ -190,7 +218,8 @@ func TestMailDraftSend_ProgressWritesToStderr(t *testing.T) {
 	if strings.Contains(stdout.String(), "mail +draft-send:") {
 		t.Errorf("stdout must not contain progress lines; got %s", stdout.String())
 	}
-	data := decodeShortcutEnvelopeData(t, stdout)
+	assertPartialFailureSignal(t, err)
+	data := decodeDraftSendPartialEnvelopeData(t, stdout)
 	if data["success_count"].(float64) != 2 || data["failure_count"].(float64) != 1 {
 		t.Errorf("unexpected aggregate counts: %#v", data)
 	}
@@ -198,7 +227,7 @@ func TestMailDraftSend_ProgressWritesToStderr(t *testing.T) {
 
 // TestMailDraftSend_PartialFailure verifies that one recoverable per-draft
 // failure does not abort the batch; the remaining drafts are attempted; both
-// arrays are populated; and the call returns ExitAPI/"partial_failure".
+// arrays are populated; and the call returns the multi-status partial-failure signal.
 func TestMailDraftSend_PartialFailure(t *testing.T) {
 	f, stdout, _, reg := mailShortcutTestFactory(t)
 	stubDraftSend(reg, "d1", map[string]interface{}{
@@ -225,18 +254,9 @@ func TestMailDraftSend_PartialFailure(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected partial_failure error, got nil")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
-	}
-	if exitErr.Code != output.ExitAPI {
-		t.Errorf("Code = %d, want ExitAPI=%d", exitErr.Code, output.ExitAPI)
-	}
-	if exitErr.Detail == nil || exitErr.Detail.Type != "partial_failure" {
-		t.Errorf("Detail.Type = %v, want partial_failure", exitErr.Detail)
-	}
+	assertPartialFailureSignal(t, err)
 
-	data := decodeShortcutEnvelopeData(t, stdout)
+	data := decodeDraftSendPartialEnvelopeData(t, stdout)
 	if data["total"].(float64) != 3 {
 		t.Errorf("total = %v, want 3", data["total"])
 	}
@@ -284,7 +304,8 @@ func TestMailDraftSend_StopOnError(t *testing.T) {
 		t.Fatal("expected partial_failure error, got nil")
 	}
 
-	data := decodeShortcutEnvelopeData(t, stdout)
+	assertPartialFailureSignal(t, err)
+	data := decodeDraftSendPartialEnvelopeData(t, stdout)
 	if data["success_count"].(float64) != 1 {
 		t.Errorf("success_count = %v, want 1", data["success_count"])
 	}
@@ -294,6 +315,14 @@ func TestMailDraftSend_StopOnError(t *testing.T) {
 	if data["total"].(float64) != 3 {
 		t.Errorf("total = %v, want 3", data["total"])
 	}
+	// A --stop-on-error stop is a caller choice over a draft-level failure,
+	// not an account-level abort: the aborted/abort_error fields stay unset.
+	if _, present := data["aborted"]; present {
+		t.Errorf("aborted should be unset for --stop-on-error, got %v", data["aborted"])
+	}
+	if _, present := data["abort_error"]; present {
+		t.Errorf("abort_error should be unset for --stop-on-error, got %v", data["abort_error"])
+	}
 }
 
 // TestMailDraftSend_FatalAborts verifies that a fatal errno (mailbox not
@@ -315,12 +344,12 @@ func TestMailDraftSend_FatalAborts(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected fatal abort error, got nil")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
 	}
-	if exitErr.Detail == nil || exitErr.Detail.Code != output.LarkErrMailboxNotFound {
-		t.Errorf("expected Detail.Code = %d, got %#v", output.LarkErrMailboxNotFound, exitErr.Detail)
+	if p.Code != output.LarkErrMailboxNotFound {
+		t.Errorf("expected code = %d, got %#v", output.LarkErrMailboxNotFound, p)
 	}
 	// No JSON envelope on stdout because Execute returned early before rt.Out.
 	if stdout.Len() != 0 {
@@ -329,9 +358,10 @@ func TestMailDraftSend_FatalAborts(t *testing.T) {
 }
 
 // TestMailDraftSend_FatalAfterSuccessEmitsLedger verifies that a fatal error
-// after earlier side effects still emits the aggregate stdout ledger before
-// returning the fatal stderr error. This lets callers avoid blindly retrying a
-// draft that was already sent.
+// after earlier side effects emits the aborted stdout ledger as the single
+// failure result: the returned partial-failure signal sets the exit code
+// without a second error envelope, and abort_error carries the typed cause so
+// callers can avoid blindly retrying a draft that was already sent.
 func TestMailDraftSend_FatalAfterSuccessEmitsLedger(t *testing.T) {
 	f, stdout, _, reg := mailShortcutTestFactory(t)
 	stubDraftSend(reg, "d1", map[string]interface{}{
@@ -349,17 +379,17 @@ func TestMailDraftSend_FatalAfterSuccessEmitsLedger(t *testing.T) {
 		"--yes",
 	}, f, stdout)
 	if err == nil {
-		t.Fatal("expected fatal abort error, got nil")
+		t.Fatal("expected partial-failure abort signal, got nil")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if exitErr.Detail == nil || exitErr.Detail.Code != output.LarkErrMailSendQuotaUser {
-		t.Errorf("expected Detail.Code = %d, got %#v", output.LarkErrMailSendQuotaUser, exitErr.Detail)
+	// The ledger is the single failure result: the returned error must be the
+	// envelope-less partial-failure signal, not a typed error that the root
+	// dispatcher would render as a second failure envelope on stderr.
+	assertPartialFailureSignal(t, err)
+	if _, ok := errs.ProblemOf(err); ok {
+		t.Fatalf("abort signal must not carry a typed problem, got %v", err)
 	}
 
-	data := decodeShortcutEnvelopeData(t, stdout)
+	data := decodeDraftSendPartialEnvelopeData(t, stdout)
 	if data["total"].(float64) != 3 {
 		t.Errorf("total = %v, want 3", data["total"])
 	}
@@ -375,6 +405,19 @@ func TestMailDraftSend_FatalAfterSuccessEmitsLedger(t *testing.T) {
 	if got := gjsonLikeString(t, data, "failed", 0, "draft_id"); got != "d2" {
 		t.Errorf("failed[0].draft_id = %q, want d2", got)
 	}
+	if data["aborted"] != true {
+		t.Errorf("aborted = %v, want true", data["aborted"])
+	}
+	abortErr, ok := data["abort_error"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("abort_error = %v, want object", data["abort_error"])
+	}
+	if abortErr["type"] != "api" {
+		t.Errorf("abort_error.type = %v, want api", abortErr["type"])
+	}
+	if abortErr["code"].(float64) != float64(output.LarkErrMailSendQuotaUser) {
+		t.Errorf("abort_error.code = %v, want %d", abortErr["code"], output.LarkErrMailSendQuotaUser)
+	}
 }
 
 // TestMailDraftSend_AutomationDisabled verifies that an HTTP-success response
@@ -402,24 +445,22 @@ func TestMailDraftSend_AutomationDisabled(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected automation_send_disabled error, got nil")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
 	}
-	if exitErr.Code != output.ExitAPI {
-		t.Errorf("Code = %d, want ExitAPI=%d", exitErr.Code, output.ExitAPI)
+	if p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeFailedPrecondition {
+		t.Errorf("problem = %#v, want validation/failed_precondition", p)
 	}
-	if exitErr.Detail == nil || exitErr.Detail.Type != "automation_send_disabled" {
-		t.Errorf("Detail.Type = %v, want automation_send_disabled", exitErr.Detail)
-	}
-	if !strings.Contains(exitErr.Error(), "outbound automation disabled") {
-		t.Errorf("error message should propagate reason, got %q", exitErr.Error())
+	if !strings.Contains(p.Message, "outbound automation disabled") {
+		t.Errorf("error message should propagate reason, got %q", p.Message)
 	}
 }
 
 // TestMailDraftSend_AutomationDisabledAfterSuccessEmitsLedger verifies that an
-// automation-send policy stop after earlier successful sends still writes the
-// batch ledger to stdout before returning the structured fatal error.
+// automation-send policy stop after earlier successful sends emits the aborted
+// batch ledger as the single failure result, with the failed-precondition
+// cause carried in abort_error.
 func TestMailDraftSend_AutomationDisabledAfterSuccessEmitsLedger(t *testing.T) {
 	f, stdout, _, reg := mailShortcutTestFactory(t)
 	stubDraftSend(reg, "d1", map[string]interface{}{
@@ -442,17 +483,27 @@ func TestMailDraftSend_AutomationDisabledAfterSuccessEmitsLedger(t *testing.T) {
 		"--yes",
 	}, f, stdout)
 	if err == nil {
-		t.Fatal("expected automation_send_disabled error, got nil")
+		t.Fatal("expected partial-failure abort signal, got nil")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if exitErr.Detail == nil || exitErr.Detail.Type != "automation_send_disabled" {
-		t.Errorf("Detail.Type = %v, want automation_send_disabled", exitErr.Detail)
+	assertPartialFailureSignal(t, err)
+	if _, ok := errs.ProblemOf(err); ok {
+		t.Fatalf("abort signal must not carry a typed problem, got %v", err)
 	}
 
-	data := decodeShortcutEnvelopeData(t, stdout)
+	data := decodeDraftSendPartialEnvelopeData(t, stdout)
+	if data["aborted"] != true {
+		t.Errorf("aborted = %v, want true", data["aborted"])
+	}
+	abortErr, ok := data["abort_error"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("abort_error = %v, want object", data["abort_error"])
+	}
+	if abortErr["type"] != "validation" || abortErr["subtype"] != "failed_precondition" {
+		t.Errorf("abort_error type/subtype = %v/%v, want validation/failed_precondition", abortErr["type"], abortErr["subtype"])
+	}
+	if msg, _ := abortErr["message"].(string); !strings.Contains(msg, "outbound automation disabled") {
+		t.Errorf("abort_error.message should carry the reason, got %q", msg)
+	}
 	if data["total"].(float64) != 3 {
 		t.Errorf("total = %v, want 3", data["total"])
 	}
@@ -600,12 +651,8 @@ func TestMailDraftSend_MissingYes(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected ExitConfirmationRequired, got nil")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
-	}
-	if exitErr.Code != output.ExitConfirmationRequired {
-		t.Errorf("Code = %d, want ExitConfirmationRequired=%d", exitErr.Code, output.ExitConfirmationRequired)
+	if code := output.ExitCodeOf(err); code != output.ExitConfirmationRequired {
+		t.Errorf("Code = %d, want ExitConfirmationRequired=%d", code, output.ExitConfirmationRequired)
 	}
 }
 
@@ -788,93 +835,58 @@ func TestIsFatalSendErr(t *testing.T) {
 			want: true,
 		},
 		{
-			name: "ExitError without Detail → fatal",
-			err:  &output.ExitError{Code: output.ExitInternal},
+			name: "internal typed fallback → fatal",
+			err:  errs.NewInternalError(errs.SubtypeSDKError, "unexpected shape"),
 			want: true,
 		},
 		{
-			name: "auth → fatal",
-			err: &output.ExitError{
-				Code:   output.ExitAuth,
-				Detail: &output.ErrDetail{Type: "auth", Message: "token expired"},
-			},
+			name: "authentication → fatal",
+			err:  errs.NewAuthenticationError(errs.SubtypeTokenExpired, "token expired"),
 			want: true,
 		},
 		{
-			name: "app_status → fatal",
-			err: &output.ExitError{
-				Code:   output.ExitAuth,
-				Detail: &output.ErrDetail{Type: "app_status", Message: "app disabled"},
-			},
+			name: "authorization → fatal",
+			err:  errs.NewPermissionError(errs.SubtypePermissionDenied, "denied"),
 			want: true,
 		},
 		{
 			name: "config → fatal",
-			err: &output.ExitError{
-				Code:   output.ExitAuth,
-				Detail: &output.ErrDetail{Type: "config", Message: "bad app_id"},
-			},
+			err:  errs.NewConfigError(errs.SubtypeInvalidConfig, "bad app_id"),
 			want: true,
 		},
 		{
-			name: "permission → fatal",
-			err: &output.ExitError{
-				Code:   output.ExitAPI,
-				Detail: &output.ErrDetail{Type: "permission", Message: "denied"},
-			},
+			name: "network → fatal",
+			err:  errs.NewNetworkError(errs.SubtypeNetworkTransport, "DNS timeout"),
 			want: true,
 		},
 		{
 			name: "rate_limit → fatal",
-			err: &output.ExitError{
-				Code:   output.ExitAPI,
-				Detail: &output.ErrDetail{Type: "rate_limit", Code: output.LarkErrRateLimit},
-			},
-			want: true,
-		},
-		{
-			name: "ExitNetwork → fatal",
-			err: &output.ExitError{
-				Code:   output.ExitNetwork,
-				Detail: &output.ErrDetail{Type: "network", Message: "DNS timeout"},
-			},
-			want: true,
-		},
-		{
-			name: "wrapped ExitNetwork → fatal",
-			err:  output.Errorf(output.ExitAPI, "api_error", "API call failed: %s", output.ErrNetwork("DNS timeout")),
+			err:  errs.NewAPIError(errs.SubtypeRateLimit, "rate limited").WithCode(output.LarkErrRateLimit),
 			want: true,
 		},
 		{
 			name: "LarkErrMailboxNotFound → fatal",
-			err: &output.ExitError{
-				Code:   output.ExitAPI,
-				Detail: &output.ErrDetail{Type: "api_error", Code: output.LarkErrMailboxNotFound},
-			},
+			err:  errs.NewAPIError(errs.SubtypeNotFound, "mailbox not found").WithCode(output.LarkErrMailboxNotFound),
 			want: true,
 		},
 		{
 			name: "LarkErrMailSendQuotaUser → fatal",
-			err: &output.ExitError{
-				Code:   output.ExitAPI,
-				Detail: &output.ErrDetail{Type: "api_error", Code: output.LarkErrMailSendQuotaUser},
-			},
+			err:  errs.NewAPIError(errs.SubtypeQuotaExceeded, "user daily send count exceeded").WithCode(output.LarkErrMailSendQuotaUser),
 			want: true,
 		},
 		{
 			name: "LarkErrTenantStorageLimit → fatal",
-			err: &output.ExitError{
-				Code:   output.ExitAPI,
-				Detail: &output.ErrDetail{Type: "api_error", Code: output.LarkErrTenantStorageLimit},
-			},
+			err:  errs.NewAPIError(errs.SubtypeQuotaExceeded, "tenant storage limit").WithCode(output.LarkErrTenantStorageLimit),
 			want: true,
 		},
 		{
-			name: "generic api_error → recoverable",
-			err: &output.ExitError{
-				Code:   output.ExitAPI,
-				Detail: &output.ErrDetail{Type: "api_error", Code: 230001},
-			},
+			name: "generic api unknown → recoverable",
+			err:  errs.NewAPIError(errs.SubtypeUnknown, "draft not found").WithCode(230001),
+			want: false,
+		},
+		{
+			name: "not_found without account-level code → recoverable",
+			err:  errs.NewAPIError(errs.SubtypeNotFound, "draft not found").WithCode(230002),
 			want: false,
 		},
 	}

shortcuts/mail/mail_errors.go

@@ -0,0 +1,76 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+)
+
+func mailValidationError(format string, args ...any) *errs.ValidationError {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...)
+}
+
+func mailValidationParamError(param, format string, args ...any) *errs.ValidationError {
+	return mailValidationError(format, args...).WithParam(param)
+}
+
+func mailInvalidParam(name, reason string) errs.InvalidParam {
+	return errs.InvalidParam{Name: name, Reason: reason}
+}
+
+func mailFailedPreconditionError(format string, args ...any) *errs.ValidationError {
+	return errs.NewValidationError(errs.SubtypeFailedPrecondition, format, args...)
+}
+
+func mailInvalidResponseError(format string, args ...any) *errs.InternalError {
+	return errs.NewInternalError(errs.SubtypeInvalidResponse, format, args...)
+}
+
+func mailFileIOError(format string, err error, args ...any) *errs.InternalError {
+	return errs.NewInternalError(errs.SubtypeFileIO, format, args...).WithCause(err)
+}
+
+func mailInputStatError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, fileio.ErrPathValidation) {
+		return mailValidationError("unsafe file path: %s", err).WithCause(err)
+	}
+	return mailValidationError("cannot read file: %s", err).WithCause(err)
+}
+
+func mailDecorateProblemMessage(err error, format string, args ...any) error {
+	if err == nil {
+		return nil
+	}
+	prefix := fmt.Sprintf(format, args...)
+	if p, ok := errs.ProblemOf(err); ok {
+		if strings.TrimSpace(prefix) != "" {
+			p.Message = prefix + ": " + p.Message
+		}
+		return err
+	}
+	return errs.NewInternalError(errs.SubtypeSDKError, "%s: %s", prefix, err.Error()).WithCause(err)
+}
+
+func mailAppendProblemHint(err error, hint string) error {
+	if err == nil {
+		return nil
+	}
+	if p, ok := errs.ProblemOf(err); ok {
+		if strings.TrimSpace(p.Hint) != "" {
+			p.Hint = p.Hint + "; " + hint
+		} else {
+			p.Hint = hint
+		}
+		return err
+	}
+	return errs.NewAPIError(errs.SubtypeUnknown, "%s", err.Error()).WithHint("%s", hint).WithCause(err)
+}

shortcuts/mail/mail_errors_test.go

@@ -0,0 +1,307 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"errors"
+	"io"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+)
+
+func TestMailFileIOErrorTyped(t *testing.T) {
+	cause := errors.New("disk read failed")
+
+	err := mailFileIOError("load %s: %v", cause, "body.html", cause)
+
+	var internalErr *errs.InternalError
+	if !errors.As(err, &internalErr) {
+		t.Fatalf("expected internal error, got %T", err)
+	}
+	if !errors.Is(err, cause) {
+		t.Fatalf("cause not preserved: %v", err)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Subtype != errs.SubtypeFileIO {
+		t.Fatalf("subtype = %q, want %q", p.Subtype, errs.SubtypeFileIO)
+	}
+	if !strings.Contains(p.Message, "body.html") || !strings.Contains(p.Message, "disk read failed") {
+		t.Fatalf("message missing context: %q", p.Message)
+	}
+}
+
+func TestMailFileIOErrorDoesNotAppendCauseAsFormatArg(t *testing.T) {
+	cause := errors.New("mkdir denied")
+
+	err := mailFileIOError("cannot create output directory %q", cause, "out")
+
+	if !errors.Is(err, cause) {
+		t.Fatalf("cause not preserved: %v", err)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if strings.Contains(p.Message, "%!(") {
+		t.Fatalf("message contains fmt extra marker: %q", p.Message)
+	}
+	if strings.Contains(p.Message, "mkdir denied") {
+		t.Fatalf("cause should not be implicitly appended to message: %q", p.Message)
+	}
+}
+
+func TestMailInputStatErrorTyped(t *testing.T) {
+	if err := mailInputStatError(nil); err != nil {
+		t.Fatalf("nil input should stay nil, got %v", err)
+	}
+
+	pathErr := fileio.ErrPathValidation
+	err := mailInputStatError(pathErr)
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected validation error, got %T", err)
+	}
+	if !errors.Is(err, pathErr) {
+		t.Fatalf("cause not preserved: %v", err)
+	}
+	if !strings.Contains(err.Error(), "unsafe file path") {
+		t.Fatalf("unexpected path validation message: %v", err)
+	}
+
+	statErr := errors.New("permission denied")
+	err = mailInputStatError(statErr)
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected validation error, got %T", err)
+	}
+	if !errors.Is(err, statErr) {
+		t.Fatalf("stat cause not preserved: %v", err)
+	}
+	if !strings.Contains(err.Error(), "cannot read file") {
+		t.Fatalf("unexpected stat message: %v", err)
+	}
+}
+
+func TestMailDecorateProblemMessageTypedAndPlain(t *testing.T) {
+	if err := mailDecorateProblemMessage(nil, "fetch profile"); err != nil {
+		t.Fatalf("nil input should stay nil, got %v", err)
+	}
+
+	typedErr := errs.NewAPIError(errs.SubtypeRateLimit, "too many requests")
+	err := mailDecorateProblemMessage(typedErr, "fetch %s", "profile")
+	if err != typedErr {
+		t.Fatalf("typed error should be decorated in place")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Message != "fetch profile: too many requests" {
+		t.Fatalf("message = %q", p.Message)
+	}
+
+	blankPrefixErr := errs.NewAPIError(errs.SubtypeUnknown, "unchanged")
+	err = mailDecorateProblemMessage(blankPrefixErr, "  ")
+	p, ok = errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Message != "unchanged" {
+		t.Fatalf("blank prefix should not change message, got %q", p.Message)
+	}
+
+	plainCause := errors.New("sdk failed")
+	err = mailDecorateProblemMessage(plainCause, "fetch mailbox")
+	var internalErr *errs.InternalError
+	if !errors.As(err, &internalErr) {
+		t.Fatalf("plain error should be upgraded to internal SDK error, got %T", err)
+	}
+	if !errors.Is(err, plainCause) {
+		t.Fatalf("cause not preserved: %v", err)
+	}
+	p, ok = errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Subtype != errs.SubtypeSDKError || !strings.Contains(p.Message, "fetch mailbox: sdk failed") {
+		t.Fatalf("unexpected problem: %+v", p)
+	}
+}
+
+func TestMailAppendProblemHintTypedAndPlain(t *testing.T) {
+	if err := mailAppendProblemHint(nil, "retry later"); err != nil {
+		t.Fatalf("nil input should stay nil, got %v", err)
+	}
+
+	withoutHint := errs.NewAPIError(errs.SubtypeUnknown, "failed")
+	err := mailAppendProblemHint(withoutHint, "retry later")
+	if err != withoutHint {
+		t.Fatalf("typed error should be updated in place")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Hint != "retry later" {
+		t.Fatalf("hint = %q", p.Hint)
+	}
+
+	withHint := errs.NewAPIError(errs.SubtypeUnknown, "failed").WithHint("check scope")
+	err = mailAppendProblemHint(withHint, "retry later")
+	p, ok = errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Hint != "check scope; retry later" {
+		t.Fatalf("hint = %q", p.Hint)
+	}
+
+	plainCause := errors.New("legacy api failed")
+	err = mailAppendProblemHint(plainCause, "retry later")
+	var apiErr *errs.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("plain error should be upgraded to API error, got %T", err)
+	}
+	if !errors.Is(err, plainCause) {
+		t.Fatalf("cause not preserved: %v", err)
+	}
+	p, ok = errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Hint != "retry later" || p.Subtype != errs.SubtypeUnknown {
+		t.Fatalf("unexpected problem: %+v", p)
+	}
+}
+
+func TestValidateBodyFileMutexTypedErrors(t *testing.T) {
+	err := validateBodyFileMutex("<p>Hello</p>", "body.html", func(string) error { return nil })
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected validation error, got %T", err)
+	}
+	if len(validationErr.Params) != 2 {
+		t.Fatalf("params = %#v, want two conflicting params", validationErr.Params)
+	}
+	if validationErr.Params[0].Name != "--body" || validationErr.Params[1].Name != "--body-file" {
+		t.Fatalf("unexpected params: %#v", validationErr.Params)
+	}
+
+	pathErr := errors.New("outside cwd")
+	err = validateBodyFileMutex("", "body.html", func(string) error { return pathErr })
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected validation error, got %T", err)
+	}
+	if validationErr.Param != "--body-file" {
+		t.Fatalf("param = %q, want --body-file", validationErr.Param)
+	}
+	if !errors.Is(err, pathErr) {
+		t.Fatalf("cause not preserved: %v", err)
+	}
+}
+
+func TestReadBodyFileTypedErrors(t *testing.T) {
+	openErr := errors.New("missing")
+	_, err := readBodyFile(bodyFileTestIO{
+		open: func(string) (fileio.File, error) { return nil, openErr },
+	}, "missing.html")
+	requireBodyFileValidationError(t, err, openErr)
+	if !strings.Contains(err.Error(), "open --body-file missing.html") {
+		t.Fatalf("unexpected open message: %v", err)
+	}
+
+	readErr := errors.New("read broken")
+	_, err = readBodyFile(bodyFileTestIO{
+		open: func(string) (fileio.File, error) {
+			return &bodyFileTestFile{readErr: readErr}, nil
+		},
+	}, "body.html")
+	requireBodyFileValidationError(t, err, readErr)
+	if !strings.Contains(err.Error(), "read --body-file body.html") {
+		t.Fatalf("unexpected read message: %v", err)
+	}
+
+	_, err = readBodyFile(bodyFileTestIO{
+		open: func(string) (fileio.File, error) {
+			return &bodyFileTestFile{remaining: maxBodyFileSize + 1}, nil
+		},
+	}, "huge.html")
+	requireBodyFileValidationError(t, err, nil)
+	if !strings.Contains(err.Error(), "file exceeds 32 MB limit") {
+		t.Fatalf("unexpected size message: %v", err)
+	}
+}
+
+func requireBodyFileValidationError(t *testing.T, err error, cause error) {
+	t.Helper()
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected validation error, got %T (%v)", err, err)
+	}
+	if validationErr.Param != "--body-file" {
+		t.Fatalf("param = %q, want --body-file", validationErr.Param)
+	}
+	if cause != nil && !errors.Is(err, cause) {
+		t.Fatalf("cause %v not preserved in %v", cause, err)
+	}
+}
+
+type bodyFileTestIO struct {
+	open func(string) (fileio.File, error)
+}
+
+func (fio bodyFileTestIO) Open(name string) (fileio.File, error) {
+	return fio.open(name)
+}
+
+func (fio bodyFileTestIO) Stat(string) (fileio.FileInfo, error) {
+	return nil, errors.New("unused")
+}
+
+func (fio bodyFileTestIO) ResolvePath(path string) (string, error) {
+	return path, nil
+}
+
+func (fio bodyFileTestIO) Save(string, fileio.SaveOptions, io.Reader) (fileio.SaveResult, error) {
+	return nil, errors.New("unused")
+}
+
+type bodyFileTestFile struct {
+	readErr   error
+	remaining int
+}
+
+func (f *bodyFileTestFile) Read(p []byte) (int, error) {
+	if f.readErr != nil {
+		return 0, f.readErr
+	}
+	if f.remaining <= 0 {
+		return 0, io.EOF
+	}
+	n := len(p)
+	if n > f.remaining {
+		n = f.remaining
+	}
+	for i := range p[:n] {
+		p[i] = 'x'
+	}
+	f.remaining -= n
+	return n, nil
+}
+
+func (f *bodyFileTestFile) ReadAt([]byte, int64) (int, error) {
+	return 0, errors.New("unused")
+}
+
+func (f *bodyFileTestFile) Close() error {
+	return nil
+}
+
+var _ fileio.FileIO = bodyFileTestIO{}
+var _ fileio.File = (*bodyFileTestFile)(nil)

shortcuts/mail/mail_forward.go

@@ -10,7 +10,7 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
 	"github.com/larksuite/cli/shortcuts/mail/emlbuilder"
@@ -135,10 +135,10 @@ var MailForward = common.Shortcut{
 		}
 		sourceMsg, err := fetchComposeSourceMessage(runtime, mailboxID, messageId)
 		if err != nil {
-			return fmt.Errorf("failed to fetch original message: %w", err)
+			return mailDecorateProblemMessage(err, "failed to fetch original message")
 		}
 		if err := validateForwardAttachmentURLs(sourceMsg); err != nil {
-			return fmt.Errorf("forward blocked: %w", err)
+			return mailDecorateProblemMessage(err, "forward blocked")
 		}
 		orig := sourceMsg.Original
 
@@ -243,7 +243,7 @@ var MailForward = common.Shortcut{
 		}
 		useHTML := !plainText && (bodyIsHTML(body) || bodyIsHTML(orig.bodyRaw) || sigResult != nil)
 		if strings.TrimSpace(inlineFlag) != "" && !useHTML {
-			return fmt.Errorf("--inline requires HTML mode, but neither the new body nor the original message contains HTML")
+			return mailValidationParamError("--inline", "--inline requires HTML mode, but neither the new body nor the original message contains HTML")
 		}
 		inlineSpecs, err := parseInlineSpecs(inlineFlag)
 		if err != nil {
@@ -257,7 +257,7 @@ var MailForward = common.Shortcut{
 		lintApplied, lintBlocked := emptyLintEnvelopeFields()
 		if useHTML {
 			if err := validateInlineImageURLs(sourceMsg); err != nil {
-				return fmt.Errorf("forward blocked: %w", err)
+				return mailDecorateProblemMessage(err, "forward blocked")
 			}
 			processedBody := buildBodyDiv(body, bodyIsHTML(body))
 			origLargeAttCard := stripLargeAttachmentCard(&orig)
@@ -274,7 +274,7 @@ var MailForward = common.Shortcut{
 			}
 			resolved, refs, resolveErr := draftpkg.ResolveLocalImagePaths(processedBody)
 			if resolveErr != nil {
-				return resolveErr
+				return mailValidationError("failed to resolve local image paths: %v", resolveErr).WithCause(resolveErr)
 			}
 			bodyWithSig := resolved
 			if sigResult != nil {
@@ -347,7 +347,7 @@ var MailForward = common.Shortcut{
 			}
 			content, err := downloadAttachmentContent(runtime, att.DownloadURL)
 			if err != nil {
-				return fmt.Errorf("failed to download original attachment %s: %w", att.Filename, err)
+				return mailDecorateProblemMessage(err, "failed to download original attachment %s", att.Filename)
 			}
 			contentType := att.ContentType
 			if contentType == "" {
@@ -381,13 +381,13 @@ var MailForward = common.Shortcut{
 		}
 		for _, f := range userFiles {
 			if f.Size > MaxLargeAttachmentSize {
-				return output.ErrValidation("attachment %s (%.1f GB) exceeds the %.0f GB single file limit",
+				return mailFailedPreconditionError("attachment %s (%.1f GB) exceeds the %.0f GB single file limit",
 					f.FileName, float64(f.Size)/1024/1024/1024, float64(MaxLargeAttachmentSize)/1024/1024/1024)
 			}
 		}
 		totalCount := len(origAtts) + len(largeAttIDs) + len(userFiles)
 		if totalCount > MaxAttachmentCount {
-			return output.ErrValidation("attachment count %d exceeds the limit of %d", totalCount, MaxAttachmentCount)
+			return mailFailedPreconditionError("attachment count %d exceeds the limit of %d", totalCount, MaxAttachmentCount)
 		}
 		allFiles = append(allFiles, userFiles...)
 		classified := classifyAttachments(allFiles, emlBase)
@@ -413,7 +413,7 @@ var MailForward = common.Shortcut{
 		// Upload oversized attachments as large attachments.
 		if len(classified.Oversized) > 0 {
 			if composedHTMLBody == "" && composedTextBody == "" {
-				return output.ErrValidation("large attachments require a body; " +
+				return mailFailedPreconditionError("large attachments require a body; " +
 					"empty messages cannot include the download link")
 			}
 			if runtime.Config == nil || runtime.UserOpenId() == "" {
@@ -421,7 +421,7 @@ var MailForward = common.Shortcut{
 				for _, f := range classified.Oversized {
 					totalBytes += f.Size
 				}
-				return output.ErrValidation("total attachment size %.1f MB exceeds the 25 MB EML limit; "+
+				return mailFailedPreconditionError("total attachment size %.1f MB exceeds the 25 MB EML limit; "+
 					"large attachment upload requires user identity (--as user)",
 					float64(totalBytes)/1024/1024)
 			}
@@ -486,18 +486,18 @@ var MailForward = common.Shortcut{
 		if len(mergedLargeAttIDs) > 0 {
 			idsJSON, err := json.Marshal(mergedLargeAttIDs)
 			if err != nil {
-				return fmt.Errorf("failed to encode large attachment IDs: %w", err)
+				return errs.NewInternalError(errs.SubtypeSDKError, "failed to encode large attachment IDs: %v", err).WithCause(err)
 			}
 			bld = bld.Header(draftpkg.LargeAttachmentIDsHeader, base64.StdEncoding.EncodeToString(idsJSON))
 		}
 		rawEML, err := bld.BuildBase64URL()
 		if err != nil {
-			return fmt.Errorf("failed to build EML: %w", err)
+			return mailValidationError("failed to build EML: %v", err).WithCause(err)
 		}
 
 		draftResult, err := draftpkg.CreateWithRaw(runtime, mailboxID, rawEML)
 		if err != nil {
-			return fmt.Errorf("failed to create draft: %w", err)
+			return mailDecorateProblemMessage(err, "failed to create draft")
 		}
 		showLintDetails := runtime.Bool("show-lint-details")
 		if !confirmSend {
@@ -510,7 +510,7 @@ var MailForward = common.Shortcut{
 		}
 		resData, err := draftpkg.Send(runtime, mailboxID, draftResult.DraftID, sendTime)
 		if err != nil {
-			return fmt.Errorf("failed to send forward (draft %s created but not sent): %w", draftResult.DraftID, err)
+			return mailDecorateProblemMessage(err, "failed to send forward (draft %s created but not sent)", draftResult.DraftID)
 		}
 		out := buildDraftSendOutput(resData, mailboxID)
 		applyLintToEnvelope(out, lintApplied, lintBlocked, showLintDetails)

shortcuts/mail/mail_lint_html.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/larksuite/cli/shortcuts/mail/lint"
@@ -54,10 +55,18 @@ var MailLintHTML = common.Shortcut{
 		// Mutual exclusion + exactly-one-of validation for --body / --body-file.
 		bodyEmpty := strings.TrimSpace(body) == ""
 		if bodyEmpty && bodyFile == "" {
-			return output.ErrValidation("exactly one of --body or --body-file is required")
+			return mailValidationError("exactly one of --body or --body-file is required").
+				WithParams(
+					mailInvalidParam("--body", "required when --body-file is empty"),
+					mailInvalidParam("--body-file", "required when --body is empty"),
+				)
 		}
 		if !bodyEmpty && bodyFile != "" {
-			return output.ErrValidation("--body and --body-file are mutually exclusive; pass exactly one")
+			return mailValidationError("--body and --body-file are mutually exclusive; pass exactly one").
+				WithParams(
+					mailInvalidParam("--body", "mutually exclusive with --body-file"),
+					mailInvalidParam("--body-file", "mutually exclusive with --body"),
+				)
 		}
 
 		// --body-file safety: cwd-subtree only. Mirrors the existing pattern
@@ -65,7 +74,7 @@ var MailLintHTML = common.Shortcut{
 		// runtime.ValidatePath.
 		if bodyFile != "" {
 			if err := runtime.ValidatePath(bodyFile); err != nil {
-				return output.ErrValidation("--body-file: %v", err)
+				return mailValidationParamError("--body-file", "--body-file: %v", err).WithCause(err)
 			}
 		}
 
@@ -141,7 +150,7 @@ func readLintHTMLBody(runtime *common.RuntimeContext) (string, error) {
 	path := strings.TrimSpace(runtime.Str("body-file"))
 	if path == "" {
 		// Should be unreachable given Validate, but defensive.
-		return "", output.ErrValidation("internal: --body-file empty after Validate")
+		return "", errs.NewInternalError(errs.SubtypeUnknown, "internal: --body-file empty after Validate")
 	}
 	return readBodyFile(runtime.FileIO(), path)
 }

shortcuts/mail/mail_message.go

@@ -5,7 +5,6 @@ package mail
 
 import (
 	"context"
-	"fmt"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -48,7 +47,7 @@ var MailMessage = common.Shortcut{
 
 		msg, err := fetchFullMessage(runtime, mailboxID, messageID, html)
 		if err != nil {
-			return fmt.Errorf("failed to fetch email: %w", err)
+			return mailDecorateProblemMessage(err, "failed to fetch email")
 		}
 
 		out := buildMessageOutput(msg, html)

shortcuts/mail/mail_reply.go

@@ -137,7 +137,7 @@ var MailReply = common.Shortcut{
 		}
 		sourceMsg, err := fetchComposeSourceMessage(runtime, mailboxID, messageId)
 		if err != nil {
-			return fmt.Errorf("failed to fetch original message: %w", err)
+			return mailDecorateProblemMessage(err, "failed to fetch original message")
 		}
 		orig := sourceMsg.Original
 		stripLargeAttachmentCard(&orig)
@@ -213,7 +213,7 @@ var MailReply = common.Shortcut{
 
 		useHTML := !plainText && (bodyIsHTML(body) || bodyIsHTML(orig.bodyRaw) || sigResult != nil)
 		if strings.TrimSpace(inlineFlag) != "" && !useHTML {
-			return fmt.Errorf("--inline requires HTML mode, but neither the new body nor the original message contains HTML")
+			return mailValidationParamError("--inline", "--inline requires HTML mode, but neither the new body nor the original message contains HTML")
 		}
 		var bodyStr string
 		if useHTML {
@@ -264,7 +264,7 @@ var MailReply = common.Shortcut{
 		lintApplied, lintBlocked := emptyLintEnvelopeFields()
 		if useHTML {
 			if err := validateInlineImageURLs(sourceMsg); err != nil {
-				return fmt.Errorf("HTML reply blocked: %w", err)
+				return mailDecorateProblemMessage(err, "HTML reply blocked")
 			}
 			var srcCIDs []string
 			bld, srcCIDs, srcInlineBytes, err = addInlineImagesToBuilder(runtime, bld, sourceMsg.InlineImages)
@@ -273,7 +273,7 @@ var MailReply = common.Shortcut{
 			}
 			resolved, refs, resolveErr := draftpkg.ResolveLocalImagePaths(bodyStr)
 			if resolveErr != nil {
-				return resolveErr
+				return mailValidationError("failed to resolve local image paths: %v", resolveErr).WithCause(resolveErr)
 			}
 			bodyWithSig := resolved
 			if sigResult != nil {
@@ -336,12 +336,12 @@ var MailReply = common.Shortcut{
 		}
 		rawEML, err := bld.BuildBase64URL()
 		if err != nil {
-			return fmt.Errorf("failed to build EML: %w", err)
+			return mailValidationError("failed to build EML: %v", err).WithCause(err)
 		}
 
 		draftResult, err := draftpkg.CreateWithRaw(runtime, mailboxID, rawEML)
 		if err != nil {
-			return fmt.Errorf("failed to create draft: %w", err)
+			return mailDecorateProblemMessage(err, "failed to create draft")
 		}
 		showLintDetails := runtime.Bool("show-lint-details")
 		if !confirmSend {
@@ -354,7 +354,7 @@ var MailReply = common.Shortcut{
 		}
 		resData, err := draftpkg.Send(runtime, mailboxID, draftResult.DraftID, sendTime)
 		if err != nil {
-			return fmt.Errorf("failed to send reply (draft %s created but not sent): %w", draftResult.DraftID, err)
+			return mailDecorateProblemMessage(err, "failed to send reply (draft %s created but not sent)", draftResult.DraftID)
 		}
 		out := buildDraftSendOutput(resData, mailboxID)
 		applyLintToEnvelope(out, lintApplied, lintBlocked, showLintDetails)

shortcuts/mail/mail_reply_all.go

@@ -139,7 +139,7 @@ var MailReplyAll = common.Shortcut{
 		}
 		sourceMsg, err := fetchComposeSourceMessage(runtime, mailboxID, messageId)
 		if err != nil {
-			return fmt.Errorf("failed to fetch original message: %w", err)
+			return mailDecorateProblemMessage(err, "failed to fetch original message")
 		}
 		orig := sourceMsg.Original
 		stripLargeAttachmentCard(&orig)
@@ -226,7 +226,7 @@ var MailReplyAll = common.Shortcut{
 
 		useHTML := !plainText && (bodyIsHTML(body) || bodyIsHTML(orig.bodyRaw) || sigResult != nil)
 		if strings.TrimSpace(inlineFlag) != "" && !useHTML {
-			return fmt.Errorf("--inline requires HTML mode, but neither the new body nor the original message contains HTML")
+			return mailValidationParamError("--inline", "--inline requires HTML mode, but neither the new body nor the original message contains HTML")
 		}
 		var bodyStr string
 		if useHTML {
@@ -271,7 +271,7 @@ var MailReplyAll = common.Shortcut{
 		lintApplied, lintBlocked := emptyLintEnvelopeFields()
 		if useHTML {
 			if err := validateInlineImageURLs(sourceMsg); err != nil {
-				return fmt.Errorf("HTML reply-all blocked: %w", err)
+				return mailDecorateProblemMessage(err, "HTML reply-all blocked")
 			}
 			var srcCIDs []string
 			bld, srcCIDs, srcInlineBytes, err = addInlineImagesToBuilder(runtime, bld, sourceMsg.InlineImages)
@@ -280,7 +280,7 @@ var MailReplyAll = common.Shortcut{
 			}
 			resolved, refs, resolveErr := draftpkg.ResolveLocalImagePaths(bodyStr)
 			if resolveErr != nil {
-				return resolveErr
+				return mailValidationError("failed to resolve local image paths: %v", resolveErr).WithCause(resolveErr)
 			}
 			bodyWithSig := resolved
 			if sigResult != nil {
@@ -341,12 +341,12 @@ var MailReplyAll = common.Shortcut{
 		}
 		rawEML, err := bld.BuildBase64URL()
 		if err != nil {
-			return fmt.Errorf("failed to build EML: %w", err)
+			return mailValidationError("failed to build EML: %v", err).WithCause(err)
 		}
 
 		draftResult, err := draftpkg.CreateWithRaw(runtime, mailboxID, rawEML)
 		if err != nil {
-			return fmt.Errorf("failed to create draft: %w", err)
+			return mailDecorateProblemMessage(err, "failed to create draft")
 		}
 		showLintDetails := runtime.Bool("show-lint-details")
 		if !confirmSend {
@@ -359,7 +359,7 @@ var MailReplyAll = common.Shortcut{
 		}
 		resData, err := draftpkg.Send(runtime, mailboxID, draftResult.DraftID, sendTime)
 		if err != nil {
-			return fmt.Errorf("failed to send reply-all (draft %s created but not sent): %w", draftResult.DraftID, err)
+			return mailDecorateProblemMessage(err, "failed to send reply-all (draft %s created but not sent)", draftResult.DraftID)
 		}
 		out := buildDraftSendOutput(resData, mailboxID)
 		applyLintToEnvelope(out, lintApplied, lintBlocked, showLintDetails)

shortcuts/mail/mail_send.go

@@ -8,7 +8,6 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
 	"github.com/larksuite/cli/shortcuts/mail/emlbuilder"
@@ -83,7 +82,7 @@ var MailSend = common.Shortcut{
 			return err
 		}
 		if !hasTemplate && strings.TrimSpace(runtime.Str("subject")) == "" {
-			return output.ErrValidation("--subject is required; pass the final email subject (or use --template-id)")
+			return mailValidationParamError("--subject", "--subject is required; pass the final email subject (or use --template-id)")
 		}
 		// With --template-id, tos/ccs/bccs may come from the template, so
 		// defer the at-least-one-recipient check to Execute (after
@@ -241,7 +240,7 @@ var MailSend = common.Shortcut{
 			}
 			resolved, refs, resolveErr := draftpkg.ResolveLocalImagePaths(htmlBody)
 			if resolveErr != nil {
-				return resolveErr
+				return mailValidationError("failed to resolve local image paths: %v", resolveErr).WithCause(resolveErr)
 			}
 			resolved = injectSignatureIntoBody(resolved, sigResult)
 			// Writing-path lint: AutoFix=true / Strict=false — the writing-path
@@ -308,12 +307,12 @@ var MailSend = common.Shortcut{
 
 		rawEML, err := bld.BuildBase64URL()
 		if err != nil {
-			return fmt.Errorf("failed to build EML: %w", err)
+			return mailValidationError("failed to build EML: %v", err).WithCause(err)
 		}
 
 		draftResult, err := draftpkg.CreateWithRaw(runtime, mailboxID, rawEML)
 		if err != nil {
-			return fmt.Errorf("failed to create draft: %w", err)
+			return mailDecorateProblemMessage(err, "failed to create draft")
 		}
 		showLintDetails := runtime.Bool("show-lint-details")
 		if !confirmSend {
@@ -326,7 +325,7 @@ var MailSend = common.Shortcut{
 		}
 		resData, err := draftpkg.Send(runtime, mailboxID, draftResult.DraftID, sendTime)
 		if err != nil {
-			return fmt.Errorf("failed to send email (draft %s created but not sent): %w", draftResult.DraftID, err)
+			return mailDecorateProblemMessage(err, "failed to send email (draft %s created but not sent)", draftResult.DraftID)
 		}
 		out := buildDraftSendOutput(resData, mailboxID)
 		applyLintToEnvelope(out, lintApplied, lintBlocked, showLintDetails)

shortcuts/mail/mail_send_receipt.go

@@ -113,10 +113,11 @@ var MailSendReceipt = common.Shortcut{
 
 		msg, err := fetchFullMessage(runtime, mailboxID, messageID, false)
 		if err != nil {
-			return fmt.Errorf("failed to fetch original message: %w", err)
+			return mailDecorateProblemMessage(err, "failed to fetch original message")
 		}
 		if !hasReadReceiptRequestLabel(msg) {
-			return fmt.Errorf("message %s did not request a read receipt (no %s label); refusing to send receipt", messageID, readReceiptRequestLabel)
+			return mailFailedPreconditionError("message %s did not request a read receipt (no %s label); refusing to send receipt", messageID, readReceiptRequestLabel).
+				WithHint("only run +send-receipt for incoming messages that carry the READ_RECEIPT_REQUEST label")
 		}
 
 		origSubject := strVal(msg["subject"])
@@ -126,12 +127,12 @@ var MailSendReceipt = common.Shortcut{
 		origSendMillis := parseInternalDateMillis(msg["internal_date"])
 
 		if origFromEmail == "" {
-			return fmt.Errorf("original message %s has no sender address; cannot address receipt", messageID)
+			return mailFailedPreconditionError("original message %s has no sender address; cannot address receipt", messageID)
 		}
 
 		senderEmail := resolveComposeSenderEmail(runtime)
 		if senderEmail == "" {
-			return fmt.Errorf("unable to determine sender email; please specify --from explicitly")
+			return mailValidationParamError("--from", "unable to determine sender email; please specify --from explicitly")
 		}
 
 		lang := detectSubjectLang(origSubject)
@@ -158,16 +159,16 @@ var MailSendReceipt = common.Shortcut{
 
 		rawEML, err := bld.BuildBase64URL()
 		if err != nil {
-			return fmt.Errorf("failed to build receipt EML: %w", err)
+			return mailValidationError("failed to build receipt EML: %v", err).WithCause(err)
 		}
 
 		draftResult, err := draftpkg.CreateWithRaw(runtime, mailboxID, rawEML)
 		if err != nil {
-			return fmt.Errorf("failed to create receipt draft: %w", err)
+			return mailDecorateProblemMessage(err, "failed to create receipt draft")
 		}
 		resData, err := draftpkg.Send(runtime, mailboxID, draftResult.DraftID, "")
 		if err != nil {
-			return fmt.Errorf("failed to send receipt (draft %s created but not sent): %w", draftResult.DraftID, err)
+			return mailDecorateProblemMessage(err, "failed to send receipt (draft %s created but not sent)", draftResult.DraftID)
 		}
 
 		out := buildDraftSendOutput(resData, mailboxID)

shortcuts/mail/mail_share_to_chat.go

@@ -5,9 +5,7 @@ package mail
 
 import (
 	"context"
-	"fmt"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -66,14 +64,22 @@ var MailShareToChat = common.Shortcut{
 		msgID := runtime.Str("message-id")
 		threadID := runtime.Str("thread-id")
 		if msgID == "" && threadID == "" {
-			return output.ErrValidation("either --message-id or --thread-id is required")
+			return mailValidationError("either --message-id or --thread-id is required").
+				WithParams(
+					mailInvalidParam("--message-id", "required when --thread-id is empty"),
+					mailInvalidParam("--thread-id", "required when --message-id is empty"),
+				)
 		}
 		if msgID != "" && threadID != "" {
-			return output.ErrValidation("--message-id and --thread-id are mutually exclusive")
+			return mailValidationError("--message-id and --thread-id are mutually exclusive").
+				WithParams(
+					mailInvalidParam("--message-id", "mutually exclusive with --thread-id"),
+					mailInvalidParam("--thread-id", "mutually exclusive with --message-id"),
+				)
 		}
 		idType := runtime.Str("receive-id-type")
 		if !validReceiveIDTypes[idType] {
-			return output.ErrValidation("--receive-id-type must be one of: chat_id, open_id, user_id, union_id, email")
+			return mailValidationParamError("--receive-id-type", "--receive-id-type must be one of: chat_id, open_id, user_id, union_id, email")
 		}
 		return nil
 	},
@@ -90,23 +96,23 @@ var MailShareToChat = common.Shortcut{
 		} else {
 			createBody = map[string]interface{}{"message_id": msgID}
 		}
-		createResp, err := runtime.CallAPI("POST",
+		createResp, err := runtime.CallAPITyped("POST",
 			mailboxPath(mailboxID, "messages", "share_token"),
 			nil, createBody)
 		if err != nil {
-			return fmt.Errorf("create share token: %w", err)
+			return mailDecorateProblemMessage(err, "create share token")
 		}
 		cardID, _ := createResp["card_id"].(string)
 		if cardID == "" {
-			return fmt.Errorf("create share token: response missing card_id")
+			return mailInvalidResponseError("create share token: response missing card_id")
 		}
 
-		sendResp, err := runtime.CallAPI("POST",
+		sendResp, err := runtime.CallAPITyped("POST",
 			mailboxPath(mailboxID, "share_tokens", cardID, "send"),
 			map[string]interface{}{"receive_id_type": receiveIDType},
 			map[string]interface{}{"receive_id": receiveID})
 		if err != nil {
-			return fmt.Errorf("share token created (card_id=%s) but send failed: %w", cardID, err)
+			return mailDecorateProblemMessage(err, "share token created (card_id=%s) but send failed", cardID)
 		}
 
 		runtime.Out(map[string]interface{}{

shortcuts/mail/mail_shortcut_validation_test.go

@@ -16,16 +16,13 @@ import (
 
 // assertValidationError fails the test unless err carries the validation
 // category with ExitValidation exit code and a message containing wantSubstr.
-// Accepts both typed *errs.ValidationError and legacy *output.ExitError so
-// the helper survives the error-contract migration.
+// Mail-produced validation errors should be typed; the exit-code fallback keeps
+// shared framework validation gates covered without asserting their shape here.
 func assertValidationError(t *testing.T, err error, wantSubstr string) {
 	t.Helper()
 	if err == nil {
 		t.Fatal("expected a validation error, got nil")
 	}
-	// Accept both typed *errs.ValidationError and legacy *output.ExitError —
-	// the helper's purpose is to assert "this is a validation-category
-	// error" via either contract, so the dual-path matches the docstring.
 	code := output.ExitCodeOf(err)
 	if !errs.IsValidation(err) && code != output.ExitValidation {
 		t.Fatalf("expected a validation-category error, got %T: %v", err, err)
@@ -190,6 +187,10 @@ func validMessageIDForTest(s string) string {
 	return base64.URLEncoding.EncodeToString([]byte(s))
 }
 
+func rawMessageIDForTest(s string) string {
+	return base64.RawURLEncoding.EncodeToString([]byte(s))
+}
+
 func TestValidateMessageIDsAcceptsValidIDs(t *testing.T) {
 	_, err := validateMessageIDs(validMessageIDForTest("biz-001") + "," + validMessageIDForTest("biz-002"))
 	if err != nil {
@@ -197,6 +198,13 @@ func TestValidateMessageIDsAcceptsValidIDs(t *testing.T) {
 	}
 }
 
+func TestValidateMessageIDsAcceptsRawBase64URLIDs(t *testing.T) {
+	_, err := validateMessageIDs(rawMessageIDForTest("biz-raw-001"))
+	if err != nil {
+		t.Fatalf("expected nil error for raw base64url ID, got: %v", err)
+	}
+}
+
 func TestValidateMessageIDsRejectsEmpty(t *testing.T) {
 	_, err := validateMessageIDs("")
 	assertValidationError(t, err, "--message-ids is required")

shortcuts/mail/mail_signature.go

@@ -110,7 +110,7 @@ func executeSignatureDetail(runtime *common.RuntimeContext, resp *signature.GetS
 		}
 	}
 	if sig == nil {
-		return output.ErrValidation("signature not found: %s", sigID)
+		return mailValidationParamError("--detail", "signature not found: %s", sigID)
 	}
 
 	lang := resolveLang(runtime)

shortcuts/mail/mail_template_create.go

@@ -9,7 +9,6 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -79,13 +78,17 @@ var MailTemplateCreate = common.Shortcut{
 			return err
 		}
 		if strings.TrimSpace(runtime.Str("name")) == "" {
-			return output.ErrValidation("--name is required")
+			return mailValidationParamError("--name", "--name is required")
 		}
 		if len([]rune(runtime.Str("name"))) > 100 {
-			return output.ErrValidation("--name must be at most 100 characters")
+			return mailValidationParamError("--name", "--name must be at most 100 characters")
 		}
 		if runtime.Str("template-content") != "" && runtime.Str("template-content-file") != "" {
-			return output.ErrValidation("--template-content and --template-content-file are mutually exclusive")
+			return mailValidationError("--template-content and --template-content-file are mutually exclusive").
+				WithParams(
+					mailInvalidParam("--template-content", "mutually exclusive with --template-content-file"),
+					mailInvalidParam("--template-content-file", "mutually exclusive with --template-content"),
+				)
 		}
 		return nil
 	},
@@ -104,7 +107,7 @@ var MailTemplateCreate = common.Shortcut{
 
 		content = wrapTemplateContentIfNeeded(content, isPlainText)
 		if int64(len(content)) > maxTemplateContentBytes {
-			return output.ErrValidation("template content exceeds %d MB (got %.1f MB)",
+			return mailFailedPreconditionError("template content exceeds %d MB (got %.1f MB)",
 				maxTemplateContentBytes/(1024*1024),
 				float64(len(content))/1024/1024)
 		}
@@ -142,7 +145,7 @@ var MailTemplateCreate = common.Shortcut{
 
 		resp, err := createTemplate(runtime, mailboxID, payload)
 		if err != nil {
-			return fmt.Errorf("create template failed: %w", err)
+			return mailDecorateProblemMessage(err, "create template failed")
 		}
 		tpl, _ := extractTemplatePayload(resp)
 		out := map[string]interface{}{
@@ -173,12 +176,12 @@ func resolveTemplateContent(runtime *common.RuntimeContext) (content, sourcePath
 	}
 	f, err := runtime.FileIO().Open(path)
 	if err != nil {
-		return "", path, output.ErrValidation("open --template-content-file %s: %v", path, err)
+		return "", path, mailValidationParamError("--template-content-file", "open --template-content-file %s: %v", path, err).WithCause(mailInputStatError(err))
 	}
 	defer f.Close()
 	buf, err := io.ReadAll(f)
 	if err != nil {
-		return "", path, output.ErrValidation("read --template-content-file %s: %v", path, err)
+		return "", path, mailValidationParamError("--template-content-file", "read --template-content-file %s: %v", path, err).WithCause(err)
 	}
 	return string(buf), path, nil
 }

shortcuts/mail/mail_template_update.go

@@ -10,7 +10,6 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -93,13 +92,17 @@ var MailTemplateUpdate = common.Shortcut{
 			return err
 		}
 		if runtime.Str("template-id") == "" {
-			return output.ErrValidation("--template-id is required (or use --print-patch-template to print the patch skeleton)")
+			return mailValidationParamError("--template-id", "--template-id is required (or use --print-patch-template to print the patch skeleton)")
 		}
 		if runtime.Str("set-template-content") != "" && runtime.Str("set-template-content-file") != "" {
-			return output.ErrValidation("--set-template-content and --set-template-content-file are mutually exclusive")
+			return mailValidationError("--set-template-content and --set-template-content-file are mutually exclusive").
+				WithParams(
+					mailInvalidParam("--set-template-content", "mutually exclusive with --set-template-content-file"),
+					mailInvalidParam("--set-template-content-file", "mutually exclusive with --set-template-content"),
+				)
 		}
 		if name := runtime.Str("set-name"); name != "" && len([]rune(name)) > 100 {
-			return output.ErrValidation("--set-name must be at most 100 characters")
+			return mailValidationParamError("--set-name", "--set-name must be at most 100 characters")
 		}
 		return nil
 	},
@@ -171,16 +174,16 @@ var MailTemplateUpdate = common.Shortcut{
 		if pf := strings.TrimSpace(runtime.Str("patch-file")); pf != "" {
 			f, err := runtime.FileIO().Open(pf)
 			if err != nil {
-				return output.ErrValidation("open --patch-file %s: %v", pf, err)
+				return mailValidationParamError("--patch-file", "open --patch-file %s: %v", pf, err).WithCause(mailInputStatError(err))
 			}
 			buf, readErr := io.ReadAll(f)
 			f.Close()
 			if readErr != nil {
-				return output.ErrValidation("read --patch-file %s: %v", pf, readErr)
+				return mailValidationParamError("--patch-file", "read --patch-file %s: %v", pf, readErr).WithCause(readErr)
 			}
 			var patch templatePatchFile
 			if err := json.Unmarshal(buf, &patch); err != nil {
-				return output.ErrValidation("parse --patch-file %s: %v", pf, err)
+				return mailValidationParamError("--patch-file", "parse --patch-file %s: %v", pf, err).WithCause(err)
 			}
 			if patch.TemplateContent != nil {
 				contentChanged = true
@@ -198,7 +201,7 @@ var MailTemplateUpdate = common.Shortcut{
 			tpl.TemplateContent = wrapTemplateContentIfNeeded(tpl.TemplateContent, tpl.IsPlainTextMode)
 		}
 		if int64(len(tpl.TemplateContent)) > maxTemplateContentBytes {
-			return output.ErrValidation("template content exceeds %d MB (got %.1f MB)",
+			return mailFailedPreconditionError("template content exceeds %d MB (got %.1f MB)",
 				maxTemplateContentBytes/(1024*1024),
 				float64(len(tpl.TemplateContent))/1024/1024)
 		}
@@ -278,7 +281,7 @@ var MailTemplateUpdate = common.Shortcut{
 
 		resp, err := updateTemplate(runtime, mailboxID, tid, tpl)
 		if err != nil {
-			return fmt.Errorf("update template failed: %w", err)
+			return mailDecorateProblemMessage(err, "update template failed")
 		}
 		updated, _ := extractTemplatePayload(resp)
 		out := map[string]interface{}{
@@ -312,12 +315,12 @@ func resolveTemplateUpdateContent(runtime *common.RuntimeContext) (content, sour
 	}
 	f, err := runtime.FileIO().Open(path)
 	if err != nil {
-		return "", path, output.ErrValidation("open --set-template-content-file %s: %v", path, err)
+		return "", path, mailValidationParamError("--set-template-content-file", "open --set-template-content-file %s: %v", path, err).WithCause(mailInputStatError(err))
 	}
 	defer f.Close()
 	buf, err := io.ReadAll(f)
 	if err != nil {
-		return "", path, output.ErrValidation("read --set-template-content-file %s: %v", path, err)
+		return "", path, mailValidationParamError("--set-template-content-file", "read --set-template-content-file %s: %v", path, err).WithCause(err)
 	}
 	return string(buf), path, nil
 }

shortcuts/mail/mail_thread.go

@@ -5,7 +5,6 @@ package mail
 
 import (
 	"context"
-	"fmt"
 	"sort"
 	"strconv"
 
@@ -88,9 +87,9 @@ var MailThread = common.Shortcut{
 		if runtime.Bool("include-spam-trash") {
 			params["include_spam_trash"] = true
 		}
-		listData, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "threads", threadID), params, nil)
+		listData, err := runtime.CallAPITyped("GET", mailboxPath(mailboxID, "threads", threadID), params, nil)
 		if err != nil {
-			return fmt.Errorf("failed to get thread: %w", err)
+			return mailDecorateProblemMessage(err, "failed to get thread")
 		}
 		// New API: data.thread.messages[]; fallback to old API: data.items[].message
 		var items []interface{}

shortcuts/mail/mail_triage.go

@@ -4,7 +4,6 @@
 package mail
 
 import (
-	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
@@ -13,6 +12,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -140,7 +141,7 @@ var MailTriage = common.Shortcut{
 		outFormat := runtime.Str("format")
 		query := runtime.Str("query")
 		if query != "" {
-			if err := common.RejectDangerousChars("--query", query); err != nil {
+			if err := common.RejectDangerousCharsTyped("--query", query); err != nil {
 				return err
 			}
 		}
@@ -265,10 +266,18 @@ var MailTriage = common.Shortcut{
 			messages = []map[string]interface{}{}
 		}
 
+		// Inject mailbox_id into every message so downstream consumers
+		// (e.g. mail +message) can preserve the mailbox context for
+		// public/shared mailbox scenarios.
+		for _, msg := range messages {
+			msg["mailbox_id"] = mailbox
+		}
+
 		switch outFormat {
 		case "json", "data":
 			outData := map[string]interface{}{
 				"messages":   messages,
+				"mailbox_id": mailbox,
 				"count":      len(messages),
 				"has_more":   hasMore,
 				"page_token": nextPageToken,
@@ -287,6 +296,9 @@ var MailTriage = common.Shortcut{
 					"subject":    sanitizeForTerminal(strVal(msg["subject"])),
 					"message_id": msg["message_id"],
 				}
+				if mailbox != "me" {
+					row["mailbox_id"] = mailbox
+				}
 				if showLabels {
 					row["labels"] = msg["labels"]
 				}
@@ -297,6 +309,9 @@ var MailTriage = common.Shortcut{
 			if hasMore && nextPageToken != "" {
 				var hint strings.Builder
 				hint.WriteString("next page: mail +triage")
+				if mailbox != "me" {
+					hint.WriteString(" --mailbox " + shellQuote(mailbox))
+				}
 				if query != "" {
 					hint.WriteString(" --query " + shellQuote(query))
 				}
@@ -306,7 +321,11 @@ var MailTriage = common.Shortcut{
 				hint.WriteString(" --page-token " + shellQuote(nextPageToken))
 				fmt.Fprintln(runtime.IO().ErrOut, hint.String())
 			}
-			fmt.Fprintln(runtime.IO().ErrOut, "tip: use mail +message --message-id <id> to read full content")
+			if mailbox != "me" {
+				fmt.Fprintln(runtime.IO().ErrOut, "tip: use mail +message --mailbox "+shellQuote(mailbox)+" --message-id <id> to read full content")
+			} else {
+				fmt.Fprintln(runtime.IO().ErrOut, "tip: use mail +message --message-id <id> to read full content")
+			}
 		}
 		return nil
 	},
@@ -403,9 +422,9 @@ func parseTriageFilter(filterStr string) (triageFilter, error) {
 	dec.DisallowUnknownFields()
 	if err := dec.Decode(&filter); err != nil {
 		if hint := triageFilterUnknownFieldHint(err.Error()); hint != "" {
-			return triageFilter{}, output.ErrValidation("invalid --filter: %s", hint)
+			return triageFilter{}, mailValidationParamError("--filter", "invalid --filter: %s", hint)
 		}
-		return triageFilter{}, output.ErrValidation("invalid --filter: %s", err)
+		return triageFilter{}, mailValidationParamError("--filter", "invalid --filter: %s", err)
 	}
 	return filter, nil
 }
@@ -924,16 +943,16 @@ func resolveTriagePath(parsed triagePageToken, query string, filter triageFilter
 	switch parsed.Path {
 	case "search":
 		if !paramWantsSearch && (strings.TrimSpace(query) != "" || len(triageQueryFilterFields(filter)) > 0) {
-			return false, fmt.Errorf("--page-token has search: prefix but current --query/--filter parameters indicate list path; remove conflicting parameters or use the correct token")
+			return false, mailValidationParamError("--page-token", "--page-token has search: prefix but current --query/--filter parameters indicate list path; remove conflicting parameters or use the correct token")
 		}
 		return true, nil
 	case "list":
 		if paramWantsSearch {
-			return false, fmt.Errorf("--page-token has list: prefix but --query or --filter contains search-only fields (e.g. from/to/subject); these parameters would be silently ignored — remove them or use a search: token")
+			return false, mailValidationParamError("--page-token", "--page-token has list: prefix but --query or --filter contains search-only fields (e.g. from/to/subject); these parameters would be silently ignored; remove them or use a search: token")
 		}
 		return false, nil
 	default:
-		return false, fmt.Errorf("invalid --page-token: must start with 'search:' or 'list:' prefix (token was obtained from a previous mail +triage response)")
+		return false, mailValidationParamError("--page-token", "invalid --page-token: must start with 'search:' or 'list:' prefix (token was obtained from a previous mail +triage response)")
 	}
 }
 
@@ -960,15 +979,15 @@ func parseTriagePageToken(token string) (triagePageToken, error) {
 	}
 	idx := strings.IndexByte(token, ':')
 	if idx < 0 {
-		return triagePageToken{}, fmt.Errorf("invalid --page-token: must start with 'search:' or 'list:' prefix (token was obtained from a previous mail +triage response)")
+		return triagePageToken{}, mailValidationParamError("--page-token", "invalid --page-token: must start with 'search:' or 'list:' prefix (token was obtained from a previous mail +triage response)")
 	}
 	path := token[:idx]
 	raw := token[idx+1:]
 	if path != "search" && path != "list" {
-		return triagePageToken{}, fmt.Errorf("invalid --page-token: must start with 'search:' or 'list:' prefix, got %q", path)
+		return triagePageToken{}, mailValidationParamError("--page-token", "invalid --page-token: must start with 'search:' or 'list:' prefix, got %q", path)
 	}
 	if raw == "" {
-		return triagePageToken{}, fmt.Errorf("invalid --page-token: token value is empty after '%s:' prefix", path)
+		return triagePageToken{}, mailValidationParamError("--page-token", "invalid --page-token: token value is empty after '%s:' prefix", path)
 	}
 	return triagePageToken{Path: path, RawToken: raw}, nil
 }
@@ -1090,24 +1109,18 @@ func doJSONAPI(runtime *common.RuntimeContext, req *larkcore.ApiReq, action stri
 	var lastErr error
 	for attempt := 0; attempt <= triageAPIRetries; attempt++ {
 		apiResp, err := runtime.DoAPI(req)
-		if err == nil {
-			var result interface{}
-			dec := json.NewDecoder(bytes.NewReader(apiResp.RawBody))
-			dec.UseNumber()
-			if err := dec.Decode(&result); err != nil {
-				return nil, output.Errorf(output.ExitAPI, "api_error", "%s: response parse error: %s", action, err)
+		if err != nil {
+			lastErr = mailDecorateProblemMessage(client.WrapDoAPIError(err), "%s", action)
+			if attempt == triageAPIRetries {
+				return nil, lastErr
 			}
-			data, handleErr := common.HandleApiResult(result, nil, action)
+		} else {
+			data, handleErr := runtime.ClassifyAPIResponse(apiResp)
 			if handleErr == nil {
 				return data, nil
 			}
-			lastErr = handleErr
-			if !shouldRetryTriageAPIError(handleErr) || attempt == triageAPIRetries {
-				return nil, handleErr
-			}
-		} else {
-			lastErr = output.Errorf(output.ExitAPI, "api_error", "%s: %s", action, err)
-			if attempt == triageAPIRetries {
+			lastErr = mailDecorateProblemMessage(handleErr, "%s", action)
+			if !shouldRetryTriageAPIError(lastErr) || attempt == triageAPIRetries {
 				return nil, lastErr
 			}
 		}
@@ -1117,11 +1130,11 @@ func doJSONAPI(runtime *common.RuntimeContext, req *larkcore.ApiReq, action stri
 }
 
 func shouldRetryTriageAPIError(err error) bool {
-	exitErr, ok := err.(*output.ExitError)
-	if !ok || exitErr.Detail == nil {
+	p, ok := errs.ProblemOf(err)
+	if !ok {
 		return false
 	}
-	return exitErr.Detail.Type == "rate_limit" || exitErr.Code == output.ExitNetwork
+	return p.Subtype == errs.SubtypeRateLimit || p.Category == errs.CategoryNetwork
 }
 
 func toQueryParams(params map[string]interface{}) larkcore.QueryParams {

shortcuts/mail/mail_triage_test.go

@@ -7,10 +7,13 @@ import (
 	"context"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
@@ -119,6 +122,36 @@ func TestBuildSearchParamsSystemLabelAsFolder(t *testing.T) {
 	}
 }
 
+func TestMailTriageRejectsDangerousQueryWithTypedValidation(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailTriage, []string{
+		"+triage", "--as", "user", "--query", "bad\x01",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected dangerous --query to return an error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryValidation {
+		t.Errorf("category = %q, want %q", p.Category, errs.CategoryValidation)
+	}
+	if p.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("subtype = %q, want %q", p.Subtype, errs.SubtypeInvalidArgument)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected ValidationError, got %T: %v", err, err)
+	}
+	if validationErr.Param != "--query" {
+		t.Errorf("param = %q, want --query", validationErr.Param)
+	}
+	if !strings.Contains(p.Message, "control character") {
+		t.Errorf("message should mention control character, got: %s", p.Message)
+	}
+}
+
 func TestSystemLabelViaFolderField(t *testing.T) {
 	// System label passed via folder field should also be converted to search folder value.
 	runtime := runtimeForMailTriageTest(t, map[string]string{
@@ -706,6 +739,43 @@ func TestFormatAddressFallbackToAddress(t *testing.T) {
 	}
 }
 
+func TestShouldRetryTriageAPIError(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{
+			name: "rate limit",
+			err:  errs.NewAPIError(errs.SubtypeRateLimit, "too many requests"),
+			want: true,
+		},
+		{
+			name: "network",
+			err:  errs.NewNetworkError(errs.SubtypeNetworkTransport, "dial timeout"),
+			want: true,
+		},
+		{
+			name: "validation",
+			err:  errs.NewValidationError(errs.SubtypeInvalidArgument, "bad query"),
+			want: false,
+		},
+		{
+			name: "plain",
+			err:  assertErr("legacy plain error"),
+			want: false,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := shouldRetryTriageAPIError(tc.err); got != tc.want {
+				t.Fatalf("shouldRetryTriageAPIError() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
 // --- extractTriageMessageIDs ---
 
 func TestExtractTriageMessageIDsStringItems(t *testing.T) {
@@ -1405,3 +1475,279 @@ func TestParseTriagePageTokenInvalidPrefix(t *testing.T) {
 }
 
 func boolPtr(v bool) *bool { return &v }
+
+// --- mailbox_id preservation tests ---
+
+func TestMailTriageStructuredOutputPreservesMailboxID(t *testing.T) {
+	tests := []struct {
+		name      string
+		mailbox   string
+		format    string
+		args      []string
+		register  func(*httpmock.Registry, string)
+		wantCount int
+	}{
+		{
+			name:    "list json default mailbox",
+			mailbox: "me",
+			format:  "json",
+			args:    []string{"--filter", `{"folder_id":"INBOX"}`},
+			register: func(reg *httpmock.Registry, mailbox string) {
+				registerMailTriageListStub(reg, mailbox, []string{"msg_001", "msg_002"}, false, "")
+				registerMailTriageBatchStub(reg, mailbox, []map[string]interface{}{
+					mailTriageBatchMessage("msg_001", "Subject 1"),
+					mailTriageBatchMessage("msg_002", "Subject 2"),
+				})
+			},
+			wantCount: 2,
+		},
+		{
+			name:    "list data public mailbox",
+			mailbox: "shared@company.com",
+			format:  "data",
+			args:    []string{"--filter", `{"folder_id":"INBOX"}`},
+			register: func(reg *httpmock.Registry, mailbox string) {
+				registerMailTriageListStub(reg, mailbox, []string{"msg_pub_001"}, false, "")
+				registerMailTriageBatchStub(reg, mailbox, []map[string]interface{}{
+					mailTriageBatchMessage("msg_pub_001", "Shared mailbox message"),
+				})
+			},
+			wantCount: 1,
+		},
+		{
+			name:    "search json public mailbox",
+			mailbox: "shared@corp.com",
+			format:  "json",
+			args:    []string{"--query", "shared keyword"},
+			register: func(reg *httpmock.Registry, mailbox string) {
+				registerMailTriageSearchStub(reg, mailbox, []interface{}{
+					mailTriageSearchItem("search_pub_001", "Shared search"),
+				}, false, "")
+			},
+			wantCount: 1,
+		},
+		{
+			name:    "empty list json keeps top-level mailbox",
+			mailbox: "me",
+			format:  "json",
+			args:    []string{"--filter", `{"folder_id":"INBOX"}`},
+			register: func(reg *httpmock.Registry, mailbox string) {
+				registerMailTriageListStub(reg, mailbox, nil, false, "")
+			},
+			wantCount: 0,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, stdout, _, reg := mailShortcutTestFactory(t)
+			defer reg.Verify(t)
+
+			tt.register(reg, tt.mailbox)
+
+			args := []string{"+triage", "--format", tt.format}
+			if tt.mailbox != "me" {
+				args = append(args, "--mailbox", tt.mailbox)
+			}
+			args = append(args, tt.args...)
+
+			if err := runMountedMailShortcut(t, MailTriage, args, f, stdout); err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			data := decodeMailTriageJSONOutput(t, stdout)
+			if data["mailbox_id"] != tt.mailbox {
+				t.Fatalf("top-level mailbox_id mismatch: got %v, want %q", data["mailbox_id"], tt.mailbox)
+			}
+			messages := mailTriageMessagesFromOutput(t, data)
+			if len(messages) != tt.wantCount {
+				t.Fatalf("message count mismatch: got %d, want %d", len(messages), tt.wantCount)
+			}
+			for i, msg := range messages {
+				if msg["mailbox_id"] != tt.mailbox {
+					t.Fatalf("message[%d] mailbox_id mismatch: got %v, want %q", i, msg["mailbox_id"], tt.mailbox)
+				}
+			}
+		})
+	}
+}
+
+func TestMailTriageMissingMessageMetadataStillGetsMailboxID(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	defer reg.Verify(t)
+
+	registerMailTriageListStub(reg, "me", []string{"msg_ok", "msg_missing"}, false, "")
+	registerMailTriageBatchStub(reg, "me", []map[string]interface{}{
+		mailTriageBatchMessage("msg_ok", "Present"),
+	})
+
+	err := runMountedMailShortcut(t, MailTriage, []string{
+		"+triage",
+		"--format", "json",
+		"--filter", `{"folder_id":"INBOX"}`,
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	messages := mailTriageMessagesFromOutput(t, decodeMailTriageJSONOutput(t, stdout))
+	if len(messages) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(messages))
+	}
+	for i, msg := range messages {
+		if msg["mailbox_id"] != "me" {
+			t.Fatalf("message[%d] mailbox_id mismatch: got %v, want me", i, msg["mailbox_id"])
+		}
+	}
+	if messages[1]["message_id"] != "msg_missing" || messages[1]["error"] == nil {
+		t.Fatalf("missing metadata placeholder mismatch: %#v", messages[1])
+	}
+}
+
+func TestMailTriageTableOutputPreservesMailboxContext(t *testing.T) {
+	tests := []struct {
+		name              string
+		mailbox           string
+		hasMore           bool
+		wantMailboxColumn bool
+		wantMailboxHint   bool
+	}{
+		{name: "default mailbox", mailbox: "me"},
+		{name: "public mailbox", mailbox: "shared@company.com", hasMore: true, wantMailboxColumn: true, wantMailboxHint: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, stdout, stderr, reg := mailShortcutTestFactory(t)
+			defer reg.Verify(t)
+
+			registerMailTriageListStub(reg, tt.mailbox, []string{"msg_001"}, tt.hasMore, "next_page_token")
+			registerMailTriageBatchStub(reg, tt.mailbox, []map[string]interface{}{
+				mailTriageBatchMessage("msg_001", "Table message"),
+			})
+
+			args := []string{"+triage", "--max", "1", "--filter", `{"folder_id":"INBOX"}`}
+			if tt.mailbox != "me" {
+				args = append(args, "--mailbox", tt.mailbox)
+			}
+			if err := runMountedMailShortcut(t, MailTriage, args, f, stdout); err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			out := stdout.String()
+			if got := strings.Contains(out, "mailbox_id"); got != tt.wantMailboxColumn {
+				t.Fatalf("mailbox_id column presence mismatch: got %v, want %v\nstdout:\n%s", got, tt.wantMailboxColumn, out)
+			}
+			if tt.wantMailboxColumn && !strings.Contains(out, tt.mailbox) {
+				t.Fatalf("table output should contain mailbox %q, stdout:\n%s", tt.mailbox, out)
+			}
+
+			errOut := stderr.String()
+			quotedMailbox := shellQuote(tt.mailbox)
+			if got := strings.Contains(errOut, "--mailbox "+quotedMailbox); got != tt.wantMailboxHint {
+				t.Fatalf("mailbox hint presence mismatch: got %v, want %v\nstderr:\n%s", got, tt.wantMailboxHint, errOut)
+			}
+			if !strings.Contains(errOut, "mail +message") {
+				t.Fatalf("stderr should contain mail +message tip, got:\n%s", errOut)
+			}
+		})
+	}
+}
+
+func decodeMailTriageJSONOutput(t *testing.T, stdout interface{ Bytes() []byte }) map[string]interface{} {
+	t.Helper()
+	var data map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &data); err != nil {
+		t.Fatalf("unmarshal stdout: %v", err)
+	}
+	return data
+}
+
+func mailTriageMessagesFromOutput(t *testing.T, data map[string]interface{}) []map[string]interface{} {
+	t.Helper()
+	rawMessages, ok := data["messages"].([]interface{})
+	if !ok {
+		t.Fatalf("messages type mismatch: %T", data["messages"])
+	}
+	messages := make([]map[string]interface{}, 0, len(rawMessages))
+	for i, item := range rawMessages {
+		msg, ok := item.(map[string]interface{})
+		if !ok {
+			t.Fatalf("messages[%d] type mismatch: %T", i, item)
+		}
+		messages = append(messages, msg)
+	}
+	return messages
+}
+
+func registerMailTriageListStub(reg *httpmock.Registry, mailbox string, items []string, hasMore bool, pageToken string) {
+	data := map[string]interface{}{
+		"items":    items,
+		"has_more": hasMore,
+	}
+	if pageToken != "" {
+		data["page_token"] = pageToken
+	}
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    mailboxPath(mailbox, "messages") + "?",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": data,
+		},
+	})
+}
+
+func registerMailTriageBatchStub(reg *httpmock.Registry, mailbox string, messages []map[string]interface{}) {
+	rawMessages := make([]interface{}, 0, len(messages))
+	for _, msg := range messages {
+		rawMessages = append(rawMessages, msg)
+	}
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    mailboxPath(mailbox, "messages", "batch_get"),
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"messages": rawMessages,
+			},
+		},
+	})
+}
+
+func registerMailTriageSearchStub(reg *httpmock.Registry, mailbox string, items []interface{}, hasMore bool, pageToken string) {
+	data := map[string]interface{}{
+		"items":    items,
+		"has_more": hasMore,
+	}
+	if pageToken != "" {
+		data["page_token"] = pageToken
+	}
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    mailboxPath(mailbox, "search"),
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": data,
+		},
+	})
+}
+
+func mailTriageBatchMessage(messageID, subject string) map[string]interface{} {
+	return map[string]interface{}{
+		"message_id": messageID,
+		"subject":    subject,
+		"head_from":  map[string]interface{}{"name": "Alice", "mail_address": "alice@example.com"},
+		"folder_id":  "INBOX",
+	}
+}
+
+func mailTriageSearchItem(messageID, subject string) map[string]interface{} {
+	return map[string]interface{}{
+		"meta_data": map[string]interface{}{
+			"message_biz_id": messageID,
+			"title":          subject,
+			"from":           map[string]interface{}{"name": "Alice", "mail_address": "alice@example.com"},
+		},
+	}
+}

shortcuts/mail/mail_watch.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -23,6 +22,8 @@ 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/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -187,7 +188,7 @@ var MailWatch = common.Shortcut{
 		switch outFormat {
 		case "json", "data", "":
 		default:
-			return output.ErrValidation("invalid --format %q: must be json or data", outFormat)
+			return mailValidationParamError("--format", "invalid --format %q: must be json or data", outFormat)
 		}
 		msgFormat := runtime.Str("msg-format")
 		outputDir := runtime.Str("output-dir")
@@ -196,18 +197,18 @@ var MailWatch = common.Shortcut{
 			// literal relative path (creating a directory named "~"), which is
 			// confusing. This also covers ~user/path forms.
 			if strings.HasPrefix(outputDir, "~") {
-				return output.ErrValidation("--output-dir does not support ~ expansion; use a relative path like ./output instead")
+				return mailValidationParamError("--output-dir", "--output-dir does not support ~ expansion; use a relative path like ./output instead")
 			}
 			// Enforce CWD containment: reject absolute paths, path traversal,
 			// and symlink escapes. SafeOutputPath returns a resolved absolute path
 			// under CWD, preventing writes to arbitrary system directories.
 			safePath, err := validate.SafeOutputPath(outputDir)
 			if err != nil {
-				return err
+				return mailValidationParamError("--output-dir", "invalid --output-dir %q: %v", outputDir, err).WithCause(err)
 			}
 			outputDir = safePath
 			if err := vfs.MkdirAll(outputDir, 0700); err != nil {
-				return fmt.Errorf("cannot create output directory %q: %w", outputDir, err)
+				return mailFileIOError("cannot create output directory %q: %v", err, outputDir, err)
 			}
 		}
 		labelIDsInput := runtime.Str("label-ids")
@@ -246,7 +247,7 @@ var MailWatch = common.Shortcut{
 
 		// Step 1: subscribe mailbox events (required before WebSocket pushes mail events)
 		info(fmt.Sprintf("Subscribing mailbox events for: %s", mailbox))
-		_, err = runtime.CallAPI("POST", mailboxPath(mailbox, "event", "subscribe"), nil, map[string]interface{}{"event_type": 1})
+		_, err = runtime.CallAPITyped("POST", mailboxPath(mailbox, "event", "subscribe"), nil, map[string]interface{}{"event_type": 1})
 		if err != nil {
 			return wrapWatchSubscribeError(err)
 		}
@@ -256,7 +257,7 @@ var MailWatch = common.Shortcut{
 		var unsubErr error
 		unsubscribe := func() error {
 			unsubOnce.Do(func() {
-				_, unsubErr = runtime.CallAPI("POST", mailboxPath(mailbox, "event", "unsubscribe"), nil, map[string]interface{}{"event_type": 1})
+				_, unsubErr = runtime.CallAPITyped("POST", mailboxPath(mailbox, "event", "unsubscribe"), nil, map[string]interface{}{"event_type": 1})
 			})
 			return unsubErr
 		}
@@ -485,7 +486,7 @@ var MailWatch = common.Shortcut{
 				if watchCtx.Err() != nil {
 					return nil
 				}
-				return output.ErrNetwork("WebSocket connection failed: %v", err)
+				return errs.NewNetworkError(errs.SubtypeNetworkTransport, "WebSocket connection failed: %v", err).WithCause(err)
 			}
 			return nil
 		}
@@ -508,7 +509,7 @@ func parseJSONArrayFlag(input, flagName string) ([]string, error) {
 	}
 	var values []string
 	if err := json.Unmarshal([]byte(trimmed), &values); err != nil {
-		return nil, output.ErrValidation("invalid --%s: expected JSON array of strings, e.g. [\"INBOX\",\"SENT\"]", flagName)
+		return nil, mailValidationParamError("--"+flagName, "invalid --%s: expected JSON array of strings, e.g. [\"INBOX\",\"SENT\"]", flagName).WithCause(err)
 	}
 	out := make([]string, 0, len(values))
 	for _, value := range values {
@@ -712,19 +713,13 @@ func fetchMessageForWatch(runtime *common.RuntimeContext, mailbox, messageID, fo
 		ApiPath:     fmt.Sprintf("/open-apis/mail/v1/user_mailboxes/%s/messages/%s", validate.EncodePathSegment(mailbox), validate.EncodePathSegment(messageID)),
 		QueryParams: queryParams,
 	})
+	if err != nil {
+		return nil, client.WrapDoAPIError(err)
+	}
+	data, err := runtime.ClassifyAPIResponse(apiResp)
 	if err != nil {
 		return nil, err
 	}
-
-	var result map[string]interface{}
-	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-		return nil, err
-	}
-	if code, _ := result["code"].(float64); code != 0 {
-		msg, _ := result["msg"].(string)
-		return nil, fmt.Errorf("[%.0f] %s", code, msg)
-	}
-	data, _ := result["data"].(map[string]interface{})
 	msg, _ := data["message"].(map[string]interface{})
 	if msg == nil {
 		return data, nil
@@ -748,29 +743,40 @@ func wrapWatchSubscribeError(err error) error {
 		return nil
 	}
 	hint := "ensure the app has scope mail:event and the event mail.user_mailbox.event.message_received_v1 is enabled"
-	if exitErr, ok := err.(*output.ExitError); ok && exitErr.Detail != nil {
-		msg := "subscribe mailbox events failed: " + exitErr.Detail.Message
-		if exitErr.Detail.Hint != "" {
-			hint = exitErr.Detail.Hint + "; " + hint
+	if p, ok := errs.ProblemOf(err); ok {
+		p.Message = "subscribe mailbox events failed: " + p.Message
+		if strings.TrimSpace(p.Hint) != "" {
+			p.Hint = p.Hint + "; " + hint
+		} else {
+			p.Hint = hint
 		}
-		return output.ErrWithHint(exitErr.Code, exitErr.Detail.Type, msg, hint)
+		return err
 	}
-	return output.ErrWithHint(output.ExitAPI, "api_error", fmt.Sprintf("subscribe mailbox events failed: %v", err), hint)
+	return errs.NewAPIError(errs.SubtypeUnknown, "subscribe mailbox events failed: %v", err).WithHint("%s", hint).WithCause(err)
 }
 
 // enhanceProfileError wraps a profile API error with actionable hints.
 // Permission errors get a scope-specific hint; other errors (network, 5xx)
 // are reported as-is so diagnostics aren't misleading.
 func enhanceProfileError(err error) error {
-	var exitErr *output.ExitError
-	if errors.As(err, &exitErr) && exitErr.Detail != nil {
-		errType := exitErr.Detail.Type
-		lower := strings.ToLower(exitErr.Detail.Message)
-		if errType == "permission" || errType == "missing_scope" ||
-			strings.Contains(lower, "permission") || strings.Contains(lower, "scope") {
-			return output.ErrWithHint(output.ExitAuth, "missing_scope",
-				"unable to resolve mailbox address: "+exitErr.Detail.Message,
-				"run `lark-cli auth login --scope \"mail:user_mailbox:readonly\"` to grant mailbox profile access")
+	if p, ok := errs.ProblemOf(err); ok {
+		lower := strings.ToLower(p.Message)
+		if p.Category == errs.CategoryAuthorization {
+			p.Message = "unable to resolve mailbox address: " + p.Message
+			p.Hint = "run `lark-cli auth login --scope \"mail:user_mailbox:readonly\"` to grant mailbox profile access"
+			return err
+		}
+		if strings.Contains(lower, "permission") || strings.Contains(lower, "scope") {
+			permErr := errs.NewPermissionError(errs.SubtypeMissingScope, "unable to resolve mailbox address: %s", p.Message).
+				WithHint("run `lark-cli auth login --scope \"mail:user_mailbox:readonly\"` to grant mailbox profile access").
+				WithCause(err)
+			if p.Code != 0 {
+				permErr = permErr.WithCode(p.Code)
+			}
+			if p.LogID != "" {
+				permErr = permErr.WithLogID(p.LogID)
+			}
+			return permErr
 		}
 	}
 	// Preserve original error (and its exit code) for non-permission failures.

shortcuts/mail/mail_watch_test.go

@@ -8,16 +8,19 @@ import (
 	"context"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
 	"strings"
 	"sync"
 	"testing"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/vfs"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
@@ -221,6 +224,72 @@ func TestMailWatchDryRunEventFormatWithLabelFilterFetchesMessage(t *testing.T) {
 	}
 }
 
+func TestMailWatchOutputDirRejectsUnsafePathTyped(t *testing.T) {
+	chdirTemp(t)
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+
+	err := runMountedMailShortcut(t, MailWatch, []string{
+		"+watch",
+		"--output-dir", "../escape",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected unsafe output-dir error")
+	}
+
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected validation error, got %T: %v", err, err)
+	}
+	if validationErr.Param != "--output-dir" {
+		t.Fatalf("param = %q, want --output-dir", validationErr.Param)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype = %q, want %q", p.Subtype, errs.SubtypeInvalidArgument)
+	}
+}
+
+func TestMailWatchOutputDirMkdirFailureTyped(t *testing.T) {
+	chdirTemp(t)
+	mkdirErr := errors.New("mkdir denied")
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	oldFS := vfs.DefaultFS
+	vfs.DefaultFS = failingMkdirFS{OsFs: vfs.OsFs{}, err: mkdirErr}
+	t.Cleanup(func() { vfs.DefaultFS = oldFS })
+
+	err := runMountedMailShortcut(t, MailWatch, []string{
+		"+watch",
+		"--output-dir", "watch-output",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected mkdir error")
+	}
+
+	var internalErr *errs.InternalError
+	if !errors.As(err, &internalErr) {
+		t.Fatalf("expected internal error, got %T: %v", err, err)
+	}
+	if !errors.Is(err, mkdirErr) {
+		t.Fatalf("cause not preserved: %v", err)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Subtype != errs.SubtypeFileIO {
+		t.Fatalf("subtype = %q, want %q", p.Subtype, errs.SubtypeFileIO)
+	}
+	if strings.Contains(p.Message, "%!(") {
+		t.Fatalf("message contains fmt extra marker: %q", p.Message)
+	}
+	if !strings.Contains(p.Message, "cannot create output directory") || !strings.Contains(p.Message, "mkdir denied") {
+		t.Fatalf("message missing context: %q", p.Message)
+	}
+}
+
 func TestWatchFetchFailureValue(t *testing.T) {
 	value := watchFetchFailureValue("msg_123", "metadata", assertErr("boom"), map[string]interface{}{
 		"mail_address": "alice@example.com",
@@ -523,24 +592,93 @@ func TestWrapWatchSubscribeErrorPlain(t *testing.T) {
 	}
 }
 
-func TestWrapWatchSubscribeErrorExitError(t *testing.T) {
-	exitErr := &output.ExitError{
-		Code: output.ExitAPI,
-		Detail: &output.ErrDetail{
-			Type:    "api_error",
-			Message: "permission denied",
-			Hint:    "check app permissions",
-		},
-	}
-	err := wrapWatchSubscribeError(exitErr)
+func TestWrapWatchSubscribeErrorTypedProblem(t *testing.T) {
+	apiErr := errs.NewAPIError(errs.SubtypePermissionDenied, "permission denied").
+		WithHint("check app permissions")
+	err := wrapWatchSubscribeError(apiErr)
 	if err == nil {
 		t.Fatal("expected error")
 	}
-	if !strings.Contains(err.Error(), "subscribe mailbox events failed") {
-		t.Fatalf("unexpected message: %v", err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
 	}
-	if !strings.Contains(err.Error(), "permission denied") {
-		t.Fatalf("original message missing: %v", err)
+	if !strings.Contains(p.Message, "subscribe mailbox events failed") {
+		t.Fatalf("unexpected message: %v", p.Message)
+	}
+	if !strings.Contains(p.Message, "permission denied") {
+		t.Fatalf("original message missing: %v", p.Message)
+	}
+	if !strings.Contains(p.Hint, "check app permissions") {
+		t.Fatalf("original hint missing: %v", p.Hint)
+	}
+}
+
+func TestWrapWatchSubscribeErrorTypedProblemAddsMissingHint(t *testing.T) {
+	apiErr := errs.NewAPIError(errs.SubtypePermissionDenied, "permission denied")
+
+	err := wrapWatchSubscribeError(apiErr)
+
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if !strings.Contains(p.Hint, "mail:event") {
+		t.Fatalf("scope hint missing: %q", p.Hint)
+	}
+}
+
+func TestEnhanceProfileErrorAuthorization(t *testing.T) {
+	original := errs.NewPermissionError(errs.SubtypeMissingScope, "missing scope")
+
+	err := enhanceProfileError(original)
+
+	if err != original {
+		t.Fatalf("authorization error should be updated in place")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if !strings.Contains(p.Message, "unable to resolve mailbox address") {
+		t.Fatalf("message missing mailbox context: %q", p.Message)
+	}
+	if !strings.Contains(p.Hint, "mail:user_mailbox:readonly") {
+		t.Fatalf("profile scope hint missing: %q", p.Hint)
+	}
+}
+
+func TestEnhanceProfileErrorPermissionMessagePromotesToMissingScope(t *testing.T) {
+	original := errs.NewAPIError(errs.SubtypeUnknown, "scope denied").
+		WithCode(99991679).
+		WithLogID("logid-profile")
+
+	err := enhanceProfileError(original)
+
+	var permissionErr *errs.PermissionError
+	if !errors.As(err, &permissionErr) {
+		t.Fatalf("expected permission error, got %T", err)
+	}
+	if !errors.Is(err, original) {
+		t.Fatalf("original error not preserved as cause: %v", err)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Subtype != errs.SubtypeMissingScope {
+		t.Fatalf("subtype = %q, want %q", p.Subtype, errs.SubtypeMissingScope)
+	}
+	if p.Code != 99991679 || p.LogID != "logid-profile" {
+		t.Fatalf("code/logid not preserved: %+v", p)
+	}
+}
+
+func TestEnhanceProfileErrorPreservesNonPermissionError(t *testing.T) {
+	original := errs.NewNetworkError(errs.SubtypeNetworkTransport, "dial timeout")
+
+	if got := enhanceProfileError(original); got != original {
+		t.Fatalf("non-permission errors should pass through, got %T", got)
 	}
 }
 
@@ -687,6 +825,15 @@ type testErr struct{ msg string }
 
 func (e *testErr) Error() string { return e.msg }
 
+type failingMkdirFS struct {
+	vfs.OsFs
+	err error
+}
+
+func (f failingMkdirFS) MkdirAll(string, fs.FileMode) error {
+	return f.err
+}
+
 type watchDryRunPayload struct {
 	API []struct {
 		Method string                 `json:"method"`

shortcuts/mail/signature/provider.go

@@ -5,9 +5,9 @@ package signature
 
 import (
 	"encoding/json"
-	"fmt"
 	"net/url"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -27,19 +27,19 @@ func ListAll(runtime *common.RuntimeContext, mailboxID string) (*GetSignaturesRe
 		return cached, nil
 	}
 
-	data, err := runtime.CallAPI("GET", signaturesPath(mailboxID), nil, nil)
+	data, err := runtime.CallAPITyped("GET", signaturesPath(mailboxID), nil, nil)
 	if err != nil {
-		return nil, fmt.Errorf("get signatures: %w", err)
+		return nil, err
 	}
 
 	raw, err := json.Marshal(data)
 	if err != nil {
-		return nil, fmt.Errorf("get signatures: marshal response: %w", err)
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "get signatures: marshal response: %v", err).WithCause(err)
 	}
 
 	var resp GetSignaturesResponse
 	if err := json.Unmarshal(raw, &resp); err != nil {
-		return nil, fmt.Errorf("get signatures: unmarshal response: %w", err)
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "get signatures: unmarshal response: %v", err).WithCause(err)
 	}
 
 	processCache[mailboxID] = &resp
@@ -66,5 +66,5 @@ func Get(runtime *common.RuntimeContext, mailboxID, signatureID string) (*Signat
 			return &resp.Signatures[i], nil
 		}
 	}
-	return nil, fmt.Errorf("signature not found: %s", signatureID)
+	return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "signature not found: %s", signatureID)
 }

shortcuts/mail/signature_compose.go

@@ -5,7 +5,6 @@ package mail
 
 import (
 	"context"
-	"fmt"
 	"io"
 	"net/http"
 	"net/url"
@@ -13,7 +12,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
 	"github.com/larksuite/cli/shortcuts/mail/emlbuilder"
@@ -33,8 +32,6 @@ type signatureResult struct {
 	Images          []draftpkg.SignatureImage
 }
 
-// resolveSignature fetches, interpolates, and downloads images for a signature.
-// Returns nil if signatureID is empty.
 // resolveSignature fetches, interpolates, and downloads images for a signature.
 // fromEmail is the --from address (may be an alias); used to match the correct
 // sender identity for template interpolation. Pass "" to use the primary address.
@@ -62,7 +59,7 @@ func resolveSignature(ctx context.Context, runtime *common.RuntimeContext, mailb
 		}
 		data, ct, err := downloadSignatureImage(runtime, img.DownloadURL, img.ImageName)
 		if err != nil {
-			return nil, fmt.Errorf("failed to download signature image %s: %w", img.ImageName, err)
+			return nil, mailDecorateProblemMessage(err, "failed to download signature image %s", img.ImageName)
 		}
 		images = append(images, draftpkg.SignatureImage{
 			CID:         img.CID,
@@ -110,13 +107,12 @@ func addSignatureImagesToBuilder(bld emlbuilder.Builder, sig *signatureResult) e
 	return bld
 }
 
-// resolveSenderInfo fetches senderName and senderEmail via the send_as API.
 // resolveSenderInfo fetches send_as addresses and returns the name/email
 // for signature interpolation. If fromEmail is non-empty, it matches
 // that address in the sendable list (for alias/send_as scenarios);
 // otherwise falls back to the first (primary) address.
 func resolveSenderInfo(runtime *common.RuntimeContext, mailboxID, fromEmail string) (name, email string) {
-	data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "settings", "send_as"), nil, nil)
+	data, err := runtime.CallAPITyped("GET", mailboxPath(mailboxID, "settings", "send_as"), nil, nil)
 	if err != nil {
 		return "", ""
 	}
@@ -155,45 +151,54 @@ func resolveSenderInfo(runtime *common.RuntimeContext, mailboxID, fromEmail stri
 func downloadSignatureImage(runtime *common.RuntimeContext, downloadURL, filename string) ([]byte, string, error) {
 	u, err := url.Parse(downloadURL)
 	if err != nil {
-		return nil, "", fmt.Errorf("signature image download: invalid URL: %w", err)
+		return nil, "", mailInvalidResponseError("signature image download: invalid URL: %v", err).WithCause(err)
 	}
 	if u.Scheme != "https" {
-		return nil, "", fmt.Errorf("signature image download: URL must use https (got %q)", u.Scheme)
+		return nil, "", mailInvalidResponseError("signature image download: URL must use https (got %q)", u.Scheme)
 	}
 	if u.Host == "" {
-		return nil, "", fmt.Errorf("signature image download: URL has no host")
+		return nil, "", mailInvalidResponseError("signature image download: URL has no host")
 	}
 
 	httpClient, err := runtime.Factory.HttpClient()
 	if err != nil {
-		return nil, "", fmt.Errorf("signature image download: %w", err)
+		return nil, "", errs.NewInternalError(errs.SubtypeSDKError, "signature image download: %v", err).WithCause(err)
 	}
 	ctx, cancel := context.WithTimeout(runtime.Ctx(), 30*time.Second)
 	defer cancel()
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
 	if err != nil {
-		return nil, "", fmt.Errorf("signature image download: %w", err)
+		return nil, "", errs.NewInternalError(errs.SubtypeSDKError, "signature image download: %v", err).WithCause(err)
 	}
 	// Do NOT send Authorization: the download URL is pre-signed.
 
 	resp, err := httpClient.Do(req)
 	if err != nil {
-		return nil, "", fmt.Errorf("signature image download: %w", err)
+		return nil, "", errs.NewNetworkError(errs.SubtypeNetworkTransport, "signature image download: %v", err).WithCause(err)
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode >= 400 {
 		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
-		return nil, "", fmt.Errorf("signature image download: HTTP %d: %s", resp.StatusCode, string(body))
+		if resp.StatusCode >= 500 {
+			return nil, "", errs.NewNetworkError(errs.SubtypeNetworkServer, "signature image download: HTTP %d: %s", resp.StatusCode, string(body)).
+				WithCode(resp.StatusCode).
+				WithRetryable()
+		}
+		subtype := errs.SubtypeUnknown
+		if resp.StatusCode == http.StatusNotFound {
+			subtype = errs.SubtypeNotFound
+		}
+		return nil, "", errs.NewAPIError(subtype, "signature image download: HTTP %d: %s", resp.StatusCode, string(body)).WithCode(resp.StatusCode)
 	}
 
 	const maxSize = 10 * 1024 * 1024
 	data, err := io.ReadAll(io.LimitReader(resp.Body, maxSize+1))
 	if err != nil {
-		return nil, "", fmt.Errorf("signature image download: read body: %w", err)
+		return nil, "", errs.NewNetworkError(errs.SubtypeNetworkTransport, "signature image download: read body: %v", err).WithCause(err)
 	}
 	if len(data) > maxSize {
-		return nil, "", fmt.Errorf("signature image download: file exceeds 10MB limit")
+		return nil, "", mailFailedPreconditionError("signature image download: file exceeds 10MB limit")
 	}
 
 	ct := resp.Header.Get("Content-Type")
@@ -242,7 +247,11 @@ func signatureCIDs(sig *signatureResult) []string {
 // validateSignatureWithPlainText returns an error if both --plain-text and --signature-id are set.
 func validateSignatureWithPlainText(plainText bool, signatureID string) error {
 	if plainText && signatureID != "" {
-		return output.ErrValidation("--plain-text and --signature-id are mutually exclusive: signatures require HTML mode")
+		return mailValidationError("--plain-text and --signature-id are mutually exclusive: signatures require HTML mode").
+			WithParams(
+				mailInvalidParam("--plain-text", "mutually exclusive with --signature-id"),
+				mailInvalidParam("--signature-id", "requires HTML mode"),
+			)
 	}
 	return nil
 }

shortcuts/mail/signature_compose_test.go

@@ -0,0 +1,207 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+func TestDownloadSignatureImageRejectsInvalidURLs(t *testing.T) {
+	rt := newDownloadRuntime(t, &http.Client{})
+
+	cases := []struct {
+		name string
+		url  string
+	}{
+		{name: "invalid", url: "https://[::1"},
+		{name: "http", url: "http://example.com/sig.png"},
+		{name: "no host", url: "https:///sig.png"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, _, err := downloadSignatureImage(rt, tc.url, "sig.png")
+			var internalErr *errs.InternalError
+			if !errors.As(err, &internalErr) {
+				t.Fatalf("expected internal error, got %T (%v)", err, err)
+			}
+			p, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed problem, got %T", err)
+			}
+			if p.Subtype != errs.SubtypeInvalidResponse {
+				t.Fatalf("subtype = %q, want %q", p.Subtype, errs.SubtypeInvalidResponse)
+			}
+		})
+	}
+}
+
+func TestDownloadSignatureImageHTTPErrorClassification(t *testing.T) {
+	for _, tc := range []struct {
+		name       string
+		statusCode int
+		wantType   any
+		wantSub    errs.Subtype
+		retryable  bool
+	}{
+		{
+			name:       "server",
+			statusCode: http.StatusInternalServerError,
+			wantType:   (*errs.NetworkError)(nil),
+			wantSub:    errs.SubtypeNetworkServer,
+			retryable:  true,
+		},
+		{
+			name:       "not found",
+			statusCode: http.StatusNotFound,
+			wantType:   (*errs.APIError)(nil),
+			wantSub:    errs.SubtypeNotFound,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				http.Error(w, "download failed", tc.statusCode)
+			}))
+			t.Cleanup(srv.Close)
+			rt := newDownloadRuntime(t, srv.Client())
+
+			_, _, err := downloadSignatureImage(rt, srv.URL+"/sig.png", "sig.png")
+			switch tc.wantType.(type) {
+			case *errs.NetworkError:
+				var networkErr *errs.NetworkError
+				if !errors.As(err, &networkErr) {
+					t.Fatalf("expected network error, got %T (%v)", err, err)
+				}
+			case *errs.APIError:
+				var apiErr *errs.APIError
+				if !errors.As(err, &apiErr) {
+					t.Fatalf("expected API error, got %T (%v)", err, err)
+				}
+			}
+			p, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed problem, got %T", err)
+			}
+			if p.Code != tc.statusCode {
+				t.Fatalf("code = %d, want %d", p.Code, tc.statusCode)
+			}
+			if p.Subtype != tc.wantSub {
+				t.Fatalf("subtype = %q, want %q", p.Subtype, tc.wantSub)
+			}
+			if p.Retryable != tc.retryable {
+				t.Fatalf("retryable = %v, want %v", p.Retryable, tc.retryable)
+			}
+		})
+	}
+}
+
+func TestDownloadSignatureImageReadAndSizeErrors(t *testing.T) {
+	readErr := errors.New("socket closed")
+	rt := newDownloadRuntime(t, &http.Client{
+		Transport: signatureRoundTripper(func(req *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     make(http.Header),
+				Body:       signatureErrorBody{err: readErr},
+				Request:    req,
+			}, nil
+		}),
+	})
+
+	_, _, err := downloadSignatureImage(rt, "https://example.com/sig.png", "sig.png")
+	var networkErr *errs.NetworkError
+	if !errors.As(err, &networkErr) {
+		t.Fatalf("expected network error, got %T (%v)", err, err)
+	}
+	if !errors.Is(err, readErr) {
+		t.Fatalf("read cause not preserved: %v", err)
+	}
+
+	rt = newDownloadRuntime(t, &http.Client{
+		Transport: signatureRoundTripper(func(req *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     make(http.Header),
+				Body:       &bodyFileTestFile{remaining: 10*1024*1024 + 1},
+				Request:    req,
+			}, nil
+		}),
+	})
+
+	_, _, err = downloadSignatureImage(rt, "https://example.com/huge.png", "huge.png")
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected validation error, got %T (%v)", err, err)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("subtype = %q, want %q", p.Subtype, errs.SubtypeFailedPrecondition)
+	}
+}
+
+func TestDownloadSignatureImageSuccessUsesFilenameContentType(t *testing.T) {
+	rt := newDownloadRuntime(t, &http.Client{
+		Transport: signatureRoundTripper(func(req *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     make(http.Header),
+				Body:       io.NopCloser(strings.NewReader("gif-data")),
+				Request:    req,
+			}, nil
+		}),
+	})
+
+	data, contentType, err := downloadSignatureImage(rt, "https://example.com/sig.gif", "sig.gif")
+	if err != nil {
+		t.Fatalf("downloadSignatureImage failed: %v", err)
+	}
+	if string(data) != "gif-data" {
+		t.Fatalf("data = %q", string(data))
+	}
+	if contentType != "image/gif" {
+		t.Fatalf("content type = %q, want image/gif", contentType)
+	}
+}
+
+func TestValidateSignatureWithPlainTextTypedError(t *testing.T) {
+	err := validateSignatureWithPlainText(true, "sig_123")
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected validation error, got %T (%v)", err, err)
+	}
+	if len(validationErr.Params) != 2 {
+		t.Fatalf("params = %#v, want two conflicting params", validationErr.Params)
+	}
+	if validationErr.Params[0].Name != "--plain-text" || validationErr.Params[1].Name != "--signature-id" {
+		t.Fatalf("unexpected params: %#v", validationErr.Params)
+	}
+}
+
+type signatureRoundTripper func(*http.Request) (*http.Response, error)
+
+func (rt signatureRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+	return rt(req)
+}
+
+type signatureErrorBody struct {
+	err error
+}
+
+func (b signatureErrorBody) Read([]byte) (int, error) {
+	return 0, b.err
+}
+
+func (b signatureErrorBody) Close() error {
+	return nil
+}

shortcuts/mail/template_compose.go

@@ -16,7 +16,7 @@ import (
 
 	"github.com/google/uuid"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
 	"github.com/larksuite/cli/shortcuts/mail/emlbuilder"
@@ -222,7 +222,7 @@ func validateTemplateID(tid string) error {
 		return nil
 	}
 	if _, err := strconv.ParseInt(tid, 10, 64); err != nil {
-		return output.ErrValidation("--template-id must be a decimal integer string")
+		return mailValidationParamError("--template-id", "--template-id must be a decimal integer string")
 	}
 	return nil
 }
@@ -264,7 +264,7 @@ func joinTemplateAddresses(addrs []templateMailAddr) string {
 func generateTemplateCID() (string, error) {
 	id, err := uuid.NewRandom()
 	if err != nil {
-		return "", fmt.Errorf("failed to generate CID: %w", err)
+		return "", errs.NewInternalError(errs.SubtypeSDKError, "failed to generate CID: %v", err).WithCause(err)
 	}
 	return id.String(), nil
 }
@@ -276,23 +276,23 @@ func generateTemplateCID() (string, error) {
 func uploadToDriveForTemplate(ctx context.Context, runtime *common.RuntimeContext, path string) (fileKey string, size int64, err error) {
 	info, err := runtime.FileIO().Stat(path)
 	if err != nil {
-		return "", 0, fmt.Errorf("failed to stat %s: %w", path, err)
+		return "", 0, mailInputStatError(err)
 	}
 	size = info.Size()
 	if size > MaxLargeAttachmentSize {
-		return "", size, fmt.Errorf("attachment %s (%.1f GB) exceeds the %.0f GB single file limit",
+		return "", size, mailFailedPreconditionError("attachment %s (%.1f GB) exceeds the %.0f GB single file limit",
 			filepath.Base(path), float64(size)/1024/1024/1024, float64(MaxLargeAttachmentSize)/1024/1024/1024)
 	}
 	name := filepath.Base(path)
 	if err := filecheck.CheckBlockedExtension(name); err != nil {
-		return "", size, err
+		return "", size, mailValidationError("%v", err).WithCause(err)
 	}
 	userOpenId := runtime.UserOpenId()
 	if userOpenId == "" {
-		return "", size, fmt.Errorf("template attachment upload requires user identity (--as user)")
+		return "", size, mailFailedPreconditionError("template attachment upload requires user identity (--as user)")
 	}
 	if size <= common.MaxDriveMediaUploadSinglePartSize {
-		fileKey, err = common.UploadDriveMediaAll(runtime, common.DriveMediaUploadAllConfig{
+		fileKey, err = common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
 			FilePath:   path,
 			FileName:   name,
 			FileSize:   size,
@@ -300,7 +300,7 @@ func uploadToDriveForTemplate(ctx context.Context, runtime *common.RuntimeContex
 			ParentNode: &userOpenId,
 		})
 	} else {
-		fileKey, err = common.UploadDriveMediaMultipart(runtime, common.DriveMediaMultipartUploadConfig{
+		fileKey, err = common.UploadDriveMediaMultipartTyped(runtime, common.DriveMediaMultipartUploadConfig{
 			FilePath:   path,
 			FileName:   name,
 			FileSize:   size,
@@ -309,7 +309,7 @@ func uploadToDriveForTemplate(ctx context.Context, runtime *common.RuntimeContex
 		})
 	}
 	if err != nil {
-		return "", size, fmt.Errorf("upload %s to Drive failed: %w", name, err)
+		return "", size, mailDecorateProblemMessage(err, "upload %s to Drive failed", name)
 	}
 	return fileKey, size, nil
 }
@@ -404,7 +404,7 @@ func (b *templateAttachmentBuilder) append(fileKey, filename, cid string, isInli
 // self-healing via the LARGE switch inside append().
 func (b *templateAttachmentBuilder) finalize() error {
 	if b.rawBodyInlineSmall > maxTemplateBodyInlineSmallBytes {
-		return fmt.Errorf("template body + inline images exceed %d MB (got %.1f MB); "+
+		return mailFailedPreconditionError("template body + inline images exceed %d MB (got %.1f MB); "+
 			"reduce inline image size or count — inline images cannot be promoted to LARGE",
 			maxTemplateBodyInlineSmallBytes/(1024*1024),
 			float64(b.rawBodyInlineSmall)/1024/1024)
@@ -511,9 +511,9 @@ func replaceImgSrcOnce(html, rawSrc, newSrc string) string {
 // fetchTemplate GETs a single template (full fields) for --template-id
 // composition and update patch workflows.
 func fetchTemplate(runtime *common.RuntimeContext, mailboxID, templateID string) (*templatePayload, error) {
-	data, err := runtime.CallAPI("GET", templateMailboxPath(mailboxID, templateID), nil, nil)
+	data, err := runtime.CallAPITyped("GET", templateMailboxPath(mailboxID, templateID), nil, nil)
 	if err != nil {
-		return nil, fmt.Errorf("fetch template %s failed: %w", templateID, err)
+		return nil, mailDecorateProblemMessage(err, "fetch template %s failed", templateID)
 	}
 	return extractTemplatePayload(data)
 }
@@ -526,29 +526,29 @@ func extractTemplatePayload(data map[string]interface{}) (*templatePayload, erro
 		raw = t
 	}
 	if raw == nil {
-		return nil, fmt.Errorf("API response missing template body")
+		return nil, mailInvalidResponseError("API response missing template body")
 	}
 	buf, err := json.Marshal(raw)
 	if err != nil {
-		return nil, fmt.Errorf("re-encode template payload failed: %w", err)
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "re-encode template payload failed: %v", err).WithCause(err)
 	}
 	var out templatePayload
 	if err := json.Unmarshal(buf, &out); err != nil {
-		return nil, fmt.Errorf("decode template payload failed: %w", err)
+		return nil, mailInvalidResponseError("decode template payload failed: %v", err).WithCause(err)
 	}
 	return &out, nil
 }
 
 // createTemplate POSTs a new template.
 func createTemplate(runtime *common.RuntimeContext, mailboxID string, tpl *templatePayload) (map[string]interface{}, error) {
-	return runtime.CallAPI("POST", templateMailboxPath(mailboxID), nil, map[string]interface{}{
+	return runtime.CallAPITyped("POST", templateMailboxPath(mailboxID), nil, map[string]interface{}{
 		"template": tpl,
 	})
 }
 
 // updateTemplate PUTs a full-replace update.
 func updateTemplate(runtime *common.RuntimeContext, mailboxID, templateID string, tpl *templatePayload) (map[string]interface{}, error) {
-	return runtime.CallAPI("PUT", templateMailboxPath(mailboxID, templateID), nil, map[string]interface{}{
+	return runtime.CallAPITyped("PUT", templateMailboxPath(mailboxID, templateID), nil, map[string]interface{}{
 		"template": tpl,
 	})
 }
@@ -889,9 +889,9 @@ func fetchTemplateAttachmentURLs(
 		}
 		apiURL := templateMailboxPath(mailboxID, templateID) + "/attachments/download_url?" + strings.Join(parts, "&")
 
-		data, err := runtime.CallAPI("GET", apiURL, nil, nil)
+		data, err := runtime.CallAPITyped("GET", apiURL, nil, nil)
 		if err != nil {
-			return nil, warnings, fmt.Errorf("template attachments/download_url (template_id=%s): %w", templateID, err)
+			return nil, warnings, mailDecorateProblemMessage(err, "template attachments/download_url (template_id=%s)", templateID)
 		}
 		if urls, ok := data["download_urls"].([]interface{}); ok {
 			for _, item := range urls {
@@ -976,11 +976,11 @@ func embedTemplateInlineAttachments(
 	for _, ref := range wanted {
 		dlURL, ok := urlMap[ref.FileKey]
 		if !ok || dlURL == "" {
-			return bld, nil, fmt.Errorf("template inline image %q (cid=%s): download URL not returned by server", ref.Filename, ref.CID)
+			return bld, nil, mailInvalidResponseError("template inline image %q (cid=%s): download URL not returned by server", ref.Filename, ref.CID)
 		}
 		bytes, err := downloadAttachmentContent(runtime, dlURL)
 		if err != nil {
-			return bld, nil, fmt.Errorf("template inline image %q (cid=%s): %w", ref.Filename, ref.CID, err)
+			return bld, nil, mailDecorateProblemMessage(err, "template inline image %q (cid=%s)", ref.Filename, ref.CID)
 		}
 		filename := ref.Filename
 		if filename == "" {
@@ -988,7 +988,7 @@ func embedTemplateInlineAttachments(
 		}
 		contentType, err := filecheck.CheckInlineImageFormat(filename, bytes)
 		if err != nil {
-			return bld, nil, fmt.Errorf("template inline image %q (cid=%s): %w", filename, ref.CID, err)
+			return bld, nil, mailValidationError("template inline image %q (cid=%s): %v", filename, ref.CID, err).WithCause(err)
 		}
 		bld = bld.AddInline(bytes, contentType, filename, ref.CID)
 		registered = append(registered, ref.CID)
@@ -1037,11 +1037,11 @@ func embedTemplateSmallAttachments(
 		}
 		dlURL, ok := urlMap[ref.FileKey]
 		if !ok || dlURL == "" {
-			return bld, 0, fmt.Errorf("template attachment %q: download URL not returned by server", ref.Filename)
+			return bld, 0, mailInvalidResponseError("template attachment %q: download URL not returned by server", ref.Filename)
 		}
 		buf, err := downloadAttachmentContent(runtime, dlURL)
 		if err != nil {
-			return bld, 0, fmt.Errorf("template attachment %q: %w", ref.Filename, err)
+			return bld, 0, mailDecorateProblemMessage(err, "template attachment %q", ref.Filename)
 		}
 		filename := ref.Filename
 		if filename == "" {

shortcuts/register_test.go

@@ -14,6 +14,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -400,17 +401,21 @@ func TestRegisterShortcutsInstallsMailFlagSuggestHook(t *testing.T) {
 
 	// The FlagErrorFunc lookup walks up to the nearest non-nil hook, so
 	// invoking it on the mail parent (or any of its children) must yield
-	// a structured *output.ExitError with type "unknown_flag".
+	// a typed validation problem for the unknown flag.
 	got := mailCmd.FlagErrorFunc()(mailCmd, errors.New("unknown flag: --bogus"))
-	var exitErr *output.ExitError
-	if !errors.As(got, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T (%v)", got, got)
+	var validationErr *errs.ValidationError
+	if !errors.As(got, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T (%v)", got, got)
 	}
-	if exitErr.Detail == nil || exitErr.Detail.Type != "unknown_flag" {
-		t.Fatalf("expected Detail.Type=unknown_flag, got %#v", exitErr.Detail)
+	if validationErr.Param != "--bogus" {
+		t.Fatalf("expected Param=--bogus, got %q", validationErr.Param)
 	}
-	if exitErr.Code != output.ExitAPI {
-		t.Fatalf("expected Code=ExitAPI(%d), got %d", output.ExitAPI, exitErr.Code)
+	problem, ok := errs.ProblemOf(got)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T (%v)", got, got)
+	}
+	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected validation/invalid_argument, got %s/%s", problem.Category, problem.Subtype)
 	}
 }
 

skills/lark-drive/SKILL.md

@@ -28,6 +28,8 @@ metadata:
 - 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
 - 用户要在云空间（云盘/云存储）里新建文件夹，优先使用 `lark-cli drive +create-folder`。
+- 用户要查看某个文件有哪些可下载预览格式，或想下载 PDF / HTML / 文本 / 图片等预览产物，使用 `lark-cli drive +preview`。
+- 用户要获取某个文件的封面图，优先使用 `lark-cli drive +cover`；先 `--list-only` 看规格，再选 `--spec` 下载。
 - 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 
@@ -266,6 +268,8 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+upload`](references/lark-drive-upload.md) | Upload a local file to a Drive folder or wiki node                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | [`+create-folder`](references/lark-drive-create-folder.md) | Create a Drive folder, optionally under a parent folder, with bot auto-grant support                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | [`+download`](references/lark-drive-download.md) | Download a file from Drive to local                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`+preview`](references/lark-drive-preview.md) | List or download available preview artifacts for a Drive file; explicit `--type` required for downloads |
+| [`+cover`](references/lark-drive-cover.md) | List or download stable built-in cover presets for a Drive file; download-time HTTP 404 means the file has no artifact for that cover spec |
 | [`+status`](references/lark-drive-status.md) | Compare a local directory with a Drive folder by exact SHA-256 hash by default, or use `--quick` for a best-effort modified-time diff that skips remote downloads; reports `new_local` / `new_remote` / `modified` / `unchanged` plus `detection=exact` or `detection=quick`. Duplicate remote `rel_path` conflicts fail fast with `error.type=duplicate_remote_path` and list every conflicting entry; do not proceed as if one was chosen. `--local-dir` 必须是 cwd 内的相对路径，越界路径 CLI 会直接拒绝；目标在 cwd 外时引导用户切换 agent 工作目录，不要私自 `cd` 绕过。 |
 | [`+pull`](references/lark-drive-pull.md) | File-level Drive → local mirror. Duplicate remote `rel_path` conflicts fail by default; for duplicate files, `rename` downloads all copies with stable hashed suffixes, while `newest` / `oldest` pick one. `--if-exists` supports `overwrite` / `smart` / `skip` (`smart` is a best-effort modified-time incremental mode for repeat syncs). `--delete-local` requires `--yes`, only removes regular files, and is skipped after item failures. `--local-dir` must stay inside cwd.                                               |
 | `+sync` | Two-way local ↔ Drive sync. Reuses `+status` diff buckets, pulls `new_remote`, pushes `new_local`, and resolves `modified` via `--on-conflict=remote-wins|local-wins|keep-both|ask`. `--quick` enables best-effort modified-time diffing (timestamp mismatches can still trigger real pull/push actions), `--on-duplicate-remote` supports `fail|newest|oldest`, and the command is intentionally non-destructive (no delete on either side). |
@@ -347,31 +351,40 @@ lark-cli drive <resource> <method> [flags] # 调用 API
 
   - `update_reaction` — 添加/删除 reaction
 
+### quota_details
+
+  - `get` — 获取当前用户的容量信息，包含各业务使用量、租户配额是否超限、用户配额、所在部门配额
+    - 仅支持 `--as user`，不要使用默认的 bot 身份
+    - `quota_detail_id` 传当前用户的 `user_id`
+
 ## 权限表
 
-| 方法                                             | 所需 scope                          |
-|------------------------------------------------|-----------------------------------|
-| `files.copy`                                   | `docs:document:copy`              |
-| `files.create_folder`                          | `space:folder:create`             |
-| `files.list`                                   | `space:document:retrieve`         |
-| `files.patch`                                  | `docx:document:write_only`        |
-| `file.comments.batch_query`                    | `docs:document.comment:read`      |
-| `file.comments.create_v2`                      | `docs:document.comment:create`    |
-| `file.comments.list`                           | `docs:document.comment:read`      |
-| `file.comments.patch`                          | `docs:document.comment:update`    |
-| `file.comment.replys.create`                   | `docs:document.comment:create`    |
-| `file.comment.replys.delete`                   | `docs:document.comment:delete`    |
-| `file.comment.replys.list`                     | `docs:document.comment:read`      |
-| `file.comment.replys.update`                   | `docs:document.comment:update`    |
-| `permission.members.auth`                      | `docs:permission.member:auth`     |
-| `permission.members.create`                    | `docs:permission.member:create`   |
-| `permission.members.transfer_owner`            | `docs:permission.member:transfer` |
-| `permission.public.get`                        | `docs:permission.setting:read`    |
+| 方法                                             | 所需 scope                             |
+|------------------------------------------------|--------------------------------------|
+| `files.copy`                                   | `docs:document:copy`                 |
+| `files.create_folder`                          | `space:folder:create`                |
+| `files.list`                                   | `space:document:retrieve`            |
+| `files.patch`                                  | `docx:document:write_only`           |
+| `file.comments.batch_query`                    | `docs:document.comment:read`         |
+| `file.comments.create_v2`                      | `docs:document.comment:create`       |
+| `file.comments.list`                           | `docs:document.comment:read`         |
+| `file.comments.patch`                          | `docs:document.comment:update`       |
+| `file.comment.replys.create`                   | `docs:document.comment:create`       |
+| `file.comment.replys.delete`                   | `docs:document.comment:delete`       |
+| `file.comment.replys.list`                     | `docs:document.comment:read`         |
+| `file.comment.replys.update`                   | `docs:document.comment:update`       |
+| `permission.members.auth`                      | `docs:permission.member:auth`        |
+| `permission.members.create`                    | `docs:permission.member:create`      |
+| `permission.members.transfer_owner`            | `docs:permission.member:transfer`    |
+| `permission.public.get`                        | `docs:permission.setting:read`       |
 | `permission.public.patch`                      | `docs:permission.setting:write_only` |
-| `metas.batch_query`                            | `drive:drive.metadata:readonly`   |
-| `user.remove_subscription`                     | `docs:event:subscribe`            |
-| `user.subscription`                            | `docs:event:subscribe`            |
-| `user.subscription_status`                     | `docs:event:subscribe`            |
-| `file.statistics.get`                          | `drive:drive.metadata:readonly`   |
-| `file.view_records.list`                       | `drive:file:view_record:readonly` |
-| `file.comment.reply.reactions.update_reaction` | `docs:document.comment:create`    |
+| `metas.batch_query`                            | `drive:drive.metadata:readonly`      |
+| `user.remove_subscription`                     | `docs:event:subscribe`               |
+| `user.subscription`                            | `docs:event:subscribe`               |
+| `user.subscription_status`                     | `docs:event:subscribe`               |
+| `file.statistics.get`                          | `drive:drive.metadata:readonly`      |
+| `file.view_records.list`                       | `drive:file:view_record:readonly`    |
+| `file.comment.reply.reactions.update_reaction` | `docs:document.comment:create`       |
+| `quota_details.get`                            | `drive:quota_detail:read_one`        |
+
+> `quota_details.get` 是 user-only OpenAPI：调用时必须显式传 `--as user`，且 `quota_detail_id` 应填写当前用户的 `user_id`。

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

@@ -0,0 +1,79 @@
+## `drive +cover`
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
+
+列出或下载 Drive 文件的稳定封面预设。这个 shortcut 只暴露 `spec`，不暴露底层 `cover_option` 细节。
+
+### 命令
+
+```bash
+# 列出内置封面规格
+lark-cli drive +cover \
+  --file-token "<FILE_TOKEN>" \
+  --list-only
+
+# 下载 square 规格封面
+lark-cli drive +cover \
+  --file-token "<FILE_TOKEN>" \
+  --spec square \
+  --output ./artifacts/report-cover
+
+# 下载默认大图封面，并在文件冲突时覆盖
+lark-cli drive +cover \
+  --file-token "<FILE_TOKEN>" \
+  --spec default \
+  --output ./artifacts/report-cover.png \
+  --if-exists overwrite
+```
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | Drive 文件 token |
+| `--spec` | 条件必填 | 封面预设：`default` / `icon` / `grid` / `small` / `middle` / `big` / `square` |
+| `--version` | 否 | 文件版本号 |
+| `--list-only` | 否 | 仅返回可选规格，不下载 |
+| `--output` | 条件必填 | 下载到本地的输出路径 |
+| `--if-exists` | 否 | 输出冲突策略：`error`（默认）/ `overwrite` / `rename` |
+
+### 输出约定
+
+- 查询态返回：
+  - `mode=list`
+  - `file_token`
+  - `candidates[]`
+  - `next_action`
+- 下载态返回：
+  - `mode=download`
+  - `file_token`
+  - `selected_spec`
+  - `output_path`
+  - `status`
+
+### 内置规格
+
+- `default` -- 标准大图封面
+- `icon` -- 列表小图标
+- `grid` -- 网格/卡片流小封面
+- `small` -- PC 小图
+- `middle` -- 中等尺寸封面
+- `big` -- 偏移动端的大图封面
+- `square` -- 正方形裁剪封面
+
+### 关键约束
+
+- 不传 `--list-only` 时，必须显式传 `--spec` 和 `--output`
+- `drive +cover` 只返回静态预设规格，不伪造后端“可下载状态”
+- 不返回底层 `bus_type` / `platform` / `width` / `height` / `policy` 等实现细节
+- 下载时直接调用 `preview_download`
+- 未显式带扩展名时，会优先根据响应头补扩展名，缺失时回退到 `.png`
+
+### 错误提示
+
+- 下载某个 `--spec` 时如果返回 **HTTP 404**，表示这个文件**没有该规格对应的封面产物**，应视为“该规格不可用”，而不是默认按网络抖动或临时失败处理
+
+### 参考
+
+- [lark-drive](../SKILL.md) -- Drive 总入口
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,87 @@
+## `drive +preview`
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
+
+列出或下载 Drive 文件可用的预览产物。这个 shortcut 不猜测默认类型：
+
+- 只想看候选项时，用 `--list-only`
+- 想下载时，必须显式传 `--type` 和 `--output`
+- 如果某个候选项还在生成中，会返回结构化错误并提示先重新 `--list-only`
+
+### 命令
+
+```bash
+# 列出可用预览候选项
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --list-only
+
+# 下载 PDF 预览
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --type pdf \
+  --output ./artifacts/report
+
+# 下载文本预览，并在目标已存在时自动改名
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --type text \
+  --output ./artifacts/report \
+  --if-exists rename
+
+# 指定版本号查询/下载
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --version "12" \
+  --type html \
+  --output ./artifacts/report.html
+```
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | Drive 文件 token |
+| `--type` | 条件必填 | 预览类型；优先使用 `--list-only` 返回的 `type`，如 `pdf` / `html` / `text` / `png` / `jpg` / `source_file` |
+| `--version` | 否 | 文件版本号 |
+| `--list-only` | 否 | 仅返回候选项，不下载 |
+| `--output` | 条件必填 | 下载到本地的输出路径 |
+| `--if-exists` | 否 | 输出冲突策略：`error`（默认）/ `overwrite` / `rename` |
+
+### 输出约定
+
+- 查询态返回：
+  - `mode=list`
+  - `file_token`
+  - `candidates[]`
+  - `next_action`
+- 下载态返回：
+  - `mode=download`
+  - `file_token`
+  - `selected_type`
+  - `output_path`
+  - `status`
+
+### 候选项字段
+
+`candidates[]` 中每个对象包含：
+
+- `type`
+- `type_code`
+- `label`
+- `status`
+- `status_code`
+- `downloadable`
+- `reason`（可选）
+
+### 关键约束
+
+- 不传 `--list-only` 时，必须显式传 `--type` 和 `--output`
+- 不会隐式选择“第一个候选项”作为默认下载目标
+- 候选项状态来自后端 `preview_status` 枚举，例如 `READY` / `PROCESSING` / `FAILED` / `NO_SUPPORT`
+- 本地文件名在未显式带扩展名时，会结合响应头自动补扩展名
+
+### 参考
+
+- [lark-drive](../SKILL.md) -- Drive 总入口
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-mail/references/lark-mail-triage.md

@@ -87,31 +87,40 @@ lark-cli mail +triage --page-size 10
   "messages": [
     {
       "message_id": "SEU2...",
+      "mailbox_id": "me",
       "date": "Fri, 21 Mar 2026 11:40:00 +0800",
       "from": "Alice <alice@example.com>",
       "subject": "Weekly update",
       "labels": "INBOX,UNREAD"
     }
   ],
+  "mailbox_id": "me",
   "count": 20,
   "has_more": true,
   "page_token": "list:FfccvoqPd_loLhtcRx8cx..."
 }
 ```
 
+- `mailbox_id`：当前邮箱标识，用于传递给 `mail +message --mailbox` 以保持公共邮箱上下文
 - `has_more`：是否还有下一页
 - `page_token`：传入 `--page-token` 可获取下一页；为空字符串表示已到末尾
 - token 前缀 `search:` / `list:` 标识来源 API 路径，不可混用
 
 ### `table` 格式
 
-`page_token` 信息输出在 stderr，自动携带 `--query`/`--filter` 参数方便续页：
+`page_token` 信息输出在 stderr，自动携带 `--query`/`--filter`/`--mailbox` 参数方便续页：
 ```text
 15 message(s)
 next page: mail +triage --query '合同审批' --page-token 'search:abc123...'
 tip: use mail +message --message-id <id> to read full content
 ```
 
+公共邮箱场景下，`--mailbox` 会自动出现在续页和 tip 中：
+```text
+next page: mail +triage --mailbox 'shared@example.com' --query '合同审批' --page-token 'search:abc123...'
+tip: use mail +message --mailbox 'shared@example.com' --message-id <id> to read full content
+```
+
 ### 搜索分页注意事项
 
 搜索路径（使用 `--query` 或 `from`/`to`/`subject` 等 filter）的分页结果在**同一翻页链内**保持一致（无重复、无丢失）。但不同 `--max` 值发起的独立搜索可能返回不同排序，这是搜索 API 的固有行为。列表路径（仅 `folder`/`label` 筛选）无此限制。

skills/lark-sheets/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-sheets
 version: 2.0.0
-description: "飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作原子批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。仅针对飞书在线电子表格，不适用于本地 Excel 文件。"
+description: "飞书电子表格：创建和操作电子表格。支持管理工作表结构、读写单元格数据与样式，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）等任务时使用。若用户是想按名称或关键词搜索表格文件，请改用 lark-drive 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。仅针对飞书在线电子表格，不适用于本地 Excel 文件。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -13,6 +13,8 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理。**
 
+**身份：电子表格通常属于用户云空间资源，优先使用 `--as user`。首次使用前执行 `lark-cli auth login`。**
+
 ## 术语约定
 
 下列词在本 skill 各文档中可能交替出现，但**指同一对象**；解析用户口语时按此映射，不要当成不同概念：
@@ -34,7 +36,7 @@ metadata:
 
 ## 场景 → 命令速查（拿不准命令名先查这里，别按直觉拼）
 
-把高频意图映射到**真实存在**的 shortcut / flag。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。
+把高频意图映射到**真实存在**的 shortcut / flag。先对照本表，避免按直觉拼不存在的命令名或 flag。
 
 | 你要做的事 | ✅ 正确写法 | ❌ 不存在（会被 cobra 拒） |
 | --- | --- | --- |
@@ -57,7 +59,7 @@ metadata:
 
 ## References
 
-本 skill 的 reference 分两组：先读**通用方法与规范**（横切所有任务的工作流、铁律、样式、公式规则，不含具体 shortcut），它们规定了"怎么做对"；再按操作对象进入**工具参考**查具体 shortcut 与调用细节。编辑类任务务必先过一遍通用方法与规范，其中的铁律对所有工具参考一律生效。
+本 skill 的 reference 分两组：先读**通用方法与规范**，再按操作对象进入**工具参考**查具体 shortcut 与调用细节。
 
 ### 通用方法与规范（先读，横切所有任务，不含具体 shortcut）
 
@@ -101,7 +103,7 @@ metadata:
 
 1. **spreadsheet 定位（必填）**：`--url` 与 `--spreadsheet-token` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --url or --spreadsheet-token`；两个都给 → 互斥冲突。
    - **`--url` 只解析 `/sheets/` 与 `/spreadsheets/` 两种链接**（从路径里抽出 token；也可以直接把裸 token 传给 `--spreadsheet-token`）。其它形态的链接不会被解析成表格 token。
-   - ⚠️ **`/wiki/` 知识库链接不能直接当表格定位用**：wiki 链接背后可能是电子表格，也可能是文档 / 多维表格等其它类型，`--url` **不会**自动把 wiki token 解析成 spreadsheet token，直接传会失败。必须先把它解析成真实文档 token —— `lark-cli wiki +node-get --node-token "<wiki 链接或 token>"`，确认返回的 `obj_type` 为 `sheet` 后，取其 `obj_token` 作为 `--spreadsheet-token` 传入（解析细节见 [`../lark-wiki/SKILL.md`](../lark-wiki/SKILL.md)）。
+   - ⚠️ **`/wiki/` 知识库链接不能直接当表格定位用**：先用 `lark-cli drive +inspect --url "<wiki_url>"` 自动解包；当返回 `type=sheet` 时，用 `token` 作为 `--spreadsheet-token`。手动方式见 [`../lark-wiki/SKILL.md`](../lark-wiki/SKILL.md)。
    - **例外**：`+workbook-create` 是新建一个还不存在的表格，**不接受任何 spreadsheet / sheet 定位 flag**（只有 `--title` / `--folder-token` / `--headers` / `--values`）。
 2. **sheet 定位（公共四件套 shortcut 必填）**：`--sheet-id` 与 `--sheet-name` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --sheet-id or --sheet-name`。
    - ⚠️ **不确定 sheet 名时禁止直接猜 `Sheet1`**：除非用户对话明确说出 sheet 名 / id，或上下文（之前的工具调用 / URL 锚点 `?sheet=xxx`）已经出现过具体值，否则**第一步先调 `+workbook-info --url "..."`**（或 `--spreadsheet-token`）拿 `sheets[].sheet_id` / `sheets[].title` 列表再选。中文环境下子表常叫"数据" / "Sheet"（无数字）/ "工作表 1" / 业务名，猜 `Sheet1` 大概率撞 `sheet not found`，比先查多耗一次失败调用 + 重试。
@@ -135,13 +137,6 @@ lark-cli sheets <shortcut> <workbook 定位> <sheet 定位> <其它 flag>
 | `--print-schema` | bool | 否 | 本地打印复合 JSON flag 的 JSON Schema 并退出，不发起任何调用、不需要其它 required flag。与 `--flag-name <name>` 搭配指定要查哪个 flag；省略 `--flag-name` 时列出该 shortcut 所有可查询的 flag。**仅在 shortcut 含复合 JSON flag 时有效**——判断方法：该 shortcut 的 Flags 表里出现类型标注为「复合 JSON」的 flag（如 `--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` / `--options`）即支持；纯标量 flag 的 shortcut 不支持。 |
 | `--flag-name` | string | 否 | 配合 `--print-schema` 使用，指定要打印 JSON Schema 的 flag 名（不带 `--` 前缀，如 `cells` / `properties` / `operations`）。 |
 
-**Agent 使用提示**：写复合 JSON flag（`--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` / `--options` 等）时，如果对结构不确定，先跑 `lark-cli sheets <shortcut> --print-schema --flag-name <name>` 把完整 JSON Schema 读出来再构造 payload，比靠 reference 的速查表更精确，也避免因为字段拼写或缺失被服务端拒绝。reference 的 `## Schemas` 段只给一层结构，深层只能靠 `--print-schema` 或 `## Examples` 的真实示例。
-
-### flag 内容类型与输出约定（术语速记）
-
-- flag 表里 JSON 类入参标三类：**复合 JSON** = 深层嵌套对象（用 `--print-schema` 取完整结构）；**简单 JSON** = 一维 / 二维标量数组（如 `["sheet1!A1:B2",...]` / `[["alice",95]]`，结构简单无需 print-schema）；**非 JSON 文本** = 原样文本（如 CSV）。`--print-schema` 只对**复合 JSON** flag 有效（同一 shortcut 的简单 JSON flag 如 `--colors` 不在此列）。
-- **envelope**：所有 shortcut 返回统一外层结构 `{ok, identity, data, ...}`。正文里 `envelope.data` 指业务数据层（如 `+csv-get` 的 `annotated_csv`）；写操作不会自动回读，如需校验请自行调用对应的 `+*-list` / `+*-get` / `+cells-get`。
-
 ## 复合 JSON / 大入参：优先 stdin
 
 flag 帮助里标注支持 **Stdin** 的入参，当 payload 较大、含换行 / 引号等特殊字符，或已经落在某个文件里时，优先用 stdin（`-`）传入，避免命令行超长与 shell 转义问题。
@@ -154,3 +149,9 @@ lark-cli sheets +cells-set --url "..." --sheet-name "Sheet1" --range "A1:B2" --c
 ```
 
 **`@file` 接绝对路径会被拒，且被拒后不要照报错提示做。** `@file` 出于安全只接受 cwd 下的相对路径，传 cwd 之外的绝对路径会被拒。此时报错会建议"先 cd 到目标目录，或改用相对路径"——**两条都不要照做**：cd 过去、或把临时文件写进用户项目目录，都会污染工作目录。正解是改用 stdin（`--<flag> - < 文件`）。
+
+## 不在本 skill 范围
+
+- 搜索云空间里的表格文件：切到 [`lark-drive`](../lark-drive/SKILL.md)
+- 评论、权限和通用 Drive 操作：切到 [`lark-drive`](../lark-drive/SKILL.md)
+- 多维表格 / Base 操作：切到 [`lark-base`](../lark-base/SKILL.md)

tests/cli_e2e/drive/drive_preview_dryrun_test.go

@@ -0,0 +1,146 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+// TestDrivePreviewDryRun_ListOnly verifies preview dry-run request structure
+// for list mode.
+func TestDrivePreviewDryRun_ListOnly(t *testing.T) {
+	setDriveDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+preview",
+			"--file-token", "fileDryRunPreview",
+			"--list-only",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	if got := gjson.Get(out, "api.0.method").String(); got != "POST" {
+		t.Fatalf("method=%q, want POST\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.url").String(); got != "/open-apis/drive/v1/medias/fileDryRunPreview/preview_result" {
+		t.Fatalf("url=%q, want preview_result endpoint\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "mode").String(); got != "list" {
+		t.Fatalf("mode=%q, want list\nstdout:\n%s", got, out)
+	}
+}
+
+// TestDrivePreviewDryRun_Download verifies preview dry-run request structure
+// for download mode.
+func TestDrivePreviewDryRun_Download(t *testing.T) {
+	setDriveDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+preview",
+			"--file-token", "fileDryRunPreview",
+			"--type", "pdf",
+			"--version", "12",
+			"--output", "./artifacts/report",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	if got := gjson.Get(out, "api.#").Int(); got != 2 {
+		t.Fatalf("api count=%d, want 2\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.body.version").String(); got != "12" {
+		t.Fatalf("version=%q, want 12\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.method").String(); got != "GET" {
+		t.Fatalf("download method=%q, want GET\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.url").String(); got != "/open-apis/drive/v1/medias/fileDryRunPreview/preview_download" {
+		t.Fatalf("download url=%q, want preview_download endpoint\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.params.preview_type").String(); got != "<selected type_code from preview_result>" {
+		t.Fatalf("preview_type=%q, want placeholder\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.1.params.version").String(); got != "12" {
+		t.Fatalf("download version=%q, want 12\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "requested_type").String(); got != "pdf" {
+		t.Fatalf("requested_type=%q, want pdf\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "output").String(); got != "./artifacts/report" {
+		t.Fatalf("output=%q, want ./artifacts/report\nstdout:\n%s", got, out)
+	}
+}
+
+// TestDriveCoverDryRun_Download verifies cover dry-run request structure for
+// download mode.
+func TestDriveCoverDryRun_Download(t *testing.T) {
+	setDriveDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+cover",
+			"--file-token", "fileDryRunCover",
+			"--spec", "square",
+			"--output", "./artifacts/cover",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	if got := gjson.Get(out, "api.0.method").String(); got != "GET" {
+		t.Fatalf("method=%q, want GET\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.url").String(); got != "/open-apis/drive/v1/medias/fileDryRunCover/preview_download" {
+		t.Fatalf("url=%q, want preview_download endpoint\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.params.preview_type").String(); got != "1" {
+		t.Fatalf("preview_type=%q, want 1\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.params.bus_type").Exists(); got {
+		t.Fatalf("bus_type should be omitted for square crop flow\nstdout:\n%s", out)
+	}
+	if got := gjson.Get(out, "api.0.params.platform").Exists(); got {
+		t.Fatalf("platform should be omitted when using default platform\nstdout:\n%s", out)
+	}
+	if got := gjson.Get(out, "api.0.params.width").String(); got != "360" {
+		t.Fatalf("width=%q, want 360\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.params.height").String(); got != "360" {
+		t.Fatalf("height=%q, want 360\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.params.policy").String(); got != "near" {
+		t.Fatalf("policy=%q, want near\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "selected_spec").String(); got != "square" {
+		t.Fatalf("selected_spec=%q, want square\nstdout:\n%s", got, out)
+	}
+}

tests/cli_e2e/drive/drive_preview_workflow_test.go

@@ -0,0 +1,258 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+// TestDrive_PreviewAndCoverWorkflow verifies preview and cover shortcuts against
+// a live Drive workflow, skipping when required bot scopes are unavailable.
+func TestDrive_PreviewAndCoverWorkflow(t *testing.T) {
+	parentT := t
+	ctx, cancel := context.WithTimeout(context.Background(), 4*time.Minute)
+	t.Cleanup(cancel)
+
+	suffix := clie2e.GenerateSuffix()
+	folderName := "lark-cli-e2e-drive-preview-" + suffix
+	folderToken := createDriveFolderOrSkipPermission(t, parentT, ctx, folderName)
+
+	workDir := t.TempDir()
+	sourceRelPath := "fixture/report.txt"
+	sourceContent := "drive preview and cover workflow\n"
+	writePreviewFixture(t, workDir, sourceRelPath, sourceContent)
+
+	fileToken := uploadPreviewFixture(t, parentT, ctx, workDir, folderToken, sourceRelPath, "report.txt")
+
+	t.Run("preview list and download", func(t *testing.T) {
+		listResult, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+			Args: []string{
+				"drive", "+preview",
+				"--file-token", fileToken,
+				"--list-only",
+			},
+			DefaultAs: "bot",
+		}, clie2e.RetryOptions{
+			Attempts:        8,
+			InitialDelay:    2 * time.Second,
+			MaxDelay:        8 * time.Second,
+			BackoffMultiple: 2,
+			ShouldRetry: func(result *clie2e.Result) bool {
+				if result == nil || result.ExitCode != 0 {
+					return true
+				}
+				return !previewListContainsReadyType(result.Stdout, "text")
+			},
+		})
+		require.NoError(t, err)
+		listResult.AssertExitCode(t, 0)
+		listResult.AssertStdoutStatus(t, true)
+
+		if !previewListContainsReadyType(listResult.Stdout, "text") {
+			t.Fatalf("preview list did not expose downloadable text preview\nstdout:\n%s", listResult.Stdout)
+		}
+
+		downloadDir := t.TempDir()
+		downloadResult, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"drive", "+preview",
+				"--file-token", fileToken,
+				"--type", "text",
+				"--output", "./artifacts/report-preview",
+			},
+			WorkDir:   downloadDir,
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		downloadResult.AssertExitCode(t, 0)
+		downloadResult.AssertStdoutStatus(t, true)
+
+		stdout := downloadResult.Stdout
+		if got := gjson.Get(stdout, "data.selected_type").String(); got != "text" {
+			t.Fatalf("selected_type=%q, want text\nstdout:\n%s", got, stdout)
+		}
+		outputPath := gjson.Get(stdout, "data.output_path").String()
+		require.NotEmpty(t, outputPath, "preview download should return output_path")
+		if ext := filepath.Ext(outputPath); ext != ".txt" {
+			t.Fatalf("preview output extension=%q, want .txt\nstdout:\n%s", ext, stdout)
+		}
+		data, readErr := os.ReadFile(outputPath)
+		require.NoError(t, readErr)
+		if !strings.Contains(string(data), "drive preview and cover workflow") {
+			t.Fatalf("preview artifact content mismatch: %q", string(data))
+		}
+	})
+
+	t.Run("cover list and download", func(t *testing.T) {
+		listResult, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"drive", "+cover",
+				"--file-token", fileToken,
+				"--list-only",
+			},
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		listResult.AssertExitCode(t, 0)
+		listResult.AssertStdoutStatus(t, true)
+
+		if !gjson.Get(listResult.Stdout, `data.candidates.#(spec=="default")`).Exists() {
+			t.Fatalf("cover list missing default spec\nstdout:\n%s", listResult.Stdout)
+		}
+
+		downloadDir := t.TempDir()
+		coverResult, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+			Args: []string{
+				"drive", "+cover",
+				"--file-token", fileToken,
+				"--spec", "default",
+				"--output", "./artifacts/report-cover",
+			},
+			WorkDir:   downloadDir,
+			DefaultAs: "bot",
+		}, clie2e.RetryOptions{
+			Attempts:        8,
+			InitialDelay:    2 * time.Second,
+			MaxDelay:        8 * time.Second,
+			BackoffMultiple: 2,
+			ShouldRetry: func(result *clie2e.Result) bool {
+				if result == nil {
+					return true
+				}
+				if result.ExitCode == 0 {
+					return false
+				}
+				return false
+			},
+		})
+		require.NoError(t, err)
+		coverResult.AssertExitCode(t, 0)
+		coverResult.AssertStdoutStatus(t, true)
+
+		stdout := coverResult.Stdout
+		if got := gjson.Get(stdout, "data.selected_spec").String(); got != "default" {
+			t.Fatalf("selected_spec=%q, want default\nstdout:\n%s", got, stdout)
+		}
+		outputPath := gjson.Get(stdout, "data.output_path").String()
+		require.NotEmpty(t, outputPath, "cover download should return output_path")
+		if ext := filepath.Ext(outputPath); ext != ".png" && ext != ".jpg" && ext != ".jpeg" && ext != ".webp" {
+			t.Fatalf("cover output extension=%q, want image extension\nstdout:\n%s", ext, stdout)
+		}
+		info, statErr := os.Stat(outputPath)
+		require.NoError(t, statErr)
+		if info.Size() <= 0 {
+			t.Fatalf("cover artifact should not be empty: %s", outputPath)
+		}
+	})
+}
+
+// writePreviewFixture writes a local fixture file used by the live workflow.
+func writePreviewFixture(t *testing.T, workDir, relPath, content string) {
+	t.Helper()
+
+	fullPath := filepath.Join(workDir, relPath)
+	if err := os.MkdirAll(filepath.Dir(fullPath), 0o755); err != nil {
+		t.Fatalf("mkdir fixture parent: %v", err)
+	}
+	if err := os.WriteFile(fullPath, []byte(content), 0o644); err != nil {
+		t.Fatalf("write fixture: %v", err)
+	}
+}
+
+// uploadPreviewFixture uploads a fixture into Drive and registers cleanup for
+// the created file token.
+func uploadPreviewFixture(t *testing.T, parentT *testing.T, ctx context.Context, workDir, folderToken, relPath, uploadName string) string {
+	t.Helper()
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+upload",
+			"--file", relPath,
+			"--folder-token", folderToken,
+			"--name", uploadName,
+		},
+		WorkDir:   workDir,
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+	result.AssertStdoutStatus(t, true)
+
+	fileToken := gjson.Get(result.Stdout, "data.file_token").String()
+	require.NotEmpty(t, fileToken, "uploaded file should have a token")
+
+	parentT.Cleanup(func() {
+		cleanupCtx, cleanupCancel := clie2e.CleanupContext()
+		defer cleanupCancel()
+
+		deleteResult, deleteErr := clie2e.RunCmdWithRetry(cleanupCtx, clie2e.Request{
+			Args:      []string{"drive", "+delete", "--file-token", fileToken, "--type", "file", "--yes"},
+			DefaultAs: "bot",
+		}, clie2e.RetryOptions{})
+		clie2e.ReportCleanupFailure(parentT, "delete drive file "+fileToken, deleteResult, deleteErr)
+	})
+
+	return fileToken
+}
+
+// previewListContainsReadyType reports whether a preview list response contains
+// a downloadable candidate for the requested type.
+func previewListContainsReadyType(stdout, wantType string) bool {
+	for _, candidate := range gjson.Get(stdout, "data.candidates").Array() {
+		if candidate.Get("type").String() != wantType {
+			continue
+		}
+		if candidate.Get("downloadable").Bool() {
+			return true
+		}
+	}
+	return false
+}
+
+// createDriveFolderOrSkipPermission creates a Drive folder for the live
+// workflow and skips when the bot lacks required folder scopes.
+func createDriveFolderOrSkipPermission(t *testing.T, parentT *testing.T, ctx context.Context, name string) string {
+	t.Helper()
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args:      []string{"drive", "+create-folder", "--name", name},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	if result.ExitCode != 0 {
+		combinedOutput := strings.ToLower(result.Stdout + "\n" + result.Stderr)
+		if strings.Contains(combinedOutput, "app scope not enabled") ||
+			strings.Contains(combinedOutput, "space:folder:create") ||
+			strings.Contains(combinedOutput, "99991672") {
+			t.Skipf("skip drive preview/cover workflow due to missing bot scope space:folder:create: %s", strings.TrimSpace(result.Stdout+"\n"+result.Stderr))
+		}
+	}
+	result.AssertExitCode(t, 0)
+	result.AssertStdoutStatus(t, true)
+
+	folderToken := gjson.Get(result.Stdout, "data.folder_token").String()
+	require.NotEmpty(t, folderToken, "drive folder token should not be empty")
+
+	parentT.Cleanup(func() {
+		cleanupCtx, cancel := clie2e.CleanupContext()
+		defer cancel()
+
+		deleteResult, deleteErr := clie2e.RunCmdWithRetry(cleanupCtx, clie2e.Request{
+			Args:      []string{"drive", "+delete", "--file-token", folderToken, "--type", "folder", "--yes"},
+			DefaultAs: "bot",
+		}, clie2e.RetryOptions{})
+		clie2e.ReportCleanupFailure(parentT, "delete drive folder "+folderToken, deleteResult, deleteErr)
+	})
+
+	return folderToken
+}

tests/cli_e2e/mail/mail_triage_dryrun_test.go

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+func TestMail_TriageDryRunPreservesMailboxInRequestChain(t *testing.T) {
+	setMailTriageDryRunEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"mail", "+triage",
+			"--mailbox", "alias@example.com",
+			"--filter", `{"folder_id":"INBOX"}`,
+			"--max", "3",
+			"--dry-run",
+		},
+		DefaultAs: "user",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	require.Equal(t, int64(2), gjson.Get(result.Stdout, "api.#").Int(), "stdout:\n%s", result.Stdout)
+	require.Equal(t, "GET", gjson.Get(result.Stdout, "api.0.method").String(), "stdout:\n%s", result.Stdout)
+	require.Equal(t, "/open-apis/mail/v1/user_mailboxes/alias@example.com/messages", gjson.Get(result.Stdout, "api.0.url").String(), "stdout:\n%s", result.Stdout)
+	require.Equal(t, int64(3), gjson.Get(result.Stdout, "api.0.params.page_size").Int(), "stdout:\n%s", result.Stdout)
+	require.Equal(t, "INBOX", gjson.Get(result.Stdout, "api.0.params.folder_id").String(), "stdout:\n%s", result.Stdout)
+
+	require.Equal(t, "POST", gjson.Get(result.Stdout, "api.1.method").String(), "stdout:\n%s", result.Stdout)
+	require.Equal(t, "/open-apis/mail/v1/user_mailboxes/alias@example.com/messages/batch_get", gjson.Get(result.Stdout, "api.1.url").String(), "stdout:\n%s", result.Stdout)
+	require.Equal(t, "metadata", gjson.Get(result.Stdout, "api.1.body.format").String(), "stdout:\n%s", result.Stdout)
+}
+
+func setMailTriageDryRunEnv(t *testing.T) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_APP_ID", "mail_triage_dryrun_test")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "mail_triage_dryrun_secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+}