docs(lark-apps): align db/file skill references with code

- db-execute: document the third failure-hint case (first statement
  failed → 'No statements were applied').
- db-env-create: describe the re-init conflict by behavior instead of
  quoting a server-side literal message.
- file-list: clarify pretty shows 5 columns; uploader/download_url are
  JSON-only (use +file-get for single-file detail).

Change-Id: I69d8473ceaf0a0166ed14fd1b8e00125cf332cba

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

internal/cmdutil/iostreams.go

@@ -18,17 +18,26 @@ type IOStreams struct {
 	Out        io.Writer
 	ErrOut     io.Writer
 	IsTerminal bool
+	// ErrIsTerminal reports whether ErrOut is an interactive terminal. Use it to
+	// gate stderr-only animations (spinners) so pipes / CI / captured stderr stay
+	// clean. Derived from ErrOut's underlying *os.File; non-file writers → false.
+	ErrIsTerminal bool
 }
 
 // NewIOStreams builds an IOStreams from arbitrary readers/writers.
 // IsTerminal is derived from in's underlying *os.File, if any; non-file
 // readers (bytes.Buffer, strings.Reader, …) yield IsTerminal=false.
+// ErrIsTerminal is derived the same way from errOut.
 func NewIOStreams(in io.Reader, out, errOut io.Writer) *IOStreams {
 	isTerminal := false
 	if f, ok := in.(*os.File); ok {
 		isTerminal = term.IsTerminal(int(f.Fd()))
 	}
-	return &IOStreams{In: in, Out: out, ErrOut: errOut, IsTerminal: isTerminal}
+	errIsTerminal := false
+	if f, ok := errOut.(*os.File); ok {
+		errIsTerminal = term.IsTerminal(int(f.Fd()))
+	}
+	return &IOStreams{In: in, Out: out, ErrOut: errOut, IsTerminal: isTerminal, ErrIsTerminal: errIsTerminal}
 }
 
 // SystemIO creates an IOStreams wired to the process's standard file descriptors.
@@ -57,6 +66,7 @@ func normalizeStreams(s *IOStreams) *IOStreams {
 		}
 		if out.ErrOut == nil {
 			out.ErrOut = sys.ErrOut
+			out.ErrIsTerminal = sys.ErrIsTerminal
 		}
 	}
 	return &out

internal/output/spinner.go

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package output
+
+import (
+	"fmt"
+	"io"
+	"sync"
+	"time"
+)
+
+// spinnerFrames are braille spinner glyphs cycled to animate progress.
+var spinnerFrames = []string{"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"}
+
+const (
+	spinnerInterval   = 80 * time.Millisecond
+	spinnerHideCursor = "\x1b[?25l"
+	spinnerShowCursor = "\x1b[?25h"
+	spinnerClearLine  = "\r\x1b[K" // CR + clear-to-end-of-line
+)
+
+// StartSpinner renders a braille spinner with an elapsed-seconds counter to w
+// until the returned stop() is called, e.g.:
+//
+//	⠹ Publishing dev → main... 3s
+//
+// It is meant for slow operations (long polls, first-time provisioning) so the
+// user sees the CLI is alive. Always write to STDERR (w = IO().ErrOut) so the
+// animation never pollutes stdout — the JSON/pretty result stays clean.
+//
+// When enabled is false (stderr is not a TTY: pipes, CI, captured output) it is
+// a no-op returning a no-op stop, so non-interactive runs emit nothing. Gate on
+// the stderr-TTY check (IOStreams.ErrIsTerminal), not the output format: the
+// spinner is stderr-only and self-clears, so it is shown in JSON mode too.
+//
+// stop() clears the spinner line, restores the cursor, and blocks until the
+// render goroutine has finished — so callers can safely write the result to
+// stdout/stderr immediately after. Call stop() BEFORE printing the result, and
+// it is safe to call more than once (e.g. an explicit call plus a defer).
+func StartSpinner(w io.Writer, enabled bool, label string) func() {
+	if !enabled || w == nil {
+		return func() {}
+	}
+
+	done := make(chan struct{})
+	finished := make(chan struct{})
+	start := time.Now()
+
+	go func() {
+		defer close(finished)
+		frame := 0
+		fmt.Fprint(w, spinnerHideCursor)
+		render := func() {
+			elapsed := int(time.Since(start).Seconds())
+			fmt.Fprintf(w, "%s%s %s... %ds", spinnerClearLine, spinnerFrames[frame], label, elapsed)
+			frame = (frame + 1) % len(spinnerFrames)
+		}
+		render()
+		ticker := time.NewTicker(spinnerInterval)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-done:
+				fmt.Fprint(w, spinnerClearLine+spinnerShowCursor)
+				return
+			case <-ticker.C:
+				render()
+			}
+		}
+	}()
+
+	var once sync.Once
+	return func() {
+		once.Do(func() {
+			close(done)
+			<-finished // wait for the line to be cleared before returning
+		})
+	}
+}

internal/output/spinner_test.go

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package output
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+// TestStartSpinner_DisabledIsNoop asserts that a disabled spinner writes nothing and its stop func is idempotent.
+func TestStartSpinner_DisabledIsNoop(t *testing.T) {
+	var buf bytes.Buffer
+	stop := StartSpinner(&buf, false, "working")
+	stop()
+	stop() // idempotent
+	if buf.Len() != 0 {
+		t.Fatalf("disabled spinner wrote %q, want nothing", buf.String())
+	}
+}
+
+// TestStartSpinner_NilWriterIsNoop asserts that a nil writer is a no-op and stopping does not panic.
+func TestStartSpinner_NilWriterIsNoop(t *testing.T) {
+	stop := StartSpinner(nil, true, "working")
+	stop() // must not panic
+}
+
+// TestStartSpinner_EnabledAnimatesAndCleansUp asserts that an enabled spinner renders a frame and label, then clears the line and restores the cursor on stop.
+func TestStartSpinner_EnabledAnimatesAndCleansUp(t *testing.T) {
+	var buf bytes.Buffer
+	stop := StartSpinner(&buf, true, "Publishing")
+	// The goroutine renders the first frame synchronously before selecting on
+	// the stop channel, so even an immediate stop() yields one full cycle.
+	stop()
+	stop() // idempotent, must not panic or double-write after finished
+
+	out := buf.String()
+	if !strings.Contains(out, spinnerHideCursor) {
+		t.Errorf("missing hide-cursor escape:\n%q", out)
+	}
+	if !strings.Contains(out, spinnerFrames[0]) {
+		t.Errorf("missing first spinner frame %q:\n%q", spinnerFrames[0], out)
+	}
+	if !strings.Contains(out, "Publishing...") {
+		t.Errorf("missing label:\n%q", out)
+	}
+	if !strings.Contains(out, spinnerClearLine) {
+		t.Errorf("missing clear-line escape:\n%q", out)
+	}
+	if !strings.HasSuffix(out, spinnerShowCursor) {
+		t.Errorf("must end by restoring the cursor:\n%q", out)
+	}
+}

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -33,6 +33,7 @@ var migratedCommonHelperPaths = []string{
 	"shortcuts/task/",
 	"shortcuts/vc/",
 	"shortcuts/whiteboard/",
+	"shortcuts/wiki/",
 }
 
 const commonImportPath = "github.com/larksuite/cli/shortcuts/common"

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -34,6 +34,7 @@ var migratedEnvelopePaths = []string{
 	"shortcuts/task/",
 	"shortcuts/vc/",
 	"shortcuts/whiteboard/",
+	"shortcuts/wiki/",
 	"shortcuts/im/",
 }
 

lint/errscontract/rules_test.go

@@ -960,6 +960,7 @@ func TestCheckNoLegacyCommonHelperCall_RejectsLegacyHelpersOnMigratedPath(t *tes
 		"shortcuts/slides/slides_create.go",
 		"shortcuts/task/task_update.go",
 		"shortcuts/whiteboard/whiteboard_query.go",
+		"shortcuts/wiki/wiki_node_get.go",
 	}
 	for _, path := range paths {
 		for _, helper := range helpers {
@@ -1076,6 +1077,23 @@ func boom() {
 	}
 }
 
+func TestCheckNoLegacyCommonHelperCall_CoversWikiPathWithAliasAndFunctionValue(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/wiki/wiki_node_get.go", src)
+	if len(v) != 2 {
+		t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on wiki path, got %d: %+v", len(v), v)
+	}
+}
+
 func TestCheckNoLegacyCommonHelperCall_AllowsNonMigratedPath(t *testing.T) {
 	src := `package contact
 

shortcuts/apps/apps_db_audit_list.go

@@ -0,0 +1,300 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsDBAuditList 列出数据表的行级审计事件（INSERT/UPDATE/DELETE 的变更追溯）。
+//
+// GET /apps/{app_id}/db/audit_list（cursor 分页）。--table 可重复传多张表；--since/--until 多格式时间。
+// operator 透传 {id,name}（json 还原对象、pretty 取 name）；before/after 是条件出现的 JSON
+// （INSERT 无 before、DELETE 无 after），json 还原成对象。
+//
+// 多表查询时，CLI 先用 schema（表是否存在）+ status（审计是否开启）在本地过滤，把不存在 /
+// 未开启审计的表剔除后再查 audit_list，被剔除的表及原因放进 skipped（服务端不再返该字段）。
+var AppsDBAuditList = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-audit-list",
+	Description: "List row-change audit events for one or more tables (cursor pagination)",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +db-audit-list --app-id <app_id> --table orders",
+		"Multiple tables: repeat --table; filter time with --since 7d / --until 2026-04-15.",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "table", Type: "string_slice", Desc: "table(s) to list audit events for (repeatable)", Required: true},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
+		{Name: "since", Desc: "filter: event at or after; relative (7d/2h) | date | datetime | ISO 8601 w/ TZ"},
+		{Name: "until", Desc: "filter: event at or before; same formats as --since"},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
+		{Name: "page-token", Desc: "pagination cursor from previous response"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		if len(auditListTables(rctx)) == 0 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--table is required (at least one table)").WithParam("--table")
+		}
+		return normalizeTimeFlags(rctx, "since", "until")
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appAuditListPath(appID)).
+			Desc("List Miaoda app table audit events").
+			Params(buildAuditListParams(rctx, auditListTables(rctx)))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		requested := auditListTables(rctx)
+		env := rctx.Str("env")
+
+		// 多表查询：CLI 侧先用 schema（表是否存在）+ status（审计是否开启）过滤，
+		// 不存在 / 未开启审计的表不进 audit_list 查询，单独在 skipped 里给出原因。
+		// 单表查询直接打 audit_list，由后端就 table-not-found / audit-not-enabled 报错。
+		queryTables := requested
+		var skipped []auditSkippedEntry
+		if len(requested) > 1 {
+			queryTables, skipped, err = filterAuditTables(rctx, appID, env, requested)
+			if err != nil {
+				return withAppsHint(err, dbChangelogHint)
+			}
+			// 所有请求表都被过滤掉 → 无可查询表，直接返回空 + skipped 提示，不调 audit_list。
+			if len(queryTables) == 0 {
+				out := map[string]interface{}{"items": []auditLogItem{}, "has_more": false, "skipped": skipped}
+				rctx.OutFormat(out, nil, func(w io.Writer) {
+					io.WriteString(w, "No audit events found.\n")
+					writeAuditSkipped(w, skipped, len(requested))
+				})
+				return nil
+			}
+		}
+
+		data, err := rctx.CallAPITyped("GET", appAuditListPath(appID), buildAuditListParams(rctx, queryTables), nil)
+		if err != nil {
+			return withAppsHint(err, dbChangelogHint)
+		}
+		items := projectAuditLogItems(data["items"])
+		data["items"] = items
+		// 服务端不再返 skipped；改由 CLI 算出的 skipped 写回输出。
+		if len(skipped) > 0 {
+			data["skipped"] = skipped
+		} else {
+			delete(data, "skipped")
+		}
+		multi := len(requested) > 1
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			renderAuditListPretty(w, items, skipped, len(requested), multi)
+		})
+		return nil
+	},
+}
+
+// auditSkippedEntry 是被 CLI 预过滤掉的表及原因（替代已删除的服务端 skipped 字段）。
+type auditSkippedEntry struct {
+	Table  string `json:"table"`
+	Reason string `json:"reason"`
+}
+
+// filterAuditTables 用 schema（存在性）+ status（审计开关）把请求表分成「可查询」与「跳过」两组。
+func filterAuditTables(rctx *common.RuntimeContext, appID, env string, requested []string) ([]string, []auditSkippedEntry, error) {
+	existing, err := fetchExistingTables(rctx, appID, env)
+	if err != nil {
+		return nil, nil, err
+	}
+	enabled, err := fetchAuditEnabledTables(rctx, appID, env)
+	if err != nil {
+		return nil, nil, err
+	}
+	valid := make([]string, 0, len(requested))
+	var skipped []auditSkippedEntry
+	for _, t := range requested {
+		switch {
+		case !existing[t]:
+			skipped = append(skipped, auditSkippedEntry{Table: t, Reason: "table not found"})
+		case !enabled[t]:
+			skipped = append(skipped, auditSkippedEntry{Table: t, Reason: "audit not enabled"})
+		default:
+			valid = append(valid, t)
+		}
+	}
+	return valid, skipped, nil
+}
+
+// fetchExistingTables 翻页拉全量表清单，返回存在表名集合（schema 命令同源接口）。
+func fetchExistingTables(rctx *common.RuntimeContext, appID, env string) (map[string]bool, error) {
+	existing := map[string]bool{}
+	token := ""
+	for {
+		params := map[string]interface{}{"env": env, "page_size": 100}
+		if token != "" {
+			params["page_token"] = token
+		}
+		data, err := rctx.CallAPITyped("GET", appTablesPath(appID), params, nil)
+		if err != nil {
+			return nil, err
+		}
+		for _, it := range asMapSlice(data["items"]) {
+			if name := common.GetString(it, "name"); name != "" {
+				existing[name] = true
+			}
+		}
+		token = common.GetString(data, "page_token")
+		if data["has_more"] != true || token == "" {
+			break
+		}
+	}
+	return existing, nil
+}
+
+// fetchAuditEnabledTables 拉审计状态，返回当前已开启审计的表名集合（status 命令同源接口）。
+func fetchAuditEnabledTables(rctx *common.RuntimeContext, appID, env string) (map[string]bool, error) {
+	data, err := rctx.CallAPITyped("GET", appAuditStatusPath(appID), map[string]interface{}{"env": env}, nil)
+	if err != nil {
+		return nil, err
+	}
+	enabled := map[string]bool{}
+	for _, it := range asMapSlice(data["items"]) {
+		if it["enabled"] == true {
+			if name := common.GetString(it, "table"); name != "" {
+				enabled[name] = true
+			}
+		}
+	}
+	return enabled, nil
+}
+
+// asMapSlice 把 interface{}（[]interface{}）里的每个 map 元素取出，非 map 丢弃。
+func asMapSlice(raw interface{}) []map[string]interface{} {
+	arr, _ := raw.([]interface{})
+	out := make([]map[string]interface{}, 0, len(arr))
+	for _, it := range arr {
+		if m, ok := it.(map[string]interface{}); ok {
+			out = append(out, m)
+		}
+	}
+	return out
+}
+
+// auditListTables 取 --table 切片，trim 去空。
+func auditListTables(rctx *common.RuntimeContext) []string {
+	out := make([]string, 0)
+	for _, t := range rctx.StrSlice("table") {
+		if v := strings.TrimSpace(t); v != "" {
+			out = append(out, v)
+		}
+	}
+	return out
+}
+
+// buildAuditListParams 组装 audit_list 查询参数：env / tables(逗号拼接) / page_size 及可选 since/until/page_token。
+func buildAuditListParams(rctx *common.RuntimeContext, tables []string) map[string]interface{} {
+	params := map[string]interface{}{
+		"env":       rctx.Str("env"),
+		"tables":    strings.Join(tables, ","),
+		"page_size": rctx.Int("page-size"),
+	}
+	addStr := func(flag, key string) {
+		if v := strings.TrimSpace(rctx.Str(flag)); v != "" {
+			params[key] = v
+		}
+	}
+	addStr("since", "since")
+	addStr("until", "until")
+	addStr("page-token", "page_token")
+	return params
+}
+
+type auditLogItem struct {
+	EventID     string       `json:"event_id"`
+	EventTime   string       `json:"event_time"`
+	TargetTable string       `json:"target_table"`
+	Type        string       `json:"type"`
+	Operator    *operatorRef `json:"operator,omitempty"`
+	Summary     string       `json:"summary"`
+	Before      interface{}  `json:"before,omitempty"`
+	After       interface{}  `json:"after,omitempty"`
+}
+
+// projectAuditLogItems 把服务端原始审计事件投影为白名单 auditLogItem（operator 解析、before/after 还原成对象）。
+func projectAuditLogItems(raw interface{}) []auditLogItem {
+	arr, _ := raw.([]interface{})
+	out := make([]auditLogItem, 0, len(arr))
+	for _, it := range arr {
+		m, ok := it.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		row := auditLogItem{
+			EventID:     common.GetString(m, "event_id"),
+			EventTime:   common.GetString(m, "event_time"),
+			TargetTable: common.GetString(m, "target_table"),
+			Type:        common.GetString(m, "type"),
+			Operator:    parseOperator(common.GetString(m, "operator")),
+			Summary:     common.GetString(m, "summary"),
+		}
+		// before/after 条件出现：INSERT 无 before、DELETE 无 after。JSON 字符串 → 还原对象。
+		if b := common.GetString(m, "before"); b != "" {
+			row.Before = safeParseJSON(b)
+		}
+		if a := common.GetString(m, "after"); a != "" {
+			row.After = safeParseJSON(a)
+		}
+		out = append(out, row)
+	}
+	return out
+}
+
+// renderAuditListPretty 单表 5 列 / 多表 6 列（首列 target_table）；末尾列出 skipped 表。
+func renderAuditListPretty(w io.Writer, items []auditLogItem, skipped []auditSkippedEntry, totalRequested int, multi bool) {
+	if len(items) == 0 {
+		io.WriteString(w, "No audit events found.\n")
+		writeAuditSkipped(w, skipped, totalRequested)
+		return
+	}
+	var headers []string
+	if multi {
+		headers = []string{"target_table", "event_time", "type", "event_id", "operator", "summary"}
+	} else {
+		headers = []string{"event_time", "type", "event_id", "operator", "summary"}
+	}
+	rows := make([][]string, 0, len(items))
+	for _, it := range items {
+		cells := []string{dashIfEmpty(it.EventTime), it.Type, it.EventID, operatorName(it.Operator), dashIfEmpty(it.Summary)}
+		if multi {
+			cells = append([]string{dashIfEmpty(it.TargetTable)}, cells...)
+		}
+		rows = append(rows, cells)
+	}
+	renderAlignedTable(w, headers, rows)
+	writeAuditSkipped(w, skipped, totalRequested)
+}
+
+// writeAuditSkipped 打 "— Skipped N of M tables: orders (audit not enabled), foo (table not found)"。
+func writeAuditSkipped(w io.Writer, skipped []auditSkippedEntry, totalRequested int) {
+	if len(skipped) == 0 {
+		return
+	}
+	parts := make([]string, 0, len(skipped))
+	for _, s := range skipped {
+		parts = append(parts, fmt.Sprintf("%s (%s)", s.Table, s.Reason))
+	}
+	fmt.Fprintf(w, "— Skipped %d of %d tables: %s\n", len(skipped), totalRequested, strings.Join(parts, ", "))
+}

shortcuts/apps/apps_db_audit_set.go

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// 审计保留期合法取值。
+var auditRetentions = []string{"7d", "30d", "180d", "360d", "forever"}
+
+const dbAuditSetHint = "verify --app-id and --table; check current config with `lark-cli apps +db-audit-status --app-id <app_id>`"
+
+// AppsDBAuditEnable 为某张表开启行级审计（变更追溯）。
+//
+// POST /apps/{app_id}/db/audit_set，body {table, enabled:true, retention}。--retention 默认 7d。
+var AppsDBAuditEnable = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-audit-enable",
+	Description: "Enable row-change audit logging for a table",
+	Risk:        "write",
+	Tips: []string{
+		"Example: lark-cli apps +db-audit-enable --app-id <app_id> --table orders --retention 30d",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "table", Desc: "table to enable audit for", Required: true},
+		{Name: "retention", Default: "7d", Enum: auditRetentions, Desc: "how long to keep audit logs"},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(appAuditSetPath(appID)).
+			Desc("Enable table audit").
+			Params(map[string]interface{}{"env": rctx.Str("env")}).
+			Body(map[string]interface{}{"table": strings.TrimSpace(rctx.Str("table")), "enabled": true, "retention": rctx.Str("retention")})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		table := strings.TrimSpace(rctx.Str("table"))
+		retention := rctx.Str("retention")
+		stop := rctx.StartSpinner("Enabling audit logging for " + table)
+		defer stop()
+		data, err := rctx.CallAPITyped("POST", appAuditSetPath(appID),
+			map[string]interface{}{"env": rctx.Str("env")},
+			map[string]interface{}{"table": table, "enabled": true, "retention": retention})
+		stop()
+		if err != nil {
+			return withAppsHint(err, dbAuditSetHint)
+		}
+		st := auditSetStatus(data, table)
+		ret := common.GetString(st, "retention")
+		if ret == "" {
+			ret = retention
+		}
+		out := map[string]interface{}{"table": common.GetString(st, "table"), "enabled": true, "retention": ret}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "✓ Audit enabled for table '%s' (retention: %s)\n", common.GetString(out, "table"), ret)
+		})
+		return nil
+	},
+}
+
+// AppsDBAuditDisable 关闭某张表的行级审计。
+//
+// POST /apps/{app_id}/db/audit_set，body {table, enabled:false}。
+var AppsDBAuditDisable = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-audit-disable",
+	Description: "Disable row-change audit logging for a table",
+	Risk:        "write",
+	Tips: []string{
+		"Example: lark-cli apps +db-audit-disable --app-id <app_id> --table orders",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "table", Desc: "table to disable audit for", Required: true},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(appAuditSetPath(appID)).
+			Desc("Disable table audit").
+			Params(map[string]interface{}{"env": rctx.Str("env")}).
+			Body(map[string]interface{}{"table": strings.TrimSpace(rctx.Str("table")), "enabled": false})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		table := strings.TrimSpace(rctx.Str("table"))
+		data, err := rctx.CallAPITyped("POST", appAuditSetPath(appID),
+			map[string]interface{}{"env": rctx.Str("env")},
+			map[string]interface{}{"table": table, "enabled": false})
+		if err != nil {
+			return withAppsHint(err, dbAuditSetHint)
+		}
+		st := auditSetStatus(data, table)
+		out := map[string]interface{}{"table": common.GetString(st, "table"), "enabled": false}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "✓ Audit disabled for table '%s'\n", common.GetString(out, "table"))
+		})
+		return nil
+	},
+}
+
+// auditSetStatus 取响应里的 status 对象（缺失时用入参 table 兜底）。
+func auditSetStatus(data map[string]interface{}, table string) map[string]interface{} {
+	if st, ok := data["status"].(map[string]interface{}); ok {
+		if common.GetString(st, "table") == "" {
+			st["table"] = table
+		}
+		return st
+	}
+	return map[string]interface{}{"table": table}
+}

shortcuts/apps/apps_db_audit_status.go

@@ -0,0 +1,139 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsDBAuditStatus 查看数据表的审计开关状态（哪些表开了行级审计、保留期）。
+//
+// GET /apps/{app_id}/db/audit_status。--table 指定单表（无记录时占位 enabled=false）；
+// 不指定返回所有已配置表。json 单表返对象、多表返数组；pretty 单表 key/value、多表表格。
+var AppsDBAuditStatus = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-audit-status",
+	Description: "Show table audit (row-change tracking) status",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +db-audit-status --app-id <app_id>",
+		"Check one table: --table orders",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
+		{Name: "table", Desc: "show status for a single table (default: all configured tables)"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appAuditStatusPath(appID)).
+			Desc("Get table audit status").
+			Params(buildAuditStatusParams(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("GET", appAuditStatusPath(appID), buildAuditStatusParams(rctx), nil)
+		if err != nil {
+			return withAppsHint(err, dbChangelogHint)
+		}
+		table := strings.TrimSpace(rctx.Str("table"))
+		items := projectAuditStatusItems(data["items"])
+		// 单表查询但后端无记录 → 占位 enabled=false（与 miaoda 一致）。
+		if table != "" && len(items) == 0 {
+			items = []map[string]interface{}{{"table": table, "enabled": false}}
+		}
+		// json：单表返对象、多表返数组。
+		var out interface{}
+		if table != "" && len(items) == 1 {
+			out = items[0]
+		} else {
+			out = map[string]interface{}{"items": items}
+		}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderAuditStatusPretty(w, items, table)
+		})
+		return nil
+	},
+}
+
+// buildAuditStatusParams 组装 audit_status 查询参数：env 及可选 table（单表查询）。
+func buildAuditStatusParams(rctx *common.RuntimeContext) map[string]interface{} {
+	params := map[string]interface{}{"env": rctx.Str("env")}
+	if t := strings.TrimSpace(rctx.Str("table")); t != "" {
+		params["table"] = t
+	}
+	return params
+}
+
+// projectAuditStatusItems 透出 {table, enabled, enabled_at?, retention?}。
+func projectAuditStatusItems(raw interface{}) []map[string]interface{} {
+	arr, _ := raw.([]interface{})
+	out := make([]map[string]interface{}, 0, len(arr))
+	for _, it := range arr {
+		m, ok := it.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		row := map[string]interface{}{
+			"table":   common.GetString(m, "table"),
+			"enabled": m["enabled"] == true,
+		}
+		if v := common.GetString(m, "enabled_at"); v != "" {
+			row["enabled_at"] = v
+		}
+		if v := common.GetString(m, "retention"); v != "" {
+			row["retention"] = v
+		}
+		out = append(out, row)
+	}
+	return out
+}
+
+// renderAuditStatusPretty 单表渲染 key/value、多表渲染对齐表格（table/enabled/enabled_at/retention）。
+func renderAuditStatusPretty(w io.Writer, items []map[string]interface{}, table string) {
+	if len(items) == 0 {
+		io.WriteString(w, "No audit configuration found.\n")
+		return
+	}
+	yesNo := func(m map[string]interface{}) string {
+		if m["enabled"] == true {
+			return "yes"
+		}
+		return "no"
+	}
+	get := func(m map[string]interface{}, k string) string { return dashIfEmpty(common.GetString(m, k)) }
+	// 单表 → key/value
+	if table != "" && len(items) == 1 {
+		it := items[0]
+		renderKeyValuePairs(w, [][2]string{
+			{"table", common.GetString(it, "table")},
+			{"enabled", yesNo(it)},
+			{"enabled_at", get(it, "enabled_at")},
+			{"retention", get(it, "retention")},
+		})
+		return
+	}
+	// 多表 → 表格
+	headers := []string{"table", "enabled", "enabled_at", "retention"}
+	rows := make([][]string, 0, len(items))
+	for _, it := range items {
+		rows = append(rows, []string{common.GetString(it, "table"), yesNo(it), get(it, "enabled_at"), get(it, "retention")})
+	}
+	renderAlignedTable(w, headers, rows)
+}

shortcuts/apps/apps_db_audit_test.go

@@ -0,0 +1,316 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const (
+	dbAuditStatusURL = "/open-apis/spark/v1/apps/app_x/db/audit_status"
+	dbAuditSetURL    = "/open-apis/spark/v1/apps/app_x/db/audit_set"
+	dbAuditListURL   = "/open-apis/spark/v1/apps/app_x/db/audit_list"
+	dbTablesListURL  = "/open-apis/spark/v1/apps/app_x/tables"
+)
+
+// ── audit-status ──
+
+// TestAppsDBAuditStatus_SingleTableObjectWithPlaceholder 验证单表查询无记录时返回 enabled:false 的占位对象（非数组）。
+func TestAppsDBAuditStatus_SingleTableObjectWithPlaceholder(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbAuditStatusURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"items": []interface{}{}}},
+	})
+	if err := runAppsShortcut(t, AppsDBAuditStatus,
+		[]string{"+db-audit-status", "--app-id", "app_x", "--table", "orders", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	// 单表无记录 → 占位对象 enabled:false（不是数组）。
+	var env struct {
+		Data struct {
+			Table   string `json:"table"`
+			Enabled bool   `json:"enabled"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
+		t.Fatalf("decode: %v\n%s", err, stdout.String())
+	}
+	if env.Data.Table != "orders" || env.Data.Enabled {
+		t.Fatalf("expected placeholder {orders,false}, got %+v", env.Data)
+	}
+}
+
+// TestAppsDBAuditStatus_MultiTablePrettyTable 验证多表 pretty 输出含 enabled/yes/no 列与 retention 值。
+func TestAppsDBAuditStatus_MultiTablePrettyTable(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbAuditStatusURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"items": []interface{}{
+			map[string]interface{}{"table": "orders", "enabled": true, "enabled_at": "2026-04-15T10:30:00Z", "retention": "30d"},
+			map[string]interface{}{"table": "users", "enabled": false},
+		}}},
+	})
+	if err := runAppsShortcut(t, AppsDBAuditStatus,
+		[]string{"+db-audit-status", "--app-id", "app_x", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "enabled") || !strings.Contains(got, "yes") || !strings.Contains(got, "no") || !strings.Contains(got, "30d") {
+		t.Fatalf("pretty table malformed:\n%s", got)
+	}
+}
+
+// ── audit-enable / disable ──
+
+// TestAppsDBAuditEnable_RequiresTableAndValidRetention 验证缺 --table 报必填错、非法 --retention 报 ValidationError。
+func TestAppsDBAuditEnable_RequiresTableAndValidRetention(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	// 缺 --table → cobra required, exit 1
+	if err := runAppsShortcut(t, AppsDBAuditEnable,
+		[]string{"+db-audit-enable", "--app-id", "app_x", "--as", "user"}, factory, stdout); err == nil {
+		t.Fatalf("expected required --table error")
+	}
+	// 非法 retention → enum 校验 (validation)
+	factory2, stdout2, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBAuditEnable,
+		[]string{"+db-audit-enable", "--app-id", "app_x", "--table", "orders", "--retention", "99d", "--as", "user"}, factory2, stdout2)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--retention" {
+		t.Fatalf("Param = %q, want --retention", ve.Param)
+	}
+}
+
+// TestAppsDBAuditEnable_DryRunAndSuccess 验证 dry-run 发出 enabled:true+retention 的 POST，成功时打印 pretty 确认行。
+func TestAppsDBAuditEnable_DryRunAndSuccess(t *testing.T) {
+	// dry-run body {table, enabled:true, retention}
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBAuditEnable,
+		[]string{"+db-audit-enable", "--app-id", "app_x", "--table", "orders", "--retention", "30d", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	a := env.API[0]
+	if a.Method != "POST" || a.URL != dbAuditSetURL || a.Body["enabled"] != true || a.Body["retention"] != "30d" || a.Body["table"] != "orders" {
+		t.Fatalf("dry-run = %s %s body=%v", a.Method, a.URL, a.Body)
+	}
+
+	// success
+	factory2, stdout2, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbAuditSetURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"status": map[string]interface{}{"table": "orders", "enabled": true, "retention": "30d"}}},
+	})
+	if err := runAppsShortcut(t, AppsDBAuditEnable,
+		[]string{"+db-audit-enable", "--app-id", "app_x", "--table", "orders", "--retention", "30d", "--format", "pretty", "--as", "user"}, factory2, stdout2); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout2.String(), "✓ Audit enabled for table 'orders' (retention: 30d)") {
+		t.Fatalf("pretty: %s", stdout2.String())
+	}
+}
+
+// TestAppsDBAuditDisable_DryRunAndSuccess 验证 dry-run 发出 enabled:false 的 POST，成功时打印 pretty 确认行。
+func TestAppsDBAuditDisable_DryRunAndSuccess(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBAuditDisable,
+		[]string{"+db-audit-disable", "--app-id", "app_x", "--table", "orders", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Body map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	if env.API[0].Body["enabled"] != false || env.API[0].Body["table"] != "orders" {
+		t.Fatalf("dry-run body=%v (want enabled:false)", env.API[0].Body)
+	}
+
+	factory2, stdout2, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbAuditSetURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"status": map[string]interface{}{"table": "orders", "enabled": false}}},
+	})
+	if err := runAppsShortcut(t, AppsDBAuditDisable,
+		[]string{"+db-audit-disable", "--app-id", "app_x", "--table", "orders", "--format", "pretty", "--as", "user"}, factory2, stdout2); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout2.String(), "✓ Audit disabled for table 'orders'") {
+		t.Fatalf("pretty: %s", stdout2.String())
+	}
+}
+
+// ── audit-list ──
+
+// TestAppsDBAuditList_RequiresTable 验证缺 --table 时报必填错误。
+func TestAppsDBAuditList_RequiresTable(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBAuditList,
+		[]string{"+db-audit-list", "--app-id", "app_x", "--as", "user"}, factory, stdout); err == nil {
+		t.Fatalf("expected required --table error")
+	}
+}
+
+// TestAppsDBAuditList_DryRunJoinsTables 验证 dry-run 将多个 --table 合并为 tables=orders,users 且归一化 since。
+func TestAppsDBAuditList_DryRunJoinsTables(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBAuditList,
+		[]string{"+db-audit-list", "--app-id", "app_x", "--table", "orders", "--table", "users", "--since", "7d", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	a := env.API[0]
+	if a.Method != "GET" || a.URL != dbAuditListURL || a.Params["tables"] != "orders,users" {
+		t.Fatalf("dry-run = %s %s tables=%v", a.Method, a.URL, a.Params["tables"])
+	}
+	if s, _ := a.Params["since"].(string); !strings.HasSuffix(s, "Z") {
+		t.Fatalf("since not normalized: %v", a.Params["since"])
+	}
+}
+
+// 单表查询：不预过滤、直接打 audit_list（后端就 not-found/not-enabled 报错），无 skipped。
+// TestAppsDBAuditList_SingleTableNoPreflight 验证单表查询不预过滤、operator/before/after 还原为对象、无 skipped。
+func TestAppsDBAuditList_SingleTableNoPreflight(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbAuditListURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"has_more": false, "page_token": "",
+			"items": []interface{}{map[string]interface{}{
+				"event_id": "01525", "event_time": "2026-04-16T10:30:00Z", "target_table": "users",
+				"type": "UPDATE", "operator": `{"id":"7311","name":"alice"}`, "summary": "UPDATE 1 field",
+				"before": `{"amount":100}`, "after": `{"amount":999}`,
+			}},
+		}},
+	})
+	if err := runAppsShortcut(t, AppsDBAuditList,
+		[]string{"+db-audit-list", "--app-id", "app_x", "--table", "users", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	// operator → 对象；before/after → 还原成对象（非字符串）。
+	for _, want := range []string{`"name": "alice"`, `"before"`, `"amount": 100`, `"after"`, `"amount": 999`} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing %q:\n%s", want, got)
+		}
+	}
+	if strings.Contains(got, `"skipped"`) {
+		t.Errorf("single-table query must not emit skipped:\n%s", got)
+	}
+	if strings.Contains(got, `"before": "{`) {
+		t.Errorf("before should be an object, not a JSON string:\n%s", got)
+	}
+}
+
+// TestAppsDBAuditList_SingleTableEmptyPretty 验证单表无事件时不报错、pretty 打印 "No audit events found." 且无 Skipped。
+func TestAppsDBAuditList_SingleTableEmptyPretty(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbAuditListURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"items": []interface{}{}}},
+	})
+	if err := runAppsShortcut(t, AppsDBAuditList,
+		[]string{"+db-audit-list", "--app-id", "app_x", "--table", "orders", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("empty audit list should NOT error (ok read), got %v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "No audit events found.") || strings.Contains(got, "Skipped") {
+		t.Fatalf("expected empty, no skipped for single table:\n%s", got)
+	}
+}
+
+// 多表查询：CLI 用 schema（存在性）+ status（审计开关）预过滤，只把有效表传给 audit_list，
+// 不存在 / 未开启审计的表进 skipped。
+// TestAppsDBAuditList_MultiTablePreflightFilters 验证多表查询用 schema+status 预过滤，仅传有效表，不存在/未开审计的表进 skipped。
+func TestAppsDBAuditList_MultiTablePreflightFilters(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	// schema：orders/users/carts 存在，ghost 不存在。
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbTablesListURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"has_more": false, "items": []interface{}{
+			map[string]interface{}{"name": "orders"}, map[string]interface{}{"name": "users"}, map[string]interface{}{"name": "carts"},
+		}}},
+	})
+	// status：orders/users 开启审计，carts 未开启。
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbAuditStatusURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"items": []interface{}{
+			map[string]interface{}{"table": "orders", "enabled": true}, map[string]interface{}{"table": "users", "enabled": true},
+			map[string]interface{}{"table": "carts", "enabled": false},
+		}}},
+	})
+	// audit_list 只应被传入有效表 orders,users。
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbAuditListURL,
+		OnMatch: func(req *http.Request) {
+			if got := req.URL.Query().Get("tables"); got != "orders,users" {
+				t.Errorf("audit_list tables = %q, want orders,users (filtered)", got)
+			}
+		},
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"has_more": false, "items": []interface{}{
+			map[string]interface{}{"event_id": "e1", "event_time": "2026-04-16T10:30:00Z", "target_table": "orders", "type": "INSERT", "summary": "INSERT"},
+		}}},
+	})
+	if err := runAppsShortcut(t, AppsDBAuditList,
+		[]string{"+db-audit-list", "--app-id", "app_x", "--table", "orders", "--table", "users", "--table", "carts", "--table", "ghost", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	// skipped：carts(audit not enabled) + ghost(table not found)，结构化 {table,reason}。
+	for _, want := range []string{`"skipped"`, `"table": "carts"`, `"reason": "audit not enabled"`, `"table": "ghost"`, `"reason": "table not found"`} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing %q:\n%s", want, got)
+		}
+	}
+}
+
+// 多表查询且全部被过滤掉 → 不调 audit_list，直接空 + skipped 提示。
+// TestAppsDBAuditList_MultiTableAllFilteredSkipsQuery 验证多表全部被过滤时跳过 audit_list 调用，直接输出空结果加 Skipped 提示。
+func TestAppsDBAuditList_MultiTableAllFilteredSkipsQuery(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbTablesListURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"has_more": false, "items": []interface{}{
+			map[string]interface{}{"name": "orders"},
+		}}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbAuditStatusURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"items": []interface{}{}}},
+	})
+	// 不注册 audit_list：若被调用会命中未注册请求而报错。
+	if err := runAppsShortcut(t, AppsDBAuditList,
+		[]string{"+db-audit-list", "--app-id", "app_x", "--table", "ghost1", "--table", "ghost2", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("all-filtered should still succeed (empty), got %v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "No audit events found.") || !strings.Contains(got, "Skipped 2 of 2 tables") {
+		t.Fatalf("expected empty + 'Skipped 2 of 2 tables':\n%s", got)
+	}
+}

shortcuts/apps/apps_db_changelog_list.go

@@ -0,0 +1,150 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const dbChangelogHint = "verify --app-id is correct; if targeting --env dev, create it first with `lark-cli apps +db-env-create --app-id <app_id> --env dev`"
+
+// AppsDBChangelogList 列出应用数据库的 DDL 变更记录（建表/改表/索引等结构变更追溯）。
+//
+// GET /apps/{app_id}/db/changelog_list（cursor 分页）。过滤：--table、--since/--until（多格式时间）。
+// --change-id 精确查单条（命中返单条、否则空）。operator 后端以 JSON 字符串透传 {id,name}，
+// json 还原成对象、pretty 只展示 name。
+var AppsDBChangelogList = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-changelog-list",
+	Description: "List a Miaoda app database's DDL change history (cursor pagination)",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +db-changelog-list --app-id <app_id>",
+		"Pin a single change with --change-id; filter time with --since 7d / --until 2026-04-15.",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
+		{Name: "table", Desc: "filter by target table"},
+		{Name: "change-id", Desc: "look up a single change by id (returns that one record only)"},
+		{Name: "since", Desc: "filter: changed at or after; relative (7d/2h) | date | datetime | ISO 8601 w/ TZ"},
+		{Name: "until", Desc: "filter: changed at or before; same formats as --since"},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
+		{Name: "page-token", Desc: "pagination cursor from previous response"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		return normalizeTimeFlags(rctx, "since", "until")
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appChangelogListPath(appID)).
+			Desc("List Miaoda app DDL changelog").
+			Params(buildChangelogParams(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("GET", appChangelogListPath(appID), buildChangelogParams(rctx), nil)
+		if err != nil {
+			return withAppsHint(err, dbChangelogHint)
+		}
+		items := projectChangelogItems(data["items"])
+		data["items"] = items
+		changeID := strings.TrimSpace(rctx.Str("change-id"))
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			renderChangelogPretty(w, items, changeID)
+		})
+		return nil
+	},
+}
+
+// buildChangelogParams 组装 changelog_list 查询参数：env / page_size 及可选 table/change_id/since/until/page_token。
+func buildChangelogParams(rctx *common.RuntimeContext) map[string]interface{} {
+	params := map[string]interface{}{
+		"env":       rctx.Str("env"),
+		"page_size": rctx.Int("page-size"),
+	}
+	addStr := func(flag, key string) {
+		if v := strings.TrimSpace(rctx.Str(flag)); v != "" {
+			params[key] = v
+		}
+	}
+	addStr("table", "table")
+	addStr("change-id", "change_id")
+	addStr("since", "since")
+	addStr("until", "until")
+	addStr("page-token", "page_token")
+	return params
+}
+
+type changelogItem struct {
+	ChangeID    string       `json:"change_id"`
+	ChangedAt   string       `json:"changed_at"`
+	Operator    *operatorRef `json:"operator,omitempty"`
+	TargetTable string       `json:"target_table"`
+	ChangeType  string       `json:"change_type"`
+	Summary     string       `json:"summary"`
+	Statement   string       `json:"statement,omitempty"`
+}
+
+// projectChangelogItems 把服务端原始 DDL 变更记录投影为白名单 changelogItem（operator 解析成对象）。
+func projectChangelogItems(raw interface{}) []changelogItem {
+	arr, _ := raw.([]interface{})
+	out := make([]changelogItem, 0, len(arr))
+	for _, it := range arr {
+		m, ok := it.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		out = append(out, changelogItem{
+			ChangeID:    common.GetString(m, "change_id"),
+			ChangedAt:   common.GetString(m, "changed_at"),
+			Operator:    parseOperator(common.GetString(m, "operator")),
+			TargetTable: common.GetString(m, "target_table"),
+			ChangeType:  common.GetString(m, "change_type"),
+			Summary:     common.GetString(m, "summary"),
+			Statement:   common.GetString(m, "statement"),
+		})
+	}
+	return out
+}
+
+// renderChangelogPretty 6 列：change_id / changed_at / operator(name) / target_table / change_type / summary。
+func renderChangelogPretty(w io.Writer, items []changelogItem, changeID string) {
+	if len(items) == 0 {
+		if changeID != "" {
+			fmt.Fprintf(w, "No DDL change with id=%s found.\n", changeID)
+		} else {
+			io.WriteString(w, "No DDL changes found.\n")
+		}
+		return
+	}
+	headers := []string{"change_id", "changed_at", "operator", "target_table", "change_type", "summary"}
+	rows := make([][]string, 0, len(items))
+	for _, it := range items {
+		rows = append(rows, []string{
+			it.ChangeID,
+			dashIfEmpty(it.ChangedAt),
+			operatorName(it.Operator),
+			dashIfEmpty(it.TargetTable),
+			it.ChangeType,
+			dashIfEmpty(it.Summary),
+		})
+	}
+	renderAlignedTable(w, headers, rows)
+}

shortcuts/apps/apps_db_changelog_list_test.go

@@ -0,0 +1,143 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const dbChangelogURL = "/open-apis/spark/v1/apps/app_x/db/changelog_list"
+
+// TestAppsDBChangelogList_RequiresAppID 验证空白 --app-id 报 --app-id 的 ValidationError。
+func TestAppsDBChangelogList_RequiresAppID(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBChangelogList,
+		[]string{"+db-changelog-list", "--app-id", "  ", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--app-id" {
+		t.Fatalf("Param = %q, want --app-id", ve.Param)
+	}
+}
+
+// TestAppsDBChangelogList_DryRunFiltersAndTimeNormalize 验证 dry-run 透传 env/table/change_id 过滤参数并将 since 归一化为 RFC3339 UTC。
+func TestAppsDBChangelogList_DryRunFiltersAndTimeNormalize(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBChangelogList,
+		[]string{"+db-changelog-list", "--app-id", "app_x", "--env", "dev", "--table", "orders",
+			"--change-id", "01J", "--since", "2026-01-01", "--page-size", "5", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	a := env.API[0]
+	if a.Method != "GET" || a.URL != dbChangelogURL {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	if a.Params["env"] != "dev" || a.Params["table"] != "orders" || a.Params["change_id"] != "01J" {
+		t.Fatalf("params = %v", a.Params)
+	}
+	if s, _ := a.Params["since"].(string); !strings.HasSuffix(s, "Z") {
+		t.Fatalf("since not normalized to RFC3339 UTC: %v", a.Params["since"])
+	}
+}
+
+// TestAppsDBChangelogList_RejectsBadSince 验证不可解析的 --since 报 --since 的 ValidationError。
+func TestAppsDBChangelogList_RejectsBadSince(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBChangelogList,
+		[]string{"+db-changelog-list", "--app-id", "app_x", "--since", "notatime", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--since" {
+		t.Fatalf("Param = %q, want --since", ve.Param)
+	}
+}
+
+// TestAppsDBChangelogList_SuccessParsesOperator 验证成功响应中 operator JSON 串被解析为对象并输出变更字段。
+func TestAppsDBChangelogList_SuccessParsesOperator(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbChangelogURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"has_more": false, "page_token": "",
+			"items": []interface{}{map[string]interface{}{
+				"change_id": "01J", "changed_at": "2026-04-15T10:30:00Z",
+				"operator": `{"id":"7311","name":"alice"}`, "target_table": "orders",
+				"change_type": "ALTER_TABLE", "summary": "add column", "statement": "ALTER TABLE orders ...",
+			}},
+		}},
+	})
+	if err := runAppsShortcut(t, AppsDBChangelogList,
+		[]string{"+db-changelog-list", "--app-id", "app_x", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{`"operator"`, `"name": "alice"`, `"id": "7311"`, `"change_type": "ALTER_TABLE"`, `"statement"`} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing %q:\n%s", want, got)
+		}
+	}
+}
+
+// TestAppsDBChangelogList_ChangeIDNotFoundPretty 验证按 --change-id 查询无结果时 pretty 打印 not-found 提示。
+func TestAppsDBChangelogList_ChangeIDNotFoundPretty(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbChangelogURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"items": []interface{}{}}},
+	})
+	if err := runAppsShortcut(t, AppsDBChangelogList,
+		[]string{"+db-changelog-list", "--app-id", "app_x", "--change-id", "nope", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "No DDL change with id=nope found.") {
+		t.Fatalf("expected not-found message, got: %s", stdout.String())
+	}
+}
+
+// TestParseOperator_Cases 验证 parseOperator 处理合法 JSON、空 name 回退 id、非 JSON 原样、空串返回 nil，以及 operatorName(nil) 为占位符。
+func TestParseOperator_Cases(t *testing.T) {
+	if op := parseOperator(`{"id":"1","name":"a"}`); op == nil || op.ID != "1" || op.Name != "a" {
+		t.Fatalf("valid: %#v", op)
+	}
+	if op := parseOperator(`{"id":"1","name":""}`); op == nil || op.Name != "1" {
+		t.Fatalf("name fallback to id: %#v", op)
+	}
+	if op := parseOperator("plain-user"); op == nil || op.ID != "plain-user" || op.Name != "plain-user" {
+		t.Fatalf("non-json raw: %#v", op)
+	}
+	if op := parseOperator(""); op != nil {
+		t.Fatalf("empty → nil, got %#v", op)
+	}
+	if operatorName(nil) != "—" {
+		t.Fatalf("nil operatorName should be —")
+	}
+}
+
+// TestSafeParseJSON_Cases 验证 safeParseJSON 合法 JSON 解析为对象、非法 JSON 原样返回字符串。
+func TestSafeParseJSON_Cases(t *testing.T) {
+	if v := safeParseJSON(`{"a":1}`); v == nil {
+		t.Fatalf("valid json → object")
+	}
+	if v, ok := safeParseJSON("not json").(string); !ok || v != "not json" {
+		t.Fatalf("invalid json → raw string, got %v", v)
+	}
+}

shortcuts/apps/apps_db_data_export.go

@@ -0,0 +1,189 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const dbDataExportMaxRows = 5000
+const dbDataExportMaxBytes = 1 * 1024 * 1024 // 1 MB
+
+const dbDataExportHint = "verify --app-id and --table; if too large, filter rows with +db-execute (WHERE/LIMIT) and export smaller subsets"
+
+// AppsDBDataExport 把应用数据表导出到本地文件（csv/json/sql）。
+//
+// GET /apps/{app_id}/db/data_export，返回原始字节（非 JSON 信封）。
+// 行数不随导出文件返回：CLI 原子编排——先查 GetAppTableRecordList 的 total，再导出文件。
+// 数据格式由 --output 扩展名推断（默认 csv，缺省输出 <table>.csv）；上限 5000 行 / 1 MB。
+var AppsDBDataExport = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-data-export",
+	Description: "Export rows from a Miaoda app table to a local file (csv/json/sql)",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +db-data-export --app-id <app_id> --table orders --output ./orders.csv",
+		"Format follows the --output extension: .csv / .json / .sql (default csv).",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "table", Desc: "source table", Required: true},
+		{Name: "output", Desc: "local output path; extension picks format .csv/.json/.sql (default: <table>.csv)"},
+		{Name: "limit", Type: "int", Default: "5000", Desc: "max rows to export (1..5000)"},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "source db environment"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		if strings.TrimSpace(rctx.Str("table")) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--table is required").WithParam("--table")
+		}
+		if n := rctx.Int("limit"); n <= 0 || n > dbDataExportMaxRows {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--limit must be a positive integer ≤ %d", dbDataExportMaxRows).WithParam("--limit")
+		}
+		if _, _, err := exportFormatAndOutput(rctx); err != nil {
+			return err
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		format, _, _ := exportFormatAndOutput(rctx)
+		return common.NewDryRunAPI().
+			GET(appDataExportPath(appID)).
+			Desc("Export Miaoda app table data (raw bytes)").
+			Params(map[string]interface{}{
+				"env": rctx.Str("env"), "table": strings.TrimSpace(rctx.Str("table")),
+				"format": format, "limit": rctx.Int("limit"),
+			})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		table := strings.TrimSpace(rctx.Str("table"))
+		format, out, err := exportFormatAndOutput(rctx)
+		if err != nil {
+			return err
+		}
+
+		// 原子编排第 1 步：先查总行数（records 列表的 total），再导出文件。
+		// total 查询失败不阻断导出——回退到按导出文件内容数行。
+		total, totalErr := queryExportTotal(rctx, appID, rctx.Str("env"), table)
+
+		resp, err := rctx.DoAPI(&larkcore.ApiReq{
+			HttpMethod: http.MethodGet,
+			ApiPath:    appDataExportPath(appID),
+			QueryParams: larkcore.QueryParams{
+				"env":    []string{rctx.Str("env")},
+				"table":  []string{table},
+				"format": []string{format},
+				"limit":  []string{strconv.Itoa(rctx.Int("limit"))},
+			},
+		})
+		if err != nil {
+			return withAppsHint(errs.NewNetworkError(errs.SubtypeNetworkTransport, "export request failed").WithCause(err).WithRetryable(), dbDataExportHint)
+		}
+		// 成功是原始字节；业务错误网关以 JSON 信封 {code,msg} 返回（以 '{' 开头）。
+		if b := bytes.TrimSpace(resp.RawBody); len(b) > 0 && b[0] == '{' {
+			if _, cerr := rctx.ClassifyAPIResponse(resp); cerr != nil {
+				return withAppsHint(cerr, dbDataExportHint)
+			}
+		}
+		if resp.StatusCode >= 400 {
+			return withAppsHint(errs.NewNetworkError(errs.SubtypeNetworkServer, "export failed: HTTP %d", resp.StatusCode).WithRetryable(), dbDataExportHint)
+		}
+		body := resp.RawBody
+		if len(body) > dbDataExportMaxBytes {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "export exceeds 1 MB limit (%d bytes); filter rows with +db-execute (WHERE/LIMIT) and export smaller subsets", len(body))
+		}
+
+		saved, err := rctx.FileIO().Save(out, fileio.SaveOptions{
+			ContentType:   resp.Header.Get("Content-Type"),
+			ContentLength: int64(len(body)),
+		}, bytes.NewReader(body))
+		if err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output: %v", err).WithParam("--output")
+		}
+		// 行数取自预查的 total（导出最多 limit 行，故取 min）；total 查询失败时按导出内容数行兜底。
+		rows := 0
+		if totalErr == nil {
+			rows = total
+			if lim := rctx.Int("limit"); rows > lim {
+				rows = lim
+			}
+		} else {
+			rows = countDataRows(body, format)
+		}
+		resolved, perr := rctx.FileIO().ResolvePath(out)
+		if perr != nil || resolved == "" {
+			resolved = out
+		}
+		result := map[string]interface{}{
+			"table": table, "output": resolved, "format": format,
+			"rows": rows, "size_bytes": saved.Size(),
+		}
+		rctx.OutFormat(result, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "✓ Exported %s → %s (%d rows)\n", table, resolved, rows)
+		})
+		return nil
+	},
+}
+
+// queryExportTotal 调 GetAppTableRecordList（page_size=1）取 total（符合条件的记录总数）。
+// 该接口与 +db-data-export 同为 spark:app:read scope，避免导出命令被迫升级到写权限。
+func queryExportTotal(rctx *common.RuntimeContext, appID, env, table string) (int, error) {
+	raw, err := rctx.CallAPITyped("GET", appTableRecordsPath(appID, table),
+		map[string]interface{}{"env": env, "page_size": 1}, nil)
+	if err != nil {
+		return 0, err
+	}
+	return totalAsInt(raw["total"]), nil
+}
+
+// totalAsInt 把 total 解析成 int，兼容 JSON number 与 i64-as-string 两种 wire 形态。
+func totalAsInt(v interface{}) int {
+	if f, ok := numericAsFloat(v); ok {
+		return int(f)
+	}
+	if s, ok := v.(string); ok {
+		if n, err := strconv.Atoi(strings.TrimSpace(s)); err == nil {
+			return n
+		}
+	}
+	return 0
+}
+
+// exportFormatAndOutput 由 --output 推断数据格式与落盘路径：
+// 给了 --output → 取其扩展名定 format（csv/json/sql）；未给 → 默认 csv、输出 <table>.csv。
+func exportFormatAndOutput(rctx *common.RuntimeContext) (format, outPath string, err error) {
+	table := strings.TrimSpace(rctx.Str("table"))
+	out := strings.TrimSpace(rctx.Str("output"))
+	if out == "" {
+		return "csv", table + ".csv", nil
+	}
+	f, ferr := resolveDataFormat(filepath.Ext(out), true)
+	if ferr != nil {
+		return "", "", ferr
+	}
+	return f, out, nil
+}

shortcuts/apps/apps_db_data_export_test.go

@@ -0,0 +1,193 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const dbDataExportURL = "/open-apis/spark/v1/apps/app_x/db/data_export"
+const dbOrdersRecordsURL = "/open-apis/spark/v1/apps/app_x/tables/orders/records"
+
+// TestAppsDBDataExport_RequiresTable 验证缺 --table 时报必填错误。
+func TestAppsDBDataExport_RequiresTable(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	// 缺 --table → cobra required-flag, exit 1
+	err := runAppsShortcut(t, AppsDBDataExport,
+		[]string{"+db-data-export", "--app-id", "app_x", "--as", "user"}, factory, stdout)
+	if err == nil {
+		t.Fatalf("expected required-flag error for missing --table")
+	}
+}
+
+// TestAppsDBDataExport_RejectsBadLimit 验证越界 --limit（0/-1/5001）均报 --limit 的 ValidationError。
+func TestAppsDBDataExport_RejectsBadLimit(t *testing.T) {
+	for _, lim := range []string{"0", "-1", "5001"} {
+		factory, stdout, _ := newAppsExecuteFactory(t)
+		err := runAppsShortcut(t, AppsDBDataExport,
+			[]string{"+db-data-export", "--app-id", "app_x", "--table", "orders", "--limit", lim, "--as", "user"}, factory, stdout)
+		var ve *errs.ValidationError
+		if !errors.As(err, &ve) {
+			t.Fatalf("limit=%s err = %T %v, want *errs.ValidationError", lim, err, err)
+		}
+		if ve.Param != "--limit" {
+			t.Fatalf("limit=%s Param = %q, want --limit", lim, ve.Param)
+		}
+	}
+}
+
+// TestAppsDBDataExport_RejectsBadOutputExtension 验证不支持的 --output 扩展名（.xml）报校验错误。
+func TestAppsDBDataExport_RejectsBadOutputExtension(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBDataExport,
+		[]string{"+db-data-export", "--app-id", "app_x", "--table", "orders", "--output", "dump.xml", "--as", "user"}, factory, stdout)
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected unsupported-format validation for .xml, got %v", err)
+	}
+}
+
+// dry-run：format 跟随 --output 扩展名；缺省 csv。
+// TestAppsDBDataExport_DryRunFormatFromOutput 验证 dry-run 的 format 参数跟随 --output 扩展名、缺省为 csv，并带 limit。
+func TestAppsDBDataExport_DryRunFormatFromOutput(t *testing.T) {
+	cases := []struct{ output, wantFmt string }{
+		{"", "csv"}, {"orders.csv", "csv"}, {"orders.json", "json"}, {"dump.sql", "sql"},
+	}
+	for _, c := range cases {
+		factory, stdout, _ := newAppsExecuteFactory(t)
+		args := []string{"+db-data-export", "--app-id", "app_x", "--table", "orders", "--dry-run", "--as", "user"}
+		if c.output != "" {
+			args = append(args, "--output", c.output)
+		}
+		if err := runAppsShortcut(t, AppsDBDataExport, args, factory, stdout); err != nil {
+			t.Fatalf("dry-run err=%v", err)
+		}
+		var env struct {
+			API []struct {
+				Method string                 `json:"method"`
+				URL    string                 `json:"url"`
+				Params map[string]interface{} `json:"params"`
+			} `json:"api"`
+		}
+		_ = json.Unmarshal([]byte(stdout.String()), &env)
+		a := env.API[0]
+		if a.Method != "GET" || a.URL != dbDataExportURL {
+			t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+		}
+		if a.Params["format"] != c.wantFmt || a.Params["table"] != "orders" {
+			t.Errorf("output=%q params.format=%v want %q", c.output, a.Params["format"], c.wantFmt)
+		}
+		if _, ok := a.Params["limit"]; !ok {
+			t.Errorf("dry-run missing limit param")
+		}
+	}
+}
+
+// 成功：先查 records 列表 total 计行，再把原始字节落盘。
+// TestAppsDBDataExport_SuccessWritesFile 验证成功路径先查 records total 计行、再将导出原始字节落盘并输出 rows/format/table。
+func TestAppsDBDataExport_SuccessWritesFile(t *testing.T) {
+	dir := chdirTemp(t)
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	// 第 1 步：records 列表 total=2（行数来源）。
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbOrdersRecordsURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"total": 2, "has_more": false, "items": "[]"}},
+	})
+	// 第 2 步：导出原始字节。
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     dbDataExportURL,
+		RawBody: []byte("id,name\n1,a\n2,b\n"),
+		Headers: http.Header{"Content-Type": []string{"text/csv"}},
+	})
+	if err := runAppsShortcut(t, AppsDBDataExport,
+		[]string{"+db-data-export", "--app-id", "app_x", "--table", "orders", "--output", "orders.csv", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	b, err := os.ReadFile(dir + "/orders.csv")
+	if err != nil || string(b) != "id,name\n1,a\n2,b\n" {
+		t.Fatalf("output file wrong: %q err=%v", string(b), err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, `"rows": 2`) || !strings.Contains(got, `"format": "csv"`) || !strings.Contains(got, `"table": "orders"`) {
+		t.Fatalf("output json missing fields:\n%s", got)
+	}
+}
+
+// 行数取自 records total，且按 --limit 截顶（min(total, limit)）。
+// TestAppsDBDataExport_RowsFromTotalCappedByLimit 验证行数取 records total 并按 --limit 截顶（total=10000、limit=100 → rows=100）。
+func TestAppsDBDataExport_RowsFromTotalCappedByLimit(t *testing.T) {
+	chdirTemp(t)
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbOrdersRecordsURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"total": 10000, "has_more": true, "items": "[]"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbDataExportURL,
+		RawBody: []byte("id\n1\n2\n3\n"), Headers: http.Header{"Content-Type": []string{"text/csv"}},
+	})
+	if err := runAppsShortcut(t, AppsDBDataExport,
+		[]string{"+db-data-export", "--app-id", "app_x", "--table", "orders", "--output", "orders.csv", "--limit", "100", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), `"rows": 100`) {
+		t.Fatalf("expected rows capped to limit 100 from total=10000:\n%s", stdout.String())
+	}
+}
+
+// total 查询失败（records 列表报错）→ 回退按导出文件内容数行，不阻断导出。
+// TestAppsDBDataExport_FallsBackToFileCountWhenTotalUnavailable 验证 records total 查询失败时回退按导出文件内容数行，不阻断落盘。
+func TestAppsDBDataExport_FallsBackToFileCountWhenTotalUnavailable(t *testing.T) {
+	dir := chdirTemp(t)
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbOrdersRecordsURL,
+		Body: map[string]interface{}{"code": 1254000, "msg": "records unavailable"},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbDataExportURL,
+		RawBody: []byte("id,name\n1,a\n2,b\n3,c\n"), Headers: http.Header{"Content-Type": []string{"text/csv"}},
+	})
+	if err := runAppsShortcut(t, AppsDBDataExport,
+		[]string{"+db-data-export", "--app-id", "app_x", "--table", "orders", "--output", "orders.csv", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("export should still succeed via fallback, got %v", err)
+	}
+	b, _ := os.ReadFile(dir + "/orders.csv")
+	if string(b) != "id,name\n1,a\n2,b\n3,c\n" {
+		t.Fatalf("file not written on fallback path: %q", string(b))
+	}
+	if !strings.Contains(stdout.String(), `"rows": 3`) {
+		t.Fatalf("expected fallback file-count rows:3:\n%s", stdout.String())
+	}
+}
+
+// 业务错误：网关回 JSON 信封 {code,msg}（非原始字节）→ typed error，不落盘。
+// TestAppsDBDataExport_BusinessErrorEnvelope 验证响应为 JSON 错误信封（非原始字节）时返回 typed error 且不落盘。
+func TestAppsDBDataExport_BusinessErrorEnvelope(t *testing.T) {
+	chdirTemp(t)
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     dbDataExportURL,
+		RawBody: []byte(`{"code":1254043,"msg":"table not found"}`),
+		Headers: http.Header{"Content-Type": []string{"application/json"}},
+	})
+	err := runAppsShortcut(t, AppsDBDataExport,
+		[]string{"+db-data-export", "--app-id", "app_x", "--table", "nope", "--output", "nope.csv", "--as", "user"}, factory, stdout)
+	if err == nil {
+		t.Fatalf("expected business error to surface, got nil; stdout=%s", stdout.String())
+	}
+	if _, statErr := os.Stat("nope.csv"); statErr == nil {
+		t.Fatalf("error path must not write the output file")
+	}
+}

shortcuts/apps/apps_db_data_import.go

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"path/filepath"
+	"strings"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const dbDataImportMaxBytes = 1 * 1024 * 1024 // 1 MB
+
+const dbDataImportHint = "verify --app-id and --table; data file must be .csv/.json and ≤1 MB — split larger files and import in batches"
+
+// AppsDBDataImport 把本地 csv/json 文件直传到应用数据表（high-risk-write）。
+//
+// POST /apps/{app_id}/db/data_import，multipart 表单：file_name + 可选 table + 文件本体（与
+// +file-upload / UploadFileForOpenAPI 一致）。文件的格式解析与转换在服务端 integration 层完成
+// （按 file_name 扩展名推断 csv/json），CLI 不再本地解析。表名缺省取文件名（去扩展名）。上限 1 MB。
+var AppsDBDataImport = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-data-import",
+	Description: "Import rows from a local csv/json file into a Miaoda app table",
+	Risk:        "high-risk-write",
+	Tips: []string{
+		"Example: lark-cli apps +db-data-import --app-id <app_id> --file ./orders.csv --yes",
+		"Table defaults to the file name; override with --table.",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "file", Desc: "local data file (.csv/.json), relative to cwd", Required: true},
+		{Name: "table", Desc: "target table (default: file name without extension)"},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		if strings.TrimSpace(rctx.Str("file")) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file is required").WithParam("--file")
+		}
+		// 文件名即可校验格式（服务端按扩展名推断）与推断表名，无需读取内容。
+		if _, err := resolveDataFormat(filepath.Ext(rctx.Str("file")), false); err != nil {
+			return err
+		}
+		// 体积守卫前移到 Validate：用 Stat 先查大小（不读内容），dry-run 也能拦超大文件、且
+		// 在读整个文件进内存之前就失败（对齐 +file-upload）。Stat 失败不在此报错，留给 Execute
+		// 的 ReadInputFile 产出更精确的「文件不存在/越界」错误。
+		if st, serr := rctx.FileIO().Stat(strings.TrimSpace(rctx.Str("file"))); serr == nil && st.Size() > dbDataImportMaxBytes {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "import data exceeds 1 MB limit (file is %d bytes); split into ≤1 MB chunks", st.Size()).WithParam("--file")
+		}
+		if importTableName(rctx) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot infer target table from file name; specify --table").WithParam("--table")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		fileName := filepath.Base(strings.TrimSpace(rctx.Str("file")))
+		return common.NewDryRunAPI().
+			POST(appDataImportPath(appID)).
+			Desc("Import data file into Miaoda app table (multipart upload)").
+			Params(map[string]interface{}{"env": rctx.Str("env"), "table": importTableName(rctx)}).
+			Body(map[string]interface{}{"file_name": fileName, "file": "<contents of --file>"})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		file := strings.TrimSpace(rctx.Str("file"))
+		content, err := cmdutil.ReadInputFile(rctx.FileIO(), file)
+		if err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: %v", err).WithParam("--file")
+		}
+		if len(content) > dbDataImportMaxBytes {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "import data exceeds 1 MB limit (file is %d bytes); split into ≤1 MB chunks", len(content)).WithParam("--file")
+		}
+		fileName := filepath.Base(file)
+		table := importTableName(rctx)
+
+		// multipart：file_name 走表单字段、文件本体走 form-files；env / table 走 query。
+		fd := larkcore.NewFormdata()
+		fd.AddField("file_name", fileName)
+		fd.AddFile("file", bytes.NewReader(content))
+
+		resp, err := rctx.DoAPI(&larkcore.ApiReq{
+			HttpMethod:  http.MethodPost,
+			ApiPath:     appDataImportPath(appID),
+			QueryParams: larkcore.QueryParams{"env": []string{rctx.Str("env")}, "table": []string{table}},
+			Body:        fd,
+		}, larkcore.WithFileUpload())
+		if err != nil {
+			return withAppsHint(errs.NewNetworkError(errs.SubtypeNetworkTransport, "import request failed").WithCause(err).WithRetryable(), dbDataImportHint)
+		}
+		data, err := rctx.ClassifyAPIResponse(resp)
+		if err != nil {
+			return withAppsHint(err, dbDataImportHint)
+		}
+
+		outTable := common.GetString(data, "table")
+		if outTable == "" {
+			outTable = table
+		}
+		rows := int64(0)
+		if f, ok := numericAsFloat(data["rows"]); ok {
+			rows = int64(f)
+		}
+		out := map[string]interface{}{"file": file, "table": outTable, "rows": rows}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "✓ Imported %s → table '%s' (%d rows)\n", file, outTable, rows)
+		})
+		return nil
+	},
+}
+
+// importTableName 取目标表名：--table 优先，否则文件名去扩展名。
+func importTableName(rctx *common.RuntimeContext) string {
+	if t := strings.TrimSpace(rctx.Str("table")); t != "" {
+		return t
+	}
+	f := strings.TrimSpace(rctx.Str("file"))
+	if f == "" {
+		return ""
+	}
+	base := filepath.Base(f)
+	return strings.TrimSuffix(base, filepath.Ext(base))
+}

shortcuts/apps/apps_db_data_import_test.go

@@ -0,0 +1,161 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const dbDataImportURL = "/open-apis/spark/v1/apps/app_x/db/data_import"
+
+// chdirTemp 切到临时工作目录（--file 走 cwd 内相对路径），返回该目录。
+func chdirTemp(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	old, _ := os.Getwd()
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(old) })
+	return dir
+}
+
+// TestAppsDBDataImport_RequiresAppID 验证空白 --app-id 报 --app-id 的 ValidationError。
+func TestAppsDBDataImport_RequiresAppID(t *testing.T) {
+	chdirTemp(t)
+	_ = os.WriteFile("orders.csv", []byte("id\n1\n"), 0o600)
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBDataImport,
+		[]string{"+db-data-import", "--app-id", "  ", "--file", "orders.csv", "--yes", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--app-id" {
+		t.Fatalf("Param = %q, want --app-id", ve.Param)
+	}
+}
+
+// TestAppsDBDataImport_RejectsUnsupportedFormat 验证非 csv/json 文件（.txt）报不支持格式的校验错误。
+func TestAppsDBDataImport_RejectsUnsupportedFormat(t *testing.T) {
+	chdirTemp(t)
+	_ = os.WriteFile("data.txt", []byte("x\n"), 0o600)
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBDataImport,
+		[]string{"+db-data-import", "--app-id", "app_x", "--file", "data.txt", "--yes", "--as", "user"}, factory, stdout)
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected unsupported-format validation, got %v", err)
+	}
+}
+
+// TestAppsDBDataImport_RequiresConfirmation 验证缺 --yes 时报 requires confirmation 错误。
+func TestAppsDBDataImport_RequiresConfirmation(t *testing.T) {
+	chdirTemp(t)
+	_ = os.WriteFile("orders.csv", []byte("id\n1\n"), 0o600)
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBDataImport,
+		[]string{"+db-data-import", "--app-id", "app_x", "--file", "orders.csv", "--as", "user"}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "requires confirmation") {
+		t.Fatalf("expected confirmation_required, got %v", err)
+	}
+}
+
+// TestAppsDBDataImport_RejectsOversizeFile 验证超过 1MB 上限的文件报 --file 的 ValidationError。
+func TestAppsDBDataImport_RejectsOversizeFile(t *testing.T) {
+	chdirTemp(t)
+	// >1MB → size 校验
+	big := append([]byte("id\n"), make([]byte, dbDataImportMaxBytes+1)...)
+	_ = os.WriteFile("big.csv", big, 0o600)
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBDataImport,
+		[]string{"+db-data-import", "--app-id", "app_x", "--file", "big.csv", "--yes", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected 1MB limit error, got %T %v", err, err)
+	}
+	if ve.Param != "--file" {
+		t.Fatalf("Param = %q, want --file", ve.Param)
+	}
+}
+
+// dry-run：multipart 上传——file_name + file 走 body，env + table 走 query（table 缺省取文件名）。
+// TestAppsDBDataImport_DryRunMultipartShape 验证 dry-run 的 multipart 形态：file_name+file 走 body、env+table 走 query 且不再发 format。
+func TestAppsDBDataImport_DryRunMultipartShape(t *testing.T) {
+	chdirTemp(t)
+	_ = os.WriteFile("orders.csv", []byte("id\n1\n"), 0o600)
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBDataImport,
+		[]string{"+db-data-import", "--app-id", "app_x", "--file", "orders.csv", "--env", "dev", "--dry-run", "--yes", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	a := env.API[0]
+	if a.Method != "POST" || a.URL != dbDataImportURL {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	if a.Body["file_name"] != "orders.csv" || a.Body["file"] == nil {
+		t.Fatalf("dry-run body should carry file_name + file: %v", a.Body)
+	}
+	if _, ok := a.Body["format"]; ok {
+		t.Fatalf("format must no longer be sent: %v", a.Body)
+	}
+	if a.Params["env"] != "dev" || a.Params["table"] != "orders" {
+		t.Fatalf("dry-run params (env+table) = %v", a.Params)
+	}
+}
+
+// TestAppsDBDataImport_Success 验证成功导入后输出含 table、rows 与回显的 file 名。
+func TestAppsDBDataImport_Success(t *testing.T) {
+	chdirTemp(t)
+	_ = os.WriteFile("orders.csv", []byte("id,name\n1,a\n2,b\n"), 0o600)
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbDataImportURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"table": "orders", "rows": 2}},
+	})
+	if err := runAppsShortcut(t, AppsDBDataImport,
+		[]string{"+db-data-import", "--app-id", "app_x", "--file", "orders.csv", "--table", "orders", "--yes", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, `"table": "orders"`) || !strings.Contains(got, `"rows": 2`) || !strings.Contains(got, `"file": "orders.csv"`) {
+		t.Fatalf("output missing fields:\n%s", got)
+	}
+}
+
+// TestAppsDBDataImport_TableDefaultsToFileBasename 验证未传 --table 时表名缺省取文件名去扩展名（customers.json→customers）。
+func TestAppsDBDataImport_TableDefaultsToFileBasename(t *testing.T) {
+	chdirTemp(t)
+	_ = os.WriteFile("customers.json", []byte(`[{"id":1}]`), 0o600)
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBDataImport,
+		[]string{"+db-data-import", "--app-id", "app_x", "--file", "customers.json", "--dry-run", "--yes", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	if env.API[0].Params["table"] != "customers" {
+		t.Fatalf("expected table=customers (from file basename) in params, got %v", env.API[0].Params)
+	}
+}

shortcuts/apps/apps_db_env_migrate.go

@@ -0,0 +1,191 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const dbEnvMigrateHint = "ensure the app is multi-env (`+db-env-create`) and has pending dev changes; preview with `+db-env-diff`"
+
+// AppsDBEnvDiff 预览 dev→online 待发布的结构变更（不落地）。
+//
+// POST /apps/{app_id}/db/env_migrate，body {dry_run:true}，同步返 {from,to,changes[]}。
+// 与 +db-env-migrate 同端点、dry_run 区分；预览也需 spark:app:write scope。
+var AppsDBEnvDiff = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-env-diff",
+	Description: "Preview pending dev→online schema changes (no apply)",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +db-env-diff --app-id <app_id>",
+		"Apply the previewed changes with +db-env-migrate --yes.",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().POST(appEnvMigratePath(appID)).Desc("Preview dev→online migration").Body(map[string]interface{}{"dry_run": true})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		stop := rctx.StartSpinner("Previewing migration diff (dev → online)")
+		defer stop()
+		data, err := rctx.CallAPITyped("POST", appEnvMigratePath(appID), nil, map[string]interface{}{"dry_run": true})
+		stop()
+		if err != nil {
+			return withAppsHint(err, dbEnvMigrateHint)
+		}
+		from, to := common.GetString(data, "from"), common.GetString(data, "to")
+		changes := projectMigrationChanges(data["changes"])
+		out := map[string]interface{}{"from": from, "to": to, "changes": changes}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderMigrationDiff(w, from, to, changes)
+		})
+		return nil
+	},
+}
+
+// AppsDBEnvMigrate 把 dev 的待发布结构变更发布到 online（异步，CLI 轮询至完成）。
+//
+// POST /apps/{app_id}/db/env_migrate，body {dry_run:false} → task_id，轮询 env_migrate_status
+// 至 success；后端 status:applied，CLI 对外统一呈现 migrated。high-risk-write。
+var AppsDBEnvMigrate = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-env-migrate",
+	Description: "Publish pending dev→online schema changes (irreversible)",
+	Risk:        "high-risk-write",
+	Tips: []string{
+		"Example: lark-cli apps +db-env-migrate --app-id <app_id> --yes",
+		"Preview first with +db-env-diff.",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().POST(appEnvMigratePath(appID)).Desc("Apply dev→online migration").Body(map[string]interface{}{"dry_run": false})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		stop := rctx.StartSpinner("Applying migration (dev → online)")
+		defer stop()
+		submit, err := rctx.CallAPITyped("POST", appEnvMigratePath(appID), nil, map[string]interface{}{"dry_run": false})
+		if err != nil {
+			return withAppsHint(err, dbEnvMigrateHint)
+		}
+		from, to := common.GetString(submit, "from"), common.GetString(submit, "to")
+		taskID := common.GetString(submit, "task_id")
+		applied := intFromAny(submit["changes_applied"])
+		if applied == 0 {
+			applied = len(projectMigrationChanges(submit["changes"]))
+		}
+		// 有 task_id → 异步，轮询至终态；无 task_id（同步完成）则直接用 submit 结果。
+		if taskID != "" {
+			final, perr := pollUntil(rctx.Ctx(), 1*time.Second, 10*time.Minute,
+				func() (map[string]interface{}, error) {
+					return rctx.CallAPITyped("GET", appEnvMigrateStatusPath(appID), map[string]interface{}{"task_id": taskID}, nil)
+				},
+				func(d map[string]interface{}) (bool, error) {
+					switch strings.ToLower(common.GetString(d, "status")) {
+					case "success", "applied", "migrated":
+						return true, nil
+					case "failed":
+						return false, withAppsHint(errs.NewAPIError(errs.SubtypeServerError, "%s", migrateFailMsg(d, taskID)), dbEnvMigrateHint)
+					}
+					return false, nil
+				})
+			if perr != nil {
+				return perr
+			}
+			if n := intFromAny(final["changes_applied"]); n > 0 {
+				applied = n
+			}
+		}
+		stop() // clear spinner before printing the result
+		out := map[string]interface{}{"status": "migrated", "from": from, "to": to, "changes_applied": applied}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "✓ Migrated %s → %s (%d changes)\n", from, to, applied)
+		})
+		return nil
+	},
+}
+
+type migrationChange struct {
+	Type      string `json:"type"`
+	Table     string `json:"table"`
+	Statement string `json:"statement"`
+}
+
+// projectMigrationChanges 把服务端原始变更项投影为白名单 migrationChange（type/table/statement）。
+func projectMigrationChanges(raw interface{}) []migrationChange {
+	arr, _ := raw.([]interface{})
+	out := make([]migrationChange, 0, len(arr))
+	for _, it := range arr {
+		if m, ok := it.(map[string]interface{}); ok {
+			out = append(out, migrationChange{
+				Type:      common.GetString(m, "type"),
+				Table:     common.GetString(m, "table"),
+				Statement: common.GetString(m, "statement"),
+			})
+		}
+	}
+	return out
+}
+
+// renderMigrationDiff 渲染 dev→online 待发布变更：无变更打提示，否则逐条打 statement。
+func renderMigrationDiff(w io.Writer, from, to string, changes []migrationChange) {
+	if len(changes) == 0 {
+		fmt.Fprintf(w, "No pending changes from %s to %s.\n", from, to)
+		return
+	}
+	fmt.Fprintf(w, "%s → %s (%d changes):\n\n", from, to, len(changes))
+	for _, c := range changes {
+		fmt.Fprintf(w, "  %s\n", c.Statement)
+	}
+}
+
+// migrateFailMsg 取发布失败信息：优先服务端 error_message，缺失则用带 task_id 的兜底文案。
+func migrateFailMsg(d map[string]interface{}, taskID string) string {
+	if m := common.GetString(d, "error_message"); m != "" {
+		return m
+	}
+	return fmt.Sprintf("migration apply failed (task_id=%s)", taskID)
+}
+
+// intFromAny 把 JSON number / json.Number 转 int（计数用）。
+func intFromAny(v interface{}) int {
+	if f, ok := numericAsFloat(v); ok {
+		return int(f)
+	}
+	return 0
+}

shortcuts/apps/apps_db_env_recovery_quota_test.go

@@ -0,0 +1,369 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const (
+	dbEnvMigrateURL       = "/open-apis/spark/v1/apps/app_x/db/env_migrate"
+	dbEnvMigrateStatusURL = "/open-apis/spark/v1/apps/app_x/db/env_migrate_status"
+	dbRecoveryURL         = "/open-apis/spark/v1/apps/app_x/db/env_recovery"
+	dbRecoveryDiffURL     = "/open-apis/spark/v1/apps/app_x/db/env_recovery_diff_status"
+	dbRecoveryApplyURL    = "/open-apis/spark/v1/apps/app_x/db/env_recovery_apply_status"
+	dbQuotaURL            = "/open-apis/spark/v1/apps/app_x/db/quota"
+)
+
+// ── env-diff ──
+
+// TestAppsDBEnvDiff_DryRunBody 校验 dry-run 请求体：POST env_migrate 且 dry_run=true。
+func TestAppsDBEnvDiff_DryRunBody(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBEnvDiff,
+		[]string{"+db-env-diff", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	a := env.API[0]
+	if a.Method != "POST" || a.URL != dbEnvMigrateURL || a.Body["dry_run"] != true {
+		t.Fatalf("dry-run = %s %s body=%v", a.Method, a.URL, a.Body)
+	}
+}
+
+// TestAppsDBEnvDiff_SuccessRendersChanges 验证 pretty 输出渲染出 dev → online 变更摘要及 DDL 语句。
+func TestAppsDBEnvDiff_SuccessRendersChanges(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbEnvMigrateURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"from": "dev", "to": "online",
+			"changes": []interface{}{
+				map[string]interface{}{"type": "ALTER_TABLE", "table": "orders", "statement": "ALTER TABLE orders ADD COLUMN note text"},
+			},
+		}},
+	})
+	if err := runAppsShortcut(t, AppsDBEnvDiff,
+		[]string{"+db-env-diff", "--app-id", "app_x", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "dev → online (1 changes)") || !strings.Contains(got, "ALTER TABLE orders ADD COLUMN note text") {
+		t.Fatalf("pretty diff malformed:\n%s", got)
+	}
+}
+
+// TestAppsDBEnvDiff_EmptyChanges 验证无变更时 pretty 输出"无待发布变更"提示。
+func TestAppsDBEnvDiff_EmptyChanges(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbEnvMigrateURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"from": "dev", "to": "online", "changes": []interface{}{}}},
+	})
+	if err := runAppsShortcut(t, AppsDBEnvDiff,
+		[]string{"+db-env-diff", "--app-id", "app_x", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "No pending changes from dev to online.") {
+		t.Fatalf("expected empty message, got: %s", stdout.String())
+	}
+}
+
+// ── env-migrate ──
+
+// TestAppsDBEnvMigrate_DryRunBody 校验 migrate 的 dry-run 请求体里 dry_run=false（真实迁移）。
+func TestAppsDBEnvMigrate_DryRunBody(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBEnvMigrate,
+		[]string{"+db-env-migrate", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Body map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	if env.API[0].Body["dry_run"] != false {
+		t.Fatalf("dry-run body=%v (want dry_run:false)", env.API[0].Body)
+	}
+}
+
+// 异步：submit 返 task_id，status 立刻 applied → CLI 对外统一 migrated。
+func TestAppsDBEnvMigrate_AsyncPollSuccess(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbEnvMigrateURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"from": "dev", "to": "online", "task_id": "t1"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbEnvMigrateStatusURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"task_id": "t1", "status": "applied", "changes_applied": 3}},
+	})
+	if err := runAppsShortcut(t, AppsDBEnvMigrate,
+		[]string{"+db-env-migrate", "--app-id", "app_x", "--yes", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "✓ Migrated dev → online (3 changes)") {
+		t.Fatalf("pretty: %s", got)
+	}
+}
+
+// TestAppsDBEnvMigrate_PollFailedSurfacesError 验证轮询到 failed 时返回 API/server_error 类型错误，携带服务端 message 与恢复 hint。
+func TestAppsDBEnvMigrate_PollFailedSurfacesError(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbEnvMigrateURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"from": "dev", "to": "online", "task_id": "t1"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbEnvMigrateStatusURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"task_id": "t1", "status": "failed", "error_message": "lock timeout"}},
+	})
+	err := runAppsShortcut(t, AppsDBEnvMigrate,
+		[]string{"+db-env-migrate", "--app-id", "app_x", "--yes", "--as", "user"}, factory, stdout)
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Category != errs.CategoryAPI || p.Subtype != errs.SubtypeServerError {
+		t.Fatalf("got %T %v, want API/server_error typed error", err, err)
+	}
+	if !strings.Contains(p.Message, "lock timeout") {
+		t.Fatalf("Message = %q, want it to contain 'lock timeout'", p.Message)
+	}
+	if !strings.Contains(p.Hint, "+db-env-diff") {
+		t.Fatalf("Hint = %q, want the db-env-migrate recovery hint", p.Hint)
+	}
+}
+
+// TestAppsDBEnvMigrate_RequiresConfirmation 验证 high-risk-write 无 --yes 时被确认门拦截。
+func TestAppsDBEnvMigrate_RequiresConfirmation(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	// high-risk-write 无 --yes → 应被确认门拦截（非 0 退出）。
+	if err := runAppsShortcut(t, AppsDBEnvMigrate,
+		[]string{"+db-env-migrate", "--app-id", "app_x", "--as", "user"}, factory, stdout); err == nil {
+		t.Fatalf("expected confirmation gate without --yes")
+	}
+}
+
+// ── recovery-diff ──
+
+// TestAppsDBRecoveryDiff_RequiresTarget 验证缺少 --target 时报必填错误。
+func TestAppsDBRecoveryDiff_RequiresTarget(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBRecoveryDiff,
+		[]string{"+db-recovery-diff", "--app-id", "app_x", "--as", "user"}, factory, stdout); err == nil {
+		t.Fatalf("expected required --target error")
+	}
+}
+
+// TestAppsDBRecoveryDiff_DryRunNormalizesTarget 验证 dry-run 走 POST env_recovery 且 --target 被归一化为 RFC3339 UTC。
+func TestAppsDBRecoveryDiff_DryRunNormalizesTarget(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBRecoveryDiff,
+		[]string{"+db-recovery-diff", "--app-id", "app_x", "--target", "2026-04-15", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	a := env.API[0]
+	if a.Method != "POST" || a.URL != dbRecoveryURL || a.Body["dry_run"] != true {
+		t.Fatalf("dry-run = %s %s body=%v", a.Method, a.URL, a.Body)
+	}
+	if s, _ := a.Body["target"].(string); !strings.HasSuffix(s, "Z") {
+		t.Fatalf("target not normalized to RFC3339 UTC: %v", a.Body["target"])
+	}
+}
+
+// TestAppsDBRecoveryDiff_SuccessRendersChanges 验证 preview 成功后 pretty 渲染受影响表数、行增删与预估耗时。
+func TestAppsDBRecoveryDiff_SuccessRendersChanges(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbRecoveryURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"preview_request_id": "p1"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbRecoveryDiffURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"preview_status": "success", "tables_affected": 2, "estimated_seconds": 12,
+			"changes": []interface{}{
+				map[string]interface{}{"table": "orders", "inserted": 5, "deleted": 2},
+				map[string]interface{}{"table": "carts", "action": "restore_table"},
+			},
+		}},
+	})
+	if err := runAppsShortcut(t, AppsDBRecoveryDiff,
+		[]string{"+db-recovery-diff", "--app-id", "app_x", "--target", "2h", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{"tables affected: 2", "orders: +5 rows, -2 rows", "carts: table will be restored", "estimated time: ~12s"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing %q:\n%s", want, got)
+		}
+	}
+}
+
+// TestAppsDBRecoveryDiff_PreviewFailed 验证 preview_status=failed 时返回 API/server_error，携带 message 与 PITR window hint。
+func TestAppsDBRecoveryDiff_PreviewFailed(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbRecoveryURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"preview_request_id": "p1"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbRecoveryDiffURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"preview_status": "failed", "error_message": "snapshot expired"}},
+	})
+	err := runAppsShortcut(t, AppsDBRecoveryDiff,
+		[]string{"+db-recovery-diff", "--app-id", "app_x", "--target", "2h", "--as", "user"}, factory, stdout)
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Category != errs.CategoryAPI || p.Subtype != errs.SubtypeServerError {
+		t.Fatalf("got %T %v, want API/server_error typed error", err, err)
+	}
+	if !strings.Contains(p.Message, "snapshot expired") {
+		t.Fatalf("Message = %q, want it to contain 'snapshot expired'", p.Message)
+	}
+	if !strings.Contains(p.Hint, "PITR window") {
+		t.Fatalf("Hint = %q, want the db-recovery recovery hint", p.Hint)
+	}
+}
+
+// ── recovery-apply ──
+
+// TestAppsDBRecoveryApply_NoChangesShortCircuits 验证 status=no_changes 时短路输出"已是该状态"，不再轮询。
+func TestAppsDBRecoveryApply_NoChangesShortCircuits(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbRecoveryURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"status": "no_changes"}},
+	})
+	if err := runAppsShortcut(t, AppsDBRecoveryApply,
+		[]string{"+db-recovery-apply", "--app-id", "app_x", "--target", "2h", "--yes", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "No changes — database is already at this state.") {
+		t.Fatalf("expected no-changes short-circuit, got: %s", stdout.String())
+	}
+}
+
+// TestAppsDBRecoveryApply_AsyncPollSuccess 验证 running → 轮询 success 后 pretty 输出恢复完成及耗时。
+func TestAppsDBRecoveryApply_AsyncPollSuccess(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: dbRecoveryURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"status": "running"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbRecoveryApplyURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"status": "success", "restore_time_sec": 8}},
+	})
+	if err := runAppsShortcut(t, AppsDBRecoveryApply,
+		[]string{"+db-recovery-apply", "--app-id", "app_x", "--target", "2h", "--yes", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "✓ Database restored to") || !strings.Contains(stdout.String(), "(8s elapsed)") {
+		t.Fatalf("pretty: %s", stdout.String())
+	}
+}
+
+// TestAppsDBRecoveryApply_RequiresConfirmation 验证无 --yes 时被确认门拦截。
+func TestAppsDBRecoveryApply_RequiresConfirmation(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBRecoveryApply,
+		[]string{"+db-recovery-apply", "--app-id", "app_x", "--target", "2h", "--as", "user"}, factory, stdout); err == nil {
+		t.Fatalf("expected confirmation gate without --yes")
+	}
+}
+
+// ── quota-get ──
+
+// TestAppsDBQuotaGet_WithQuotaPretty 验证已对接配额时 pretty 渲染存储用量、百分比及 tables/views 数。
+func TestAppsDBQuotaGet_WithQuotaPretty(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbQuotaURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"storage_used_bytes": 1048576, "storage_quota_bytes": 10485760, "usage_percent": 10.0,
+			"tables": 4, "views": 1,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsDBQuotaGet,
+		[]string{"+db-quota-get", "--app-id", "app_x", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{"Storage", "(10.0%)", "Tables", "4", "Views", "1"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing %q:\n%s", want, got)
+		}
+	}
+}
+
+// 配额未对接（storage_quota_bytes=0）→ json 删 quota/usage_percent，仅留已用量与 tables/views。
+func TestAppsDBQuotaGet_NoQuotaOmitsFields(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: dbQuotaURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"storage_used_bytes": 2048, "storage_quota_bytes": 0, "tables": 2, "views": 0,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsDBQuotaGet,
+		[]string{"+db-quota-get", "--app-id", "app_x", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if strings.Contains(got, "storage_quota_bytes") || strings.Contains(got, "usage_percent") {
+		t.Fatalf("quota fields should be omitted when not provisioned:\n%s", got)
+	}
+	if !strings.Contains(got, "storage_used_bytes") || !strings.Contains(got, "\"tables\"") {
+		t.Fatalf("expected used + tables retained:\n%s", got)
+	}
+}
+
+// TestProjectDbQuota_WhitelistsFields 验证 projectDbQuota 白名单投影：只保留 used/tables/views（及配额已对接时的
+// quota/usage_percent），后端额外字段不透传。
+func TestProjectDbQuota_WhitelistsFields(t *testing.T) {
+	out := projectDbQuota(map[string]interface{}{
+		"storage_used_bytes": 2048, "storage_quota_bytes": float64(0), "usage_percent": float64(0),
+		"tables": 2, "views": 1, "tenant_key": "leak", "internal_shard": "s1",
+	})
+	if _, ok := out["storage_quota_bytes"]; ok {
+		t.Errorf("zero quota should be omitted: %v", out)
+	}
+	if out["storage_used_bytes"] != 2048 || out["tables"] != 2 || out["views"] != 1 {
+		t.Errorf("whitelisted fields should be kept: %v", out)
+	}
+	for _, leaked := range []string{"tenant_key", "internal_shard"} {
+		if _, ok := out[leaked]; ok {
+			t.Errorf("non-whitelisted field %q must be dropped: %v", leaked, out)
+		}
+	}
+
+	out2 := projectDbQuota(map[string]interface{}{"storage_used_bytes": 2048, "storage_quota_bytes": float64(4096), "usage_percent": float64(50), "tables": 2})
+	if _, ok := out2["storage_quota_bytes"]; !ok {
+		t.Errorf("non-zero quota should be kept: %v", out2)
+	}
+	if _, ok := out2["usage_percent"]; !ok {
+		t.Errorf("usage_percent should be kept when quota>0: %v", out2)
+	}
+}

shortcuts/apps/apps_db_execute.go

@@ -12,6 +12,7 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -31,11 +32,18 @@ import (
 //   - 多语句部分失败：`Statement K: ✗ <message> [<code>]` + 末尾「前序语句已落地」提示
 //
 // 失败语义：server 多语句失败仍返 code:0，把失败语句标成 ERROR 哨兵塞进 result。Execute 检测到哨兵
-// 后升级成 typed api_error（exit 非 0、detail 带 statement_index / completed / rolled_back），
-// 避免 agent 误判 ok:true 假成功。CLI 永远 DBA 模式（transactional=false），失败前的语句已 auto-commit
-// 落地，故 rolled_back=false（真机 boe 实证）。
+// 后升级成 typed errs.APIError（CategoryAPI → exit 1），避免 agent 误判 ok:true 假成功。诊断信息
+// （第几条失败 / 共几条 / 是否整批回滚 / 前序是否落地）写进 message+hint 文案（errs.* 信封扁平、无
+// detail 容器）：失败在用户显式 BEGIN…COMMIT 事务内 → 整批回滚、前序未落库；否则前序语句已逐条
+// commit、未回滚。rolled_back 语义由 inferRolledBack 按 BEGIN/COMMIT 计数推断。
 //
-// JSON envelope（成功路径）：CLI 把 server 返的 result 字符串解出来放进 `data.results` 数组。
+// JSON（成功路径）按 SQL 类型归一化 `data`（不透传后端 result 字符串）：
+//   - 单 SELECT → data 是行数组 `[{...}]`（空 → `[]`）
+//   - 单 DML    → data = `{command, rows_affected}`
+//   - 单 DDL    → data = `{command}`
+//   - 多语句    → data = `[{command:"SELECT",rows:[...]} | {command,rows_affected} | {command}]`
+//
+// 字段裁剪用框架原生 --jq/-q。
 //
 // Risk: high-risk-write —— SQL 可含 DML/DDL，框架对所有执行强制 --yes 确认关卡（--dry-run 预览豁免）。
 //
@@ -49,7 +57,7 @@ var AppsDBExecute = common.Shortcut{
 	Tips: []string{
 		`Example: lark-cli apps +db-execute --app-id <app_id> --sql "SELECT * FROM orders LIMIT 10" --yes`,
 		`Example: lark-cli apps +db-execute --app-id <app_id> --env dev --file ./migration.sql --yes`,
-		"Tip: filter fields with --jq, e.g. -q '.data.results[].sql_type'",
+		"Tip: single SELECT returns data as a row array — filter with --jq, e.g. -q '.data[].id'",
 	},
 	Scopes:    []string{"spark:app:write"},
 	AuthTypes: []string{"user"},
@@ -104,13 +112,18 @@ var AppsDBExecute = common.Shortcut{
 			return withAppsHint(err, "verify table/column names with `lark-cli apps +db-table-get --app-id "+appID+" --table <table>`; for day-to-day debugging target the dev database with `--env dev`")
 		}
 
-		// server `result: string` 内嵌结构化数组 —— CLI 解出来放进 envelope 的 data.results，
+		// server `result: string` 内嵌结构化数组 —— CLI 解出来后按 SQL 类型归一化成 PRD 形态，
 		// 让 json/pretty 路径都基于同一份反序列化产物渲染。
 		stmts := parseSQLResult(common.GetString(raw, "result"))
-		// 注意：data.results 在 json（默认）路径下原样透出全部行，CLI 侧不再二次截断。
-		// 这不是无界 token 黑洞 —— server 对单条 SELECT 结果集有 1000 行硬上限，超出会直接
-		// 返报错（而非静默截断）。需要更大结果集时请在 SQL 里显式 LIMIT/分页，由调用方控制规模。
-		data := map[string]interface{}{"results": stmts}
+		// JSON data 形态（不再透传后端 result 字符串）：
+		//   - 单 SELECT → data 是行数组 [{...}]（空 → []）
+		//   - 单 DML    → data = {command, rows_affected}
+		//   - 单 DDL    → data = {command}
+		//   - 多语句    → data = [{command:"SELECT",rows:[...]} | {command,rows_affected} | {command}]
+		// 字段裁剪走框架原生 --jq/-q（不引入 miaoda 的 --json <fields>）。
+		// 这不是无界 token 黑洞 —— server 对单条 SELECT 结果集有 1000 行硬上限，超出直接报错
+		// （而非静默截断）。需要更大结果集时请在 SQL 里显式 LIMIT/分页，由调用方控制规模。
+		data := shapeSQLData(stmts)
 
 		// 多语句 / 单语句失败：server 仍返 code:0，把失败语句标成 ERROR 哨兵塞进 result。
 		// 升级成 typed api_error（exit 非 0），别让 agent 误判 ok:true 假成功。
@@ -129,6 +142,70 @@ var AppsDBExecute = common.Shortcut{
 	},
 }
 
+// shapeSQLData 把解析出的 statements 归一化成 PRD 约定的 JSON `data` 形态：
+//   - 无语句       → []（空数组）
+//   - 单条语句     → singleStatementJSON（SELECT 是行数组、DML/DDL 是对象）
+//   - 多条语句     → []multiStatementElement（每条统一成 {command,...} 对象，SELECT 行放 rows）
+//
+// 不再透传后端 result 字符串（旧形态 data.results[].data 是 JSON 字符串，对 agent 不友好）。
+func shapeSQLData(stmts []map[string]interface{}) interface{} {
+	if len(stmts) == 0 {
+		return []interface{}{}
+	}
+	if len(stmts) == 1 {
+		return singleStatementJSON(stmts[0])
+	}
+	out := make([]interface{}, 0, len(stmts))
+	for _, s := range stmts {
+		out = append(out, multiStatementElement(s))
+	}
+	return out
+}
+
+// singleStatementJSON 单条语句的 PRD JSON 形态：
+//   - SELECT → 行数组（空 → []）
+//   - DML    → {command, rows_affected}
+//   - DDL / OK / 其它 → {command}
+func singleStatementJSON(s map[string]interface{}) interface{} {
+	sqlType := common.GetString(s, "sql_type")
+	switch {
+	case sqlType == "SELECT":
+		return selectRows(s)
+	case isDMLType(sqlType):
+		return map[string]interface{}{"command": sqlType, "rows_affected": intOrZero(s["affected_rows"])}
+	default:
+		return map[string]interface{}{"command": sqlType}
+	}
+}
+
+// multiStatementElement 多语句里单条的 PRD JSON 形态：与单条一致，但 SELECT 包成
+// {command:"SELECT", rows:[...]}（避免数组里直接嵌套数组造成歧义）。
+func multiStatementElement(s map[string]interface{}) map[string]interface{} {
+	sqlType := common.GetString(s, "sql_type")
+	switch {
+	case sqlType == "SELECT":
+		return map[string]interface{}{"command": "SELECT", "rows": selectRows(s)}
+	case isDMLType(sqlType):
+		return map[string]interface{}{"command": sqlType, "rows_affected": intOrZero(s["affected_rows"])}
+	default:
+		return map[string]interface{}{"command": sqlType}
+	}
+}
+
+// selectRows 把 SELECT statement 的 data 字段（行 JSON 数组字符串）解析成行数组；
+// 空 / 非法一律返回非 nil 的空数组（保证 JSON 序列化成 [] 而非 null）。
+func selectRows(s map[string]interface{}) []map[string]interface{} {
+	dataJSON := strings.TrimSpace(common.GetString(s, "data"))
+	if dataJSON == "" || dataJSON == "null" {
+		return []map[string]interface{}{}
+	}
+	var rows []map[string]interface{}
+	if err := json.Unmarshal([]byte(dataJSON), &rows); err != nil || rows == nil {
+		return []map[string]interface{}{}
+	}
+	return rows
+}
+
 // findErrorSentinel 在 statements 里找 ERROR 哨兵（server 失败时追加在失败语句位置）。
 // 返回失败语句下标（0-based）、该 ERROR statement、是否命中。
 func findErrorSentinel(stmts []map[string]interface{}) (int, map[string]interface{}, bool) {
@@ -140,31 +217,48 @@ func findErrorSentinel(stmts []map[string]interface{}) (int, map[string]interfac
 	return 0, nil, false
 }
 
-// sqlStatementError 把 ERROR 哨兵升级成 typed api_error。
+// sqlStatementError 把 ERROR 哨兵升级成 typed errs.APIError（CategoryAPI → exit 1）。
 //
-// CLI 永远 DBA 模式（transactional=false），真机 boe 实证：失败语句之前的语句已逐条 auto-commit
-// 落地，不存在外层事务回滚。因此 rolled_back=false、completed 列出已落地的前序语句，hint 提示用户
-// 别整批重跑（否则会重复写入）。
+// 多语句失败的诊断信息——第几条失败 / 共几条 / 是否整批回滚 / 前序是否落地——都写进
+// message + hint 的人类可读文案（errs.* 信封是扁平字段、不带结构化 detail 容器）。文案对齐
+// miaoda-cli（src/cli/handlers/db/sql.ts、src/api/db/api.ts）：
+//   - message 末尾 "(at statement N of M)" 给出失败位置；
+//   - hint 由 inferRolledBack 推断（实测后端把 BEGIN/COMMIT 也作为 statement 返回）：
+//     失败仍在用户显式事务内 → 服务端整批回滚，用 miaoda 原句 "Transaction rolled back; no changes persisted."；
+//     否则前序语句已逐条 commit、未回滚（flat 信封无逐句 breakdown，故 hint 简述前序已落地 + 从失败处续跑）。
 func sqlStatementError(stmts []map[string]interface{}, errIdx int, errStmt map[string]interface{}) error {
 	code, msg := parseErrorSentinel(common.GetString(errStmt, "data"))
 	stmtNo := errIdx + 1 // 1-based 给人看
 	fullMsg := fmt.Sprintf("%s (at statement %d of %d)", msg, stmtNo, len(stmts))
 
-	apiErr := output.ErrAPI(code, fullMsg, map[string]interface{}{
-		"statement_index": errIdx,
-		"completed":       stmts[:errIdx],
-		"rolled_back":     false,
-	})
-	if apiErr.Detail != nil {
-		if errIdx > 0 {
-			apiErr.Detail.Hint = fmt.Sprintf(
-				"statements 1-%d were already applied (DBA mode auto-commits each statement); fix statement %d and re-run only the remaining statements.",
-				errIdx, stmtNo)
-		} else {
-			apiErr.Detail.Hint = "no statements were applied; fix the SQL and re-run."
+	var hint string
+	switch {
+	case inferRolledBack(stmts[:errIdx]):
+		hint = "Transaction rolled back; no changes persisted."
+	case errIdx > 0:
+		hint = fmt.Sprintf("Earlier statements were committed and not rolled back; fix statement %d and re-run the remaining statements.", stmtNo)
+	default:
+		hint = "No statements were applied; fix the SQL and re-run."
+	}
+	return errs.NewAPIError(errs.SubtypeServerError, "%s", fullMsg).WithCode(code).WithHint("%s", hint)
+}
+
+// inferRolledBack 推断失败时是否处于用户显式事务内（→ 服务端整批回滚）。
+// 遍历已完成语句的 sql_type：BEGIN/START TRANSACTION +1，COMMIT/ROLLBACK/END -1；
+// 结束 depth>0 说明事务还开着、已被服务端回滚。对齐 miaoda-cli inferRolledBack。
+func inferRolledBack(completed []map[string]interface{}) bool {
+	depth := 0
+	for _, s := range completed {
+		switch strings.ToUpper(strings.TrimSpace(common.GetString(s, "sql_type"))) {
+		case "BEGIN", "START TRANSACTION", "START_TRANSACTION":
+			depth++
+		case "COMMIT", "ROLLBACK", "END":
+			if depth > 0 {
+				depth--
+			}
 		}
 	}
-	return apiErr
+	return depth > 0
 }
 
 // parseErrorSentinel 解析 ERROR 哨兵的 data（`{code,message}` JSON），返回数值 code 与 message。
@@ -346,10 +440,10 @@ func renderMultiStatementPretty(w io.Writer, stmts []map[string]interface{}) {
 	}
 	fmt.Fprintln(w)
 	if failedIdx >= 0 {
-		// CLI 永远 DBA 模式（transactional=false），失败语句之前的语句已 auto-commit 落地，
-		// 不存在整批回滚 —— 如实告诉用户，避免整批重跑导致重复写入。
+		// CLI 永远传 transactional=false，失败语句之前的语句已逐条 commit 落地、不会整批回滚——
+		// 如实告诉用户，避免整批重跑导致重复写入。
 		if successCount > 0 {
-			fmt.Fprintf(w, "(statement %d failed; %d statement%s before it already applied — DBA mode auto-commits each)\n",
+			fmt.Fprintf(w, "(statement %d failed; %d statement%s before it committed and not rolled back)\n",
 				failedIdx+1, successCount, plural(int64(successCount)))
 		} else {
 			fmt.Fprintf(w, "(statement %d failed; no statements applied)\n", failedIdx+1)
@@ -453,6 +547,7 @@ func isDMLType(sqlType string) bool {
 	return false
 }
 
+// dmlVerb 把 DML sql_type 映射成过去分词动词：INSERT→inserted / UPDATE→updated / DELETE→deleted / MERGE→merged，未知 → affected。
 func dmlVerb(sqlType string) string {
 	switch strings.ToUpper(sqlType) {
 	case "INSERT":
@@ -467,6 +562,7 @@ func dmlVerb(sqlType string) string {
 	return "affected"
 }
 
+// plural 返回英文复数后缀：n==1 时空串，否则 "s"。
 func plural(n int64) string {
 	if n == 1 {
 		return ""

shortcuts/apps/apps_db_execute_test.go

@@ -5,17 +5,18 @@ package apps
 
 import (
 	"encoding/json"
-	"errors"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
 )
 
-func TestAppsDBExecute_SingleSELECTJSONEnvelopeWrapsResults(t *testing.T) {
+// TestAppsDBExecute_SingleSELECTJSONIsRowArray 断言单条 SELECT 的 JSON data 直接是行数组（不再透传 result 字符串）。
+func TestAppsDBExecute_SingleSELECTJSONIsRowArray(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
 	reg.Register(&httpmock.Stub{
 		Method: "POST",
@@ -33,23 +34,130 @@ func TestAppsDBExecute_SingleSELECTJSONEnvelopeWrapsResults(t *testing.T) {
 		factory, stdout); err != nil {
 		t.Fatalf("execute err=%v", err)
 	}
-	// JSON envelope 应该把 result 字符串 parse 之后放进 data.results
+	// PRD 单 SELECT：data 直接是行数组（不再是 data.results[].data 字符串）
 	var env struct {
-		Data struct {
-			Results []map[string]interface{} `json:"results"`
-		} `json:"data"`
+		Data []map[string]interface{} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
 		t.Fatalf("decode envelope: %v\n%s", err, stdout.String())
 	}
-	if len(env.Data.Results) != 1 {
-		t.Fatalf("data.results = %d items (want 1)", len(env.Data.Results))
+	if len(env.Data) != 1 {
+		t.Fatalf("data = %d rows (want 1)\n%s", len(env.Data), stdout.String())
 	}
-	if env.Data.Results[0]["sql_type"] != "SELECT" {
-		t.Fatalf("results[0].sql_type = %v", env.Data.Results[0]["sql_type"])
+	if env.Data[0]["id"] != float64(101) || env.Data[0]["total_cents"] != float64(2500) {
+		t.Fatalf("data[0] = %v, want {id:101,total_cents:2500}", env.Data[0])
 	}
 }
 
+// TestAppsDBExecute_SingleDMLJSONShape 断言单条 DML 的 JSON data 形如 {command, rows_affected}。
+func TestAppsDBExecute_SingleDMLJSONShape(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[{"sql_type":"INSERT","data":"","affected_rows":3}]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "insert", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	// PRD 单 DML：data = {command, rows_affected}
+	var env struct {
+		Data struct {
+			Command      string `json:"command"`
+			RowsAffected int    `json:"rows_affected"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("decode: %v\n%s", err, stdout.String())
+	}
+	if env.Data.Command != "INSERT" || env.Data.RowsAffected != 3 {
+		t.Fatalf("data = %+v, want {command:INSERT, rows_affected:3}", env.Data)
+	}
+}
+
+// TestAppsDBExecute_SingleDDLJSONShape 断言单条 DDL 的 JSON data 形如 {command}。
+func TestAppsDBExecute_SingleDDLJSONShape(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[{"sql_type":"CREATE_TABLE","data":"[]"}]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "create", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	// PRD 单 DDL：data = {command}
+	var env struct {
+		Data struct {
+			Command string `json:"command"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("decode: %v\n%s", err, stdout.String())
+	}
+	if env.Data.Command != "CREATE_TABLE" {
+		t.Fatalf("data.command = %q, want CREATE_TABLE", env.Data.Command)
+	}
+}
+
+// TestAppsDBExecute_MultiStatementJSONShape 断言多语句的 JSON data 是元素数组，且 SELECT 包成 {command:"SELECT", rows:[...]}。
+func TestAppsDBExecute_MultiStatementJSONShape(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[` +
+					`{"sql_type":"INSERT","data":"","affected_rows":1},` +
+					`{"sql_type":"SELECT","data":"[{\"id\":999}]","record_count":1}` +
+					`]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "x", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	// PRD 多语句：data 是元素数组；SELECT 包成 {command:"SELECT", rows:[...]}
+	var env struct {
+		Data []map[string]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("decode: %v\n%s", err, stdout.String())
+	}
+	if len(env.Data) != 2 {
+		t.Fatalf("data = %d elements (want 2)\n%s", len(env.Data), stdout.String())
+	}
+	if env.Data[0]["command"] != "INSERT" || env.Data[0]["rows_affected"] != float64(1) {
+		t.Fatalf("data[0] = %v, want {command:INSERT, rows_affected:1}", env.Data[0])
+	}
+	if env.Data[1]["command"] != "SELECT" {
+		t.Fatalf("data[1].command = %v, want SELECT", env.Data[1]["command"])
+	}
+	rows, ok := env.Data[1]["rows"].([]interface{})
+	if !ok || len(rows) != 1 {
+		t.Fatalf("data[1].rows = %v, want 1 row", env.Data[1]["rows"])
+	}
+}
+
+// TestAppsDBExecute_DryRunSendsTransactionalFalse 断言 dry-run 发出的请求是 POST、params 带 transactional=false（DBA 模式）且 transactional 不在 body 里。
 func TestAppsDBExecute_DryRunSendsTransactionalFalse(t *testing.T) {
 	factory, stdout, _ := newAppsExecuteFactory(t)
 	if err := runAppsShortcut(t, AppsDBExecute,
@@ -85,6 +193,7 @@ func TestAppsDBExecute_DryRunSendsTransactionalFalse(t *testing.T) {
 	}
 }
 
+// TestAppsDBExecute_RejectsEmptySQL 断言 --sql 全空白时校验报错（提示需要 --sql 或 --file）。
 func TestAppsDBExecute_RejectsEmptySQL(t *testing.T) {
 	factory, stdout, _ := newAppsExecuteFactory(t)
 	err := runAppsShortcut(t, AppsDBExecute,
@@ -147,6 +256,7 @@ func TestAppsDBExecute_FileReadsSQLIntoBody(t *testing.T) {
 // 输入用 BOE 真实抓包数据（test_scripts/boe_e2e/run.log）。
 // ============================================================================
 
+// TestAppsDBExecute_LegacyWireSingleSelect 断言 legacy 字符串数组 wire 的单 SELECT 能正常渲染表格、不回退到 RAW。
 func TestAppsDBExecute_LegacyWireSingleSelect(t *testing.T) {
 	// BOE 实测：SELECT 1 AS x  →  result: "[\"[{\\\"x\\\":1}]\"]"
 	factory, stdout, reg := newAppsExecuteFactory(t)
@@ -178,8 +288,9 @@ func TestAppsDBExecute_LegacyWireSingleSelect(t *testing.T) {
 	}
 }
 
-func TestAppsDBExecute_LegacyWireSingleSelectJSONEnvelope(t *testing.T) {
-	// 验证 JSON envelope 也把 legacy result 正确归一化进 data.results
+// TestAppsDBExecute_LegacyWireSingleSelectJSONIsRowArray 断言 legacy wire 的 SELECT 同样归一化成 PRD 行数组形态。
+func TestAppsDBExecute_LegacyWireSingleSelectJSONIsRowArray(t *testing.T) {
+	// 验证 legacy wire 的 SELECT 也归一化成 PRD 行数组形态（data 直接是行）
 	factory, stdout, reg := newAppsExecuteFactory(t)
 	reg.Register(&httpmock.Stub{
 		Method: "POST",
@@ -197,24 +308,20 @@ func TestAppsDBExecute_LegacyWireSingleSelectJSONEnvelope(t *testing.T) {
 		t.Fatalf("execute err=%v", err)
 	}
 	var env struct {
-		Data struct {
-			Results []map[string]interface{} `json:"results"`
-		} `json:"data"`
+		Data []map[string]interface{} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
 		t.Fatalf("decode: %v\n%s", err, stdout.String())
 	}
-	if len(env.Data.Results) != 1 {
-		t.Fatalf("results length = %d, want 1; got: %v", len(env.Data.Results), env.Data.Results)
+	if len(env.Data) != 1 {
+		t.Fatalf("data length = %d, want 1; got: %v", len(env.Data), env.Data)
 	}
-	if env.Data.Results[0]["sql_type"] != "SELECT" {
-		t.Fatalf("results[0].sql_type = %v, want SELECT", env.Data.Results[0]["sql_type"])
-	}
-	if env.Data.Results[0]["record_count"] != float64(1) {
-		t.Fatalf("results[0].record_count = %v, want 1", env.Data.Results[0]["record_count"])
+	if env.Data[0]["x"] != float64(1) {
+		t.Fatalf("data[0].x = %v, want 1", env.Data[0]["x"])
 	}
 }
 
+// TestAppsDBExecute_LegacyWireMultiSelect 断言 legacy wire 多 SELECT 输出带 Statement N header 与末尾 "✓ N statements executed" 汇总。
 func TestAppsDBExecute_LegacyWireMultiSelect(t *testing.T) {
 	// BOE 实测：SELECT 1; SELECT 2  →  result: "[\"[{\\\"?column?\\\":1}]\",\"[{\\\"?column?\\\":2}]\"]"
 	factory, stdout, reg := newAppsExecuteFactory(t)
@@ -244,6 +351,7 @@ func TestAppsDBExecute_LegacyWireMultiSelect(t *testing.T) {
 	}
 }
 
+// TestAppsDBExecute_LegacyWireDDLEmptyResult 断言 result 为空字符串时（legacy DDL）pretty 输出 "(empty result)"。
 func TestAppsDBExecute_LegacyWireDDLEmptyResult(t *testing.T) {
 	// BOE 实测：CREATE TABLE  →  result: "" （空字符串，无 rows）
 	// 老 wire 不区分 DDL/DML/无返回，统一标 "ok"
@@ -270,6 +378,7 @@ func TestAppsDBExecute_LegacyWireDDLEmptyResult(t *testing.T) {
 	}
 }
 
+// TestAppsDBExecute_LegacyWireMultiSelectWithRealTable 断言含 CJK / uuid / int 字段的真实表行能正确显示在 pretty 表格里。
 func TestAppsDBExecute_LegacyWireMultiSelectWithRealTable(t *testing.T) {
 	// BOE 实测真实表抓包（course 表第一行）：复杂 JSON 含 CJK / timestamp / uuid 字段
 	factory, stdout, reg := newAppsExecuteFactory(t)
@@ -328,6 +437,7 @@ func TestAppsDBExecute_PrettySingleSelectTable(t *testing.T) {
 	}
 }
 
+// TestAppsDBExecute_PrettyEmptySelect 断言空 SELECT 的 pretty 输出为 "(0 rows)"。
 func TestAppsDBExecute_PrettyEmptySelect(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
 	reg.Register(&httpmock.Stub{
@@ -350,6 +460,7 @@ func TestAppsDBExecute_PrettyEmptySelect(t *testing.T) {
 	}
 }
 
+// TestAppsDBExecute_PrettySingleDMLAndDDL 断言单条 DML 渲染 "✓ N row(s) <verb>"、各类 DDL（含细粒度动词）渲染 "✓ DDL executed"。
 func TestAppsDBExecute_PrettySingleDMLAndDDL(t *testing.T) {
 	cases := []struct {
 		name    string
@@ -386,6 +497,7 @@ func TestAppsDBExecute_PrettySingleDMLAndDDL(t *testing.T) {
 	}
 }
 
+// TestAppsDBExecute_PrettyMultiStatementsAllSuccess 断言多语句全成功时逐条 Statement 摘要 + 末尾 "✓ N statements executed"。
 func TestAppsDBExecute_PrettyMultiStatementsAllSuccess(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
 	reg.Register(&httpmock.Stub{
@@ -455,6 +567,7 @@ func TestAppsDBExecute_PrettyMultiStatementsDDL(t *testing.T) {
 	}
 }
 
+// TestAppsDBExecute_PrettyMultiStatementsPartialFailureWithErrorSentinel 断言多语句部分失败时 pretty 仍打逐条 ✓/✗ 摘要、声明前序已 commit 未回滚，且返回 typed error、不打成功汇总。
 func TestAppsDBExecute_PrettyMultiStatementsPartialFailureWithErrorSentinel(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
 	reg.Register(&httpmock.Stub{
@@ -486,19 +599,20 @@ func TestAppsDBExecute_PrettyMultiStatementsPartialFailureWithErrorSentinel(t *t
 			t.Errorf("missing %q in pretty output\nfull:\n%s", line, got)
 		}
 	}
-	// DBA 模式（transactional=false）前序语句已 auto-commit 落地，绝不能误报「rolled back」。
-	if strings.Contains(got, "rolled back") {
-		t.Errorf("DBA mode must NOT claim rollback (prior statements persisted); got:\n%s", got)
+	// 非事务（transactional=false）前序语句已逐条 commit 落地，须如实说明「committed and not rolled back」，
+	// 绝不能误报整批回滚。
+	if !strings.Contains(got, "committed and not rolled back") {
+		t.Errorf("non-tx failure must state prior statements committed & not rolled back; got:\n%s", got)
 	}
 	if strings.Contains(got, "statements executed") {
 		t.Errorf("failed run should NOT print success summary; got:\n%s", got)
 	}
 }
 
-// TestAppsDBExecute_MultiStatementFailureReturnsTypedError 钉死「多语句失败 → typed api_error」：
-// json 默认不再打 ok:true 假成功，而是返回 *output.ExitError（type=api_error、非零 exit），
-// detail 带 statement_index / completed / rolled_back。rolled_back=false 因 CLI 永远 DBA 模式
-// （真机 boe 实证：失败前的语句已落地）。
+// TestAppsDBExecute_MultiStatementFailureReturnsTypedError 钉死「多语句失败 → typed errs.APIError」：
+// json 默认不再打 ok:true 假成功，而是返回 typed errs.* 错误（type=api / subtype=server_error、
+// exit=1）。失败位置在 message 的 "(at statement N of M)"，前序是否落地/是否回滚写在 hint。
+// 本例无 BEGIN → 前序逐条 commit、未回滚（hint 含 "committed and not rolled back"）。
 func TestAppsDBExecute_MultiStatementFailureReturnsTypedError(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
 	reg.Register(&httpmock.Stub{
@@ -524,35 +638,26 @@ func TestAppsDBExecute_MultiStatementFailureReturnsTypedError(t *testing.T) {
 	if strings.Contains(stdout.String(), `"ok": true`) {
 		t.Errorf("must not emit ok:true success envelope on failure; stdout:\n%s", stdout.String())
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("want *output.ExitError with detail, got %T: %v", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("want a typed errs.* error, got %T: %v", err, err)
 	}
-	if exitErr.Detail.Type != "api_error" {
-		t.Errorf("error.type = %q, want api_error", exitErr.Detail.Type)
+	if p.Category != errs.CategoryAPI || p.Subtype != errs.SubtypeServerError {
+		t.Errorf("category/subtype = %s/%s, want api/server_error", p.Category, p.Subtype)
 	}
-	if exitErr.Detail.Code != 1300002 {
-		t.Errorf("error.code = %d, want 1300002", exitErr.Detail.Code)
+	if p.Code != 1300002 {
+		t.Errorf("code = %d, want 1300002", p.Code)
 	}
-	if !strings.Contains(exitErr.Detail.Message, "(at statement 2 of 2)") {
-		t.Errorf("error.message missing statement locator: %q", exitErr.Detail.Message)
+	if !strings.Contains(p.Message, "(at statement 2 of 2)") {
+		t.Errorf("message missing statement locator: %q", p.Message)
+	}
+	// 无 BEGIN → 前序逐条 commit、未回滚，语义写在 hint。
+	if !strings.Contains(p.Hint, "committed and not rolled back") {
+		t.Errorf("hint should state prior statements committed & not rolled back: %q", p.Hint)
 	}
 	if output.ExitCodeOf(err) != output.ExitAPI {
 		t.Errorf("exit = %d, want %d (ExitAPI)", output.ExitCodeOf(err), output.ExitAPI)
 	}
-	detail, ok := exitErr.Detail.Detail.(map[string]interface{})
-	if !ok {
-		t.Fatalf("error.detail not a map: %T", exitErr.Detail.Detail)
-	}
-	if detail["statement_index"] != 1 {
-		t.Errorf("statement_index = %v, want 1", detail["statement_index"])
-	}
-	if detail["rolled_back"] != false {
-		t.Errorf("rolled_back = %v, want false (DBA mode persists prior statements)", detail["rolled_back"])
-	}
-	if completed, ok := detail["completed"].([]map[string]interface{}); !ok || len(completed) != 1 {
-		t.Errorf("completed = %v, want 1 persisted statement", detail["completed"])
-	}
 }
 
 // TestAppsDBExecute_SingleErrorReturnsTypedError 单条语句失败（server 也返 code:0 + ERROR 哨兵）
@@ -575,22 +680,90 @@ func TestAppsDBExecute_SingleErrorReturnsTypedError(t *testing.T) {
 	if err == nil {
 		t.Fatalf("single ERROR sentinel must return a typed error; stdout:\n%s", stdout.String())
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("want *output.ExitError with detail, got %T: %v", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("want a typed errs.* error, got %T: %v", err, err)
 	}
-	if !strings.Contains(exitErr.Detail.Message, "(at statement 1 of 1)") {
-		t.Errorf("error.message missing locator: %q", exitErr.Detail.Message)
+	if p.Category != errs.CategoryAPI || p.Subtype != errs.SubtypeServerError {
+		t.Errorf("category/subtype = %s/%s, want api/server_error", p.Category, p.Subtype)
 	}
-	detail, _ := exitErr.Detail.Detail.(map[string]interface{})
-	if detail["statement_index"] != 0 {
-		t.Errorf("statement_index = %v, want 0", detail["statement_index"])
+	if !strings.Contains(p.Message, "(at statement 1 of 1)") {
+		t.Errorf("message missing locator: %q", p.Message)
 	}
-	if completed, ok := detail["completed"].([]map[string]interface{}); !ok || len(completed) != 0 {
-		t.Errorf("completed = %v, want empty", detail["completed"])
+	// 第一条就失败、无落地 的语义写在 hint。
+	if !strings.Contains(p.Hint, "No statements were applied") {
+		t.Errorf("hint should state nothing applied: %q", p.Hint)
 	}
 }
 
+// TestAppsDBExecute_TransactionFailureRolledBack 钉死「显式事务内失败 → 整批回滚」：
+// 实测后端把 BEGIN 也作为 statement 返回；completed 含未配对 BEGIN → inferRolledBack 判定回滚。
+// 回滚语义现写在 hint（miaoda 原句 "Transaction rolled back; no changes persisted."），失败位置在 message。
+func TestAppsDBExecute_TransactionFailureRolledBack(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				// BOE 实测 wire：BEGIN; CREATE; INSERT(ok); INSERT(dup→ERROR)
+				"result": `[` +
+					`{"sql_type":"BEGIN","data":"[]"},` +
+					`{"sql_type":"CREATE_TABLE","data":"[]"},` +
+					`{"sql_type":"INSERT","data":"[{\"rowCount\":1}]","affected_rows":1},` +
+					`{"sql_type":"ERROR","data":"{\"code\":\"k_dl_1300002\",\"message\":\"duplicate key value violates unique constraint\"}"}` +
+					`]`,
+			},
+		},
+	})
+	err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "x", "--as", "user"},
+		factory, stdout)
+	if err == nil {
+		t.Fatalf("transaction failure must return a typed error; stdout:\n%s", stdout.String())
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("want a typed errs.* error, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryAPI || p.Subtype != errs.SubtypeServerError {
+		t.Errorf("category/subtype = %s/%s, want api/server_error", p.Category, p.Subtype)
+	}
+	if !strings.Contains(p.Message, "(at statement 4 of 4)") {
+		t.Errorf("message missing statement locator: %q", p.Message)
+	}
+	// 事务整批回滚 / 前序未落库 的语义写在 hint（miaoda 原句）。
+	if !strings.Contains(p.Hint, "Transaction rolled back; no changes persisted.") {
+		t.Errorf("hint should state transaction rolled back & nothing persisted: %q", p.Hint)
+	}
+}
+
+// TestInferRolledBack_Cases 断言 inferRolledBack 按 BEGIN/COMMIT/ROLLBACK 计数判定失败时事务是否仍开着（即整批回滚）。
+func TestInferRolledBack_Cases(t *testing.T) {
+	stmt := func(t string) map[string]interface{} { return map[string]interface{}{"sql_type": t} }
+	cases := []struct {
+		name      string
+		completed []map[string]interface{}
+		want      bool
+	}{
+		{"empty", nil, false},
+		{"autocommit single", []map[string]interface{}{stmt("INSERT")}, false},
+		{"open tx (unmatched BEGIN)", []map[string]interface{}{stmt("BEGIN"), stmt("CREATE_TABLE"), stmt("INSERT")}, true},
+		{"closed tx (BEGIN+COMMIT)", []map[string]interface{}{stmt("BEGIN"), stmt("INSERT"), stmt("COMMIT")}, false},
+		{"reopened tx", []map[string]interface{}{stmt("BEGIN"), stmt("COMMIT"), stmt("BEGIN"), stmt("INSERT")}, true},
+		{"rollback closes tx", []map[string]interface{}{stmt("BEGIN"), stmt("INSERT"), stmt("ROLLBACK")}, false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := inferRolledBack(c.completed); got != c.want {
+				t.Errorf("inferRolledBack(%s) = %v, want %v", c.name, got, c.want)
+			}
+		})
+	}
+}
+
+// TestCellString_AllKinds 断言 cellString 对 nil/string/bool/整数/小数/对象各类型的字符串化结果。
 func TestCellString_AllKinds(t *testing.T) {
 	cases := []struct {
 		name string
@@ -614,6 +787,7 @@ func TestCellString_AllKinds(t *testing.T) {
 	}
 }
 
+// TestCodeString_Forms 断言 codeString 处理 nil / "k_dl_xxx" / 纯数字串 / float64 / 不支持类型各形态。
 func TestCodeString_Forms(t *testing.T) {
 	cases := []struct {
 		name string
@@ -635,6 +809,7 @@ func TestCodeString_Forms(t *testing.T) {
 	}
 }
 
+// TestDmlVerb_AllVerbs 断言 dmlVerb 对 INSERT/UPDATE/DELETE/MERGE 的动词映射（大小写不敏感），非 DML 返回 affected。
 func TestDmlVerb_AllVerbs(t *testing.T) {
 	cases := map[string]string{
 		"INSERT":       "inserted",
@@ -650,6 +825,7 @@ func TestDmlVerb_AllVerbs(t *testing.T) {
 	}
 }
 
+// TestIntOrZero_Cases 断言 intOrZero 对 JSON number 取整、对非数字 / nil 返回 0。
 func TestIntOrZero_Cases(t *testing.T) {
 	if got := intOrZero(float64(5)); got != 5 {
 		t.Errorf("intOrZero(5)=%d want 5", got)
@@ -662,6 +838,7 @@ func TestIntOrZero_Cases(t *testing.T) {
 	}
 }
 
+// TestErrorSummary_Cases 断言 errorSummary 对空 / 非法 JSON / 带 code / 无 code 各情形生成 "message [code]" 文案。
 func TestErrorSummary_Cases(t *testing.T) {
 	cases := []struct {
 		name, in, want string
@@ -680,6 +857,7 @@ func TestErrorSummary_Cases(t *testing.T) {
 	}
 }
 
+// TestParseErrorSentinel_Cases 断言 parseErrorSentinel 解析 ERROR 哨兵 data 得到数值 code 与 message（含空 / 非法 / 空 message 回退）。
 func TestParseErrorSentinel_Cases(t *testing.T) {
 	cases := []struct {
 		name, in string
@@ -701,6 +879,7 @@ func TestParseErrorSentinel_Cases(t *testing.T) {
 	}
 }
 
+// TestIsStructuredResult_Cases 断言 isStructuredResult 仅在首元素含 sql_type 时判为新结构化形态。
 func TestIsStructuredResult_Cases(t *testing.T) {
 	if !isStructuredResult([]map[string]interface{}{{"sql_type": "SELECT"}}) {
 		t.Error("expected structured=true when sql_type present")
@@ -713,6 +892,7 @@ func TestIsStructuredResult_Cases(t *testing.T) {
 	}
 }
 
+// TestNormalizeLegacyStatement_Cases 断言 normalizeLegacyStatement 把空 / null / 非 JSON 标为 OK、把 rows 数组标为 SELECT 并带 record_count。
 func TestNormalizeLegacyStatement_Cases(t *testing.T) {
 	t.Run("empty -> OK", func(t *testing.T) {
 		got := normalizeLegacyStatement("")
@@ -743,6 +923,7 @@ func TestNormalizeLegacyStatement_Cases(t *testing.T) {
 	})
 }
 
+// TestCellString_MarshalFallback 断言 cellString 对 json.Marshal 拒绝的类型（如 complex）回退到 fmt %v。
 func TestCellString_MarshalFallback(t *testing.T) {
 	// complex128 is not switch-handled and json.Marshal rejects it →
 	// falls back to fmt.Sprintf("%v", v), which is deterministic for complex.
@@ -751,6 +932,7 @@ func TestCellString_MarshalFallback(t *testing.T) {
 	}
 }
 
+// TestRenderSingleStatementPretty_Branches 断言 renderSingleStatementPretty 对 SELECT/ERROR/DML/legacy OK/DDL 各分支的输出。
 func TestRenderSingleStatementPretty_Branches(t *testing.T) {
 	cases := []struct {
 		name   string
@@ -774,6 +956,7 @@ func TestRenderSingleStatementPretty_Branches(t *testing.T) {
 	}
 }
 
+// TestRenderSelectRowsAsTable_Branches 断言 renderSelectRowsAsTable 对空串 / 空数组 / 非法 JSON 回退 / 正常 rows 各分支的输出。
 func TestRenderSelectRowsAsTable_Branches(t *testing.T) {
 	cases := []struct {
 		name   string

shortcuts/apps/apps_db_quota_get.go

@@ -0,0 +1,100 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsDBQuotaGet reports an app's database storage usage and object counts.
+//
+// GET /apps/{app_id}/db/quota。storage_quota_bytes / usage_percent 在配额未对接（=0）时
+// 不输出（与 +file-quota-get 一致）；tables / views 始终输出。
+var AppsDBQuotaGet = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-quota-get",
+	Description: "Get an app's database storage usage",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +db-quota-get --app-id <app_id>",
+		"Example: lark-cli apps +db-quota-get --app-id <app_id> --env dev",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appDbQuotaPath(appID)).
+			Desc("Get Miaoda app database storage usage").
+			Params(map[string]interface{}{"env": rctx.Str("env")})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("GET", appDbQuotaPath(appID), map[string]interface{}{"env": rctx.Str("env")}, nil)
+		if err != nil {
+			return withAppsHint(err, appIDListHint)
+		}
+		out := projectDbQuota(data)
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderDbQuotaPretty(w, out)
+		})
+		return nil
+	},
+}
+
+// projectDbQuota 白名单投影 db quota 字段：只保留 storage_used_bytes / tables / views，
+// 配额已对接时再加 storage_quota_bytes / usage_percent。不透传后端其它字段，避免无用字段消耗上下文。
+func projectDbQuota(data map[string]interface{}) map[string]interface{} {
+	out := map[string]interface{}{"storage_used_bytes": data["storage_used_bytes"]}
+	for _, k := range []string{"tables", "views"} {
+		if v, ok := data[k]; ok {
+			out[k] = v
+		}
+	}
+	// 配额未对接（storage_quota_bytes=0/缺失）时不输出 quota / usage_percent。
+	if q, ok := numericAsFloat(data["storage_quota_bytes"]); ok && q > 0 {
+		out["storage_quota_bytes"] = data["storage_quota_bytes"]
+		if v, ok := data["usage_percent"]; ok {
+			out["usage_percent"] = v
+		}
+	}
+	return out
+}
+
+// renderDbQuotaPretty 打 Storage（已用 / 配额 (百分比)）与 Tables / Views 行（标签对齐 miaoda-cli）。
+func renderDbQuotaPretty(w io.Writer, data map[string]interface{}) {
+	used := humanBytes(data["storage_used_bytes"])
+	usage := used
+	if q, ok := numericAsFloat(data["storage_quota_bytes"]); ok && q > 0 {
+		pct := ""
+		if p, ok := numericAsFloat(data["usage_percent"]); ok {
+			pct = fmt.Sprintf(" (%.1f%%)", p)
+		}
+		usage = fmt.Sprintf("%s / %s%s", used, humanBytes(data["storage_quota_bytes"]), pct)
+	}
+	pairs := [][2]string{{"Storage", usage}}
+	if f, ok := numericAsFloat(data["tables"]); ok {
+		pairs = append(pairs, [2]string{"Tables", fmt.Sprintf("%d", int64(f))})
+	}
+	if f, ok := numericAsFloat(data["views"]); ok {
+		pairs = append(pairs, [2]string{"Views", fmt.Sprintf("%d", int64(f))})
+	}
+	renderKeyValuePairs(w, pairs)
+}

shortcuts/apps/apps_db_recovery.go

@@ -0,0 +1,267 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const dbRecoveryHint = "PITR window is up to 7 days back, limited by your last `+db-env-migrate`; pass --target as a time (e.g. 2h / 2026-04-15 / 2026-04-15T10:00:00Z)"
+
+// AppsDBRecoveryDiff 预览把数据库恢复到某个时间点会带来的变更（PITR diff，不落地）。
+//
+// POST /apps/{app_id}/db/env_recovery，body {target, dry_run:true} → preview_request_id，
+// 轮询 env_recovery_diff_status 至终态，返回受影响表与行数变化。预览也需 spark:app:write scope。
+var AppsDBRecoveryDiff = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-recovery-diff",
+	Description: "Preview restoring the database to a point in time (PITR diff)",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +db-recovery-diff --app-id <app_id> --target 2h",
+		"Apply with +db-recovery-apply --target <same> --yes.",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "target", Desc: "point in time to restore to; relative (2h/3d) | date | datetime | ISO 8601 w/ TZ", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		return normalizeTimeFlags(rctx, "target")
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().POST(appRecoveryPath(appID)).Desc("Preview PITR recovery").
+			Body(map[string]interface{}{"target": rctx.Str("target"), "dry_run": true})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		target := rctx.Str("target")
+		preview, err := runRecoveryPreview(rctx, appID, target)
+		if err != nil {
+			return err
+		}
+		out := recoveryDiffOutput(target, preview)
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderRecoveryDiff(w, target, out)
+		})
+		return nil
+	},
+}
+
+// AppsDBRecoveryApply 把数据库恢复到某个时间点（覆盖当前数据，异步，CLI 轮询至完成）。
+//
+// POST /apps/{app_id}/db/env_recovery，body {target, dry_run:false}；目标=当前态时短路 no_changes，
+// 否则轮询 env_recovery_apply_status 至 success。high-risk-write。
+var AppsDBRecoveryApply = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-recovery-apply",
+	Description: "Restore the database to a point in time (overwrites current data, irreversible)",
+	Risk:        "high-risk-write",
+	Tips: []string{
+		"Example: lark-cli apps +db-recovery-apply --app-id <app_id> --target 2026-04-15T10:00:00Z --yes",
+		"Preview first with +db-recovery-diff.",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "target", Desc: "point in time to restore to; relative (2h/3d) | date | datetime | ISO 8601 w/ TZ", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		return normalizeTimeFlags(rctx, "target")
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().POST(appRecoveryPath(appID)).Desc("Apply PITR recovery").
+			Body(map[string]interface{}{"target": rctx.Str("target"), "dry_run": false})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		target := rctx.Str("target")
+		stop := rctx.StartSpinner("Restoring database (target: " + target + ")")
+		defer stop()
+		submit, err := rctx.CallAPITyped("POST", appRecoveryPath(appID), nil, map[string]interface{}{"target": target, "dry_run": false})
+		if err != nil {
+			return withAppsHint(err, dbRecoveryHint)
+		}
+		// 目标=当前态 → 后端短路 no_changes，不轮询。
+		if strings.ToLower(common.GetString(submit, "status")) == "no_changes" {
+			stop()
+			out := map[string]interface{}{"status": "no_changes", "target": target}
+			rctx.OutFormat(out, nil, func(w io.Writer) {
+				io.WriteString(w, "No changes — database is already at this state.\n")
+			})
+			return nil
+		}
+		final, perr := pollUntil(rctx.Ctx(), 2*time.Second, 30*time.Minute,
+			func() (map[string]interface{}, error) {
+				return rctx.CallAPITyped("GET", appRecoveryApplyStatusPath(appID), nil, nil)
+			},
+			func(d map[string]interface{}) (bool, error) {
+				switch strings.ToLower(common.GetString(d, "status")) {
+				case "success", "restored", "ready":
+					return true, nil
+				case "failed":
+					msg := common.GetString(d, "error_message")
+					if msg == "" {
+						msg = fmt.Sprintf("recovery to %s failed", target)
+					}
+					return false, withAppsHint(errs.NewAPIError(errs.SubtypeServerError, "%s", msg), dbRecoveryHint)
+				}
+				return false, nil
+			})
+		if perr != nil {
+			return perr
+		}
+		stop()
+		out := map[string]interface{}{"status": "restored", "target": target}
+		if n := intFromAny(final["restore_time_sec"]); n > 0 {
+			out["restore_time_sec"] = n
+		}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			if n, ok := out["restore_time_sec"].(int); ok {
+				fmt.Fprintf(w, "✓ Database restored to %s (%ds elapsed)\n", target, n)
+			} else {
+				fmt.Fprintf(w, "✓ Database restored to %s\n", target)
+			}
+		})
+		return nil
+	},
+}
+
+// runRecoveryPreview 触发 PITR 预览（dry_run=true）拿 preview_request_id，轮询 diff_status 至终态。
+func runRecoveryPreview(rctx *common.RuntimeContext, appID, target string) (map[string]interface{}, error) {
+	stop := rctx.StartSpinner("Previewing recovery impact (target: " + target + ")")
+	defer stop()
+	submit, err := rctx.CallAPITyped("POST", appRecoveryPath(appID), nil, map[string]interface{}{"target": target, "dry_run": true})
+	if err != nil {
+		return nil, withAppsHint(err, dbRecoveryHint)
+	}
+	prid := common.GetString(submit, "preview_request_id")
+	if prid == "" {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "recovery diff did not return preview_request_id")
+	}
+	return pollUntil(rctx.Ctx(), 1*time.Second, 10*time.Minute,
+		func() (map[string]interface{}, error) {
+			return rctx.CallAPITyped("GET", appRecoveryDiffStatusPath(appID), map[string]interface{}{"preview_request_id": prid}, nil)
+		},
+		func(d map[string]interface{}) (bool, error) {
+			switch strings.ToLower(common.GetString(d, "preview_status")) {
+			case "success":
+				return true, nil
+			case "failed":
+				msg := common.GetString(d, "error_message")
+				if msg == "" {
+					msg = "recovery preview failed"
+				}
+				return false, withAppsHint(errs.NewAPIError(errs.SubtypeServerError, "%s", msg), dbRecoveryHint)
+			}
+			return false, nil
+		})
+}
+
+type recoveryChange struct {
+	Table     string      `json:"table"`
+	Inserted  interface{} `json:"inserted,omitempty"`
+	Deleted   interface{} `json:"deleted,omitempty"`
+	Action    string      `json:"action,omitempty"`
+	DroppedAt string      `json:"dropped_at,omitempty"`
+}
+
+// recoveryDiffOutput 组装 diff 输出：target / tables_affected / changes[] / estimated_seconds。
+func recoveryDiffOutput(target string, preview map[string]interface{}) map[string]interface{} {
+	arr, _ := preview["changes"].([]interface{})
+	changes := make([]recoveryChange, 0, len(arr))
+	for _, it := range arr {
+		m, ok := it.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		changes = append(changes, recoveryChange{
+			Table:     common.GetString(m, "table"),
+			Inserted:  m["inserted"],
+			Deleted:   m["deleted"],
+			Action:    common.GetString(m, "action"),
+			DroppedAt: common.GetString(m, "dropped_at"),
+		})
+	}
+	tablesAffected := intFromAny(preview["tables_affected"])
+	if tablesAffected == 0 {
+		tablesAffected = len(changes)
+	}
+	est := intFromAny(preview["estimated_seconds"])
+	if est == 0 {
+		est = 30 // PRD 兜底
+	}
+	return map[string]interface{}{
+		"target": target, "tables_affected": tablesAffected,
+		"changes": changes, "estimated_seconds": est,
+	}
+}
+
+// renderRecoveryDiff 渲染 PITR 恢复预览：受影响表数、逐表变化描述及预估耗时；无变更打提示。
+func renderRecoveryDiff(w io.Writer, target string, out map[string]interface{}) {
+	changes, _ := out["changes"].([]recoveryChange)
+	if len(changes) == 0 {
+		io.WriteString(w, "No changes — database is already at this state.\n")
+		return
+	}
+	fmt.Fprintf(w, "Recovery preview (→ %s):\n\n", target)
+	fmt.Fprintf(w, "  tables affected: %d\n", intFromAny(out["tables_affected"]))
+	for _, c := range changes {
+		fmt.Fprintf(w, "  %s: %s\n", c.Table, describeRecoveryChange(c))
+	}
+	fmt.Fprintf(w, "\n  estimated time: ~%ds\n", intFromAny(out["estimated_seconds"]))
+}
+
+// describeRecoveryChange：schema 动作 或 数据行变化二选一（无 modified，对齐设计）。
+func describeRecoveryChange(c recoveryChange) string {
+	switch c.Action {
+	case "restore_table":
+		return "table will be restored"
+	case "drop_table":
+		return "table will be dropped"
+	case "alter_table":
+		return "table will be altered"
+	case "unavailable":
+		if c.DroppedAt != "" {
+			return "diff unavailable: " + c.DroppedAt
+		}
+		return "diff unavailable"
+	}
+	parts := make([]string, 0, 2)
+	if n := intFromAny(c.Inserted); n != 0 {
+		parts = append(parts, fmt.Sprintf("+%d rows", n))
+	}
+	if n := intFromAny(c.Deleted); n != 0 {
+		parts = append(parts, fmt.Sprintf("-%d rows", n))
+	}
+	if len(parts) == 0 {
+		return "no changes"
+	}
+	return strings.Join(parts, ", ")
+}

shortcuts/apps/apps_file_delete.go

@@ -0,0 +1,148 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsFileDelete batch-deletes files by remote path（high-risk-write，框架自动注入 --yes 确认）。
+//
+// POST /apps/{app_id}/storage/file_batch_remove，body {paths:[...]}。网关把该路由注册为 POST
+// （DELETE-with-body 不被网关支持，实测 DELETE→404 / POST→200）。后端 results[] 与请求 paths
+// 顺序一一对应：成功项带 file，失败项带 error_code（CLI 据下标回填 path）。
+// 部分失败整体仍 ok:true —— 失败项落在 data.results[].error，不翻成非 0 退出码（lark-cli 信封语义）。
+var AppsFileDelete = common.Shortcut{
+	Service:     appsService,
+	Command:     "+file-delete",
+	Description: "Delete one or more files by remote path (batch)",
+	Risk:        "high-risk-write",
+	Tips: []string{
+		"Example: lark-cli apps +file-delete --app-id <app_id> --path /1858537546760216.png --yes",
+		"Repeat --path for batch delete.",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "path", Type: "string_slice", Desc: "remote file path to delete (repeatable)", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		if len(cleanDeletePaths(rctx)) == 0 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--path is required (at least one remote path)").WithParam("--path")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(appFileBatchRemovePath(appID)).
+			Desc("Batch delete Miaoda app files").
+			Body(map[string]interface{}{"paths": cleanDeletePaths(rctx)})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		paths := cleanDeletePaths(rctx)
+		data, err := rctx.CallAPITyped("POST", appFileBatchRemovePath(appID), nil, map[string]interface{}{"paths": paths})
+		if err != nil {
+			return err
+		}
+		results := projectDeleteResults(data["results"], paths)
+		out := map[string]interface{}{"results": results}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderFileDeletePretty(w, results)
+		})
+		return nil
+	},
+}
+
+// cleanDeletePaths 取 --path 切片，trim 去空。
+func cleanDeletePaths(rctx *common.RuntimeContext) []string {
+	out := make([]string, 0)
+	for _, p := range rctx.StrSlice("path") {
+		if t := strings.TrimSpace(p); t != "" {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+// projectDeleteResults 把后端 results[] 按下标 zip 回请求 paths，回填 path，
+// 失败项把 error_code 包成 {code,message} 便于消费。
+func projectDeleteResults(raw interface{}, inputs []string) []map[string]interface{} {
+	arr, _ := raw.([]interface{})
+	out := make([]map[string]interface{}, 0, len(inputs))
+	for i, input := range inputs {
+		var r map[string]interface{}
+		if i < len(arr) {
+			r, _ = arr[i].(map[string]interface{})
+		}
+		status := "ok"
+		if r != nil && common.GetString(r, "status") != "" {
+			status = common.GetString(r, "status")
+		}
+		item := map[string]interface{}{"status": status, "path": input}
+		if status == "ok" {
+			if r != nil {
+				if f, ok := r["file"].(map[string]interface{}); ok {
+					item["file_name"] = common.GetString(f, "file_name")
+				}
+			}
+		} else {
+			code := ""
+			if r != nil {
+				code = common.GetString(r, "error_code")
+			}
+			if code == "" {
+				code = "DELETE_FAILED"
+			}
+			item["error"] = map[string]interface{}{
+				"code":    code,
+				"message": deleteErrorMessage(code, input),
+			}
+		}
+		out = append(out, item)
+	}
+	return out
+}
+
+// deleteErrorMessage 据 error_code 生成删除失败文案：FILE_NOT_FOUND 提示文件不存在，其余统一删除失败。
+func deleteErrorMessage(code, path string) string {
+	if code == "FILE_NOT_FOUND" {
+		return fmt.Sprintf("File '%s' does not exist", path)
+	}
+	return fmt.Sprintf("Failed to delete '%s'", path)
+}
+
+// renderFileDeletePretty 逐项打 ✓ / ✗，末行汇总 deleted 计数。
+func renderFileDeletePretty(w io.Writer, results []map[string]interface{}) {
+	okCount := 0
+	for _, r := range results {
+		path := common.GetString(r, "path")
+		if common.GetString(r, "status") == "ok" {
+			fmt.Fprintf(w, "✓ %s\n", path)
+			okCount++
+			continue
+		}
+		code := ""
+		if e, ok := r["error"].(map[string]interface{}); ok {
+			code = common.GetString(e, "code")
+		}
+		fmt.Fprintf(w, "✗ %s (%s)\n", path, code)
+	}
+	fmt.Fprintf(w, "\n%d/%d deleted\n", okCount, len(results))
+}

shortcuts/apps/apps_file_delete_test.go

@@ -0,0 +1,132 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const fileDeleteURL = "/open-apis/spark/v1/apps/app_x/storage/file_batch_remove"
+
+// TestAppsFileDelete_RequiresAppIDAndPath 验证仅含空白的 --path 去空后为空时，Validate 报 --path typed 校验错误。
+func TestAppsFileDelete_RequiresAppIDAndPath(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	// 传入仅含空白的 --path：满足 cobra 的 Required 检查，但 cleanDeletePaths 去空后为空，
+	// 触发 Validate 内的 typed --path 校验。
+	err := runAppsShortcut(t, AppsFileDelete,
+		[]string{"+file-delete", "--app-id", "app_x", "--path", "  ", "--yes", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--path" {
+		t.Fatalf("Param = %q, want --path", ve.Param)
+	}
+}
+
+// high-risk-write：无 --yes → confirmation_required（exit 10）。
+func TestAppsFileDelete_RequiresConfirmation(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsFileDelete,
+		[]string{"+file-delete", "--app-id", "app_x", "--path", "/a.png", "--as", "user"}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "requires confirmation") {
+		t.Fatalf("expected confirmation_required, got %v", err)
+	}
+}
+
+// TestAppsFileDelete_DryRunSendsPaths 验证 dry-run 输出 POST file_batch_remove，body.paths 按序携带多个 --path。
+func TestAppsFileDelete_DryRunSendsPaths(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsFileDelete,
+		[]string{"+file-delete", "--app-id", "app_x", "--path", "/a.png", "--path", "/b.png", "--yes", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	a := env.API[0]
+	if a.Method != "POST" || a.URL != fileDeleteURL {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	paths, _ := a.Body["paths"].([]interface{})
+	if len(paths) != 2 || paths[0] != "/a.png" || paths[1] != "/b.png" {
+		t.Fatalf("body.paths = %v", a.Body["paths"])
+	}
+}
+
+// 部分失败仍 ok:true；results 按下标 zip 回 path；失败项带 error{code,message}。
+func TestAppsFileDelete_PartialFailureStillOK(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: fileDeleteURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"results": []interface{}{
+				map[string]interface{}{"status": "ok", "file": map[string]interface{}{"file_name": "a.png", "path": "/a.png"}},
+				map[string]interface{}{"status": "error", "error_code": "FILE_NOT_FOUND"},
+			},
+		}},
+	})
+	err := runAppsShortcut(t, AppsFileDelete,
+		[]string{"+file-delete", "--app-id", "app_x", "--path", "/a.png", "--path", "/missing.png", "--yes", "--as", "user"}, factory, stdout)
+	if err != nil {
+		t.Fatalf("partial failure should NOT error (ok:true semantics), got %v", err)
+	}
+	got := stdout.String()
+	var env struct {
+		Data struct {
+			Results []map[string]interface{} `json:"results"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(got), &env); err != nil {
+		t.Fatalf("decode: %v\n%s", err, got)
+	}
+	if len(env.Data.Results) != 2 {
+		t.Fatalf("want 2 results, got %d: %s", len(env.Data.Results), got)
+	}
+	r0, r1 := env.Data.Results[0], env.Data.Results[1]
+	if r0["status"] != "ok" || r0["path"] != "/a.png" {
+		t.Errorf("result[0] = %v", r0)
+	}
+	if r1["status"] != "error" || r1["path"] != "/missing.png" {
+		t.Errorf("result[1] = %v (path must be back-filled by index)", r1)
+	}
+	if e, ok := r1["error"].(map[string]interface{}); !ok || e["code"] != "FILE_NOT_FOUND" {
+		t.Errorf("result[1].error = %v (want code FILE_NOT_FOUND)", r1["error"])
+	}
+}
+
+// TestAppsFileDelete_PrettySummary 验证 pretty 输出逐项 ✓/✗ 标记并汇总 "1/2 deleted"。
+func TestAppsFileDelete_PrettySummary(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: fileDeleteURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"results": []interface{}{
+				map[string]interface{}{"status": "ok", "file": map[string]interface{}{"file_name": "a.png"}},
+				map[string]interface{}{"status": "error", "error_code": "FILE_NOT_FOUND"},
+			},
+		}},
+	})
+	if err := runAppsShortcut(t, AppsFileDelete,
+		[]string{"+file-delete", "--app-id", "app_x", "--path", "/a.png", "--path", "/missing.png", "--yes", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{"✓ /a.png", "✗ /missing.png (FILE_NOT_FOUND)", "1/2 deleted"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("pretty missing %q:\n%s", want, got)
+		}
+	}
+}

shortcuts/apps/apps_file_download.go

@@ -0,0 +1,122 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"path"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsFileDownload downloads a file to a local path via a signed URL。
+//
+// 两步：POST /apps/{app_id}/storage/file_sign 拿 signed_url（presigned，直连对象存储），
+// 再客户端 GET signed_url 落盘到 --output（默认远端 basename）。不单设 download 接口。
+var AppsFileDownload = common.Shortcut{
+	Service:     appsService,
+	Command:     "+file-download",
+	Description: "Download a file to a local path (via a signed URL)",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +file-download --app-id <app_id> --path /1858537546760216.png --output ./logo.png",
+		"Example (omit --output): lark-cli apps +file-download --app-id <app_id> --path /1858537546760216.png   # saves to ./1858537546760216.png",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "path", Desc: "remote file path", Required: true},
+		{Name: "output", Desc: "local output path (default: remote file basename in cwd)"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		_, err := requireFilePath(rctx.Str("path"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		remotePath, _ := requireFilePath(rctx.Str("path"))
+		return common.NewDryRunAPI().
+			POST(appFileSignPath(appID)).
+			Desc("Sign a download URL, then GET it to --output").
+			Body(map[string]interface{}{"path": remotePath})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		remotePath, err := requireFilePath(rctx.Str("path"))
+		if err != nil {
+			return err
+		}
+
+		// 1. 签名拿 presigned signed_url。
+		signData, err := rctx.CallAPITyped("POST", appFileSignPath(appID), nil, map[string]interface{}{"path": remotePath})
+		if err != nil {
+			return err
+		}
+		signedURL := common.GetString(signData, "signed_url")
+		if signedURL == "" {
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "sign returned no signed_url")
+		}
+
+		// 2. 直连 GET signed_url 落盘。
+		out := strings.TrimSpace(rctx.Str("output"))
+		if out == "" {
+			out = path.Base(strings.TrimPrefix(remotePath, "/"))
+			if out == "" || out == "." || out == "/" {
+				out = "download"
+			}
+		}
+		req, err := http.NewRequestWithContext(rctx.Ctx(), http.MethodGet, signedURL, nil) //nolint:forbidigo // GET from a presigned object-storage URL bypasses the Lark gateway; raw HTTP required (not a Lark API call).
+		if err != nil {
+			return errs.NewNetworkError(errs.SubtypeNetworkTransport, "build download request").WithCause(err)
+		}
+		resp, err := newFileTransferClient().Do(req) //nolint:forbidigo // see above: direct presigned-URL download, RuntimeContext.DoAPI does not apply.
+		if err != nil {
+			// dial/transport 失败是典型可重试场景。
+			return errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed").WithCause(err).WithRetryable()
+		}
+		defer resp.Body.Close()
+		if resp.StatusCode >= 400 {
+			io.Copy(io.Discard, io.LimitReader(resp.Body, 4096))
+			// 5xx 是上游瞬时故障，标 retryable；4xx（如签名过期）需重新签名而非盲重试，不标。
+			if resp.StatusCode >= 500 {
+				return errs.NewNetworkError(errs.SubtypeNetworkServer, "download failed: HTTP %d", resp.StatusCode).WithRetryable()
+			}
+			return errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: HTTP %d", resp.StatusCode)
+		}
+		saved, err := rctx.FileIO().Save(out, fileio.SaveOptions{
+			ContentType:   resp.Header.Get("Content-Type"),
+			ContentLength: resp.ContentLength,
+		}, resp.Body)
+		if err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output: %v", err).WithParam("--output").WithCause(err)
+		}
+		resolved, perr := rctx.FileIO().ResolvePath(out)
+		if perr != nil || resolved == "" {
+			resolved = out
+		}
+		result := map[string]interface{}{
+			"path":       remotePath,
+			"output":     resolved,
+			"size_bytes": saved.Size(),
+		}
+		rctx.OutFormat(result, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "✓ Downloaded %s → %s (%s)\n", remotePath, resolved, humanBytes(saved.Size()))
+		})
+		return nil
+	},
+}

shortcuts/apps/apps_file_download_test.go

@@ -0,0 +1,122 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const fileSignURLForDownload = "/open-apis/spark/v1/apps/app_x/storage/file_sign"
+
+// TestAppsFileDownload_RequiresAppIDAndPath 验证仅含空白的 --path 触发 --path typed 校验错误。
+func TestAppsFileDownload_RequiresAppIDAndPath(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsFileDownload,
+		[]string{"+file-download", "--app-id", "app_x", "--path", "  ", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--path" {
+		t.Fatalf("Param = %q, want --path", ve.Param)
+	}
+}
+
+// TestAppsFileDownload_DryRunSignsFirst 验证 dry-run 第一步是 POST file_sign。
+func TestAppsFileDownload_DryRunSignsFirst(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsFileDownload,
+		[]string{"+file-download", "--app-id", "app_x", "--path", "/x.png", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string `json:"method"`
+			URL    string `json:"url"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	if env.API[0].Method != "POST" || env.API[0].URL != fileSignURLForDownload {
+		t.Fatalf("dry-run = %s %s (want POST sign)", env.API[0].Method, env.API[0].URL)
+	}
+}
+
+// sign → 客户端 GET presigned signed_url → 落盘 --output。
+func TestAppsFileDownload_EndToEnd(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			w.WriteHeader(http.StatusMethodNotAllowed)
+			return
+		}
+		w.Header().Set("Content-Type", "image/png")
+		io.WriteString(w, "PNGDATA")
+	}))
+	defer srv.Close()
+
+	dir := t.TempDir()
+	oldWD, _ := os.Getwd()
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(oldWD) })
+
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: fileSignURLForDownload,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"signed_url": srv.URL}},
+	})
+	if err := runAppsShortcut(t, AppsFileDownload,
+		[]string{"+file-download", "--app-id", "app_x", "--path", "/x.png", "--output", "out.png", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	b, err := os.ReadFile(filepath.Join(dir, "out.png"))
+	if err != nil {
+		t.Fatalf("read output file: %v", err)
+	}
+	if string(b) != "PNGDATA" {
+		t.Fatalf("downloaded content = %q, want PNGDATA", b)
+	}
+	if !strings.Contains(stdout.String(), `"size_bytes": 7`) {
+		t.Errorf("output json missing size_bytes:7\n%s", stdout.String())
+	}
+}
+
+// 不传 --output → 默认远端 basename。
+func TestAppsFileDownload_DefaultsOutputToBasename(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		io.WriteString(w, "DATA")
+	}))
+	defer srv.Close()
+
+	dir := t.TempDir()
+	oldWD, _ := os.Getwd()
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(oldWD) })
+
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: fileSignURLForDownload,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"signed_url": srv.URL}},
+	})
+	if err := runAppsShortcut(t, AppsFileDownload,
+		[]string{"+file-download", "--app-id", "app_x", "--path", "/1858537546760216.png", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "1858537546760216.png")); err != nil {
+		t.Fatalf("default output basename not written: %v", err)
+	}
+}

shortcuts/apps/apps_file_get.go

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"io"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsFileGet gets one file's metadata by exact remote path（动词对齐 +file-list）。
+//
+// GET /apps/{app_id}/storage/file?path=<path>。file 仅按 path 精确寻址，无按名寻址。
+// pretty 渲染 key/value：file_name / path / size(含 bytes) / type / uploaded_by(只 name) / uploaded_at /
+// download_url（条件出现）。server created_at/created_by → uploaded_at/uploaded_by。
+var AppsFileGet = common.Shortcut{
+	Service:     appsService,
+	Command:     "+file-get",
+	Description: "Get a single file's metadata by path",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +file-get --app-id <app_id> --path /1858537546760216.png",
+		"Tip: extract a single field with --jq, e.g. -q '.size_bytes' or -q '.download_url'",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "path", Desc: "remote file path", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		_, err := requireFilePath(rctx.Str("path"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appFileGetPath(appID)).
+			Desc("Get Miaoda app file metadata").
+			Params(buildFileGetParams(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("GET", appFileGetPath(appID), buildFileGetParams(rctx), nil)
+		if err != nil {
+			return err
+		}
+		info := projectFileInfo(data)
+		rctx.OutFormat(info, nil, func(w io.Writer) {
+			renderFileGetPretty(w, info)
+		})
+		return nil
+	},
+}
+
+// buildFileGetParams 组装 file_get 查询参数：按 path 精确寻址单文件。
+func buildFileGetParams(rctx *common.RuntimeContext) map[string]interface{} {
+	path, _ := requireFilePath(rctx.Str("path"))
+	return map[string]interface{}{"path": path}
+}
+
+// renderFileGetPretty 输出对齐 key/value；uploaded_by 只展示 name（id 仅 json 保留）。
+func renderFileGetPretty(w io.Writer, info fileInfo) {
+	pairs := [][2]string{
+		{"file_name", dashIfEmpty(info.FileName)},
+		{"path", info.Path},
+		{"size", fileSizeDetail(info.SizeBytes)},
+		{"type", dashIfEmpty(info.Type)},
+	}
+	if info.UploadedBy != nil {
+		pairs = append(pairs, [2]string{"uploaded_by", info.UploadedBy.Name})
+	}
+	pairs = append(pairs, [2]string{"uploaded_at", dashIfEmpty(info.UploadedAt)})
+	if info.DownloadURL != "" {
+		pairs = append(pairs, [2]string{"download_url", info.DownloadURL})
+	}
+	renderKeyValuePairs(w, pairs)
+}

shortcuts/apps/apps_file_get_test.go

@@ -0,0 +1,89 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const fileGetURL = "/open-apis/spark/v1/apps/app_x/storage/file"
+
+// TestAppsFileGet_RequiresAppIDAndPath 验证空白 --app-id 与空白 --path 分别触发对应的 typed 校验错误。
+func TestAppsFileGet_RequiresAppIDAndPath(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsFileGet,
+		[]string{"+file-get", "--app-id", "  ", "--path", "/x.png", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--app-id" {
+		t.Fatalf("Param = %q, want --app-id", ve.Param)
+	}
+	factory2, stdout2, _ := newAppsExecuteFactory(t)
+	err2 := runAppsShortcut(t, AppsFileGet,
+		[]string{"+file-get", "--app-id", "app_x", "--path", "  ", "--as", "user"}, factory2, stdout2)
+	var ve2 *errs.ValidationError
+	if !errors.As(err2, &ve2) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err2, err2)
+	}
+	if ve2.Param != "--path" {
+		t.Fatalf("Param = %q, want --path", ve2.Param)
+	}
+}
+
+// TestAppsFileGet_DryRunSendsPathQuery 验证 dry-run 输出 GET file，path 作为 query 参数下发。
+func TestAppsFileGet_DryRunSendsPathQuery(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsFileGet,
+		[]string{"+file-get", "--app-id", "app_x", "--path", "/x.png", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	if env.API[0].Method != "GET" || env.API[0].URL != fileGetURL || env.API[0].Params["path"] != "/x.png" {
+		t.Fatalf("dry-run = %s %s params=%v", env.API[0].Method, env.API[0].URL, env.API[0].Params)
+	}
+}
+
+// TestAppsFileGet_SuccessAndPrettyKeyValue 验证 pretty key/value 展示 size 含 bytes、uploaded_by 只显示 name 且不泄漏 user id。
+func TestAppsFileGet_SuccessAndPrettyKeyValue(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: fileGetURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"file_name": "logo.png", "path": "/1858537546760216.png",
+			"size_bytes": 24580, "type": "image/png",
+			"created_at": "2026-04-15T10:30:00Z",
+			"created_by": `{"id":"7311","name":"alice"}`,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsFileGet,
+		[]string{"+file-get", "--app-id", "app_x", "--path", "/1858537546760216.png", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	// pretty key/value：size 含 bytes、uploaded_by 只展示 name。
+	for _, want := range []string{"file_name:", "24 KB (24580 bytes)", "uploaded_by: alice", "uploaded_at: 2026-04-15T10:30:00Z"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("pretty missing %q:\n%s", want, got)
+		}
+	}
+	// pretty 不该泄漏 user id。
+	if strings.Contains(got, "7311") {
+		t.Errorf("pretty should show name only, not id:\n%s", got)
+	}
+}

shortcuts/apps/apps_file_list.go

@@ -0,0 +1,145 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsFileList lists files in a Miaoda app's storage (cursor pagination)。
+//
+// GET /apps/{app_id}/storage/file_list。过滤器：--name / --path / --type / --size-gt /
+// --size-lt / --uploaded-since / --uploaded-until（精确或区间），分页 --page-size/--page-token。
+// file 域不分 dev/online，无 --env。
+//
+// pretty 渲染 5 列：file_name / path / size / type / uploaded_at；空结果打 "No files found."。
+// server 字段 created_at → 产品语义 uploaded_at。
+var AppsFileList = common.Shortcut{
+	Service:     appsService,
+	Command:     "+file-list",
+	Description: "List files in a Miaoda app's storage (cursor pagination)",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +file-list --app-id <app_id>",
+		"Tip: filter fields with --jq, e.g. -q '.data.items[].path'",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "name", Desc: "filter by exact file name"},
+		{Name: "path", Desc: "filter by exact remote path"},
+		{Name: "type", Desc: "filter by MIME type"},
+		{Name: "size-gt", Type: "int", Desc: "filter: size greater than (bytes)"},
+		{Name: "size-lt", Type: "int", Desc: "filter: size less than (bytes)"},
+		{Name: "uploaded-since", Desc: "filter: uploaded at or after; relative (7d/2h/30s) | date (2026-04-15) | datetime (2026-04-15T10:00:00) | ISO 8601 w/ TZ"},
+		{Name: "uploaded-until", Desc: "filter: uploaded at or before; relative (7d/2h/30s) | date (2026-04-15) | datetime (2026-04-15T10:00:00) | ISO 8601 w/ TZ"},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
+		{Name: "page-token", Desc: "pagination cursor from previous response"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		// 设计原则三：<timestamp> 多格式 → 归一化为 RFC3339 UTC，回写到 flag 供 buildFileListParams 透传。
+		for _, f := range []string{"uploaded-since", "uploaded-until"} {
+			if strings.TrimSpace(rctx.Str(f)) == "" {
+				continue
+			}
+			n, err := normalizeTimestamp(rctx.Str(f))
+			if err != nil {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--%s: %v", f, err).WithParam("--" + f)
+			}
+			_ = rctx.Cmd.Flags().Set(f, n)
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appFileListPath(appID)).
+			Desc("List Miaoda app files").
+			Params(buildFileListParams(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("GET", appFileListPath(appID), buildFileListParams(rctx), nil)
+		if err != nil {
+			return err
+		}
+		// 白名单投影：server created_at/created_by → uploaded_at/uploaded_by，替换原始 items[]。
+		items := projectFileItems(data["items"])
+		data["items"] = items
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			renderFileListPretty(w, items)
+		})
+		return nil
+	},
+}
+
+// projectFileItems 把服务端原始 items 逐项投影为白名单 fileInfo（created_*→uploaded_*）。
+func projectFileItems(raw interface{}) []fileInfo {
+	arr, _ := raw.([]interface{})
+	out := make([]fileInfo, 0, len(arr))
+	for _, it := range arr {
+		if m, ok := it.(map[string]interface{}); ok {
+			out = append(out, projectFileInfo(m))
+		}
+	}
+	return out
+}
+
+// buildFileListParams 组装 file_list 查询参数：page_size 及可选 name/path/type/size_gt/size_lt/uploaded_since/uploaded_until/page_token。
+func buildFileListParams(rctx *common.RuntimeContext) map[string]interface{} {
+	params := map[string]interface{}{
+		"page_size": rctx.Int("page-size"),
+	}
+	addStr := func(flag, key string) {
+		if v := strings.TrimSpace(rctx.Str(flag)); v != "" {
+			params[key] = v
+		}
+	}
+	addStr("name", "name")
+	addStr("path", "path")
+	addStr("type", "type")
+	addStr("uploaded-since", "uploaded_since")
+	addStr("uploaded-until", "uploaded_until")
+	addStr("page-token", "page_token")
+	if v := rctx.Int("size-gt"); v > 0 {
+		params["size_gt"] = v
+	}
+	if v := rctx.Int("size-lt"); v > 0 {
+		params["size_lt"] = v
+	}
+	return params
+}
+
+// renderFileListPretty 5 列对齐表：file_name / path / size / type / uploaded_at。
+func renderFileListPretty(w io.Writer, items []fileInfo) {
+	if len(items) == 0 {
+		io.WriteString(w, "No files found.\n")
+		return
+	}
+	headers := []string{"file_name", "path", "size", "type", "uploaded_at"}
+	rows := make([][]string, 0, len(items))
+	for _, it := range items {
+		rows = append(rows, []string{
+			dashIfEmpty(it.FileName),
+			it.Path,
+			humanBytes(it.SizeBytes),
+			dashIfEmpty(it.Type),
+			dashIfEmpty(it.UploadedAt),
+		})
+	}
+	renderAlignedTable(w, headers, rows)
+}

shortcuts/apps/apps_file_list_test.go

@@ -0,0 +1,252 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+// 设计原则三：<timestamp> 四种格式 → 统一 RFC3339 UTC。
+func TestNormalizeTimestamp_AllFormats(t *testing.T) {
+	// 空串透传
+	if got, err := normalizeTimestamp("  "); err != nil || got != "" {
+		t.Fatalf("empty → %q,%v want \"\",nil", got, err)
+	}
+
+	// ISO 8601 带 TZ：Z 原样、显式偏移换算到 UTC
+	mustEq := func(in, want string) {
+		got, err := normalizeTimestamp(in)
+		if err != nil || got != want {
+			t.Errorf("normalizeTimestamp(%q)=%q,%v want %q", in, got, err, want)
+		}
+	}
+	mustEq("2026-04-15T10:00:00Z", "2026-04-15T10:00:00Z")
+	mustEq("2026-04-15T10:00:00+08:00", "2026-04-15T02:00:00Z") // +08:00 → UTC -8h
+
+	// date / local datetime：按本地时区解释再转 UTC（与 time.ParseInLocation 对齐）
+	dExp, _ := time.ParseInLocation("2006-01-02", "2026-04-15", time.Local)
+	mustEq("2026-04-15", dExp.UTC().Format(time.RFC3339))
+	ldExp, _ := time.ParseInLocation("2006-01-02T15:04:05", "2026-04-15T10:00:00", time.Local)
+	mustEq("2026-04-15T10:00:00", ldExp.UTC().Format(time.RFC3339))
+
+	// 相对：从现在往前推，结果应 ≈ now-dur（5s 容差）
+	for _, c := range []struct {
+		in  string
+		dur time.Duration
+	}{{"30s", 30 * time.Second}, {"5m", 5 * time.Minute}, {"2h", 2 * time.Hour}, {"3d", 72 * time.Hour}, {"1w", 7 * 24 * time.Hour}} {
+		got, err := normalizeTimestamp(c.in)
+		if err != nil {
+			t.Errorf("normalizeTimestamp(%q) err=%v", c.in, err)
+			continue
+		}
+		ts, perr := time.Parse(time.RFC3339, got)
+		if perr != nil {
+			t.Errorf("normalizeTimestamp(%q)=%q not RFC3339", c.in, got)
+			continue
+		}
+		want := time.Now().Add(-c.dur)
+		if diff := want.Sub(ts); diff > 5*time.Second || diff < -5*time.Second {
+			t.Errorf("normalizeTimestamp(%q)=%q off by %v from now-%v", c.in, got, diff, c.dur)
+		}
+	}
+
+	// 非法格式 → error
+	for _, bad := range []string{"notatime", "7x", "2026/04/15", "2026-13-99"} {
+		if _, err := normalizeTimestamp(bad); err == nil {
+			t.Errorf("normalizeTimestamp(%q) expected error", bad)
+		}
+	}
+}
+
+const fileListURL = "/open-apis/spark/v1/apps/app_x/storage/file_list"
+
+// TestAppsFileList_RequiresAppID 验证空白 --app-id 触发 --app-id typed 校验错误。
+func TestAppsFileList_RequiresAppID(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsFileList,
+		[]string{"+file-list", "--app-id", "  ", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--app-id" {
+		t.Fatalf("Param = %q, want --app-id", ve.Param)
+	}
+}
+
+// 过滤器 + 分页全部进 query（size-gt/lt 走 int，uploaded_since/until 原样）。
+func TestAppsFileList_DryRunSendsFiltersAndPagination(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsFileList,
+		[]string{"+file-list", "--app-id", "app_x",
+			"--name", "logo.png", "--path", "/x.png", "--type", "image/png",
+			"--size-gt", "100", "--size-lt", "9000",
+			"--uploaded-since", "2026-01-01", "--uploaded-until", "2026-02-01",
+			"--page-size", "5", "--page-token", "cur-1",
+			"--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
+		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
+	}
+	a := env.API[0]
+	if a.Method != "GET" || a.URL != fileListURL {
+		t.Fatalf("method/url = %s %s", a.Method, a.URL)
+	}
+	// 设计原则三：date 入参会被归一化为 RFC3339 UTC，期望值用 normalizeTimestamp 计算（避开本地时区脆弱断言）。
+	sinceN, _ := normalizeTimestamp("2026-01-01")
+	untilN, _ := normalizeTimestamp("2026-02-01")
+	wantStr := map[string]string{
+		"name": "logo.png", "path": "/x.png", "type": "image/png",
+		"uploaded_since": sinceN, "uploaded_until": untilN, "page_token": "cur-1",
+	}
+	for k, v := range wantStr {
+		if a.Params[k] != v {
+			t.Errorf("params.%s = %v, want %v", k, a.Params[k], v)
+		}
+	}
+	// 且确实归一化成了 UTC（以 Z 结尾），不是原样透传。
+	if s, _ := a.Params["uploaded_since"].(string); !strings.HasSuffix(s, "Z") {
+		t.Errorf("uploaded_since not normalized to RFC3339 UTC: %v", a.Params["uploaded_since"])
+	}
+	for _, k := range []string{"size_gt", "size_lt", "page_size"} {
+		if _, ok := a.Params[k]; !ok {
+			t.Errorf("params missing %s: %v", k, a.Params)
+		}
+	}
+}
+
+// 0 值过滤器不下发（size-gt/lt 缺省 0、空字符串过滤器）。
+func TestAppsFileList_DryRunOmitsEmptyFilters(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsFileList,
+		[]string{"+file-list", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	for _, banned := range []string{"name", "path", "type", "size_gt", "size_lt", "uploaded_since", "uploaded_until", "page_token"} {
+		if _, ok := env.API[0].Params[banned]; ok {
+			t.Errorf("params should omit empty %s: %v", banned, env.API[0].Params)
+		}
+	}
+	if _, ok := env.API[0].Params["page_size"]; !ok {
+		t.Errorf("params should always carry page_size: %v", env.API[0].Params)
+	}
+}
+
+// created_at/created_by → uploaded_at/uploaded_by；created_by 是 JSON 字符串 → parse 成对象。
+func TestAppsFileList_SuccessProjectsCreatedToUploaded(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    fileListURL,
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"has_more":   false,
+				"page_token": "",
+				"items": []interface{}{
+					map[string]interface{}{
+						"file_name":    "logo.png",
+						"path":         "/1858537546760216.png",
+						"size_bytes":   24580,
+						"type":         "image/png",
+						"created_at":   "2026-04-15T10:30:00Z",
+						"created_by":   `{"id":"7311","name":"alice"}`,
+						"download_url": "/spark/app/x/1858537546760216.png",
+					},
+				},
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsFileList,
+		[]string{"+file-list", "--app-id", "app_x", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{`"uploaded_at": "2026-04-15T10:30:00Z"`, `"uploaded_by"`, `"name": "alice"`, `"id": "7311"`} {
+		if !strings.Contains(got, want) {
+			t.Errorf("stdout missing %q:\n%s", want, got)
+		}
+	}
+	// created_* 不应再出现在输出。
+	for _, banned := range []string{"created_at", "created_by"} {
+		if strings.Contains(got, banned) {
+			t.Errorf("stdout should not contain %q (renamed to uploaded_*):\n%s", banned, got)
+		}
+	}
+}
+
+// TestAppsFileList_PrettyTableAndEmpty 验证 pretty 非空时渲染表头与人类可读 size，空结果时输出 "No files found."。
+func TestAppsFileList_PrettyTableAndEmpty(t *testing.T) {
+	// 非空：5 列表头。
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: fileListURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"items": []interface{}{map[string]interface{}{
+				"file_name": "logo.png", "path": "/x.png", "size_bytes": 24576, "type": "image/png",
+				"created_at": "2026-04-15T10:30:00Z",
+			}},
+		}},
+	})
+	if err := runAppsShortcut(t, AppsFileList,
+		[]string{"+file-list", "--app-id", "app_x", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "file_name") || !strings.Contains(got, "uploaded_at") || !strings.Contains(got, "24 KB") {
+		t.Fatalf("pretty table malformed:\n%s", got)
+	}
+
+	// 空：No files found.
+	factory2, stdout2, reg2 := newAppsExecuteFactory(t)
+	reg2.Register(&httpmock.Stub{
+		Method: "GET", URL: fileListURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"items": []interface{}{}}},
+	})
+	if err := runAppsShortcut(t, AppsFileList,
+		[]string{"+file-list", "--app-id", "app_x", "--format", "pretty", "--as", "user"}, factory2, stdout2); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout2.String(), "No files found.") {
+		t.Fatalf("empty pretty should say 'No files found.', got: %s", stdout2.String())
+	}
+}
+
+// TestParseFileUser_Cases 验证 parseFileUser：合法 JSON 解析成对象，空串/非法/全空字段均返回 nil。
+func TestParseFileUser_Cases(t *testing.T) {
+	if u := parseFileUser(`{"id":"1","name":"a"}`); u == nil || u.ID != "1" || u.Name != "a" {
+		t.Fatalf("valid parse failed: %#v", u)
+	}
+	if u := parseFileUser(""); u != nil {
+		t.Errorf("empty → nil, got %#v", u)
+	}
+	if u := parseFileUser("not json"); u != nil {
+		t.Errorf("invalid → nil, got %#v", u)
+	}
+	if u := parseFileUser(`{"id":"","name":""}`); u != nil {
+		t.Errorf("all-empty → nil, got %#v", u)
+	}
+}

shortcuts/apps/apps_file_quota_get.go

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsFileQuotaGet reports an app's file-storage usage（动词对齐 +db-quota-get）。
+//
+// GET /apps/{app_id}/storage/file_quota。storage_quota_bytes / usage_percent 在配额未对接（=0）时
+// 不输出（json 删字段、pretty 只打已用量）。
+var AppsFileQuotaGet = common.Shortcut{
+	Service:     appsService,
+	Command:     "+file-quota-get",
+	Description: "Get an app's file-storage usage",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +file-quota-get --app-id <app_id>",
+		"Tip: get just the usage percent with -q '.usage_percent'",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appFileQuotaPath(appID)).
+			Desc("Get Miaoda app file-storage usage")
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("GET", appFileQuotaPath(appID), nil, nil)
+		if err != nil {
+			return err
+		}
+		out := projectFileQuota(data)
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderFileQuotaPretty(w, out)
+		})
+		return nil
+	},
+}
+
+// projectFileQuota 白名单投影 file quota 字段：只保留 agent 需要的 storage_used_bytes / files，
+// 配额已对接时再加 storage_quota_bytes / usage_percent。不透传后端其它字段，避免无用字段消耗上下文。
+func projectFileQuota(data map[string]interface{}) map[string]interface{} {
+	out := map[string]interface{}{"storage_used_bytes": data["storage_used_bytes"]}
+	if v, ok := data["files"]; ok {
+		out["files"] = v
+	}
+	// 配额未对接（storage_quota_bytes=0/缺失）时不输出 quota / usage_percent，避免误导。
+	if q, ok := numericAsFloat(data["storage_quota_bytes"]); ok && q > 0 {
+		out["storage_quota_bytes"] = data["storage_quota_bytes"]
+		if v, ok := data["usage_percent"]; ok {
+			out["usage_percent"] = v
+		}
+	}
+	return out
+}
+
+// renderFileQuotaPretty 打 Storage（已用 / 配额 (百分比)）与 Files 行（标签对齐 miaoda-cli）。
+func renderFileQuotaPretty(w io.Writer, data map[string]interface{}) {
+	used := humanBytes(data["storage_used_bytes"])
+	usage := used
+	if q, ok := numericAsFloat(data["storage_quota_bytes"]); ok && q > 0 {
+		pct := ""
+		if p, ok := numericAsFloat(data["usage_percent"]); ok {
+			pct = fmt.Sprintf(" (%.1f%%)", p)
+		}
+		usage = fmt.Sprintf("%s / %s%s", used, humanBytes(data["storage_quota_bytes"]), pct)
+	}
+	pairs := [][2]string{{"Storage", usage}}
+	if f, ok := numericAsFloat(data["files"]); ok {
+		pairs = append(pairs, [2]string{"Files", fmt.Sprintf("%d", int64(f))})
+	}
+	renderKeyValuePairs(w, pairs)
+}

shortcuts/apps/apps_file_quota_get_test.go

@@ -0,0 +1,96 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const fileQuotaURL = "/open-apis/spark/v1/apps/app_x/storage/file_quota"
+
+// TestAppsFileQuotaGet_QuotaConnectedShowsAllFields 验证配额已对接时输出 storage_quota_bytes/usage_percent/files 全字段。
+func TestAppsFileQuotaGet_QuotaConnectedShowsAllFields(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: fileQuotaURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"storage_used_bytes":  157286400,
+			"storage_quota_bytes": 1073741824,
+			"usage_percent":       14.6,
+			"files":               42,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsFileQuotaGet,
+		[]string{"+file-quota-get", "--app-id", "app_x", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{`"storage_quota_bytes"`, `"usage_percent"`, `"files"`} {
+		if !strings.Contains(got, want) {
+			t.Errorf("quota json missing %q:\n%s", want, got)
+		}
+	}
+}
+
+// 配额未对接（=0）：storage_quota_bytes / usage_percent 不输出。
+func TestAppsFileQuotaGet_UnconnectedOmitsQuotaFields(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: fileQuotaURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"storage_used_bytes":  157286400,
+			"storage_quota_bytes": 0,
+			"usage_percent":       0,
+			"files":               42,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsFileQuotaGet,
+		[]string{"+file-quota-get", "--app-id", "app_x", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, banned := range []string{"storage_quota_bytes", "usage_percent"} {
+		if strings.Contains(got, banned) {
+			t.Errorf("unconnected quota should omit %q:\n%s", banned, got)
+		}
+	}
+	if !strings.Contains(got, `"storage_used_bytes"`) || !strings.Contains(got, `"files"`) {
+		t.Errorf("should still show used/files:\n%s", got)
+	}
+}
+
+// TestProjectFileQuota_OmitsZeroQuotaAndDropsUnknownFields 验证 projectFileQuota 白名单投影：
+// quota=0 时不输出 storage_quota_bytes/usage_percent，非零时保留；后端额外字段不透传。
+func TestProjectFileQuota_OmitsZeroQuotaAndDropsUnknownFields(t *testing.T) {
+	out := projectFileQuota(map[string]interface{}{
+		"storage_used_bytes": 100, "storage_quota_bytes": float64(0), "usage_percent": float64(0),
+		"files": 3, "tenant_key": "leak", "request_id": "rid",
+	})
+	if _, ok := out["storage_quota_bytes"]; ok {
+		t.Errorf("zero quota should be omitted: %v", out)
+	}
+	if _, ok := out["usage_percent"]; ok {
+		t.Errorf("usage_percent should be omitted when quota=0: %v", out)
+	}
+	if out["storage_used_bytes"] != 100 || out["files"] != 3 {
+		t.Errorf("whitelisted fields should be kept: %v", out)
+	}
+	// 白名单外的字段必须被丢弃，避免无用字段消耗 agent 上下文。
+	for _, leaked := range []string{"tenant_key", "request_id"} {
+		if _, ok := out[leaked]; ok {
+			t.Errorf("non-whitelisted field %q must be dropped: %v", leaked, out)
+		}
+	}
+
+	out2 := projectFileQuota(map[string]interface{}{"storage_used_bytes": 100, "storage_quota_bytes": float64(1024), "usage_percent": float64(9.8), "files": 3})
+	if _, ok := out2["storage_quota_bytes"]; !ok {
+		t.Errorf("non-zero quota should be kept: %v", out2)
+	}
+	if _, ok := out2["usage_percent"]; !ok {
+		t.Errorf("usage_percent should be kept when quota>0: %v", out2)
+	}
+}

shortcuts/apps/apps_file_sign.go

@@ -0,0 +1,82 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// fileSignMaxExpiresSeconds 是签名链接最长有效期（30 天）。超出 → 校验失败。
+const fileSignMaxExpiresSeconds = 30 * 24 * 60 * 60
+
+// AppsFileSign generates a temporary signed download URL for a file。
+//
+// POST /apps/{app_id}/storage/file_sign，body {path, expires_in}。
+// pretty 模式只打 signed_url（便于直接管道 / curl）；json 返 {file_name,path,signed_url,expires_at}。
+var AppsFileSign = common.Shortcut{
+	Service:     appsService,
+	Command:     "+file-sign",
+	Description: "Generate a temporary signed download URL for a file",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +file-sign --app-id <app_id> --path /1858537546760216.png",
+		"Tip: curl the signed_url directly to download.",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "path", Desc: "remote file path", Required: true},
+		{Name: "expires-in", Type: "int", Default: "86400", Desc: "link validity in seconds (max 2592000 = 30d)"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		if _, err := requireFilePath(rctx.Str("path")); err != nil {
+			return err
+		}
+		if rctx.Int("expires-in") > fileSignMaxExpiresSeconds {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--expires-in exceeds the maximum of %d seconds (30d)", fileSignMaxExpiresSeconds).WithParam("--expires-in")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(appFileSignPath(appID)).
+			Desc("Sign a temporary download URL").
+			Body(buildFileSignBody(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("POST", appFileSignPath(appID), nil, buildFileSignBody(rctx))
+		if err != nil {
+			return err
+		}
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			fmt.Fprintln(w, common.GetString(data, "signed_url"))
+		})
+		return nil
+	},
+}
+
+// buildFileSignBody 组装 file_sign 请求体：path 及可选 expires_in（秒）。
+func buildFileSignBody(rctx *common.RuntimeContext) map[string]interface{} {
+	path, _ := requireFilePath(rctx.Str("path"))
+	body := map[string]interface{}{"path": path}
+	if v := rctx.Int("expires-in"); v > 0 {
+		body["expires_in"] = v
+	}
+	return body
+}

shortcuts/apps/apps_file_sign_test.go

@@ -0,0 +1,74 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const fileSignURL = "/open-apis/spark/v1/apps/app_x/storage/file_sign"
+
+// TestAppsFileSign_DryRunBody 验证 dry-run 输出 POST file_sign，body 携带 path 与 expires_in。
+func TestAppsFileSign_DryRunBody(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsFileSign,
+		[]string{"+file-sign", "--app-id", "app_x", "--path", "/x.png", "--expires-in", "3600", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	a := env.API[0]
+	if a.Method != "POST" || a.URL != fileSignURL || a.Body["path"] != "/x.png" {
+		t.Fatalf("dry-run = %s %s body=%v", a.Method, a.URL, a.Body)
+	}
+	if ei, _ := a.Body["expires_in"].(float64); int(ei) != 3600 {
+		t.Fatalf("body.expires_in = %v, want 3600", a.Body["expires_in"])
+	}
+}
+
+// TestAppsFileSign_RejectsDurationOverMax 验证 --expires-in 超过上限时触发 --expires-in typed 校验错误。
+func TestAppsFileSign_RejectsDurationOverMax(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsFileSign,
+		[]string{"+file-sign", "--app-id", "app_x", "--path", "/x.png", "--expires-in", "9999999", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--expires-in" {
+		t.Fatalf("Param = %q, want --expires-in", ve.Param)
+	}
+}
+
+// TestAppsFileSign_PrettyPrintsSignedURL 验证 pretty 只输出 signed_url 本身。
+func TestAppsFileSign_PrettyPrintsSignedURL(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: fileSignURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"file_name": "x.png", "path": "/x.png",
+			"signed_url": "https://tos.example/x.png?sig=abc", "expires_at": "2026-04-16T10:30:00Z",
+		}},
+	})
+	if err := runAppsShortcut(t, AppsFileSign,
+		[]string{"+file-sign", "--app-id", "app_x", "--path", "/x.png", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := strings.TrimSpace(stdout.String())
+	if got != "https://tos.example/x.png?sig=abc" {
+		t.Fatalf("pretty should print only signed_url, got: %q", got)
+	}
+}

shortcuts/apps/apps_file_upload.go

@@ -0,0 +1,206 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"mime"
+	"net/http"
+	"path/filepath"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// fileUploadMaxBytes 是单文件上传上限（100 MB，对齐 miaoda）。
+const fileUploadMaxBytes = 100 * 1024 * 1024
+
+// AppsFileUpload uploads a local file to an app's storage（三步直传）。
+//
+// 1. POST /apps/{app_id}/storage/file_pre_upload {file_name,file_size,content_type} → {upload_url,upload_id}
+// 2. 客户端 PUT 文件字节到 presigned upload_url，取响应 ETag
+// 3. POST /apps/{app_id}/storage/file_upload_callback {upload_id,etag} → 文件元数据
+// file_name 取本地 basename；path 由平台生成 16 位 ID（不可指定）。仅收 --file。
+var AppsFileUpload = common.Shortcut{
+	Service:     appsService,
+	Command:     "+file-upload",
+	Description: "Upload a local file to an app's storage",
+	Risk:        "write",
+	Tips: []string{
+		"Example: lark-cli apps +file-upload --app-id <app_id> --file ./logo.png",
+		"Example: lark-cli apps +file-upload --app-id <app_id> --file ./report.pdf -q '.path'   # print the platform-generated file path",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "file", Desc: "local file to upload (file_name = basename)", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		f := strings.TrimSpace(rctx.Str("file"))
+		if f == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file is required").WithParam("--file")
+		}
+		st, err := rctx.FileIO().Stat(f)
+		if err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: %v", err).WithParam("--file").WithCause(err)
+		}
+		if st.IsDir() {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file must be a file, not a directory").WithParam("--file")
+		}
+		if st.Size() > fileUploadMaxBytes {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "file size %d bytes exceeds the 100 MB upload limit", st.Size()).WithParam("--file")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(appFilePreUploadPath(appID)).
+			Desc("Pre-upload → client PUT bytes → callback (3-step)").
+			Body(map[string]interface{}{"file_name": filepath.Base(strings.TrimSpace(rctx.Str("file")))})
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		localPath := strings.TrimSpace(rctx.Str("file"))
+		content, err := cmdutil.ReadInputFile(rctx.FileIO(), localPath)
+		if err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: %v", err).WithParam("--file").WithCause(err)
+		}
+		fileName := filepath.Base(localPath)
+		contentType := mimeByExt(fileName)
+
+		// 1. pre-upload
+		pre, err := rctx.CallAPITyped("POST", appFilePreUploadPath(appID), nil, map[string]interface{}{
+			"file_name":    fileName,
+			"file_size":    len(content),
+			"content_type": contentType,
+		})
+		if err != nil {
+			return err
+		}
+		uploadURL := common.GetString(pre, "upload_url")
+		uploadID := common.GetString(pre, "upload_id")
+		if uploadURL == "" || uploadID == "" {
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "pre-upload returned no upload_url / upload_id")
+		}
+
+		// 2. PUT 文件字节到 presigned URL，取 ETag（带 Content-Disposition 透传原始文件名）
+		etag, err := putFileBytes(rctx.Ctx(), uploadURL, content, contentType, fileName)
+		if err != nil {
+			return err
+		}
+
+		// 3. callback
+		result, err := rctx.CallAPITyped("POST", appFileUploadCallbackPath(appID), nil, map[string]interface{}{
+			"upload_id": uploadID,
+			"etag":      etag,
+		})
+		if err != nil {
+			return err
+		}
+		info := projectFileInfo(result)
+		rctx.OutFormat(info, nil, func(w io.Writer) {
+			renderFileUploadPretty(w, fileName, info)
+		})
+		return nil
+	},
+}
+
+// putFileBytes 直连 PUT 文件字节到 presigned URL，返回响应的 ETag。
+//
+// Content-Disposition 透传原始文件名：TOS 把它存成对象 metadata，callback 阶段后端
+// HeadObject 读回解析出 filename 写入 DB 的 display name。不传则后端兜底用 storage key
+// （平台 16 位 ID）当文件名 —— 即「上传后文件名变成 ID」的根因。
+//
+//nolint:forbidigo // direct PUT to a presigned object-storage URL bypasses the Lark gateway — raw HTTP is required (no Lark auth/gateway); RuntimeContext.DoAPI cannot target a presigned URL.
+func putFileBytes(ctx context.Context, url string, content []byte, contentType, fileName string) (string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut, url, bytes.NewReader(content))
+	if err != nil {
+		return "", errs.NewNetworkError(errs.SubtypeNetworkTransport, "build upload request").WithCause(err)
+	}
+	req.ContentLength = int64(len(content))
+	if contentType != "" {
+		req.Header.Set("Content-Type", contentType)
+	}
+	req.Header.Set("Content-Disposition", "attachment; filename=\""+sanitizeUploadFileName(fileName)+"\"")
+	resp, err := newFileTransferClient().Do(req)
+	if err != nil {
+		// dial/transport 失败是典型可重试场景。
+		return "", errs.NewNetworkError(errs.SubtypeNetworkTransport, "upload failed").WithCause(err).WithRetryable()
+	}
+	defer resp.Body.Close()
+	io.Copy(io.Discard, io.LimitReader(resp.Body, 4096))
+	if resp.StatusCode >= 400 {
+		// 5xx 是上游瞬时故障，标 retryable；4xx（如签名过期）需重新签名而非盲重试，不标。
+		if resp.StatusCode >= 500 {
+			return "", errs.NewNetworkError(errs.SubtypeNetworkServer, "upload failed: HTTP %d", resp.StatusCode).WithRetryable()
+		}
+		return "", errs.NewNetworkError(errs.SubtypeNetworkTransport, "upload failed: HTTP %d", resp.StatusCode)
+	}
+	return resp.Header.Get("ETag"), nil
+}
+
+// sanitizeUploadFileName 对齐 miaoda：先去掉 TOS 非法字符 [:"\/*?<>|,;]，再 encodeURIComponent
+// （UTF-8 百分号编码，兼容中文等非 ASCII，且让 Content-Disposition header 合法），空则兜底 download_file。
+func sanitizeUploadFileName(name string) string {
+	var b strings.Builder
+	for _, r := range name {
+		switch r {
+		case ':', '"', '\\', '/', '*', '?', '<', '>', '|', ',', ';':
+			continue
+		default:
+			b.WriteRune(r)
+		}
+	}
+	enc := encodeURIComponent(b.String())
+	if enc == "" {
+		return "download_file"
+	}
+	return enc
+}
+
+// encodeURIComponent 复刻 JS encodeURIComponent：除 A-Za-z0-9-_.!~*'() 外按 UTF-8 字节 %XX 编码。
+func encodeURIComponent(s string) string {
+	const keep = "-_.!~*'()"
+	var b strings.Builder
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		if (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || strings.IndexByte(keep, c) >= 0 {
+			b.WriteByte(c)
+		} else {
+			b.WriteString(fmt.Sprintf("%%%02X", c))
+		}
+	}
+	return b.String()
+}
+
+// mimeByExt 按扩展名推断 Content-Type，未知回退 application/octet-stream。
+func mimeByExt(name string) string {
+	if t := mime.TypeByExtension(filepath.Ext(name)); t != "" {
+		return t
+	}
+	return "application/octet-stream"
+}
+
+// renderFileUploadPretty 打 ✓ Uploaded <local> → <path> + size / download_url。
+func renderFileUploadPretty(w io.Writer, localName string, info fileInfo) {
+	fmt.Fprintf(w, "✓ Uploaded %s → %s\n", localName, info.Path)
+	fmt.Fprintf(w, "size:         %s\n", fileSizeDetail(info.SizeBytes))
+	if info.DownloadURL != "" {
+		fmt.Fprintf(w, "download_url: %s\n", info.DownloadURL)
+	}
+}

shortcuts/apps/apps_file_upload_test.go

@@ -0,0 +1,179 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+// TestAppsFileUpload_RequiresAppIDAndFile 验证仅含空白的 --file 经 Validate 去空后触发 --file typed 校验错误。
+func TestAppsFileUpload_RequiresAppIDAndFile(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	// --file is a cobra-required flag; pass whitespace so cobra's required check
+	// passes and our Validate (which trims) rejects it with a typed error.
+	err := runAppsShortcut(t, AppsFileUpload,
+		[]string{"+file-upload", "--app-id", "app_x", "--file", "  ", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--file" {
+		t.Fatalf("Param = %q, want --file", ve.Param)
+	}
+}
+
+// TestAppsFileUpload_RejectsDirectory 验证 --file 指向目录时触发 --file typed 校验错误。
+func TestAppsFileUpload_RejectsDirectory(t *testing.T) {
+	dir := t.TempDir()
+	oldWD, _ := os.Getwd()
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(oldWD) })
+	if err := os.Mkdir(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsFileUpload,
+		[]string{"+file-upload", "--app-id", "app_x", "--file", "sub", "--as", "user"}, factory, stdout)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("err = %T %v, want *errs.ValidationError", err, err)
+	}
+	if ve.Param != "--file" {
+		t.Fatalf("Param = %q, want --file", ve.Param)
+	}
+}
+
+// TestAppsFileUpload_DryRunPreUpload 验证 dry-run 输出 POST file_pre_upload，body.file_name 取文件 basename。
+func TestAppsFileUpload_DryRunPreUpload(t *testing.T) {
+	// Validate 会 Stat --file（在 DryRun 之前），故 dry-run 也需要真实存在的文件。
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "logo.png"), []byte("x"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	oldWD, _ := os.Getwd()
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(oldWD) })
+
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsFileUpload,
+		[]string{"+file-upload", "--app-id", "app_x", "--file", "logo.png", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	a := env.API[0]
+	if a.Method != "POST" || a.URL != "/open-apis/spark/v1/apps/app_x/storage/file_pre_upload" {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	if a.Body["file_name"] != "logo.png" {
+		t.Fatalf("dry-run body.file_name = %v, want logo.png (basename)", a.Body["file_name"])
+	}
+}
+
+// 三步直传：pre-upload → 客户端 PUT 字节 → callback。
+func TestAppsFileUpload_EndToEnd(t *testing.T) {
+	var putBody []byte
+	var putContentType, putCD string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPut {
+			w.WriteHeader(http.StatusMethodNotAllowed)
+			return
+		}
+		putBody, _ = io.ReadAll(r.Body)
+		putContentType = r.Header.Get("Content-Type")
+		putCD = r.Header.Get("Content-Disposition")
+		w.Header().Set("ETag", `"etag-123"`)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "logo.png"), []byte("PNGBYTES"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	oldWD, _ := os.Getwd()
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(oldWD) })
+
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/storage/file_pre_upload",
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"upload_url": srv.URL, "upload_id": "up-1"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/storage/file_upload_callback",
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"file_name": "logo.png", "path": "/1858537546760216.png", "size_bytes": 8, "type": "image/png",
+			"download_url": "/spark/app/x/1858537546760216.png",
+		}},
+	})
+
+	if err := runAppsShortcut(t, AppsFileUpload,
+		[]string{"+file-upload", "--app-id", "app_x", "--file", "logo.png", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if string(putBody) != "PNGBYTES" {
+		t.Fatalf("PUT body = %q, want file bytes", putBody)
+	}
+	if putContentType != "image/png" {
+		t.Errorf("PUT Content-Type = %q, want image/png", putContentType)
+	}
+	// 原始文件名必须经 Content-Disposition 透传给 TOS（否则后端用 storage key 当文件名）。
+	if putCD != `attachment; filename="logo.png"` {
+		t.Errorf("PUT Content-Disposition = %q, want attachment; filename=\"logo.png\"", putCD)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, `"path": "/1858537546760216.png"`) {
+		t.Errorf("output missing uploaded path:\n%s", got)
+	}
+}
+
+// TestSanitizeUploadFileName_Cases 验证 sanitizeUploadFileName：空格转 %20、去 TOS 非法字符、全非法兜底、非 ASCII 百分号编码。
+func TestSanitizeUploadFileName_Cases(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"logo.png", "logo.png"},
+		{"a b.png", "a%20b.png"},     // 空格 → %20（encodeURIComponent）
+		{`a:b/c*d?.png`, "abcd.png"}, // 去掉 TOS 非法字符
+		{"///", "download_file"},     // 全非法 → 兜底
+		{"中.txt", "%E4%B8%AD.txt"},   // 非 ASCII → UTF-8 百分号编码
+	}
+	for _, c := range cases {
+		if got := sanitizeUploadFileName(c.in); got != c.want {
+			t.Errorf("sanitizeUploadFileName(%q)=%q want %q", c.in, got, c.want)
+		}
+	}
+}
+
+// TestMimeByExt_Cases 验证 mimeByExt：按扩展名识别 image/png，未知扩展名兜底 application/octet-stream。
+func TestMimeByExt_Cases(t *testing.T) {
+	if got := mimeByExt("a.png"); !strings.HasPrefix(got, "image/png") {
+		t.Errorf("mimeByExt(a.png)=%q want image/png", got)
+	}
+	if got := mimeByExt("data.unknownext"); got != "application/octet-stream" {
+		t.Errorf("mimeByExt(unknown)=%q want application/octet-stream", got)
+	}
+}

shortcuts/apps/db_common.go

@@ -4,13 +4,50 @@
 package apps
 
 import (
+	"context"
+	"encoding/json"
 	"fmt"
 	"strings"
+	"time"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 )
 
+// pollUntil 轮询异步任务直到 check 判定终态。async migrate/recovery 用：dataloom 立即返
+// task_id/preview_request_id，CLI 自己 poll（避免单连接长挂被网关/SDK 30s 中断）。
+// 首次立即 fetch（不睡）；check 返 done→返回；返 err→透传（失败终态）；否则按 interval 间隔重试至 maxWait。
+func pollUntil(ctx context.Context, interval, maxWait time.Duration,
+	fetch func() (map[string]interface{}, error),
+	check func(map[string]interface{}) (done bool, err error)) (map[string]interface{}, error) {
+	maxAttempts := int(maxWait / interval)
+	if maxAttempts < 1 {
+		maxAttempts = 1
+	}
+	for i := 0; ; i++ {
+		data, err := fetch()
+		if err != nil {
+			return nil, err
+		}
+		done, cerr := check(data)
+		if cerr != nil {
+			return nil, cerr
+		}
+		if done {
+			return data, nil
+		}
+		if i+1 >= maxAttempts {
+			// async 任务多半还在服务端推进，poll 超时是可重试的——标 retryable 让 agent 重新轮询而非放弃。
+			return nil, errs.NewNetworkError(errs.SubtypeNetworkTimeout, "timed out waiting for completion after %s", maxWait).WithRetryable()
+		}
+		select {
+		case <-ctx.Done():
+			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "cancelled while waiting").WithCause(ctx.Err())
+		case <-time.After(interval):
+		}
+	}
+}
+
 // URL helpers for the db CLI commands.
 
 // appTablesPath 返回 app db 表列表 URL（复用存量「获取数据表列表」接口）。
@@ -33,11 +70,167 @@ func appDbEnvCreatePath(appID string) string {
 	return fmt.Sprintf("%s/apps/%s/db_dev_init", apiBasePath, validate.EncodePathSegment(appID))
 }
 
+// ── 多环境发布（env diff/migrate）/ 数据恢复（recovery）/ 配额 路由 ──
+
+// appEnvMigratePath 返回 dev→online 发布（预览/落地共用）URL：db/env_migrate。
+func appEnvMigratePath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/env_migrate", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appEnvMigrateStatusPath 返回发布异步任务状态查询 URL：db/env_migrate_status。
+func appEnvMigrateStatusPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/env_migrate_status", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appRecoveryPath 返回 PITR 数据恢复（预览/落地共用）URL：db/env_recovery。
+func appRecoveryPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/env_recovery", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appRecoveryDiffStatusPath 返回恢复预览（diff）异步状态查询 URL：db/env_recovery_diff_status。
+func appRecoveryDiffStatusPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/env_recovery_diff_status", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appRecoveryApplyStatusPath 返回恢复落地异步状态查询 URL：db/env_recovery_apply_status。
+func appRecoveryApplyStatusPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/env_recovery_apply_status", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appDbQuotaPath 返回 db 配额查询 URL：db/quota。
+func appDbQuotaPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/quota", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// ── 变更追溯（changelog / audit）路由 ──
+
+// appChangelogListPath 返回 DDL 变更记录列表 URL：db/changelog_list。
+func appChangelogListPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/changelog_list", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appAuditStatusPath 返回表审计开关状态查询 URL：db/audit_status。
+func appAuditStatusPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/audit_status", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appAuditSetPath 返回表审计开关设置 URL：db/audit_set。
+func appAuditSetPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/audit_set", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appAuditListPath 返回行级审计事件列表 URL：db/audit_list。
+func appAuditListPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/audit_list", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// operatorRef 是 operator 的 {id,name}。后端用 JSON 字符串内嵌透传，CLI parse：
+// json 输出还原成对象（下游能区分同名用户），pretty 只取 name。
+type operatorRef struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+}
+
+// parseOperator 解析 operator 字符串：空→nil；非 JSON→{raw,raw}；JSON→{id,name}（name 空兜底 id）。
+func parseOperator(raw string) *operatorRef {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return nil
+	}
+	if !strings.HasPrefix(s, "{") {
+		return &operatorRef{ID: s, Name: s}
+	}
+	var o operatorRef
+	if json.Unmarshal([]byte(s), &o) != nil {
+		return &operatorRef{ID: s, Name: s}
+	}
+	if o.Name == "" {
+		o.Name = o.ID
+	}
+	return &o
+}
+
+// operatorName 取 operator 的展示名（pretty），空用 "—"。
+func operatorName(op *operatorRef) string {
+	if op == nil || op.Name == "" {
+		return "—"
+	}
+	return op.Name
+}
+
+// safeParseJSON 把 before/after 的 JSON 字符串还原成结构化对象供下游消费；失败时透传原始串。
+func safeParseJSON(s string) interface{} {
+	var v interface{}
+	if json.Unmarshal([]byte(s), &v) == nil {
+		return v
+	}
+	return s
+}
+
+// appDataImportPath 返回 db 数据导入 URL（新增 db/ 域段路由）。
+func appDataImportPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/data_import", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appDataExportPath 返回 db 数据导出 URL（返原始字节）。
+func appDataExportPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/db/data_export", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appTableRecordsPath 返回数据表记录列表 URL（复用 GetAppTableRecordList，其 total 即符合条件的记录总数）。
+func appTableRecordsPath(appID, table string) string {
+	return appTablePath(appID, table) + "/records"
+}
+
+// resolveDataFormat 由文件扩展名推断数据格式。lark-cli 的 --format 已被框架占用（输出渲染），
+// 故数据格式从文件名推断：import 接受 csv/json，export 还接受 sql。
+func resolveDataFormat(ext string, allowSQL bool) (string, error) {
+	raw := strings.TrimPrefix(strings.ToLower(strings.TrimSpace(ext)), ".")
+	switch raw {
+	case "csv", "json":
+		return raw, nil
+	case "sql":
+		if allowSQL {
+			return "sql", nil
+		}
+	}
+	if allowSQL {
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported data format %q (file must end in .csv, .json or .sql)", raw)
+	}
+	return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported data format %q (file must end in .csv or .json)", raw)
+}
+
+// countDataRows 粗估数据行数（用于导入上限校验、导出兜底计数）。
+// csv：非空行数 - 1（表头）；json：顶层数组长度，非数组算 1，解析失败算 0。
+func countDataRows(body []byte, format string) int {
+	if format == "csv" {
+		lines := 0
+		for _, ln := range strings.Split(string(body), "\n") {
+			if strings.TrimRight(ln, "\r") != "" {
+				lines++
+			}
+		}
+		if lines > 0 {
+			return lines - 1
+		}
+		return 0
+	}
+	var arr []json.RawMessage
+	if err := json.Unmarshal(body, &arr); err == nil {
+		return len(arr)
+	}
+	var obj map[string]json.RawMessage
+	if err := json.Unmarshal(body, &obj); err == nil {
+		return 1
+	}
+	return 0
+}
+
 // requireAppID trims --app-id and rejects blank, returning a uniform validation error.
 func requireAppID(raw string) (string, error) {
 	id := strings.TrimSpace(raw)
 	if id == "" {
-		return "", output.ErrValidation("--app-id is required")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--app-id is required").WithParam("--app-id")
 	}
 	return id, nil
 }

shortcuts/apps/file_common.go

@@ -0,0 +1,228 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var (
+	reTsRelative      = regexp.MustCompile(`^([0-9]+)([smhdw])$`)
+	reTsDate          = regexp.MustCompile(`^[0-9]{4}-[0-9]{2}-[0-9]{2}$`)
+	reTsLocalDateTime = regexp.MustCompile(`^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}$`)
+)
+
+// normalizeTimestamp 实现设计原则三的 <timestamp> 多格式输入，统一归一化为 RFC3339 UTC：
+//   - 相对：30s / 5m / 2h / 3d / 1w（从现在往前推）
+//   - date：2026-04-15（本地时区 00:00:00）
+//   - local datetime：2026-04-15T10:00:00（本地时区，T 分隔）
+//   - ISO 8601 带 TZ：...Z（UTC）/ ...+08:00（显式偏移）
+//
+// 归一化到 UTC 是必须的：服务端对无 TZ 的串按 UTC 裸解析，故 date / local datetime 的「本地」
+// 语义只能在 CLI 端换算；相对时间服务端也不认。空串原样返回（调用方据此跳过该过滤）。
+func normalizeTimestamp(raw string) (string, error) {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return "", nil
+	}
+	if m := reTsRelative.FindStringSubmatch(s); m != nil {
+		n, _ := strconv.Atoi(m[1])
+		var unit time.Duration
+		switch m[2] {
+		case "s":
+			unit = time.Second
+		case "m":
+			unit = time.Minute
+		case "h":
+			unit = time.Hour
+		case "d":
+			unit = 24 * time.Hour
+		case "w":
+			unit = 7 * 24 * time.Hour
+		}
+		return time.Now().Add(-time.Duration(n) * unit).UTC().Format(time.RFC3339), nil
+	}
+	if reTsDate.MatchString(s) {
+		t, err := time.ParseInLocation("2006-01-02", s, time.Local)
+		if err != nil {
+			return "", fmt.Errorf("invalid date %q", s)
+		}
+		return t.UTC().Format(time.RFC3339), nil
+	}
+	if reTsLocalDateTime.MatchString(s) {
+		t, err := time.ParseInLocation("2006-01-02T15:04:05", s, time.Local)
+		if err != nil {
+			return "", fmt.Errorf("invalid local datetime %q", s)
+		}
+		return t.UTC().Format(time.RFC3339), nil
+	}
+	if t, err := time.Parse(time.RFC3339, s); err == nil {
+		return t.UTC().Format(time.RFC3339), nil
+	}
+	return "", fmt.Errorf("invalid timestamp %q (want relative 7d/2h/30s, date 2026-04-15, datetime 2026-04-15T10:00:00, or ISO 8601 with TZ)", s)
+}
+
+// newFileTransferClient 直传 / 直下对象存储 presigned URL 用（绕开 Lark 网关，无需 auth、无超时以容纳大文件）。
+//
+//nolint:forbidigo // presigned object-storage transfer bypasses the Lark gateway — raw http.Client is required (no Lark auth, no gateway routing); not a Lark API call, so RuntimeContext.DoAPI does not apply.
+func newFileTransferClient() *http.Client {
+	return &http.Client{Transport: http.DefaultTransport}
+}
+
+// URL helpers for the file (storage) CLI commands.
+//
+// 全部走 spark OpenAPI，path 形如 /open-apis/spark/v1/apps/{app_id}/storage/<name>。
+// 路由段不含 HTTP 方法名（file_get→file、file_delete→file_batch_remove、file_quota_get→file_quota）。
+
+// appFileListPath 返回文件列表 URL：storage/file_list。
+func appFileListPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/storage/file_list", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appFileGetPath 返回单文件元数据 URL：storage/file（file_get→file，路由不含方法名）。
+func appFileGetPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/storage/file", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appFileSignPath 返回临时签名下载 URL 生成接口：storage/file_sign。
+func appFileSignPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/storage/file_sign", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appFilePreUploadPath 返回上传预处理（取 presigned 直传地址）URL：storage/file_pre_upload。
+func appFilePreUploadPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/storage/file_pre_upload", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appFileUploadCallbackPath 返回直传完成回调（登记文件）URL：storage/file_upload_callback。
+func appFileUploadCallbackPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/storage/file_upload_callback", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appFileBatchRemovePath 返回批量删除文件 URL：storage/file_batch_remove（file_delete→file_batch_remove）。
+func appFileBatchRemovePath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/storage/file_batch_remove", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appFileQuotaPath 返回存储配额查询 URL：storage/file_quota（file_quota_get→file_quota）。
+func appFileQuotaPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/storage/file_quota", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// requireFilePath trims --path and rejects blank, returning a uniform validation error.
+func requireFilePath(raw string) (string, error) {
+	p := strings.TrimSpace(raw)
+	if p == "" {
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--path is required").WithParam("--path")
+	}
+	return p, nil
+}
+
+// fileUser 是 uploaded_by 的 {id,name}。OpenAPI 以 created_by 的 JSON 字符串透传，CLI parse。
+type fileUser struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+}
+
+// fileInfo 是 file 命令对外输出的白名单字段。
+// OpenAPI 字段 created_at / created_by → CLI 产品语义 uploaded_at / uploaded_by。
+type fileInfo struct {
+	FileName    string      `json:"file_name"`
+	Path        string      `json:"path"`
+	SizeBytes   interface{} `json:"size_bytes,omitempty"`
+	Type        string      `json:"type,omitempty"`
+	UploadedBy  *fileUser   `json:"uploaded_by,omitempty"`
+	UploadedAt  string      `json:"uploaded_at,omitempty"`
+	DownloadURL string      `json:"download_url,omitempty"`
+}
+
+// projectFileInfo 把 server 原始 file map 投影为 CLI fileInfo（created_*→uploaded_*）。
+func projectFileInfo(m map[string]interface{}) fileInfo {
+	return fileInfo{
+		FileName:    common.GetString(m, "file_name"),
+		Path:        common.GetString(m, "path"),
+		SizeBytes:   m["size_bytes"],
+		Type:        common.GetString(m, "type"),
+		UploadedBy:  parseFileUser(common.GetString(m, "created_by")),
+		UploadedAt:  common.GetString(m, "created_at"),
+		DownloadURL: common.GetString(m, "download_url"),
+	}
+}
+
+// parseFileUser 解析 created_by 的 JSON 字符串 {id,name}；空 / 非法 / 全空 → nil。
+func parseFileUser(raw string) *fileUser {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return nil
+	}
+	var u fileUser
+	if err := json.Unmarshal([]byte(s), &u); err != nil {
+		return nil
+	}
+	if u.ID == "" && u.Name == "" {
+		return nil
+	}
+	return &u
+}
+
+// normalizeTimeFlags 把若干时间 flag（如 --since/--until/--uploaded-since）就地归一化为 RFC3339 UTC
+// 并回写，供 build*Params 透传。空 flag 跳过；非法格式 → validation 错误。复用 normalizeTimestamp。
+func normalizeTimeFlags(rctx *common.RuntimeContext, flags ...string) error {
+	for _, f := range flags {
+		if strings.TrimSpace(rctx.Str(f)) == "" {
+			continue
+		}
+		n, err := normalizeTimestamp(rctx.Str(f))
+		if err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--%s: %v", f, err).WithParam("--" + f)
+		}
+		_ = rctx.Cmd.Flags().Set(f, n)
+	}
+	return nil
+}
+
+// dashIfEmpty 空白串用 "—" 占位（pretty 列对齐）。
+func dashIfEmpty(s string) string {
+	if strings.TrimSpace(s) == "" {
+		return "—"
+	}
+	return s
+}
+
+// fileSizeDetail 把 size_bytes 渲染成 "24 KB (24580 bytes)"（pretty 单文件详情用）。
+func fileSizeDetail(raw interface{}) string {
+	n, ok := numericAsFloat(raw)
+	if !ok {
+		return "—"
+	}
+	return fmt.Sprintf("%s (%d bytes)", humanBytes(raw), int64(n))
+}
+
+// renderKeyValuePairs 输出对齐的 key: value（key 列按最长 key 右填充）。
+func renderKeyValuePairs(w io.Writer, pairs [][2]string) {
+	width := 0
+	for _, p := range pairs {
+		if dw := displayWidth(p[0]); dw > width {
+			width = dw
+		}
+	}
+	for _, p := range pairs {
+		io.WriteString(w, p[0]+":")
+		if pad := width - displayWidth(p[0]); pad > 0 {
+			io.WriteString(w, strings.Repeat(" ", pad))
+		}
+		io.WriteString(w, " "+p[1]+"\n")
+	}
+}

shortcuts/apps/git_credential.go

@@ -11,6 +11,7 @@ import (
 	"io"
 	"net/http"
 	"net/url"
+	"path/filepath"
 	"sort"
 	"strconv"
 	"strings"
@@ -61,7 +62,15 @@ var AppsGitCredentialInit = common.Shortcut{
 		return common.NewDryRunAPI().
 			GET(gitCredentialIssuePath).
 			Desc("Issue a Miaoda Git repository PAT").
+			Set("mode", "api-plus-local-setup").
+			Set("action", "initialize_local_git_credential").
 			Set("app_id", appID).
+			Set("metadata_file", appKeyPath(appID, gitcred.MetadataFilename)).
+			Set("local_effects", []string{
+				"save the issued PAT in the local system credential store",
+				"write app-scoped git credential metadata",
+				"configure a URL-scoped Git credential helper in global git config when possible",
+			}).
 			Params(gitCredentialIssueParams(appID))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
@@ -124,6 +133,21 @@ var AppsGitCredentialRemove = common.Shortcut{
 		}
 		return validate.ResourceName(strings.TrimSpace(rctx.Str("app-id")), "--app-id")
 	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID := strings.TrimSpace(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			Desc("Preview local Git credential cleanup (no API call; would clean up local-only state).").
+			Set("mode", "local-cleanup-only").
+			Set("action", "remove_local_git_credential").
+			Set("app_id", appID).
+			Set("metadata_file", appKeyPath(appID, gitcred.MetadataFilename)).
+			Set("effects", []string{
+				"read app-scoped git credential metadata",
+				"remove the saved PAT from the local system credential store",
+				"remove the app-scoped Git helper from global git config when present",
+				"delete the local metadata record after cleanup succeeds",
+			})
+	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		manager := newGitCredentialManager(appID, rctx.Factory.Keychain, nil)
@@ -171,6 +195,17 @@ var AppsGitCredentialList = common.Shortcut{
 	Scopes:    []string{},
 	AuthTypes: []string{"user"},
 	HasFormat: true,
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		return common.NewDryRunAPI().
+			Desc("Preview local Git credential listing (no API call, read-only local state).").
+			Set("mode", "local-read-only").
+			Set("action", "list_local_git_credentials").
+			Set("storage_root", filepath.Join(core.GetConfigDir(), storageRoot)).
+			Set("reads", []string{
+				"scan app-scoped git credential metadata under the CLI config directory",
+				"derive per-app repository URLs and local credential status from local metadata",
+			})
+	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		records, err := listGitCredentialRecords(rctx.Factory.Keychain, time.Now)
 		if err != nil {

shortcuts/apps/git_credential_test.go

@@ -45,6 +45,11 @@ func TestAppsGitCredentialInitDryRunRequestShape(t *testing.T) {
 			Params map[string]interface{} `json:"params"`
 			Body   interface{}            `json:"body"`
 		} `json:"api"`
+		Mode         string   `json:"mode"`
+		Action       string   `json:"action"`
+		AppID        string   `json:"app_id"`
+		MetadataFile string   `json:"metadata_file"`
+		LocalEffects []string `json:"local_effects"`
 	}
 	if err := json.Unmarshal([]byte(stdout.String()), &payload); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
@@ -65,6 +70,107 @@ func TestAppsGitCredentialInitDryRunRequestShape(t *testing.T) {
 	if call.Body != nil {
 		t.Fatalf("body = %#v, want nil", call.Body)
 	}
+	if payload.Mode != "api-plus-local-setup" {
+		t.Fatalf("mode = %q", payload.Mode)
+	}
+	if payload.Action != "initialize_local_git_credential" {
+		t.Fatalf("action = %q", payload.Action)
+	}
+	if payload.AppID != "app_xxx" {
+		t.Fatalf("app_id = %q", payload.AppID)
+	}
+	if !strings.HasSuffix(payload.MetadataFile, filepath.Join("spark", "app_xxx", "git.json")) {
+		t.Fatalf("metadata_file = %q", payload.MetadataFile)
+	}
+	assertStringSliceEqual(t, payload.LocalEffects, []string{
+		"save the issued PAT in the local system credential store",
+		"write app-scoped git credential metadata",
+		"configure a URL-scoped Git credential helper in global git config when possible",
+	})
+}
+
+func TestAppsGitCredentialListDryRunDescribesLocalReads(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsGitCredentialList,
+		[]string{"+git-credential-list", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var payload struct {
+		Description string        `json:"description"`
+		API         []interface{} `json:"api"`
+		Mode        string        `json:"mode"`
+		Action      string        `json:"action"`
+		StorageRoot string        `json:"storage_root"`
+		Reads       []string      `json:"reads"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &payload); err != nil {
+		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
+	}
+	if payload.Description != "Preview local Git credential listing (no API call, read-only local state)." {
+		t.Fatalf("description = %q", payload.Description)
+	}
+	if len(payload.API) != 0 {
+		t.Fatalf("api len = %d, want 0", len(payload.API))
+	}
+	if payload.Mode != "local-read-only" {
+		t.Fatalf("mode = %q", payload.Mode)
+	}
+	if payload.Action != "list_local_git_credentials" {
+		t.Fatalf("action = %q", payload.Action)
+	}
+	if !strings.HasSuffix(payload.StorageRoot, filepath.Join("spark")) {
+		t.Fatalf("storage_root = %q", payload.StorageRoot)
+	}
+	assertStringSliceEqual(t, payload.Reads, []string{
+		"scan app-scoped git credential metadata under the CLI config directory",
+		"derive per-app repository URLs and local credential status from local metadata",
+	})
+}
+
+func TestAppsGitCredentialRemoveDryRunDescribesLocalCleanup(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsGitCredentialRemove,
+		[]string{"+git-credential-remove", "--app-id", "app_xxx", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var payload struct {
+		Description  string        `json:"description"`
+		API          []interface{} `json:"api"`
+		Mode         string        `json:"mode"`
+		Action       string        `json:"action"`
+		AppID        string        `json:"app_id"`
+		MetadataFile string        `json:"metadata_file"`
+		Effects      []string      `json:"effects"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &payload); err != nil {
+		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
+	}
+	if payload.Description != "Preview local Git credential cleanup (no API call; would clean up local-only state)." {
+		t.Fatalf("description = %q", payload.Description)
+	}
+	if len(payload.API) != 0 {
+		t.Fatalf("api len = %d, want 0", len(payload.API))
+	}
+	if payload.Mode != "local-cleanup-only" {
+		t.Fatalf("mode = %q", payload.Mode)
+	}
+	if payload.Action != "remove_local_git_credential" {
+		t.Fatalf("action = %q", payload.Action)
+	}
+	if payload.AppID != "app_xxx" {
+		t.Fatalf("app_id = %q", payload.AppID)
+	}
+	if !strings.HasSuffix(payload.MetadataFile, filepath.Join("spark", "app_xxx", "git.json")) {
+		t.Fatalf("metadata_file = %q", payload.MetadataFile)
+	}
+	assertStringSliceEqual(t, payload.Effects, []string{
+		"read app-scoped git credential metadata",
+		"remove the saved PAT from the local system credential store",
+		"remove the app-scoped Git helper from global git config when present",
+		"delete the local metadata record after cleanup succeeds",
+	})
 }
 
 func TestAppsGitCredentialInitRequiresAppID(t *testing.T) {
@@ -579,6 +685,18 @@ func TestAppsGitCredentialRemoveReturnsStoreError(t *testing.T) {
 	}
 }
 
+func assertStringSliceEqual(t *testing.T, got, want []string) {
+	t.Helper()
+	if len(got) != len(want) {
+		t.Fatalf("slice len = %d, want %d; got %#v", len(got), len(want), got)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("slice[%d] = %q, want %q; got %#v", i, got[i], want[i], got)
+		}
+	}
+}
+
 func TestGitCredentialLocalErrorWrapsOnlyPlainErrors(t *testing.T) {
 	plain := errors.New("git config failed")
 	wrapped := gitCredentialLocalError("List local Miaoda Git credentials", plain)

shortcuts/apps/shortcuts.go

@@ -23,6 +23,25 @@ func Shortcuts() []common.Shortcut {
 		AppsDBTableGet,
 		AppsDBExecute,
 		AppsDBEnvCreate,
+		AppsDBDataImport,
+		AppsDBDataExport,
+		AppsDBChangelogList,
+		AppsDBAuditStatus,
+		AppsDBAuditEnable,
+		AppsDBAuditDisable,
+		AppsDBAuditList,
+		AppsDBEnvDiff,
+		AppsDBEnvMigrate,
+		AppsDBRecoveryDiff,
+		AppsDBRecoveryApply,
+		AppsDBQuotaGet,
+		AppsFileList,
+		AppsFileGet,
+		AppsFileSign,
+		AppsFileDownload,
+		AppsFileUpload,
+		AppsFileDelete,
+		AppsFileQuotaGet,
 		AppsGitCredentialInit,
 		AppsGitCredentialList,
 		AppsGitCredentialRemove,

shortcuts/apps/shortcuts_test.go

@@ -10,12 +10,16 @@ import (
 )
 
 // 钉死域内 shortcut 数量。少一条（漏挂）或多一条（误加）都会被这个测试拦截。
-// 6 基础 + 1 init + 3 publish + 1 env-pull + 4 db（table-list/table-schema/sql/dev-init）
-// + 3 git-credential + 5 session（create/list/get/stop/chat）= 23。
-func TestAppsShortcuts_Returns23(t *testing.T) {
+// 6 基础 + 1 init + 3 publish + 1 env-pull
+//   - 16 db（table-list/table-schema/sql/dev-init/data-import/data-export/changelog-list/
+//     audit-status/audit-enable/audit-disable/audit-list/
+//     env-diff/env-migrate/recovery-diff/recovery-apply/quota-get）
+//   - 3 git-credential + 5 session（create/list/get/stop/chat）
+//   - 7 file（list/get/sign/download/upload/delete/quota-get）= 42。
+func TestAppsShortcuts_Returns42(t *testing.T) {
 	got := Shortcuts()
-	if len(got) != 23 {
-		t.Fatalf("Shortcuts() returned %d entries, want 23", len(got))
+	if len(got) != 42 {
+		t.Fatalf("Shortcuts() returned %d entries, want 42", len(got))
 	}
 }
 
@@ -40,6 +44,7 @@ func TestAppsShortcuts_IncludesSessionCommands(t *testing.T) {
 	}
 }
 
+// TestAppsGitCredentialHelper_IsNotAShortcut 确认 git credential helper 不作为 shortcut 暴露。
 func TestAppsGitCredentialHelper_IsNotAShortcut(t *testing.T) {
 	for _, shortcut := range Shortcuts() {
 		if shortcut.Command == "git-credential-helper" {
@@ -48,18 +53,21 @@ func TestAppsGitCredentialHelper_IsNotAShortcut(t *testing.T) {
 	}
 }
 
+// TestAppsGitCredentialRemove_IsLocalCleanupWithoutScopes 确认 git credential remove 是本地清理、不带任何 scope。
 func TestAppsGitCredentialRemove_IsLocalCleanupWithoutScopes(t *testing.T) {
 	if len(AppsGitCredentialRemove.Scopes) != 0 {
 		t.Fatalf("git credential remove scopes = %#v, want none for local cleanup", AppsGitCredentialRemove.Scopes)
 	}
 }
 
+// TestAppsGitCredentialList_IsLocalReadWithoutScopes 确认 git credential list 是本地读取、不带任何 scope。
 func TestAppsGitCredentialList_IsLocalReadWithoutScopes(t *testing.T) {
 	if len(AppsGitCredentialList.Scopes) != 0 {
 		t.Fatalf("git credential list scopes = %#v, want none for local read", AppsGitCredentialList.Scopes)
 	}
 }
 
+// TestInstallOnApps_AddsHiddenGitCredentialHelper 验证 InstallOnApps 挂载一个隐藏、带 RunE 且独立于 shortcut 管线的 git-credential-helper 命令。
 func TestInstallOnApps_AddsHiddenGitCredentialHelper(t *testing.T) {
 	parent := &cobra.Command{Use: "apps"}
 	InstallOnApps(parent, nil)

shortcuts/common/runner.go

@@ -407,6 +407,8 @@ func (ctx *RuntimeContext) StreamPages(method, url string, params map[string]int
 	return ac.StreamPages(ctx.ctx, req, onItems, opts)
 }
 
+// buildRequest assembles a client.RawApiRequest for the current identity,
+// attaching any shortcut-scoped header options carried on the context.
 func (ctx *RuntimeContext) buildRequest(method, url string, params map[string]interface{}, data interface{}) client.RawApiRequest {
 	req := client.RawApiRequest{
 		Method: method,
@@ -421,6 +423,8 @@ func (ctx *RuntimeContext) buildRequest(method, url string, params map[string]in
 	return req
 }
 
+// callRaw issues the request via the cached APIClient.CallAPI and returns the
+// raw result; it is the shared transport behind CallAPI and RawAPI.
 func (ctx *RuntimeContext) callRaw(method, url string, params map[string]interface{}, data interface{}) (interface{}, error) {
 	ac, err := ctx.getAPIClient()
 	if err != nil {
@@ -514,6 +518,8 @@ func (ctx *RuntimeContext) DoAPIJSONTyped(method, apiPath string, query larkcore
 	return ctx.ClassifyAPIResponse(resp)
 }
 
+// doAPIJSON issues an API request and decodes the response into a JSON map, mapping
+// HTTP/business errors to typed output errors (optionally attaching the log id when includeLogID).
 func (ctx *RuntimeContext) doAPIJSON(method, apiPath string, query larkcore.QueryParams, body any, includeLogID bool) (map[string]any, error) {
 	req := &larkcore.ApiReq{
 		HttpMethod:  method,
@@ -588,6 +594,20 @@ func (ctx *RuntimeContext) IO() *cmdutil.IOStreams {
 	return ctx.Factory.IOStreams
 }
 
+// StartSpinner shows a braille spinner with elapsed time on stderr for a slow
+// operation, until the returned stop() runs. It is a no-op unless stderr is an
+// interactive terminal, so pipes / CI / captured output emit nothing and stdout
+// (JSON/pretty) is never polluted — hence it is shown in JSON mode too. Call
+// stop() before printing the result; stop() is safe to call multiple times
+// (e.g. `defer stop()` plus an explicit call on the success path).
+func (ctx *RuntimeContext) StartSpinner(label string) func() {
+	io := ctx.IO()
+	if io == nil {
+		return func() {}
+	}
+	return output.StartSpinner(io.ErrOut, io.ErrIsTerminal, label)
+}
+
 // FileIO resolves the FileIO using the current execution context.
 // Falls back to the globally registered provider when Factory or its
 // FileIOProvider is nil (e.g. in lightweight test helpers).
@@ -807,6 +827,8 @@ func (ctx *RuntimeContext) OutFormatRaw(data interface{}, meta *output.Meta, pre
 	ctx.outFormat(data, meta, prettyFn, true)
 }
 
+// outFormat renders data according to ctx.Format (pretty/json/table/csv/ndjson), running the
+// safety scan and pretty renderer for pretty mode; raw selects the unwrapped output sink.
 func (ctx *RuntimeContext) outFormat(data interface{}, meta *output.Meta, prettyFn func(w io.Writer), raw bool) {
 	outFn := ctx.Out
 	if raw {
@@ -917,12 +939,17 @@ func (s Shortcut) Mount(parent *cobra.Command, f *cmdutil.Factory) {
 	s.MountWithContext(context.Background(), parent, f)
 }
 
+// MountWithContext registers the shortcut on parent using the given context,
+// dispatching to mountDeclarative when the shortcut defines an Execute func.
 func (s Shortcut) MountWithContext(ctx context.Context, parent *cobra.Command, f *cmdutil.Factory) {
 	if s.Execute != nil {
 		s.mountDeclarative(ctx, parent, f)
 	}
 }
 
+// mountDeclarative builds the cobra.Command for a declarative shortcut — wiring
+// RunE to runShortcut, registering flags, identities, tips and risk, and adding
+// it to parent — defaulting AuthTypes to user and deriving the bot-only flag.
 func (s Shortcut) mountDeclarative(ctx context.Context, parent *cobra.Command, f *cmdutil.Factory) {
 	shortcut := s
 	if len(shortcut.AuthTypes) == 0 {
@@ -1050,6 +1077,8 @@ func runShortcut(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut, botOnly bo
 	return rctx.outputErr
 }
 
+// resolveShortcutIdentity determines the effective identity (--as > default-as >
+// auto-detect), enforces strict mode, and verifies the shortcut supports it.
 func resolveShortcutIdentity(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut) (core.Identity, error) {
 	// Step 1: determine identity (--as > default-as > auto-detect).
 	asFlag, _ := cmd.Flags().GetString("as")
@@ -1066,6 +1095,9 @@ func resolveShortcutIdentity(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut
 	return as, nil
 }
 
+// checkShortcutScopes runs the pre-flight scope check for the resolved identity,
+// returning a typed PermissionError (with a login hint) when scopes are missing;
+// it is a no-op when no scopes are required or scope metadata is unavailable.
 func checkShortcutScopes(f *cmdutil.Factory, ctx context.Context, as core.Identity, config *core.CliConfig, scopes []string) error {
 	if len(scopes) == 0 {
 		return nil
@@ -1084,6 +1116,9 @@ func checkShortcutScopes(f *cmdutil.Factory, ctx context.Context, as core.Identi
 		WithHint("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(missing, " "))
 }
 
+// newRuntimeContext builds a RuntimeContext for a shortcut invocation: it seeds
+// the shortcut context, lazily wires the API client and bot-info providers,
+// eagerly initializes the Lark SDK, and reads the format and jq flags.
 func newRuntimeContext(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut, config *core.CliConfig, as core.Identity, botOnly bool) (*RuntimeContext, error) {
 	ctx := cmd.Context()
 	ctx = cmdutil.ContextWithShortcut(ctx, s.Service+":"+s.Command, uuid.New().String())
@@ -1186,6 +1221,8 @@ func resolveInputFlags(rctx *RuntimeContext, flags []Flag) error {
 	return nil
 }
 
+// validateEnumFlags checks that every flag with an Enum constraint holds an
+// allowed value, returning a validation error naming the flag otherwise.
 func validateEnumFlags(rctx *RuntimeContext, flags []Flag) error {
 	for _, fl := range flags {
 		if len(fl.Enum) == 0 {
@@ -1210,6 +1247,8 @@ func validateEnumFlags(rctx *RuntimeContext, flags []Flag) error {
 	return nil
 }
 
+// handleShortcutDryRun runs the shortcut's DryRun hook and prints its result
+// (pretty or JSON per --format), erroring if the shortcut declares no DryRun.
 func handleShortcutDryRun(f *cmdutil.Factory, rctx *RuntimeContext, s *Shortcut) error {
 	if s.DryRun == nil {
 		return ValidationErrorf("--dry-run is not supported for %s %s", s.Service, s.Command).
@@ -1238,10 +1277,16 @@ func rejectPositionalArgs() cobra.PositionalArgs {
 	}
 }
 
+// registerShortcutFlags registers the shortcut's flags using a background
+// context; a convenience wrapper over registerShortcutFlagsWithContext.
 func registerShortcutFlags(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut) {
 	registerShortcutFlagsWithContext(context.Background(), cmd, f, s)
 }
 
+// registerShortcutFlagsWithContext declares all of the shortcut's flags on cmd —
+// typed flags with enum/input hints, completions, required and hidden markers —
+// plus the framework flags (--dry-run, --format/--json, --jq, identity, and the
+// --print-schema/--flag-name introspection flags when opted in).
 func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut) {
 	for _, fl := range s.Flags {
 		desc := fl.Desc

shortcuts/whiteboard/whiteboard_query.go

@@ -184,10 +184,7 @@ func fetchWhiteboardNodes(runtime *common.RuntimeContext, wbToken string) (*wbNo
 		return nil, err
 	}
 	var nodes wbNodesResp
-	rawNodes, ok := data["nodes"]
-	if !ok {
-		return nil, wbInvalidResponse("get whiteboard nodes failed: missing data.nodes")
-	}
+	rawNodes, _ := data["nodes"]
 	if rawNodes != nil {
 		var ok bool
 		nodes.Data.Nodes, ok = rawNodes.([]interface{})

shortcuts/whiteboard/whiteboard_query_test.go

@@ -848,11 +848,6 @@ func TestFetchWhiteboardNodes_InvalidResponseTypedError(t *testing.T) {
 		token string
 		data  map[string]interface{}
 	}{
-		{
-			name:  "missing nodes",
-			token: "test-token-missing-nodes",
-			data:  map[string]interface{}{},
-		},
 		{
 			name:  "nodes not array",
 			token: "test-token-bad-nodes",
@@ -880,6 +875,32 @@ func TestFetchWhiteboardNodes_InvalidResponseTypedError(t *testing.T) {
 	}
 }
 
+// TestFetchWhiteboardNodes_MissingNodesIsEmpty verifies that a response with
+// missing nodes field is treated as an empty whiteboard (success), not an error.
+// This matches the behavior introduced in commit 4b39b037.
+func TestFetchWhiteboardNodes_MissingNodesIsEmpty(t *testing.T) {
+	factory, stdout, reg := newExecuteFactory(t)
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/board/v1/whiteboards/test-token-missing-nodes/nodes",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "success",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	args := []string{"+query", "--whiteboard-token", "test-token-missing-nodes", "--output_as", "raw"}
+	if err := runShortcut(t, WhiteboardQuery, args, factory, stdout); err != nil {
+		t.Fatalf("expected success for missing nodes (empty whiteboard), got err=%v", err)
+	}
+
+	if !strings.Contains(stdout.String(), "whiteboard is empty") {
+		t.Fatalf("stdout missing empty whiteboard message: %s", stdout.String())
+	}
+}
+
 func assertInvalidResponse(t *testing.T, err error) {
 	t.Helper()
 	if err == nil {

shortcuts/wiki/wiki_async_task.go

@@ -5,12 +5,11 @@ package wiki
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -95,7 +94,7 @@ func (s wikiAsyncTaskStatus) StatusLabel() string {
 }
 
 // wikiAsyncTaskFetcher returns the latest status for taskID. Implementations
-// translate from runtime.CallAPI responses or test fakes.
+// translate from runtime.CallAPITyped responses or test fakes.
 type wikiAsyncTaskFetcher func(ctx context.Context, taskID string) (wikiAsyncTaskStatus, error)
 
 // parseWikiAsyncTaskStatus normalizes an /wiki/v2/tasks/{task_id} payload.
@@ -103,7 +102,7 @@ type wikiAsyncTaskFetcher func(ctx context.Context, taskID string) (wikiAsyncTas
 // "simple_task_result" for delete-node).
 func parseWikiAsyncTaskStatus(taskID string, task map[string]interface{}, resultKey string) (wikiAsyncTaskStatus, error) {
 	if task == nil {
-		return wikiAsyncTaskStatus{}, output.Errorf(output.ExitAPI, "api_error", "wiki task response missing task")
+		return wikiAsyncTaskStatus{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki task response missing task")
 	}
 
 	result := common.GetMap(task, resultKey)
@@ -167,7 +166,7 @@ func pollWikiAsyncTask(
 			return status, true, nil
 		}
 		if status.Failed() {
-			return status, false, output.Errorf(output.ExitAPI, "api_error", "wiki %s task %s failed: %s", label, taskID, status.StatusLabel())
+			return status, false, errs.NewAPIError(errs.SubtypeServerError, "wiki %s task %s failed: %s", label, taskID, status.StatusLabel())
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Wiki %s status %d/%d: %s\n", label, attempt, attempts, status.StatusLabel())
@@ -178,29 +177,18 @@ func pollWikiAsyncTask(
 			"the wiki %s task was created but every status poll failed (task_id=%s)\nretry status lookup with: %s",
 			label, taskID, nextCommand,
 		)
-		var exitErr *output.ExitError
-		if errors.As(lastErr, &exitErr) && exitErr.Detail != nil {
-			if strings.TrimSpace(exitErr.Detail.Hint) != "" {
-				hint = exitErr.Detail.Hint + "\n" + hint
-			}
-			// ErrWithHint rebuilds the error and drops the upstream Lark
-			// Detail.Code / ConsoleURL / Risk / nested Detail. Build the
-			// ExitError by hand so the original API code survives a fully
-			// failed poll, matching wrapWikiNodeDeleteAPIError.
-			return lastStatus, false, &output.ExitError{
-				Code: exitErr.Code,
-				Detail: &output.ErrDetail{
-					Type:       exitErr.Detail.Type,
-					Code:       exitErr.Detail.Code,
-					Message:    exitErr.Detail.Message,
-					Hint:       hint,
-					ConsoleURL: exitErr.Detail.ConsoleURL,
-					Risk:       exitErr.Detail.Risk,
-					Detail:     exitErr.Detail.Detail,
-				},
+		// The poll error comes from a typed CallAPITyped path; append the resume
+		// hint in place so the original category / subtype / code / log_id
+		// survives a fully failed poll (per ERROR_CONTRACT.md "propagate typed
+		// errors unchanged"), matching wrapWikiNodeDeleteAPIError.
+		if p, ok := errs.ProblemOf(lastErr); ok {
+			if strings.TrimSpace(p.Hint) != "" {
+				hint = p.Hint + "\n" + hint
 			}
+			p.Hint = hint
+			return lastStatus, false, lastErr
 		}
-		return lastStatus, false, output.ErrWithHint(output.ExitAPI, "api_error", lastErr.Error(), hint)
+		return lastStatus, false, errs.NewInternalError(errs.SubtypeUnknown, "%s", lastErr.Error()).WithHint("%s", hint).WithCause(lastErr)
 	}
 
 	return lastStatus, false, nil

shortcuts/wiki/wiki_async_task_test.go

@@ -10,8 +10,8 @@ import (
 	"testing"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
 )
 
 // pollWikiAsyncTask is shared infrastructure for every wiki delete shortcut,
@@ -88,45 +88,54 @@ func TestPollWikiAsyncTaskAllPollsFailWrapsWithResumeHint(t *testing.T) {
 	t.Parallel()
 
 	runtime, stderr := newWikiNodeDeleteRuntime(t, core.AsUser)
+	transportErr := errors.New("transport boom")
 	_, ready, err := pollWikiAsyncTask(
 		context.Background(), runtime, "task_lost", "delete-node", 2, 0,
 		func(context.Context, string) (wikiAsyncTaskStatus, error) {
-			return wikiAsyncTaskStatus{}, errors.New("transport boom")
+			return wikiAsyncTaskStatus{}, transportErr
 		},
 		"lark-cli drive +task_result --task-id task_lost",
 	)
 	if ready {
 		t.Fatalf("ready = true, want false when every poll failed")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("err = %T %v, want *output.ExitError with detail", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("err = %T %v, want a typed errs.* error", err, err)
 	}
-	if exitErr.Code != output.ExitAPI {
-		t.Fatalf("exit code = %d, want ExitAPI", exitErr.Code)
+	if p.Subtype != errs.SubtypeUnknown {
+		t.Fatalf("subtype = %q, want unknown for an untyped poll failure", p.Subtype)
 	}
-	if !strings.Contains(exitErr.Detail.Hint, "every status poll failed (task_id=task_lost)") ||
-		!strings.Contains(exitErr.Detail.Hint, "lark-cli drive +task_result --task-id task_lost") {
-		t.Fatalf("hint = %q, want resume guidance naming the task", exitErr.Detail.Hint)
+	if !errors.Is(err, transportErr) {
+		t.Fatalf("err does not preserve the transport cause: %v", err)
+	}
+	if !strings.Contains(p.Hint, "every status poll failed (task_id=task_lost)") ||
+		!strings.Contains(p.Hint, "lark-cli drive +task_result --task-id task_lost") {
+		t.Fatalf("hint = %q, want resume guidance naming the task", p.Hint)
 	}
 	if !strings.Contains(stderr.String(), "attempt 2/2 failed") {
 		t.Fatalf("stderr = %q, want per-attempt progress", stderr.String())
 	}
 }
 
+func TestParseWikiAsyncTaskStatusRejectsNilTask(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiAsyncTaskStatus("task_x", nil, "delete_space_result")
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+		t.Fatalf("expected internal/invalid_response, got %v", err)
+	}
+}
+
 func TestPollWikiAsyncTaskPrependsUpstreamExitHint(t *testing.T) {
 	t.Parallel()
 
 	runtime, _ := newWikiNodeDeleteRuntime(t, core.AsUser)
-	upstream := &output.ExitError{
-		Code: output.ExitAPI,
-		Detail: &output.ErrDetail{
-			Type:    "permission",
-			Code:    99991663,
-			Message: "permission denied",
-			Hint:    "grant the wiki:node:retrieve scope",
-		},
-	}
+	// The upstream poll error is a typed error carrying its own hint, mirroring
+	// what runtime.CallAPITyped produces for a permission failure.
+	upstream := errs.NewPermissionError(errs.SubtypePermissionDenied, "permission denied").
+		WithHint("grant the wiki:node:retrieve scope")
 	_, _, err := pollWikiAsyncTask(
 		context.Background(), runtime, "task_perm", "delete-node", 1, 0,
 		func(context.Context, string) (wikiAsyncTaskStatus, error) {
@@ -134,23 +143,23 @@ func TestPollWikiAsyncTaskPrependsUpstreamExitHint(t *testing.T) {
 		},
 		"resume-cmd",
 	)
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("err = %T %v, want *output.ExitError", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("err = %T %v, want a typed errs.* error", err, err)
 	}
 	// The upstream hint must lead so the actionable cause is read first, with
-	// the resume guidance appended. Type and exit code propagate from upstream.
-	if !strings.HasPrefix(exitErr.Detail.Hint, "grant the wiki:node:retrieve scope\n") {
-		t.Fatalf("hint = %q, want upstream hint prepended", exitErr.Detail.Hint)
+	// the resume guidance appended. The original typed error propagates in place.
+	if !strings.HasPrefix(p.Hint, "grant the wiki:node:retrieve scope\n") {
+		t.Fatalf("hint = %q, want upstream hint prepended", p.Hint)
 	}
-	if !strings.Contains(exitErr.Detail.Hint, "resume-cmd") {
-		t.Fatalf("hint = %q, want resume command appended", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "resume-cmd") {
+		t.Fatalf("hint = %q, want resume command appended", p.Hint)
 	}
-	if exitErr.Detail.Type != "permission" || exitErr.Code != output.ExitAPI {
-		t.Fatalf("exitErr = %+v, want permission/ExitAPI propagated", exitErr)
+	if p.Subtype != errs.SubtypePermissionDenied {
+		t.Fatalf("subtype = %q, want permission_denied propagated", p.Subtype)
 	}
-	if exitErr.Detail.Message != "permission denied" {
-		t.Fatalf("message = %q, want upstream message preserved", exitErr.Detail.Message)
+	if p.Message != "permission denied" {
+		t.Fatalf("message = %q, want upstream message preserved", p.Message)
 	}
 }
 

shortcuts/wiki/wiki_delete.go

@@ -9,8 +9,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -89,7 +89,7 @@ type wikiDeleteSpaceAPI struct {
 }
 
 func (api wikiDeleteSpaceAPI) DeleteSpace(ctx context.Context, spaceID string) (*wikiDeleteSpaceResponse, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"DELETE",
 		fmt.Sprintf("/open-apis/wiki/v2/spaces/%s", validate.EncodePathSegment(spaceID)),
 		nil,
@@ -104,7 +104,7 @@ func (api wikiDeleteSpaceAPI) DeleteSpace(ctx context.Context, spaceID string) (
 }
 
 func (api wikiDeleteSpaceAPI) GetDeleteSpaceTask(ctx context.Context, taskID string) (wikiDeleteSpaceTaskStatus, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"GET",
 		fmt.Sprintf("/open-apis/wiki/v2/tasks/%s", validate.EncodePathSegment(taskID)),
 		map[string]interface{}{"task_type": "delete_space"},
@@ -124,7 +124,7 @@ func readWikiDeleteSpaceSpec(runtime *common.RuntimeContext) wikiDeleteSpaceSpec
 
 func validateWikiDeleteSpaceSpec(spec wikiDeleteSpaceSpec) error {
 	if spec.SpaceID == "" {
-		return output.ErrValidation("--space-id is required")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--space-id is required").WithParam("--space-id")
 	}
 	return validateOptionalResourceName(spec.SpaceID, "--space-id")
 }

shortcuts/wiki/wiki_delete_test.go

@@ -6,7 +6,6 @@ package wiki
 import (
 	"bytes"
 	"context"
-	"errors"
 	"reflect"
 	"strings"
 	"sync"
@@ -14,11 +13,12 @@ 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/credential"
+	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -266,19 +266,18 @@ func TestPollWikiDeleteSpaceTaskWrapsPollFailuresWithHint(t *testing.T) {
 	withSingleWikiDeleteSpacePoll(t)
 
 	runtime, stderr := newWikiDeleteSpaceRuntimeWithScopes(t, core.AsUser, "")
-	// Seed an error that carries an upstream Lark Detail.Code so the test
+	// Seed a typed error that carries an upstream Lark code and hint so the test
 	// pins that structured fields survive a fully failed poll (not just the
-	// hint). ErrWithHint drops Detail.Code, which is exactly what we fixed.
+	// hint): the poll-exhaustion path must propagate the typed error in place.
+	seeded := errclass.BuildAPIError(
+		map[string]any{"code": float64(131006), "msg": "poll failed"},
+		errclass.ClassifyContext{},
+	)
+	if p, ok := errs.ProblemOf(seeded); ok {
+		p.Hint = "retry original"
+	}
 	client := &fakeWikiDeleteSpaceClient{
-		taskErrs: []error{&output.ExitError{
-			Code: output.ExitAPI,
-			Detail: &output.ErrDetail{
-				Type:    "api_error",
-				Code:    131006,
-				Message: "poll failed",
-				Hint:    "retry original",
-			},
-		}},
+		taskErrs: []error{seeded},
 	}
 
 	status, ready, err := pollWikiDeleteSpaceTask(context.Background(), client, runtime, "task_123")
@@ -291,15 +290,15 @@ func TestPollWikiDeleteSpaceTaskWrapsPollFailuresWithHint(t *testing.T) {
 	if status.TaskID != "task_123" {
 		t.Fatalf("status.TaskID = %q, want %q", status.TaskID, "task_123")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected structured exit error, got %T %v", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected a typed errs.* error, got %T %v", err, err)
 	}
-	if !strings.Contains(exitErr.Detail.Hint, "retry original") || !strings.Contains(exitErr.Detail.Hint, wikiDeleteSpaceTaskResultCommand("task_123", core.AsUser)) {
-		t.Fatalf("hint = %q, want original hint and resume command", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "retry original") || !strings.Contains(p.Hint, wikiDeleteSpaceTaskResultCommand("task_123", core.AsUser)) {
+		t.Fatalf("hint = %q, want original hint and resume command", p.Hint)
 	}
-	if exitErr.Detail.Code != 131006 {
-		t.Fatalf("Detail.Code = %d, want 131006 preserved through poll exhaustion", exitErr.Detail.Code)
+	if p.Code != 131006 {
+		t.Fatalf("Code = %d, want 131006 preserved through poll exhaustion", p.Code)
 	}
 	if !strings.Contains(stderr.String(), "Wiki delete-space status attempt 1/1 failed") {
 		t.Fatalf("stderr = %q, want poll failure log", stderr.String())

shortcuts/wiki/wiki_list_copy_test.go

@@ -351,6 +351,7 @@ func TestWikiNodeCopyRequiresTargetSpaceOrParent(t *testing.T) {
 	if err == nil || !strings.Contains(err.Error(), "--target-space-id or --target-parent-node-token") {
 		t.Fatalf("expected target validation error, got %v", err)
 	}
+	requireWikiValidationParams(t, err, "--target-space-id", "--target-parent-node-token")
 }
 
 func TestWikiNodeCopyRejectsBothTargetFlags(t *testing.T) {
@@ -365,6 +366,7 @@ func TestWikiNodeCopyRejectsBothTargetFlags(t *testing.T) {
 	if err == nil || !strings.Contains(err.Error(), "mutually exclusive") {
 		t.Fatalf("expected mutually exclusive error, got %v", err)
 	}
+	requireWikiValidationParams(t, err, "--target-space-id", "--target-parent-node-token")
 }
 
 // TestWikiNodeCopyDeclaredHighRiskWrite pins down the high-risk-write

shortcuts/wiki/wiki_member_add.go

@@ -8,7 +8,7 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -65,7 +65,7 @@ var WikiMemberAdd = common.Shortcut{
 			common.MaskToken(spec.MemberID), spec.MemberType, spec.MemberRole, common.MaskToken(spaceID))
 
 		path := fmt.Sprintf("/open-apis/wiki/v2/spaces/%s/members", validate.EncodePathSegment(spaceID))
-		data, err := runtime.CallAPI("POST", path, spec.QueryParams(), spec.RequestBody())
+		data, err := runtime.CallAPITyped("POST", path, spec.QueryParams(), spec.RequestBody())
 		if err != nil {
 			return err
 		}
@@ -131,16 +131,16 @@ func readWikiMemberAddSpec(runtime *common.RuntimeContext) (wikiMemberAddSpec, e
 		return wikiMemberAddSpec{}, err
 	}
 	if spec.MemberID == "" {
-		return wikiMemberAddSpec{}, output.ErrValidation("--member-id is required and cannot be blank")
+		return wikiMemberAddSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--member-id is required and cannot be blank").WithParam("--member-id")
 	}
 	// The space-member API rejects opendepartmentid grants under a
 	// tenant_access_token; surface that as a CLI validation error so callers do
 	// not waste a network round-trip on a server-side 403. The escape hatch is
 	// --as user, which is the only identity the API accepts for departments.
 	if runtime.As().IsBot() && spec.MemberType == "opendepartmentid" {
-		return wikiMemberAddSpec{}, output.ErrValidation(
+		return wikiMemberAddSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 			"--as bot does not support --member-type opendepartmentid; rerun with --as user",
-		)
+		).WithParam("--member-type")
 	}
 	// --member-type / --member-role enum membership is enforced by the
 	// framework's validateEnumFlags (runner.go) before Validate runs, so no

shortcuts/wiki/wiki_member_helpers.go

@@ -6,7 +6,7 @@ package wiki
 import (
 	"fmt"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -27,10 +27,10 @@ var wikiMemberRoles = []string{"admin", "member"}
 //     tenant_access_token; same contract as +node-list / +node-create)
 func validateWikiMemberSpaceID(runtime *common.RuntimeContext, spaceID string) error {
 	if spaceID == "" {
-		return output.ErrValidation("--space-id is required and cannot be blank")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--space-id is required and cannot be blank").WithParam("--space-id")
 	}
 	if runtime.As().IsBot() && spaceID == wikiMyLibrarySpaceID {
-		return output.ErrValidation("bot identity does not support --space-id my_library; use an explicit --space-id")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "bot identity does not support --space-id my_library; use an explicit --space-id").WithParam("--space-id")
 	}
 	return validateOptionalResourceName(spaceID, "--space-id")
 }

shortcuts/wiki/wiki_member_list.go

@@ -122,7 +122,7 @@ func fetchWikiMembers(runtime *common.RuntimeContext, spaceID string) ([]map[str
 		if pageToken != "" {
 			params["page_token"] = pageToken
 		}
-		data, err := runtime.CallAPI("GET", apiPath, params, nil)
+		data, err := runtime.CallAPITyped("GET", apiPath, params, nil)
 		if err != nil {
 			return nil, false, "", err
 		}

shortcuts/wiki/wiki_member_remove.go

@@ -8,7 +8,7 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -68,7 +68,7 @@ var WikiMemberRemove = common.Shortcut{
 			validate.EncodePathSegment(spaceID),
 			validate.EncodePathSegment(spec.MemberID),
 		)
-		data, err := runtime.CallAPI("DELETE", path, nil, spec.RequestBody())
+		data, err := runtime.CallAPITyped("DELETE", path, nil, spec.RequestBody())
 		if err != nil {
 			return err
 		}
@@ -122,7 +122,7 @@ func readWikiMemberRemoveSpec(runtime *common.RuntimeContext) (wikiMemberRemoveS
 		return wikiMemberRemoveSpec{}, err
 	}
 	if spec.MemberID == "" {
-		return wikiMemberRemoveSpec{}, output.ErrValidation("--member-id is required and cannot be blank")
+		return wikiMemberRemoveSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--member-id is required and cannot be blank").WithParam("--member-id")
 	}
 	// Enum membership for --member-type / --member-role is enforced by the
 	// framework's validateEnumFlags (runner.go) before Validate runs.

shortcuts/wiki/wiki_move.go

@@ -5,13 +5,12 @@ package wiki
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -65,7 +64,7 @@ var WikiMove = common.Shortcut{
 		// for a tenant_access_token (--as bot), so reject early with a clear
 		// hint instead of letting the API return a confusing error.
 		if runtime.As().IsBot() && spec.TargetSpaceID == wikiMyLibrarySpaceID {
-			return output.ErrValidation("--target-space-id my_library is a per-user personal library alias and cannot be used with --as bot; resolve it to a real space_id first via `lark-cli wiki spaces get --params '{\"space_id\":\"my_library\"}' --as user`")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--target-space-id my_library is a per-user personal library alias and cannot be used with --as bot; resolve it to a real space_id first via `lark-cli wiki spaces get --params '{\"space_id\":\"my_library\"}' --as user`").WithParam("--target-space-id")
 		}
 		return validateWikiMoveSpec(spec)
 	},
@@ -230,7 +229,7 @@ type wikiMoveAPI struct {
 }
 
 func (api wikiMoveAPI) GetNode(ctx context.Context, token string) (*wikiNodeRecord, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"GET",
 		"/open-apis/wiki/v2/spaces/get_node",
 		map[string]interface{}{"token": token},
@@ -243,7 +242,7 @@ func (api wikiMoveAPI) GetNode(ctx context.Context, token string) (*wikiNodeReco
 }
 
 func (api wikiMoveAPI) MoveNode(ctx context.Context, sourceSpaceID string, spec wikiMoveSpec) (*wikiNodeRecord, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"POST",
 		fmt.Sprintf(
 			"/open-apis/wiki/v2/spaces/%s/nodes/%s/move",
@@ -260,7 +259,7 @@ func (api wikiMoveAPI) MoveNode(ctx context.Context, sourceSpaceID string, spec
 }
 
 func (api wikiMoveAPI) MoveDocsToWiki(ctx context.Context, targetSpaceID string, spec wikiMoveSpec) (*wikiMoveDocsResponse, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"POST",
 		fmt.Sprintf(
 			"/open-apis/wiki/v2/spaces/%s/nodes/move_docs_to_wiki",
@@ -281,7 +280,7 @@ func (api wikiMoveAPI) MoveDocsToWiki(ctx context.Context, targetSpaceID string,
 }
 
 func (api wikiMoveAPI) GetMoveTask(ctx context.Context, taskID string) (wikiMoveTaskStatus, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"GET",
 		fmt.Sprintf("/open-apis/wiki/v2/tasks/%s", validate.EncodePathSegment(taskID)),
 		map[string]interface{}{"task_type": "move"},
@@ -324,28 +323,42 @@ func validateWikiMoveSpec(spec wikiMoveSpec) error {
 
 	if spec.NodeToken != "" {
 		if spec.ObjType != "" || spec.ObjToken != "" || spec.Apply {
-			return output.ErrValidation("--node-token cannot be combined with --obj-type, --obj-token, or --apply")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--node-token cannot be combined with --obj-type, --obj-token, or --apply").
+				WithParams(
+					errs.InvalidParam{Name: "--obj-type", Reason: "cannot be combined with --node-token"},
+					errs.InvalidParam{Name: "--obj-token", Reason: "cannot be combined with --node-token"},
+					errs.InvalidParam{Name: "--apply", Reason: "cannot be combined with --node-token"},
+				)
 		}
 		if spec.TargetParentToken == "" && spec.TargetSpaceID == "" {
-			return output.ErrValidation("--target-parent-token and --target-space-id cannot both be empty for wiki node move")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--target-parent-token and --target-space-id cannot both be empty for wiki node move").
+				WithParams(
+					errs.InvalidParam{Name: "--target-parent-token", Reason: "provide --target-parent-token or --target-space-id"},
+					errs.InvalidParam{Name: "--target-space-id", Reason: "provide --target-parent-token or --target-space-id"},
+				)
 		}
 		return nil
 	}
 
 	if spec.SourceSpaceID != "" {
-		return output.ErrValidation("--source-space-id can only be used with --node-token")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--source-space-id can only be used with --node-token").WithParam("--source-space-id")
 	}
 	if spec.ObjType == "" && spec.ObjToken == "" && !spec.Apply {
-		return output.ErrValidation("provide --node-token for wiki node move, or provide --obj-type and --obj-token for docs-to-wiki move")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "provide --node-token for wiki node move, or provide --obj-type and --obj-token for docs-to-wiki move").
+			WithParams(
+				errs.InvalidParam{Name: "--node-token", Reason: "provide --node-token, or --obj-type and --obj-token"},
+				errs.InvalidParam{Name: "--obj-type", Reason: "provide --node-token, or --obj-type and --obj-token"},
+				errs.InvalidParam{Name: "--obj-token", Reason: "provide --node-token, or --obj-type and --obj-token"},
+			)
 	}
 	if spec.ObjType == "" {
-		return output.ErrValidation("--obj-type is required for docs-to-wiki move")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--obj-type is required for docs-to-wiki move").WithParam("--obj-type")
 	}
 	if spec.ObjToken == "" {
-		return output.ErrValidation("--obj-token is required for docs-to-wiki move")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--obj-token is required for docs-to-wiki move").WithParam("--obj-token")
 	}
 	if spec.TargetSpaceID == "" {
-		return output.ErrValidation("--target-space-id is required for docs-to-wiki move")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--target-space-id is required for docs-to-wiki move").WithParam("--target-space-id")
 	}
 
 	return nil
@@ -426,7 +439,7 @@ func runWikiMove(ctx context.Context, client wikiMoveClient, runtime *common.Run
 	case wikiMoveModeDocsToWiki:
 		return runWikiDocsToWikiMove(ctx, client, runtime, spec)
 	default:
-		return nil, output.ErrValidation("unknown wiki move mode")
+		return nil, errs.NewInternalError(errs.SubtypeUnknown, "unknown wiki move mode")
 	}
 }
 
@@ -479,11 +492,11 @@ func resolveWikiNodeMoveSpaces(ctx context.Context, client wikiMoveClient, spec
 		if targetSpaceID == "" {
 			targetSpaceID = parentSpaceID
 		} else if targetSpaceID != parentSpaceID {
-			return "", "", output.ErrValidation(
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"--target-space-id %q does not match target parent node space %q",
 				spec.TargetSpaceID,
 				parentSpaceID,
-			)
+			).WithParam("--target-space-id")
 		}
 	}
 
@@ -549,7 +562,7 @@ func runWikiDocsToWikiMove(ctx context.Context, client wikiMoveClient, runtime *
 		}
 		return out, nil
 	default:
-		return nil, output.Errorf(output.ExitAPI, "api_error", "move_docs_to_wiki returned neither wiki_token, task_id, nor applied result")
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "move_docs_to_wiki returned neither wiki_token, task_id, nor applied result")
 	}
 }
 
@@ -592,7 +605,7 @@ func pollWikiMoveTask(ctx context.Context, client wikiMoveClient, runtime *commo
 			return status, true, nil
 		}
 		if status.Failed() {
-			return status, false, output.Errorf(output.ExitAPI, "api_error", "wiki move task failed: %s", status.PrimaryStatusLabel())
+			return status, false, errs.NewAPIError(errs.SubtypeServerError, "wiki move task failed: %s", status.PrimaryStatusLabel())
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Wiki move status %d/%d: %s\n", attempt, wikiMovePollAttempts, status.PrimaryStatusLabel())
@@ -605,14 +618,18 @@ func pollWikiMoveTask(ctx context.Context, client wikiMoveClient, runtime *commo
 			taskID,
 			nextCommand,
 		)
-		var exitErr *output.ExitError
-		if errors.As(lastErr, &exitErr) && exitErr.Detail != nil {
-			if strings.TrimSpace(exitErr.Detail.Hint) != "" {
-				hint = exitErr.Detail.Hint + "\n" + hint
+		// The poll error comes from a typed CallAPITyped path; append the resume
+		// hint in place so the original category / subtype / code / log_id
+		// survives a fully failed poll (per ERROR_CONTRACT.md "propagate typed
+		// errors unchanged").
+		if p, ok := errs.ProblemOf(lastErr); ok {
+			if strings.TrimSpace(p.Hint) != "" {
+				hint = p.Hint + "\n" + hint
 			}
-			return lastStatus, false, output.ErrWithHint(exitErr.Code, exitErr.Detail.Type, exitErr.Detail.Message, hint)
+			p.Hint = hint
+			return lastStatus, false, lastErr
 		}
-		return lastStatus, false, output.ErrWithHint(output.ExitAPI, "api_error", lastErr.Error(), hint)
+		return lastStatus, false, errs.NewInternalError(errs.SubtypeSDKError, "%s", lastErr.Error()).WithHint("%s", hint).WithCause(lastErr)
 	}
 
 	return lastStatus, false, nil
@@ -620,7 +637,7 @@ func pollWikiMoveTask(ctx context.Context, client wikiMoveClient, runtime *commo
 
 func parseWikiMoveTaskStatus(taskID string, task map[string]interface{}) (wikiMoveTaskStatus, error) {
 	if task == nil {
-		return wikiMoveTaskStatus{}, output.Errorf(output.ExitAPI, "api_error", "wiki task response missing task")
+		return wikiMoveTaskStatus{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki task response missing task")
 	}
 
 	status := wikiMoveTaskStatus{

shortcuts/wiki/wiki_move_test.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"reflect"
 	"strings"
 	"sync"
@@ -15,11 +14,11 @@ 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/credential"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -181,39 +180,52 @@ func TestValidateWikiMoveSpecRejectsInvalidCombinations(t *testing.T) {
 	t.Parallel()
 
 	tests := []struct {
-		name    string
-		spec    wikiMoveSpec
-		wantErr string
+		name       string
+		spec       wikiMoveSpec
+		wantErr    string
+		wantParams []string
 	}{
 		{
-			name:    "node move rejects docs flags",
-			spec:    wikiMoveSpec{NodeToken: "wik_node", ObjType: "sheet", TargetSpaceID: "space_dst"},
-			wantErr: "cannot be combined",
+			name:       "node move rejects docs flags",
+			spec:       wikiMoveSpec{NodeToken: "wik_node", ObjType: "sheet", TargetSpaceID: "space_dst"},
+			wantErr:    "cannot be combined",
+			wantParams: []string{"--obj-type", "--obj-token", "--apply"},
 		},
 		{
-			name:    "node move requires target",
-			spec:    wikiMoveSpec{NodeToken: "wik_node"},
-			wantErr: "cannot both be empty",
+			name:       "node move requires target",
+			spec:       wikiMoveSpec{NodeToken: "wik_node"},
+			wantErr:    "cannot both be empty",
+			wantParams: []string{"--target-parent-token", "--target-space-id"},
 		},
 		{
-			name:    "source space requires node token",
-			spec:    wikiMoveSpec{SourceSpaceID: "space_src", ObjType: "sheet", ObjToken: "sheet_token", TargetSpaceID: "space_dst"},
-			wantErr: "can only be used with --node-token",
+			name:       "requires a move mode",
+			spec:       wikiMoveSpec{TargetSpaceID: "space_dst"},
+			wantErr:    "provide --node-token for wiki node move",
+			wantParams: []string{"--node-token", "--obj-type", "--obj-token"},
 		},
 		{
-			name:    "docs to wiki requires obj type",
-			spec:    wikiMoveSpec{ObjToken: "sheet_token", TargetSpaceID: "space_dst"},
-			wantErr: "--obj-type is required",
+			name:       "source space requires node token",
+			spec:       wikiMoveSpec{SourceSpaceID: "space_src", ObjType: "sheet", ObjToken: "sheet_token", TargetSpaceID: "space_dst"},
+			wantErr:    "can only be used with --node-token",
+			wantParams: []string{"--source-space-id"},
 		},
 		{
-			name:    "docs to wiki requires obj token",
-			spec:    wikiMoveSpec{ObjType: "sheet", TargetSpaceID: "space_dst"},
-			wantErr: "--obj-token is required",
+			name:       "docs to wiki requires obj type",
+			spec:       wikiMoveSpec{ObjToken: "sheet_token", TargetSpaceID: "space_dst"},
+			wantErr:    "--obj-type is required",
+			wantParams: []string{"--obj-type"},
 		},
 		{
-			name:    "docs to wiki requires target space",
-			spec:    wikiMoveSpec{ObjType: "sheet", ObjToken: "sheet_token"},
-			wantErr: "--target-space-id is required",
+			name:       "docs to wiki requires obj token",
+			spec:       wikiMoveSpec{ObjType: "sheet", TargetSpaceID: "space_dst"},
+			wantErr:    "--obj-token is required",
+			wantParams: []string{"--obj-token"},
+		},
+		{
+			name:       "docs to wiki requires target space",
+			spec:       wikiMoveSpec{ObjType: "sheet", ObjToken: "sheet_token"},
+			wantErr:    "--target-space-id is required",
+			wantParams: []string{"--target-space-id"},
 		},
 	}
 
@@ -225,6 +237,9 @@ func TestValidateWikiMoveSpecRejectsInvalidCombinations(t *testing.T) {
 			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
 				t.Fatalf("expected error containing %q, got %v", tt.wantErr, err)
 			}
+			if len(tt.wantParams) > 0 {
+				requireWikiValidationParams(t, err, tt.wantParams...)
+			}
 		})
 	}
 }
@@ -837,7 +852,7 @@ func TestPollWikiMoveTaskWrapsRepeatedPollFailuresWithHint(t *testing.T) {
 
 	runtime, stderr := newWikiMoveRuntimeWithScopes(t, core.AsUser, "")
 	client := &fakeWikiMoveClient{
-		taskErrs: []error{output.ErrWithHint(output.ExitAPI, "api_error", "poll failed", "retry original")},
+		taskErrs: []error{errs.NewAPIError(errs.SubtypeServerError, "poll failed").WithHint("retry original")},
 	}
 
 	status, ready, err := pollWikiMoveTask(context.Background(), client, runtime, "task_123")
@@ -850,12 +865,12 @@ func TestPollWikiMoveTaskWrapsRepeatedPollFailuresWithHint(t *testing.T) {
 	if status.TaskID != "task_123" {
 		t.Fatalf("status.TaskID = %q, want %q", status.TaskID, "task_123")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected structured exit error, got %T %v", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected a typed errs.* error, got %T %v", err, err)
 	}
-	if !strings.Contains(exitErr.Detail.Hint, "retry original") || !strings.Contains(exitErr.Detail.Hint, wikiMoveTaskResultCommand("task_123", core.AsUser)) {
-		t.Fatalf("hint = %q, want original hint and resume command", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "retry original") || !strings.Contains(p.Hint, wikiMoveTaskResultCommand("task_123", core.AsUser)) {
+		t.Fatalf("hint = %q, want original hint and resume command", p.Hint)
 	}
 	if !strings.Contains(stderr.String(), "Wiki move status attempt 1/1 failed") {
 		t.Fatalf("stderr = %q, want poll failure log", stderr.String())

shortcuts/wiki/wiki_node_copy.go

@@ -9,7 +9,7 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -44,10 +44,18 @@ var WikiNodeCopy = common.Shortcut{
 		targetSpaceID := strings.TrimSpace(runtime.Str("target-space-id"))
 		targetParent := strings.TrimSpace(runtime.Str("target-parent-node-token"))
 		if targetSpaceID == "" && targetParent == "" {
-			return output.ErrValidation("at least one of --target-space-id or --target-parent-node-token is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "at least one of --target-space-id or --target-parent-node-token is required").
+				WithParams(
+					errs.InvalidParam{Name: "--target-space-id", Reason: "provide --target-space-id or --target-parent-node-token"},
+					errs.InvalidParam{Name: "--target-parent-node-token", Reason: "provide --target-space-id or --target-parent-node-token"},
+				)
 		}
 		if targetSpaceID != "" && targetParent != "" {
-			return output.ErrValidation("--target-space-id and --target-parent-node-token are mutually exclusive; provide only one")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--target-space-id and --target-parent-node-token are mutually exclusive; provide only one").
+				WithParams(
+					errs.InvalidParam{Name: "--target-space-id", Reason: "mutually exclusive with --target-parent-node-token"},
+					errs.InvalidParam{Name: "--target-parent-node-token", Reason: "mutually exclusive with --target-space-id"},
+				)
 		}
 		if err := validateOptionalResourceName(targetSpaceID, "--target-space-id"); err != nil {
 			return err
@@ -72,7 +80,7 @@ var WikiNodeCopy = common.Shortcut{
 		fmt.Fprintf(runtime.IO().ErrOut, "Copying wiki node %s from space %s\n",
 			common.MaskToken(nodeToken), common.MaskToken(spaceID))
 
-		data, err := runtime.CallAPI("POST",
+		data, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/wiki/v2/spaces/%s/nodes/%s/copy",
 				validate.EncodePathSegment(spaceID),
 				validate.EncodePathSegment(nodeToken)),

shortcuts/wiki/wiki_node_create.go

@@ -5,12 +5,12 @@ package wiki
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"io"
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -170,7 +170,7 @@ type wikiNodeCreateAPI struct {
 }
 
 func (api wikiNodeCreateAPI) GetNode(ctx context.Context, token string) (*wikiNodeRecord, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"GET",
 		"/open-apis/wiki/v2/spaces/get_node",
 		map[string]interface{}{"token": token},
@@ -183,7 +183,7 @@ func (api wikiNodeCreateAPI) GetNode(ctx context.Context, token string) (*wikiNo
 }
 
 func (api wikiNodeCreateAPI) GetSpace(ctx context.Context, spaceID string) (*wikiSpaceRecord, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"GET",
 		fmt.Sprintf("/open-apis/wiki/v2/spaces/%s", validate.EncodePathSegment(spaceID)),
 		nil,
@@ -196,7 +196,7 @@ func (api wikiNodeCreateAPI) GetSpace(ctx context.Context, spaceID string) (*wik
 }
 
 func (api wikiNodeCreateAPI) CreateNode(ctx context.Context, spaceID string, spec wikiNodeCreateSpec) (*wikiNodeRecord, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"POST",
 		fmt.Sprintf("/open-apis/wiki/v2/spaces/%s/nodes", validate.EncodePathSegment(spaceID)),
 		nil,
@@ -231,22 +231,26 @@ func validateWikiNodeCreateSpec(spec wikiNodeCreateSpec, identity core.Identity)
 	}
 
 	if spec.NodeType == wikiNodeTypeShortcut && spec.OriginNodeToken == "" {
-		return output.ErrValidation("--origin-node-token is required when --node-type=shortcut")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--origin-node-token is required when --node-type=shortcut").WithParam("--origin-node-token")
 	}
 	if spec.NodeType != wikiNodeTypeShortcut && spec.OriginNodeToken != "" {
-		return output.ErrValidation("--origin-node-token can only be used when --node-type=shortcut")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--origin-node-token can only be used when --node-type=shortcut").WithParam("--origin-node-token")
 	}
 
 	// Bot identity has no meaningful "personal document library" target, so
 	// my_library must be rejected explicitly instead of deferring to API-time
 	// resolution errors.
 	if identity.IsBot() && spec.SpaceID == wikiMyLibrarySpaceID {
-		return output.ErrValidation("bot identity does not support --space-id my_library; use an explicit --space-id or --parent-node-token")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "bot identity does not support --space-id my_library; use an explicit --space-id or --parent-node-token").WithParam("--space-id")
 	}
 	// Bot identity also cannot fall back implicitly, so it requires an explicit
 	// target or a parent it can resolve from.
 	if identity.IsBot() && spec.SpaceID == "" && spec.ParentNodeToken == "" {
-		return output.ErrValidation("bot identity requires --space-id or --parent-node-token")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "bot identity requires --space-id or --parent-node-token").
+			WithParams(
+				errs.InvalidParam{Name: "--space-id", Reason: "provide --space-id or --parent-node-token for bot identity"},
+				errs.InvalidParam{Name: "--parent-node-token", Reason: "provide --space-id or --parent-node-token for bot identity"},
+			)
 	}
 
 	return nil
@@ -334,7 +338,7 @@ func runWikiNodeCreate(ctx context.Context, client wikiNodeCreateClient, identit
 		return nil, wrapWikiNodeCreateRetryError(lastErr)
 	}
 	if node == nil {
-		return nil, output.Errorf(output.ExitAPI, "api_error", "wiki node create returned no node")
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki node create returned no node")
 	}
 
 	return &wikiNodeCreateExecution{
@@ -346,45 +350,32 @@ func runWikiNodeCreate(ctx context.Context, client wikiNodeCreateClient, identit
 // isWikiNodeLockContention returns true if the error is a Lark API error with
 // code 131009 (wiki node lock contention), which is retryable with backoff.
 func isWikiNodeLockContention(err error) bool {
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+	p, ok := errs.ProblemOf(err)
+	if !ok {
 		return false
 	}
-	return exitErr.Detail.Code == output.LarkErrWikiLockContention
+	return p.Code == output.LarkErrWikiLockContention
 }
 
 // wrapWikiNodeCreateRetryError appends a retry-exhaustion hint to the original
-// API error. It builds the ExitError by hand (instead of using ErrWithHint) so
-// the original Lark error code survives in the envelope.
+// API error in place, preserving its typed category / subtype / code / log_id.
 func wrapWikiNodeCreateRetryError(err error) error {
 	if err == nil {
 		return nil
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+	p, ok := errs.ProblemOf(err)
+	if !ok {
 		return err
 	}
 	hint := fmt.Sprintf(
 		"wiki node create failed after %d retries due to lock contention; try again later or reduce concurrent node creations under the same parent",
 		wikiNodeCreateMaxRetries,
 	)
-	if existing := strings.TrimSpace(exitErr.Detail.Hint); existing != "" {
+	if existing := strings.TrimSpace(p.Hint); existing != "" {
 		hint = existing + "\n" + hint
 	}
-	return &output.ExitError{
-		Code: exitErr.Code,
-		Detail: &output.ErrDetail{
-			Type:       exitErr.Detail.Type,
-			Code:       exitErr.Detail.Code,
-			Message:    exitErr.Detail.Message,
-			Hint:       hint,
-			ConsoleURL: exitErr.Detail.ConsoleURL,
-			Risk:       exitErr.Detail.Risk,
-			Detail:     exitErr.Detail.Detail,
-		},
-		Err: exitErr.Err,
-		Raw: exitErr.Raw,
-	}
+	p.Hint = hint
+	return err
 }
 
 // resolveWikiNodeCreateSpace applies the shortcut's precedence rules:
@@ -397,7 +388,11 @@ func resolveWikiNodeCreateSpace(ctx context.Context, client wikiNodeCreateClient
 		return resolveWikiNodeCreateSpaceFromParentNode(ctx, client, spec.ParentNodeToken)
 	}
 	if identity.IsBot() {
-		return wikiResolvedSpace{}, output.ErrValidation("bot identity requires --space-id or --parent-node-token")
+		return wikiResolvedSpace{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "bot identity requires --space-id or --parent-node-token").
+			WithParams(
+				errs.InvalidParam{Name: "--space-id", Reason: "provide --space-id or --parent-node-token for bot identity"},
+				errs.InvalidParam{Name: "--parent-node-token", Reason: "provide --space-id or --parent-node-token for bot identity"},
+			)
 	}
 	return resolveWikiNodeCreateSpaceFromMyLibrary(ctx, client)
 }
@@ -434,12 +429,12 @@ func resolveWikiNodeCreateSpaceFromExplicitSpace(ctx context.Context, client wik
 		return wikiResolvedSpace{}, err
 	}
 	if parentSpaceID != resolved.SpaceID {
-		return wikiResolvedSpace{}, output.ErrValidation(
+		return wikiResolvedSpace{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 			"--space-id %q does not match parent node space %q (resolved space: %q)",
 			spec.SpaceID,
 			parentSpaceID,
 			resolved.SpaceID,
-		)
+		).WithParam("--space-id")
 	}
 
 	resolved.ParentNode = parent
@@ -483,21 +478,22 @@ func requireWikiNodeSpaceID(node *wikiNodeRecord) (string, error) {
 	if node != nil && node.SpaceID != "" {
 		return node.SpaceID, nil
 	}
-	return "", output.Errorf(output.ExitAPI, "api_error", "wiki node lookup returned no space_id")
+	return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki node lookup returned no space_id")
 }
 
 func requireWikiSpaceID(space *wikiSpaceRecord) (string, error) {
 	if space != nil && space.SpaceID != "" {
 		return space.SpaceID, nil
 	}
-	return "", output.ErrValidation("personal document library was not found, please specify --space-id")
+	return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "personal document library lookup returned no space_id").
+		WithHint("specify --space-id explicitly to target a space directly")
 }
 
 // resolveMyLibrarySpaceID calls GET /wiki/v2/spaces/my_library and returns
 // the per-user real space_id. Shared by shortcuts that accept the my_library
 // alias (e.g. +node-create, +node-list) so the behavior stays consistent.
 func resolveMyLibrarySpaceID(runtime *common.RuntimeContext) (string, error) {
-	data, err := runtime.CallAPI(
+	data, err := runtime.CallAPITyped(
 		"GET",
 		fmt.Sprintf("/open-apis/wiki/v2/spaces/%s", validate.EncodePathSegment(wikiMyLibrarySpaceID)),
 		nil, nil,
@@ -517,14 +513,14 @@ func validateOptionalResourceName(value, flagName string) error {
 		return nil
 	}
 	if err := validate.ResourceName(value, flagName); err != nil {
-		return output.ErrValidation("%s", err)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam(flagName).WithCause(err)
 	}
 	return nil
 }
 
 func parseWikiNodeRecord(node map[string]interface{}) (*wikiNodeRecord, error) {
 	if node == nil {
-		return nil, output.Errorf(output.ExitAPI, "api_error", "wiki node response missing node")
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki node response missing node")
 	}
 	return &wikiNodeRecord{
 		SpaceID:         common.GetString(node, "space_id"),
@@ -542,7 +538,7 @@ func parseWikiNodeRecord(node map[string]interface{}) (*wikiNodeRecord, error) {
 
 func parseWikiSpaceRecord(space map[string]interface{}) (*wikiSpaceRecord, error) {
 	if space == nil {
-		return nil, output.Errorf(output.ExitAPI, "api_error", "wiki space response missing space")
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki space response missing space")
 	}
 	return &wikiSpaceRecord{
 		SpaceID:     common.GetString(space, "space_id"),

shortcuts/wiki/wiki_node_create_test.go

@@ -16,13 +16,26 @@ 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/errclass"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+// wikiTestLockContentionErr builds the typed API error that runtime.CallAPITyped
+// produces for a wiki write-lock-contention response (code 131009), so the
+// retry path's errs.ProblemOf(...).Code check sees the same shape in tests as
+// in production.
+func wikiTestLockContentionErr() error {
+	return errclass.BuildAPIError(
+		map[string]any{"code": float64(output.LarkErrWikiLockContention), "msg": "lock contention"},
+		errclass.ClassifyContext{},
+	)
+}
+
 type fakeWikiNodeCreateCall struct {
 	SpaceID string
 	Spec    wikiNodeCreateSpec
@@ -116,6 +129,44 @@ func mountAndRunWiki(t *testing.T, shortcut common.Shortcut, args []string, fact
 	return parent.Execute()
 }
 
+// requireWikiValidationParams asserts err carries a *errs.ValidationError of
+// category validation / subtype invalid_argument and that its named flags
+// (single Param or structured Params) cover every wanted flag, locking the
+// typed contract and input-recovery fields so callers and agents can re-fill
+// the right flags without parsing the prose message.
+func requireWikiValidationParams(t *testing.T, err error, wantNames ...string) {
+	t.Helper()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T (%v)", err, err)
+	}
+	if ve.Category != errs.CategoryValidation || ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected validation/invalid_argument, got %s/%s", ve.Category, ve.Subtype)
+	}
+	have := make(map[string]bool, len(ve.Params)+1)
+	if ve.Param != "" {
+		have[ve.Param] = true
+	}
+	for _, p := range ve.Params {
+		have[p.Name] = true
+	}
+	for _, name := range wantNames {
+		if !have[name] {
+			t.Fatalf("flag %q not found; Param=%q Params=%+v", name, ve.Param, ve.Params)
+		}
+	}
+}
+
+func TestRequireWikiSpaceIDTreatsEmptyAsInvalidResponse(t *testing.T) {
+	t.Parallel()
+
+	_, err := requireWikiSpaceID(&wikiSpaceRecord{})
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+		t.Fatalf("expected internal/invalid_response, got %v", err)
+	}
+}
+
 func TestValidateWikiNodeCreateSpecRejectsShortcutWithoutOriginNodeToken(t *testing.T) {
 	t.Parallel()
 
@@ -151,6 +202,7 @@ func TestValidateWikiNodeCreateSpecRejectsBotWithoutLocation(t *testing.T) {
 	if err == nil || !strings.Contains(err.Error(), "bot identity requires --space-id or --parent-node-token") {
 		t.Fatalf("expected bot location validation error, got %v", err)
 	}
+	requireWikiValidationParams(t, err, "--space-id", "--parent-node-token")
 }
 
 func TestValidateWikiNodeCreateSpecRejectsBotMyLibrarySpaceID(t *testing.T) {
@@ -236,6 +288,19 @@ func TestResolveWikiNodeCreateSpaceUsesMyLibraryFallback(t *testing.T) {
 	}
 }
 
+func TestResolveWikiNodeCreateSpaceRejectsBotWithoutLocation(t *testing.T) {
+	t.Parallel()
+
+	_, err := resolveWikiNodeCreateSpace(context.Background(), &fakeWikiNodeCreateClient{}, core.AsBot, wikiNodeCreateSpec{
+		NodeType: wikiNodeTypeOrigin,
+		ObjType:  "docx",
+	})
+	if err == nil || !strings.Contains(err.Error(), "bot identity requires --space-id or --parent-node-token") {
+		t.Fatalf("expected bot location validation error, got %v", err)
+	}
+	requireWikiValidationParams(t, err, "--space-id", "--parent-node-token")
+}
+
 func TestRunWikiNodeCreateCreatesNodeInResolvedSpace(t *testing.T) {
 	t.Parallel()
 
@@ -785,7 +850,7 @@ func TestWikiNodeURL(t *testing.T) {
 func TestRunWikiNodeCreateRetriesOnLockContention(t *testing.T) {
 	t.Parallel()
 
-	lockErr := output.ErrAPI(output.LarkErrWikiLockContention, "lock contention", nil)
+	lockErr := wikiTestLockContentionErr()
 
 	client := &fakeWikiNodeCreateClient{
 		spaces: map[string]*wikiSpaceRecord{
@@ -831,7 +896,7 @@ func TestRunWikiNodeCreateRetriesOnLockContention(t *testing.T) {
 func TestRunWikiNodeCreateRetriesExhausted(t *testing.T) {
 	t.Parallel()
 
-	lockErr := output.ErrAPI(output.LarkErrWikiLockContention, "lock contention", nil)
+	lockErr := wikiTestLockContentionErr()
 
 	client := &fakeWikiNodeCreateClient{
 		spaces: map[string]*wikiSpaceRecord{
@@ -853,25 +918,30 @@ func TestRunWikiNodeCreateRetriesExhausted(t *testing.T) {
 	if len(client.createInvoked) != 3 {
 		t.Fatalf("create invoked %d times, want 3", len(client.createInvoked))
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected ExitError, got %T: %v", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected a typed errs.* error, got %T: %v", err, err)
 	}
-	if exitErr.Detail.Code != output.LarkErrWikiLockContention {
-		t.Fatalf("error code = %d, want %d", exitErr.Detail.Code, output.LarkErrWikiLockContention)
+	if p.Code != output.LarkErrWikiLockContention {
+		t.Fatalf("error code = %d, want %d", p.Code, output.LarkErrWikiLockContention)
 	}
-	if !strings.Contains(exitErr.Detail.Hint, "failed after 2 retries") {
-		t.Fatalf("hint = %q, want retry exhaustion message", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "failed after 2 retries") {
+		t.Fatalf("hint = %q, want retry exhaustion message", p.Hint)
 	}
-	if !strings.Contains(exitErr.Detail.Hint, "lock contention") {
-		t.Fatalf("hint = %q, want original classification hint preserved", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "lock contention") {
+		t.Fatalf("hint = %q, want original classification hint preserved", p.Hint)
 	}
 }
 
 func TestRunWikiNodeCreateNoRetryOnNonContentionError(t *testing.T) {
 	t.Parallel()
 
-	otherErr := output.ErrAPI(output.LarkErrRateLimit, "rate limit", nil) // rate limit, not lock contention
+	// A typed API error for a different code (rate limit, not lock contention),
+	// mirroring what runtime.CallAPITyped produces.
+	otherErr := errclass.BuildAPIError(
+		map[string]any{"code": float64(output.LarkErrRateLimit), "msg": "rate limit"},
+		errclass.ClassifyContext{},
+	)
 
 	client := &fakeWikiNodeCreateClient{
 		spaces: map[string]*wikiSpaceRecord{
@@ -901,7 +971,7 @@ func TestRunWikiNodeCreateNoRetryOnNonContentionError(t *testing.T) {
 func TestRunWikiNodeCreateRetriesOnFirstLockThenSucceeds(t *testing.T) {
 	t.Parallel()
 
-	lockErr := output.ErrAPI(output.LarkErrWikiLockContention, "lock contention", nil)
+	lockErr := wikiTestLockContentionErr()
 
 	client := &fakeWikiNodeCreateClient{
 		spaces: map[string]*wikiSpaceRecord{
@@ -944,7 +1014,7 @@ func TestRunWikiNodeCreateRetriesOnFirstLockThenSucceeds(t *testing.T) {
 func TestRunWikiNodeCreateRetryContextCancelled(t *testing.T) {
 	t.Parallel()
 
-	lockErr := output.ErrAPI(output.LarkErrWikiLockContention, "lock contention", nil)
+	lockErr := wikiTestLockContentionErr()
 
 	client := &fakeWikiNodeCreateClient{
 		spaces: map[string]*wikiSpaceRecord{

shortcuts/wiki/wiki_node_delete.go

@@ -5,14 +5,13 @@ package wiki
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"net/url"
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -135,7 +134,7 @@ func (api wikiNodeDeleteAPI) ResolveNode(ctx context.Context, token, objType str
 	if objType != "" && objType != "wiki" {
 		params["obj_type"] = objType
 	}
-	data, err := api.runtime.CallAPI("GET", "/open-apis/wiki/v2/spaces/get_node", params, nil)
+	data, err := api.runtime.CallAPITyped("GET", "/open-apis/wiki/v2/spaces/get_node", params, nil)
 	if err != nil {
 		return nil, err
 	}
@@ -143,7 +142,7 @@ func (api wikiNodeDeleteAPI) ResolveNode(ctx context.Context, token, objType str
 }
 
 func (api wikiNodeDeleteAPI) DeleteNode(ctx context.Context, spaceID string, spec wikiNodeDeleteSpec) (string, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"DELETE",
 		fmt.Sprintf(
 			"/open-apis/wiki/v2/spaces/%s/nodes/%s",
@@ -160,7 +159,7 @@ func (api wikiNodeDeleteAPI) DeleteNode(ctx context.Context, spaceID string, spe
 }
 
 func (api wikiNodeDeleteAPI) GetDeleteNodeTask(ctx context.Context, taskID string) (wikiAsyncTaskStatus, error) {
-	data, err := api.runtime.CallAPI(
+	data, err := api.runtime.CallAPITyped(
 		"GET",
 		fmt.Sprintf("/open-apis/wiki/v2/tasks/%s", validate.EncodePathSegment(taskID)),
 		map[string]interface{}{"task_type": wikiAsyncTaskTypeDeleteNode},
@@ -188,7 +187,7 @@ func readWikiNodeDeleteSpec(runtime *common.RuntimeContext) (wikiNodeDeleteSpec,
 func parseWikiNodeDeleteSpec(rawToken, rawObjType, rawSpaceID string, includeChildren bool) (wikiNodeDeleteSpec, error) {
 	tokenInput := strings.TrimSpace(rawToken)
 	if tokenInput == "" {
-		return wikiNodeDeleteSpec{}, output.ErrValidation("--node-token is required")
+		return wikiNodeDeleteSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--node-token is required").WithParam("--node-token")
 	}
 
 	spec := wikiNodeDeleteSpec{
@@ -200,14 +199,14 @@ func parseWikiNodeDeleteSpec(rawToken, rawObjType, rawSpaceID string, includeChi
 	if strings.Contains(tokenInput, "://") {
 		u, err := url.Parse(tokenInput)
 		if err != nil || u.Path == "" {
-			return wikiNodeDeleteSpec{}, output.ErrValidation("--node-token URL is malformed: %q", tokenInput)
+			return wikiNodeDeleteSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--node-token URL is malformed: %q", tokenInput).WithParam("--node-token")
 		}
 		token, urlObjType, ok := tokenAndObjTypeFromWikiURL(u.Path)
 		if !ok {
-			return wikiNodeDeleteSpec{}, output.ErrValidation(
+			return wikiNodeDeleteSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"unsupported --node-token URL path %q: expected /wiki/, /docx/, /doc/, /sheets/, /base/, /mindnote/, /slides/, or /file/ followed by a token",
 				u.Path,
-			)
+			).WithParam("--node-token")
 		}
 		spec.NodeToken = token
 		spec.SourceKind = "url"
@@ -222,32 +221,32 @@ func parseWikiNodeDeleteSpec(rawToken, rawObjType, rawSpaceID string, includeChi
 		case spec.ObjType == "":
 			spec.ObjType = inferred
 		case spec.ObjType != inferred:
-			return wikiNodeDeleteSpec{}, output.ErrValidation(
+			return wikiNodeDeleteSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"--obj-type %q does not match the obj_type %q implied by the URL path; pass only one",
 				spec.ObjType, inferred,
-			)
+			).WithParam("--obj-type")
 		}
 	} else if strings.ContainsAny(tokenInput, "/?#") {
-		return wikiNodeDeleteSpec{}, output.ErrValidation(
+		return wikiNodeDeleteSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 			"--node-token must be a raw token or a full URL; partial paths are not accepted: %q",
 			tokenInput,
-		)
+		).WithParam("--node-token")
 	} else {
 		spec.NodeToken = tokenInput
 		spec.SourceKind = "raw"
 	}
 
 	if spec.ObjType == "" {
-		return wikiNodeDeleteSpec{}, output.ErrValidation(
+		return wikiNodeDeleteSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 			"--obj-type is required (one of: %s)",
 			strings.Join(wikiNodeDeleteObjTypes, ", "),
-		)
+		).WithParam("--obj-type")
 	}
 	if !isValidWikiDeleteObjType(spec.ObjType) {
-		return wikiNodeDeleteSpec{}, output.ErrValidation(
+		return wikiNodeDeleteSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 			"--obj-type %q is not valid; pick one of: %s",
 			spec.ObjType, strings.Join(wikiNodeDeleteObjTypes, ", "),
-		)
+		).WithParam("--obj-type")
 	}
 	if err := validateOptionalResourceName(spec.NodeToken, "--node-token"); err != nil {
 		return wikiNodeDeleteSpec{}, err
@@ -405,12 +404,12 @@ func wrapWikiNodeDeleteAPIError(err error) error {
 	if err == nil {
 		return nil
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+	p, ok := errs.ProblemOf(err)
+	if !ok {
 		return err
 	}
 	var hint string
-	switch exitErr.Detail.Code {
+	switch p.Code {
 	case wikiDeleteNodeErrCodeApprovalRequired:
 		hint = "this wiki node has delete-approval enabled; ask the user to apply via the Wiki UI (CLI cannot bypass approval)"
 	case wikiDeleteNodeErrCodeSubtreeTooLarge:
@@ -419,22 +418,11 @@ func wrapWikiNodeDeleteAPIError(err error) error {
 	if hint == "" {
 		return err
 	}
-	if existing := strings.TrimSpace(exitErr.Detail.Hint); existing != "" {
+	// Append the hint in place so the typed error keeps its category / subtype /
+	// code / log_id (per ERROR_CONTRACT.md "propagate typed errors unchanged").
+	if existing := strings.TrimSpace(p.Hint); existing != "" {
 		hint = existing + "\n" + hint
 	}
-	// ErrWithHint drops the upstream Detail.Code / Detail / Risk fields; build
-	// the ExitError by hand so the Lark error code stays available to logs and
-	// downstream pivots.
-	return &output.ExitError{
-		Code: exitErr.Code,
-		Detail: &output.ErrDetail{
-			Type:       exitErr.Detail.Type,
-			Code:       exitErr.Detail.Code,
-			Message:    exitErr.Detail.Message,
-			Hint:       hint,
-			ConsoleURL: exitErr.Detail.ConsoleURL,
-			Risk:       exitErr.Detail.Risk,
-			Detail:     exitErr.Detail.Detail,
-		},
-	}
+	p.Hint = hint
+	return err
 }

shortcuts/wiki/wiki_node_delete_test.go

@@ -9,17 +9,17 @@ import (
 	"encoding/json"
 	"errors"
 	"net/http"
-	"reflect"
 	"strings"
 	"sync"
 	"testing"
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -357,63 +357,55 @@ func TestRunWikiNodeDeleteAsyncFailureSurfacesReason(t *testing.T) {
 func TestWrapWikiNodeDeleteAPIErrorAddsApprovalHint(t *testing.T) {
 	t.Parallel()
 
-	in := &output.ExitError{
-		Code: output.ExitAPI,
-		Detail: &output.ErrDetail{
-			Type:    "api_error",
-			Code:    wikiDeleteNodeErrCodeApprovalRequired,
-			Message: "node requires delete approval",
-		},
-	}
+	in := errclass.BuildAPIError(
+		map[string]any{"code": float64(wikiDeleteNodeErrCodeApprovalRequired), "msg": "node requires delete approval"},
+		errclass.ClassifyContext{},
+	)
 	got := wrapWikiNodeDeleteAPIError(in)
-	var exitErr *output.ExitError
-	if !errors.As(got, &exitErr) || exitErr.Detail == nil {
-		t.Fatalf("expected ExitError, got %T %v", got, got)
+	p, ok := errs.ProblemOf(got)
+	if !ok {
+		t.Fatalf("expected a typed errs.* error, got %T %v", got, got)
 	}
-	if !strings.Contains(exitErr.Detail.Hint, "delete-approval enabled") || !strings.Contains(exitErr.Detail.Hint, "Wiki UI") {
-		t.Fatalf("hint = %q, want approval guidance", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "delete-approval enabled") || !strings.Contains(p.Hint, "Wiki UI") {
+		t.Fatalf("hint = %q, want approval guidance", p.Hint)
 	}
 	// Original code/message must be preserved so logs and dashboards still
 	// pivot on the upstream error code.
-	if exitErr.Detail.Code != wikiDeleteNodeErrCodeApprovalRequired {
-		t.Fatalf("hint wrapper lost the original code: %d", exitErr.Detail.Code)
+	if p.Code != wikiDeleteNodeErrCodeApprovalRequired {
+		t.Fatalf("hint wrapper lost the original code: %d", p.Code)
 	}
-	if exitErr.Detail.Message != "node requires delete approval" {
-		t.Fatalf("message changed unexpectedly: %q", exitErr.Detail.Message)
+	if p.Message != "node requires delete approval" {
+		t.Fatalf("message changed unexpectedly: %q", p.Message)
 	}
 }
 
 func TestWrapWikiNodeDeleteAPIErrorAddsSubtreeHint(t *testing.T) {
 	t.Parallel()
 
-	in := &output.ExitError{
-		Code: output.ExitAPI,
-		Detail: &output.ErrDetail{
-			Type:    "api_error",
-			Code:    wikiDeleteNodeErrCodeSubtreeTooLarge,
-			Message: "subtree too large",
-		},
-	}
+	in := errclass.BuildAPIError(
+		map[string]any{"code": float64(wikiDeleteNodeErrCodeSubtreeTooLarge), "msg": "subtree too large"},
+		errclass.ClassifyContext{},
+	)
 	got := wrapWikiNodeDeleteAPIError(in)
-	var exitErr *output.ExitError
-	if !errors.As(got, &exitErr) {
-		t.Fatalf("expected ExitError, got %T %v", got, got)
+	p, ok := errs.ProblemOf(got)
+	if !ok {
+		t.Fatalf("expected a typed errs.* error, got %T %v", got, got)
 	}
-	if !strings.Contains(exitErr.Detail.Hint, "--include-children=false") {
-		t.Fatalf("hint = %q, want subtree-too-large guidance", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "--include-children=false") {
+		t.Fatalf("hint = %q, want subtree-too-large guidance", p.Hint)
 	}
 }
 
 func TestWrapWikiNodeDeleteAPIErrorPassesThroughUnknownCodes(t *testing.T) {
 	t.Parallel()
 
-	in := &output.ExitError{
-		Code:   output.ExitAPI,
-		Detail: &output.ErrDetail{Type: "api_error", Code: 131005, Message: "node not found"},
-	}
+	in := errclass.BuildAPIError(
+		map[string]any{"code": float64(131005), "msg": "node not found"},
+		errclass.ClassifyContext{},
+	)
 	got := wrapWikiNodeDeleteAPIError(in)
-	if !reflect.DeepEqual(got, in) {
-		t.Fatalf("unknown code should pass through; got %#v", got)
+	if got != in {
+		t.Fatalf("unknown code should pass through unchanged; got %#v", got)
 	}
 }
 

shortcuts/wiki/wiki_node_get.go

@@ -12,7 +12,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
@@ -98,7 +98,7 @@ var WikiNodeGet = common.Shortcut{
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Fetching wiki node %s...\n", common.MaskToken(spec.Token))
 
-		data, err := runtime.CallAPI("GET", "/open-apis/wiki/v2/spaces/get_node", spec.RequestParams(), nil)
+		data, err := runtime.CallAPITyped("GET", "/open-apis/wiki/v2/spaces/get_node", spec.RequestParams(), nil)
 		if err != nil {
 			return err
 		}
@@ -109,10 +109,10 @@ var WikiNodeGet = common.Shortcut{
 		}
 
 		if spec.SpaceID != "" && node.SpaceID != "" && spec.SpaceID != node.SpaceID {
-			return output.ErrValidation(
+			return errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"--space-id %q does not match the resolved node space %q (node_token=%s)",
 				spec.SpaceID, node.SpaceID, node.NodeToken,
-			)
+			).WithParam("--space-id")
 		}
 		if spec.SpaceID != "" && node.SpaceID == "" {
 			// The cross-check was requested but get_node returned no space_id,
@@ -178,8 +178,8 @@ func resolveWikiNodeGetRawToken(nodeToken, legacyToken string) (string, error) {
 	legacy := strings.TrimSpace(legacyToken)
 	switch {
 	case canonical != "" && legacy != "" && canonical != legacy:
-		return "", output.ErrValidation(
-			"--node-token and --token are both set with different values; pass --node-token only (--token is deprecated)")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"--node-token and --token are both set with different values; pass --node-token only (--token is deprecated)").WithParam("--token")
 	case canonical != "":
 		return nodeToken, nil
 	default:
@@ -193,7 +193,7 @@ func resolveWikiNodeGetRawToken(nodeToken, legacyToken string) (string, error) {
 func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetSpec, error) {
 	tokenInput := strings.TrimSpace(rawToken)
 	if tokenInput == "" {
-		return wikiNodeGetSpec{}, output.ErrValidation("--node-token is required")
+		return wikiNodeGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--node-token is required").WithParam("--node-token")
 	}
 
 	spec := wikiNodeGetSpec{
@@ -204,14 +204,14 @@ func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetS
 	if strings.Contains(tokenInput, "://") {
 		u, err := url.Parse(tokenInput)
 		if err != nil || u.Path == "" {
-			return wikiNodeGetSpec{}, output.ErrValidation("--node-token URL is malformed: %q", tokenInput)
+			return wikiNodeGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--node-token URL is malformed: %q", tokenInput).WithParam("--node-token")
 		}
 		token, urlObjType, ok := tokenAndObjTypeFromWikiURL(u.Path)
 		if !ok {
-			return wikiNodeGetSpec{}, output.ErrValidation(
+			return wikiNodeGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"unsupported --node-token URL path %q: expected /wiki/, /docx/, /doc/, /sheets/, /base/, /mindnote/, /slides/, or /file/ followed by a token",
 				u.Path,
-			)
+			).WithParam("--node-token")
 		}
 		spec.Token = token
 		if urlObjType == "" {
@@ -223,16 +223,16 @@ func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetS
 		case spec.ObjType == "" && urlObjType != "":
 			spec.ObjType = urlObjType
 		case spec.ObjType != "" && urlObjType != "" && spec.ObjType != urlObjType:
-			return wikiNodeGetSpec{}, output.ErrValidation(
+			return wikiNodeGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"--obj-type %q does not match the obj_type %q implied by the URL path; pass only one",
 				spec.ObjType, urlObjType,
-			)
+			).WithParam("--obj-type")
 		}
 	} else if strings.ContainsAny(tokenInput, "/?#") {
-		return wikiNodeGetSpec{}, output.ErrValidation(
+		return wikiNodeGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 			"--node-token must be a raw token or a full URL; partial paths are not accepted: %q",
 			tokenInput,
-		)
+		).WithParam("--node-token")
 	} else {
 		spec.Token = tokenInput
 		if looksLikeWikiNodeToken(spec.Token) {
@@ -241,10 +241,10 @@ func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetS
 			// than silently passing it (the API would just ignore it, but the
 			// mismatch signals caller confusion).
 			if spec.ObjType != "" {
-				return wikiNodeGetSpec{}, output.ErrValidation(
+				return wikiNodeGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 					"--obj-type is only valid for obj_tokens; %q looks like a node_token",
 					spec.Token,
-				)
+				).WithParam("--obj-type")
 			}
 		} else {
 			spec.SourceKind = "raw-obj"
@@ -253,10 +253,10 @@ func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetS
 			// sheet / bitable / ... Fail fast with the same upfront contract
 			// as +node-delete instead of deferring to an opaque API error.
 			if spec.ObjType == "" {
-				return wikiNodeGetSpec{}, output.ErrValidation(
+				return wikiNodeGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
 					"--obj-type is required for a raw obj_token %q (one of: %s); or pass a typed Lark URL (e.g. /docx/<token>) so it can be inferred",
 					spec.Token, strings.Join(wikiNodeGetObjTypeEnum, ", "),
-				)
+				).WithParam("--obj-type")
 			}
 		}
 	}

shortcuts/wiki/wiki_node_list.go

@@ -10,6 +10,7 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -53,7 +54,7 @@ var WikiNodeList = common.Shortcut{
 		// hint instead of deferring to API-time errors. Matches the contract
 		// used by +node-create and +move.
 		if runtime.As().IsBot() && spaceID == wikiMyLibrarySpaceID {
-			return output.ErrValidation("bot identity does not support --space-id my_library; use an explicit --space-id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "bot identity does not support --space-id my_library; use an explicit --space-id").WithParam("--space-id")
 		}
 		if err := validateOptionalResourceName(spaceID, "--space-id"); err != nil {
 			return err
@@ -150,7 +151,7 @@ func fetchWikiNodes(runtime *common.RuntimeContext, spaceID string) ([]map[strin
 		if pageToken != "" {
 			params["page_token"] = pageToken
 		}
-		data, err := runtime.CallAPI("GET", apiPath, params, nil)
+		data, err := runtime.CallAPITyped("GET", apiPath, params, nil)
 		if err != nil {
 			return nil, false, "", err
 		}

shortcuts/wiki/wiki_space_create.go

@@ -8,7 +8,7 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -60,14 +60,14 @@ var WikiSpaceCreate = common.Shortcut{
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Creating wiki space %q...\n", spec.Name)
 
-		data, err := runtime.CallAPI("POST", wikiSpacesAPIPath, nil, spec.RequestBody())
+		data, err := runtime.CallAPITyped("POST", wikiSpacesAPIPath, nil, spec.RequestBody())
 		if err != nil {
 			return err
 		}
 
 		raw := common.GetMap(data, "space")
 		if raw == nil {
-			return output.Errorf(output.ExitAPI, "api_error", "wiki space create returned no space")
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki space create returned no space")
 		}
 
 		out := wikiSpaceCreateOutput(raw)
@@ -100,7 +100,7 @@ func readWikiSpaceCreateSpec(runtime *common.RuntimeContext) (wikiSpaceCreateSpe
 		Description: strings.TrimSpace(runtime.Str("description")),
 	}
 	if spec.Name == "" {
-		return wikiSpaceCreateSpec{}, output.ErrValidation("--name is required and cannot be blank")
+		return wikiSpaceCreateSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--name is required and cannot be blank").WithParam("--name")
 	}
 	return spec, nil
 }

shortcuts/wiki/wiki_space_list.go

@@ -10,6 +10,7 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -103,7 +104,7 @@ func fetchWikiSpaces(runtime *common.RuntimeContext) ([]map[string]interface{},
 		if pageToken != "" {
 			params["page_token"] = pageToken
 		}
-		data, err := runtime.CallAPI("GET", wikiSpacesAPIPath, params, nil)
+		data, err := runtime.CallAPITyped("GET", wikiSpacesAPIPath, params, nil)
 		if err != nil {
 			return nil, false, "", err
 		}
@@ -181,10 +182,10 @@ func valueOrDash(v interface{}) string {
 // +space-list and +node-list.
 func validateWikiListPagination(runtime *common.RuntimeContext, maxPageSize int) error {
 	if n := runtime.Int("page-size"); n < 1 || n > maxPageSize {
-		return common.FlagErrorf("--page-size must be between 1 and %d", maxPageSize)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-size must be between 1 and %d", maxPageSize).WithParam("--page-size")
 	}
 	if n := runtime.Int("page-limit"); n < 0 {
-		return common.FlagErrorf("--page-limit must be a non-negative integer")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-limit must be a non-negative integer").WithParam("--page-limit")
 	}
 	return nil
 }

skills/lark-apps/SKILL.md

@@ -24,7 +24,9 @@ metadata:
 | 发布本地 `index.html` 或静态目录为可访问 URL | `+html-publish` | [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md) |
 | 开发已有应用 / 初始化本地仓库（开发方式已定为本地后；先解析 app_id，勿 `+create` 新建） | `+init`（或手动 `+git-credential-init` + 原生 git） | [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md), [`lark-apps-init.md`](references/lark-apps-init.md), [`lark-apps-git-credential.md`](references/lark-apps-git-credential.md) |
 | 本地开发时 `.env.local` 损坏/丢失，重新拉取启动期环境变量 | `+env-pull` | [`lark-apps-env-pull.md`](references/lark-apps-env-pull.md) |
-| 看表、看 schema、跑 SQL、初始化 dev/online 多环境 DB | `+db-table-list`, `+db-table-get`, `+db-execute`, `+db-env-create` | 对应 `lark-apps-db-*.md` |
+| 看表 / 看结构 / 初始化多环境 / 导入导出数据 / 变更追溯 / 行级审计 / dev→online 发布 / 时间点恢复 / 查 DB 用量 | `+db-table-list`、`+db-table-get`、`+db-env-create`、`+db-data-export`/`+db-data-import`、`+db-changelog-list`、`+db-audit-status`/`+db-audit-enable`/`+db-audit-disable`/`+db-audit-list`、`+db-env-diff`/`+db-env-migrate`、`+db-recovery-diff`/`+db-recovery-apply`、`+db-quota-get` | [`lark-apps-db.md`](references/lark-apps-db.md) |
+| 逐条执行 SQL（SELECT / DML / DDL） | `+db-execute` | [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md) |
+| 管理应用文件存储：上传/下载本地文件、列出/查看/删除已存文件、生成临时分享链接、查存储用量 | `+file-upload`/`+file-download`/`+file-list`/`+file-get`/`+file-sign`/`+file-delete`/`+file-quota-get` | [`lark-apps-file.md`](references/lark-apps-file.md) |
 | **部署/上线全栈应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | `+release-create`（部署上线动作）, `+release-get`（轮询发布结果，finished 给 online_url / failed 给 error_logs）, `+release-list` | [`lark-apps-release-create.md`](references/lark-apps-release-create.md), [`lark-apps-release-get.md`](references/lark-apps-release-get.md), [`lark-apps-release-list.md`](references/lark-apps-release-list.md) |
 | 设置或查看运行时可见范围 | `+access-scope-set`, `+access-scope-get` | 对应 access-scope reference |
 | 云端 Agent 生成/迭代应用（开发方式已定为云端后） | `+session-create` -> `+chat` -> `+session-get` | [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) |

skills/lark-apps/references/lark-apps-db-env-create.md

@@ -1,31 +0,0 @@
-# apps +db-env-create
-
-把存量单库应用初始化为 `dev` / `online` 多环境数据库。运行时命令事实以 `lark-cli apps +db-env-create --help` 为准。
-
-## 何时用
-
-仅用于存量单库应用需要拆成 `dev` / `online` 两套数据库的场景。普通查看表、查 schema、执行 SQL 不需要先初始化。注意：通过 `+create --app-type full_stack` 新建的应用通常已自带多环境，无需再初始化（重复初始化会返回「已初始化」错误）。
-
-## 命令骨架
-
-- 必填：`--app-id`。
-- `--env`：要创建的环境，由调用方传入，目前只支持 `dev`（默认 `dev`）。
-- `--sync-data`：bool 开关，传 `--sync-data` 则把现有 online 数据复制到新环境；不传则不复制（默认）。
-- risk 是 `high-risk-write`；单库拆成 dev/online 后不可逆。
-
-## 示例
-
-```bash
-lark-cli apps +db-env-create --app-id app_xxx --env dev --dry-run
-lark-cli apps +db-env-create --app-id app_xxx --env dev --sync-data --yes
-```
-
-## 输出契约
-
-- 成功读取 `data.status`、`data.environments`、`data.data_synced`；pretty 会提示是否初始化、多环境列表、是否同步数据。
-- 未确认时返回 `confirmation_required` / exit 10；按 lark-shared 询问用户后再补 `--yes` 重试。
-- 如果服务端提示已启用多环境（`Multi-env is already initialized`），转述状态即可，不要重复初始化。
-
-## Agent 规则
-
-不要静默追加 `--yes`。遇到 confirmation_required 时，按 `lark-shared` 的 exit-10 协议向用户确认不可逆风险；用户明确同意后才在原 argv 末尾追加 `--yes` 重试。

skills/lark-apps/references/lark-apps-db-execute.md

@@ -26,15 +26,19 @@ lark-cli apps +db-execute --app-id app_xxx --env dev --sql - --yes < /Users/.../
 
 ## 输出契约
 
-- 成功默认 JSON 读取 `data.results[]`；每个元素对应一条 SQL，常见字段有 `sql_type`、`data`、`record_count`、`affected_rows`。
+- 成功默认 JSON 的 `data` 按 SQL 类型自适应（不透传后端原始串）：
+  - 单 SELECT → `data` 是行数组 `[{...}]`（空 → `[]`），直接 `-q '.data[].col'` 取字段。
+  - 单 DML → `data = {command, rows_affected}`（如 `{"command":"INSERT","rows_affected":1}`）。
+  - 单 DDL → `data = {command}`（如 `{"command":"CREATE_TABLE"}`）。
+  - 多语句 → `data` 是元素数组：SELECT 为 `{command:"SELECT", rows:[...]}`，DML 为 `{command, rows_affected}`，DDL 为 `{command}`。
 - pretty 会按 SELECT/DML/DDL 自适应渲染；多语句会逐条显示 Statement 摘要。
-- 失败可能仍有前序语句已执行；看 `error.detail.statement_index`、`completed`、`rolled_back` 和 `hint` 决定从哪条继续。
+- 失败返回 typed `error`（`type:"api"`、`subtype:"server_error"`、`code`、`message`、`hint`）：失败位置在 `message` 的「(at statement N of M)」；前序是否落地 / 是否整批回滚写在 `hint`——事务内失败「Transaction rolled back; no changes persisted.」；非事务多语句前序已落地「Earlier statements were committed and not rolled back; fix statement N and re-run the remaining statements.」；首句即失败（无前序落地）「No statements were applied; fix the SQL and re-run.」。据此决定整段重跑还是只跑剩余语句。
 
 ## Agent 规则
 
 - 该命令为 high-risk-write，执行一律需 `--yes`；无 `--yes` 会返回 `confirmation_required` / exit 10。
   - **只读查询、以及不删除/不丢失既有数据且可撤回的语句**：已授权时可直接带 `--yes` 执行。
   - **会删除或丢失既有数据、或难以撤回的语句**：先 `--dry-run` 预览（无需 `--yes`），向用户确认后再带 `--yes` 执行；不要在用户不知情时自动补 `--yes`。
-- 多语句失败时，失败前的语句可能已经 auto-commit。不要整批重跑；按错误 detail/hint 修失败语句，并从剩余语句继续。
+- 多语句失败时，失败前的语句可能已经 commit 落地。不要整批重跑；按错误 message/hint 修失败语句，并从剩余语句继续。
 - 如果需要原子性，让用户在 SQL 内显式写 `BEGIN` / `COMMIT`，不要假设 CLI 会包事务。
 - 不要把数据库连接串从 env 中取出来裸连。

skills/lark-apps/references/lark-apps-db-table-get.md

@@ -1,29 +0,0 @@
-# apps +db-table-get
-
-查看妙搭应用数据库某张表的结构。运行时命令事实以 `lark-cli apps +db-table-get --help` 为准。
-
-## 何时用
-
-用于查看已知表的字段、索引、约束，或给 SQL/迁移生成提供依据。只想知道有哪些表时先 `+db-table-list`。
-
-## 命令骨架
-
-- 必填：`--app-id`、`--table`。
-- `--env` 枚举：`dev` / `online`，默认 `online`。
-- `--format pretty` 会向服务端请求 DDL，并直接输出 DDL 文本；默认 JSON 返回结构化 columns/indexes/constraints/stats。
-
-## 示例
-
-```bash
-lark-cli apps +db-table-get --app-id app_xxx --table orders
-lark-cli apps +db-table-get --app-id app_xxx --table orders --env dev --format pretty
-```
-
-## 输出契约
-
-- 默认 JSON 读取 `data.name`、`columns`、`indexes`、`constraints`、`estimated_row_count`、`size_bytes`。
-- `--format pretty` stdout 是服务端返回的 DDL 文本，不是 JSON envelope；需要建表语句时可原样给用户。
-
-## Agent 规则
-
-需要给用户看建表语句或迁移参照时用 `--format pretty`；需要程序化分析字段/索引/约束时保留默认 JSON。

skills/lark-apps/references/lark-apps-db-table-list.md

@@ -1,31 +0,0 @@
-# apps +db-table-list
-
-列出妙搭应用某个数据库环境的数据表。运行时命令事实以 `lark-cli apps +db-table-list --help` 为准。
-
-## 何时用
-
-用于先摸清应用数据库里有哪些表，或在用户只给业务对象名时定位可能的表名。已知表名且要字段/索引时直接用 `+db-table-get`。
-
-## 命令骨架
-
-- 必填：`--app-id`。
-- `--env` 枚举：`dev` / `online`，默认 `online`。
-- 分页：`--page-size` 默认 20，`--page-token` 使用上一页 cursor。
-- pretty 输出列包含 `name`、`description`、`estimated_row_count`、`size`、`columns`（列数）。
-
-## 示例
-
-```bash
-lark-cli apps +db-table-list --app-id app_xxx
-lark-cli apps +db-table-list --app-id app_xxx --env dev --page-size 50
-```
-
-## 输出契约
-
-- 成功读取 `data.items[]`；每项字段是 `name`、`description`、`estimated_row_count`、`size_bytes`、`column_count`（列数）。CLI 默认不透出每表完整 `columns[]`（与 `+db-table-get` 重复且放大 token），只给 `column_count`；要完整列定义/索引/约束用 `+db-table-get`。
-- pretty 输出是 5 列扫描表：`name`、`description`、`estimated_row_count`、`size`、`columns`（即列数）。
-- 若响应带 `has_more=true`，用返回的 `page_token` / `next_page_token` 翻页。
-
-## Agent 规则
-
-用户说“本地/开发库/调试库”时优先 `--env dev`；线上问题排查用 `--env online`。如果 dev 返回服务端错误提示未初始化，多环境入口是 [`+db-env-create`](lark-apps-db-env-create.md)。

skills/lark-apps/references/lark-apps-db.md

@@ -0,0 +1,160 @@
+# apps db 域命令
+
+管理妙搭应用数据库：看表与结构、初始化与发布多环境、数据搬运、变更治理、时间点恢复、用量。逐条跑 SQL（SELECT/DML/DDL）走 [`+db-execute`](lark-apps-db-execute.md)（单独一篇）。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；认证、`--as user`、exit 码、`_notice` 等通用处理见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 与本域 [`SKILL.md`](../SKILL.md)。
+
+## 何时用
+
+用户要看应用里有哪些表 / 某张表的结构、把单库应用拆成 dev/online 多环境、把数据导进导出表、查谁在什么时候改了表结构或表数据、开关行级审计、把开发环境的库结构发布到线上、把库恢复到过去某个时间点、或看数据库用量时。逐条执行 SQL 走 [`+db-execute`](lark-apps-db-execute.md)；文件存储（上传/下载文件）走 [`lark-apps-file.md`](lark-apps-file.md)。
+
+## 命令一览
+
+| 命令 | 做什么 | 关键参数 |
+|---|---|---|
+| `+db-table-list` | 列出某环境的数据表 | `--env`、`--page-size`/`--page-token` |
+| `+db-table-get` | 看单张表的结构（字段/索引/约束/DDL） | `--table`、`--env`、`--format` |
+| `+db-env-create` | 把单库应用初始化为 dev/online 多环境（高危） | `--env`、`--sync-data`、`--yes` |
+| `+db-data-export` | 把一张表的数据导出到本地文件 | `--table`、`--output`、`--limit`、`--env` |
+| `+db-data-import` | 把本地 csv/json 文件导进一张表（高危） | `--file`、`--table`、`--env`、`--yes` |
+| `+db-changelog-list` | 查表结构变更（DDL）历史 | `--table`、`--change-id`、`--since`/`--until`、`--env` |
+| `+db-audit-status` | 看哪些表开了行级审计、保留期 | `--table`、`--env` |
+| `+db-audit-enable` | 给某表开启行级变更审计 | `--table`、`--retention`、`--env` |
+| `+db-audit-disable` | 关闭某表的行级审计 | `--table`、`--env` |
+| `+db-audit-list` | 列出表的行级变更事件（增删改追溯） | `--table`（可重复）、`--since`/`--until`、`--env` |
+| `+db-env-diff` | 预览开发环境待发布到线上的结构变更 | `--app-id` |
+| `+db-env-migrate` | 把开发环境的结构变更发布到线上（高危） | `--app-id`、`--yes` |
+| `+db-recovery-diff` | 预览把库恢复到某时间点会带来的变更 | `--target` |
+| `+db-recovery-apply` | 把库恢复到某个时间点、覆盖当前数据（高危） | `--target`、`--yes` |
+| `+db-quota-get` | 查数据库存储用量 | `--env` |
+
+## 约定（先读）
+
+- **环境 `--env dev|online`（默认 online）**：看表、看结构、数据导入导出、变更追溯、审计、配额、初始化都按环境区分，写操作建议先在 `dev` 验。`+db-env-diff`/`+db-env-migrate` 是「dev→online 发布」语义、`+db-recovery-*` 作用于当前库，二者**没有** `--env`。
+- **本地文件用工作目录内相对路径**：导入 `--file ./orders.csv`、导出 `--output ./out.csv`；路径在别处先 `cd` 过去或改成相对路径。
+- **高危操作必须带 `--yes`**：`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply` 缺省会被确认关卡拦下；动手前先用对应的预览命令或 `--dry-run` 看清影响。
+- **时间参数按口语自然传**（`--since`/`--until`/`--target`），格式见末尾。
+
+## 各命令
+
+### 表与结构
+
+**`+db-table-list`**：列出某环境的数据表。分页 `--page-size`（默认 20）/ `--page-token`（上一页 cursor）。每项给表名、描述、估算行数、大小、列数；要完整列定义 / 索引 / 约束用 `+db-table-get`。只知道业务对象名时，先用它定位可能的表名。
+
+```bash
+lark-cli apps +db-table-list --app-id app_xxx
+lark-cli apps +db-table-list --app-id app_xxx --env dev --page-size 50
+```
+
+**`+db-table-get`**：看单张表的结构。默认 JSON 给结构化的字段 / 索引 / 约束 / 估算行数 / 大小；`--format pretty` 直接输出建表 DDL 文本（给用户看建表语句或做迁移参照时用）。
+
+```bash
+lark-cli apps +db-table-get --app-id app_xxx --table orders
+lark-cli apps +db-table-get --app-id app_xxx --table orders --env dev --format pretty
+```
+
+### 多环境数据库（初始化 + 发布）
+
+**`+db-env-create`（高危）**：把存量单库应用初始化为 dev/online 两套库，不可逆，必须带 `--yes`。`--env` 目前只支持 `dev`（默认 `dev`）；`--sync-data` 把现有 online 数据复制到新环境（不传则不复制）。注意：`+create --app-type full_stack` 新建的应用通常已自带多环境，重复初始化会返回冲突错误（应用已是多环境）——按 `error.hint` 转述状态即可，别重复初始化。
+
+```bash
+lark-cli apps +db-env-create --app-id app_xxx --env dev --dry-run
+lark-cli apps +db-env-create --app-id app_xxx --env dev --sync-data --yes
+```
+
+**`+db-env-diff`**：预览开发环境里待发布到线上的表结构变更，不落地。发布前先看这个。无待发布变更时明确返回「无变更」。
+
+**`+db-env-migrate`（高危）**：把开发环境的结构变更正式发布到线上，不可逆，必须带 `--yes`，返回实际发布的变更条数。发布是异步的，命令会等到完成再返回结果。
+
+> 预览与发布同一端点，故 `+db-env-diff` 也需 `spark:app:write` scope（不是纯只读权限）。
+
+```bash
+lark-cli apps +db-env-diff --app-id app_xxx
+lark-cli apps +db-env-migrate --app-id app_xxx --yes
+```
+
+### 数据导入导出
+
+**`+db-data-export`**：把一张表导出到本地文件。导出格式**只由 `--output` 的扩展名决定**——`.csv` / `.json` / `.sql`，缺省按 `<表名>.csv` 落在当前目录。注意：全局 `--format json|pretty` 只控制**命令自身输出**（成功摘要 / 错误信封）的渲染，**不影响导出文件的格式**；`--output` 后缀必须是 `.csv/.json/.sql` 之一，否则报 validation 错误（exit 2），且不支持导出到 stdout。两道体量约束：
+
+- `--limit`（1..5000，默认 5000）是**行数上限守卫**：表的行数超过它会被整体拒掉（不是「只导前 N 行」）；
+- 导出产物 >1 MB 也会被拒。
+
+超大表别硬导：先用 `+db-execute` 加 `WHERE` / `LIMIT` 缩小范围、分批导。
+
+```bash
+lark-cli apps +db-data-export --app-id app_xxx --table orders --output ./orders.csv
+lark-cli apps +db-data-export --app-id app_xxx --table orders --output ./orders.json --env dev
+```
+
+**`+db-data-import`（高危）**：把本地 csv/json 文件的数据导进表。文件需是 `.csv`/`.json`、≤1 MB，必须带 `--yes`。目标表缺省取文件名去掉**最后一个**扩展名（如 `orders.csv`→`orders`，`orders.2026.csv`→`orders.2026`）；文件名带点号时建议显式传 `--table` 以免落到意外的表名。
+
+```bash
+lark-cli apps +db-data-import --app-id app_xxx --table orders --file ./orders.csv --env dev --yes
+```
+
+**导入/导出限额**：体积 ≤ **1 MB**、行数 ≤ **5000**，导入导出都一样，超限会被拒。超限就分批——导入拆成 ≤1 MB / ≤5000 行的多个文件，导出用 `WHERE` / `LIMIT` 缩小范围。
+
+### 变更追溯与审计
+
+**`+db-changelog-list`**：查表结构变更（DDL）历史——谁、什么时候、改了哪张表、做了什么。可按 `--table` 过滤、按 `--change-id` 精确定位某条、用 `--since`/`--until` 圈时间区间，分页 `--page-size`/`--page-token`。
+
+```bash
+lark-cli apps +db-changelog-list --app-id app_xxx --table orders --since 7d
+```
+
+**`+db-audit-status`**：看审计开关状态。给 `--table` 看单表，不给则列出所有已配置的表（开没开、保留期）。
+
+**`+db-audit-enable` / `+db-audit-disable`**：开 / 关某张表的行级变更审计。`--retention` 设保留期，取值 `7d`/`30d`/`180d`/`360d`/`forever`（默认 `7d`）。不要对已经开启审计的表重复 enable——不确定就先用 `+db-audit-status` 查。
+
+```bash
+lark-cli apps +db-audit-enable --app-id app_xxx --table orders --retention 30d
+lark-cli apps +db-audit-disable --app-id app_xxx --table orders
+```
+
+**`+db-audit-list`**：列出表的行级变更事件（INSERT/UPDATE/DELETE 的前后值与操作人）。`--table` 必填、可重复传多张表；`--since`/`--until` 圈时间。
+- **多表查询**：会先帮用户把不存在、或没开审计的表过滤掉再查，被过滤的表及原因列在结果的 `skipped` 里——据此告诉用户哪些表没纳入及为什么。
+- **单表查询**：不预过滤，表不存在 / 未开审计会直接报错（按 `error.hint` 转述给用户，引导先 `+db-audit-enable`）。
+
+```bash
+lark-cli apps +db-audit-list --app-id app_xxx --table orders --since 24h
+lark-cli apps +db-audit-list --app-id app_xxx --table orders --table users
+```
+
+### 时间点恢复（PITR）
+
+**`+db-recovery-diff`**：预览把库恢复到 `--target` 时间点会带来哪些变更（受影响的表、行数、预计耗时），不落地。同样需 `spark:app:write` scope。
+
+**`+db-recovery-apply`（高危）**：把库恢复到某个时间点，**会覆盖当前数据**，不可逆，必须带 `--yes`。
+
+- 可恢复窗口最长 **7 天**，且不早于**最近一次 `+db-env-migrate`**；超出窗口的目标会被拒。
+- 目标时间点与当前库一致时返回 `no_changes`（空操作），不算失败。
+- 动手前务必先 `+db-recovery-diff` 给用户确认。
+
+```bash
+lark-cli apps +db-recovery-diff --app-id app_xxx --target 2h
+lark-cli apps +db-recovery-apply --app-id app_xxx --target 2026-04-15T10:00:00Z --yes
+```
+
+### 配额
+
+**`+db-quota-get`**：查数据库存储用量（已用量、表数、视图数；配额接入后还会给总配额与使用率）。
+
+```bash
+lark-cli apps +db-quota-get --app-id app_xxx --env dev
+```
+
+## 时间格式（`--since` / `--until` / `--target`）
+
+按用户口语自然传入即可，支持：
+- 相对时间 `7d` / `2h` / `30s`（从现在往前推）
+- 日期 `2026-04-15`
+- 日期时间 `2026-04-15T10:00:00`
+- 带时区的 ISO 8601 `2026-04-15T10:00:00Z` / `2026-04-15T10:00:00+08:00`
+
+## Agent 规则
+
+- 用户说「本地 / 开发库 / 调试库」优先 `--env dev`，线上排查用 `--env online`；数据面写操作（导入 / 审计开关）默认先在 `dev` 验再动 `online`。
+- 看表用 `+db-table-list`，看结构用 `+db-table-get`（要建表语句加 `--format pretty`）；`+db-env-create` 仅用于存量单库拆多环境，新建的 full_stack 应用一般不需要。
+- 四个高危命令（`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply`）动手前先看清影响再带 `--yes`：发布 / 恢复先跑对应预览 `+db-env-diff` / `+db-recovery-diff`，导入无预览命令、可先 `--dry-run` 看请求或先在 `--env dev` 验；不要静默追加 `--yes`，遇 confirmation_required（exit 10）按 lark-shared 协议向用户确认不可逆风险后再补 `--yes` 重试。
+- 导入 / 导出的本地路径用工作目录内相对路径；超大表导出会被行数 / 体积上限拒，改用 `+db-execute` 分批。
+- `+db-audit-list` 多表查询时，把结果里 `skipped` 的表（不存在 / 未开审计）连同原因一并向用户说明，不要让用户以为这些表「没有变更」。
+- 恢复是覆盖式且不可逆：`+db-recovery-apply` 前必须先 `+db-recovery-diff`，并明确告知用户会覆盖当前数据。

skills/lark-apps/references/lark-apps-file.md

@@ -0,0 +1,94 @@
+# apps file 域命令（应用存储）
+
+管理妙搭应用的文件存储：上传 / 下载本地文件、列出与查看已存文件、生成临时分享链接、批量删除、查看用量。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；认证、`--as user`、exit 码、`_notice` 等通用处理见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 与本域 [`SKILL.md`](../SKILL.md)。
+
+## 何时用
+
+用户要在某个妙搭应用里上传 / 下载 / 列出 / 删除文件、拿文件的临时分享链接、或看存储用量时。普通飞书云盘走 [`lark-drive`](../../lark-drive/SKILL.md)；数据库里的表数据走 `+db-*`。
+
+## 命令一览
+
+| 命令 | 做什么 | 关键参数 |
+|---|---|---|
+| `+file-list` | 列出文件，可按名/路径/类型/大小/上传时间过滤 | `--app-id`、过滤器、`--page-size`/`--page-token` |
+| `+file-get` | 查单个文件的元数据 | `--app-id`、`--path` |
+| `+file-sign` | 生成有时效的下载链接（用于分享 / 直接下载） | `--app-id`、`--path`、`--expires-in` |
+| `+file-download` | 把远端文件保存到本地 | `--app-id`、`--path`、`--output` |
+| `+file-upload` | 上传本地文件到应用存储 | `--app-id`、`--file` |
+| `+file-delete` | 按路径批量删除文件 | `--app-id`、`--path`（可重复）、`--yes` |
+| `+file-quota-get` | 查应用的文件存储用量 | `--app-id` |
+
+## 寻址与约定（先读）
+
+- **远端文件统一用 `--path` 精确寻址**（远端路径，带前导 `/`）。只知道文件名时，先用 `+file-list --name <名>` 定位拿到 `path`，再做后续操作。
+- **本地文件 / 输出路径用工作目录内的相对路径**（如 `--file ./report.pdf`、`--output ./out.png`）；路径在别处时先 `cd` 过去或改成相对路径。
+- 上传只接收本地 `--file`：文件名沿用本地文件名，远端路径由平台分配、全局唯一（无需也无法手填）。
+- file 域不区分环境，没有 `--env`。
+
+## 各命令
+
+### +file-list
+列出应用文件，支持精确过滤：`--name`（文件名）、`--path`（远端路径）、`--type`（MIME 类型）、`--size-gt`/`--size-lt`（字节）、`--uploaded-since`/`--uploaded-until`（上传时间区间，时间格式见末尾）。分页 `--page-size`（默认 20）/ `--page-token`。列表每项给名称、路径、大小、类型、上传时间（pretty 表格即这 5 列）；上传者、下载地址（如有）仅在 JSON 输出里，单文件详情用 `+file-get`。
+
+```bash
+lark-cli apps +file-list --app-id app_xxx
+lark-cli apps +file-list --app-id app_xxx --type image/png --uploaded-since 7d
+```
+
+### +file-get
+按 `--path` 查单个文件的元数据。路径不存在时返回明确的「文件不存在」错误。
+
+```bash
+lark-cli apps +file-get --app-id app_xxx --path /1858537546760216.png
+```
+
+### +file-sign
+为指定文件生成一个**有时效的下载链接**——适合发给用户分享、或直接下载。`--expires-in` 设有效期秒数（默认 1 天，最长 30 天）。`pretty` 模式只输出链接本身，便于复制 / 管道；要把到期时间一并告诉用户时用默认 JSON 输出（含到期时间）。
+
+```bash
+lark-cli apps +file-sign --app-id app_xxx --path /1858537546760216.png --expires-in 3600
+```
+
+### +file-download
+把远端文件保存到本地。`--output` 指定保存路径，缺省时按远端文件名保存到当前目录。
+
+```bash
+lark-cli apps +file-download --app-id app_xxx --path /1858537546760216.png --output ./logo.png
+```
+
+### +file-upload
+上传一个本地文件。文件名沿用本地文件名，远端路径由平台分配。单文件上限 100 MB。
+
+```bash
+lark-cli apps +file-upload --app-id app_xxx --file ./report.pdf
+```
+
+### +file-delete（高危）
+按路径批量删除，`--path` 可重复传多个。删除是高危操作，必须带 `--yes`；缺省会被确认关卡拦下。**逐项返回结果**：部分文件删除失败（如某个路径不存在）不影响其余文件，整体仍算成功，失败项在结果里单独标出原因。
+
+```bash
+lark-cli apps +file-delete --app-id app_xxx --path /1858537546760216.png --yes
+lark-cli apps +file-delete --app-id app_xxx --path /a.png --path /b.png --yes
+```
+
+### +file-quota-get
+查应用的文件存储用量（已用量、文件数；配额接入后还会给总配额与使用率）。
+
+```bash
+lark-cli apps +file-quota-get --app-id app_xxx
+```
+
+## 时间格式（`--uploaded-since` / `--uploaded-until`）
+
+按用户口语自然传入即可，支持：
+- 相对时间 `7d` / `2h` / `30s`（从现在往前推）
+- 日期 `2026-04-15`
+- 日期时间 `2026-04-15T10:00:00`
+- 带时区的 ISO 8601 `2026-04-15T10:00:00Z` / `2026-04-15T10:00:00+08:00`
+
+## Agent 规则
+
+- 寻址一律用 `--path`；用户只给文件名时先 `+file-list --name <名>` 定位，多个同名再让用户确认。
+- 上传 / 下载的本地路径用工作目录内相对路径；不在当前目录就 `cd` 过去或改相对路径。
+- 用户要「分享链接 / 临时下载地址」时用 `+file-sign`，把返回的链接转述给用户。
+- 删除前判断意图：已明确要删且授权时可直接带 `--yes`；不确定删哪些时先 `+file-list` 给用户确认。批量删除部分失败不报错，按逐项结果向用户说明哪些成功、哪些没删掉及原因。

tests/cli_e2e/apps/apps_git_credential_dryrun_test.go

@@ -5,6 +5,8 @@ package apps
 
 import (
 	"context"
+	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -26,7 +28,8 @@ func TestAppsGitCredentialInitDryRun(t *testing.T) {
 			"--app-id", "app_xxx",
 			"--dry-run",
 		},
-		DefaultAs: "user",
+		BinaryPath: "../../../lark-cli",
+		DefaultAs:  "user",
 	})
 	require.NoError(t, err)
 	result.AssertExitCode(t, 0)
@@ -35,4 +38,56 @@ func TestAppsGitCredentialInitDryRun(t *testing.T) {
 	assert.Equal(t, "/open-apis/spark/v1/apps/app_xxx/git_info", gjson.Get(result.Stdout, "api.0.url").String())
 	assert.Equal(t, "app_xxx", gjson.Get(result.Stdout, "api.0.params.app_id").String())
 	assert.False(t, gjson.Get(result.Stdout, "api.0.body").Exists())
+	assert.Equal(t, "api-plus-local-setup", gjson.Get(result.Stdout, "mode").String())
+	assert.Equal(t, "initialize_local_git_credential", gjson.Get(result.Stdout, "action").String())
+	assert.True(t, strings.HasSuffix(gjson.Get(result.Stdout, "metadata_file").String(), filepath.Join("spark", "app_xxx", "git.json")))
+	assert.Equal(t, int64(3), gjson.Get(result.Stdout, "local_effects.#").Int())
+	assert.Equal(t, "save the issued PAT in the local system credential store", gjson.Get(result.Stdout, "local_effects.0").String())
+	assert.Equal(t, "write app-scoped git credential metadata", gjson.Get(result.Stdout, "local_effects.1").String())
+	assert.Equal(t, "configure a URL-scoped Git credential helper in global git config when possible", gjson.Get(result.Stdout, "local_effects.2").String())
+}
+
+func TestAppsGitCredentialListDryRun(t *testing.T) {
+	setAppsDryRunEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args:       []string{"apps", "+git-credential-list", "--dry-run"},
+		BinaryPath: "../../../lark-cli",
+		DefaultAs:  "user",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	assert.Equal(t, "Preview local Git credential listing (no API call, read-only local state).", gjson.Get(result.Stdout, "description").String())
+	assert.Equal(t, "local-read-only", gjson.Get(result.Stdout, "mode").String())
+	assert.Equal(t, "list_local_git_credentials", gjson.Get(result.Stdout, "action").String())
+	assert.Equal(t, int64(0), gjson.Get(result.Stdout, "api.#").Int())
+	assert.Contains(t, gjson.Get(result.Stdout, "storage_root").String(), filepath.Join("", "spark"))
+	assert.Equal(t, "scan app-scoped git credential metadata under the CLI config directory", gjson.Get(result.Stdout, "reads.0").String())
+}
+
+func TestAppsGitCredentialRemoveDryRun(t *testing.T) {
+	setAppsDryRunEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args:       []string{"apps", "+git-credential-remove", "--app-id", "app_xxx", "--dry-run"},
+		BinaryPath: "../../../lark-cli",
+		DefaultAs:  "user",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	assert.Equal(t, "Preview local Git credential cleanup (no API call; would clean up local-only state).", gjson.Get(result.Stdout, "description").String())
+	assert.Equal(t, "local-cleanup-only", gjson.Get(result.Stdout, "mode").String())
+	assert.Equal(t, "remove_local_git_credential", gjson.Get(result.Stdout, "action").String())
+	assert.Equal(t, "app_xxx", gjson.Get(result.Stdout, "app_id").String())
+	assert.Equal(t, int64(0), gjson.Get(result.Stdout, "api.#").Int())
+	assert.True(t, strings.HasSuffix(gjson.Get(result.Stdout, "metadata_file").String(), filepath.Join("spark", "app_xxx", "git.json")))
+	assert.Equal(t, "read app-scoped git credential metadata", gjson.Get(result.Stdout, "effects.0").String())
 }