feat(drive): harden inspect shortcut failures

.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/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|internal/event/consume/|cmd/event/|events/|shortcuts/event/)
+      - 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/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/)
         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/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/common/mcp_client\.go|cmd/event/|events/|shortcuts/event/)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|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/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|cmd/event/|events/|shortcuts/event/)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo

AGENTS.md

@@ -75,31 +75,7 @@ The one rule to internalize: **every error message you write will be parsed by a
 
 ### Structured errors in commands
 
-Command-facing failures must be typed `errs.*` errors — never the legacy `output.Err*` helpers and never a final bare `fmt.Errorf`. AI agents parse the stderr envelope's `type` / `subtype` / `param` / `hint` fields to decide their next action; the full taxonomy lives in `errs/ERROR_CONTRACT.md`.
-
-Picking a constructor:
-
-| Failure | Constructor |
-|---------|-------------|
-| User flag/arg fails validation | `errs.NewValidationError(errs.SubtypeInvalidArgument, ...).WithParam("--flag")` |
-| Valid request, wrong system state | `errs.NewValidationError(errs.SubtypeFailedPrecondition, ...).WithHint(...)` |
-| Lark API returned `code != 0` | `runtime.CallAPITyped` (shortcuts) / `errclass.BuildAPIError` (raw responses) — never hand-build |
-| Network / transport failure | `errs.NewNetworkError(errs.SubtypeNetworkTransport, ...)` |
-| Local file I/O failure | `errs.NewInternalError(errs.SubtypeFileIO, ...)` — validate the path first (`validate.SafeInputPath` / `SafeOutputPath`) and use `vfs.*` |
-| Unclassified lower-layer error as final | `errs.NewInternalError(errs.SubtypeUnknown, ...).WithCause(err)` |
-| Lower layer already returned a typed error | pass it through unchanged — re-wrapping downgrades its classification |
-
-Signatures that are easy to guess wrong:
-
-- `runtime.CallAPITyped(method, url string, params map[string]interface{}, data interface{}) (map[string]interface{}, error)` — it performs the HTTP request itself and classifies `code != 0` into a typed error; just return the error it gives you.
-- Typed pass-through check: `if _, ok := errs.ProblemOf(err); ok { return err }` — `ProblemOf` returns `(*errs.Problem, bool)`, not a nilable pointer.
-- `.WithParam` exists only on `*errs.ValidationError`. `InternalError` / `NetworkError` have no param field — file or endpoint context goes in the message or `.WithHint(...)`.
-
-`forbidigo` + `lint/errscontract` reject the legacy `output.Err*` helpers, bare final `fmt.Errorf` / `errors.New`, and legacy envelope literals on migrated paths. Beyond what lint catches, three authoring conventions apply:
-
-- Preserve the underlying error with `.WithCause(err)` so `errors.Is` / `errors.Unwrap` keep working.
-- `param` names only the user input that actually failed. Recovery guidance goes in `.WithHint(...)`; machine-readable recovery fields (`missing_scopes`, `log_id`) carry server/system ground truth only — never caller-side guesses.
-- Error-path tests assert typed metadata via `errs.ProblemOf` (`category` / `subtype` / `param`) and cause preservation, not message substrings alone.
+`RunE` functions must return `output.Errorf` / `output.ErrWithHint` — never bare `fmt.Errorf`. AI agents parse stderr as JSON; bare errors break this contract.
 
 ### stdout is data, stderr is everything else
 

CHANGELOG.md

@@ -2,68 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [v1.0.50] - 2026-06-09
-
-### Features
-
-- **doc**: Emit typed error envelopes across the doc domain (#1346)
-- **event**: Emit typed error envelopes across the event domain (#1289)
-- **contact**: Emit typed error envelopes across the contact domain (#1287)
-- **sheets**: Guard `+csv-put --csv` against a path passed without `@` (#1337)
-- **cli**: Adjust agent timeout hint output conditions (#1328)
-
-### Bug Fixes
-
-- **drive**: Add `@file`/stdin support to `+add-comment --content` (#1343)
-- **slides**: Build create URL locally instead of drive metas call (#1329)
-- **cli**: Clarify `--block-id` supports comma-separated batch delete in help text (#1336)
-
-### Documentation
-
-- **doc**: Replace append with `block_insert_after` in skeleton workflow guidance (#1340)
-- **doc**: Document `<folder-manager>` resource block (#1168)
-- **drive**: Add drive comment location guidance (#1258)
-
-## [v1.0.49] - 2026-06-08
-
-### Features
-
-- **events**: Add whiteboard event domain with per-board subscription (#1265)
-- **im**: Support feed group (#1102)
-- **im**: Add feed shortcut create, list, and remove shortcuts (#1273)
-- **im**: Format feed group error handling (#1308)
-- **im**: Return typed error envelopes across the im domain (#1230)
-- **base**: Emit typed error envelopes across the base domain (#1248)
-- **calendar**: Emit typed error envelopes across the calendar domain (#1232)
-- **task**: Emit typed error envelopes across the task domain (#1231)
-- **okr,whiteboard**: Emit typed error envelopes across both domains (#1236)
-- **minutes,vc**: Emit typed error envelopes across both domains (#1234)
-- **markdown**: Harden create upload failures (#1325)
-- **drive**: Harden inspect shortcut failures (#1324)
-- **slides**: Add IconPark lookup for Lark slides (#1123)
-- **doc**: Remove docs v1 API (#1291)
-- **cli**: Add `skills` command to read embedded skill content (#1318)
-- **cli**: Fetch official skills index (#1301)
-- **shared**: Document relative-path-only file arguments (#1319)
-- **scopes**: Clear `recommend.allow` scope auto-approve overrides (#1272)
-- **shortcuts**: Check shortcut example commands against the live CLI tree (#1244)
-
-### Bug Fixes
-
-- **events**: Keep bounded event consume runs alive after stdin EOF (#1285)
-- **drive**: Use docs secure label read scope (#1281)
-
-### Documentation
-
-- **approval**: Restructure skill with intent table and scope boundaries (#1307)
-- **skills**: Tighten drive and markdown guardrails (#1326)
-- **skills**: Optimize calendar, vc, and minutes skill guidance (#1269)
-- **markdown**: Add markdown domain template (#1293)
-- **markdown**: Improve lark-markdown skill guidance (#1279)
-- **doc**: Improve lark-doc skill guidance (#1283)
-- **wiki**: Optimize skill guidance and routing boundaries (#1275)
-- **slides**: Tighten routing/boundary and reconcile in-slide whiteboard (#1169)
-
 ## [v1.0.48] - 2026-06-04
 
 ### Features
@@ -1088,8 +1026,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
-[v1.0.50]: https://github.com/larksuite/cli/releases/tag/v1.0.50
-[v1.0.49]: https://github.com/larksuite/cli/releases/tag/v1.0.49
 [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

cmd/auth/login.go

@@ -296,11 +296,10 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 
 	// Step 2: Show user code and verification URL.
-	// JSON mode embeds AgentTimeoutHint as a structured field so agents that
-	// capture stdout into a JSON parser see it without stream-mixing surprises.
-	// Text mode prints the hint to stderr only when running under a non-TTY
-	// (i.e. piped / agent harness), since humans reading a terminal don't need
-	// the agent-oriented instructions.
+	// Both branches surface AgentTimeoutHint, but on different channels:
+	// JSON mode embeds it as a structured field (so an agent that captures
+	// stdout into a JSON parser sees it without stream-mixing surprises),
+	// text mode prints to stderr (alongside the URL prompt).
 	if opts.JSON {
 		data := map[string]interface{}{
 			"event":                     "device_authorization",
@@ -318,9 +317,7 @@ func authLoginRun(opts *LoginOptions) error {
 	} else {
 		fmt.Fprintf(f.IOStreams.ErrOut, msg.OpenURL)
 		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", authResp.VerificationUriComplete)
-		if f.IOStreams != nil && !f.IOStreams.IsTerminal {
-			fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
-		}
+		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 
 	// Step 3: Poll for token
@@ -407,11 +404,10 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 			fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] [WARN] auth login: failed to remove cached requested scopes: %v\n", err)
 		}
 	}
-	// Skip the stderr hint in JSON mode (the --no-wait call that issued
-	// the device_code already surfaced it as a JSON field), and also skip it
-	// when running on an interactive terminal — the agent-oriented
-	// instructions only matter for piped / harness environments.
-	if !opts.JSON && f.IOStreams != nil && !f.IOStreams.IsTerminal {
+	// Skip the stderr hint in JSON mode — the --no-wait call that issued the
+	// device_code already returned the hint as a JSON field, and writing
+	// text to stderr would pollute consumers that combine streams via 2>&1.
+	if !opts.JSON {
 		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 	log(msg.WaitingAuth)

cmd/event/bus.go

@@ -12,7 +12,6 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/event"
@@ -39,8 +38,7 @@ func NewCmdBus(f *cmdutil.Factory) *cobra.Command {
 
 			logger, err := bus.SetupBusLogger(eventsDir)
 			if err != nil {
-				return errs.NewInternalError(errs.SubtypeFileIO,
-					"set up bus logger: %s", err).WithCause(err)
+				return err
 			}
 
 			tr := transport.New()
@@ -60,14 +58,7 @@ func NewCmdBus(f *cmdutil.Factory) *cobra.Command {
 				}
 			}()
 
-			if err := b.Run(ctx); err != nil {
-				if _, ok := errs.ProblemOf(err); ok {
-					return err
-				}
-				return errs.NewInternalError(errs.SubtypeUnknown,
-					"event bus daemon exited: %s", err).WithCause(err)
-			}
-			return nil
+			return b.Run(ctx)
 		},
 	}
 

cmd/event/bus_test.go

@@ -1,45 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package event
-
-import (
-	"os"
-	"path/filepath"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// The hidden `event _bus` daemon command must exit with a typed file_io error
-// when its log directory cannot be created (the error is only visible in the
-// forked process's captured stderr / bus.log).
-func TestBusCommandLoggerSetupFailureIsTypedFileIO(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	// Block the events/ root with a regular file so MkdirAll fails.
-	if err := os.WriteFile(filepath.Join(dir, "events"), []byte("x"), 0600); err != nil {
-		t.Fatal(err)
-	}
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "cli_bus_test", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-	cmd := NewCmdBus(f)
-	cmd.SetArgs([]string{})
-
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected logger setup error")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeFileIO {
-		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
-			errs.CategoryInternal, errs.SubtypeFileIO)
-	}
-}

cmd/event/consume.go

@@ -16,7 +16,6 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/appmeta"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -65,8 +64,8 @@ Use 'event schema <EventKey>' for parameter details.`,
 	cmd.Flags().StringVar(&o.jqExpr, "jq", "", "JQ expression to filter output")
 	cmd.Flags().BoolVar(&o.quiet, "quiet", false, "Suppress informational messages on stderr")
 	cmd.Flags().StringVar(&o.outputDir, "output-dir", "", "Write each event as a file in this directory (relative paths only; absolute paths and ~ are rejected to prevent path traversal)")
-	cmd.Flags().IntVar(&o.maxEvents, "max-events", 0, "Exit after N successful emits (0 = unlimited). Multi-worker EventKeys may emit up to workers-1 past N before all workers stop. Bounded runs ignore stdin EOF.")
-	cmd.Flags().DurationVar(&o.timeout, "timeout", 0, "Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout'). Bounded runs ignore stdin EOF.")
+	cmd.Flags().IntVar(&o.maxEvents, "max-events", 0, "Exit after N successful emits (0 = unlimited). Multi-worker EventKeys may emit up to workers-1 past N before all workers stop.")
+	cmd.Flags().DurationVar(&o.timeout, "timeout", 0, "Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout').")
 	cmd.Flags().String("as", "auto", "identity type: user | bot | auto (must match EventKey's declared AuthTypes)")
 	_ = cmd.RegisterFlagCompletionFunc("as", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return []string{"user", "bot", "auto"}, cobra.ShellCompDirectiveNoFileComp
@@ -102,10 +101,11 @@ func runConsume(cmd *cobra.Command, f *cmdutil.Factory, eventKey string, o consu
 
 	if o.jqExpr != "" {
 		if err := output.ValidateJqExpression(o.jqExpr); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).
-				WithParam("--jq").
-				WithCause(err).
-				WithHint("see `lark-cli event consume --help` EXAMPLES for common patterns, or `lark-cli event schema %s` for valid field paths", eventKey)
+			return output.ErrWithHint(
+				output.ExitValidation, "validation",
+				err.Error(),
+				fmt.Sprintf("see `lark-cli event consume --help` EXAMPLES for common patterns, or `lark-cli event schema %s` for valid field paths", eventKey),
+			)
 		}
 	}
 
@@ -184,9 +184,8 @@ func runConsume(cmd *cobra.Command, f *cmdutil.Factory, eventKey string, o consu
 		errOut = io.Discard
 	}
 
-	// Non-TTY unbounded consumers use stdin EOF as shutdown for subprocess callers.
-	// Bounded runs already have --max-events/--timeout as their lifecycle control.
-	if shouldWatchStdinEOF(f.IOStreams.IsTerminal, o.maxEvents, o.timeout) {
+	// Non-TTY only: stdin EOF is shutdown for subprocess callers; in TTY Ctrl-D must not exit.
+	if !f.IOStreams.IsTerminal {
 		watchStdinEOF(os.Stdin, cancel, errOut)
 	}
 
@@ -261,12 +260,12 @@ func preflightScopes(ctx context.Context, pf *preflightCtx) error {
 	if len(missing) == 0 {
 		return nil
 	}
-	return errs.NewPermissionError(errs.SubtypeMissingScope,
-		"missing required scopes for EventKey %s (as %s): %s",
-		pf.eventKey, pf.identity, strings.Join(missing, ", ")).
-		WithIdentity(string(pf.identity)).
-		WithMissingScopes(missing...).
-		WithHint("%s", scopeRemediationHint(pf.identity, missing, pf.appID, pf.brand))
+	return output.ErrWithHint(
+		output.ExitAuth, "auth",
+		fmt.Sprintf("missing required scopes for EventKey %s (as %s): %s",
+			pf.eventKey, pf.identity, strings.Join(missing, ", ")),
+		scopeRemediationHint(pf.identity, missing, pf.appID, pf.brand),
+	)
 }
 
 // scopeRemediationHint returns an identity-appropriate fix for missing scopes.
@@ -301,27 +300,23 @@ func preflightEventTypes(pf *preflightCtx) error {
 	if len(missing) == 0 {
 		return nil
 	}
-	return errs.NewValidationError(errs.SubtypeFailedPrecondition,
-		"EventKey %s requires event types not subscribed in console: %s",
-		pf.keyDef.Key, strings.Join(missing, ", ")).
-		WithHint("subscribe these events and publish a new app version at: %s",
-			consoleEventSubscriptionURL(pf.brand, pf.appID))
+	return output.ErrWithHint(
+		output.ExitValidation, "validation",
+		fmt.Sprintf("EventKey %s requires event types not subscribed in console: %s",
+			pf.keyDef.Key, strings.Join(missing, ", ")),
+		fmt.Sprintf("subscribe these events and publish a new app version at: %s",
+			consoleEventSubscriptionURL(pf.brand, pf.appID)),
+	)
 }
 
 // sanitizeOutputDir rejects absolute/parent-escaping paths and ~ (SafeOutputPath treats it as a literal dir name).
 func sanitizeOutputDir(dir string) (string, error) {
 	if strings.HasPrefix(dir, "~") {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"%s; use a relative path like ./output instead", errOutputDirTilde).
-			WithParam("--output-dir").
-			WithCause(errOutputDirTilde)
+		return "", output.ErrValidation("%s; use a relative path like ./output instead", errOutputDirTilde)
 	}
 	safe, err := validate.SafeOutputPath(dir)
 	if err != nil {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"%s %q: %s", errOutputDirUnsafe, dir, err).
-			WithParam("--output-dir").
-			WithCause(errOutputDirUnsafe)
+		return "", output.ErrValidation("%s %q: %s", errOutputDirUnsafe, dir, err)
 	}
 	return safe, nil
 }
@@ -333,21 +328,18 @@ func resolveTenantToken(ctx context.Context, f *cmdutil.Factory, appID string) (
 	}
 	result, err := f.Credential.ResolveToken(ctx, credential.NewTokenSpec(core.AsBot, appID))
 	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return "", err
-		}
-		return "", errs.NewAuthenticationError(errs.SubtypeTokenMissing,
-			"resolve tenant access token: %s", err).WithCause(err)
+		return "", output.ErrAuth("resolve tenant access token: %s", err)
 	}
 	if result == nil || result.Token == "" {
-		return "", errs.NewAuthenticationError(errs.SubtypeTokenMissing,
-			"no tenant access token available for app %s", appID).
-			WithHint("Check that app_secret is configured (lark-cli config show) and try 'lark-cli auth login'.")
+		return "", output.ErrWithHint(
+			output.ExitAuth, "auth",
+			fmt.Sprintf("no tenant access token available for app %s", appID),
+			"Check that app_secret is configured (lark-cli config show) and try 'lark-cli auth login'.",
+		)
 	}
 	return result.Token, nil
 }
 
-// Sentinels for errors.Is checks; call sites wrap them as typed ValidationError causes.
 var (
 	errInvalidParamFormat = errors.New("invalid --param format")
 	errOutputDirTilde     = errors.New("--output-dir does not support ~ expansion")
@@ -359,10 +351,7 @@ func parseParams(raw []string) (map[string]string, error) {
 	for _, kv := range raw {
 		k, v, ok := strings.Cut(kv, "=")
 		if !ok || k == "" {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"%s %q: expected key=value", errInvalidParamFormat, kv).
-				WithParam("--param").
-				WithCause(errInvalidParamFormat)
+			return nil, output.ErrValidation("%s %q: expected key=value", errInvalidParamFormat, kv)
 		}
 		m[k] = v
 	}
@@ -381,8 +370,3 @@ func watchStdinEOF(r io.Reader, cancel context.CancelFunc, errOut io.Writer) {
 		cancel()
 	}()
 }
-
-// shouldWatchStdinEOF gates the stdin-EOF shutdown watcher: non-TTY unbounded runs only (<= 0 mirrors downstream's >0-is-bounded semantics, so negative bounds stay unbounded).
-func shouldWatchStdinEOF(isTerminal bool, maxEvents int, timeout time.Duration) bool {
-	return !isTerminal && maxEvents <= 0 && timeout <= 0
-}

cmd/event/consume_stdin_test.go

@@ -61,70 +61,3 @@ func TestWatchStdinEOF_DiagnosticMessage(t *testing.T) {
 		t.Fatal("watchStdinEOF did not cancel within 1s of EOF")
 	}
 }
-
-func TestShouldWatchStdinEOF(t *testing.T) {
-	tests := []struct {
-		name       string
-		isTerminal bool
-		maxEvents  int
-		timeout    time.Duration
-		want       bool
-	}{
-		{
-			name:       "terminal",
-			isTerminal: true,
-			want:       false,
-		},
-		{
-			name: "non terminal unbounded",
-			want: true,
-		},
-		{
-			name:      "non terminal negative max events is unbounded",
-			maxEvents: -1,
-			want:      true,
-		},
-		{
-			name:    "non terminal negative timeout is unbounded",
-			timeout: -1 * time.Second,
-			want:    true,
-		},
-		{
-			name:      "non terminal max events bounded",
-			maxEvents: 1,
-			want:      false,
-		},
-		{
-			name:    "non terminal timeout bounded",
-			timeout: 10 * time.Minute,
-			want:    false,
-		},
-		{
-			name:      "non terminal both bounds positive",
-			maxEvents: 1,
-			timeout:   10 * time.Minute,
-			want:      false,
-		},
-		{
-			name:      "non terminal bounded max events with negative timeout",
-			maxEvents: 1,
-			timeout:   -1 * time.Second,
-			want:      false,
-		},
-		{
-			name:      "non terminal bounded timeout with negative max events",
-			maxEvents: -1,
-			timeout:   10 * time.Minute,
-			want:      false,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := shouldWatchStdinEOF(tt.isTerminal, tt.maxEvents, tt.timeout)
-			if got != tt.want {
-				t.Fatalf("shouldWatchStdinEOF() = %v, want %v", got, tt.want)
-			}
-		})
-	}
-}

cmd/event/consume_test.go

@@ -4,14 +4,9 @@
 package event
 
 import (
-	"context"
 	"errors"
 	"strings"
 	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/credential"
 )
 
 func TestParseParams(t *testing.T) {
@@ -78,7 +73,6 @@ func TestParseParams(t *testing.T) {
 				if tc.wantEcho != "" && !strings.Contains(err.Error(), tc.wantEcho) {
 					t.Errorf("err %q should echo %q so user sees the bad input", err.Error(), tc.wantEcho)
 				}
-				assertInvalidArgumentParam(t, err, "--param")
 				return
 			}
 			if err != nil {
@@ -96,77 +90,6 @@ func TestParseParams(t *testing.T) {
 	}
 }
 
-// emptyTokenResolver resolves to a result that carries no token.
-type emptyTokenResolver struct{}
-
-func (emptyTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
-	return &credential.TokenResult{}, nil
-}
-
-// failingTokenResolver fails outright with an untyped error.
-type failingTokenResolver struct{}
-
-func (failingTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
-	return nil, errors.New("backend unavailable")
-}
-
-func factoryWithResolver(r credential.DefaultTokenResolver) *cmdutil.Factory {
-	return &cmdutil.Factory{Credential: credential.NewCredentialProvider(nil, nil, r, nil)}
-}
-
-func TestResolveTenantToken_EmptyTokenResult(t *testing.T) {
-	_, err := resolveTenantToken(context.Background(), factoryWithResolver(emptyTokenResolver{}), "cli_x")
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryAuthentication || p.Subtype != errs.SubtypeTokenMissing {
-		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
-			errs.CategoryAuthentication, errs.SubtypeTokenMissing)
-	}
-	var malformed *credential.MalformedTokenResultError
-	if !errors.As(err, &malformed) {
-		t.Error("empty-token failure should preserve the credential-layer cause")
-	}
-}
-
-func TestResolveTenantToken_ResolverFailure(t *testing.T) {
-	_, err := resolveTenantToken(context.Background(), factoryWithResolver(failingTokenResolver{}), "cli_x")
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryAuthentication || p.Subtype != errs.SubtypeTokenMissing {
-		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
-			errs.CategoryAuthentication, errs.SubtypeTokenMissing)
-	}
-	if errors.Unwrap(err) == nil {
-		t.Error("resolver failure should preserve its cause")
-	}
-}
-
-// assertInvalidArgumentParam verifies err is a typed validation error with
-// subtype invalid_argument naming the given flag in its param field.
-func assertInvalidArgumentParam(t *testing.T, err error, param string) {
-	t.Helper()
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype = %s, want %s", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != param {
-		t.Errorf("param = %q, want %q", ve.Param, param)
-	}
-}
-
 func TestSanitizeOutputDir(t *testing.T) {
 	cases := []struct {
 		name       string
@@ -207,7 +130,6 @@ func TestSanitizeOutputDir(t *testing.T) {
 				if !errors.Is(err, tc.wantSentry) {
 					t.Fatalf("want errors.Is(err, %v), got %q", tc.wantSentry, err.Error())
 				}
-				assertInvalidArgumentParam(t, err, "--output-dir")
 				return
 			}
 			if err != nil {

cmd/event/preflight_test.go

@@ -8,10 +8,10 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/appmeta"
 	"github.com/larksuite/cli/internal/core"
 	eventlib "github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/output"
 )
 
 func newPreflightCtx(appID string, brand core.LarkBrand, identity core.Identity, keyDef *eventlib.KeyDefinition, appVer *appmeta.AppVersion) *preflightCtx {
@@ -89,17 +89,19 @@ func TestPreflightEventTypes_MissingBlocks(t *testing.T) {
 	if !strings.Contains(err.Error(), "mail.user_mailbox.event.message_read_v1") {
 		t.Errorf("error should name the missing event type, got: %v", err)
 	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	var exit *output.ExitError
+	if !errors.As(err, &exit) {
+		t.Fatalf("expected output.ExitError, got %T: %v", err, err)
 	}
-	if p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
-			errs.CategoryValidation, errs.SubtypeFailedPrecondition)
+	if exit.Code != output.ExitValidation {
+		t.Errorf("ExitCode = %d, want ExitValidation (%d)", exit.Code, output.ExitValidation)
+	}
+	if exit.Detail == nil {
+		t.Fatal("expected Detail with hint")
 	}
 	wantURL := "https://open.feishu.cn/app/cli_XXXXXXXXXXXXXXXX/event"
-	if !strings.Contains(p.Hint, wantURL) {
-		t.Errorf("hint missing subscription URL %q\ngot: %s", wantURL, p.Hint)
+	if !strings.Contains(exit.Detail.Hint, wantURL) {
+		t.Errorf("hint missing subscription URL %q\ngot: %s", wantURL, exit.Detail.Hint)
 	}
 }
 
@@ -143,19 +145,17 @@ func TestPreflightScopes_Bot_MissingBlocks(t *testing.T) {
 	if !strings.Contains(err.Error(), "im:message.group_at_msg") {
 		t.Errorf("error should name missing scope, got: %v", err)
 	}
-	var permErr *errs.PermissionError
-	if !errors.As(err, &permErr) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
+	var exit *output.ExitError
+	if !errors.As(err, &exit) {
+		t.Fatalf("expected output.ExitError, got %T: %v", err, err)
 	}
-	if permErr.Category != errs.CategoryAuthorization || permErr.Subtype != errs.SubtypeMissingScope {
-		t.Errorf("problem = %s/%s, want %s/%s", permErr.Category, permErr.Subtype,
-			errs.CategoryAuthorization, errs.SubtypeMissingScope)
+	if exit.Code != output.ExitAuth {
+		t.Errorf("ExitCode = %d, want ExitAuth (%d)", exit.Code, output.ExitAuth)
 	}
-	wantMissing := []string{"im:message.group_at_msg"}
-	if len(permErr.MissingScopes) != 1 || permErr.MissingScopes[0] != wantMissing[0] {
-		t.Errorf("MissingScopes = %v, want %v", permErr.MissingScopes, wantMissing)
+	if exit.Detail == nil {
+		t.Fatal("expected Detail with hint, got nil Detail")
 	}
-	hint := permErr.Hint
+	hint := exit.Detail.Hint
 	wantSubstrings := []string{
 		"https://open.feishu.cn/app/cli_x/auth?q=",
 		"im:message.group_at_msg",

cmd/event/runtime.go

@@ -6,8 +6,8 @@ package event
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/core"
 )
@@ -26,11 +26,7 @@ func (r *consumeRuntime) CallAPI(ctx context.Context, method, path string, body
 		As:     r.accessIdentity,
 	})
 	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport,
-			"api %s %s: %s", method, path, err).WithCause(err)
+		return nil, err
 	}
 	// Non-JSON HTTP errors (gateway text/plain 404 etc.) skip OAPI envelope parsing.
 	ct := resp.Header.Get("Content-Type")
@@ -40,20 +36,11 @@ func (r *consumeRuntime) CallAPI(ctx context.Context, method, path string, body
 		if len(body) > maxBodyEcho {
 			body = body[:maxBodyEcho] + "…(truncated)"
 		}
-		if resp.StatusCode >= 500 {
-			return nil, errs.NewNetworkError(errs.SubtypeNetworkServer,
-				"api %s %s returned %d: %s", method, path, resp.StatusCode, body).WithRetryable()
-		}
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"api %s %s returned %d: %s", method, path, resp.StatusCode, body)
+		return nil, fmt.Errorf("api %s %s returned %d: %s", method, path, resp.StatusCode, body)
 	}
 	result, err := client.ParseJSONResponse(resp)
 	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"api %s %s: %s", method, path, err).WithCause(err)
+		return nil, err
 	}
 	if apiErr := r.client.CheckResponse(result, r.accessIdentity); apiErr != nil {
 		return json.RawMessage(resp.RawBody), apiErr

cmd/event/runtime_test.go

@@ -1,147 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package event
-
-import (
-	"context"
-	"errors"
-	"io"
-	"net/http"
-	"strings"
-	"testing"
-
-	lark "github.com/larksuite/oapi-sdk-go/v3"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/client"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-// staticTokenResolver always returns a fixed token without any HTTP calls.
-type staticTokenResolver struct{}
-
-func (s *staticTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
-	return &credential.TokenResult{Token: "test-token"}, nil
-}
-
-// stubRoundTripper intercepts every outgoing request with a canned response.
-type stubRoundTripper struct {
-	respond func(*http.Request) (*http.Response, error)
-}
-
-func (s stubRoundTripper) RoundTrip(r *http.Request) (*http.Response, error) { return s.respond(r) }
-
-func newTestConsumeRuntime(rt http.RoundTripper) *consumeRuntime {
-	sdk := lark.NewClient("test-app", "test-secret",
-		lark.WithEnableTokenCache(false),
-		lark.WithLogLevel(larkcore.LogLevelError),
-		lark.WithHttpClient(&http.Client{Transport: rt}),
-	)
-	return &consumeRuntime{
-		client: &client.APIClient{
-			SDK:        sdk,
-			ErrOut:     io.Discard,
-			Credential: credential.NewCredentialProvider(nil, nil, &staticTokenResolver{}, nil),
-			Config:     &core.CliConfig{AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu},
-		},
-		accessIdentity: core.AsBot,
-	}
-}
-
-func stubResponse(status int, contentType, body string) func(*http.Request) (*http.Response, error) {
-	return func(r *http.Request) (*http.Response, error) {
-		return &http.Response{
-			StatusCode: status,
-			Header:     http.Header{"Content-Type": []string{contentType}},
-			Body:       io.NopCloser(strings.NewReader(body)),
-			Request:    r,
-		}, nil
-	}
-}
-
-func requireCallAPIProblem(t *testing.T, err error, category errs.Category, subtype errs.Subtype) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != category || p.Subtype != subtype {
-		t.Fatalf("problem = %s/%s, want %s/%s", p.Category, p.Subtype, category, subtype)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_NonJSONHTTPError(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusNotFound, "text/plain", "gone")})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	requireCallAPIProblem(t, err, errs.CategoryInternal, errs.SubtypeInvalidResponse)
-	if !strings.Contains(err.Error(), "returned 404") {
-		t.Errorf("error should echo the HTTP status, got: %v", err)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_NonJSONHTTPErrorTruncatesLongBody(t *testing.T) {
-	long := strings.Repeat("x", 300)
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusBadGateway, "text/html", long)})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	requireCallAPIProblem(t, err, errs.CategoryNetwork, errs.SubtypeNetworkServer)
-	p, _ := errs.ProblemOf(err)
-	if !p.Retryable {
-		t.Fatal("5xx non-JSON response should be marked retryable")
-	}
-	if !strings.Contains(err.Error(), "…(truncated)") {
-		t.Errorf("long body should be truncated in the message, got: %v", err)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_UnparsableJSONBody(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusOK, "application/json", "{not json")})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	requireCallAPIProblem(t, err, errs.CategoryInternal, errs.SubtypeInvalidResponse)
-}
-
-func TestConsumeRuntimeCallAPI_TransportFailure(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: func(*http.Request) (*http.Response, error) {
-		return nil, errors.New("connection refused")
-	}})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryNetwork {
-		t.Fatalf("category = %s, want %s", p.Category, errs.CategoryNetwork)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_EnvelopeErrorIsTyped(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusOK, "application/json",
-		`{"code":99991663,"msg":"app not found"}`)})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	if _, ok := errs.ProblemOf(err); !ok {
-		t.Fatalf("envelope error should be typed via BuildAPIError, got %T: %v", err, err)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_Success(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusOK, "application/json",
-		`{"code":0,"data":{"ok":true}}`)})
-	raw, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if !strings.Contains(string(raw), `"code":0`) {
-		t.Errorf("raw body should pass through, got: %s", raw)
-	}
-}

cmd/event/schema.go

@@ -11,7 +11,6 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	eventlib "github.com/larksuite/cli/internal/event"
 	"github.com/larksuite/cli/internal/event/schemas"
@@ -40,14 +39,12 @@ func resolveSchemaJSON(def *eventlib.KeyDefinition) (json.RawMessage, []string,
 	if len(def.Schema.FieldOverrides) > 0 {
 		var parsed map[string]interface{}
 		if err := json.Unmarshal(base, &parsed); err != nil {
-			return nil, nil, errs.NewInternalError(errs.SubtypeUnknown,
-				"parse base schema for field overrides: %s", err).WithCause(err)
+			return nil, nil, err
 		}
 		orphans := schemas.ApplyFieldOverrides(parsed, def.Schema.FieldOverrides)
 		out, err := json.Marshal(parsed)
 		if err != nil {
-			return nil, nil, errs.NewInternalError(errs.SubtypeUnknown,
-				"serialize schema with field overrides: %s", err).WithCause(err)
+			return nil, nil, err
 		}
 		return out, orphans, nil
 	}
@@ -76,7 +73,7 @@ func renderSpec(s *eventlib.SchemaSpec) (json.RawMessage, error) {
 		copy(buf, s.Raw)
 		return buf, nil
 	}
-	return nil, errs.NewInternalError(errs.SubtypeUnknown, "schemaSpec has neither Type nor Raw")
+	return nil, fmt.Errorf("schemaSpec has neither Type nor Raw")
 }
 
 func NewCmdSchema(f *cmdutil.Factory) *cobra.Command {
@@ -168,7 +165,7 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 
 	resolved, _, err := resolveSchemaJSON(def)
 	if err != nil {
-		return err
+		return output.Errorf(output.ExitInternal, "internal", "resolve schema: %v", err)
 	}
 	if resolved != nil {
 		fmt.Fprintf(out, "\nOutput Schema:\n")

cmd/event/schema_test.go

@@ -10,7 +10,6 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	eventlib "github.com/larksuite/cli/internal/event"
@@ -130,38 +129,3 @@ func TestResolveSchemaJSON_CustomWithOverlay(t *testing.T) {
 		t.Errorf("overlay format = %v, want open_id", got)
 	}
 }
-
-func TestRenderSpec_EmptySpecIsTypedInternalError(t *testing.T) {
-	_, err := renderSpec(&eventlib.SchemaSpec{})
-	if err == nil {
-		t.Fatal("expected error for spec with neither Type nor Raw")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryInternal {
-		t.Errorf("category = %s, want %s", p.Category, errs.CategoryInternal)
-	}
-}
-
-func TestResolveSchemaJSON_InvalidBaseWithOverridesIsTypedInternalError(t *testing.T) {
-	def := &eventlib.KeyDefinition{
-		Key: "synthetic.invalid.base",
-		Schema: eventlib.SchemaDef{
-			Custom:         &eventlib.SchemaSpec{Raw: json.RawMessage("{not json")},
-			FieldOverrides: map[string]schemas.FieldMeta{"x": {}},
-		},
-	}
-	_, _, err := resolveSchemaJSON(def)
-	if err == nil {
-		t.Fatal("expected error for unparsable base schema")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryInternal {
-		t.Errorf("category = %s, want %s", p.Category, errs.CategoryInternal)
-	}
-}

cmd/event/suggestions.go

@@ -8,8 +8,8 @@ import (
 	"sort"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	eventlib "github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/suggest"
 )
 
@@ -64,6 +64,9 @@ func unknownEventKeyErr(key string) error {
 	if guesses := suggestEventKeys(key); len(guesses) > 0 {
 		msg += " — did you mean " + formatSuggestions(guesses) + "?"
 	}
-	return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", msg).
-		WithHint("Run 'lark-cli event list' to see available keys.")
+	return output.ErrWithHint(
+		output.ExitValidation, "validation",
+		msg,
+		"Run 'lark-cli event list' to see available keys.",
+	)
 }

events/minutes/preconsume.go

@@ -5,9 +5,9 @@ package minutes
 
 import (
 	"context"
+	"fmt"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/event"
 )
 
@@ -16,8 +16,7 @@ const cleanupTimeout = 5 * time.Second
 func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
 	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) {
 		if rt == nil {
-			return nil, errs.NewInternalError(errs.SubtypeUnknown,
-				"runtime API client is required for pre-consume subscription")
+			return nil, fmt.Errorf("runtime API client is required for pre-consume subscription")
 		}
 
 		body := map[string]string{"event_type": eventType}

events/vc/note_detail_retry_test.go

@@ -1,35 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package vc
-
-import (
-	"errors"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// isLarkCode must match the API code on typed errs.* errors — the consume
-// runtime classifies OAPI failures via errclass.BuildAPIError, so the
-// not-found retry in fillVCNoteGeneratedDetails depends on this reading
-// Problem.Code rather than the legacy envelope shape.
-func TestIsLarkCode_MatchesTypedAPIErrorCode(t *testing.T) {
-	typedNotFound := errs.NewAPIError(errs.SubtypeNotFound, "note not ready").
-		WithCode(vcNoteDetailNotFoundCode)
-	if !isLarkCode(typedNotFound, vcNoteDetailNotFoundCode) {
-		t.Fatal("typed API error carrying the not-found code must match (retry path)")
-	}
-	if isLarkCode(typedNotFound, 99999) {
-		t.Error("a different expected code must not match")
-	}
-
-	otherTyped := errs.NewAPIError(errs.SubtypeServerError, "boom").WithCode(500)
-	if isLarkCode(otherTyped, vcNoteDetailNotFoundCode) {
-		t.Error("typed error with another code must not match")
-	}
-
-	if isLarkCode(errors.New("plain failure"), vcNoteDetailNotFoundCode) {
-		t.Error("untyped error must not match")
-	}
-}

events/vc/note_generated.go

@@ -6,11 +6,12 @@ package vc
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 )
 
@@ -147,8 +148,9 @@ func fillVCNoteGeneratedDetails(ctx context.Context, rt event.APIClient, out *VC
 }
 
 func isLarkCode(err error, code int) bool {
-	if p, ok := errs.ProblemOf(err); ok {
-		return p.Code == code
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) && exitErr.Detail != nil {
+		return exitErr.Detail.Code == code
 	}
 	return false
 }

events/vc/preconsume.go

@@ -5,9 +5,9 @@ package vc
 
 import (
 	"context"
+	"fmt"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/event"
 )
 
@@ -16,8 +16,7 @@ const cleanupTimeout = 5 * time.Second
 func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
 	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) {
 		if rt == nil {
-			return nil, errs.NewInternalError(errs.SubtypeUnknown,
-				"runtime API client is required for pre-consume subscription")
+			return nil, fmt.Errorf("runtime API client is required for pre-consume subscription")
 		}
 
 		body := map[string]string{"event_type": eventType}

events/whiteboard/preconsume.go

@@ -8,7 +8,6 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/event"
 	"github.com/larksuite/cli/internal/validate"
 )
@@ -25,15 +24,11 @@ const cleanupTimeout = 5 * time.Second
 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, errs.NewInternalError(errs.SubtypeUnknown,
-				"runtime API client is required for pre-consume subscription")
+			return nil, fmt.Errorf("runtime API client is required for pre-consume subscription")
 		}
 		whiteboardID := params["whiteboard_id"]
 		if whiteboardID == "" {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"param whiteboard_id is required for %s", eventType).
-				WithParam("--param").
-				WithHint("pass it as --param whiteboard_id=<id>; run `lark-cli event schema %s` for details", eventType)
+			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)

events/whiteboard/preconsume_test.go

@@ -11,7 +11,6 @@ import (
 	"sync"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/event"
 )
 
@@ -59,16 +58,6 @@ func TestWhiteboardSubscriptionPreConsume_MissingWhiteboardID(t *testing.T) {
 	if !strings.Contains(err.Error(), "whiteboard_id") {
 		t.Fatalf("error should mention whiteboard_id, got: %v", err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument || ve.Param != "--param" {
-		t.Errorf("subtype/param = %s/%q, want %s/%q", ve.Subtype, ve.Param, errs.SubtypeInvalidArgument, "--param")
-	}
-	if ve.Hint == "" {
-		t.Error("missing whiteboard_id should carry a hint")
-	}
 }
 
 // TestWhiteboardSubscriptionPreConsume_NilRuntime verifies that PreConsume
@@ -81,9 +70,6 @@ func TestWhiteboardSubscriptionPreConsume_NilRuntime(t *testing.T) {
 	if err == nil {
 		t.Fatalf("expected error when runtime client is nil")
 	}
-	if p, ok := errs.ProblemOf(err); !ok || p.Category != errs.CategoryInternal {
-		t.Errorf("nil-runtime invariant should be a typed internal error, got %T: %v", err, err)
-	}
 }
 
 // TestWhiteboardSubscriptionPreConsume_SubscribeError verifies that a

internal/event/consume/consume.go

@@ -14,7 +14,6 @@ import (
 	"sync/atomic"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/event"
 	"github.com/larksuite/cli/internal/event/transport"
 )
@@ -45,9 +44,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 
 	keyDef, ok := event.Lookup(opts.EventKey)
 	if !ok {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"unknown EventKey: %s", opts.EventKey).
-			WithHint("run `lark-cli event list` to see available keys")
+		return fmt.Errorf("unknown EventKey: %s\nRun 'lark-cli event list' to see available keys", opts.EventKey)
 	}
 
 	if err := validateParams(keyDef, opts.Params); err != nil {
@@ -83,8 +80,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 
 	ack, br, err := doHello(conn, opts.EventKey, []string{keyDef.EventType})
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeUnknown,
-			"event bus handshake failed: %s", err).WithCause(err)
+		return fmt.Errorf("handshake failed: %w", err)
 	}
 
 	var cleanup func()
@@ -94,11 +90,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 		}
 		cleanup, err = keyDef.PreConsume(ctx, opts.Runtime, opts.Params)
 		if err != nil {
-			if _, ok := errs.ProblemOf(err); ok {
-				return err
-			}
-			return errs.NewInternalError(errs.SubtypeUnknown,
-				"pre-consume failed: %s", err).WithCause(err)
+			return fmt.Errorf("pre-consume failed: %w", err)
 		}
 	}
 
@@ -138,7 +130,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 	if !opts.Quiet {
 		fmt.Fprintln(errOut, listeningText(opts))
 		if !opts.IsTTY {
-			fmt.Fprintln(errOut, stopHintText(opts))
+			fmt.Fprintln(errOut, stopHintText())
 		}
 	}
 
@@ -160,10 +152,8 @@ func validateParams(def *event.KeyDefinition, params map[string]string) error {
 	for _, p := range def.Params {
 		if p.Required {
 			if _, ok := params[p.Name]; !ok {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"required param %q missing for EventKey %s", p.Name, def.Key).
-					WithParam("--param").
-					WithHint("pass it as --param %s=<value>; run `lark-cli event schema %s` for details", p.Name, def.Key)
+				return fmt.Errorf("required param %q missing for EventKey %s. Run 'lark-cli event schema %s' for details",
+					p.Name, def.Key, def.Key)
 			}
 		}
 	}
@@ -179,15 +169,11 @@ func validateParams(def *event.KeyDefinition, params map[string]string) error {
 			continue
 		}
 		if len(validNames) == 0 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"unknown param %q: EventKey %s accepts no params", k, def.Key).
-				WithParam("--param").
-				WithHint("run `lark-cli event schema %s` for details", def.Key)
+			return fmt.Errorf("unknown param %q: EventKey %s accepts no params. Run 'lark-cli event schema %s' for details",
+				k, def.Key, def.Key)
 		}
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"unknown param %q for EventKey %s. valid params: %s", k, def.Key, strings.Join(validNames, ", ")).
-			WithParam("--param").
-			WithHint("run `lark-cli event schema %s` for details", def.Key)
+		return fmt.Errorf("unknown param %q for EventKey %s. valid params: %s. Run 'lark-cli event schema %s' for details",
+			k, def.Key, strings.Join(validNames, ", "), def.Key)
 	}
 	return nil
 }
@@ -227,11 +213,7 @@ func exitReason(ctx context.Context, emitted int64, opts Options) string {
 	return "signal"
 }
 
-func stopHintText(opts Options) string {
-	if opts.MaxEvents > 0 || opts.Timeout > 0 {
-		return "[event] to stop gracefully: send SIGTERM (kill <pid>). " +
-			"Avoid kill -9 — it skips cleanup and may leak server-side subscriptions."
-	}
+func stopHintText() string {
 	return "[event] to stop gracefully: send SIGTERM (kill <pid>) or close stdin. " +
 		"Avoid kill -9 — it skips cleanup and may leak server-side subscriptions."
 }

internal/event/consume/jq.go

@@ -8,21 +8,17 @@ import (
 	"fmt"
 
 	"github.com/itchyny/gojq"
-
-	"github.com/larksuite/cli/errs"
 )
 
 // CompileJQ compiles once for hot-path reuse; exported so callers can preflight before side effects.
 func CompileJQ(expr string) (*gojq.Code, error) {
 	query, err := gojq.Parse(expr)
 	if err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"invalid jq expression: %s", err).WithParam("--jq").WithCause(err)
+		return nil, fmt.Errorf("invalid jq expression: %w", err)
 	}
 	code, err := gojq.Compile(query)
 	if err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"jq compile error: %s", err).WithParam("--jq").WithCause(err)
+		return nil, fmt.Errorf("jq compile error: %w", err)
 	}
 	return code, nil
 }

internal/event/consume/listening_text_test.go

@@ -50,32 +50,12 @@ func TestListeningText_NonTTY_MaxEventsAndTimeout(t *testing.T) {
 }
 
 // AI-facing contract: must name "kill -9" + "cleanup" so agents parsing stderr are steered away from SIGKILL.
-func TestStopHintText_Unbounded(t *testing.T) {
-	got := stopHintText(Options{})
-	mustContain := []string{"SIGTERM", "kill -9", "cleanup", "close stdin"}
+func TestStopHintText_Content(t *testing.T) {
+	got := stopHintText()
+	mustContain := []string{"SIGTERM", "kill -9", "cleanup"}
 	for _, s := range mustContain {
 		if !bytes.Contains([]byte(got), []byte(s)) {
-			t.Errorf("stopHintText(unbounded) missing %q; got %q", s, got)
-		}
-	}
-}
-
-// AI-facing contract: must name "kill -9" + "cleanup" so agents parsing stderr are steered away from SIGKILL.
-func TestStopHintText_Bounded(t *testing.T) {
-	cases := []Options{
-		{MaxEvents: 1},
-		{Timeout: 30 * time.Second},
-	}
-	for _, opts := range cases {
-		got := stopHintText(opts)
-		mustContain := []string{"SIGTERM", "kill -9", "cleanup"}
-		for _, s := range mustContain {
-			if !bytes.Contains([]byte(got), []byte(s)) {
-				t.Errorf("stopHintText(bounded) missing %q; got %q", s, got)
-			}
-		}
-		if bytes.Contains([]byte(got), []byte("close stdin")) {
-			t.Errorf("stopHintText(bounded) must not contain \"close stdin\"; got %q", got)
+			t.Errorf("stopHintText missing %q; got %q", s, got)
 		}
 	}
 }

internal/event/consume/loop_jq_test.go

@@ -5,13 +5,10 @@ package consume
 
 import (
 	"encoding/json"
-	"errors"
 	"fmt"
 	"strings"
 	"sync"
 	"testing"
-
-	"github.com/larksuite/cli/errs"
 )
 
 func TestCompileJQReportsErrorEarly(t *testing.T) {
@@ -23,16 +20,6 @@ func TestCompileJQReportsErrorEarly(t *testing.T) {
 	if !strings.Contains(msg, "compile") && !strings.Contains(msg, "parse") && !strings.Contains(msg, "invalid") {
 		t.Errorf("error should mention compile/parse/invalid, got: %v", err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument || ve.Param != "--jq" {
-		t.Errorf("subtype/param = %s/%q, want %s/%q", ve.Subtype, ve.Param, errs.SubtypeInvalidArgument, "--jq")
-	}
-	if errors.Unwrap(err) == nil {
-		t.Error("compile error should preserve its cause")
-	}
 }
 
 func TestCompileJQReturnsUsableCode(t *testing.T) {

internal/event/consume/sink.go

@@ -13,7 +13,6 @@ import (
 	"sync/atomic"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -24,8 +23,7 @@ type Sink interface {
 func newSink(opts Options) (Sink, error) {
 	if opts.OutputDir != "" {
 		if err := vfs.MkdirAll(opts.OutputDir, 0755); err != nil {
-			return nil, errs.NewInternalError(errs.SubtypeFileIO,
-				"create output dir: %s", err).WithCause(err)
+			return nil, fmt.Errorf("create output dir: %w", err)
 		}
 		// PID disambiguates filenames across processes sharing a Dir.
 		return &DirSink{Dir: opts.OutputDir, pid: os.Getpid()}, nil

internal/event/consume/startup.go

@@ -16,7 +16,6 @@ import (
 	"path/filepath"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/event"
 	"github.com/larksuite/cli/internal/event/protocol"
@@ -52,9 +51,10 @@ func EnsureBus(ctx context.Context, tr transport.IPC, appID, profileName, domain
 		} else {
 			fmt.Fprintf(errOut, "[event] remote connection check: online_instance_cnt=%d\n", count)
 			if count > 0 {
-				return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition,
-					"another event bus is already connected to this app (%d active connection(s) detected via API); only one bus should run globally to avoid duplicate event delivery", count).
-					WithHint("use `lark-cli event status` to check, or `lark-cli event stop` on the other machine first")
+				return nil, fmt.Errorf("another event bus is already connected to this app "+
+					"(%d active connection(s) detected via API).\n"+
+					"Only one bus should run globally to avoid duplicate event delivery.\n"+
+					"Use 'lark-cli event status' to check, or 'lark-cli event stop' on the other machine first", count)
 			}
 		}
 	} else {
@@ -65,10 +65,8 @@ func EnsureBus(ctx context.Context, tr transport.IPC, appID, profileName, domain
 	pid, forkErr := forkBus(tr, appID, profileName, domain)
 	if forkErr != nil && !errors.Is(forkErr, lockfile.ErrHeld) {
 		eventsRoot := filepath.Join(core.GetConfigDir(), "events")
-		return nil, errs.NewInternalError(errs.SubtypeUnknown,
-			"failed to start event bus daemon: %s", forkErr).
-			WithCause(forkErr).
-			WithHint("check disk space, permissions on %s, and `lark-cli doctor`", eventsRoot)
+		return nil, fmt.Errorf("failed to start event bus daemon: %w\n"+
+			"Check: disk space, permissions on %s, and 'lark-cli doctor'", forkErr, eventsRoot)
 	}
 	if pid > 0 {
 		announceForkedBus(errOut, pid)
@@ -90,9 +88,7 @@ func EnsureBus(ctx context.Context, tr transport.IPC, appID, profileName, domain
 	fmt.Fprintln(errOut, "[event] event bus exited unexpectedly.")
 	fmt.Fprintln(errOut, "[event] please check app credentials (lark-cli config show) and retry.")
 	fmt.Fprintf(errOut, "[event] logs: %s\n", logPath)
-	return nil, errs.NewInternalError(errs.SubtypeUnknown,
-		"failed to connect to event bus within %v (app=%s)", dialTimeout, appID).
-		WithHint("check app credentials (`lark-cli config show`) and retry; bus logs: %s", logPath)
+	return nil, fmt.Errorf("failed to connect to event bus within %v (app=%s)", dialTimeout, appID)
 }
 
 // probeAndDialBus distinguishes a healthy bus from a mid-shutdown listener via StatusQuery first.

internal/event/consume/startup_guard_test.go

@@ -1,99 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package consume
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"io"
-	"net"
-	"strconv"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/event"
-)
-
-// failDialTransport refuses every dial so EnsureBus falls through to the
-// remote-connection check without a local bus.
-type failDialTransport struct{}
-
-func (failDialTransport) Listen(string) (net.Listener, error) { return nil, errors.New("no listen") }
-func (failDialTransport) Dial(string) (net.Conn, error)       { return nil, errors.New("refused") }
-func (failDialTransport) Address(string) string               { return "guard-test-addr" }
-func (failDialTransport) Cleanup(string)                      {}
-
-// remoteBusyAPIClient reports active remote WebSocket connections.
-type remoteBusyAPIClient struct{ count int }
-
-func (c remoteBusyAPIClient) CallAPI(context.Context, string, string, interface{}) (json.RawMessage, error) {
-	return json.RawMessage(`{"code":0,"msg":"ok","data":{"online_instance_cnt":` +
-		strconv.Itoa(c.count) + `}}`), nil
-}
-
-func TestEnsureBus_RemoteBusAlreadyConnectedIsFailedPrecondition(t *testing.T) {
-	conn, err := EnsureBus(context.Background(), failDialTransport{},
-		"cli_guard_test", "", "", remoteBusyAPIClient{count: 2}, io.Discard)
-	if conn != nil {
-		t.Fatal("expected nil conn when a remote bus is already connected")
-	}
-	if err == nil {
-		t.Fatal("expected single-bus guard error")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("subtype = %s, want %s", ve.Subtype, errs.SubtypeFailedPrecondition)
-	}
-	if !strings.Contains(ve.Hint, "event stop") {
-		t.Errorf("hint should point at `event stop`, got: %q", ve.Hint)
-	}
-}
-
-func TestRun_UnknownEventKeyIsTypedValidation(t *testing.T) {
-	err := Run(context.Background(), failDialTransport{}, "cli_x", "", "", Options{
-		EventKey: "bogus.run.key",
-		ErrOut:   io.Discard,
-	})
-	if err == nil {
-		t.Fatal("expected unknown EventKey error")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype = %s, want %s", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if !strings.Contains(ve.Hint, "event list") {
-		t.Errorf("hint should point at `event list`, got: %q", ve.Hint)
-	}
-}
-
-func TestRun_InvalidJQFailsBeforeAnySideEffect(t *testing.T) {
-	event.RegisterKey(event.KeyDefinition{
-		Key:       "consume.runtest.jq",
-		EventType: "consume.runtest.jq_v1",
-		Schema:    event.SchemaDef{Custom: &event.SchemaSpec{Raw: json.RawMessage(`{}`)}},
-	})
-	err := Run(context.Background(), failDialTransport{}, "cli_x", "", "", Options{
-		EventKey: "consume.runtest.jq",
-		JQExpr:   "[invalid{{{",
-		ErrOut:   io.Discard,
-	})
-	if err == nil {
-		t.Fatal("expected jq validation error")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Param != "--jq" {
-		t.Errorf("param = %q, want %q", ve.Param, "--jq")
-	}
-}

internal/event/consume/validate_params_test.go

@@ -1,64 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package consume
-
-import (
-	"errors"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/event"
-)
-
-func requireParamValidationError(t *testing.T, err error) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected validation error, got nil")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument || ve.Param != "--param" {
-		t.Errorf("subtype/param = %s/%q, want %s/%q", ve.Subtype, ve.Param, errs.SubtypeInvalidArgument, "--param")
-	}
-	if ve.Hint == "" {
-		t.Error("param validation error should hint at `lark-cli event schema`")
-	}
-}
-
-func TestValidateParams_RequiredMissing(t *testing.T) {
-	def := &event.KeyDefinition{
-		Key:    "x.test",
-		Params: []event.ParamDef{{Name: "chat_id", Required: true}},
-	}
-	requireParamValidationError(t, validateParams(def, map[string]string{}))
-}
-
-func TestValidateParams_UnknownParam(t *testing.T) {
-	def := &event.KeyDefinition{
-		Key:    "x.test",
-		Params: []event.ParamDef{{Name: "chat_id"}},
-	}
-	requireParamValidationError(t, validateParams(def, map[string]string{"nope": "1"}))
-}
-
-func TestValidateParams_UnknownParamNoParamsAccepted(t *testing.T) {
-	def := &event.KeyDefinition{Key: "x.test"}
-	requireParamValidationError(t, validateParams(def, map[string]string{"nope": "1"}))
-}
-
-func TestValidateParams_DefaultAppliedAndValidPasses(t *testing.T) {
-	def := &event.KeyDefinition{
-		Key:    "x.test",
-		Params: []event.ParamDef{{Name: "mode", Required: true, Default: "all"}},
-	}
-	params := map[string]string{}
-	if err := validateParams(def, params); err != nil {
-		t.Fatalf("default should satisfy required param, got: %v", err)
-	}
-	if params["mode"] != "all" {
-		t.Errorf("default not applied, params=%v", params)
-	}
-}

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -15,15 +15,9 @@ import (
 // legacy validation/save helpers are forbidden; callers must use the typed
 // common replacements or construct an errs.* typed error directly.
 var migratedCommonHelperPaths = []string{
-	"cmd/event/",
-	"events/",
-	"internal/event/consume/",
 	"shortcuts/base/",
 	"shortcuts/calendar/",
-	"shortcuts/contact/",
-	"shortcuts/doc/",
 	"shortcuts/drive/",
-	"shortcuts/event/",
 	"shortcuts/mail/",
 	"shortcuts/minutes/",
 	"shortcuts/okr/",

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -16,15 +16,9 @@ import (
 // call sites must return a typed errs.* error instead. Future domains opt in by
 // appending their path prefix here.
 var migratedEnvelopePaths = []string{
-	"cmd/event/",
-	"events/",
-	"internal/event/consume/",
 	"shortcuts/base/",
 	"shortcuts/calendar/",
-	"shortcuts/contact/",
-	"shortcuts/doc/",
 	"shortcuts/drive/",
-	"shortcuts/event/",
 	"shortcuts/mail/",
 	"shortcuts/minutes/",
 	"shortcuts/okr/",

lint/errscontract/rule_no_legacy_runtime_api_call.go

@@ -27,11 +27,6 @@ import (
 // is not matched. runtime.DoAPI / runtime.RawAPI are intentionally not listed:
 // they return the raw response for the caller to classify and do not emit a
 // legacy envelope themselves.
-//
-// Files that do not import shortcuts/common are skipped: the legacy helpers
-// are methods on common.RuntimeContext, so a same-named method on another
-// receiver (for example the event domain's APIClient interface, whose
-// implementation classifies into typed errs.* errors) is not a legacy call.
 func CheckNoLegacyRuntimeAPICall(path, src string) []Violation {
 	if !isMigratedEnvelopePath(path) || strings.HasSuffix(path, "_test.go") {
 		return nil
@@ -41,9 +36,6 @@ func CheckNoLegacyRuntimeAPICall(path, src string) []Violation {
 	if err != nil {
 		return nil
 	}
-	if !importsPath(file, commonImportPath) {
-		return nil
-	}
 	var out []Violation
 	ast.Inspect(file, func(n ast.Node) bool {
 		call, ok := n.(*ast.CallExpr)
@@ -79,16 +71,3 @@ func matchLegacyRuntimeAPIMethod(name string) (string, bool) {
 	}
 	return "", false
 }
-
-// importsPath reports whether the file imports the given package path.
-func importsPath(file *ast.File, importPath string) bool {
-	for _, imp := range file.Imports {
-		if imp.Path == nil {
-			continue
-		}
-		if strings.Trim(imp.Path.Value, "`\"") == importPath {
-			return true
-		}
-	}
-	return false
-}

lint/errscontract/rules_test.go

@@ -691,7 +691,7 @@ func boom() error {
 	return &output.ExitError{Code: 1}
 }
 `
-	v := CheckNoLegacyEnvelopeLiteral("shortcuts/unmigrated/foo.go", src)
+	v := CheckNoLegacyEnvelopeLiteral("shortcuts/contact/foo.go", src)
 	if len(v) != 0 {
 		t.Errorf("non-migrated path should pass, got: %+v", v)
 	}
@@ -813,8 +813,6 @@ func boom() error {
 func TestCheckNoLegacyRuntimeAPICall_RejectsCallAPIOnDrivePath(t *testing.T) {
 	src := `package drive
 
-import "github.com/larksuite/cli/shortcuts/common"
-
 func boom(runtime *common.RuntimeContext) error {
 	_, err := runtime.CallAPI("POST", "/x", nil, nil)
 	return err
@@ -835,8 +833,6 @@ func boom(runtime *common.RuntimeContext) error {
 func TestCheckNoLegacyRuntimeAPICall_RejectsCallAPIOnTaskPath(t *testing.T) {
 	src := `package task
 
-import "github.com/larksuite/cli/shortcuts/common"
-
 func boom(runtime *common.RuntimeContext) error {
 	_, err := runtime.CallAPI("POST", "/x", nil, nil)
 	return err
@@ -857,8 +853,6 @@ func boom(runtime *common.RuntimeContext) error {
 func TestCheckNoLegacyRuntimeAPICall_RejectsDoAPIJSONWithLogIDOnDrivePath(t *testing.T) {
 	src := `package drive
 
-import "github.com/larksuite/cli/shortcuts/common"
-
 func boom(runtime *common.RuntimeContext) error {
 	_, err := runtime.DoAPIJSONWithLogID("POST", "/x", nil, nil)
 	return err
@@ -913,7 +907,7 @@ func boom(runtime *common.RuntimeContext) error {
 	return err
 }
 `
-	v := CheckNoLegacyRuntimeAPICall("shortcuts/unmigrated/sample.go", src)
+	v := CheckNoLegacyRuntimeAPICall("shortcuts/contact/contact_get.go", src)
 	if len(v) != 0 {
 		t.Errorf("non-migrated path must not fire, got: %+v", v)
 	}
@@ -950,7 +944,6 @@ func TestCheckNoLegacyCommonHelperCall_RejectsLegacyHelpersOnMigratedPath(t *tes
 		"HandleApiResult",
 	}
 	paths := []string{
-		"shortcuts/doc/docs_fetch_v2.go",
 		"shortcuts/drive/drive_search.go",
 		"shortcuts/mail/mail_send.go",
 		"shortcuts/okr/okr_progress_create.go",
@@ -1004,23 +997,6 @@ func boom() {
 	}
 }
 
-func TestCheckNoLegacyCommonHelperCall_CoversDocPathWithAliasAndFunctionValue(t *testing.T) {
-	src := `package migrated
-
-import c "github.com/larksuite/cli/shortcuts/common"
-
-func boom() {
-	f := c.FlagErrorf
-	_ = f
-	c.WrapInputStatError(nil)
-}
-`
-	v := CheckNoLegacyCommonHelperCall("shortcuts/doc/docs_fetch_v2.go", src)
-	if len(v) != 2 {
-		t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on doc path, got %d: %+v", len(v), v)
-	}
-}
-
 func TestCheckNoLegacyCommonHelperCall_AllowsNonMigratedPath(t *testing.T) {
 	src := `package contact
 
@@ -1030,7 +1006,7 @@ func boom() {
 	common.FlagErrorf("legacy allowed until domain migrates")
 }
 `
-	v := CheckNoLegacyCommonHelperCall("shortcuts/unmigrated/sample.go", src)
+	v := CheckNoLegacyCommonHelperCall("shortcuts/contact/contact_get.go", src)
 	if len(v) != 0 {
 		t.Errorf("non-migrated path must pass, got: %+v", v)
 	}
@@ -1100,23 +1076,3 @@ func boom() error {
 		t.Fatalf("expected 1 violation for function-value reference, got %d: %+v", len(v), v)
 	}
 }
-
-func TestCheckNoLegacyRuntimeAPICall_SkipsNonCommonReceiver(t *testing.T) {
-	// The event domain's APIClient interface has a same-named CallAPI method
-	// whose implementation classifies into typed errs.* errors; without the
-	// shortcuts/common import the call cannot be the legacy RuntimeContext
-	// helper and must not fire.
-	src := `package vc
-
-import "github.com/larksuite/cli/internal/event"
-
-func boom(rt event.APIClient) error {
-	_, err := rt.CallAPI(nil, "POST", "/x", nil)
-	return err
-}
-`
-	v := CheckNoLegacyRuntimeAPICall("events/vc/preconsume.go", src)
-	if len(v) != 0 {
-		t.Errorf("non-common CallAPI receiver must not fire, got: %+v", v)
-	}
-}

package.json

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

shortcuts/common/userids.go

@@ -6,8 +6,24 @@ package common
 import (
 	"fmt"
 	"strings"
+
+	"github.com/larksuite/cli/internal/output"
 )
 
+// ResolveOpenIDs expands the special identifier "me" to the current user's
+// open_id, removes duplicates case-insensitively while preserving the
+// first-occurrence form, and returns nil for an empty input. flagName is
+// used in error messages to point the user at the offending CLI flag.
+//
+// Deprecated: use ResolveOpenIDsTyped for typed error envelopes.
+func ResolveOpenIDs(flagName string, ids []string, runtime *RuntimeContext) ([]string, error) {
+	out, msg := resolveOpenIDs(flagName, ids, runtime)
+	if msg != "" {
+		return nil, output.ErrValidation("%s", msg)
+	}
+	return out, nil
+}
+
 // ResolveOpenIDsTyped expands the special identifier "me" to the current
 // user's open_id, removes duplicates case-insensitively while preserving the
 // first-occurrence form, and returns nil for an empty input. flagName names

shortcuts/common/userids_test.go

@@ -17,9 +17,9 @@ func resolveOpenIDsTestRuntime(userOpenID string) *RuntimeContext {
 	return TestNewRuntimeContext(cmd, cfg)
 }
 
-func TestResolveOpenIDsTyped_Empty(t *testing.T) {
+func TestResolveOpenIDs_Empty(t *testing.T) {
 	rt := resolveOpenIDsTestRuntime("ou_self")
-	out, err := ResolveOpenIDsTyped("--user-ids", nil, rt)
+	out, err := ResolveOpenIDs("--user-ids", nil, rt)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -28,9 +28,21 @@ func TestResolveOpenIDsTyped_Empty(t *testing.T) {
 	}
 }
 
-func TestResolveOpenIDsTyped_MeIsCaseInsensitive(t *testing.T) {
+func TestResolveOpenIDs_ExpandsMeAndDedups(t *testing.T) {
 	rt := resolveOpenIDsTestRuntime("ou_self")
-	out, err := ResolveOpenIDsTyped("--user-ids", []string{"ou_other", "me", "Me", "ME"}, rt)
+	out, err := ResolveOpenIDs("--user-ids", []string{"me", "ou_a", "me", "ou_a"}, rt)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	want := []string{"ou_self", "ou_a"}
+	if len(out) != len(want) || out[0] != want[0] || out[1] != want[1] {
+		t.Fatalf("got %v, want %v", out, want)
+	}
+}
+
+func TestResolveOpenIDs_MeIsCaseInsensitive(t *testing.T) {
+	rt := resolveOpenIDsTestRuntime("ou_self")
+	out, err := ResolveOpenIDs("--user-ids", []string{"ou_other", "me", "Me", "ME"}, rt)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -40,11 +52,22 @@ func TestResolveOpenIDsTyped_MeIsCaseInsensitive(t *testing.T) {
 	}
 }
 
-func TestResolveOpenIDsTyped_DedupIsCaseInsensitive(t *testing.T) {
+func TestResolveOpenIDs_MeWithoutLogin(t *testing.T) {
+	rt := resolveOpenIDsTestRuntime("")
+	_, err := ResolveOpenIDs("--user-ids", []string{"me"}, rt)
+	if err == nil {
+		t.Fatal("expected validation error")
+	}
+	if !strings.Contains(err.Error(), "--user-ids") {
+		t.Fatalf("error should mention the offending flag name; got: %v", err)
+	}
+}
+
+func TestResolveOpenIDs_DedupIsCaseInsensitive(t *testing.T) {
 	rt := resolveOpenIDsTestRuntime("ou_self")
 	// Same underlying open_id with three case variants — should collapse to
 	// one entry, preserving the first-occurrence form.
-	out, err := ResolveOpenIDsTyped("--user-ids", []string{"ou_abc123", "OU_ABC123", "Ou_Abc123"}, rt)
+	out, err := ResolveOpenIDs("--user-ids", []string{"ou_abc123", "OU_ABC123", "Ou_Abc123"}, rt)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}

shortcuts/common/validate_ids.go

@@ -5,6 +5,8 @@ package common
 
 import (
 	"strings"
+
+	"github.com/larksuite/cli/internal/output"
 )
 
 // ValidateChatIDTyped checks if a chat ID has valid format (oc_ prefix).
@@ -40,6 +42,17 @@ func normalizeChatID(input string) (string, string) {
 	return input, ""
 }
 
+// ValidateUserID checks if a user ID has valid format (ou_ prefix).
+//
+// Deprecated: use ValidateUserIDTyped for typed error envelopes.
+func ValidateUserID(input string) (string, error) {
+	userID, msg := normalizeUserID(input)
+	if msg != "" {
+		return "", output.ErrValidation("%s", msg)
+	}
+	return userID, nil
+}
+
 // ValidateUserIDTyped checks if a user ID has valid format (ou_ prefix).
 // param names the flag being validated (e.g. "--creator-ids") and is
 // recorded on the typed error.

shortcuts/contact/contact_errors.go

@@ -1,78 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package contact
-
-import (
-	"errors"
-	"fmt"
-	"net/http"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-)
-
-const contactFanoutRetryHint = "retry the command; if it persists, narrow --queries to a single term to isolate the failing input"
-
-func contactInvalidResponseError(format string, args ...any) *errs.InternalError {
-	return errs.NewInternalError(errs.SubtypeInvalidResponse, format, args...)
-}
-
-func contactFanoutErrorSummary(err error) string {
-	if p, ok := errs.ProblemOf(err); ok {
-		if p.Code >= 100 && p.Code < 600 {
-			prefix := fmt.Sprintf("HTTP %d:", p.Code)
-			body := strings.TrimSpace(strings.TrimPrefix(p.Message, prefix))
-			msg := fmt.Sprintf("HTTP %d %s", p.Code, http.StatusText(p.Code))
-			if body != "" {
-				msg = fmt.Sprintf("%s: %s", msg, contactTruncateError(body, 200))
-			}
-			return msg
-		}
-		if p.Code != 0 {
-			return fmt.Sprintf("API %d: %s", p.Code, p.Message)
-		}
-		return p.Message
-	}
-	return err.Error()
-}
-
-// contactFanoutAllFailedError builds the top-level error returned when every
-// fanout query fails. It mirrors the representative (first) failure's
-// classification — category, subtype, code, log_id, retryable, hint — so the
-// exit-code classifier still sees the real signal, while carrying the aggregate
-// message. The representative error is copied (never mutated) and kept as the
-// cause, so a single-query problem object is not rewritten into an aggregate one.
-func contactFanoutAllFailedError(err error, msg string) error {
-	var (
-		apiErr *errs.APIError
-		netErr *errs.NetworkError
-		intErr *errs.InternalError
-	)
-	switch {
-	case errors.As(err, &apiErr):
-		c := *apiErr
-		c.Message = msg
-		c.Cause = err
-		return &c
-	case errors.As(err, &netErr):
-		c := *netErr
-		c.Message = msg
-		c.Cause = err
-		return &c
-	case errors.As(err, &intErr):
-		c := *intErr
-		c.Message = msg
-		c.Cause = err
-		return &c
-	}
-	return errs.NewInternalError(errs.SubtypeUnknown, "%s", msg).WithHint(contactFanoutRetryHint).WithCause(err)
-}
-
-func contactTruncateError(s string, maxRunes int) string {
-	r := []rune(s)
-	if len(r) <= maxRunes {
-		return s
-	}
-	return string(r[:maxRunes]) + "..."
-}

shortcuts/contact/contact_errors_test.go

@@ -1,81 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package contact
-
-import (
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-func TestContactFanoutErrorSummary_HTTPStatus(t *testing.T) {
-	err := errs.NewNetworkError(errs.SubtypeNetworkServer, `HTTP 503: {"reason":"upstream_unavailable"}`).
-		WithCode(503).
-		WithRetryable()
-
-	got := contactFanoutErrorSummary(err)
-	if !strings.HasPrefix(got, "HTTP 503 Service Unavailable: ") {
-		t.Fatalf("summary: got %q", got)
-	}
-	if !strings.Contains(got, "upstream_unavailable") {
-		t.Fatalf("summary should include truncated body details, got %q", got)
-	}
-}
-
-func TestContactInvalidResponseError_TypedInternal(t *testing.T) {
-	got := contactInvalidResponseError("decode contact response failed")
-	p, ok := errs.ProblemOf(got)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T", got)
-	}
-	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
-		t.Fatalf("problem type: got %s/%s", p.Category, p.Subtype)
-	}
-}
-
-func TestContactFanoutAllFailedError_PreservesTypedProblem(t *testing.T) {
-	err := errs.NewAPIError(errs.SubtypeRateLimit, "rate limit").
-		WithCode(99991663).
-		WithLogID("log-contact-1").
-		WithRetryable()
-
-	got := contactFanoutAllFailedError(err, "all 2 queries failed; first: API 99991663: rate limit (query=\"alice\")")
-	p, ok := errs.ProblemOf(got)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T", got)
-	}
-	if p.Category != errs.CategoryAPI || p.Subtype != errs.SubtypeRateLimit {
-		t.Fatalf("problem type: got %s/%s", p.Category, p.Subtype)
-	}
-	if p.Code != 99991663 || p.LogID != "log-contact-1" || !p.Retryable {
-		t.Fatalf("problem metadata not preserved: %+v", p)
-	}
-	if !strings.Contains(p.Message, "all 2 queries failed") {
-		t.Fatalf("problem message not decorated: %q", p.Message)
-	}
-	// The representative error must not be mutated: it stays a single-query
-	// failure, while the aggregate is a distinct value carrying it as cause.
-	if err.Message != "rate limit" {
-		t.Fatalf("representative error message was mutated: %q", err.Message)
-	}
-	if !errors.Is(got, err) {
-		t.Fatalf("aggregate error should keep the representative failure as its cause")
-	}
-}
-
-func TestContactFanoutAllFailedError_UntypedGetsActionableHint(t *testing.T) {
-	got := contactFanoutAllFailedError(nil, "all 2 queries failed; first: internal error (query=\"alice\")")
-	p, ok := errs.ProblemOf(got)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T", got)
-	}
-	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeUnknown {
-		t.Fatalf("problem type: got %s/%s", p.Category, p.Subtype)
-	}
-	if !strings.Contains(p.Hint, "narrow --queries") {
-		t.Fatalf("hint should guide recovery, got %q", p.Hint)
-	}
-}

shortcuts/contact/contact_get_user.go

@@ -28,8 +28,7 @@ var ContactGetUser = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if runtime.Str("user-id") == "" && runtime.IsBot() {
-			return common.ValidationErrorf("bot identity cannot get current user info, specify --user-id").
-				WithParam("--user-id")
+			return common.FlagErrorf("bot identity cannot get current user info, specify --user-id")
 		}
 		return nil
 	},
@@ -64,7 +63,7 @@ var ContactGetUser = common.Shortcut{
 
 		if userId == "" {
 			// Current user
-			data, err := runtime.CallAPITyped("GET", "/open-apis/authen/v1/user_info", nil, nil)
+			data, err := runtime.CallAPI("GET", "/open-apis/authen/v1/user_info", nil, nil)
 			if err != nil {
 				return err
 			}
@@ -88,7 +87,7 @@ var ContactGetUser = common.Shortcut{
 
 		if runtime.IsBot() {
 			// Bot identity: GET /contact/v3/users/:user_id (full profile)
-			data, err := runtime.CallAPITyped("GET", "/open-apis/contact/v3/users/"+url.PathEscape(userId),
+			data, err := runtime.CallAPI("GET", "/open-apis/contact/v3/users/"+url.PathEscape(userId),
 				map[string]interface{}{"user_id_type": userIdType}, nil)
 			if err != nil {
 				return err
@@ -111,7 +110,7 @@ var ContactGetUser = common.Shortcut{
 		}
 
 		// User identity: POST /contact/v3/users/basic_batch (lightweight)
-		data, err := runtime.CallAPITyped("POST", "/open-apis/contact/v3/users/basic_batch",
+		data, err := runtime.CallAPI("POST", "/open-apis/contact/v3/users/basic_batch",
 			map[string]interface{}{"user_id_type": userIdType},
 			map[string]interface{}{"user_ids": []string{userId}})
 		if err != nil {

shortcuts/contact/contact_get_user_test.go

@@ -1,125 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package contact
-
-import (
-	"bytes"
-	"errors"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/httpmock"
-)
-
-func TestGetUser_BotCurrentUserValidationTyped(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, searchUserDefaultConfig())
-
-	err := mountAndRun(t, ContactGetUser, []string{"+get-user", "--as", "bot"}, f, stdout)
-	if err == nil {
-		t.Fatalf("expected validation error")
-	}
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) {
-		t.Fatalf("expected validation error, got %T: %v", err, err)
-	}
-	if validation.Param != "--user-id" {
-		t.Fatalf("param: got %q, want --user-id", validation.Param)
-	}
-}
-
-func TestGetUser_DryRunShapes(t *testing.T) {
-	cases := []struct {
-		name string
-		args []string
-		want []string
-	}{
-		{
-			name: "current user",
-			args: []string{"+get-user", "--dry-run", "--as", "user"},
-			want: []string{"GET", "/authen/v1/user_info", "current_user"},
-		},
-		{
-			name: "bot specific user",
-			args: []string{"+get-user", "--user-id", "ou_a", "--dry-run", "--as", "bot"},
-			want: []string{"GET", "/contact/v3/users/ou_a", "ou_a", "open_id"},
-		},
-		{
-			name: "user basic batch",
-			args: []string{"+get-user", "--user-id", "ou_a", "--dry-run", "--as", "user"},
-			want: []string{"POST", "/contact/v3/users/basic_batch", "ou_a", "open_id"},
-		},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			f, stdout, _, _ := cmdutil.TestFactory(t, searchUserDefaultConfig())
-			if err := mountAndRun(t, ContactGetUser, tc.args, f, stdout); err != nil {
-				t.Fatalf("dry-run: %v", err)
-			}
-			out := stdout.String()
-			for _, want := range tc.want {
-				if !bytes.Contains(stdout.Bytes(), []byte(want)) {
-					t.Fatalf("dry-run output missing %q: %s", want, out)
-				}
-			}
-		})
-	}
-}
-
-func TestGetUser_CurrentUserAPIFailureTyped(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, searchUserDefaultConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/authen/v1/user_info",
-		Body:   map[string]interface{}{"code": 123456, "msg": "upstream rejected contact request"},
-	})
-
-	err := mountAndRun(t, ContactGetUser, []string{"+get-user", "--as", "user"}, f, stdout)
-	if err == nil {
-		t.Fatalf("expected API error")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T: %v", err, err)
-	}
-	if p.Code != 123456 {
-		t.Fatalf("code: got %d, want 123456", p.Code)
-	}
-	if p.Category != errs.CategoryAPI {
-		t.Fatalf("category: got %q, want %q", p.Category, errs.CategoryAPI)
-	}
-	if stdout.Len() != 0 {
-		t.Fatalf("stdout should stay empty on API failure, got %q", stdout.String())
-	}
-}
-
-func TestGetUser_UserBasicBatchUsesTypedAPI(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, searchUserDefaultConfig())
-	stub := &httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/contact/v3/users/basic_batch?user_id_type=open_id",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"data": map[string]interface{}{
-				"users": []interface{}{
-					map[string]interface{}{"user_id": "ou_a", "name": "Alice"},
-				},
-			},
-		},
-	}
-	reg.Register(stub)
-
-	err := mountAndRun(t, ContactGetUser, []string{"+get-user", "--user-id", "ou_a", "--as", "user", "--format", "json"}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute: %v", err)
-	}
-	if !bytes.Contains(stub.CapturedBody, []byte(`"ou_a"`)) {
-		t.Fatalf("request body should include user id, got %s", string(stub.CapturedBody))
-	}
-	if !bytes.Contains(stdout.Bytes(), []byte(`"user"`)) {
-		t.Fatalf("stdout should include user object, got %s", stdout.String())
-	}
-}

shortcuts/contact/contact_search_user.go

@@ -15,7 +15,6 @@ import (
 	"strings"
 	"unicode/utf8"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -81,6 +80,12 @@ type searchUserAPIFilter struct {
 	HasEnterpriseEmail  bool     `json:"has_enterprise_email,omitempty"`
 }
 
+type searchUserAPIEnvelope struct {
+	Code int                `json:"code"`
+	Msg  string             `json:"msg"`
+	Data *searchUserAPIData `json:"data"`
+}
+
 type searchUserAPIData struct {
 	Items     []searchUserAPIItem `json:"items"`
 	HasMore   bool                `json:"has_more"`
@@ -211,17 +216,19 @@ func executeSearchUserSingle(ctx context.Context, runtime *common.RuntimeContext
 	if err != nil {
 		return err
 	}
-
-	data, err := runtime.ClassifyAPIResponse(apiResp)
-	if err != nil {
-		return err
-	}
-	respData, err := decodeSearchUserAPIData(data)
-	if err != nil {
-		return err
+	if apiResp.StatusCode != http.StatusOK {
+		return output.ErrAPI(apiResp.StatusCode, http.StatusText(apiResp.StatusCode), string(apiResp.RawBody))
 	}
 
-	users, hasMore := projectUsers(respData, runtime.Str("lang"), runtime.Config.Brand)
+	var resp searchUserAPIEnvelope
+	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
+		return output.ErrWithHint(output.ExitInternal, "validation", "unmarshal response failed", err.Error())
+	}
+	if resp.Code != 0 {
+		return output.ErrAPI(resp.Code, resp.Msg, string(apiResp.RawBody))
+	}
+
+	users, hasMore := projectUsers(resp.Data, runtime.Str("lang"), runtime.Config.Brand)
 	out := searchUserResponse{Users: users, HasMore: hasMore}
 
 	runtime.OutFormat(out, &output.Meta{Count: len(users)}, func(w io.Writer) {
@@ -238,20 +245,6 @@ func executeSearchUserSingle(ctx context.Context, runtime *common.RuntimeContext
 	return nil
 }
 
-func decodeSearchUserAPIData(data map[string]interface{}) (*searchUserAPIData, error) {
-	raw, err := json.Marshal(data)
-	if err != nil {
-		return nil, contactInvalidResponseError("marshal search user response data failed").
-			WithCause(err)
-	}
-	var out searchUserAPIData
-	if err := json.Unmarshal(raw, &out); err != nil {
-		return nil, contactInvalidResponseError("decode search user response data failed").
-			WithCause(err)
-	}
-	return &out, nil
-}
-
 func isHumanReadableFormat(format string) bool {
 	return format == "pretty" || format == "table"
 }
@@ -380,74 +373,52 @@ func rowFromItem(item *searchUserAPIItem, lang string, brand core.LarkBrand) sea
 
 func validateSearchUser(runtime *common.RuntimeContext) error {
 	if !hasAnySearchInput(runtime) {
-		return common.ValidationErrorf(
+		return common.FlagErrorf(
 			"specify at least one of --query, --queries, --user-ids, --has-chatted, --has-enterprise-email, --exclude-external-users, --left-organization",
-		).WithParams(
-			errs.InvalidParam{Name: "--query", Reason: "required; specify at least one search input"},
-			errs.InvalidParam{Name: "--queries", Reason: "required; specify at least one search input"},
-			errs.InvalidParam{Name: "--user-ids", Reason: "required; specify at least one search input"},
-			errs.InvalidParam{Name: "--has-chatted", Reason: "required; specify at least one search input"},
-			errs.InvalidParam{Name: "--has-enterprise-email", Reason: "required; specify at least one search input"},
-			errs.InvalidParam{Name: "--exclude-external-users", Reason: "required; specify at least one search input"},
-			errs.InvalidParam{Name: "--left-organization", Reason: "required; specify at least one search input"},
 		)
 	}
 
 	queriesRaw := strings.TrimSpace(runtime.Str("queries"))
 	if queriesRaw != "" {
 		if strings.TrimSpace(runtime.Str("query")) != "" {
-			return common.ValidationErrorf("--query and --queries are mutually exclusive").
-				WithParams(
-					errs.InvalidParam{Name: "--query", Reason: "mutually exclusive with --queries"},
-					errs.InvalidParam{Name: "--queries", Reason: "mutually exclusive with --query"},
-				)
+			return common.FlagErrorf("--query and --queries are mutually exclusive")
 		}
 		if strings.TrimSpace(runtime.Str("user-ids")) != "" {
-			return common.ValidationErrorf("--user-ids and --queries are mutually exclusive").
-				WithParams(
-					errs.InvalidParam{Name: "--user-ids", Reason: "mutually exclusive with --queries"},
-					errs.InvalidParam{Name: "--queries", Reason: "mutually exclusive with --user-ids"},
-				)
+			return common.FlagErrorf("--user-ids and --queries are mutually exclusive")
 		}
 		queries := parseAndDedupQueries(queriesRaw)
 		if len(queries) == 0 {
-			return common.ValidationErrorf("--queries: no valid query parsed from %q (separate entries with ',')", queriesRaw).
-				WithParam("--queries")
+			return common.FlagErrorf("--queries: no valid query parsed from %q (separate entries with ',')", queriesRaw)
 		}
 		if len(queries) > maxFanoutQueries {
-			return common.ValidationErrorf("--queries: must be at most %d entries (got %d)", maxFanoutQueries, len(queries)).
-				WithParam("--queries")
+			return common.FlagErrorf("--queries: must be at most %d entries (got %d)", maxFanoutQueries, len(queries))
 		}
 		for _, q := range queries {
 			if utf8.RuneCountInString(q) > maxSearchUserQueryChars {
-				return common.ValidationErrorf("--queries: entry %q exceeds %d characters", q, maxSearchUserQueryChars).
-					WithParam("--queries")
+				return common.FlagErrorf("--queries: entry %q exceeds %d characters", q, maxSearchUserQueryChars)
 			}
 		}
 	}
 
 	if q := strings.TrimSpace(runtime.Str("query")); q != "" {
 		if utf8.RuneCountInString(q) > maxSearchUserQueryChars {
-			return common.ValidationErrorf("--query: length must be between 1 and %d characters", maxSearchUserQueryChars).
-				WithParam("--query")
+			return common.FlagErrorf("--query: length must be between 1 and %d characters", maxSearchUserQueryChars)
 		}
 	}
 
 	if raw := strings.TrimSpace(runtime.Str("user-ids")); raw != "" {
-		ids, err := common.ResolveOpenIDsTyped("--user-ids", common.SplitCSV(raw), runtime)
+		ids, err := common.ResolveOpenIDs("--user-ids", common.SplitCSV(raw), runtime)
 		if err != nil {
 			return err
 		}
 		if len(ids) == 0 {
-			return common.ValidationErrorf("--user-ids: no valid open_id parsed from %q (separate entries with ',')", raw).
-				WithParam("--user-ids")
+			return common.FlagErrorf("--user-ids: no valid open_id parsed from %q (separate entries with ',')", raw)
 		}
 		if len(ids) > maxSearchUserUserIDs {
-			return common.ValidationErrorf("--user-ids: must be at most %d entries", maxSearchUserUserIDs).
-				WithParam("--user-ids")
+			return common.FlagErrorf("--user-ids: must be at most %d entries", maxSearchUserUserIDs)
 		}
 		for _, id := range ids {
-			if _, err := common.ValidateUserIDTyped("--user-ids", id); err != nil {
+			if _, err := common.ValidateUserID(id); err != nil {
 				return err
 			}
 		}
@@ -458,16 +429,15 @@ func validateSearchUser(runtime *common.RuntimeContext) error {
 	// silent wrong-result bugs.
 	for _, bf := range searchUserBoolFilters {
 		if runtime.Cmd.Flags().Changed(bf.Flag) && !runtime.Bool(bf.Flag) {
-			return common.ValidationErrorf(
+			return common.FlagErrorf(
 				"--%s: pass the flag to enable the filter; omit it to disable filtering (=false is rejected to prevent silent wrong results)",
 				bf.Flag,
-			).WithParam("--" + bf.Flag)
+			)
 		}
 	}
 
 	if n := runtime.Int("page-size"); n < 1 || n > maxSearchUserPageSize {
-		return common.ValidationErrorf("--page-size: must be between 1 and %d", maxSearchUserPageSize).
-			WithParam("--page-size")
+		return common.FlagErrorf("--page-size: must be between 1 and %d", maxSearchUserPageSize)
 	}
 	return nil
 }
@@ -503,7 +473,7 @@ func buildSearchUserBody(runtime *common.RuntimeContext) (*searchUserAPIRequest,
 	hasFilter := false
 
 	if raw := strings.TrimSpace(runtime.Str("user-ids")); raw != "" {
-		ids, err := common.ResolveOpenIDsTyped("--user-ids", common.SplitCSV(raw), runtime)
+		ids, err := common.ResolveOpenIDs("--user-ids", common.SplitCSV(raw), runtime)
 		if err != nil {
 			return nil, err
 		}

shortcuts/contact/contact_search_user_fanout.go

@@ -5,6 +5,7 @@ package contact
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
@@ -46,7 +47,7 @@ type fanoutResult struct {
 	Users   []searchUser
 	HasMore bool
 	ErrMsg  string // empty = success
-	Err     error  // original failure, kept for typed all-failed propagation
+	ErrCode int    // 0 = success or unknown; otherwise an HTTP status or Lark API code corresponding to the first error
 }
 
 // isFanoutSummaryFormat gates the per-fanout stderr summary line. Includes csv
@@ -66,7 +67,7 @@ func runOneQuery(ctx context.Context, runtime *common.RuntimeContext, index int,
 	// Pre-check ctx so queued workers see cancellation before issuing a
 	// request; in-flight workers continue until DoAPI returns.
 	if err := ctx.Err(); err != nil {
-		return fanoutErrorResult(index, query, err)
+		return fanoutResult{Index: index, Query: query, ErrMsg: err.Error()}
 	}
 
 	body := &searchUserAPIRequest{Query: query}
@@ -81,29 +82,38 @@ func runOneQuery(ctx context.Context, runtime *common.RuntimeContext, index int,
 		QueryParams: larkcore.QueryParams{"page_size": []string{strconv.Itoa(runtime.Int("page-size"))}},
 	})
 	if err != nil {
-		return fanoutErrorResult(index, query, err)
+		return fanoutResult{Index: index, Query: query, ErrMsg: err.Error()}
+	}
+	if apiResp.StatusCode != http.StatusOK {
+		body := strings.TrimSpace(string(apiResp.RawBody))
+		const maxBody = 200
+		if len(body) > maxBody {
+			body = body[:maxBody] + "..."
+		}
+		msg := fmt.Sprintf("HTTP %d %s", apiResp.StatusCode, http.StatusText(apiResp.StatusCode))
+		if body != "" {
+			msg = fmt.Sprintf("%s: %s", msg, body)
+		}
+		return fanoutResult{Index: index, Query: query,
+			ErrMsg:  msg,
+			ErrCode: apiResp.StatusCode}
 	}
 
-	data, err := runtime.ClassifyAPIResponse(apiResp)
-	if err != nil {
-		return fanoutErrorResult(index, query, err)
+	var resp searchUserAPIEnvelope
+	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
+		return fanoutResult{Index: index, Query: query,
+			ErrMsg: fmt.Sprintf("parse response failed: %v", err)}
 	}
-	respData, err := decodeSearchUserAPIData(data)
-	if err != nil {
-		return fanoutErrorResult(index, query, err)
+	if resp.Code != 0 {
+		return fanoutResult{Index: index, Query: query,
+			ErrMsg:  fmt.Sprintf("API %d: %s", resp.Code, resp.Msg),
+			ErrCode: resp.Code}
 	}
 
-	users, hasMore := projectUsers(respData, runtime.Str("lang"), runtime.Config.Brand)
+	users, hasMore := projectUsers(resp.Data, runtime.Str("lang"), runtime.Config.Brand)
 	return fanoutResult{Index: index, Query: query, Users: users, HasMore: hasMore}
 }
 
-func fanoutErrorResult(index int, query string, err error) fanoutResult {
-	if err == nil {
-		return fanoutResult{Index: index, Query: query}
-	}
-	return fanoutResult{Index: index, Query: query, ErrMsg: contactFanoutErrorSummary(err), Err: err}
-}
-
 type fanoutUser struct {
 	searchUser
 	MatchedQuery string `json:"matched_query"`
@@ -136,7 +146,7 @@ func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutRespo
 	}
 	failed := 0
 	var firstErrMsg, firstErrQuery string
-	var firstErr error
+	var firstErrCode int
 	for i, r := range indexed {
 		out.Queries = append(out.Queries, querySummary{
 			Query:   queries[i],
@@ -148,7 +158,7 @@ func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutRespo
 			if firstErrMsg == "" {
 				firstErrMsg = r.ErrMsg
 				firstErrQuery = queries[i]
-				firstErr = r.Err
+				firstErrCode = r.ErrCode
 			}
 			continue
 		}
@@ -159,7 +169,18 @@ func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutRespo
 	if failed == len(queries) && len(queries) > 0 {
 		msg := fmt.Sprintf("all %d queries failed; first: %s (query=%q)",
 			len(queries), firstErrMsg, firstErrQuery)
-		return nil, contactFanoutAllFailedError(firstErr, msg)
+		// Only the HTTP-status / Lark-API-code branches in runOneQuery populate
+		// ErrCode; transport, parse, panic, and ctx-canceled stay at 0. Code 0
+		// means success in the Lark protocol, so don't pretend it's an API error
+		// when we have nothing structured to report.
+		if firstErrCode != 0 {
+			return nil, output.ErrAPI(firstErrCode, msg, "")
+		}
+		// No structured API code — the failure was transport, parse, panic, or
+		// cancellation. Suggest the actionable next step rather than shipping
+		// an empty hint that would leave the calling agent with nothing to do.
+		return nil, output.ErrWithHint(output.ExitInternal, "fanout", msg,
+			"retry the command; if it persists, narrow --queries to a single term to isolate the failing input")
 	}
 	return out, nil
 }

shortcuts/contact/contact_search_user_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"strings"
@@ -15,10 +16,10 @@ import (
 	"time"
 	"unicode/utf8"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
@@ -253,16 +254,6 @@ func TestRowFromItem_CrossTenantEmptyEmailNoPanic(t *testing.T) {
 	}
 }
 
-func TestProjectUsers_NilData(t *testing.T) {
-	users, hasMore := projectUsers(nil, "", core.BrandFeishu)
-	if users == nil {
-		t.Fatalf("users should be an empty slice, not nil")
-	}
-	if len(users) != 0 || hasMore {
-		t.Fatalf("projectUsers(nil): got users=%v hasMore=%v", users, hasMore)
-	}
-}
-
 func TestValidateSearchUser_AllEmpty_Errors(t *testing.T) {
 	cmd := newSearchUserTestCommand()
 	rt := common.TestNewRuntimeContext(cmd, searchUserDefaultConfig())
@@ -488,26 +479,6 @@ func TestBuildBody_UserIDsResolveAndDedup(t *testing.T) {
 	}
 }
 
-func TestBuildBody_UserIDsMeWithoutLoginReturnsTypedError(t *testing.T) {
-	cmd := newSearchUserTestCommand()
-	_ = cmd.Flags().Set("user-ids", "me")
-	cfg := searchUserDefaultConfig()
-	cfg.UserOpenId = ""
-	rt := common.TestNewRuntimeContext(cmd, cfg)
-
-	body, err := buildSearchUserBody(rt)
-	if err == nil {
-		t.Fatalf("expected error, got body %+v", body)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryValidation {
-		t.Fatalf("category: got %q, want %q", p.Category, errs.CategoryValidation)
-	}
-}
-
 func TestValidateSearchUser_PageSizeOutOfRange_Errors(t *testing.T) {
 	for _, n := range []int{0, 31} {
 		cmd := newSearchUserTestCommand()
@@ -533,20 +504,6 @@ func TestValidateSearchUser_PageSizeBoundaries_OK(t *testing.T) {
 	}
 }
 
-func TestDecodeSearchUserAPIData_MarshalFailureTyped(t *testing.T) {
-	_, err := decodeSearchUserAPIData(map[string]interface{}{"bad": func() {}})
-	if err == nil {
-		t.Fatalf("expected marshal failure")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
-		t.Fatalf("problem type: got %s/%s", p.Category, p.Subtype)
-	}
-}
-
 // mountAndRun mounts the shortcut under a parent cobra command and runs it
 // with the given args. Mirrors the pattern used in other shortcut packages.
 func mountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Factory, stdout *bytes.Buffer) error {
@@ -1054,13 +1011,6 @@ func TestRunOneQuery_APINonZeroCode(t *testing.T) {
 	if got.ErrMsg != "API 99991663: rate limited" {
 		t.Errorf("ErrMsg = %q, want 'API 99991663: rate limited'", got.ErrMsg)
 	}
-	p, ok := errs.ProblemOf(got.Err)
-	if !ok {
-		t.Fatalf("expected typed problem on fanout result, got %T", got.Err)
-	}
-	if p.Code != 99991663 {
-		t.Errorf("problem code: got %d, want 99991663", p.Code)
-	}
 	if got.Users != nil || got.HasMore {
 		t.Errorf("on error, Users/HasMore must be zero values; got %+v", got)
 	}
@@ -1082,15 +1032,8 @@ func TestRunOneQuery_HTTPNon200(t *testing.T) {
 	if !strings.Contains(got.ErrMsg, "upstream_unavailable") {
 		t.Errorf("ErrMsg should include response body for diagnosis; got %q", got.ErrMsg)
 	}
-	p, ok := errs.ProblemOf(got.Err)
-	if !ok {
-		t.Fatalf("expected typed problem on fanout result, got %T", got.Err)
-	}
-	if p.Code != 503 {
-		t.Errorf("problem code: got %d, want 503", p.Code)
-	}
-	if p.Category != errs.CategoryNetwork {
-		t.Errorf("problem category: got %q, want %q", p.Category, errs.CategoryNetwork)
+	if got.ErrCode != 503 {
+		t.Errorf("ErrCode = %d, want 503", got.ErrCode)
 	}
 }
 
@@ -1137,16 +1080,6 @@ func TestRunOneQuery_TransportError(t *testing.T) {
 	}
 }
 
-func TestFanoutErrorResult_NilErrorIsSuccess(t *testing.T) {
-	got := fanoutErrorResult(4, "alice", nil)
-	if got.Index != 4 || got.Query != "alice" {
-		t.Fatalf("Index/Query mismatch: %+v", got)
-	}
-	if got.ErrMsg != "" || got.Err != nil {
-		t.Fatalf("nil error should produce a success result, got %+v", got)
-	}
-}
-
 func TestFanoutAssemble_OrderAndShape(t *testing.T) {
 	results := []fanoutResult{
 		{Index: 1, Query: "bob", Users: []searchUser{{OpenID: "ou_b"}}, HasMore: true},
@@ -1203,7 +1136,7 @@ func TestFanoutAssemble_AllFailed_ReturnsError(t *testing.T) {
 }
 
 // When all queries fail with no structured Lark API code (transport, parse,
-// panic, ctx-canceled), the returned typed error must carry an actionable
+// panic, ctx-canceled), the returned ExitError must carry an actionable
 // hint so the calling agent has a next step to try instead of giving up.
 func TestFanoutAssemble_AllFailed_NoCode_HasActionableHint(t *testing.T) {
 	results := []fanoutResult{
@@ -1214,38 +1147,28 @@ func TestFanoutAssemble_AllFailed_NoCode_HasActionableHint(t *testing.T) {
 	if err == nil {
 		t.Fatalf("expected error when all queries failed")
 	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T", err)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
 	}
-	if p.Category != errs.CategoryInternal {
-		t.Fatalf("category: got %q, want %q", p.Category, errs.CategoryInternal)
+	if exitErr.Detail == nil {
+		t.Fatalf("expected Detail, got nil")
 	}
-	if p.Hint == "" {
+	if exitErr.Detail.Hint == "" {
 		t.Errorf("expected non-empty Hint so agents have a next step; got empty")
 	}
-	if !strings.Contains(p.Hint, "retry") {
-		t.Errorf("hint should suggest retry as the first action; got %q", p.Hint)
+	if !strings.Contains(exitErr.Detail.Hint, "retry") {
+		t.Errorf("hint should suggest retry as the first action; got %q", exitErr.Detail.Hint)
 	}
 }
 
-// Codes from the first failure must propagate through typed problem fields so
-// the CLI's exit-code classifier sees the real signal (e.g., 99991663 rate limit)
+// Codes from the first failure must propagate through output.ErrAPI so the
+// CLI's exit-code classifier sees the real signal (e.g., 99991663 rate limit)
 // instead of 0, which would mean "success" in the Lark protocol.
 func TestFanoutAssemble_AllFailed_PropagatesFirstCode(t *testing.T) {
 	results := []fanoutResult{
-		{
-			Index:  0,
-			Query:  "alice",
-			ErrMsg: "API 99991663: rate limit",
-			Err:    errs.NewAPIError(errs.SubtypeRateLimit, "rate limit").WithCode(99991663),
-		},
-		{
-			Index:  1,
-			Query:  "bob",
-			ErrMsg: "HTTP 500",
-			Err:    errs.NewNetworkError(errs.SubtypeNetworkServer, "HTTP 500").WithCode(500),
-		},
+		{Index: 0, Query: "alice", ErrMsg: "API 99991663: rate limit", ErrCode: 99991663},
+		{Index: 1, Query: "bob", ErrMsg: "HTTP 500", ErrCode: 500},
 	}
 	_, err := buildFanoutResponse([]string{"alice", "bob"}, results)
 	if err == nil {
@@ -1254,16 +1177,6 @@ func TestFanoutAssemble_AllFailed_PropagatesFirstCode(t *testing.T) {
 	if !strings.Contains(err.Error(), "rate limit") {
 		t.Errorf("error should contain first ErrMsg; got %v", err)
 	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T", err)
-	}
-	if p.Code != 99991663 {
-		t.Errorf("problem code: got %d, want 99991663", p.Code)
-	}
-	if p.Subtype != errs.SubtypeRateLimit {
-		t.Errorf("problem subtype: got %q, want %q", p.Subtype, errs.SubtypeRateLimit)
-	}
 }
 
 func TestFanoutAssemble_PartialFailureOK(t *testing.T) {
@@ -1307,37 +1220,6 @@ func TestFanoutAssemble_NoTopLevelHasMore(t *testing.T) {
 	}
 }
 
-func TestPrettyFanoutUserRows(t *testing.T) {
-	rows := prettyFanoutUserRows([]fanoutUser{
-		{
-			searchUser: searchUser{
-				OpenID:          "ou_a",
-				LocalizedName:   "Alice",
-				Department:      strings.Repeat("d", 80),
-				EnterpriseEmail: "alice@example.com",
-				HasChatted:      true,
-				ChatRecencyHint: "Contacted yesterday",
-			},
-			MatchedQuery: "alice",
-		},
-	})
-	if len(rows) != 1 {
-		t.Fatalf("rows: got %d, want 1", len(rows))
-	}
-	row := rows[0]
-	for _, key := range []string{"matched_query", "localized_name", "department", "enterprise_email", "has_chatted", "chat_recency_hint", "open_id"} {
-		if _, ok := row[key]; !ok {
-			t.Fatalf("row missing key %q: %+v", key, row)
-		}
-	}
-	if row["matched_query"] != "alice" || row["open_id"] != "ou_a" {
-		t.Fatalf("row identity fields: %+v", row)
-	}
-	if len(row["department"].(string)) >= 80 {
-		t.Fatalf("department should be truncated for table display, got %q", row["department"])
-	}
-}
-
 // Verifies that with the auto-pagination flags removed, --page-all / --page-limit
 // are no longer accepted. cobra must reject the unknown flag at parse time —
 // no stub is registered because the command should never reach the API.

shortcuts/doc/clipboard.go

@@ -11,8 +11,6 @@ import (
 	"regexp"
 	"runtime"
 	"strings"
-
-	"github.com/larksuite/cli/errs"
 )
 
 // readClipboardImageBytes reads the current clipboard image and returns the
@@ -37,13 +35,13 @@ func readClipboardImageBytes() ([]byte, error) {
 	case "linux":
 		data, err = readClipboardLinux()
 	default:
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard image upload is not supported on %s", runtime.GOOS)
+		return nil, fmt.Errorf("clipboard image upload is not supported on %s", runtime.GOOS)
 	}
 	if err != nil {
 		return nil, err
 	}
 	if len(data) == 0 {
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no image data")
+		return nil, fmt.Errorf("clipboard contains no image data")
 	}
 	return data, nil
 }
@@ -93,9 +91,9 @@ func readClipboardDarwin() ([]byte, error) {
 	}
 
 	if stderrText != "" {
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no image data (osascript: %s)", stderrText)
+		return nil, fmt.Errorf("clipboard contains no image data (osascript: %s)", stderrText)
 	}
-	return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no image data")
+	return nil, fmt.Errorf("clipboard contains no image data")
 }
 
 // runOsascript invokes osascript with a single AppleScript expression and
@@ -190,14 +188,14 @@ func decodeOsascriptData(s string) ([]byte, error) {
 // decodeHex decodes an uppercase hex string (as produced by osascript) to bytes.
 func decodeHex(h string) ([]byte, error) {
 	if len(h)%2 != 0 {
-		return nil, fmt.Errorf("odd hex length") //nolint:forbidigo // intermediate decode helper; result discarded by caller on error
+		return nil, fmt.Errorf("odd hex length")
 	}
 	b := make([]byte, len(h)/2)
 	for i := 0; i < len(h); i += 2 {
 		hi := hexVal(h[i])
 		lo := hexVal(h[i+1])
 		if hi < 0 || lo < 0 {
-			return nil, fmt.Errorf("invalid hex char at %d", i) //nolint:forbidigo // intermediate decode helper; result discarded by caller on error
+			return nil, fmt.Errorf("invalid hex char at %d", i)
 		}
 		b[i/2] = byte(hi<<4 | lo)
 	}
@@ -239,12 +237,12 @@ $img.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)
 		if msg == "" {
 			msg = err.Error()
 		}
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard read failed (%s)", msg).WithCause(err)
+		return nil, fmt.Errorf("clipboard read failed (%s)", msg)
 	}
 	b64 := strings.TrimSpace(string(out))
 	data, decErr := base64.StdEncoding.DecodeString(b64)
 	if decErr != nil {
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard image decode failed: %s", decErr).WithCause(decErr)
+		return nil, fmt.Errorf("clipboard image decode failed: %w", decErr)
 	}
 	return data, nil
 }
@@ -327,15 +325,15 @@ func readClipboardLinux() ([]byte, error) {
 		foundTool = true
 		out, err := exec.Command(t.name, t.args...).Output()
 		if err != nil {
-			lastErr = errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard image read failed via %s: %s", t.name, err).WithCause(err)
+			lastErr = fmt.Errorf("clipboard image read failed via %s: %w", t.name, err)
 			continue
 		}
 		if len(out) == 0 {
-			lastErr = errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no image data (%s returned empty output)", t.name)
+			lastErr = fmt.Errorf("clipboard contains no image data (%s returned empty output)", t.name)
 			continue
 		}
 		if t.validatePNG && !hasPNGMagic(out) {
-			lastErr = errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no PNG image data (%s output is not a PNG)", t.name)
+			lastErr = fmt.Errorf("clipboard contains no PNG image data (%s output is not a PNG)", t.name)
 			continue
 		}
 		return out, nil
@@ -344,8 +342,8 @@ func readClipboardLinux() ([]byte, error) {
 	if foundTool && lastErr != nil {
 		return nil, lastErr
 	}
-	return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition,
-		"clipboard image read failed: no supported tool found. "+
-			"Install one of xclip, wl-clipboard, or xsel via your distro's package manager "+
+	return nil, fmt.Errorf(
+		"clipboard image read failed: no supported tool found. " +
+			"Install one of xclip, wl-clipboard, or xsel via your distro's package manager " +
 			"(apt, dnf, pacman, apk, brew, etc.).")
 }

shortcuts/doc/doc_errors.go

@@ -1,34 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"errors"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// wrapDocNetworkErr returns err unchanged when it is already a typed errs.*
-// error (preserving its subtype / code / log_id from the runtime boundary),
-// and only wraps a raw, unclassified error as a transport-level network error.
-func wrapDocNetworkErr(err error, format string, args ...any) error {
-	if _, ok := errs.ProblemOf(err); ok {
-		return err
-	}
-	return errs.NewNetworkError(errs.SubtypeNetworkTransport, format, args...).WithCause(err)
-}
-
-// wrapDocInputFileErr wraps a --file Stat/read failure via the shared typed
-// helper (which sets the cause) and tags it with the --file param so agents
-// learn which flag to fix. The common helper is flag-agnostic, so the param is
-// attached here at the Doc call site rather than mutating shared behavior.
-func wrapDocInputFileErr(err error, readMsg string) error {
-	wrapped := common.WrapInputStatErrorTyped(err, readMsg)
-	var ve *errs.ValidationError
-	if errors.As(wrapped, &ve) {
-		ve.Param = "--file"
-	}
-	return wrapped
-}

shortcuts/doc/doc_errors_test.go

@@ -1,420 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"context"
-	"errors"
-	"slices"
-	"strconv"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// testDocxToken is a bare docx token that parseDocumentRef accepts, letting the
-// validation tests reach the flag checks that run after --doc is resolved.
-const testDocxToken = "doxcnDocErrorsTestToken"
-
-// docValidateRuntime builds a RuntimeContext carrying only the flags a Doc
-// Validate function reads. String values are applied (and marked Changed) only
-// when non-empty; int values are always applied so Changed() reports true,
-// mirroring how cobra records an explicitly supplied numeric flag.
-func docValidateRuntime(t *testing.T, str map[string]string, bools map[string]bool, ints map[string]int) *common.RuntimeContext {
-	t.Helper()
-	cmd := &cobra.Command{Use: "docs"}
-	fs := cmd.Flags()
-	for name, val := range str {
-		fs.String(name, "", "")
-		if val != "" {
-			if err := fs.Set(name, val); err != nil {
-				t.Fatalf("set --%s=%q: %v", name, val, err)
-			}
-		}
-	}
-	for name, val := range bools {
-		fs.Bool(name, false, "")
-		if val {
-			if err := fs.Set(name, "true"); err != nil {
-				t.Fatalf("set --%s: %v", name, err)
-			}
-		}
-	}
-	for name, val := range ints {
-		fs.Int(name, 0, "")
-		if err := fs.Set(name, strconv.Itoa(val)); err != nil {
-			t.Fatalf("set --%s=%d: %v", name, val, err)
-		}
-	}
-	return common.TestNewRuntimeContext(cmd, nil)
-}
-
-// assertValidationContract pins the typed envelope every migrated Doc
-// validation fault must emit: a *errs.ValidationError in CategoryValidation
-// with the expected Subtype, the single offending flag in Param, and every
-// involved flag in Params. Single-flag faults set Param and leave Params empty;
-// multi-flag faults (mutual exclusion, "one of A or B") leave Param empty and
-// enumerate each flag in Params so agents resolve them without parsing the text.
-func assertValidationContract(t *testing.T, err error, wantSubtype errs.Subtype, wantParam string, wantParams ...string) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected validation error, got nil")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("error type = %T, want *errs.ValidationError (%v)", err, err)
-	}
-	if ve.Category != errs.CategoryValidation {
-		t.Errorf("category = %q, want %q", ve.Category, errs.CategoryValidation)
-	}
-	if ve.Subtype != wantSubtype {
-		t.Errorf("subtype = %q, want %q", ve.Subtype, wantSubtype)
-	}
-	if ve.Param != wantParam {
-		t.Errorf("param = %q, want %q", ve.Param, wantParam)
-	}
-	gotParams := make([]string, len(ve.Params))
-	for i, p := range ve.Params {
-		gotParams[i] = p.Name
-	}
-	if !slices.Equal(gotParams, wantParams) {
-		t.Errorf("params = %v, want %v", gotParams, wantParams)
-	}
-}
-
-func TestDocMediaInsertValidateContract(t *testing.T) {
-	cases := []struct {
-		name       string
-		str        map[string]string
-		bools      map[string]bool
-		ints       map[string]int
-		wantParam  string
-		wantParams []string
-	}{
-		{
-			name:       "neither file nor clipboard",
-			str:        map[string]string{"doc": testDocxToken},
-			wantParam:  "", // one-of-two flags: enumerated in Params
-			wantParams: []string{"--file", "--from-clipboard"},
-		},
-		{
-			name:       "file and clipboard together",
-			str:        map[string]string{"doc": testDocxToken, "file": "dummy.png"},
-			bools:      map[string]bool{"from-clipboard": true},
-			wantParam:  "", // mutual exclusion: enumerated in Params
-			wantParams: []string{"--file", "--from-clipboard"},
-		},
-		{
-			name:      "non-docx document",
-			str:       map[string]string{"doc": "https://example.larksuite.com/doc/xxxxxx", "file": "dummy.png"},
-			wantParam: "--doc",
-		},
-		{
-			name:      "blank selection",
-			str:       map[string]string{"doc": testDocxToken, "file": "dummy.png", "selection-with-ellipsis": "   "},
-			wantParam: "--selection-with-ellipsis",
-		},
-		{
-			name:      "before without selection",
-			str:       map[string]string{"doc": testDocxToken, "file": "dummy.png"},
-			bools:     map[string]bool{"before": true},
-			wantParam: "--before",
-		},
-		{
-			name:      "invalid file-view",
-			str:       map[string]string{"doc": testDocxToken, "file": "dummy.png", "file-view": "bogus"},
-			wantParam: "--file-view",
-		},
-		{
-			name:      "file-view without type file",
-			str:       map[string]string{"doc": testDocxToken, "file": "dummy.png", "file-view": "card", "type": "image"},
-			wantParam: "--file-view",
-		},
-		{
-			name:       "dimensions with non-image type",
-			str:        map[string]string{"doc": testDocxToken, "file": "dummy.png", "type": "file"},
-			ints:       map[string]int{"width": 100},
-			wantParam:  "", // only --width was set here, so only it is enumerated
-			wantParams: []string{"--width"},
-		},
-		{
-			name:      "non-positive width",
-			str:       map[string]string{"doc": testDocxToken, "file": "dummy.png", "type": "image"},
-			ints:      map[string]int{"width": 0},
-			wantParam: "--width",
-		},
-		{
-			name:      "non-positive height",
-			str:       map[string]string{"doc": testDocxToken, "file": "dummy.png", "type": "image"},
-			ints:      map[string]int{"height": 0},
-			wantParam: "--height",
-		},
-		{
-			name:      "width over maximum",
-			str:       map[string]string{"doc": testDocxToken, "file": "dummy.png", "type": "image"},
-			ints:      map[string]int{"width": 10001},
-			wantParam: "--width",
-		},
-		{
-			name:      "height over maximum",
-			str:       map[string]string{"doc": testDocxToken, "file": "dummy.png", "type": "image"},
-			ints:      map[string]int{"height": 10001},
-			wantParam: "--height",
-		},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			rt := docValidateRuntime(t, tc.str, tc.bools, tc.ints)
-			err := DocMediaInsert.Validate(context.Background(), rt)
-			assertValidationContract(t, err, errs.SubtypeInvalidArgument, tc.wantParam, tc.wantParams...)
-		})
-	}
-}
-
-func TestValidateCreateV2Contract(t *testing.T) {
-	cases := []struct {
-		name       string
-		str        map[string]string
-		wantParam  string
-		wantParams []string
-	}{
-		{
-			name:      "content required",
-			str:       map[string]string{},
-			wantParam: "--content",
-		},
-		{
-			name:       "parent token and position mutually exclusive",
-			str:        map[string]string{"content": "<doc/>", "parent-token": "fldcnX", "parent-position": "my_library"},
-			wantParam:  "", // mutual exclusion: enumerated in Params
-			wantParams: []string{"--parent-token", "--parent-position"},
-		},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			rt := docValidateRuntime(t, tc.str, nil, nil)
-			err := validateCreateV2(context.Background(), rt)
-			assertValidationContract(t, err, errs.SubtypeInvalidArgument, tc.wantParam, tc.wantParams...)
-		})
-	}
-}
-
-func TestValidateFetchV2Contract(t *testing.T) {
-	cases := []struct {
-		name       string
-		str        map[string]string
-		ints       map[string]int
-		wantParam  string
-		wantParams []string
-	}{
-		{
-			name:       "range mode without block ids",
-			str:        map[string]string{"doc": testDocxToken, "detail": "simple", "scope": "range"},
-			wantParam:  "", // either --start-block-id or --end-block-id: enumerated in Params
-			wantParams: []string{"--start-block-id", "--end-block-id"},
-		},
-		{
-			name:      "keyword mode without keyword",
-			str:       map[string]string{"doc": testDocxToken, "detail": "simple", "scope": "keyword"},
-			wantParam: "--keyword",
-		},
-		{
-			name:      "section mode without start block id",
-			str:       map[string]string{"doc": testDocxToken, "detail": "simple", "scope": "section"},
-			wantParam: "--start-block-id",
-		},
-		{
-			name:      "negative context-before",
-			str:       map[string]string{"doc": testDocxToken, "detail": "simple", "scope": "outline"},
-			ints:      map[string]int{"context-before": -1},
-			wantParam: "--context-before",
-		},
-		{
-			name:      "unknown scope",
-			str:       map[string]string{"doc": testDocxToken, "detail": "simple", "scope": "bogus"},
-			wantParam: "--scope",
-		},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			rt := docValidateRuntime(t, tc.str, nil, tc.ints)
-			err := validateFetchV2(context.Background(), rt)
-			assertValidationContract(t, err, errs.SubtypeInvalidArgument, tc.wantParam, tc.wantParams...)
-		})
-	}
-}
-
-// TestBuildDocsSearchRequestPreservesParseCause pins the --filter parse faults:
-// the typed envelope carries Param --filter and chains the original parse error
-// so errors.Is/Unwrap traversal keeps the underlying JSON/time-parse detail.
-func TestBuildDocsSearchRequestPreservesParseCause(t *testing.T) {
-	cases := []struct {
-		name   string
-		filter string
-	}{
-		{"invalid filter json", "{not json"},
-		{"invalid open_time start", `{"open_time":{"start":"not-a-time"}}`},
-		{"invalid open_time end", `{"open_time":{"end":"not-a-time"}}`},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			_, err := buildDocsSearchRequest("q", tc.filter, "", "15")
-			var ve *errs.ValidationError
-			if !errors.As(err, &ve) {
-				t.Fatalf("error type = %T, want *errs.ValidationError (%v)", err, err)
-			}
-			if ve.Subtype != errs.SubtypeInvalidArgument {
-				t.Errorf("subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-			}
-			if ve.Param != "--filter" {
-				t.Errorf("param = %q, want %q", ve.Param, "--filter")
-			}
-			if errors.Unwrap(ve) == nil {
-				t.Error("parse error not chained: errors.Unwrap == nil")
-			}
-		})
-	}
-}
-
-// TestWrapDocNetworkErr pins wrapDocNetworkErr's contract: a typed error passes
-// through untouched, while a raw error becomes a transport-level NetworkError
-// that still chains the original cause for errors.Is/Unwrap.
-func TestWrapDocNetworkErr(t *testing.T) {
-	t.Run("typed error passes through unchanged", func(t *testing.T) {
-		typed := errs.NewValidationError(errs.SubtypeInvalidArgument, "bad input")
-		got := wrapDocNetworkErr(typed, "fetch failed")
-		if got != error(typed) {
-			t.Fatalf("typed error must pass through unchanged, got %T", got)
-		}
-	})
-	t.Run("raw error becomes transport network error", func(t *testing.T) {
-		raw := errors.New("dial tcp: i/o timeout")
-		got := wrapDocNetworkErr(raw, "fetch failed: %s", "docx")
-		var ne *errs.NetworkError
-		if !errors.As(got, &ne) {
-			t.Fatalf("raw error must become *errs.NetworkError, got %T", got)
-		}
-		if ne.Subtype != errs.SubtypeNetworkTransport {
-			t.Errorf("subtype = %q, want %q", ne.Subtype, errs.SubtypeNetworkTransport)
-		}
-		if !errors.Is(got, raw) {
-			t.Error("cause not chained: errors.Is(got, raw) == false")
-		}
-	})
-}
-
-// TestWrapDocInputFileErr pins that a --file stat/read failure becomes a typed
-// validation error tagged with the --file param and the cause preserved, so an
-// agent knows which flag to fix even though the shared helper is flag-agnostic.
-func TestWrapDocInputFileErr(t *testing.T) {
-	raw := errors.New("no such file or directory")
-	got := wrapDocInputFileErr(raw, "file not found")
-	var ve *errs.ValidationError
-	if !errors.As(got, &ve) {
-		t.Fatalf("error type = %T, want *errs.ValidationError (%v)", got, got)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--file" {
-		t.Errorf("param = %q, want %q", ve.Param, "--file")
-	}
-	if !errors.Is(got, raw) {
-		t.Error("cause not chained: errors.Is(got, raw) == false")
-	}
-}
-
-func TestValidateUpdateV2Contract(t *testing.T) {
-	cases := []struct {
-		name      string
-		str       map[string]string
-		wantParam string
-	}{
-		{
-			name:      "command required",
-			str:       map[string]string{"doc": testDocxToken},
-			wantParam: "--command",
-		},
-		{
-			name:      "invalid command",
-			str:       map[string]string{"doc": testDocxToken, "command": "bogus"},
-			wantParam: "--command",
-		},
-		{
-			name:      "str_replace without pattern",
-			str:       map[string]string{"doc": testDocxToken, "command": "str_replace"},
-			wantParam: "--pattern",
-		},
-		{
-			name:      "block_delete without block id",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_delete"},
-			wantParam: "--block-id",
-		},
-		{
-			name:      "block_insert_after without block id",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_insert_after"},
-			wantParam: "--block-id",
-		},
-		{
-			name:      "block_insert_after without content",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_insert_after", "block-id": "blkX"},
-			wantParam: "--content",
-		},
-		{
-			name:      "block_copy_insert_after without block id",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_copy_insert_after"},
-			wantParam: "--block-id",
-		},
-		{
-			name:      "block_copy_insert_after without src block ids",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_copy_insert_after", "block-id": "blkX"},
-			wantParam: "--src-block-ids",
-		},
-		{
-			name:      "block_move_after without block id",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_move_after"},
-			wantParam: "--block-id",
-		},
-		{
-			name:      "block_move_after without src block ids",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_move_after", "block-id": "blkX"},
-			wantParam: "--src-block-ids",
-		},
-		{
-			name:      "block_move_after rejects content",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_move_after", "block-id": "blkX", "src-block-ids": "blkY", "content": "x"},
-			wantParam: "--content",
-		},
-		{
-			name:      "block_replace without block id",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_replace"},
-			wantParam: "--block-id",
-		},
-		{
-			name:      "block_replace without content",
-			str:       map[string]string{"doc": testDocxToken, "command": "block_replace", "block-id": "blkX"},
-			wantParam: "--content",
-		},
-		{
-			name:      "overwrite without content",
-			str:       map[string]string{"doc": testDocxToken, "command": "overwrite"},
-			wantParam: "--content",
-		},
-		{
-			name:      "append without content",
-			str:       map[string]string{"doc": testDocxToken, "command": "append"},
-			wantParam: "--content",
-		},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			rt := docValidateRuntime(t, tc.str, nil, nil)
-			err := validateUpdateV2(context.Background(), rt)
-			assertValidationContract(t, err, errs.SubtypeInvalidArgument, tc.wantParam)
-		})
-	}
-}

shortcuts/doc/doc_media_download.go

@@ -10,8 +10,8 @@ import (
 
 	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/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -51,10 +51,10 @@ var DocMediaDownload = common.Shortcut{
 		overwrite := runtime.Bool("overwrite")
 
 		if err := validate.ResourceName(token, "--token"); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+			return output.ErrValidation("%s", err)
 		}
 		if _, err := runtime.ResolveSavePath(outputPath); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
+			return output.ErrValidation("unsafe output path: %s", err)
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Downloading: %s %s\n", mediaType, common.MaskToken(token))
@@ -73,7 +73,7 @@ var DocMediaDownload = common.Shortcut{
 			ApiPath:    apiPath,
 		})
 		if err != nil {
-			return wrapDocNetworkErr(err, "download failed: %v", err)
+			return output.ErrNetwork("download failed: %v", err)
 		}
 		defer resp.Body.Close()
 
@@ -86,14 +86,14 @@ var DocMediaDownload = common.Shortcut{
 		// Validate final path after extension append
 		if finalPath != outputPath {
 			if _, err := runtime.ResolveSavePath(finalPath); err != nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
+				return output.ErrValidation("unsafe output path: %s", err)
 			}
 		}
 
 		// Overwrite check on final path (after extension detection)
 		if !overwrite {
 			if _, statErr := runtime.FileIO().Stat(finalPath); statErr == nil {
-				return errs.NewValidationError(errs.SubtypeFailedPrecondition, "output file already exists: %s (use --overwrite to replace)", finalPath).WithParam("--output")
+				return output.ErrValidation("output file already exists: %s (use --overwrite to replace)", finalPath)
 			}
 		}
 
@@ -102,7 +102,7 @@ var DocMediaDownload = common.Shortcut{
 			ContentLength: resp.ContentLength,
 		}, resp.Body)
 		if err != nil {
-			return common.WrapSaveErrorTyped(err)
+			return common.WrapSaveErrorByCategory(err, "io")
 		}
 
 		savedPath, _ := runtime.ResolveSavePath(finalPath)

shortcuts/doc/doc_media_insert.go

@@ -15,8 +15,8 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -67,16 +67,10 @@ var DocMediaInsert = common.Shortcut{
 		filePath := runtime.Str("file")
 		fromClipboard := runtime.Bool("from-clipboard")
 		if filePath == "" && !fromClipboard {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "one of --file or --from-clipboard is required").WithParams(
-				errs.InvalidParam{Name: "--file", Reason: "provide either --file or --from-clipboard"},
-				errs.InvalidParam{Name: "--from-clipboard", Reason: "provide either --file or --from-clipboard"},
-			)
+			return common.FlagErrorf("one of --file or --from-clipboard is required")
 		}
 		if filePath != "" && fromClipboard {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file and --from-clipboard are mutually exclusive").WithParams(
-				errs.InvalidParam{Name: "--file", Reason: "mutually exclusive with --from-clipboard"},
-				errs.InvalidParam{Name: "--from-clipboard", Reason: "mutually exclusive with --file"},
-			)
+			return common.FlagErrorf("--file and --from-clipboard are mutually exclusive")
 		}
 
 		docRef, err := parseDocumentRef(runtime.Str("doc"))
@@ -84,7 +78,7 @@ var DocMediaInsert = common.Shortcut{
 			return err
 		}
 		if docRef.Kind == "doc" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx").WithParam("--doc")
+			return output.ErrValidation("docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx")
 		}
 		rawSelection := runtime.Str("selection-with-ellipsis")
 		trimmedSelection := strings.TrimSpace(rawSelection)
@@ -93,43 +87,36 @@ var DocMediaInsert = common.Shortcut{
 		// trim-to-empty would make +media-insert fall back to append-mode and
 		// write at the wrong location.
 		if rawSelection != "" && trimmedSelection == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--selection-with-ellipsis must not be blank or whitespace-only").WithParam("--selection-with-ellipsis")
+			return output.ErrValidation("--selection-with-ellipsis must not be blank or whitespace-only")
 		}
 		if runtime.Bool("before") && trimmedSelection == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--before requires --selection-with-ellipsis").WithParam("--before")
+			return output.ErrValidation("--before requires --selection-with-ellipsis")
 		}
 		if view := runtime.Str("file-view"); view != "" {
 			if _, ok := fileViewMap[view]; !ok {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --file-view value %q, expected one of: card | preview | inline", view).WithParam("--file-view")
+				return output.ErrValidation("invalid --file-view value %q, expected one of: card | preview | inline", view)
 			}
 			if runtime.Str("type") != "file" {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file-view only applies when --type=file").WithParam("--file-view")
+				return output.ErrValidation("--file-view only applies when --type=file")
 			}
 		}
 		widthChanged := runtime.Changed("width")
 		heightChanged := runtime.Changed("height")
 		if (widthChanged || heightChanged) && runtime.Str("type") != "image" {
-			var params []errs.InvalidParam
-			if widthChanged {
-				params = append(params, errs.InvalidParam{Name: "--width", Reason: "only applies when --type=image"})
-			}
-			if heightChanged {
-				params = append(params, errs.InvalidParam{Name: "--height", Reason: "only applies when --type=image"})
-			}
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--width/--height only apply when --type=image").WithParams(params...)
+			return output.ErrValidation("--width/--height only apply when --type=image")
 		}
 		if widthChanged && runtime.Int("width") <= 0 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--width must be a positive integer").WithParam("--width")
+			return output.ErrValidation("--width must be a positive integer")
 		}
 		if heightChanged && runtime.Int("height") <= 0 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--height must be a positive integer").WithParam("--height")
+			return output.ErrValidation("--height must be a positive integer")
 		}
 		const maxDimension = 10000
 		if widthChanged && runtime.Int("width") > maxDimension {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--width must not exceed %d pixels", maxDimension).WithParam("--width")
+			return output.ErrValidation("--width must not exceed %d pixels", maxDimension)
 		}
 		if heightChanged && runtime.Int("height") > maxDimension {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--height must not exceed %d pixels", maxDimension).WithParam("--height")
+			return output.ErrValidation("--height must not exceed %d pixels", maxDimension)
 		}
 		return nil
 	},
@@ -282,10 +269,10 @@ var DocMediaInsert = common.Shortcut{
 		} else {
 			stat, err := runtime.FileIO().Stat(filePath)
 			if err != nil {
-				return wrapDocInputFileErr(err, "file not found")
+				return common.WrapInputStatError(err, "file not found")
 			}
 			if !stat.Mode().IsRegular() {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "file must be a regular file: %s", filePath).WithParam("--file")
+				return output.ErrValidation("file must be a regular file: %s", filePath)
 			}
 			fileSize = stat.Size()
 			fileName = filepath.Base(filePath)
@@ -297,7 +284,7 @@ var DocMediaInsert = common.Shortcut{
 		}
 
 		// Step 1: Get document root block to find where to insert
-		rootData, err := runtime.CallAPITyped("GET",
+		rootData, err := runtime.CallAPI("GET",
 			fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/%s", validate.EncodePathSegment(documentID), validate.EncodePathSegment(documentID)),
 			nil, nil)
 		if err != nil {
@@ -331,7 +318,7 @@ var DocMediaInsert = common.Shortcut{
 		// Step 2: Create an empty block at the target position
 		fmt.Fprintf(runtime.IO().ErrOut, "Creating block at index %d\n", insertIndex)
 
-		createData, err := runtime.CallAPITyped("POST",
+		createData, err := runtime.CallAPI("POST",
 			fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/%s/children", validate.EncodePathSegment(documentID), validate.EncodePathSegment(parentBlockID)),
 			nil, buildCreateBlockData(mediaType, insertIndex, fileViewType))
 		if err != nil {
@@ -341,7 +328,7 @@ var DocMediaInsert = common.Shortcut{
 		blockId, uploadParentNode, replaceBlockID := extractCreatedBlockTargets(createData, mediaType)
 
 		if blockId == "" {
-			return errs.NewInternalError(errs.SubtypeInvalidResponse, "failed to create block: no block_id returned")
+			return output.Errorf(output.ExitAPI, "api_error", "failed to create block: no block_id returned")
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Block created: %s\n", blockId)
@@ -353,7 +340,7 @@ var DocMediaInsert = common.Shortcut{
 		// later steps should try to remove it instead of leaving an empty artifact.
 		rollback := func() error {
 			fmt.Fprintf(runtime.IO().ErrOut, "Rolling back: deleting block %s\n", blockId)
-			_, err := runtime.CallAPITyped("DELETE",
+			_, err := runtime.CallAPI("DELETE",
 				fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/%s/children/batch_delete", validate.EncodePathSegment(documentID), validate.EncodePathSegment(parentBlockID)),
 				nil, buildDeleteBlockData(insertIndex))
 			return err
@@ -392,21 +379,15 @@ var DocMediaInsert = common.Shortcut{
 				} else {
 					f, openErr := runtime.FileIO().Open(filePath)
 					if openErr != nil {
-						return withRollbackWarning(errs.NewValidationError(errs.SubtypeInvalidArgument,
-							"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName).WithCause(openErr).WithParams(
-							errs.InvalidParam{Name: "--width", Reason: "provide explicitly; source image dimensions could not be detected"},
-							errs.InvalidParam{Name: "--height", Reason: "provide explicitly; source image dimensions could not be detected"},
-						))
+						return withRollbackWarning(output.ErrValidation(
+							"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName))
 					}
 					nativeW, nativeH, dimErr = detectImageDimensions(f)
 					f.Close()
 				}
 				if dimErr != nil {
-					return withRollbackWarning(errs.NewValidationError(errs.SubtypeInvalidArgument,
-						"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName).WithCause(dimErr).WithParams(
-						errs.InvalidParam{Name: "--width", Reason: "provide explicitly; source image dimensions could not be detected"},
-						errs.InvalidParam{Name: "--height", Reason: "provide explicitly; source image dimensions could not be detected"},
-					))
+					return withRollbackWarning(output.ErrValidation(
+						"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName))
 				}
 				dims := computeMissingDimension(userWidth, userHeight, nativeW, nativeH)
 				finalWidth = dims.width
@@ -436,7 +417,7 @@ var DocMediaInsert = common.Shortcut{
 		// Step 4: Bind file token to block via batch_update
 		fmt.Fprintf(runtime.IO().ErrOut, "Binding uploaded media to block %s\n", replaceBlockID)
 
-		if _, err := runtime.CallAPITyped("PATCH",
+		if _, err := runtime.CallAPI("PATCH",
 			fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/batch_update", validate.EncodePathSegment(documentID)),
 			nil, buildBatchUpdateData(replaceBlockID, mediaType, fileToken, alignStr, caption, finalWidth, finalHeight)); err != nil {
 			return withRollbackWarning(err)
@@ -531,10 +512,10 @@ func resolveDocxDocumentID(runtime *common.RuntimeContext, input string) (string
 	case "docx":
 		return docRef.Token, nil
 	case "doc":
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx").WithParam("--doc")
+		return "", output.ErrValidation("docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx")
 	case "wiki":
 		fmt.Fprintf(runtime.IO().ErrOut, "Resolving wiki node: %s\n", common.MaskToken(docRef.Token))
-		data, err := runtime.CallAPITyped(
+		data, err := runtime.CallAPI(
 			"GET",
 			"/open-apis/wiki/v2/spaces/get_node",
 			map[string]interface{}{"token": docRef.Token},
@@ -548,16 +529,16 @@ func resolveDocxDocumentID(runtime *common.RuntimeContext, input string) (string
 		objType := common.GetString(node, "obj_type")
 		objToken := common.GetString(node, "obj_token")
 		if objType == "" || objToken == "" {
-			return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki get_node returned incomplete node data")
+			return "", output.Errorf(output.ExitAPI, "api_error", "wiki get_node returned incomplete node data")
 		}
 		if objType != "docx" {
-			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "wiki resolved to %q, but docs +media-insert only supports docx documents", objType).WithParam("--doc")
+			return "", output.ErrValidation("wiki resolved to %q, but docs +media-insert only supports docx documents", objType)
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Resolved wiki to docx: %s\n", common.MaskToken(objToken))
 		return objToken, nil
 	default:
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "docs +media-insert only supports docx documents").WithParam("--doc")
+		return "", output.ErrValidation("docs +media-insert only supports docx documents")
 	}
 }
 
@@ -641,7 +622,7 @@ func buildBatchUpdateData(blockID, mediaType, fileToken, alignStr, caption strin
 func extractAppendTarget(rootData map[string]interface{}, fallbackBlockID string) (parentBlockID string, insertIndex int, children []interface{}, err error) {
 	block, _ := rootData["block"].(map[string]interface{})
 	if len(block) == 0 {
-		return "", 0, nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "failed to query document root block")
+		return "", 0, nil, output.Errorf(output.ExitAPI, "api_error", "failed to query document root block")
 	}
 
 	parentBlockID = fallbackBlockID
@@ -672,10 +653,12 @@ func locateInsertIndex(runtime *common.RuntimeContext, documentID string, select
 
 	matches := common.GetSlice(result, "matches")
 	if len(matches) == 0 {
-		return 0, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"locate-doc did not find any block matching selection (%s)", redactSelection(selection)).
-			WithParam("--selection-with-ellipsis").
-			WithHint("check spelling or use 'start...end' syntax to narrow the selection")
+		return 0, output.ErrWithHint(
+			output.ExitValidation,
+			"no_match",
+			fmt.Sprintf("locate-doc did not find any block matching selection (%s)", redactSelection(selection)),
+			"check spelling or use 'start...end' syntax to narrow the selection",
+		)
 	}
 	if len(matches) > 1 {
 		// Silently picking the first match surprises users whose selection appears
@@ -699,7 +682,7 @@ func locateInsertIndex(runtime *common.RuntimeContext, documentID string, select
 		}
 	}
 	if anchorBlockID == "" {
-		return 0, errs.NewInternalError(errs.SubtypeInvalidResponse, "locate-doc response missing anchor_block_id")
+		return 0, output.Errorf(output.ExitAPI, "api_error", "locate-doc response missing anchor_block_id")
 	}
 	parentBlockID := common.GetString(matchMap, "parent_block_id")
 
@@ -757,7 +740,7 @@ func locateInsertIndex(runtime *common.RuntimeContext, documentID string, select
 		nextParent = "" // clear hint after first use
 		if parent == "" || parent == cur {
 			// Need to fetch this block to find its parent.
-			data, err := runtime.CallAPITyped("GET",
+			data, err := runtime.CallAPI("GET",
 				fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/%s",
 					validate.EncodePathSegment(documentID), validate.EncodePathSegment(cur)),
 				nil, nil)
@@ -774,10 +757,12 @@ func locateInsertIndex(runtime *common.RuntimeContext, documentID string, select
 		walkDepth++
 	}
 
-	return 0, errs.NewValidationError(errs.SubtypeInvalidArgument,
-		"block matching selection (%s) is not reachable from document root", redactSelection(selection)).
-		WithParam("--selection-with-ellipsis").
-		WithHint("try a top-level heading or paragraph as the selection")
+	return 0, output.ErrWithHint(
+		output.ExitValidation,
+		"block_not_reachable",
+		fmt.Sprintf("block matching selection (%s) is not reachable from document root", redactSelection(selection)),
+		"try a top-level heading or paragraph as the selection",
+	)
 }
 
 func extractCreatedBlockTargets(createData map[string]interface{}, mediaType string) (blockID, uploadParentNode, replaceBlockID string) {

shortcuts/doc/doc_media_preview.go

@@ -10,8 +10,8 @@ import (
 
 	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/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -45,11 +45,11 @@ var DocMediaPreview = common.Shortcut{
 		overwrite := runtime.Bool("overwrite")
 
 		if err := validate.ResourceName(token, "--token"); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+			return output.ErrValidation("%s", err)
 		}
 		// Early path validation before API call (final validation after auto-extension below)
 		if _, err := runtime.ResolveSavePath(outputPath); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
+			return output.ErrValidation("unsafe output path: %s", err)
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Previewing: media %s\n", common.MaskToken(token))
@@ -65,7 +65,7 @@ var DocMediaPreview = common.Shortcut{
 			},
 		})
 		if err != nil {
-			return wrapDocNetworkErr(err, "preview failed: %v", err)
+			return output.ErrNetwork("preview failed: %v", err)
 		}
 		defer resp.Body.Close()
 
@@ -74,14 +74,14 @@ var DocMediaPreview = common.Shortcut{
 		// Validate final path after extension append
 		if finalPath != outputPath {
 			if _, err := runtime.ResolveSavePath(finalPath); err != nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
+				return output.ErrValidation("unsafe output path: %s", err)
 			}
 		}
 
 		// Overwrite check on final path (after extension detection)
 		if !overwrite {
 			if _, statErr := runtime.FileIO().Stat(finalPath); statErr == nil {
-				return errs.NewValidationError(errs.SubtypeFailedPrecondition, "output file already exists: %s (use --overwrite to replace)", finalPath).WithParam("--output")
+				return output.ErrValidation("output file already exists: %s (use --overwrite to replace)", finalPath)
 			}
 		}
 
@@ -90,7 +90,7 @@ var DocMediaPreview = common.Shortcut{
 			ContentLength: resp.ContentLength,
 		}, resp.Body)
 		if err != nil {
-			return common.WrapSaveErrorTyped(err)
+			return common.WrapSaveErrorByCategory(err, "io")
 		}
 
 		savedPath, _ := runtime.ResolveSavePath(finalPath)

shortcuts/doc/doc_media_upload.go

@@ -9,8 +9,8 @@ import (
 	"io"
 	"path/filepath"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -84,10 +84,10 @@ var DocMediaUpload = common.Shortcut{
 		// Validate file
 		stat, err := runtime.FileIO().Stat(filePath)
 		if err != nil {
-			return wrapDocInputFileErr(err, "file not found")
+			return common.WrapInputStatError(err, "file not found")
 		}
 		if !stat.Mode().IsRegular() {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "file must be a regular file: %s", filePath).WithParam("--file")
+			return output.ErrValidation("file must be a regular file: %s", filePath)
 		}
 
 		fileName := filepath.Base(filePath)

shortcuts/doc/docs_create_v2.go

@@ -7,7 +7,6 @@ import (
 	"context"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -26,13 +25,10 @@ func validateCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
 		return err
 	}
 	if runtime.Str("content") == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is required").WithParam("--content")
+		return common.FlagErrorf("--content is required")
 	}
 	if runtime.Str("parent-token") != "" && runtime.Str("parent-position") != "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--parent-token and --parent-position are mutually exclusive").WithParams(
-			errs.InvalidParam{Name: "--parent-token", Reason: "mutually exclusive with --parent-position"},
-			errs.InvalidParam{Name: "--parent-position", Reason: "mutually exclusive with --parent-token"},
-		)
+		return common.FlagErrorf("--parent-token and --parent-position are mutually exclusive")
 	}
 	return nil
 }

shortcuts/doc/docs_fetch_v2.go

@@ -10,7 +10,6 @@ import (
 	"strconv"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -38,7 +37,7 @@ func validateFetchV2(_ context.Context, runtime *common.RuntimeContext) error {
 		return err
 	}
 	if _, err := parseDocumentRef(runtime.Str("doc")); err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --doc: %v", err).WithParam("--doc")
+		return common.FlagErrorf("invalid --doc: %v", err)
 	}
 	if err := validateFetchDetail(runtime); err != nil {
 		return err
@@ -154,7 +153,7 @@ func validateFetchDetail(runtime *common.RuntimeContext) error {
 		return nil
 	}
 	if detail == "with-ids" || detail == "full" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--detail %s is only supported with --doc-format xml; %s output has no block ids, use --detail simple or switch to --doc-format xml", detail, format).WithParam("--detail")
+		return common.FlagErrorf("--detail %s is only supported with --doc-format xml; %s output has no block ids, use --detail simple or switch to --doc-format xml", detail, format)
 	}
 	return nil
 }
@@ -167,13 +166,13 @@ func validateReadModeFlags(runtime *common.RuntimeContext) error {
 	}
 
 	if v := runtime.Int("context-before"); v < 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--context-before must be >= 0, got %d", v).WithParam("--context-before")
+		return common.FlagErrorf("--context-before must be >= 0, got %d", v)
 	}
 	if v := runtime.Int("context-after"); v < 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--context-after must be >= 0, got %d", v).WithParam("--context-after")
+		return common.FlagErrorf("--context-after must be >= 0, got %d", v)
 	}
 	if v := runtime.Int("max-depth"); v < -1 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--max-depth must be >= -1, got %d", v).WithParam("--max-depth")
+		return common.FlagErrorf("--max-depth must be >= -1, got %d", v)
 	}
 
 	switch mode {
@@ -182,23 +181,20 @@ func validateReadModeFlags(runtime *common.RuntimeContext) error {
 	case "range":
 		if strings.TrimSpace(runtime.Str("start-block-id")) == "" &&
 			strings.TrimSpace(runtime.Str("end-block-id")) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "range mode requires --start-block-id or --end-block-id").WithParams(
-				errs.InvalidParam{Name: "--start-block-id", Reason: "provide --start-block-id or --end-block-id for range mode"},
-				errs.InvalidParam{Name: "--end-block-id", Reason: "provide --start-block-id or --end-block-id for range mode"},
-			)
+			return common.FlagErrorf("range mode requires --start-block-id or --end-block-id")
 		}
 		return nil
 	case "keyword":
 		if strings.TrimSpace(runtime.Str("keyword")) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "keyword mode requires --keyword").WithParam("--keyword")
+			return common.FlagErrorf("keyword mode requires --keyword")
 		}
 		return nil
 	case "section":
 		if strings.TrimSpace(runtime.Str("start-block-id")) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "section mode requires --start-block-id").WithParam("--start-block-id")
+			return common.FlagErrorf("section mode requires --start-block-id")
 		}
 		return nil
 	default:
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --scope %q", mode).WithParam("--scope")
+		return common.FlagErrorf("invalid --scope %q", mode)
 	}
 }

shortcuts/doc/docs_search.go

@@ -14,7 +14,6 @@ import (
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -59,7 +58,7 @@ var DocsSearch = common.Shortcut{
 			return err
 		}
 
-		data, err := runtime.CallAPITyped("POST", "/open-apis/search/v2/doc_wiki/search", nil, requestData)
+		data, err := runtime.CallAPI("POST", "/open-apis/search/v2/doc_wiki/search", nil, requestData)
 		if err != nil {
 			return err
 		}
@@ -160,7 +159,7 @@ func buildDocsSearchRequest(query, filterStr, pageToken, pageSizeStr string) (ma
 
 	var filter map[string]interface{}
 	if err := json.Unmarshal([]byte(filterStr), &filter); err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--filter is not valid JSON").WithParam("--filter").WithCause(err)
+		return nil, output.ErrValidation("--filter is not valid JSON")
 	}
 	if err := convertTimeRangeInFilter(filter, "open_time"); err != nil {
 		return nil, err
@@ -173,7 +172,7 @@ func buildDocsSearchRequest(query, filterStr, pageToken, pageSizeStr string) (ma
 	hasSpaceIDs := hasNonEmptyFilterArray(filter, "space_ids")
 
 	if hasFolderTokens && hasSpaceIDs {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--filter cannot contain both folder_tokens and space_ids; doc and wiki scoped search cannot be combined").WithParam("--filter")
+		return nil, output.ErrValidation("--filter cannot contain both folder_tokens and space_ids; doc and wiki scoped search cannot be combined")
 	}
 
 	docFilter := cloneFilterMap(filter)
@@ -226,14 +225,14 @@ func convertTimeRangeInFilter(filter map[string]interface{}, key string) error {
 	if start, ok := rangeMap["start"].(string); ok && start != "" {
 		startTime, err := toUnixSeconds(start)
 		if err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid %s.start %q: %s", key, start, err).WithParam("--filter").WithCause(err)
+			return output.ErrValidation("invalid %s.start %q: %s", key, start, err)
 		}
 		result["start"] = startTime
 	}
 	if end, ok := rangeMap["end"].(string); ok && end != "" {
 		endTime, err := toUnixSeconds(end)
 		if err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid %s.end %q: %s", key, end, err).WithParam("--filter").WithCause(err)
+			return output.ErrValidation("invalid %s.end %q: %s", key, end, err)
 		}
 		result["end"] = endTime
 	}
@@ -257,7 +256,7 @@ func toUnixSeconds(input string) (int64, error) {
 	if n, err := strconv.ParseInt(input, 10, 64); err == nil {
 		return n, nil
 	}
-	return 0, fmt.Errorf("expected RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds") //nolint:forbidigo // intermediate parse helper; caller wraps into typed ValidationError
+	return 0, fmt.Errorf("expected RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds")
 }
 
 func unixTimestampToISO8601(v interface{}) string {

shortcuts/doc/docs_update_v2.go

@@ -7,7 +7,6 @@ import (
 	"context"
 	"fmt"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -25,11 +24,11 @@ var validCommandsV2 = map[string]bool{
 // v2UpdateFlags returns the flag definitions for the v2 (OpenAPI) update path.
 func v2UpdateFlags() []common.Flag {
 	return []common.Flag{
-		{Name: "command", Desc: "operation; requirements: str_replace(--pattern), block_delete(--block-id, comma-separated for batch), block_insert_after/block_replace(--block-id,--content), block_copy_insert_after/block_move_after(--block-id,--src-block-ids), overwrite/append(--content)", Enum: validCommandsV2Keys()},
+		{Name: "command", Desc: "operation; requirements: str_replace(--pattern), block_delete(--block-id), block_insert_after/block_replace(--block-id,--content), block_copy_insert_after/block_move_after(--block-id,--src-block-ids), overwrite/append(--content)", Enum: validCommandsV2Keys()},
 		{Name: "doc-format", Desc: "content format for --content; xml is default for precise rich edits, markdown for user-provided Markdown or plain append/overwrite", Default: "xml", Enum: []string{"xml", "markdown"}},
 		{Name: "content", Desc: "replacement or inserted content; XML by default or Markdown when --doc-format markdown; empty with str_replace deletes match. " + docsContentSkillHelp + "; use --help for the latest command flags", Input: []string{common.File, common.Stdin}},
 		{Name: "pattern", Desc: "str_replace match pattern; XML mode is inline text, Markdown mode can match multiline text"},
-		{Name: "block-id", Desc: "target block ID(s) for block operations (comma-separated for batch delete); -1 means document end where supported"},
+		{Name: "block-id", Desc: "target anchor/block id for block operations; -1 means document end where supported"},
 		{Name: "src-block-ids", Desc: "comma-separated source block ids for block_copy_insert_after and block_move_after"},
 		{Name: "revision-id", Desc: "base revision id; -1 means latest", Type: "int", Default: "-1"},
 	}
@@ -44,14 +43,14 @@ func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 		return err
 	}
 	if _, err := parseDocumentRef(runtime.Str("doc")); err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --doc: %v", err).WithParam("--doc")
+		return common.FlagErrorf("invalid --doc: %v", err)
 	}
 	cmd := runtime.Str("command")
 	if cmd == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command is required").WithParam("--command")
+		return common.FlagErrorf("--command is required")
 	}
 	if !validCommandsV2[cmd] {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --command %q, valid: str_replace | block_delete | block_insert_after | block_copy_insert_after | block_replace | block_move_after | overwrite | append", cmd).WithParam("--command")
+		return common.FlagErrorf("invalid --command %q, valid: str_replace | block_delete | block_insert_after | block_copy_insert_after | block_replace | block_move_after | overwrite | append", cmd)
 	}
 	content := runtime.Str("content")
 	pattern := runtime.Str("pattern")
@@ -61,50 +60,50 @@ func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 	switch cmd {
 	case "str_replace":
 		if pattern == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command str_replace requires --pattern").WithParam("--pattern")
+			return common.FlagErrorf("--command str_replace requires --pattern")
 		}
 	case "block_delete":
 		if blockID == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_delete requires --block-id").WithParam("--block-id")
+			return common.FlagErrorf("--command block_delete requires --block-id")
 		}
 	case "block_insert_after":
 		if blockID == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_insert_after requires --block-id").WithParam("--block-id")
+			return common.FlagErrorf("--command block_insert_after requires --block-id")
 		}
 		if content == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_insert_after requires --content").WithParam("--content")
+			return common.FlagErrorf("--command block_insert_after requires --content")
 		}
 	case "block_copy_insert_after":
 		if blockID == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_copy_insert_after requires --block-id").WithParam("--block-id")
+			return common.FlagErrorf("--command block_copy_insert_after requires --block-id")
 		}
 		if srcBlockIDs == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_copy_insert_after requires --src-block-ids").WithParam("--src-block-ids")
+			return common.FlagErrorf("--command block_copy_insert_after requires --src-block-ids")
 		}
 	case "block_move_after":
 		if blockID == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_move_after requires --block-id").WithParam("--block-id")
+			return common.FlagErrorf("--command block_move_after requires --block-id")
 		}
 		if srcBlockIDs == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_move_after requires --src-block-ids").WithParam("--src-block-ids")
+			return common.FlagErrorf("--command block_move_after requires --src-block-ids")
 		}
 		if content != "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_move_after does not accept --content; use --src-block-ids").WithParam("--content")
+			return common.FlagErrorf("--command block_move_after does not accept --content; use --src-block-ids")
 		}
 	case "block_replace":
 		if blockID == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_replace requires --block-id").WithParam("--block-id")
+			return common.FlagErrorf("--command block_replace requires --block-id")
 		}
 		if content == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_replace requires --content").WithParam("--content")
+			return common.FlagErrorf("--command block_replace requires --content")
 		}
 	case "overwrite":
 		if content == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command overwrite requires --content").WithParam("--content")
+			return common.FlagErrorf("--command overwrite requires --content")
 		}
 	case "append":
 		if content == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command append requires --content").WithParam("--content")
+			return common.FlagErrorf("--command append requires --content")
 		}
 	}
 	return nil

shortcuts/doc/helpers.go

@@ -8,7 +8,7 @@ import (
 	"encoding/json"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -24,7 +24,7 @@ type documentRef struct {
 func parseDocumentRef(input string) (documentRef, error) {
 	raw := strings.TrimSpace(input)
 	if raw == "" {
-		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--doc cannot be empty").WithParam("--doc")
+		return documentRef{}, output.ErrValidation("--doc cannot be empty")
 	}
 
 	if token, ok := extractDocumentToken(raw, "/wiki/"); ok {
@@ -37,10 +37,10 @@ func parseDocumentRef(input string) (documentRef, error) {
 		return documentRef{Kind: "doc", Token: token}, nil
 	}
 	if strings.Contains(raw, "://") {
-		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --doc input %q: use a docx URL/token or a wiki URL that resolves to docx", raw).WithParam("--doc")
+		return documentRef{}, output.ErrValidation("unsupported --doc input %q: use a docx URL/token or a wiki URL that resolves to docx", raw)
 	}
 	if strings.ContainsAny(raw, "/?#") {
-		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --doc input %q: use a docx token or a wiki URL", raw).WithParam("--doc")
+		return documentRef{}, output.ErrValidation("unsupported --doc input %q: use a docx token or a wiki URL", raw)
 	}
 
 	return documentRef{Kind: "docx", Token: raw}, nil
@@ -64,10 +64,10 @@ func extractDocumentToken(raw, marker string) (string, bool) {
 
 // doDocAPI executes an OpenAPI request against the docs_ai endpoints and returns
 // the parsed "data" field from the standard Lark response envelope {code, msg, data}.
-// CallAPITyped lifts the x-tt-logid response header onto the typed error so log_id
-// surfaces for support escalations even when the body omits it.
+// Uses the log-id-aware variant so the x-tt-logid header is surfaced in both the
+// success payload and error details — doc v2 callers rely on it for support escalations.
 func doDocAPI(runtime *common.RuntimeContext, method, apiPath string, body interface{}) (map[string]interface{}, error) {
-	return runtime.CallAPITyped(method, apiPath, nil, body)
+	return runtime.DoAPIJSONWithLogID(method, apiPath, nil, body)
 }
 
 func docsSceneFromContext(ctx context.Context) string {
@@ -87,7 +87,7 @@ func injectDocsScene(runtime *common.RuntimeContext, body map[string]interface{}
 func buildDriveRouteExtra(docID string) (string, error) {
 	extra, err := json.Marshal(map[string]string{"drive_route_token": docID})
 	if err != nil {
-		return "", errs.NewInternalError(errs.SubtypeUnknown, "failed to marshal upload extra data: %v", err).WithCause(err)
+		return "", output.Errorf(output.ExitInternal, "internal_error", "failed to marshal upload extra data: %v", err)
 	}
 	return string(extra), nil
 }

shortcuts/doc/v2_only.go

@@ -6,7 +6,6 @@ package doc
 import (
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -66,7 +65,7 @@ func validateDocsV2Only(runtime *common.RuntimeContext, shortcut string, legacyF
 	switch apiVersion := strings.TrimSpace(runtime.Str("api-version")); apiVersion {
 	case "", "v1", "v2":
 	default:
-		return docsV2OnlyError(shortcut, "--api-version is deprecated and only accepts v1 or v2; both values execute the v2 API", "--api-version")
+		return docsV2OnlyError(shortcut, "--api-version is deprecated and only accepts v1 or v2; both values execute the v2 API")
 	}
 
 	var used []string
@@ -88,12 +87,11 @@ func validateDocsV2Only(runtime *common.RuntimeContext, shortcut string, legacyF
 	if len(replacements) > 0 {
 		detail += "; " + strings.Join(replacements, "; ")
 	}
-	return docsV2OnlyError(shortcut, detail, used[0])
+	return docsV2OnlyError(shortcut, detail)
 }
 
-func docsV2OnlyError(shortcut, detail, param string) error {
-	err := errs.NewValidationError(
-		errs.SubtypeInvalidArgument,
+func docsV2OnlyError(shortcut, detail string) error {
+	return common.FlagErrorf(
 		"docs %s is v2-only; %s. Run `%s` for the current schema and examples. AI agents MUST read `%s` (XML) or `%s` (Markdown) and follow the latest format rules there. MUST NOT grep/open local SKILL.md files to discover this guidance; use `lark-cli skills read ...` so content stays version-matched with this CLI. Run `%s` for the latest command flags",
 		shortcut,
 		detail,
@@ -102,8 +100,4 @@ func docsV2OnlyError(shortcut, detail, param string) error {
 		docsMDSkillReadCommand,
 		docsHelpCommandForShortcut(shortcut),
 	)
-	if param != "" {
-		err = err.WithParam(param)
-	}
-	return err
 }

shortcuts/drive/drive_add_comment.go

@@ -133,7 +133,7 @@ var DriveAddComment = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "doc", Desc: "document URL/token, file URL/token, sheet/slides URL, or wiki URL that resolves to doc/docx/file/sheet/slides", Required: true},
 		{Name: "type", Desc: "document type: doc, docx, file, sheet, slides (required when --doc is a bare token; auto-detected for URLs)", Enum: []string{"doc", "docx", "file", "sheet", "slides"}},
-		{Name: "content", Desc: "reply_elements JSON string", Required: true, Input: []string{common.File, common.Stdin}},
+		{Name: "content", Desc: "reply_elements JSON string", Required: true},
 		{Name: "full-comment", Type: "bool", Desc: "create a full-document comment; also the default when no location is provided"},
 		{Name: "selection-with-ellipsis", Desc: "target content locator (plain text or 'start...end')"},
 		{Name: "block-id", Desc: "for docx: anchor block ID; for sheet: <sheetId>!<cell> (e.g. a281f9!D6); for slides: <slide-block-type>!<xml-id> (e.g. shape!bPq)"},

shortcuts/event/errors.go

@@ -1,32 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package event
-
-import "github.com/larksuite/cli/errs"
-
-func eventValidationError(format string, args ...any) *errs.ValidationError {
-	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...)
-}
-
-func eventValidationParamError(param, format string, args ...any) *errs.ValidationError {
-	return eventValidationError(format, args...).WithParam(param)
-}
-
-// eventValidationParamErrorWithCause appends ": <err>" to the formatted
-// message and preserves err as the unwrap cause.
-func eventValidationParamErrorWithCause(err error, param, format string, args ...any) *errs.ValidationError {
-	return eventValidationParamError(param, format+": %s", append(args, err)...).WithCause(err)
-}
-
-// eventFileIOError appends ": <err>" to the formatted message and preserves
-// err as the unwrap cause.
-func eventFileIOError(err error, format string, args ...any) *errs.InternalError {
-	return errs.NewInternalError(errs.SubtypeFileIO, format+": %s", append(args, err)...).WithCause(err)
-}
-
-// eventNetworkError appends ": <err>" to the formatted message and preserves
-// err as the unwrap cause.
-func eventNetworkError(err error, format string, args ...any) *errs.NetworkError {
-	return errs.NewNetworkError(errs.SubtypeNetworkTransport, format+": %s", append(args, err)...).WithCause(err)
-}

shortcuts/event/pipeline.go

@@ -63,13 +63,13 @@ func NewEventPipeline(
 func (p *EventPipeline) EnsureDirs() error {
 	if p.config.OutputDir != "" {
 		if err := vfs.MkdirAll(p.config.OutputDir, 0700); err != nil {
-			return eventFileIOError(err, "create output dir")
+			return fmt.Errorf("create output dir: %w", err)
 		}
 	}
 	if p.config.Router != nil {
 		for _, route := range p.config.Router.routes {
 			if err := vfs.MkdirAll(route.dir, 0700); err != nil {
-				return eventFileIOError(err, "create route dir %s", route.dir)
+				return fmt.Errorf("create route dir %s: %w", route.dir, err)
 			}
 		}
 	}

shortcuts/event/processor_test.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"io"
 	"os"
 	"path/filepath"
@@ -16,13 +15,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/lockfile"
-	"github.com/larksuite/cli/shortcuts/common"
 	larkevent "github.com/larksuite/oapi-sdk-go/v3/event"
-	"github.com/spf13/cobra"
 )
 
 // chdirTemp changes cwd to a fresh temp dir for the test duration.
@@ -51,87 +44,6 @@ func makeRawEvent(eventType string, eventJSON string) *RawEvent {
 	}
 }
 
-func requireProblem(t *testing.T, err error, category errs.Category, subtype errs.Subtype, param string) {
-	t.Helper()
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("ProblemOf(%T) = false, error: %v", err, err)
-	}
-	if p.Category != category || p.Subtype != subtype {
-		t.Fatalf("problem = %s/%s, want %s/%s", p.Category, p.Subtype, category, subtype)
-	}
-	if param != "" {
-		var ve *errs.ValidationError
-		if !errors.As(err, &ve) {
-			t.Fatalf("error %T is not *errs.ValidationError", err)
-		}
-		if ve.Param != param {
-			t.Fatalf("Param = %q, want %q", ve.Param, param)
-		}
-	}
-}
-
-func TestEventTypedErrorHelpers(t *testing.T) {
-	cause := errors.New("cause")
-
-	validation := eventValidationError("bad input")
-	requireProblem(t, validation, errs.CategoryValidation, errs.SubtypeInvalidArgument, "")
-
-	paramErr := eventValidationParamErrorWithCause(cause, "--flag", "bad %s value", "flag")
-	requireProblem(t, paramErr, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--flag")
-	if got := paramErr.Error(); got != "bad flag value: cause" {
-		t.Fatalf("message = %q, want %q", got, "bad flag value: cause")
-	}
-	if !errors.Is(paramErr, cause) {
-		t.Fatal("validation error should preserve its cause")
-	}
-
-	fileErr := eventFileIOError(cause, "write failed")
-	requireProblem(t, fileErr, errs.CategoryInternal, errs.SubtypeFileIO, "")
-	if got := fileErr.Error(); got != "write failed: cause" {
-		t.Fatalf("message = %q, want %q", got, "write failed: cause")
-	}
-	if !errors.Is(fileErr, cause) {
-		t.Fatal("file_io error should preserve its cause")
-	}
-
-	networkErr := eventNetworkError(cause, "websocket failed")
-	requireProblem(t, networkErr, errs.CategoryNetwork, errs.SubtypeNetworkTransport, "")
-	if got := networkErr.Error(); got != "websocket failed: cause" {
-		t.Fatalf("message = %q, want %q", got, "websocket failed: cause")
-	}
-	if !errors.Is(networkErr, cause) {
-		t.Fatal("network error should preserve its cause")
-	}
-}
-
-func newSubscribeTestRuntime(t *testing.T) *common.RuntimeContext {
-	t.Helper()
-
-	var out, errOut bytes.Buffer
-	cmd := &cobra.Command{Use: "+subscribe"}
-	cmd.Flags().String("event-types", "", "")
-	cmd.Flags().String("filter", "", "")
-	cmd.Flags().Bool("json", false, "")
-	cmd.Flags().Bool("compact", false, "")
-	cmd.Flags().String("output-dir", "", "")
-	cmd.Flags().Bool("quiet", false, "")
-	cmd.Flags().StringArray("route", nil, "")
-	cmd.Flags().Bool("force", false, "")
-
-	return &common.RuntimeContext{
-		Cmd: cmd,
-		Config: &core.CliConfig{
-			AppID:     "cli_event_test",
-			AppSecret: "secret",
-			Brand:     core.BrandFeishu,
-		},
-		Factory: &cmdutil.Factory{
-			IOStreams: cmdutil.NewIOStreams(strings.NewReader(""), &out, &errOut),
-		},
-	}
-}
-
 // --- Registry ---
 
 func TestRegistryLookup(t *testing.T) {
@@ -151,11 +63,9 @@ func TestRegistryDuplicateReturnsError(t *testing.T) {
 	if err := r.Register(&ImMessageProcessor{}); err != nil {
 		t.Fatalf("first register should succeed: %v", err)
 	}
-	err := r.Register(&ImMessageProcessor{})
-	if err == nil {
+	if err := r.Register(&ImMessageProcessor{}); err == nil {
 		t.Error("expected error on duplicate registration")
 	}
-	requireProblem(t, err, errs.CategoryInternal, errs.SubtypeUnknown, "")
 }
 
 // --- Filters ---
@@ -196,54 +106,6 @@ func TestRegexFilter_Invalid(t *testing.T) {
 	}
 }
 
-func TestEventSubscribeExecuteRejectsUnsafeOutputDir(t *testing.T) {
-	rt := newSubscribeTestRuntime(t)
-	if err := rt.Cmd.Flags().Set("output-dir", "/tmp/events"); err != nil {
-		t.Fatal(err)
-	}
-	err := EventSubscribe.Execute(context.Background(), rt)
-	if err == nil {
-		t.Fatal("expected unsafe output-dir error")
-	}
-	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--output-dir")
-	if errors.Unwrap(err) == nil {
-		t.Fatal("unsafe output-dir error should preserve its cause")
-	}
-}
-
-func TestEventSubscribeExecuteRejectsInvalidFilter(t *testing.T) {
-	rt := newSubscribeTestRuntime(t)
-	if err := rt.Cmd.Flags().Set("force", "true"); err != nil {
-		t.Fatal(err)
-	}
-	if err := rt.Cmd.Flags().Set("filter", "[invalid"); err != nil {
-		t.Fatal(err)
-	}
-	err := EventSubscribe.Execute(context.Background(), rt)
-	if err == nil {
-		t.Fatal("expected invalid filter error")
-	}
-	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--filter")
-	if errors.Unwrap(err) == nil {
-		t.Fatal("invalid filter error should preserve its cause")
-	}
-}
-
-func TestEventSubscribeExecuteRejectsInvalidRoute(t *testing.T) {
-	rt := newSubscribeTestRuntime(t)
-	if err := rt.Cmd.Flags().Set("force", "true"); err != nil {
-		t.Fatal(err)
-	}
-	if err := rt.Cmd.Flags().Set("route", "no-equals-sign"); err != nil {
-		t.Fatal(err)
-	}
-	err := EventSubscribe.Execute(context.Background(), rt)
-	if err == nil {
-		t.Fatal("expected invalid route error")
-	}
-	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
-}
-
 func TestFilterChain(t *testing.T) {
 	etf := NewEventTypeFilter("im.message.receive_v1, drive.file.edit_v1")
 	rf, _ := NewRegexFilter("im\\..*")
@@ -477,106 +339,6 @@ func TestPipeline_OutputDir(t *testing.T) {
 	}
 }
 
-func TestEventSubscribeExecuteRejectsHeldLock(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	lock, err := lockfile.ForSubscribe("cli_event_test")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := lock.TryLock(); err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(func() { _ = lock.Unlock() })
-
-	rt := newSubscribeTestRuntime(t)
-	execErr := EventSubscribe.Execute(context.Background(), rt)
-	if execErr == nil {
-		t.Fatal("expected lock-held error")
-	}
-	requireProblem(t, execErr, errs.CategoryValidation, errs.SubtypeFailedPrecondition, "")
-	if !errors.Is(execErr, lockfile.ErrHeld) {
-		t.Error("lock-held error should preserve lockfile.ErrHeld for errors.Is")
-	}
-	p, _ := errs.ProblemOf(execErr)
-	if p.Hint == "" {
-		t.Error("lock-held error should carry a recovery hint")
-	}
-	var ve *errs.ValidationError
-	if errors.As(execErr, &ve) && ve.Param != "" {
-		t.Errorf("lock contention names no offending flag; param = %q, want empty", ve.Param)
-	}
-}
-
-func TestEventSubscribeDryRunEchoesFlags(t *testing.T) {
-	rt := newSubscribeTestRuntime(t)
-	for flag, value := range map[string]string{
-		"event-types": "im.message.receive_v1",
-		"filter":      "^im\\.",
-		"output-dir":  "events_out",
-	} {
-		if err := rt.Cmd.Flags().Set(flag, value); err != nil {
-			t.Fatal(err)
-		}
-	}
-	if err := rt.Cmd.Flags().Set("route", "^im\\.message=dir:./messages"); err != nil {
-		t.Fatal(err)
-	}
-
-	d := EventSubscribe.DryRun(context.Background(), rt)
-	if d == nil {
-		t.Fatal("DryRun returned nil")
-	}
-	payload, err := json.Marshal(d)
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, want := range []string{
-		`"command":"event +subscribe"`,
-		`"app_id":"cli_event_test"`,
-		`"event_types":"im.message.receive_v1"`,
-		`"output_dir":"events_out"`,
-	} {
-		if !strings.Contains(string(payload), want) {
-			t.Errorf("dry-run payload missing %s\ngot: %s", want, payload)
-		}
-	}
-}
-
-func TestPipeline_EnsureDirsRouteDirFileIOError(t *testing.T) {
-	chdirTemp(t)
-	if err := os.WriteFile("blocked", []byte("x"), 0600); err != nil {
-		t.Fatal(err)
-	}
-	router, err := ParseRoutes([]string{`^im\.=dir:./blocked/child`})
-	if err != nil {
-		t.Fatalf("ParseRoutes: %v", err)
-	}
-	p := NewEventPipeline(DefaultRegistry(), NewFilterChain(),
-		PipelineConfig{Mode: TransformCompact, Router: router}, io.Discard, io.Discard)
-	err = p.EnsureDirs()
-	if err == nil {
-		t.Fatal("expected file_io error for route dir blocked by a file")
-	}
-	requireProblem(t, err, errs.CategoryInternal, errs.SubtypeFileIO, "")
-}
-
-func TestPipeline_EnsureDirsFileIOError(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "not-a-dir")
-	if err := os.WriteFile(path, []byte("x"), 0600); err != nil {
-		t.Fatal(err)
-	}
-	p := NewEventPipeline(DefaultRegistry(), NewFilterChain(),
-		PipelineConfig{Mode: TransformCompact, OutputDir: filepath.Join(path, "child")}, io.Discard, io.Discard)
-	err := p.EnsureDirs()
-	if err == nil {
-		t.Fatal("expected file_io error")
-	}
-	requireProblem(t, err, errs.CategoryInternal, errs.SubtypeFileIO, "")
-	if errors.Unwrap(err) == nil {
-		t.Fatal("file_io error should preserve its cause")
-	}
-}
-
 // --- Pipeline: JsonFlag ---
 
 func TestPipeline_JsonFlag(t *testing.T) {
@@ -846,7 +608,6 @@ func TestParseRoutes_MissingEquals(t *testing.T) {
 	if err == nil {
 		t.Error("expected error for missing =")
 	}
-	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 }
 
 func TestParseRoutes_InvalidRegex(t *testing.T) {
@@ -854,10 +615,6 @@ func TestParseRoutes_InvalidRegex(t *testing.T) {
 	if err == nil {
 		t.Error("expected error for invalid regex")
 	}
-	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
-	if errors.Unwrap(err) == nil {
-		t.Fatal("invalid regex error should preserve its cause")
-	}
 }
 
 func TestParseRoutes_MissingPrefix(t *testing.T) {
@@ -865,7 +622,6 @@ func TestParseRoutes_MissingPrefix(t *testing.T) {
 	if err == nil {
 		t.Error("expected error for missing dir: prefix")
 	}
-	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 	if !strings.Contains(err.Error(), "dir:") {
 		t.Errorf("error should mention dir: prefix, got: %v", err)
 	}
@@ -876,7 +632,6 @@ func TestParseRoutes_EmptyPath(t *testing.T) {
 	if err == nil {
 		t.Error("expected error for empty path")
 	}
-	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 }
 
 func TestParseRoutes_RejectsAbsolutePath(t *testing.T) {
@@ -884,7 +639,6 @@ func TestParseRoutes_RejectsAbsolutePath(t *testing.T) {
 	if err == nil {
 		t.Error("expected error for absolute path in route")
 	}
-	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 }
 
 func TestParseRoutes_RejectsTraversal(t *testing.T) {
@@ -892,7 +646,6 @@ func TestParseRoutes_RejectsTraversal(t *testing.T) {
 	if err == nil {
 		t.Error("expected error for path traversal in route")
 	}
-	requireProblem(t, err, errs.CategoryValidation, errs.SubtypeInvalidArgument, "--route")
 }
 
 func TestParseRoutes_PathSafety(t *testing.T) {

shortcuts/event/registry.go

@@ -3,7 +3,7 @@
 
 package event
 
-import "github.com/larksuite/cli/errs"
+import "fmt"
 
 // ProcessorRegistry manages event_type → EventProcessor mappings.
 type ProcessorRegistry struct {
@@ -23,7 +23,7 @@ func NewProcessorRegistry(fallback EventProcessor) *ProcessorRegistry {
 func (r *ProcessorRegistry) Register(p EventProcessor) error {
 	et := p.EventType()
 	if _, exists := r.processors[et]; exists {
-		return errs.NewInternalError(errs.SubtypeUnknown, "duplicate event processor for: %s", et)
+		return fmt.Errorf("duplicate event processor for: %s", et)
 	}
 	r.processors[et] = p
 	return nil

shortcuts/event/router.go

@@ -4,6 +4,7 @@
 package event
 
 import (
+	"fmt"
 	"regexp"
 	"strings"
 
@@ -33,27 +34,27 @@ func ParseRoutes(specs []string) (*EventRouter, error) {
 	for _, spec := range specs {
 		parts := strings.SplitN(spec, "=", 2)
 		if len(parts) != 2 {
-			return nil, eventValidationParamError("--route", "invalid --route %q: expected format regex=dir:./path", spec)
+			return nil, fmt.Errorf("invalid route %q: expected format regex=dir:./path", spec)
 		}
 		pattern := parts[0]
 		target := parts[1]
 
 		re, err := regexp.Compile(pattern)
 		if err != nil {
-			return nil, eventValidationParamErrorWithCause(err, "--route", "invalid regex in --route %q", spec)
+			return nil, fmt.Errorf("invalid regex in route %q: %w", spec, err)
 		}
 
 		if !strings.HasPrefix(target, "dir:") {
-			return nil, eventValidationParamError("--route", "invalid --route target %q: must start with \"dir:\" prefix (format: regex=dir:./path)", target)
+			return nil, fmt.Errorf("invalid route target %q: must start with \"dir:\" prefix (format: regex=dir:./path)", target)
 		}
 		dir := strings.TrimPrefix(target, "dir:")
 		if dir == "" {
-			return nil, eventValidationParamError("--route", "invalid --route %q: directory path is empty", spec)
+			return nil, fmt.Errorf("invalid route %q: directory path is empty", spec)
 		}
 
 		safeDir, err := validate.SafeOutputPath(dir)
 		if err != nil {
-			return nil, eventValidationParamErrorWithCause(err, "--route", "invalid --route %q", spec)
+			return nil, fmt.Errorf("invalid route %q: %w", spec, err)
 		}
 
 		routes = append(routes, Route{pattern: re, dir: safeDir})

shortcuts/event/subscribe.go

@@ -6,7 +6,6 @@ package event
 import (
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -14,7 +13,6 @@ import (
 	"strings"
 	"syscall"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/lockfile"
 	"github.com/larksuite/cli/internal/output"
@@ -146,7 +144,7 @@ var EventSubscribe = common.Shortcut{
 		if outputDir != "" {
 			safePath, err := validate.SafeOutputPath(outputDir)
 			if err != nil {
-				return eventValidationParamErrorWithCause(err, "--output-dir", "unsafe --output-dir")
+				return output.ErrValidation("unsafe output path: %s", err)
 			}
 			outputDir = safePath
 		}
@@ -164,18 +162,15 @@ var EventSubscribe = common.Shortcut{
 		if !forceFlag {
 			lock, err := lockfile.ForSubscribe(runtime.Config.AppID)
 			if err != nil {
-				return eventFileIOError(err, "failed to create event subscriber lock")
+				return fmt.Errorf("failed to create lock: %w", err)
 			}
 			if err := lock.TryLock(); err != nil {
-				if errors.Is(err, lockfile.ErrHeld) {
-					return errs.NewValidationError(errs.SubtypeFailedPrecondition,
-						"another event +subscribe instance is already running for app %s\n"+
-							"  Only one subscriber per app is allowed to prevent competing consumers.\n"+
-							"  Use --force to bypass this check.",
-						runtime.Config.AppID,
-					).WithHint("stop the existing subscriber for this app, or rerun with --force if you accept split event delivery").WithCause(err)
-				}
-				return eventFileIOError(err, "failed to acquire event subscriber lock")
+				return output.ErrValidation(
+					"another event +subscribe instance is already running for app %s\n"+
+						"  Only one subscriber per app is allowed to prevent competing consumers.\n"+
+						"  Use --force to bypass this check.",
+					runtime.Config.AppID,
+				)
 			}
 			defer lock.Unlock()
 		}
@@ -184,7 +179,7 @@ var EventSubscribe = common.Shortcut{
 		eventTypeFilter := NewEventTypeFilter(eventTypesStr)
 		regexFilter, err := NewRegexFilter(filterStr)
 		if err != nil {
-			return eventValidationParamErrorWithCause(err, "--filter", "invalid --filter regex %q", filterStr)
+			return output.ErrValidation("invalid --filter regex: %s", filterStr)
 		}
 		var filterList []EventFilter
 		if eventTypeFilter != nil {
@@ -198,7 +193,7 @@ var EventSubscribe = common.Shortcut{
 		// --- Parse route ---
 		router, err := ParseRoutes(routeSpecs)
 		if err != nil {
-			return err
+			return output.ErrValidation("invalid --route: %v", err)
 		}
 
 		// --- Build pipeline ---
@@ -297,7 +292,7 @@ var EventSubscribe = common.Shortcut{
 				return nil
 			}
 			if err != nil {
-				return eventNetworkError(err, "WebSocket connection failed")
+				return output.ErrNetwork("WebSocket connection failed: %v", err)
 			}
 			return nil
 		}

shortcuts/markdown/helpers.go

@@ -13,12 +13,10 @@ import (
 	"path"
 	"path/filepath"
 	"strings"
-	"time"
 
 	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"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -30,17 +28,8 @@ const markdownEmptyContentError = "empty markdown content is not supported; cann
 const (
 	markdownUploadParentTypeExplorer = "explorer"
 	markdownUploadParentTypeWiki     = "wiki"
-	markdownUploadAllAction          = "upload markdown file failed"
-	markdownUploadPrepareAction      = "initialize markdown multipart upload failed"
-	markdownUploadFinishAction       = "finalize markdown multipart upload failed"
-	markdownFetchNameAction          = "fetch existing markdown file name failed"
 )
 
-var markdownUploadRetryBackoffs = []time.Duration{
-	200 * time.Millisecond,
-	500 * time.Millisecond,
-}
-
 type markdownUploadSpec struct {
 	FileToken   string
 	FileName    string
@@ -398,68 +387,58 @@ func uploadMarkdownContent(runtime *common.RuntimeContext, spec markdownUploadSp
 	fileName := finalMarkdownFileName(spec)
 	fileSize := int64(len(payload))
 	if fileSize > markdownSinglePartSizeLimit {
-		return uploadMarkdownFileMultipart(runtime, spec, fileName, fileSize, func() (io.ReadCloser, error) {
-			return io.NopCloser(bytes.NewReader(payload)), nil
-		})
+		return uploadMarkdownFileMultipart(runtime, spec, bytes.NewReader(payload), fileName, fileSize)
 	}
-	return uploadMarkdownFileAll(runtime, spec, fileName, fileSize, func() (io.ReadCloser, error) {
-		return io.NopCloser(bytes.NewReader(payload)), nil
-	})
+	return uploadMarkdownFileAll(runtime, spec, bytes.NewReader(payload), fileName, fileSize)
 }
 
 func uploadMarkdownLocalFile(runtime *common.RuntimeContext, spec markdownUploadSpec, fileSize int64) (markdownUploadResult, error) {
 	fileName := finalMarkdownFileName(spec)
-	if fileSize > markdownSinglePartSizeLimit {
-		return uploadMarkdownFileMultipart(runtime, spec, fileName, fileSize, func() (io.ReadCloser, error) {
-			return runtime.FileIO().Open(spec.FilePath)
-		})
+	f, err := runtime.FileIO().Open(spec.FilePath)
+	if err != nil {
+		return markdownUploadResult{}, common.WrapInputStatError(err)
 	}
-	return uploadMarkdownFileAll(runtime, spec, fileName, fileSize, func() (io.ReadCloser, error) {
-		return runtime.FileIO().Open(spec.FilePath)
-	})
+	defer f.Close()
+
+	if fileSize > markdownSinglePartSizeLimit {
+		return uploadMarkdownFileMultipart(runtime, spec, f, fileName, fileSize)
+	}
+	return uploadMarkdownFileAll(runtime, spec, f, fileName, fileSize)
 }
 
-func uploadMarkdownFileAll(runtime *common.RuntimeContext, spec markdownUploadSpec, fileName string, fileSize int64, openReader func() (io.ReadCloser, error)) (markdownUploadResult, error) {
+func uploadMarkdownFileAll(runtime *common.RuntimeContext, spec markdownUploadSpec, fileReader io.Reader, fileName string, fileSize int64) (markdownUploadResult, error) {
 	target := spec.Target()
-	return withMarkdownUploadRetryResult(runtime, markdownUploadAllAction, func() (markdownUploadResult, error) {
-		fileReader, err := openReader()
-		if err != nil {
-			return markdownUploadResult{}, common.WrapInputStatErrorTyped(err)
-		}
-		defer fileReader.Close()
+	fd := larkcore.NewFormdata()
+	fd.AddField("file_name", fileName)
+	fd.AddField("parent_type", target.ParentType)
+	fd.AddField("parent_node", target.ParentNode)
+	fd.AddField("size", fmt.Sprintf("%d", fileSize))
+	if spec.FileToken != "" {
+		fd.AddField("file_token", spec.FileToken)
+	}
+	fd.AddFile("file", fileReader)
 
-		fd := larkcore.NewFormdata()
-		fd.AddField("file_name", fileName)
-		fd.AddField("parent_type", target.ParentType)
-		fd.AddField("parent_node", target.ParentNode)
-		fd.AddField("size", fmt.Sprintf("%d", fileSize))
-		if spec.FileToken != "" {
-			fd.AddField("file_token", spec.FileToken)
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod: http.MethodPost,
+		ApiPath:    "/open-apis/drive/v1/files/upload_all",
+		Body:       fd,
+	}, larkcore.WithFileUpload())
+	if err != nil {
+		var exitErr *output.ExitError
+		if errors.As(err, &exitErr) {
+			return markdownUploadResult{}, err
 		}
-		fd.AddFile("file", fileReader)
+		return markdownUploadResult{}, output.ErrNetwork("upload failed: %v", err)
+	}
 
-		apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
-			HttpMethod: http.MethodPost,
-			ApiPath:    "/open-apis/drive/v1/files/upload_all",
-			Body:       fd,
-		}, larkcore.WithFileUpload())
-		if err != nil {
-			return markdownUploadResult{}, markdownUploadProblem(client.WrapDoAPIError(err), markdownUploadAllAction)
-		}
-
-		data, err := runtime.ClassifyAPIResponse(apiResp)
-		if err != nil {
-			return markdownUploadResult{}, markdownUploadProblem(err, markdownUploadAllAction)
-		}
-		result, err := parseMarkdownUploadResult(data, spec.FileToken != "")
-		if err != nil {
-			return markdownUploadResult{}, markdownUploadProblem(err, markdownUploadAllAction)
-		}
-		return result, nil
-	})
+	data, err := common.ParseDriveMediaUploadResponse(apiResp, "upload failed")
+	if err != nil {
+		return markdownUploadResult{}, err
+	}
+	return parseMarkdownUploadResult(data, spec.FileToken != "")
 }
 
-func uploadMarkdownFileMultipart(runtime *common.RuntimeContext, spec markdownUploadSpec, fileName string, fileSize int64, openReader func() (io.ReadCloser, error)) (markdownUploadResult, error) {
+func uploadMarkdownFileMultipart(runtime *common.RuntimeContext, spec markdownUploadSpec, fileReader io.Reader, fileName string, fileSize int64) (markdownUploadResult, error) {
 	target := spec.Target()
 	prepareBody := map[string]interface{}{
 		"file_name":   fileName,
@@ -471,53 +450,31 @@ func uploadMarkdownFileMultipart(runtime *common.RuntimeContext, spec markdownUp
 		prepareBody["file_token"] = spec.FileToken
 	}
 
-	prepareResult, err := withMarkdownUploadRetryData(runtime, markdownUploadPrepareAction, func() (map[string]interface{}, error) {
-		data, err := runtime.CallAPITyped("POST", "/open-apis/drive/v1/files/upload_prepare", nil, prepareBody)
-		if err != nil {
-			return nil, markdownUploadProblem(err, markdownUploadPrepareAction)
-		}
-		return data, nil
-	})
+	prepareResult, err := runtime.CallAPI("POST", "/open-apis/drive/v1/files/upload_prepare", nil, prepareBody)
 	if err != nil {
 		return markdownUploadResult{}, err
 	}
 
 	session, err := parseMarkdownMultipartSession(prepareResult)
 	if err != nil {
-		return markdownUploadResult{}, markdownUploadProblem(err, markdownUploadPrepareAction)
+		return markdownUploadResult{}, err
 	}
 
 	fmt.Fprintf(runtime.IO().ErrOut, "Multipart upload initialized: %d chunks x %s\n", session.BlockNum, common.FormatSize(session.BlockSize))
 
-	fileReader, err := openReader()
-	if err != nil {
-		return markdownUploadResult{}, common.WrapInputStatErrorTyped(err)
-	}
-	defer fileReader.Close()
-
 	if err := uploadMarkdownMultipartParts(runtime, fileReader, fileSize, session); err != nil {
 		return markdownUploadResult{}, err
 	}
 
-	finishResult, err := withMarkdownUploadRetryData(runtime, markdownUploadFinishAction, func() (map[string]interface{}, error) {
-		data, err := runtime.CallAPITyped("POST", "/open-apis/drive/v1/files/upload_finish", nil, map[string]interface{}{
-			"upload_id": session.UploadID,
-			"block_num": session.BlockNum,
-		})
-		if err != nil {
-			return nil, markdownUploadProblem(err, markdownUploadFinishAction)
-		}
-		return data, nil
+	finishResult, err := runtime.CallAPI("POST", "/open-apis/drive/v1/files/upload_finish", nil, map[string]interface{}{
+		"upload_id": session.UploadID,
+		"block_num": session.BlockNum,
 	})
 	if err != nil {
 		return markdownUploadResult{}, err
 	}
 
-	result, err := parseMarkdownUploadResult(finishResult, spec.FileToken != "")
-	if err != nil {
-		return markdownUploadResult{}, markdownUploadProblem(err, markdownUploadFinishAction)
-	}
-	return result, nil
+	return parseMarkdownUploadResult(finishResult, spec.FileToken != "")
 }
 
 func parseMarkdownMultipartSession(data map[string]interface{}) (markdownMultipartSession, error) {
@@ -527,7 +484,7 @@ func parseMarkdownMultipartSession(data map[string]interface{}) (markdownMultipa
 		BlockNum:  int(common.GetFloat(data, "block_num")),
 	}
 	if session.UploadID == "" || session.BlockSize <= 0 || session.BlockNum <= 0 {
-		return markdownMultipartSession{}, errs.NewInternalError(errs.SubtypeInvalidResponse,
+		return markdownMultipartSession{}, output.Errorf(output.ExitAPI, "api_error",
 			"upload_prepare returned invalid data: upload_id=%q, block_size=%d, block_num=%d",
 			session.UploadID, session.BlockSize, session.BlockNum)
 	}
@@ -537,8 +494,9 @@ func parseMarkdownMultipartSession(data map[string]interface{}) (markdownMultipa
 func uploadMarkdownMultipartParts(runtime *common.RuntimeContext, fileReader io.Reader, payloadSize int64, session markdownMultipartSession) error {
 	expectedBlocks := int((payloadSize + session.BlockSize - 1) / session.BlockSize)
 	if session.BlockNum != expectedBlocks {
-		return errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
+		return output.Errorf(
+			output.ExitAPI,
+			"api_error",
 			"upload_prepare returned inconsistent chunk plan: block_size=%d, block_num=%d, expected_block_num=%d, payload_size=%d",
 			session.BlockSize,
 			session.BlockNum,
@@ -549,7 +507,7 @@ func uploadMarkdownMultipartParts(runtime *common.RuntimeContext, fileReader io.
 
 	maxInt := int64(^uint(0) >> 1)
 	if session.BlockSize > maxInt {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "upload prepare failed: invalid block_size returned")
+		return output.Errorf(output.ExitAPI, "api_error", "upload prepare failed: invalid block_size returned")
 	}
 
 	buffer := make([]byte, int(session.BlockSize))
@@ -570,27 +528,22 @@ func uploadMarkdownMultipartParts(runtime *common.RuntimeContext, fileReader io.
 		fd.AddField("upload_id", session.UploadID)
 		fd.AddField("seq", fmt.Sprintf("%d", seq))
 		fd.AddField("size", fmt.Sprintf("%d", n))
-		action := fmt.Sprintf("upload markdown file part %d/%d failed", seq+1, session.BlockNum)
-		if err := withMarkdownUploadRetryVoid(runtime, action, func() error {
-			fd := larkcore.NewFormdata()
-			fd.AddField("upload_id", session.UploadID)
-			fd.AddField("seq", fmt.Sprintf("%d", seq))
-			fd.AddField("size", fmt.Sprintf("%d", n))
-			fd.AddFile("file", bytes.NewReader(buffer[:n]))
+		fd.AddFile("file", bytes.NewReader(buffer[:n]))
 
-			apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
-				HttpMethod: http.MethodPost,
-				ApiPath:    "/open-apis/drive/v1/files/upload_part",
-				Body:       fd,
-			}, larkcore.WithFileUpload())
-			if err != nil {
-				return markdownUploadProblem(client.WrapDoAPIError(err), action)
+		apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+			HttpMethod: http.MethodPost,
+			ApiPath:    "/open-apis/drive/v1/files/upload_part",
+			Body:       fd,
+		}, larkcore.WithFileUpload())
+		if err != nil {
+			var exitErr *output.ExitError
+			if errors.As(err, &exitErr) {
+				return err
 			}
-			if _, err := runtime.ClassifyAPIResponse(apiResp); err != nil {
-				return markdownUploadProblem(err, action)
-			}
-			return nil
-		}); err != nil {
+			return output.ErrNetwork("upload part %d/%d failed: %v", seq+1, session.BlockNum, err)
+		}
+
+		if _, err := common.ParseDriveMediaUploadResponse(apiResp, fmt.Sprintf("upload part %d/%d failed", seq+1, session.BlockNum)); err != nil {
 			return err
 		}
 
@@ -598,8 +551,9 @@ func uploadMarkdownMultipartParts(runtime *common.RuntimeContext, fileReader io.
 		remaining -= int64(n)
 	}
 	if remaining != 0 {
-		return errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
+		return output.Errorf(
+			output.ExitAPI,
+			"api_error",
 			"upload_prepare returned inconsistent chunk plan: %d bytes remain after %d blocks",
 			remaining,
 			session.BlockNum,
@@ -618,34 +572,28 @@ func parseMarkdownUploadResult(data map[string]interface{}, requireVersion bool)
 		result.Version = common.GetString(data, "data_version")
 	}
 	if result.FileToken == "" {
-		return markdownUploadResult{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "upload failed: no file_token returned")
+		return markdownUploadResult{}, output.Errorf(output.ExitAPI, "api_error", "upload failed: no file_token returned")
 	}
 	if requireVersion && result.Version == "" {
-		return markdownUploadResult{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "overwrite failed: no version returned")
+		return markdownUploadResult{}, output.Errorf(output.ExitAPI, "api_error", "overwrite failed: no version returned")
 	}
 	return result, nil
 }
 
 func fetchMarkdownFileName(runtime *common.RuntimeContext, fileToken string) (string, error) {
-	data, err := withMarkdownUploadRetryData(runtime, markdownFetchNameAction, func() (map[string]interface{}, error) {
-		data, err := runtime.CallAPITyped(
-			"POST",
-			"/open-apis/drive/v1/metas/batch_query",
-			nil,
-			map[string]interface{}{
-				"request_docs": []map[string]interface{}{
-					{
-						"doc_token": fileToken,
-						"doc_type":  "file",
-					},
+	data, err := runtime.CallAPI(
+		"POST",
+		"/open-apis/drive/v1/metas/batch_query",
+		nil,
+		map[string]interface{}{
+			"request_docs": []map[string]interface{}{
+				{
+					"doc_token": fileToken,
+					"doc_type":  "file",
 				},
 			},
-		)
-		if err != nil {
-			return nil, markdownUploadProblem(err, markdownFetchNameAction)
-		}
-		return data, nil
-	})
+		},
+	)
 	if err != nil {
 		return "", err
 	}
@@ -658,97 +606,6 @@ func fetchMarkdownFileName(runtime *common.RuntimeContext, fileToken string) (st
 	return common.GetString(meta, "title"), nil
 }
 
-func withMarkdownUploadRetryResult(runtime *common.RuntimeContext, action string, fn func() (markdownUploadResult, error)) (markdownUploadResult, error) {
-	var zero markdownUploadResult
-	for attempt := 0; ; attempt++ {
-		result, err := fn()
-		if err == nil {
-			return result, nil
-		}
-		if !markdownUploadShouldRetry(err) || attempt >= len(markdownUploadRetryBackoffs) {
-			return zero, markdownUploadRetryExhausted(err, action, attempt)
-		}
-		fmt.Fprintf(runtime.IO().ErrOut, "%s; retrying (attempt %d/%d)\n", err.Error(), attempt+1, len(markdownUploadRetryBackoffs))
-		time.Sleep(markdownUploadRetryBackoffs[attempt])
-	}
-}
-
-func withMarkdownUploadRetryData(runtime *common.RuntimeContext, action string, fn func() (map[string]interface{}, error)) (map[string]interface{}, error) {
-	for attempt := 0; ; attempt++ {
-		result, err := fn()
-		if err == nil {
-			return result, nil
-		}
-		if !markdownUploadShouldRetry(err) || attempt >= len(markdownUploadRetryBackoffs) {
-			return nil, markdownUploadRetryExhausted(err, action, attempt)
-		}
-		fmt.Fprintf(runtime.IO().ErrOut, "%s; retrying (attempt %d/%d)\n", err.Error(), attempt+1, len(markdownUploadRetryBackoffs))
-		time.Sleep(markdownUploadRetryBackoffs[attempt])
-	}
-}
-
-func withMarkdownUploadRetryVoid(runtime *common.RuntimeContext, action string, fn func() error) error {
-	for attempt := 0; ; attempt++ {
-		err := fn()
-		if err == nil {
-			return nil
-		}
-		if !markdownUploadShouldRetry(err) || attempt >= len(markdownUploadRetryBackoffs) {
-			return markdownUploadRetryExhausted(err, action, attempt)
-		}
-		fmt.Fprintf(runtime.IO().ErrOut, "%s; retrying (attempt %d/%d)\n", err.Error(), attempt+1, len(markdownUploadRetryBackoffs))
-		time.Sleep(markdownUploadRetryBackoffs[attempt])
-	}
-}
-
-func markdownUploadShouldRetry(err error) bool {
-	p, ok := errs.ProblemOf(err)
-	if !ok || p == nil {
-		return false
-	}
-	return p.Retryable || p.Category == errs.CategoryNetwork
-}
-
-func markdownUploadRetryExhausted(err error, action string, retries int) error {
-	if retries <= 0 {
-		return err
-	}
-	return appendMarkdownProblemHint(err, fmt.Sprintf("%s remained retryable after %d attempts; retry later if the upstream service is throttling or temporarily unavailable", action, retries+1))
-}
-
-func markdownUploadProblem(err error, action string) error {
-	if p, ok := errs.ProblemOf(err); ok {
-		p.Message = action + ": " + p.Message
-		switch p.Code {
-		case 99991672, 99991679:
-			appendMarkdownProblemHint(err, "The current token or identity lacks the required document upload scope/capability. Grant the document upload scope or use a token with the appropriate permissions, then retry.")
-		case 10071:
-			appendMarkdownProblemHint(err, "The target document has reached its version limit. Clean up old versions or create a new file before retrying.")
-		case 90003087:
-			appendMarkdownProblemHint(err, "The current tenant or user may not have document capabilities enabled. Ask an administrator to verify document-module access.")
-		case 1061003, 1061044:
-			appendMarkdownProblemHint(err, "Check whether the target folder or wiki node still exists, and verify the token you passed to the command.")
-		case 1061004, 1062501:
-			appendMarkdownProblemHint(err, "Check whether the current identity has write access to the target folder or wiki node.")
-		}
-	}
-	return err
-}
-
-func appendMarkdownProblemHint(err error, hint string) error {
-	if strings.TrimSpace(hint) == "" {
-		return err
-	}
-	if p, ok := errs.ProblemOf(err); ok {
-		if strings.TrimSpace(p.Hint) != "" {
-			p.Hint = p.Hint + "\n" + hint
-		} else {
-			p.Hint = hint
-		}
-	}
-	return err
-}
-
 func prettyPrintMarkdownWrite(w io.Writer, data map[string]interface{}) {
 	fmt.Fprintf(w, "file_token: %s\n", common.GetString(data, "file_token"))
 	fmt.Fprintf(w, "file_name: %s\n", common.GetString(data, "file_name"))

shortcuts/markdown/markdown_test.go

@@ -17,11 +17,9 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
-	"time"
 
 	"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/core"
@@ -605,100 +603,6 @@ func TestMarkdownCreateSuccessUploadAllToWikiReturnsMetaURL(t *testing.T) {
 	}
 }
 
-func TestMarkdownCreateUploadAllReturnsTypedScopeError(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/files/upload_all",
-		Body: map[string]interface{}{
-			"code": 99991672,
-			"msg":  "Access denied. One of the following scopes is required: [drive:file:upload]",
-			"error": map[string]interface{}{
-				"log_id": "log-md-upload-scope",
-			},
-		},
-	})
-
-	err := mountAndRunMarkdown(t, MarkdownCreate, []string{
-		"+create",
-		"--name", "README.md",
-		"--content", "# hello\n",
-	}, f, stdout)
-	if err == nil {
-		t.Fatal("expected scope error")
-	}
-
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T (%v)", err, err)
-	}
-	if p.Code != 99991672 {
-		t.Fatalf("code = %d, want 99991672", p.Code)
-	}
-	if p.Subtype != errs.SubtypeAppScopeNotApplied {
-		t.Fatalf("subtype = %s, want %s", p.Subtype, errs.SubtypeAppScopeNotApplied)
-	}
-	if !strings.HasPrefix(p.Message, markdownUploadAllAction+": ") {
-		t.Fatalf("message = %q, want %q prefix", p.Message, markdownUploadAllAction+": ")
-	}
-	if !strings.Contains(p.Hint, "lacks the required document upload scope") {
-		t.Fatalf("hint = %q, want upload scope guidance", p.Hint)
-	}
-}
-
-func TestMarkdownCreateUploadAllRetriesRateLimit(t *testing.T) {
-	f, stdout, stderr, reg := cmdutil.TestFactory(t, markdownTestConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/files/upload_all",
-		Body: map[string]interface{}{
-			"code": 99991400,
-			"msg":  "request frequency limit exceeded",
-			"error": map[string]interface{}{
-				"log_id": "log-md-upload-ratelimit-1",
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/files/upload_all",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"file_token": "box_md_retry_success",
-				"version":    "1003",
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/metas/batch_query",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"metas": []map[string]interface{}{
-					{"doc_token": "box_md_retry_success", "doc_type": "file", "url": "https://tenant.example.com/file/box_md_retry_success"},
-				},
-			},
-		},
-	})
-
-	err := mountAndRunMarkdown(t, MarkdownCreate, []string{
-		"+create",
-		"--name", "README.md",
-		"--content", "# hello\n",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if !strings.Contains(stderr.String(), "retrying (attempt 1/2)") {
-		t.Fatalf("stderr = %q, want retry log", stderr.String())
-	}
-	if !strings.Contains(stdout.String(), `"file_token": "box_md_retry_success"`) {
-		t.Fatalf("stdout missing retried upload token: %s", stdout.String())
-	}
-}
-
 func TestMarkdownCreatePrettyOutputIncludesPermissionGrant(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
@@ -1129,270 +1033,6 @@ func TestUploadMarkdownMultipartPartsRejectsOversizedBlockSize(t *testing.T) {
 	}
 }
 
-func TestWithMarkdownUploadRetryDataDoesNotRetryNonRetryable(t *testing.T) {
-	f, _, stderr, _ := cmdutil.TestFactory(t, markdownTestConfig())
-	rt := common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser)
-
-	attempts := 0
-	expected := errs.NewAPIError(errs.SubtypePermissionDenied, "permission denied").WithCode(1061004)
-	_, err := withMarkdownUploadRetryData(rt, markdownUploadAllAction, func() (map[string]interface{}, error) {
-		attempts++
-		return nil, expected
-	})
-	if err != expected {
-		t.Fatalf("err = %v, want original error", err)
-	}
-	if attempts != 1 {
-		t.Fatalf("attempts = %d, want 1", attempts)
-	}
-	if stderr.String() != "" {
-		t.Fatalf("stderr = %q, want no retry log", stderr.String())
-	}
-}
-
-func TestWithMarkdownUploadRetryVoidExhaustedAppendsHint(t *testing.T) {
-	f, _, stderr, _ := cmdutil.TestFactory(t, markdownTestConfig())
-	rt := common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser)
-
-	orig := markdownUploadRetryBackoffs
-	markdownUploadRetryBackoffs = []time.Duration{0, 0}
-	t.Cleanup(func() { markdownUploadRetryBackoffs = orig })
-
-	attempts := 0
-	err := withMarkdownUploadRetryVoid(rt, markdownUploadFinishAction, func() error {
-		attempts++
-		return errs.NewAPIError(errs.SubtypeRateLimit, "too many requests").WithCode(99991400).WithRetryable()
-	})
-	if err == nil {
-		t.Fatal("expected retryable error")
-	}
-	if attempts != 3 {
-		t.Fatalf("attempts = %d, want 3", attempts)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T (%v)", err, err)
-	}
-	if !strings.Contains(p.Hint, "remained retryable after 3 attempts") {
-		t.Fatalf("hint = %q, want retry exhaustion guidance", p.Hint)
-	}
-	if strings.Count(stderr.String(), "retrying (attempt") != 2 {
-		t.Fatalf("stderr = %q, want 2 retry logs", stderr.String())
-	}
-}
-
-func TestMarkdownUploadShouldRetryBranches(t *testing.T) {
-	if markdownUploadShouldRetry(errors.New("plain")) {
-		t.Fatal("plain error should not be retryable")
-	}
-	if !markdownUploadShouldRetry(errs.NewAPIError(errs.SubtypeRateLimit, "slow down").WithRetryable()) {
-		t.Fatal("retryable API error should be retryable")
-	}
-	if !markdownUploadShouldRetry(errs.NewNetworkError(errs.SubtypeNetworkServer, "gateway").WithCode(502)) {
-		t.Fatal("network error should be retryable by category")
-	}
-}
-
-func TestMarkdownUploadRetryExhaustedZeroRetriesKeepsOriginal(t *testing.T) {
-	original := errs.NewAPIError(errs.SubtypeRateLimit, "slow down").WithRetryable()
-	got := markdownUploadRetryExhausted(original, markdownUploadAllAction, 0)
-	if got != original {
-		t.Fatalf("got = %v, want original error", got)
-	}
-}
-
-func TestMarkdownUploadProblemAppendsCodeSpecificHints(t *testing.T) {
-	tests := []struct {
-		name string
-		code int
-		want string
-	}{
-		{
-			name: "missing scope",
-			code: 99991672,
-			want: "lacks the required document upload scope",
-		},
-		{
-			name: "version limit",
-			code: 10071,
-			want: "reached its version limit",
-		},
-		{
-			name: "document capability",
-			code: 90003087,
-			want: "document capabilities enabled",
-		},
-		{
-			name: "target not found",
-			code: 1061044,
-			want: "target folder or wiki node still exists",
-		},
-		{
-			name: "no write access",
-			code: 1062501,
-			want: "has write access",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			err := errs.NewAPIError(errs.SubtypeUnknown, "boom").WithCode(tt.code)
-			got := markdownUploadProblem(err, markdownUploadAllAction)
-			p, ok := errs.ProblemOf(got)
-			if !ok {
-				t.Fatalf("expected typed problem, got %T (%v)", got, got)
-			}
-			if !strings.HasPrefix(p.Message, markdownUploadAllAction+": ") {
-				t.Fatalf("message = %q, want action prefix", p.Message)
-			}
-			if !strings.Contains(p.Hint, tt.want) {
-				t.Fatalf("hint = %q, want substring %q", p.Hint, tt.want)
-			}
-		})
-	}
-}
-
-func TestUploadMarkdownFileAllMissingFileTokenGetsActionPrefix(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/files/upload_all",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"version": "1001",
-			},
-		},
-	})
-
-	_, err := uploadMarkdownFileAll(
-		common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser),
-		markdownUploadSpec{ContentSet: true},
-		"README.md",
-		int64(len("# hello\n")),
-		func() (io.ReadCloser, error) {
-			return io.NopCloser(strings.NewReader("# hello\n")), nil
-		},
-	)
-	if err == nil {
-		t.Fatal("expected parse error")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T (%v)", err, err)
-	}
-	if !strings.HasPrefix(p.Message, markdownUploadAllAction+": ") {
-		t.Fatalf("message = %q, want %q prefix", p.Message, markdownUploadAllAction+": ")
-	}
-}
-
-func TestUploadMarkdownFileMultipartPrepareAndFinishParseErrorsGetActionPrefix(t *testing.T) {
-	t.Run("prepare", func(t *testing.T) {
-		f, _, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
-		reg.Register(&httpmock.Stub{
-			Method: "POST",
-			URL:    "/open-apis/drive/v1/files/upload_prepare",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{
-					"upload_id": "upload_123",
-					"block_num": 1,
-				},
-			},
-		})
-
-		_, err := uploadMarkdownFileMultipart(
-			common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser),
-			markdownUploadSpec{ContentSet: true},
-			"README.md",
-			int64(len("# hello\n")),
-			func() (io.ReadCloser, error) {
-				return io.NopCloser(strings.NewReader("# hello\n")), nil
-			},
-		)
-		if err == nil {
-			t.Fatal("expected prepare parse error")
-		}
-		p, ok := errs.ProblemOf(err)
-		if !ok {
-			t.Fatalf("expected typed problem, got %T (%v)", err, err)
-		}
-		if !strings.HasPrefix(p.Message, markdownUploadPrepareAction+": ") {
-			t.Fatalf("message = %q, want %q prefix", p.Message, markdownUploadPrepareAction+": ")
-		}
-	})
-
-	t.Run("finish", func(t *testing.T) {
-		f, _, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
-		reg.Register(&httpmock.Stub{
-			Method: "POST",
-			URL:    "/open-apis/drive/v1/files/upload_prepare",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{
-					"upload_id":  "upload_123",
-					"block_size": float64(8),
-					"block_num":  float64(1),
-				},
-			},
-		})
-		reg.Register(&httpmock.Stub{
-			Method: "POST",
-			URL:    "/open-apis/drive/v1/files/upload_part",
-			Body:   map[string]interface{}{"code": 0, "msg": "ok"},
-		})
-		reg.Register(&httpmock.Stub{
-			Method: "POST",
-			URL:    "/open-apis/drive/v1/files/upload_finish",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{
-					"version": "1001",
-				},
-			},
-		})
-
-		_, err := uploadMarkdownFileMultipart(
-			common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser),
-			markdownUploadSpec{ContentSet: true},
-			"README.md",
-			int64(len("# hello\n")),
-			func() (io.ReadCloser, error) {
-				return io.NopCloser(strings.NewReader("# hello\n")), nil
-			},
-		)
-		if err == nil {
-			t.Fatal("expected finish parse error")
-		}
-		p, ok := errs.ProblemOf(err)
-		if !ok {
-			t.Fatalf("expected typed problem, got %T (%v)", err, err)
-		}
-		if !strings.HasPrefix(p.Message, markdownUploadFinishAction+": ") {
-			t.Fatalf("message = %q, want %q prefix", p.Message, markdownUploadFinishAction+": ")
-		}
-	})
-}
-
-func TestAppendMarkdownProblemHintAppendsAndIgnoresBlank(t *testing.T) {
-	err := errs.NewAPIError(errs.SubtypeUnknown, "boom").WithHint("first")
-	appendMarkdownProblemHint(err, "second")
-	appendMarkdownProblemHint(err, "   ")
-
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T (%v)", err, err)
-	}
-	if p.Hint != "first\nsecond" {
-		t.Fatalf("hint = %q, want newline-joined hints", p.Hint)
-	}
-
-	plain := errors.New("plain")
-	if got := appendMarkdownProblemHint(plain, "ignored"); got != plain {
-		t.Fatalf("plain error should pass through unchanged")
-	}
-}
-
 func TestMarkdownOverwriteUploadAllIncludesFileTokenAndVersion(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
@@ -1663,18 +1303,7 @@ func TestMarkdownOverwriteRejectsEmptyLocalFile(t *testing.T) {
 }
 
 func TestMarkdownOverwriteMetadataLookupFailure(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/metas/batch_query",
-		Body: map[string]interface{}{
-			"code": 1061044,
-			"msg":  "parent node not exist",
-			"error": map[string]interface{}{
-				"log_id": "log-md-meta-notfound",
-			},
-		},
-	})
+	f, stdout, _, _ := cmdutil.TestFactory(t, markdownTestConfig())
 
 	err := mountAndRunMarkdown(t, MarkdownOverwrite, []string{
 		"+overwrite",
@@ -1684,19 +1313,6 @@ func TestMarkdownOverwriteMetadataLookupFailure(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected metadata lookup failure")
 	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T (%v)", err, err)
-	}
-	if p.Code != 1061044 {
-		t.Fatalf("code = %d, want 1061044", p.Code)
-	}
-	if !strings.HasPrefix(p.Message, markdownFetchNameAction+": ") {
-		t.Fatalf("message = %q, want %q prefix", p.Message, markdownFetchNameAction+": ")
-	}
-	if !strings.Contains(p.Hint, "target folder or wiki node still exists") {
-		t.Fatalf("hint = %q, want target guidance", p.Hint)
-	}
 }
 
 func TestMarkdownOverwriteMissingFileReturnsReadError(t *testing.T) {

shortcuts/sheets/csv_put_guard_test.go

@@ -1,58 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package sheets
-
-import (
-	"os"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	_ "github.com/larksuite/cli/internal/vfs/localfileio"
-	"github.com/larksuite/cli/shortcuts/common"
-	"github.com/spf13/cobra"
-)
-
-func newCSVGuardRuntime(csvVal string) *common.RuntimeContext {
-	cmd := &cobra.Command{Use: "test"}
-	cmd.Flags().String("csv", "", "")
-	cmd.ParseFlags(nil)
-	cmd.Flags().Set("csv", csvVal)
-	return &common.RuntimeContext{Cmd: cmd}
-}
-
-// TestGuardCSVValueIsNotFilePath verifies the guard flags a bare --csv value
-// only when it names a real file (a forgotten @), while leaving genuine inline
-// content alone — including the case the old name-shape heuristic got wrong:
-// prose that merely ends in or mentions a filename.
-func TestGuardCSVValueIsNotFilePath(t *testing.T) {
-	dir := t.TempDir()
-	cmdutil.TestChdir(t, dir)
-	if err := os.WriteFile("data.csv", []byte("a,b\n1,2\n"), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	// Bare value naming an existing file → guarded with a fix-it hint.
-	err := guardCSVValueIsNotFilePath(newCSVGuardRuntime("data.csv"))
-	if err == nil {
-		t.Fatal("expected guard error when --csv names an existing file")
-	}
-	if !strings.Contains(err.Error(), "existing file") || !strings.Contains(err.Error(), "@data.csv") {
-		t.Errorf("error should flag the file and suggest @data.csv, got: %v", err)
-	}
-
-	// Content that is not a real file must pass through unchanged.
-	for _, v := range []string{
-		"改完记得更新config.json",           // prose ending in a filename — not a real file
-		"remember to update data.csv", // mentions the real file but isn't its name
-		"a,b\n1,2",                    // multi-cell CSV
-		"hello world",
-		"nope.csv", // path-shaped but no such file
-		"",
-	} {
-		if err := guardCSVValueIsNotFilePath(newCSVGuardRuntime(v)); err != nil {
-			t.Errorf("content %q must pass through, got: %v", v, err)
-		}
-	}
-}

shortcuts/sheets/lark_sheet_write_cells.go

@@ -219,12 +219,7 @@ var CsvPut = common.Shortcut{
 		}
 		cmd.MarkFlagsOneRequired("start-cell", "range")
 	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if err := guardCSVValueIsNotFilePath(runtime); err != nil {
-			return err
-		}
-		return validateViaInput(csvPutInput)(ctx, runtime)
-	},
+	Validate: validateViaInput(csvPutInput),
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		token, _ := resolveSpreadsheetToken(runtime)
 		sheetID, sheetName, _ := resolveSheetSelector(runtime)
@@ -300,36 +295,6 @@ func csvPutWriteRangeFromInput(input map[string]interface{}) (string, bool) {
 	return fmt.Sprintf("%s:%s%d", anchor, endCol, endRow), true
 }
 
-// guardCSVValueIsNotFilePath catches the common slip of passing a CSV file path
-// to --csv without the "@" that reads it (e.g. `--csv data.csv` instead of
-// `--csv @data.csv`). Because any string is a valid one-cell CSV, the mistake
-// would otherwise be written silently as the literal text "data.csv". It runs
-// in +csv-put's Validate, after resolveInputFlags — so an @file / stdin value is
-// already its contents (a real CSV blob, never a path) and only a bare value
-// reaches here unchanged. It flags the value only when it actually names an
-// existing file in the cwd subtree; checking real existence (not name shape)
-// means inline content that merely ends in a filename ("see config.json") is
-// never misjudged. Fails open: any Stat error or a directory leaves the value
-// untouched. Scoped to --csv only — no other flag is affected.
-func guardCSVValueIsNotFilePath(runtime *common.RuntimeContext) error {
-	raw := strings.TrimSpace(runtime.Str("csv"))
-	if raw == "" {
-		return nil
-	}
-	fio := runtime.FileIO()
-	if fio == nil {
-		return nil
-	}
-	info, err := fio.Stat(raw)
-	if err != nil || info == nil || info.IsDir() {
-		return nil //nolint:nilerr // fail-open: a missing/unreadable path is treated as inline content, not a forgotten @
-	}
-	return common.FlagErrorf(
-		"--csv value %q is an existing file, not inline CSV; to read it use --csv @%s, or pass the literal text via stdin (--csv -)",
-		raw, raw,
-	)
-}
-
 func csvPutInput(runtime flagView, token, sheetID, sheetName string) (map[string]interface{}, error) {
 	if err := requireSheetSelector(sheetID, sheetName); err != nil {
 		return nil, err

shortcuts/slides/slides_create.go

@@ -33,9 +33,6 @@ var SlidesCreate = common.Shortcut{
 	// like wiki_move) so the pre-flight check fails fast and lark-cli's
 	// auth login --scope hint guides the user, instead of leaving an orphaned
 	// empty presentation when the in-flight upload 403s.
-	// NB: no drive scope here on purpose — slides creation never touches drive;
-	// the presentation URL is built locally (see Execute), so we don't gate a
-	// drive-free operation behind a drive scope.
 	Scopes: []string{"slides:presentation:create", "slides:presentation:write_only", "docs:document.media:upload"},
 	Flags: []common.Flag{
 		{Name: "title", Desc: "presentation title"},
@@ -208,14 +205,29 @@ var SlidesCreate = common.Shortcut{
 			}
 		}
 
-		// Build the presentation URL locally from the token. The brand-standard
-		// host transparently redirects to the tenant domain (same fallback used by
-		// drive +upload / wiki +node-create). This avoids the prior best-effort
-		// drive metas/batch_query call, which needed an extra drive scope and 403'd
-		// for users who only authorized slides scopes — without ever blocking an
-		// otherwise-successful creation.
-		if url := common.BuildResourceURL(runtime.Config.Brand, "slides", presentationID); url != "" {
-			result["url"] = url
+		// Fetch presentation URL via drive meta (best-effort)
+		if metaData, err := runtime.CallAPI(
+			"POST",
+			"/open-apis/drive/v1/metas/batch_query",
+			nil,
+			map[string]interface{}{
+				"request_docs": []map[string]interface{}{
+					{
+						"doc_token": presentationID,
+						"doc_type":  "slides",
+					},
+				},
+				"with_url": true,
+			},
+		); err == nil {
+			metas := common.GetSlice(metaData, "metas")
+			if len(metas) > 0 {
+				if meta, ok := metas[0].(map[string]interface{}); ok {
+					if url := common.GetString(meta, "url"); url != "" {
+						result["url"] = url
+					}
+				}
+			}
 		}
 
 		if grant := common.AutoGrantCurrentUserDrivePermission(runtime, presentationID, "slides"); grant != nil {

shortcuts/slides/slides_create_test.go

@@ -35,6 +35,7 @@ func TestSlidesCreateBasic(t *testing.T) {
 			},
 		},
 	})
+	registerBatchQueryStub(reg, "pres_abc123", "https://example.feishu.cn/slides/pres_abc123")
 
 	err := runSlidesCreateShortcut(t, f, stdout, []string{
 		"+create",
@@ -52,10 +53,8 @@ func TestSlidesCreateBasic(t *testing.T) {
 	if data["title"] != "项目汇报" {
 		t.Fatalf("title = %v, want 项目汇报", data["title"])
 	}
-	// URL is built locally from the token (brand-standard host), not fetched from
-	// drive metas, so it is deterministic and needs no drive scope.
-	if data["url"] != "https://www.feishu.cn/slides/pres_abc123" {
-		t.Fatalf("url = %v, want https://www.feishu.cn/slides/pres_abc123", data["url"])
+	if data["url"] != "https://example.feishu.cn/slides/pres_abc123" {
+		t.Fatalf("url = %v, want https://example.feishu.cn/slides/pres_abc123", data["url"])
 	}
 	if _, ok := data["permission_grant"]; ok {
 		t.Fatalf("did not expect permission_grant in user mode")
@@ -79,6 +78,7 @@ func TestSlidesCreateBotAutoGrant(t *testing.T) {
 			},
 		},
 	})
+	registerBatchQueryStub(reg, "pres_bot", "https://example.feishu.cn/slides/pres_bot")
 	reg.Register(&httpmock.Stub{
 		Method: "POST",
 		URL:    "/open-apis/drive/v1/permissions/pres_bot/members",
@@ -131,6 +131,7 @@ func TestSlidesCreateBotSkippedWithoutCurrentUser(t *testing.T) {
 			},
 		},
 	})
+	registerBatchQueryStub(reg, "pres_no_user", "https://example.feishu.cn/slides/pres_no_user")
 
 	err := runSlidesCreateShortcut(t, f, stdout, []string{
 		"+create",
@@ -167,6 +168,7 @@ func TestSlidesCreateBotAutoGrantFailed(t *testing.T) {
 			},
 		},
 	})
+	registerBatchQueryStub(reg, "pres_grant_fail", "https://example.feishu.cn/slides/pres_grant_fail")
 
 	reg.Register(&httpmock.Stub{
 		Method: "POST",
@@ -236,6 +238,7 @@ func TestSlidesCreateDefaultTitle(t *testing.T) {
 			},
 		},
 	})
+	registerBatchQueryStub(reg, "pres_default", "https://example.feishu.cn/slides/pres_default")
 
 	err := runSlidesCreateShortcut(t, f, stdout, []string{
 		"+create",
@@ -298,6 +301,7 @@ func TestSlidesCreateWithSlides(t *testing.T) {
 			},
 		},
 	})
+	registerBatchQueryStub(reg, "pres_with_slides", "https://example.feishu.cn/slides/pres_with_slides")
 	reg.Register(&httpmock.Stub{
 		Method: "POST",
 		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_with_slides/slide",
@@ -474,6 +478,7 @@ func TestSlidesCreateWithSlidesEmptyArray(t *testing.T) {
 			},
 		},
 	})
+	registerBatchQueryStub(reg, "pres_empty_slides", "https://example.feishu.cn/slides/pres_empty_slides")
 
 	err := runSlidesCreateShortcut(t, f, stdout, []string{
 		"+create",
@@ -546,6 +551,7 @@ func TestSlidesCreateWithoutSlidesUnchanged(t *testing.T) {
 			},
 		},
 	})
+	registerBatchQueryStub(reg, "pres_no_slides", "https://example.feishu.cn/slides/pres_no_slides")
 
 	err := runSlidesCreateShortcut(t, f, stdout, []string{
 		"+create",
@@ -574,12 +580,8 @@ func TestSlidesCreateWithoutSlidesUnchanged(t *testing.T) {
 	}
 }
 
-// TestSlidesCreateURLBuiltLocally verifies the presentation URL is constructed
-// locally from the token — no drive metas/batch_query call is made, so creation
-// works for users who only authorized slides scopes. The httpmock registry has no
-// batch_query stub registered; if the shortcut tried to call it, the request would
-// fail the test (unregistered stub), proving the URL is built without a drive call.
-func TestSlidesCreateURLBuiltLocally(t *testing.T) {
+// TestSlidesCreateURLFetchBestEffort verifies that the shortcut succeeds even when batch_query fails.
+func TestSlidesCreateURLFetchBestEffort(t *testing.T) {
 	t.Parallel()
 
 	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
@@ -590,15 +592,24 @@ func TestSlidesCreateURLBuiltLocally(t *testing.T) {
 			"code": 0,
 			"msg":  "ok",
 			"data": map[string]interface{}{
-				"xml_presentation_id": "pres_local_url",
+				"xml_presentation_id": "pres_no_url",
 				"revision_id":         1,
 			},
 		},
 	})
+	// batch_query returns an error — URL fetch should be silently skipped
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 99999,
+			"msg":  "no permission",
+		},
+	})
 
 	err := runSlidesCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--title", "Local URL",
+		"--title", "No URL",
 		"--as", "user",
 	})
 	if err != nil {
@@ -606,11 +617,11 @@ func TestSlidesCreateURLBuiltLocally(t *testing.T) {
 	}
 
 	data := decodeSlidesCreateEnvelope(t, stdout)
-	if data["xml_presentation_id"] != "pres_local_url" {
-		t.Fatalf("xml_presentation_id = %v, want pres_local_url", data["xml_presentation_id"])
+	if data["xml_presentation_id"] != "pres_no_url" {
+		t.Fatalf("xml_presentation_id = %v, want pres_no_url", data["xml_presentation_id"])
 	}
-	if data["url"] != "https://www.feishu.cn/slides/pres_local_url" {
-		t.Fatalf("url = %v, want https://www.feishu.cn/slides/pres_local_url", data["url"])
+	if _, ok := data["url"]; ok {
+		t.Fatalf("did not expect url when batch_query fails")
 	}
 }
 
@@ -661,6 +672,22 @@ func runSlidesCreateShortcut(t *testing.T, f *cmdutil.Factory, stdout *bytes.Buf
 	return parent.Execute()
 }
 
+// registerBatchQueryStub registers a drive meta batch_query mock that returns the given URL.
+func registerBatchQueryStub(reg *httpmock.Registry, token, url string) {
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"metas": []map[string]interface{}{
+					{"doc_token": token, "doc_type": "slides", "title": "", "url": url},
+				},
+			},
+		},
+	})
+}
+
 // decodeSlidesCreateEnvelope parses the JSON output and returns the data map.
 func decodeSlidesCreateEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
 	t.Helper()
@@ -731,6 +758,7 @@ func TestSlidesCreateWithImagePlaceholders(t *testing.T) {
 	}
 	reg.Register(slideStub1)
 	reg.Register(slideStub2)
+	registerBatchQueryStub(reg, "pres_img", "https://x.feishu.cn/slides/pres_img")
 
 	slidesJSON := `[
 	  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><img src=\"@a.png\" topLeftX=\"10\"/><img src=\"@b.png\" topLeftX=\"20\"/></data></slide>",

skills/lark-approval/SKILL.md

@@ -1,35 +1,56 @@
 ---
 name: lark-approval
-version: 1.1.0
-description: "飞书审批：当前用户审批的查询与全部处理操作，覆盖待本人审批的任务与本人发起的实例。审批待办不是飞书任务（任务类待办走 lark-task）；不负责创建审批定义和发起新审批。"
+version: 1.0.0
+description: "飞书审批 API：审批实例、审批任务管理。"
 metadata:
   requires:
     bins: ["lark-cli"]
   cliHelp: "lark-cli approval --help"
 ---
 
+# approval (v4)
+
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
-所有命令默认 `--as user`（审批是人的动作）。调用前先 `lark-cli schema approval.<resource>.<method>` 查参数结构，不要猜字段。
-
-## 选哪个命令
-
-| 想做什么 | 命令 |
-|---|---|
-| 查待办/已办 | `tasks query`（`topic`：1待办 2已办 17未读 18已读）|
-| 看表单/进度/当前节点 | `instances get` |
-| 同意/拒绝 | `tasks approve` / `tasks reject` |
-| 转交/加签/退回 | `tasks transfer` / `tasks add_sign` / `tasks rollback` |
-| 催办 | `tasks remind` |
-| 撤回/抄送/按定义查已发起 | `instances cancel` / `instances cc` / `instances initiated` |
-
-处理链：`tasks query` 拿 `instance_code` + `task_id`（操作必须成对带上）→ 需要细节再 `instances get` → 执行操作。
+## API Resources
 
 ```bash
-lark-cli approval tasks query --params '{"topic":"1"}' --as user
-lark-cli approval tasks approve --data '{"instance_code":"<ic>","task_id":"<tid>","comment":"同意"}' --as user
+lark-cli schema approval.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli approval <resource> <method> [flags] # 调用 API
 ```
 
-## 不在本 skill 范围
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+### instances
+
+  - `get` — 获取单个审批实例详情
+  - `cancel` — 撤回审批实例
+  - `cc` — 抄送审批实例
+  - `initiated` — 查询用户的已发起列表
+
+### tasks
+
+  - `remind` — 催办审批人
+  - `approve` — 同意审批任务
+  - `reject` — 拒绝审批任务
+  - `transfer` — 转交审批任务
+  - `query` — 查询用户的任务列表
+  - `add_sign` — 审批任务加签
+  - `rollback` — 退回审批任务
+
+## 权限表
+
+| 方法 | 所需 scope |
+|------|-----------|
+| `instances.get` | `approval:instance:read` |
+| `instances.cancel` | `approval:instance:write` |
+| `instances.cc` | `approval:instance:write` |
+| `instances.initiated` | `approval:instance:read` |
+| `tasks.remind` | `approval:instance:write` |
+| `tasks.approve` | `approval:task:write` |
+| `tasks.reject` | `approval:task:write` |
+| `tasks.transfer` | `approval:task:write` |
+| `tasks.query` | `approval:task:read` |
+| `tasks.add_sign` | `approval:task:write` |
+| `tasks.rollback` | `approval:task:write` |
 
-创建审批定义/发起新审批（走飞书客户端或审批管理后台）；非审批类待办 → [`lark-task`](../lark-task/SKILL.md)

skills/lark-calendar/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-calendar
 version: 1.0.0
-description: "飞书日历：管理日历日程和会议室。查看/搜索日程、创建/更新日程、管理参会人、查询忙闲和推荐时段、预定会议室。当用户需要查看日程安排、创建/修改会议、查询/预定会议室时使用。不负责：查询过去的视频会议记录（走 lark-vc）、待办任务（走 lark-task）。"
+description: "飞书日历（calendar）：提供日历与日程（会议）的全面管理能力。核心场景包括：查看/搜索日程、创建/更新日程、管理参会人、查询忙闲状态及推荐空闲时段、查询/搜索与预定会议室。注意：涉及【预约日程/会议】或【查询/预定会议室】时，必须先读取 references/lark-calendar-schedule-meeting.md 工作流！高频操作请优先使用 Shortcuts：+agenda（快速概览今日/近期行程）、+create（创建日程并按需邀请参会人及预定会议室）、+update（更新既有日程字段，或独立增删参会人/会议室）、+freebusy（查询用户主日历的忙闲信息和rsvp的状态）、+rsvp（回复日程邀请）"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -10,88 +10,93 @@ metadata:
 
 # calendar (v4)
 
-开始前先读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)（认证、权限处理）。
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+**CRITICAL — 所有的 Shortcuts 在执行之前，务必先使用 Read 工具读取其对应的说明文档，禁止直接盲目调用命令。**
+**CRITICAL — 凡涉及【预约日程/会议】或【查询/搜索会议室】，第一步 MUST 强制使用 Read 工具读取 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。禁止跳过此步直接调用 API 或 Shortcut！**
+**CRITICAL — 术语约束：用户日常表达中常说的“帮我约个日历”、“查一下今天的日历”等，其实际意图通常是针对 日程（Event） 的创建或查询，而非操作 日历（Calendar） 容器本身。请自动将口语化的“日历”意图映射为“日程”操作（如 `+create`, `+agenda`）。**
+**CRITICAL — 会议与日程的意图路由：**
+- **查询过去时间的会议**：如果用户明确查询过去时间的会议（如“昨天的会议”、“上周的会议”），**优先使用 [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md) 搜索会议记录**。因为会议数据不仅包含从日程发起的视频会议，还包含即时会议，仅查询日程数据会导致结果不全。
+- **查询日历/日程或未来时间的会议**：如果用户明确表达的是“日历”、“日程”，或者涉及**未来时间**的安排，则属于本技能（lark-calendar）的业务域，请继续使用本技能处理。
+**CRITICAL — 任务类型分流：处理“预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间”时，必须先判断用户是在“新建日程”还是“编辑已有日程”。**
+- **编辑已有日程的强信号**：用户明确提到某个已存在的日程锚点（如标题、时间段、`这个日程`、`这场会`）并表达修改动作（如“添加”“移除”“改到”“换会议室”“调整时间”）。这类请求默认走**编辑已有日程**，绝不能直接按新建处理。
+- **编辑已有日程的前置步骤**：一旦判定为编辑，MUST 先定位目标日程或具体实例的 `event_id`，再继续后续流程。若是重复性日程，MUST 先定位到对应实例的 `event_id`。
+- **新建日程**：只有当用户表达的是“新约一个会/创建一个日程/安排一次会议”等新增意图，且没有指向某个既有日程的修改动作时，才进入新建流程。
 
-**CRITICAL — 凡涉及预约日程/会议或查询/搜索会议室，第一步 MUST 读 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。禁止跳过此步直接调用 API 或 Shortcut！**
+**CRITICAL — 验证与同步延迟：在涉及删除日程（delete）、修改日程（patch）或者涉及添加移除参与人/会议室之后，如果需要进行二次查询验证操作结果，MUST 等待至少 2 秒后再进行查询，以防止因数据同步延迟导致查不到最新数据。注意：不要向用户提及你等待了这 2 秒钟的事情。**
 
-## 身份
+**CRITICAL — 重复性日程的实例操作：目前已经完全具备对重复性日程的某个具体实例进行操作的能力（例如：编辑某个实例、删除某个实例、为某个实例添加/删除参与人、为某个实例添加/移除会议室）。只要在对应的操作中传递对应实例的 `event_id` 即可。因此，MUST 先定位到对应的那次实例的 `event_id`（可通过 `events search_event` 搜索日程，或 `+agenda` 查看对应时间范围的日程等相关查询获取），绝对禁止直接使用原重复性日程的 `event_id` 进行操作。**
 
-日程操作默认使用 `--as user`（查看和管理当前用户的日程）。`--as bot` 只能访问 bot 自己的（空）日历，会拿到空结果——不要用 bot 身份查用户日程。
+**时间与日期推断规范：**
+为确保准确性，在涉及时间推断时，请严格遵循以下规则：
+- **星期的定义**：周一是一周的第一天，周日是一周的最后一天。计算`下周一`等相对日期时，务必基于当前真实日期和星期基准进行推算，避免算错日期。
+- **一天的范围**：当用户提到`明天`、`今天`等泛指某一天时，时间范围应默认覆盖整天时间范围。**切勿**自行缩减查询范围，以免遗漏晚上的时间安排。
+- **历史时间约束**：不能预约已经完全过去的时间。唯一的例外情况是“跨越当前时间”的日程，即日程的开始时间在过去，但结束时间在未来。
 
-```bash
-# BAD — bot 身份查用户日程，返回空列表
-lark-cli calendar +agenda --as bot
+## 核心场景
 
-# GOOD — user 身份查日程
-lark-cli calendar +agenda --as user
+### 1. 预约新日程/会议、编辑已有日程、查询/搜索可用会议室
+**BLOCKING REQUIREMENT (阻塞性要求): 只要用户的意图包含“预约日程/会议”或“查询/搜索可用会议室”，你必须立即停止其他思考，优先使用 Read 工具完整读取 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)！未读取该文件前，绝对禁止执行任何日程创建或会议室查询操作。**
+**CRITICAL: 必须严格按照上述文档中定义的工作流（Workflow）执行后续操作。处理该场景时，默认做“智能助理”，不要做“表单填写机”。能补全的默认值先补全，只有在时间冲突、结果无法唯一确定、时间语义存在歧义时才主动追问。**
+**CRITICAL: 执行顺序必须固定为：先判断任务类型（新建/编辑）；若为编辑先定位目标日程 `event_id`；再补默认值或继承已定位日程的已知信息；再判断时间是否明确；最后进入“明确时间”或“模糊时间/无时间信息”分支。不要跳步。**
+**CRITICAL: 明确时间且需要会议室时，先基于最终确定的时间块执行 `+room-find`，再按需执行 `+freebusy`；模糊时间或无时间信息时，先 `+suggestion`，如需会议室再批量 `+room-find`。如果是编辑已有日程且不改时间，只新增会议室，则必须基于已定位日程的原始时间执行 `+room-find`，且最终落地时默认保留已存在的会议室；只有用户明确表达“更换会议室”或“移除会议室”时，才删除原会议室。**
+**CRITICAL: 当用户说“查会议室”“找会议室”“搜可用会议室”或“推荐常用会议室”时，默认是查会议室可用性，不是查会议室资源名录，更严禁拉取历史日程做统计分析。完整规则以 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) 为准。**
+**BLOCKING REQUIREMENT: 即使用户的核心诉求是“查会议室”，只要【没有提供明确的起止时间】，绝对禁止直接调用 `+room-find`！必须先进入【无时间/模糊时间】分支，调用 `+suggestion` 拿到候选时间块后，再将时间块传给 `+room-find`。**
+**BLOCKING REQUIREMENT: 只要面临时间方案或会议室方案的选择（如模糊时间、无时间或需要会议室），在最终执行创建新日程或更新既有日程之前，必须先向用户展示候选方案并等待用户明确确认。绝对禁止擅自替用户做决定。**
+
+## 核心概念
+
+- **日历（Calendar）**：日程的容器。每个用户有一个主日历（primary calendar），也可以创建或订阅共享日历。
+- **日程（Event）**：日历中的单个日程，包含起止时间、地点、标题、参与人等属性。支持单次日程和重复日程，遵循RFC5545 iCalendar国际标准。
+- ***全天日程（All-day Event）***: 只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
+- **日程实例（Instance）**：日程的具体时间实例，本质是对日程的展开。普通日程和例外日程对应1个Instance，重复性日程对应N个Instance。在按时间段查询时，可通过实例视图将重复日程展开为独立的实例返回，以便在时间线上准确展示和管理。
+- **重复规则（Rrule/Recurrence Rule）**：定义重复性日程的重复规则，比如`FREQ=DAILY;UNTIL=20230307T155959Z;INTERVAL=14`表示每14天重复一次。
+- **例外日程（Exception）**：重复性日程中与原重复性日程不一致的日程。
+- **参会人（Attendee）**：日程的参与者，可以是用户、群、会议室资源、外部邮箱地址等。每个参与人有独立的RSVP状态。
+- **响应状态（RSVP）**：参与人对日程邀请的回复状态（接受/拒绝/待定）。
+- **忙闲时间（FreeBusy）**：查询用户在指定时间段的忙闲状态，用于会议时间协调。
+- **会议室（Room）**：“room”不是“房间”，是“会议室”。请在理解和处理意图时将“room”和“房间”准确映射为“会议室”及其相关操作。
+- **时间块（Time Slot / Time Block）**：指一个**具体且确定**的连续时间段（如 `14:00~15:00`）。在文档中，它与泛指的“时间范围/区间”（如“今天下午”、“下周”）有严格区别。在调用预定、查询可用会议室等确切操作时，必须基于确定的“时间块”而非模糊的“时间范围”。
+
+## 资源关系
+
+```
+Calendar (日历)
+└── Event (日程)
+    ├── Attendee (参会人)
+    └── Reminder (提醒)
 ```
 
-## Shortcuts
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli calendar +<verb> [flags]`）。有 Shortcut 的操作优先使用。
 
 | Shortcut | 说明 |
 |----------|------|
 | [`+agenda`](references/lark-calendar-agenda.md) | 查看日程安排（默认今天） |
 | [`+create`](references/lark-calendar-create.md) | 创建日程并邀请参会人（ISO 8601 时间） |
 | [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室 |
-| [`+freebusy`](references/lark-calendar-freebusy.md) | 查询用户主日历的忙闲信息和 RSVP 状态 |
-| [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（无明确时间时禁止直接调用，需先走 +suggestion） |
+| [`+freebusy`](references/lark-calendar-freebusy.md) | 查询用户主日历的忙闲信息和rsvp的状态 |
+| [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（**无明确时间时禁止直接调用，需先走 +suggestion**） |
 | [`+rsvp`](references/lark-calendar-rsvp.md) | 回复日程（接受/拒绝/待定） |
 | [`+suggestion`](references/lark-calendar-suggestion.md) | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 |
 
-## 前置条件路由
+## 会议室相关规则
 
-| 场景 | 前置要求 |
-|------|----------|
-| 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
-| 编辑已有日程 | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
-| 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
-| 调用任何 Shortcut | 先读其对应 reference 文档 |
-
-## 核心概念
-
-- **日程实例（Instance）**：重复性日程展开后的具体时间实例。操作重复日程的某次实例时，必须先定位该实例的 `event_id`，禁止使用原重复日程的 `event_id`。
-- **全天日程（All-day Event）**：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
-- **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
-- **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
-
-## 术语映射
-
-用户日常说的"帮我约个日历""查一下今天的日历"，实际意图是针对**日程（Event）**的创建或查询，而非操作日历（Calendar）容器本身。自动将口语化的"日历"意图映射为"日程"操作。
-
-## 意图路由
-
-| 用户意图 | 路由到 |
-|----------|--------|
-| 查询过去的会议（"昨天的会议""上周的会"） | [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md)（会议数据含即时会议，仅查日程会遗漏） |
-| 查询日历/日程或未来时间的会议 | 本 skill |
-| 预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
-
-## 任务类型分流
-
-处理"预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间"时，必须先判断新建 vs 编辑：
-
-- **编辑已有日程的强信号**：用户提到已存在的日程锚点（标题、时间段、`这个日程`、`这场会`）并表达修改动作（添加、移除、改到、换会议室、调整时间）。默认走编辑流，绝不能按新建处理。
-- **新建日程**：用户表达新增意图（"新约一个会""创建一个日程""安排一次会议"），且没有指向既有日程的修改动作。
-
-## 时间推断规范
-
-- **星期的定义**：周一是一周的第一天，周日是最后一天。计算"下周一"等相对日期时，基于当前真实日期推算。
-- **一天的范围**：用户提到"明天""今天"等泛指某天时，时间范围应覆盖整天，不要自行缩减。
-- **历史时间约束**：不能预约已经完全过去的时间。唯一例外是"跨越当前时间"的日程（开始在过去、结束在未来）。
-
-## 会议室规则
-
-- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)。
-- `+room-find` 的时间输入必须是确定时间块，不能是时间区间搜索。
-- 用户仅要求"查会议室"但未提供明确时间时，必须先调用 `+suggestion` 获取可用时间块，再将时间块交给 `+room-find`。严禁猜测时间盲目调用。
-- 编辑已有日程时，"添加会议室"默认是增量语义，保留已有会议室；只有用户明确说"更换会议室""移除会议室"时才删除旧会议室。
+- **会议室是日程的一种参与人（resource attendee），不能脱离日程单独存在或单独预定。**
+- **凡是用户意图是“预定/查询/搜索可用会议室”时，都必须进入 `references/lark-calendar-schedule-meeting.md` 工作流处理。**
+- `+room-find` 的时间输入必须是**确定时间块**，不能是时间区间搜索。
+- **强制约束：如果用户仅要求“查询会议室”但未提供明确时间，必须先调用 `+suggestion` 获取可用时间块，然后再将时间块交给 `+room-find` 批量查询。严禁直接猜测时间并盲目调用 `+room-find`。**
+- **编辑已有日程时，如果用户表达的是“添加会议室/再加一个会议室”，默认语义是增量添加，必须保留已有会议室；只有在用户明确表达“更换会议室”“把原会议室换掉”“移除会议室”时，才执行旧会议室删除。**
 
 ## API Resources
 
 ```bash
-lark-cli calendar <resource> <method> [flags]
+lark-cli schema calendar.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli calendar <resource> <method> [flags] # 调用 API
 ```
 
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
 ### calendars
 
   - `create` — 创建共享日历
@@ -115,18 +120,35 @@ lark-cli calendar <resource> <method> [flags]
   - `get` — 获取日程
   - `instance_view` — 查询日程视图
   - `patch` — 更新日程
-  - `search_event` — 搜索日程（仅返回 日程ID/主题/时间，详情需走 `events get`）
+  - `search_event` — 搜索日程（注：目前只会返回日程id、日程主题、日程时间的信息，需要更多的日程详情，需要走 `events get` 命令）
   - `share_info` — 获取日程分享链接
 
 ### freebusys
 
   - `list` — 查询主日历日程忙闲信息
 
-## 不在本 skill 范围
+## 权限表
 
-- 查询过去的视频会议记录 → [lark-vc](../lark-vc/SKILL.md)
-- 待办任务管理 → [lark-task](../lark-task/SKILL.md)
-- 会议室物理设施管理 → 管理员后台
+| 方法 | 所需 scope |
+|------|-----------|
+| `calendars.create` | `calendar:calendar:create` |
+| `calendars.delete` | `calendar:calendar:delete` |
+| `calendars.get` | `calendar:calendar:read` |
+| `calendars.list` | `calendar:calendar:read` |
+| `calendars.patch` | `calendar:calendar:update` |
+| `calendars.primary` | `calendar:calendar:read` |
+| `calendars.search` | `calendar:calendar:read` |
+| `event.attendees.batch_delete` | `calendar:calendar.event:update` |
+| `event.attendees.create` | `calendar:calendar.event:update` |
+| `event.attendees.list` | `calendar:calendar.event:read` |
+| `events.create` | `calendar:calendar.event:create` |
+| `events.delete` | `calendar:calendar.event:delete` |
+| `events.get` | `calendar:calendar.event:read` |
+| `events.instance_view` | `calendar:calendar.event:read` |
+| `events.patch` | `calendar:calendar.event:update` |
+| `events.search_event` | `calendar:calendar.event:read` |
+| `events.share_info` | `calendar:calendar.event:read` |
+| `freebusys.list` | `calendar:calendar.free_busy:read` |
 
 **注意（强制性）：**
 - 涉及日期（时间）字符串与时间戳的相互转换时，务必调用系统命令或脚本代码等外部工具进行处理，以确保转换的绝对准确。违者将导致严重的逻辑错误！

skills/lark-doc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-doc
 version: 2.0.0
-description: "飞书云文档（Docx / Wiki 文档，v2 API）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。"
+description: "飞书云文档 / Docx / 知识库 Wiki 文档（v2）：创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token，或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、需要将重要信息可视化为画板（含 SVG 画板）、引用或同步块时，也先用本 skill 读取和提取 token，再切到对应 skill 下钻。默认使用 DocxXML，也支持 Markdown。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -10,9 +10,7 @@ metadata:
 
 # docs (v2)
 
-**身份：文档操作默认使用 `--as user`。首次使用前执行 `lark-cli auth login`。**
-
-> **CRITICAL — API 版本：本 skill 使用 v2 API。执行 `docs +create`、`docs +fetch`、`docs +update` 时必须显式传入 `--api-version v2`。**
+> **⚠️ API 版本：本 skill 使用 v2 API。所有 `docs +create --api-version v2`、`docs +fetch --api-version v2`、`docs +update --api-version v2` 命令必须携带 `--api-version v2`。**
 
 ```bash
 # 常用示例
@@ -71,9 +69,3 @@ Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）
 | [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) |
 | [`+media-preview`](references/lark-doc-media-preview.md) | Preview document media file (auto-detects extension) |
 | [`+whiteboard-update`](../lark-whiteboard/references/lark-whiteboard-update.md) | Alias of `whiteboard +update`. Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer `whiteboard +update`; refer to lark-whiteboard skill for details. |
-
-## 不在本 Skill 范围
-
-- 文档评论管理 → [`lark-drive`](../lark-drive/SKILL.md)
-- 电子表格或 Base 的数据操作 → [`lark-sheets`](../lark-sheets/SKILL.md) / [`lark-base`](../lark-base/SKILL.md)
-- 云空间文件上传、下载、权限管理 → [`lark-drive`](../lark-drive/SKILL.md)

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

@@ -73,7 +73,7 @@ lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项
 ## 最佳实践
 
 - 文档标题从内容中自动提取（XML `<title>` 或 Markdown `#`），不要在内容开头重复写标题
-- **创建较长的文档时只建骨架**：`--content` 仅传标题 + 各级 heading + 简短占位摘要；正文留给后续 `block_insert_after --block-id <章节标题 block_id>` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。
+- **创建较长的文档时只建骨架**：`--content` 仅传标题 + 各级 heading + 简短占位摘要；正文留给后续 `docs +update --command append` 或 `block_insert_after` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。
 - **视觉丰富度**：必须遵循 [`lark-doc-style.md`](style/lark-doc-style.md) 中的样式指南，主动使用结构化 block 丰富文档
 
 ## 参考

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

@@ -26,7 +26,7 @@
 | `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
 | `--content` | 视指令 | 写入内容（`str_replace` 传空字符串可实现删除） |
 | `--pattern` | 视指令 | 匹配文本（str_replace） |
-| `--block-id` | 视指令 | 目标 block ID（block_* 操作），逗号分隔可批量删除，-1 表示末尾 |
+| `--block-id` | 视指令 | 目标 block ID（block_* 操作）,-1 表示末尾 |
 | `--src-block-ids` | 视指令 | 源 block ID（逗号分隔），用于 block_copy_insert_after / block_move_after |
 | `--revision-id` | 否 | 基准版本号，-1 = 最新（默认 `-1`） |
 
@@ -40,8 +40,8 @@
 | `block_replace` | 替换指定 block（同一 block 仅限一次） | `--block-id` `--content` |
 | `block_delete` | 删除指定 block（逗号分隔可批量） | `--block-id` |
 | `overwrite` | ⚠️ 清空文档后全文重写（可能丢失图片、评论） | `--content` |
-| `append` | ⚠️ 在文档**末尾**追加内容（等价于 `block_insert_after --block-id -1`）。**不适用于逐章填充**——逐章写入请用 `block_insert_after` 并指定对应标题的 `--block-id` | `--content` |
-| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` `--src-block-ids` |
+| `append` | 在文档末尾追加内容（等价于 `block_insert_after --block-id -1`） | `--content` |
+| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` + (`--content` 或 `--src-block-ids`) |
 
 ## 指令示例
 
@@ -116,9 +116,8 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_replace
 ### block_delete — 删除指定 block
 
 ```bash
-# 删除多个块时用逗号 "," 分隔
 lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_delete \
-  --block-id "block_id_1,block_id_2,block_id_3"
+  --block-id "目标 block_id"
 ```
 
 ### overwrite — 全文覆盖

skills/lark-doc/references/lark-doc-xml.md

@@ -45,7 +45,6 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 - `<sheet>` — `<sheet type="blank"></sheet>` 空白；`<sheet sheet-id="SID" token="TOKEN"></sheet>` 复制已有
 - `<task>` — `<task task-id="GUID"></task>`，必传 task-id（任务 guid）
 - `<chat_card>` — `<chat_card chat-id="CHAT_ID"></chat_card>`，必传 chat-id
-- `<sub-page-list>` — `<sub-page-list></sub-page-list>` 子页面列表块；仅 wiki 文档可插入
 - bitable、base_ref、synced_reference、synced_source、okr — 不可创建，仅支持移动
 
 # 四、块级复制与移动
@@ -55,7 +54,7 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 
 ## 复制（block_copy_insert_after）
 - **基础标签**（块级标签、容器标签、行内组件）：均支持复制
-- **资源块**：仅 img、source、whiteboard、sheet、chat_card、sub-page-list 支持复制；task、bitable、base_ref、synced_reference、synced_source、okr 不支持复制
+- **资源块**：仅 img、source、whiteboard、sheet、chat_card 支持复制；task、bitable、base_ref、synced_reference、synced_source、okr 不支持复制
 
 使用 `docs +update --command block_copy_insert_after --block-id "<锚点>" --src-block-ids "id1,id2"`。
 
@@ -167,5 +166,4 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 
 <task task-id="TASK_GUID"></task>
 <chat_card chat-id="CHAT_ID"></chat_card>
-<sub-page-list></sub-page-list>
 ```

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

@@ -22,14 +22,14 @@
 2. 设计大纲——每个 h1/h2 章节至少规划 1 个非文本 block；承载重要信息的章节优先规划画板
 3. `docs +create --api-version v2` **只建骨架**：标题 + 开头 `<callout>` + 各级标题 + 每节一句占位摘要
    - ⚠️ **不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
-   - 完整内容留到第二波，由各 Agent 用 `block_insert_after --block-id <章节标题 block_id>` 分段写入。
+   - 完整内容留到第二波，由各 Agent 用 `docs +update --command append` 或 `block_insert_after` 分段写入。
 
 ### 第二波 — 内容撰写（并行 Agent）
 
 4. Spawn Agent 并行撰写各章节。每个 Agent 需收到：
    - 文档 token、负责的章节范围、期望的 block 类型
    - `lark-doc-xml.md` 和 `lark-doc-style.md` 的完整路径（Agent 须先读取）
-   - 使用 `block_insert_after --block-id <章节标题 block_id>` 写入对应章节内容
+   - 使用 `docs +update --command append` 或 `block_insert_after` 写入
 
 ### 第三波 — 整合审查 + 画板意图识别（串行）
 

skills/lark-drive/SKILL.md

@@ -20,7 +20,6 @@ metadata:
 
 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--mine`，实为 owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
-- 用户要**根据文档评论定位正文位置**，例如 根据评论 review 文档、根据评论内容回看文档、区分多处相同引用文本时，对于 docx 类型（`file_type=docx`）的文档支持通过 `need_relation=true` 返回评论位置，其他类型暂不支持，具体用法需要先阅读 [`references/lark-drive-comment-location.md`](references/lark-drive-comment-location.md) 了解。
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
@@ -33,8 +32,6 @@ metadata:
 - 用户要获取某个文件的封面图，优先使用 `lark-cli drive +cover`；先 `--list-only` 看规格，再选 `--spec` 下载。
 - 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
-- 用户给的是 wiki URL / token，且后续还没明确底层资源类型时，先用 `lark-cli drive +inspect` 解包；`+inspect` 失败后不要自动切到别的写接口继续尝试，先按错误提示处理权限、scope 或链接问题。
-- `drive +inspect` / `drive +upload` 遇到 `not found`、`permission denied`、`missing scope` 时，默认停止重试；只有 `rate limit` 或临时网络错误才适合有限重试。
 
 ## 修改标题
 - 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型
@@ -218,9 +215,6 @@ lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "
 - 使用 `drive file.comments batch_query` 是**已知评论 ID 后**的批量查询，需要传入具体的评论 ID 列表。
 - 使用 `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论，或获取"最新/最后 N 条评论"等场景。
 
-#### 评论定位字段
-- 需要根据评论定位到文档正文位置时（例如根据评论 review 文档、区分多处相同引用文本、把评论落点映射到 `docs +fetch` 的 block），先确认目标是 `file_type=docx`，再阅读 [评论定位字段说明](references/lark-drive-comment-location.md)，其他文档类型暂不支持返回定位字段。
-
 #### Reaction / 表情场景
 - 遇到评论 / 回复上的 reaction（表情、各表情数量、谁点了什么、添加/删除表情）相关问题时，**先阅读 [lark-drive-reactions.md](../../skills/lark-drive/references/lark-drive-reactions.md) 了解如何使用**。
 

skills/lark-drive/references/lark-drive-comment-location.md

@@ -1,193 +0,0 @@
-# 文档评论定位字段
-
-当用户需要根据评论定位文档正文位置、对文档做 review、区分多处相同引用文本，或把评论落点映射到 `docs +fetch --detail with-ids` 的内容时，docx 文档的评论查询必须带 `need_relation=true`。
-
-## 适用范围
-
-- 当前只有 `file_type=docx` 支持通过 `need_relation=true` 查询评论的位置，并返回可用于定位正文 block 的 `relation`、`parent_type`、`parent_token` 等字段。
-- 其他文件类型暂不支持通过 `need_relation` 查询评论位置。遇到 sheet、bitable、slides、普通文件等类型的评论时，不要承诺可以用 `need_relation` 精确定位正文位置，应退回普通评论字段、对应资源能力下钻或人工确认。
-
-## 调用方式
-
-分页列出评论时，把 `need_relation` 放在 query params：
-
-```bash
-lark-cli drive file.comments list \
-  --params '{"file_token":"<doc_token>","file_type":"docx","is_solved":false,"need_relation":true}'
-```
-
-已知评论 ID 批量查询时，把 `need_relation` 放在请求体里：
-
-```bash
-lark-cli drive file.comments batch_query \
-  --params '{"file_token":"<doc_token>","file_type":"docx"}' \
-  --data '{"comment_ids":["<comment_id>"],"need_relation":true}'
-```
-
-同时获取文档内容，并要求返回 block id：
-
-```bash
-lark-cli docs +fetch --api-version v2 --doc '<doc_token_or_url>' --detail with-ids
-```
-
-## 字段含义
-
-- `relation`：评论在文档内容中的结构化位置。`relation.relation` 是一个 JSON 字符串，需要再解析一次；其中 `positionInfo.blockID` 是最关键字段，用于匹配 `docs +fetch --detail with-ids` 返回的文档 block。
-- `relation.content_deleted`：评论引用的内容是否已被删除。为 `true` 时，不要假设还能在当前正文中找到原位置。
-- `parent_type`：评论所在的父级嵌入资源类型。常见值包括 `SHEET_BLOCK`、`BITABLE_BLOCK`、`WHITEBOARD_BLOCK`，表示评论落在文档内嵌电子表格、多维表格或画板内部。
-- `parent_token`：父级嵌入资源 token。对 sheet / bitable / whiteboard 内部评论，服务端可能无法给出内部单元格、记录或画板节点的文档 block 级 `relation`，但可以通过 `parent_type` + `parent_token` 定位到文档里的父级嵌入 block。
-
-## 准确度分级
-
-输出定位结论时，必须区分以下三类，不要把弱推断说成精确定位：
-
-| 等级 | 判定条件 | 输出口径 |
-|---|---|---|
-| `relation 精确` | `relation.relation` 中有 `positionInfo.blockID`，且能在 `docs +fetch --detail with-ids` 中匹配到同一 block | 可说“准确定位到 block” |
-| `父级资源精确，内部需下钻` | 只有父级嵌入资源的 `blockID` / `parent_type` / `parent_token`，或内部资源的 `positionInfo` 为空 | 可说“准确定位到嵌入资源；内部单元格/记录/节点需用对应 skill 下钻确认” |
-| `弱匹配/推断` | 只能依赖 `quote`、序号、当前展示顺序或文本搜索 | 必须标明“推断”，说明歧义来源和需要的补充信息 |
-
-## 返回示例
-
-普通 docx block 上的评论会返回 `relation`。注意 `relation.relation` 本身是字符串，需要再 JSON parse 一次：
-
-```json
-{
-  "comment_id": "7646774324967295982",
-  "quote": "code2",
-  "relation": {
-    "content_deleted": false,
-    "relation": "{\"22-doc_token_xxx\":{\"objType\":22,\"index\":2,\"objVersion\":10,\"positionInfo\":{\"blockID\":\"block_id_xxx\"}}}"
-  },
-  "parent_type": null,
-  "parent_token": null
-}
-```
-
-把 `relation.relation` 再解析后，取 `positionInfo.blockID`：
-
-```json
-{
-  "22-doc_token_xxx": {
-    "objType": 22,
-    "index": 2,
-    "objVersion": 10,
-    "positionInfo": {
-      "blockID": "block_id_xxx"
-    }
-  }
-}
-```
-
-然后在 `docs +fetch --detail with-ids` 的结果里查找同一个 block id，例如：
-
-```json
-{
-  "block_id": "block_id_xxx",
-  "block_type": "code",
-  "text": "code1\ncode2"
-}
-```
-
-嵌入 sheet / bitable / whiteboard 内部评论可能没有可用 `relation`，但会返回父级标记：
-
-```json
-{
-  "comment_id": "7646775036988148672",
-  "quote": "记录 2",
-  "relation": null,
-  "parent_type": "BITABLE_BLOCK",
-  "parent_token": "bitable_app_token_xxx_table_id_xxx"
-}
-```
-
-这种情况下，用 `parent_type` 判断目标是嵌入资源，再用 `parent_token` 匹配 `docs +fetch --detail with-ids` 中的 bitable / sheet block。定位粒度是文档里的父级嵌入 block，不是内部记录、字段或单元格。
-
-画板内部评论的返回形态类似：
-
-```json
-{
-  "comment_id": "7646775036988148673",
-  "quote": "画板节点文本",
-  "relation": null,
-  "parent_type": "WHITEBOARD_BLOCK",
-  "parent_token": "whiteboard_token_xxx"
-}
-```
-
-此时 `parent_token` 对应 `docs +fetch --detail with-ids` 结果中 `<whiteboard>` 的 `token` 属性，例如：
-
-```xml
-<whiteboard id="whiteboard_block_id_xxx" token="whiteboard_token_xxx"></whiteboard>
-```
-
-匹配到这个 `<whiteboard>` 后，`id` 就是文档正文里的父级画板 block id。定位粒度是文档里的画板 block；如果需要继续定位到画板内部具体节点，需要再用画板能力读取画板内部结构。
-
-## 定位流程
-
-1. 确认目标是 `file_type=docx`；只有 docx 文档支持通过 `need_relation` 查询评论位置。
-2. 用 `drive file.comments list` 或 `drive file.comments batch_query` 获取评论，并带 `need_relation=true`。
-3. 用 `docs +fetch --api-version v2 --detail with-ids` 获取文档内容。
-4. 对每条评论先看 `relation`：
-   - 如果存在 `relation.relation`，解析这个 JSON 字符串。
-   - 从解析结果里取 `positionInfo.blockID`。
-   - 在 `docs +fetch` 结果中查找相同 block id，这就是评论对应的文档 block。
-5. 如果没有可用 `relation`，但有 `parent_type` 和 `parent_token`：
-   - `SHEET_BLOCK`：定位到文档中的 sheet 嵌入 block；`parent_token` 通常包含 sheet token 和 sheet id，必要时取 `_` 前的 token 与文档 block 的嵌入资源 token 对比。
-   - `BITABLE_BLOCK`：定位到文档中的 bitable 嵌入 block；`parent_token` 通常包含 bitable app token 和 table id，必要时取 `_` 前的 token 与文档 block 的嵌入资源 token 对比。
-   - `WHITEBOARD_BLOCK`：定位到文档中的 whiteboard 嵌入 block；`parent_token` 对应 `docs +fetch --detail with-ids` 中 `<whiteboard>` 的 `token` 属性。
-   - 这种场景能定位到父级嵌入 block，但通常不能仅凭评论接口定位到嵌入资源内部的具体单元格、字段、记录或画板节点。
-6. 只有在 `relation`、`parent_type`、`parent_token` 都缺失时，才退回使用 `quote` 文本做弱匹配；`quote` 是评论接口返回的引用文本字段。弱匹配不能区分多处相同文本。
-
-## 嵌入资源内部定位
-
-### Sheet 内部评论
-
-- `parent_token` 常见格式是 `<spreadsheet_token>_<sheet_id>`；也可能在 `relation.relation` 中看到 `subToken` 为 `3-<spreadsheet_token>`。
-- 评论接口通常只把 `positionInfo.blockID` 指到文档里的 `<sheet>` block，内部 sheet 的 `positionInfo` 可能为空。
-- 如果 `quote` 是 `C3`、`A1` 这类单元格坐标，可拆出 `spreadsheet_token` / `sheet_id` 后用 `lark-sheets` 读取该单元格确认：
-
-```bash
-lark-cli sheets +read \
-  --spreadsheet-token '<spreadsheet_token>' \
-  --sheet-id '<sheet_id>' \
-  --range '<cell>'
-```
-
-- 准确度口径：父级 sheet block 可由 relation/parent token 精确定位；单元格坐标若只来自 `quote`，应说明“单元格来自 quote，已通过 sheets 读取验证”，不要说它来自 `positionInfo`。
-
-### Bitable / Base 内部评论
-
-- `parent_token` 常见格式是 `<base_token>_<table_id>`，其中 `table_id` 通常以 `tbl` 开头。解析时优先按最后一个 `_tbl` 边界拆分，避免 base token 内出现 `_` 时误拆。
-- 评论接口可能只返回 `parent_type=BITABLE_BLOCK` 和 `parent_token`，没有 `relation`；即使有 relation，也通常只足够定位到文档里的 `<bitable>` block。
-- 下钻读取时切到 `lark-base`，最少确认表、字段、记录：
-
-```bash
-lark-cli base +table-list --base-token '<base_token>'
-lark-cli base +field-list --base-token '<base_token>' --table-id '<table_id>'
-lark-cli base +record-list --base-token '<base_token>' --table-id '<table_id>' --limit 200 --format json
-```
-
-- 如果 `quote` 是某个稳定业务值，优先用字段/记录数据做精确匹配；如果 `quote` 只是“第 N 条”“第 N 行”这类 UI 序号，只能基于当前记录顺序推断对应记录，必须输出为“推断”，并说明评论接口没有返回 `record_id` / `field_id`。
-- 如果 `record-list` 返回 `has_more=true`，不要基于第一页下全局结论；继续分页或说明只能覆盖已读取范围。
-- 需要写入时，如果评论没有字段信息，不要自行猜字段；除非用户给出默认规则，否则请求用户确认字段，或明确说明将使用哪个字段作为默认。
-
-### Whiteboard 内部评论
-
-- `parent_token` 对应文档 XML 中 `<whiteboard token="...">`；先用它匹配文档里的 whiteboard block。
-- 若要定位画板内部节点，切到 `lark-whiteboard` 读取 raw 节点结构：
-
-```bash
-lark-cli whiteboard +query \
-  --whiteboard-token '<whiteboard_token>' \
-  --output_as raw
-```
-
-- 如果 raw 节点中存在唯一匹配 `quote` 的文本节点，可定位到该节点；如果有多个相同文本节点，仍然是弱匹配，需要结合位置、样式、用户描述或人工确认。
-- 修改画板节点前，先说明匹配到的节点 id 和文本；复杂画板不要只凭 `quote` 批量替换全部同名节点。
-
-## 使用原则
-
-- Review 文档时，不要只依赖 `quote` 文本定位评论；多处相同文本会产生歧义。
-- 能拿到 `relation.positionInfo.blockID` 时，以 block id 为准，再用 block 内容理解上下文。
-- 对嵌入 sheet / bitable / whiteboard 内的评论，以父级嵌入 block 作为文档正文定位点；如需继续定位到表格单元格、多维表格记录或画板内部节点，需要再调用对应 sheet / bitable / whiteboard 能力读取内部数据。

skills/lark-event/SKILL.md

@@ -69,7 +69,7 @@ wait
 
 ### stdin EOF = graceful exit
 
-`event consume` treats stdin close as a shutdown signal (wired for AI subprocess callers). **Bounded runs are exempt: when `--max-events` or `--timeout` is set (> 0), stdin EOF is ignored and the run exits only via its own bound, timeout, or SIGTERM.** For unbounded runs, `< /dev/null` / `nohup` / systemd's default `StandardInput=null` will cause an immediate graceful exit (stderr `reason: signal`). To keep an unbounded run alive:
+`event consume` treats stdin close as a shutdown signal (wired for AI subprocess callers). `< /dev/null` / `nohup` / systemd's default `StandardInput=null` will cause an immediate graceful exit (stderr `reason: signal`). To keep running:
 
 - Feed stdin a source that never EOFs: `< <(tail -f /dev/null)`
 - Or run bounded: `--max-events N` / `--timeout D`
@@ -82,13 +82,8 @@ On exit, the last stderr line is `[event] exited — received N event(s) in Xs (
 |---|---|---|
 | 0 | `reason: limit` | `--max-events` reached |
 | 0 | `reason: timeout` | `--timeout` reached |
-| 0 | `reason: signal` | Ctrl+C / SIGTERM / stdin EOF (stdin EOF applies to unbounded runs only) |
-| 1 | JSON error envelope on stderr | Lark API business failure during pre-consume setup (for example subscription create/delete) |
-| 2 | JSON error envelope on stderr (no `exited` line) | Validation failure (unknown EventKey, bad `--param` / `--jq`, another bus already connected) |
-| 3 | JSON error envelope on stderr | Auth failure (missing token, missing scopes) |
-| 4 / 5 | JSON error envelope on stderr | Network / internal failure (bus startup, handshake, file I/O) |
-
-Startup and runtime failures emit a structured JSON envelope on stderr: `{"ok":false,"error":{"type","subtype","param","message","hint",...}}` (the envelope may also carry top-level `identity` / `_notice` siblings). Parse `error.type` / `error.subtype` to branch (e.g. `missing_scope` carries a `missing_scopes` list), `error.param` to find the offending flag, and `error.hint` for the recovery action — do not regex-match message text.
+| 0 | `reason: signal` | Ctrl+C / SIGTERM / stdin EOF |
+| non-0 | `Error: ...` (no `exited` line) | Startup / runtime failure (permissions, network, params, config) |
 
 Orchestrators should treat `reason: limit/timeout/signal` (all exit 0) as "business completion" and non-zero as "failure".
 

skills/lark-markdown/SKILL.md

@@ -15,7 +15,6 @@ metadata:
 ## 快速决策
 
 - 身份：Markdown 文件通常属于用户云空间资源，优先使用 `--as user`。如为自动化场景，或应用已创建并持有目标文件权限，可按场景使用 `--as bot`。首次以 `user` 身份访问前执行 `lark-cli auth login`
-- `markdown +create` / `+overwrite` 失败时，先判断是不是身份和权限问题：`bot` 更常见的是 app scope 或目标目录 ACL，`user` 更常见的是用户授权或用户 ACL；不要不加判断地来回切身份重试。
 
 - 用户要**上传、创建一个原生 `.md` 文件**，使用 `lark-cli markdown +create`
 - 用户要**比较原生 `.md` 文件的历史版本差异**，或比较远端 Markdown 与本地草稿，使用 `lark-cli markdown +diff`
@@ -25,7 +24,6 @@ metadata:
 - 用户要先拿 Markdown 文件的历史版本号，再做比较/下载/回滚，先用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +version-history`
 - 用户要把本地 Markdown **导入成在线新版文档（docx）**，不要用本 skill，改用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +import --type docx`
 - 用户要对 Markdown 文件做**rename / move / delete / 搜索 / 权限 / 评论**等云空间（云盘/云存储）操作，不要留在本 skill，切到 [`lark-drive`](../lark-drive/SKILL.md)
-- `markdown +create` / `+overwrite` 命中 `missing scope`、`permission denied`、`not found`、`version limit` 时，默认停止重试并按报错 hint 处理；只有 `rate limit` 或临时网络错误才做有限重试。
 
 ## 核心边界
 

skills/lark-minutes/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-minutes
 version: 1.0.0
-description: "飞书妙记：搜索妙记列表、查看妙记基础信息、下载妙记音视频文件、上传音视频生成妙记、更新妙记标题、替换说话人。当需要获取、操作或者生成妙记时使用。也支持将本地音视频文件转成纪要和逐字稿（优先使用本 skill，不要用 ffmpeg/whisper 本地转写）。不负责：获取会议关联妙记、纪要/逐字稿内容获取走 lark-vc"
+description: "飞书妙记：妙记相关基本功能。1.查询妙记列表（按关键词/所有者/参与者/时间范围）；2.获取妙记基础信息（标题、封面、时长 等）；3.下载妙记音视频文件；4.获取妙记相关 AI 产物（总结、待办、章节）；5.上传音视频生成妙记，也支持将本地音视频文件转成纪要、逐字稿、文字稿、撰写文字等产物；6.更新妙记标题（重命名妙记）；7.替换妙记逐字稿中的说话人。遇到这类请求时，应优先使用本 skill。飞书妙记 URL 格式: http(s)://<host>/minutes/<minute-token>"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -18,40 +18,10 @@ metadata:
 > 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
 > 4. 了解会议总结、分析和信息提取的标准流程
 
-## 身份
-
-所有 minutes 命令默认使用 `--as user`。
-
-## Shortcuts
-
-| Shortcut | 说明 |
-|----------|------|
-| [`+search`](references/lark-minutes-search.md) | 按关键词、所有者、参与者、时间范围搜索妙记 |
-| [`+download`](references/lark-minutes-download.md) | 下载妙记音视频媒体文件 |
-| [`+upload`](references/lark-minutes-upload.md) | 上传 file_token 生成妙记 |
-| [`+update`](references/lark-minutes-update.md) | 更新妙记标题 |
-| [`+speaker-replace`](references/lark-minutes-speaker-replace.md) | 替换妙记逐字稿中的说话人（仅支持用户 ID，不支持姓名） |
-
-- 使用任何 Shortcut 前，必须先读其对应 reference 文档。
-
-## 意图路由
-
-| 用户意图 | 路由到 |
-|----------|--------|
-| "我的妙记""搜索妙记""妙记列表" | 本 skill（`+search`） |
-| "这个妙记的标题/时长/封面/链接" | 本 skill（`minutes get`） |
-| "下载妙记的视频/音频" | 本 skill（`+download`） |
-| "把音视频转妙记/上传文件生成妙记" | 本 skill（`+upload`） |
-| "重命名妙记/改妙记标题" | 本 skill（`+update`） |
-| "替换说话人/把 A 的发言改成 B" | 本 skill（`+speaker-replace`） |
-| "这个妙记的逐字稿/总结/待办/章节" | [lark-vc](../lark-vc/SKILL.md)（`vc +notes --minute-tokens`） |
-| "把音视频文件转成纪要/逐字稿/文字稿" | 先本 skill（`+upload`），再 [lark-vc](../lark-vc/SKILL.md)（`vc +notes --minute-tokens`） |
-| 用户同时提到"会议/开会"和"妙记" | 先 [lark-vc](../lark-vc/SKILL.md)（`+search` → `+recording`），再本 skill |
-
 ## 核心概念
 
 - **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，通过 `minute_token` 标识。
-- **妙记 Token（minute_token）**：妙记的唯一标识符，可从妙记 URL 末尾提取（如 `https://*.feishu.cn/minutes/obcnxxx` 中的 `obcnxxx`）。如果 URL 中包含额外参数（如 `?xxx`），截取路径最后一段。
+- **妙记 Token（minute\_token）**：妙记的唯一标识符，可从妙记 URL 末尾提取（例如 `https://*.feishu.cn/minutes/obcnxxxxxxxxxxxxxxxxxxxx` 中的 `obcnxxxxxxxxxxxxxxxxxxxx`）。如果 URL 中包含额外参数（如 `?xxx`），应截取路径最后一段。
 
 ## 核心场景
 
@@ -60,7 +30,7 @@ metadata:
 1. 当用户描述的是"我的妙记""包含某个关键词的妙记""某段时间内的妙记"，优先使用 `minutes +search`。
 2. 仅支持使用关键词、时间段、参与者、所有者等筛选条件搜索妙记记录，对于不支持的筛选条件，需要提示用户。
 3. 搜索结果存在多条数据时，务必注意分页数据获取，不要遗漏任何妙记记录。
-4. 如果是会议的妙记，应优先通过 [lark-vc](../lark-vc/SKILL.md) 定位会议并获取 `minute_token`。
+4. 如果是会议的妙记，应优先使用 [vc +search](../lark-vc/references/lark-vc-search.md) 先定位会议，再按需通过 [vc +recording](../lark-vc/references/lark-vc-recording.md) 获取 `minute_token`。
 5. 会议场景的妙记路由，以及"参与的妙记"如何解释，统一以 [minutes +search](references/lark-minutes-search.md) 为准。
 
 
@@ -76,7 +46,7 @@ metadata:
 ### 3. 下载妙记音视频文件
 
 1. 下载妙记音视频文件到本地，或获取有效期 1 天的下载链接。详见 [minutes +download](references/lark-minutes-download.md)。
-2. `+download` 只负责音视频媒体文件。用户需要逐字稿、总结、待办、章节等纪要内容时，请使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)。
+2. `minutes +download` 只负责音视频媒体文件。
 3. 用户只想拿可分享的下载地址时，使用 `--url-only`；用户要落地到本地文件时，直接下载。
 4. 未显式指定路径时，文件默认落到 `./minutes/{minute_token}/<server-filename>`，与 `vc +notes` 的逐字稿共享同一目录便于聚合。
 
@@ -137,20 +107,49 @@ Minutes (妙记) ← minute_token 标识
 > - 用户说"重命名妙记 / 改妙记标题 / 修改妙记名字" → `minutes +update`
 > - 用户说"替换说话人 / 把 A 的发言改成 B / 重新归属发言人" → `minutes +speaker-replace`
 
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli minutes +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut                                           | 说明                                                              |
+| -------------------------------------------------- | --------------------------------------------------------------- |
+| [`+search`](references/lark-minutes-search.md)     | Search minutes by keyword, owners, participants, and time range |
+| [`+download`](references/lark-minutes-download.md) | Download audio/video media file of a minute                     |
+| [`+upload`](references/lark-minutes-upload.md)     | Upload a media file token to generate a minute                  |
+| [`+update`](references/lark-minutes-update.md)     | Update a minute's title                                         |
+| [`+speaker-replace`](references/lark-minutes-speaker-replace.md) | Replace a speaker in a minute's transcript (rebind from one user to another) |
+
+- 使用 `+search` 命令时，必须阅读 [references/lark-minutes-search.md](references/lark-minutes-search.md)，了解搜索参数和返回值结构。
+- 使用 `+download` 命令时，必须阅读 [references/lark-minutes-download.md](references/lark-minutes-download.md)，了解下载参数和返回值结构。
+- 使用 `+upload` 命令时，必须阅读 [references/lark-minutes-upload.md](references/lark-minutes-upload.md)，了解生成参数和返回值结构。
+- 使用 `+update` 命令时，必须阅读 [references/lark-minutes-update.md](references/lark-minutes-update.md)，了解修改参数和返回值结构。
+- 使用 `+speaker-replace` 命令时，必须阅读 [references/lark-minutes-speaker-replace.md](references/lark-minutes-speaker-replace.md)，了解参数和限制（仅支持用户 ID，不支持姓名）。
+
+<!-- AUTO-GENERATED-START — gen-skills.py 管理，勿手动编辑 -->
+
 ## API Resources
 
 ```bash
-lark-cli minutes <resource> <method> [flags]
+lark-cli schema minutes.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli minutes <resource> <method> [flags] # 调用 API
 ```
 
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
 ### minutes
 
 - `get` — 获取妙记信息
 
 > **权限错误**：如果返回 `[2091005] permission deny`，表示用户没有对应妙记文件的阅读权限，需提示用户联系妙记 owner 申请权限。
 
-## 不在本 skill 范围
+## 权限表
 
-- 纪要/逐字稿/总结/待办/章节内容获取 → [lark-vc](../lark-vc/SKILL.md)（`vc +notes --minute-tokens`）
-- 搜索历史会议记录 → [lark-vc](../lark-vc/SKILL.md)
-- 查询未来的会议日程 → [lark-calendar](../lark-calendar/SKILL.md)
+| 方法            | 所需 scope                       |
+| ------------- | ------------------------------ |
+| `+search`     | `minutes:minutes.search:read`  |
+| `minutes.get` | `minutes:minutes:readonly`     |
+| `+download`   | `minutes:minutes.media:export` |
+| `+update`     | `minutes:minutes:update`       |
+| `+speaker-replace` | `minutes:minutes:update` |
+
+<!-- AUTO-GENERATED-END -->

skills/lark-slides/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-slides
 version: 1.0.0
-description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
+description: "飞书幻灯片：创建和编辑幻灯片，接口通过 XML 协议通信。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -25,7 +25,7 @@ metadata:
 | 用户提到模板、主题、版式 | 先检索模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` |
 | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
 **CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
 
@@ -267,14 +267,12 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 | [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
 | [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
 
-没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
-
 ```bash
 lark-cli schema slides.<resource>.<method>   # 调用 API 前必须先查看参数结构
 lark-cli slides <resource> <method> [flags] # 调用 API
 ```
 
-> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+原生 API 高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜字段。
 
 ## 核心规则
 
@@ -287,4 +285,17 @@ lark-cli slides <resource> <method> [flags] # 调用 API
 7. **编辑已有页面优先块级替换**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；只有需要替换整页结构时才用 `slide.delete` + `slide.create`
 8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
 
+## 权限速查
+
+| 方法 | 所需 scope |
+|------|-----------|
+| `slides +create` | `slides:presentation:create`, `slides:presentation:write_only`（含 `@` 占位符时还需 `docs:document.media:upload`） |
+| `slides +media-upload` | `docs:document.media:upload`（wiki URL 解析还需 `wiki:node:read`） |
+| `slides +replace-slide` | `slides:presentation:update`（wiki URL 解析还需 `wiki:node:read`） |
+| `xml_presentations.get` | `slides:presentation:read` |
+| `xml_presentation.slide.create` | `slides:presentation:update` 或 `slides:presentation:write_only` |
+| `xml_presentation.slide.delete` | `slides:presentation:update` 或 `slides:presentation:write_only` |
+| `xml_presentation.slide.get` | `slides:presentation:read` |
+| `xml_presentation.slide.replace` | `slides:presentation:update` |
+
 > **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。

skills/lark-vc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-vc
 version: 1.0.0
-description: "飞书视频会议：搜索历史会议记录、查询会议纪要（总结/待办/章节/逐字稿）、查询参会人快照。当用户查询已结束的会议、获取会议产物（纪要/妙记）、查看参会人时使用；查询未来日程走 lark-calendar。不负责：Agent 真实入会/离会、会中实时事件（走 lark-vc-agent）。"
+description: "飞书视频会议：搜索历史会议、查询会议纪要产物（总结、待办、章节、逐字稿）、查询会议参会人快照。1. 查询已经结束的会议数量或详情时使用本技能（如历史日期｜昨天｜上周｜今天已经开过的会议等场景），查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议。3. 获取或整理会议纪要、逐字稿、录制产物时使用本技能。4. 查询“谁参加过某会议”“参会人列表”等参会人快照信息用 vc meeting get --with-participants（任意时点可查，含已结束会议）。注意：**Agent 真实入会/离会、感知正在进行中会议的实时事件**请使用 lark-vc-agent 技能，本技能不覆盖写操作和会中事件流。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -18,59 +18,15 @@ metadata:
 > 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
 > 4. 了解会议总结、分析和信息提取的标准流程
 
-## 身份
-
-所有 vc 命令默认使用 `--as user`。`+search` 和 `meeting get` 也支持 `--as bot`。
-
-```bash
-# BAD — 查昨天的会议用 calendar，会漏掉即时会议
-lark-cli calendar events search_event --query "站会" --start-time ...
-
-# GOOD — 查已结束的会议用 vc +search
-lark-cli vc +search --query "站会" --start-time ...
-```
-
-## Shortcuts （推荐优先使用）
-
-| Shortcut | 说明 |
-|----------|------|
-| [`+search`](references/lark-vc-search.md) | 搜索历史会议记录（需至少一个筛选条件） |
-| [`+notes`](references/lark-vc-notes.md) | 查询会议纪要和妙记产物（通过 meeting-ids、minute-tokens 或 calendar-event-ids） |
-| [`+recording`](references/lark-vc-recording.md) | 通过 meeting-ids 或 calendar-event-ids 查询 minute_token |
-
-- 使用任何 Shortcut 前，必须先读其对应 reference 文档。
-
-## 意图路由
-
-| 用户意图 | 路由到 |
-|----------|--------|
-| 查"昨天的会议""上周的会""已结束的会议" | 本 skill（`+search`，含即时会议） |
-| 查日历/日程或未来时间的会议 | [lark-calendar](../lark-calendar/SKILL.md) |
-| 查"今天有哪些会议" | `vc +search`（已结束）+ lark-calendar（未开始），合并展示 |
-| Agent 真实入会/离会、会中实时事件 | [lark-vc-agent](../lark-vc-agent/SKILL.md) |
-| 本地音视频文件转纪要/逐字稿 | 先走 [lark-minutes](../lark-minutes/SKILL.md) 上传，再回 `vc +notes --minute-tokens` |
-
 ## 核心概念
 
-- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索。
-- **会议纪要（Note）**：视频会议结束后生成的结构化文档，包含纪要文档（总结+待办）和逐字稿文档。
-- **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，包含总结、待办、章节和文字记录，通过 minute_token 标识。
+- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索（见 `+search`）。
+- **会议纪要（Note）**：视频会议结束后生成的结构化文档，包含纪要文档（包含总结、待办）和逐字稿文档。
+- **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，支持视频/音频的转写，包含总结、待办、章节和文字记录，通过 minute_token 标识。
 - **纪要文档（MainDoc）**：AI 智能纪要的主文档，包含 AI 生成的总结和待办，对应 `note_doc_token`。
 - **用户会议纪要（MeetingNotes）**：用户主动绑定到会议的纪要文档，对应 `meeting_notes`。仅通过 `--calendar-event-ids` 路径返回。
 - **逐字稿（VerbatimDoc）**：会议的逐句文字记录，包含说话人和时间戳。
 
-## 产物选择决策
-
-| 用户意图 | 必须读取的产物 | 禁止 |
-|---------|-------------|------|
-| 提炼/总结/重新总结/整理会议内容/回顾会议 | 逐字稿（`verbatim_doc_token`）或妙记文字记录（Transcript），基于原始对话独立分析 | 禁止直接搬运 AI 纪要（`note_doc_token`）的总结作为最终输出 |
-| 查看待办/章节 | AI 纪要（`note_doc_token`）或妙记产物 — AI 待办更友好（含提出人和负责人），章节按话题划分更结构化 | — |
-| 查看纪要链接/文档地址 | 仅返回文档链接，无需读取内容 | — |
-| 直接看 AI 总结结果 | AI 纪要（`note_doc_token`） | — |
-| 谁说了什么/完整发言记录 | 逐字稿（`verbatim_doc_token`） | — |
-
-> **为什么"提炼/总结"必须从逐字稿出发？** AI 纪要是模型对会议的二次压缩，可能遗漏讨论细节、争论过程和隐含决策。用户要求"提炼"或"重新总结"时，期望的是基于原始对话的独立分析，而非对 AI 产物的重新排版。
-
 ## 核心场景
 
 ### 1. 搜索会议记录
@@ -80,12 +36,23 @@ lark-cli vc +search --query "站会" --start-time ...
 
 ### 2. 整理会议纪要
 
-> 在选择读取哪个产物前，先确认你理解 AI 总结链路 vs 录制链路的区别。如不确定，先读 [`references/vc-domain-boundaries.md`](references/vc-domain-boundaries.md)。
+> ⚠️ 在选择读取哪个产物前，请先确认你理解 AI 总结链路 vs 录制链路的区别。如不确定，先读 [`references/vc-domain-boundaries.md`](references/vc-domain-boundaries.md) 的「两条链路的独立性」章节。
+
+**⚠️ 产物选择决策 — 根据用户意图严格区分：**
+
+| 用户意图 | 必须读取的产物 | 禁止 |
+|---------|-------------|------|
+| **提炼/总结/重新总结/整理会议内容/回顾会议** | 逐字稿（`verbatim_doc_token`）或妙记文字记录（Transcript），基于原始对话独立分析 | 禁止直接搬运 AI 纪要（`note_doc_token`）的总结作为最终输出|
+| **查看待办/章节** | AI 纪要（`note_doc_token`）或妙记产物 — AI 待办更友好（含提出人和负责人），章节按话题划分更结构化 | — |
+| **查看纪要链接/文档地址** | 仅返回文档链接，无需读取内容 | — |
+| **直接看 AI 总结结果** | AI 纪要（`note_doc_token`） | — |
+| **谁说了什么/完整发言记录** | 逐字稿（`verbatim_doc_token`） | — |
+
+> **为什么"提炼/总结"必须从逐字稿出发？** AI 纪要是模型对会议的二次压缩，可能遗漏讨论细节、争论过程和隐含决策。用户要求"提炼"或"重新总结"时，期望的是基于原始对话的独立分析，而非对 AI 产物的重新排版。AI 纪要可作为补充参考，但不能作为唯一信息源。
 
 1. 整理纪要文档时默认给出纪要文档、逐字稿、妙记链接即可，无需读取纪要文档或逐字稿内容。
 2. 用户明确需要获取总结、待办、章节产物时，再读取文档获取具体内容。
 3. 读取智能纪要（`note_doc_token`）内容时，纪要文档的**第一个 `<whiteboard>`** 标签是封面图（AI 生成的总结可视化），应同时下载展示给用户：
-
 ```bash
 # 1. 读取纪要内容
 lark-cli docs +fetch --api-version v2 --doc <note_doc_token> --doc-format markdown
@@ -154,31 +121,70 @@ Meeting (视频会议)
     └── Keywords (推荐关键词)
 ```
 
+> **注意**：`+search` 只能查询已结束的历史会议。查询未来的日程安排请使用 [lark-calendar](../lark-calendar/SKILL.md)。
+>
+> **优先级**：当用户搜索历史会议时，应优先使用 `vc +search` 而非 `calendar events search`。calendar 的搜索面向日程，vc 的搜索面向已结束的会议记录，支持按参会人、组织者、会议室等维度过滤。
+>
+> **路由规则**：如果用户在问“开过的会”“今天开了哪些会”“最近参加过什么会”“已结束的会议”“历史会议记录”，优先使用 `vc +search`。只有在查询未来日程、待开的会、agenda 时才优先使用 [lark-calendar](../lark-calendar/SKILL.md)。
+>
+> **妙记边界**：`+notes` 负责纪要内容、逐字稿和 AI 产物；妙记基础信息请优先看 [`+recording`](references/lark-vc-recording.md) 与 [lark-minutes](../lark-minutes/SKILL.md)。
+>
+> **文件转纪要边界**：如果用户给的是本地音视频文件，并希望得到纪要、逐字稿、总结、待办或章节，入口应先走 [lark-minutes](../lark-minutes/SKILL.md) 的上传流程生成 `minute_url` / `minute_token`，再回到 `vc +notes --minute-tokens` 获取内容产物。
+>
+> **特殊情况**: 当用户查询“今天有哪些会议”时，通过 `vc +search` 查询今天开过的会议记录，同时使用 lark-calendar 技能查询今天还未开始的会议，统一整理后展示给用户。
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+search`](references/lark-vc-search.md) | Search meeting records (requires at least one filter) |
+| [`+notes`](references/lark-vc-notes.md) | Query meeting notes and minutes (via meeting-ids, minute-tokens, or calendar-event-ids) |
+| [`+recording`](references/lark-vc-recording.md) | Query minute_token from meeting-ids or calendar-event-ids |
+
+- 使用 `+search` 命令时，必须阅读 [references/lark-vc-search.md](references/lark-vc-search.md)，了解搜索参数和返回值结构。
+- 使用 `+notes` 命令时，必须阅读 [references/lark-vc-notes.md](references/lark-vc-notes.md)，了解查询参数、产物类型和返回值结构。
+- 使用 `+recording` 命令时，必须阅读 [references/lark-vc-recording.md](references/lark-vc-recording.md)，了解查询参数和返回值结构。
+
+> **Agent 参会相关命令已独立**：`+meeting-join` / `+meeting-leave` / `+meeting-events` 请使用 [`lark-vc-agent`](../lark-vc-agent/SKILL.md) 技能。
+
 ## API Resources
 
 ```bash
-lark-cli vc <resource> <method> [flags]
+lark-cli schema vc.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli vc <resource> <method> [flags] # 调用 API
 ```
 
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
 ### meeting
 
   - `get` — 获取会议详情（主题、时间、参会人、note_id）
 
 ```bash
-# 获取会议基础信息（不含参会人）
+# 获取会议基础信息：不包含参会人列表
 lark-cli vc meeting get --params '{"meeting_id": "<meeting_id>"}'
 
-# 获取会议基础信息（含参会人）
+
+# 获取会议基础信息：包含参会人列表
 lark-cli vc meeting get --params '{"meeting_id": "<meeting_id>", "with_participants": true}'
 ```
 
 ### minutes（跨域，详见 [lark-minutes](../lark-minutes/SKILL.md)）
 
-  - `get` — 获取妙记基础信息（标题、时长、封面）；查询妙记**内容**请用 `+notes --minute-tokens <minute-token>`
+  - `get` — 获取妙记基础信息（标题、时长、封面）；查询纪要**内容**请用 `+notes --minute-tokens <minute-token>`
 
-## 不在本 skill 范围
+## 权限表
 
-- 查询未来的会议日程 → [lark-calendar](../lark-calendar/SKILL.md)
-- Agent 真实入会/离会、会中实时事件 → [lark-vc-agent](../lark-vc-agent/SKILL.md)
-- 本地音视频文件转纪要/逐字稿 → [lark-minutes](../lark-minutes/SKILL.md)（上传后回 `vc +notes`）
-- 妙记搜索/下载/上传/重命名/替换说话人 → [lark-minutes](../lark-minutes/SKILL.md)
+| 方法 | 所需 scope |
+|------|-----------|
+| `+notes --meeting-ids` | `vc:meeting.meetingevent:read`、`vc:note:read`、 `vc:record:readonly` |
+| `+notes --minute-tokens` | `vc:note:read`、`minutes:minutes:readonly`、`minutes:minutes.artifacts:read`、`minutes:minutes.transcript:export` |
+| `+notes --calendar-event-ids` | `calendar:calendar:read`、`calendar:calendar.event:read`、`vc:meeting.meetingevent:read`、`vc:note:read`、 `vc:record:readonly` |
+| `+recording --meeting-ids` | `vc:record:readonly` |
+| `+recording --calendar-event-ids` | `vc:record:readonly`、`calendar:calendar:read`、`calendar:calendar.event:read` |
+| `+search` | `vc:meeting.search:read` |
+| `meeting.get` | `vc:meeting.meetingevent:read` |
+
+> Agent 参会相关 scope（`vc:meeting.bot.join:write` / `vc:meeting.meetingevent:read`）见 [`lark-vc-agent`](../lark-vc-agent/SKILL.md)。

tests/cli_e2e/docs/docs_update_dryrun_test.go

@@ -66,17 +66,6 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 			},
 			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E",
 		},
-		{
-			name: "block_delete batch",
-			args: []string{
-				"docs", "+update",
-				"--doc", "doxcnDryRunE2E",
-				"--command", "block_delete",
-				"--block-id", "blkA,blkB,blkC",
-				"--dry-run",
-			},
-			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E",
-		},
 	}
 
 	for _, tt := range tests {

tests/cli_e2e/event/event_consume_error_test.go

@@ -1,41 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package event
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	"github.com/stretchr/testify/require"
-	"github.com/tidwall/gjson"
-)
-
-// TestEventConsumeUnknownKeyRegression locks the typed error envelope emitted
-// on stderr when `event consume` rejects an unknown EventKey. The lookup fails
-// before any daemon fork or network access, so the test needs no credentials.
-func TestEventConsumeUnknownKeyRegression(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
-	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
-	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args:      []string{"event", "consume", "bogus.key"},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 2)
-
-	errJSON := gjson.Get(result.Stderr, "error")
-	require.True(t, errJSON.Exists(), "stderr missing 'error' JSON envelope\nstderr:\n%s", result.Stderr)
-	require.Equal(t, "validation", errJSON.Get("type").String(), "stderr:\n%s", result.Stderr)
-	require.Equal(t, "invalid_argument", errJSON.Get("subtype").String(), "stderr:\n%s", result.Stderr)
-	require.Contains(t, errJSON.Get("message").String(), "unknown EventKey: bogus.key", "stderr:\n%s", result.Stderr)
-	require.Contains(t, errJSON.Get("hint").String(), "event list", "stderr:\n%s", result.Stderr)
-}

tests/cli_e2e/event/event_subscribe_dryrun_test.go

@@ -1,46 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package event
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	"github.com/stretchr/testify/require"
-	"github.com/tidwall/gjson"
-)
-
-func TestEventSubscribeDryRun(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
-	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
-	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"event", "+subscribe",
-			"--event-types", "im.message.receive_v1,contact.user.created_v3",
-			"--filter", "^im\\.",
-			"--output-dir", "events_out",
-			"--route", "^im\\.message=dir:./messages",
-			"--dry-run",
-		},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-
-	out := result.Stdout
-	require.Equal(t, "event +subscribe", gjson.Get(out, "command").String(), "stdout:\n%s", out)
-	require.Equal(t, "app", gjson.Get(out, "app_id").String(), "stdout:\n%s", out)
-	require.Equal(t, "im.message.receive_v1,contact.user.created_v3", gjson.Get(out, "event_types").String(), "stdout:\n%s", out)
-	require.Equal(t, "^im\\.", gjson.Get(out, "filter").String(), "stdout:\n%s", out)
-	require.Equal(t, "events_out", gjson.Get(out, "output_dir").String(), "stdout:\n%s", out)
-	require.Equal(t, "^im\\.message=dir:./messages", gjson.Get(out, "route").String(), "stdout:\n%s", out)
-}

tests/cli_e2e/event/event_subscribe_error_test.go

@@ -1,47 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package event
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	"github.com/stretchr/testify/require"
-	"github.com/tidwall/gjson"
-)
-
-// TestEventSubscribeInvalidRouteRegression locks the typed error envelope
-// emitted on stderr when +subscribe route parsing rejects user input. Route
-// validation fails before any WebSocket connection is opened, so the test
-// needs no credentials or network.
-func TestEventSubscribeInvalidRouteRegression(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
-	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
-	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"event", "+subscribe",
-			"--force",
-			"--route", "no-equals-sign",
-		},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 2)
-
-	errJSON := gjson.Get(result.Stderr, "error")
-	require.True(t, errJSON.Exists(), "stderr missing 'error' JSON envelope\nstderr:\n%s", result.Stderr)
-	require.Equal(t, "validation", errJSON.Get("type").String(), "stderr:\n%s", result.Stderr)
-	require.Equal(t, "invalid_argument", errJSON.Get("subtype").String(), "stderr:\n%s", result.Stderr)
-	require.Equal(t, "--route", errJSON.Get("param").String(), "stderr:\n%s", result.Stderr)
-	require.Equal(t, `invalid --route "no-equals-sign": expected format regex=dir:./path`,
-		errJSON.Get("message").String(), "stderr:\n%s", result.Stderr)
-}