Fix missing help text for drive files patch

.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/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/)
+      - 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/)
         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/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/|shortcuts/common/mcp_client\.go)
+      - path-except: (shortcuts/drive/|shortcuts/calendar/helpers\.go|shortcuts/common/mcp_client\.go)
         text: errs-no-bare-wrap
         linters:
           - forbidigo
-      # errs-no-legacy-helper enforced on domains whose shared validation/save
-      # helpers have migrated to typed final errors.
-      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/)
+      # 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/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo
@@ -115,15 +115,17 @@ linters:
           msg: >-
             [errs-typed-only] use errs.NewXxxError(...) builder
             (see errs/types.go).
-        # ── legacy shared error helpers banned on migrated domains ──
-        # These helpers emit legacy output.Err* / bare error shapes or drop
-        # typed metadata such as Param/Cause. Migrated domains must use typed
-        # common replacements or local typed helpers instead.
-        - pattern: (common\.FlagErrorf|common\.RejectDangerousChars|common\.WrapInputStatError|common\.WrapSaveErrorByCategory)\b
+        # ── legacy shared error helpers banned on drive ──
+        # These helpers internally produce legacy output.Err* shapes, so they
+        # are invisible to the errs-typed-only ban above. Drive has migrated its
+        # calls to typed errs.* (drive-local driveInputStatError / driveSaveError);
+        # this prevents reintroduction. Other domains still use the shared
+        # helpers (migrated globally in a later phase), so this is drive-scoped.
+        - pattern: (common\.FlagErrorf|common\.WrapInputStatError|common\.WrapSaveErrorByCategory)\b
           msg: >-
-            [errs-no-legacy-helper] these shared helpers emit legacy or
-            metadata-poor error shapes. Use typed common replacements, typed
-            errs.NewXxxError builders, or domain-local typed helpers.
+            [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).
         # ── bare error wraps banned on fully-typed paths ──
         - pattern: (fmt\.Errorf|errors\.New)\b
           msg: >-

CHANGELOG.md

@@ -2,23 +2,6 @@
 
 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
@@ -1026,7 +1009,6 @@ 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

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

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

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

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

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

cmd/root_integration_test.go

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

cmd/schema/schema.go

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

cmd/schema/schema_test.go

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

cmd/service/service.go

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

cmd/service/service_test.go

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

cmd/update/update_test.go

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

events/register.go

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

events/whiteboard/native.go

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

events/whiteboard/preconsume.go

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

events/whiteboard/preconsume_test.go

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

events/whiteboard/register.go

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

internal/errclass/classify.go

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

internal/errclass/classify_test.go

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

internal/errclass/codemeta_calendar.go

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

internal/errclass/codemeta_calendar_test.go

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

internal/errclass/codemeta_mail.go

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

internal/registry/method_desc.go

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

internal/registry/registry_test.go

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

internal/registry/scope_overrides.json

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

internal/selfupdate/updater.go

@@ -165,10 +165,6 @@ 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,13 +188,6 @@ 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,7 +4,6 @@
 package skillscheck
 
 import (
-	"encoding/json"
 	"fmt"
 	"regexp"
 	"sort"
@@ -58,28 +57,6 @@ 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{}
@@ -100,11 +77,8 @@ func parseGlobalSkillsList(lines []string) []string {
 			continue
 		}
 
-		if strings.HasPrefix(trimmed, "Agents:") {
-			continue
-		}
-
-		if isGlobalSkillsSectionHeader(trimmed) {
+		// Skip indented lines (Agents: ...)
+		if strings.HasPrefix(line, "  ") || strings.HasPrefix(line, "\t") {
 			continue
 		}
 
@@ -117,24 +91,21 @@ func parseGlobalSkillsList(lines []string) []string {
 		candidate := parts[0]
 
 		// Validate and add
-		if candidate == "" || !skillNamePattern.MatchString(candidate) {
+		if candidate == "" || strings.Contains(candidate, " ") || strings.HasSuffix(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{}
@@ -224,7 +195,6 @@ 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
@@ -269,9 +239,10 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	}
 
 	// --- Step 2: List local (installed) skills ---
-	local, ok := listLocalSkills(opts.Runner)
-	if !ok {
-		return fallbackFullInstall(opts, "local skills list failed or parsed as empty", official)
+	local := []string{}
+	localResult := opts.Runner.ListGlobalSkills()
+	if localResult != nil && localResult.Err == nil {
+		local = ParseSkillsList(localResult.Stdout.String())
 	}
 
 	// --- Step 3: Read previous state ---
@@ -327,24 +298,6 @@ 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,49 +67,6 @@ 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{
@@ -156,18 +113,14 @@ func TestPlanForceRestoresAllOfficial(t *testing.T) {
 }
 
 type fakeSkillsRunner struct {
-	officialOut      string
-	globalJSONOut    string
-	globalOut        string
-	officialErr      error
-	globalJSONErr    error
-	globalErr        error
-	installErr       error
-	installAllErr    error
-	installed        [][]string
-	installedAll     int
-	listedGlobalJSON int
-	listedGlobalText int
+	officialOut   string
+	globalOut     string
+	officialErr   error
+	globalErr     error
+	installErr    error
+	installAllErr error
+	installed     [][]string
+	installedAll  int
 }
 
 func officialSkillsOutput(names ...string) string {
@@ -193,19 +146,6 @@ 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)
@@ -213,16 +153,7 @@ 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
@@ -255,9 +186,8 @@ func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	}
 
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail", "lark-new"),
-		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-custom"),
-		globalOut:     globalSkillsOutput("lark-mail"),
+		officialOut: officialSkillsOutput("lark-calendar", "lark-mail", "lark-new"),
+		globalOut:   globalSkillsOutput("lark-calendar", "lark-custom"),
 	}
 	result := SyncSkills(SyncOptions{
 		Version: "1.0.33",
@@ -269,12 +199,6 @@ 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 {
@@ -338,73 +262,47 @@ func TestSyncSkills_ListOfficialFailureAndFullInstallFails(t *testing.T) {
 	}
 }
 
-func TestSyncSkills_GlobalJSONFailureFallsBackToTextList(t *testing.T) {
+func TestSyncSkills_GlobalListFailureDegradesToColdStart(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONErr: fmt.Errorf("json list failed"),
-		globalOut:     globalSkillsOutput("lark-calendar"),
+		officialOut: officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalErr:   fmt.Errorf("global list failed"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
 	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
+		t.Fatalf("SyncSkills() err = %v, want nil (degraded to cold start)", result.Err)
 	}
 	if result.Action != "synced" {
 		t.Fatalf("SyncSkills() action = %q, want synced", result.Action)
 	}
 	assertStrings(t, result.Updated, []string{"lark-calendar", "lark-mail"})
-	if runner.listedGlobalJSON != 1 || runner.listedGlobalText != 1 {
-		t.Fatalf("listed JSON/text = %d/%d, want 1/1", runner.listedGlobalJSON, runner.listedGlobalText)
+	assertStrings(t, result.SkippedDeleted, []string{})
+}
+
+func TestSyncSkills_ParseEmptyGlobalListWithNonEmptyStdoutDegradesToColdStart(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",
 	}
+
+	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 != "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.installedAll != 0 {
-		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
+		t.Fatalf("installedAll = %d, want 0 (no fallback)", runner.installedAll)
 	}
-}
-
-func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	runner := &fakeSkillsRunner{
-		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.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)
-	}
-	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)
+	if len(runner.installed) != 1 {
+		t.Fatalf("installed = %d calls, want 1 (incremental)", len(runner.installed))
 	}
 }
 
@@ -446,7 +344,6 @@ 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,
@@ -478,7 +375,6 @@ 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"),
@@ -577,7 +473,6 @@ 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,
@@ -602,7 +497,6 @@ 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,
@@ -643,9 +537,8 @@ func TestSyncSkills_FallbackBreaksDegradationLoop(t *testing.T) {
 	}
 
 	runner2 := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
-		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
+		officialOut: officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalOut:   globalSkillsOutput("lark-calendar", "lark-mail"),
 	}
 	result2 := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner2, Now: time.Now})
 	if result2.Action != "synced" {

lint/errscontract/rule_no_legacy_common_helper_call.go

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

lint/errscontract/rule_no_legacy_envelope_literal.go

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

lint/errscontract/rule_no_legacy_runtime_api_call.go

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

lint/errscontract/rules_test.go

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

package.json

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

shortcuts/base/base_advperm_disable.go

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

shortcuts/base/base_advperm_enable.go

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

shortcuts/base/base_advperm_test.go

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

shortcuts/base/base_block_ops.go

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

shortcuts/base/base_data_query.go

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

shortcuts/base/base_errors.go

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

shortcuts/base/base_errors_test.go

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

shortcuts/base/base_execute_test.go

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

shortcuts/base/base_form_questions_create.go

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

shortcuts/base/base_form_questions_delete.go

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

shortcuts/base/base_form_questions_update.go

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

shortcuts/base/base_form_submit.go

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

shortcuts/base/base_role_common.go

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

shortcuts/base/base_role_create.go

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

shortcuts/base/base_role_delete.go

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

shortcuts/base/base_role_get.go

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

shortcuts/base/base_role_list.go

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

shortcuts/base/base_role_test.go

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

shortcuts/base/base_role_update.go

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

shortcuts/base/base_shortcut_helpers.go

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

shortcuts/base/dashboard_block_create.go

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

shortcuts/base/field_ops.go

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

shortcuts/base/helpers.go

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

shortcuts/base/record_markdown.go

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

shortcuts/base/record_markdown_test.go

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

shortcuts/base/record_ops.go

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

shortcuts/base/record_query.go

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

shortcuts/base/record_upload_attachment.go

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

shortcuts/base/table_ops.go

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

shortcuts/base/workflow_create.go

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

shortcuts/base/workflow_disable.go

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

shortcuts/base/workflow_enable.go

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

shortcuts/base/workflow_get.go

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

shortcuts/base/workflow_list.go

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

shortcuts/base/workflow_update.go

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

shortcuts/calendar/calendar_agenda.go

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

shortcuts/calendar/calendar_create.go

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

shortcuts/calendar/calendar_freebusy.go

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

shortcuts/calendar/calendar_room_find.go

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

shortcuts/calendar/calendar_rsvp.go

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

shortcuts/calendar/calendar_suggestion.go

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

shortcuts/calendar/calendar_update.go

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

shortcuts/calendar/errors.go

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

shortcuts/calendar/errors_attribution_test.go

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

shortcuts/common/call_api_typed_test.go

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

shortcuts/common/drive_media_upload.go

@@ -15,7 +15,6 @@ 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"
 )
 
@@ -58,7 +57,6 @@ 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 {
@@ -100,52 +98,6 @@ 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
@@ -178,43 +130,6 @@ 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.
@@ -365,122 +280,3 @@ 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

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

shortcuts/common/runner.go

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

shortcuts/common/validate.go

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

shortcuts/common/validate_ids.go

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

shortcuts/common/validate_test.go

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

shortcuts/drive/drive_cover.go

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

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

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

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

shortcuts/drive/drive_secure_label.go

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

shortcuts/drive/drive_secure_label_test.go

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

shortcuts/drive/shortcuts.go

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

shortcuts/drive/shortcuts_test.go

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

shortcuts/im/convert_lib/helpers.go

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

shortcuts/im/convert_lib/merge.go

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

shortcuts/im/convert_lib/reactions.go

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

shortcuts/im/convert_lib/thread.go

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

shortcuts/im/helpers.go

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