chore(release): v1.0.34 (#972)

Change-Id: I0908c20f6ab9cf76a5d75cc1c81871591aa6a841

.gitignore

@@ -41,3 +41,4 @@ app.log
 /sidecar-server-demo
 /server-demo
 .tmp/
+cover*.out

.golangci.yml

@@ -45,6 +45,7 @@ linters:
       - path: _test\.go$
         linters:
           - bodyclose
+          - bidichk
           - gocritic
           - depguard
           - forbidigo

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.34] - 2026-05-19
+
+### Features
+
+- **drive**: Switch markdown export to V2 `docs_ai` fetch API (#948)
+- **drive**: Add `+inspect` shortcut for document URL inspection with wiki unwrapping (#947)
+- **wiki**: Add `+node-get` / `+node-delete` / `+space-create` shortcuts (#904)
+- **base**: Support Base attachment APIs (#887)
+- **mail**: Validate `bot` + `mailbox=me` and add dynamic `--as` help tests (#895)
+- **mail**: Expose draft priority in `--inspect` projection and document `--set-priority` (#779)
+
+### Bug Fixes
+
+- **identitydiag**: Harden verify path and tighten status semantics (#961)
+- **wiki**: Surface real node URL for `+node-create` / `+node-copy` (#960)
+- **auth**: Split bot and user identity diagnostics (#957)
+- **base**: Address Base attachment review follow-ups (#958)
+- **docs**: Clarify `replace_all` selection errors (#954)
+
+### Documentation
+
+- **drive**: Clarify add comment constraints (#967)
+- **lark-im**: Clarify message activity search (#865)
+
+### Tests
+
+- Verify e2e resource cleanup (#949)
+- **lint**: Exclude `bidichk` from test files (#959)
+
 ## [v1.0.33] - 2026-05-18
 
 ### Features
@@ -745,6 +774,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.34]: https://github.com/larksuite/cli/releases/tag/v1.0.34
 [v1.0.33]: https://github.com/larksuite/cli/releases/tag/v1.0.33
 [v1.0.32]: https://github.com/larksuite/cli/releases/tag/v1.0.32
 [v1.0.31]: https://github.com/larksuite/cli/releases/tag/v1.0.31

cmd/auth/status.go

@@ -5,13 +5,11 @@ package auth
 
 import (
 	"context"
-	"time"
 
 	"github.com/spf13/cobra"
 
-	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/identitydiag"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -60,73 +58,83 @@ func authStatusRun(opts *StatusOptions) error {
 		"defaultAs": defaultAs,
 	}
 
-	if config.UserOpenId == "" {
-		result["identity"] = "bot"
-		result["note"] = "No user logged in. Only bot (tenant) identity is available for API calls. Run `lark-cli auth login` to log in."
-		output.PrintJson(f.IOStreams.Out, result)
-		return nil
-	}
-
-	stored := larkauth.GetStoredToken(config.AppID, config.UserOpenId)
-	if stored == nil {
-		result["identity"] = "bot"
-		result["userName"] = config.UserName
-		result["userOpenId"] = config.UserOpenId
-		result["note"] = "Token does not exist or has been cleared. Only bot (tenant) identity is available. Re-login: lark-cli auth login"
-		output.PrintJson(f.IOStreams.Out, result)
-		return nil
-	}
-
-	status := larkauth.TokenStatus(stored)
-	if status == "expired" {
-		result["identity"] = "bot"
-		result["note"] = "User token has expired. Only bot (tenant) identity is available. Re-login: lark-cli auth login"
-	} else {
-		result["identity"] = "user"
-	}
-	result["userName"] = config.UserName
-	result["userOpenId"] = config.UserOpenId
-	result["tokenStatus"] = status
-	result["scope"] = stored.Scope
-	result["expiresAt"] = time.UnixMilli(stored.ExpiresAt).Format(time.RFC3339)
-	result["refreshExpiresAt"] = time.UnixMilli(stored.RefreshExpiresAt).Format(time.RFC3339)
-	result["grantedAt"] = time.UnixMilli(stored.GrantedAt).Format(time.RFC3339)
-
-	// --verify: call the server to confirm token is actually usable.
-	if opts.Verify && status != "expired" {
-		verified, verifyErr := verifyTokenOnServer(f, config)
-		result["verified"] = verified
-		if verifyErr != "" {
-			result["verifyError"] = verifyErr
-		}
-	}
+	diagnostics := identitydiag.Diagnose(context.Background(), f, config, opts.Verify)
+	result["identities"] = diagnostics
+	result["identity"] = effectiveIdentity(diagnostics)
+	addLegacyUserFields(result, diagnostics.User)
+	addEffectiveVerification(result, diagnostics)
+	addStatusNote(result, diagnostics)
 
 	output.PrintJson(f.IOStreams.Out, result)
 	return nil
 }
 
-// verifyTokenOnServer obtains a valid access token (refreshing if needed)
-// and calls /authen/v1/user_info to confirm the server accepts it.
-// Returns (true, "") on success or (false, reason) on failure.
-func verifyTokenOnServer(f *cmdutil.Factory, config *core.CliConfig) (bool, string) {
-	httpClient, err := f.HttpClient()
-	if err != nil {
-		return false, "failed to create HTTP client: " + err.Error()
-	}
+const (
+	identityUser = "user"
+	identityBot  = "bot"
+	identityNone = "none"
+)
 
-	token, err := larkauth.GetValidAccessToken(httpClient, larkauth.NewUATCallOptions(config, f.IOStreams.ErrOut))
-	if err != nil {
-		return false, "token unusable: " + err.Error()
+func effectiveIdentity(d identitydiag.Result) string {
+	switch {
+	case d.User.Available:
+		return identityUser
+	case d.Bot.Available:
+		return identityBot
+	default:
+		return identityNone
+	}
+}
+
+func addLegacyUserFields(result map[string]interface{}, user identitydiag.Identity) {
+	if user.OpenID == "" {
+		return
+	}
+	result["userName"] = user.UserName
+	result["userOpenId"] = user.OpenID
+	if user.TokenStatus != "" {
+		result["tokenStatus"] = user.TokenStatus
+	}
+	if user.Scope != "" {
+		result["scope"] = user.Scope
+	}
+	if user.ExpiresAt != "" {
+		result["expiresAt"] = user.ExpiresAt
+	}
+	if user.RefreshExpiresAt != "" {
+		result["refreshExpiresAt"] = user.RefreshExpiresAt
+	}
+	if user.GrantedAt != "" {
+		result["grantedAt"] = user.GrantedAt
+	}
+}
+
+func addEffectiveVerification(result map[string]interface{}, d identitydiag.Result) {
+	switch result["identity"] {
+	case identityUser:
+		if d.User.Verified != nil {
+			result["verified"] = *d.User.Verified
+			if !*d.User.Verified {
+				result["verifyError"] = d.User.Message
+			}
+		}
+	case identityBot:
+		if d.Bot.Verified != nil {
+			result["verified"] = *d.Bot.Verified
+			if !*d.Bot.Verified {
+				result["verifyError"] = d.Bot.Message
+			}
+		}
+	}
+}
+
+func addStatusNote(result map[string]interface{}, d identitydiag.Result) {
+	switch {
+	case !d.User.Available && d.Bot.Available:
+		result["note"] = "User identity is " + identitydiag.StatusMessage(d.User.Status) + "; bot identity is ready for bot/tenant API calls. Run `lark-cli auth login` to enable user identity."
+	case d.User.Status == identitydiag.StatusNeedsRefresh:
+		result["note"] = "User identity needs refresh and will be refreshed automatically on the next user API call."
+	case !d.User.Available && !d.Bot.Available:
+		result["note"] = "No usable identity is available. Configure bot credentials or run `lark-cli auth login`."
 	}
-
-	sdk, err := f.LarkClient()
-	if err != nil {
-		return false, "failed to create SDK client: " + err.Error()
-	}
-
-	if err := larkauth.VerifyUserToken(context.Background(), sdk, token); err != nil {
-		return false, "server rejected token: " + err.Error()
-	}
-
-	return true, ""
 }

cmd/auth/status_test.go

@@ -0,0 +1,96 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestAuthStatusRun_SplitsBotAndUserIdentity(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+
+	if err := authStatusRun(&StatusOptions{Factory: f}); err != nil {
+		t.Fatalf("authStatusRun() error = %v", err)
+	}
+
+	var got statusOutput
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+	if got.Identity != "bot" {
+		t.Fatalf("identity = %q, want bot", got.Identity)
+	}
+	if got.Identities.Bot.Status != "ready" || !got.Identities.Bot.Available {
+		t.Fatalf("bot = %#v, want ready and available", got.Identities.Bot)
+	}
+	if got.Identities.User.Status != "missing" || got.Identities.User.Available {
+		t.Fatalf("user = %#v, want missing and unavailable", got.Identities.User)
+	}
+}
+
+func TestAuthStatusRun_VerifyReportsBotIdentity(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    "/open-apis/bot/v3/info",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"bot": map[string]interface{}{
+				"open_id":  "ou_bot",
+				"app_name": "diagnostic bot",
+			},
+		},
+	})
+
+	if err := authStatusRun(&StatusOptions{Factory: f, Verify: true}); err != nil {
+		t.Fatalf("authStatusRun() error = %v", err)
+	}
+
+	var got statusOutput
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+	if got.Identity != "bot" {
+		t.Fatalf("identity = %q, want bot", got.Identity)
+	}
+	if got.Verified == nil || !*got.Verified {
+		t.Fatalf("verified = %v, want true", got.Verified)
+	}
+	if got.Identities.Bot.Verified == nil || !*got.Identities.Bot.Verified {
+		t.Fatalf("bot verified = %v, want true", got.Identities.Bot.Verified)
+	}
+	if got.Identities.Bot.OpenID != "ou_bot" {
+		t.Fatalf("bot open id = %q, want ou_bot", got.Identities.Bot.OpenID)
+	}
+	if got.Identities.User.Status != "missing" {
+		t.Fatalf("user status = %q, want missing", got.Identities.User.Status)
+	}
+}
+
+type statusOutput struct {
+	Identity   string `json:"identity"`
+	Verified   *bool  `json:"verified"`
+	Identities struct {
+		Bot  statusIdentity `json:"bot"`
+		User statusIdentity `json:"user"`
+	} `json:"identities"`
+}
+
+type statusIdentity struct {
+	Status    string `json:"status"`
+	Available bool   `json:"available"`
+	Verified  *bool  `json:"verified"`
+	OpenID    string `json:"openId"`
+}

cmd/doctor/doctor.go

@@ -14,10 +14,10 @@ import (
 
 	"github.com/spf13/cobra"
 
-	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/identitydiag"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/update"
 )
@@ -51,7 +51,7 @@ func NewCmdDoctor(f *cmdutil.Factory) *cobra.Command {
 // checkResult represents one diagnostic check.
 type checkResult struct {
 	Name    string `json:"name"`
-	Status  string `json:"status"` // "pass", "fail", "skip"
+	Status  string `json:"status"` // "pass", "warn", "fail", "skip"
 	Message string `json:"message"`
 	Hint    string `json:"hint,omitempty"`
 }
@@ -118,59 +118,31 @@ func doctorRun(opts *DoctorOptions) error {
 
 	ep := core.ResolveEndpoints(cfg.Brand)
 
-	// ── 3. Token exists ──
-	if cfg.UserOpenId == "" {
-		checks = append(checks, fail("token_exists", "no user logged in", "run: lark-cli auth login --help"))
-		checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
-		return finishDoctor(f, checks)
-	}
-	stored := larkauth.GetStoredToken(cfg.AppID, cfg.UserOpenId)
-	if stored == nil {
-		checks = append(checks, fail("token_exists", "no token in keychain for "+cfg.UserOpenId, "run: lark-cli auth login --help"))
-		checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
-		return finishDoctor(f, checks)
-	}
-	checks = append(checks, pass("token_exists", fmt.Sprintf("token found for %s (%s)", cfg.UserName, cfg.UserOpenId)))
-
-	// ── 4. Token local validity ──
-	status := larkauth.TokenStatus(stored)
-	switch status {
-	case "valid":
-		checks = append(checks, pass("token_local", "token valid, expires "+time.UnixMilli(stored.ExpiresAt).Format(time.RFC3339)))
-	case "needs_refresh":
-		checks = append(checks, pass("token_local", "token needs refresh (will auto-refresh on next call)"))
-	default: // expired
-		checks = append(checks, fail("token_local", "token expired", "run: lark-cli auth login --help"))
-		checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
-		return finishDoctor(f, checks)
-	}
-
-	// ── 5. Token server verification ──
-	if opts.Offline {
-		checks = append(checks, skip("token_verified", "skipped (--offline)"))
+	// ── 3. Identity readiness ──
+	diagnostics := identitydiag.Diagnose(opts.Ctx, f, cfg, !opts.Offline)
+	checks = append(checks,
+		identityCheck("bot_identity", diagnostics.Bot),
+		identityCheck("user_identity", diagnostics.User),
+	)
+	if diagnostics.Bot.Available || diagnostics.User.Available {
+		checks = append(checks, pass("identity_ready", "at least one identity is available"))
 	} else {
-		httpClient := mustHTTPClient(f)
-		token, err := larkauth.GetValidAccessToken(httpClient, larkauth.NewUATCallOptions(cfg, f.IOStreams.ErrOut))
-		if err != nil {
-			checks = append(checks, fail("token_verified", "cannot obtain valid token: "+err.Error(), "run: lark-cli auth login --help"))
-		} else {
-			sdk, err := f.LarkClient()
-			if err != nil {
-				checks = append(checks, fail("token_verified", "SDK init failed: "+err.Error(), ""))
-			} else if err := larkauth.VerifyUserToken(opts.Ctx, sdk, token); err != nil {
-				checks = append(checks, fail("token_verified", "server rejected token: "+err.Error(), "run: lark-cli auth login --help"))
-			} else {
-				checks = append(checks, pass("token_verified", "server confirmed token is valid"))
-			}
-		}
+		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", "run: lark-cli auth status --verify"))
 	}
 
-	// ── 6 & 7. Endpoint reachability ──
+	// ── 4 & 5. Endpoint reachability ──
 	checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
 
 	return finishDoctor(f, checks)
 }
 
+func identityCheck(name string, id identitydiag.Identity) checkResult {
+	if id.Available {
+		return pass(name, id.Message)
+	}
+	return warn(name, id.Message, id.Hint)
+}
+
 // networkChecks probes Open API and MCP endpoints concurrently.
 func networkChecks(ctx context.Context, opts *DoctorOptions, ep core.Endpoints) []checkResult {
 	if opts.Offline {
@@ -232,15 +204,6 @@ func probeEndpoint(ctx context.Context, client *http.Client, url string) error {
 	return nil
 }
 
-// mustHTTPClient returns f.HttpClient() or a default client.
-func mustHTTPClient(f *cmdutil.Factory) *http.Client {
-	c, err := f.HttpClient()
-	if err != nil {
-		return &http.Client{Timeout: 30 * time.Second}
-	}
-	return c
-}
-
 // checkCLIUpdate actively queries the npm registry for the latest version.
 // Unlike the root-level async check, this does a synchronous fetch with timeout
 // and works regardless of build version (dev builds included).

cmd/doctor/doctor_test.go

@@ -95,3 +95,59 @@ func TestNetworkChecks_Offline(t *testing.T) {
 		}
 	}
 }
+
+func TestDoctorRun_SplitsBotAndMissingUserIdentity(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{
+				Name:      "default",
+				AppId:     "test-app",
+				AppSecret: core.PlainSecret("secret"),
+				Brand:     core.BrandFeishu,
+			},
+		},
+	}); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	err := doctorRun(&DoctorOptions{
+		Factory: f,
+		Ctx:     context.Background(),
+		Offline: true,
+	})
+	if err != nil {
+		t.Fatalf("doctorRun() error = %v", err)
+	}
+
+	var got struct {
+		OK     bool          `json:"ok"`
+		Checks []checkResult `json:"checks"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+	if !got.OK {
+		t.Fatalf("ok = false, want true; checks = %#v", got.Checks)
+	}
+	assertCheck(t, got.Checks, "bot_identity", "pass")
+	assertCheck(t, got.Checks, "user_identity", "warn")
+	assertCheck(t, got.Checks, "identity_ready", "pass")
+}
+
+func assertCheck(t *testing.T, checks []checkResult, name, status string) {
+	t.Helper()
+	for _, check := range checks {
+		if check.Name == name {
+			if check.Status != status {
+				t.Fatalf("%s status = %q, want %q", name, check.Status, status)
+			}
+			return
+		}
+	}
+	t.Fatalf("check %q not found in %#v", name, checks)
+}

internal/cmdutil/identity_flag_test.go

@@ -5,6 +5,7 @@ package cmdutil
 
 import (
 	"context"
+	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/internal/core"
@@ -66,3 +67,49 @@ func TestAddShortcutIdentityFlag_NoDefault(t *testing.T) {
 		t.Fatalf("default value = %q, want empty string", got)
 	}
 }
+
+// TC-10: AuthTypes=["user"] → usage contains "identity type: user" and NOT "bot".
+func TestAddShortcutIdentityFlag_UserOnlyAuthTypes(t *testing.T) {
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "a", AppSecret: "s"})
+	cmd := &cobra.Command{Use: "test"}
+
+	AddShortcutIdentityFlag(context.Background(), cmd, f, []string{"user"})
+
+	flag := cmd.Flags().Lookup("as")
+	if flag == nil {
+		t.Fatal("expected --as flag to be registered")
+	}
+	if flag.Hidden {
+		t.Fatal("expected --as flag to be visible")
+	}
+	wantUsage := "identity type: user"
+	if flag.Usage != wantUsage {
+		t.Errorf("Usage = %q, want %q", flag.Usage, wantUsage)
+	}
+	if strings.Contains(flag.Usage, "bot") {
+		t.Errorf("Usage should not contain \"bot\" for user-only shortcut, got %q", flag.Usage)
+	}
+}
+
+// TC-11: AuthTypes=["user","bot"] → usage == "identity type: user | bot".
+func TestAddShortcutIdentityFlag_UserBotAuthTypes(t *testing.T) {
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "a", AppSecret: "s"})
+	cmd := &cobra.Command{Use: "test"}
+
+	AddShortcutIdentityFlag(context.Background(), cmd, f, []string{"user", "bot"})
+
+	flag := cmd.Flags().Lookup("as")
+	if flag == nil {
+		t.Fatal("expected --as flag to be registered")
+	}
+	if flag.Hidden {
+		t.Fatal("expected --as flag to be visible")
+	}
+	if got := flag.DefValue; got != "" {
+		t.Fatalf("default value = %q, want empty string", got)
+	}
+	wantUsage := "identity type: user | bot"
+	if flag.Usage != wantUsage {
+		t.Errorf("Usage = %q, want %q", flag.Usage, wantUsage)
+	}
+}

internal/identitydiag/diagnostics.go

@@ -0,0 +1,325 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package identitydiag
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+)
+
+const (
+	StatusReady         = "ready"
+	StatusNotConfigured = "not_configured"
+	StatusMissing       = "missing"
+	StatusNeedsRefresh  = "needs_refresh"
+	StatusVerifyFailed  = "verify_failed"
+)
+
+// verifyTimeout bounds each network call made during --verify so that a
+// hanging server cannot wedge `auth status --verify` or `doctor`. Mirrors
+// the 10s timeout used by the doctor endpoint probe.
+const verifyTimeout = 10 * time.Second
+
+// Result describes the independently usable bot and user identities.
+type Result struct {
+	Bot  Identity `json:"bot"`
+	User Identity `json:"user"`
+}
+
+// Identity is a single identity diagnostic result.
+type Identity struct {
+	Status           string `json:"status"`
+	Available        bool   `json:"available"`
+	Verified         *bool  `json:"verified,omitempty"`
+	Message          string `json:"message,omitempty"`
+	Hint             string `json:"hint,omitempty"`
+	OpenID           string `json:"openId,omitempty"`
+	AppName          string `json:"appName,omitempty"`
+	UserName         string `json:"userName,omitempty"`
+	TokenStatus      string `json:"tokenStatus,omitempty"`
+	Scope            string `json:"scope,omitempty"`
+	ExpiresAt        string `json:"expiresAt,omitempty"`
+	RefreshExpiresAt string `json:"refreshExpiresAt,omitempty"`
+	GrantedAt        string `json:"grantedAt,omitempty"`
+}
+
+// Diagnose checks bot and user identities separately. When verify is false,
+// it only reports local readiness and skips server calls.
+func Diagnose(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, verify bool) Result {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	return Result{
+		Bot:  diagnoseBot(ctx, f, cfg, verify),
+		User: diagnoseUser(ctx, f, cfg, verify),
+	}
+}
+
+func diagnoseBot(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, verify bool) Identity {
+	if cfg == nil || cfg.AppID == "" {
+		return Identity{
+			Status:  StatusNotConfigured,
+			Message: "Bot identity: not configured (missing app config)",
+			Hint:    "run: lark-cli config --help",
+		}
+	}
+	if !cfg.CanBot() {
+		return Identity{
+			Status:  StatusNotConfigured,
+			Message: "Bot identity: not configured (bot identity is not available in current credential context)",
+			Hint:    "check strict mode or the active credential provider",
+		}
+	}
+	if cfg.SupportedIdentities == 0 && !credential.HasRealAppSecret(cfg.AppSecret) {
+		return Identity{
+			Status:  StatusNotConfigured,
+			Message: "Bot identity: not configured (missing app secret or bot token)",
+			Hint:    "run: lark-cli config --help",
+		}
+	}
+
+	id := Identity{
+		Status:    StatusReady,
+		Available: true,
+		Message:   "Bot identity: ready",
+	}
+	if !verify {
+		return id
+	}
+
+	token, err := resolveBotToken(ctx, f, cfg)
+	if err != nil {
+		status := StatusVerifyFailed
+		var unavailable *credential.TokenUnavailableError
+		if errors.As(err, &unavailable) {
+			status = StatusNotConfigured
+		}
+		return Identity{
+			Status:   status,
+			Verified: boolPtr(false),
+			Message:  "Bot identity: " + StatusMessage(status) + ": " + err.Error(),
+			Hint:     "check app credentials or the active credential provider",
+		}
+	}
+
+	info, err := fetchBotInfo(ctx, f, cfg, token)
+	if err != nil {
+		return Identity{
+			Status:   StatusVerifyFailed,
+			Verified: boolPtr(false),
+			Message:  "Bot identity: verify failed: " + err.Error(),
+			Hint:     "check app credentials, scopes, network, or tenant access token configuration",
+		}
+	}
+
+	id.Verified = boolPtr(true)
+	id.OpenID = info.OpenID
+	id.AppName = info.AppName
+	return id
+}
+
+func diagnoseUser(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, verify bool) Identity {
+	if cfg == nil || cfg.AppID == "" {
+		return Identity{
+			Status:  StatusNotConfigured,
+			Message: "User identity: not configured (missing app config)",
+			Hint:    "run: lark-cli config --help",
+		}
+	}
+	if cfg.UserOpenId == "" {
+		return Identity{
+			Status:  StatusMissing,
+			Message: "User identity: missing (no user logged in)",
+			Hint:    "run: lark-cli auth login --help",
+		}
+	}
+
+	id := Identity{
+		UserName: cfg.UserName,
+		OpenID:   cfg.UserOpenId,
+	}
+	stored := larkauth.GetStoredToken(cfg.AppID, cfg.UserOpenId)
+	if stored == nil {
+		id.Status = StatusMissing
+		id.Message = "User identity: missing (no token in keychain for " + cfg.UserOpenId + ")"
+		id.Hint = "run: lark-cli auth login --help"
+		return id
+	}
+
+	fillTokenFields(&id, stored)
+	switch larkauth.TokenStatus(stored) {
+	case "valid":
+		id.Status = StatusReady
+		id.Available = true
+		id.Message = "User identity: ready"
+	case "needs_refresh":
+		id.Status = StatusNeedsRefresh
+		id.Available = true
+		id.Message = "User identity: needs refresh (will auto-refresh on next user API call)"
+	default:
+		id.Status = StatusMissing
+		id.Message = "User identity: missing (refresh token expired)"
+		id.Hint = "run: lark-cli auth login --help"
+		return id
+	}
+
+	if !verify {
+		return id
+	}
+
+	markVerifyFailed := func(reason, hint string) Identity {
+		id.Status = StatusVerifyFailed
+		id.Available = false
+		id.Verified = boolPtr(false)
+		id.Message = "User identity: verify failed: " + reason
+		if hint != "" {
+			id.Hint = hint
+		}
+		return id
+	}
+
+	httpClient, err := f.HttpClient()
+	if err != nil {
+		return markVerifyFailed("create HTTP client: "+err.Error(), "")
+	}
+	token, err := larkauth.GetValidAccessToken(httpClient, larkauth.NewUATCallOptions(cfg, f.IOStreams.ErrOut))
+	if err != nil {
+		return markVerifyFailed("token unusable: "+err.Error(), "run: lark-cli auth login --help")
+	}
+	sdk, err := f.LarkClient()
+	if err != nil {
+		return markVerifyFailed("SDK init failed: "+err.Error(), "")
+	}
+	verifyCtx, cancel := context.WithTimeout(ctx, verifyTimeout)
+	defer cancel()
+	if err := larkauth.VerifyUserToken(verifyCtx, sdk, token); err != nil {
+		return markVerifyFailed("server rejected token: "+err.Error(), "run: lark-cli auth login --help")
+	}
+
+	id.Verified = boolPtr(true)
+	if id.Status == StatusReady {
+		id.Message = "User identity: ready"
+	} else {
+		id.Message = "User identity: needs refresh (server verification succeeded after refresh)"
+	}
+	return id
+}
+
+func resolveBotToken(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig) (string, error) {
+	if f == nil || f.Credential == nil {
+		return "", &credential.TokenUnavailableError{Type: credential.TokenTypeTAT}
+	}
+	result, err := f.Credential.ResolveToken(ctx, credential.NewTokenSpec(core.AsBot, cfg.AppID))
+	if err != nil {
+		return "", err
+	}
+	if result == nil || result.Token == "" {
+		return "", &credential.TokenUnavailableError{Type: credential.TokenTypeTAT}
+	}
+	return result.Token, nil
+}
+
+type botInfo struct {
+	OpenID  string
+	AppName string
+}
+
+func fetchBotInfo(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, token string) (*botInfo, error) {
+	httpClient, err := f.HttpClient()
+	if err != nil {
+		return nil, fmt.Errorf("create HTTP client: %w", err)
+	}
+	ctx, cancel := context.WithTimeout(ctx, verifyTimeout)
+	defer cancel()
+	url := strings.TrimRight(core.ResolveEndpoints(cfg.Brand).Open, "/") + "/open-apis/bot/v3/info"
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+	// /open-apis/bot/v3/info returns `{code, msg, bot: {...}}` — the bot
+	// payload is under "bot", not "data" as the newer Lark API convention.
+	var envelope struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+		Data struct {
+			OpenID  string `json:"open_id"`
+			AppName string `json:"app_name"`
+		} `json:"bot"`
+	}
+	parseErr := json.Unmarshal(body, &envelope)
+
+	if resp.StatusCode >= 400 {
+		// Lark error responses are usually `{code, msg}` envelopes even on
+		// non-2xx — surface them when present so callers see why bot auth
+		// was rejected, not just the bare HTTP code.
+		if parseErr == nil && envelope.Code != 0 {
+			return nil, fmt.Errorf("HTTP %d: [%d] %s", resp.StatusCode, envelope.Code, envelope.Msg)
+		}
+		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+	if parseErr != nil {
+		return nil, fmt.Errorf("parse response: %w", parseErr)
+	}
+	if envelope.Code != 0 {
+		return nil, fmt.Errorf("[%d] %s", envelope.Code, envelope.Msg)
+	}
+	if envelope.Data.OpenID == "" {
+		return nil, errors.New("open_id is empty")
+	}
+	return &botInfo{OpenID: envelope.Data.OpenID, AppName: envelope.Data.AppName}, nil
+}
+
+func fillTokenFields(id *Identity, token *larkauth.StoredUAToken) {
+	id.TokenStatus = larkauth.TokenStatus(token)
+	id.Scope = token.Scope
+	id.ExpiresAt = formatMillis(token.ExpiresAt)
+	id.RefreshExpiresAt = formatMillis(token.RefreshExpiresAt)
+	id.GrantedAt = formatMillis(token.GrantedAt)
+}
+
+func formatMillis(ms int64) string {
+	if ms <= 0 {
+		return ""
+	}
+	return time.UnixMilli(ms).Format(time.RFC3339)
+}
+
+func StatusMessage(status string) string {
+	switch status {
+	case StatusNotConfigured:
+		return "not configured"
+	case StatusVerifyFailed:
+		return "verify failed"
+	case StatusNeedsRefresh:
+		return "needs refresh"
+	case StatusMissing:
+		return "missing"
+	default:
+		return status
+	}
+}
+
+func boolPtr(v bool) *bool {
+	return &v
+}

internal/identitydiag/diagnostics_test.go

@@ -0,0 +1,350 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package identitydiag
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/zalando/go-keyring"
+)
+
+func TestDiagnose_NoUserReportsBotReadyAndUserMissing(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu}
+	f, _, _, _ := cmdutil.TestFactory(t, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, false)
+	if got.Bot.Status != StatusReady || !got.Bot.Available {
+		t.Fatalf("bot = %#v, want ready and available", got.Bot)
+	}
+	if got.User.Status != StatusMissing || got.User.Available {
+		t.Fatalf("user = %#v, want missing and unavailable", got.User)
+	}
+}
+
+func TestDiagnose_BotIdentityNotConfigured(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "test-app", Brand: core.BrandFeishu}
+	f, _, _, _ := cmdutil.TestFactory(t, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, false)
+	if got.Bot.Status != StatusNotConfigured || got.Bot.Available {
+		t.Fatalf("bot = %#v, want not_configured and unavailable", got.Bot)
+	}
+}
+
+func TestDiagnose_VerifyBotIdentity(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu}
+	f, _, _, reg := cmdutil.TestFactory(t, cfg)
+	stub := &httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    "/open-apis/bot/v3/info",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"bot": map[string]interface{}{
+				"open_id":  "ou_bot",
+				"app_name": "diagnostic bot",
+			},
+		},
+	}
+	reg.Register(stub)
+
+	got := Diagnose(context.Background(), f, cfg, true)
+	if got.Bot.Status != StatusReady || !got.Bot.Available {
+		t.Fatalf("bot = %#v, want ready and available", got.Bot)
+	}
+	if got.Bot.Verified == nil || !*got.Bot.Verified {
+		t.Fatalf("bot verified = %v, want true", got.Bot.Verified)
+	}
+	if got.Bot.OpenID != "ou_bot" || got.Bot.AppName != "diagnostic bot" {
+		t.Fatalf("bot info = %#v, want open id and app name", got.Bot)
+	}
+	if got := stub.CapturedHeaders.Get("Authorization"); got != "Bearer test-token" {
+		t.Fatalf("Authorization = %q, want %q", got, "Bearer test-token")
+	}
+}
+
+func TestDiagnose_VerifyUserIdentity(t *testing.T) {
+	keyring.MockInit()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
+
+	cfg := &core.CliConfig{
+		AppID:      "test-app-user",
+		AppSecret:  "secret",
+		Brand:      core.BrandFeishu,
+		UserOpenId: "ou_user",
+		UserName:   "tester",
+	}
+	now := time.Now()
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:            cfg.AppID,
+		UserOpenId:       cfg.UserOpenId,
+		AccessToken:      "user-access-token",
+		RefreshToken:     "refresh-token",
+		ExpiresAt:        now.Add(time.Hour).UnixMilli(),
+		RefreshExpiresAt: now.Add(24 * time.Hour).UnixMilli(),
+		GrantedAt:        now.Add(-time.Hour).UnixMilli(),
+		Scope:            "offline_access",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, _, reg := cmdutil.TestFactory(t, cfg)
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    "/open-apis/bot/v3/info",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"bot": map[string]interface{}{
+				"open_id":  "ou_bot",
+				"app_name": "diagnostic bot",
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    larkauth.PathUserInfoV1,
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+		},
+	})
+
+	got := Diagnose(context.Background(), f, cfg, true)
+	if got.User.Status != StatusReady || !got.User.Available {
+		t.Fatalf("user = %#v, want ready and available", got.User)
+	}
+	if got.User.Verified == nil || !*got.User.Verified {
+		t.Fatalf("user verified = %v, want true", got.User.Verified)
+	}
+	if got.User.OpenID != "ou_user" || got.User.UserName != "tester" {
+		t.Fatalf("user = %#v, want user identity details", got.User)
+	}
+}
+
+func TestDiagnose_VerifyBotIdentity_HTTPErrorSurfacesEnvelope(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu}
+	f, _, _, reg := cmdutil.TestFactory(t, cfg)
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    "/open-apis/bot/v3/info",
+		Status: http.StatusUnauthorized,
+		Body: map[string]interface{}{
+			"code": 99991663,
+			"msg":  "app ticket invalid",
+		},
+	})
+
+	got := Diagnose(context.Background(), f, cfg, true)
+	if got.Bot.Status != StatusVerifyFailed || got.Bot.Available {
+		t.Fatalf("bot = %#v, want verify_failed and unavailable", got.Bot)
+	}
+	if got.Bot.Verified == nil || *got.Bot.Verified {
+		t.Fatalf("bot verified = %v, want false", got.Bot.Verified)
+	}
+	if !strings.Contains(got.Bot.Message, "401") || !strings.Contains(got.Bot.Message, "99991663") {
+		t.Fatalf("bot message = %q, want both HTTP code and envelope code", got.Bot.Message)
+	}
+}
+
+func TestDiagnose_VerifyBotIdentity_BusinessErrorCode(t *testing.T) {
+	cfg := &core.CliConfig{AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu}
+	f, _, _, reg := cmdutil.TestFactory(t, cfg)
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    "/open-apis/bot/v3/info",
+		Body: map[string]interface{}{
+			"code": 10013,
+			"msg":  "scope not granted",
+		},
+	})
+
+	got := Diagnose(context.Background(), f, cfg, true)
+	if got.Bot.Status != StatusVerifyFailed || got.Bot.Available {
+		t.Fatalf("bot = %#v, want verify_failed and unavailable", got.Bot)
+	}
+	if !strings.Contains(got.Bot.Message, "10013") || !strings.Contains(got.Bot.Message, "scope not granted") {
+		t.Fatalf("bot message = %q, want envelope code/msg", got.Bot.Message)
+	}
+}
+
+func TestDiagnose_VerifyUserIdentity_ServerRejects(t *testing.T) {
+	keyring.MockInit()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
+
+	cfg := &core.CliConfig{
+		AppID:      "test-app-reject",
+		AppSecret:  "secret",
+		Brand:      core.BrandFeishu,
+		UserOpenId: "ou_user",
+		UserName:   "tester",
+	}
+	now := time.Now()
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:            cfg.AppID,
+		UserOpenId:       cfg.UserOpenId,
+		AccessToken:      "user-access-token",
+		RefreshToken:     "refresh-token",
+		ExpiresAt:        now.Add(time.Hour).UnixMilli(),
+		RefreshExpiresAt: now.Add(24 * time.Hour).UnixMilli(),
+		GrantedAt:        now.Add(-time.Hour).UnixMilli(),
+		Scope:            "offline_access",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, _, reg := cmdutil.TestFactory(t, cfg)
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    "/open-apis/bot/v3/info",
+		Body: map[string]interface{}{
+			"code": 0,
+			"bot":  map[string]interface{}{"open_id": "ou_bot", "app_name": "bot"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    larkauth.PathUserInfoV1,
+		Body: map[string]interface{}{
+			"code": 99991661,
+			"msg":  "access token invalid",
+		},
+	})
+
+	got := Diagnose(context.Background(), f, cfg, true)
+	if got.User.Status != StatusVerifyFailed || got.User.Available {
+		t.Fatalf("user = %#v, want verify_failed and unavailable", got.User)
+	}
+	if got.User.Verified == nil || *got.User.Verified {
+		t.Fatalf("user verified = %v, want false", got.User.Verified)
+	}
+	if !strings.Contains(got.User.Message, "server rejected token") {
+		t.Fatalf("user message = %q, want 'server rejected token'", got.User.Message)
+	}
+}
+
+func TestDiagnose_UserIdentityExpired(t *testing.T) {
+	keyring.MockInit()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
+
+	cfg := &core.CliConfig{
+		AppID:      "test-app-expired",
+		AppSecret:  "secret",
+		Brand:      core.BrandFeishu,
+		UserOpenId: "ou_expired",
+		UserName:   "tester",
+	}
+	now := time.Now()
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:            cfg.AppID,
+		UserOpenId:       cfg.UserOpenId,
+		AccessToken:      "user-access-token",
+		RefreshToken:     "refresh-token",
+		ExpiresAt:        now.Add(-time.Hour).UnixMilli(),
+		RefreshExpiresAt: now.Add(-time.Minute).UnixMilli(),
+		GrantedAt:        now.Add(-24 * time.Hour).UnixMilli(),
+		Scope:            "offline_access",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, cfg)
+	got := Diagnose(context.Background(), f, cfg, false)
+	if got.User.Status != StatusMissing || got.User.Available {
+		t.Fatalf("user = %#v, want missing and unavailable", got.User)
+	}
+	if got.User.Hint == "" {
+		t.Fatalf("user hint is empty, want re-login hint")
+	}
+}
+
+func TestDiagnose_BotIdentityStrictUserOnly(t *testing.T) {
+	// SupportedIdentities = SupportsUser (1) only — bot path should be
+	// reported as not_configured even though an app secret is present.
+	cfg := &core.CliConfig{
+		AppID:               "test-app",
+		AppSecret:           "secret",
+		Brand:               core.BrandFeishu,
+		SupportedIdentities: 1,
+	}
+	f, _, _, _ := cmdutil.TestFactory(t, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, false)
+	if got.Bot.Status != StatusNotConfigured || got.Bot.Available {
+		t.Fatalf("bot = %#v, want not_configured and unavailable", got.Bot)
+	}
+}
+
+func TestDiagnose_UserIdentityMissingAppConfig(t *testing.T) {
+	cfg := &core.CliConfig{Brand: core.BrandFeishu}
+	f, _, _, _ := cmdutil.TestFactory(t, cfg)
+
+	got := Diagnose(context.Background(), f, cfg, false)
+	if got.User.Status != StatusNotConfigured || got.User.Available {
+		t.Fatalf("user = %#v, want not_configured and unavailable", got.User)
+	}
+}
+
+func TestStatusMessage(t *testing.T) {
+	cases := map[string]string{
+		StatusReady:         StatusReady,
+		StatusNotConfigured: "not configured",
+		StatusVerifyFailed:  "verify failed",
+		StatusNeedsRefresh:  "needs refresh",
+		StatusMissing:       "missing",
+		"unknown":           "unknown",
+	}
+	for in, want := range cases {
+		if got := StatusMessage(in); got != want {
+			t.Errorf("StatusMessage(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestDiagnose_UserIdentityNeedsRefresh(t *testing.T) {
+	keyring.MockInit()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
+
+	cfg := &core.CliConfig{
+		AppID:      "test-app-needs-refresh",
+		AppSecret:  "secret",
+		Brand:      core.BrandFeishu,
+		UserOpenId: "ou_refresh",
+		UserName:   "tester",
+	}
+	now := time.Now()
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:            cfg.AppID,
+		UserOpenId:       cfg.UserOpenId,
+		AccessToken:      "user-access-token",
+		RefreshToken:     "refresh-token",
+		ExpiresAt:        now.Add(time.Minute).UnixMilli(),
+		RefreshExpiresAt: now.Add(24 * time.Hour).UnixMilli(),
+		GrantedAt:        now.Add(-time.Hour).UnixMilli(),
+		Scope:            "offline_access",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, cfg)
+	got := Diagnose(context.Background(), f, cfg, false)
+	if got.User.Status != StatusNeedsRefresh || !got.User.Available {
+		t.Fatalf("user = %#v, want needs_refresh and available", got.User)
+	}
+	if got.User.TokenStatus != "needs_refresh" {
+		t.Fatalf("token status = %q, want needs_refresh", got.User.TokenStatus)
+	}
+}

package.json

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

shortcuts/base/base_dryrun_ops_test.go

@@ -149,29 +149,26 @@ func TestDryRunRecordOps(t *testing.T) {
 	assertDryRunContains(t, dryRunRecordGet(ctx, getJSONRT), "POST /open-apis/base/v3/bases/app_x/tables/tbl_1/records/batch_get", `"record_id_list":["rec_3"]`, `"select_fields":["Status"]`)
 	assertDryRunContains(t, dryRunRecordDelete(ctx, getJSONRT), "POST /open-apis/base/v3/bases/app_x/tables/tbl_1/records/batch_delete", `"record_id_list":["rec_3"]`)
 
-	uploadAttachmentRT := newBaseTestRuntime(
+	uploadAttachmentRT := newBaseTestRuntimeWithArrays(
 		map[string]string{
 			"base-token": "app_x",
 			"table-id":   "tbl_1",
 			"record-id":  "rec_1",
 			"field-id":   "fld_att",
-			"file":       "/tmp/report.pdf",
-			"name":       "report-final.pdf",
 		},
+		map[string][]string{"file": {"/tmp/report.pdf"}},
 		nil,
 		nil,
 	)
 	assertDryRunContains(t,
 		BaseRecordUploadAttachment.DryRun(ctx, uploadAttachmentRT),
 		"GET /open-apis/base/v3/bases/app_x/tables/tbl_1/fields/fld_att",
-		"GET /open-apis/base/v3/bases/app_x/tables/tbl_1/records/rec_1",
 		"POST /open-apis/drive/v1/medias/upload_all",
 		"bitable_file",
-		"PATCH /open-apis/base/v3/bases/app_x/tables/tbl_1/records/rec_1",
-		"report-final.pdf",
-		`"mime_type":"\u003cdetected_mime_type\u003e"`,
-		`"size":"\u003cfile_size\u003e"`,
-		"deprecated_set_attachment",
+		"POST /open-apis/base/v3/bases/app_x/tables/tbl_1/append_attachments",
+		"report.pdf",
+		`"image_width":"\u003cimage_width_if_image\u003e"`,
+		`"image_height":"\u003cimage_height_if_image\u003e"`,
 	)
 }
 

shortcuts/base/base_execute_test.go

@@ -7,6 +7,11 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
+	"image"
+	"image/color"
+	"image/png"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
@@ -15,6 +20,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
@@ -1589,12 +1595,14 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 	t.Run("upload attachment", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 
-		tmpFile, err := os.CreateTemp(t.TempDir(), "base-attachment-*.txt")
+		tmpFile, err := os.CreateTemp(t.TempDir(), "base-attachment-*.png")
 		if err != nil {
 			t.Fatalf("CreateTemp() err=%v", err)
 		}
-		if _, err := tmpFile.WriteString("hello attachment"); err != nil {
-			t.Fatalf("WriteString() err=%v", err)
+		img := image.NewRGBA(image.Rect(0, 0, 3, 2))
+		img.Set(0, 0, color.RGBA{R: 255, A: 255})
+		if err := png.Encode(tmpFile, img); err != nil {
+			t.Fatalf("png.Encode() err=%v", err)
 		}
 		if err := tmpFile.Close(); err != nil {
 			t.Fatalf("Close() err=%v", err)
@@ -1609,28 +1617,6 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 				"data": map[string]interface{}{"id": "fld_att", "name": "附件", "type": "attachment"},
 			},
 		})
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/rec_x",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{
-					"record_id": "rec_x",
-					"fields": map[string]interface{}{
-						"附件": []interface{}{
-							map[string]interface{}{
-								"file_token":                "existing_tok",
-								"name":                      "existing.pdf",
-								"size":                      2048,
-								"image_width":               640,
-								"image_height":              480,
-								"deprecated_set_attachment": false,
-							},
-						},
-					},
-				},
-			},
-		})
 		uploadStub := &httpmock.Stub{
 			Method: "POST",
 			URL:    "/open-apis/drive/v1/medias/upload_all",
@@ -1640,34 +1626,27 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			},
 		}
 		reg.Register(uploadStub)
-		updateStub := &httpmock.Stub{
-			Method: "PATCH",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/rec_x",
+		appendStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/append_attachments",
 			Body: map[string]interface{}{
 				"code": 0,
 				"data": map[string]interface{}{
-					"record_id": "rec_x",
-					"fields": map[string]interface{}{
-						"附件": []interface{}{
-							map[string]interface{}{
-								"file_token":                "existing_tok",
-								"name":                      "existing.pdf",
-								"size":                      2048,
-								"image_width":               640,
-								"image_height":              480,
-								"deprecated_set_attachment": true,
-							},
-							map[string]interface{}{
-								"file_token":                "file_tok_1",
-								"name":                      "report.txt",
-								"deprecated_set_attachment": true,
+					"attachments": map[string]interface{}{
+						"rec_x": map[string]interface{}{
+							"fld_att": []interface{}{
+								map[string]interface{}{
+									"file_token": "file_tok_1",
+									"name":       "base-attachment.png",
+									"size":       73,
+								},
 							},
 						},
 					},
 				},
 			},
 		}
-		reg.Register(updateStub)
+		reg.Register(appendStub)
 
 		if err := runShortcut(t, BaseRecordUploadAttachment, []string{
 			"+record-upload-attachment",
@@ -1676,11 +1655,10 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			"--record-id", "rec_x",
 			"--field-id", "fld_att",
 			"--file", "./" + filepath.Base(tmpFile.Name()),
-			"--name", "report.txt",
 		}, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
 		}
-		if got := stdout.String(); !strings.Contains(got, `"updated": true`) || !strings.Contains(got, `"file_tok_1"`) || !strings.Contains(got, `"report.txt"`) {
+		if got := stdout.String(); !strings.Contains(got, `"file_tok_1"`) || strings.Contains(got, `"updated"`) || strings.Contains(got, `"uploaded"`) {
 			t.Fatalf("stdout=%s", got)
 		}
 
@@ -1689,19 +1667,13 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			t.Fatalf("upload body=%s", uploadBody)
 		}
 
-		updateBody := string(updateStub.CapturedBody)
-		if !strings.Contains(updateBody, `"附件"`) ||
-			!strings.Contains(updateBody, `"file_token":"existing_tok"`) ||
-			!strings.Contains(updateBody, `"name":"existing.pdf"`) ||
-			!strings.Contains(updateBody, `"size":2048`) ||
-			!strings.Contains(updateBody, `"image_width":640`) ||
-			!strings.Contains(updateBody, `"image_height":480`) ||
-			!strings.Contains(updateBody, `"deprecated_set_attachment":true`) ||
-			!strings.Contains(updateBody, `"file_token":"file_tok_1"`) ||
-			!strings.Contains(updateBody, `"name":"report.txt"`) ||
-			!strings.Contains(updateBody, `"size":16`) ||
-			!strings.Contains(updateBody, `"mime_type":"text/plain"`) {
-			t.Fatalf("update body=%s", updateBody)
+		appendBody := string(appendStub.CapturedBody)
+		if !strings.Contains(appendBody, `"rec_x"`) ||
+			!strings.Contains(appendBody, `"fld_att"`) ||
+			!strings.Contains(appendBody, `"file_token":"file_tok_1"`) ||
+			!strings.Contains(appendBody, `"image_width":3`) ||
+			!strings.Contains(appendBody, `"image_height":2`) {
+			t.Fatalf("append body=%s", appendBody)
 		}
 	})
 
@@ -1728,17 +1700,6 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 				"data": map[string]interface{}{"id": "fld_att", "name": "附件", "type": "attachment"},
 			},
 		})
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/rec_x",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{
-					"record_id": "rec_x",
-					"fields":    map[string]interface{}{},
-				},
-			},
-		})
 
 		prepareStub := &httpmock.Stub{
 			Method: "POST",
@@ -1778,26 +1739,23 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 		reg.Register(finishStub)
 
-		updateStub := &httpmock.Stub{
-			Method: "PATCH",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/rec_x",
+		appendStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/append_attachments",
 			Body: map[string]interface{}{
 				"code": 0,
 				"data": map[string]interface{}{
-					"record_id": "rec_x",
-					"fields": map[string]interface{}{
-						"附件": []interface{}{
-							map[string]interface{}{
-								"file_token":                "file_tok_big",
-								"name":                      "large-report.bin",
-								"deprecated_set_attachment": true,
+					"attachments": map[string]interface{}{
+						"rec_x": map[string]interface{}{
+							"fld_att": []interface{}{
+								map[string]interface{}{"file_token": "file_tok_big"},
 							},
 						},
 					},
 				},
 			},
 		}
-		reg.Register(updateStub)
+		reg.Register(appendStub)
 
 		if err := runShortcut(t, BaseRecordUploadAttachment, []string{
 			"+record-upload-attachment",
@@ -1806,17 +1764,16 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			"--record-id", "rec_x",
 			"--field-id", "fld_att",
 			"--file", "./" + filepath.Base(tmpFile.Name()),
-			"--name", "large-report.bin",
 		}, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
 		}
 
-		if got := stdout.String(); !strings.Contains(got, `"updated": true`) || !strings.Contains(got, `"file_tok_big"`) || !strings.Contains(got, `"large-report.bin"`) {
+		if got := stdout.String(); !strings.Contains(got, `"file_tok_big"`) || strings.Contains(got, `"updated"`) || strings.Contains(got, `"uploaded"`) {
 			t.Fatalf("stdout=%s", got)
 		}
 
 		prepareBody := string(prepareStub.CapturedBody)
-		if !strings.Contains(prepareBody, `"file_name":"large-report.bin"`) ||
+		if !strings.Contains(prepareBody, `"file_name":"`+filepath.Base(tmpFile.Name())+`"`) ||
 			!strings.Contains(prepareBody, `"parent_type":"bitable_file"`) ||
 			!strings.Contains(prepareBody, `"parent_node":"app_x"`) ||
 			!strings.Contains(prepareBody, `"size":20971521`) {
@@ -1847,14 +1804,11 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			t.Fatalf("finish body=%s", finishBody)
 		}
 
-		updateBody := string(updateStub.CapturedBody)
-		if !strings.Contains(updateBody, `"附件"`) ||
-			!strings.Contains(updateBody, `"file_token":"file_tok_big"`) ||
-			!strings.Contains(updateBody, `"name":"large-report.bin"`) ||
-			!strings.Contains(updateBody, `"size":20971521`) ||
-			!strings.Contains(updateBody, `"mime_type":"application/octet-stream"`) ||
-			!strings.Contains(updateBody, `"deprecated_set_attachment":true`) {
-			t.Fatalf("update body=%s", updateBody)
+		appendBody := string(appendStub.CapturedBody)
+		if !strings.Contains(appendBody, `"rec_x"`) ||
+			!strings.Contains(appendBody, `"fld_att"`) ||
+			!strings.Contains(appendBody, `"file_token":"file_tok_big"`) {
+			t.Fatalf("append body=%s", appendBody)
 		}
 	})
 
@@ -1928,6 +1882,434 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			t.Fatalf("err=%v", err)
 		}
 	})
+
+	t.Run("upload attachment rejects deprecated name flag", func(t *testing.T) {
+		factory, stdout, _ := newExecuteFactory(t)
+
+		tmpFile, err := os.CreateTemp(t.TempDir(), "base-name-*.txt")
+		if err != nil {
+			t.Fatalf("CreateTemp() err=%v", err)
+		}
+		if err := tmpFile.Close(); err != nil {
+			t.Fatalf("Close() err=%v", err)
+		}
+		withBaseWorkingDir(t, filepath.Dir(tmpFile.Name()))
+
+		err = runShortcut(t, BaseRecordUploadAttachment, []string{
+			"+record-upload-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--field-id", "fld_att",
+			"--file", "./" + filepath.Base(tmpFile.Name()),
+			"--name", "renamed.txt",
+		}, factory, stdout)
+		if err == nil || !strings.Contains(err.Error(), "--name is no longer supported") {
+			t.Fatalf("err=%v", err)
+		}
+	})
+
+	t.Run("download attachment includes extra query parameter", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+
+		extra := `{"bitablePerm":{"tableId":"tbl_x","attachments":{"fld_att":{"rec_x":["box_a"]}}}}`
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/get_attachments",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"attachments": map[string]interface{}{
+						"rec_x": map[string]interface{}{
+							"fld_att": []interface{}{
+								map[string]interface{}{
+									"file_token": "box_a",
+									"name":       "pic.png",
+									"size":       7,
+									"extra_info": extra,
+								},
+							},
+						},
+					},
+				},
+			},
+		})
+		downloadStub := &httpmock.Stub{
+			Method:      "GET",
+			URL:         "/open-apis/drive/v1/medias/box_a/download?" + url.Values{"extra": []string{extra}}.Encode(),
+			RawBody:     []byte("payload"),
+			ContentType: "image/png",
+		}
+		reg.Register(downloadStub)
+
+		tmpDir := t.TempDir()
+		withBaseWorkingDir(t, tmpDir)
+		if err := os.Mkdir("downloads", 0700); err != nil {
+			t.Fatalf("Mkdir() err=%v", err)
+		}
+
+		if err := runShortcut(t, BaseRecordDownloadAttachment, []string{
+			"+record-download-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--file-token", "box_a",
+			"--output", "downloads",
+		}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if _, err := os.Stat(filepath.Join(tmpDir, "downloads", "pic.png")); err != nil {
+			t.Fatalf("expected downloaded file: %v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		gotItems, _ := data["downloaded"].([]interface{})
+		if len(gotItems) != 1 {
+			t.Fatalf("downloaded=%#v", data["downloaded"])
+		}
+		got, _ := gotItems[0].(map[string]interface{})
+		if got["file_token"] != "box_a" || got["saved_path"] == "" || got["extra_info_used"] != nil {
+			t.Fatalf("download output=%#v", got)
+		}
+	})
+
+	t.Run("download all row attachments when file token omitted", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/get_attachments",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"attachments": map[string]interface{}{
+						"rec_x": map[string]interface{}{
+							"fld_att": []interface{}{
+								map[string]interface{}{"file_token": "box_a", "name": "a.txt", "size": 7},
+								map[string]interface{}{"file_token": "box_b", "name": "b.txt", "size": 8},
+							},
+						},
+					},
+				},
+			},
+		})
+		reg.Register(&httpmock.Stub{
+			Method:      "GET",
+			URL:         "/open-apis/drive/v1/medias/box_a/download",
+			RawBody:     []byte("payload-a"),
+			ContentType: "text/plain",
+		})
+		reg.Register(&httpmock.Stub{
+			Method:      "GET",
+			URL:         "/open-apis/drive/v1/medias/box_b/download",
+			RawBody:     []byte("payload-b"),
+			ContentType: "text/plain",
+		})
+
+		tmpDir := t.TempDir()
+		withBaseWorkingDir(t, tmpDir)
+		if err := os.Mkdir("downloads", 0700); err != nil {
+			t.Fatalf("Mkdir() err=%v", err)
+		}
+
+		if err := runShortcut(t, BaseRecordDownloadAttachment, []string{
+			"+record-download-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--output", "downloads",
+		}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if _, err := os.Stat(filepath.Join(tmpDir, "downloads", "a.txt")); err != nil {
+			t.Fatalf("expected downloaded file a.txt: %v", err)
+		}
+		if _, err := os.Stat(filepath.Join(tmpDir, "downloads", "b.txt")); err != nil {
+			t.Fatalf("expected downloaded file b.txt: %v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		gotItems, _ := data["downloaded"].([]interface{})
+		if len(gotItems) != 2 {
+			t.Fatalf("downloaded=%#v", data["downloaded"])
+		}
+	})
+
+	t.Run("download without file token requires output directory", func(t *testing.T) {
+		factory, stdout, _ := newExecuteFactory(t)
+		tmpDir := t.TempDir()
+		withBaseWorkingDir(t, tmpDir)
+
+		err := runShortcut(t, BaseRecordDownloadAttachment, []string{
+			"+record-download-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--output", "file.txt",
+		}, factory, stdout)
+		if err == nil || !strings.Contains(err.Error(), "--output must be an existing directory") {
+			t.Fatalf("err=%v", err)
+		}
+	})
+
+	t.Run("download all disambiguates duplicate attachment names with file token", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/get_attachments",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"attachments": map[string]interface{}{
+						"rec_x": map[string]interface{}{
+							"fld_att": []interface{}{
+								map[string]interface{}{"file_token": "box_a", "name": "same.txt", "size": 7},
+								map[string]interface{}{"file_token": "box_a", "name": "same.txt", "size": 7},
+								map[string]interface{}{"file_token": "box_b", "name": "same.txt", "size": 8},
+							},
+						},
+					},
+				},
+			},
+		})
+		reg.Register(&httpmock.Stub{
+			Method:      "GET",
+			URL:         "/open-apis/drive/v1/medias/box_a/download",
+			RawBody:     []byte("payload-a"),
+			ContentType: "text/plain",
+		})
+		reg.Register(&httpmock.Stub{
+			Method:      "GET",
+			URL:         "/open-apis/drive/v1/medias/box_b/download",
+			RawBody:     []byte("payload-b"),
+			ContentType: "text/plain",
+		})
+
+		tmpDir := t.TempDir()
+		withBaseWorkingDir(t, tmpDir)
+		if err := os.Mkdir("downloads", 0700); err != nil {
+			t.Fatalf("Mkdir() err=%v", err)
+		}
+
+		if err := runShortcut(t, BaseRecordDownloadAttachment, []string{
+			"+record-download-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--output", "downloads",
+		}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if _, err := os.Stat(filepath.Join(tmpDir, "downloads", "same_box_a.txt")); err != nil {
+			t.Fatalf("expected downloaded file same_box_a.txt: %v", err)
+		}
+		if _, err := os.Stat(filepath.Join(tmpDir, "downloads", "same_box_b.txt")); err != nil {
+			t.Fatalf("expected downloaded file same_box_b.txt: %v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		gotItems, _ := data["downloaded"].([]interface{})
+		if len(gotItems) != 2 {
+			t.Fatalf("downloaded=%#v", data["downloaded"])
+		}
+	})
+
+	t.Run("download duplicate requested file token only once", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/get_attachments",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"attachments": map[string]interface{}{
+						"rec_x": map[string]interface{}{
+							"fld_att": []interface{}{
+								map[string]interface{}{"file_token": "box_a", "name": "a.txt", "size": 7},
+							},
+						},
+					},
+				},
+			},
+		})
+		reg.Register(&httpmock.Stub{
+			Method:      "GET",
+			URL:         "/open-apis/drive/v1/medias/box_a/download",
+			RawBody:     []byte("payload-a"),
+			ContentType: "text/plain",
+		})
+
+		tmpDir := t.TempDir()
+		withBaseWorkingDir(t, tmpDir)
+		if err := runShortcut(t, BaseRecordDownloadAttachment, []string{
+			"+record-download-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--file-token", "box_a",
+			"--file-token", "box_a",
+			"--output", "a.txt",
+		}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		gotItems, _ := data["downloaded"].([]interface{})
+		if len(gotItems) != 1 {
+			t.Fatalf("downloaded=%#v", data["downloaded"])
+		}
+	})
+
+	t.Run("download all preflights local target conflicts before writing", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/get_attachments",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"attachments": map[string]interface{}{
+						"rec_x": map[string]interface{}{
+							"fld_att": []interface{}{
+								map[string]interface{}{"file_token": "box_a", "name": "a.txt", "size": 7},
+								map[string]interface{}{"file_token": "box_b", "name": "b.txt", "size": 8},
+							},
+						},
+					},
+				},
+			},
+		})
+
+		tmpDir := t.TempDir()
+		withBaseWorkingDir(t, tmpDir)
+		if err := os.Mkdir("downloads", 0700); err != nil {
+			t.Fatalf("Mkdir() err=%v", err)
+		}
+		if err := os.WriteFile(filepath.Join("downloads", "b.txt"), []byte("existing"), 0600); err != nil {
+			t.Fatalf("WriteFile() err=%v", err)
+		}
+
+		err := runShortcut(t, BaseRecordDownloadAttachment, []string{
+			"+record-download-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--output", "downloads",
+		}, factory, stdout)
+		if err == nil || !strings.Contains(err.Error(), "output file already exists: downloads/b.txt") {
+			t.Fatalf("err=%v", err)
+		}
+		if _, err := os.Stat(filepath.Join(tmpDir, "downloads", "a.txt")); err == nil {
+			t.Fatalf("a.txt should not be written after preflight conflict")
+		}
+	})
+
+	t.Run("download reports progress when later attachment fails", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/get_attachments",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"attachments": map[string]interface{}{
+						"rec_x": map[string]interface{}{
+							"fld_att": []interface{}{
+								map[string]interface{}{"file_token": "box_a", "name": "a.txt", "size": 7},
+								map[string]interface{}{"file_token": "box_b", "name": "b.txt", "size": 8},
+							},
+						},
+					},
+				},
+			},
+		})
+		reg.Register(&httpmock.Stub{
+			Method:      "GET",
+			URL:         "/open-apis/drive/v1/medias/box_a/download",
+			RawBody:     []byte("payload-a"),
+			ContentType: "text/plain",
+		})
+		reg.Register(&httpmock.Stub{
+			Method:  "GET",
+			URL:     "/open-apis/drive/v1/medias/box_b/download",
+			Status:  500,
+			RawBody: []byte("server error"),
+		})
+
+		tmpDir := t.TempDir()
+		withBaseWorkingDir(t, tmpDir)
+		if err := os.Mkdir("downloads", 0700); err != nil {
+			t.Fatalf("Mkdir() err=%v", err)
+		}
+
+		err := runShortcut(t, BaseRecordDownloadAttachment, []string{
+			"+record-download-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--output", "downloads",
+		}, factory, stdout)
+		if err == nil || !strings.Contains(err.Error(), "download failed after 1 attachment(s) succeeded and 1 failed") {
+			t.Fatalf("err=%v", err)
+		}
+		var exitErr *output.ExitError
+		if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+			t.Fatalf("expected structured error, got %T %v", err, err)
+		}
+		detail, _ := exitErr.Detail.Detail.(map[string]interface{})
+		downloaded, _ := detail["downloaded"].([]map[string]interface{})
+		failed, _ := detail["failed"].([]map[string]interface{})
+		if len(downloaded) != 1 || downloaded[0]["file_token"] != "box_a" || len(failed) != 1 || failed[0]["file_token"] != "box_b" {
+			t.Fatalf("detail=%#v", exitErr.Detail.Detail)
+		}
+		if _, err := os.Stat(filepath.Join(tmpDir, "downloads", "a.txt")); err != nil {
+			t.Fatalf("expected first file to remain: %v", err)
+		}
+	})
+
+	t.Run("remove attachment", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields/fld_att",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{"id": "fld_att", "name": "附件", "type": "attachment"},
+			},
+		})
+		removeStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/remove_attachments",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"attachments": map[string]interface{}{
+						"rec_x": map[string]interface{}{"fld_att": []interface{}{}},
+					},
+				},
+			},
+		}
+		reg.Register(removeStub)
+
+		if err := runShortcut(t, BaseRecordRemoveAttachment, []string{
+			"+record-remove-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--field-id", "fld_att",
+			"--file-token", "box_a",
+			"--file-token", "box_b",
+			"--yes",
+		}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if got := stdout.String(); strings.Contains(got, `"removed"`) || strings.Contains(got, `"updated"`) {
+			t.Fatalf("stdout=%s", got)
+		}
+		body := string(removeStub.CapturedBody)
+		if !strings.Contains(body, `"rec_x"`) ||
+			!strings.Contains(body, `"fld_att"`) ||
+			!strings.Contains(body, `"file_token":"box_a"`) ||
+			!strings.Contains(body, `"file_token":"box_b"`) {
+			t.Fatalf("remove body=%s", body)
+		}
+	})
 }
 
 func TestBaseViewExecuteReadCreateDeleteAndFilter(t *testing.T) {

shortcuts/base/base_shortcuts_test.go

@@ -132,7 +132,7 @@ func TestShortcutsCatalog(t *testing.T) {
 		"+table-list", "+table-get", "+table-create", "+table-update", "+table-delete",
 		"+field-list", "+field-get", "+field-create", "+field-update", "+field-delete", "+field-search-options",
 		"+view-list", "+view-get", "+view-create", "+view-delete", "+view-get-filter", "+view-set-filter", "+view-get-visible-fields", "+view-set-visible-fields", "+view-get-group", "+view-set-group", "+view-get-sort", "+view-set-sort", "+view-get-timebar", "+view-set-timebar", "+view-get-card", "+view-set-card", "+view-rename",
-		"+record-list", "+record-search", "+record-get", "+record-upsert", "+record-batch-create", "+record-batch-update", "+record-share-link-create", "+record-upload-attachment", "+record-delete",
+		"+record-list", "+record-search", "+record-get", "+record-upsert", "+record-batch-create", "+record-batch-update", "+record-share-link-create", "+record-upload-attachment", "+record-download-attachment", "+record-remove-attachment", "+record-delete",
 		"+record-history-list",
 		"+base-get", "+base-copy", "+base-create",
 		"+role-create", "+role-delete", "+role-update", "+role-list", "+role-get", "+advperm-enable", "+advperm-disable",
@@ -175,14 +175,15 @@ func TestBaseFieldUpdateRisk(t *testing.T) {
 
 func TestBaseDeleteShortcutsRisk(t *testing.T) {
 	cases := map[string]string{
-		BaseFieldDelete.Command:          BaseFieldDelete.Risk,
-		BaseViewDelete.Command:           BaseViewDelete.Risk,
-		BaseRecordDelete.Command:         BaseRecordDelete.Risk,
-		BaseFormDelete.Command:           BaseFormDelete.Risk,
-		BaseFormQuestionsDelete.Command:  BaseFormQuestionsDelete.Risk,
-		BaseDashboardDelete.Command:      BaseDashboardDelete.Risk,
-		BaseDashboardBlockDelete.Command: BaseDashboardBlockDelete.Risk,
-		BaseRoleDelete.Command:           BaseRoleDelete.Risk,
+		BaseFieldDelete.Command:            BaseFieldDelete.Risk,
+		BaseViewDelete.Command:             BaseViewDelete.Risk,
+		BaseRecordDelete.Command:           BaseRecordDelete.Risk,
+		BaseRecordRemoveAttachment.Command: BaseRecordRemoveAttachment.Risk,
+		BaseFormDelete.Command:             BaseFormDelete.Risk,
+		BaseFormQuestionsDelete.Command:    BaseFormQuestionsDelete.Risk,
+		BaseDashboardDelete.Command:        BaseDashboardDelete.Risk,
+		BaseDashboardBlockDelete.Command:   BaseDashboardBlockDelete.Risk,
+		BaseRoleDelete.Command:             BaseRoleDelete.Risk,
 	}
 
 	for command, risk := range cases {
@@ -338,6 +339,79 @@ func TestBaseFieldUpdateHelpGuidesAgents(t *testing.T) {
 	}
 }
 
+func TestBaseAttachmentHelpGuidesAgents(t *testing.T) {
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		wantHelp []string
+		wantTips []string
+	}{
+		{
+			name:     "upload attachment",
+			shortcut: BaseRecordUploadAttachment,
+			wantHelp: []string{
+				"repeat to append multiple attachments in one cell",
+				"max 50 files, max 2GB each",
+			},
+			wantTips: []string{
+				"lark-cli base +record-upload-attachment",
+				"Repeat --file to append multiple attachments",
+				"Reuse returned file_token values for download/remove",
+			},
+		},
+		{
+			name:     "download attachment",
+			shortcut: BaseRecordDownloadAttachment,
+			wantHelp: []string{
+				"repeat to download selected files",
+				"omit to download all attachments in the record",
+				"with multiple or omitted file tokens this must be an existing directory",
+			},
+			wantTips: []string{
+				"lark-cli base +record-download-attachment",
+				"Omit --file-token to download every attachment in the record",
+				"Base attachments should be downloaded with this command",
+				"other download commands may fail",
+			},
+		},
+		{
+			name:     "remove attachment",
+			shortcut: BaseRecordRemoveAttachment,
+			wantHelp: []string{
+				"remove from the target cell",
+				"max 50 tokens",
+			},
+			wantTips: []string{
+				"lark-cli base +record-remove-attachment",
+				"Repeat --file-token",
+				"requires --yes",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			parent := &cobra.Command{Use: "base"}
+			tt.shortcut.Mount(parent, &cmdutil.Factory{})
+			cmd := parent.Commands()[0]
+
+			help := cmd.Flags().FlagUsages()
+			for _, want := range tt.wantHelp {
+				if !strings.Contains(help, want) {
+					t.Fatalf("flag help missing %q:\n%s", want, help)
+				}
+			}
+
+			tips := strings.Join(cmdutil.GetTips(cmd), "\n")
+			for _, want := range tt.wantTips {
+				if !strings.Contains(tips, want) {
+					t.Fatalf("tips missing %q:\n%s", want, tips)
+				}
+			}
+		})
+	}
+}
+
 func assertHelpOrder(t *testing.T, help string, before string, after string) {
 	t.Helper()
 	beforeIndex := strings.Index(help, before)

shortcuts/base/record_upload_attachment.go

@@ -8,27 +8,37 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"image"
+	_ "image/gif"
+	_ "image/jpeg"
+	_ "image/png"
 	"io"
 	"mime"
+	"net/http"
 	"path/filepath"
+	"sort"
 	"strings"
 	"unicode/utf8"
 
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
 
 const (
 	baseAttachmentUploadMaxFileSize int64 = 2 * 1024 * 1024 * 1024
 	baseAttachmentParentType              = "bitable_file"
+	baseAttachmentMaxBatchSize            = 50
+	baseAttachmentGetMaxRecords           = 10
 )
 
 var BaseRecordUploadAttachment = common.Shortcut{
 	Service:     "base",
 	Command:     "+record-upload-attachment",
-	Description: "Upload a local file to a Base attachment field and write it into the target record",
+	Description: "Upload one or more local files and append the returned file_token values to a Base attachment cell",
 	Risk:        "write",
 	Scopes:      []string{"base:record:update", "base:field:read", "docs:document.media:upload"},
 	AuthTypes:   authTypes(),
@@ -37,34 +47,99 @@ var BaseRecordUploadAttachment = common.Shortcut{
 		tableRefFlag(true),
 		recordRefFlag(true),
 		fieldRefFlag(true),
-		{Name: "file", Desc: "local file path (max 2GB; files > 20MB use multipart upload automatically)", Required: true},
-		{Name: "name", Desc: "attachment file name (default: local file name)"},
+		{Name: "file", Type: "string_array", Desc: "local file path; repeat to append multiple attachments in one cell; max 50 files, max 2GB each; files > 20MB use multipart upload automatically", Required: true},
+		{Name: "name", Desc: "deprecated; attachment names are derived from local file basenames", Hidden: true},
+	},
+	Tips: []string{
+		`Example: lark-cli base +record-upload-attachment --base-token <base_token> --table-id <table_id> --record-id <record_id> --field-id <attachment_field_id> --file ./report.pdf`,
+		`Repeat --file to append multiple attachments: --file ./report.pdf --file ./screenshot.png`,
+		`Reuse returned file_token values for download/remove`,
 	},
 	DryRun: dryRunRecordUploadAttachment,
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateRecordUploadAttachment(runtime)
+	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeRecordUploadAttachment(runtime)
 	},
 }
 
+var BaseRecordDownloadAttachment = common.Shortcut{
+	Service:     "base",
+	Command:     "+record-download-attachment",
+	Description: "Download Base record attachments by record-id, optionally filtering by file-token",
+	Risk:        "read",
+	Scopes:      []string{"base:record:read", "docs:document.media:download"},
+	AuthTypes:   authTypes(),
+	Flags: []common.Flag{
+		baseTokenFlag(true),
+		tableRefFlag(true),
+		recordRefFlag(true),
+		{Name: "file-token", Type: "string_array", Desc: "attachment file_token returned by Base; repeat to download selected files; omit to download all attachments in the record", Required: false},
+		{Name: "output", Desc: "local save path; with exactly one file token this may be a file path; with multiple or omitted file tokens this must be an existing directory", Required: true},
+		{Name: "overwrite", Type: "bool", Desc: "overwrite existing output file"},
+	},
+	Tips: []string{
+		`Example: lark-cli base +record-download-attachment --base-token <base_token> --table-id <table_id> --record-id <record_id> --file-token <file_token> --output ./downloads/`,
+		`Omit --file-token to download every attachment in the record.`,
+		`Base attachments should be downloaded with this command; other download commands may fail for Base attachment files.`,
+		`With one --file-token, --output may be a file path or directory; with multiple or omitted --file-token values, --output must be an existing directory.`,
+	},
+	DryRun: dryRunRecordDownloadAttachment,
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateRecordDownloadAttachment(runtime)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return executeRecordDownloadAttachment(ctx, runtime)
+	},
+}
+
+var BaseRecordRemoveAttachment = common.Shortcut{
+	Service:     "base",
+	Command:     "+record-remove-attachment",
+	Description: "Remove one or more file_token values from a Base record attachment cell",
+	Risk:        "high-risk-write",
+	Scopes:      []string{"base:record:update", "base:field:read"},
+	AuthTypes:   authTypes(),
+	Flags: []common.Flag{
+		baseTokenFlag(true),
+		tableRefFlag(true),
+		recordRefFlag(true),
+		fieldRefFlag(true),
+		{Name: "file-token", Type: "string_array", Desc: "attachment file_token to remove from the target cell; repeat to remove multiple attachments; max 50 tokens", Required: true},
+	},
+	Tips: []string{
+		`Example: lark-cli base +record-remove-attachment --base-token <base_token> --table-id <table_id> --record-id <record_id> --field-id <attachment_field_id> --file-token <file_token> --yes`,
+		`Repeat --file-token to remove multiple attachments from the same cell in one call.`,
+		`This is a high-risk write command and requires --yes.`,
+	},
+	DryRun: dryRunRecordRemoveAttachment,
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateRecordRemoveAttachment(runtime)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return executeRecordRemoveAttachment(runtime)
+	},
+}
+
 func dryRunRecordUploadAttachment(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	filePath := runtime.Str("file")
-	fileName := strings.TrimSpace(runtime.Str("name"))
-	if fileName == "" {
+	files := runtime.StrArray("file")
+	filePath := "<file>"
+	fileName := "<local_file_name>"
+	if len(files) > 0 {
+		filePath = files[0]
 		fileName = filepath.Base(filePath)
 	}
 	dry := common.NewDryRunAPI().
-		Desc("4-step orchestration: validate attachment field → read existing record attachments → upload file to Base → patch merged attachment array").
+		Desc("3-step orchestration: validate attachment field → upload local file(s) to Base → append uploaded file token(s) to the attachment cell").
 		GET("/open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id").
 		Desc("[1] Read target field and ensure it is an attachment field").
 		Set("base_token", runtime.Str("base-token")).
 		Set("table_id", baseTableID(runtime)).
-		Set("field_id", runtime.Str("field-id")).
-		GET("/open-apis/base/v3/bases/:base_token/tables/:table_id/records/:record_id").
-		Desc("[2] Read current record to preserve existing attachments in the target cell").
-		Set("record_id", runtime.Str("record-id"))
+		Set("field_id", runtime.Str("field-id"))
 	if baseAttachmentShouldUseMultipart(runtime.FileIO(), filePath) {
 		dry.POST("/open-apis/drive/v1/medias/upload_prepare").
-			Desc("[3a] Initialize multipart attachment upload to the current Base").
+			Desc("[2a] Initialize multipart attachment upload to the current Base").
 			Body(map[string]interface{}{
 				"file_name":   fileName,
 				"parent_type": baseAttachmentParentType,
@@ -72,7 +147,7 @@ func dryRunRecordUploadAttachment(_ context.Context, runtime *common.RuntimeCont
 				"size":        "<file_size>",
 			}).
 			POST("/open-apis/drive/v1/medias/upload_part").
-			Desc("[3b] Upload attachment parts (repeated)").
+			Desc("[2b] Upload attachment parts (repeated for each large file)").
 			Body(map[string]interface{}{
 				"upload_id": "<upload_id>",
 				"seq":       "<chunk_index>",
@@ -80,14 +155,14 @@ func dryRunRecordUploadAttachment(_ context.Context, runtime *common.RuntimeCont
 				"file":      "<chunk_binary>",
 			}).
 			POST("/open-apis/drive/v1/medias/upload_finish").
-			Desc("[3c] Finalize multipart attachment upload and get file token").
+			Desc("[2c] Finalize multipart attachment upload and get file token").
 			Body(map[string]interface{}{
 				"upload_id": "<upload_id>",
 				"block_num": "<block_num>",
 			})
 	} else {
 		dry.POST("/open-apis/drive/v1/medias/upload_all").
-			Desc("[3] Upload local file to the current Base as attachment media (multipart/form-data)").
+			Desc("[2] Upload local file(s) to the current Base as attachment media (multipart/form-data)").
 			Body(map[string]interface{}{
 				"file_name":   fileName,
 				"parent_type": baseAttachmentParentType,
@@ -97,46 +172,87 @@ func dryRunRecordUploadAttachment(_ context.Context, runtime *common.RuntimeCont
 			})
 	}
 	return dry.
-		PATCH("/open-apis/base/v3/bases/:base_token/tables/:table_id/records/:record_id").
-		Desc("[4] Update the target attachment cell with existing attachments plus the uploaded file token").
+		POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/append_attachments").
+		Desc("[3] Append uploaded file token(s) to the target attachment cell").
 		Body(map[string]interface{}{
-			"<attachment_field_name>": []interface{}{
-				map[string]interface{}{
-					"file_token":                "<existing_file_token>",
-					"name":                      "<existing_file_name>",
-					"deprecated_set_attachment": true,
-				},
-				map[string]interface{}{
-					"file_token":                "<uploaded_file_token>",
-					"name":                      fileName,
-					"mime_type":                 "<detected_mime_type>",
-					"size":                      "<file_size>",
-					"deprecated_set_attachment": true,
+			"attachments": map[string]interface{}{
+				runtime.Str("record-id"): map[string]interface{}{
+					runtime.Str("field-id"): []interface{}{
+						map[string]interface{}{
+							"file_token":   "<uploaded_file_token>",
+							"image_width":  "<image_width_if_image>",
+							"image_height": "<image_height_if_image>",
+						},
+					},
 				},
 			},
 		})
 }
 
-func executeRecordUploadAttachment(runtime *common.RuntimeContext) error {
-	filePath := runtime.Str("file")
-	fio := runtime.FileIO()
-	if fio == nil {
-		return output.ErrValidation("file operations require a FileIO provider")
-	}
-	fileInfo, err := fio.Stat(filePath)
-	if err != nil {
-		if errors.Is(err, fileio.ErrPathValidation) {
-			return output.ErrValidation("unsafe file path: %s", err)
-		}
-		return output.ErrValidation("file not accessible: %s: %v", filePath, err)
-	}
-	if fileInfo.Size() > baseAttachmentUploadMaxFileSize {
-		return output.ErrValidation("file %s exceeds 2GB limit", common.FormatSize(fileInfo.Size()))
-	}
+func dryRunRecordDownloadAttachment(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	return common.NewDryRunAPI().
+		Desc("2-step orchestration: read Base attachment metadata → download each requested attachment file").
+		POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/get_attachments").
+		Desc("[1] Read attachment metadata for the record").
+		Body(map[string]interface{}{"record_id_list": []string{runtime.Str("record-id")}}).
+		Set("base_token", runtime.Str("base-token")).
+		Set("table_id", baseTableID(runtime)).
+		GET("/open-apis/drive/v1/medias/:file_token/download").
+		Desc("[2] Download attachment media through the Base attachment flow").
+		Set("file_token", "<file_token>").
+		Set("output", runtime.Str("output")).
+		Params(map[string]interface{}{"extra": "<extra_info_if_present>"})
+}
 
-	fileName := strings.TrimSpace(runtime.Str("name"))
-	if fileName == "" {
-		fileName = filepath.Base(filePath)
+func dryRunRecordRemoveAttachment(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	body := buildSingleCellAttachmentsBody(runtime.Str("record-id"), runtime.Str("field-id"), fileTokenPatchItems(runtime.StrArray("file-token")))
+	return common.NewDryRunAPI().
+		POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/remove_attachments").
+		Desc("Remove attachment file token(s) from the target attachment cell").
+		Body(body).
+		Set("base_token", runtime.Str("base-token")).
+		Set("table_id", baseTableID(runtime))
+}
+
+func validateRecordUploadAttachment(runtime *common.RuntimeContext) error {
+	if runtime.Changed("name") {
+		return common.FlagErrorf("--name is no longer supported; uploaded attachment names are derived from local file basenames")
+	}
+	files, err := normalizeAttachmentFiles(runtime.StrArray("file"))
+	if err != nil {
+		return err
+	}
+	for _, path := range files {
+		if _, err := validateAttachmentInputFile(runtime, path); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func validateRecordDownloadAttachment(runtime *common.RuntimeContext) error {
+	tokens, err := normalizeOptionalDownloadAttachmentFileTokens(runtime.StrArray("file-token"))
+	if err != nil {
+		return err
+	}
+	if len(tokens) != 1 {
+		info, statErr := runtime.FileIO().Stat(runtime.Str("output"))
+		if statErr != nil || !info.IsDir() {
+			return common.FlagErrorf("--output must be an existing directory when downloading multiple attachments or when --file-token is omitted")
+		}
+	}
+	return nil
+}
+
+func validateRecordRemoveAttachment(runtime *common.RuntimeContext) error {
+	_, err := normalizeAttachmentFileTokens(runtime.StrArray("file-token"))
+	return err
+}
+
+func executeRecordUploadAttachment(runtime *common.RuntimeContext) error {
+	files, err := normalizeAttachmentFiles(runtime.StrArray("file"))
+	if err != nil {
+		return err
 	}
 
 	field, err := fetchBaseField(runtime, runtime.Str("base-token"), baseTableID(runtime), runtime.Str("field-id"))
@@ -146,44 +262,172 @@ func executeRecordUploadAttachment(runtime *common.RuntimeContext) error {
 	if normalized := normalizeFieldTypeName(fieldTypeName(field)); normalized != "attachment" {
 		return output.ErrValidation("field %q is type %q, expected attachment", fieldName(field), normalized)
 	}
+	resolvedFieldID := fieldID(field)
+	if resolvedFieldID == "" {
+		resolvedFieldID = runtime.Str("field-id")
+	}
 
-	record, err := fetchBaseRecord(runtime, runtime.Str("base-token"), baseTableID(runtime), runtime.Str("record-id"))
+	appendItems := make([]interface{}, 0, len(files))
+	for _, filePath := range files {
+		fileInfo, err := validateAttachmentInputFile(runtime, filePath)
+		if err != nil {
+			return err
+		}
+		fileName := filepath.Base(filePath)
+		fmt.Fprintf(runtime.IO().ErrOut, "Uploading attachment: %s -> record %s field %s\n", fileName, runtime.Str("record-id"), fieldName(field))
+		if fileInfo.Size() > common.MaxDriveMediaUploadSinglePartSize {
+			fmt.Fprintf(runtime.IO().ErrOut, "File exceeds 20MB, using multipart upload\n")
+		}
+		attachment, err := uploadAttachmentToBase(runtime, filePath, fileName, runtime.Str("base-token"), fileInfo.Size())
+		if err != nil {
+			return err
+		}
+		appendItems = append(appendItems, attachmentAppendItem(attachment))
+	}
+
+	body := buildSingleCellAttachmentsBody(runtime.Str("record-id"), resolvedFieldID, appendItems)
+	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", runtime.Str("base-token"), "tables", baseTableID(runtime), "append_attachments"), nil, body)
 	if err != nil {
 		return err
 	}
-
-	fmt.Fprintf(runtime.IO().ErrOut, "Uploading attachment: %s -> record %s field %s\n", fileName, runtime.Str("record-id"), fieldName(field))
-	if fileInfo.Size() > common.MaxDriveMediaUploadSinglePartSize {
-		fmt.Fprintf(runtime.IO().ErrOut, "File exceeds 20MB, using multipart upload\n")
-	}
-
-	attachment, err := uploadAttachmentToBase(runtime, filePath, fileName, runtime.Str("base-token"), fileInfo.Size())
-	if err != nil {
-		return err
-	}
-
-	attachments, err := mergeRecordAttachments(record, fieldName(field), attachment)
-	if err != nil {
-		return err
-	}
-
-	body := map[string]interface{}{
-		fieldName(field): attachments,
-	}
-	data, err := baseV3Call(runtime, "PATCH", baseV3Path("bases", runtime.Str("base-token"), "tables", baseTableID(runtime), "records", runtime.Str("record-id")), nil, body)
-	if err != nil {
-		return err
-	}
-	runtime.Out(map[string]interface{}{
-		"record":      data,
-		"attachment":  attachment,
-		"attachments": attachments,
-		"updated":     true,
-	}, nil)
+	runtime.Out(data, nil)
 	return nil
 }
 
+func executeRecordRemoveAttachment(runtime *common.RuntimeContext) error {
+	tokens, err := normalizeAttachmentFileTokens(runtime.StrArray("file-token"))
+	if err != nil {
+		return err
+	}
+	field, err := fetchBaseField(runtime, runtime.Str("base-token"), baseTableID(runtime), runtime.Str("field-id"))
+	if err != nil {
+		return err
+	}
+	if normalized := normalizeFieldTypeName(fieldTypeName(field)); normalized != "attachment" {
+		return output.ErrValidation("field %q is type %q, expected attachment", fieldName(field), normalized)
+	}
+	resolvedFieldID := fieldID(field)
+	if resolvedFieldID == "" {
+		resolvedFieldID = runtime.Str("field-id")
+	}
+	body := buildSingleCellAttachmentsBody(runtime.Str("record-id"), resolvedFieldID, fileTokenPatchItems(tokens))
+	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", runtime.Str("base-token"), "tables", baseTableID(runtime), "remove_attachments"), nil, body)
+	if err != nil {
+		return err
+	}
+	runtime.Out(data, nil)
+	return nil
+}
+
+func executeRecordDownloadAttachment(ctx context.Context, runtime *common.RuntimeContext) error {
+	tokens, err := normalizeOptionalDownloadAttachmentFileTokens(runtime.StrArray("file-token"))
+	if err != nil {
+		return err
+	}
+	attachments, err := fetchBaseAttachments(runtime, runtime.Str("base-token"), baseTableID(runtime), []string{runtime.Str("record-id")})
+	if err != nil {
+		return err
+	}
+	items, err := selectAttachmentDownloadItems(attachments, runtime.Str("record-id"), tokens)
+	if err != nil {
+		return err
+	}
+	targets, err := planAttachmentDownloadTargets(runtime, items, runtime.Str("output"), len(tokens) != 1 || len(items) > 1, runtime.Bool("overwrite"))
+	if err != nil {
+		return err
+	}
+	downloaded := make([]map[string]interface{}, 0, len(targets))
+	for _, target := range targets {
+		saved, err := downloadBaseAttachment(ctx, runtime, target.Item, target.TargetPath, runtime.Bool("overwrite"))
+		if err != nil {
+			failed := attachmentDownloadFailure(target, err)
+			return attachmentDownloadProgressError(err, downloaded, []map[string]interface{}{failed})
+		}
+		downloaded = append(downloaded, saved)
+	}
+	runtime.Out(map[string]interface{}{"downloaded": downloaded}, nil)
+	return nil
+}
+
+func validateAttachmentInputFile(runtime *common.RuntimeContext, filePath string) (fileio.FileInfo, error) {
+	fio := runtime.FileIO()
+	if fio == nil {
+		return nil, output.ErrValidation("file operations require a FileIO provider")
+	}
+	fileInfo, err := fio.Stat(filePath)
+	if err != nil {
+		if errors.Is(err, fileio.ErrPathValidation) {
+			return nil, output.ErrValidation("unsafe file path: %s", err)
+		}
+		return nil, output.ErrValidation("file not accessible: %s: %v", filePath, err)
+	}
+	if fileInfo.IsDir() {
+		return nil, output.ErrValidation("file path is a directory: %s", filePath)
+	}
+	if fileInfo.Size() > baseAttachmentUploadMaxFileSize {
+		return nil, output.ErrValidation("file %s exceeds 2GB limit", common.FormatSize(fileInfo.Size()))
+	}
+	return fileInfo, nil
+}
+
+func normalizeAttachmentFiles(files []string) ([]string, error) {
+	return normalizeStringList(files, stringListNormalizeOptions{
+		typeError:     "attachment files must be a string array",
+		emptyError:    "provide at least one --file",
+		itemName:      "attachment file",
+		duplicateName: "attachment file",
+		limitName:     "attachment file count",
+		max:           baseAttachmentMaxBatchSize,
+	})
+}
+
+func normalizeAttachmentFileTokens(tokens []string) ([]string, error) {
+	return normalizeStringList(tokens, stringListNormalizeOptions{
+		typeError:     "attachment file tokens must be a string array",
+		emptyError:    "provide at least one --file-token",
+		itemName:      "attachment file token",
+		duplicateName: "attachment file token",
+		limitName:     "attachment file token count",
+		max:           baseAttachmentMaxBatchSize,
+	})
+}
+
+func normalizeOptionalDownloadAttachmentFileTokens(tokens []string) ([]string, error) {
+	if len(tokens) == 0 {
+		return nil, nil
+	}
+	normalized := make([]string, 0, len(tokens))
+	for index, token := range tokens {
+		token = strings.TrimSpace(token)
+		if token == "" {
+			return nil, common.FlagErrorf("attachment file token %d must not be empty", index+1)
+		}
+		normalized = append(normalized, token)
+	}
+	normalized = dedupeStringsPreserveOrder(normalized)
+	if len(normalized) > baseAttachmentMaxBatchSize {
+		return nil, common.FlagErrorf("attachment file token count exceeds maximum limit of %d (got %d)", baseAttachmentMaxBatchSize, len(normalized))
+	}
+	return normalized, nil
+}
+
+func dedupeStringsPreserveOrder(values []string) []string {
+	seen := make(map[string]struct{}, len(values))
+	result := make([]string, 0, len(values))
+	for _, value := range values {
+		if _, exists := seen[value]; exists {
+			continue
+		}
+		seen[value] = struct{}{}
+		result = append(result, value)
+	}
+	return result
+}
+
 func baseAttachmentShouldUseMultipart(fio fileio.FileIO, filePath string) bool {
+	if fio == nil {
+		return false
+	}
 	info, err := fio.Stat(filePath)
 	if err != nil {
 		return false
@@ -195,57 +439,24 @@ func fetchBaseField(runtime *common.RuntimeContext, baseToken, tableIDValue, fie
 	return baseV3Call(runtime, "GET", baseV3Path("bases", baseToken, "tables", tableIDValue, "fields", fieldRef), nil, nil)
 }
 
-func fetchBaseRecord(runtime *common.RuntimeContext, baseToken, tableIDValue, recordID string) (map[string]interface{}, error) {
-	return baseV3Call(runtime, "GET", baseV3Path("bases", baseToken, "tables", tableIDValue, "records", recordID), nil, nil)
-}
-
-func mergeRecordAttachments(record map[string]interface{}, fieldName string, uploaded map[string]interface{}) ([]interface{}, error) {
-	fields, _ := record["fields"].(map[string]interface{})
-	if fields == nil {
-		return []interface{}{uploaded}, nil
+func fetchBaseAttachments(runtime *common.RuntimeContext, baseToken, tableIDValue string, recordIDs []string) (map[string]interface{}, error) {
+	if len(recordIDs) == 0 {
+		return nil, output.ErrValidation("provide at least one record id")
 	}
-	current, exists := fields[fieldName]
-	if !exists || util.IsNil(current) {
-		return []interface{}{uploaded}, nil
+	if len(recordIDs) > baseAttachmentGetMaxRecords {
+		return nil, output.ErrValidation("get attachments record selection exceeds maximum limit of %d (got %d)", baseAttachmentGetMaxRecords, len(recordIDs))
 	}
-	items, ok := current.([]interface{})
-	if !ok {
-		return nil, output.ErrValidation("record field %q has unexpected attachment payload type %T", fieldName, current)
+	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", baseToken, "tables", tableIDValue, "get_attachments"), nil, map[string]interface{}{
+		"record_id_list": recordIDs,
+	})
+	if err != nil {
+		return nil, err
 	}
-	merged := make([]interface{}, 0, len(items)+1)
-	for _, item := range items {
-		attachment, ok := item.(map[string]interface{})
-		if !ok {
-			return nil, output.ErrValidation("record field %q contains unexpected attachment item type %T", fieldName, item)
-		}
-		merged = append(merged, normalizeAttachmentForPatch(attachment))
+	attachments, _ := data["attachments"].(map[string]interface{})
+	if attachments == nil {
+		return map[string]interface{}{}, nil
 	}
-	merged = append(merged, uploaded)
-	return merged, nil
-}
-
-func normalizeAttachmentForPatch(attachment map[string]interface{}) map[string]interface{} {
-	normalized := map[string]interface{}{}
-	if fileToken, _ := attachment["file_token"].(string); fileToken != "" {
-		normalized["file_token"] = fileToken
-	}
-	if name, _ := attachment["name"].(string); name != "" {
-		normalized["name"] = name
-	}
-	if mimeType, _ := attachment["mime_type"].(string); mimeType != "" {
-		normalized["mime_type"] = mimeType
-	}
-	if size, ok := attachment["size"]; ok && !util.IsNil(size) {
-		normalized["size"] = size
-	}
-	if imageWidth, ok := attachment["image_width"]; ok && !util.IsNil(imageWidth) {
-		normalized["image_width"] = imageWidth
-	}
-	if imageHeight, ok := attachment["image_height"]; ok && !util.IsNil(imageHeight) {
-		normalized["image_height"] = imageHeight
-	}
-	normalized["deprecated_set_attachment"] = true
-	return normalized
+	return attachments, nil
 }
 
 func uploadAttachmentToBase(runtime *common.RuntimeContext, filePath, fileName, baseToken string, fileSize int64) (map[string]interface{}, error) {
@@ -280,15 +491,51 @@ func uploadAttachmentToBase(runtime *common.RuntimeContext, filePath, fileName,
 	}
 
 	attachment := map[string]interface{}{
-		"file_token":                fileToken,
-		"name":                      fileName,
-		"mime_type":                 mimeType,
-		"size":                      fileSize,
-		"deprecated_set_attachment": true,
+		"file_token": fileToken,
+		"name":       fileName,
+		"mime_type":  mimeType,
+		"size":       fileSize,
+	}
+	if width, height, ok := detectAttachmentImageDimensions(runtime.FileIO(), filePath, mimeType); ok {
+		attachment["image_width"] = width
+		attachment["image_height"] = height
+	} else if attachmentImageDimensionsWarningEnabled(mimeType) {
+		fmt.Fprintf(runtime.IO().ErrOut, "Warning: image dimensions unavailable for %s; attachment may display as square\n", fileName)
 	}
 	return attachment, nil
 }
 
+func attachmentAppendItem(attachment map[string]interface{}) map[string]interface{} {
+	item := map[string]interface{}{
+		"file_token": attachment["file_token"],
+	}
+	if width, ok := attachment["image_width"]; ok && !util.IsNil(width) {
+		item["image_width"] = width
+	}
+	if height, ok := attachment["image_height"]; ok && !util.IsNil(height) {
+		item["image_height"] = height
+	}
+	return item
+}
+
+func fileTokenPatchItems(tokens []string) []interface{} {
+	items := make([]interface{}, 0, len(tokens))
+	for _, token := range tokens {
+		items = append(items, map[string]interface{}{"file_token": token})
+	}
+	return items
+}
+
+func buildSingleCellAttachmentsBody(recordID, fieldID string, items []interface{}) map[string]interface{} {
+	return map[string]interface{}{
+		"attachments": map[string]interface{}{
+			recordID: map[string]interface{}{
+				fieldID: items,
+			},
+		},
+	}
+}
+
 func detectAttachmentMIMEType(fio fileio.FileIO, filePath, fileName string) (string, error) {
 	if byExt := strings.TrimSpace(mime.TypeByExtension(strings.ToLower(filepath.Ext(fileName)))); byExt != "" {
 		return stripMIMEParams(byExt), nil
@@ -311,6 +558,309 @@ func detectAttachmentMIMEType(fio fileio.FileIO, filePath, fileName string) (str
 	return detectAttachmentMIMEFromContent(buf[:n]), nil
 }
 
+func detectAttachmentImageDimensions(fio fileio.FileIO, filePath string, mimeType string) (int, int, bool) {
+	if fio == nil || !strings.HasPrefix(mimeType, "image/") {
+		return 0, 0, false
+	}
+	f, err := fio.Open(filePath)
+	if err != nil {
+		return 0, 0, false
+	}
+	defer f.Close()
+	cfg, _, err := image.DecodeConfig(f)
+	if err != nil || cfg.Width <= 0 || cfg.Height <= 0 {
+		return 0, 0, false
+	}
+	return cfg.Width, cfg.Height, true
+}
+
+func attachmentImageDimensionsWarningEnabled(mimeType string) bool {
+	switch mimeType {
+	case "image/gif", "image/jpeg", "image/png":
+		return true
+	default:
+		return false
+	}
+}
+
+type baseAttachmentDownloadItem struct {
+	RecordID   string
+	FieldID    string
+	FileToken  string
+	Name       string
+	Size       interface{}
+	ExtraInfo  string
+	MimeType   string
+	RawPayload map[string]interface{}
+}
+
+type baseAttachmentDownloadTarget struct {
+	Item         baseAttachmentDownloadItem
+	TargetPath   string
+	ResolvedPath string
+}
+
+func selectAttachmentDownloadItems(attachments map[string]interface{}, recordID string, tokens []string) ([]baseAttachmentDownloadItem, error) {
+	recordRaw, ok := attachments[recordID]
+	if !ok {
+		return nil, output.ErrValidation("record %q has no attachment metadata; verify the record-id", recordID)
+	}
+	fields, ok := recordRaw.(map[string]interface{})
+	if !ok {
+		return nil, output.ErrValidation("record %q attachment metadata has unexpected type %T", recordID, recordRaw)
+	}
+	byToken := map[string]baseAttachmentDownloadItem{}
+	fieldIDs := make([]string, 0, len(fields))
+	for currentFieldID := range fields {
+		fieldIDs = append(fieldIDs, currentFieldID)
+	}
+	sort.Strings(fieldIDs)
+	for _, currentFieldID := range fieldIDs {
+		rawList := fields[currentFieldID]
+		items, ok := rawList.([]interface{})
+		if !ok {
+			return nil, output.ErrValidation("record %q field %q attachment metadata has unexpected type %T", recordID, currentFieldID, rawList)
+		}
+		for _, rawItem := range items {
+			item, ok := rawItem.(map[string]interface{})
+			if !ok {
+				return nil, output.ErrValidation("record %q field %q contains unexpected attachment item type %T", recordID, currentFieldID, rawItem)
+			}
+			fileToken, _ := item["file_token"].(string)
+			if fileToken == "" {
+				continue
+			}
+			if _, exists := byToken[fileToken]; exists {
+				continue
+			}
+			name, _ := item["name"].(string)
+			extraInfo, _ := item["extra_info"].(string)
+			mimeType, _ := item["mime_type"].(string)
+			byToken[fileToken] = baseAttachmentDownloadItem{
+				RecordID:   recordID,
+				FieldID:    currentFieldID,
+				FileToken:  fileToken,
+				Name:       name,
+				Size:       item["size"],
+				ExtraInfo:  extraInfo,
+				MimeType:   mimeType,
+				RawPayload: item,
+			}
+		}
+	}
+	result := make([]baseAttachmentDownloadItem, 0, len(tokens))
+	if len(tokens) == 0 {
+		for _, item := range byToken {
+			result = append(result, item)
+		}
+		if len(result) == 0 {
+			return nil, output.ErrValidation("record %q has no attachments to download", recordID)
+		}
+		sort.SliceStable(result, func(i, j int) bool {
+			leftName := strings.ToLower(baseAttachmentDownloadName(result[i]))
+			rightName := strings.ToLower(baseAttachmentDownloadName(result[j]))
+			if leftName != rightName {
+				return leftName < rightName
+			}
+			return result[i].FileToken < result[j].FileToken
+		})
+		return result, nil
+	}
+	for _, token := range tokens {
+		item, ok := byToken[token]
+		if !ok {
+			return nil, output.ErrValidation("attachment file_token %q not found in record %q; verify the record-id/file-token pair", token, recordID)
+		}
+		result = append(result, item)
+	}
+	return result, nil
+}
+
+func planAttachmentDownloadTargets(runtime *common.RuntimeContext, items []baseAttachmentDownloadItem, outputPath string, outputIsDir bool, overwrite bool) ([]baseAttachmentDownloadTarget, error) {
+	names := downloadTargetNames(items, outputIsDir || outputPathLooksDirectory(runtime, outputPath))
+	targets := make([]baseAttachmentDownloadTarget, 0, len(items))
+	seen := map[string]baseAttachmentDownloadItem{}
+	for _, item := range items {
+		targetName := names[item.FileToken]
+		targetPath := outputPath
+		if targetName != "" {
+			targetPath = filepath.Join(outputPath, targetName)
+		}
+		resolved, err := runtime.ResolveSavePath(targetPath)
+		if err != nil {
+			return nil, output.ErrValidation("unsafe output path: %s", err)
+		}
+		if previous, exists := seen[resolved]; exists {
+			return nil, output.ErrValidation("multiple attachments resolve to the same output path %q (%s and %s); download them separately or choose a different directory", resolved, previous.FileToken, item.FileToken)
+		}
+		seen[resolved] = item
+		if !overwrite {
+			if _, statErr := runtime.FileIO().Stat(targetPath); statErr == nil {
+				return nil, output.ErrValidation("output file already exists: %s (use --overwrite to replace)", targetPath)
+			}
+		}
+		targets = append(targets, baseAttachmentDownloadTarget{
+			Item:         item,
+			TargetPath:   targetPath,
+			ResolvedPath: resolved,
+		})
+	}
+	return targets, nil
+}
+
+func downloadTargetNames(items []baseAttachmentDownloadItem, outputIsDir bool) map[string]string {
+	if !outputIsDir {
+		return nil
+	}
+	nameCounts := make(map[string]int, len(items))
+	for _, item := range items {
+		nameCounts[baseAttachmentDownloadName(item)]++
+	}
+	names := make(map[string]string, len(items))
+	for _, item := range items {
+		name := baseAttachmentDownloadName(item)
+		if nameCounts[name] > 1 {
+			name = attachmentNameWithTokenSuffix(name, item.FileToken)
+		}
+		names[item.FileToken] = name
+	}
+	return names
+}
+
+func baseAttachmentDownloadName(item baseAttachmentDownloadItem) string {
+	name := filepath.Base(strings.TrimSpace(item.Name))
+	if name == "" || name == "." || name == string(filepath.Separator) {
+		name = item.FileToken
+	}
+	return name
+}
+
+func attachmentNameWithTokenSuffix(name, fileToken string) string {
+	ext := filepath.Ext(name)
+	stem := strings.TrimSuffix(name, ext)
+	if stem == "" {
+		stem = name
+	}
+	return stem + "_" + safeAttachmentFileTokenSuffix(fileToken) + ext
+}
+
+func safeAttachmentFileTokenSuffix(fileToken string) string {
+	var b strings.Builder
+	for _, r := range fileToken {
+		if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') || r == '_' || r == '-' {
+			b.WriteRune(r)
+			continue
+		}
+		b.WriteByte('_')
+	}
+	suffix := strings.Trim(b.String(), "_")
+	if suffix == "" {
+		return "file"
+	}
+	return suffix
+}
+
+func downloadBaseAttachment(ctx context.Context, runtime *common.RuntimeContext, item baseAttachmentDownloadItem, targetPath string, overwrite bool) (map[string]interface{}, error) {
+	if _, err := runtime.ResolveSavePath(targetPath); err != nil {
+		return nil, output.ErrValidation("unsafe output path: %s", err)
+	}
+
+	query := larkcore.QueryParams{}
+	if item.ExtraInfo != "" {
+		query.Set("extra", item.ExtraInfo)
+	}
+	resp, err := runtime.DoAPIStream(ctx, &larkcore.ApiReq{
+		HttpMethod:  http.MethodGet,
+		ApiPath:     fmt.Sprintf("/open-apis/drive/v1/medias/%s/download", validate.EncodePathSegment(item.FileToken)),
+		QueryParams: query,
+	})
+	if err != nil {
+		return nil, output.ErrNetwork("download failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if !overwrite {
+		if _, statErr := runtime.FileIO().Stat(targetPath); statErr == nil {
+			return nil, output.ErrValidation("output file already exists: %s (use --overwrite to replace)", targetPath)
+		}
+	}
+	result, err := runtime.FileIO().Save(targetPath, fileio.SaveOptions{
+		ContentType:   resp.Header.Get("Content-Type"),
+		ContentLength: resp.ContentLength,
+	}, resp.Body)
+	if err != nil {
+		return nil, common.WrapSaveErrorByCategory(err, "io")
+	}
+	savedPath, _ := runtime.ResolveSavePath(targetPath)
+	if savedPath == "" {
+		savedPath = targetPath
+	}
+	return map[string]interface{}{
+		"record_id":    item.RecordID,
+		"field_id":     item.FieldID,
+		"file_token":   item.FileToken,
+		"name":         item.Name,
+		"size":         item.Size,
+		"saved_path":   savedPath,
+		"size_bytes":   result.Size(),
+		"content_type": resp.Header.Get("Content-Type"),
+	}, nil
+}
+
+func attachmentDownloadFailure(target baseAttachmentDownloadTarget, err error) map[string]interface{} {
+	return map[string]interface{}{
+		"record_id":     target.Item.RecordID,
+		"field_id":      target.Item.FieldID,
+		"file_token":    target.Item.FileToken,
+		"name":          target.Item.Name,
+		"target_path":   target.TargetPath,
+		"resolved_path": target.ResolvedPath,
+		"error":         err.Error(),
+	}
+}
+
+func attachmentDownloadProgressError(err error, downloaded []map[string]interface{}, failed []map[string]interface{}) error {
+	msg := fmt.Sprintf("download failed after %d attachment(s) succeeded and %d failed: %v", len(downloaded), len(failed), err)
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) && exitErr.Detail != nil {
+		return &output.ExitError{
+			Code: exitErr.Code,
+			Detail: &output.ErrDetail{
+				Type:    exitErr.Detail.Type,
+				Code:    exitErr.Detail.Code,
+				Message: msg,
+				Hint:    "Some files may already have been saved. Inspect error.detail.downloaded before retrying, or rerun with --overwrite if the failed target now exists.",
+				Detail: map[string]interface{}{
+					"downloaded": downloaded,
+					"failed":     failed,
+				},
+			},
+			Err: err,
+		}
+	}
+	return &output.ExitError{
+		Code: output.ExitInternal,
+		Detail: &output.ErrDetail{
+			Type:    "io",
+			Message: msg,
+			Hint:    "Some files may already have been saved. Inspect error.detail.downloaded before retrying, or rerun with --overwrite if the failed target now exists.",
+			Detail: map[string]interface{}{
+				"downloaded": downloaded,
+				"failed":     failed,
+			},
+		},
+		Err: err,
+	}
+}
+
+func outputPathLooksDirectory(runtime *common.RuntimeContext, outputPath string) bool {
+	if strings.HasSuffix(outputPath, "/") || strings.HasSuffix(outputPath, string(filepath.Separator)) {
+		return true
+	}
+	info, err := runtime.FileIO().Stat(outputPath)
+	return err == nil && info.IsDir()
+}
+
 func stripMIMEParams(value string) string {
 	if i := strings.IndexByte(value, ';'); i != -1 {
 		value = value[:i]

shortcuts/base/record_upload_attachment_test.go

@@ -5,6 +5,9 @@ package base
 
 import (
 	"bytes"
+	"image"
+	"image/color"
+	"image/png"
 	"io"
 	"io/fs"
 	"os"
@@ -82,6 +85,42 @@ func TestDetectAttachmentMIMETypeFallsBackToContent(t *testing.T) {
 	}
 }
 
+func TestDetectAttachmentImageDimensions(t *testing.T) {
+	var buf bytes.Buffer
+	img := image.NewRGBA(image.Rect(0, 0, 4, 3))
+	img.Set(0, 0, color.RGBA{G: 255, A: 255})
+	if err := png.Encode(&buf, img); err != nil {
+		t.Fatalf("png.Encode() error = %v", err)
+	}
+	fio := attachmentTestFileIO{openFile: newAttachmentTestFile(buf.Bytes())}
+
+	width, height, ok := detectAttachmentImageDimensions(fio, "image.png", "image/png")
+	if !ok || width != 4 || height != 3 {
+		t.Fatalf("detectAttachmentImageDimensions() = (%d,%d,%v), want (4,3,true)", width, height, ok)
+	}
+}
+
+func TestAttachmentImageDimensionsWarningEnabled(t *testing.T) {
+	tests := []struct {
+		mimeType string
+		want     bool
+	}{
+		{mimeType: "image/gif", want: true},
+		{mimeType: "image/jpeg", want: true},
+		{mimeType: "image/png", want: true},
+		{mimeType: "image/webp", want: false},
+		{mimeType: "application/pdf", want: false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.mimeType, func(t *testing.T) {
+			if got := attachmentImageDimensionsWarningEnabled(tt.mimeType); got != tt.want {
+				t.Fatalf("attachmentImageDimensionsWarningEnabled(%q) = %v, want %v", tt.mimeType, got, tt.want)
+			}
+		})
+	}
+}
+
 func TestDetectAttachmentMIMETypeWrapsOpenError(t *testing.T) {
 	fio := attachmentTestFileIO{openErr: os.ErrNotExist}
 

shortcuts/base/shortcuts.go

@@ -44,6 +44,8 @@ func Shortcuts() []common.Shortcut {
 		BaseRecordBatchUpdate,
 		BaseRecordShareLinkCreate,
 		BaseRecordUploadAttachment,
+		BaseRecordDownloadAttachment,
+		BaseRecordRemoveAttachment,
 		BaseRecordDelete,
 		BaseRecordHistoryList,
 		BaseBaseGet,

shortcuts/common/drive_meta.go

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package common
+
+// FetchDriveMetaTitle looks up the document title via the drive metas batch_query API.
+func FetchDriveMetaTitle(runtime *RuntimeContext, token, docType string) (string, error) {
+	data, err := runtime.CallAPI(
+		"POST",
+		"/open-apis/drive/v1/metas/batch_query",
+		nil,
+		map[string]interface{}{
+			"request_docs": []map[string]interface{}{
+				{
+					"doc_token": token,
+					"doc_type":  docType,
+				},
+			},
+		},
+	)
+	if err != nil {
+		return "", err
+	}
+
+	metas := GetSlice(data, "metas")
+	if len(metas) == 0 {
+		return "", nil
+	}
+	meta, _ := metas[0].(map[string]interface{})
+	return GetString(meta, "title"), nil
+}

shortcuts/common/drive_meta_test.go

@@ -0,0 +1,123 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+	"fmt"
+	"sync/atomic"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+var driveMetaTestSeq atomic.Int64
+
+func TestFetchDriveMetaTitle(t *testing.T) {
+	t.Run("returns title from batch_query response", func(t *testing.T) {
+		runtime, reg := newDriveMetaTestRuntime(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/metas/batch_query",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"metas": []map[string]interface{}{
+						{"doc_token": "doxcnABC", "doc_type": "docx", "title": "My Document"},
+					},
+				},
+			},
+		})
+
+		title, err := FetchDriveMetaTitle(runtime, "doxcnABC", "docx")
+		if err != nil {
+			t.Fatalf("FetchDriveMetaTitle() error: %v", err)
+		}
+		if title != "My Document" {
+			t.Errorf("title = %q, want %q", title, "My Document")
+		}
+	})
+
+	t.Run("returns empty string when metas is empty", func(t *testing.T) {
+		runtime, reg := newDriveMetaTestRuntime(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/metas/batch_query",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"metas": []map[string]interface{}{},
+				},
+			},
+		})
+
+		title, err := FetchDriveMetaTitle(runtime, "doxcnABC", "docx")
+		if err != nil {
+			t.Fatalf("FetchDriveMetaTitle() error: %v", err)
+		}
+		if title != "" {
+			t.Errorf("title = %q, want empty string", title)
+		}
+	})
+
+	t.Run("returns empty string when meta has no title", func(t *testing.T) {
+		runtime, reg := newDriveMetaTestRuntime(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/metas/batch_query",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"metas": []map[string]interface{}{
+						{"doc_token": "doxcnABC", "doc_type": "docx"},
+					},
+				},
+			},
+		})
+
+		title, err := FetchDriveMetaTitle(runtime, "doxcnABC", "docx")
+		if err != nil {
+			t.Fatalf("FetchDriveMetaTitle() error: %v", err)
+		}
+		if title != "" {
+			t.Errorf("title = %q, want empty string", title)
+		}
+	})
+
+	t.Run("propagates API error", func(t *testing.T) {
+		runtime, reg := newDriveMetaTestRuntime(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/metas/batch_query",
+			Body: map[string]interface{}{
+				"code": 99991668,
+				"msg":  "permission denied",
+			},
+		})
+
+		_, err := FetchDriveMetaTitle(runtime, "doxcnABC", "docx")
+		if err == nil {
+			t.Fatal("FetchDriveMetaTitle() expected error, got nil")
+		}
+	})
+}
+
+func newDriveMetaTestRuntime(t *testing.T) (*RuntimeContext, *httpmock.Registry) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	cfg := &core.CliConfig{
+		AppID: fmt.Sprintf("drive-meta-test-%d", driveMetaTestSeq.Add(1)), AppSecret: "test-secret", Brand: core.BrandFeishu,
+	}
+	f, _, _, reg := cmdutil.TestFactory(t, cfg)
+	runtime := &RuntimeContext{
+		ctx:        context.Background(),
+		Config:     cfg,
+		Factory:    f,
+		resolvedAs: core.AsBot,
+	}
+	return runtime, reg
+}

shortcuts/common/resource_url.go

@@ -4,6 +4,7 @@
 package common
 
 import (
+	"net/url"
 	"strings"
 
 	"github.com/larksuite/cli/internal/core"
@@ -55,3 +56,79 @@ func BuildResourceURL(brand core.LarkBrand, kind, token string) string {
 		return ""
 	}
 }
+
+// ResourceRef holds the parsed type and token from a Lark resource URL.
+type ResourceRef struct {
+	Type  string // e.g. "docx", "bitable", "wiki", "sheet", etc.
+	Token string // the token extracted from the URL path
+}
+
+// urlPathToType maps URL path prefixes to resource types.
+// Longer prefixes must come first to avoid false matches
+// (e.g. "/drive/folder/" before a hypothetical "/drive/").
+// Aliases (e.g. "/bitable/" → "bitable") must come after the
+// canonical prefix to keep the list deterministic.
+var urlPathToType = []struct {
+	Prefix string
+	Type   string
+}{
+	{"/drive/folder/", "folder"},
+	{"/docx/", "docx"},
+	{"/doc/", "doc"},
+	{"/sheets/", "sheet"},
+	{"/base/", "bitable"},
+	{"/bitable/", "bitable"},
+	{"/wiki/", "wiki"},
+	{"/file/", "file"},
+	{"/mindnote/", "mindnote"},
+	{"/slides/", "slides"},
+}
+
+// ParseResourceURL parses a Lark/Feishu URL and extracts the resource type
+// and token from the URL path. It is the inverse of BuildResourceURL.
+//
+// Supported path patterns:
+//
+//	/docx/TOKEN      -> {Type: "docx", Token: TOKEN}
+//	/doc/TOKEN       -> {Type: "doc",  Token: TOKEN}
+//	/sheets/TOKEN    -> {Type: "sheet", Token: TOKEN}
+//	/base/TOKEN      -> {Type: "bitable", Token: TOKEN}
+//	/wiki/TOKEN      -> {Type: "wiki", Token: TOKEN}
+//	/file/TOKEN      -> {Type: "file", Token: TOKEN}
+//	/drive/folder/TOKEN -> {Type: "folder", Token: TOKEN}
+//	/mindnote/TOKEN  -> {Type: "mindnote", Token: TOKEN}
+//	/slides/TOKEN    -> {Type: "slides", Token: TOKEN}
+//
+// Returns (ResourceRef{}, false) when the URL does not match any known pattern.
+func ParseResourceURL(rawURL string) (ResourceRef, bool) {
+	rawURL = strings.TrimSpace(rawURL)
+	if rawURL == "" {
+		return ResourceRef{}, false
+	}
+
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return ResourceRef{}, false
+	}
+
+	path := u.Path
+
+	for _, mapping := range urlPathToType {
+		if !strings.HasPrefix(path, mapping.Prefix) {
+			continue
+		}
+		token := path[len(mapping.Prefix):]
+		// Trim trailing slashes and stop at the next path segment boundary.
+		token = strings.TrimRight(token, "/")
+		if idx := strings.IndexByte(token, '/'); idx >= 0 {
+			token = token[:idx]
+		}
+		token = strings.TrimSpace(token)
+		if token == "" {
+			return ResourceRef{}, false
+		}
+		return ResourceRef{Type: mapping.Type, Token: token}, true
+	}
+
+	return ResourceRef{}, false
+}

shortcuts/common/resource_url_test.go

@@ -9,6 +9,102 @@ import (
 	"github.com/larksuite/cli/internal/core"
 )
 
+func TestParseResourceURL(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		rawURL    string
+		wantType  string
+		wantToken string
+		wantOK    bool
+	}{
+		// All 9 supported types
+		{"docx", "https://xxx.feishu.cn/docx/doxcnABC", "docx", "doxcnABC", true},
+		{"doc", "https://xxx.feishu.cn/doc/doccnABC", "doc", "doccnABC", true},
+		{"sheet", "https://xxx.feishu.cn/sheets/shtcnABC", "sheet", "shtcnABC", true},
+		{"bitable via /base/", "https://xxx.feishu.cn/base/bascnABC", "bitable", "bascnABC", true},
+		{"bitable via /bitable/", "https://xxx.feishu.cn/bitable/bascnABC", "bitable", "bascnABC", true},
+		{"wiki", "https://xxx.feishu.cn/wiki/wikcnABC", "wiki", "wikcnABC", true},
+		{"file", "https://xxx.feishu.cn/file/boxcnABC", "file", "boxcnABC", true},
+		{"folder", "https://xxx.feishu.cn/drive/folder/fldcnABC", "folder", "fldcnABC", true},
+		{"mindnote", "https://xxx.feishu.cn/mindnote/mncnABC", "mindnote", "mncnABC", true},
+		{"slides", "https://xxx.feishu.cn/slides/slkcnABC", "slides", "slkcnABC", true},
+
+		// Lark domain
+		{"lark docx", "https://xxx.larksuite.com/docx/doxcnABC", "docx", "doxcnABC", true},
+		{"lark wiki", "https://xxx.larksuite.com/wiki/wikcnABC", "wiki", "wikcnABC", true},
+
+		// With query parameters
+		{"with query", "https://xxx.feishu.cn/docx/doxcnABC?from=wiki", "docx", "doxcnABC", true},
+		{"with fragment", "https://xxx.feishu.cn/docx/doxcnABC#section", "docx", "doxcnABC", true},
+
+		// With trailing slash
+		{"trailing slash", "https://xxx.feishu.cn/docx/doxcnABC/", "docx", "doxcnABC", true},
+
+		// With extra path segments after token
+		{"extra path", "https://xxx.feishu.cn/docx/doxcnABC/edit", "docx", "doxcnABC", true},
+
+		// Non-Lark host with Lark-like path (host validation is the caller's responsibility)
+		{"non-lark host with lark path", "https://google.com/docx/doxcnABC", "docx", "doxcnABC", true},
+
+		// Negative cases
+		{"unrecognized path", "https://xxx.feishu.cn/calendar/calABC", "", "", false},
+		{"non-lark host unrecognized path", "https://example.com/page", "", "", false},
+		{"empty input", "", "", "", false},
+		{"bare token", "doxcnABC", "", "", false},
+		{"invalid url parse", "://not-a-valid-url", "", "", false},
+		{"matching prefix but empty token", "https://xxx.feishu.cn/docx/", "", "", false},
+		{"matching prefix but whitespace-only token", "https://xxx.feishu.cn/docx/   ", "", "", false},
+		{"whitespace-only input", "   ", "", "", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ref, ok := ParseResourceURL(tt.rawURL)
+			if ok != tt.wantOK {
+				t.Errorf("ParseResourceURL(%q) ok = %v, want %v", tt.rawURL, ok, tt.wantOK)
+			}
+			if ok {
+				if ref.Type != tt.wantType {
+					t.Errorf("ParseResourceURL(%q) Type = %q, want %q", tt.rawURL, ref.Type, tt.wantType)
+				}
+				if ref.Token != tt.wantToken {
+					t.Errorf("ParseResourceURL(%q) Token = %q, want %q", tt.rawURL, ref.Token, tt.wantToken)
+				}
+			}
+		})
+	}
+}
+
+// TestParseResourceURL_RoundTrip verifies that ParseResourceURL is the inverse
+// of BuildResourceURL for all supported types.
+func TestParseResourceURL_RoundTrip(t *testing.T) {
+	t.Parallel()
+
+	types := []string{"docx", "doc", "sheet", "bitable", "wiki", "file", "folder", "mindnote", "slides"}
+	token := "testTOKEN123"
+
+	for _, kind := range types {
+		t.Run(kind, func(t *testing.T) {
+			built := BuildResourceURL(core.BrandFeishu, kind, token)
+			if built == "" {
+				t.Fatalf("BuildResourceURL returned empty for kind %q", kind)
+			}
+			ref, ok := ParseResourceURL(built)
+			if !ok {
+				t.Fatalf("ParseResourceURL(%q) returned ok=false", built)
+			}
+			if ref.Type != kind {
+				t.Errorf("round-trip type mismatch: got %q, want %q", ref.Type, kind)
+			}
+			if ref.Token != token {
+				t.Errorf("round-trip token mismatch: got %q, want %q", ref.Token, token)
+			}
+		})
+	}
+}
+
 func TestBuildResourceURL(t *testing.T) {
 	t.Parallel()
 

shortcuts/common/runner.go

@@ -103,13 +103,15 @@ func (ctx *RuntimeContext) fetchBotInfo() (*BotInfo, error) {
 	if resp.StatusCode >= 400 {
 		return nil, fmt.Errorf("fetch bot info: HTTP %d", resp.StatusCode)
 	}
+	// /open-apis/bot/v3/info returns `{code, msg, bot: {...}}` — the bot
+	// payload is under "bot", not "data" as the newer Lark API convention.
 	var envelope struct {
 		Code int    `json:"code"`
 		Msg  string `json:"msg"`
 		Data struct {
 			OpenID  string `json:"open_id"`
 			AppName string `json:"app_name"`
-		} `json:"data"`
+		} `json:"bot"`
 	}
 	if err := json.Unmarshal(resp.RawBody, &envelope); err != nil {
 		return nil, fmt.Errorf("fetch bot info: unmarshal: %w", err)

shortcuts/common/runner_botinfo_test.go

@@ -57,7 +57,7 @@ func TestFetchBotInfo_Success(t *testing.T) {
 		URL:    "/open-apis/bot/v3/info",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
+			"bot": map[string]interface{}{
 				"open_id":  "ou_bot_abc123",
 				"app_name": "TestBot",
 			},
@@ -86,7 +86,7 @@ func TestFetchBotInfo_ShortcutHeaders(t *testing.T) {
 		URL:    "/open-apis/bot/v3/info",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
+			"bot": map[string]interface{}{
 				"open_id":  "ou_bot_header",
 				"app_name": "HeaderBot",
 			},
@@ -119,7 +119,7 @@ func TestFetchBotInfo_OnceSemantics(t *testing.T) {
 		URL:    "/open-apis/bot/v3/info",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
+			"bot": map[string]interface{}{
 				"open_id":  "ou_bot_once",
 				"app_name": "OnceBot",
 			},
@@ -183,7 +183,7 @@ func TestFetchBotInfo_EmptyOpenID(t *testing.T) {
 		URL:    "/open-apis/bot/v3/info",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
+			"bot": map[string]interface{}{
 				"open_id":  "",
 				"app_name": "EmptyBot",
 			},

shortcuts/doc/docs_update.go

@@ -118,7 +118,7 @@ func validateUpdateV1(_ context.Context, runtime *common.RuntimeContext) error {
 	}
 
 	if needsSelectionV1[mode] && selEllipsis == "" && selTitle == "" {
-		return common.FlagErrorf("--%s mode requires --selection-with-ellipsis or --selection-by-title", mode)
+		return common.FlagErrorf(selectionRequiredMessageV1(mode))
 	}
 	if err := validateSelectionByTitleV1(selTitle); err != nil {
 		return err
@@ -127,6 +127,14 @@ func validateUpdateV1(_ context.Context, runtime *common.RuntimeContext) error {
 	return nil
 }
 
+func selectionRequiredMessageV1(mode string) string {
+	msg := fmt.Sprintf("--%s mode requires --selection-with-ellipsis or --selection-by-title", mode)
+	if mode == "replace_all" {
+		msg += ". If you intended to replace the entire document body, use --mode overwrite instead."
+	}
+	return msg
+}
+
 func validateSelectionByTitleV1(title string) error {
 	if title == "" {
 		return nil

shortcuts/doc/docs_update_test.go

@@ -4,6 +4,7 @@ package doc
 
 import (
 	"reflect"
+	"strings"
 	"testing"
 )
 
@@ -32,6 +33,33 @@ func TestValidCommandsV2(t *testing.T) {
 
 // ── V1 tests ──
 
+func TestSelectionRequiredMessageV1ReplaceAllSuggestsOverwrite(t *testing.T) {
+	t.Parallel()
+
+	msg := selectionRequiredMessageV1("replace_all")
+	for _, needle := range []string{
+		"--replace_all mode requires --selection-with-ellipsis or --selection-by-title",
+		"replace the entire document body",
+		"--mode overwrite",
+	} {
+		if !strings.Contains(msg, needle) {
+			t.Fatalf("message missing %q: %s", needle, msg)
+		}
+	}
+}
+
+func TestSelectionRequiredMessageV1OtherModesDoNotSuggestOverwrite(t *testing.T) {
+	t.Parallel()
+
+	msg := selectionRequiredMessageV1("replace_range")
+	if strings.Contains(msg, "--mode overwrite") {
+		t.Fatalf("replace_range message should not suggest overwrite: %s", msg)
+	}
+	if !strings.Contains(msg, "--replace_range mode requires --selection-with-ellipsis or --selection-by-title") {
+		t.Fatalf("unexpected message: %s", msg)
+	}
+}
+
 func TestIsWhiteboardCreateMarkdown(t *testing.T) {
 	t.Run("blank whiteboard tags", func(t *testing.T) {
 		markdown := "<whiteboard type=\"blank\"></whiteboard>\n<whiteboard type=\"blank\"></whiteboard>"

shortcuts/drive/drive_export.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -25,6 +26,7 @@ var DriveExport = common.Shortcut{
 	Scopes: []string{
 		"docs:document.content:read",
 		"docs:document:export",
+		"docx:document:readonly",
 		"drive:drive.metadata:readonly",
 	},
 	AuthTypes: []string{"user", "bot"},
@@ -52,16 +54,15 @@ var DriveExport = common.Shortcut{
 			FileExtension: runtime.Str("file-extension"),
 			SubID:         runtime.Str("sub-id"),
 		}
-		// Markdown export is a special case: docx markdown comes from docs content
-		// directly instead of the Drive export task API.
+		// Markdown export is a special case: docx markdown comes from the V2
+		// docs_ai fetch API directly instead of the Drive export task API.
 		if spec.FileExtension == "markdown" {
+			apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/fetch", validate.EncodePathSegment(spec.Token))
 			dr := common.NewDryRunAPI().
 				Desc("2-step orchestration: fetch docx markdown -> write local file").
-				GET("/open-apis/docs/v1/content").
-				Params(map[string]interface{}{
-					"doc_token":    spec.Token,
-					"doc_type":     "docx",
-					"content_type": "markdown",
+				POST(apiPath).
+				Body(map[string]interface{}{
+					"format": "markdown",
 				}).
 				Set("output_dir", runtime.Str("output-dir"))
 			if name := strings.TrimSpace(runtime.Str("file-name")); name != "" {
@@ -101,28 +102,38 @@ var DriveExport = common.Shortcut{
 		overwrite := runtime.Bool("overwrite")
 
 		// Markdown export bypasses the async export task and writes the fetched
-		// markdown content directly to disk.
+		// markdown content directly to disk. Uses the V2 docs_ai fetch API for
+		// higher-quality Lark-flavored Markdown output.
 		if spec.FileExtension == "markdown" {
 			fmt.Fprintf(runtime.IO().ErrOut, "Exporting docx as markdown: %s\n", common.MaskToken(spec.Token))
-			data, err := runtime.CallAPI(
-				"GET",
-				"/open-apis/docs/v1/content",
-				map[string]interface{}{
-					"doc_token":    spec.Token,
-					"doc_type":     "docx",
-					"content_type": "markdown",
-				},
+			apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/fetch", validate.EncodePathSegment(spec.Token))
+			data, err := runtime.DoAPIJSONWithLogID(
+				"POST",
+				apiPath,
 				nil,
+				map[string]interface{}{
+					"format": "markdown",
+				},
 			)
 			if err != nil {
 				return err
 			}
 
+			// Extract content from the V2 response: data.document.content
+			doc, ok := data["document"].(map[string]interface{})
+			if !ok {
+				return output.Errorf(output.ExitAPI, "api_error", "invalid markdown fetch response: missing document object")
+			}
+			content, ok := doc["content"].(string)
+			if !ok {
+				return output.Errorf(output.ExitAPI, "api_error", "invalid markdown fetch response: missing document.content")
+			}
+
 			fileName := preferredFileName
 			if fileName == "" {
 				// Prefer the remote title for the exported file name, but still fall
 				// back to the token if metadata is empty.
-				title, err := fetchDriveMetaTitle(runtime, spec.Token, spec.DocType)
+				title, err := common.FetchDriveMetaTitle(runtime, spec.Token, spec.DocType)
 				if err != nil {
 					fmt.Fprintf(runtime.IO().ErrOut, "Title lookup failed, using token as filename: %v\n", err)
 					title = spec.Token
@@ -130,7 +141,7 @@ var DriveExport = common.Shortcut{
 				fileName = title
 			}
 			fileName = ensureExportFileExtension(sanitizeExportFileName(fileName, spec.Token), spec.FileExtension)
-			savedPath, err := saveContentToOutputDir(runtime.FileIO(), outputDir, fileName, []byte(common.GetString(data, "content")), overwrite)
+			savedPath, err := saveContentToOutputDir(runtime.FileIO(), outputDir, fileName, []byte(content), overwrite)
 			if err != nil {
 				return err
 			}
@@ -141,7 +152,7 @@ var DriveExport = common.Shortcut{
 				"file_extension": spec.FileExtension,
 				"file_name":      filepath.Base(savedPath),
 				"saved_path":     savedPath,
-				"size_bytes":     len([]byte(common.GetString(data, "content"))),
+				"size_bytes":     len(content),
 			}, nil)
 			return nil
 		}

shortcuts/drive/drive_export_common.go

@@ -228,34 +228,6 @@ func parseDriveExportStatus(ticket string, data map[string]interface{}) driveExp
 	return status
 }
 
-// fetchDriveMetaTitle looks up the document title so exported files can use a
-// human-readable default name when possible.
-func fetchDriveMetaTitle(runtime *common.RuntimeContext, token, docType string) (string, error) {
-	data, err := runtime.CallAPI(
-		"POST",
-		"/open-apis/drive/v1/metas/batch_query",
-		nil,
-		map[string]interface{}{
-			"request_docs": []map[string]interface{}{
-				{
-					"doc_token": token,
-					"doc_type":  docType,
-				},
-			},
-		},
-	)
-	if err != nil {
-		return "", err
-	}
-
-	metas := common.GetSlice(data, "metas")
-	if len(metas) == 0 {
-		return "", nil
-	}
-	meta, _ := metas[0].(map[string]interface{})
-	return common.GetString(meta, "title"), nil
-}
-
 // saveContentToOutputDir validates the target path, enforces overwrite policy,
 // and writes the payload atomically via FileIO.Save.
 func saveContentToOutputDir(fio fileio.FileIO, outputDir, fileName string, payload []byte, overwrite bool) (string, error) {

shortcuts/drive/drive_export_test.go

@@ -81,16 +81,19 @@ func TestValidateDriveExportSpec(t *testing.T) {
 
 func TestDriveExportMarkdownWritesFile(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/docs/v1/content",
+	fetchStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/docs_ai/v1/documents/docx123/fetch",
 		Body: map[string]interface{}{
 			"code": 0,
 			"data": map[string]interface{}{
-				"content": "# hello\n",
+				"document": map[string]interface{}{
+					"content": "# hello\n",
+				},
 			},
 		},
-	})
+	}
+	reg.Register(fetchStub)
 	reg.Register(&httpmock.Stub{
 		Method: "POST",
 		URL:    "/open-apis/drive/v1/metas/batch_query",
@@ -118,6 +121,14 @@ func TestDriveExportMarkdownWritesFile(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 
+	var reqBody map[string]interface{}
+	if err := json.Unmarshal(fetchStub.CapturedBody, &reqBody); err != nil {
+		t.Fatalf("unmarshal docs_ai fetch body: %v", err)
+	}
+	if reqBody["format"] != "markdown" {
+		t.Fatalf("docs_ai fetch body format = %v, want %q", reqBody["format"], "markdown")
+	}
+
 	data, err := os.ReadFile(filepath.Join(tmpDir, "Weekly Notes.md"))
 	if err != nil {
 		t.Fatalf("ReadFile() error: %v", err)
@@ -132,16 +143,19 @@ func TestDriveExportMarkdownWritesFile(t *testing.T) {
 
 func TestDriveExportMarkdownUsesProvidedFileName(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/docs/v1/content",
+	fetchStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/docs_ai/v1/documents/docx123/fetch",
 		Body: map[string]interface{}{
 			"code": 0,
 			"data": map[string]interface{}{
-				"content": "# custom\n",
+				"document": map[string]interface{}{
+					"content": "# custom\n",
+				},
 			},
 		},
-	})
+	}
+	reg.Register(fetchStub)
 
 	tmpDir := t.TempDir()
 	withDriveWorkingDir(t, tmpDir)
@@ -158,6 +172,14 @@ func TestDriveExportMarkdownUsesProvidedFileName(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 
+	var reqBody map[string]interface{}
+	if err := json.Unmarshal(fetchStub.CapturedBody, &reqBody); err != nil {
+		t.Fatalf("unmarshal docs_ai fetch body: %v", err)
+	}
+	if reqBody["format"] != "markdown" {
+		t.Fatalf("docs_ai fetch body format = %v, want %q", reqBody["format"], "markdown")
+	}
+
 	data, err := os.ReadFile(filepath.Join(tmpDir, "custom-notes.md"))
 	if err != nil {
 		t.Fatalf("ReadFile() error: %v", err)
@@ -179,7 +201,7 @@ func TestDriveExportDryRunIncludesLocalFileNameMetadata(t *testing.T) {
 	}{
 		{
 			name:         "markdown",
-			wantURL:      "/open-apis/docs/v1/content",
+			wantURL:      "/open-apis/docs_ai/v1/documents/docx123/fetch",
 			wantFileName: `"file_name": "notes.md"`,
 			args: []string{
 				"+export",
@@ -233,16 +255,19 @@ func TestDriveExportDryRunIncludesLocalFileNameMetadata(t *testing.T) {
 
 func TestDriveExportMarkdownFallsBackToTokenWhenTitleLookupFails(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/docs/v1/content",
+	fetchStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/docs_ai/v1/documents/docx123/fetch",
 		Body: map[string]interface{}{
 			"code": 0,
 			"data": map[string]interface{}{
-				"content": "# fallback\n",
+				"document": map[string]interface{}{
+					"content": "# fallback\n",
+				},
 			},
 		},
-	})
+	}
+	reg.Register(fetchStub)
 	reg.Register(&httpmock.Stub{
 		Method: "POST",
 		URL:    "/open-apis/drive/v1/metas/batch_query",
@@ -267,6 +292,14 @@ func TestDriveExportMarkdownFallsBackToTokenWhenTitleLookupFails(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 
+	var reqBody map[string]interface{}
+	if err := json.Unmarshal(fetchStub.CapturedBody, &reqBody); err != nil {
+		t.Fatalf("unmarshal docs_ai fetch body: %v", err)
+	}
+	if reqBody["format"] != "markdown" {
+		t.Fatalf("docs_ai fetch body format = %v, want %q", reqBody["format"], "markdown")
+	}
+
 	data, err := os.ReadFile(filepath.Join(tmpDir, "docx123.md"))
 	if err != nil {
 		t.Fatalf("ReadFile() error: %v", err)
@@ -279,6 +312,76 @@ func TestDriveExportMarkdownFallsBackToTokenWhenTitleLookupFails(t *testing.T) {
 	}
 }
 
+func TestDriveExportMarkdownRejectsMissingDocumentObject(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/docs_ai/v1/documents/docx123/fetch",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "docx123",
+		"--doc-type", "docx",
+		"--file-extension", "markdown",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error for missing document object, got nil")
+	}
+
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected structured exit error, got %v", err)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "missing document object") {
+		t.Fatalf("error message = %q, want mention of missing document object", exitErr.Detail.Message)
+	}
+}
+
+func TestDriveExportMarkdownRejectsMissingDocumentContent(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/docs_ai/v1/documents/docx123/fetch",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"document": map[string]interface{}{},
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "docx123",
+		"--doc-type", "docx",
+		"--file-extension", "markdown",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error for missing document.content, got nil")
+	}
+
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected structured exit error, got %v", err)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "missing document.content") {
+		t.Fatalf("error message = %q, want mention of missing document.content", exitErr.Detail.Message)
+	}
+}
+
 func TestDriveExportAsyncSuccess(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	reg.Register(&httpmock.Stub{

shortcuts/drive/drive_inspect.go

@@ -0,0 +1,183 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var DriveInspect = common.Shortcut{
+	Service:           "drive",
+	Command:           "+inspect",
+	Description:       "Inspect a Lark document URL to get its type, title, and canonical token (with wiki unwrapping)",
+	Risk:              "read",
+	Scopes:            []string{"drive:drive.metadata:readonly"},
+	ConditionalScopes: []string{"wiki:node:retrieve"},
+	AuthTypes:         []string{"user", "bot"},
+	HasFormat:         true,
+	Flags: []common.Flag{
+		{
+			Name:     "url",
+			Desc:     "Lark/Feishu document URL (docx, doc, sheet, bitable, wiki, file, folder, mindnote, slides)",
+			Required: true,
+		},
+		{
+			Name: "type",
+			Desc: "document type (required when --url is a bare token; auto-detected for URLs)",
+			Enum: []string{"doc", "docx", "sheet", "bitable", "wiki", "file", "folder", "mindnote", "slides"},
+		},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		raw := strings.TrimSpace(runtime.Str("url"))
+		if raw == "" {
+			return output.ErrValidation("--url cannot be empty")
+		}
+
+		_, ok := common.ParseResourceURL(raw)
+		if !ok {
+			// Not a recognized URL pattern.
+			if strings.Contains(raw, "://") {
+				return output.ErrValidation("unsupported --url %q: use a recognized Lark document URL or a bare token with --type", raw)
+			}
+			// Bare token: --type is required.
+			if strings.TrimSpace(runtime.Str("type")) == "" {
+				return output.ErrValidation("--type is required when --url is a bare token (allowed: doc, docx, sheet, bitable, wiki, file, folder, mindnote, slides)")
+			}
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		raw := strings.TrimSpace(runtime.Str("url"))
+		ref, ok := common.ParseResourceURL(raw)
+		if !ok {
+			ref = common.ResourceRef{
+				Type:  strings.TrimSpace(runtime.Str("type")),
+				Token: raw,
+			}
+		}
+
+		dry := common.NewDryRunAPI()
+
+		if ref.Type == "wiki" {
+			dry.Desc("2-step: inspect wiki node, then batch query metadata")
+			dry.GET("/open-apis/wiki/v2/spaces/get_node").
+				Desc("[1] Inspect wiki node to get underlying document").
+				Params(map[string]interface{}{"token": ref.Token})
+			dry.POST("/open-apis/drive/v1/metas/batch_query").
+				Desc("[2] Batch query document metadata (title)").
+				Body(map[string]interface{}{
+					"request_docs": []map[string]interface{}{
+						{"doc_token": "<obj_token from step 1>", "doc_type": "<obj_type from step 1>"},
+					},
+				})
+			return dry
+		}
+
+		dry.Desc("1-step: batch query document metadata")
+		dry.POST("/open-apis/drive/v1/metas/batch_query").
+			Body(map[string]interface{}{
+				"request_docs": []map[string]interface{}{
+					{"doc_token": ref.Token, "doc_type": ref.Type},
+				},
+			})
+		return dry
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		raw := strings.TrimSpace(runtime.Str("url"))
+
+		// Step 1: Parse URL to extract {type, token}.
+		ref, ok := common.ParseResourceURL(raw)
+		if !ok {
+			// Bare token: use --type.
+			ref = common.ResourceRef{
+				Type:  strings.TrimSpace(runtime.Str("type")),
+				Token: raw,
+			}
+		}
+
+		inputURL := raw
+		docType := ref.Type
+		docToken := ref.Token
+
+		var wikiNode map[string]interface{}
+
+		// Step 2: If type is "wiki", unwrap via get_node API.
+		if docType == "wiki" {
+			fmt.Fprintf(runtime.IO().ErrOut, "Inspecting wiki node: %s\n", common.MaskToken(docToken))
+			data, err := runtime.CallAPI(
+				"GET",
+				"/open-apis/wiki/v2/spaces/get_node",
+				map[string]interface{}{"token": docToken},
+				nil,
+			)
+			if err != nil {
+				return err
+			}
+
+			node := common.GetMap(data, "node")
+			objType := common.GetString(node, "obj_type")
+			objToken := common.GetString(node, "obj_token")
+			spaceID := common.GetString(node, "space_id")
+			nodeToken := common.GetString(node, "node_token")
+
+			if objType == "" || objToken == "" {
+				return output.Errorf(output.ExitAPI, "api_error", "wiki get_node returned incomplete node data (obj_type=%q, obj_token=%q)", objType, objToken)
+			}
+
+			wikiNode = map[string]interface{}{
+				"space_id":   spaceID,
+				"node_token": nodeToken,
+				"obj_token":  objToken,
+				"obj_type":   objType,
+			}
+
+			docType = objType
+			docToken = objToken
+
+			fmt.Fprintf(runtime.IO().ErrOut, "Wiki unwrapped to %s: %s\n", docType, common.MaskToken(docToken))
+		}
+
+		// Step 3: Call batch_query to verify and get title.
+		title, err := common.FetchDriveMetaTitle(runtime, docToken, docType)
+		if err != nil {
+			return err
+		}
+
+		// Step 4: Build the resolved URL.
+		resolvedURL := common.BuildResourceURL(runtime.Config.Brand, docType, docToken)
+
+		// Step 5: Build output.
+		result := map[string]interface{}{
+			"input_url": inputURL,
+			"type":      docType,
+			"title":     title,
+			"token":     docToken,
+			"url":       resolvedURL,
+		}
+		if wikiNode != nil {
+			result["wiki_node"] = wikiNode
+		}
+
+		runtime.OutFormat(result, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Type:  %s\n", docType)
+			if title != "" {
+				fmt.Fprintf(w, "Title: %s\n", title)
+			}
+			fmt.Fprintf(w, "Token: %s\n", docToken)
+			if resolvedURL != "" {
+				fmt.Fprintf(w, "URL:   %s\n", resolvedURL)
+			}
+			if wikiNode != nil {
+				fmt.Fprintf(w, "Wiki:  space_id=%s, node_token=%s\n", wikiNode["space_id"], wikiNode["node_token"])
+			}
+		})
+		return nil
+	},
+}

shortcuts/drive/drive_inspect_test.go

@@ -0,0 +1,466 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// --- Validate tests ---
+
+func TestDriveInspectValidate_EmptyURL(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	err := DriveInspect.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected error for empty --url, got nil")
+	}
+}
+
+func TestDriveInspectValidate_UnsupportedURL(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "https://google.com/some/page")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	err := DriveInspect.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected error for unsupported URL, got nil")
+	}
+}
+
+func TestDriveInspectValidate_NonLarkHostWithLarkPath(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "https://google.com/docx/doxcnLooksValid")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	err := DriveInspect.Validate(context.Background(), runtime)
+	if err != nil {
+		t.Fatalf("expected no error for non-Lark host with Lark-like path (host validation removed), got %v", err)
+	}
+}
+
+func TestDriveInspectValidate_BareTokenWithoutType(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "doxcnBareToken")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	err := DriveInspect.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected error for bare token without --type, got nil")
+	}
+}
+
+func TestDriveInspectValidate_BareTokenWithType(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "doxcnBareToken")
+	_ = cmd.Flags().Set("type", "docx")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	err := DriveInspect.Validate(context.Background(), runtime)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+}
+
+func TestDriveInspectValidate_ValidDocxURL(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "https://xxx.feishu.cn/docx/doxcnABC")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	err := DriveInspect.Validate(context.Background(), runtime)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+}
+
+func TestDriveInspectValidate_ValidWikiURL(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "https://xxx.feishu.cn/wiki/wikcnABC")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	err := DriveInspect.Validate(context.Background(), runtime)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+}
+
+// --- DryRun tests ---
+
+func TestDriveInspectDryRun_DocxURL(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "https://xxx.feishu.cn/docx/doxcnABC")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	dry := DriveInspect.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			URL    string                 `json:"url"`
+			Method string                 `json:"method"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run: %v", err)
+	}
+	if len(got.API) != 1 {
+		t.Fatalf("expected 1 API step, got %d", len(got.API))
+	}
+	if got.API[0].URL != "/open-apis/drive/v1/metas/batch_query" {
+		t.Errorf("API URL = %q, want /open-apis/drive/v1/metas/batch_query", got.API[0].URL)
+	}
+	// Verify body contains request_docs with the correct token and type.
+	reqDocs, ok := got.API[0].Body["request_docs"].([]interface{})
+	if !ok || len(reqDocs) != 1 {
+		t.Fatalf("expected request_docs with 1 entry, got %v", got.API[0].Body["request_docs"])
+	}
+	doc, _ := reqDocs[0].(map[string]interface{})
+	if doc["doc_token"] != "doxcnABC" {
+		t.Errorf("doc_token = %v, want doxcnABC", doc["doc_token"])
+	}
+	if doc["doc_type"] != "docx" {
+		t.Errorf("doc_type = %v, want docx", doc["doc_type"])
+	}
+}
+
+func TestDriveInspectDryRun_WikiURL(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "https://xxx.feishu.cn/wiki/wikcnABC")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	dry := DriveInspect.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run: %v", err)
+	}
+	if len(got.API) != 2 {
+		t.Fatalf("expected 2 API steps, got %d", len(got.API))
+	}
+	if got.API[0].URL != "/open-apis/wiki/v2/spaces/get_node" {
+		t.Errorf("step 1 URL = %q, want /open-apis/wiki/v2/spaces/get_node", got.API[0].URL)
+	}
+	// Verify step 1 params contain the wiki token.
+	if got.API[0].Params["token"] != "wikcnABC" {
+		t.Errorf("step 1 params.token = %v, want wikcnABC", got.API[0].Params["token"])
+	}
+	if got.API[1].URL != "/open-apis/drive/v1/metas/batch_query" {
+		t.Errorf("step 2 URL = %q, want /open-apis/drive/v1/metas/batch_query", got.API[1].URL)
+	}
+	// Verify step 2 body contains request_docs placeholder.
+	if got.API[1].Body["request_docs"] == nil {
+		t.Error("step 2 body should contain request_docs")
+	}
+}
+
+func TestDriveInspectDryRun_BareTokenWithType(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "doxcnBareToken")
+	_ = cmd.Flags().Set("type", "docx")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	dry := DriveInspect.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			URL string `json:"url"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run: %v", err)
+	}
+	if len(got.API) != 1 {
+		t.Fatalf("expected 1 API step, got %d", len(got.API))
+	}
+}
+
+// --- Execute tests ---
+
+func TestDriveInspectExecute_DocxURL(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := driveTestConfig()
+	f, stdout, _, reg := cmdutil.TestFactory(t, cfg)
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"metas": []map[string]interface{}{
+					{"doc_token": "doxcnABC", "doc_type": "docx", "title": "Test Doc"},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveInspect, []string{
+		"+inspect",
+		"--url", "https://xxx.feishu.cn/docx/doxcnABC",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if data["type"] != "docx" {
+		t.Errorf("type = %v, want docx", data["type"])
+	}
+	if data["token"] != "doxcnABC" {
+		t.Errorf("token = %v, want doxcnABC", data["token"])
+	}
+	if data["title"] != "Test Doc" {
+		t.Errorf("title = %v, want Test Doc", data["title"])
+	}
+	if _, ok := data["wiki_node"]; ok {
+		t.Error("wiki_node should not be present for non-wiki URL")
+	}
+}
+
+func TestDriveInspectExecute_WikiURL(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := driveTestConfig()
+	f, stdout, _, reg := cmdutil.TestFactory(t, cfg)
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":   "docx",
+					"obj_token":  "doxcnUnwrapped",
+					"space_id":   "space123",
+					"node_token": "wikcnNodeToken",
+					"title":      "Wiki Doc",
+					"node_type":  "origin",
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"metas": []map[string]interface{}{
+					{"doc_token": "doxcnUnwrapped", "doc_type": "docx", "title": "Wiki Doc"},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveInspect, []string{
+		"+inspect",
+		"--url", "https://xxx.feishu.cn/wiki/wikcnABC",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if data["type"] != "docx" {
+		t.Errorf("type = %v, want docx (unwrapped from wiki)", data["type"])
+	}
+	if data["token"] != "doxcnUnwrapped" {
+		t.Errorf("token = %v, want doxcnUnwrapped", data["token"])
+	}
+	if data["title"] != "Wiki Doc" {
+		t.Errorf("title = %v, want Wiki Doc", data["title"])
+	}
+	wikiNode, ok := data["wiki_node"].(map[string]interface{})
+	if !ok {
+		t.Fatal("wiki_node should be present for wiki URL")
+	}
+	if wikiNode["space_id"] != "space123" {
+		t.Errorf("wiki_node.space_id = %v, want space123", wikiNode["space_id"])
+	}
+}
+
+func TestDriveInspectExecute_WikiGetNodeIncompleteData(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := driveTestConfig()
+	f, stdout, _, reg := cmdutil.TestFactory(t, cfg)
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "",
+					"obj_token": "",
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveInspect, []string{
+		"+inspect",
+		"--url", "https://xxx.feishu.cn/wiki/wikcnABC",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected error for incomplete wiki node data, got nil")
+	}
+}
+
+func TestDriveInspectExecute_BareTokenWithType(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := driveTestConfig()
+	f, stdout, _, reg := cmdutil.TestFactory(t, cfg)
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"metas": []map[string]interface{}{
+					{"doc_token": "doxcnBare", "doc_type": "docx", "title": "Bare Doc"},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveInspect, []string{
+		"+inspect",
+		"--url", "doxcnBare",
+		"--type", "docx",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if data["type"] != "docx" {
+		t.Errorf("type = %v, want docx", data["type"])
+	}
+	if data["token"] != "doxcnBare" {
+		t.Errorf("token = %v, want doxcnBare", data["token"])
+	}
+}
+
+func TestDriveInspectExecute_BatchQueryError(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := driveTestConfig()
+	f, stdout, _, reg := cmdutil.TestFactory(t, cfg)
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 99991668,
+			"msg":  "permission denied",
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveInspect, []string{
+		"+inspect",
+		"--url", "https://xxx.feishu.cn/docx/doxcnABC",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected error for batch_query failure, got nil")
+	}
+}
+
+func TestDriveInspectExecute_PrettyFormat(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := driveTestConfig()
+	f, stdout, _, reg := cmdutil.TestFactory(t, cfg)
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"metas": []map[string]interface{}{
+					{"doc_token": "doxcnABC", "doc_type": "docx", "title": "Test Doc"},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveInspect, []string{
+		"+inspect",
+		"--url", "https://xxx.feishu.cn/docx/doxcnABC",
+		"--format", "pretty",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Pretty format outputs to stdout as text, not JSON envelope.
+	// Just verify it didn't error.
+	_ = stdout
+}

shortcuts/drive/drive_task_result.go

@@ -20,7 +20,7 @@ import (
 var DriveTaskResult = common.Shortcut{
 	Service:     "drive",
 	Command:     "+task_result",
-	Description: "Poll async task result for import, export, drive move/delete, wiki move, or wiki delete-space operations",
+	Description: "Poll async task result for import, export, drive move/delete, wiki move, wiki delete-space, or wiki delete-node operations",
 	Risk:        "read",
 	// This shortcut multiplexes multiple backend APIs with different scope
 	// requirements, so scenario-specific prechecks are handled in Validate.
@@ -28,8 +28,8 @@ var DriveTaskResult = common.Shortcut{
 	AuthTypes: []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "ticket", Desc: "async task ticket (for import/export tasks)", Required: false},
-		{Name: "task-id", Desc: "async task ID (for drive task_check, wiki_move, or wiki_delete_space tasks)", Required: false},
-		{Name: "scenario", Desc: "task scenario: import, export, task_check, wiki_move, or wiki_delete_space", Required: true},
+		{Name: "task-id", Desc: "async task ID (for drive task_check, wiki_move, wiki_delete_space, or wiki_delete_node tasks)", Required: false},
+		{Name: "scenario", Desc: "task scenario: import, export, task_check, wiki_move, wiki_delete_space, or wiki_delete_node", Required: true},
 		{Name: "file-token", Desc: "source document token used for export task status lookup", Required: false},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -40,9 +40,10 @@ var DriveTaskResult = common.Shortcut{
 			"task_check":        true,
 			"wiki_move":         true,
 			"wiki_delete_space": true,
+			"wiki_delete_node":  true,
 		}
 		if !validScenarios[scenario] {
-			return output.ErrValidation("unsupported scenario: %s. Supported scenarios: import, export, task_check, wiki_move, wiki_delete_space", scenario)
+			return output.ErrValidation("unsupported scenario: %s. Supported scenarios: import, export, task_check, wiki_move, wiki_delete_space, wiki_delete_node", scenario)
 		}
 
 		// Validate required params based on scenario
@@ -54,7 +55,7 @@ var DriveTaskResult = common.Shortcut{
 			if err := validate.ResourceName(runtime.Str("ticket"), "--ticket"); err != nil {
 				return output.ErrValidation("%s", err)
 			}
-		case "task_check", "wiki_move", "wiki_delete_space":
+		case "task_check", "wiki_move", "wiki_delete_space", "wiki_delete_node":
 			if runtime.Str("task-id") == "" {
 				return output.ErrValidation("--task-id is required for %s scenario", scenario)
 			}
@@ -108,6 +109,11 @@ var DriveTaskResult = common.Shortcut{
 				Desc("[1] Query wiki delete-space task result").
 				Set("task_id", taskID).
 				Params(map[string]interface{}{"task_type": "delete_space"})
+		case "wiki_delete_node":
+			dry.GET("/open-apis/wiki/v2/tasks/:task_id").
+				Desc("[1] Query wiki delete-node task result").
+				Set("task_id", taskID).
+				Params(map[string]interface{}{"task_type": "delete_node"})
 		}
 
 		return dry
@@ -136,6 +142,8 @@ var DriveTaskResult = common.Shortcut{
 			result, err = queryWikiMoveTask(runtime, taskID)
 		case "wiki_delete_space":
 			result, err = queryWikiDeleteSpaceTask(runtime, taskID)
+		case "wiki_delete_node":
+			result, err = queryWikiDeleteNodeTask(runtime, taskID)
 		}
 
 		if err != nil {
@@ -236,7 +244,7 @@ func validateDriveTaskResultScopes(ctx context.Context, runtime *common.RuntimeC
 	switch scenario {
 	case "import", "export", "task_check":
 		required = []string{"drive:drive.metadata:readonly"}
-	case "wiki_move", "wiki_delete_space":
+	case "wiki_move", "wiki_delete_space", "wiki_delete_node":
 		required = []string{"wiki:space:read"}
 	}
 
@@ -540,3 +548,64 @@ func queryWikiDeleteSpaceTask(runtime *common.RuntimeContext, taskID string) (ma
 		"status_msg": label,
 	}, nil
 }
+
+// queryWikiDeleteNodeTask returns the normalized status of an async wiki
+// delete-node task. For historical reasons the gateway stashes delete-node
+// status under the generic `simple_task_result` key (NOT `delete_node_result`),
+// and that object only carries `status` — there is no `status_msg`, so the
+// label falls back to the status code. Mirrors queryWikiDeleteSpaceTask;
+// intentionally duplicated here (rather than importing the wiki package) to
+// keep drive from depending on shortcuts/wiki.
+func queryWikiDeleteNodeTask(runtime *common.RuntimeContext, taskID string) (map[string]interface{}, error) {
+	if err := validate.ResourceName(taskID, "--task-id"); err != nil {
+		return nil, output.ErrValidation("%s", err)
+	}
+
+	data, err := runtime.CallAPI(
+		"GET",
+		fmt.Sprintf("/open-apis/wiki/v2/tasks/%s", validate.EncodePathSegment(taskID)),
+		map[string]interface{}{"task_type": "delete_node"},
+		nil,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	task := common.GetMap(data, "task")
+	if task == nil {
+		return nil, output.Errorf(output.ExitAPI, "api_error", "wiki task response missing task")
+	}
+
+	resolvedTaskID := common.GetString(task, "task_id")
+	if resolvedTaskID == "" {
+		resolvedTaskID = taskID
+	}
+
+	result := common.GetMap(task, "simple_task_result")
+	var status string
+	if result != nil {
+		status = common.GetString(result, "status")
+	}
+
+	// Keep in sync with wiki.parseWikiAsyncTaskStatus / wikiAsyncTaskStatus
+	// classification (intentionally duplicated to avoid a drive→wiki import —
+	// see the doc comment above). If the success/failed/processing rules change
+	// there, mirror the change here.
+	lowered := strings.ToLower(strings.TrimSpace(status))
+	ready := lowered == "success"
+	failed := lowered == "failure" || lowered == "failed"
+
+	resolvedStatus := strings.TrimSpace(status)
+	if resolvedStatus == "" {
+		resolvedStatus = "processing"
+	}
+
+	return map[string]interface{}{
+		"scenario":   "wiki_delete_node",
+		"task_id":    resolvedTaskID,
+		"ready":      ready,
+		"failed":     failed,
+		"status":     resolvedStatus,
+		"status_msg": resolvedStatus,
+	}, nil
+}

shortcuts/drive/drive_task_result_test.go

@@ -417,10 +417,10 @@ func TestDriveTaskResultWikiMoveIncludesFlattenedNodeFields(t *testing.T) {
 func TestValidateDriveTaskResultScopesWikiScenariosRequireWikiScope(t *testing.T) {
 	t.Parallel()
 
-	// wiki_move and wiki_delete_space both read wiki task status, so both must
-	// require wiki:space:read. A single table keeps this invariant explicit
-	// without duplicating near-identical test functions per scenario.
-	for _, scenario := range []string{"wiki_move", "wiki_delete_space"} {
+	// wiki_move, wiki_delete_space and wiki_delete_node all read wiki task
+	// status, so all must require wiki:space:read. A single table keeps this
+	// invariant explicit without duplicating near-identical test functions.
+	for _, scenario := range []string{"wiki_move", "wiki_delete_space", "wiki_delete_node"} {
 		t.Run(scenario+"/rejects missing scope", func(t *testing.T) {
 			t.Parallel()
 			runtime := newDriveTaskResultRuntimeWithScopes(t, core.AsUser, "drive:drive.metadata:readonly")
@@ -518,6 +518,105 @@ func TestDriveTaskResultWikiDeleteSpaceSuccess(t *testing.T) {
 	}
 }
 
+func TestDriveTaskResultDryRunWikiDeleteNodeIncludesTaskTypeParam(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +task_result"}
+	cmd.Flags().String("scenario", "", "")
+	cmd.Flags().String("ticket", "", "")
+	cmd.Flags().String("task-id", "", "")
+	cmd.Flags().String("file-token", "", "")
+	if err := cmd.Flags().Set("scenario", "wiki_delete_node"); err != nil {
+		t.Fatalf("set --scenario: %v", err)
+	}
+	if err := cmd.Flags().Set("task-id", "task_del_node_1"); err != nil {
+		t.Fatalf("set --task-id: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+	dry := DriveTaskResult.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if len(got.API) != 1 {
+		t.Fatalf("expected 1 API call, got %d", len(got.API))
+	}
+	if got.API[0].Params["task_type"] != "delete_node" {
+		t.Fatalf("wiki delete-node params = %#v, want task_type=delete_node", got.API[0].Params)
+	}
+}
+
+func TestDriveTaskResultWikiDeleteNodeSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/tasks/task_del_node_1",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"task": map[string]interface{}{
+					// Gateway returns delete-node status under the generic
+					// simple_task_result key (NOT delete_node_result), and it
+					// carries only `status` (no status_msg).
+					"simple_task_result": map[string]interface{}{
+						"status": "success",
+					},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveTaskResult, []string{
+		"+task_result",
+		"--scenario", "wiki_delete_node",
+		"--task-id", "task_del_node_1",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if data["scenario"] != "wiki_delete_node" || data["task_id"] != "task_del_node_1" {
+		t.Fatalf("unexpected wiki_delete_node envelope: %#v", data)
+	}
+	if data["ready"] != true || data["failed"] != false || data["status"] != "success" {
+		t.Fatalf("unexpected readiness fields: %#v", data)
+	}
+	// simple_task_result has no status_msg; label must fall back to status.
+	if data["status_msg"] != "success" {
+		t.Fatalf("status_msg = %#v, want fallback to status", data["status_msg"])
+	}
+}
+
+func TestDriveTaskResultRejectsUnknownScenarioListsWikiDeleteNode(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+
+	err := mountAndRunDrive(t, DriveTaskResult, []string{
+		"+task_result",
+		"--scenario", "bogus",
+		"--task-id", "task_x",
+		"--as", "user",
+	}, f, stdout)
+	if err == nil || !strings.Contains(err.Error(), "wiki_delete_node") {
+		t.Fatalf("expected unsupported-scenario error listing wiki_delete_node, got %v", err)
+	}
+}
+
 func TestValidateDriveTaskResultScopesDriveScenariosRequireDriveScope(t *testing.T) {
 	t.Parallel()
 

shortcuts/drive/shortcuts.go

@@ -29,5 +29,6 @@ func Shortcuts() []common.Shortcut {
 		DriveTaskResult,
 		DriveApplyPermission,
 		DriveSearch,
+		DriveInspect,
 	}
 }

shortcuts/drive/shortcuts_test.go

@@ -32,6 +32,7 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+task_result",
 		"+apply-permission",
 		"+search",
+		"+inspect",
 	}
 
 	if len(got) != len(want) {

shortcuts/mail/draft/model.go

@@ -166,6 +166,7 @@ type DraftProjection struct {
 	LargeAttachmentsSummary []LargeAttachmentSummary `json:"large_attachments_summary,omitempty"`
 	InlineSummary           []PartSummary            `json:"inline_summary,omitempty"`
 	Warnings                []string                 `json:"warnings,omitempty"`
+	Priority                string                   `json:"priority"`
 }
 
 type Patch struct {

shortcuts/mail/draft/projection.go

@@ -140,9 +140,53 @@ func Project(snapshot *DraftSnapshot) DraftProjection {
 
 	proj.LargeAttachmentsSummary = projectLargeAttachments(snapshot.Headers, htmlBody)
 
+	proj.Priority = parsePriorityFromHeaders(snapshot.Headers)
+
 	return proj
 }
 
+// parsePriorityFromHeaders derives the read-side priority projection from
+// EML headers. It mirrors the write-side helper helpers.go:parsePriority
+// (which translates --set-priority high|normal|low into set_header /
+// remove_header X-Cli-Priority ops). Lookup order is case-insensitive
+// via headerValue:
+//  1. X-Cli-Priority (CLI/OAPI-specific header recognised by
+//     mail-data-access headersToPbBodyExtra)
+//  2. X-Priority (RFC standard, fallback for IMAP-回灌 historical drafts)
+//
+// When neither header is present (including after the write-side translates
+// --set-priority normal into remove_header X-Cli-Priority), this returns
+// "normal" — absence of a priority header is the standard email convention
+// for normal priority. Agents cannot distinguish "explicitly normal" from
+// "never set" — known limitation.
+func parsePriorityFromHeaders(headers []Header) string {
+	if v := headerValue(headers, "X-Cli-Priority"); v != "" {
+		return mapPriorityValue(v)
+	}
+	if v := headerValue(headers, "X-Priority"); v != "" {
+		return mapPriorityValue(v)
+	}
+	return "normal"
+}
+
+// mapPriorityValue normalises a raw priority header value to the projection
+// vocabulary {"high","normal","low","unknown"}. The accepted input table is
+// kept in sync with backend gopkg/mail_priority.PriorityValueToType so that
+// CLI read-side projection observes the same set of values the server
+// recognises on write.
+func mapPriorityValue(raw string) string {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "1", "high", "1 (highest)":
+		return "high"
+	case "3", "normal", "3 (normal)":
+		return "normal"
+	case "5", "low", "5 (lowest)":
+		return "low"
+	default:
+		return "unknown"
+	}
+}
+
 // projectLargeAttachments extracts large attachment info from the draft.
 // It first tries the server-format header (X-Lark-Large-Attachment) which
 // carries filename and size directly. Falls back to merging CLI-format

shortcuts/mail/draft/projection_test.go

@@ -178,6 +178,170 @@ func TestSplitAtQuoteFalsePositivePlainText(t *testing.T) {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// Priority projection (X-Cli-Priority primary, X-Priority fallback)
+// ---------------------------------------------------------------------------
+
+func TestProjectPriorityXCliPriorityHigh(t *testing.T) {
+	snapshot := mustParseFixtureDraft(t, `Subject: priority high
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+X-Cli-Priority: 1
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+hello
+`)
+	proj := Project(snapshot)
+	if proj.Priority != "high" {
+		t.Fatalf("Priority = %q, want %q", proj.Priority, "high")
+	}
+}
+
+func TestProjectPriorityFallbackXPriorityLow(t *testing.T) {
+	// Only the standard X-Priority header is present (e.g. an IMAP-回灌
+	// historical draft). The fallback path should kick in.
+	snapshot := mustParseFixtureDraft(t, `Subject: priority low (fallback)
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+X-Priority: 5
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+hello
+`)
+	proj := Project(snapshot)
+	if proj.Priority != "low" {
+		t.Fatalf("Priority = %q, want %q", proj.Priority, "low")
+	}
+}
+
+func TestProjectPriorityBothAbsentNormal(t *testing.T) {
+	// Neither header is present — default priority is normal.
+	snapshot := mustParseFixtureDraft(t, `Subject: no priority
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+hello
+`)
+	proj := Project(snapshot)
+	if proj.Priority != "normal" {
+		t.Fatalf("Priority = %q, want %q", proj.Priority, "normal")
+	}
+}
+
+func TestProjectPriorityXCliPriorityOutlookStyleHigh(t *testing.T) {
+	// X-Cli-Priority set to the Outlook-style string "high" (any case).
+	snapshot := mustParseFixtureDraft(t, `Subject: priority high (string)
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+X-Cli-Priority: High
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+hello
+`)
+	proj := Project(snapshot)
+	if proj.Priority != "high" {
+		t.Fatalf("Priority = %q, want %q", proj.Priority, "high")
+	}
+}
+
+func TestProjectPriorityUnmappedValueUnknown(t *testing.T) {
+	// Value outside the recognised mapping table (e.g. "urgent") falls
+	// back to "unknown".
+	snapshot := mustParseFixtureDraft(t, `Subject: priority urgent
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+X-Cli-Priority: urgent
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+hello
+`)
+	proj := Project(snapshot)
+	if proj.Priority != "unknown" {
+		t.Fatalf("Priority = %q, want %q", proj.Priority, "unknown")
+	}
+}
+
+func TestProjectPriorityXCliPriorityWinsOverXPriority(t *testing.T) {
+	// X-Cli-Priority must take precedence over X-Priority when both are
+	// set (defensive: agent or upstream may write both).
+	snapshot := mustParseFixtureDraft(t, `Subject: both headers
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+X-Cli-Priority: 1
+X-Priority: 5
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+hello
+`)
+	proj := Project(snapshot)
+	if proj.Priority != "high" {
+		t.Fatalf("Priority = %q, want %q (X-Cli-Priority must win)", proj.Priority, "high")
+	}
+}
+
+func TestProjectPriorityNormalThree(t *testing.T) {
+	// X-Cli-Priority=3 → "normal" (rare in CLI write path since
+	// `--set-priority normal` actually removes the header, but this case
+	// covers e.g. a draft set by another OAPI client that wrote 3).
+	snapshot := mustParseFixtureDraft(t, `Subject: priority three
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+X-Cli-Priority: 3
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+hello
+`)
+	proj := Project(snapshot)
+	if proj.Priority != "normal" {
+		t.Fatalf("Priority = %q, want %q", proj.Priority, "normal")
+	}
+}
+
+func TestProjectPriorityFallbackXPriorityNormalString(t *testing.T) {
+	// IMAP-回灌 / external client writes the RFC-standard `X-Priority: Normal`
+	// string. The fallback path must project this as "normal" — symmetric with
+	// how `X-Priority: High` / `Low` are already handled.
+	snapshot := mustParseFixtureDraft(t, `Subject: priority normal (fallback)
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+X-Priority: Normal
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+hello
+`)
+	proj := Project(snapshot)
+	if proj.Priority != "normal" {
+		t.Fatalf("Priority = %q, want %q", proj.Priority, "normal")
+	}
+}
+
+func TestProjectPriorityOutlookStyleThreeNormal(t *testing.T) {
+	// Outlook-style `3 (Normal)` parenthesised form — symmetric with the
+	// already-supported `1 (Highest)` / `5 (Lowest)`.
+	snapshot := mustParseFixtureDraft(t, `Subject: priority three (normal)
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+X-Priority: 3 (Normal)
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+hello
+`)
+	proj := Project(snapshot)
+	if proj.Priority != "normal" {
+		t.Fatalf("Priority = %q, want %q", proj.Priority, "normal")
+	}
+}
+
 func TestParseMissingInlineCIDReportedAsProjectionWarning(t *testing.T) {
 	// Missing CID references should NOT prevent parsing; they are reported
 	// as warnings in Project() instead.

shortcuts/mail/helpers.go

@@ -2602,3 +2602,14 @@ func buildCalendarBody(runtime *common.RuntimeContext, senderEmail string, toAdd
 		senderEmail, toAddrs, ccAddrs,
 	)
 }
+
+// validateBotMailboxNotMe rejects the combination of bot identity with --mailbox me.
+// bot uses tenant access token; "me" cannot be resolved to a user mailbox under TAT.
+func validateBotMailboxNotMe(runtime *common.RuntimeContext) error {
+	if runtime.IsBot() && runtime.Str("mailbox") == "me" {
+		return output.ErrValidation(
+			"--as bot does not support --mailbox me: bot identity uses a tenant token and cannot resolve \"me\" to a user mailbox; " +
+				"pass an explicit email address, e.g. --mailbox alice@example.com")
+	}
+	return nil
+}

shortcuts/mail/mail_draft_edit.go

@@ -293,6 +293,9 @@ func executeDraftInspect(runtime *common.RuntimeContext, mailboxID, draftID stri
 		if len(projection.Warnings) > 0 {
 			fmt.Fprintf(w, "warnings: %s\n", sanitizeForTerminal(strings.Join(projection.Warnings, "; ")))
 		}
+		if projection.Priority != "" {
+			fmt.Fprintf(w, "priority: %s\n", sanitizeForTerminal(projection.Priority))
+		}
 	})
 	return nil
 }
@@ -553,6 +556,7 @@ func buildDraftEditPatchTemplate() map[string]interface{} {
 			"`add_inline`/`replace_inline`/`remove_inline` are for CID-based inline images",
 			"`replace_inline` keeps the original filename and content_type when those fields are omitted",
 			"protected headers require `allow_protected_header_edits=true`",
+			"--set-priority high|normal|low controls draft priority via X-Cli-Priority header (CLI/OAPI specific). high → set_header X-Cli-Priority=1; low → set_header X-Cli-Priority=5; normal → remove_header X-Cli-Priority. Backend mail-data-access headersToPbBodyExtra recognizes X-Cli-Priority but not standard X-Priority/Importance for OAPI flow.",
 		},
 		"command_example":    "lark-cli mail +draft-edit --print-patch-template",
 		"patch_file_example": "lark-cli mail +draft-edit --draft-id d_xxx --patch-file ./patch.json",

shortcuts/mail/mail_message.go

@@ -26,6 +26,9 @@ var MailMessage = common.Shortcut{
 		{Name: "html", Type: "bool", Default: "true", Desc: "Whether to return HTML body (false returns plain text only to save bandwidth)"},
 		{Name: "print-output-schema", Type: "bool", Desc: "Print output field reference (run this first to learn field names before parsing output)"},
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateBotMailboxNotMe(runtime)
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		mailboxID := resolveMailboxID(runtime)
 		messageID := runtime.Str("message-id")

shortcuts/mail/mail_messages.go

@@ -34,6 +34,9 @@ var MailMessages = common.Shortcut{
 		{Name: "html", Type: "bool", Default: "true", Desc: "Whether to return HTML body (false returns plain text only to save bandwidth)"},
 		{Name: "print-output-schema", Type: "bool", Desc: "Print output field reference (run this first to learn field names before parsing output)"},
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateBotMailboxNotMe(runtime)
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		mailboxID := resolveMailboxID(runtime)
 		messageIDs := splitByComma(runtime.Str("message-ids"))

shortcuts/mail/mail_shortcut_validation_test.go

@@ -0,0 +1,130 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/output"
+)
+
+// assertValidationError fails the test unless err is a *output.ExitError with
+// ExitValidation code whose message contains wantSubstr.
+func assertValidationError(t *testing.T, err error, wantSubstr string) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected a validation error, got nil")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("expected exit code %d (ExitValidation), got %d", output.ExitValidation, exitErr.Code)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "validation" {
+		t.Errorf("expected detail type \"validation\", got %+v", exitErr.Detail)
+	}
+	if wantSubstr != "" && !strings.Contains(exitErr.Error(), wantSubstr) {
+		t.Errorf("expected error message to contain %q, got: %v", wantSubstr, exitErr.Error())
+	}
+}
+
+// assertValidatePasses fails the test if err is a validation error; other
+// errors (e.g. API call failures from missing tokens) are acceptable because
+// we only care that the Validate callback passed.
+func assertValidatePasses(t *testing.T, err error) {
+	t.Helper()
+	if err == nil {
+		return
+	}
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) && exitErr.Code == output.ExitValidation {
+		t.Fatalf("Validate callback should have passed but returned validation error: %v", exitErr)
+	}
+	// Non-validation errors (auth/API failures) are expected without HTTP mocks.
+}
+
+// TC-1: +message --as bot --mailbox me → ErrValidation
+func TestMailMessageBotMailboxMeReturnsValidationError(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailMessage, []string{
+		"+message", "--as", "bot", "--mailbox", "me", "--message-id", "msg_xxx",
+	}, f, stdout)
+	assertValidationError(t, err, "does not support --mailbox me")
+}
+
+// TC-2: +message --as bot --mailbox explicit → Validate passes
+func TestMailMessageBotExplicitMailboxPassesValidation(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailMessage, []string{
+		"+message", "--as", "bot", "--mailbox", "alice@example.com", "--message-id", "msg_xxx",
+	}, f, stdout)
+	assertValidatePasses(t, err)
+}
+
+// TC-3: +message --as user --mailbox me → Validate passes
+func TestMailMessageUserMailboxMePassesValidation(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailMessage, []string{
+		"+message", "--as", "user", "--mailbox", "me", "--message-id", "msg_xxx",
+	}, f, stdout)
+	assertValidatePasses(t, err)
+}
+
+// TC-4: +messages --as bot (default mailbox=me) → ErrValidation
+func TestMailMessagesBotDefaultMailboxMeReturnsValidationError(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailMessages, []string{
+		"+messages", "--as", "bot", "--message-ids", "msg_xxx",
+	}, f, stdout)
+	assertValidationError(t, err, "does not support --mailbox me")
+}
+
+// TC-5: +messages --as bot --mailbox explicit → Validate passes
+func TestMailMessagesBotExplicitMailboxPassesValidation(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailMessages, []string{
+		"+messages", "--as", "bot", "--mailbox", "alice@example.com", "--message-ids", "msg_xxx",
+	}, f, stdout)
+	assertValidatePasses(t, err)
+}
+
+// TC-6: +thread --as bot (default mailbox=me) → ErrValidation
+func TestMailThreadBotDefaultMailboxMeReturnsValidationError(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailThread, []string{
+		"+thread", "--as", "bot", "--thread-id", "thread_xxx",
+	}, f, stdout)
+	assertValidationError(t, err, "does not support --mailbox me")
+}
+
+// TC-7: +thread --as bot --mailbox explicit → Validate passes
+func TestMailThreadBotExplicitMailboxPassesValidation(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailThread, []string{
+		"+thread", "--as", "bot", "--mailbox", "alice@example.com", "--thread-id", "thread_xxx",
+	}, f, stdout)
+	assertValidatePasses(t, err)
+}
+
+// TC-8: +triage --as bot (default mailbox=me) → ErrValidation
+func TestMailTriageBotDefaultMailboxMeReturnsValidationError(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailTriage, []string{
+		"+triage", "--as", "bot",
+	}, f, stdout)
+	assertValidationError(t, err, "does not support --mailbox me")
+}
+
+// TC-9: +triage --as bot --mailbox explicit → Validate passes
+func TestMailTriageBotExplicitMailboxPassesValidation(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailTriage, []string{
+		"+triage", "--as", "bot", "--mailbox", "alice@example.com",
+	}, f, stdout)
+	assertValidatePasses(t, err)
+}

shortcuts/mail/mail_template_create.go

@@ -75,6 +75,9 @@ var MailTemplateCreate = common.Shortcut{
 		return api
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := validateBotMailboxNotMe(runtime); err != nil {
+			return err
+		}
 		if strings.TrimSpace(runtime.Str("name")) == "" {
 			return output.ErrValidation("--name is required")
 		}

shortcuts/mail/mail_template_update.go

@@ -86,6 +86,9 @@ var MailTemplateUpdate = common.Shortcut{
 		if runtime.Bool("print-patch-template") {
 			return nil
 		}
+		if err := validateBotMailboxNotMe(runtime); err != nil {
+			return err
+		}
 		if err := validateTemplateID(runtime.Str("template-id")); err != nil {
 			return err
 		}

shortcuts/mail/mail_thread.go

@@ -58,6 +58,9 @@ var MailThread = common.Shortcut{
 		{Name: "include-spam-trash", Type: "bool", Desc: "Also return messages from SPAM and TRASH folders (excluded by default)"},
 		{Name: "print-output-schema", Type: "bool", Desc: "Print output field reference (run this first to learn field names before parsing output)"},
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateBotMailboxNotMe(runtime)
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		mailboxID := resolveMailboxID(runtime)
 		threadID := runtime.Str("thread-id")

shortcuts/mail/mail_triage.go

@@ -64,6 +64,9 @@ var MailTriage = common.Shortcut{
 		{Name: "labels", Type: "bool", Desc: "include label IDs in output"},
 		{Name: "print-filter-schema", Type: "bool", Desc: "print --filter field reference and exit"},
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateBotMailboxNotMe(runtime)
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		mailbox := resolveMailboxID(runtime)
 		query := runtime.Str("query")

shortcuts/wiki/shortcuts.go

@@ -12,7 +12,10 @@ func Shortcuts() []common.Shortcut {
 		WikiNodeCreate,
 		WikiDeleteSpace,
 		WikiSpaceList,
+		WikiSpaceCreate,
 		WikiNodeList,
 		WikiNodeCopy,
+		WikiNodeGet,
+		WikiNodeDelete,
 	}
 }

shortcuts/wiki/wiki_async_task.go

@@ -0,0 +1,207 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// Shared async-task polling for wiki delete operations. The wiki delete
+// endpoints (DELETE /spaces/{id}, DELETE /spaces/{id}/nodes/{token}) may
+// return either an empty task_id (sync completion) or a task_id that must
+// be polled against /wiki/v2/tasks/{task_id}?task_type=<...>.
+//
+// For historical reasons /wiki/v2/tasks/{task_id} stashes the status under a
+// different key per task type: delete-space uses `delete_space_result`, while
+// delete-node uses the generic `simple_task_result` (the gateway's reusable
+// "future async tasks share this" field). move tasks use `move_result` and are
+// handled separately in wiki_move.go. Every key still exposes a `status`, so
+// the poll loop / classification is factored out here and the caller passes
+// the right result key.
+//
+// Note: `simple_task_result` only carries `status` (no `status_msg`), so for
+// delete-node StatusLabel() falls back to the status code — which is fine.
+
+const (
+	wikiAsyncStatusSuccess    = "success"
+	wikiAsyncStatusFailure    = "failure"
+	wikiAsyncStatusProcessing = "processing"
+
+	wikiAsyncTaskTypeDeleteSpace = "delete_space"
+	wikiAsyncTaskTypeDeleteNode  = "delete_node"
+
+	wikiAsyncResultDeleteSpace = "delete_space_result"
+	// wikiAsyncResultSimpleTask is the generic result key the gateway uses for
+	// delete-node (and intends to reuse for future async task types). It is
+	// NOT `delete_node_result` — that key does not exist in the response.
+	wikiAsyncResultSimpleTask = "simple_task_result"
+)
+
+// wikiAsyncTaskStatus is the unified poll-response shape used by every wiki
+// delete task. The taskID is captured so error/resume hints can name it.
+type wikiAsyncTaskStatus struct {
+	TaskID    string
+	Status    string
+	StatusMsg string
+}
+
+// normalizedStatus collapses whitespace and case so "  SUCCESS  " classifies
+// the same as "success". Ready()/Failed() (control flow) derive from this;
+// StatusCode()/StatusLabel() (display) deliberately surface the raw backend
+// value instead. For the real status enums (delete-node: processing/success/
+// failed; delete-space's documented set) the two agree. They only diverge for
+// an undocumented status string, which is intentional — an unrecognized status
+// is shown verbatim rather than masked as a hard failure.
+func (s wikiAsyncTaskStatus) normalizedStatus() string {
+	return strings.ToLower(strings.TrimSpace(s.Status))
+}
+
+func (s wikiAsyncTaskStatus) Ready() bool {
+	return s.normalizedStatus() == wikiAsyncStatusSuccess
+}
+
+func (s wikiAsyncTaskStatus) Failed() bool {
+	// The sample protocol only documents "success" as a terminal OK. Treat any
+	// explicit "failure"/"failed" signal as terminal, and unknown non-success
+	// values as still-processing so we don't misreport a novel status as a hard
+	// failure.
+	lowered := s.normalizedStatus()
+	return lowered == wikiAsyncStatusFailure || lowered == "failed"
+}
+
+// StatusCode returns a never-empty status value for the output envelope. If
+// the backend response omits delete_*_result.status (or sends whitespace),
+// fall back to "processing" so the documented timeout-shape stays accurate.
+func (s wikiAsyncTaskStatus) StatusCode() string {
+	if status := strings.TrimSpace(s.Status); status != "" {
+		return status
+	}
+	return wikiAsyncStatusProcessing
+}
+
+func (s wikiAsyncTaskStatus) StatusLabel() string {
+	if msg := strings.TrimSpace(s.StatusMsg); msg != "" {
+		return msg
+	}
+	return s.StatusCode()
+}
+
+// wikiAsyncTaskFetcher returns the latest status for taskID. Implementations
+// translate from runtime.CallAPI responses or test fakes.
+type wikiAsyncTaskFetcher func(ctx context.Context, taskID string) (wikiAsyncTaskStatus, error)
+
+// parseWikiAsyncTaskStatus normalizes an /wiki/v2/tasks/{task_id} payload.
+// resultKey selects the right shape ("delete_space_result" for delete-space,
+// "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")
+	}
+
+	result := common.GetMap(task, resultKey)
+	status := wikiAsyncTaskStatus{
+		TaskID: common.GetString(task, "task_id"),
+	}
+	if status.TaskID == "" {
+		status.TaskID = taskID
+	}
+	if result != nil {
+		status.Status = common.GetString(result, "status")
+		status.StatusMsg = common.GetString(result, "status_msg")
+	}
+	return status, nil
+}
+
+// pollWikiAsyncTask runs the bounded polling loop shared by every wiki delete
+// shortcut. label is the human-readable operation name surfaced in stderr
+// progress lines ("delete-space" / "delete-node"). nextCommand is the resume
+// hint embedded into the wrapped error when every poll fails.
+//
+// attempts/interval are taken as parameters (instead of consts) so callers
+// can keep their per-operation tunable constants for back-compat with the
+// existing test hooks.
+func pollWikiAsyncTask(
+	ctx context.Context,
+	runtime *common.RuntimeContext,
+	taskID, label string,
+	attempts int,
+	interval time.Duration,
+	fetcher wikiAsyncTaskFetcher,
+	nextCommand string,
+) (wikiAsyncTaskStatus, bool, error) {
+	lastStatus := wikiAsyncTaskStatus{TaskID: taskID}
+	var lastErr error
+	hadSuccessfulPoll := false
+
+	// The delete request already succeeded. Treat poll failures as transient
+	// until every attempt fails, then return a resume hint instead of
+	// discarding the task identifier.
+	for attempt := 1; attempt <= attempts; attempt++ {
+		if attempt > 1 {
+			select {
+			case <-ctx.Done():
+				return lastStatus, false, ctx.Err()
+			case <-time.After(interval):
+			}
+		}
+
+		status, err := fetcher(ctx, taskID)
+		if err != nil {
+			lastErr = err
+			fmt.Fprintf(runtime.IO().ErrOut, "Wiki %s status attempt %d/%d failed: %v\n", label, attempt, attempts, err)
+			continue
+		}
+		lastStatus = status
+		hadSuccessfulPoll = true
+
+		if status.Ready() {
+			fmt.Fprintf(runtime.IO().ErrOut, "Wiki %s task completed successfully.\n", label)
+			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())
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Wiki %s status %d/%d: %s\n", label, attempt, attempts, status.StatusLabel())
+	}
+
+	if !hadSuccessfulPoll && lastErr != nil {
+		hint := fmt.Sprintf(
+			"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,
+				},
+			}
+		}
+		return lastStatus, false, output.ErrWithHint(output.ExitAPI, "api_error", lastErr.Error(), hint)
+	}
+
+	return lastStatus, false, nil
+}

shortcuts/wiki/wiki_async_task_test.go

@@ -0,0 +1,181 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// pollWikiAsyncTask is shared infrastructure for every wiki delete shortcut,
+// so it gets a dedicated test surface here rather than relying only on the
+// transitive coverage from the delete-space / delete-node paths.
+
+func TestPollWikiAsyncTaskSuccessFirstPoll(t *testing.T) {
+	t.Parallel()
+
+	runtime, stderr := newWikiNodeDeleteRuntime(t, core.AsUser)
+	status, ready, err := pollWikiAsyncTask(
+		context.Background(), runtime, "task_ok", "delete-node", 3, 0,
+		func(context.Context, string) (wikiAsyncTaskStatus, error) {
+			return wikiAsyncTaskStatus{Status: "success"}, nil
+		},
+		"resume-cmd",
+	)
+	if err != nil {
+		t.Fatalf("pollWikiAsyncTask() error = %v", err)
+	}
+	if !ready || !status.Ready() {
+		t.Fatalf("ready = %v, status = %+v, want ready", ready, status)
+	}
+	if !strings.Contains(stderr.String(), "delete-node task completed successfully") {
+		t.Fatalf("stderr = %q", stderr.String())
+	}
+}
+
+func TestPollWikiAsyncTaskFailureIsTerminal(t *testing.T) {
+	t.Parallel()
+
+	runtime, _ := newWikiNodeDeleteRuntime(t, core.AsUser)
+	_, ready, err := pollWikiAsyncTask(
+		context.Background(), runtime, "task_x", "delete-node", 3, 0,
+		func(context.Context, string) (wikiAsyncTaskStatus, error) {
+			return wikiAsyncTaskStatus{Status: "failure", StatusMsg: "denied"}, nil
+		},
+		"resume-cmd",
+	)
+	if ready {
+		t.Fatalf("ready = true, want false on failure")
+	}
+	if err == nil || !strings.Contains(err.Error(), "delete-node task task_x failed: denied") {
+		t.Fatalf("err = %v, want terminal failure with reason", err)
+	}
+}
+
+func TestPollWikiAsyncTaskTimeoutWhenAlwaysProcessing(t *testing.T) {
+	t.Parallel()
+
+	runtime, _ := newWikiNodeDeleteRuntime(t, core.AsUser)
+	status, ready, err := pollWikiAsyncTask(
+		context.Background(), runtime, "task_slow", "delete-space", 2, 0,
+		func(context.Context, string) (wikiAsyncTaskStatus, error) {
+			return wikiAsyncTaskStatus{Status: "processing"}, nil
+		},
+		"resume-cmd",
+	)
+	// A still-processing task after the bounded window is a soft timeout:
+	// no error, ready=false, status preserved so the caller can print the
+	// follow-up command.
+	if err != nil {
+		t.Fatalf("pollWikiAsyncTask() error = %v, want nil on timeout", err)
+	}
+	if ready {
+		t.Fatalf("ready = true, want false on timeout")
+	}
+	if status.StatusCode() != "processing" {
+		t.Fatalf("status = %+v, want processing preserved", status)
+	}
+}
+
+func TestPollWikiAsyncTaskAllPollsFailWrapsWithResumeHint(t *testing.T) {
+	t.Parallel()
+
+	runtime, stderr := newWikiNodeDeleteRuntime(t, core.AsUser)
+	_, ready, err := pollWikiAsyncTask(
+		context.Background(), runtime, "task_lost", "delete-node", 2, 0,
+		func(context.Context, string) (wikiAsyncTaskStatus, error) {
+			return wikiAsyncTaskStatus{}, errors.New("transport boom")
+		},
+		"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)
+	}
+	if exitErr.Code != output.ExitAPI {
+		t.Fatalf("exit code = %d, want ExitAPI", exitErr.Code)
+	}
+	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 !strings.Contains(stderr.String(), "attempt 2/2 failed") {
+		t.Fatalf("stderr = %q, want per-attempt progress", stderr.String())
+	}
+}
+
+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",
+		},
+	}
+	_, _, err := pollWikiAsyncTask(
+		context.Background(), runtime, "task_perm", "delete-node", 1, 0,
+		func(context.Context, string) (wikiAsyncTaskStatus, error) {
+			return wikiAsyncTaskStatus{}, upstream
+		},
+		"resume-cmd",
+	)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("err = %T %v, want *output.ExitError", 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)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "resume-cmd") {
+		t.Fatalf("hint = %q, want resume command appended", exitErr.Detail.Hint)
+	}
+	if exitErr.Detail.Type != "permission" || exitErr.Code != output.ExitAPI {
+		t.Fatalf("exitErr = %+v, want permission/ExitAPI propagated", exitErr)
+	}
+	if exitErr.Detail.Message != "permission denied" {
+		t.Fatalf("message = %q, want upstream message preserved", exitErr.Detail.Message)
+	}
+}
+
+func TestPollWikiAsyncTaskHonoursContextCancellation(t *testing.T) {
+	t.Parallel()
+
+	runtime, _ := newWikiNodeDeleteRuntime(t, core.AsUser)
+	ctx, cancel := context.WithCancel(context.Background())
+	calls := 0
+	_, ready, err := pollWikiAsyncTask(
+		ctx, runtime, "task_cancel", "delete-node", 5, time.Hour,
+		func(context.Context, string) (wikiAsyncTaskStatus, error) {
+			calls++
+			cancel() // cancel before the next attempt's inter-poll wait
+			return wikiAsyncTaskStatus{Status: "processing"}, nil
+		},
+		"resume-cmd",
+	)
+	if ready {
+		t.Fatalf("ready = true, want false on cancellation")
+	}
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("err = %v, want context.Canceled", err)
+	}
+	if calls != 1 {
+		t.Fatalf("fetcher calls = %d, want 1 (cancelled before second poll)", calls)
+	}
+}

shortcuts/wiki/wiki_delete.go

@@ -5,7 +5,6 @@ package wiki
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"strings"
 	"time"
@@ -21,10 +20,12 @@ var (
 	wikiDeleteSpacePollInterval = 2 * time.Second
 )
 
+// Back-compat aliases — the shared async-task helper now owns the strings,
+// but tests still reference these names.
 const (
-	wikiDeleteSpaceStatusSuccess    = "success"
-	wikiDeleteSpaceStatusFailure    = "failure"
-	wikiDeleteSpaceStatusProcessing = "processing"
+	wikiDeleteSpaceStatusSuccess    = wikiAsyncStatusSuccess
+	wikiDeleteSpaceStatusFailure    = wikiAsyncStatusFailure
+	wikiDeleteSpaceStatusProcessing = wikiAsyncStatusProcessing
 )
 
 // WikiDeleteSpace deletes a wiki space. The DELETE endpoint may complete
@@ -73,48 +74,10 @@ type wikiDeleteSpaceResponse struct {
 	TaskID string
 }
 
-type wikiDeleteSpaceTaskStatus struct {
-	TaskID    string
-	Status    string
-	StatusMsg string
-}
-
-// normalizedStatus collapses whitespace and case so "  SUCCESS  " is
-// classified the same as "success". Ready / Failed / StatusCode all derive
-// from this so classification and the output `status` field can't disagree.
-func (s wikiDeleteSpaceTaskStatus) normalizedStatus() string {
-	return strings.ToLower(strings.TrimSpace(s.Status))
-}
-
-func (s wikiDeleteSpaceTaskStatus) Ready() bool {
-	return s.normalizedStatus() == wikiDeleteSpaceStatusSuccess
-}
-
-func (s wikiDeleteSpaceTaskStatus) Failed() bool {
-	// The sample protocol only documents "success" as a terminal OK. Treat any
-	// explicit "failure"/"failed" signal as terminal, and unknown non-success
-	// values as still-processing so we don't misreport a novel status as a hard
-	// failure.
-	lowered := s.normalizedStatus()
-	return lowered == wikiDeleteSpaceStatusFailure || lowered == "failed"
-}
-
-// StatusCode returns a never-empty status value for the output envelope. If
-// the backend response omits delete_space_result.status (or sends whitespace),
-// fall back to "processing" so the documented timeout-shape stays accurate.
-func (s wikiDeleteSpaceTaskStatus) StatusCode() string {
-	if status := strings.TrimSpace(s.Status); status != "" {
-		return status
-	}
-	return wikiDeleteSpaceStatusProcessing
-}
-
-func (s wikiDeleteSpaceTaskStatus) StatusLabel() string {
-	if msg := strings.TrimSpace(s.StatusMsg); msg != "" {
-		return msg
-	}
-	return s.StatusCode()
-}
+// wikiDeleteSpaceTaskStatus is an alias for the shared wiki async-task shape;
+// kept as a named type for the existing test surface. delete-node uses the
+// same type directly under its real name (wikiAsyncTaskStatus).
+type wikiDeleteSpaceTaskStatus = wikiAsyncTaskStatus
 
 type wikiDeleteSpaceClient interface {
 	DeleteSpace(ctx context.Context, spaceID string) (*wikiDeleteSpaceResponse, error)
@@ -150,7 +113,7 @@ func (api wikiDeleteSpaceAPI) GetDeleteSpaceTask(ctx context.Context, taskID str
 	if err != nil {
 		return wikiDeleteSpaceTaskStatus{}, err
 	}
-	return parseWikiDeleteSpaceTaskStatus(taskID, common.GetMap(data, "task"))
+	return parseWikiAsyncTaskStatus(taskID, common.GetMap(data, "task"), wikiAsyncResultDeleteSpace)
 }
 
 func readWikiDeleteSpaceSpec(runtime *common.RuntimeContext) wikiDeleteSpaceSpec {
@@ -237,77 +200,18 @@ func wikiDeleteSpaceTaskResultCommand(taskID string, identity core.Identity) str
 }
 
 func pollWikiDeleteSpaceTask(ctx context.Context, client wikiDeleteSpaceClient, runtime *common.RuntimeContext, taskID string) (wikiDeleteSpaceTaskStatus, bool, error) {
-	lastStatus := wikiDeleteSpaceTaskStatus{TaskID: taskID}
-	var lastErr error
-	hadSuccessfulPoll := false
-
-	// The delete request already succeeded. Treat poll failures as transient
-	// until every attempt fails, then return a resume hint instead of discarding
-	// the task identifier.
-	for attempt := 1; attempt <= wikiDeleteSpacePollAttempts; attempt++ {
-		if attempt > 1 {
-			select {
-			case <-ctx.Done():
-				return lastStatus, false, ctx.Err()
-			case <-time.After(wikiDeleteSpacePollInterval):
-			}
-		}
-
-		status, err := client.GetDeleteSpaceTask(ctx, taskID)
-		if err != nil {
-			lastErr = err
-			fmt.Fprintf(runtime.IO().ErrOut, "Wiki delete-space status attempt %d/%d failed: %v\n", attempt, wikiDeleteSpacePollAttempts, err)
-			continue
-		}
-		lastStatus = status
-		hadSuccessfulPoll = true
-
-		if status.Ready() {
-			fmt.Fprintf(runtime.IO().ErrOut, "Wiki delete-space task completed successfully.\n")
-			return status, true, nil
-		}
-		if status.Failed() {
-			return status, false, output.Errorf(output.ExitAPI, "api_error", "wiki delete-space task %s failed: %s", taskID, status.StatusLabel())
-		}
-
-		fmt.Fprintf(runtime.IO().ErrOut, "Wiki delete-space status %d/%d: %s\n", attempt, wikiDeleteSpacePollAttempts, status.StatusLabel())
-	}
-
-	if !hadSuccessfulPoll && lastErr != nil {
-		nextCommand := wikiDeleteSpaceTaskResultCommand(taskID, runtime.As())
-		hint := fmt.Sprintf(
-			"the wiki delete-space task was created but every status poll failed (task_id=%s)\nretry status lookup with: %s",
-			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
-			}
-			return lastStatus, false, output.ErrWithHint(exitErr.Code, exitErr.Detail.Type, exitErr.Detail.Message, hint)
-		}
-		return lastStatus, false, output.ErrWithHint(output.ExitAPI, "api_error", lastErr.Error(), hint)
-	}
-
-	return lastStatus, false, nil
+	return pollWikiAsyncTask(
+		ctx, runtime, taskID, "delete-space",
+		wikiDeleteSpacePollAttempts, wikiDeleteSpacePollInterval,
+		func(ctx context.Context, id string) (wikiAsyncTaskStatus, error) {
+			return client.GetDeleteSpaceTask(ctx, id)
+		},
+		wikiDeleteSpaceTaskResultCommand(taskID, runtime.As()),
+	)
 }
 
+// parseWikiDeleteSpaceTaskStatus is kept as a thin wrapper for the existing
+// test surface; new callers should use parseWikiAsyncTaskStatus directly.
 func parseWikiDeleteSpaceTaskStatus(taskID string, task map[string]interface{}) (wikiDeleteSpaceTaskStatus, error) {
-	if task == nil {
-		return wikiDeleteSpaceTaskStatus{}, output.Errorf(output.ExitAPI, "api_error", "wiki task response missing task")
-	}
-
-	result := common.GetMap(task, "delete_space_result")
-	status := wikiDeleteSpaceTaskStatus{
-		TaskID: common.GetString(task, "task_id"),
-	}
-	if status.TaskID == "" {
-		status.TaskID = taskID
-	}
-	if result != nil {
-		status.Status = common.GetString(result, "status")
-		status.StatusMsg = common.GetString(result, "status_msg")
-	}
-	return status, nil
+	return parseWikiAsyncTaskStatus(taskID, task, wikiAsyncResultDeleteSpace)
 }

shortcuts/wiki/wiki_delete_test.go

@@ -266,8 +266,19 @@ 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
+	// pins that structured fields survive a fully failed poll (not just the
+	// hint). ErrWithHint drops Detail.Code, which is exactly what we fixed.
 	client := &fakeWikiDeleteSpaceClient{
-		taskErrs: []error{output.ErrWithHint(output.ExitAPI, "api_error", "poll failed", "retry original")},
+		taskErrs: []error{&output.ExitError{
+			Code: output.ExitAPI,
+			Detail: &output.ErrDetail{
+				Type:    "api_error",
+				Code:    131006,
+				Message: "poll failed",
+				Hint:    "retry original",
+			},
+		}},
 	}
 
 	status, ready, err := pollWikiDeleteSpaceTask(context.Background(), client, runtime, "task_123")
@@ -287,6 +298,9 @@ func TestPollWikiDeleteSpaceTaskWrapsPollFailuresWithHint(t *testing.T) {
 	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 exitErr.Detail.Code != 131006 {
+		t.Fatalf("Detail.Code = %d, want 131006 preserved through poll exhaustion", exitErr.Detail.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_helpers.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"strings"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// wikiNodeURL returns the user-facing link for a wiki node. The create/copy
+// OpenAPI responses carry a real `url` (undocumented in the server-docs schema
+// but present in practice); prefer it so the CLI surfaces the canonical link.
+// Fall back to BuildResourceURL synthesis only when the response omits it.
+//
+// Shared by +node-create and +node-copy, hence kept here rather than in either
+// command's file.
+func wikiNodeURL(brand core.LarkBrand, node *wikiNodeRecord) string {
+	if node == nil {
+		return ""
+	}
+	if u := strings.TrimSpace(node.URL); u != "" {
+		return u
+	}
+	return common.BuildResourceURL(brand, "wiki", node.NodeToken)
+}

shortcuts/wiki/wiki_list_copy_test.go

@@ -415,6 +415,7 @@ func TestWikiNodeCopyCopiesNodeToTargetSpace(t *testing.T) {
 					"node_type":         "origin",
 					"title":             "Architecture (Copy)",
 					"has_child":         false,
+					"url":               "https://abc.feishu.cn/wiki/wik_copied_real",
 				},
 			},
 			"msg": "success",
@@ -451,6 +452,9 @@ func TestWikiNodeCopyCopiesNodeToTargetSpace(t *testing.T) {
 	if envelope.Data["space_id"] != "space_dst" {
 		t.Fatalf("space_id = %v, want %q", envelope.Data["space_id"], "space_dst")
 	}
+	if got, want := envelope.Data["url"], "https://abc.feishu.cn/wiki/wik_copied_real"; got != want {
+		t.Fatalf("url = %#v, want %q (copy must surface the response url)", got, want)
+	}
 
 	var captured map[string]interface{}
 	if err := json.Unmarshal(stub.CapturedBody, &captured); err != nil {

shortcuts/wiki/wiki_node_copy.go

@@ -89,6 +89,9 @@ var WikiNodeCopy = common.Shortcut{
 		fmt.Fprintf(runtime.IO().ErrOut, "Copied to node %s in space %s\n",
 			common.MaskToken(node.NodeToken), common.MaskToken(node.SpaceID))
 		out := wikiNodeCopyOutput(node)
+		if u := wikiNodeURL(runtime.Config.Brand, node); u != "" {
+			out["url"] = u
+		}
 		runtime.OutFormat(out, nil, func(w io.Writer) {
 			renderWikiNodeCopyPretty(w, out)
 		})
@@ -106,6 +109,9 @@ func renderWikiNodeCopyPretty(w io.Writer, out map[string]interface{}) {
 	if parent, _ := out["parent_node_token"].(string); parent != "" {
 		fmt.Fprintf(w, "  parent_node_token: %s\n", parent)
 	}
+	if url, _ := out["url"].(string); url != "" {
+		fmt.Fprintf(w, "  url:               %s\n", url)
+	}
 }
 
 func buildNodeCopyBody(runtime *common.RuntimeContext) map[string]interface{} {

shortcuts/wiki/wiki_node_create.go

@@ -118,6 +118,7 @@ type wikiNodeRecord struct {
 	OriginNodeToken string
 	Title           string
 	HasChild        bool
+	URL             string
 }
 
 // wikiSpaceRecord contains the response fields used when resolving spaces.
@@ -456,6 +457,7 @@ func parseWikiNodeRecord(node map[string]interface{}) (*wikiNodeRecord, error) {
 		OriginNodeToken: common.GetString(node, "origin_node_token"),
 		Title:           common.GetString(node, "title"),
 		HasChild:        common.GetBool(node, "has_child"),
+		URL:             common.GetString(node, "url"),
 	}, nil
 }
 
@@ -498,7 +500,7 @@ func augmentWikiNodeCreateOutput(runtime *common.RuntimeContext, execution *wiki
 	if grant := common.AutoGrantCurrentUserDrivePermission(runtime, execution.Node.NodeToken, "wiki"); grant != nil {
 		out["permission_grant"] = grant
 	}
-	if u := common.BuildResourceURL(runtime.Config.Brand, "wiki", execution.Node.NodeToken); u != "" {
+	if u := wikiNodeURL(runtime.Config.Brand, execution.Node); u != "" {
 		out["url"] = u
 	}
 	return out

shortcuts/wiki/wiki_node_create_test.go

@@ -107,24 +107,6 @@ func mountAndRunWiki(t *testing.T, shortcut common.Shortcut, args []string, fact
 	return parent.Execute()
 }
 
-func TestWikiShortcutsIncludeAllCommands(t *testing.T) {
-	t.Parallel()
-
-	shortcuts := Shortcuts()
-	if len(shortcuts) != 6 {
-		t.Fatalf("len(Shortcuts()) = %d, want 6", len(shortcuts))
-	}
-	if shortcuts[0].Command != "+move" {
-		t.Fatalf("shortcuts[0].Command = %q, want %q", shortcuts[0].Command, "+move")
-	}
-	if shortcuts[1].Command != "+node-create" {
-		t.Fatalf("shortcuts[1].Command = %q, want %q", shortcuts[1].Command, "+node-create")
-	}
-	if shortcuts[2].Command != "+delete-space" {
-		t.Fatalf("shortcuts[2].Command = %q, want %q", shortcuts[2].Command, "+delete-space")
-	}
-}
-
 func TestValidateWikiNodeCreateSpecRejectsShortcutWithoutOriginNodeToken(t *testing.T) {
 	t.Parallel()
 
@@ -469,6 +451,7 @@ func TestWikiNodeCreateMountedExecuteWithExplicitSpaceID(t *testing.T) {
 					"origin_node_token": "",
 					"title":             "Wiki Node",
 					"has_child":         false,
+					"url":               "https://abc.feishu.cn/wiki/wik_created_real",
 				},
 			},
 			"msg": "success",
@@ -502,8 +485,8 @@ func TestWikiNodeCreateMountedExecuteWithExplicitSpaceID(t *testing.T) {
 	if envelope.Data["node_token"] != "wik_created" {
 		t.Fatalf("node_token = %#v, want %q", envelope.Data["node_token"], "wik_created")
 	}
-	if got, want := envelope.Data["url"], "https://www.feishu.cn/wiki/wik_created"; got != want {
-		t.Fatalf("url = %#v, want %q", got, want)
+	if got, want := envelope.Data["url"], "https://abc.feishu.cn/wiki/wik_created_real"; got != want {
+		t.Fatalf("url = %#v, want %q (response url must win over synthesized fallback)", got, want)
 	}
 
 	var captured map[string]interface{}
@@ -646,3 +629,47 @@ func TestAugmentWikiNodeCreateOutputReturnsEmptyMapForNilInput(t *testing.T) {
 		t.Fatalf("augmentWikiNodeCreateOutput(nil, empty execution) = %#v, want empty map", got)
 	}
 }
+
+func TestWikiNodeURL(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		node *wikiNodeRecord
+		want string
+	}{
+		{
+			name: "prefers response url over synthesized fallback",
+			node: &wikiNodeRecord{NodeToken: "wik_token", URL: "https://abc.feishu.cn/wiki/wik_real"},
+			want: "https://abc.feishu.cn/wiki/wik_real",
+		},
+		{
+			name: "falls back to synthesized url when response omits it",
+			node: &wikiNodeRecord{NodeToken: "wik_token"},
+			want: "https://www.feishu.cn/wiki/wik_token",
+		},
+		{
+			name: "blank response url is treated as absent",
+			node: &wikiNodeRecord{NodeToken: "wik_token", URL: "   "},
+			want: "https://www.feishu.cn/wiki/wik_token",
+		},
+		{
+			name: "nil node yields empty string",
+			node: nil,
+			want: "",
+		},
+		{
+			name: "no token and no url yields empty string",
+			node: &wikiNodeRecord{},
+			want: "",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := wikiNodeURL(core.BrandFeishu, tc.node); got != tc.want {
+				t.Fatalf("wikiNodeURL() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}

shortcuts/wiki/wiki_node_delete.go

@@ -0,0 +1,440 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// wikiNodeDeleteObjTypes is the set of obj_type values the delete-node API
+// accepts. Unlike wikiNodeGetObjTypeEnum this includes "wiki" — for
+// delete-node, obj_type="wiki" means the token is a wiki node_token, whereas
+// the get_node API omits obj_type for node_tokens.
+var wikiNodeDeleteObjTypes = []string{
+	"wiki", "doc", "docx", "sheet", "bitable", "mindnote", "slides", "file",
+}
+
+var (
+	wikiDeleteNodePollAttempts = 30
+	wikiDeleteNodePollInterval = 2 * time.Second
+)
+
+// Lark wiki API error codes the delete-node API surfaces with actionable
+// CLI workarounds. The full list is in the OpenAPI spec; we only special-case
+// the codes whose remediation is non-obvious (UI approval, subtree size).
+const (
+	wikiDeleteNodeErrCodeApprovalRequired = 131011
+	wikiDeleteNodeErrCodeSubtreeTooLarge  = 131003
+)
+
+// WikiNodeDelete deletes a wiki node (or pulls a cloud doc out of Wiki). The
+// API mirrors +delete-space — synchronous on small deletes, async with a
+// task_id for cascade deletes — so this shortcut shares the async-polling
+// helper. Space ID is optional: when omitted, +node-delete first looks up the
+// node via get_node to resolve the space ID so callers do not have to chain
+// commands.
+var WikiNodeDelete = common.Shortcut{
+	Service:     "wiki",
+	Command:     "+node-delete",
+	Description: "Delete a wiki node, polling the async delete task when needed",
+	Risk:        "high-risk-write",
+	// API spec lists wiki:node:create as the only declared scope for the
+	// delete endpoint. Naming is unfortunate, but the scope-preflight needs
+	// the literal string.
+	Scopes:    []string{"wiki:node:create"},
+	AuthTypes: []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "node-token", Desc: "wiki node_token, cloud-doc obj_token, or a Lark URL embedding one of them", Required: true},
+		// Not Required at the cobra level: URL inputs auto-infer obj_type
+		// from the path, and the parser enforces explicit obj_type for raw
+		// tokens. Forcing Cobra Required here breaks the URL ergonomic.
+		{Name: "obj-type", Desc: "token kind; no default — pass explicitly when --node-token is a raw token (URL inputs auto-infer)", Enum: wikiNodeDeleteObjTypes},
+		{Name: "space-id", Desc: "wiki space ID; auto-resolved via get_node when omitted"},
+		{Name: "include-children", Type: "bool", Default: "true", Desc: "cascade delete the subtree (default); pass --include-children=false to lift direct children up to the parent"},
+	},
+	Tips: []string{
+		"Deletion is irreversible; double-check --node-token and --obj-type before running.",
+		"This is a high-risk-write command; pass --yes to confirm the deletion.",
+		"--node-token accepts a raw token (wikcnXXX, docxXXX, ...) or a Lark URL like https://feishu.cn/wiki/<token> or https://feishu.cn/docx/<token>; URL paths also imply --obj-type.",
+		"Run +node-get first to confirm space_id / obj_type when in doubt.",
+		"Auto-resolving space_id (when --space-id is omitted) also calls get_node, which needs the wiki:node:retrieve scope; pass --space-id to skip that lookup if your token only carries wiki:node:create.",
+		"Async deletes return a task_id; this command polls for a bounded window and then prints a follow-up drive +task_result command.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := readWikiNodeDeleteSpec(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec, err := readWikiNodeDeleteSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return buildWikiNodeDeleteDryRun(spec)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec, err := readWikiNodeDeleteSpec(runtime)
+		if err != nil {
+			return err
+		}
+
+		out, err := runWikiNodeDelete(ctx, wikiNodeDeleteAPI{runtime: runtime}, runtime, spec)
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+// wikiNodeDeleteSpec is the normalized input for the shortcut. Token / ObjType
+// reconcile URL inputs with the explicit flags; SourceKind is purely for the
+// dry-run description string.
+type wikiNodeDeleteSpec struct {
+	NodeToken       string
+	ObjType         string
+	SpaceID         string
+	IncludeChildren bool
+	SourceKind      string // "raw" | "url"
+}
+
+// RequestBody builds the JSON body for DELETE /spaces/{id}/nodes/{token}.
+func (spec wikiNodeDeleteSpec) RequestBody() map[string]interface{} {
+	return map[string]interface{}{
+		"obj_type":         spec.ObjType,
+		"include_children": spec.IncludeChildren,
+	}
+}
+
+// wikiNodeDeleteClient isolates the network operations so business logic can
+// be unit-tested without real HTTP calls. Mirrors wikiDeleteSpaceClient.
+type wikiNodeDeleteClient interface {
+	ResolveNode(ctx context.Context, token, objType string) (*wikiNodeRecord, error)
+	DeleteNode(ctx context.Context, spaceID string, spec wikiNodeDeleteSpec) (string, error)
+	GetDeleteNodeTask(ctx context.Context, taskID string) (wikiAsyncTaskStatus, error)
+}
+
+type wikiNodeDeleteAPI struct {
+	runtime *common.RuntimeContext
+}
+
+func (api wikiNodeDeleteAPI) ResolveNode(ctx context.Context, token, objType string) (*wikiNodeRecord, error) {
+	params := map[string]interface{}{"token": token}
+	// get_node takes obj_type only when the token is an obj_token. For
+	// wiki node_tokens the API rejects an obj_type kwarg, so omit it.
+	if objType != "" && objType != "wiki" {
+		params["obj_type"] = objType
+	}
+	data, err := api.runtime.CallAPI("GET", "/open-apis/wiki/v2/spaces/get_node", params, nil)
+	if err != nil {
+		return nil, err
+	}
+	return parseWikiNodeRecord(common.GetMap(data, "node"))
+}
+
+func (api wikiNodeDeleteAPI) DeleteNode(ctx context.Context, spaceID string, spec wikiNodeDeleteSpec) (string, error) {
+	data, err := api.runtime.CallAPI(
+		"DELETE",
+		fmt.Sprintf(
+			"/open-apis/wiki/v2/spaces/%s/nodes/%s",
+			validate.EncodePathSegment(spaceID),
+			validate.EncodePathSegment(spec.NodeToken),
+		),
+		nil,
+		spec.RequestBody(),
+	)
+	if err != nil {
+		return "", wrapWikiNodeDeleteAPIError(err)
+	}
+	return common.GetString(data, "task_id"), nil
+}
+
+func (api wikiNodeDeleteAPI) GetDeleteNodeTask(ctx context.Context, taskID string) (wikiAsyncTaskStatus, error) {
+	data, err := api.runtime.CallAPI(
+		"GET",
+		fmt.Sprintf("/open-apis/wiki/v2/tasks/%s", validate.EncodePathSegment(taskID)),
+		map[string]interface{}{"task_type": wikiAsyncTaskTypeDeleteNode},
+		nil,
+	)
+	if err != nil {
+		return wikiAsyncTaskStatus{}, err
+	}
+	return parseWikiAsyncTaskStatus(taskID, common.GetMap(data, "task"), wikiAsyncResultSimpleTask)
+}
+
+func readWikiNodeDeleteSpec(runtime *common.RuntimeContext) (wikiNodeDeleteSpec, error) {
+	return parseWikiNodeDeleteSpec(
+		runtime.Str("node-token"),
+		runtime.Str("obj-type"),
+		runtime.Str("space-id"),
+		runtime.Bool("include-children"),
+	)
+}
+
+// parseWikiNodeDeleteSpec normalizes the raw flag values: extracts a token
+// from a URL when provided, reconciles URL-implied obj_type against the
+// explicit flag, and validates that the resulting obj_type is one the delete
+// API accepts.
+func parseWikiNodeDeleteSpec(rawToken, rawObjType, rawSpaceID string, includeChildren bool) (wikiNodeDeleteSpec, error) {
+	tokenInput := strings.TrimSpace(rawToken)
+	if tokenInput == "" {
+		return wikiNodeDeleteSpec{}, output.ErrValidation("--node-token is required")
+	}
+
+	spec := wikiNodeDeleteSpec{
+		ObjType:         strings.ToLower(strings.TrimSpace(rawObjType)),
+		SpaceID:         strings.TrimSpace(rawSpaceID),
+		IncludeChildren: includeChildren,
+	}
+
+	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)
+		}
+		token, urlObjType, ok := tokenAndObjTypeFromWikiURL(u.Path)
+		if !ok {
+			return wikiNodeDeleteSpec{}, output.ErrValidation(
+				"unsupported --node-token URL path %q: expected /wiki/, /docx/, /doc/, /sheets/, /base/, /mindnote/, /slides/, or /file/ followed by a token",
+				u.Path,
+			)
+		}
+		spec.NodeToken = token
+		spec.SourceKind = "url"
+
+		// /wiki/<token> implies node_token → obj_type=wiki for the delete API.
+		// Cloud doc paths (/docx/, /sheets/, ...) already give us a concrete type.
+		inferred := urlObjType
+		if inferred == "" {
+			inferred = "wiki"
+		}
+		switch {
+		case spec.ObjType == "":
+			spec.ObjType = inferred
+		case spec.ObjType != inferred:
+			return wikiNodeDeleteSpec{}, output.ErrValidation(
+				"--obj-type %q does not match the obj_type %q implied by the URL path; pass only one",
+				spec.ObjType, inferred,
+			)
+		}
+	} else if strings.ContainsAny(tokenInput, "/?#") {
+		return wikiNodeDeleteSpec{}, output.ErrValidation(
+			"--node-token must be a raw token or a full URL; partial paths are not accepted: %q",
+			tokenInput,
+		)
+	} else {
+		spec.NodeToken = tokenInput
+		spec.SourceKind = "raw"
+	}
+
+	if spec.ObjType == "" {
+		return wikiNodeDeleteSpec{}, output.ErrValidation(
+			"--obj-type is required (one of: %s)",
+			strings.Join(wikiNodeDeleteObjTypes, ", "),
+		)
+	}
+	if !isValidWikiDeleteObjType(spec.ObjType) {
+		return wikiNodeDeleteSpec{}, output.ErrValidation(
+			"--obj-type %q is not valid; pick one of: %s",
+			spec.ObjType, strings.Join(wikiNodeDeleteObjTypes, ", "),
+		)
+	}
+	if err := validateOptionalResourceName(spec.NodeToken, "--node-token"); err != nil {
+		return wikiNodeDeleteSpec{}, err
+	}
+	if err := validateOptionalResourceName(spec.SpaceID, "--space-id"); err != nil {
+		return wikiNodeDeleteSpec{}, err
+	}
+	return spec, nil
+}
+
+func isValidWikiDeleteObjType(v string) bool {
+	for _, t := range wikiNodeDeleteObjTypes {
+		if v == t {
+			return true
+		}
+	}
+	return false
+}
+
+func buildWikiNodeDeleteDryRun(spec wikiNodeDeleteSpec) *common.DryRunAPI {
+	dry := common.NewDryRunAPI().Desc(
+		"async-aware: delete wiki node -> poll wiki delete-node task when task_id is returned (auto-resolves space_id via get_node when --space-id is omitted)",
+	)
+
+	if spec.SpaceID == "" {
+		params := map[string]interface{}{"token": spec.NodeToken}
+		if spec.ObjType != "" && spec.ObjType != "wiki" {
+			params["obj_type"] = spec.ObjType
+		}
+		dry.GET("/open-apis/wiki/v2/spaces/get_node").
+			Desc("[1] Resolve space_id via get_node").
+			Params(params)
+		dry.DELETE(fmt.Sprintf(
+			"/open-apis/wiki/v2/spaces/%s/nodes/%s",
+			"<resolved_space_id>",
+			validate.EncodePathSegment(spec.NodeToken),
+		)).
+			Desc("[2] Delete wiki node").
+			Body(spec.RequestBody())
+	} else {
+		dry.DELETE(fmt.Sprintf(
+			"/open-apis/wiki/v2/spaces/%s/nodes/%s",
+			validate.EncodePathSegment(spec.SpaceID),
+			validate.EncodePathSegment(spec.NodeToken),
+		)).
+			Desc("[1] Delete wiki node").
+			Body(spec.RequestBody())
+	}
+
+	dry.GET("/open-apis/wiki/v2/tasks/:task_id").
+		Desc("[N] Poll wiki delete-node task result when async").
+		Set("task_id", "<task_id>").
+		Params(map[string]interface{}{"task_type": wikiAsyncTaskTypeDeleteNode})
+
+	return dry
+}
+
+func runWikiNodeDelete(ctx context.Context, client wikiNodeDeleteClient, runtime *common.RuntimeContext, spec wikiNodeDeleteSpec) (map[string]interface{}, error) {
+	spaceID, err := resolveWikiNodeDeleteSpaceID(ctx, client, runtime, spec)
+	if err != nil {
+		return nil, err
+	}
+
+	fmt.Fprintf(runtime.IO().ErrOut, "Deleting wiki node %s in space %s (obj_type=%s, include_children=%t)...\n",
+		common.MaskToken(spec.NodeToken), common.MaskToken(spaceID), spec.ObjType, spec.IncludeChildren)
+
+	taskID, err := client.DeleteNode(ctx, spaceID, spec)
+	if err != nil {
+		return nil, err
+	}
+
+	out := map[string]interface{}{
+		"space_id":         spaceID,
+		"node_token":       spec.NodeToken,
+		"obj_type":         spec.ObjType,
+		"include_children": spec.IncludeChildren,
+	}
+
+	// Empty task_id means the delete completed synchronously. Match the
+	// shape used by +delete-space so downstream scripts can read `status`
+	// uniformly regardless of which branch fired.
+	if taskID == "" {
+		out["ready"] = true
+		out["failed"] = false
+		out["status"] = wikiAsyncStatusSuccess
+		out["status_msg"] = wikiAsyncStatusSuccess
+		return out, nil
+	}
+
+	fmt.Fprintf(runtime.IO().ErrOut, "Wiki node delete is async, polling task %s...\n", taskID)
+	nextCommand := wikiDeleteNodeTaskResultCommand(taskID, runtime.As())
+	status, ready, err := pollWikiAsyncTask(
+		ctx, runtime, taskID, "delete-node",
+		wikiDeleteNodePollAttempts, wikiDeleteNodePollInterval,
+		func(ctx context.Context, id string) (wikiAsyncTaskStatus, error) {
+			return client.GetDeleteNodeTask(ctx, id)
+		},
+		nextCommand,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	out["task_id"] = taskID
+	out["ready"] = ready
+	out["failed"] = status.Failed()
+	out["status"] = status.StatusCode()
+	out["status_msg"] = status.StatusLabel()
+
+	if !ready {
+		fmt.Fprintf(runtime.IO().ErrOut, "Wiki delete-node task is still in progress. Continue with: %s\n", nextCommand)
+		out["timed_out"] = true
+		out["next_command"] = nextCommand
+	}
+	return out, nil
+}
+
+// resolveWikiNodeDeleteSpaceID returns the explicit space_id when the caller
+// supplied one, otherwise resolves it via get_node. The latter saves callers
+// from running +node-get first when they only have a node_token.
+func resolveWikiNodeDeleteSpaceID(ctx context.Context, client wikiNodeDeleteClient, runtime *common.RuntimeContext, spec wikiNodeDeleteSpec) (string, error) {
+	if spec.SpaceID != "" {
+		return spec.SpaceID, nil
+	}
+	fmt.Fprintf(runtime.IO().ErrOut, "Resolving space_id via get_node for token %s...\n", common.MaskToken(spec.NodeToken))
+	node, err := client.ResolveNode(ctx, spec.NodeToken, spec.ObjType)
+	if err != nil {
+		return "", err
+	}
+	spaceID, err := requireWikiNodeSpaceID(node)
+	if err != nil {
+		return "", err
+	}
+	fmt.Fprintf(runtime.IO().ErrOut, "Resolved to space %s\n", common.MaskToken(spaceID))
+	return spaceID, nil
+}
+
+func wikiDeleteNodeTaskResultCommand(taskID string, identity core.Identity) string {
+	asFlag := string(identity)
+	if asFlag == "" {
+		asFlag = "user"
+	}
+	return fmt.Sprintf("lark-cli drive +task_result --scenario wiki_delete_node --task-id %s --as %s", taskID, asFlag)
+}
+
+// wrapWikiNodeDeleteAPIError attaches actionable hints to the two Lark error
+// codes whose remediation lives outside the CLI:
+//   - 131011: approval required (deletion gated by Wiki UI approval flow)
+//   - 131003: subtree too large to cascade-delete (must split or use
+//     include_children=false)
+//
+// Other codes pass through untouched so the generic error envelope still
+// surfaces the original code+message.
+func wrapWikiNodeDeleteAPIError(err error) error {
+	if err == nil {
+		return nil
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		return err
+	}
+	var hint string
+	switch exitErr.Detail.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:
+		hint = "the subtree is too large to cascade-delete in one call; pass --include-children=false to keep the children (they will be moved up to the parent), or delete sub-trees first"
+	}
+	if hint == "" {
+		return err
+	}
+	if existing := strings.TrimSpace(exitErr.Detail.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,
+		},
+	}
+}

shortcuts/wiki/wiki_node_delete_test.go

@@ -0,0 +1,611 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ── parseWikiNodeDeleteSpec ─────────────────────────────────────────────────
+
+func TestParseWikiNodeDeleteSpecAcceptsRawWikiToken(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeDeleteSpec("wikcnABC", "wiki", "", true)
+	if err != nil {
+		t.Fatalf("parseWikiNodeDeleteSpec() error = %v", err)
+	}
+	if spec.NodeToken != "wikcnABC" || spec.ObjType != "wiki" || spec.SourceKind != "raw" || !spec.IncludeChildren {
+		t.Fatalf("spec = %+v", spec)
+	}
+	body := spec.RequestBody()
+	if body["obj_type"] != "wiki" || body["include_children"] != true {
+		t.Fatalf("RequestBody = %#v", body)
+	}
+}
+
+func TestParseWikiNodeDeleteSpecRejectsMissingObjType(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiNodeDeleteSpec("wikcnABC", "", "", true)
+	if err == nil || !strings.Contains(err.Error(), "--obj-type is required") {
+		t.Fatalf("expected obj-type required error, got %v", err)
+	}
+}
+
+func TestParseWikiNodeDeleteSpecRejectsInvalidObjType(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiNodeDeleteSpec("wikcnABC", "comment", "", true)
+	if err == nil || !strings.Contains(err.Error(), "is not valid") {
+		t.Fatalf("expected invalid obj-type error, got %v", err)
+	}
+}
+
+func TestParseWikiNodeDeleteSpecRejectsEmptyToken(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiNodeDeleteSpec("   ", "wiki", "", true)
+	if err == nil || !strings.Contains(err.Error(), "--node-token is required") {
+		t.Fatalf("expected token required error, got %v", err)
+	}
+}
+
+func TestParseWikiNodeDeleteSpecExtractsTokenFromWikiURL(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeDeleteSpec("https://feishu.cn/wiki/wikcnABC", "", "", true)
+	if err != nil {
+		t.Fatalf("parseWikiNodeDeleteSpec() error = %v", err)
+	}
+	if spec.NodeToken != "wikcnABC" || spec.ObjType != "wiki" || spec.SourceKind != "url" {
+		t.Fatalf("spec = %+v, want url-extracted node_token + obj_type=wiki", spec)
+	}
+}
+
+func TestParseWikiNodeDeleteSpecInfersObjTypeFromDocxURL(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeDeleteSpec("https://feishu.cn/docx/docxXYZ", "", "", false)
+	if err != nil {
+		t.Fatalf("parseWikiNodeDeleteSpec() error = %v", err)
+	}
+	if spec.NodeToken != "docxXYZ" || spec.ObjType != "docx" || spec.IncludeChildren {
+		t.Fatalf("spec = %+v, want docxXYZ obj_type=docx include_children=false", spec)
+	}
+}
+
+func TestParseWikiNodeDeleteSpecRejectsURLObjTypeMismatch(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiNodeDeleteSpec("https://feishu.cn/docx/docxXYZ", "wiki", "", true)
+	if err == nil || !strings.Contains(err.Error(), "does not match the obj_type") {
+		t.Fatalf("expected obj-type mismatch error, got %v", err)
+	}
+}
+
+func TestParseWikiNodeDeleteSpecRejectsPartialPath(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiNodeDeleteSpec("/wiki/wikcnABC", "wiki", "", true)
+	if err == nil || !strings.Contains(err.Error(), "partial paths are not accepted") {
+		t.Fatalf("expected partial-path rejection, got %v", err)
+	}
+}
+
+// ── DryRun ──────────────────────────────────────────────────────────────────
+
+func TestBuildWikiNodeDeleteDryRunWithoutSpaceIDShowsResolve(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeDeleteSpec("https://feishu.cn/docx/docxXYZ", "", "", true)
+	if err != nil {
+		t.Fatalf("parseWikiNodeDeleteSpec() error = %v", err)
+	}
+
+	dry := buildWikiNodeDeleteDryRun(spec)
+	got := decodeDryRunAPIs(t, dry)
+	if len(got) != 3 {
+		t.Fatalf("len(dry.api) = %d, want 3 (get_node, delete, task poll)", len(got))
+	}
+	if got[0].URL != "/open-apis/wiki/v2/spaces/get_node" {
+		t.Fatalf("step[0].URL = %q, want get_node", got[0].URL)
+	}
+	if got[0].Params["obj_type"] != "docx" || got[0].Params["token"] != "docxXYZ" {
+		t.Fatalf("step[0].params = %#v", got[0].Params)
+	}
+	if got[1].URL != "/open-apis/wiki/v2/spaces/<resolved_space_id>/nodes/docxXYZ" {
+		t.Fatalf("step[1].URL = %q, want delete with placeholder", got[1].URL)
+	}
+	if got[1].Body["obj_type"] != "docx" || got[1].Body["include_children"] != true {
+		t.Fatalf("step[1].body = %#v", got[1].Body)
+	}
+	if got[2].Params["task_type"] != "delete_node" {
+		t.Fatalf("step[2].params task_type = %#v, want delete_node", got[2].Params)
+	}
+}
+
+func TestBuildWikiNodeDeleteDryRunWithSpaceIDOmitsResolve(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeDeleteSpec("wikcnABC", "wiki", "7629741305993170448", false)
+	if err != nil {
+		t.Fatalf("parseWikiNodeDeleteSpec() error = %v", err)
+	}
+
+	dry := buildWikiNodeDeleteDryRun(spec)
+	got := decodeDryRunAPIs(t, dry)
+	if len(got) != 2 {
+		t.Fatalf("len(dry.api) = %d, want 2 (delete + task poll) when --space-id supplied", len(got))
+	}
+	if got[0].Method != "DELETE" || got[0].URL != "/open-apis/wiki/v2/spaces/7629741305993170448/nodes/wikcnABC" {
+		t.Fatalf("step[0] = %+v", got[0])
+	}
+	if got[0].Body["include_children"] != false {
+		t.Fatalf("body include_children = %#v", got[0].Body["include_children"])
+	}
+}
+
+// ── runWikiNodeDelete unit ──────────────────────────────────────────────────
+
+type fakeWikiNodeDeleteClient struct {
+	resolveErr   error
+	resolveNode  *wikiNodeRecord
+	resolveCalls []string
+
+	deleteErr    error
+	deleteTaskID string
+	deleteCalls  []struct {
+		SpaceID string
+		Spec    wikiNodeDeleteSpec
+	}
+
+	taskStatuses []wikiAsyncTaskStatus
+	taskErrs     []error
+	taskCallArgs []string
+}
+
+func (fake *fakeWikiNodeDeleteClient) ResolveNode(ctx context.Context, token, objType string) (*wikiNodeRecord, error) {
+	fake.resolveCalls = append(fake.resolveCalls, token)
+	if fake.resolveErr != nil {
+		return nil, fake.resolveErr
+	}
+	return fake.resolveNode, nil
+}
+
+func (fake *fakeWikiNodeDeleteClient) DeleteNode(ctx context.Context, spaceID string, spec wikiNodeDeleteSpec) (string, error) {
+	fake.deleteCalls = append(fake.deleteCalls, struct {
+		SpaceID string
+		Spec    wikiNodeDeleteSpec
+	}{SpaceID: spaceID, Spec: spec})
+	if fake.deleteErr != nil {
+		return "", fake.deleteErr
+	}
+	return fake.deleteTaskID, nil
+}
+
+func (fake *fakeWikiNodeDeleteClient) GetDeleteNodeTask(ctx context.Context, taskID string) (wikiAsyncTaskStatus, error) {
+	idx := len(fake.taskCallArgs)
+	fake.taskCallArgs = append(fake.taskCallArgs, taskID)
+	if idx < len(fake.taskErrs) && fake.taskErrs[idx] != nil {
+		return wikiAsyncTaskStatus{TaskID: taskID}, fake.taskErrs[idx]
+	}
+	if idx < len(fake.taskStatuses) {
+		status := fake.taskStatuses[idx]
+		if status.TaskID == "" {
+			status.TaskID = taskID
+		}
+		return status, nil
+	}
+	return wikiAsyncTaskStatus{TaskID: taskID}, nil
+}
+
+var wikiDeleteNodePollMu sync.Mutex
+
+func withSingleWikiDeleteNodePoll(t *testing.T) {
+	t.Helper()
+	wikiDeleteNodePollMu.Lock()
+
+	prevAttempts, prevInterval := wikiDeleteNodePollAttempts, wikiDeleteNodePollInterval
+	wikiDeleteNodePollAttempts, wikiDeleteNodePollInterval = 1, 0
+	t.Cleanup(func() {
+		wikiDeleteNodePollAttempts, wikiDeleteNodePollInterval = prevAttempts, prevInterval
+		wikiDeleteNodePollMu.Unlock()
+	})
+}
+
+func newWikiNodeDeleteRuntime(t *testing.T, as core.Identity) (*common.RuntimeContext, *bytes.Buffer) {
+	t.Helper()
+
+	cfg := wikiTestConfig()
+	factory, _, stderr, _ := cmdutil.TestFactory(t, cfg)
+	runtime := common.TestNewRuntimeContextWithIdentity(&cobra.Command{Use: "wiki +node-delete"}, cfg, as)
+	runtime.Factory = factory
+	return runtime, stderr
+}
+
+func TestRunWikiNodeDeleteResolvesSpaceWhenMissing(t *testing.T) {
+	t.Parallel()
+
+	runtime, _ := newWikiNodeDeleteRuntime(t, core.AsUser)
+	client := &fakeWikiNodeDeleteClient{
+		resolveNode: &wikiNodeRecord{SpaceID: "space_resolved"},
+	}
+
+	out, err := runWikiNodeDelete(context.Background(), client, runtime, wikiNodeDeleteSpec{
+		NodeToken:       "wikcnABC",
+		ObjType:         "wiki",
+		IncludeChildren: true,
+	})
+	if err != nil {
+		t.Fatalf("runWikiNodeDelete() error = %v", err)
+	}
+	if len(client.resolveCalls) != 1 || client.resolveCalls[0] != "wikcnABC" {
+		t.Fatalf("resolve calls = %v", client.resolveCalls)
+	}
+	if len(client.deleteCalls) != 1 || client.deleteCalls[0].SpaceID != "space_resolved" {
+		t.Fatalf("delete calls = %+v", client.deleteCalls)
+	}
+	if out["space_id"] != "space_resolved" || out["ready"] != true || out["status"] != "success" {
+		t.Fatalf("sync output = %#v", out)
+	}
+}
+
+func TestRunWikiNodeDeleteSkipsResolveWhenSpaceProvided(t *testing.T) {
+	t.Parallel()
+
+	runtime, _ := newWikiNodeDeleteRuntime(t, core.AsUser)
+	client := &fakeWikiNodeDeleteClient{}
+
+	_, err := runWikiNodeDelete(context.Background(), client, runtime, wikiNodeDeleteSpec{
+		NodeToken: "wikcnABC", ObjType: "wiki", SpaceID: "space_explicit",
+	})
+	if err != nil {
+		t.Fatalf("runWikiNodeDelete() error = %v", err)
+	}
+	if len(client.resolveCalls) != 0 {
+		t.Fatalf("resolveCalls should be empty when --space-id supplied, got %v", client.resolveCalls)
+	}
+	if client.deleteCalls[0].SpaceID != "space_explicit" {
+		t.Fatalf("delete used wrong space: %+v", client.deleteCalls)
+	}
+}
+
+func TestRunWikiNodeDeleteAsyncReadyShape(t *testing.T) {
+	withSingleWikiDeleteNodePoll(t)
+
+	runtime, stderr := newWikiNodeDeleteRuntime(t, core.AsUser)
+	client := &fakeWikiNodeDeleteClient{
+		deleteTaskID: "task_async_node",
+		taskStatuses: []wikiAsyncTaskStatus{{Status: "success"}},
+	}
+
+	out, err := runWikiNodeDelete(context.Background(), client, runtime, wikiNodeDeleteSpec{
+		NodeToken: "wikcnABC", ObjType: "wiki", SpaceID: "space_123", IncludeChildren: true,
+	})
+	if err != nil {
+		t.Fatalf("runWikiNodeDelete() error = %v", err)
+	}
+	if out["task_id"] != "task_async_node" || out["ready"] != true || out["failed"] != false {
+		t.Fatalf("async-ready output = %#v", out)
+	}
+	if !strings.Contains(stderr.String(), "async, polling task") || !strings.Contains(stderr.String(), "delete-node task completed successfully") {
+		t.Fatalf("stderr = %q", stderr.String())
+	}
+}
+
+func TestRunWikiNodeDeleteAsyncTimeoutReturnsNextCommand(t *testing.T) {
+	withSingleWikiDeleteNodePoll(t)
+
+	runtime, _ := newWikiNodeDeleteRuntime(t, core.AsUser)
+	client := &fakeWikiNodeDeleteClient{
+		deleteTaskID: "task_async_node",
+		taskStatuses: []wikiAsyncTaskStatus{{Status: "processing"}},
+	}
+
+	out, err := runWikiNodeDelete(context.Background(), client, runtime, wikiNodeDeleteSpec{
+		NodeToken: "wikcnABC", ObjType: "wiki", SpaceID: "space_123",
+	})
+	if err != nil {
+		t.Fatalf("runWikiNodeDelete() error = %v", err)
+	}
+	wantNext := wikiDeleteNodeTaskResultCommand("task_async_node", core.AsUser)
+	if out["ready"] != false || out["timed_out"] != true || out["next_command"] != wantNext {
+		t.Fatalf("timeout output = %#v", out)
+	}
+	if !strings.Contains(wantNext, "wiki_delete_node") {
+		t.Fatalf("next command should scope wiki_delete_node, got %q", wantNext)
+	}
+}
+
+func TestRunWikiNodeDeleteAsyncFailureSurfacesReason(t *testing.T) {
+	withSingleWikiDeleteNodePoll(t)
+
+	runtime, _ := newWikiNodeDeleteRuntime(t, core.AsUser)
+	client := &fakeWikiNodeDeleteClient{
+		deleteTaskID: "task_async_node",
+		taskStatuses: []wikiAsyncTaskStatus{{Status: "failure", StatusMsg: "permission denied"}},
+	}
+
+	_, err := runWikiNodeDelete(context.Background(), client, runtime, wikiNodeDeleteSpec{
+		NodeToken: "wikcnABC", ObjType: "wiki", SpaceID: "space_123",
+	})
+	if err == nil || !strings.Contains(err.Error(), "delete-node task task_async_node failed: permission denied") {
+		t.Fatalf("expected async failure error, got %v", err)
+	}
+}
+
+// ── error code hint mapping ─────────────────────────────────────────────────
+
+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",
+		},
+	}
+	got := wrapWikiNodeDeleteAPIError(in)
+	var exitErr *output.ExitError
+	if !errors.As(got, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError, 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)
+	}
+	// 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 exitErr.Detail.Message != "node requires delete approval" {
+		t.Fatalf("message changed unexpectedly: %q", exitErr.Detail.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",
+		},
+	}
+	got := wrapWikiNodeDeleteAPIError(in)
+	var exitErr *output.ExitError
+	if !errors.As(got, &exitErr) {
+		t.Fatalf("expected ExitError, 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)
+	}
+}
+
+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"},
+	}
+	got := wrapWikiNodeDeleteAPIError(in)
+	if !reflect.DeepEqual(got, in) {
+		t.Fatalf("unknown code should pass through; got %#v", got)
+	}
+}
+
+func TestWrapWikiNodeDeleteAPIErrorIgnoresNonExit(t *testing.T) {
+	t.Parallel()
+
+	in := errors.New("transport boom")
+	if got := wrapWikiNodeDeleteAPIError(in); got != in {
+		t.Fatalf("non-ExitError should pass through, got %T %v", got, got)
+	}
+	if got := wrapWikiNodeDeleteAPIError(nil); got != nil {
+		t.Fatalf("nil should pass through, got %v", got)
+	}
+}
+
+// ── Mounted execute (httpmock) ──────────────────────────────────────────────
+
+func TestWikiNodeDeleteExecuteRequiresYesConfirmation(t *testing.T) {
+	factory, stdout, _, _ := cmdutil.TestFactory(t, wikiTestConfig())
+
+	err := mountAndRunWiki(t, WikiNodeDelete, []string{
+		"+node-delete",
+		"--node-token", "wikcnABC",
+		"--obj-type", "wiki",
+		"--space-id", "space_123",
+		"--as", "user",
+	}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "requires confirmation") {
+		t.Fatalf("expected high-risk confirmation error, got %v", err)
+	}
+}
+
+func TestWikiNodeDeleteExecuteSync(t *testing.T) {
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+
+	deleteStub := &httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes/wikcnABC",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{},
+			"msg":  "success",
+		},
+	}
+	reg.Register(deleteStub)
+
+	err := mountAndRunWiki(t, WikiNodeDelete, []string{
+		"+node-delete",
+		"--node-token", "wikcnABC",
+		"--obj-type", "wiki",
+		"--space-id", "space_123",
+		"--yes",
+		"--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	if data["ready"] != true || data["failed"] != false || data["space_id"] != "space_123" {
+		t.Fatalf("sync output = %#v", data)
+	}
+	if data["obj_type"] != "wiki" || data["include_children"] != true {
+		t.Fatalf("obj_type/include_children = %#v / %#v", data["obj_type"], data["include_children"])
+	}
+
+	var captured map[string]interface{}
+	if err := json.Unmarshal(deleteStub.CapturedBody, &captured); err != nil {
+		t.Fatalf("unmarshal captured body: %v", err)
+	}
+	if captured["obj_type"] != "wiki" || captured["include_children"] != true {
+		t.Fatalf("captured DELETE body = %#v", captured)
+	}
+}
+
+func TestWikiNodeDeleteExecuteResolvesSpaceIDFromURL(t *testing.T) {
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+
+	resolveStub := &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"space_id":   "space_resolved",
+					"node_token": "wikcnABC",
+					"obj_token":  "docxXYZ",
+					"obj_type":   "docx",
+				},
+			},
+		},
+	}
+	var resolveQuery string
+	resolveStub.OnMatch = func(req *http.Request) { resolveQuery = req.URL.RawQuery }
+	reg.Register(resolveStub)
+
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/wiki/v2/spaces/space_resolved/nodes/docxXYZ",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRunWiki(t, WikiNodeDelete, []string{
+		"+node-delete",
+		"--node-token", "https://feishu.cn/docx/docxXYZ",
+		"--yes",
+		"--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+
+	if !strings.Contains(resolveQuery, "token=docxXYZ") || !strings.Contains(resolveQuery, "obj_type=docx") {
+		t.Fatalf("resolve query = %q, want token+obj_type", resolveQuery)
+	}
+	data := decodeWikiEnvelope(t, stdout)
+	if data["space_id"] != "space_resolved" || data["obj_type"] != "docx" {
+		t.Fatalf("output = %#v", data)
+	}
+}
+
+func TestWikiNodeDeleteExecuteAsyncSuccess(t *testing.T) {
+	withSingleWikiDeleteNodePoll(t)
+
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes/wikcnABC",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"task_id": "task_async_node"},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/tasks/task_async_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"task": map[string]interface{}{
+					// Gateway returns delete-node status under the generic
+					// simple_task_result key (NOT delete_node_result).
+					"simple_task_result": map[string]interface{}{
+						"status": "success",
+					},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunWiki(t, WikiNodeDelete, []string{
+		"+node-delete",
+		"--node-token", "wikcnABC",
+		"--obj-type", "wiki",
+		"--space-id", "space_123",
+		"--yes",
+		"--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+	data := decodeWikiEnvelope(t, stdout)
+	if data["task_id"] != "task_async_node" || data["ready"] != true || data["failed"] != false {
+		t.Fatalf("async-success output = %#v", data)
+	}
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+type dryRunStep struct {
+	Method string                 `json:"method"`
+	URL    string                 `json:"url"`
+	Body   map[string]interface{} `json:"body"`
+	Params map[string]interface{} `json:"params"`
+}
+
+func decodeDryRunAPIs(t *testing.T, dry *common.DryRunAPI) []dryRunStep {
+	t.Helper()
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+	var got struct {
+		API []dryRunStep `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run: %v", err)
+	}
+	return got.API
+}

shortcuts/wiki/wiki_node_get.go

@@ -0,0 +1,370 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// wikiNodeGetURLObjTypes maps a Lark URL path prefix (slash-bounded) to the
+// obj_type the wiki get_node API expects when the token is an obj_token.
+// /wiki/ is handled separately because node_tokens take no obj_type.
+//
+// INVARIANT: the prefixes must be mutually exclusive (no prefix may be a
+// prefix of another). tokenAndObjTypeFromWikiURL ranges this map, and Go map
+// iteration order is randomized — overlapping prefixes would make the match
+// non-deterministic. The trailing slash keeps them disjoint today (e.g.
+// "/docx/" does not start with "/doc/"); preserve that when adding entries.
+var wikiNodeGetURLObjTypes = map[string]string{
+	"/docx/":     "docx",
+	"/doc/":      "doc",
+	"/sheets/":   "sheet",
+	"/base/":     "bitable",
+	"/mindnote/": "mindnote",
+	"/slides/":   "slides",
+	"/file/":     "file",
+}
+
+// wikiNodeGetObjTypeEnum is the union of obj_types accepted by the upstream
+// API. It is a superset of the create / move enums so this shortcut can look
+// up legacy `doc` nodes too.
+var wikiNodeGetObjTypeEnum = []string{
+	"doc", "docx", "sheet", "bitable", "mindnote", "slides", "file",
+}
+
+// WikiNodeGet wraps wiki.spaces.get_node so callers can resolve a node by
+// node_token, obj_token, or a Lark URL without hand-rolling a
+// `wiki spaces get_node --params ...` invocation. The shortcut prints a
+// formatted view of the node (title / obj_type / obj_token / parent /
+// creator / updated_at) and is intended as the "what am I about to
+// touch?" step before +move / +node-copy / +delete-space.
+var WikiNodeGet = common.Shortcut{
+	Service:     "wiki",
+	Command:     "+node-get",
+	Description: "Get wiki node details by node_token, obj_token, or Lark URL",
+	Risk:        "read",
+	Scopes:      []string{"wiki:node:retrieve"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "token", Desc: "wiki node_token, obj_token, or a Lark URL embedding one of them", Required: true},
+		{Name: "obj-type", Desc: "obj_type when --token is an obj_token; auto-inferred from URL path when omitted", Enum: wikiNodeGetObjTypeEnum},
+		{Name: "space-id", Desc: "optional: assert the resolved node lives in this space"},
+	},
+	Tips: []string{
+		"--token accepts a raw token (wikcnXXX, docxXXX, ...) or a Lark URL like https://feishu.cn/wiki/<token> or https://feishu.cn/docx/<token>.",
+		"For raw obj_tokens (not starting with wik), pass --obj-type so the API knows how to resolve them; URL inputs infer it from the path.",
+		"Pair with +move / +node-copy / +delete-space to confirm space_id, obj_type, and parent before mutating.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := readWikiNodeGetSpec(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec, err := readWikiNodeGetSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return buildWikiNodeGetDryRun(spec)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec, err := readWikiNodeGetSpec(runtime)
+		if err != nil {
+			return err
+		}
+
+		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)
+		if err != nil {
+			return err
+		}
+		raw := common.GetMap(data, "node")
+		node, err := parseWikiNodeRecord(raw)
+		if err != nil {
+			return err
+		}
+
+		if spec.SpaceID != "" && node.SpaceID != "" && spec.SpaceID != node.SpaceID {
+			return output.ErrValidation(
+				"--space-id %q does not match the resolved node space %q (node_token=%s)",
+				spec.SpaceID, node.SpaceID, node.NodeToken,
+			)
+		}
+		if spec.SpaceID != "" && node.SpaceID == "" {
+			// The cross-check was requested but get_node returned no space_id,
+			// so it silently passed. Surface that the assertion was a no-op
+			// rather than letting the caller assume it was verified.
+			fmt.Fprintf(runtime.IO().ErrOut,
+				"Warning: --space-id %q could not be verified; the resolved node carries no space_id.\n",
+				spec.SpaceID)
+		}
+
+		out := wikiNodeGetOutput(node, raw)
+		runtime.OutFormat(out, nil, func(w io.Writer) {
+			renderWikiNodeGetPretty(w, out)
+		})
+		return nil
+	},
+}
+
+// wikiNodeGetSpec is the normalized input for the shortcut.
+type wikiNodeGetSpec struct {
+	// Token is the resolved token (after URL extraction) to send to the API.
+	Token string
+	// ObjType is the resolved obj_type. Empty for node_tokens (the API does
+	// not need obj_type for `wik`-prefixed tokens).
+	ObjType string
+	// SpaceID is an optional cross-check; when set, the response space_id must match.
+	SpaceID string
+	// SourceKind records how Token was derived for the dry-run description:
+	// "url-wiki", "url-obj", "raw-node", "raw-obj".
+	SourceKind string
+}
+
+// RequestParams returns the query params for GET /wiki/v2/spaces/get_node.
+func (spec wikiNodeGetSpec) RequestParams() map[string]interface{} {
+	params := map[string]interface{}{"token": spec.Token}
+	if spec.ObjType != "" {
+		params["obj_type"] = spec.ObjType
+	}
+	return params
+}
+
+func readWikiNodeGetSpec(runtime *common.RuntimeContext) (wikiNodeGetSpec, error) {
+	return parseWikiNodeGetSpec(
+		runtime.Str("token"),
+		runtime.Str("obj-type"),
+		runtime.Str("space-id"),
+	)
+}
+
+// parseWikiNodeGetSpec normalizes the raw flag values: extracts a token from a
+// URL when needed, picks the obj_type (URL path > explicit flag > none for
+// node_tokens), and validates the token shape.
+func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetSpec, error) {
+	tokenInput := strings.TrimSpace(rawToken)
+	if tokenInput == "" {
+		return wikiNodeGetSpec{}, output.ErrValidation("--token is required")
+	}
+
+	spec := wikiNodeGetSpec{
+		ObjType: strings.ToLower(strings.TrimSpace(rawObjType)),
+		SpaceID: strings.TrimSpace(rawSpaceID),
+	}
+
+	if strings.Contains(tokenInput, "://") {
+		u, err := url.Parse(tokenInput)
+		if err != nil || u.Path == "" {
+			return wikiNodeGetSpec{}, output.ErrValidation("--token URL is malformed: %q", tokenInput)
+		}
+		token, urlObjType, ok := tokenAndObjTypeFromWikiURL(u.Path)
+		if !ok {
+			return wikiNodeGetSpec{}, output.ErrValidation(
+				"unsupported --token URL path %q: expected /wiki/, /docx/, /doc/, /sheets/, /base/, /mindnote/, /slides/, or /file/ followed by a token",
+				u.Path,
+			)
+		}
+		spec.Token = token
+		if urlObjType == "" {
+			spec.SourceKind = "url-wiki"
+		} else {
+			spec.SourceKind = "url-obj"
+		}
+		switch {
+		case spec.ObjType == "" && urlObjType != "":
+			spec.ObjType = urlObjType
+		case spec.ObjType != "" && urlObjType != "" && spec.ObjType != urlObjType:
+			return wikiNodeGetSpec{}, output.ErrValidation(
+				"--obj-type %q does not match the obj_type %q implied by the URL path; pass only one",
+				spec.ObjType, urlObjType,
+			)
+		}
+	} else if strings.ContainsAny(tokenInput, "/?#") {
+		return wikiNodeGetSpec{}, output.ErrValidation(
+			"--token must be a raw token or a full URL; partial paths are not accepted: %q",
+			tokenInput,
+		)
+	} else {
+		spec.Token = tokenInput
+		if looksLikeWikiNodeToken(spec.Token) {
+			spec.SourceKind = "raw-node"
+			// node_tokens take no obj_type; reject a conflicting flag rather
+			// than silently passing it (the API would just ignore it, but the
+			// mismatch signals caller confusion).
+			if spec.ObjType != "" {
+				return wikiNodeGetSpec{}, output.ErrValidation(
+					"--obj-type is only valid for obj_tokens; %q looks like a node_token",
+					spec.Token,
+				)
+			}
+		} else {
+			spec.SourceKind = "raw-obj"
+			// A raw obj_token needs an explicit obj_type: get_node would
+			// otherwise default to "doc" and fail confusingly for docx /
+			// 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(
+					"--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, ", "),
+				)
+			}
+		}
+	}
+
+	if err := validateOptionalResourceName(spec.Token, "--token"); err != nil {
+		return wikiNodeGetSpec{}, err
+	}
+	if err := validateOptionalResourceName(spec.SpaceID, "--space-id"); err != nil {
+		return wikiNodeGetSpec{}, err
+	}
+	return spec, nil
+}
+
+// looksLikeWikiNodeToken returns true when the token has the `wik` prefix used
+// for node_tokens. Lark wiki tokens are case-insensitive in practice; callers
+// pass `wikcn`/`wikus`/`Wik...` interchangeably, so normalize for the check.
+//
+// This is a heuristic based on the current Lark token-naming convention, not a
+// guaranteed invariant: if Lark ever introduces a non-node token type that
+// also starts with `wik`, it would be misclassified. Worst case is a
+// confusing API error (no data risk); revisit if the token scheme changes.
+func looksLikeWikiNodeToken(token string) bool {
+	return strings.HasPrefix(strings.ToLower(token), "wik")
+}
+
+// tokenAndObjTypeFromWikiURL extracts the token and inferred obj_type from a
+// Lark URL path. The wiki path returns an empty obj_type because node_tokens
+// don't need one.
+func tokenAndObjTypeFromWikiURL(path string) (token, objType string, ok bool) {
+	if t, found := wikiPathSegmentAfter(path, "/wiki/"); found {
+		return t, "", true
+	}
+	for prefix, ot := range wikiNodeGetURLObjTypes {
+		if t, found := wikiPathSegmentAfter(path, prefix); found {
+			return t, ot, true
+		}
+	}
+	return "", "", false
+}
+
+// wikiPathSegmentAfter returns the first path segment after prefix, or ("",
+// false) when path doesn't start with prefix or the segment is empty.
+func wikiPathSegmentAfter(path, prefix string) (string, bool) {
+	if !strings.HasPrefix(path, prefix) {
+		return "", false
+	}
+	rest := path[len(prefix):]
+	if i := strings.IndexByte(rest, '/'); i >= 0 {
+		rest = rest[:i]
+	}
+	rest = strings.TrimSpace(rest)
+	if rest == "" {
+		return "", false
+	}
+	return rest, true
+}
+
+func buildWikiNodeGetDryRun(spec wikiNodeGetSpec) *common.DryRunAPI {
+	dry := common.NewDryRunAPI()
+	switch spec.SourceKind {
+	case "url-wiki":
+		dry.Desc("Resolve wiki node from /wiki/ URL")
+	case "url-obj":
+		dry.Desc("Resolve wiki node from Lark document URL (obj_type inferred from path)")
+	case "raw-node":
+		dry.Desc("Look up wiki node by node_token")
+	case "raw-obj":
+		dry.Desc("Look up wiki node by obj_token")
+	}
+	return dry.GET("/open-apis/wiki/v2/spaces/get_node").Params(spec.RequestParams())
+}
+
+// wikiNodeGetOutput shapes the structured output. It carries the formatted
+// values (title/obj_type/obj_token/parent_node_token/creator/updated_at)
+// the user asked for, plus enough raw fields (node_type, has_child, owner,
+// timestamps) that callers can pipe into +move / +node-copy without rerunning
+// get_node.
+//
+// No synthesized `url` is emitted: get_node returns none, and a
+// BuildResourceURL fallback (www.feishu.cn/wiki/<node_token>) is a
+// non-canonical link that misleads in a read/confirm command. Sibling read
+// shortcuts (+node-list, +node-copy) likewise omit it; node_token/obj_token
+// are the precise identifiers.
+func wikiNodeGetOutput(node *wikiNodeRecord, raw map[string]interface{}) map[string]interface{} {
+	out := map[string]interface{}{
+		"space_id":          node.SpaceID,
+		"node_token":        node.NodeToken,
+		"obj_token":         node.ObjToken,
+		"obj_type":          node.ObjType,
+		"node_type":         node.NodeType,
+		"parent_node_token": node.ParentNodeToken,
+		"origin_node_token": node.OriginNodeToken,
+		"title":             node.Title,
+		"has_child":         node.HasChild,
+	}
+
+	creator := strings.TrimSpace(common.GetString(raw, "node_creator"))
+	if creator == "" {
+		creator = strings.TrimSpace(common.GetString(raw, "creator"))
+	}
+	out["creator"] = creator
+	out["owner"] = common.GetString(raw, "owner")
+
+	objEditRaw := common.GetString(raw, "obj_edit_time")
+	out["obj_edit_time"] = objEditRaw
+	out["obj_create_time"] = common.GetString(raw, "obj_create_time")
+	out["node_create_time"] = common.GetString(raw, "node_create_time")
+	out["updated_at"] = formatWikiTimestamp(objEditRaw)
+
+	return out
+}
+
+// formatWikiTimestamp turns a Lark unix-seconds string (the format used by
+// wiki.spaces.get_node) into a UTC RFC3339 string. UTC (not the host's local
+// zone) keeps the output stable regardless of where the CLI runs. Returns ""
+// when the input is empty or not numeric so the pretty renderer falls back
+// to "-".
+func formatWikiTimestamp(s string) string {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return ""
+	}
+	secs, err := strconv.ParseInt(s, 10, 64)
+	if err != nil {
+		return ""
+	}
+	return time.Unix(secs, 0).UTC().Format(time.RFC3339)
+}
+
+func renderWikiNodeGetPretty(w io.Writer, out map[string]interface{}) {
+	fmt.Fprintln(w, "Wiki node:")
+	fmt.Fprintf(w, "  title:             %s\n", valueOrDash(out["title"]))
+	fmt.Fprintf(w, "  obj_type:          %s\n", valueOrDash(out["obj_type"]))
+	fmt.Fprintf(w, "  obj_token:         %s\n", valueOrDash(out["obj_token"]))
+	fmt.Fprintf(w, "  node_token:        %s\n", valueOrDash(out["node_token"]))
+	fmt.Fprintf(w, "  space_id:          %s\n", valueOrDash(out["space_id"]))
+	fmt.Fprintf(w, "  parent_node_token: %s\n", valueOrDash(out["parent_node_token"]))
+	fmt.Fprintf(w, "  node_type:         %s\n", valueOrDash(out["node_type"]))
+	if origin, _ := out["origin_node_token"].(string); origin != "" {
+		fmt.Fprintf(w, "  origin_node_token: %s\n", origin)
+	}
+	hasChild, _ := out["has_child"].(bool)
+	fmt.Fprintf(w, "  has_child:         %t\n", hasChild)
+	fmt.Fprintf(w, "  creator:           %s\n", valueOrDash(out["creator"]))
+	if owner, _ := out["owner"].(string); owner != "" {
+		fmt.Fprintf(w, "  owner:             %s\n", owner)
+	}
+	fmt.Fprintf(w, "  updated_at:        %s\n", valueOrDash(out["updated_at"]))
+}

shortcuts/wiki/wiki_node_get_test.go

@@ -0,0 +1,321 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"encoding/json"
+	"net/http"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestParseWikiNodeGetSpecRawNodeToken(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeGetSpec("wikcnABC", "", "")
+	if err != nil {
+		t.Fatalf("parseWikiNodeGetSpec() error = %v", err)
+	}
+	if spec.Token != "wikcnABC" || spec.ObjType != "" || spec.SourceKind != "raw-node" {
+		t.Fatalf("spec = %+v, want raw-node wikcnABC with no obj_type", spec)
+	}
+	if got := spec.RequestParams(); !reflect.DeepEqual(got, map[string]interface{}{"token": "wikcnABC"}) {
+		t.Fatalf("RequestParams() = %v, want {token: wikcnABC}", got)
+	}
+}
+
+func TestParseWikiNodeGetSpecRawObjTokenWithExplicitObjType(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeGetSpec("docxXYZ", "docx", "")
+	if err != nil {
+		t.Fatalf("parseWikiNodeGetSpec() error = %v", err)
+	}
+	if spec.Token != "docxXYZ" || spec.ObjType != "docx" || spec.SourceKind != "raw-obj" {
+		t.Fatalf("spec = %+v, want raw-obj docxXYZ obj_type=docx", spec)
+	}
+}
+
+func TestParseWikiNodeGetSpecRejectsRawObjTokenWithoutObjType(t *testing.T) {
+	t.Parallel()
+
+	// Mirrors +node-delete: a raw obj_token with no --obj-type must fail
+	// upfront instead of defaulting to "doc" and hitting an opaque API error.
+	_, err := parseWikiNodeGetSpec("bascnXYZ", "", "")
+	if err == nil || !strings.Contains(err.Error(), "--obj-type is required for a raw obj_token") {
+		t.Fatalf("expected raw obj_token obj-type-required error, got %v", err)
+	}
+}
+
+func TestParseWikiNodeGetSpecRejectsObjTypeOnNodeToken(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiNodeGetSpec("wikcnABC", "docx", "")
+	if err == nil || !strings.Contains(err.Error(), "only valid for obj_tokens") {
+		t.Fatalf("expected node_token + obj_type rejection, got %v", err)
+	}
+}
+
+func TestParseWikiNodeGetSpecExtractsTokenFromWikiURL(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeGetSpec("https://feishu.cn/wiki/wikcnABC?foo=bar", "", "")
+	if err != nil {
+		t.Fatalf("parseWikiNodeGetSpec() error = %v", err)
+	}
+	if spec.Token != "wikcnABC" || spec.ObjType != "" || spec.SourceKind != "url-wiki" {
+		t.Fatalf("spec = %+v, want url-wiki wikcnABC", spec)
+	}
+}
+
+func TestParseWikiNodeGetSpecExtractsTokenAndObjTypeFromDocxURL(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeGetSpec("https://feishu.cn/docx/docxXYZ", "", "")
+	if err != nil {
+		t.Fatalf("parseWikiNodeGetSpec() error = %v", err)
+	}
+	if spec.Token != "docxXYZ" || spec.ObjType != "docx" || spec.SourceKind != "url-obj" {
+		t.Fatalf("spec = %+v, want url-obj docxXYZ", spec)
+	}
+}
+
+func TestParseWikiNodeGetSpecRejectsURLObjTypeMismatch(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiNodeGetSpec("https://feishu.cn/sheets/shtXYZ", "docx", "")
+	if err == nil || !strings.Contains(err.Error(), "does not match the obj_type") {
+		t.Fatalf("expected URL/obj-type mismatch error, got %v", err)
+	}
+}
+
+func TestParseWikiNodeGetSpecRejectsUnsupportedURLPath(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiNodeGetSpec("https://feishu.cn/im/chat/oc_123", "", "")
+	if err == nil || !strings.Contains(err.Error(), "unsupported --token URL path") {
+		t.Fatalf("expected unsupported URL path error, got %v", err)
+	}
+}
+
+func TestParseWikiNodeGetSpecRejectsPartialPath(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiNodeGetSpec("/wiki/wikcnABC", "", "")
+	if err == nil || !strings.Contains(err.Error(), "partial paths are not accepted") {
+		t.Fatalf("expected partial-path rejection, got %v", err)
+	}
+}
+
+func TestParseWikiNodeGetSpecRejectsEmptyToken(t *testing.T) {
+	t.Parallel()
+
+	if _, err := parseWikiNodeGetSpec("   ", "", ""); err == nil || !strings.Contains(err.Error(), "--token is required") {
+		t.Fatalf("expected required-token error, got %v", err)
+	}
+}
+
+func TestBuildWikiNodeGetDryRunSendsObjType(t *testing.T) {
+	t.Parallel()
+
+	spec, err := parseWikiNodeGetSpec("https://feishu.cn/docx/docxXYZ", "", "")
+	if err != nil {
+		t.Fatalf("parseWikiNodeGetSpec() error = %v", err)
+	}
+
+	dry := buildWikiNodeGetDryRun(spec)
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+	var got struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run: %v", err)
+	}
+	if len(got.API) != 1 || got.API[0].URL != "/open-apis/wiki/v2/spaces/get_node" {
+		t.Fatalf("dry-run api = %#v, want single get_node call", got.API)
+	}
+	if got.API[0].Params["token"] != "docxXYZ" || got.API[0].Params["obj_type"] != "docx" {
+		t.Fatalf("dry-run params = %#v", got.API[0].Params)
+	}
+}
+
+func TestFormatWikiTimestamp(t *testing.T) {
+	t.Parallel()
+
+	if got := formatWikiTimestamp(""); got != "" {
+		t.Fatalf("formatWikiTimestamp(empty) = %q, want empty", got)
+	}
+	if got := formatWikiTimestamp("not-a-number"); got != "" {
+		t.Fatalf("formatWikiTimestamp(non-numeric) = %q, want empty", got)
+	}
+	// Output is UTC, so it is deterministic regardless of host timezone.
+	if got := formatWikiTimestamp("1700000000"); got != "2023-11-14T22:13:20Z" {
+		t.Fatalf("formatWikiTimestamp(1700000000) = %q, want 2023-11-14T22:13:20Z (UTC)", got)
+	}
+}
+
+func TestWikiNodeGetMountedExecuteParsesURLAndFormatsOutput(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, stderr, reg := cmdutil.TestFactory(t, wikiTestConfig())
+
+	stub := &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"space_id":          "space_123",
+					"node_token":        "wikcnABC",
+					"obj_token":         "docxXYZ",
+					"obj_type":          "docx",
+					"parent_node_token": "wikcnPARENT",
+					"node_type":         "origin",
+					"title":             "Design Spec",
+					"has_child":         true,
+					"node_creator":      "ou_creator",
+					"owner":             "ou_owner",
+					"obj_edit_time":     "1700000000",
+					"obj_create_time":   "1690000000",
+					"node_create_time":  "1690000001",
+				},
+			},
+			"msg": "success",
+		},
+	}
+	var capturedQuery string
+	stub.OnMatch = func(req *http.Request) {
+		capturedQuery = req.URL.RawQuery
+	}
+	reg.Register(stub)
+
+	err := mountAndRunWiki(t, WikiNodeGet, []string{
+		"+node-get",
+		"--token", "https://feishu.cn/docx/docxXYZ",
+		"--as", "bot",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+
+	if !strings.Contains(capturedQuery, "token=docxXYZ") || !strings.Contains(capturedQuery, "obj_type=docx") {
+		t.Fatalf("captured query = %q, want token=docxXYZ and obj_type=docx", capturedQuery)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	if data["title"] != "Design Spec" {
+		t.Fatalf("title = %#v, want Design Spec", data["title"])
+	}
+	if data["obj_type"] != "docx" || data["obj_token"] != "docxXYZ" {
+		t.Fatalf("obj_type/obj_token = %#v / %#v", data["obj_type"], data["obj_token"])
+	}
+	if data["parent_node_token"] != "wikcnPARENT" {
+		t.Fatalf("parent_node_token = %#v", data["parent_node_token"])
+	}
+	if data["creator"] != "ou_creator" {
+		t.Fatalf("creator = %#v, want ou_creator", data["creator"])
+	}
+	if data["owner"] != "ou_owner" {
+		t.Fatalf("owner = %#v, want ou_owner", data["owner"])
+	}
+	if got, _ := data["updated_at"].(string); got != "2023-11-14T22:13:20Z" {
+		t.Fatalf("updated_at = %#v, want 2023-11-14T22:13:20Z (UTC)", data["updated_at"])
+	}
+	// +node-get deliberately does not synthesize a url (get_node returns none;
+	// a BuildResourceURL fallback would be a non-canonical, misleading link in
+	// a read/confirm command).
+	if _, ok := data["url"]; ok {
+		t.Fatalf("did not expect a url field in +node-get output, got %#v", data["url"])
+	}
+	if got := stderr.String(); !strings.Contains(got, "Fetching wiki node") {
+		t.Fatalf("stderr = %q, want fetching message", got)
+	}
+}
+
+func TestWikiNodeGetFallsBackToCreatorWhenNodeCreatorMissing(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"space_id":   "space_123",
+					"node_token": "wikcnABC",
+					"obj_token":  "docxXYZ",
+					"obj_type":   "docx",
+					"node_type":  "origin",
+					"title":      "Fallback Creator",
+					"creator":    "ou_legacy_creator",
+				},
+			},
+			"msg": "success",
+		},
+	})
+
+	err := mountAndRunWiki(t, WikiNodeGet, []string{
+		"+node-get",
+		"--token", "wikcnABC",
+		"--as", "bot",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	if data["creator"] != "ou_legacy_creator" {
+		t.Fatalf("creator = %#v, want fallback to creator field", data["creator"])
+	}
+}
+
+func TestWikiNodeGetRejectsSpaceIDMismatch(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"space_id":   "space_actual",
+					"node_token": "wikcnABC",
+					"obj_token":  "docxXYZ",
+					"obj_type":   "docx",
+					"node_type":  "origin",
+					"title":      "Mismatch",
+				},
+			},
+			"msg": "success",
+		},
+	})
+
+	err := mountAndRunWiki(t, WikiNodeGet, []string{
+		"+node-get",
+		"--token", "wikcnABC",
+		"--space-id", "space_expected",
+		"--as", "bot",
+	}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "does not match the resolved node space") {
+		t.Fatalf("expected space mismatch error, got %v", err)
+	}
+}

shortcuts/wiki/wiki_space_create.go

@@ -0,0 +1,120 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// WikiSpaceCreate wraps wiki.spaces.create. The raw API only takes two
+// optional string fields, so the shortcut's value is flag ergonomics
+// (no hand-written --params JSON), output flattening (data.space.* lifted
+// to the top level), and a dry-run preview.
+//
+// The API only accepts a user access token (no tenant/bot), so AuthTypes is
+// user-only — the framework's CheckIdentity rejects --as bot for us.
+var WikiSpaceCreate = common.Shortcut{
+	Service:     "wiki",
+	Command:     "+space-create",
+	Description: "Create a wiki space",
+	Risk:        "write",
+	// The API accepts wiki:wiki or wiki:space:write_only. The framework's
+	// scope preflight does exact-string matching (see +space-list), so
+	// declare the narrowest form the API takes to avoid false-rejecting
+	// tokens that only carry wiki:space:write_only.
+	Scopes:    []string{"wiki:space:write_only"},
+	AuthTypes: []string{"user"},
+	Flags: []common.Flag{
+		{Name: "name", Desc: "wiki space name", Required: true},
+		{Name: "description", Desc: "wiki space description"},
+	},
+	Tips: []string{
+		"Only --as user is supported; the create API does not accept a tenant/bot token.",
+		"The underlying spaces.create API is flagged danger in the schema browser; a space is recoverable via `wiki +delete-space` if created by mistake.",
+		"--name is required: an unnamed space is almost always an accident and is hard to find later.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := readWikiSpaceCreateSpec(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec, err := readWikiSpaceCreateSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			POST(wikiSpacesAPIPath).
+			Body(spec.RequestBody())
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec, err := readWikiSpaceCreateSpec(runtime)
+		if err != nil {
+			return err
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Creating wiki space %q...\n", spec.Name)
+
+		data, err := runtime.CallAPI("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")
+		}
+
+		out := wikiSpaceCreateOutput(raw)
+		fmt.Fprintf(runtime.IO().ErrOut, "Created wiki space %s\n", common.MaskToken(common.GetString(out, "space_id")))
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+// wikiSpaceCreateSpec is the normalized CLI input.
+type wikiSpaceCreateSpec struct {
+	Name        string
+	Description string
+}
+
+// RequestBody converts the normalized input into the OpenAPI payload. Both
+// fields are optional per the API, but Validate enforces a non-empty name,
+// so name is always present here.
+func (spec wikiSpaceCreateSpec) RequestBody() map[string]interface{} {
+	body := map[string]interface{}{"name": spec.Name}
+	if spec.Description != "" {
+		body["description"] = spec.Description
+	}
+	return body
+}
+
+func readWikiSpaceCreateSpec(runtime *common.RuntimeContext) (wikiSpaceCreateSpec, error) {
+	spec := wikiSpaceCreateSpec{
+		Name:        strings.TrimSpace(runtime.Str("name")),
+		Description: strings.TrimSpace(runtime.Str("description")),
+	}
+	if spec.Name == "" {
+		return wikiSpaceCreateSpec{}, output.ErrValidation("--name is required and cannot be blank")
+	}
+	return spec, nil
+}
+
+// wikiSpaceCreateOutput flattens data.space into the top-level envelope. It
+// reads the raw map (rather than parseWikiSpaceRecord) so the description
+// the caller just set round-trips back in the output.
+func wikiSpaceCreateOutput(raw map[string]interface{}) map[string]interface{} {
+	return map[string]interface{}{
+		"space_id":     common.GetString(raw, "space_id"),
+		"name":         common.GetString(raw, "name"),
+		"description":  common.GetString(raw, "description"),
+		"space_type":   common.GetString(raw, "space_type"),
+		"visibility":   common.GetString(raw, "visibility"),
+		"open_sharing": common.GetString(raw, "open_sharing"),
+	}
+}

shortcuts/wiki/wiki_space_create_test.go

@@ -0,0 +1,207 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestWikiSpaceCreateDeclaredContract(t *testing.T) {
+	t.Parallel()
+
+	if WikiSpaceCreate.Command != "+space-create" {
+		t.Fatalf("Command = %q, want +space-create", WikiSpaceCreate.Command)
+	}
+	if WikiSpaceCreate.Risk != "write" {
+		t.Fatalf("Risk = %q, want write", WikiSpaceCreate.Risk)
+	}
+	if !reflect.DeepEqual(WikiSpaceCreate.AuthTypes, []string{"user"}) {
+		t.Fatalf("AuthTypes = %v, want [user]", WikiSpaceCreate.AuthTypes)
+	}
+	if !reflect.DeepEqual(WikiSpaceCreate.Scopes, []string{"wiki:space:write_only"}) {
+		t.Fatalf("Scopes = %v, want [wiki:space:write_only]", WikiSpaceCreate.Scopes)
+	}
+}
+
+func TestReadWikiSpaceCreateSpecRejectsBlankName(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "wiki +space-create"}
+	cmd.Flags().String("name", "   ", "")
+	cmd.Flags().String("description", "", "")
+
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+	if _, err := readWikiSpaceCreateSpec(runtime); err == nil || !strings.Contains(err.Error(), "--name is required") {
+		t.Fatalf("expected blank-name rejection, got %v", err)
+	}
+}
+
+func TestWikiSpaceCreateRequestBody(t *testing.T) {
+	t.Parallel()
+
+	nameOnly := wikiSpaceCreateSpec{Name: "Eng Wiki"}.RequestBody()
+	if !reflect.DeepEqual(nameOnly, map[string]interface{}{"name": "Eng Wiki"}) {
+		t.Fatalf("name-only body = %#v", nameOnly)
+	}
+
+	full := wikiSpaceCreateSpec{Name: "Eng Wiki", Description: "team docs"}.RequestBody()
+	if full["name"] != "Eng Wiki" || full["description"] != "team docs" {
+		t.Fatalf("full body = %#v", full)
+	}
+}
+
+func TestWikiSpaceCreateDryRun(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "wiki +space-create"}
+	cmd.Flags().String("name", "Eng Wiki", "")
+	cmd.Flags().String("description", "team docs", "")
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+
+	dry := WikiSpaceCreate.DryRun(nil, runtime)
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+	var got struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run: %v", err)
+	}
+	if len(got.API) != 1 || got.API[0].Method != "POST" || got.API[0].URL != "/open-apis/wiki/v2/spaces" {
+		t.Fatalf("dry-run api = %#v", got.API)
+	}
+	if got.API[0].Body["name"] != "Eng Wiki" || got.API[0].Body["description"] != "team docs" {
+		t.Fatalf("dry-run body = %#v", got.API[0].Body)
+	}
+}
+
+func TestWikiSpaceCreateDryRunBlankNameSurfacesError(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "wiki +space-create"}
+	cmd.Flags().String("name", "", "")
+	cmd.Flags().String("description", "", "")
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+
+	dry := WikiSpaceCreate.DryRun(nil, runtime)
+	data, _ := json.Marshal(dry)
+	if !strings.Contains(string(data), "--name is required") {
+		t.Fatalf("dry-run should surface validation error, got %s", data)
+	}
+}
+
+func TestWikiSpaceCreateMountedExecuteFlattensSpace(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, stderr, reg := cmdutil.TestFactory(t, wikiTestConfig())
+
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/wiki/v2/spaces",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"space": map[string]interface{}{
+					"space_id":     "7160145948494381236",
+					"name":         "Eng Wiki",
+					"description":  "team docs",
+					"space_type":   "team",
+					"visibility":   "private",
+					"open_sharing": "closed",
+				},
+			},
+			"msg": "success",
+		},
+	}
+	reg.Register(createStub)
+
+	err := mountAndRunWiki(t, WikiSpaceCreate, []string{
+		"+space-create",
+		"--name", "Eng Wiki",
+		"--description", "team docs",
+		"--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	if data["space_id"] != "7160145948494381236" {
+		t.Fatalf("space_id = %#v", data["space_id"])
+	}
+	if data["name"] != "Eng Wiki" || data["description"] != "team docs" {
+		t.Fatalf("name/description = %#v / %#v", data["name"], data["description"])
+	}
+	if data["space_type"] != "team" || data["visibility"] != "private" || data["open_sharing"] != "closed" {
+		t.Fatalf("space_type/visibility/open_sharing = %#v", data)
+	}
+	if _, ok := data["url"]; ok {
+		t.Fatalf("output must not include a url field, got %#v", data["url"])
+	}
+
+	var captured map[string]interface{}
+	if err := json.Unmarshal(createStub.CapturedBody, &captured); err != nil {
+		t.Fatalf("unmarshal captured body: %v", err)
+	}
+	if captured["name"] != "Eng Wiki" || captured["description"] != "team docs" {
+		t.Fatalf("captured request body = %#v", captured)
+	}
+	if !strings.Contains(stderr.String(), "Created wiki space") {
+		t.Fatalf("stderr = %q, want creation log", stderr.String())
+	}
+}
+
+func TestWikiSpaceCreateRejectsBotIdentity(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, _, _ := cmdutil.TestFactory(t, wikiTestConfig())
+
+	err := mountAndRunWiki(t, WikiSpaceCreate, []string{
+		"+space-create",
+		"--name", "Eng Wiki",
+		"--as", "bot",
+	}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "only supports: user") {
+		t.Fatalf("expected bot identity rejection, got %v", err)
+	}
+}
+
+func TestWikiSpaceCreateErrorsWhenNoSpaceReturned(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/wiki/v2/spaces",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{},
+			"msg":  "success",
+		},
+	})
+
+	err := mountAndRunWiki(t, WikiSpaceCreate, []string{
+		"+space-create",
+		"--name", "Eng Wiki",
+		"--as", "user",
+	}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "returned no space") {
+		t.Fatalf("expected missing-space error, got %v", err)
+	}
+}

shortcuts/wiki/wiki_space_list.go

@@ -15,7 +15,7 @@ import (
 )
 
 const (
-	wikiSpaceListAPIPath         = "/open-apis/wiki/v2/spaces"
+	wikiSpacesAPIPath            = "/open-apis/wiki/v2/spaces"
 	wikiSpaceListDefaultPageSize = 50
 	wikiSpaceListMaxPageSize     = 50
 )
@@ -59,7 +59,7 @@ var WikiSpaceList = common.Shortcut{
 		if wikiListShouldAutoPaginate(runtime) {
 			dry.Desc("Auto-paginates through all pages (capped by --page-limit when > 0)")
 		}
-		return dry.GET(wikiSpaceListAPIPath).Params(params)
+		return dry.GET(wikiSpacesAPIPath).Params(params)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		warnIfConflictingPagingFlags(runtime)
@@ -103,7 +103,7 @@ func fetchWikiSpaces(runtime *common.RuntimeContext) ([]map[string]interface{},
 		if pageToken != "" {
 			params["page_token"] = pageToken
 		}
-		data, err := runtime.CallAPI("GET", wikiSpaceListAPIPath, params, nil)
+		data, err := runtime.CallAPI("GET", wikiSpacesAPIPath, params, nil)
 		if err != nil {
 			return nil, false, "", err
 		}

skill-template/domains/drive.md

@@ -34,6 +34,16 @@
 
 #### 处理流程
 
+**推荐方式：使用 `drive +inspect` 自动解包**
+
+```bash
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
+```
+
+返回结果包含 `type`（底层文档类型）、`token`（真实 file_token）、`title`、`url` 等字段，直接用于后续操作。
+
+**手动方式：使用 `wiki.spaces.get_node` 查询节点信息**
+
 1. **使用 `wiki.spaces.get_node` 查询节点信息**
    ```bash
    lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

skills/lark-base/SKILL.md

@@ -107,8 +107,9 @@ metadata:
 |------|------------------|----------------|----------|
 | `+record-search / +record-list / +record-get` | 按关键词检索记录、读取记录明细 / 分页导出，或按 ID 获取一条或多条记录 | [`lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md) | 记录读取统一先读 data analysis SOP：已知 `record_id` 用 `+record-get`；明确关键词用 `+record-search`；普通明细用 `+record-list`；明确筛选 / 排序 / Top N 用临时视图投影后 `+record-list --view-id`；统计聚合才分流到 `+data-query`；`+record-get` 支持重复 `--record-id` 或 `--json` 读取多条记录 |
 | `+record-upsert / +record-batch-create / +record-batch-update` | 创建、更新或批量写入记录 | [`lark-base-record-upsert.md`](references/lark-base-record-upsert.md)、[`lark-base-record-batch-create.md`](references/lark-base-record-batch-create.md)、[`lark-base-record-batch-update.md`](references/lark-base-record-batch-update.md)、[`lark-base-cell-value.md`](references/lark-base-cell-value.md) | 写前先 `+field-list`；只写存储字段；`+record-batch-update` 为同值更新（同一 patch 应用到多条记录）；批量单次不超过 `200` 条；附件不要走这里 |
-| `+record-upload-attachment` | 给已有记录上传附件 | [`lark-base-record-upload-attachment.md`](references/lark-base-record-upload-attachment.md) | 附件上传专用链路，不要用 `+record-upsert` / `+record-batch-*` 伪造附件值 |
-| `lark-cli docs +media-download` | 下载 Base 附件文件到本地 | [`../lark-doc/references/lark-doc-media-download.md`](../lark-doc/references/lark-doc-media-download.md) | Base 附件的 `file_token` 从 `+record-get` 返回的附件字段数组里取；**不要用 `lark-cli drive +download`**（对 Base 附件返回 403） |
+| `+record-upload-attachment` | 给已有记录上传一个或多个附件 | 看 `lark-cli base +record-upload-attachment --help` | 附件上传专用链路，不要用 `+record-upsert` / `+record-batch-*` 伪造附件值；不支持 `--name` |
+| `+record-download-attachment` | 下载一个或多个 Base 附件到本地 | 看 `lark-cli base +record-download-attachment --help` | Base 附件必须用这个命令下载；用其他下载入口可能失败 |
+| `+record-remove-attachment` | 删除附件字段里的一个或多个附件 | 看 `lark-cli base +record-remove-attachment --help` | 删除操作；确认目标后带 `--yes` |
 | `+record-delete` | 删除一条或多条记录 | [`lark-base-record-delete.md`](references/lark-base-record-delete.md) | 删除多条时重复传 `--record-id` 指定多个记录；用户已明确目标可直接执行并带 `--yes` |
 | `+record-history-list` | 查询指定记录的变更历史 | [`lark-base-record-history-list.md`](references/lark-base-record-history-list.md) | 按 `table-id + record-id` 查询，不支持整表扫描；`+record-history-list` 只能串行执行 |
 | `+record-share-link-create` | 为一条或多条记录生成分享链接 | [`lark-base-record-share-link-create.md`](references/lark-base-record-share-link-create.md) | 单次最多 100 条；重复 record_id 会自动去重；适合分享单条记录或批量分享场景 |
@@ -211,7 +212,7 @@ metadata:
 | 字段类型 | 含义 | 能否直接作为 `+record-upsert / +record-batch-create / +record-batch-update` 写入目标 | 说明 |
 |----------|------|-----------------------------------------------------------|------|
 | 存储字段 | 真实存用户输入的数据 | 可以 | 常见如文本、数字、日期、单选、多选、人员、关联 |
-| 附件字段 | 存储文件附件 | 不应直接按普通字段写 | 上传附件走 `+record-upload-attachment`；下载附件走 `lark-cli docs +media-download` |
+| 附件字段 | 存储文件附件 | 不应直接按普通字段写 | 上传附件走 `+record-upload-attachment`；下载附件走 `+record-download-attachment`；删除附件走 `+record-remove-attachment` |
 | 系统字段 | 平台自动维护 | 不可以 | 常见如创建时间、更新时间、创建人、修改人、自动编号 |
 | `formula` 字段 | 通过表达式计算 | 不可以 | 只读字段 |
 | `lookup` 字段 | 通过跨表规则查找引用 | 不可以 | 只读字段 |
@@ -225,7 +226,7 @@ metadata:
 | 用户明确要求 lookup，或天然是固定查找配置 | `lookup` 字段 | 不要默认先上 lookup；先判断 formula 是否更合适 |
 | 读取原始记录明细 / 关键词检索 / 导出 | `+record-search / +record-list / +record-get` | 不要拿 `+data-query` 当取数命令 |
 | 上传附件到记录 | `+record-upload-attachment` | 不要用 `+record-upsert` / `+record-batch-*` 伪造附件值 |
-| 下载记录里的附件文件 | `lark-cli docs +media-download --token <file_token> --output <path>` | `file_token` 从 `+record-get` 返回的附件字段里取；用法见 [`../lark-doc/references/lark-doc-media-download.md`](../lark-doc/references/lark-doc-media-download.md) |
+| 下载记录里的附件文件 | `+record-download-attachment --record-id <record_id> --output <dir>`，可加 `--file-token <file_token>` 只下指定附件 | Base 附件必须用这个命令下载；用其他下载入口可能失败 |
 | 基于视图做筛选读取 | `+view-set-filter` + `+record-list` | 不要跳过视图筛选直接猜条件 |
 | 本地 Excel / CSV / `.base` 导入为 Base | `lark-cli drive +import --type bitable` | 不要误走 `+base-create`、`+table-create` 或 `+record-upsert` |
 

skills/lark-base/references/lark-base-cell-value.md

@@ -119,9 +119,9 @@
 
 ### 2.9 attachment（不作为普通 CellValue 写入）
 
-用户要把本地文件加到记录里时，必须使用 `lark-cli base +record-upload-attachment --file <path>` 上传到已有记录。不能用普通记录操作接口来上传附件。
-
-`+record-get` 返回的附件字段单元格包含 `file_token` 和文件名，可以把 `file_token` 交给 `lark-cli docs +media-download` 进行附件下载。
+- 追加附件：使用 `lark-cli base +record-upload-attachment --record-id <record_id> --field-id <field_id> --file <path>`；可重复 `--file` 一次追加多个附件，不能用普通记录操作接口写附件值。
+- 删除附件：使用 `lark-cli base +record-remove-attachment --record-id <record_id> --field-id <field_id> --file-token <file_token> --yes`；可重复 `--file-token` 一次删除同一单元格里的多个附件。
+- 下载附件：使用 `lark-cli base +record-download-attachment --record-id <record_id> --file-token <file_token> --output <dir>`；不传 `--file-token` 时下载整行所有附件，也可重复 `--file-token` 只下载指定附件。Base 附件必须用这个命令下载，用其他下载入口可能失败。
 
 ## 3. 只读字段（不要写）
 

skills/lark-base/references/lark-base-record-upload-attachment.md

@@ -1,50 +0,0 @@
-# base +record-upload-attachment
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-上传本地文件到当前 Base，并把附件值写入指定记录的附件字段。
-
-## 推荐命令
-
-```bash
-lark-cli base +record-upload-attachment \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --record-id <record_id> \
-  --field-id <field_id> \
-  --file ./report.pdf
-
-lark-cli base +record-upload-attachment \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --record-id <record_id> \
-  --field-id "附件" \
-  --file ./report.pdf \
-  --name "Q1-final.pdf"
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token |
-| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
-| `--record-id <id>` | 是 | 记录 ID |
-| `--field-id <id_or_name>` | 是 | 附件字段 ID 或字段名 |
-| `--file <path>` | 是 | 本地文件路径，最大 2GB |
-| `--name <name>` | 否 | 写入附件字段时显示的文件名，默认使用本地文件名 |
-
-
-## 工作流
-
-> [!CAUTION]
-> 这是写入操作。用户已经明确要上传到某条记录的某个附件字段时可直接执行；如果 `record-id` 或目标字段仍有歧义，再先确认。
-
-## 坑点
-
-- ⚠️ 目标字段必须是 `attachment` 字段。
-- ⚠️ 记录里的附件 `file_token` 属于 Drive media token；下载时不要走 `lark-cli drive +download`，应使用 `lark-cli docs +media-download --token <file_token> --output <path>`。
-
-## 参考
-
-- [lark-base-record.md](lark-base-record.md) — record 索引页

skills/lark-base/references/lark-base-record.md

@@ -12,8 +12,9 @@ record 相关命令索引。
 | [lark-base-record-upsert.md](lark-base-record-upsert.md) | `+record-upsert` | 创建或更新记录 |
 | [lark-base-record-batch-create.md](lark-base-record-batch-create.md) | `+record-batch-create` | 按 `fields/rows` 批量创建记录 |
 | [lark-base-record-batch-update.md](lark-base-record-batch-update.md) | `+record-batch-update` | 批量更新记录 |
-| [lark-base-record-upload-attachment.md](lark-base-record-upload-attachment.md) | `+record-upload-attachment` | 上传本地文件到附件字段并更新记录 |
-| [`../../lark-doc/references/lark-doc-media-download.md`](../../lark-doc/references/lark-doc-media-download.md) | `lark-cli docs +media-download` | 下载 Base 附件到本地（附件的 `file_token` 来自 `+record-get` 的附件字段） |
+| `--help` | `+record-upload-attachment` | 上传一个或多个本地文件到附件字段 |
+| `--help` | `+record-download-attachment` | 下载一个或多个 Base 附件到本地；Base 附件必须用这个命令下载 |
+| `--help` | `+record-remove-attachment` | 删除附件字段中的一个或多个附件 |
 | [lark-base-record-delete.md](lark-base-record-delete.md) | `+record-delete` | 删除一条或多条记录 |
 | [lark-base-record-share-link-create.md](lark-base-record-share-link-create.md) | `+record-share-link-create` | 生成记录分享链接（支持单条或批量，最多 100 条）|
 
@@ -25,5 +26,6 @@ record 相关命令索引。
 - `+record-list` 支持重复传参 `--field-id` 做字段筛选。
 - `+record-get` 支持重复 `--record-id` 或 `--json '{"record_id_list":[...]}'` 批量读取；也支持重复传参 `--field-id` 裁剪返回字段，避免返回全字段。
 - 写记录 JSON 前优先阅读 [lark-base-cell-value.md](lark-base-cell-value.md)。
-- 本地文件写入附件字段时，必须使用 `+record-upload-attachment`。
-- 从附件字段下载文件时，用 `lark-cli docs +media-download --token <file_token> --output <path>`，用法见 [`../../lark-doc/references/lark-doc-media-download.md`](../../lark-doc/references/lark-doc-media-download.md)。
+- 本地文件写入一个或多个附件字段时，必须使用 `+record-upload-attachment`。
+- 从附件字段下载一个或多个文件时，用 `+record-download-attachment`。
+- 删除附件字段里的文件时，用 `+record-remove-attachment --yes`。

skills/lark-drive/SKILL.md

@@ -51,6 +51,16 @@ metadata:
 
 #### 处理流程
 
+**推荐方式：使用 `drive +inspect` 自动解包**
+
+```bash
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
+```
+
+返回结果包含 `type`（底层文档类型）、`token`（真实 file_token）、`title`、`url` 等字段，直接用于后续操作。
+
+**手动方式：使用 `wiki.spaces.get_node` 查询节点信息**
+
 1. **使用 `wiki.spaces.get_node` 查询节点信息**
    ```bash
    lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
@@ -259,6 +269,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+delete`](references/lark-drive-delete.md) | Delete a Drive file or folder with limited polling for folder deletes |
 | [`+push`](references/lark-drive-push.md) | File-level local → Drive mirror. Duplicate remote `rel_path` conflicts fail by default; `newest` / `oldest` only apply to duplicate files when you explicitly want to target one remote file. `--if-exists` supports `skip` / `smart` / `overwrite` (`smart` skips files whose remote `modified_time` is already up to date, but falls through to the same overwrite path when the remote is older, so it inherits overwrite's rollout caveat). `--delete-remote` requires `--yes`. `--local-dir` must stay inside cwd. |
 | [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations |
+| [`+inspect`](references/lark-drive-inspect.md) | Inspect a Lark document URL to get its type, title, and canonical token; auto-unwraps wiki URLs to the underlying document |
 | [`+apply-permission`](references/lark-drive-apply-permission.md) | Apply to the document owner for view/edit access (user-only; 5/day per document) |
 
 ## API Resources

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

@@ -150,8 +150,6 @@ lark-cli drive +add-comment \
 - `type=text` 的评论文本不能直接包含 `<`、`>`；应优先传 `&lt;`、`&gt;`。shortcut 在发送前也会自动将 `<`、`>` 转义为 `&lt;`、`&gt;` 作为兜底。
 - **所有 `type=text` 元素的字符总和 ≤ 10000**（按字符算，中英文 / 符号一视同仁）。超过会被 shortcut 在发送前拒绝，并指出累计超长的元素。**拆成多个 text element 不能绕过这个上限**——上限是总额，不是每元素。需要更长内容就缩短或拆成多条评论。
 - 长度限制只对 `type=text` 生效，`mention_user` / `link` 不计入。
-- 局部评论走 `locate-doc` 时，内部固定使用 `limit=10`。
-- 当 `locate-doc` 命中多处时，shortcut 会中止并提示用户继续收窄 `--selection-with-ellipsis`，不支持手动指定匹配序号。
 - 写入评论前会自动生成符合 OpenAPI 定义的请求体：
   - 统一接口：`POST /new_comments`
   - 统一字段：`file_type` + `reply_elements`

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

@@ -25,8 +25,8 @@ lark-cli drive +export \
   --doc-type doc \
   --file-extension docx
 
-# 导出 docx 为 markdown
-# 注意：markdown 只支持 docx，底层走 /open-apis/docs/v1/content
+# 导出 docx 为 markdown（Lark-flavored Markdown）
+# 注意：markdown 只支持 docx
 lark-cli drive +export \
   --token "<DOCX_TOKEN>" \
   --doc-type docx \

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

@@ -0,0 +1,50 @@
+
+# drive +inspect（文档 URL 检视：类型、标题、Token 解析）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+给定一个飞书文档 URL 或 bare token，返回其类型、标题和 canonical token。对 wiki URL 自动解包到底层文档。
+
+## 命令
+
+```bash
+# 检视一个 docx URL
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/docx/doxcnXXX'
+
+# 检视一个 wiki URL（自动解包到底层文档）
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
+
+# bare token 需要指定 --type
+lark-cli drive +inspect --url doxcnXXX --type docx
+
+# 格式化输出
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/base/bascnXXX' --format pretty
+```
+
+## 输出
+
+JSON 输出包含以下字段：
+
+| 字段 | 说明 |
+|------|------|
+| `input_url` | 原始输入 URL |
+| `type` | 文档类型（docx, doc, sheet, bitable, wiki, file, folder, mindnote, slides） |
+| `title` | 文档标题 |
+| `token` | canonical file token |
+| `url` | 重建的 canonical URL |
+| `wiki_node` | 仅 wiki URL：包含 `space_id`, `node_token`, `obj_token`, `obj_type` |
+
+## 典型场景
+
+| 场景 | 命令 |
+|------|------|
+| 用户给了一个 URL，想知道它是什么类型的文档 | `lark-cli drive +inspect --url '<url>'` |
+| wiki 链接需要拿到底层文档的 token 来做后续操作 | `lark-cli drive +inspect --url '<wiki_url>'`，取输出中的 `token` |
+| 只有 token 没有 URL | `lark-cli drive +inspect --url <token> --type <type>` |
+
+## 注意事项
+
+- `--url` 为必填参数
+- 当 `--url` 是 bare token（非完整 URL）时，`--type` 也是必填的
+- wiki URL 会自动调用 `get_node` API 解包，输出中 `type` 和 `token` 是底层文档的类型和 token
+- 支持 `--dry-run` 查看将调用的 API 步骤

skills/lark-im/references/lark-im-chat-messages-list.md

@@ -135,6 +135,12 @@ lark-cli api GET /open-apis/im/v1/messages \
 4. **For time ranges:** both ISO 8601 and date-only inputs are supported. Date-only is usually simpler.
 5. **For full content:** table output truncates content. Use `--format json` when you need the complete message body.
 6. **For sender info:** the command already resolves sender names, so you do not need a separate lookup.
+7. **Application/bot identity + named group history:** If the user says "使用应用身份/以 bot 身份" and asks to list or read historical messages for a named group, use bot identity for both steps:
+   ```bash
+   lark-cli im +chat-search --as bot --query "<chat name keyword>" --format json
+   lark-cli im +chat-messages-list --as bot --chat-id <chat_id> --page-size 50 --format json
+   ```
+   Do not use `im +messages-search --as bot`; `+messages-search` is user-only. Continue with `--page-token` if `has_more=true`.
 
 ## References
 

skills/lark-im/references/lark-im-messages-search.md

@@ -156,6 +156,21 @@ Use `im +messages-resources-download` if you need to fetch the underlying image
 
 ## AI Usage Guidance
 
+### Query boundary for activity review
+
+Use `--query` only for real message keywords. If the user asks for activity review such as "最近一周我和哪些 Bot 有过交互" or "整理我和某人的聊天记录", and the useful constraints are sender type, chat, person, or time range, keep `--query ""` and rely on those filters. Do not put generic instruction words such as "看看", "总结", "交互内容", or "聊天记录" into `--query`; those words often over-constrain message search and hide the relevant messages.
+
+This guidance applies only when using user identity. `im +messages-search` is user-only; if the user explicitly asks for application/bot identity, do not try `--as bot`. For bot identity with a named group and history/listing intent, resolve the group with `im +chat-search --as bot`, then list messages with `im +chat-messages-list --as bot --chat-id <chat_id>`.
+
+```bash
+# Review recent bot interactions without forcing a keyword
+lark-cli im +messages-search --query "" --sender-type bot --start "<YYYY-MM-DDT00:00:00+08:00>" --end "<YYYY-MM-DDT23:59:59+08:00>" --page-all --format json
+```
+
+Replace the time placeholders at execution time. For example, "最近一周" means computing the start date and end date from the current day before running the command; do not copy date literals from this reference into answers for relative requests.
+
+For activity summaries, validate evidence by message IDs and chat context. The final answer should cite or retain the `message_id`, sender, chat, and create time for each important item. If the row's source data contains concrete `om_...` message IDs or `ou_...` user IDs, treat those IDs as strong recall targets during verification; do not rely only on a high-level keyword match.
+
 ### Resolving chat_id from a chat name
 
 When the user refers to a chat by name and you need its `chat_id` for the `--chat-id` filter, use [`+chat-search`](lark-im-chat-search.md) first:

skills/lark-vc/references/lark-vc-search.md

@@ -7,6 +7,12 @@
 
 本 skill 对应 shortcut：`lark-cli vc +search`（调用 `POST /open-apis/vc/v1/meetings/search`）。
 
+## 关键词使用边界
+
+`--query` 只用于真实会议关键词，例如会议主题、项目名、评审名、客户名。用户只是说"我这月参加的所有视频会议"、"最近两周我组织的所有视频会议"、"总结主要议题 / 看看参会情况"时，本质是历史会议列表和后续总结，不要把"回顾"、"所有视频会议"、"总结主要议题"等动作词放进 `--query`。这类请求应先用时间范围 + `--participant-ids` / `--organizer-ids` 搜全量候选，再按结果继续取纪要或录制信息。
+
+列表阶段只负责找会议记录；总结阶段必须继续取证。若用户要求"主要议题"、"主要决策"、"参会情况"，先确认搜索结果的 `meeting_id`、时间、组织者/参与者符合过滤条件，然后用 `vc +notes` 或 `vc +recording` / `minutes` 读取纪要、妙记或录制信息。没有纪要或妙记时，如实说明只能基于会议标题/参会数据汇总，不要编造议题。
+
 ## 典型触发表达
 
 以下说法通常应优先使用 `vc +search`：
@@ -42,6 +48,12 @@ lark-cli vc +search --organizer-ids "ou_a,ou_b"
 # 按参与者过滤（open_id，逗号分隔）
 lark-cli vc +search --participant-ids "ou_x,ou_y"
 
+# 查询我这个月参加过的历史会议，不带关键词
+lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --participant-ids "ou_me"
+
+# 查询最近两周我组织的历史会议，不带关键词
+lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --organizer-ids "ou_me"
+
 # 按会议室过滤
 lark-cli vc +search --room-ids "123,456"
 
@@ -76,6 +88,10 @@ lark-cli vc +search --query "周会" --format json
 
 所有参数均可选，但必须至少提供一个过滤条件：`--query`、`--start`、`--end`、`--organizer-ids`、`--participant-ids` 或 `--room-ids`。
 
+没有真实关键词时，时间范围或人员过滤已经满足这个约束，`--query` 可以省略。
+
+涉及"本月"、"最近两周"这类相对时间时，先基于执行当天计算 `"<YYYY-MM-DD>"` 占位符，再运行命令；不要沿用文档示例生成时的具体日期。
+
 ### 2. 仅搜索历史会议
 
 `vc +search` 只能搜索已结束的历史会议记录，不用于查询未来日程。查询未来会议安排请使用 [lark-calendar](../../lark-calendar/SKILL.md)。
@@ -128,7 +144,8 @@ lark-cli vc +search --query "周会" --format json
 - 当结果中返回 `has_more=true` 时，说明还有更多页可继续获取。
 - 继续翻页时，使用响应中的 `page_token` 搭配 `--page-token` 发起下一次查询。
 - 不要假设调大 `--page-size` 就能拿全结果；分页遍历时应以 `has_more` 和 `page_token` 为准。
-- `total` 数量小于 50 时，自动分页获取所有结果；`total` 数量大于 50 时，向用户确认是否获取全部结果。
+- 未明确要求全量时，`total` 数量小于 50 可自动分页获取所有结果；`total` 数量大于 50 时，先向用户确认是否继续获取全部结果。
+- 用户明确说"所有 / 全部 / 统计 / 按时间排序"时，该全量意图优先于 `total > 50` 的确认门槛；直接完成分页和去重，再排序或统计，不要只用第一页回答。
 
 ```bash
 # First page

skills/lark-wiki/SKILL.md

@@ -62,8 +62,11 @@ Shortcut 是对常用操作的高级封装（`lark-cli wiki +<verb> [flags]`）
 | [`+node-create`](references/lark-wiki-node-create.md) | Create a wiki node with automatic space resolution |
 | [`+delete-space`](references/lark-wiki-delete-space.md) | Delete a wiki space, polling the async delete task when needed |
 | [`+space-list`](references/lark-wiki-space-list.md) | List all wiki spaces accessible to the caller |
+| [`+space-create`](references/lark-wiki-space-create.md) | Create a wiki space (user identity only) |
 | [`+node-list`](references/lark-wiki-node-list.md) | List wiki nodes in a space or under a parent node (supports pagination) |
 | [`+node-copy`](references/lark-wiki-node-copy.md) | Copy a wiki node to a target space or parent node |
+| [`+node-get`](references/lark-wiki-node-get.md) | Get a wiki node's details by node_token / obj_token / Lark URL |
+| [`+node-delete`](references/lark-wiki-node-delete.md) | Delete a wiki node, polling the async delete task when needed |
 
 ## API Resources
 

skills/lark-wiki/references/lark-wiki-node-delete.md

@@ -0,0 +1,62 @@
+# lark-wiki +node-delete
+
+Delete a wiki node (or pull a cloud doc out of Wiki). OpenAPI: `DELETE /open-apis/wiki/v2/spaces/:space_id/nodes/:node_token`.
+
+> ⚠️ **High-risk write & irreversible** — deletes the node and (by default) its whole subtree. Requires explicit `--yes`; without it the CLI returns a `confirmation_required` error and nothing is deleted.
+
+- **Sync / async**: an empty `task_id` means the delete completed synchronously (`ready=true`). A non-empty `task_id` triggers bounded polling; if the window elapses the output carries `timed_out=true` and a `next_command`:
+  `lark-cli drive +task_result --scenario wiki_delete_node --task-id <TASK_ID> --as <user|bot>`
+
+## Usage
+
+```bash
+lark-cli wiki +node-delete \
+  --node-token <node_token | obj_token | Lark URL> \
+  [--obj-type <wiki|doc|docx|sheet|bitable|mindnote|slides|file>] \
+  [--space-id <space_id>] \
+  [--include-children=true|false] \
+  --yes \
+  [--as user|bot]
+
+# Preview the call chain without deleting
+lark-cli wiki +node-delete --node-token <token> --obj-type wiki --dry-run
+```
+
+## Flags
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--node-token` | string | **Yes** | — | `node_token`, cloud-doc `obj_token`, or a Lark URL embedding one; URL paths also imply `--obj-type` |
+| `--obj-type` | enum | Conditional | — | Required for a raw token (URL inputs auto-infer). `wiki` = the token is a `node_token`; otherwise the cloud-doc type |
+| `--space-id` | string | No | — | Auto-resolved via `get_node` when omitted (extra lookup; pass it to skip) |
+| `--include-children` | bool | No | `true` | Cascade-delete the subtree (default). `--include-children=false` lifts direct children up to the parent |
+| `--yes` | bool | Yes (real delete) | — | Confirm the high-risk operation. Without it the CLI returns `confirmation_required` |
+| `--as` | enum | No | `auto` | Identity `user`/`bot`; wiki is user-centric → pass `--as user` |
+
+## Output
+
+```json
+{
+  "space_id": "7160145948494381236",
+  "node_token": "wikcnEXAMPLE",
+  "obj_type": "wiki",
+  "include_children": true,
+  "ready": true,
+  "failed": false,
+  "status": "success",
+  "status_msg": "success"
+}
+```
+
+Async/timeout adds `task_id`, `timed_out`, and `next_command`.
+
+## Behavior
+
+- **Task poll**: `GET /open-apis/wiki/v2/tasks/{task_id}?task_type=delete_node`. The status lives under `data.task.simple_task_result.status` (the gateway's generic key — **not** `delete_node_result`); that object has no `status_msg`, so the label falls back to the status code.
+- **Error hints**:
+  - `131011` → the node has delete-approval enabled; apply via the Wiki UI (CLI cannot bypass approval).
+  - `131003` → subtree too large to cascade-delete; use `--include-children=false` or delete sub-trees first.
+
+## Required Scope
+
+`wiki:node:create` (the delete endpoint declares this scope). Auto-resolving `space_id` additionally needs `wiki:node:retrieve`; pass `--space-id` to avoid that lookup.

skills/lark-wiki/references/lark-wiki-node-get.md

@@ -0,0 +1,56 @@
+# lark-wiki +node-get
+
+Get a wiki node's details by `node_token`, `obj_token`, or a Lark URL. Use this as the "what am I about to touch?" step before `+move` / `+node-copy` / `+node-delete`.
+
+## Usage
+
+```bash
+lark-cli wiki +node-get \
+  --token <node_token | obj_token | Lark URL> \
+  [--obj-type <doc|docx|sheet|bitable|mindnote|slides|file>] \
+  [--space-id <space_id>] \
+  [--format json|pretty|table|csv|ndjson] \
+  [--as user|bot]
+```
+
+## Flags
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--token` | string | **Yes** | — | `node_token`, cloud-doc `obj_token`, or a Lark URL embedding one (e.g. `https://feishu.cn/wiki/<token>` or `https://feishu.cn/docx/<token>`) |
+| `--obj-type` | enum | No | — | Needed when `--token` is a raw `obj_token`; auto-inferred from the URL path. Not allowed when the token looks like a `node_token` (`wik...`) |
+| `--space-id` | string | No | — | Optional cross-check: fail if the resolved node does not live in this space |
+| `--format` | enum | No | `json` | `json` / `pretty` / `table` / `csv` / `ndjson` |
+| `--as` | enum | No | `auto` | Identity `user`/`bot`; wiki is user-centric → pass `--as user` |
+
+## Output
+
+```json
+{
+  "space_id": "7160145948494381236",
+  "node_token": "wikcnEXAMPLE",
+  "obj_token": "docxEXAMPLE",
+  "obj_type": "docx",
+  "node_type": "origin",
+  "parent_node_token": "wikcnPARENT",
+  "origin_node_token": "",
+  "title": "Design Spec",
+  "has_child": true,
+  "creator": "ou_xxx",
+  "owner": "ou_yyy",
+  "obj_edit_time": "1700000000",
+  "obj_create_time": "1690000000",
+  "node_create_time": "1690000001",
+  "updated_at": "2023-11-14T22:13:20Z"
+}
+```
+
+## Notes
+
+- The underlying API is `GET /open-apis/wiki/v2/spaces/get_node`. For a `node_token` no `obj_type` is sent; for an `obj_token` the `obj_type` (explicit or URL-inferred) is required.
+- `creator` falls back to `creator` when `node_creator` is absent. `updated_at` is `obj_edit_time` formatted as RFC3339.
+- No `url` is returned: `get_node` does not provide one and a synthesized `www.feishu.cn/wiki/<node_token>` link is non-canonical/misleading for a read command. Use `node_token` / `obj_token` as the identifiers.
+
+## Required Scope
+
+`wiki:node:retrieve`

skills/lark-wiki/references/lark-wiki-space-create.md

@@ -0,0 +1,46 @@
+# lark-wiki +space-create
+
+Create a wiki space. OpenAPI: `POST /open-apis/wiki/v2/spaces`. This is the project-initialization entry point — the alternative is hand-writing `wiki spaces create --params '{...}'`.
+
+> The underlying `spaces.create` API is flagged `danger: true` in the schema browser, but it is **not** confirmation-gated (no `--yes`). A space created by mistake is recoverable via `wiki +delete-space`.
+
+## Usage
+
+```bash
+lark-cli wiki +space-create \
+  --name <space_name> \
+  [--description <text>] \
+  [--as user]
+```
+
+## Flags
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--name` | string | **Yes** | — | Wiki space name. Blank/whitespace is rejected (an unnamed space is almost always an accident) |
+| `--description` | string | No | — | Wiki space description |
+| `--as` | enum | No | `user` | **User identity only** — the create API does not accept a tenant/bot token; `--as bot` is rejected upfront |
+
+## Output
+
+```json
+{
+  "space_id": "7160145948494381236",
+  "name": "Engineering Wiki",
+  "description": "team docs",
+  "space_type": "team",
+  "visibility": "private",
+  "open_sharing": "closed"
+}
+```
+
+There is no `url` field — the create API does not return one.
+
+## Notes
+
+- Only `--as user` is supported; this command declares `AuthTypes: ["user"]` and the framework rejects `--as bot` with a clear message.
+- `--dry-run` previews the `POST /open-apis/wiki/v2/spaces` request (and surfaces the blank-name validation error early).
+
+## Required Scope
+
+`wiki:space:write_only`

tests/cli_e2e/base/base_attachment_dryrun_test.go

@@ -0,0 +1,121 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+func TestBase_AttachmentDryRun(t *testing.T) {
+	setBaseDryRunConfigEnv(t)
+
+	workDir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(workDir, "report.txt"), []byte("hello"), 0o600))
+	require.NoError(t, os.Mkdir(filepath.Join(workDir, "downloads"), 0o700))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	t.Run("upload", func(t *testing.T) {
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"base", "+record-upload-attachment",
+				"--base-token", "app_x",
+				"--table-id", "tbl_x",
+				"--record-id", "rec_x",
+				"--field-id", "fld_att",
+				"--file", "report.txt",
+				"--dry-run",
+			},
+			WorkDir:   workDir,
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		out := result.Stdout
+		require.Equal(t, "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields/fld_att", gjson.Get(out, "api.0.url").String(), out)
+		require.Equal(t, "/open-apis/drive/v1/medias/upload_all", gjson.Get(out, "api.1.url").String(), out)
+		require.Equal(t, "/open-apis/base/v3/bases/app_x/tables/tbl_x/append_attachments", gjson.Get(out, "api.2.url").String(), out)
+		require.Equal(t, "<uploaded_file_token>", gjson.Get(out, "api.2.body.attachments.rec_x.fld_att.0.file_token").String(), out)
+	})
+
+	t.Run("download", func(t *testing.T) {
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"base", "+record-download-attachment",
+				"--base-token", "app_x",
+				"--table-id", "tbl_x",
+				"--record-id", "rec_x",
+				"--file-token", "box_a",
+				"--output", "downloads",
+				"--dry-run",
+			},
+			WorkDir:   workDir,
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		out := result.Stdout
+		require.Equal(t, "/open-apis/base/v3/bases/app_x/tables/tbl_x/get_attachments", gjson.Get(out, "api.0.url").String(), out)
+		require.Equal(t, "/open-apis/drive/v1/medias/%3Cfile_token%3E/download", gjson.Get(out, "api.1.url").String(), out)
+		require.Equal(t, "<extra_info_if_present>", gjson.Get(out, "api.1.params.extra").String(), out)
+	})
+
+	t.Run("download all", func(t *testing.T) {
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"base", "+record-download-attachment",
+				"--base-token", "app_x",
+				"--table-id", "tbl_x",
+				"--record-id", "rec_x",
+				"--output", "downloads",
+				"--dry-run",
+			},
+			WorkDir:   workDir,
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		out := result.Stdout
+		require.Equal(t, "/open-apis/base/v3/bases/app_x/tables/tbl_x/get_attachments", gjson.Get(out, "api.0.url").String(), out)
+		require.Equal(t, "/open-apis/drive/v1/medias/%3Cfile_token%3E/download", gjson.Get(out, "api.1.url").String(), out)
+	})
+
+	t.Run("remove", func(t *testing.T) {
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"base", "+record-remove-attachment",
+				"--base-token", "app_x",
+				"--table-id", "tbl_x",
+				"--record-id", "rec_x",
+				"--field-id", "fld_att",
+				"--file-token", "box_a",
+				"--dry-run",
+			},
+			WorkDir:   workDir,
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		out := result.Stdout
+		require.Equal(t, "/open-apis/base/v3/bases/app_x/tables/tbl_x/remove_attachments", gjson.Get(out, "api.0.url").String(), out)
+		require.Equal(t, "box_a", gjson.Get(out, "api.0.body.attachments.rec_x.fld_att.0.file_token").String(), out)
+	})
+}
+
+func setBaseDryRunConfigEnv(t *testing.T) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_APP_ID", "base_dryrun_test")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "base_dryrun_secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+}

tests/cli_e2e/base/coverage.md

@@ -54,7 +54,9 @@
 | ✕ | base +record-history-list | shortcut |  | none | record workflows not covered |
 | ✕ | base +record-list | shortcut |  | none | record workflows not covered |
 | ✕ | base +record-search | shortcut |  | none | record workflows not covered |
-| ✕ | base +record-upload-attachment | shortcut |  | none | record workflows not covered |
+| ✓ | base +record-upload-attachment | shortcut | base_attachment_dryrun_test.go::TestBase_AttachmentDryRun/upload | dry-run only | request shape only |
+| ✓ | base +record-download-attachment | shortcut | base_attachment_dryrun_test.go::TestBase_AttachmentDryRun/download | dry-run only | request shape only |
+| ✓ | base +record-remove-attachment | shortcut | base_attachment_dryrun_test.go::TestBase_AttachmentDryRun/remove | dry-run only | request shape only |
 | ✕ | base +record-upsert | shortcut |  | none | record workflows not covered |
 | ✓ | base +role-create | shortcut | base/helpers_test.go::createRole | `--base-token`; `--json` | helper asserts created role id |
 | ✕ | base +role-delete | shortcut |  | none | cleanup only |

tests/cli_e2e/base/helpers_test.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/larksuite/cli/tests/cli_e2e/drive"
 	"github.com/stretchr/testify/require"
 	"github.com/tidwall/gjson"
 )
@@ -83,9 +84,11 @@ func isCleanupSuppressedResult(result *clie2e.Result) bool {
 func createBaseWithRetry(t *testing.T, ctx context.Context, name string) string {
 	t.Helper()
 
+	const defaultAs = "bot"
+
 	result, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
 		Args:      []string{"base", "+base-create", "--name", name, "--time-zone", "Asia/Shanghai"},
-		DefaultAs: "bot",
+		DefaultAs: defaultAs,
 	}, clie2e.RetryOptions{})
 	require.NoError(t, err)
 	result.AssertExitCode(t, 0)
@@ -96,6 +99,13 @@ func createBaseWithRetry(t *testing.T, ctx context.Context, name string) string
 		baseToken = gjson.Get(result.Stdout, "data.base.base_token").String()
 	}
 	require.NotEmpty(t, baseToken, "stdout:\n%s", result.Stdout)
+	t.Cleanup(func() {
+		cleanupCtx, cancel := clie2e.CleanupContext()
+		defer cancel()
+
+		deleteResult, deleteErr := drive.DeleteDriveResourceAndVerify(cleanupCtx, baseToken, "bitable", defaultAs)
+		clie2e.ReportCleanupFailure(t, "delete base "+baseToken, deleteResult, deleteErr)
+	})
 	return baseToken
 }
 

tests/cli_e2e/docs/docs_create_fetch_test.go

@@ -9,7 +9,7 @@ import (
 	"time"
 
 	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	drivee2e "github.com/larksuite/cli/tests/cli_e2e/drive"
+	"github.com/larksuite/cli/tests/cli_e2e/drive"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"github.com/tidwall/gjson"
@@ -26,11 +26,12 @@ func TestDocs_CreateAndFetchWorkflowAsBot(t *testing.T) {
 	docTitle := "lark-cli-e2e-docs-" + suffix
 	docContent := "# Test Document\n\nThis document was created by lark-cli e2e test."
 
-	folderToken := drivee2e.CreateDriveFolder(t, parentT, ctx, folderName, "bot", "")
+	const defaultAs = "bot"
+	folderToken := drive.CreateDriveFolder(t, parentT, ctx, folderName, defaultAs, "")
 	var docToken string
 
 	t.Run("create", func(t *testing.T) {
-		docToken = createDocWithRetry(t, parentT, ctx, folderToken, docTitle, docContent, "bot")
+		docToken = createDocWithRetry(t, parentT, ctx, folderToken, docTitle, docContent, defaultAs)
 	})
 
 	t.Run("fetch", func(t *testing.T) {
@@ -61,10 +62,11 @@ func TestDocs_CreateAndFetchWorkflowAsUser(t *testing.T) {
 	docTitle := "lark-cli-e2e-user-docs-" + suffix
 	docContent := "# User Test Document\n\nCreated with user access token."
 	var docToken string
-	folderToken := drivee2e.CreateDriveFolder(t, parentT, ctx, folderName, "user", "")
+	const defaultAs = "user"
+	folderToken := drive.CreateDriveFolder(t, parentT, ctx, folderName, defaultAs, "")
 
 	t.Run("create as user", func(t *testing.T) {
-		docToken = createDocWithRetry(t, parentT, ctx, folderToken, docTitle, docContent, "user")
+		docToken = createDocWithRetry(t, parentT, ctx, folderToken, docTitle, docContent, defaultAs)
 	})
 
 	t.Run("fetch as user", func(t *testing.T) {
@@ -72,7 +74,7 @@ func TestDocs_CreateAndFetchWorkflowAsUser(t *testing.T) {
 
 		result, err := clie2e.RunCmd(ctx, clie2e.Request{
 			Args:      []string{"docs", "+fetch", "--doc", docToken},
-			DefaultAs: "user",
+			DefaultAs: defaultAs,
 		})
 		require.NoError(t, err)
 		result.AssertExitCode(t, 0)

tests/cli_e2e/docs/docs_update_test.go

@@ -9,7 +9,7 @@ import (
 	"time"
 
 	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	drivee2e "github.com/larksuite/cli/tests/cli_e2e/drive"
+	"github.com/larksuite/cli/tests/cli_e2e/drive"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"github.com/tidwall/gjson"
@@ -27,12 +27,13 @@ func TestDocs_UpdateWorkflow(t *testing.T) {
 	updatedTitle := "lark-cli-e2e-update-updated-" + suffix
 	originalContent := "# Original\n\nThis is the original content."
 	updatedContent := "# Updated\n\nThis is the updated content."
+	const defaultAs = "bot"
 
-	folderToken := drivee2e.CreateDriveFolder(t, parentT, ctx, folderName, "bot", "")
+	folderToken := drive.CreateDriveFolder(t, parentT, ctx, folderName, defaultAs, "")
 	var docToken string
 
 	t.Run("create as bot", func(t *testing.T) {
-		docToken = createDocWithRetry(t, parentT, ctx, folderToken, originalTitle, originalContent, "bot")
+		docToken = createDocWithRetry(t, parentT, ctx, folderToken, originalTitle, originalContent, defaultAs)
 	})
 
 	t.Run("update-title-and-content as bot", func(t *testing.T) {
@@ -46,7 +47,7 @@ func TestDocs_UpdateWorkflow(t *testing.T) {
 				"--markdown", updatedContent,
 				"--new-title", updatedTitle,
 			},
-			DefaultAs: "bot",
+			DefaultAs: defaultAs,
 		})
 		require.NoError(t, err)
 		result.AssertExitCode(t, 0)
@@ -61,7 +62,7 @@ func TestDocs_UpdateWorkflow(t *testing.T) {
 				"docs", "+fetch",
 				"--doc", docToken,
 			},
-			DefaultAs: "bot",
+			DefaultAs: defaultAs,
 		})
 		require.NoError(t, err)
 		result.AssertExitCode(t, 0)

tests/cli_e2e/docs/helpers_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/larksuite/cli/tests/cli_e2e/drive"
 	"github.com/stretchr/testify/require"
 	"github.com/tidwall/gjson"
 )
@@ -37,15 +38,7 @@ func createDocWithRetry(t *testing.T, parentT *testing.T, ctx context.Context, f
 		cleanupCtx, cancel := clie2e.CleanupContext()
 		defer cancel()
 
-		deleteResult, deleteErr := clie2e.RunCmd(cleanupCtx, clie2e.Request{
-			Args: []string{
-				"drive", "+delete",
-				"--file-token", docToken,
-				"--type", "docx",
-				"--yes",
-			},
-			DefaultAs: defaultAs,
-		})
+		deleteResult, deleteErr := drive.DeleteDriveResourceAndVerify(cleanupCtx, docToken, "docx", defaultAs)
 		clie2e.ReportCleanupFailure(parentT, "delete doc "+docToken, deleteResult, deleteErr)
 	})
 

tests/cli_e2e/drive/drive_export_dryrun_test.go

@@ -60,3 +60,42 @@ func TestDriveExportDryRun_FileNameMetadata(t *testing.T) {
 		t.Fatalf("output_dir=%q, want ./exports\nstdout:\n%s", got, out)
 	}
 }
+
+func TestDriveExportDryRun_MarkdownFetchAPI(t *testing.T) {
+	setDriveDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+export",
+			"--token", "docxMdDryRun",
+			"--doc-type", "docx",
+			"--file-extension", "markdown",
+			"--file-name", "my-notes",
+			"--output-dir", "./md-exports",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	if got := gjson.Get(out, "api.0.method").String(); got != "POST" {
+		t.Fatalf("method=%q, want POST\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.url").String(); got != "/open-apis/docs_ai/v1/documents/docxMdDryRun/fetch" {
+		t.Fatalf("url=%q, want docs_ai fetch\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "api.0.body.format").String(); got != "markdown" {
+		t.Fatalf("body.format=%q, want markdown\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "file_name").String(); got != "my-notes.md" {
+		t.Fatalf("file_name=%q, want my-notes.md\nstdout:\n%s", got, out)
+	}
+	if got := gjson.Get(out, "output_dir").String(); got != "./md-exports" {
+		t.Fatalf("output_dir=%q, want ./md-exports\nstdout:\n%s", got, out)
+	}
+}

tests/cli_e2e/drive/drive_inspect_dryrun_test.go

@@ -0,0 +1,237 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+// --- Happy path: all supported URL types ---
+
+func TestDriveInspectDryRun_DocxURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+	result := runInspectDryRun(t, "https://xxx.feishu.cn/docx/doxcnDryRunE2E")
+	assertOneStepBatchQuery(t, result)
+}
+
+func TestDriveInspectDryRun_DocURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+	result := runInspectDryRun(t, "https://xxx.feishu.cn/doc/doccnDryRunE2E")
+	assertOneStepBatchQuery(t, result)
+}
+
+func TestDriveInspectDryRun_SheetURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+	result := runInspectDryRun(t, "https://xxx.feishu.cn/sheets/shtcnDryRunE2E")
+	assertOneStepBatchQuery(t, result)
+}
+
+func TestDriveInspectDryRun_BitableURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+	result := runInspectDryRun(t, "https://xxx.feishu.cn/base/bascnDryRunE2E")
+	assertOneStepBatchQuery(t, result)
+}
+
+func TestDriveInspectDryRun_FileURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+	result := runInspectDryRun(t, "https://xxx.feishu.cn/file/boxcnDryRunE2E")
+	assertOneStepBatchQuery(t, result)
+}
+
+func TestDriveInspectDryRun_FolderURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+	result := runInspectDryRun(t, "https://xxx.feishu.cn/drive/folder/fldcnDryRunE2E")
+	assertOneStepBatchQuery(t, result)
+}
+
+func TestDriveInspectDryRun_MindnoteURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+	result := runInspectDryRun(t, "https://xxx.feishu.cn/mindnote/mncnDryRunE2E")
+	assertOneStepBatchQuery(t, result)
+}
+
+func TestDriveInspectDryRun_SlidesURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+	result := runInspectDryRun(t, "https://xxx.feishu.cn/slides/slkcnDryRunE2E")
+	assertOneStepBatchQuery(t, result)
+}
+
+// --- Wiki URL: two-step flow ---
+
+func TestDriveInspectDryRun_WikiURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+inspect",
+			"--url", "https://xxx.feishu.cn/wiki/wikcnDryRunE2E",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	require.Equal(t, int64(2), gjson.Get(result.Stdout, "api.#").Int(),
+		"expected exactly 2 dry-run API steps for wiki URL, stdout:\n%s", result.Stdout)
+	require.Equal(t, "/open-apis/wiki/v2/spaces/get_node",
+		gjson.Get(result.Stdout, "api.0.url").String(),
+		"expected get_node as first step, stdout:\n%s", result.Stdout)
+	require.Equal(t, "/open-apis/drive/v1/metas/batch_query",
+		gjson.Get(result.Stdout, "api.1.url").String(),
+		"expected batch_query as second step, stdout:\n%s", result.Stdout)
+}
+
+// --- Bare token with --type ---
+
+func TestDriveInspectDryRun_BareTokenWithType(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+inspect",
+			"--url", "doxcnBareToken",
+			"--type", "docx",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+	assertOneStepBatchQuery(t, result)
+}
+
+// --- Validation errors ---
+
+func TestDriveInspectValidation_EmptyURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+inspect",
+			"--url", "",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 2)
+	require.Contains(t, result.Stderr, "--url cannot be empty",
+		"expected empty URL validation error, stderr:\n%s", result.Stderr)
+}
+
+func TestDriveInspectValidation_UnsupportedURL(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+inspect",
+			"--url", "https://google.com/some/page",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 2)
+	require.Contains(t, result.Stderr, "unsupported --url",
+		"expected unsupported URL validation error, stderr:\n%s", result.Stderr)
+}
+
+func TestDriveInspectValidation_BareTokenWithoutType(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+inspect",
+			"--url", "doxcnBareToken",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 2)
+	require.Contains(t, result.Stderr, "--type is required when --url is a bare token",
+		"expected bare-token-without-type validation error, stderr:\n%s", result.Stderr)
+}
+
+func TestDriveInspectValidation_InvalidType(t *testing.T) {
+	setDriveInspectE2EEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+inspect",
+			"--url", "someToken",
+			"--type", "invalid_type",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 2)
+	require.Contains(t, result.Stderr, "invalid_type",
+		"expected invalid type validation error, stderr:\n%s", result.Stderr)
+}
+
+// --- Helpers ---
+
+func runInspectDryRun(t *testing.T, url string) *clie2e.Result {
+	t.Helper()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+inspect",
+			"--url", url,
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+	return result
+}
+
+func assertOneStepBatchQuery(t *testing.T, result *clie2e.Result) {
+	t.Helper()
+
+	require.Equal(t, int64(1), gjson.Get(result.Stdout, "api.#").Int(),
+		"expected exactly 1 dry-run API step, stdout:\n%s", result.Stdout)
+	require.Equal(t, "/open-apis/drive/v1/metas/batch_query",
+		gjson.Get(result.Stdout, "api.0.url").String(),
+		"expected batch_query URL, stdout:\n%s", result.Stdout)
+}
+
+func setDriveInspectE2EEnv(t *testing.T) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_APP_ID", "drive_inspect_e2e_app")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "drive_inspect_e2e_secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+}

tests/cli_e2e/drive/helpers.go

@@ -5,7 +5,10 @@ package drive
 
 import (
 	"context"
+	"fmt"
+	"strings"
 	"testing"
+	"time"
 
 	clie2e "github.com/larksuite/cli/tests/cli_e2e"
 	"github.com/tidwall/gjson"
@@ -44,12 +47,124 @@ func CreateDriveFolder(t *testing.T, parentT *testing.T, ctx context.Context, na
 		cleanupCtx, cancel := clie2e.CleanupContext()
 		defer cancel()
 
-		deleteResult, deleteErr := clie2e.RunCmdWithRetry(cleanupCtx, clie2e.Request{
-			Args:      []string{"drive", "+delete", "--file-token", folderToken, "--type", "folder", "--yes"},
-			DefaultAs: defaultAs,
-		}, clie2e.RetryOptions{})
+		deleteResult, deleteErr := DeleteDriveResourceAndVerify(cleanupCtx, folderToken, "folder", defaultAs)
 		clie2e.ReportCleanupFailure(parentT, "delete drive folder "+folderToken, deleteResult, deleteErr)
 	})
 
 	return folderToken
 }
+
+// DeleteDriveResourceAndVerify deletes a Drive-backed resource, then polls
+// drive meta until the token is either gone or no longer has an accessible URL.
+// This prevents cleanup from looking successful when the delete command
+// returned a suppressed not_found or partial API error but the resource still
+// exists.
+func DeleteDriveResourceAndVerify(ctx context.Context, token, docType, defaultAs string) (*clie2e.Result, error) {
+	if defaultAs == "" {
+		defaultAs = "bot"
+	}
+
+	deleteResult, deleteErr := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+		Args:      []string{"drive", "+delete", "--file-token", token, "--type", docType, "--yes"},
+		DefaultAs: defaultAs,
+	}, clie2e.RetryOptions{})
+	if deleteErr != nil || deleteResult == nil {
+		return deleteResult, deleteErr
+	}
+	if deleteResult.ExitCode != 0 {
+		deleted, verifyErr := IsDriveResourceDeleted(ctx, token, docType, defaultAs)
+		if verifyErr != nil {
+			return deleteResult, verifyErr
+		}
+		if deleted {
+			deleteResult.ExitCode = 0
+			return deleteResult, nil
+		}
+		return deleteResult, fmt.Errorf("drive resource %s/%s still exists after delete failed: exit=%d stdout=%s stderr=%s", docType, token, deleteResult.ExitCode, deleteResult.Stdout, deleteResult.Stderr)
+	}
+	if err := WaitDriveResourceDeleted(ctx, token, docType, defaultAs); err != nil {
+		return deleteResult, err
+	}
+	return deleteResult, nil
+}
+
+func WaitDriveResourceDeleted(ctx context.Context, token, docType, defaultAs string) error {
+	deadline := time.NewTimer(20 * time.Second)
+	defer deadline.Stop()
+	ticker := time.NewTicker(time.Second)
+	defer ticker.Stop()
+
+	for {
+		deleted, err := IsDriveResourceDeleted(ctx, token, docType, defaultAs)
+		if err != nil {
+			return err
+		}
+		if deleted {
+			return nil
+		}
+
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-deadline.C:
+			return fmt.Errorf("drive resource %s/%s still exists after delete", docType, token)
+		case <-ticker.C:
+		}
+	}
+}
+
+func IsDriveResourceDeleted(ctx context.Context, token, docType, defaultAs string) (bool, error) {
+	if defaultAs == "" {
+		defaultAs = "bot"
+	}
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args:      []string{"api", "post", "/open-apis/drive/v1/metas/batch_query"},
+		DefaultAs: defaultAs,
+		Data: map[string]any{
+			"request_docs": []map[string]any{{
+				"doc_token": token,
+				"doc_type":  docType,
+			}},
+		},
+	})
+	if err != nil {
+		return false, err
+	}
+	if result.ExitCode != 0 {
+		combined := strings.ToLower(result.Stdout + "\n" + result.Stderr)
+		if strings.Contains(combined, "not found") || strings.Contains(combined, "404") {
+			return true, nil
+		}
+		return false, fmt.Errorf("verify drive resource %s/%s after delete: exit=%d stdout=%s stderr=%s", docType, token, result.ExitCode, result.Stdout, result.Stderr)
+	}
+	if !isDriveMetaQuerySuccessful(result.Stdout) {
+		return false, fmt.Errorf("verify drive resource %s/%s after delete returned unsuccessful envelope: stdout=%s stderr=%s", docType, token, result.Stdout, result.Stderr)
+	}
+	metas := gjson.Get(result.Stdout, "data.metas").Array()
+	if len(metas) == 0 {
+		return true, nil
+	}
+	if docType != "folder" {
+		allURLsCleared := true
+		for _, meta := range metas {
+			if meta.Get("url").String() != "" {
+				allURLsCleared = false
+				break
+			}
+		}
+		if allURLsCleared {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+func isDriveMetaQuerySuccessful(stdout string) bool {
+	if ok := gjson.Get(stdout, "ok"); ok.Exists() {
+		return ok.Bool()
+	}
+	if code := gjson.Get(stdout, "code"); code.Exists() {
+		return code.Int() == 0
+	}
+	return false
+}

tests/cli_e2e/sheets/helpers_test.go

@@ -8,7 +8,7 @@ import (
 	"testing"
 
 	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	drivee2e "github.com/larksuite/cli/tests/cli_e2e/drive"
+	"github.com/larksuite/cli/tests/cli_e2e/drive"
 	"github.com/stretchr/testify/require"
 	"github.com/tidwall/gjson"
 )
@@ -16,7 +16,7 @@ import (
 func createSpreadsheet(t *testing.T, parentT *testing.T, ctx context.Context, title string, defaultAs string) string {
 	t.Helper()
 
-	folderToken := drivee2e.CreateDriveFolder(t, parentT, ctx, title+"-folder", defaultAs, "")
+	folderToken := drive.CreateDriveFolder(t, parentT, ctx, title+"-folder", defaultAs, "")
 
 	result, err := clie2e.RunCmd(ctx, clie2e.Request{
 		Args: []string{
@@ -37,15 +37,7 @@ func createSpreadsheet(t *testing.T, parentT *testing.T, ctx context.Context, ti
 		cleanupCtx, cancel := clie2e.CleanupContext()
 		defer cancel()
 
-		deleteResult, deleteErr := clie2e.RunCmd(cleanupCtx, clie2e.Request{
-			Args: []string{
-				"drive", "+delete",
-				"--file-token", spreadsheetToken,
-				"--type", "sheet",
-				"--yes",
-			},
-			DefaultAs: defaultAs,
-		})
+		deleteResult, deleteErr := drive.DeleteDriveResourceAndVerify(cleanupCtx, spreadsheetToken, "sheet", defaultAs)
 		clie2e.ReportCleanupFailure(parentT, "delete spreadsheet "+spreadsheetToken, deleteResult, deleteErr)
 	})
 

tests/cli_e2e/sheets/sheets_crud_workflow_test.go

@@ -12,7 +12,7 @@ import (
 	"time"
 
 	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	drivee2e "github.com/larksuite/cli/tests/cli_e2e/drive"
+	"github.com/larksuite/cli/tests/cli_e2e/drive"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"github.com/tidwall/gjson"
@@ -180,12 +180,13 @@ func TestSheets_SpreadsheetsResource(t *testing.T) {
 
 	suffix := clie2e.GenerateSuffix()
 	spreadsheetToken := ""
+	const defaultAs = "bot"
 
 	t.Run("create spreadsheet with spreadsheets create as bot", func(t *testing.T) {
-		folderToken := drivee2e.CreateDriveFolder(t, parentT, ctx, "lark-cli-e2e-sheets-resource-folder-"+suffix, "bot", "")
+		folderToken := drive.CreateDriveFolder(t, parentT, ctx, "lark-cli-e2e-sheets-resource-folder-"+suffix, defaultAs, "")
 		result, err := clie2e.RunCmd(ctx, clie2e.Request{
 			Args:      []string{"sheets", "spreadsheets", "create"},
-			DefaultAs: "bot",
+			DefaultAs: defaultAs,
 			Data: map[string]any{
 				"title":        "lark-cli-e2e-sheets-resource-" + suffix,
 				"folder_token": folderToken,
@@ -202,15 +203,7 @@ func TestSheets_SpreadsheetsResource(t *testing.T) {
 			cleanupCtx, cancel := clie2e.CleanupContext()
 			defer cancel()
 
-			deleteResult, deleteErr := clie2e.RunCmd(cleanupCtx, clie2e.Request{
-				Args: []string{
-					"drive", "+delete",
-					"--file-token", spreadsheetToken,
-					"--type", "sheet",
-					"--yes",
-				},
-				DefaultAs: "bot",
-			})
+			deleteResult, deleteErr := drive.DeleteDriveResourceAndVerify(cleanupCtx, spreadsheetToken, "sheet", defaultAs)
 			clie2e.ReportCleanupFailure(parentT, "delete spreadsheet "+spreadsheetToken, deleteResult, deleteErr)
 		})
 	})

tests/cli_e2e/wiki/helpers_test.go

@@ -5,14 +5,17 @@ package wiki
 
 import (
 	"context"
+	"fmt"
+	"strings"
 	"testing"
+	"time"
 
 	clie2e "github.com/larksuite/cli/tests/cli_e2e"
 	"github.com/stretchr/testify/require"
 	"github.com/tidwall/gjson"
 )
 
-func createWikiNode(t *testing.T, parentT *testing.T, ctx context.Context, spaceID string, data map[string]any) gjson.Result {
+func createWikiNode(t *testing.T, parentT *testing.T, ctx context.Context, spaceID string, data map[string]any) (gjson.Result, *clie2e.Result, error) {
 	t.Helper()
 
 	result, err := clie2e.RunCmd(ctx, clie2e.Request{
@@ -20,9 +23,9 @@ func createWikiNode(t *testing.T, parentT *testing.T, ctx context.Context, space
 		DefaultAs: "bot",
 		Data:      data,
 	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-	result.AssertStdoutStatus(t, 0)
+	if err != nil || result.ExitCode != 0 {
+		return gjson.Result{}, result, err
+	}
 
 	node := gjson.Get(result.Stdout, "data.node")
 	require.True(t, node.Exists(), "stdout:\n%s", result.Stdout)
@@ -34,11 +37,118 @@ func createWikiNode(t *testing.T, parentT *testing.T, ctx context.Context, space
 		cleanupCtx, cancel := clie2e.CleanupContext()
 		defer cancel()
 
-		deleteResult, deleteErr := deleteWikiNode(cleanupCtx, spaceID, nodeToken, objType)
+		deleteResult, deleteErr := deleteWikiNodeAndVerify(cleanupCtx, spaceID, nodeToken, objType)
 		clie2e.ReportCleanupFailure(parentT, "delete wiki node "+nodeToken, deleteResult, deleteErr)
 	})
 
-	return node
+	return node, result, nil
+}
+
+// createWikiNodeUnderAnyHost creates an isolated parent under an existing
+// my_library root node. It avoids adding test nodes directly at the root level,
+// whose single-layer limit is easy to exhaust when cleanup regresses. If the
+// library is empty, it creates one reusable root host and keeps it for future
+// test runs.
+func createWikiNodeUnderAnyHost(t *testing.T, parentT *testing.T, ctx context.Context, title string) (gjson.Result, gjson.Result) {
+	t.Helper()
+
+	hosts := listWikiRootHosts(t, ctx)
+	if len(hosts) == 0 {
+		hosts = append(hosts, createWikiRootHost(t, ctx))
+	}
+
+	var layerLimitResults []string
+	for _, host := range hosts {
+		spaceID := host.Get("space_id").String()
+		hostNodeToken := host.Get("node_token").String()
+		if spaceID == "" || hostNodeToken == "" {
+			continue
+		}
+		node, result, err := createWikiNode(t, parentT, ctx, spaceID, map[string]any{
+			"node_type":         "origin",
+			"obj_type":          "docx",
+			"title":             title,
+			"parent_node_token": hostNodeToken,
+		})
+		if err == nil && result.ExitCode == 0 {
+			return host, node
+		}
+		if isWikiLayerLimitResult(result) {
+			layerLimitResults = append(layerLimitResults, fmt.Sprintf("host=%s stdout=%s stderr=%s", hostNodeToken, result.Stdout, result.Stderr))
+			continue
+		}
+		require.NoError(t, err)
+		require.Failf(t, "create wiki node under host failed", "host=%s exit=%d stdout=%s stderr=%s", hostNodeToken, result.ExitCode, result.Stdout, result.Stderr)
+	}
+	require.Failf(t, "create wiki node under host failed", "all candidate hosts hit the single-layer node limit:\n%s", strings.Join(layerLimitResults, "\n"))
+	return gjson.Result{}, gjson.Result{}
+}
+
+func createWikiRootHost(t *testing.T, ctx context.Context) gjson.Result {
+	t.Helper()
+
+	result, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+		Args:      []string{"api", "post", "/open-apis/wiki/v2/spaces/my_library/nodes"},
+		DefaultAs: "bot",
+		Data: map[string]any{
+			"node_type": "origin",
+			"obj_type":  "docx",
+			"title":     "lark-cli-e2e-wiki-host",
+		},
+	}, clie2e.RetryOptions{})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+	result.AssertStdoutStatus(t, 0)
+
+	host := gjson.Get(result.Stdout, "data.node")
+	require.True(t, host.Exists(), "stdout:\n%s", result.Stdout)
+	require.NotEmpty(t, host.Get("space_id").String(), "stdout:\n%s", result.Stdout)
+	require.NotEmpty(t, host.Get("node_token").String(), "stdout:\n%s", result.Stdout)
+	return host
+}
+
+func listWikiRootHosts(t *testing.T, ctx context.Context) []gjson.Result {
+	t.Helper()
+
+	var hosts []gjson.Result
+	pageToken := ""
+	seenPageTokens := map[string]struct{}{}
+	for {
+		params := map[string]any{"page_size": 50}
+		if pageToken != "" {
+			if _, exists := seenPageTokens[pageToken]; exists {
+				t.Fatalf("wiki root host pagination loop detected for page_token %q", pageToken)
+			}
+			seenPageTokens[pageToken] = struct{}{}
+			params["page_token"] = pageToken
+		}
+
+		listResult, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+			Args:      []string{"api", "get", "/open-apis/wiki/v2/spaces/my_library/nodes"},
+			DefaultAs: "bot",
+			Params:    params,
+		}, clie2e.RetryOptions{})
+		require.NoError(t, err)
+		listResult.AssertExitCode(t, 0)
+		listResult.AssertStdoutStatus(t, 0)
+
+		parsed := gjson.Parse(listResult.Stdout)
+		hosts = append(hosts, parsed.Get("data.items").Array()...)
+
+		pageToken = parsed.Get("data.page_token").String()
+		if pageToken == "" || !parsed.Get("data.has_more").Bool() {
+			return hosts
+		}
+	}
+}
+
+func isWikiLayerLimitResult(result *clie2e.Result) bool {
+	if result == nil {
+		return false
+	}
+	combined := result.Stdout + "\n" + result.Stderr
+	return strings.Contains(combined, "131003") ||
+		strings.Contains(strings.ToLower(combined), "single-layer nodes")
 }
 
 func getWikiNode(t *testing.T, ctx context.Context, nodeToken string) gjson.Result {
@@ -88,19 +198,213 @@ func listWikiSpaces(t *testing.T, ctx context.Context, pageSize int) gjson.Resul
 	return gjson.Parse(result.Stdout)
 }
 
-// deleteWikiNode removes a wiki space node. The DELETE endpoint requires
-// obj_type as a body field (validation error 99992402 if omitted), so
-// pass it via --data rather than --params even though DELETE bodies are
-// uncommon.
-func deleteWikiNode(ctx context.Context, spaceID, nodeToken, objType string) (*clie2e.Result, error) {
-	return clie2e.RunCmd(ctx, clie2e.Request{
-		Args:      []string{"api", "delete", "/open-apis/wiki/v2/spaces/" + spaceID + "/nodes/" + nodeToken},
-		DefaultAs: "bot",
-		Data:      map[string]any{"obj_type": objType},
-	})
+type wikiNodeInfo struct {
+	NodeToken string
+	ObjType   string
 }
 
-func findWikiNodeByToken(t *testing.T, ctx context.Context, spaceID string, nodeToken string) gjson.Result {
+// deleteWikiNodeAndVerify removes a wiki node, then polls get_node until the
+// original node token is gone. Wiki cleanup cannot use drive +delete because
+// wiki origin nodes need the backing obj_token and parent nodes must delete
+// children first.
+func deleteWikiNodeAndVerify(ctx context.Context, spaceID, nodeToken, objType string) (*clie2e.Result, error) {
+	getResult, getErr := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+		Args:      []string{"api", "get", "/open-apis/wiki/v2/spaces/get_node"},
+		DefaultAs: "bot",
+		Params:    map[string]any{"token": nodeToken},
+	}, clie2e.RetryOptions{})
+	if getErr != nil {
+		return getResult, getErr
+	}
+	if getResult == nil {
+		return nil, fmt.Errorf("get wiki node %s before delete returned nil result", nodeToken)
+	}
+	if getResult.ExitCode != 0 || !wikiAPISuccess(getResult.Stdout) {
+		if isWikiNodeDeletedResult(getResult) {
+			getResult.ExitCode = 0
+			getResult.RunErr = nil
+			return getResult, nil
+		}
+		return getResult, fmt.Errorf("get wiki node %s before delete failed: exit=%d stdout=%s stderr=%s", nodeToken, getResult.ExitCode, getResult.Stdout, getResult.Stderr)
+	}
+
+	node := gjson.Get(getResult.Stdout, "data.node")
+	originalNodeToken := nodeToken
+	if resolvedSpaceID := node.Get("space_id").String(); resolvedSpaceID != "" {
+		spaceID = resolvedSpaceID
+	}
+	if resolvedObjType := node.Get("obj_type").String(); resolvedObjType != "" {
+		objType = resolvedObjType
+	}
+	if objType == "" {
+		objType = "docx"
+	}
+
+	children, childListResult, childListErr := listWikiNodeChildren(ctx, spaceID, originalNodeToken)
+	if childListErr != nil || childListResult == nil || childListResult.ExitCode != 0 {
+		return childListResult, childListErr
+	}
+	for _, child := range children {
+		childDeleteResult, childDeleteErr := deleteWikiNodeAndVerify(ctx, spaceID, child.NodeToken, child.ObjType)
+		if childDeleteErr != nil || childDeleteResult == nil || (childDeleteResult.ExitCode != 0 && !isWikiNodeDeletedResult(childDeleteResult)) {
+			return childDeleteResult, childDeleteErr
+		}
+	}
+
+	deleteToken := originalNodeToken
+	if node.Get("node_type").String() == "origin" {
+		if objToken := node.Get("obj_token").String(); objToken != "" {
+			deleteToken = objToken
+		}
+	}
+
+	deleteResult, deleteErr := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+		Args:      []string{"api", "delete", "/open-apis/wiki/v2/spaces/" + spaceID + "/nodes/" + deleteToken},
+		DefaultAs: "bot",
+		Data:      map[string]any{"obj_type": objType},
+	}, clie2e.RetryOptions{})
+	if deleteErr != nil || deleteResult == nil {
+		return deleteResult, deleteErr
+	}
+	if deleteResult.ExitCode != 0 || !wikiAPISuccess(deleteResult.Stdout) {
+		deleted, verifyErr := isWikiNodeDeleted(ctx, originalNodeToken)
+		if verifyErr != nil {
+			return deleteResult, verifyErr
+		}
+		if deleted {
+			deleteResult.ExitCode = 0
+			return deleteResult, nil
+		}
+		return deleteResult, fmt.Errorf("wiki node %s still exists after delete failed: exit=%d stdout=%s stderr=%s", originalNodeToken, deleteResult.ExitCode, deleteResult.Stdout, deleteResult.Stderr)
+	}
+	if err := waitWikiNodeDeleted(ctx, originalNodeToken); err != nil {
+		return deleteResult, err
+	}
+	return deleteResult, nil
+}
+
+func listWikiNodeChildren(ctx context.Context, spaceID, parentNodeToken string) ([]wikiNodeInfo, *clie2e.Result, error) {
+	var children []wikiNodeInfo
+	pageToken := ""
+	seenPageTokens := map[string]struct{}{}
+	for {
+		params := map[string]any{
+			"page_size":         50,
+			"parent_node_token": parentNodeToken,
+		}
+		if pageToken != "" {
+			if _, exists := seenPageTokens[pageToken]; exists {
+				return children, nil, fmt.Errorf("wiki children pagination loop detected for parent %s page_token %q", parentNodeToken, pageToken)
+			}
+			seenPageTokens[pageToken] = struct{}{}
+			params["page_token"] = pageToken
+		}
+
+		result, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+			Args:      []string{"api", "get", "/open-apis/wiki/v2/spaces/" + spaceID + "/nodes"},
+			DefaultAs: "bot",
+			Params:    params,
+		}, clie2e.RetryOptions{})
+		if err != nil || result == nil || result.ExitCode != 0 {
+			return children, result, err
+		}
+		if !wikiAPISuccess(result.Stdout) {
+			return children, result, fmt.Errorf("list wiki node children for parent %s failed: stdout=%s stderr=%s", parentNodeToken, result.Stdout, result.Stderr)
+		}
+
+		parsed := gjson.Parse(result.Stdout)
+		for _, item := range parsed.Get("data.items").Array() {
+			nodeToken := item.Get("node_token").String()
+			if nodeToken == "" {
+				continue
+			}
+			objType := item.Get("obj_type").String()
+			if objType == "" {
+				objType = "docx"
+			}
+			children = append(children, wikiNodeInfo{NodeToken: nodeToken, ObjType: objType})
+		}
+
+		pageToken = parsed.Get("data.page_token").String()
+		if pageToken == "" || !parsed.Get("data.has_more").Bool() {
+			return children, result, nil
+		}
+	}
+}
+
+func waitWikiNodeDeleted(ctx context.Context, nodeToken string) error {
+	deadline := time.NewTimer(20 * time.Second)
+	defer deadline.Stop()
+	ticker := time.NewTicker(time.Second)
+	defer ticker.Stop()
+
+	for {
+		deleted, err := isWikiNodeDeleted(ctx, nodeToken)
+		if err != nil {
+			return err
+		}
+		if deleted {
+			return nil
+		}
+
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-deadline.C:
+			return fmt.Errorf("wiki node %s still exists after delete", nodeToken)
+		case <-ticker.C:
+		}
+	}
+}
+
+func isWikiNodeDeleted(ctx context.Context, nodeToken string) (bool, error) {
+	result, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+		Args:      []string{"api", "get", "/open-apis/wiki/v2/spaces/get_node"},
+		DefaultAs: "bot",
+		Params:    map[string]any{"token": nodeToken},
+	}, clie2e.RetryOptions{})
+	if err != nil {
+		return false, err
+	}
+	if result == nil {
+		return false, fmt.Errorf("verify wiki node %s after delete returned nil result", nodeToken)
+	}
+	if result.ExitCode == 0 && wikiAPISuccess(result.Stdout) {
+		return false, nil
+	}
+	if isWikiNodeDeletedResult(result) {
+		return true, nil
+	}
+	return false, fmt.Errorf("verify wiki node %s after delete: exit=%d stdout=%s stderr=%s", nodeToken, result.ExitCode, result.Stdout, result.Stderr)
+}
+
+func wikiAPISuccess(stdout string) bool {
+	if ok := gjson.Get(stdout, "ok"); ok.Exists() {
+		return ok.Bool()
+	}
+	if code := gjson.Get(stdout, "code"); code.Exists() {
+		return code.Int() == 0
+	}
+	return false
+}
+
+func isWikiNodeDeletedResult(result *clie2e.Result) bool {
+	if result == nil {
+		return false
+	}
+	if code := gjson.Get(result.Stdout, "error.code"); code.Exists() && code.Int() == 131005 {
+		return true
+	}
+	if code := gjson.Get(result.Stdout, "code"); code.Exists() && code.Int() == 131005 {
+		return true
+	}
+	combined := strings.ToLower(result.Stdout + "\n" + result.Stderr)
+	return strings.Contains(combined, "131005") ||
+		strings.Contains(combined, "node not found") ||
+		strings.Contains(combined, "not found")
+}
+
+func findWikiNodeByToken(t *testing.T, ctx context.Context, spaceID string, nodeToken string, parentNodeTokens ...string) gjson.Result {
 	t.Helper()
 
 	pageToken := ""
@@ -108,6 +412,9 @@ func findWikiNodeByToken(t *testing.T, ctx context.Context, spaceID string, node
 	seenPageTokens := map[string]struct{}{}
 	for {
 		params := map[string]any{"page_size": 50}
+		if len(parentNodeTokens) > 0 && parentNodeTokens[0] != "" {
+			params["parent_node_token"] = parentNodeTokens[0]
+		}
 		if pageToken != "" {
 			if _, exists := seenPageTokens[pageToken]; exists {
 				t.Fatalf("wiki list pagination loop detected for page_token %q, last stdout:\n%s", pageToken, lastStdout)

tests/cli_e2e/wiki/wiki_shortcut_workflow_test.go

@@ -31,7 +31,7 @@ func TestWiki_ShortcutWorkflow(t *testing.T) {
 	childTitle := "lark-cli-e2e-wiki-sc-child-" + suffix
 	copyTitle := "lark-cli-e2e-wiki-sc-copy-" + suffix
 
-	var spaceID, parentNodeToken, childNodeToken, childObjType string
+	var spaceID, parentNodeToken, childNodeToken, childObjType, copiedNodeToken string
 
 	// Setup: reuse an existing first-layer node in my_library as the host so
 	// we never bump the top-layer node count (the bot's my_library top layer
@@ -46,44 +46,22 @@ func TestWiki_ShortcutWorkflow(t *testing.T) {
 	// parent always has exactly the children this test creates, so the
 	// pagination scan never has to dig through historical cruft.
 	t.Run("setup: locate my_library host node + create isolated parent + create test child", func(t *testing.T) {
-		listResult, err := clie2e.RunCmd(ctx, clie2e.Request{
-			Args:      []string{"api", "get", "/open-apis/wiki/v2/spaces/my_library/nodes"},
-			DefaultAs: "bot",
-			Params:    map[string]any{"page_size": 50},
-		})
-		require.NoError(t, err)
-		listResult.AssertExitCode(t, 0)
-		listResult.AssertStdoutStatus(t, 0)
-
-		items := gjson.Get(listResult.Stdout, "data.items").Array()
-		if len(items) == 0 {
-			t.Skip("skipped: my_library has no existing top-level nodes to host the test structure")
-		}
-		host := items[0]
+		host, isolatedParent := createWikiNodeUnderAnyHost(t, parentT, ctx, parentTitle)
 		spaceID = host.Get("space_id").String()
-		hostNodeToken := host.Get("node_token").String()
 		require.NotEmpty(t, spaceID, "host space_id must be present in listing")
-		require.NotEmpty(t, hostNodeToken, "host node_token must be present in listing")
-
-		// Create a fresh intermediate parent under the host. The helper
-		// auto-registers a t.Cleanup callback that deletes this parent
-		// (and, by API cascade, anything still under it) after the test.
-		isolatedParent := createWikiNode(t, parentT, ctx, spaceID, map[string]any{
-			"node_type":         "origin",
-			"obj_type":          "docx",
-			"title":             parentTitle,
-			"parent_node_token": hostNodeToken,
-		})
 		parentNodeToken = isolatedParent.Get("node_token").String()
 		require.NotEmpty(t, parentNodeToken, "isolated parent node_token must be present after create")
 
 		// Create the test child UNDER the freshly-isolated parent.
-		child := createWikiNode(t, parentT, ctx, spaceID, map[string]any{
+		child, result, err := createWikiNode(t, parentT, ctx, spaceID, map[string]any{
 			"node_type":         "origin",
 			"obj_type":          "docx",
 			"title":             childTitle,
 			"parent_node_token": parentNodeToken,
 		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		result.AssertStdoutStatus(t, 0)
 		childNodeToken = child.Get("node_token").String()
 		childObjType = child.Get("obj_type").String()
 		require.NotEmpty(t, childNodeToken)
@@ -184,7 +162,7 @@ func TestWiki_ShortcutWorkflow(t *testing.T) {
 		require.NotEmpty(t, parentNodeToken)
 		require.NotEmpty(t, childNodeToken)
 
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		result, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
 			Args: []string{
 				"wiki", "+node-copy",
 				"--space-id", spaceID,
@@ -197,13 +175,13 @@ func TestWiki_ShortcutWorkflow(t *testing.T) {
 			// explicit confirmation before issuing the request.
 			Yes:       true,
 			DefaultAs: "bot",
-		})
+		}, clie2e.RetryOptions{})
 		require.NoError(t, err)
 		result.AssertExitCode(t, 0)
 
 		out := gjson.Parse(result.Stdout)
 		require.True(t, out.Get("ok").Bool(), "stdout:\n%s", result.Stdout)
-		copiedNodeToken := out.Get("data.node_token").String()
+		copiedNodeToken = out.Get("data.node_token").String()
 		copiedSpaceID := out.Get("data.space_id").String()
 		copiedObjType := out.Get("data.obj_type").String()
 		require.NotEmpty(t, copiedNodeToken, "stdout:\n%s", result.Stdout)
@@ -213,7 +191,7 @@ func TestWiki_ShortcutWorkflow(t *testing.T) {
 		parentT.Cleanup(func() {
 			cleanupCtx, cancel := clie2e.CleanupContext()
 			defer cancel()
-			deleteResult, deleteErr := deleteWikiNode(cleanupCtx, copiedSpaceID, copiedNodeToken, copiedObjType)
+			deleteResult, deleteErr := deleteWikiNodeAndVerify(cleanupCtx, copiedSpaceID, copiedNodeToken, copiedObjType)
 			clie2e.ReportCleanupFailure(parentT, "delete copied wiki node "+copiedNodeToken, deleteResult, deleteErr)
 		})
 

tests/cli_e2e/wiki/wiki_workflow_test.go

@@ -25,21 +25,20 @@ func TestWiki_NodeWorkflow(t *testing.T) {
 	copiedTitle := "lark-cli-e2e-wiki-copy-" + suffix
 
 	var spaceID string
+	var hostNodeToken string
 	var parentNodeToken string
 	var createdNodeToken string
 	var createdObjToken string
 	var copiedNodeToken string
 	var copiedSpaceID string
 
-	t.Run("create isolated parent node as bot", func(t *testing.T) {
-		parentNode := createWikiNode(t, parentT, ctx, "my_library", map[string]any{
-			"node_type": "origin",
-			"obj_type":  "docx",
-			"title":     parentTitle,
-		})
+	t.Run("create isolated parent node under host as bot", func(t *testing.T) {
+		host, parentNode := createWikiNodeUnderAnyHost(t, parentT, ctx, parentTitle)
 		spaceID = parentNode.Get("space_id").String()
+		hostNodeToken = host.Get("node_token").String()
 		parentNodeToken = parentNode.Get("node_token").String()
 		require.NotEmpty(t, spaceID)
+		require.NotEmpty(t, hostNodeToken)
 		require.NotEmpty(t, parentNodeToken)
 		assert.Equal(t, parentTitle, parentNode.Get("title").String())
 	})
@@ -47,12 +46,15 @@ func TestWiki_NodeWorkflow(t *testing.T) {
 	t.Run("create node as bot", func(t *testing.T) {
 		require.NotEmpty(t, parentNodeToken, "parent node token should be created before child node")
 
-		node := createWikiNode(t, parentT, ctx, spaceID, map[string]any{
+		node, result, err := createWikiNode(t, parentT, ctx, spaceID, map[string]any{
 			"node_type":         "origin",
 			"obj_type":          "docx",
 			"title":             createdTitle,
 			"parent_node_token": parentNodeToken,
 		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		result.AssertStdoutStatus(t, 0)
 
 		createdNodeToken = node.Get("node_token").String()
 		createdObjToken = node.Get("obj_token").String()
@@ -94,9 +96,10 @@ func TestWiki_NodeWorkflow(t *testing.T) {
 
 	t.Run("list nodes and find isolated parent node as bot", func(t *testing.T) {
 		require.NotEmpty(t, spaceID, "space ID should be available before list")
+		require.NotEmpty(t, hostNodeToken, "host node token should be available before list")
 		require.NotEmpty(t, parentNodeToken, "parent node token should be available before list")
 
-		nodeItem := findWikiNodeByToken(t, ctx, spaceID, parentNodeToken)
+		nodeItem := findWikiNodeByToken(t, ctx, spaceID, parentNodeToken, hostNodeToken)
 		assert.Equal(t, parentTitle, nodeItem.Get("title").String())
 	})
 
@@ -104,14 +107,15 @@ func TestWiki_NodeWorkflow(t *testing.T) {
 		require.NotEmpty(t, spaceID, "space ID should be available before copy")
 		require.NotEmpty(t, createdNodeToken, "node token should be available before copy")
 
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		result, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
 			Args:      []string{"api", "post", "/open-apis/wiki/v2/spaces/" + spaceID + "/nodes/" + createdNodeToken + "/copy"},
 			DefaultAs: "bot",
 			Data: map[string]any{
-				"target_space_id": spaceID,
-				"title":           copiedTitle,
+				"target_space_id":     spaceID,
+				"target_parent_token": parentNodeToken,
+				"title":               copiedTitle,
 			},
-		})
+		}, clie2e.RetryOptions{})
 		require.NoError(t, err)
 		result.AssertExitCode(t, 0)
 		result.AssertStdoutStatus(t, 0)
@@ -125,7 +129,7 @@ func TestWiki_NodeWorkflow(t *testing.T) {
 			cleanupCtx, cancel := clie2e.CleanupContext()
 			defer cancel()
 
-			deleteResult, deleteErr := deleteWikiNode(cleanupCtx, copiedSpaceID, copiedNodeToken, copiedObjType)
+			deleteResult, deleteErr := deleteWikiNodeAndVerify(cleanupCtx, copiedSpaceID, copiedNodeToken, copiedObjType)
 			clie2e.ReportCleanupFailure(parentT, "delete copied wiki node "+copiedNodeToken, deleteResult, deleteErr)
 		})
 	})