refactor: enhance file lock and token file directory writable checking logic

* docs(base): clarify form and file operation routing

* docs: clarify complete base role table rules

* docs: clarify base advanced permission status

* docs: clarify base form field lifecycle

* docs: guide base form question creation

* fix(base): address form dry-run review findings

* docs(base): add complete editable role example

* fix(base): validate form question create inputs

internal/auth/token_store.go

@@ -40,15 +40,23 @@ func MaskToken(token string) string {
 
 // GetStoredToken reads the stored UAT for a given (appId, userOpenId) pair.
 func GetStoredToken(appId, userOpenId string) *StoredUAToken {
+	token, _ := readStoredToken(appId, userOpenId)
+	return token
+}
+
+func readStoredToken(appId, userOpenId string) (*StoredUAToken, error) {
 	jsonStr, err := keychain.Get(keychain.LarkCliService, accountKey(appId, userOpenId))
-	if err != nil || jsonStr == "" {
-		return nil
+	if err != nil {
+		return nil, err
+	}
+	if jsonStr == "" {
+		return nil, nil
 	}
 	var token StoredUAToken
 	if err := json.Unmarshal([]byte(jsonStr), &token); err != nil {
-		return nil
+		return nil, err
 	}
-	return &token
+	return &token, nil
 }
 
 // SetStoredToken persists a UAT.
@@ -66,6 +74,54 @@ func RemoveStoredToken(appId, userOpenId string) error {
 	return keychain.Remove(keychain.LarkCliService, accountKey(appId, userOpenId))
 }
 
+// sameStoredTokenGeneration reports whether two snapshots represent the same
+// refresh-token generation. Access tokens are used only for case that does not 
+// contain a refresh token.
+func isSameStoredTokenGeneration(current, expected *StoredUAToken) bool {
+	if current == nil || expected == nil ||
+		current.AppId != expected.AppId ||
+		current.UserOpenId != expected.UserOpenId {
+		return false
+	}
+	if current.RefreshToken != "" || expected.RefreshToken != "" {
+		return current.RefreshToken == expected.RefreshToken
+	}
+	return current.AccessToken == expected.AccessToken
+}
+
+// setStoredTokenIfCurrent stores updated only when expected is still the
+// current token generation. It returns the token present after the check and
+// whether the update was applied.
+func setStoredTokenIfCurrent(expected, updated *StoredUAToken) (*StoredUAToken, bool, error) {
+	current, err := readStoredToken(expected.AppId, expected.UserOpenId)
+	if err != nil {
+		return nil, false, err
+	}
+	if !isSameStoredTokenGeneration(current, expected) {
+		return current, false, nil
+	}
+	if err := SetStoredToken(updated); err != nil {
+		return current, false, err
+	}
+	return updated, true, nil
+}
+
+// removeStoredTokenIfCurrent removes expected only when it is still the
+// current token generation. It returns the token retained on a mismatch.
+func removeStoredTokenIfCurrent(expected *StoredUAToken) (*StoredUAToken, bool, error) {
+	current, err := readStoredToken(expected.AppId, expected.UserOpenId)
+	if err != nil {
+		return nil, false, err
+	}
+	if !isSameStoredTokenGeneration(current, expected) {
+		return current, false, nil
+	}
+	if err := RemoveStoredToken(expected.AppId, expected.UserOpenId); err != nil {
+		return current, false, err
+	}
+	return nil, true, nil
+}
+
 // TokenStatus determines the freshness of a stored token.
 func TokenStatus(token *StoredUAToken) string {
 	now := time.Now().UnixMilli()

internal/auth/uat_client.go

@@ -4,17 +4,18 @@
 package auth
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
-	"net/url"
+	"net/http/httptrace"
 	"os"
 	"path/filepath"
 	"regexp"
-	"strings"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/gofrs/flock"
@@ -81,7 +82,7 @@ func GetValidAccessToken(httpClient *http.Client, opts UATCallOptions) (string,
 	}
 
 	if status == "needs_refresh" {
-		refreshed, err := refreshWithLock(httpClient, opts, stored)
+		refreshed, err := refreshWithLock(httpClient, opts)
 		if err != nil {
 			return "", err
 		}
@@ -103,7 +104,7 @@ func GetValidAccessToken(httpClient *http.Client, opts UATCallOptions) (string,
 }
 
 // refreshWithLock acquires a file lock before attempting to refresh the token.
-func refreshWithLock(httpClient *http.Client, opts UATCallOptions, stored *StoredUAToken) (*StoredUAToken, error) {
+func refreshWithLock(httpClient *http.Client, opts UATCallOptions) (*StoredUAToken, error) {
 	key := fmt.Sprintf("%s:%s", opts.AppId, opts.UserOpenId)
 
 	// 1. Process-level lock (prevents multiple goroutines in the same process)
@@ -125,12 +126,9 @@ func refreshWithLock(httpClient *http.Client, opts UATCallOptions, stored *Store
 		refreshLocks.Delete(key)
 	}()
 
-	// 2. Cross-process lock using flock
-	// We use the same underlying storage directory resolution as keychain_other.go
-	// to ensure locks are isolated properly alongside other sensitive data.
-	configDir := core.GetConfigDir()
-
-	lockDir := filepath.Join(configDir, "locks")
+	// 2. Cross-process lock using the global config directory so all
+	// workspaces sharing the same token also share the same lock.
+	lockDir := filepath.Join(core.GetBaseConfigDir(), "locks")
 	if err := vfs.MkdirAll(lockDir, 0700); err != nil {
 		return nil, fmt.Errorf("failed to create lock directory: %w", err)
 	}
@@ -153,21 +151,91 @@ func refreshWithLock(httpClient *http.Client, opts UATCallOptions, stored *Store
 	}
 	defer fileLock.Unlock()
 
-	// 3. Double-checked locking: Check if another process has already refreshed the token
-	freshStored := GetStoredToken(opts.AppId, opts.UserOpenId)
-	if freshStored != nil {
-		status := TokenStatus(freshStored)
-		if status == "valid" {
-			// Another process refreshed it, we can just use the new token
-			if opts.ErrOut != nil {
-				fmt.Fprintf(opts.ErrOut, "[lark-cli] uat-client: token already refreshed by another process\n")
-			}
-			return freshStored, nil
+	// 3. Re-read under the global lock and use only the current generation.
+	freshStored, err := readStoredToken(opts.AppId, opts.UserOpenId)
+	if err != nil {
+		return nil, err
+	}
+	if freshStored == nil {
+		return nil, nil
+	}
+
+	switch TokenStatus(freshStored) {
+	case "valid":
+		if opts.ErrOut != nil {
+			fmt.Fprintf(opts.ErrOut, "[lark-cli] uat-client: token already refreshed by another process\n")
 		}
+		return freshStored, nil
+	case "expired":
+		retained, removed, err := removeStoredTokenIfCurrent(freshStored)
+		if err != nil {
+			return nil, err
+		}
+		if !removed {
+			return storedTokenAfterGenerationChange(retained, opts.UserOpenId)
+		}
+		if opts.ErrOut != nil {
+			fmt.Fprintf(opts.ErrOut, "[lark-cli] uat-client: refresh_token expired for %s, clearing\n", opts.UserOpenId)
+		}
+		return nil, nil
+	}
+
+	if err := ensureDirWritable(lockDir, "tmp_writetest-*"); err != nil {
+		if opts.ErrOut != nil {
+			fmt.Fprintf(opts.ErrOut,
+				"[lark-cli] [WARN] uat-client: refresh lock directory is not writable while refreshing: %v\n",
+				err)
+		}
+		return nil, err
 	}
 
 	// 4. Actually perform the refresh
-	return doRefreshToken(httpClient, opts, stored)
+	return doRefreshToken(httpClient, opts, freshStored)
+}
+
+const refreshMaxAttempts = 2
+
+type refreshRequest struct {
+	GrantType    string `json:"grant_type"`
+	RefreshToken string `json:"refresh_token"`
+	ClientID     string `json:"client_id"`
+	ClientSecret string `json:"client_secret"`
+}
+
+// refreshResponse contains only fields documented by the OAuth token endpoint.
+// Pointers distinguish an omitted numeric field from a real zero value.
+type refreshResponse struct {
+	Code                  *int   `json:"code"`
+	AccessToken           string `json:"access_token"`
+	ExpiresIn             *int64 `json:"expires_in"`
+	RefreshToken          string `json:"refresh_token"`
+	RefreshTokenExpiresIn *int64 `json:"refresh_token_expires_in"`
+	TokenType             string `json:"token_type"`
+	Scope                 string `json:"scope"`
+	Error                 string `json:"error"`
+	ErrorDescription      string `json:"error_description"`
+}
+
+// refreshAction describes both retry behavior and local token disposition.
+type refreshAction uint8
+
+const (
+	// refreshSaveResponse saves a successful response.
+	refreshSaveResponse refreshAction = iota
+	// refreshRetryAndPreserve retries, preserving the stored token if retry fails.
+	refreshRetryAndPreserve
+	// refreshRetryAndClear retries, clearing the stored token if retry fails.
+	refreshRetryAndClear
+	// refreshStopAndPreserve stops without clearing the stored token.
+	refreshStopAndPreserve
+	// refreshStopAndClear stops and clears the stored token.
+	refreshStopAndClear
+)
+
+type refreshResult struct {
+	action   refreshAction
+	response refreshResponse
+	err      error
 }
 
 // doRefreshToken performs the actual HTTP request to refresh the token.
@@ -177,141 +245,318 @@ func doRefreshToken(httpClient *http.Client, opts UATCallOptions, stored *Stored
 		errOut = os.Stderr
 	}
 
-	now := time.Now().UnixMilli()
-	if now >= stored.RefreshExpiresAt {
+	if time.Now().UnixMilli() >= stored.RefreshExpiresAt {
 		fmt.Fprintf(errOut, "[lark-cli] uat-client: refresh_token expired for %s, clearing\n", opts.UserOpenId)
-		if err := RemoveStoredToken(opts.AppId, opts.UserOpenId); err != nil {
+		retained, removed, err := removeStoredTokenIfCurrent(stored)
+		if err != nil {
 			fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: failed to remove expired token: %v\n", err)
+			return nil, err
+		}
+		if !removed {
+			return storedTokenAfterGenerationChange(retained, opts.UserOpenId)
 		}
 		return nil, nil
 	}
 
-	endpoints := ResolveOAuthEndpoints(opts.Domain)
+	endpoint := ResolveOAuthEndpoints(opts.Domain).Token
+	uncertain := false
+	for attempt := 1; attempt <= refreshMaxAttempts; attempt++ {
+		result := refreshOnce(httpClient, endpoint, opts, stored)
+		if result.action == refreshSaveResponse {
+			return saveRefreshResponse(opts, stored, result.response)
+		}
 
-	callEndpoint := func() (map[string]interface{}, error) {
-		form := url.Values{}
-		form.Set("grant_type", "refresh_token")
-		form.Set("refresh_token", stored.RefreshToken)
-		form.Set("client_id", opts.AppId)
-		form.Set("client_secret", opts.AppSecret)
+		switch result.action {
+		case refreshRetryAndPreserve, refreshRetryAndClear:
+			if result.action == refreshRetryAndClear {
+				uncertain = true
+			}
+			if attempt < refreshMaxAttempts {
+				fmt.Fprintf(errOut,
+					"[lark-cli] [WARN] uat-client: refresh attempt %d/%d failed for %s: %v; retrying\n",
+					attempt, refreshMaxAttempts, opts.UserOpenId, result.err)
+				continue
+			}
+		case refreshStopAndPreserve, refreshStopAndClear:
+		default:
+			return nil, errs.NewInternalError(errs.SubtypeUnknown,
+				"unrecognized token refresh action %d", result.action)
+		}
 
-		req, err := http.NewRequest("POST", endpoints.Token, strings.NewReader(form.Encode()))
+		clearToken := result.action == refreshStopAndClear ||
+			result.action == refreshRetryAndClear ||
+			(result.action == refreshRetryAndPreserve && uncertain)
+		if !clearToken {
+			fmt.Fprintf(errOut,
+				"[lark-cli] [WARN] uat-client: refresh failed for %s, preserving token: %v\n",
+				opts.UserOpenId, result.err)
+			return nil, result.err
+		}
+
+		if problem, ok := errs.ProblemOf(result.err); ok {
+			problem.Retryable = false
+		}
+		retained, removed, err := removeStoredTokenIfCurrent(stored)
 		if err != nil {
+			fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: failed to remove token: %v\n", err)
 			return nil, err
 		}
-		req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-
-		resp, err := httpClient.Do(req)
-		if err != nil {
-			return nil, err
+		if !removed {
+			fmt.Fprintf(errOut,
+				"[lark-cli] [WARN] uat-client: stored token changed during refresh for %s, preserving current token\n",
+				opts.UserOpenId)
+			return storedTokenAfterGenerationChange(retained, opts.UserOpenId)
 		}
-		defer resp.Body.Close()
-		logHTTPResponse(resp)
-
-		body, err := io.ReadAll(resp.Body)
-		if err != nil {
-			return nil, fmt.Errorf("token refresh read error: %v", err)
-		}
-		var data map[string]interface{}
-		if err := json.Unmarshal(body, &data); err != nil {
-			return nil, fmt.Errorf("token refresh parse error: %w", err)
-		}
-		return data, nil
+		fmt.Fprintf(errOut,
+			"[lark-cli] [WARN] uat-client: refresh failed for %s, token cleared: %v\n",
+			opts.UserOpenId, result.err)
+		return nil, result.err
 	}
 
-	data, err := callEndpoint()
+	return nil, errs.NewInternalError(errs.SubtypeUnknown,
+		"token refresh exhausted attempts without a result")
+}
+
+func refreshOnce(httpClient *http.Client, endpoint string, opts UATCallOptions, stored *StoredUAToken) refreshResult {
+	payload, err := json.Marshal(refreshRequest{
+		GrantType:    "refresh_token",
+		RefreshToken: stored.RefreshToken,
+		ClientID:     opts.AppId,
+		ClientSecret: opts.AppSecret,
+	})
 	if err != nil {
-		return nil, err
-	}
-
-	code := getInt(data, "code", -1)
-	meta, metaOK := errclass.LookupCodeMeta(code)
-	if metaOK && meta.Category == errs.CategoryPolicy {
-		challengeUrl := getStr(data, "challenge_url")
-		cliHint := getStr(data, "cli_hint")
-		msg := getStr(data, "error_description")
-
-		return nil, &errs.SecurityPolicyError{
-			Problem: errs.Problem{
-				Category: errs.CategoryPolicy,
-				Subtype:  meta.Subtype,
-				Code:     code,
-				Message:  msg,
-				Hint:     cliHint,
-			},
-			ChallengeURL: challengeUrl,
+		return refreshResult{
+			action: refreshStopAndPreserve,
+			err: errs.NewInternalError(errs.SubtypeSDKError,
+				"failed to encode token refresh request: %v", err).
+				WithCause(err),
 		}
 	}
 
-	errStr := getStr(data, "error")
+	var wroteRequest atomic.Bool
+	trace := &httptrace.ClientTrace{
+		WroteRequest: func(httptrace.WroteRequestInfo) {
+			wroteRequest.Store(true)
+		},
+	}
+	ctx := httptrace.WithClientTrace(context.Background(), trace)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(payload))
+	if err != nil {
+		return refreshResult{
+			action: refreshStopAndPreserve,
+			err: errs.NewInternalError(errs.SubtypeSDKError,
+				"failed to create token refresh request: %v", err).
+				WithCause(err),
+		}
+	}
+	req.Header.Set("Content-Type", "application/json; charset=utf-8")
 
-	if (code != -1 && code != 0) || errStr != "" {
-		// Retryable server error: retry once, then clear token on second failure.
-		if metaOK && meta.Category == errs.CategoryAuthentication && meta.Retryable {
-			fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: refresh transient error (code=%d) for %s, retrying once\n", code, opts.UserOpenId)
-			data, err = callEndpoint()
-			if err != nil {
-				fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: refresh retry network error for %s, clearing token\n", opts.UserOpenId)
-				if err := RemoveStoredToken(opts.AppId, opts.UserOpenId); err != nil {
-					fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: failed to remove token: %v\n", err)
-				}
-				return nil, nil
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		action := refreshRetryAndPreserve
+		if wroteRequest.Load() {
+			action = refreshRetryAndClear
+		}
+		return refreshResult{action: action, err: err}
+	}
+	defer resp.Body.Close()
+	logHTTPResponse(resp)
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return refreshResult{
+			action: refreshRetryAndClear,
+			err: errs.NewNetworkError(errs.SubtypeNetworkTransport,
+				"token refresh response read failed: %v", err).
+				WithRetryable().
+				WithCause(err),
+		}
+	}
+
+	var parsed refreshResponse
+	if err := json.Unmarshal(body, &parsed); err != nil {
+		return refreshResult{
+			action: refreshRetryAndClear,
+			err: errs.NewInternalError(errs.SubtypeInvalidResponse,
+				"token refresh returned invalid JSON: %v", err).
+				WithRetryable().
+				WithCause(err),
+		}
+	}
+	if parsed.Code == nil {
+		return refreshResult{
+			action: refreshRetryAndClear,
+			err: errs.NewInternalError(errs.SubtypeInvalidResponse,
+				"token refresh response is missing required field code").
+				WithRetryable(),
+		}
+	}
+
+	code := *parsed.Code
+	if code != 0 {
+		if meta, ok := errclass.LookupCodeMeta(code); ok && meta.Category == errs.CategoryPolicy {
+			var policyFields struct {
+				ChallengeURL string `json:"challenge_url"`
+				CLIHint      string `json:"cli_hint"`
 			}
-			code = getInt(data, "code", -1)
-			errStr = getStr(data, "error")
-			if (code != -1 && code != 0) || errStr != "" {
-				fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: refresh failed after retry (code=%d) for %s, clearing token\n", code, opts.UserOpenId)
-				if err := RemoveStoredToken(opts.AppId, opts.UserOpenId); err != nil {
-					fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: failed to remove token: %v\n", err)
-				}
-				return nil, nil
+			_ = json.Unmarshal(body, &policyFields)
+			return refreshResult{
+				action: refreshStopAndPreserve,
+				err: &errs.SecurityPolicyError{
+					Problem: errs.Problem{
+						Category: errs.CategoryPolicy,
+						Subtype:  meta.Subtype,
+						Code:     code,
+						Message:  parsed.ErrorDescription,
+						Hint:     policyFields.CLIHint,
+					},
+					ChallengeURL: policyFields.ChallengeURL,
+				},
 			}
-			// Retry succeeded, fall through to parse token below.
+		}
+
+		message := parsed.ErrorDescription
+		if message == "" {
+			message = parsed.Error
+		}
+		// BuildAPIError accepts the common OpenAPI message key; OAuth names
+		// the same value error_description.
+		apiErr := errclass.BuildAPIError(map[string]any{
+			"code": code,
+			"msg":  message,
+		}, errclass.ClassifyContext{
+			Brand:    string(opts.Domain),
+			AppID:    opts.AppId,
+			Identity: "user",
+		})
+		if authErr, ok := apiErr.(*errs.AuthenticationError); ok {
+			authErr.UserOpenID = opts.UserOpenId
+		}
+		return refreshResult{action: refreshActionForCode(code), err: apiErr}
+	}
+
+	if parsed.RefreshToken == "" {
+		parsed.RefreshToken = stored.RefreshToken
+	}
+
+	if parsed.AccessToken == "" {
+		return refreshResult{
+			action: refreshStopAndPreserve,
+			err: errs.NewInternalError(errs.SubtypeInvalidResponse,
+				"token refresh response is missing required field access_token").
+				WithRetryable(),
+		}
+	}
+
+	if parsed.ExpiresIn == nil || *parsed.ExpiresIn <= 0 {
+		parsed.ExpiresIn = new(int64)
+		*parsed.ExpiresIn = 7200 // 2 hours
+	}
+
+	if parsed.RefreshTokenExpiresIn == nil || *parsed.RefreshTokenExpiresIn <= 0 {
+		parsed.RefreshTokenExpiresIn = new(int64)
+		if stored.RefreshExpiresAt <= 0 {
+			*parsed.RefreshTokenExpiresIn = 2592000 // 30 days
 		} else {
-			// All other errors: clear token, require re-authorization.
-			fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: refresh failed (code=%d), clearing token for %s\n", code, opts.UserOpenId)
-			if err := RemoveStoredToken(opts.AppId, opts.UserOpenId); err != nil {
-				fmt.Fprintf(errOut, "[lark-cli] [WARN] uat-client: failed to remove token: %v\n", err)
-			}
-			return nil, nil
+			now := time.Now().UnixMilli()
+			*parsed.RefreshTokenExpiresIn = (stored.RefreshExpiresAt - now) / 1000
 		}
 	}
 
-	accessToken := getStr(data, "access_token")
-	if accessToken == "" {
-		return nil, fmt.Errorf("Token refresh returned no access_token")
-	}
+	return refreshResult{action: refreshSaveResponse, response: parsed}
+}
 
-	refreshToken := getStr(data, "refresh_token")
-	if refreshToken == "" {
-		refreshToken = stored.RefreshToken
+func refreshActionForCode(code int) refreshAction {
+	meta, ok := errclass.LookupCodeMeta(code)
+	switch {
+	case !ok:
+		return refreshRetryAndClear
+	case meta.Category == errs.CategoryPolicy:
+		return refreshStopAndPreserve
+	case meta.Retryable:
+		return refreshRetryAndPreserve
+	default:
+		return refreshStopAndClear
 	}
+}
 
-	expiresIn := getInt(data, "expires_in", 7200)
-	refreshExpiresIn := getInt(data, "refresh_token_expires_in", 0)
-	refreshExpiresAt := stored.RefreshExpiresAt
-	if refreshExpiresIn > 0 {
-		refreshExpiresAt = now + int64(refreshExpiresIn)*1000
-	}
-
-	scope := getStr(data, "scope")
-	if scope == "" {
-		scope = stored.Scope
-	}
+func saveRefreshResponse(opts UATCallOptions, stored *StoredUAToken, response refreshResponse) (*StoredUAToken, error) {
+	now := time.Now().UnixMilli()
 
 	updated := &StoredUAToken{
 		UserOpenId:       stored.UserOpenId,
 		AppId:            opts.AppId,
-		AccessToken:      accessToken,
-		RefreshToken:     refreshToken,
-		ExpiresAt:        now + int64(expiresIn)*1000,
-		RefreshExpiresAt: refreshExpiresAt,
-		Scope:            scope,
+		AccessToken:      response.AccessToken,
+		RefreshToken:     response.RefreshToken,
+		ExpiresAt:        now + *response.ExpiresIn*1000,
+		RefreshExpiresAt: now + *response.RefreshTokenExpiresIn*1000,
+		Scope:            response.Scope,
 		GrantedAt:        stored.GrantedAt,
 	}
-
-	if err := SetStoredToken(updated); err != nil {
+	current, saved, err := setStoredTokenIfCurrent(stored, updated)
+	if err != nil {
 		return nil, err
 	}
+	if !saved {
+		if opts.ErrOut != nil {
+			fmt.Fprintf(opts.ErrOut,
+				"[lark-cli] [WARN] uat-client: stored token changed during refresh for %s, preserving current token\n",
+				opts.UserOpenId)
+		}
+		return storedTokenAfterGenerationChange(current, opts.UserOpenId)
+	}
 	return updated, nil
 }
+
+func storedTokenAfterGenerationChange(current *StoredUAToken, userOpenId string) (*StoredUAToken, error) {
+	if current == nil {
+		return nil, nil
+	}
+	if TokenStatus(current) == "valid" {
+		return current, nil
+	}
+	return nil, errs.NewInternalError(errs.SubtypeStorage,
+		"stored refresh token changed while refreshing user %q", userOpenId).
+		WithRetryable().
+		WithHint("retry the command")
+}
+
+func ensureDirWritable(dir, tempPrefix string) error {
+	if dir == "" {
+		return nil
+	}
+
+	if err := vfs.MkdirAll(dir, 0700); err != nil {
+		return errs.NewInternalError(errs.SubtypeFileIO,
+			"failed to access refresh lock directory %q", dir).
+			WithCause(err).
+			WithHint("If running in a sandbox or read-only workspace, grant write access for this directory and retry.")
+	}
+
+	tmp, err := vfs.CreateTemp(dir, tempPrefix)
+	if err != nil {
+		return errs.NewInternalError(errs.SubtypeFileIO,
+			"failed to create temporary file in refresh lock directory %q", dir).
+			WithCause(err).
+			WithHint("If running in a sandbox or read-only workspace, grant write access for this directory and retry.")
+	}
+
+	tmpName := tmp.Name()
+	closeErr := tmp.Close()
+	if removeErr := vfs.Remove(tmpName); removeErr != nil {
+		err := fmt.Errorf("%v", removeErr)
+		if closeErr != nil {
+			err = fmt.Errorf("%v; also failed to close temp file: %v", removeErr, closeErr)
+		}
+		return errs.NewInternalError(errs.SubtypeFileIO,
+			"failed to clean up refresh lock write-check file %q", tmpName).
+			WithCause(err)
+	}
+	if closeErr != nil {
+		return errs.NewInternalError(errs.SubtypeFileIO,
+			"failed to close refresh lock write-check file %q", tmpName).
+			WithCause(closeErr)
+	}
+
+	return nil
+}

internal/errclass/codemeta.go

@@ -38,11 +38,13 @@ var codeMeta = map[int]CodeMeta{
 	99991668: {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeTokenInvalid},                        // UAT invalid/expired (server does not distinguish)
 	99991663: {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeTokenInvalid},                        // access_token invalid
 	99991677: {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeTokenExpired},                        // UAT expired
-	20026:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshTokenInvalid},                 // refresh_token v1 legacy format
+	20024:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshTokenInvalid},                 // authorization code or refresh_token does not match client_id
+	20026:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshTokenInvalid},                 // refresh_token is invalid or v1 legacy format
 	20037:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshTokenExpired},                 // refresh_token expired
-	20064:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshTokenRevoked},                 // refresh_token revoked
-	20073:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshTokenReused},                  // refresh_token already used
 	20050:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshServerError, Retryable: true}, // refresh endpoint transient error
+	20064:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshTokenRevoked},                 // refresh_token revoked
+	20072:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshServerError},                  // refresh endpoint temporarily unavailable
+	20073:    {Category: errs.CategoryAuthentication, Subtype: errs.SubtypeRefreshTokenReused},                  // refresh_token already used
 
 	// CategoryAuthorization
 	99991672: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeAppScopeNotApplied},
@@ -51,6 +53,13 @@ var codeMeta = map[int]CodeMeta{
 	230027:   {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeUserUnauthorized}, // user never authorized the app
 	99991673: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeAppUnavailable},   // app status unavailable
 	99991662: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeAppDisabled},      // app currently disabled in tenant
+	20008:    {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeUserUnauthorized}, // user does not exist
+	20009:    {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeAppUnavailable},   // app specified is not installed
+	20010:    {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeUserUnauthorized}, // user does not have permission to use this app
+	20048:    {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeAppUnavailable},   // app specified is not exist
+	20066:    {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeUserUnauthorized}, // user staus is not normal
+	20069:    {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeAppDisabled},      // app specified is disabled
+	20074:    {Category: errs.CategoryAuthorization, Subtype: errs.SubtypeAppUnavailable},   // app specified not allows for refresh token
 
 	// CategoryAPI
 	99991400: {Category: errs.CategoryAPI, Subtype: errs.SubtypeRateLimit, Retryable: true},
@@ -62,10 +71,17 @@ var codeMeta = map[int]CodeMeta{
 	1063006:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeRateLimit}, // drive perm-apply quota; 5/day, not short-term retryable
 	1063007:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},
 	231205:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeOwnershipMismatch},
+	20001:    {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // request missing required parameter
+	20036:    {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // grant_type not supported
+	20063:    {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // request format error
+	20067:    {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // scope list contains duplicated items
+	20068:    {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // scope list contains forbidden permissions
+	20070:    {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // request provide multiple authorization methods
 
 	// CategoryConfig
 	99991543: {Category: errs.CategoryConfig, Subtype: errs.SubtypeInvalidClient}, // RFC 6749 §5.2 — app_id / app_secret incorrect (Open API)
 	10014:    {Category: errs.CategoryConfig, Subtype: errs.SubtypeInvalidClient}, // legacy TAT endpoint — "app secret invalid" (pre-v3 variant of 99991543; CLI now reports invalid_client)
+	20002:    {Category: errs.CategoryConfig, Subtype: errs.SubtypeInvalidClient}, // client secret invalid
 
 	// CategoryPolicy
 	21000: {Category: errs.CategoryPolicy, Subtype: errs.SubtypeChallengeRequired},

internal/errclass/codemeta_test.go

@@ -23,11 +23,27 @@ func TestLookupCodeMeta_CredentialCodes(t *testing.T) {
 		{99991668, errs.CategoryAuthentication, errs.SubtypeTokenInvalid, false},
 		{99991663, errs.CategoryAuthentication, errs.SubtypeTokenInvalid, false},
 		{99991677, errs.CategoryAuthentication, errs.SubtypeTokenExpired, false},
+		{20024, errs.CategoryAuthentication, errs.SubtypeRefreshTokenInvalid, false},
 		{20026, errs.CategoryAuthentication, errs.SubtypeRefreshTokenInvalid, false},
 		{20037, errs.CategoryAuthentication, errs.SubtypeRefreshTokenExpired, false},
-		{20064, errs.CategoryAuthentication, errs.SubtypeRefreshTokenRevoked, false},
-		{20073, errs.CategoryAuthentication, errs.SubtypeRefreshTokenReused, false},
 		{20050, errs.CategoryAuthentication, errs.SubtypeRefreshServerError, true},
+		{20064, errs.CategoryAuthentication, errs.SubtypeRefreshTokenRevoked, false},
+		{20072, errs.CategoryAuthentication, errs.SubtypeRefreshServerError, false},
+		{20073, errs.CategoryAuthentication, errs.SubtypeRefreshTokenReused, false},
+		{20008, errs.CategoryAuthorization, errs.SubtypeUserUnauthorized, false},
+		{20009, errs.CategoryAuthorization, errs.SubtypeAppUnavailable, false},
+		{20010, errs.CategoryAuthorization, errs.SubtypeUserUnauthorized, false},
+		{20048, errs.CategoryAuthorization, errs.SubtypeAppUnavailable, false},
+		{20066, errs.CategoryAuthorization, errs.SubtypeUserUnauthorized, false},
+		{20069, errs.CategoryAuthorization, errs.SubtypeAppDisabled, false},
+		{20074, errs.CategoryAuthorization, errs.SubtypeAppUnavailable, false},
+		{20001, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{20036, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{20063, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{20067, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{20068, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{20070, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{20002, errs.CategoryConfig, errs.SubtypeInvalidClient, false},
 	}
 	for _, tc := range cases {
 		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {

internal/qualitygate/config/allowlists/public-domains.txt

@@ -15,5 +15,4 @@ registry.npmjs.org
 registry.npmmirror.com
 sf16-sg.tiktokcdn.com
 www.feishu.cn
-www.larkoffice.com
 www.larksuite.com

shortcuts/apps/apps_cache_clear.go

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsCacheClear clears all cache entries for the app in the given environment.
+//
+// POST /apps/{app_id}/cache/clear，body {env}。清空当前应用指定环境下全部缓存，用于无法定位
+// 具体 key 的快速恢复；影响面大，定 high-risk-write（框架自动注入 --yes 确认）。
+var AppsCacheClear = common.Shortcut{
+	Service:     appsService,
+	Command:     "+cache-clear",
+	Description: "Clear all cache entries for the app in the given environment",
+	Risk:        "high-risk-write",
+	Tips: []string{
+		"Example: lark-cli apps +cache-clear --app-id <app_id> --environment dev --yes",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		cacheEnvFlag(),
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(appCacheClearPath(appID)).
+			Desc("Clear all cache entries for the app in the given environment").
+			Body(dbEnvParams(rctx, map[string]interface{}{}))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("POST", appCacheClearPath(appID), nil, dbEnvParams(rctx, map[string]interface{}{}))
+		if err != nil {
+			return withAppsHint(err, appIDListHint)
+		}
+		out := map[string]interface{}{
+			"environment":       resolvedEnv(data, rctx),
+			"deleted_key_count": cacheInt(data["deleted_key_count"]),
+		}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderCacheClearPretty(w, out)
+		})
+		return nil
+	},
+}
+
+// renderCacheClearPretty 打 "✓ cache cleared: N entries (env)"。
+func renderCacheClearPretty(w io.Writer, out map[string]interface{}) {
+	n := int64(0)
+	if f, ok := numericAsFloat(out["deleted_key_count"]); ok {
+		n = int64(f)
+	}
+	fmt.Fprintf(w, "✓ cache cleared: %d entries (%s)\n", n, common.GetString(out, "environment"))
+}

shortcuts/apps/apps_cache_delete.go

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsCacheDelete deletes a single business cache key (idempotent).
+//
+// DELETE /apps/{app_id}/cache?env=&key=。缓存是派生数据、删单 key 影响面小且可重建，
+// 故定 write（非 high-risk-write、不需 --yes）。目标不存在按幂等成功处理（deleted_key_count=0）。
+var AppsCacheDelete = common.Shortcut{
+	Service:     appsService,
+	Command:     "+cache-delete",
+	Description: "Delete a single business cache key (idempotent)",
+	Risk:        "write",
+	Tips: []string{
+		"Example: lark-cli apps +cache-delete --app-id <app_id> --environment dev --key <key>",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "key", Desc: "business cache key", Required: true},
+		cacheEnvFlag(),
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			DELETE(appCachePath(appID)).
+			Desc("Delete a Miaoda app runtime cache key").
+			Params(dbEnvParams(rctx, map[string]interface{}{"key": rctx.Str("key")}))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		key := rctx.Str("key")
+		data, err := rctx.CallAPITyped("DELETE", appCachePath(appID), dbEnvParams(rctx, map[string]interface{}{"key": key}), nil)
+		if err != nil {
+			return withAppsHint(err, appIDListHint)
+		}
+		out := map[string]interface{}{
+			"key":               key,
+			"environment":       resolvedEnv(data, rctx),
+			"deleted_key_count": cacheInt(data["deleted_key_count"]),
+		}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderCacheDeletePretty(w, out)
+		})
+		return nil
+	},
+}
+
+// renderCacheDeletePretty 命中打 "✓ cache deleted"，幂等未命中打 "✓ cache already absent"（措辞区分，都成功）。
+func renderCacheDeletePretty(w io.Writer, out map[string]interface{}) {
+	key := common.GetString(out, "key")
+	if n, ok := numericAsFloat(out["deleted_key_count"]); ok && n > 0 {
+		fmt.Fprintf(w, "✓ cache deleted: %s\n", key)
+		return
+	}
+	fmt.Fprintf(w, "✓ cache already absent: %s\n", key)
+}

shortcuts/apps/apps_cache_get.go

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsCacheGet reads a single business cache key's value + metadata.
+//
+// GET /apps/{app_id}/cache?env=&key=。value 在 wire 上是 JSON 字符串透传：--format json
+// 原样输出该字符串（不反序列化），--format pretty 反序列化后缩进展开。value_size_bytes 由 CLI
+// 按 value 字节长度算出（端点不返回）；未命中（exists=false）时不带 value，ttl_ms/value_size_bytes 为 null。
+var AppsCacheGet = common.Shortcut{
+	Service:     appsService,
+	Command:     "+cache-get",
+	Description: "Get a business cache key's value and metadata",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +cache-get --app-id <app_id> --key spotbonus:2026:winners:list:v1",
+		"Example: lark-cli apps +cache-get --app-id <app_id> --environment online --key <key>",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "key", Desc: "business cache key", Required: true},
+		cacheEnvFlag(),
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appCachePath(appID)).
+			Desc("Get a Miaoda app runtime cache key").
+			Params(dbEnvParams(rctx, map[string]interface{}{"key": rctx.Str("key")}))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		key := rctx.Str("key")
+		data, err := rctx.CallAPITyped("GET", appCachePath(appID), dbEnvParams(rctx, map[string]interface{}{"key": key}), nil)
+		if err != nil {
+			return withAppsHint(err, appIDListHint)
+		}
+		out := projectCacheGet(data, key, rctx)
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderCacheGetPretty(w, out)
+		})
+		return nil
+	},
+}
+
+// projectCacheGet 组装 cache-get 输出：key 回显、environment 取 resolved env、exists 直读；
+// 命中时带 ttl_ms + value（原始串）+ value_size_bytes（CLI 算），未命中时 ttl_ms/value_size_bytes 为 null、无 value。
+func projectCacheGet(data map[string]interface{}, key string, rctx *common.RuntimeContext) map[string]interface{} {
+	exists := cacheBool(data["exists"])
+	out := map[string]interface{}{
+		"key":         key,
+		"environment": resolvedEnv(data, rctx),
+		"exists":      exists,
+	}
+	if exists {
+		val := common.GetString(data, "value")
+		out["ttl_ms"] = cacheInt(data["ttl_ms"])
+		out["value_size_bytes"] = len([]byte(val))
+		out["value"] = val
+	} else {
+		out["ttl_ms"] = nil
+		out["value_size_bytes"] = nil
+	}
+	return out
+}
+
+// renderCacheGetPretty 打元信息块（key/environment/exists，命中再加 ttl/value_size），命中时末尾展开 value。
+func renderCacheGetPretty(w io.Writer, out map[string]interface{}) {
+	exists, _ := out["exists"].(bool)
+	pairs := [][2]string{
+		{"key", common.GetString(out, "key")},
+		{"environment", common.GetString(out, "environment")},
+		{"exists", fmt.Sprintf("%v", exists)},
+	}
+	if exists {
+		pairs = append(pairs,
+			[2]string{"ttl", formatCacheTTL(out["ttl_ms"])},
+			[2]string{"value_size", humanBytes(out["value_size_bytes"])},
+		)
+	}
+	renderKeyValuePairs(w, pairs)
+	if exists {
+		fmt.Fprintln(w, "value:")
+		printCacheValuePretty(w, common.GetString(out, "value"))
+	}
+}

shortcuts/apps/apps_cache_test.go

@@ -0,0 +1,357 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const (
+	cacheURL      = "/open-apis/spark/v1/apps/app_x/cache"
+	cacheClearURL = "/open-apis/spark/v1/apps/app_x/cache/clear"
+)
+
+// cacheValueStr 是服务端在 wire 上透传的原始 JSON 字符串（value 不反序列化）。
+const cacheValueStr = `[{"name":"Alice","award":"Gold"},{"name":"Bob","award":"Silver"}]`
+
+// ── cache-get ──
+
+// TestAppsCacheGet_HitJSON：命中时 json 默认——value 原样透传（不反序列化），
+// value_size_bytes 由 CLI 按 value 字节长度算出，environment 取服务端 resolved env。
+func TestAppsCacheGet_HitJSON(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": true, "ttl_ms": 272000, "value": cacheValueStr,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if d["key"] != "k:1" || d["environment"] != "online" || d["exists"] != true {
+		t.Fatalf("get hit data=%v", d)
+	}
+	if v, _ := d["value"].(string); v != cacheValueStr {
+		t.Fatalf("value must be raw passthrough string, got %v", d["value"])
+	}
+	if sz, _ := numericAsFloat(d["value_size_bytes"]); int(sz) != len(cacheValueStr) {
+		t.Fatalf("value_size_bytes = %v, want %d", d["value_size_bytes"], len(cacheValueStr))
+	}
+	// ttl_ms 必须是 JSON number（透传服务端数字，不得变成字符串）；JSON 解析后为 float64。
+	if _, ok := d["ttl_ms"].(float64); !ok {
+		t.Fatalf("ttl_ms must be a JSON number, got %T (%v)", d["ttl_ms"], d["ttl_ms"])
+	}
+}
+
+// TestAppsCacheGet_HitPretty：pretty 把 value 反序列化后展开（含缩进后的字段），并打元信息标签。
+func TestAppsCacheGet_HitPretty(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": true, "ttl_ms": 272000, "value": cacheValueStr,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{"key", "environment", "exists", "value", "Alice"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("pretty missing %q:\n%s", want, got)
+		}
+	}
+}
+
+// TestAppsCacheGet_Miss：未命中——exists=false，无 value，ttl_ms / value_size_bytes 为 null。
+func TestAppsCacheGet_Miss(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": false,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if d["exists"] != false {
+		t.Fatalf("miss exists=%v", d["exists"])
+	}
+	if _, ok := d["value"]; ok {
+		t.Fatalf("miss must not carry value: %v", d)
+	}
+	if d["ttl_ms"] != nil || d["value_size_bytes"] != nil {
+		t.Fatalf("miss ttl_ms/value_size_bytes must be null: %v", d)
+	}
+}
+
+// TestAppsCacheGet_ExistsAsString：服务端把 exists 返成字符串 "true" 时仍按命中处理
+// （cacheBool 容错，防 exists 以字符串形态出现被误判成未命中、hit→miss 翻转）。
+func TestAppsCacheGet_ExistsAsString(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": "true", "ttl_ms": 272000, "value": cacheValueStr,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if d["exists"] != true {
+		t.Fatalf("exists string \"true\" 应按命中解析, got exists=%v", d["exists"])
+	}
+	if v, _ := d["value"].(string); v != cacheValueStr {
+		t.Fatalf("命中应带 value, got %v", d["value"])
+	}
+}
+
+// TestAppsCacheGet_PrettyNonJSONFallback：pretty 下 value 不是合法 JSON 时降级原样输出
+// （safeParseJSON 解析失败→原样打印，不报错、不吞值）。补齐 HitPretty 只覆盖了"能反序列化"路径的缺口。
+func TestAppsCacheGet_PrettyNonJSONFallback(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": true, "ttl_ms": 272000, "value": "hello-plain-not-json",
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "hello-plain-not-json") {
+		t.Fatalf("非 JSON value 应原样输出（降级）, got:\n%s", stdout.String())
+	}
+}
+
+// TestAppsCacheGet_TTLAsStringNormalized：服务端把 ttl_ms 返成字符串 "272000" 时，
+// 输出的 ttl_ms 必须归一成 JSON number（cacheInt），不得随 wire 形态漂移成字符串。
+func TestAppsCacheGet_TTLAsStringNormalized(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": true, "ttl_ms": "272000", "value": cacheValueStr,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	f, ok := d["ttl_ms"].(float64)
+	if !ok {
+		t.Fatalf("ttl_ms string wire 应归一成 JSON number, got %T (%v)", d["ttl_ms"], d["ttl_ms"])
+	}
+	if int(f) != 272000 {
+		t.Fatalf("ttl_ms = %v, want 272000", f)
+	}
+}
+
+// TestAppsCacheDelete_CountAsStringNormalized：服务端把 deleted_key_count 返成字符串 "1" 时，
+// 输出必须归一成 JSON number（cacheInt）。
+func TestAppsCacheDelete_CountAsStringNormalized(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": "1"}},
+	})
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if _, ok := d["deleted_key_count"].(float64); !ok {
+		t.Fatalf("deleted_key_count string wire 应归一成 JSON number, got %T (%v)", d["deleted_key_count"], d["deleted_key_count"])
+	}
+}
+
+// TestAppsCacheGet_DryRunOmitsEnv：不传 --environment 时 dry-run query 不带 env（服务端自动选），但带 key。
+func TestAppsCacheGet_DryRunOmitsEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--key", "k:1", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if a.Method != "GET" || a.URL != cacheURL {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	if _, ok := a.Params["env"]; ok {
+		t.Fatalf("no --environment → env must be omitted, params=%v", a.Params)
+	}
+	if a.Params["key"] != "k:1" {
+		t.Fatalf("key must be in query, params=%v", a.Params)
+	}
+}
+
+// TestAppsCacheGet_DryRunWithEnv：显式 --environment dev → query 带 env=dev。
+func TestAppsCacheGet_DryRunWithEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if a.Params["env"] != "dev" {
+		t.Fatalf("env must be dev, params=%v", a.Params)
+	}
+}
+
+// TestAppsCacheGet_RequiresKey：缺 --key → 校验错。
+func TestAppsCacheGet_RequiresKey(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--as", "user"}, factory, stdout); err == nil {
+		t.Fatalf("expected required --key error")
+	}
+}
+
+// ── cache-delete ──
+
+// TestAppsCacheDelete_Hit：删中命中的 key → deleted_key_count=1；pretty 打 "✓ cache deleted"。
+func TestAppsCacheDelete_Hit(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": 1}},
+	})
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "✓ cache deleted") {
+		t.Fatalf("pretty: %s", stdout.String())
+	}
+}
+
+// TestAppsCacheDelete_AbsentJSON：目标不存在 → 幂等成功，deleted_key_count=0，pretty 措辞区分。
+func TestAppsCacheDelete_AbsentJSON(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": 0}},
+	})
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if sz, _ := numericAsFloat(d["deleted_key_count"]); int(sz) != 0 || d["key"] != "k:1" || d["environment"] != "dev" {
+		t.Fatalf("absent data=%v", d)
+	}
+}
+
+// TestAppsCacheDelete_AbsentPretty：不存在 pretty 打 "✓ cache already absent"。
+func TestAppsCacheDelete_AbsentPretty(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": 0}},
+	})
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "already absent") {
+		t.Fatalf("pretty: %s", stdout.String())
+	}
+}
+
+// TestAppsCacheDelete_DryRun：DELETE 方法、/cache 路由，query 带 key + env。
+func TestAppsCacheDelete_DryRun(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if a.Method != "DELETE" || a.URL != cacheURL {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	if a.Params["key"] != "k:1" || a.Params["env"] != "dev" {
+		t.Fatalf("params=%v", a.Params)
+	}
+}
+
+// ── cache-clear ──
+
+// TestAppsCacheClear_Success：清空成功 → deleted_key_count=128；pretty 打 "✓ cache cleared: 128 entries (dev)"。
+func TestAppsCacheClear_Success(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: cacheClearURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": 128}},
+	})
+	if err := runAppsShortcut(t, AppsCacheClear,
+		[]string{"+cache-clear", "--app-id", "app_x", "--environment", "dev", "--yes", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "✓ cache cleared: 128 entries (dev)") {
+		t.Fatalf("pretty: %s", stdout.String())
+	}
+}
+
+// TestAppsCacheClear_RequiresConfirmation：high-risk-write 无 --yes → 被确认门拦截。
+func TestAppsCacheClear_RequiresConfirmation(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheClear,
+		[]string{"+cache-clear", "--app-id", "app_x", "--environment", "dev", "--as", "user"}, factory, stdout); err == nil {
+		t.Fatalf("expected confirmation gate without --yes")
+	}
+}
+
+// TestAppsCacheClear_DryRunBodyWithEnv：dry-run POST /cache/clear，body 带 env=dev。
+func TestAppsCacheClear_DryRunBodyWithEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheClear,
+		[]string{"+cache-clear", "--app-id", "app_x", "--environment", "dev", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if a.Method != "POST" || a.URL != cacheClearURL {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	if a.Body["env"] != "dev" {
+		t.Fatalf("body must carry env=dev, body=%v", a.Body)
+	}
+}
+
+// TestAppsCacheClear_DryRunBodyOmitsEnv：不传 --environment → body 不带 env（服务端自动选）。
+func TestAppsCacheClear_DryRunBodyOmitsEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheClear,
+		[]string{"+cache-clear", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if _, ok := a.Body["env"]; ok {
+		t.Fatalf("no --environment → body env must be omitted, body=%v", a.Body)
+	}
+}
+
+// firstDryRunAPI 解析 dry-run 输出的第一个 api[] 项（method/url/params/body）。
+// 复用本包规范的 dryRunAPIEnvelope（api 现嵌在 data.api 下，见 dryrun_test.go）。
+func firstDryRunAPI(t *testing.T, s string) dryRunAPICall {
+	t.Helper()
+	var env dryRunAPIEnvelope
+	if err := json.Unmarshal([]byte(s), &env); err != nil || len(env.API) == 0 {
+		t.Fatalf("bad dry-run json: %v\n%s", err, s)
+	}
+	return env.API[0]
+}

shortcuts/apps/cache_common.go

@@ -0,0 +1,99 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// 应用运行时缓存（Cache）调试命令共享件：路由 + 环境 flag + 渲染。
+//
+// 三条命令都走 spark OpenAPI `/apps/{app_id}/cache[/clear]`，按运行环境（env→dbBranch）隔离：
+// 环境 flag 用 cacheEnvFlag()（只 --environment，不带 db 家族的旧名 --env），env 值经 dbEnv 读、
+// 经 dbEnvParams 注入——get/delete 放 query，clear 放 body（省略即服务端自动选分支）。
+
+// appCachePath 返回缓存单 key 读/删 URL：cache（GET 读、DELETE 删，靠方法区分）。
+func appCachePath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/cache", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appCacheClearPath 返回清空指定环境缓存 URL：cache/clear。
+func appCacheClearPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/cache/clear", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// cacheEnvFlag 返回缓存命令的运行环境 flag。cache 是全新命令、从无旧名 --env，
+// 故只注册干净的 --environment（不带 db 家族那套隐藏 --env + 拒收逻辑）。
+// 省略即服务端按应用多环境状态自动选分支（多环境→dev，非多环境→online）。
+func cacheEnvFlag() common.Flag {
+	return common.Flag{
+		Name: "environment",
+		Enum: []string{"dev", "online"},
+		Desc: "target runtime environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online",
+	}
+}
+
+// cacheBool 防御性解析布尔：真 bool 直接用；若服务端把 exists 返成字符串 "true"/"false" 也归一成 bool，
+// 其它类型按 false。避免 exists 万一以字符串形态出现时被误判成未命中（hit→miss 翻转）。
+func cacheBool(v interface{}) bool {
+	switch x := v.(type) {
+	case bool:
+		return x
+	case string:
+		return strings.EqualFold(strings.TrimSpace(x), "true")
+	}
+	return false
+}
+
+// cacheInt 把服务端下发的数值字段归一成 int64（无法解析→nil）。本仓惯例：数值可能以字符串下发
+// （见 numericAsFloat 的 string 分支），若直接透传，--format json 的字段类型会随服务端 wire 形态漂移
+// （number ↔ string）。归一后输出类型恒定为数字或 null，消费方无需自己容忍字符串。
+func cacheInt(raw interface{}) interface{} {
+	if f, ok := numericAsFloat(raw); ok {
+		return int64(f)
+	}
+	return nil
+}
+
+// resolvedEnv 取服务端回吐的 resolved env；缺失时兜底成请求侧 --environment（可能为空）。
+// 省略 --environment 时服务端自动选分支，靠服务端回吐才知道实际命中 dev / online。
+func resolvedEnv(data map[string]interface{}, rctx *common.RuntimeContext) string {
+	if env := common.GetString(data, "env"); env != "" {
+		return env
+	}
+	return dbEnv(rctx)
+}
+
+// formatCacheTTL 把剩余 TTL（毫秒）格式化成 4m32s 这样的时长串；非数字返回 "—"。
+func formatCacheTTL(ms interface{}) string {
+	f, ok := numericAsFloat(ms)
+	if !ok {
+		return "—"
+	}
+	return (time.Duration(int64(f)) * time.Millisecond).String()
+}
+
+// printCacheValuePretty 把 value 反序列化后缩进展开（pretty 口径）；非 JSON 则原样打印。
+// 与「json 原样字符串、pretty 才反序列化」的设计一致。
+func printCacheValuePretty(w io.Writer, raw string) {
+	v := safeParseJSON(raw)
+	if s, ok := v.(string); ok {
+		fmt.Fprintln(w, s)
+		return
+	}
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		fmt.Fprintln(w, raw)
+		return
+	}
+	w.Write(b)
+	fmt.Fprintln(w)
+}

shortcuts/apps/shortcuts.go

@@ -64,6 +64,9 @@ func Shortcuts() []common.Shortcut {
 		AppsFileUpload,
 		AppsFileDelete,
 		AppsFileQuotaGet,
+		AppsCacheGet,
+		AppsCacheDelete,
+		AppsCacheClear,
 		AppsGitCredentialInit,
 		AppsGitCredentialList,
 		AppsGitCredentialRemove,

shortcuts/apps/shortcuts_test.go

@@ -20,13 +20,14 @@ import (
 //   - 3 git-credential
 //   - 5 session（create/list/get/stop/chat）+ 1 session-messages-list
 //   - 8 openapi-key（list/get/create/update/enable/disable/delete/reset）
+//   - 3 cache（get/delete/clear）
 //   - 3 plugin（install/uninstall/list）
 //   - 6 automation（list/get/create/update/enable/disable）
-//   - 9 role（role CRUD + role-member list/add/remove + role-match-list）= 79。
-func TestAppsShortcuts_Returns79(t *testing.T) {
+//   - 9 role（role CRUD + role-member list/add/remove + role-match-list）= 82。
+func TestAppsShortcuts_Returns82(t *testing.T) {
 	got := Shortcuts()
-	if len(got) != 79 {
-		t.Fatalf("Shortcuts() returned %d entries, want 79", len(got))
+	if len(got) != 82 {
+		t.Fatalf("Shortcuts() returned %d entries, want 82", len(got))
 	}
 }
 

shortcuts/base/base_form_questions_create.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"strings"
 
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -27,19 +28,23 @@ var BaseFormQuestionsCreate = common.Shortcut{
 		{Name: "form-id", Desc: "form ID", Required: true},
 		{Name: "questions", Desc: `questions JSON array, max 10 items. Each item requires "title"(field title) and "type"(text/number/select/datetime/user/attachment/location). Optional fields: "description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown/1=vertical/2=horizontal,select only),"multiple"(bool,select/user),"options"([{"name":"opt","hue":"Blue"}],select only),"style"({"type":"plain/phone/url/email/barcode/rating","precision":2,"format":"yyyy/MM/dd","icon":"star","min":1,"max":5}),"visible_rule"(display condition; same shape as view filter {"logic":"and","conditions":[["前序题目","==","是"]]}, field references another question's title/id, empty/absent = always shown). E.g. '[{"type":"text","title":"Your name","required":true}]'`, Required: true},
 	},
+	Tips: []string{
+		"If the form may already contain questions and has not been checked, run +form-questions-list for the same --base-token, --table-id, and --form-id. A verified empty form can create directly.",
+		"Each new question creates a field in the form's table; question IDs are field IDs.",
+		"Unless the user explicitly requests a separate same-title question, update an existing title with +form-questions-update instead of creating a duplicate.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := parseFormQuestionsCreate(runtime.Str("questions"))
+		return err
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		api := common.NewDryRunAPI().
+		questions, _ := parseFormQuestionsCreate(runtime.Str("questions"))
+		return common.NewDryRunAPI().
 			POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id/questions").
 			Set("base_token", runtime.Str("base-token")).
 			Set("table_id", runtime.Str("table-id")).
-			Set("form_id", runtime.Str("form-id"))
-		// Transcribe the questions body verbatim so the preview shows exactly
-		// what would be sent (including optional fields like visible_rule).
-		var questions []interface{}
-		if err := json.Unmarshal([]byte(runtime.Str("questions")), &questions); err == nil {
-			api.Body(map[string]interface{}{"questions": questions})
-		}
-		return api
+			Set("form_id", runtime.Str("form-id")).
+			Body(map[string]interface{}{"questions": questions})
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		baseToken := runtime.Str("base-token")
@@ -47,9 +52,9 @@ var BaseFormQuestionsCreate = common.Shortcut{
 		formId := runtime.Str("form-id")
 		questionsJSON := runtime.Str("questions")
 
-		var questions []interface{}
-		if err := json.Unmarshal([]byte(questionsJSON), &questions); err != nil {
-			return baseValidationErrorf("--questions must be a valid JSON array: %s", err)
+		questions, err := parseFormQuestionsCreate(questionsJSON)
+		if err != nil {
+			return err
 		}
 
 		data, err := baseV3Call(runtime, "POST",
@@ -78,3 +83,31 @@ var BaseFormQuestionsCreate = common.Shortcut{
 		return nil
 	},
 }
+
+func parseFormQuestionsCreate(raw string) ([]interface{}, error) {
+	var questions []interface{}
+	if err := json.Unmarshal([]byte(raw), &questions); err != nil {
+		return nil, baseValidationErrorf("--questions must be a valid JSON array: %s", err)
+	}
+	if questions == nil {
+		return nil, baseValidationErrorf("--questions must be a non-null JSON array")
+	}
+	if len(questions) > 10 {
+		return nil, baseValidationErrorf("--questions must contain at most 10 items")
+	}
+	for i, question := range questions {
+		item, ok := question.(map[string]interface{})
+		if !ok {
+			return nil, baseValidationErrorf("--questions item %d must be an object", i+1)
+		}
+		title, ok := item["title"].(string)
+		if !ok || strings.TrimSpace(title) == "" {
+			return nil, baseValidationErrorf("--questions item %d must include a non-empty string \"title\"", i+1)
+		}
+		questionType, ok := item["type"].(string)
+		if !ok || strings.TrimSpace(questionType) == "" {
+			return nil, baseValidationErrorf("--questions item %d must include a non-empty string \"type\"", i+1)
+		}
+	}
+	return questions, nil
+}

shortcuts/base/base_form_questions_create_tips_test.go

@@ -0,0 +1,24 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestBaseFormQuestionsCreateTipsRequireExistingQuestionCheck(t *testing.T) {
+	tips := strings.Join(BaseFormQuestionsCreate.Tips, "\n")
+	for _, want := range []string{
+		"+form-questions-list",
+		"verified empty form can create directly",
+		"question IDs are field IDs",
+		"explicitly requests a separate same-title question",
+		"+form-questions-update",
+	} {
+		if !strings.Contains(tips, want) {
+			t.Fatalf("tips missing %q:\n%s", want, tips)
+		}
+	}
+}

shortcuts/drive/drive_download.go

@@ -202,7 +202,7 @@ var DriveDownload = common.Shortcut{
 			ApiPath:    fmt.Sprintf("/open-apis/drive/v1/files/%s/download", validate.EncodePathSegment(fileToken)),
 		})
 		if err != nil {
-			return wrapDriveNetworkErr(err, "download failed: %s", err)
+			return withDriveDownloadForbiddenPreviewHint(wrapDriveNetworkErr(err, "download failed: %s", err), fileToken)
 		}
 		defer resp.Body.Close()
 

shortcuts/drive/drive_errors.go

@@ -5,6 +5,8 @@ package drive
 
 import (
 	"errors"
+	"fmt"
+	"net/http"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
@@ -21,6 +23,30 @@ func wrapDriveNetworkErr(err error, format string, args ...any) error {
 	return errs.NewNetworkError(errs.SubtypeNetworkTransport, format, args...).WithCause(err)
 }
 
+// withDriveDownloadForbiddenPreviewHint keeps the HTTP 403 network error from
+// +download intact while giving callers a preview-based path to view content.
+func withDriveDownloadForbiddenPreviewHint(err error, _ string) error {
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryNetwork || problem.Code != http.StatusForbidden {
+		return err
+	}
+	if strings.Contains(problem.Hint, "drive +preview") {
+		return err
+	}
+	hint := driveDownloadForbiddenPreviewHint()
+	if strings.TrimSpace(problem.Hint) == "" {
+		problem.Hint = hint
+		return err
+	}
+	problem.Hint = strings.TrimSpace(problem.Hint) + " " + hint
+	return err
+}
+
+func driveDownloadForbiddenPreviewHint() string {
+	const tokenArg = "<FILE_TOKEN>"
+	return fmt.Sprintf("Direct Drive download returned HTTP 403. To view file content through preview artifacts, try `lark-cli drive +preview --file-token %s --type source_file --output <path>`; for PDF/text/image preview choices, run `lark-cli drive +preview --file-token %s --list-only`.", tokenArg, tokenArg)
+}
+
 // driveInputStatError maps a FileIO.Stat/Open error for input file validation
 // to a typed validation error:
 //   - Path validation failures → "unsafe file path: ..."

shortcuts/drive/drive_io_test.go

@@ -1580,6 +1580,84 @@ func TestDriveDownloadAllowsOverwriteFlag(t *testing.T) {
 	}
 }
 
+func TestDriveDownloadHTTP403SuggestsPreview(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/files/file_403/download",
+		Status:  http.StatusForbidden,
+		RawBody: []byte("permission denied"),
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	err := mountAndRunDrive(t, DriveDownload, []string{
+		"+download",
+		"--file-token", "file_403",
+		"--output", "blocked.md",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected HTTP 403 error, got nil")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T: %v", err, err)
+	}
+	if problem.Category != errs.CategoryNetwork {
+		t.Fatalf("category=%q, want network", problem.Category)
+	}
+	if problem.Code != http.StatusForbidden {
+		t.Fatalf("code=%d, want %d", problem.Code, http.StatusForbidden)
+	}
+	if !strings.Contains(problem.Hint, "drive +preview") {
+		t.Fatalf("hint=%q, want preview guidance", problem.Hint)
+	}
+	if strings.Contains(problem.Hint, "file_403") {
+		t.Fatalf("hint=%q, want placeholder file token", problem.Hint)
+	}
+	if !strings.Contains(problem.Hint, "--file-token <FILE_TOKEN>") {
+		t.Fatalf("hint=%q, want file token placeholder", problem.Hint)
+	}
+	if !strings.Contains(problem.Hint, "--type source_file") || !strings.Contains(problem.Hint, "--output <path>") {
+		t.Fatalf("hint=%q, want source_file output command", problem.Hint)
+	}
+}
+
+func TestDriveDownloadHTTP404DoesNotSuggestPreview(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/files/file_missing/download",
+		Status:  http.StatusNotFound,
+		RawBody: []byte("not found"),
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	err := mountAndRunDrive(t, DriveDownload, []string{
+		"+download",
+		"--file-token", "file_missing",
+		"--output", "missing.md",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected HTTP 404 error, got nil")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T: %v", err, err)
+	}
+	if problem.Code != http.StatusNotFound {
+		t.Fatalf("code=%d, want %d", problem.Code, http.StatusNotFound)
+	}
+	if strings.Contains(problem.Hint, "drive +preview") {
+		t.Fatalf("hint=%q, want no preview guidance for non-403", problem.Hint)
+	}
+}
+
 func TestDriveDownloadDefaultOutputPathSanitizesSlashOnlyNames(t *testing.T) {
 	header := http.Header{
 		"Content-Disposition": []string{`attachment; filename="////"`},

shortcuts/drive/drive_preview.go

@@ -16,13 +16,13 @@ import (
 var DrivePreview = common.Shortcut{
 	Service:     "drive",
 	Command:     "+preview",
-	Description: "List or download available preview artifacts for a Drive file",
+	Description: "View or download Drive file content, or list and fetch available preview artifacts",
 	Risk:        "read",
 	Scopes:      []string{"drive:file:download"},
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "file-token", Desc: "Drive file token", Required: true},
-		{Name: "type", Desc: "preview type to download: pdf | html | text | image | source"},
+		{Name: "type", Desc: "preview type to download: pdf | html | text | image | source_file"},
 		{Name: "version", Desc: "optional file version"},
 		{Name: "list-only", Type: "bool", Desc: "list preview candidates without downloading"},
 		{Name: "output", Desc: "local output path for downloaded preview"},
@@ -40,6 +40,25 @@ var DrivePreview = common.Shortcut{
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		fileToken := runtime.Str("file-token")
 		version := strings.TrimSpace(runtime.Str("version"))
+		requestedType := strings.TrimSpace(runtime.Str("type"))
+		if requestedType == "source_file" {
+			downloadParams := map[string]interface{}{
+				"preview_type": drivePreviewTypeSourceFile,
+			}
+			if version != "" {
+				downloadParams["version"] = version
+			}
+			return common.NewDryRunAPI().
+				GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+				Desc("Download the source file artifact").
+				Params(downloadParams).
+				Set("file_token", fileToken).
+				Set("mode", "download").
+				Set("requested_type", requestedType).
+				Set("selected_type", "source_file").
+				Set("selected_type_code", drivePreviewTypeSourceFile).
+				Set("output", runtime.Str("output"))
+		}
 		body := map[string]interface{}{}
 		if version != "" {
 			body["version"] = version
@@ -67,7 +86,7 @@ var DrivePreview = common.Shortcut{
 			Desc("[2] Download the requested preview after selecting a matching candidate from preview_result").
 			Params(downloadParams).
 			Set("mode", "download").
-			Set("requested_type", runtime.Str("type")).
+			Set("requested_type", requestedType).
 			Set("output", runtime.Str("output"))
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -82,9 +101,25 @@ var DrivePreview = common.Shortcut{
 			body["version"] = version
 		}
 
+		if requestedType == "source_file" {
+			fmt.Fprintf(runtime.IO().ErrOut, "Downloading source file artifact: %s\n", common.MaskToken(fileToken))
+			result, err := downloadDrivePreviewArtifact(ctx, runtime, fileToken, drivePreviewTypeSourceFile, version, outputPath, ifExists, drivePreviewFallbackExt("source_file"))
+			if err != nil {
+				return err
+			}
+			result["mode"] = "download"
+			result["file_token"] = fileToken
+			result["selected_type"] = "source_file"
+			runtime.Out(result, nil)
+			return nil
+		}
+
 		fmt.Fprintf(runtime.IO().ErrOut, "Fetching preview candidates: %s\n", common.MaskToken(fileToken))
 		data, candidates, err := fetchDrivePreviewCandidates(runtime, fileToken, body)
 		if err != nil {
+			if runtime.Bool("list-only") {
+				return withDrivePreviewSourceFileHint(err)
+			}
 			return err
 		}
 		if runtime.Bool("list-only") {

shortcuts/drive/drive_preview_common.go

@@ -27,6 +27,8 @@ const (
 	drivePreviewIfExistsError     = "error"
 	drivePreviewIfExistsOverwrite = "overwrite"
 	drivePreviewIfExistsRename    = "rename"
+	drivePreviewTypeSourceFile    = "16"
+	drivePreviewSourceFileHint    = "Preview candidates are unavailable for this file. To fetch the source file artifact, rerun with --type source_file --output <path>."
 )
 
 type drivePreviewCandidate struct {
@@ -88,7 +90,9 @@ var drivePreviewMimeToExt = map[string]string{
 	"image/webp":               ".webp",
 	"text/csv":                 ".csv",
 	"text/html":                ".html",
+	"text/markdown":            ".md",
 	"text/plain":               ".txt",
+	"text/x-markdown":          ".md",
 	"text/xml":                 ".xml",
 	"video/mp4":                ".mp4",
 	"application/octet-stream": "",
@@ -464,7 +468,7 @@ func downloadDrivePreviewArtifactWithParams(ctx context.Context, runtime *common
 	}
 	defer resp.Body.Close()
 
-	finalPath, _, err := resolveDrivePreviewOutputPath(runtime, outputPath, resp.Header, fallbackExt, ifExists)
+	finalPath, _, err := resolveDrivePreviewOutputPath(runtime, outputPath, resp.Header, fallbackExt, ifExists, fileToken)
 	if err != nil {
 		return nil, err
 	}
@@ -492,8 +496,8 @@ func downloadDrivePreviewArtifactWithParams(ctx context.Context, runtime *common
 
 // resolveDrivePreviewOutputPath finalizes the save path, applying extension
 // inference and the selected collision policy.
-func resolveDrivePreviewOutputPath(runtime *common.RuntimeContext, outputPath string, header http.Header, fallbackExt, ifExists string) (string, *driveExtensionResolution, error) {
-	finalPath, resolution := autoAppendDrivePreviewExtension(outputPath, header, fallbackExt)
+func resolveDrivePreviewOutputPath(runtime *common.RuntimeContext, outputPath string, header http.Header, fallbackExt, ifExists, fallbackName string) (string, *driveExtensionResolution, error) {
+	finalPath, resolution := resolveDrivePreviewOutputPathName(runtime, outputPath, header, fallbackExt, fallbackName)
 	if _, err := runtime.ResolveSavePath(finalPath); err != nil {
 		return "", nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output")
 	}
@@ -522,6 +526,32 @@ func resolveDrivePreviewOutputPath(runtime *common.RuntimeContext, outputPath st
 	}
 }
 
+func resolveDrivePreviewOutputPathName(runtime *common.RuntimeContext, outputPath string, header http.Header, fallbackExt, fallbackName string) (string, *driveExtensionResolution) {
+	if drivePreviewOutputIsDirectory(runtime, outputPath) {
+		fileName, resolution := drivePreviewDefaultFileName(header, fallbackExt, fallbackName)
+		return filepath.Join(outputPath, fileName), resolution
+	}
+	return autoAppendDrivePreviewExtension(outputPath, header, fallbackExt)
+}
+
+func drivePreviewOutputIsDirectory(runtime *common.RuntimeContext, outputPath string) bool {
+	if strings.HasSuffix(outputPath, "/") || strings.HasSuffix(outputPath, "\\") {
+		return true
+	}
+	info, err := runtime.FileIO().Stat(outputPath)
+	return err == nil && info.IsDir()
+}
+
+func drivePreviewDefaultFileName(header http.Header, fallbackExt, fallbackName string) (string, *driveExtensionResolution) {
+	name := driveDownloadNormalizeFileName(larkcore.FileNameByHeader(header))
+	if name == "" {
+		name = driveDownloadNormalizeFileName(fallbackName)
+	}
+	name = sanitizeExportFileName(name, "preview")
+	name, resolution := autoAppendDrivePreviewExtension(name, header, fallbackExt)
+	return name, resolution
+}
+
 // nextAvailableDrivePreviewPath finds the first unused "name (n)" variant for a
 // target output path.
 func nextAvailableDrivePreviewPath(fio fileio.FileIO, path string) (string, error) {
@@ -556,6 +586,15 @@ func autoAppendDrivePreviewExtension(outputPath string, header http.Header, fall
 	if filepath.Ext(outputPath) == "." {
 		normalizedPath = strings.TrimSuffix(outputPath, ".")
 	}
+	if fallbackExt == "" {
+		if resolution := drivePreviewExtensionByContentDisposition(header); resolution != nil {
+			return normalizedPath + resolution.Ext, resolution
+		}
+		if resolution := drivePreviewExtensionByContentType(header.Get("Content-Type")); resolution != nil {
+			return normalizedPath + resolution.Ext, resolution
+		}
+		return normalizedPath, nil
+	}
 	if resolution := drivePreviewExtensionByContentType(header.Get("Content-Type")); resolution != nil {
 		return normalizedPath + resolution.Ext, resolution
 	}
@@ -804,6 +843,36 @@ func wrapDrivePreviewNotReady(fileToken, requested string, candidate drivePrevie
 	return errs.NewValidationError(errs.SubtypeFailedPrecondition, reason).WithHint(hint).WithParam("--type")
 }
 
+// withDrivePreviewSourceFileHint adds source_file guidance to preview candidate
+// API failures without changing their classification or server diagnostics.
+func withDrivePreviewSourceFileHint(err error) error {
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryAPI {
+		return err
+	}
+	if problem.Retryable || problem.Subtype == errs.SubtypeRateLimit {
+		return err
+	}
+	if strings.Contains(problem.Hint, "--type source_file") {
+		return err
+	}
+	if !isDrivePreviewCandidatesUnavailableProblem(problem) {
+		return err
+	}
+	if strings.TrimSpace(problem.Hint) == "" {
+		problem.Hint = drivePreviewSourceFileHint
+		return err
+	}
+	problem.Hint = strings.TrimSpace(problem.Hint) + " " + drivePreviewSourceFileHint
+	return err
+}
+
+func isDrivePreviewCandidatesUnavailableProblem(problem *errs.Problem) bool {
+	return problem != nil &&
+		problem.Code == 1 &&
+		strings.Contains(problem.Message, "mGetFilePreviewCore failed")
+}
+
 // wrapDriveCoverUnavailable builds a validation error for an unknown cover
 // spec.
 func wrapDriveCoverUnavailable(requested string) error {

shortcuts/drive/drive_preview_test.go

@@ -147,6 +147,63 @@ func TestDrivePreviewDownloadUsesResolvedTypeCodeAndRenamePolicy(t *testing.T) {
 	}
 }
 
+// TestDrivePreviewSourceFileDirectDownloadSkipsPreviewResult verifies
+// source_file downloads the source file artifact without first fetching preview
+// candidates.
+func TestDrivePreviewSourceFileDirectDownloadSkipsPreviewResult(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/medias/file_source/preview_download?preview_type=16",
+		Status: 200,
+		Body:   []byte("# markdown\n"),
+		Headers: http.Header{
+			"Content-Disposition": []string{`attachment; filename="README.md"`},
+			"Content-Type":        []string{"text/plain; charset=utf-8"},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	err := mountAndRunDrive(t, DrivePreview, []string{
+		"+preview",
+		"--file-token", "file_source",
+		"--type", "source_file",
+		"--output", "artifacts/",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if _, ok := data["requested_type"]; ok {
+		t.Fatalf("requested_type should be omitted from execute output: %#v", data)
+	}
+	if got := data["selected_type"]; got != "source_file" {
+		t.Fatalf("selected_type=%v, want source_file", got)
+	}
+	if _, ok := data["selected_type_code"]; ok {
+		t.Fatalf("selected_type_code should be omitted from execute output: %#v", data)
+	}
+	resolvedTmpDir, err := filepath.EvalSymlinks(tmpDir)
+	if err != nil {
+		t.Fatalf("EvalSymlinks() error: %v", err)
+	}
+	wantPath := filepath.Join(resolvedTmpDir, "artifacts", "README.md")
+	if got := data["output_path"]; got != wantPath {
+		t.Fatalf("output_path=%v, want %s", got, wantPath)
+	}
+	gotBody, err := os.ReadFile(wantPath)
+	if err != nil {
+		t.Fatalf("ReadFile(%q) error: %v", wantPath, err)
+	}
+	if string(gotBody) != "# markdown\n" {
+		t.Fatalf("saved body=%q, want markdown source", string(gotBody))
+	}
+}
+
 // TestDrivePreviewRejectsUnavailableType verifies unavailable preview types
 // return an actionable validation error.
 func TestDrivePreviewRejectsUnavailableType(t *testing.T) {
@@ -434,6 +491,72 @@ func TestDrivePreviewDryRunIncludesVersionAndMode(t *testing.T) {
 	}
 }
 
+// TestDrivePreviewDryRunSourceFileDocumentsDirectDownload verifies source_file
+// dry-run documents the direct source artifact download path.
+func TestDrivePreviewDryRunSourceFileDocumentsDirectDownload(t *testing.T) {
+	runtime := newDrivePreviewRuntime(t, "drive +preview", map[string]string{
+		"file-token": "file_source",
+		"type":       "source_file",
+		"version":    "7",
+		"output":     "source",
+	}, nil)
+
+	data := decodeDryRunOutput(t, DrivePreview.DryRun(context.Background(), runtime))
+	if got := data["mode"]; got != "download" {
+		t.Fatalf("mode=%v, want download", got)
+	}
+	if got := data["requested_type"]; got != "source_file" {
+		t.Fatalf("requested_type=%v, want source_file", got)
+	}
+	if got := data["selected_type"]; got != "source_file" {
+		t.Fatalf("selected_type=%v, want source_file", got)
+	}
+	if got := data["selected_type_code"]; got != drivePreviewTypeSourceFile {
+		t.Fatalf("selected_type_code=%v, want %s", got, drivePreviewTypeSourceFile)
+	}
+	api, _ := data["api"].([]interface{})
+	if len(api) != 1 {
+		t.Fatalf("len(api)=%d, want 1", len(api))
+	}
+	call, _ := api[0].(map[string]interface{})
+	if got := call["method"]; got != "GET" {
+		t.Fatalf("method=%v, want GET", got)
+	}
+	if got := call["url"]; got != "/open-apis/drive/v1/medias/file_source/preview_download" {
+		t.Fatalf("url=%v, want preview_download", got)
+	}
+	params, _ := call["params"].(map[string]interface{})
+	if got := params["preview_type"]; got != drivePreviewTypeSourceFile {
+		t.Fatalf("params.preview_type=%v, want %s", got, drivePreviewTypeSourceFile)
+	}
+	if got := params["version"]; got != "7" {
+		t.Fatalf("params.version=%v, want 7", got)
+	}
+}
+
+// TestDrivePreviewDryRunSourceAliasUsesPreviewCandidates verifies only the
+// explicit source_file request bypasses preview_result.
+func TestDrivePreviewDryRunSourceAliasUsesPreviewCandidates(t *testing.T) {
+	runtime := newDrivePreviewRuntime(t, "drive +preview", map[string]string{
+		"file-token": "file_source",
+		"type":       "source",
+		"output":     "source",
+	}, nil)
+
+	data := decodeDryRunOutput(t, DrivePreview.DryRun(context.Background(), runtime))
+	api, _ := data["api"].([]interface{})
+	if len(api) != 2 {
+		t.Fatalf("len(api)=%d, want 2", len(api))
+	}
+	call, _ := api[0].(map[string]interface{})
+	if got := call["url"]; got != "/open-apis/drive/v1/medias/file_source/preview_result" {
+		t.Fatalf("url=%v, want preview_result", got)
+	}
+	if _, ok := data["selected_type_code"]; ok {
+		t.Fatalf("selected_type_code should be omitted for non-source_file dry-run: %#v", data)
+	}
+}
+
 // TestDrivePreviewDryRunListOmitsBodyWithoutVersion verifies list-mode DryRun
 // omits the request body when no version is supplied.
 func TestDrivePreviewDryRunListOmitsBodyWithoutVersion(t *testing.T) {
@@ -612,6 +735,135 @@ func TestDrivePreviewNotReadyReturnsFailedPrecondition(t *testing.T) {
 	}
 }
 
+// TestDrivePreviewListOnlyErrorAddsSourceFileHint verifies preview_result API
+// failures keep server diagnostics while guiding callers to source_file.
+func TestDrivePreviewListOnlyErrorAddsSourceFileHint(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/file_markdown/preview_result",
+		Body: map[string]interface{}{
+			"code":   1,
+			"msg":    "fail:mGetFilePreviewCore failed",
+			"log_id": "log-preview-result",
+			"error": map[string]interface{}{
+				"troubleshooter": "https://open.feishu.cn/document/troubleshoot/preview-result",
+				"details": []interface{}{
+					map[string]interface{}{"value": "server preview_result detail"},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePreview, []string{
+		"+preview",
+		"--file-token", "file_markdown",
+		"--list-only",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected preview_result error, got nil")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T: %v", err, err)
+	}
+	if problem.Category != errs.CategoryAPI {
+		t.Fatalf("category=%q, want api", problem.Category)
+	}
+	if problem.Code != 1 {
+		t.Fatalf("code=%d, want 1", problem.Code)
+	}
+	if problem.LogID != "log-preview-result" {
+		t.Fatalf("log_id=%q, want log-preview-result", problem.LogID)
+	}
+	if problem.Troubleshooter != "https://open.feishu.cn/document/troubleshoot/preview-result" {
+		t.Fatalf("troubleshooter=%q, want passthrough", problem.Troubleshooter)
+	}
+	if !strings.Contains(problem.Hint, "server preview_result detail") {
+		t.Fatalf("hint=%q, want server detail preserved", problem.Hint)
+	}
+	if !strings.Contains(problem.Hint, "--type source_file") || !strings.Contains(problem.Hint, "--output") {
+		t.Fatalf("hint=%q, want source_file output guidance", problem.Hint)
+	}
+}
+
+// TestDrivePreviewListOnlyRateLimitKeepsOriginalHint verifies retryable API
+// errors are not reframed as source_file recovery.
+func TestDrivePreviewListOnlyRateLimitKeepsOriginalHint(t *testing.T) {
+	err := withDrivePreviewSourceFileHint(errs.NewAPIError(errs.SubtypeRateLimit, "request trigger frequency limit").WithCode(99991400).WithRetryable())
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T: %v", err, err)
+	}
+	if problem.Hint != "" {
+		t.Fatalf("hint=%q, want empty hint for rate limit", problem.Hint)
+	}
+	if !problem.Retryable {
+		t.Fatal("retryable=false, want true")
+	}
+}
+
+// TestDrivePreviewSourceFileHintGuards verifies source_file recovery guidance
+// only rewrites eligible API errors and preserves existing source_file hints.
+func TestDrivePreviewSourceFileHintGuards(t *testing.T) {
+	plainErr := errors.New("plain failure")
+	if got := withDrivePreviewSourceFileHint(plainErr); got != plainErr {
+		t.Fatalf("non-API error changed: got %T %v, want original", got, got)
+	}
+
+	for _, tt := range []struct {
+		name string
+		err  *errs.APIError
+		want string
+	}{
+		{
+			name: "already has source file hint",
+			err:  errs.NewAPIError(errs.SubtypeServerError, "preview_result failed").WithHint("rerun with --type source_file --output <path>"),
+			want: "rerun with --type source_file --output <path>",
+		},
+		{
+			name: "candidate core failure empty hint",
+			err:  errs.NewAPIError(errs.SubtypeServerError, "fail:mGetFilePreviewCore failed").WithCode(1),
+			want: drivePreviewSourceFileHint,
+		},
+		{
+			name: "candidate core failure whitespace hint",
+			err:  errs.NewAPIError(errs.SubtypeServerError, "fail:mGetFilePreviewCore failed").WithCode(1).WithHint(" \n\t "),
+			want: drivePreviewSourceFileHint,
+		},
+		{
+			name: "generic server error",
+			err:  errs.NewAPIError(errs.SubtypeServerError, "preview_result failed"),
+			want: "",
+		},
+		{
+			name: "not found",
+			err:  errs.NewAPIError(errs.SubtypeNotFound, "file not found").WithCode(1061044),
+			want: "",
+		},
+		{
+			name: "invalid parameters",
+			err:  errs.NewAPIError(errs.SubtypeInvalidParameters, "invalid file token").WithCode(1063007),
+			want: "",
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			gotErr := withDrivePreviewSourceFileHint(tt.err)
+			if gotErr != tt.err {
+				t.Fatalf("API error pointer changed: got %T, want original", gotErr)
+			}
+			problem, ok := errs.ProblemOf(gotErr)
+			if !ok {
+				t.Fatalf("expected typed error, got %T: %v", gotErr, gotErr)
+			}
+			if problem.Hint != tt.want {
+				t.Fatalf("hint=%q, want %q", problem.Hint, tt.want)
+			}
+		})
+	}
+}
+
 // TestDriveCoverRejectsUnknownSpec verifies unsupported cover specs produce a
 // validation error with available alternatives.
 func TestDriveCoverRejectsUnknownSpec(t *testing.T) {
@@ -721,6 +973,21 @@ func TestDrivePreviewCommonHelpers(t *testing.T) {
 	if path != "cover.pdf" || fallback != nil {
 		t.Fatalf("explicit ext append = (%q, %+v), want unchanged path", path, fallback)
 	}
+
+	header = http.Header{}
+	header.Set("Content-Type", "text/plain")
+	header.Set("Content-Disposition", `attachment; filename="README.md"`)
+	path, fallback = autoAppendDrivePreviewExtension("source", header, "")
+	if path != "source.md" || fallback == nil || fallback.Source != "Content-Disposition" {
+		t.Fatalf("source_file append = (%q, %+v), want source.md from Content-Disposition", path, fallback)
+	}
+
+	header = http.Header{}
+	header.Set("Content-Type", "text/plain")
+	path, fallback = autoAppendDrivePreviewExtension("source", header, "")
+	if path != "source.txt" || fallback == nil || fallback.Source != "Content-Type" {
+		t.Fatalf("source_file content-type append = (%q, %+v), want source.txt from Content-Type", path, fallback)
+	}
 }
 
 // TestDrivePreviewMetadataAndPathResolution verifies metadata normalization
@@ -751,7 +1018,7 @@ func TestDrivePreviewMetadataAndPathResolution(t *testing.T) {
 	runtime := newDrivePreviewRuntime(t, "drive +preview", nil, nil)
 	header := http.Header{}
 	header.Set("Content-Type", "application/pdf")
-	renamed, _, err := resolveDrivePreviewOutputPath(runtime, "preview", header, ".pdf", drivePreviewIfExistsRename)
+	renamed, _, err := resolveDrivePreviewOutputPath(runtime, "preview", header, ".pdf", drivePreviewIfExistsRename, "file_preview")
 	if err != nil {
 		t.Fatalf("resolveDrivePreviewOutputPath(rename) error: %v", err)
 	}
@@ -759,7 +1026,7 @@ func TestDrivePreviewMetadataAndPathResolution(t *testing.T) {
 		t.Fatalf("renamed=%q, want preview (1).pdf suffix", renamed)
 	}
 
-	_, _, err = resolveDrivePreviewOutputPath(runtime, "preview", header, ".pdf", "keep")
+	_, _, err = resolveDrivePreviewOutputPath(runtime, "preview", header, ".pdf", "keep", "file_preview")
 	if err == nil {
 		t.Fatal("expected invalid if-exists error, got nil")
 	}
@@ -771,6 +1038,20 @@ func TestDrivePreviewMetadataAndPathResolution(t *testing.T) {
 		t.Fatalf("param=%q, want --if-exists", validationErr.Param)
 	}
 
+	if err := os.Mkdir("artifacts", 0755); err != nil {
+		t.Fatalf("Mkdir() error: %v", err)
+	}
+	sourceHeader := http.Header{}
+	sourceHeader.Set("Content-Type", "text/plain")
+	sourceHeader.Set("Content-Disposition", `attachment; filename="README.md"`)
+	dirOutput, _, err := resolveDrivePreviewOutputPath(runtime, "artifacts", sourceHeader, "", drivePreviewIfExistsError, "file_source")
+	if err != nil {
+		t.Fatalf("resolveDrivePreviewOutputPath(directory) error: %v", err)
+	}
+	if !strings.HasSuffix(dirOutput, filepath.Join("artifacts", "README.md")) {
+		t.Fatalf("dirOutput=%q, want artifacts/README.md suffix", dirOutput)
+	}
+
 	unusedPath, err := nextAvailableDrivePreviewPath(runtime.FileIO(), "fresh.pdf")
 	if err != nil {
 		t.Fatalf("nextAvailableDrivePreviewPath(unused) error: %v", err)
@@ -779,7 +1060,7 @@ func TestDrivePreviewMetadataAndPathResolution(t *testing.T) {
 		t.Fatalf("unusedPath=%q, want fresh.pdf", unusedPath)
 	}
 
-	overwritten, _, err := resolveDrivePreviewOutputPath(runtime, "preview.pdf", header, ".pdf", drivePreviewIfExistsOverwrite)
+	overwritten, _, err := resolveDrivePreviewOutputPath(runtime, "preview.pdf", header, ".pdf", drivePreviewIfExistsOverwrite, "file_preview")
 	if err != nil {
 		t.Fatalf("resolveDrivePreviewOutputPath(overwrite) error: %v", err)
 	}
@@ -791,7 +1072,7 @@ func TestDrivePreviewMetadataAndPathResolution(t *testing.T) {
 	f.FileIOProvider = &statErrorProvider{inner: f.FileIOProvider, err: fs.ErrPermission}
 	runtimeWithStatErr := newDrivePreviewRuntime(t, "drive +preview", nil, nil)
 	runtimeWithStatErr.Factory = f
-	_, _, err = resolveDrivePreviewOutputPath(runtimeWithStatErr, "blocked.pdf", header, ".pdf", drivePreviewIfExistsError)
+	_, _, err = resolveDrivePreviewOutputPath(runtimeWithStatErr, "blocked.pdf", header, ".pdf", drivePreviewIfExistsError, "file_preview")
 	if err == nil {
 		t.Fatal("expected stat permission error, got nil")
 	}
@@ -876,7 +1157,6 @@ func TestDrivePreviewAliasAndAvailabilityHelpers(t *testing.T) {
 	if got := normalizeDrivePreviewRequest(" Source File "); got != "source_file" {
 		t.Fatalf("normalizeDrivePreviewRequest()=%q, want source_file", got)
 	}
-
 	aliases := previewAliasesForCandidate(drivePreviewCandidate{TypeCode: "1"})
 	if len(aliases) == 0 || aliases[0] != "image" {
 		t.Fatalf("previewAliasesForCandidate()=%v, want image alias", aliases)

shortcuts/markdown/helpers.go

@@ -32,6 +32,7 @@ const (
 	markdownUploadPrepareAction      = "initialize markdown multipart upload failed"
 	markdownUploadFinishAction       = "finalize markdown multipart upload failed"
 	markdownFetchNameAction          = "fetch existing markdown file name failed"
+	markdownSourceFilePreviewType    = "16"
 )
 
 var markdownUploadRetryBackoffs = []time.Duration{
@@ -192,9 +193,14 @@ func resolveMarkdownOverwriteFileName(runtime *common.RuntimeContext, spec markd
 }
 
 func openMarkdownDownload(ctx context.Context, runtime *common.RuntimeContext, fileToken string) (*http.Response, error) {
+	query, err := markdownSourceFilePreviewQuery("", "")
+	if err != nil {
+		return nil, err
+	}
 	resp, err := runtime.DoAPIStream(ctx, &larkcore.ApiReq{
-		HttpMethod: http.MethodGet,
-		ApiPath:    fmt.Sprintf("/open-apis/drive/v1/files/%s/download", validate.EncodePathSegment(fileToken)),
+		HttpMethod:  http.MethodGet,
+		ApiPath:     fmt.Sprintf("/open-apis/drive/v1/medias/%s/preview_download", validate.EncodePathSegment(fileToken)),
+		QueryParams: query,
 	})
 	if err != nil {
 		return nil, wrapMarkdownDownloadError(err)
@@ -230,15 +236,15 @@ func markdownSourceSize(runtime *common.RuntimeContext, spec markdownUploadSpec)
 	return size, nil
 }
 
-func openMarkdownDownloadVersion(ctx context.Context, runtime *common.RuntimeContext, fileToken, version string) (*http.Response, string, error) {
-	req := &larkcore.ApiReq{
-		HttpMethod: http.MethodGet,
-		ApiPath:    fmt.Sprintf("/open-apis/drive/v1/files/%s/download", validate.EncodePathSegment(fileToken)),
+func openMarkdownDownloadVersion(ctx context.Context, runtime *common.RuntimeContext, fileToken, version, versionParam string) (*http.Response, string, error) {
+	query, err := markdownSourceFilePreviewQuery(version, versionParam)
+	if err != nil {
+		return nil, "", err
 	}
-	if strings.TrimSpace(version) != "" {
-		req.QueryParams = larkcore.QueryParams{
-			"version": []string{strings.TrimSpace(version)},
-		}
+	req := &larkcore.ApiReq{
+		HttpMethod:  http.MethodGet,
+		ApiPath:     fmt.Sprintf("/open-apis/drive/v1/medias/%s/preview_download", validate.EncodePathSegment(fileToken)),
+		QueryParams: query,
 	}
 
 	resp, err := runtime.DoAPIStream(ctx, req)
@@ -248,6 +254,58 @@ func openMarkdownDownloadVersion(ctx context.Context, runtime *common.RuntimeCon
 	return resp, fileNameFromDownloadHeader(resp.Header, fileToken+".md"), nil
 }
 
+func markdownSourceFilePreviewQuery(version, versionParam string) (larkcore.QueryParams, error) {
+	if err := validateMarkdownSourceFilePreviewVersion(version, versionParam); err != nil {
+		return nil, err
+	}
+	query := larkcore.QueryParams{
+		"preview_type": []string{markdownSourceFilePreviewType},
+	}
+	if version != "" {
+		query["version"] = []string{version}
+	}
+	return query, nil
+}
+
+func markdownSourceFilePreviewDryRunParams(version, versionParam string) (map[string]interface{}, error) {
+	if err := validateMarkdownSourceFilePreviewVersion(version, versionParam); err != nil {
+		return nil, err
+	}
+	params := map[string]interface{}{
+		"preview_type": markdownSourceFilePreviewType,
+	}
+	if version != "" {
+		params["version"] = version
+	}
+	return params, nil
+}
+
+func markdownSourceFilePreviewDryRunParamsForValidatedVersion(version, versionParam string) map[string]interface{} {
+	params, err := markdownSourceFilePreviewDryRunParams(version, versionParam)
+	if err != nil {
+		// Shortcut validation runs before DryRun. If a caller bypasses that
+		// contract, preserve the supplied value instead of silently dropping it.
+		params = map[string]interface{}{
+			"preview_type": markdownSourceFilePreviewType,
+			"version":      version,
+		}
+	}
+	return params
+}
+
+func validateMarkdownSourceFilePreviewVersion(version, flagName string) error {
+	if version == "" {
+		return nil
+	}
+	if strings.TrimSpace(version) != "" {
+		return nil
+	}
+	if flagName == "" {
+		flagName = "--version"
+	}
+	return markdownValidationParamError(flagName, "%s cannot be empty", flagName)
+}
+
 func markdownDryRunFileField(spec markdownUploadSpec) string {
 	if spec.FilePath != "" {
 		return "@" + spec.FilePath

shortcuts/markdown/markdown_diff.go

@@ -112,9 +112,8 @@ func validateMarkdownDiffSpec(runtime *common.RuntimeContext, spec markdownDiffS
 }
 
 func validateMarkdownDiffVersionValue(value, flagName string) error {
-	value = strings.TrimSpace(value)
-	if value == "" {
-		return markdownValidationParamError(flagName, "%s cannot be empty", flagName)
+	if err := validateMarkdownSourceFilePreviewVersion(value, flagName); err != nil {
+		return err
 	}
 	if !markdownDiffVersionRe.MatchString(value) {
 		return markdownValidationParamError(flagName, "%s must be a numeric version string", flagName)
@@ -134,31 +133,33 @@ func markdownDiffDryRun(spec markdownDiffSpec) *common.DryRunAPI {
 	switch markdownDiffMode(spec) {
 	case markdownDiffModeRemoteVsLocal:
 		if spec.FromVersion != "" {
-			dry.GET("/open-apis/drive/v1/files/:file_token/download").
-				Desc("[1] Download the specified remote Markdown version").
+			dry.GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+				Desc("[1] Download the specified remote Markdown source file preview artifact").
 				Set("file_token", spec.FileToken).
-				Params(map[string]interface{}{"version": spec.FromVersion})
+				Params(markdownSourceFilePreviewDryRunParamsForValidatedVersion(spec.FromVersion, "--from-version"))
 		} else {
-			dry.GET("/open-apis/drive/v1/files/:file_token/download").
-				Desc("[1] Download the latest remote Markdown version").
-				Set("file_token", spec.FileToken)
+			dry.GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+				Desc("[1] Download the latest remote Markdown source file preview artifact").
+				Set("file_token", spec.FileToken).
+				Params(markdownSourceFilePreviewDryRunParamsForValidatedVersion("", ""))
 		}
 		dry.Set("local_file", spec.FilePath)
 		dry.Set("mode", markdownDiffModeRemoteVsLocal)
 	default:
-		dry.GET("/open-apis/drive/v1/files/:file_token/download").
-			Desc("[1] Download the base remote Markdown version").
+		dry.GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+			Desc("[1] Download the base remote Markdown source file preview artifact").
 			Set("file_token", spec.FileToken).
-			Params(map[string]interface{}{"version": spec.FromVersion})
+			Params(markdownSourceFilePreviewDryRunParamsForValidatedVersion(spec.FromVersion, "--from-version"))
 		if spec.ToVersion != "" {
-			dry.GET("/open-apis/drive/v1/files/:file_token/download").
-				Desc("[2] Download the target remote Markdown version").
+			dry.GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+				Desc("[2] Download the target remote Markdown source file preview artifact").
 				Set("file_token", spec.FileToken).
-				Params(map[string]interface{}{"version": spec.ToVersion})
+				Params(markdownSourceFilePreviewDryRunParamsForValidatedVersion(spec.ToVersion, "--to-version"))
 		} else {
-			dry.GET("/open-apis/drive/v1/files/:file_token/download").
-				Desc("[2] Download the latest remote Markdown version").
-				Set("file_token", spec.FileToken)
+			dry.GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+				Desc("[2] Download the latest remote Markdown source file preview artifact").
+				Set("file_token", spec.FileToken).
+				Params(markdownSourceFilePreviewDryRunParamsForValidatedVersion("", ""))
 		}
 		dry.Set("mode", markdownDiffModeRemoteVsRemote)
 	}
@@ -166,8 +167,8 @@ func markdownDiffDryRun(spec markdownDiffSpec) *common.DryRunAPI {
 	return dry
 }
 
-func downloadMarkdownContent(ctx context.Context, runtime *common.RuntimeContext, fileToken, version string) (string, string, error) {
-	resp, fileName, err := openMarkdownDownloadVersion(ctx, runtime, fileToken, version)
+func downloadMarkdownContent(ctx context.Context, runtime *common.RuntimeContext, fileToken, version, versionParam string) (string, string, error) {
+	resp, fileName, err := openMarkdownDownloadVersion(ctx, runtime, fileToken, version, versionParam)
 	if err != nil {
 		return "", "", err
 	}
@@ -446,8 +447,8 @@ var MarkdownDiff = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateMarkdownDiffSpec(runtime, markdownDiffSpec{
 			FileToken:    strings.TrimSpace(runtime.Str("file-token")),
-			FromVersion:  strings.TrimSpace(runtime.Str("from-version")),
-			ToVersion:    strings.TrimSpace(runtime.Str("to-version")),
+			FromVersion:  runtime.Str("from-version"),
+			ToVersion:    runtime.Str("to-version"),
 			FilePath:     strings.TrimSpace(runtime.Str("file")),
 			ContextLines: runtime.Int("context-lines"),
 			Format:       runtime.Format,
@@ -456,8 +457,8 @@ var MarkdownDiff = common.Shortcut{
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return markdownDiffDryRun(markdownDiffSpec{
 			FileToken:    strings.TrimSpace(runtime.Str("file-token")),
-			FromVersion:  strings.TrimSpace(runtime.Str("from-version")),
-			ToVersion:    strings.TrimSpace(runtime.Str("to-version")),
+			FromVersion:  runtime.Str("from-version"),
+			ToVersion:    runtime.Str("to-version"),
 			FilePath:     strings.TrimSpace(runtime.Str("file")),
 			ContextLines: runtime.Int("context-lines"),
 		})
@@ -465,8 +466,8 @@ var MarkdownDiff = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		spec := markdownDiffSpec{
 			FileToken:    strings.TrimSpace(runtime.Str("file-token")),
-			FromVersion:  strings.TrimSpace(runtime.Str("from-version")),
-			ToVersion:    strings.TrimSpace(runtime.Str("to-version")),
+			FromVersion:  runtime.Str("from-version"),
+			ToVersion:    runtime.Str("to-version"),
 			FilePath:     strings.TrimSpace(runtime.Str("file")),
 			ContextLines: runtime.Int("context-lines"),
 		}
@@ -487,7 +488,7 @@ var MarkdownDiff = common.Shortcut{
 			} else {
 				fromLabel += "@latest"
 			}
-			_, fromContent, err = downloadMarkdownContent(ctx, runtime, spec.FileToken, spec.FromVersion)
+			_, fromContent, err = downloadMarkdownContent(ctx, runtime, spec.FileToken, spec.FromVersion, "--from-version")
 			if err != nil {
 				return err
 			}
@@ -499,17 +500,17 @@ var MarkdownDiff = common.Shortcut{
 			}
 		default:
 			fromLabel = "a/" + spec.FileToken + "@version:" + spec.FromVersion
-			_, fromContent, err = downloadMarkdownContent(ctx, runtime, spec.FileToken, spec.FromVersion)
+			_, fromContent, err = downloadMarkdownContent(ctx, runtime, spec.FileToken, spec.FromVersion, "--from-version")
 			if err != nil {
 				return err
 			}
 
 			if spec.ToVersion != "" {
 				toLabel = "b/" + spec.FileToken + "@version:" + spec.ToVersion
-				_, toContent, err = downloadMarkdownContent(ctx, runtime, spec.FileToken, spec.ToVersion)
+				_, toContent, err = downloadMarkdownContent(ctx, runtime, spec.FileToken, spec.ToVersion, "--to-version")
 			} else {
 				toLabel = "b/" + spec.FileToken + "@latest"
-				_, toContent, err = downloadMarkdownContent(ctx, runtime, spec.FileToken, "")
+				_, toContent, err = downloadMarkdownContent(ctx, runtime, spec.FileToken, "", "")
 			}
 			if err != nil {
 				return err

shortcuts/markdown/markdown_diff_test.go

@@ -48,6 +48,73 @@ func TestMarkdownDiffRejectsToVersionWithoutFromVersion(t *testing.T) {
 	}
 }
 
+func TestMarkdownDiffRejectsBlankVersion(t *testing.T) {
+	tests := []struct {
+		name      string
+		args      []string
+		wantParam string
+	}{
+		{
+			name: "from version",
+			args: []string{
+				"+diff",
+				"--file-token", "box_md_diff",
+				"--from-version", " \t",
+				"--file", "./local.md",
+			},
+			wantParam: "--from-version",
+		},
+		{
+			name: "to version",
+			args: []string{
+				"+diff",
+				"--file-token", "box_md_diff",
+				"--from-version", "7633658129540910621",
+				"--to-version", "  ",
+			},
+			wantParam: "--to-version",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+			f, stdout, _, _ := cmdutil.TestFactory(t, markdownTestConfig())
+
+			err := mountAndRunMarkdown(t, MarkdownDiff, tt.args, f, stdout)
+			requireMarkdownValidationParam(t, err, tt.wantParam)
+			if !strings.Contains(err.Error(), "cannot be empty") {
+				t.Fatalf("expected empty version validation error, got %v", err)
+			}
+		})
+	}
+}
+
+func TestMarkdownSourceFilePreviewParamsValidateAndPreserveVersion(t *testing.T) {
+	version := " 7633658129540910621 "
+
+	query, err := markdownSourceFilePreviewQuery(version, "--from-version")
+	if err != nil {
+		t.Fatalf("markdownSourceFilePreviewQuery() error: %v", err)
+	}
+	if got := query["version"]; len(got) != 1 || got[0] != version {
+		t.Fatalf("query version = %#v, want original %q", got, version)
+	}
+
+	params, err := markdownSourceFilePreviewDryRunParams(version, "--from-version")
+	if err != nil {
+		t.Fatalf("markdownSourceFilePreviewDryRunParams() error: %v", err)
+	}
+	if got := params["version"]; got != version {
+		t.Fatalf("dry-run version = %#v, want original %q", got, version)
+	}
+
+	_, err = markdownSourceFilePreviewQuery(" \n", "--from-version")
+	requireMarkdownValidationParam(t, err, "--from-version")
+	_, err = markdownSourceFilePreviewDryRunParams(" \t", "--to-version")
+	requireMarkdownValidationParam(t, err, "--to-version")
+}
+
 func TestMarkdownDiffMissingVersionAndFileNamesCandidateParams(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _, _ := cmdutil.TestFactory(t, markdownTestConfig())
@@ -79,7 +146,7 @@ func TestMarkdownDiffRemoteVsRemoteJSON(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_diff/download?version=7633658129540910621",
+		URL:     "/open-apis/drive/v1/medias/box_md_diff/preview_download?preview_type=16&version=7633658129540910621",
 		Status:  200,
 		RawBody: []byte("# Title\n\n- alpha\n- beta\n"),
 		Headers: http.Header{
@@ -88,7 +155,7 @@ func TestMarkdownDiffRemoteVsRemoteJSON(t *testing.T) {
 	})
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_diff/download?version=7633658129540910628",
+		URL:     "/open-apis/drive/v1/medias/box_md_diff/preview_download?preview_type=16&version=7633658129540910628",
 		Status:  200,
 		RawBody: []byte("# Title\n\n- alpha\n- beta updated\n- gamma\n"),
 		Headers: http.Header{
@@ -151,7 +218,7 @@ func TestMarkdownDiffRemoteVsLocalPretty(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_diff/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_diff/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# Title\n\nhello old\n"),
 		Headers: http.Header{
@@ -191,7 +258,7 @@ func TestMarkdownDiffRejectsOversizedRemoteContent(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_diff/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_diff/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: bytes.Repeat([]byte("x"), markdownDiffMaxContentBytes+1),
 	})
@@ -218,7 +285,7 @@ func TestMarkdownDiffRejectsOversizedLocalContent(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_diff/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_diff/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# Title\n"),
 	})
@@ -337,7 +404,7 @@ func TestMarkdownDiffRemoteVsRemoteJSONMultipleHunks(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_diff/download?version=7633658129540910621",
+		URL:     "/open-apis/drive/v1/medias/box_md_diff/preview_download?preview_type=16&version=7633658129540910621",
 		Status:  200,
 		RawBody: []byte("line1\nline2\nline3\nline4\nline5\nline6\n"),
 		Headers: http.Header{
@@ -346,7 +413,7 @@ func TestMarkdownDiffRemoteVsRemoteJSONMultipleHunks(t *testing.T) {
 	})
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_diff/download?version=7633658129540910628",
+		URL:     "/open-apis/drive/v1/medias/box_md_diff/preview_download?preview_type=16&version=7633658129540910628",
 		Status:  200,
 		RawBody: []byte("line1\nline2 changed\nline3\nline4\nline5 changed\nline6\n"),
 		Headers: http.Header{
@@ -398,13 +465,13 @@ func TestMarkdownDiffNoChangesPretty(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_diff/download?version=7633658129540910621",
+		URL:     "/open-apis/drive/v1/medias/box_md_diff/preview_download?preview_type=16&version=7633658129540910621",
 		Status:  200,
 		RawBody: []byte("# Title\n"),
 	})
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_diff/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_diff/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# Title\n"),
 	})
@@ -445,8 +512,11 @@ func TestMarkdownDiffDryRunRemoteVsLocal(t *testing.T) {
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if !strings.Contains(stdout.String(), "/open-apis/drive/v1/files/:file_token/download") && !strings.Contains(stdout.String(), "/open-apis/drive/v1/files/box_md_diff/download") {
-		t.Fatalf("dry-run missing download call: %s", stdout.String())
+	if !strings.Contains(stdout.String(), "/open-apis/drive/v1/medias/box_md_diff/preview_download") {
+		t.Fatalf("dry-run missing source preview download call: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"preview_type": "16"`) {
+		t.Fatalf("dry-run missing source_file preview_type: %s", stdout.String())
 	}
 	if !strings.Contains(stdout.String(), `"local_file": "local.md"`) && !strings.Contains(stdout.String(), `"local_file": "./local.md"`) {
 		t.Fatalf("dry-run missing local file metadata: %s", stdout.String())

shortcuts/markdown/markdown_fetch.go

@@ -5,14 +5,10 @@ package markdown
 
 import (
 	"context"
-	"fmt"
 	"io"
-	"net/http"
 	"path/filepath"
 	"strings"
 
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -47,8 +43,9 @@ var MarkdownFetch = common.Shortcut{
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		dry := common.NewDryRunAPI().
-			Desc("download markdown file bytes; when --output is omitted the CLI returns content as UTF-8 text").
-			GET("/open-apis/drive/v1/files/:file_token/download").
+			Desc("download markdown source file preview artifact bytes; when --output is omitted the CLI returns content as UTF-8 text").
+			GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+			Params(markdownSourceFilePreviewDryRunParamsForValidatedVersion("", "")).
 			Set("file_token", runtime.Str("file-token"))
 		if outputPath := strings.TrimSpace(runtime.Str("output")); outputPath != "" {
 			dry.Set("output", outputPath)
@@ -61,12 +58,9 @@ var MarkdownFetch = common.Shortcut{
 		fileToken := strings.TrimSpace(runtime.Str("file-token"))
 		outputPath := strings.TrimSpace(runtime.Str("output"))
 
-		resp, err := runtime.DoAPIStream(ctx, &larkcore.ApiReq{
-			HttpMethod: http.MethodGet,
-			ApiPath:    fmt.Sprintf("/open-apis/drive/v1/files/%s/download", validate.EncodePathSegment(fileToken)),
-		})
+		resp, err := openMarkdownDownload(ctx, runtime, fileToken)
 		if err != nil {
-			return wrapMarkdownDownloadError(err)
+			return err
 		}
 		defer resp.Body.Close()
 

shortcuts/markdown/markdown_patch.go

@@ -62,8 +62,9 @@ var MarkdownPatch = common.Shortcut{
 		sizeThreshold := common.FormatSize(markdownSinglePartSizeLimit)
 		return common.NewDryRunAPI().
 			Desc("Download the current Markdown file, apply the replacement locally, and overwrite the file only when matches are found").
-			GET("/open-apis/drive/v1/files/:file_token/download").
-			Desc("[1] Download the current Markdown content").
+			GET("/open-apis/drive/v1/medias/:file_token/preview_download").
+			Desc("[1] Download the current Markdown source file preview artifact").
+			Params(markdownSourceFilePreviewDryRunParamsForValidatedVersion("", "")).
 			Set("file_token", spec.FileToken).
 			POST("/open-apis/drive/v1/metas/batch_query").
 			Desc("[2] Read current file metadata to preserve the existing file name before overwrite").

shortcuts/markdown/markdown_patch_test.go

@@ -85,9 +85,12 @@ func TestMarkdownPatchDryRunLiteral(t *testing.T) {
 	if got := len(dry.API); got != 6 {
 		t.Fatalf("api steps = %d, want 6", got)
 	}
-	if got := dry.API[0].URL; got != "/open-apis/drive/v1/files/box_md_patch/download" {
+	if got := dry.API[0].URL; got != "/open-apis/drive/v1/medias/box_md_patch/preview_download" {
 		t.Fatalf("download url = %q", got)
 	}
+	if got := dry.API[0].Params["preview_type"]; got != markdownSourceFilePreviewType {
+		t.Fatalf("download preview_type = %#v", got)
+	}
 	if got := dry.API[1].URL; got != "/open-apis/drive/v1/metas/batch_query" {
 		t.Fatalf("metas url = %q", got)
 	}
@@ -120,7 +123,7 @@ func TestMarkdownPatchDryRunRegex(t *testing.T) {
 	if got := dry.Mode; got != markdownPatchModeRegex {
 		t.Fatalf("mode = %q, want %q", got, markdownPatchModeRegex)
 	}
-	if got := dry.API[0].Desc; !strings.Contains(got, "Download the current Markdown content") {
+	if got := dry.API[0].Desc; !strings.Contains(got, "Download the current Markdown source file preview artifact") {
 		t.Fatalf("download desc = %q", got)
 	}
 	if got := dry.API[3].Desc; !strings.Contains(got, "multipart overwrite upload") {
@@ -144,7 +147,7 @@ func TestMarkdownPatchReturnsSuccessWhenNothingMatches(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_patch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_patch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 	})
@@ -187,7 +190,7 @@ func TestMarkdownPatchPrettyOutputWhenNothingMatches(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_patch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_patch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 	})
@@ -224,7 +227,7 @@ func TestMarkdownPatchLiteralOverwrite(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_patch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_patch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# TODO\nTODO\n"),
 		Headers: map[string][]string{
@@ -299,7 +302,7 @@ func TestMarkdownPatchPrettyOutputWhenUpdated(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_patch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_patch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# TODO\n"),
 		Headers: map[string][]string{
@@ -360,7 +363,7 @@ func TestMarkdownPatchRegexOverwrite(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_patch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_patch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("Version: 12\nVersion: 34\n"),
 	})
@@ -429,7 +432,7 @@ func TestMarkdownPatchAllowsEmptyReplacement(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_patch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_patch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("hello world\n"),
 	})
@@ -478,7 +481,7 @@ func TestMarkdownPatchRejectsEmptyPatchedContent(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_patch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_patch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("hello\n"),
 	})
@@ -509,9 +512,10 @@ func decodeMarkdownEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]inter
 type markdownPatchDryRunOutput struct {
 	Mode string `json:"mode"`
 	API  []struct {
-		Desc string                 `json:"desc"`
-		URL  string                 `json:"url"`
-		Body map[string]interface{} `json:"body"`
+		Desc   string                 `json:"desc"`
+		URL    string                 `json:"url"`
+		Params map[string]interface{} `json:"params"`
+		Body   map[string]interface{} `json:"body"`
 	} `json:"api"`
 }
 

shortcuts/markdown/markdown_test.go

@@ -1984,7 +1984,7 @@ func TestMarkdownFetchReturnsContent(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_fetch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_fetch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 		Headers: map[string][]string{
@@ -2050,7 +2050,7 @@ func TestMarkdownFetchPrettyReturnsContent(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_fetch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_fetch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 		Headers: map[string][]string{
@@ -2078,7 +2078,7 @@ func TestMarkdownFetchSavesFile(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_fetch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_fetch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 		Headers: map[string][]string{
@@ -2122,7 +2122,7 @@ func TestMarkdownFetchRejectsExistingFileWithoutOverwrite(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_fetch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_fetch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 		Headers: map[string][]string{
@@ -2151,7 +2151,7 @@ func TestMarkdownFetchOverwritesExistingFileWhenRequested(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_fetch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_fetch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 		Headers: map[string][]string{
@@ -2189,7 +2189,7 @@ func TestMarkdownFetchSavesUsingRemoteNameWhenOutputIsExistingDirectory(t *testi
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_fetch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_fetch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 		Headers: map[string][]string{
@@ -2226,7 +2226,7 @@ func TestMarkdownFetchSavesUsingRemoteNameWhenOutputUsesDirectorySyntax(t *testi
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_fetch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_fetch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 		Headers: map[string][]string{
@@ -2260,7 +2260,7 @@ func TestMarkdownFetchPrettySavesFile(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_fetch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_fetch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 		Headers: map[string][]string{
@@ -2295,7 +2295,7 @@ func TestMarkdownFetchSaveFailure(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/box_md_fetch/download",
+		URL:     "/open-apis/drive/v1/medias/box_md_fetch/preview_download?preview_type=16",
 		Status:  200,
 		RawBody: []byte("# hello\n"),
 		Headers: map[string][]string{

shortcuts/slides/helpers.go

@@ -10,7 +10,6 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -111,16 +110,6 @@ func resolvePresentationID(runtime *common.RuntimeContext, ref presentationRef)
 	}
 }
 
-// slideReplaceAPIPath builds the xml_presentation.slide.replace endpoint for a
-// presentation. Shared by +replace-slide (element-level parts) and
-// +update-slide (a single whole-page part) so the two cannot drift apart.
-func slideReplaceAPIPath(presentationID string) string {
-	return fmt.Sprintf(
-		"/open-apis/slides_ai/v1/xml_presentations/%s/slide/replace",
-		validate.EncodePathSegment(presentationID),
-	)
-}
-
 // imgSrcPlaceholderRegex matches `src="@<path>"` or `src='@<path>'` inside <img> tags.
 // The "@" prefix is the magic marker for "this is a local file path; upload it and
 // replace with file_token".

shortcuts/slides/shortcuts.go

@@ -18,102 +18,50 @@ var presentationFlagAliases = []string{
 	"url",
 }
 
-// contentFlagAliases are the spellings agents reach for instead of --content
-// when handing a whole page of XML to +update-slide.
-//
-// Deliberately not "slide": several slides commands take a --slide-id, so
-// `--slide <id>` is a likely typo for that, and resolving it to --content
-// would turn the typo into a request carrying an id where page XML belongs.
-var contentFlagAliases = []string{
-	"xml",
-	"slide-xml",
-	"slide-content",
-	"content-xml",
-}
-
-// presentationAliasMap resolves every --presentation spelling and is attached
-// to every shortcut that declares that flag.
-var presentationAliasMap = aliasMap(map[string][]string{"presentation": presentationFlagAliases})
-
-// wholePageAliasMap additionally resolves the --content spellings. It is
-// attached only to the whole-page overwrite commands: --content exists on
-// other slides shortcuts too, and letting these aliases resolve there would
-// rewrite a mistyped flag into one the caller never meant to use.
-var wholePageAliasMap = aliasMap(map[string][]string{
-	"presentation": presentationFlagAliases,
-	"content":      contentFlagAliases,
-})
-
-// aliasMap inverts canonical→aliases into alias→canonical.
-func aliasMap(byCanonical map[string][]string) map[string]string {
-	out := make(map[string]string)
-	for canonical, aliases := range byCanonical {
-		for _, alias := range aliases {
-			out[alias] = canonical
-		}
-	}
-	return out
-}
-
 // Shortcuts returns all slides shortcuts.
 func Shortcuts() []common.Shortcut {
-	all := []struct {
-		shortcut common.Shortcut
-		aliases  map[string]string
-	}{
-		{shortcut: SlidesCreate, aliases: presentationAliasMap},
-		{shortcut: SlidesMediaUpload, aliases: presentationAliasMap},
-		{shortcut: SlidesReplaceSlide, aliases: presentationAliasMap},
-		{shortcut: SlidesReplacePages, aliases: presentationAliasMap},
-		{shortcut: SlidesUpdateSlide, aliases: wholePageAliasMap},
-		{shortcut: SlidesUpdate, aliases: wholePageAliasMap},
-		{shortcut: SlidesScreenshot, aliases: presentationAliasMap},
-		{shortcut: SlidesXMLGet, aliases: presentationAliasMap},
-		{shortcut: SlidesHistoryList, aliases: presentationAliasMap},
-		{shortcut: SlidesHistoryRevert, aliases: presentationAliasMap},
-		{shortcut: SlidesHistoryRevertStatus, aliases: presentationAliasMap},
+	all := []common.Shortcut{
+		SlidesCreate,
+		SlidesMediaUpload,
+		SlidesReplaceSlide,
+		SlidesReplacePages,
+		SlidesScreenshot,
+		SlidesXMLGet,
+		SlidesHistoryList,
+		SlidesHistoryRevert,
+		SlidesHistoryRevertStatus,
 	}
-	out := make([]common.Shortcut, 0, len(all))
-	for _, entry := range all {
-		if hasAliasableFlag(entry.shortcut.Flags, entry.aliases) {
-			entry.shortcut.PostMount = withFlagAliases(entry.aliases, entry.shortcut.PostMount)
+	for i := range all {
+		if hasPresentationFlag(all[i].Flags) {
+			all[i].PostMount = withPresentationFlagAliases(all[i].PostMount)
 		}
-		out = append(out, entry.shortcut)
 	}
-	return out
+	return all
 }
 
-// hasAliasableFlag reports whether the shortcut declares a flag that one of
-// the aliases resolves to, i.e. whether attaching the normalizer can do
-// anything.
-func hasAliasableFlag(flags []common.Flag, aliases map[string]string) bool {
+func hasPresentationFlag(flags []common.Flag) bool {
 	for _, flag := range flags {
-		for _, canonical := range aliases {
-			if flag.Name == canonical {
-				return true
-			}
+		if flag.Name == "presentation" {
+			return true
 		}
 	}
 	return false
 }
 
-// withFlagAliases accepts common agent-generated spellings for canonical flags
-// without registering extra flags. The aliases therefore stay out of help and
-// completion while resolving to the canonical flag at parse time, matching the
-// zero-round-trip compatibility used by Sheets.
-func withFlagAliases(aliases map[string]string, prev func(cmd *cobra.Command)) func(cmd *cobra.Command) {
+// withPresentationFlagAliases accepts common agent-generated spellings for
+// --presentation without registering extra flags. The aliases therefore stay
+// out of help and completion while resolving to the canonical flag at parse
+// time, matching the zero-round-trip compatibility used by Sheets.
+func withPresentationFlagAliases(prev func(cmd *cobra.Command)) func(cmd *cobra.Command) {
 	return func(cmd *cobra.Command) {
 		if prev != nil {
 			prev(cmd)
 		}
-		cmd.Flags().SetNormalizeFunc(func(fs *pflag.FlagSet, name string) pflag.NormalizedName {
-			// fs.Lookup re-enters this func with the canonical name; that
-			// terminates because no canonical name is itself an alias key
-			// (asserted by TestFlagAliasesAreNotCanonicalNames). Looking the
-			// canonical name up keeps a mistyped alias reported as the flag
-			// the caller actually typed on commands that lack the target.
-			if canonical, ok := aliases[name]; ok && fs.Lookup(canonical) != nil {
-				return pflag.NormalizedName(canonical)
+		cmd.Flags().SetNormalizeFunc(func(_ *pflag.FlagSet, name string) pflag.NormalizedName {
+			for _, alias := range presentationFlagAliases {
+				if name == alias {
+					return pflag.NormalizedName("presentation")
+				}
 			}
 			return pflag.NormalizedName(name)
 		})

shortcuts/slides/shortcuts_alias_test.go

@@ -7,128 +7,37 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
 
-func TestWithFlagAliases(t *testing.T) {
-	cases := []struct {
-		canonical string
-		aliases   []string
-	}{
-		{canonical: "presentation", aliases: presentationFlagAliases},
-		{canonical: "content", aliases: contentFlagAliases},
-	}
-	for _, tc := range cases {
-		for _, alias := range tc.aliases {
-			t.Run(tc.canonical+"/"+alias, func(t *testing.T) {
-				cmd := &cobra.Command{Use: "test"}
-				cmd.Flags().String(tc.canonical, "", tc.canonical+" value")
-				withFlagAliases(wholePageAliasMap, nil)(cmd)
+func TestWithPresentationFlagAliases(t *testing.T) {
+	for _, alias := range presentationFlagAliases {
+		t.Run(alias, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("presentation", "", "presentation reference")
+			withPresentationFlagAliases(nil)(cmd)
 
-				if err := cmd.Flags().Parse([]string{"--" + alias, "valABC"}); err != nil {
-					t.Fatalf("--%s should resolve to --%s: %v", alias, tc.canonical, err)
-				}
-				got, err := cmd.Flags().GetString(tc.canonical)
-				if err != nil {
-					t.Fatalf("read --%s: %v", tc.canonical, err)
-				}
-				if got != "valABC" {
-					t.Fatalf("--%s set --%s to %q, want valABC", alias, tc.canonical, got)
-				}
-				if usage := cmd.Flags().FlagUsages(); strings.Contains(usage, "--"+alias) {
-					t.Fatalf("hidden compatibility alias --%s leaked into help:\n%s", alias, usage)
-				}
-			})
-		}
-	}
-}
-
-// TestFlagAliasesOnlyResolveDeclaredFlags pins the guard that keeps a mistyped
-// alias reported as the flag the caller actually typed: when the command does
-// not declare the canonical target, the alias must be left alone.
-func TestFlagAliasesOnlyResolveDeclaredFlags(t *testing.T) {
-	cmd := &cobra.Command{Use: "test"}
-	cmd.Flags().String("presentation", "", "presentation reference")
-	withFlagAliases(wholePageAliasMap, nil)(cmd)
-
-	err := cmd.Flags().Parse([]string{"--xml", "<slide/>"})
-	if err == nil {
-		t.Fatal("--xml resolved on a command without --content, want unknown-flag error")
-	}
-	if !strings.Contains(err.Error(), "xml") {
-		t.Fatalf("error should name the flag the user typed, got: %v", err)
-	}
-}
-
-// TestContentAliasesStayOffOtherShortcuts is the regression guard for a
-// package-wide alias table: --content exists on other slides shortcuts, so a
-// shared table silently turned `--xml` / `--slide-xml` there into a --content
-// value the caller never meant to pass. Only the whole-page commands may
-// resolve them.
-func TestContentAliasesStayOffOtherShortcuts(t *testing.T) {
-	wholePage := map[string]bool{"+update-slide": true, "+update": true}
-	for _, shortcut := range Shortcuts() {
-		if wholePage[shortcut.Command] || !declaresFlag(shortcut.Flags, "content") {
-			continue
-		}
-		if shortcut.PostMount == nil {
-			continue
-		}
-		cmd := &cobra.Command{Use: shortcut.Command}
-		cmd.Flags().String("content", "", "content")
-		cmd.Flags().String("presentation", "", "presentation reference")
-		shortcut.PostMount(cmd)
-
-		for _, alias := range contentFlagAliases {
-			if err := cmd.Flags().Parse([]string{"--" + alias, "x"}); err == nil {
-				t.Errorf("%s resolved --%s to --content; content aliases must be scoped to the whole-page commands", shortcut.Command, alias)
+			if err := cmd.Flags().Parse([]string{"--" + alias, "presABC"}); err != nil {
+				t.Fatalf("--%s should resolve to --presentation: %v", alias, err)
 			}
-		}
+			got, err := cmd.Flags().GetString("presentation")
+			if err != nil {
+				t.Fatalf("read --presentation: %v", err)
+			}
+			if got != "presABC" {
+				t.Fatalf("--%s set --presentation to %q, want presABC", alias, got)
+			}
+			if usage := cmd.Flags().FlagUsages(); strings.Contains(usage, "--"+alias) {
+				t.Fatalf("hidden compatibility alias --%s leaked into help:\n%s", alias, usage)
+			}
+		})
 	}
 }
 
-// TestFlagAliasesAreNotCanonicalNames guards the termination argument in
-// withFlagAliases: fs.Lookup re-enters the normalizer with the canonical name,
-// which must not itself be an alias key.
-func TestFlagAliasesAreNotCanonicalNames(t *testing.T) {
-	for _, aliases := range []map[string]string{presentationAliasMap, wholePageAliasMap} {
-		canonical := map[string]bool{}
-		for _, name := range aliases {
-			canonical[name] = true
-		}
-		for alias, target := range aliases {
-			if canonical[alias] {
-				t.Errorf("alias %q is also a canonical flag name; normalization would recurse", alias)
-			}
-			if alias == target {
-				t.Errorf("alias %q maps to itself", alias)
-			}
-		}
-	}
-}
-
-// TestFlagAliasesDoNotShadowRealFlags catches the dangerous direction of
-// pflag.SetNormalizeFunc: it re-normalizes flags that are already registered,
-// so if a shortcut ever declares a flag whose name is an alias key, that flag
-// collapses into the canonical one — no panic, no error, just a missing flag.
-func TestFlagAliasesDoNotShadowRealFlags(t *testing.T) {
-	for _, shortcut := range Shortcuts() {
-		if shortcut.PostMount == nil {
-			continue
-		}
-		for _, flag := range shortcut.Flags {
-			if canonical, ok := wholePageAliasMap[flag.Name]; ok {
-				t.Errorf("%s declares --%s, which is an alias of --%s; the normalizer would erase it", shortcut.Command, flag.Name, canonical)
-			}
-		}
-	}
-}
-
-func TestShortcutsAttachFlagAliases(t *testing.T) {
+func TestShortcutsAttachPresentationFlagAliases(t *testing.T) {
 	count := 0
 	for _, shortcut := range Shortcuts() {
-		if !declaresFlag(shortcut.Flags, "presentation") {
+		if !hasPresentationFlag(shortcut.Flags) {
 			continue
 		}
 		count++
@@ -157,12 +66,3 @@ func TestShortcutsAttachFlagAliases(t *testing.T) {
 		t.Fatal("expected at least one slides shortcut with --presentation")
 	}
 }
-
-func declaresFlag(flags []common.Flag, name string) bool {
-	for _, flag := range flags {
-		if flag.Name == name {
-			return true
-		}
-	}
-	return false
-}

shortcuts/slides/slides_replace_slide.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -115,7 +116,10 @@ var SlidesReplaceSlide = common.Shortcut{
 		} else {
 			dry.Desc(fmt.Sprintf("Replace %d part(s) on slide %s", len(parts), slideID))
 		}
-		dry.POST(slideReplaceAPIPath(presentationID)).
+		dry.POST(fmt.Sprintf(
+			"/open-apis/slides_ai/v1/xml_presentations/%s/slide/replace",
+			validate.EncodePathSegment(presentationID),
+		)).
 			Params(query).
 			Body(body)
 		return dry.Set("parts_count", len(parts))
@@ -152,7 +156,11 @@ var SlidesReplaceSlide = common.Shortcut{
 		}
 		body := map[string]interface{}{"parts": injected}
 
-		data, err := runtime.CallAPITyped("POST", slideReplaceAPIPath(presentationID), query, body)
+		url := fmt.Sprintf(
+			"/open-apis/slides_ai/v1/xml_presentations/%s/slide/replace",
+			validate.EncodePathSegment(presentationID),
+		)
+		data, err := runtime.CallAPITyped("POST", url, query, body)
 		if err != nil {
 			return enrichSlidesReplaceError(err)
 		}

shortcuts/slides/slides_update_slide.go

@@ -1,390 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package slides
-
-import (
-	"context"
-	"fmt"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// SlidesUpdateSlide applies a whole page of XML to an existing slide, keeping
-// its slide_id and its position in the deck.
-//
-// The caller hands over the page they want; the CLI reads the page that is
-// there, diffs the two, and sends one element-level part per difference. That
-// indirection is not a stylistic choice — a single part covering the whole page
-// is impossible. ReplacePart.block_id is validated as a short ELEMENT id (it
-// must start with "b"), so the page's own id ("p"-prefixed) and the background
-// fill's id ("f"-prefixed) are both rejected with 3350001. Element ids are the
-// only handles this endpoint offers.
-//
-// What that buys the caller is the part they actually found painful: they no
-// longer enumerate parts or hand-write each element's full XML (coordinates,
-// size, font size included) to restyle a page. What it costs is one capability
-// the endpoint cannot express at all:
-//
-//   - The page background lives in <style>, which has no id of its own and
-//     whose <fill> id starts with "f". A changed <style> is therefore an error,
-//     not a silent no-op.
-//
-// Two more limits fall out of having no move operation and no way to invent
-// ids: reordering existing elements is rejected, and an id in --content that
-// does not exist on the page is rejected rather than created.
-var SlidesUpdateSlide = common.Shortcut{
-	Service:     "slides",
-	Command:     "+update-slide",
-	Description: "Apply a full <slide> XML to an existing slide by diffing it against the current page (keeps slide_id and page order; background changes are not supported)",
-	Risk:        "write",
-	// slides:presentation:read is unconditional: every execution reads the
-	// page before writing it, so it belongs in the enforced pre-flight set —
-	// ConditionalScopes is metadata only and would let a write-only token
-	// reach the GET before failing.
-	Scopes: []string{"slides:presentation:read", "slides:presentation:update", "slides:presentation:write_only"},
-	// wiki:node:read is required only when --presentation is a wiki URL.
-	ConditionalScopes: []string{"wiki:node:read"},
-	AuthTypes:         []string{"user", "bot"},
-	Tips: []string{
-		"Read-modify-write: `slides +xml-get --presentation <id> --slide-id <sid> --output page.xml` → edit page.xml → `slides +update-slide --content @page.xml`",
-		"--content is the page's target state: an element you drop is deleted, an element without an id is created",
-		"Keep the <style> block from the read unchanged — the page background cannot be changed through this command",
-		"Elements cannot be reordered and an unknown id cannot be created; both are rejected up front",
-		"Editing one shape / image is cheaper with `slides +replace-slide`",
-	},
-	Flags:    updateSlideFlags,
-	Validate: updateSlideValidate,
-	DryRun:   updateSlideDryRun,
-	Execute:  updateSlideExecute,
-}
-
-// SlidesUpdate registers `slides +update` as a hidden alias of +update-slide.
-//
-// Agents reach for "slide update" before reading --help (the command did not
-// exist, so they burned turns on the error plus a help dump). Accepting the
-// shorter spelling costs nothing and removes those round trips; it stays out
-// of --help so the canonical name is the only one advertised.
-//
-// Derived from the canonical shortcut rather than re-declared, so scopes,
-// identities and flags cannot drift between the two spellings.
-var SlidesUpdate = func() common.Shortcut {
-	sc := SlidesUpdateSlide
-	sc.Command = "+update"
-	sc.Hidden = true
-	return sc
-}()
-
-var updateSlideFlags = []common.Flag{
-	{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
-	{Name: "slide-id", Desc: "slide page identifier (slide_id) of the page to update", Required: true},
-	{Name: "content", Desc: "full page XML with a single <slide> root; it is diffed against the current page", Required: true, Input: []string{common.File, common.Stdin}},
-	{Name: "revision-id", Type: "int", Default: "-1", Desc: "revision to read and apply against; -1 (default) means latest. Pinning an older revision rebuilds the page from that snapshot and discards newer edits to it"},
-	{Name: "tid", Desc: "transaction id for concurrent-edit locking (usually empty)"},
-}
-
-func updateSlideValidate(_ context.Context, runtime *common.RuntimeContext) error {
-	ref, err := parsePresentationRef(runtime.Str("presentation"))
-	if err != nil {
-		return err
-	}
-	if ref.Kind == "wiki" {
-		if err := runtime.EnsureScopes([]string{"wiki:node:read"}); err != nil {
-			return err
-		}
-	}
-	slideID, err := updateSlideID(runtime)
-	if err != nil {
-		return err
-	}
-	// Only the shape of --content can be checked without a network call; the
-	// diff itself needs the current page.
-	_, err = parseWantedPageFor(runtime.Str("content"), slideID)
-	return err
-}
-
-// updateSlideDryRun reports what would be read and how, without calling the
-// API. The parts cannot be shown: they are derived from the page's current
-// state, which is exactly what dry-run must not fetch.
-func updateSlideDryRun(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	ref, err := parsePresentationRef(runtime.Str("presentation"))
-	if err != nil {
-		return common.NewDryRunAPI().Set("error", err.Error())
-	}
-	slideID, err := updateSlideID(runtime)
-	if err != nil {
-		return common.NewDryRunAPI().Set("error", err.Error())
-	}
-	wanted, err := parseWantedPageFor(runtime.Str("content"), slideID)
-	if err != nil {
-		return common.NewDryRunAPI().Set("error", err.Error())
-	}
-
-	dry := common.NewDryRunAPI()
-	presentationID := ref.Token
-	if ref.Kind == "wiki" {
-		presentationID = "<resolved_slides_token>"
-		dry.Desc("3-step orchestration: resolve wiki → read page → replace changed elements").
-			GET("/open-apis/wiki/v2/spaces/get_node").
-			Desc("[1] Resolve wiki node to slides presentation").
-			Params(map[string]interface{}{"token": ref.Token})
-	} else {
-		dry.Desc(fmt.Sprintf("2-step orchestration: read slide %s, then replace the elements that differ", slideID))
-	}
-	dry.GET(slideReadAPIPath(presentationID)).
-		Desc("[1] Read the current page to diff against").
-		Params(updateSlideQuery(runtime, slideID))
-	dry.POST(slideReplaceAPIPath(presentationID)).
-		Desc("[2] One element-level part per difference; the parts depend on the page's current state").
-		Params(updateSlideQuery(runtime, slideID))
-	return dry.Set("wanted_element_count", len(wanted.Elements))
-}
-
-func updateSlideExecute(_ context.Context, runtime *common.RuntimeContext) error {
-	ref, err := parsePresentationRef(runtime.Str("presentation"))
-	if err != nil {
-		return err
-	}
-	presentationID, err := resolvePresentationID(runtime, ref)
-	if err != nil {
-		return err
-	}
-	slideID, err := updateSlideID(runtime)
-	if err != nil {
-		return err
-	}
-	wanted, err := parseWantedPageFor(runtime.Str("content"), slideID)
-	if err != nil {
-		return err
-	}
-
-	current, err := readCurrentPage(runtime, presentationID, slideID)
-	if err != nil {
-		return err
-	}
-
-	// diffPage already reports the edits it cannot express as typed validation
-	// errors against --content.
-	diff, err := diffPage(current, wanted)
-	if err != nil {
-		return err
-	}
-
-	result := map[string]interface{}{
-		"xml_presentation_id": presentationID,
-		"slide_id":            slideID,
-		"parts_count":         len(diff.Parts),
-		"replaced":            diff.Replaced,
-		"inserted":            diff.Inserted,
-		"deleted":             diff.Deleted,
-	}
-	if diff.NoteCleared {
-		result["note_cleared"] = true
-	}
-	if diff.NoteReplaced {
-		result["note_replaced"] = true
-	}
-	// Nothing differs: report it instead of sending an empty batch, which the
-	// backend rejects, and instead of claiming a write that never happened.
-	if len(diff.Parts) == 0 {
-		result["unchanged"] = true
-		runtime.Out(result, nil)
-		return nil
-	}
-	if len(diff.Parts) > maxReplaceParts {
-		return errs.NewValidationError(
-			errs.SubtypeInvalidArgument,
-			"the page differs in %d elements, which needs %d parts and exceeds the maximum of %d; split the edit across several calls",
-			len(diff.Parts), len(diff.Parts), maxReplaceParts,
-		).WithParam("--content")
-	}
-
-	parts := make([]map[string]interface{}, 0, len(diff.Parts))
-	for _, part := range diff.Parts {
-		parts = append(parts, part.toMap())
-	}
-	data, err := runtime.CallAPITyped(
-		"POST",
-		slideReplaceAPIPath(presentationID),
-		updateSlideQuery(runtime, slideID),
-		map[string]interface{}{"parts": parts},
-	)
-	if err != nil {
-		return enrichSlidesReplaceError(err)
-	}
-
-	// A failure reason means the batch was rejected and nothing was written, so
-	// it cannot be reported inside a success envelope. The backend currently
-	// pairs one with a non-zero code, which CallAPITyped already turns into an
-	// error, so this guards an inconsistent response rather than a reachable
-	// path.
-	if reason := strings.TrimSpace(common.GetString(data, "failed_reason")); reason != "" {
-		return errs.NewAPIError(
-			errs.SubtypeInvalidParameters,
-			"slide %s was not updated: %s", slideID, reason,
-		).WithHint(slides3350001Hint)
-	}
-	if _, ok := data["revision_id"]; ok {
-		result["revision_id"] = int(common.GetFloat(data, "revision_id"))
-	}
-
-	runtime.Out(result, nil)
-	return nil
-}
-
-// readCurrentPage fetches the page the diff is computed against.
-func readCurrentPage(runtime *common.RuntimeContext, presentationID, slideID string) (pageDoc, error) {
-	data, err := runtime.CallAPITyped("GET", slideReadAPIPath(presentationID), updateSlideQuery(runtime, slideID), nil)
-	if err != nil {
-		return pageDoc{}, err
-	}
-	content := common.GetString(common.GetMap(data, "slide"), "content")
-	if strings.TrimSpace(content) == "" {
-		return pageDoc{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "reading slide %s returned empty content", slideID)
-	}
-	current, err := parsePageDoc(content)
-	if err != nil {
-		return pageDoc{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "slide %s returned XML the CLI cannot parse: %v", slideID, err).WithCause(err)
-	}
-	// A page whose structure the diff cannot see cannot be safely edited: the
-	// unrecognized part would be invisible to the comparison, so the command
-	// could neither preserve it deliberately nor notice the caller changing it.
-	if current.Unsupported != "" {
-		return pageDoc{}, errs.NewValidationError(
-			errs.SubtypeFailedPrecondition,
-			"slide %s contains %s, which this command cannot represent; use `slides +replace-slide` for element-level edits on this page",
-			slideID, current.Unsupported,
-		)
-	}
-	// A page carrying an <undefined> placeholder is refused outright. The
-	// placeholder stands for an object the server could not export (a
-	// whiteboard, unexported media); whether the whole-page rewrite behind
-	// slide.replace preserves an untouched one is a server-owned behavior that
-	// no self-contained test can pin down — boards cannot be created
-	// programmatically. Editing on top of an unverifiable assumption risks
-	// silently destroying the one object the caller cannot see, so the page is
-	// off-limits to this command until preservation is provable.
-	for _, el := range current.Elements {
-		if el.Tag == placeholderTag {
-			return pageDoc{}, errs.NewValidationError(
-				errs.SubtypeFailedPrecondition,
-				"slide %s contains an <undefined> placeholder (element %s) for an object the server could not export, such as a whiteboard; this command refuses to edit the page because it cannot prove a rewrite would preserve that object — use `slides +replace-slide` for element-level edits here",
-				slideID, el.ID,
-			)
-		}
-	}
-	return current, nil
-}
-
-// parseWantedPage validates --content and decomposes it.
-//
-// The root-tag check is a safety gate, not politeness: --content describes the
-// whole page, so an element-level fragment would be read as "the page should
-// contain only this", and every other element on it would be deleted.
-func parseWantedPage(content string) (pageDoc, error) {
-	trimmed := strings.TrimSpace(content)
-	if trimmed == "" {
-		return pageDoc{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content cannot be empty").WithParam("--content")
-	}
-	doc, err := parsePageDoc(trimmed)
-	if err != nil {
-		return pageDoc{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is not well-formed XML: %v", err).WithParam("--content").WithCause(err)
-	}
-	if doc.RootTag == "" {
-		return pageDoc{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content has no root element; pass one full <slide>…</slide> fragment").WithParam("--content")
-	}
-	if doc.RootTag != "slide" {
-		return pageDoc{}, updateSlideRootTagError(doc.RootTag)
-	}
-	if doc.TrailingTag != "" {
-		return pageDoc{}, errs.NewValidationError(
-			errs.SubtypeInvalidArgument,
-			"--content has a <%s> element after the </slide> root; pass exactly one page per call",
-			doc.TrailingTag,
-		).WithParam("--content")
-	}
-	if doc.TrailingText {
-		return pageDoc{}, errs.NewValidationError(
-			errs.SubtypeInvalidArgument,
-			"--content has text after the </slide> root; pass exactly one <slide>…</slide> fragment",
-		).WithParam("--content")
-	}
-	// Anything the decomposition could not place has no part it could become.
-	// Accepting it and diffing only the recognized parts would drop the edit —
-	// and could even answer `unchanged` for a change the caller asked for.
-	if doc.Unsupported != "" {
-		return pageDoc{}, contentError(
-			"--content contains %s, which this command cannot represent; a <slide> carries exactly one <style>, one <data> and one <note>",
-			doc.Unsupported,
-		)
-	}
-	return doc, nil
-}
-
-// parseWantedPageFor additionally pins the root id, when present, to the page
-// being updated. XML fetched for page A and posted against --slide-id for page
-// B is the classic wrong-target mistake; the element-id checks catch it only
-// incidentally (an empty page, or one whose element ids were stripped, would
-// sail through and rebuild B with A's content).
-func parseWantedPageFor(content, slideID string) (pageDoc, error) {
-	doc, err := parseWantedPage(content)
-	if err != nil {
-		return doc, err
-	}
-	if doc.RootID != "" && doc.RootID != slideID {
-		return doc, contentError(
-			"--content root carries id %q but --slide-id is %q; this XML looks like it was read from a different page — re-run `slides +xml-get` for this page, or drop the root id to apply the content here",
-			doc.RootID, slideID,
-		)
-	}
-	return doc, nil
-}
-
-// updateSlideRootTagError explains what to use instead, picked by what the
-// caller actually passed: a whole presentation is a multi-page job, anything
-// else is an element-level edit.
-func updateSlideRootTagError(rootTag string) error {
-	remedy := "use `slides +replace-slide` to edit individual elements"
-	if rootTag == "presentation" {
-		remedy = "pass a single page's <slide> XML, or use `slides +replace-pages` to rebuild several pages at once"
-	}
-	return errs.NewValidationError(
-		errs.SubtypeInvalidArgument,
-		"--content root element is <%s>, but +update-slide takes a whole page and requires a single <slide> root; %s",
-		rootTag, remedy,
-	).WithParam("--content")
-}
-
-// updateSlideID reads and validates --slide-id.
-func updateSlideID(runtime *common.RuntimeContext) (string, error) {
-	slideID := strings.TrimSpace(runtime.Str("slide-id"))
-	if slideID == "" {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--slide-id cannot be empty").WithParam("--slide-id")
-	}
-	return slideID, nil
-}
-
-// updateSlideQuery builds the query params shared by the read, the write and
-// dry-run. The same revision is used for both calls so the parts are applied to
-// the snapshot they were computed from.
-func updateSlideQuery(runtime *common.RuntimeContext, slideID string) map[string]interface{} {
-	query := map[string]interface{}{
-		"slide_id":    slideID,
-		"revision_id": runtime.Int("revision-id"),
-	}
-	if tid := strings.TrimSpace(runtime.Str("tid")); tid != "" {
-		query["tid"] = tid
-	}
-	return query
-}
-
-// slideReadAPIPath is the single-slide read endpoint.
-func slideReadAPIPath(presentationID string) string {
-	return fmt.Sprintf(
-		"/open-apis/slides_ai/v1/xml_presentations/%s/slide",
-		validate.EncodePathSegment(presentationID),
-	)
-}

shortcuts/slides/slides_update_slide_diff.go

@@ -1,598 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package slides
-
-import (
-	"encoding/xml"
-	"errors"
-	"fmt"
-	"io"
-	"sort"
-	"strconv"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// This file turns "here is the page I want" into the element-level parts the
-// slide.replace endpoint accepts.
-//
-// A whole-page part is not an option: ReplacePart.block_id is validated as a
-// short ELEMENT id (it must start with "b"), so neither the page's own id nor
-// the background fill's id (which starts with "f") can be addressed. Verified
-// against the live API — a slide-rooted replacement and a fill-targeted
-// replacement are both rejected with 3350001, while element-level parts on the
-// same page succeed. So the CLI diffs the caller's page against the current one
-// and emits one part per changed element.
-//
-// Comparison is canonical (attributes sorted, insignificant whitespace
-// dropped) because the server returns pretty-printed XML with normalized
-// attribute order and injected style defaults; a raw string compare would call
-// every element changed. What gets SENT is the caller's exact bytes, so their
-// formatting and attribute order survive into the page.
-
-// contentError reports an edit --content asks for that element-level parts
-// cannot express. Every one of these is a refusal to guess: the alternative is
-// applying part of the edit, or returning success with it silently dropped.
-func contentError(format string, args ...any) error {
-	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...).WithParam("--content")
-}
-
-// smlNamespaces are the namespace forms a page may declare on its root — the
-// official identifier plus the two read-back spellings the server emits.
-// Mirrors ACCEPTED_SML_NAMESPACES in
-// skills/lark-slides/scripts/sxsd_validator.py; keep the two lists in sync.
-var smlNamespaces = map[string]bool{
-	"http://www.larkoffice.com/sml/2.0":  true,
-	"https://www.larkoffice.com/sml/2.0": true,
-	"/sml/2.0":                           true,
-}
-
-// placeholderTag is the element the server substitutes for objects it cannot
-// export as SML — a whiteboard read without its export option, video and audio
-// embeds. The caller cannot see what is behind one, and no self-contained
-// endpoint test can prove that a page rewrite preserves it (boards cannot be
-// created programmatically — the CLI has no whiteboard-create and SML has no
-// whiteboard element), so pages carrying one are refused outright rather than
-// edited on an unverifiable assumption. The element-level escape hatch is
-// +replace-slide.
-const placeholderTag = "undefined"
-
-// pageNode is one addressable node of a page.
-type pageNode struct {
-	Tag string
-	// ID is the short id carried by the node, empty when it has none. Only
-	// "b"-prefixed ids are addressable as a part's block_id.
-	ID string
-	// Raw is the caller's (or server's) exact bytes for this node.
-	Raw string
-	// Canon is the comparison form: attributes sorted, whitespace collapsed.
-	Canon string
-}
-
-// pageDoc is a decomposed <slide> document.
-type pageDoc struct {
-	// RootTag is the local name of the first element, "" when there is none.
-	RootTag string
-	RootID  string
-	// Style and Note are the <style> / <note> children of <slide>, nil when
-	// absent.
-	Style *pageNode
-	Note  *pageNode
-	// Elements are the <data> children in document order.
-	Elements []pageNode
-	// TrailingTag and TrailingText report content after the root's close tag.
-	TrailingTag  string
-	TrailingText bool
-	// Unsupported names the first slide-level structure the diff cannot
-	// represent: an unknown direct child of <slide>, a duplicate <style> /
-	// <data> / <note>, or stray text. Empty means the page decomposed cleanly.
-	//
-	// This must be an error, not a shrug: a diff computed from only the
-	// recognized parts would drop the unrecognized edit and could even report
-	// `unchanged` — a success claim for a change that never happened.
-	Unsupported string
-}
-
-// elementByID indexes Elements by id, skipping nodes without one.
-func (d pageDoc) elementByID() map[string]pageNode {
-	out := make(map[string]pageNode, len(d.Elements))
-	for _, el := range d.Elements {
-		if el.ID != "" {
-			out[el.ID] = el
-		}
-	}
-	return out
-}
-
-// orderedIDs returns the ids of Elements that carry one, in document order.
-func (d pageDoc) orderedIDs() []string {
-	out := make([]string, 0, len(d.Elements))
-	for _, el := range d.Elements {
-		if el.ID != "" {
-			out = append(out, el.ID)
-		}
-	}
-	return out
-}
-
-// parsePageDoc walks a <slide> document once and records every addressable
-// node together with the exact bytes it came from.
-//
-// Raw slices are cut from the input using the decoder's byte offsets rather
-// than re-serialized, so a replacement carries the caller's own formatting
-// instead of whatever encoding/xml would emit.
-func parsePageDoc(pageXML string) (pageDoc, error) {
-	var doc pageDoc
-	decoder := xml.NewDecoder(strings.NewReader(pageXML))
-	var (
-		stack      []string
-		rootClosed bool
-		dataSeen   int
-		// capture is the node currently being sliced out: its start offset and
-		// the depth at which it ends.
-		capturing  bool
-		captureAt  int64
-		captureTag string
-		captureID  string
-		captureIn  string // "root" for <slide> children, "data" for <data> children
-	)
-	unsupported := func(format string, args ...any) {
-		if doc.Unsupported == "" {
-			doc.Unsupported = fmt.Sprintf(format, args...)
-		}
-	}
-	for {
-		before := decoder.InputOffset()
-		token, err := decoder.Token()
-		if errors.Is(err, io.EOF) {
-			break
-		}
-		if err != nil {
-			return doc, err
-		}
-		switch t := token.(type) {
-		case xml.StartElement:
-			switch {
-			case len(stack) == 0 && rootClosed:
-				if doc.TrailingTag == "" {
-					doc.TrailingTag = t.Name.Local
-				}
-			case len(stack) == 0:
-				doc.RootTag, doc.RootID = t.Name.Local, attrValue(t, "id")
-				// The diff carries the root's id and nothing else, so any
-				// other attribute would be accepted and then neither compared
-				// nor sent — an edit to it would vanish into `unchanged`.
-				// Namespace declarations are no exception: a binding inherited
-				// from the root changes what every descendant name means, and
-				// the canonical comparison reads local names precisely because
-				// legitimate pages differ only in carrying the one official
-				// declaration or not. Anything else must not be waved through.
-				for _, attr := range t.Attr {
-					switch {
-					case attr.Name.Space == "" && attr.Name.Local == "id":
-					case attr.Name.Space == "" && attr.Name.Local == "xmlns":
-						if !smlNamespaces[attr.Value] {
-							unsupported("an unsupported xmlns %q on <%s>", attr.Value, t.Name.Local)
-						}
-					case attr.Name.Space == "xmlns":
-						unsupported("a prefixed namespace declaration %q on <%s>", "xmlns:"+attr.Name.Local, t.Name.Local)
-					default:
-						unsupported("an unsupported attribute %q on <%s>", attrDisplayName(attr), t.Name.Local)
-					}
-				}
-			case !capturing && len(stack) == 1:
-				// Direct children of <slide>: exactly one <style>, one <data>
-				// and one <note> are representable; anything else has no
-				// element-level part it could become.
-				switch t.Name.Local {
-				case "style":
-					if doc.Style != nil {
-						unsupported("a second <style> element")
-						break
-					}
-					capturing, captureAt = true, elementStart(pageXML, before)
-					captureTag, captureID, captureIn = t.Name.Local, attrValue(t, "id"), "root"
-				case "note":
-					if doc.Note != nil {
-						unsupported("a second <note> element")
-						break
-					}
-					capturing, captureAt = true, elementStart(pageXML, before)
-					captureTag, captureID, captureIn = t.Name.Local, attrValue(t, "id"), "root"
-				case "data":
-					dataSeen++
-					if dataSeen > 1 {
-						unsupported("a second <data> element")
-					}
-					// <data> is pure structure to the diff; an attribute on it
-					// — namespace declarations included, since captured Raw
-					// slices would not carry an inherited binding — has no
-					// element-level part it could travel in.
-					for _, attr := range t.Attr {
-						unsupported("an unsupported attribute %q on <data>", attrDisplayName(attr))
-					}
-				default:
-					unsupported("an unknown <%s> element directly under <slide>", t.Name.Local)
-				}
-			case !capturing && len(stack) == 2 && stack[1] == "data":
-				capturing, captureAt = true, elementStart(pageXML, before)
-				captureTag, captureID, captureIn = t.Name.Local, attrValue(t, "id"), "data"
-			}
-			stack = append(stack, t.Name.Local)
-		case xml.EndElement:
-			closingDepth := len(stack)
-			if closingDepth > 0 {
-				stack = stack[:closingDepth-1]
-			}
-			if len(stack) == 0 {
-				rootClosed = true
-			}
-			// A captured node ends when the stack returns to the depth it
-			// started at: "root" children start at depth 1, "data" children at
-			// depth 2.
-			startDepth := 1
-			if captureIn == "data" {
-				startDepth = 2
-			}
-			if capturing && len(stack) == startDepth {
-				raw := strings.TrimSpace(pageXML[captureAt:decoder.InputOffset()])
-				canon, err := canonicalizeElement(raw)
-				if err != nil {
-					return doc, err
-				}
-				node := pageNode{Tag: captureTag, ID: captureID, Raw: raw, Canon: canon}
-				switch {
-				case captureIn == "root" && captureTag == "style":
-					doc.Style = &node
-				case captureIn == "root" && captureTag == "note":
-					doc.Note = &node
-				case captureIn == "data":
-					doc.Elements = append(doc.Elements, node)
-				}
-				capturing = false
-			}
-		case xml.CharData:
-			if strings.TrimSpace(string(t)) == "" {
-				break // pretty-printed indentation, never meaningful
-			}
-			switch {
-			case rootClosed && len(stack) == 0:
-				doc.TrailingText = true
-			case !capturing && len(stack) == 1:
-				unsupported("text directly inside <slide>")
-			case !capturing && len(stack) == 2 && stack[1] == "data":
-				unsupported("text directly inside <data>")
-			}
-		}
-	}
-	return doc, nil
-}
-
-// elementStart returns the offset of the '<' that opens the token beginning at
-// or after off, so a captured slice starts at the tag rather than at the
-// whitespace preceding it.
-func elementStart(s string, off int64) int64 {
-	for i := int(off); i < len(s); i++ {
-		if s[i] == '<' {
-			return int64(i)
-		}
-	}
-	return off
-}
-
-func attrValue(el xml.StartElement, name string) string {
-	for _, attr := range el.Attr {
-		if attr.Name.Local == name {
-			return attr.Value
-		}
-	}
-	return ""
-}
-
-// attrDisplayName renders an attribute name for error messages.
-func attrDisplayName(attr xml.Attr) string {
-	if attr.Name.Space != "" {
-		return attr.Name.Space + ":" + attr.Name.Local
-	}
-	return attr.Name.Local
-}
-
-// canonicalizeElement renders an element fragment in a stable form: attributes
-// sorted by name, indentation between structural elements dropped, paragraph
-// text preserved verbatim and escaped.
-//
-// This exists so "unchanged" survives the round trip through the server, which
-// re-orders attributes, indents the XML and injects style defaults that the
-// caller never wrote.
-//
-// The whitespace rule is asymmetric by design. Outside <p>, whitespace-only
-// character data is the pretty-printer's indentation and never content. Inside
-// a <p> subtree it is kept verbatim: SML itself collapses a literal space
-// between inline tags, but a preserved space written as &#32; decodes to the
-// very same token, so dropping "insignificant" whitespace here would also drop
-// a real &#32; edit as `unchanged`. Keeping both costs at most a spurious
-// rewrite of identical content; dropping either loses an edit.
-func canonicalizeElement(fragment string) (string, error) {
-	decoder := xml.NewDecoder(strings.NewReader(fragment))
-	var out strings.Builder
-	pDepth := 0
-	for {
-		token, err := decoder.Token()
-		if errors.Is(err, io.EOF) {
-			return out.String(), nil
-		}
-		if err != nil {
-			return "", err
-		}
-		switch t := token.(type) {
-		case xml.StartElement:
-			// Element names stay namespace-free on purpose: a fragment cut
-			// from a document with a default xmlns resolves its elements into
-			// that namespace, while the same fragment from the server's plain
-			// output does not — including it would make every round-trip look
-			// changed. SML is a single vocabulary, so local names cannot clash.
-			out.WriteString("<" + t.Name.Local)
-			attrs := make([]string, 0, len(t.Attr))
-			for _, attr := range t.Attr {
-				name := attr.Name.Local
-				// Attributes do not inherit the default namespace, so a
-				// non-empty Space is explicit (xmlns declarations, prefixed
-				// attributes) and part of the attribute's identity.
-				if attr.Name.Space != "" {
-					name = attr.Name.Space + ":" + name
-				}
-				// Quote the value: with bare name=value concatenation,
-				// alt="foo rotateWithShape=true" and the two attributes
-				// alt="foo" rotateWithShape="true" canonicalize identically,
-				// and the diff would drop a real change as unchanged.
-				attrs = append(attrs, name+"="+strconv.Quote(attr.Value))
-			}
-			sort.Strings(attrs)
-			for _, attr := range attrs {
-				out.WriteString(" " + attr)
-			}
-			out.WriteString(">")
-			if t.Name.Local == "p" {
-				pDepth++
-			}
-		case xml.EndElement:
-			out.WriteString("</" + t.Name.Local + ">")
-			if t.Name.Local == "p" && pDepth > 0 {
-				pDepth--
-			}
-		case xml.CharData:
-			if pDepth == 0 && strings.TrimSpace(string(t)) == "" {
-				break // indentation between structural elements, never content
-			}
-			// Escaped, so text can never imitate markup in the comparison
-			// stream: a paragraph holding the literal text "</p><p>" must not
-			// compare equal to two empty paragraphs.
-			if err := xml.EscapeText(&out, t); err != nil {
-				return "", err
-			}
-		}
-	}
-}
-
-// replacePart is one entry of the request body.
-type replacePartOut struct {
-	Action              string
-	BlockID             string
-	Replacement         string
-	Insertion           string
-	InsertBeforeBlockID string
-}
-
-func (p replacePartOut) toMap() map[string]interface{} {
-	m := map[string]interface{}{"action": p.Action}
-	switch p.Action {
-	case "block_replace":
-		m["block_id"] = p.BlockID
-		m["replacement"] = p.Replacement
-	case "block_insert":
-		m["insertion"] = p.Insertion
-		if p.InsertBeforeBlockID != "" {
-			m["insert_before_block_id"] = p.InsertBeforeBlockID
-		}
-	}
-	return m
-}
-
-// pageDiff is the outcome of comparing the wanted page against the current one.
-type pageDiff struct {
-	Parts []replacePartOut
-	// Counters describe what the parts do, for the result envelope.
-	Replaced, Inserted, Deleted int
-	NoteCleared, NoteReplaced   bool
-}
-
-// diffPage produces the parts that turn current into wanted.
-//
-// Semantics: --content is the page's target state. An element present in
-// current but absent from wanted is deleted; an element without an id is
-// created. The background is the one thing that cannot be expressed, so a
-// changed <style> is an error rather than a silent no-op.
-func diffPage(current, wanted pageDoc) (pageDiff, error) {
-	var diff pageDiff
-
-	if err := diffStyle(current, wanted); err != nil {
-		return diff, err
-	}
-
-	currentByID := current.elementByID()
-	// Pages carrying a placeholder are rejected on read (see readCurrentPage),
-	// so one here can only be hand-authored content — and there is nothing it
-	// could correctly mean: the object it stands for cannot be created, and a
-	// page that really had one would never have reached the diff.
-	for _, el := range wanted.Elements {
-		if el.Tag == placeholderTag {
-			return diff, contentError(
-				"--content contains an <undefined> element; it is only the server's stand-in for an object it could not export, and pages carrying one cannot be edited by this command — use `slides +replace-slide`",
-			)
-		}
-	}
-	wantedIDs := map[string]bool{}
-	for _, el := range wanted.Elements {
-		if el.ID == "" {
-			continue
-		}
-		if _, ok := currentByID[el.ID]; !ok {
-			return diff, contentError(
-				"element id %q in --content does not exist on slide %s; drop the id to create it as a new element, or re-read the page",
-				el.ID, current.RootID,
-			)
-		}
-		if wantedIDs[el.ID] {
-			return diff, contentError("element id %q appears twice in --content", el.ID)
-		}
-		wantedIDs[el.ID] = true
-	}
-
-	// Surviving elements must keep their relative order: there is no move
-	// operation, so a reorder cannot be expressed and must not be silently
-	// dropped.
-	if err := checkOrderPreserved(current.orderedIDs(), wanted.orderedIDs(), wantedIDs); err != nil {
-		return diff, err
-	}
-
-	// Deletions first so later inserts land at the positions the caller meant.
-	for _, el := range current.Elements {
-		if el.ID != "" && !wantedIDs[el.ID] {
-			diff.Parts = append(diff.Parts, replacePartOut{
-				Action:  "block_replace",
-				BlockID: el.ID,
-				// An empty replacement deletes the block.
-				Replacement: "",
-			})
-			diff.Deleted++
-		}
-	}
-
-	for i, el := range wanted.Elements {
-		switch {
-		case el.ID == "":
-			diff.Parts = append(diff.Parts, replacePartOut{
-				Action:              "block_insert",
-				Insertion:           el.Raw,
-				InsertBeforeBlockID: nextSurvivingID(wanted.Elements, i, wantedIDs),
-			})
-			diff.Inserted++
-		case el.Canon != currentByID[el.ID].Canon:
-			diff.Parts = append(diff.Parts, replacePartOut{
-				Action:      "block_replace",
-				BlockID:     el.ID,
-				Replacement: el.Raw,
-			})
-			diff.Replaced++
-		}
-	}
-
-	notePart, err := diffNote(current, wanted)
-	if err != nil {
-		return diff, err
-	}
-	if notePart != nil {
-		diff.Parts = append(diff.Parts, *notePart)
-		if wanted.Note == nil {
-			diff.NoteCleared = true
-		} else {
-			diff.NoteReplaced = true
-		}
-	}
-
-	return diff, nil
-}
-
-// diffStyle rejects a background change instead of dropping it.
-//
-// <style> has no id of its own and the <fill> inside it carries an "f"-prefixed
-// id, which the endpoint's block_id validation rejects. There is therefore no
-// way to change a page's background through this path at all — saying so beats
-// returning success with the background untouched.
-func diffStyle(current, wanted pageDoc) error {
-	currentStyle, wantedStyle := "", ""
-	if current.Style != nil {
-		currentStyle = current.Style.Canon
-	}
-	if wanted.Style != nil {
-		wantedStyle = wanted.Style.Canon
-	}
-	if currentStyle == wantedStyle {
-		return nil
-	}
-	if wanted.Style == nil {
-		return contentError(
-			"--content has no <style> but the slide has one; the page background cannot be changed through this command — copy the existing <style> over from `slides +xml-get` output",
-		)
-	}
-	return contentError(
-		"--content changes <style> (the page background), which this command cannot express: the background has no addressable element id — keep the <style> from `slides +xml-get` output unchanged",
-	)
-}
-
-// diffNote turns a note change into a part, or reports that it cannot be made.
-func diffNote(current, wanted pageDoc) (*replacePartOut, error) {
-	currentNote, wantedNote := "", ""
-	if current.Note != nil {
-		currentNote = current.Note.Canon
-	}
-	if wanted.Note != nil {
-		wantedNote = wanted.Note.Canon
-	}
-	if currentNote == wantedNote {
-		return nil, nil
-	}
-	// Editing or clearing the note both go through the existing note block, so
-	// the current page has to have one to address.
-	if current.Note == nil || current.Note.ID == "" {
-		return nil, contentError("slide %s has no addressable <note>; speaker notes cannot be changed through this command", current.RootID)
-	}
-	replacement := fmt.Sprintf("<note id=%q><content/></note>", current.Note.ID)
-	if wanted.Note != nil {
-		replacement = wanted.Note.Raw
-	}
-	return &replacePartOut{
-		Action:      "block_replace",
-		BlockID:     current.Note.ID,
-		Replacement: replacement,
-	}, nil
-}
-
-// checkOrderPreserved verifies the surviving ids appear in the same relative
-// order on both sides.
-func checkOrderPreserved(currentIDs, wantedIDs []string, surviving map[string]bool) error {
-	kept := make([]string, 0, len(currentIDs))
-	for _, id := range currentIDs {
-		if surviving[id] {
-			kept = append(kept, id)
-		}
-	}
-	if len(kept) != len(wantedIDs) {
-		// Length mismatch is already covered by the unknown-id and duplicate
-		// checks in diffPage; nothing to add here.
-		return nil
-	}
-	for i := range kept {
-		if kept[i] != wantedIDs[i] {
-			return contentError(
-				"--content reorders existing elements (expected %s at position %d, got %s); this command cannot move elements — delete and re-insert them, or keep the original order",
-				kept[i], i+1, wantedIDs[i],
-			)
-		}
-	}
-	return nil
-}
-
-// nextSurvivingID finds the id-bearing element that follows position i, so a
-// new element is inserted at the position the caller wrote it in. An empty
-// result means "append to the end of the page".
-func nextSurvivingID(elements []pageNode, i int, surviving map[string]bool) string {
-	for _, el := range elements[i+1:] {
-		if el.ID != "" && surviving[el.ID] {
-			return el.ID
-		}
-	}
-	return ""
-}

shortcuts/slides/slides_update_slide_test.go

@@ -1,898 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package slides
-
-import (
-	"encoding/json"
-	"errors"
-	"net/http"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// currentPageXML is shaped like what the server actually returns: pretty
-// printed, attributes in its own order, style defaults injected that the caller
-// never wrote, and ids on the style fill ("f"-prefixed) and the note
-// ("b"-prefixed).
-const currentPageXML = `<slide id="piy">
-  <style>
-    <fill id="fiy">
-      <fillColor color="rgba(255, 255, 255, 1)"/>
-    </fill>
-  </style>
-  <data>
-    <shape width="800" height="120" topLeftX="80" topLeftY="80" type="text" id="bbD">
-      <content textType="title" fontSize="54" fontFamily="思源黑体">
-        <p>BEFORE</p>
-      </content>
-    </shape>
-    <shape width="400" height="80" topLeftX="80" topLeftY="260" type="text" id="bbv">
-      <content fontSize="16" fontFamily="思源黑体">
-        <p>SECOND</p>
-      </content>
-    </shape>
-  </data>
-  <note id="bbb">
-    <content/>
-  </note>
-</slide>`
-
-const currentStyleXML = `<style>
-    <fill id="fiy">
-      <fillColor color="rgba(255, 255, 255, 1)"/>
-    </fill>
-  </style>`
-
-// wantPage assembles a page in the caller's own style, so the tests exercise
-// the canonical comparison rather than string equality.
-func wantPage(style, data, note string) string {
-	return `<slide id="piy">` + style + `<data>` + data + `</data>` + note + `</slide>`
-}
-
-const (
-	elemOne    = `<shape id="bbD" type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title" fontSize="54" fontFamily="思源黑体"><p>BEFORE</p></content></shape>`
-	elemOneNew = `<shape id="bbD" type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title" fontSize="54" fontFamily="楷体"><p>BEFORE</p></content></shape>`
-	elemTwo    = `<shape id="bbv" type="text" topLeftX="80" topLeftY="260" width="400" height="80"><content fontSize="16" fontFamily="思源黑体"><p>SECOND</p></content></shape>`
-	noteKept   = `<note id="bbb"><content/></note>`
-)
-
-// registerPageRead stubs the read half. The write stub must be registered with
-// Method POST, since httpmock matches the URL by substring and "/slide" is a
-// prefix of "/slide/replace".
-func registerPageRead(t *testing.T, reg *httpmock.Registry, pageXML string) {
-	t.Helper()
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"slide":       map[string]interface{}{"slide_id": "piy", "content": pageXML},
-				"revision_id": 7,
-			},
-		},
-	})
-}
-
-func registerWriteStub(t *testing.T, reg *httpmock.Registry, revision int) *httpmock.Stub {
-	t.Helper()
-	stub := &httpmock.Stub{
-		Method: "POST",
-		URL:    "/slide/replace",
-		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"revision_id": revision}},
-	}
-	reg.Register(stub)
-	return stub
-}
-
-// forbidWrite registers a POST stub that fails the test if it is ever hit.
-func forbidWrite(t *testing.T, reg *httpmock.Registry, why string) {
-	t.Helper()
-	reg.Register(&httpmock.Stub{
-		Method:   "POST",
-		URL:      "/slide/replace",
-		Optional: true,
-		OnMatch:  func(*http.Request) { t.Error(why) },
-		Body:     map[string]interface{}{"code": 0, "data": map[string]interface{}{}},
-	})
-}
-
-func runUpdateSlide(t *testing.T, f *cmdutil.Factory, content string, extra ...string) error {
-	t.Helper()
-	args := append([]string{
-		"+update-slide",
-		"--presentation", "pres_abc",
-		"--slide-id", "piy",
-		"--content", content,
-	}, extra...)
-	return runSlidesShortcut(t, f, nil, SlidesUpdateSlide, append(args, "--as", "user"))
-}
-
-func TestUpdateSlideDeclaredScopes(t *testing.T) {
-	// The read scope is ENFORCED, not merely declared: every execution reads
-	// the page before writing it, and ConditionalScopes would let a write-only
-	// token reach the GET before failing.
-	want := []string{"slides:presentation:read", "slides:presentation:update", "slides:presentation:write_only"}
-	for _, sc := range []common.Shortcut{SlidesUpdateSlide, SlidesUpdate} {
-		if got := sc.ScopesForIdentity("user"); !reflect.DeepEqual(got, want) {
-			t.Errorf("%s user preflight scopes = %#v, want %#v", sc.Command, got, want)
-		}
-		declared := sc.DeclaredScopesForIdentity("user")
-		found := false
-		for _, got := range declared {
-			if got == "wiki:node:read" {
-				found = true
-			}
-		}
-		if !found {
-			t.Errorf("%s declared scopes %#v missing wiki:node:read", sc.Command, declared)
-		}
-	}
-}
-
-func TestUpdateSlideIsRegisteredWithAlias(t *testing.T) {
-	canonical := findSlidesShortcut(t, "+update-slide")
-	alias := findSlidesShortcut(t, "+update")
-
-	if canonical.Hidden {
-		t.Error("+update-slide must be visible in --help")
-	}
-	if !alias.Hidden {
-		t.Error("+update alias must stay hidden so only the canonical name is advertised")
-	}
-	if alias.Service != canonical.Service || alias.Risk != canonical.Risk ||
-		!reflect.DeepEqual(alias.AuthTypes, canonical.AuthTypes) ||
-		!reflect.DeepEqual(alias.Scopes, canonical.Scopes) ||
-		!reflect.DeepEqual(alias.ConditionalScopes, canonical.ConditionalScopes) ||
-		!reflect.DeepEqual(alias.Flags, canonical.Flags) ||
-		!reflect.DeepEqual(alias.Tips, canonical.Tips) ||
-		alias.Description != canonical.Description {
-		t.Error("alias metadata drifted from +update-slide; it must be derived, not re-declared")
-	}
-}
-
-// TestUpdateSlideSendsOnePartPerChangedElement is the core contract: only what
-// differs is touched, the part addresses the element by its own id, and the
-// replacement carries the caller's bytes rather than a re-serialized form.
-func TestUpdateSlideSendsOnePartPerChangedElement(t *testing.T) {
-	t.Parallel()
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, currentPageXML)
-	stub := registerWriteStub(t, reg, 8)
-
-	err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOneNew+elemTwo, noteKept))
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	parts := decodeUpdateSlideParts(t, stub.CapturedBody)
-	if len(parts) != 1 {
-		t.Fatalf("parts = %d, want 1 (only the restyled element differs): %#v", len(parts), parts)
-	}
-	if parts[0].Action != "block_replace" || parts[0].BlockID != "bbD" {
-		t.Errorf("part = %+v, want block_replace on bbD", parts[0])
-	}
-	if !strings.Contains(parts[0].Replacement, `fontFamily="楷体"`) {
-		t.Errorf("replacement lost the edit: %q", parts[0].Replacement)
-	}
-	if parts[0].Replacement != elemOneNew {
-		t.Errorf("replacement should be the caller's exact bytes:\n got %q\nwant %q", parts[0].Replacement, elemOneNew)
-	}
-
-	data := decodeShortcutData(t, stdout)
-	if data["parts_count"] != float64(1) || data["replaced"] != float64(1) ||
-		data["inserted"] != float64(0) || data["deleted"] != float64(0) {
-		t.Errorf("counters = %v", data)
-	}
-	if data["revision_id"] != float64(8) {
-		t.Errorf("revision_id = %v, want 8", data["revision_id"])
-	}
-}
-
-// TestUpdateSlideCanonicalComparison pins that the server's own formatting does
-// not read as a change. The caller here reorders attributes, collapses the
-// indentation and self-closes differently, but means the same page.
-func TestUpdateSlideCanonicalComparison(t *testing.T) {
-	t.Parallel()
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, currentPageXML)
-	forbidWrite(t, reg, "an unchanged page must not be written")
-
-	err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOne+elemTwo, noteKept))
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	data := decodeShortcutData(t, stdout)
-	if data["unchanged"] != true || data["parts_count"] != float64(0) {
-		t.Fatalf("an identical page should report unchanged, got %v", data)
-	}
-}
-
-func TestUpdateSlideDeletesDroppedElements(t *testing.T) {
-	t.Parallel()
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, currentPageXML)
-	stub := registerWriteStub(t, reg, 9)
-
-	// bbv is dropped from the target page.
-	err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOne, noteKept))
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	parts := decodeUpdateSlideParts(t, stub.CapturedBody)
-	if len(parts) != 1 {
-		t.Fatalf("parts = %#v, want a single delete", parts)
-	}
-	if parts[0].BlockID != "bbv" || parts[0].Replacement != "" {
-		t.Errorf("part = %+v, want an empty replacement on bbv (delete)", parts[0])
-	}
-	if data := decodeShortcutData(t, stdout); data["deleted"] != float64(1) {
-		t.Errorf("deleted = %v, want 1", data["deleted"])
-	}
-}
-
-func TestUpdateSlideInsertsNewElementsInPlace(t *testing.T) {
-	t.Parallel()
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, currentPageXML)
-	stub := registerWriteStub(t, reg, 10)
-
-	// A new element without an id, written between the two existing ones.
-	fresh := `<img src="tok" topLeftX="500" topLeftY="100" width="200" height="150"/>`
-	err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOne+fresh+elemTwo, noteKept))
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	parts := decodeUpdateSlideParts(t, stub.CapturedBody)
-	if len(parts) != 1 || parts[0].Action != "block_insert" {
-		t.Fatalf("parts = %#v, want a single block_insert", parts)
-	}
-	if parts[0].Insertion != fresh {
-		t.Errorf("insertion = %q, want the caller's bytes", parts[0].Insertion)
-	}
-	// Position is expressed by naming the element it precedes; without it the
-	// new element would land at the end of the page.
-	if parts[0].InsertBeforeBlockID != "bbv" {
-		t.Errorf("insert_before_block_id = %q, want bbv", parts[0].InsertBeforeBlockID)
-	}
-	if data := decodeShortcutData(t, stdout); data["inserted"] != float64(1) {
-		t.Errorf("inserted = %v, want 1", data["inserted"])
-	}
-}
-
-func TestUpdateSlideAppendsWhenNewElementIsLast(t *testing.T) {
-	t.Parallel()
-
-	f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, currentPageXML)
-	stub := registerWriteStub(t, reg, 11)
-
-	fresh := `<img src="tok" width="100" height="100"/>`
-	err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOne+elemTwo+fresh, noteKept))
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	parts := decodeUpdateSlideParts(t, stub.CapturedBody)
-	if len(parts) != 1 || parts[0].InsertBeforeBlockID != "" {
-		t.Fatalf("a trailing new element must be appended, got %#v", parts)
-	}
-}
-
-// TestUpdateSlideRejectsBackgroundChange is the honest-failure case. The
-// background has no addressable element id, so the only alternative to an error
-// is returning success with the background untouched.
-func TestUpdateSlideRejectsBackgroundChange(t *testing.T) {
-	t.Parallel()
-
-	for _, tt := range []struct {
-		name     string
-		style    string
-		wantWord string
-	}{
-		{
-			name:     "changed_fill",
-			style:    `<style><fill id="fiy"><fillColor color="rgba(255, 0, 0, 1)"/></fill></style>`,
-			wantWord: "background",
-		},
-		{
-			name:     "style_dropped",
-			style:    ``,
-			wantWord: "background",
-		},
-	} {
-		t.Run(tt.name, func(t *testing.T) {
-			f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-			registerPageRead(t, reg, currentPageXML)
-			forbidWrite(t, reg, "a background change must be rejected before any write")
-
-			err := runUpdateSlide(t, f, wantPage(tt.style, elemOne+elemTwo, noteKept))
-			if err == nil {
-				t.Fatal("expected a validation error")
-			}
-			var ve *errs.ValidationError
-			if !errors.As(err, &ve) {
-				t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-			}
-			if ve.Param != "--content" || !strings.Contains(ve.Message, tt.wantWord) {
-				t.Fatalf("error should name --content and mention the background, got %q (param %q)", ve.Message, ve.Param)
-			}
-		})
-	}
-}
-
-func TestUpdateSlideHandlesNote(t *testing.T) {
-	t.Parallel()
-
-	t.Run("replaced", func(t *testing.T) {
-		f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-		registerPageRead(t, reg, currentPageXML)
-		stub := registerWriteStub(t, reg, 12)
-
-		newNote := `<note id="bbb"><content><p>talk track</p></content></note>`
-		err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOne+elemTwo, newNote))
-		if err != nil {
-			t.Fatalf("unexpected error: %v", err)
-		}
-		parts := decodeUpdateSlideParts(t, stub.CapturedBody)
-		if len(parts) != 1 || parts[0].BlockID != "bbb" || parts[0].Replacement != newNote {
-			t.Fatalf("parts = %#v, want a block_replace on the note id", parts)
-		}
-		if data := decodeShortcutData(t, stdout); data["note_replaced"] != true {
-			t.Errorf("note_replaced = %v, want true", data["note_replaced"])
-		}
-	})
-
-	t.Run("cleared_when_omitted", func(t *testing.T) {
-		f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-		// A page whose note has content, so omitting <note> is a real change.
-		withNote := strings.Replace(currentPageXML, `<note id="bbb">
-    <content/>
-  </note>`, `<note id="bbb"><content><p>old note</p></content></note>`, 1)
-		registerPageRead(t, reg, withNote)
-		stub := registerWriteStub(t, reg, 13)
-
-		err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOne+elemTwo, ""))
-		if err != nil {
-			t.Fatalf("unexpected error: %v", err)
-		}
-		parts := decodeUpdateSlideParts(t, stub.CapturedBody)
-		if len(parts) != 1 || parts[0].BlockID != "bbb" {
-			t.Fatalf("parts = %#v, want the note cleared", parts)
-		}
-		if !strings.Contains(parts[0].Replacement, "<content/>") {
-			t.Errorf("replacement = %q, want an empty note", parts[0].Replacement)
-		}
-		if data := decodeShortcutData(t, stdout); data["note_cleared"] != true {
-			t.Errorf("note_cleared = %v, want true", data["note_cleared"])
-		}
-	})
-}
-
-// TestUpdateSlideRejectsUnexpressibleEdits covers the edits that element-level
-// parts cannot describe. Each one must fail before any write rather than land
-// partially.
-func TestUpdateSlideRejectsUnexpressibleEdits(t *testing.T) {
-	t.Parallel()
-
-	for _, tt := range []struct {
-		name     string
-		content  string
-		wantWord string
-	}{
-		{
-			name:     "reordered_elements",
-			content:  wantPage(currentStyleXML, elemTwo+elemOne, noteKept),
-			wantWord: "reorders",
-		},
-		{
-			name:     "unknown_element_id",
-			content:  wantPage(currentStyleXML, elemOne+elemTwo+`<shape id="bZZ" type="text"><content/></shape>`, noteKept),
-			wantWord: "does not exist",
-		},
-		{
-			name:     "duplicate_element_id",
-			content:  wantPage(currentStyleXML, elemOne+elemOne+elemTwo, noteKept),
-			wantWord: "twice",
-		},
-	} {
-		t.Run(tt.name, func(t *testing.T) {
-			f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-			registerPageRead(t, reg, currentPageXML)
-			forbidWrite(t, reg, "an unexpressible edit must be rejected before any write")
-
-			err := runUpdateSlide(t, f, tt.content)
-			if err == nil {
-				t.Fatal("expected a validation error")
-			}
-			p, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("expected a typed errs.* error, got %T: %v", err, err)
-			}
-			if !strings.Contains(p.Message, tt.wantWord) {
-				t.Fatalf("error message = %q, want it to mention %q", p.Message, tt.wantWord)
-			}
-		})
-	}
-}
-
-// TestUpdateSlideRejectsBadContentBeforeReading pins that malformed input fails
-// without spending an API call.
-func TestUpdateSlideRejectsBadContentBeforeReading(t *testing.T) {
-	t.Parallel()
-
-	for _, tt := range []struct {
-		name     string
-		content  string
-		wantWord string
-	}{
-		{name: "element_root", content: `<shape type="text"><content/></shape>`, wantWord: "+replace-slide"},
-		{name: "presentation_root", content: `<presentation><slide id="piy"><data/></slide></presentation>`, wantWord: "+replace-pages"},
-		{name: "second_page", content: `<slide id="p1"><data/></slide><slide id="p2"><data/></slide>`, wantWord: "one page per call"},
-		{name: "trailing_text", content: `<slide id="p1"><data/></slide>oops`, wantWord: "text after"},
-		{name: "not_xml", content: `not xml at all`, wantWord: "no root element"},
-		{name: "unclosed", content: `<slide id="p1"><data>`, wantWord: "well-formed"},
-		{name: "blank", content: `   `, wantWord: "cannot be empty"},
-		// Slide-level structure the diff cannot represent: accepting any of
-		// these would silently drop the edit — and could even answer
-		// `unchanged` for a change the caller asked for.
-		{name: "unknown_slide_child", content: `<slide id="piy"><data/><foo requestedChange="true"/></slide>`, wantWord: "unknown <foo>"},
-		{name: "duplicate_data", content: `<slide id="piy"><data/><data><shape type="text"><content/></shape></data></slide>`, wantWord: "second <data>"},
-		{name: "duplicate_style", content: `<slide id="piy"><style/><style/><data/></slide>`, wantWord: "second <style>"},
-		{name: "duplicate_note", content: `<slide id="piy"><data/><note><content/></note><note><content/></note></slide>`, wantWord: "second <note>"},
-		{name: "text_in_slide", content: `<slide id="piy"><data/>stray</slide>`, wantWord: "text directly inside <slide>"},
-		{name: "text_in_data", content: `<slide id="piy"><data><shape type="text"><content/></shape>stray</data></slide>`, wantWord: "text directly inside <data>"},
-		// XML fetched for page A posted against page B: the root id is the
-		// only reliable cross-check — element-id checks catch it merely
-		// incidentally, and an empty page would sail through them.
-		{name: "root_id_mismatch", content: `<slide id="pother"><data/></slide>`, wantWord: "read from a different page"},
-		// Container attributes have no element-level part to travel in, so
-		// accepting them means an edit that silently vanishes into unchanged.
-		{name: "root_attr", content: `<slide id="piy" requestedChange="true"><data/></slide>`, wantWord: `unsupported attribute "requestedChange" on <slide>`},
-		{name: "data_attr", content: `<slide id="piy"><data requestedChange="true"/></slide>`, wantWord: `unsupported attribute "requestedChange" on <data>`},
-		// Namespace declarations are not a loophole: an inherited binding
-		// changes what every descendant name means, and the canonicalizer
-		// compares local names, so a binding-only edit would vanish into
-		// unchanged. Only the official SML default namespace may appear, and
-		// only on the root.
-		{name: "wrong_default_xmlns", content: `<slide xmlns="urn:not-sml" id="piy"><data/></slide>`, wantWord: `unsupported xmlns "urn:not-sml"`},
-		{name: "prefixed_xmlns_on_slide", content: `<slide xmlns:x="urn:a" id="piy"><data/></slide>`, wantWord: `prefixed namespace declaration "xmlns:x"`},
-		{name: "xmlns_on_data", content: `<slide id="piy"><data xmlns="http://www.larkoffice.com/sml/2.0"/></slide>`, wantWord: `on <data>`},
-	} {
-		t.Run(tt.name, func(t *testing.T) {
-			f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-			reg.Register(&httpmock.Stub{
-				Method:   "GET",
-				URL:      "/slide",
-				Optional: true,
-				OnMatch:  func(*http.Request) { t.Error("malformed --content must fail before reading the page") },
-				Body:     map[string]interface{}{"code": 0, "data": map[string]interface{}{}},
-			})
-
-			err := runUpdateSlide(t, f, tt.content)
-			if err == nil {
-				t.Fatal("expected a validation error")
-			}
-			p, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("expected a typed errs.* error, got %T: %v", err, err)
-			}
-			if !strings.Contains(p.Message, tt.wantWord) {
-				t.Fatalf("error message = %q, want it to mention %q", p.Message, tt.wantWord)
-			}
-		})
-	}
-}
-
-// TestUpdateSlideRejectsUnsupportedCurrentPage covers the read side of the
-// structure guard: a page whose slide-level structure the diff cannot see
-// cannot be safely edited, because the comparison could neither preserve the
-// unrecognized part nor notice the caller changing it.
-func TestUpdateSlideRejectsUnsupportedCurrentPage(t *testing.T) {
-	t.Parallel()
-
-	f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, `<slide id="piy"><style/><data><shape id="bbD" type="text"><content/></shape></data><transition type="fade"/><note id="bbb"><content/></note></slide>`)
-	forbidWrite(t, reg, "a page the diff cannot represent must never be written")
-
-	err := runUpdateSlide(t, f, wantPage("<style/>", elemOne, noteKept))
-	if err == nil {
-		t.Fatal("expected an error for a page with unrepresentable structure")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("subtype = %q, want failed_precondition (the page state, not the flag, is the problem)", ve.Subtype)
-	}
-	if !strings.Contains(ve.Message, "<transition>") || !strings.Contains(ve.Message, "cannot represent") {
-		t.Errorf("message should name the structure: %q", ve.Message)
-	}
-}
-
-// TestUpdateSlideRootIDMayBeOmitted pins the other half of the root-id rule:
-// only a non-empty mismatching id is rejected; hand-written pages without one
-// apply normally.
-func TestUpdateSlideRootIDMayBeOmitted(t *testing.T) {
-	t.Parallel()
-
-	f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, currentPageXML)
-	stub := registerWriteStub(t, reg, 23)
-
-	err := runUpdateSlide(t, f, `<slide>`+currentStyleXML+`<data>`+elemOneNew+elemTwo+`</data>`+noteKept+`</slide>`)
-	if err != nil {
-		t.Fatalf("a missing root id must be allowed: %v", err)
-	}
-	if parts := decodeUpdateSlideParts(t, stub.CapturedBody); len(parts) != 1 || parts[0].BlockID != "bbD" {
-		t.Fatalf("parts = %#v, want the single font change", parts)
-	}
-}
-
-// TestUpdateSlideCanonicalAttrCollision is the regression for ambiguous
-// canonical encoding: with bare name=value concatenation these two elements
-// canonicalize identically, and the edit would be dropped as unchanged.
-func TestUpdateSlideCanonicalAttrCollision(t *testing.T) {
-	t.Parallel()
-
-	a, err := canonicalizeElement(`<img id="bbD" alt="foo rotateWithShape=true" src="x"/>`)
-	if err != nil {
-		t.Fatalf("canonicalize a: %v", err)
-	}
-	b, err := canonicalizeElement(`<img id="bbD" alt="foo" rotateWithShape="true" src="x"/>`)
-	if err != nil {
-		t.Fatalf("canonicalize b: %v", err)
-	}
-	if a == b {
-		t.Fatalf("distinct attribute sets must not canonicalize identically:\n%s", a)
-	}
-
-	// And through the whole command: the change must become a replacement part.
-	f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, `<slide id="piy"><style/><data><img id="bbD" alt="foo rotateWithShape=true" src="x"/></data><note id="bbb"><content/></note></slide>`)
-	stub := registerWriteStub(t, reg, 24)
-
-	err = runUpdateSlide(t, f, `<slide id="piy"><style/><data><img id="bbD" alt="foo" rotateWithShape="true" src="x"/></data><note id="bbb"><content/></note></slide>`)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	parts := decodeUpdateSlideParts(t, stub.CapturedBody)
-	if len(parts) != 1 || parts[0].BlockID != "bbD" {
-		t.Fatalf("the attribute change must produce a replacement, got %#v", parts)
-	}
-}
-
-// TestUpdateSlidePlaceholderRefusal pins the conservative contract for
-// <undefined> placeholders — the server's stand-ins for objects it cannot
-// export (a whiteboard read without its export option, video/audio embeds).
-// Whether the whole-page rewrite preserves an untouched one is a server-owned
-// behavior no self-contained test can pin down (boards cannot be created
-// programmatically), so pages carrying one are refused outright rather than
-// edited on an unverifiable assumption.
-func TestUpdateSlidePlaceholderRefusal(t *testing.T) {
-	t.Parallel()
-
-	currentWithBoard := `<slide id="piy"><style/><data>` + elemOne + `<undefined id="bbW" type="whiteboard"/></data><note id="bbb"><content/></note></slide>`
-
-	t.Run("page_with_placeholder_is_refused", func(t *testing.T) {
-		f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-		registerPageRead(t, reg, currentWithBoard)
-		forbidWrite(t, reg, "a page carrying a placeholder must never be written")
-
-		// Even an edit that does not touch the placeholder is refused: the
-		// rewrite behind the endpoint is whole-page, and preservation of the
-		// placeholder is exactly what cannot be proven.
-		err := runUpdateSlide(t, f, `<slide id="piy"><style/><data>`+elemOneNew+`<undefined id="bbW" type="whiteboard"/></data><note id="bbb"><content/></note></slide>`)
-		if err == nil {
-			t.Fatal("expected a refusal")
-		}
-		var ve *errs.ValidationError
-		if !errors.As(err, &ve) {
-			t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-		}
-		if ve.Subtype != errs.SubtypeFailedPrecondition {
-			t.Errorf("subtype = %q, want failed_precondition (the page state, not the flag, is the problem)", ve.Subtype)
-		}
-		if !strings.Contains(ve.Message, "<undefined>") || !strings.Contains(ve.Message, "bbW") || !strings.Contains(ve.Message, "+replace-slide") {
-			t.Errorf("message should name the placeholder and the escape hatch: %q", ve.Message)
-		}
-	})
-
-	t.Run("placeholder_in_content_is_refused", func(t *testing.T) {
-		f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-		registerPageRead(t, reg, currentPageXML) // a clean page
-		forbidWrite(t, reg, "hand-authored placeholders must be rejected before any write")
-
-		err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOne+`<undefined type="whiteboard"/>`, noteKept))
-		if err == nil {
-			t.Fatal("expected a validation error")
-		}
-		var ve *errs.ValidationError
-		if !errors.As(err, &ve) {
-			t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-		}
-		if ve.Param != "--content" || !strings.Contains(ve.Message, "<undefined>") {
-			t.Fatalf("error = %q (param %q)", ve.Message, ve.Param)
-		}
-	})
-}
-
-// TestUpdateSlideAcceptsSMLNamespaces pins that every namespace form the
-// repository's own SXSD validator accepts — the official identifier plus the
-// two server read-back spellings — round-trips on both sides of the diff. The
-// primary workflow copies `+xml-get` output back in, so rejecting a read-back
-// form would break the feature's core contract.
-func TestUpdateSlideAcceptsSMLNamespaces(t *testing.T) {
-	t.Parallel()
-
-	for _, ns := range []string{
-		"http://www.larkoffice.com/sml/2.0",
-		"https://www.larkoffice.com/sml/2.0",
-		"/sml/2.0",
-	} {
-		t.Run(ns, func(t *testing.T) {
-			f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-			// The server itself may return the namespace on the read side.
-			currentNS := `<slide xmlns="` + ns + `" id="piy">` + currentStyleXML + `<data>` + elemOne + elemTwo + `</data>` + noteKept + `</slide>`
-			registerPageRead(t, reg, currentNS)
-			stub := registerWriteStub(t, reg, 25)
-
-			err := runUpdateSlide(t, f, `<slide xmlns="`+ns+`" id="piy">`+currentStyleXML+`<data>`+elemOneNew+elemTwo+`</data>`+noteKept+`</slide>`)
-			if err != nil {
-				t.Fatalf("namespace %q must be accepted on both sides: %v", ns, err)
-			}
-			if parts := decodeUpdateSlideParts(t, stub.CapturedBody); len(parts) != 1 || parts[0].BlockID != "bbD" {
-				t.Fatalf("parts = %#v, want the single font change", parts)
-			}
-		})
-	}
-}
-
-// TestUpdateSlideDetectsTextEdits is the regression for lossy text
-// canonicalization. Both edits were previously reported as `unchanged`: the
-// whitespace-only node between inline runs was trimmed away (dropping a
-// preserved &#32; space, which decodes to the same token as a literal one),
-// and unescaped text let literal markup collide with real elements.
-func TestUpdateSlideDetectsTextEdits(t *testing.T) {
-	t.Parallel()
-
-	page := func(paragraph string) string {
-		return `<slide id="piy"><style/><data><shape id="bbD" type="text"><content>` + paragraph + `</content></shape></data><note id="bbb"><content/></note></slide>`
-	}
-	for _, tt := range []struct {
-		name    string
-		current string
-		wanted  string
-	}{
-		{
-			name:    "space_between_inline_runs",
-			current: page(`<p><strong>Hello</strong> <em>world</em></p>`),
-			wanted:  page(`<p><strong>Hello</strong><em>world</em></p>`),
-		},
-		{
-			name:    "escaped_literal_markup_vs_elements",
-			current: page(`<p>&lt;/p&gt;&lt;p&gt;</p>`),
-			wanted:  page(`<p></p><p></p>`),
-		},
-	} {
-		t.Run(tt.name, func(t *testing.T) {
-			// The pair must not canonicalize identically…
-			a, err := canonicalizeElement(tt.current)
-			if err != nil {
-				t.Fatalf("canonicalize current: %v", err)
-			}
-			b, err := canonicalizeElement(tt.wanted)
-			if err != nil {
-				t.Fatalf("canonicalize wanted: %v", err)
-			}
-			if a == b {
-				t.Fatalf("distinct content must not canonicalize identically:\n%s", a)
-			}
-
-			// …and the edit must become a replacement, never `unchanged`.
-			f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-			registerPageRead(t, reg, tt.current)
-			stub := registerWriteStub(t, reg, 26)
-
-			if err := runUpdateSlide(t, f, tt.wanted); err != nil {
-				t.Fatalf("unexpected error: %v", err)
-			}
-			parts := decodeUpdateSlideParts(t, stub.CapturedBody)
-			if len(parts) != 1 || parts[0].Action != "block_replace" || parts[0].BlockID != "bbD" {
-				t.Fatalf("the text edit must produce a replacement, got %#v", parts)
-			}
-			if data := decodeShortcutData(t, stdout); data["unchanged"] == true {
-				t.Fatal("a real text edit was reported as unchanged")
-			}
-		})
-	}
-}
-
-// TestUpdateSlideFailedReasonIsAFailure pins that a rejected batch is reported
-// as a command failure rather than as a field on a success envelope.
-func TestUpdateSlideFailedReasonIsAFailure(t *testing.T) {
-	t.Parallel()
-
-	f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, currentPageXML)
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/slide/replace",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{"failed_reason": "block with id 'bbD' not found"},
-		},
-	})
-
-	err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOneNew+elemTwo, noteKept))
-	if err == nil {
-		t.Fatal("a rejected batch must fail the command")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected a typed errs.* error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryAPI || !strings.Contains(p.Message, "not found") {
-		t.Fatalf("error = %+v, want an API error carrying the backend reason", p)
-	}
-}
-
-func TestUpdateSlideDryRunShowsBothCalls(t *testing.T) {
-	t.Parallel()
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	reg.Register(&httpmock.Stub{
-		Method:   "GET",
-		URL:      "/slide",
-		Optional: true,
-		OnMatch:  func(*http.Request) { t.Error("--dry-run must not call the API") },
-		Body:     map[string]interface{}{"code": 0, "data": map[string]interface{}{}},
-	})
-
-	err := runSlidesShortcut(t, f, stdout, SlidesUpdateSlide, []string{
-		"+update-slide",
-		"--presentation", "pres_abc",
-		"--slide-id", "piy",
-		"--content", wantPage(currentStyleXML, elemOne, noteKept),
-		"--dry-run",
-		"--as", "user",
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	out := stdout.String()
-	// Both halves must be visible: the parts cannot be, because they depend on
-	// the page's current state and dry-run must not fetch it.
-	if !strings.Contains(out, `"GET"`) || !strings.Contains(out, `"POST"`) {
-		t.Errorf("dry-run should show the read and the write: %s", out)
-	}
-	if !strings.Contains(out, "/slide/replace") {
-		t.Errorf("dry-run missing the write endpoint: %s", out)
-	}
-}
-
-func TestUpdateSlideForwardsRevisionAndTID(t *testing.T) {
-	t.Parallel()
-
-	f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	var readQuery, writeQuery string
-	reg.Register(&httpmock.Stub{
-		Method:  "GET",
-		URL:     "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
-		OnMatch: func(req *http.Request) { readQuery = req.URL.RawQuery },
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{"slide": map[string]interface{}{"content": currentPageXML}},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method:  "POST",
-		URL:     "/slide/replace",
-		OnMatch: func(req *http.Request) { writeQuery = req.URL.RawQuery },
-		Body:    map[string]interface{}{"code": 0, "data": map[string]interface{}{"revision_id": 20}},
-	})
-
-	err := runUpdateSlide(t, f, wantPage(currentStyleXML, elemOneNew+elemTwo, noteKept),
-		"--revision-id", "19", "--tid", "tid_9")
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	// The same revision is used for both calls so the parts apply to the
-	// snapshot they were computed from.
-	for name, query := range map[string]string{"read": readQuery, "write": writeQuery} {
-		if !strings.Contains(query, "revision_id=19") {
-			t.Errorf("%s query = %q, want revision_id=19", name, query)
-		}
-		if !strings.Contains(query, "tid=tid_9") {
-			t.Errorf("%s query = %q, want tid=tid_9", name, query)
-		}
-	}
-}
-
-func TestUpdateSlideAliasSharesBehavior(t *testing.T) {
-	t.Parallel()
-
-	f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, currentPageXML)
-	stub := registerWriteStub(t, reg, 21)
-
-	err := runSlidesShortcut(t, f, nil, SlidesUpdate, []string{
-		"+update",
-		"--presentation", "pres_abc",
-		"--slide-id", "piy",
-		"--content", wantPage(currentStyleXML, elemOneNew+elemTwo, noteKept),
-		"--as", "user",
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if parts := decodeUpdateSlideParts(t, stub.CapturedBody); len(parts) != 1 || parts[0].BlockID != "bbD" {
-		t.Fatalf("alias sent %#v, want the same single part", parts)
-	}
-}
-
-func TestUpdateSlideAcceptsContentFlagAlias(t *testing.T) {
-	t.Parallel()
-
-	sc := findSlidesShortcut(t, "+update-slide")
-	f, _, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	registerPageRead(t, reg, currentPageXML)
-	stub := registerWriteStub(t, reg, 22)
-
-	err := runSlidesShortcut(t, f, nil, sc, []string{
-		"+update-slide",
-		"--token", "pres_abc",
-		"--slide-id", "piy",
-		"--xml", wantPage(currentStyleXML, elemOneNew+elemTwo, noteKept),
-		"--as", "user",
-	})
-	if err != nil {
-		t.Fatalf("--token / --xml aliases should resolve: %v", err)
-	}
-	if parts := decodeUpdateSlideParts(t, stub.CapturedBody); len(parts) != 1 {
-		t.Fatalf("parts = %d, want 1", len(parts))
-	}
-}
-
-// findSlidesShortcut returns the registered shortcut for command, failing the
-// test when it is not wired into Shortcuts().
-func findSlidesShortcut(t *testing.T, command string) common.Shortcut {
-	t.Helper()
-	for _, sc := range Shortcuts() {
-		if sc.Command == command {
-			return sc
-		}
-	}
-	t.Fatalf("shortcut %s is not registered in Shortcuts()", command)
-	return common.Shortcut{}
-}
-
-type updateSlidePart struct {
-	Action              string `json:"action"`
-	BlockID             string `json:"block_id"`
-	Replacement         string `json:"replacement"`
-	Insertion           string `json:"insertion"`
-	InsertBeforeBlockID string `json:"insert_before_block_id"`
-}
-
-func decodeUpdateSlideParts(t *testing.T, raw []byte) []updateSlidePart {
-	t.Helper()
-	var body struct {
-		Parts []updateSlidePart `json:"parts"`
-	}
-	if err := json.Unmarshal(raw, &body); err != nil {
-		t.Fatalf("decode body: %v\nraw=%s", err, raw)
-	}
-	return body.Parts
-}

skills/lark-apps/SKILL.md

@@ -41,6 +41,7 @@ lark-cli auth login --domain apps
 | 看表 / 看结构 / 初始化多环境 / 导入导出数据 / 变更追溯 / 行级审计 / dev→online 发布 / 时间点恢复 / 查 DB 用量 | `+db-table-list`、`+db-table-get`、`+db-env-create`、`+db-data-export`/`+db-data-import`、`+db-changelog-list`、`+db-audit-status`/`+db-audit-enable`/`+db-audit-disable`/`+db-audit-list`、`+db-env-diff`/`+db-env-migrate`、`+db-recovery-diff`/`+db-recovery-apply`、`+db-quota-get` | [`lark-apps-db.md`](references/lark-apps-db.md) |
 | 逐条执行 SQL（SELECT / DML / DDL）；建表 / 改表 / 写 SQL 的平台规范 | `+db-execute` | [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)（含「平台 SQL 规范」：审计列 / RLS / `user_profile` / 禁用 SQL / PG 陷阱） |
 | 管理应用文件存储：上传/下载本地文件、列出/查看/删除已存文件、生成临时分享链接、查存储用量 | `+file-upload`/`+file-download`/`+file-list`/`+file-get`/`+file-sign`/`+file-delete`/`+file-quota-get` | [`lark-apps-file.md`](references/lark-apps-file.md) |
+| 调试应用运行时缓存：查看/删除单个业务 key、清空指定环境缓存 | `+cache-get`/`+cache-delete`/`+cache-clear` | [`lark-apps-cache.md`](references/lark-apps-cache.md) |
 | **部署/上线应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | 本地开发链路先按 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) 确认本次改动已 git commit + git push，再用 `+release-create` / `+release-get`；查历史用 `+release-list` | [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md), [`lark-apps-release-create.md`](references/lark-apps-release-create.md), [`lark-apps-release-get.md`](references/lark-apps-release-get.md), [`lark-apps-release-list.md`](references/lark-apps-release-list.md) |
 | 设置或查看运行时可见范围 | `+access-scope-set`, `+access-scope-get` | 对应 access-scope reference |
 | 创意模式（html）应用的评论相关操作 | 创意模式应用评论走 lark-drive 文档评论体系，读取 [`../lark-drive/SKILL.md`](../lark-drive/SKILL.md) 了解评论能力 | [`../lark-drive/SKILL.md`](../lark-drive/SKILL.md) |

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

@@ -0,0 +1,61 @@
+# apps cache 域命令（应用运行时缓存调试）
+
+调试妙搭应用的运行时缓存：查看某个缓存 key 的内容、删除单个 key、清空某个环境的全部缓存。缓存是应用为了加速而临时存放的数据，删除或清空后，应用下次用到时会自动重新取最新数据。命令事实以 `lark-cli apps +<cmd> --help` 为准；认证、`--as user`、exit 码、`_notice` 等通用处理见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 与本域 [`SKILL.md`](../SKILL.md)。
+
+## 何时用
+
+用户要排查「某个缓存 key 里存的是什么 / 有没有命中」、想删掉某个 key 让应用下次拿到最新数据、或想清空某个环境的缓存做快速恢复时。
+
+## 命令一览
+
+| 命令 | 做什么 | 关键参数 |
+|---|---|---|
+| `+cache-get` | 查一个缓存 key 的内容与信息 | `--key`、`--environment`、`--format` |
+| `+cache-delete` | 删一个缓存 key（重复删不会报错；不需 `--yes`） | `--key`、`--environment` |
+| `+cache-clear` | 清空指定环境下的全部缓存（**高危**） | `--environment`、`--yes` |
+
+> 所有命令都需 `--app-id`。
+
+## 约定（先读）
+
+- **环境 `--environment dev|online`（可省略）**：缓存按运行环境隔离。不指定时按应用当前的环境配置自动选择——有多环境的应用默认落到开发环境 `dev`，没有多环境的就是线上 `online`；返回结果里的 `environment` 会告诉你这次实际操作的是哪个环境。想固定就显式传。
+- **缓存 key 用 `--key` 传**：传业务里使用的那个 key；是否合法（非空、长度等）由服务端校验，不合法会返回错误。
+- **风险分级**：`+cache-clear` 会清掉整个环境的缓存，是高危操作，不带 `--yes` 会被确认关卡拦下；`+cache-delete` 只删单个 key、影响小，不需 `--yes`。
+- **`+cache-get` 的内容有两种展示**：`--format json`（默认）原样返回缓存内容，适合精确比对；`--format pretty` 会把内容格式化展开，更便于阅读。
+
+## 各命令
+
+### +cache-get
+按 `--key` 查单个缓存。命中时返回：是否存在、剩余有效期（TTL）、内容及其大小；未命中（或已过期）时只返回 `exists=false`、不带内容。
+
+> 每次查询都会连内容一起返回（没有「只看信息、不取内容」的模式），内容可能较大——只是想确认「在不在 / 还有多久过期」时，留意别占用太多上下文。
+
+```bash
+lark-cli apps +cache-get --app-id app_xxx --key spotbonus:2026:winners:list:v1
+lark-cli apps +cache-get --app-id app_xxx --environment online --key <key> --format pretty
+```
+
+### +cache-delete
+删一个缓存 key。**重复删、或删一个本就不存在的 key，都算成功**（返回删除数量 0）、不会报错；删中则返回删除数量 1。删掉后应用下次会自动重新取最新数据，影响小，故不需 `--yes`。
+
+```bash
+lark-cli apps +cache-delete --app-id app_xxx --environment dev --key <key>
+```
+
+### +cache-clear（高危）
+清空当前应用在**指定环境**下的全部缓存，用于定位不到具体 key 时的快速恢复。影响面是整个环境，必须带 `--yes`；返回本次清除的 key 数量。动手前可先 `--dry-run` 预览将要执行的操作。
+
+```bash
+lark-cli apps +cache-clear --app-id app_xxx --environment dev --yes
+```
+
+## 错误与边界
+
+- **key 不合法 / 缓存服务暂时不可用**：命令会返回带说明的错误，按 `error.hint` 转述给用户；「服务暂时不可用」这类可稍后重试。
+
+## Agent 规则
+
+- **写操作先定环境**：`+cache-clear` / `+cache-delete` 不指定 `--environment` 时会落到自动选中的环境——**没有多环境的应用会直接作用到线上 `online`（生产）**。不确定应用有没有多环境时，写操作显式传 `--environment`；纯查看（`+cache-get`）影响小，可以省略。
+- **`+cache-clear` 会清掉整个环境的缓存**：执行前先跟用户确认环境无误、说明会清掉该环境全部缓存。已明确授权可直接带 `--yes`；遇到确认关卡（`confirmation_required`，exit 10）按 lark-shared 约定与用户确认后再补 `--yes` 重试，不要静默追加。
+- **排查缓存内容优先用 `+cache-get`**：想看结构化、易读的内容用 `--format pretty`；想拿原始内容做精确比对用默认 JSON。
+- **删 key 前先对齐 key**：用户只描述了业务含义、没给准确 key 时，先确认再删——删错影响也有限（应用会自动重建），但仍应避免误删。

skills/lark-base/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-base
 version: 1.2.3
-description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限；遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入转 lark-drive，认证/授权转 lark-shared。"
+description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限；遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入/导出转 lark-drive，认证/授权转 lark-shared。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -23,14 +23,15 @@ metadata:
 不要使用本 skill：
 
 - 只是认证、初始化配置、切换身份、处理 scope 或权限授权恢复，转 `lark-shared`。
-- 把本地 Excel / CSV / `.base` 导入成 Base，转 `lark-drive +import --type bitable`。
+- 把本地文件导入成 Base，或将 Base 导出为本地文件，转 `lark-drive`。
 - 泛化数据分析、字段设计、公式讨论，但没有 Base/多维表格上下文。
 
 ## 使用边界
 
 - Base 业务操作只使用 `lark-cli base +...` shortcut，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`。
 - 执行 update 前必须先查当前 shortcut 的 `--help` 或对应 reference。若命令要求完整配置，首次请求必须基于可信的当前配置执行 read-modify-write：只修改用户明确指定的内容，保留其他仍适用的可写配置，并按命令要求的结构提交。若命令支持局部／delta update，按其契约提交最小合法 payload；不得以不完整请求试错补参。
-- 用户要把 Excel / CSV / `.base` 导入成 Base 时，先转 `lark-cli drive +import --type bitable`，导入完成后再回到 Base 命令。
+- 本地文件与 Base 之间的导入/导出转 `lark-drive`，具体格式、参数、路径限制和仅结构导出规则由 `lark-drive` 负责；导入完成后再回到 Base 命令。
+- 在线复制 Base 使用 `+base-copy`，不要绕行导出/导入。
 - 认证、初始化、scope、身份切换、权限不足恢复属于 `lark-shared`；Base 文档只保留会影响 Base 路径选择的权限规则。
 
 ## 先获取 Base Token 和所需 ID
@@ -49,6 +50,7 @@ metadata:
 |---|---|---|
 | 查 Base 本体 | `+base-get` | 用返回确认 Base 名称、owner、权限和可继续操作的 token |
 | 创建/复制 Base | `+base-create` / `+base-copy` | 新建时强烈推荐用 `--table-name` + `--fields` 同时配置新 Base 里唯一一个初始数据表的 name 和 schema；写入后报告新 Base 标识和 `permission_grant` |
+| Base 文件导入/导出 | 转 `lark-drive` | 文件格式、参数、路径限制和仅结构导出规则由 `lark-drive` 负责；在线复制走 `+base-copy` |
 | 查看 Base 内资源目录 | `+base-block-list` | 想先了解一个 Base 里有哪些 table/docx/dashboard/workflow/folder 时优先用它；返回 ID 关系和 fewshot 看 `--help` |
 | 管理 Base 内资源目录 | `+base-block-create/move/rename/delete` | 创建或整理 Base 直接管理的 folder/table/docx/dashboard/workflow；资源内容继续用对应命令 |
 | 管理数据表 | `+table-list/get/create/update/delete` | 处理 table 的列出、详情、创建、重命名和删除 |
@@ -63,8 +65,9 @@ metadata:
 | 公式字段 | `+field-create/update --json '{"type":"formula",...}'` | 必读 [formula-field-guide.md](references/formula-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
 | Lookup 字段 | `+field-create/update --json '{"type":"lookup",...}'` | 必读 [lookup-field-guide.md](references/lookup-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
 | 表单提交 | `+form-submit` | 先读 [lark-base-form-detail.md](references/lark-base-form-detail.md) 获取题目、filter 和附件所需 `base_token`；提交 JSON 读 [lark-base-form-submit.md](references/lark-base-form-submit.md) |
-| 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)；题目显隐条件 `visible_rule` 结构见公共协议 [lark-base-filter-condition.md](references/lark-base-filter-condition.md) |
-| 其他表单管理 | `+form-list/get/detail/create/update/delete` / `+form-questions-list/delete` | `+form-detail` 读 [lark-base-form-detail.md](references/lark-base-form-detail.md)；删除前确认目标表单 |
+| 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | Base 内表单按 table 管理；先确定并复用真实 `table_id`。读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)；题目显隐条件 `visible_rule` 结构见公共协议 [lark-base-filter-condition.md](references/lark-base-filter-condition.md) |
+| Base 内表单管理 | `+form-list/get/create/update/delete` / `+form-questions-list/delete` | 缺少或不确定归属时，先用 `+table-list` 或 `+base-block-list` 取得真实 `table_id`；这些命令使用 `--base-token + --table-id` 并在整个工作流中复用同一 `table_id`，删除前确认目标表单 |
+| 分享表单详情 | `+form-detail --share-token <share_token>` | 只接受表单分享链接里的 `share_token`，不要传 `--base-token` / `--form-id`；提交前读 [lark-base-form-detail.md](references/lark-base-form-detail.md) |
 | 仪表盘与组件 | `+dashboard-*` / `+dashboard-block-*` | 提到图表/看板/block 时先读 [lark-base-dashboard.md](references/lark-base-dashboard.md)；组件 `data_config` 读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)；读取图表计算结果用 `+dashboard-block-get-data` |
 | Workflow | `+workflow-*` | 创建/更新或理解 steps 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；list/get/enable/disable 只处理 workflow ID 与启停状态 |
 | 高级权限与角色 | `+advperm-*` / `+role-*` | 角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)；角色 create/update 或解读完整配置再读权限 JSON SSOT [role-config.md](references/role-config.md)；系统角色不可删除；关闭高级权限会影响自定义角色 |
@@ -116,6 +119,9 @@ metadata:
 
 ## 表单与视图细节
 
+- Base 内表单 list/get/create/update/delete 和题目管理都属于具体数据表：第一个管理命令前必须已有归属明确的真实 `table_id`；缺失或归属不明确时才用 `+table-list` 或 `+base-block-list` 定位，已有真实 ID 时直接复用。后续管理命令始终传同一 `base_token + table_id`。`+form-detail` 是分享表单入口，标识域不同，只使用 `share_token`。
+- 表单问题由数据表字段承载，question `id` 就是 `field_id`。创建问题前先 `+form-questions-list`；除非用户明确要求同名的独立问题，否则标题已存在时优先用 `+form-questions-update` 修改必填状态、标题或描述，不要先创建同名问题再删除旧问题。
+- `+form-questions-delete` 会删除承载问题的数据表字段。主字段问题不可删除；不要把主字段 ID 放入 `--question-ids`，需要修改时使用 `+form-questions-update`。
 - `+form-submit` 是高风险写操作，必须带 `--yes` 确认；调用前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
 - `+form-questions-update` 是题目配置全量覆盖，不是 patch；未传字段会回落默认值，传空字符串 / `null` / 空数组会直接写入空或清空。更新前先 `+form-questions-list` 读取当前题目，把要保留的 `title` / `description` / `required` / `option_display_mode` / `visible_rule` 等字段带回请求。
 - 表单附件不要写进 `fields`，放在 `--json.attachments`；提交附件时必须同时传表单所属 Base 的 `--base-token`。

skills/lark-base/references/lark-base-form-questions-create.md

@@ -137,9 +137,12 @@ lark-cli base +form-questions-create \
 > [!CAUTION]
 > 这是**写入操作** — 执行前必须向用户确认。
 
-1. 先用 `+form-questions-list` 查看现有问题
-2. 确认要添加的问题内容
-3. 执行命令并报告新建的问题 ID
+1. 先确定表单所属的真实 `table_id`，并在整个表单管理工作流中复用它；仅在 ID 缺失或归属不明确时调用 `+table-list`。
+2. 用 `+form-questions-list` 查看现有问题。问题 `id` 是承载该问题的 `field_id`，不是独立于数据表的临时 ID。
+3. 除非用户明确要求同名的独立问题，否则目标标题已经存在时用 `+form-questions-update` 更新必填状态、标题或描述；不要创建同名问题后再删除旧问题。
+4. 创建确实不存在的问题，或用户明确要求的同名独立问题，并报告新建的问题 ID。
+
+`+form-questions-delete` 会删除承载问题的数据表字段，不能删除主字段问题。不要通过“新建重复问题再删除旧问题”来替换主字段。
 
 ## 参考
 

skills/lark-base/references/lark-base-role-guide.md

@@ -6,6 +6,7 @@ This guide is the entry point for Base advanced permissions and roles. Use it to
 
 | Goal | Command | Notes |
 |------|---------|-------|
+| Check advanced permission status | `+base-get` | Read `data.base.is_advanced`. There is no `+advperm-get` command. |
 | Enable advanced permissions | `+advperm-enable` | Required before creating or updating roles. Caller must be a Base admin. |
 | Disable advanced permissions | `+advperm-disable` | High-risk write. Disabling invalidates existing custom roles. |
 | Locate roles | `+role-list` | Returns role summaries. Use `+role-get` for full config. |
@@ -14,6 +15,16 @@ This guide is the entry point for Base advanced permissions and roles. Use it to
 | Update a role | `+role-update` | Delta merge. Read current config first, then send only intended changes. |
 | Delete a role | `+role-delete` | Custom roles only. System roles cannot be deleted. |
 
+## Required order
+
+At the start of a role workflow, before the first `+role-list`, `+role-get`, `+role-create`, `+role-update`, or `+role-delete` call:
+
+1. Run `lark-cli base +base-get --base-token <base_token>` and inspect `data.base.is_advanced`.
+2. If `is_advanced` is `false`, run `+advperm-enable` before the role command. If the user did not authorize enabling advanced permissions, stop and explain the required precondition.
+3. Run the requested role commands only after `is_advanced` is `true` or `+advperm-enable` succeeds. Reuse that confirmed status for later role calls in the same workflow.
+
+Do not probe with `+advperm-get`: that command is not supported. Do not use an empty `+role-list` response to infer the advanced permission status; a disabled Base can also return an empty list.
+
 ## Safety boundaries
 
 - Role operations require advanced permissions to be enabled and the caller to be a Base admin.

skills/lark-base/references/role-config.md

@@ -154,12 +154,34 @@
   "table_rule_map": {
     "订单表": {
       "perm": "edit",
-      "view_rule": { "..." : "..." },
-      "record_rule": { "..." : "..." },
-      "field_rule": { "..." : "..." }
+      "view_rule": {
+        "allow_edit": true,
+        "visibility": { "all_visible": true }
+      },
+      "record_rule": {
+        "record_operations": ["add", "delete"],
+        "other_record_all_read": true
+      },
+      "field_rule": {
+        "field_perm_mode": "all_edit"
+      }
     },
     "用户表": {
-      "perm": "read_only"
+      "perm": "read_only",
+      "view_rule": {
+        "allow_edit": false,
+        "visibility": { "all_visible": true }
+      },
+      "record_rule": {
+        "record_operations": [],
+        "other_record_all_read": true
+      },
+      "field_rule": {
+        "field_perm_mode": "all_read"
+      }
+    },
+    "内部表": {
+      "perm": "no_perm"
     }
   }
 }
@@ -172,7 +194,11 @@
 | `record_rule` | RecordRule | 记录权限配置 |
 | `field_rule` | FieldRule | 字段权限配置 |
 
-**注意**: 当 `perm` 为 `no_perm` 时，`view_rule`、`record_rule`、`field_rule` 均无须再设置。
+**`+role-create` 硬约束**:
+
+- 当 `perm` 为 `no_perm` 时，不要设置 `view_rule`、`record_rule`、`field_rule`。
+- 当 `perm` 为其他值时，必须同时提供完整的 `view_rule`、`record_rule`、`field_rule`，缺少任意一项都会导致创建失败。
+- `+role-update` 是 delta merge，只提交要修改的字段；不要为局部更新补造未变更配置。
 
 ---
 

skills/lark-drive/SKILL.md

@@ -43,7 +43,7 @@ metadata:
 - 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
 - 用户要在云空间（云盘/云存储）里新建文件夹，优先使用 `lark-cli drive +create-folder`。
-- 用户要查看某个文件有哪些可下载预览格式，或想下载 PDF / HTML / 文本 / 图片等预览产物，使用 `lark-cli drive +preview`。
+- 用户要查看或下载文件内容，或者查看文件可用预览格式并获取 PDF / HTML / 文本 / 图片等转换预览产物，使用 `lark-cli drive +preview`。
 - 用户要获取某个文件的封面图，优先使用 `lark-cli drive +cover`；先 `--list-only` 看规格，再选 `--spec` 下载。
 - 用户要导出云文档时，优先使用 `lark-cli drive +export --url '<文档 URL>' --file-extension <格式>`；详细参数、Wiki token 和错误码处理见 [`references/lark-drive-export.md`](references/lark-drive-export.md)。
 - 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
@@ -121,7 +121,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+upload`](references/lark-drive-upload.md) | 上传本地文件到 Drive 文件夹或 wiki 节点；修改/重写/更新已有文件时优先覆盖上传，而不是直接上传一个新文件。 |
 | [`+create-folder`](references/lark-drive-create-folder.md) | 新建 Drive 文件夹，支持父文件夹与 bot 创建后自动授权。 |
 | [`+download`](references/lark-drive-download.md) | 下载 Drive 文件到本地。 |
-| [`+preview`](references/lark-drive-preview.md) | 查看或下载文件的 PDF / HTML / 文本 / 图片等预览产物。 |
+| [`+preview`](references/lark-drive-preview.md) | 查看或下载文件内容，或者查看文件可用预览格式并获取 PDF / HTML / 文本 / 图片等转换预览产物。 |
 | [`+cover`](references/lark-drive-cover.md) | 查看或下载文件封面图规格。 |
 | [`+status`](references/lark-drive-status.md) | 比较本地目录与 Drive 文件夹差异；默认按 SHA-256 精确比较，`--quick` 使用修改时间近似比较。 |
 | [`+pull`](references/lark-drive-pull.md) | 从 Drive 拉取文件到本地目录，支持重复远端路径处理和增量模式。 |

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

@@ -25,6 +25,10 @@ https://xxx.feishu.cn/drive/file/boxbc_xxx
                                   file_token
 ```
 
+## 排障
+
+- 如果返回 `HTTP 403`，可以使用 [lark-drive-preview](lark-drive-preview.md) 下载源文件产物。
+
 ## 参考
 
 - [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令

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

@@ -2,15 +2,24 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
 
-列出或下载 Drive 文件可用的预览产物。这个 shortcut 不猜测默认类型：
+查看或下载 Drive 文件内容，或列出并获取文件可用的预览产物。这个 shortcut 不猜测默认类型：
 
+- 如果只需要查看或下载文件内容，或不关心 PDF/text/image 等转换预览，优先使用 `--type source_file --output <path>`
 - 只想看候选项时，用 `--list-only`
+- 如果需要服务端生成的预览效果，例如 doc/docx 的 PDF 版式预览，先用 `--list-only` 查看候选项，再按候选项选择 `--type pdf` / `text` / `image` 等
 - 想下载时，必须显式传 `--type` 和 `--output`
+- 如果 `--list-only` 没有可用预览候选项，或错误提示明确建议使用 `--type source_file`，可以改用 `--type source_file --output <path>` 查看文件内容；资源不存在、token 无效等终态错误需要先修正输入
 - 如果某个候选项还在生成中，会返回结构化错误并提示先重新 `--list-only`
 
 ### 命令
 
 ```bash
+# 查看文件内容
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --type source_file \
+  --output ./artifacts/source
+
 # 列出可用预览候选项
 lark-cli drive +preview \
   --file-token "<FILE_TOKEN>" \
@@ -78,6 +87,7 @@ lark-cli drive +preview \
 
 - 不传 `--list-only` 时，必须显式传 `--type` 和 `--output`
 - 不会隐式选择“第一个候选项”作为默认下载目标
+- `--type source_file` 用于查看文件内容，不依赖 `--list-only` 返回的候选项；它适合读取或保存源内容，不等同于 PDF/text/image 等转换预览
 - 候选项状态来自后端 `preview_status` 枚举，例如 `READY` / `PROCESSING` / `FAILED` / `NO_SUPPORT`
 - 本地文件名在未显式带扩展名时，会结合响应头自动补扩展名
 

skills/lark-slides/SKILL.md

@@ -82,7 +82,6 @@ metadata:
 | 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`lark-slides-create.md`、`slides +create` |
 | 用户要求使用模板，或提供 PPTX 文件要求修改、美化 | 将模板导入为 Slides 再编辑 | `lark-slides-pptx-template-workflows.md` |
 | 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
-| 一页里大部分元素都要改（批量换字体 / 换配色 / 重排版式） | 先读回该页 XML，本地改完整交回去；CLI 做 diff 只发有差异的元素 | `slides +xml-get` → `slides +update-slide`、[`lark-slides-update-slide.md`](references/lark-slides-update-slide.md) |
 | 读取或分析已有 PPT | 解析 slides/wiki token，用 shortcut 回读全文 XML 或读取单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get`、`lark-slides-xml-presentations-get.md` |
 | 查看或回滚历史版本 | 先用 `+history-list` 找 `history_version_id`，再 `+history-revert`，必要时 `+history-revert-status` 轮询 | [`lark-slides-history.md`](references/lark-slides-history.md) |
 | 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面，一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` |
@@ -104,19 +103,13 @@ metadata:
 
 **CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。**
 
-**CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create --slides`、`xml_presentation.slide create`、`slides +replace-pages` 或 `slides +update-slide` 之前，MUST 先把待提交 XML 保存到本地文件并运行唯一版式准出入口 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)；`summary.error_count` 必须为 0 才能调用接口，`summary.warning_count > 0` 时必须先做对应页面的截图复核。改字体、字号、宽高同样会改变文本度量和换行，属于必须过闸的编辑。**
-
-**注意 `--revision-id` 不是乐观锁。** 实测传过期版本号服务端不会拒绝——它的含义是「在这个快照上应用改动」，钉住旧版本会丢弃该版本之后对这一页的所有编辑。**默认 `-1`（最新）就是推荐值。**
+**CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create --slides`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前，MUST 先把待提交 XML 保存到本地文件并运行唯一版式准出入口 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)；`summary.error_count` 必须为 0 才能调用接口，`summary.warning_count > 0` 时必须先做对应页面的截图复核。**
 
 **CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素，并使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py) 统一检查 XML、越界、重叠、空白页和内容稀疏风险。**
 
 **CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
 
-**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；一页里大部分元素都要改（批量换字体、换配色、重排版式）用 [`+update-slide`](references/lark-slides-update-slide.md)（交整页 XML，CLI diff 后只改有差异的元素；`slide_id` 和页序不变，但改不了背景）；已有 Slides 的多页大改优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内批量重建页面，避免 `slides +create` 生成新链接。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
-
-**CRITICAL — 用 `+update-slide` 时，MUST 以 `slides +xml-get --slide-id <sid>` 读回的 XML 为基准修改，不要凭记忆手写整页**：`--content` 是这一页的目标状态——带原 `id` 的元素被更新、**不带 `id` 的当新元素插入**、原有但没出现在 `--content` 里的元素**被删除**、`<note>` 没出现则**备注被清空**。页面上有 `<undefined>` 占位符（画板、未导出的音视频）时 **`+update-slide` 会整页拒绝**（无法证明重写会保留它），该页改用 `+replace-slide` 做元素级编辑。手写整页即使渲染一致，也会变成大规模删建。
-
-**CRITICAL — `+update-slide` 改不了页面背景，会直接报错而不是静默忽略。** 底层端点的 `block_id` 只收 `b` 开头的元素 id，而 `<style>` 没有自己的 id、`<fill>` 的 id 是 `f` 开头。把 `+xml-get` 读回的 `<style>` 原样保留即可；确实要改背景只能重建该页。同理**现有元素的顺序也不能调换**（没有 move 操作），会报错。整页更新还会**打散页面上所有组合且不可恢复**、把挂在非空 master / layout 的页面重新挂到空白 layout（与主题脱钩）——这些是端点行为，`+replace-slide` 同样触发，不是 `+update-slide` 独有。详见 [`lark-slides-update-slide.md`](references/lark-slides-update-slide.md)。
+**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；已有 Slides 的多页大改优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内批量重建页面，避免 `slides +create` 生成新链接。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
 
 **用户要求使用模板**：按 [lark-slides-pptx-template-workflows.md](references/lark-slides-pptx-template-workflows.md) 处理。
 
@@ -154,7 +147,7 @@ lark-cli auth login --domain slides
 
 - 创建：[`lark-slides-create.md`](references/lark-slides-create.md)、[`lark-slides-xml-presentation-slide-create.md`](references/lark-slides-xml-presentation-slide-create.md)（逐页添加）
 - 阅读：[`lark-slides-xml-presentations-get.md`](references/lark-slides-xml-presentations-get.md)
-- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-update-slide.md`](references/lark-slides-update-slide.md)（按整页 XML 更新一页）、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md)
+- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md)
 - 历史版本：[`lark-slides-history.md`](references/lark-slides-history.md)
 - 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)
 - 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
@@ -314,7 +307,6 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 | [`+screenshot`](references/lark-slides-screenshot.md) | 把幻灯片页面截图保存为本地图片，用 `--slide-number` 指定页号（从 1 开始，多页重复传入，一次最多 10 页），用 `--output-dir` 指定保存目录（必须是 CWD 内的相对路径，默认 `.lark-slides/screenshots`），失败时降级到 XML 回读等非截图检查 |
 | [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
 | [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
-| [`+update-slide`](references/lark-slides-update-slide.md) | 交一份完整 `<slide>` XML，CLI 读回当前页做 diff，只对有差异的元素发替换 / 新增 / 删除；`slide_id` 和页序不变。适合一页里多个元素都要改（批量换字体 / 配色 / 版式）。**改不了页面背景**，必须以 `+xml-get` 读回的 XML 为基准 |
 | [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面：先创建新页到旧页前，再删除旧页；适合已有 Slides 的多页大改，不新建链接 |
 
 没有 Shortcut 覆盖时使用原生 API。高频资源：`slides +xml-get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
@@ -334,7 +326,7 @@ lark-cli slides <resource> <method> [flags] # 调用 API
 4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
 5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
 6. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
-7. **编辑已有页面优先原链接更新**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；单页里多个元素都要改用 `+update-slide`（交整页 XML，CLI diff 后只改差异项，`slide_id` 不变，必须基于 `+xml-get` 读回的 XML，且改不了背景）；已有 Slides 的多页整页重建用 `+replace-pages`，不要用 `slides +create` 新建整份 PPT；只有没有 shortcut 覆盖的特殊操作才手动 `slide.create` + `slide.delete`
+7. **编辑已有页面优先原链接更新**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；已有 Slides 的多页整页重建用 `+replace-pages`，不要用 `slides +create` 新建整份 PPT；只有没有 shortcut 覆盖的特殊单页整页操作才手动 `slide.create` + `slide.delete`
 8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传，或在 `+create --slides` 的 XML 里写 `<img src="@./path">` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
 
 > **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。

skills/lark-slides/references/lark-slides-update-slide.md

@@ -1,177 +0,0 @@
-# slides +update-slide（按整页 XML 更新一页）
-
-交一份完整的 `<slide>` XML，CLI 读回这一页当前的样子、和你给的做 diff，然后**只对有差异的元素**发替换 / 新增 / 删除。`slide_id` 和页序不变。
-
-`slides +update` 是等价别名（不出现在 `--help` 里）。
-
-## 为什么是 diff 而不是整页覆盖
-
-底层端点 `xml_presentation.slide.replace` 的 part 里，`block_id` 被校验成**短元素 id（必须 `b` 开头）**。所以：
-
-- 页面自己的 id 是 `p` 开头 → **不能**用一个 part 覆盖整页
-- 背景 fill 的 id 是 `f` 开头 → **不能**改背景
-
-这两条都实测确认过（各自返回 3350001，而同一页上 `b` 开头的元素级 part 成功）。元素 id 是这个端点唯一的抓手，所以整页语义只能由 CLI 在客户端拆成元素级操作来表达。
-
-**这带来一个硬限制：背景改不了。** 见下方「改不了的东西」。
-
-## 什么时候用它，什么时候用 +replace-slide
-
-| 场景 | 用哪个 |
-|------|--------|
-| 改一个标题、换一张图、动一个形状 | [`+replace-slide`](lark-slides-replace-slide.md)，你已经知道要改哪个块，不需要 diff |
-| 一页里多个元素都要改（批量换字体 / 换配色 / 重排版式） | `+update-slide`，交整页 XML，不用逐块枚举 parts 和手写元素 XML |
-| 多页整页重建 | [`+replace-pages`](lark-slides-replace-pages.md) |
-| 新增一页 | `xml_presentation.slide create` |
-| 只改页面背景 | **本命令做不到**，见下 |
-
-## 命令
-
-```bash
-# 典型用法：读-改-写（--content 走文件，避免 shell 转义和长度问题）
-PID=slidesXXXXXXXXXXXXXXXXXXXXXX
-SID=piy
-
-# 1) 读回这一页
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" --slide-id "$SID" --output .lark-slides/page.xml
-
-# 2) 本地改（这里：把整页字体统一成思源黑体；-i.bak 写法 macOS / Linux 通用）
-sed -i.bak 's/fontFamily="[^"]*"/fontFamily="思源黑体"/g' .lark-slides/page.xml && rm .lark-slides/page.xml.bak
-
-# 3) 版式准出检查（改字体会改变文本度量，必须过这一关）
-python3 skills/lark-slides/scripts/xml_text_overlap_lint.py .lark-slides/page.xml
-
-# 4) 写回：CLI 自己再读一次做 diff，只发有差异的元素
-lark-cli slides +update-slide --as user \
-  --presentation "$PID" --slide-id "$SID" --content @.lark-slides/page.xml
-
-# stdin 也可以
-cat .lark-slides/page.xml | lark-cli slides +update-slide --as user \
-  --presentation "$PID" --slide-id "$SID" --content -
-
-# 预览（只显示会发哪两个请求；parts 取决于页面当前状态，dry-run 不读页面所以显示不了）
-lark-cli slides +update-slide --as user \
-  --presentation "$PID" --slide-id "$SID" --content @.lark-slides/page.xml --dry-run
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL（wiki 自动解析） |
-| `--slide-id` | 是 | 要更新的页面 ID |
-| `--content` | 是 | 整页 XML，**单个 `<slide>` 根元素**；支持 `@<file>` 和 `-`（stdin） |
-| `--revision-id` | 否 | 读取和应用所基于的版本；默认 `-1` = 最新。**不是乐观锁**，见下方「revision 不是乐观锁」 |
-| `--tid` | 否 | 并发事务 ID；多人协作长事务才用，单次单人调用留空 |
-
-`--content` 也接受 `--xml` / `--slide-xml` / `--slide-content` / `--content-xml`，`--presentation` 也接受 `--token` / `--url` 等；不出现在 `--help` 里但传了能识别。**`--slide` 不是别名**——太容易和 `--slide-id` 混淆，故意没收录。
-
-## 语义：`--content` 是这一页的目标状态
-
-| 你写的 | 结果 |
-|---|---|
-| 元素带原 `id`、内容有变 | 替换该元素（`replaced`）|
-| 元素带原 `id`、内容没变 | 不动它，不产生 part |
-| 元素**不带 `id`** | 当新元素插入到你写的位置（`inserted`）|
-| 原有元素**没出现**在 `--content` 里 | 删除（`deleted`）|
-| `<note>` 有变 | 替换备注（`note_replaced`）|
-| `<note>` 没出现 | **清空备注**（`note_cleared`）|
-| 完全没有差异 | 不发写请求，返回 `unchanged: true` |
-
-比较是**规范化**的：服务端返回的 XML 是 pretty-print、属性顺序被重排、还会注入你没写的样式默认值。CLI 比较时会把属性排序、忽略**结构元素之间**的排版空白，所以这些都不算变化——**原样读回、原样写回是幂等的**（已实测）。而发出去的替换内容是**你的原始字节**，你的格式和属性顺序会保留到页面里。
-
-注意 **`<p>` 段落内的文本按原样比较**（包括空白）：SML 里 `&#32;` 是"保留空格"，解码后和普通空格是同一个字符，宁可把一个语义等价的空白变化多发一次替换，也不能把真实的 `&#32;` 编辑误判成"没变化"。
-
-## 改不了的东西（会报错，不会静默）
-
-| 你想做的 | 结果 | 为什么 |
-|---|---|---|
-| 改页面背景 / `<style>` | **报错** | `<style>` 自身没有 id，`<fill>` 的 id 是 `f` 开头，端点只收 `b` 开头 |
-| 调换现有元素的顺序 | **报错** | 没有 move 操作，元素级 part 表达不出来 |
-| `--content` 里写一个页面上不存在的 `id` | **报错** | CLI 不会替你造 id；想新建就**别写 id** |
-| 同一个 `id` 出现两次 | **报错** | — |
-| 根元素不是 `<slide>` | **报错** | `--content` 描述整页，传元素级片段会被理解成"这一页只剩这个"，其余全删 |
-| 根元素 `id` 与 `--slide-id` 不一致 | **报错** | 大概率是拿错了页的 XML（读的 A 页、写的 B 页）。确实要跨页套用内容，就把根 `id` 去掉 |
-| `<slide>` 下出现 `style` / `data` / `note` 之外的子元素、或它们重复出现、或夹带文本 | **报错** | diff 表达不了这类结构；如果放过去，这部分改动会被静默丢弃，甚至误报 `unchanged` |
-| 给 `<slide>` 或 `<data>` 加属性 | **报错** | 容器属性没有可承载它的元素级 part。仅有的例外：`<slide>` 上可以带 SML namespace——接受与 `sxsd_validator.py` 相同的三种写法：`http://www.larkoffice.com/sml/2.0`、`https://www.larkoffice.com/sml/2.0`、`/sml/2.0`（或不带）；其它 xmlns、前缀 `xmlns:x`、`<data>` 上的任何属性都会被拒绝 |
-| 编辑**任何**含 `<undefined>` 占位符的页面 | **报错** | 占位符是服务端对"导不出来的对象"（画板、未导出的音视频）的替身。整页重写是否会保留一个没被触碰的占位符，是服务端行为，**没有可编程复现的端点测试能证明它**（画板无法程序化创建），所以本命令直接拒绝编辑这类页面，而不是在无法验证的假设上动手。该页要改，用 [`+replace-slide`](lark-slides-replace-slide.md) 做元素级编辑 |
-| 一次传多页 | **报错** | 一页一次调用 |
-
-背景确实要改的话，目前只能重建这一页（`slide create` + `slide delete`），或在客户端手动改。
-
-## revision 不是乐观锁
-
-**实测确认**：传一个已经过期的 `--revision-id` 服务端**不会拒绝**。它的含义是"在这个版本的快照上应用改动"，然后把结果提交为新版本——所以钉住旧版本会把**该版本之后对这一页的所有编辑全部丢弃**。
-
-所以：
-
-- **默认 `-1`（最新）就是推荐值**，别去钉住你读到的那个 revision。`-1` 下你的 parts 应用在最新快照上，你没碰的元素保持别人的最新状态。
-- 只有在明确想"回到某个快照 + 我的改动"时才传具体版本号，并且清楚这会丢掉之后的编辑。
-- 想避免和别人抢同一页，靠的是 `--tid` 事务或流程约定，不是 `--revision-id`。
-
-## 返回值
-
-```json
-{
-  "xml_presentation_id": "slidesXXXXXXXXXXXXXXXXXXXXXX",
-  "slide_id": "piy",
-  "parts_count": 3,
-  "replaced": 2,
-  "inserted": 1,
-  "deleted": 0,
-  "revision_id": 103
-}
-```
-
-| 字段 | 说明 |
-|------|------|
-| `parts_count` | 本次发出的元素级操作条数；`0` 表示没有差异 |
-| `replaced` / `inserted` / `deleted` | 分别替换、新增、删除了几个元素 |
-| `note_replaced` / `note_cleared` | 仅在备注被改 / 被清空时出现且为 `true` |
-| `unchanged` | 仅在完全没有差异时出现且为 `true`，此时没有发生写入 |
-| `revision_id` | 写入成功后的新版本号 |
-| `failed_reason` | 不会出现在成功返回里——批次被拒时整条命令失败 |
-
-单次最多 200 个 part（服务端上限）。差异超过 200 个元素会在本地报错，让你拆开调用。
-
-## 整页更新会连带影响的东西
-
-下面这些是**这个端点**的行为，不是本命令引入的——[`+replace-slide`](lark-slides-replace-slide.md) 改一个元素也一样会触发（两者最终都走同一个整页 rewrite）：
-
-| 影响 | 说明 |
-|---|---|
-| **组合被打散** | 页面上所有 group 会被解除组合，且无法恢复——`<group>` 在读写两侧都不可表达 |
-| **主题挂载被改** | 页面原本挂在非空 master / layout 上时，会被重新挂到空白 layout，从此与主题脱钩；占位符会被清理 |
-| **动画丢失** | 被删除或被重建的元素上的动画会一并删掉（保住 `id` 的元素不受影响）；`<smartLayout>` 每次都重建所以动画必丢。翻页转场不受影响 |
-| **静态图表换数据源** | 可编辑图表保留原有数据源；静态图表会拿到新 token，旧数据被弃用 |
-| **评论锚点** | `id` 匹配的元素上的评论保留；元素被删则锚点随之消失 |
-| **含 `<undefined>` 占位符的页面整页拒绝** | 画板、未导出的音视频读回来是 `<undefined>` 占位符；整页重写是否保留它无法用可复现的测试证明，所以本命令直接拒绝编辑这类页面（见上表）。[`+replace-slide`](lark-slides-replace-slide.md) 仍可对该页做元素级编辑 |
-
-最后两条再次指向同一条建议：**以 `+xml-get` 的输出为基准做最小改动**，别手写整页。
-
-## 常见错误
-
-| 现象 | 原因 | 对策 |
-|------|------|------|
-| `--content changes <style> (the page background)` | 改了背景 | 把 `+xml-get` 读回的 `<style>` 原样保留；确实要改背景只能重建该页 |
-| `--content reorders existing elements` | 调换了现有元素顺序 | 保持原顺序；要挪位置就删掉再以新元素插入 |
-| `element id "bZZ" ... does not exist` | 写了页面上不存在的 id | 想新建元素就**不要写 id**；或重新 `+xml-get` 确认 id |
-| `--content root element is <shape>` | 传了元素级片段 | 单个元素改动用 [`+replace-slide`](lark-slides-replace-slide.md)；整页更新要补全 `<slide>` 外层 |
-| `--content root carries id "pold" but --slide-id is "pnew"` | 拿 A 页的 XML 写 B 页 | 重新对目标页 `+xml-get`；确实要跨页套用就去掉根 `id` |
-| `--content contains an unknown <foo> element` / `a second <data>` | `<slide>` 下有 diff 表达不了的结构 | 一页只有一个 `<style>`、一个 `<data>`、一个 `<note>`；把多余结构去掉 |
-| `slide piy contains an <undefined> placeholder` | 这一页上有画板或未导出的媒体对象 | 本命令拒绝编辑该页；用 [`+replace-slide`](lark-slides-replace-slide.md) 做元素级编辑 |
-| `an unsupported xmlns "…" on <slide>` | xmlns 写错或用了前缀声明 | 根元素接受 `sxsd_validator.py` 认可的三种 SML namespace（可不带）；`<data>` 不收任何属性 |
-| `slide piy contains ... which this command cannot represent` | **当前页**（不是你的输入）带有本命令无法处理的结构 | 这一页改用 [`+replace-slide`](lark-slides-replace-slide.md) 做元素级编辑 |
-| `--content is not well-formed XML` | 括号没闭合、引号没配对、实体没转义 | 报错里带解析位置 |
-| 返回 `unchanged: true` 但你以为改了 | 你的改动被规范化比较判定为无差异（例如只动了缩进或属性顺序） | 检查是不是真的改了内容 |
-| 3350001 | 元素 XML 结构不合法，或嵌套 `<shape>` 缺 `<content/>` | 对照 [`xml-schema-quick-ref.md`](xml-schema-quick-ref.md)。注意 `+replace-slide` 会自动补 `<content/>`，本命令不会——元素 XML 原样发出 |
-| 大页面偶发失败，报错与排队 / 超时相关 | 服务端处理背压，不是尺寸超限 | 先重试；持续出现说明该页确实偏大，拆成几次 `+replace-slide` |
-| 403 | 权限不足 | 需要 `slides:presentation:update` 或 `write_only`，**以及 `slides:presentation:read`**（要先读页面）；wiki URL 还需要 `wiki:node:read` |
-
-## 相关命令
-
-- [+xml-get](lark-slides-xml-presentations-get.md) — 读回整页 XML，本命令的输入来源
-- [+replace-slide](lark-slides-replace-slide.md) — 元素级替换 / 插入，已知目标块时用它
-- [+replace-pages](lark-slides-replace-pages.md) — 多页整页重建
-- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环 + 决策树

tests/cli_e2e/base/base_form_detail_dryrun_test.go

@@ -55,3 +55,26 @@ func TestBaseFormDetailDryRun_MissingShareToken(t *testing.T) {
 	assert.NotEqual(t, 0, result.ExitCode)
 	assert.Contains(t, result.Stderr, "share-token")
 }
+
+func TestBaseFormListDryRun_UsesBaseAndTableIdentifiers(t *testing.T) {
+	setBaseDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"base", "+form-list",
+			"--base-token", "basXXXX",
+			"--table-id", "tblXXXX",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	output := strings.TrimSpace(result.Stdout)
+	assert.Contains(t, output, "/open-apis/base/v3/bases/basXXXX/tables/tblXXXX/forms")
+	assert.Contains(t, output, `"method": "GET"`)
+}

tests/cli_e2e/base/base_form_questions_create_dryrun_test.go

@@ -0,0 +1,108 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+func TestBaseFormQuestionsCreateDryRun(t *testing.T) {
+	setBaseDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"base", "+form-questions-create",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--form-id", "vew_x",
+			"--questions", `[{"type":"text","title":"Risk","required":true}]`,
+			"--dry-run",
+		},
+		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/forms/vew_x/questions", clie2e.DryRunGet(out, "api.0.url").String(), out)
+	require.Equal(t, "POST", clie2e.DryRunGet(out, "api.0.method").String(), out)
+	require.Equal(t, "text", clie2e.DryRunGet(out, "api.0.body.questions.0.type").String(), out)
+	require.Equal(t, "Risk", clie2e.DryRunGet(out, "api.0.body.questions.0.title").String(), out)
+	require.True(t, clie2e.DryRunGet(out, "api.0.body.questions.0.required").Bool(), out)
+}
+
+func TestBaseFormQuestionsCreateDryRunRejectsInvalidInput(t *testing.T) {
+	setBaseDryRunConfigEnv(t)
+
+	tests := []struct {
+		name    string
+		input   string
+		message string
+	}{
+		{name: "malformed JSON", input: "{", message: "must be a valid JSON array"},
+		{name: "non-array JSON", input: "{}", message: "must be a valid JSON array"},
+		{name: "null", input: "null", message: "must be a non-null JSON array"},
+		{name: "non-object item", input: "[1]", message: "item 1 must be an object"},
+		{name: "missing title", input: `[{"type":"text"}]`, message: `item 1 must include a non-empty string "title"`},
+		{name: "blank title", input: `[{"title":" ","type":"text"}]`, message: `item 1 must include a non-empty string "title"`},
+		{name: "missing type", input: `[{"title":"Risk"}]`, message: `item 1 must include a non-empty string "type"`},
+		{name: "non-string type", input: `[{"title":"Risk","type":1}]`, message: `item 1 must include a non-empty string "type"`},
+		{name: "more than ten items", input: `[{},{},{},{},{},{},{},{},{},{},{}]`, message: "must contain at most 10 items"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+			t.Cleanup(cancel)
+
+			result, err := clie2e.RunCmd(ctx, clie2e.Request{
+				Args: []string{
+					"base", "+form-questions-create",
+					"--base-token", "app_x",
+					"--table-id", "tbl_x",
+					"--form-id", "vew_x",
+					"--questions", tt.input,
+					"--dry-run",
+				},
+				DefaultAs: "bot",
+			})
+			require.NoError(t, err)
+			result.AssertExitCode(t, 2)
+
+			require.Equal(t, "validation", gjson.Get(result.Stderr, "error.type").String(), result.Stderr)
+			require.Equal(t, "invalid_argument", gjson.Get(result.Stderr, "error.subtype").String(), result.Stderr)
+			require.Equal(t, "--questions", gjson.Get(result.Stderr, "error.param").String(), result.Stderr)
+			require.Contains(t, gjson.Get(result.Stderr, "error.message").String(), tt.message)
+			require.Empty(t, result.Stdout)
+		})
+	}
+}
+
+func TestBaseFormQuestionsCreateHelpShowsExistingQuestionGuard(t *testing.T) {
+	setBaseDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args:      []string{"base", "+form-questions-create", "--help"},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	require.Contains(t, strings.ToLower(result.Stdout), "form may already contain questions")
+	require.Contains(t, result.Stdout, "+form-questions-list")
+	require.Contains(t, result.Stdout, "+form-questions-update")
+}

tests/cli_e2e/base/base_skill_contract_test.go

@@ -0,0 +1,30 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/larksuite/cli/internal/vfs"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBaseSkillRoutesFileImportExportToDrive(t *testing.T) {
+	_, currentFile, _, ok := runtime.Caller(0)
+	require.True(t, ok)
+
+	skillPath := filepath.Join(filepath.Dir(currentFile), "..", "..", "..", "skills", "lark-base", "SKILL.md")
+	content, err := vfs.ReadFile(skillPath)
+	require.NoError(t, err)
+
+	skill := string(content)
+	require.Contains(t, skill, "文件导入/导出转 lark-drive")
+	require.Contains(t, skill, "本地文件与 Base 之间的导入/导出转 `lark-drive`")
+	require.Contains(t, skill, "在线复制走 `+base-copy`")
+	require.NotContains(t, skill, "--only-schema")
+	require.NotContains(t, skill, "--output-dir")
+	require.NotContains(t, skill, "/tmp/")
+}

tests/cli_e2e/base/coverage.md

@@ -1,17 +1,21 @@
 # Base CLI E2E Coverage
 
 ## Metrics
-- Denominator: 78 leaf commands
-- Covered: 22
-- Coverage: 28.2%
+- Denominator: 87 leaf commands
+- Covered: 28
+- Coverage: 32.2%
 
 ## Summary
 - TestBase_BasicWorkflow: proves `+base-create`, `+base-get`, `+table-create`, `+table-get`, and `+table-list`; key `t.Run(...)` proof points are `get base as bot`, `get table as bot`, and `list tables and find created table as bot`.
 - TestBaseBlockDryRun: proves the five `+base-block-*` shortcuts request shapes without touching live data.
 - TestBaseFieldCreateDryRunArrayCompat: proves `+field-create` dry-run request shape for the internal JSON-array compatibility path.
+- TestBaseFormQuestionsCreateDryRun: proves `+form-questions-create` preserves its POST body and renders the existing-question guard in command help.
+- TestBaseFormDetailDryRun / TestBaseFormSubmitDryRun: prove shared-form detail and submission request shapes.
+- TestBaseDashboardBlockGetDataDryRun: proves dashboard block data request shapes and identifier handling.
 - TestBaseRecordBatchUpdatePerRecordDryRun: proves `+record-batch-update` preserves the per-record `update_records` request shape.
 - TestBaseRecordBatchUpdatePerRecordWorkflow: creates two records, updates different field types in one request, asserts the minimal response contract, reads both records back, verifies a missing record ID is not prevalidated, and cleans up the temporary Base.
 - TestBase_RoleWorkflow: proves `+advperm-enable`, `+role-create`, `+role-list`, `+role-get`, and `+role-update`; key `t.Run(...)` proof points are `list as bot`, `get as bot`, and `update as bot`.
+- TestBaseFormListDryRun_UsesBaseAndTableIdentifiers: proves `+form-list` dry-run request shape uses Base and table identifiers in the endpoint.
 - TestBaseFormQuestionsCreateVisibleRuleDryRun / TestBaseFormQuestionsUpdateVisibleRuleDryRun: prove `+form-questions-create` / `+form-questions-update` dry-run request shape and that the optional `visible_rule` display condition is transcribed verbatim into the request body.
 - Cleanup note: `+table-delete` and `+role-delete` only run in cleanup and are intentionally left uncovered.
 - Blocked area: dashboard, field, most record operations, form, view, and workflow operations still lack deterministic create/read/update workflows in this suite.
@@ -34,6 +38,7 @@
 | ✕ | base +dashboard-block-create | shortcut |  | none | dashboard workflows not covered |
 | ✕ | base +dashboard-block-delete | shortcut |  | none | dashboard workflows not covered |
 | ✕ | base +dashboard-block-get | shortcut |  | none | dashboard workflows not covered |
+| ✓ | base +dashboard-block-get-data | shortcut | base_dashboard_block_get_data_dryrun_test.go | `--base-token`; `--dashboard-id`; `--block-id`; dry-run only | request shape and identifier handling |
 | ✕ | base +dashboard-block-list | shortcut |  | none | dashboard workflows not covered |
 | ✕ | base +dashboard-block-update | shortcut |  | none | dashboard workflows not covered |
 | ✕ | base +dashboard-create | shortcut |  | none | dashboard workflows not covered |
@@ -50,12 +55,14 @@
 | ✕ | base +field-update | shortcut |  | none | field workflows not covered |
 | ✕ | base +form-create | shortcut |  | none | form workflows not covered |
 | ✕ | base +form-delete | shortcut |  | none | form workflows not covered |
+| ✓ | base +form-detail | shortcut | base_form_detail_dryrun_test.go::TestBaseFormDetailDryRun | `--share-token`; dry-run only | shared-form request shape |
 | ✕ | base +form-get | shortcut |  | none | form workflows not covered |
-| ✕ | base +form-list | shortcut |  | none | form workflows not covered |
-| ✓ | base +form-questions-create | shortcut | TestBaseFormQuestionsCreateVisibleRuleDryRun | questions[].visible_rule | dry-run: request shape + visible_rule body passthrough |
+| ✓ | base +form-list | shortcut | base_form_detail_dryrun_test.go::TestBaseFormListDryRun_UsesBaseAndTableIdentifiers | `--base-token`; `--table-id`; dry-run only | request shape only |
+| ✓ | base +form-questions-create | shortcut | TestBaseFormQuestionsCreateVisibleRuleDryRun; base_form_questions_create_dryrun_test.go | questions[].visible_rule; dry-run | request body, visible_rule passthrough, and help guard covered |
 | ✕ | base +form-questions-delete | shortcut |  | none | form workflows not covered |
 | ✕ | base +form-questions-list | shortcut |  | none | form workflows not covered |
 | ✓ | base +form-questions-update | shortcut | TestBaseFormQuestionsUpdateVisibleRuleDryRun | questions[].visible_rule | dry-run: request shape + visible_rule body passthrough |
+| ✓ | base +form-submit | shortcut | base_form_submit_dryrun_test.go::TestBaseFormSubmitDryRun | `--share-token`; `--json`; dry-run only | submission request shape |
 | ✕ | base +form-update | shortcut |  | none | form workflows not covered |
 | ✓ | base +record-batch-create | shortcut | base_record_batch_update_workflow_test.go::TestBaseRecordBatchUpdatePerRecordWorkflow | `--base-token`; `--table-id`; `--json.create_records` | seeds heterogeneous live workflow records |
 | ✓ | base +record-batch-update | shortcut | base_record_batch_update_dryrun_test.go::TestBaseRecordBatchUpdatePerRecordDryRun; base_record_batch_update_workflow_test.go::TestBaseRecordBatchUpdatePerRecordWorkflow | `--base-token`; `--table-id`; `--json.update_records`; dry-run + live | heterogeneous select/number update with write-back verification |
@@ -64,6 +71,7 @@
 | ✕ | 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-share-link-create | 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 |
@@ -78,6 +86,8 @@
 | ✓ | base +table-get | shortcut | base_basic_workflow_test.go::TestBase_BasicWorkflow/get table as bot | `--base-token`; `--table-id` | |
 | ✓ | base +table-list | shortcut | base_basic_workflow_test.go::TestBase_BasicWorkflow/list tables and find created table as bot | `--base-token` | |
 | ✕ | base +table-update | shortcut |  | none | no rename workflow yet |
+| ✕ | base +title-resolve | shortcut |  | none | resolver workflow not covered |
+| ✕ | base +url-resolve | shortcut |  | none | resolver workflow not covered |
 | ✕ | base +view-create | shortcut |  | none | view workflows not covered |
 | ✕ | base +view-delete | shortcut |  | none | view workflows not covered |
 | ✕ | base +view-get | shortcut |  | none | view workflows not covered |

tests/cli_e2e/drive/drive_preview_dryrun_test.go

@@ -93,6 +93,55 @@ func TestDrivePreviewDryRun_Download(t *testing.T) {
 	}
 }
 
+// TestDrivePreviewDryRun_SourceFile verifies source_file mode maps to a direct
+// source artifact download request.
+func TestDrivePreviewDryRun_SourceFile(t *testing.T) {
+	setDriveDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"drive", "+preview",
+			"--file-token", "fileDryRunPreview",
+			"--type", "source_file",
+			"--version", "12",
+			"--output", "./artifacts/source",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	if got := clie2e.DryRunGet(out, "api.#").Int(); got != 1 {
+		t.Fatalf("api count=%d, want 1\nstdout:\n%s", got, out)
+	}
+	if got := clie2e.DryRunGet(out, "api.0.method").String(); got != "GET" {
+		t.Fatalf("method=%q, want GET\nstdout:\n%s", got, out)
+	}
+	if got := clie2e.DryRunGet(out, "api.0.url").String(); got != "/open-apis/drive/v1/medias/fileDryRunPreview/preview_download" {
+		t.Fatalf("url=%q, want preview download endpoint\nstdout:\n%s", got, out)
+	}
+	if got := clie2e.DryRunGet(out, "api.0.params.preview_type").String(); got != "16" {
+		t.Fatalf("preview_type=%q, want 16\nstdout:\n%s", got, out)
+	}
+	if got := clie2e.DryRunGet(out, "api.0.params.version").String(); got != "12" {
+		t.Fatalf("version=%q, want 12\nstdout:\n%s", got, out)
+	}
+	if got := clie2e.DryRunGet(out, "requested_type").String(); got != "source_file" {
+		t.Fatalf("requested_type=%q, want source_file\nstdout:\n%s", got, out)
+	}
+	if got := clie2e.DryRunGet(out, "selected_type").String(); got != "source_file" {
+		t.Fatalf("selected_type=%q, want source_file\nstdout:\n%s", got, out)
+	}
+	if got := clie2e.DryRunGet(out, "selected_type_code").String(); got != "16" {
+		t.Fatalf("selected_type_code=%q, want 16\nstdout:\n%s", got, out)
+	}
+}
+
 // TestDriveCoverDryRun_Download verifies cover dry-run request structure for
 // download mode.
 func TestDriveCoverDryRun_Download(t *testing.T) {

tests/cli_e2e/drive/drive_preview_workflow_test.go

@@ -35,6 +35,41 @@ func TestDrive_PreviewAndCoverWorkflow(t *testing.T) {
 
 	fileToken := uploadPreviewFixture(t, parentT, ctx, workDir, folderToken, sourceRelPath, "report.txt")
 
+	t.Run("source file download", func(t *testing.T) {
+		downloadDir := t.TempDir()
+		downloadResult, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"drive", "+preview",
+				"--file-token", fileToken,
+				"--type", "source_file",
+				"--output", "./artifacts/report-source",
+			},
+			WorkDir:   downloadDir,
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		downloadResult.AssertExitCode(t, 0)
+		downloadResult.AssertStdoutStatus(t, true)
+
+		stdout := downloadResult.Stdout
+		if gjson.Get(stdout, "data.requested_type").Exists() {
+			t.Fatalf("requested_type should be omitted from execute output\nstdout:\n%s", stdout)
+		}
+		if got := gjson.Get(stdout, "data.selected_type").String(); got != "source_file" {
+			t.Fatalf("selected_type=%q, want source_file\nstdout:\n%s", got, stdout)
+		}
+		if gjson.Get(stdout, "data.selected_type_code").Exists() {
+			t.Fatalf("selected_type_code should be omitted from execute output\nstdout:\n%s", stdout)
+		}
+		outputPath := gjson.Get(stdout, "data.output_path").String()
+		require.NotEmpty(t, outputPath, "source file preview should return output_path")
+		data, readErr := os.ReadFile(outputPath)
+		require.NoError(t, readErr)
+		if string(data) != sourceContent {
+			t.Fatalf("source file preview content=%q want %q", string(data), sourceContent)
+		}
+	})
+
 	t.Run("preview list and download", func(t *testing.T) {
 		listResult, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
 			Args: []string{

tests/cli_e2e/markdown/markdown_dryrun_test.go

@@ -149,11 +149,14 @@ func TestMarkdownDiffDryRun_RemoteVsRemote(t *testing.T) {
 	result.AssertExitCode(t, 0)
 
 	output := strings.TrimSpace(result.Stdout)
-	assert.Contains(t, output, "/open-apis/drive/v1/files/boxcnMarkdownDryRun/download")
-	assert.Contains(t, output, `"mode": "remote_vs_remote"`)
-	assert.Contains(t, output, `"version": "7633658129540910621"`)
-	assert.Contains(t, output, `"version": "7633658129540910628"`)
-	assert.Contains(t, output, `"context_lines": 1`)
+	assert.Contains(t, output, "/open-apis/drive/v1/medias/boxcnMarkdownDryRun/preview_download")
+	require.Equal(t, "remote_vs_remote", clie2e.DryRunGet(output, "mode").String(), output)
+	require.Equal(t, int64(2), clie2e.DryRunGet(output, "api.#").Int(), output)
+	require.Equal(t, "16", clie2e.DryRunGet(output, "api.0.params.preview_type").String(), output)
+	require.Equal(t, "7633658129540910621", clie2e.DryRunGet(output, "api.0.params.version").String(), output)
+	require.Equal(t, "16", clie2e.DryRunGet(output, "api.1.params.preview_type").String(), output)
+	require.Equal(t, "7633658129540910628", clie2e.DryRunGet(output, "api.1.params.version").String(), output)
+	require.Equal(t, int64(1), clie2e.DryRunGet(output, "context_lines").Int(), output)
 }
 
 func TestMarkdownDiffDryRun_RemoteVsLocal(t *testing.T) {
@@ -179,8 +182,9 @@ func TestMarkdownDiffDryRun_RemoteVsLocal(t *testing.T) {
 	result.AssertExitCode(t, 0)
 
 	output := strings.TrimSpace(result.Stdout)
-	assert.Contains(t, output, "/open-apis/drive/v1/files/boxcnMarkdownDryRun/download")
+	assert.Contains(t, output, "/open-apis/drive/v1/medias/boxcnMarkdownDryRun/preview_download")
 	assert.Contains(t, output, `"mode": "remote_vs_local"`)
+	assert.Contains(t, output, `"preview_type": "16"`)
 	assert.Contains(t, output, `"local_file": "./draft.md"`)
 }
 
@@ -224,7 +228,8 @@ func TestMarkdownFetchDryRun_OutputFile(t *testing.T) {
 	result.AssertExitCode(t, 0)
 
 	output := strings.TrimSpace(result.Stdout)
-	assert.Contains(t, output, "/open-apis/drive/v1/files/boxcnMarkdownDryRun/download")
+	assert.Contains(t, output, "/open-apis/drive/v1/medias/boxcnMarkdownDryRun/preview_download")
+	assert.Contains(t, output, `"preview_type": "16"`)
 	assert.Contains(t, output, `"output": "./copy.md"`)
 }
 
@@ -305,7 +310,8 @@ func TestMarkdownPatchDryRun_Content(t *testing.T) {
 	result.AssertExitCode(t, 0)
 
 	output := strings.TrimSpace(result.Stdout)
-	assert.Contains(t, output, "/open-apis/drive/v1/files/boxcnMarkdownDryRun/download")
+	assert.Contains(t, output, "/open-apis/drive/v1/medias/boxcnMarkdownDryRun/preview_download")
+	assert.Contains(t, output, `"preview_type": "16"`)
 	assert.Contains(t, output, "/open-apis/drive/v1/metas/batch_query")
 	assert.Contains(t, output, "/open-apis/drive/v1/files/upload_all")
 	assert.Contains(t, output, "/open-apis/drive/v1/files/upload_prepare")

tests/cli_e2e/slides/coverage.md

@@ -1,16 +1,12 @@
 # Slides CLI E2E Coverage
 
 ## Metrics
-- Denominator: 3 leaf commands
-- Covered: 2
-- Coverage: 66.7%
+- Denominator: 2 leaf commands
+- Covered: 1
+- Coverage: 50.0%
 
 ## Summary
 - TestSlides_CreateWorkflowAsUser: proves the user slides workflow through `create presentation with slide as user` and `get created presentation xml as user`; creates a fresh presentation, asserts returned IDs, then reads back the XML content to prove the title and slide body persisted.
-- TestSlides_UpdateSlideWorkflowAsUser: proves `+update-slide` end to end on a two-page deck — restyle an element (one replace part), rewrite the same page (no-op, no request), add an element without an id (insert), drop an element (delete), and confirm a background change is refused with the page left untouched; then checks the control page and the deck order did not move. **This test is why the command works**: the first version of the command sent a single part covering the whole page, which HTTP stubs accepted and the real API rejects outright — `ReplacePart.block_id` is validated as a short ELEMENT id, so neither the page id (`p`-prefixed) nor the background fill id (`f`-prefixed) can be addressed. Stubs prove the request shape; only a live round trip proves the request is legal.
-- TestSlidesUpdateSlideDryRunE2E / TestSlidesUpdateAliasDryRunE2E / TestSlidesUpdateSlideRejectsElementRootDryRunE2E: dry-run coverage for the read-then-write orchestration, the shared revision and slide_id on both calls, the hidden `slides +update` alias with the hidden `--token` / `--xml` spellings, and the refusal of a non-`<slide>` root before any request is built.
-- **Known gap**: the live workflow test skips without a user token, so a CI run configured only with bot credentials leaves the load-bearing backend behavior unverified — exactly the blind spot that let the original design reach review. A CI user token, or a bot-identity variant of this workflow, would close it.
-- Cleanup deletes the deck through `drive +delete`, which needs `space:document:delete` and `drive:drive.metadata:readonly`. For **stored credentials** the workflow probes that capability up front with a `--dry-run` delete (whose scope pre-flight reads the stored grants) and skips before creating anything when they are missing; an unexpected probe failure is fatal. For **environment tokens** (`TEST_USER_ACCESS_TOKEN`) no scope metadata exists and no API exposes a token's grants without exercising them, so the probe proves nothing there — the CI identity must be provisioned with the cleanup scopes, and a cleanup failure stays fatal and visible. A fully-scoped run creates, edits and deletes its own deck (verified green end to end).
 - Blocked area: `slides +media-upload` is still uncovered because it needs a deterministic local image fixture plus XML follow-up proof that is separate from the base create/read workflow.
 
 ## Command Table
@@ -18,5 +14,4 @@
 | Status | Cmd | Type | Testcase | Key parameter shapes | Notes / uncovered reason |
 | --- | --- | --- | --- | --- | --- |
 | ✓ | slides +create | shortcut | slides_create_workflow_test.go::TestSlides_CreateWorkflowAsUser/create presentation with slide as user | `--title`; `--slides ["<slide ...>"]` | read back through raw slides API to prove persisted XML |
-| ✓ | slides +update-slide | shortcut | slides_update_slide_workflow_test.go::TestSlides_UpdateSlideWorkflowAsUser | `--presentation`; `--slide-id`; `--content "<slide ...>"`; `--revision-id` | live run needs a user token carrying `slides:presentation:create` / `read` / `update` / `write_only`, plus `space:document:delete` for cleanup; the dry-run half needs no secrets |
 | ✕ | slides +media-upload | shortcut |  | none | needs a stable local image fixture plus follow-up slide XML proof |

tests/cli_e2e/slides/slides_update_slide_dryrun_test.go

@@ -1,175 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package slides
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	"github.com/stretchr/testify/require"
-	"github.com/tidwall/gjson"
-)
-
-const updateSlideDryRunPageXML = `<slide id="piy"><style><fill id="fiy"><fillColor color="rgba(255, 255, 255, 1)"/></fill></style><data><shape id="bRU" type="text" topLeftX="46" topLeftY="34" width="400" height="36"><content textType="headline" fontSize="28"><p>Overview</p></content></shape></data><note id="bno"><content/></note></slide>`
-
-// TestSlidesUpdateSlideDryRunE2E pins the shape of the orchestration through the
-// built CLI: the command reads the page before writing it, because the parts it
-// sends are derived from the page's current state rather than from --content
-// alone. Dry-run deliberately cannot show the parts — computing them would
-// require the read it is not allowed to perform.
-func TestSlidesUpdateSlideDryRunE2E(t *testing.T) {
-	setSlidesDryRunEnv(t)
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"slides", "+update-slide",
-			"--presentation", "presUpdateSlideDryRun",
-			"--slide-id", "piy",
-			"--content", updateSlideDryRunPageXML,
-			"--revision-id", "17",
-			"--dry-run",
-		},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-
-	api := gjson.Get(result.Stdout, "data.api").Array()
-	require.Len(t, api, 2, "the command reads then writes\n%s", result.Stdout)
-
-	require.Equal(t, "GET", api[0].Get("method").String(), result.Stdout)
-	require.Equal(t,
-		"/open-apis/slides_ai/v1/xml_presentations/presUpdateSlideDryRun/slide",
-		api[0].Get("url").String(), result.Stdout,
-	)
-	require.Equal(t, "POST", api[1].Get("method").String(), result.Stdout)
-	require.Equal(t,
-		"/open-apis/slides_ai/v1/xml_presentations/presUpdateSlideDryRun/slide/replace",
-		api[1].Get("url").String(), result.Stdout,
-	)
-
-	// The same revision is used for both calls so the parts apply to the
-	// snapshot they were diffed against.
-	for i := range api {
-		require.Equal(t, "piy", api[i].Get("params.slide_id").String(), result.Stdout)
-		require.Equal(t, int64(17), api[i].Get("params.revision_id").Int(), result.Stdout)
-		require.False(t, api[i].Get("params.tid").Exists(), "tid must be omitted when empty\n%s", result.Stdout)
-	}
-
-	require.Equal(t, int64(1), gjson.Get(result.Stdout, "data.wanted_element_count").Int(), result.Stdout)
-}
-
-// TestSlidesUpdateAliasDryRunE2E proves the hidden `+update` spelling reaches
-// the same logic through the real CLI, along with the hidden --token / --xml
-// flag spellings.
-func TestSlidesUpdateAliasDryRunE2E(t *testing.T) {
-	setSlidesDryRunEnv(t)
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"slides", "+update",
-			"--token", "presUpdateSlideDryRun",
-			"--slide-id", "piy",
-			"--xml", updateSlideDryRunPageXML,
-			"--dry-run",
-		},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-
-	require.Equal(t,
-		"/open-apis/slides_ai/v1/xml_presentations/presUpdateSlideDryRun/slide/replace",
-		gjson.Get(result.Stdout, "data.api.1.url").String(),
-		result.Stdout,
-	)
-	require.Equal(t, int64(-1), gjson.Get(result.Stdout, "data.api.1.params.revision_id").Int(),
-		"-1 is the default: apply against the latest revision\n%s", result.Stdout)
-}
-
-// TestSlidesUpdateSlideRejectsBadContentDryRunE2E is the guardrail check
-// through the built CLI: inputs whose failure mode is data loss must be
-// refused before any request is built, with the full typed error contract —
-// agents branch on type/subtype/param, not on prose.
-func TestSlidesUpdateSlideRejectsBadContentDryRunE2E(t *testing.T) {
-	setSlidesDryRunEnv(t)
-
-	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
-	t.Cleanup(cancel)
-
-	for _, tt := range []struct {
-		name        string
-		content     string
-		wantMessage string
-	}{
-		{
-			// An element-level fragment would mean "the page should contain
-			// only this" and delete everything else.
-			name:        "element_root",
-			content:     `<shape type="text"><content><p>oops</p></content></shape>`,
-			wantMessage: "+replace-slide",
-		},
-		{
-			// XML fetched for page A posted against page B.
-			name:        "root_id_mismatch",
-			content:     `<slide id="pother"><data/></slide>`,
-			wantMessage: "read from a different page",
-		},
-		{
-			// Slide-level structure the diff cannot represent would be
-			// silently dropped — possibly reported as `unchanged`.
-			name:        "unknown_slide_child",
-			content:     `<slide id="piy"><data/><foo requestedChange="true"/></slide>`,
-			wantMessage: "unknown <foo>",
-		},
-		{
-			// Container attributes have no element-level part to travel in.
-			name:        "root_attribute",
-			content:     `<slide id="piy" requestedChange="true"><data/></slide>`,
-			wantMessage: "unsupported attribute",
-		},
-		{
-			// A namespace binding inherited from the root changes what every
-			// descendant name means; only the official SML declaration passes.
-			name:        "wrong_default_xmlns",
-			content:     `<slide xmlns="urn:not-sml" id="piy"><data/></slide>`,
-			wantMessage: "unsupported xmlns",
-		},
-	} {
-		t.Run(tt.name, func(t *testing.T) {
-			result, err := clie2e.RunCmd(ctx, clie2e.Request{
-				Args: []string{
-					"slides", "+update-slide",
-					"--presentation", "presUpdateSlideDryRun",
-					"--slide-id", "piy",
-					"--content", tt.content,
-					"--dry-run",
-				},
-				DefaultAs: "bot",
-			})
-			// RunCmd errors only when the CLI could not be launched; a normal
-			// non-zero exit lands in result.ExitCode. Discarding this error
-			// would turn a broken harness into a nil-pointer panic.
-			require.NoError(t, err, "the CLI must launch")
-			// Validation errors have a fixed process contract: exit code 2,
-			// nothing on stdout, the typed envelope on stderr.
-			require.Equal(t, 2, result.ExitCode,
-				"stdout:\n%s\nstderr:\n%s", result.Stdout, result.Stderr)
-			require.Empty(t, result.Stdout, "a refused command must not emit a result")
-
-			require.Equal(t, "validation", gjson.Get(result.Stderr, "error.type").String(), result.Stderr)
-			require.Equal(t, "invalid_argument", gjson.Get(result.Stderr, "error.subtype").String(), result.Stderr)
-			require.Equal(t, "--content", gjson.Get(result.Stderr, "error.param").String(), result.Stderr)
-			require.Contains(t, gjson.Get(result.Stderr, "error.message").String(), tt.wantMessage, result.Stderr)
-		})
-	}
-}

tests/cli_e2e/slides/slides_update_slide_workflow_test.go

@@ -1,262 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package slides
-
-import (
-	"context"
-	"os"
-	"regexp"
-	"strings"
-	"testing"
-	"time"
-
-	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	"github.com/stretchr/testify/require"
-	"github.com/tidwall/gjson"
-)
-
-// skipWithoutCleanupScopes refuses to create a deck this run cannot delete,
-// when that is knowable. AGENTS.md wants live workflows self-contained
-// (create → use → cleanup); a cleanup that fails on missing scopes both fails
-// the package after the workflow already passed and leaks one presentation per
-// run. The capability is probed up front with --dry-run, which runs the same
-// scope pre-flight as the real cleanup without touching anything remote.
-//
-// The probe is authoritative only for stored credentials, whose scope grants
-// the pre-flight can read. A token injected through the environment
-// (TEST_USER_ACCESS_TOKEN / LARKSUITE_CLI_USER_ACCESS_TOKEN) carries no scope
-// metadata, and the pre-flight deliberately skips when scopes are unknown —
-// exit 0 from the probe proves nothing there. No API exposes a token's grants
-// without exercising them, so for that path the run proceeds on the documented
-// requirement that the CI identity is provisioned with the cleanup scopes
-// (coverage.md), and a cleanup failure stays fatal and visible.
-func skipWithoutCleanupScopes(ctx context.Context, t *testing.T) {
-	t.Helper()
-	if os.Getenv("TEST_USER_ACCESS_TOKEN") != "" || os.Getenv("LARKSUITE_CLI_USER_ACCESS_TOKEN") != "" {
-		t.Log("cleanup-scope probe skipped: environment tokens carry no scope metadata, so a dry-run pre-flight cannot prove anything; the CI identity must be provisioned with space:document:delete and drive:drive.metadata:readonly (see coverage.md)")
-		return
-	}
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args:      []string{"drive", "+delete", "--file-token", "cleanup_scope_probe", "--type", "slides", "--yes", "--dry-run"},
-		DefaultAs: "user",
-	})
-	require.NoError(t, err, "the CLI must launch for the scope probe")
-	switch {
-	case result.ExitCode == 0:
-		// Stored credential with the scopes present.
-	case strings.Contains(result.Stderr, "missing_scope"):
-		t.Skipf("user token lacks the cleanup scopes (space:document:delete, drive:drive.metadata:readonly); refusing to create a deck the run cannot delete\nstderr:\n%s", result.Stderr)
-	default:
-		// Anything else is a broken probe, not a known-good capability;
-		// proceeding would risk creating a deck under unknown conditions.
-		t.Fatalf("cleanup-scope probe failed unexpectedly (exit %d)\nstdout:\n%s\nstderr:\n%s", result.ExitCode, result.Stdout, result.Stderr)
-	}
-}
-
-// TestSlides_UpdateSlideWorkflowAsUser is the only test that can prove this
-// command works, and it exists because an earlier version of it did not: the
-// whole design once rested on sending a single part covering the page, which
-// unit stubs happily accepted and the real API rejects outright (block_id is
-// validated as a short ELEMENT id, so a page id cannot be addressed). Stubs
-// prove the request shape; only a live round trip proves the request is legal
-// and does what it claims.
-//
-// It walks every operation the diff can emit — replace, insert, delete, and the
-// no-op — then checks the two things element-level parts cannot express are
-// refused rather than silently dropped.
-func TestSlides_UpdateSlideWorkflowAsUser(t *testing.T) {
-	ctx, cancel := context.WithTimeout(context.Background(), 4*time.Minute)
-	t.Cleanup(cancel)
-
-	// Without a user token the load-bearing backend behavior goes unverified in
-	// this run; say so rather than skipping quietly.
-	clie2e.SkipWithoutUserToken(t)
-	skipWithoutCleanupScopes(ctx, t)
-
-	parentT := t
-	suffix := clie2e.GenerateSuffix()
-	title := "slides-update-e2e-" + suffix
-	controlText := "Control " + suffix
-	originalText := "Original " + suffix
-
-	page := func(body string) string {
-		return `<slide xmlns="http://www.larkoffice.com/sml/2.0"><data>` +
-			`<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">` +
-			`<content textType="title"><p>` + body + `</p></content></shape></data></slide>`
-	}
-	jsonArray := func(xmls ...string) string {
-		quoted := make([]string, 0, len(xmls))
-		for _, xml := range xmls {
-			quoted = append(quoted, `"`+strings.ReplaceAll(xml, `"`, `\"`)+`"`)
-		}
-		return "[" + strings.Join(quoted, ",") + "]"
-	}
-	readPage := func(t *testing.T, presentationID, slideID string) string {
-		t.Helper()
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{
-			Args:      []string{"slides", "+xml-get", "--presentation", presentationID, "--slide-id", slideID},
-			DefaultAs: "user",
-		})
-		require.NoError(t, err)
-		result.AssertExitCode(t, 0)
-		content := gjson.Get(result.Stdout, "data.slide.content").String()
-		require.NotEmpty(t, content, "stdout:\n%s", result.Stdout)
-		return content
-	}
-	update := func(t *testing.T, presentationID, slideID, content string) *clie2e.Result {
-		t.Helper()
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{
-			Args: []string{
-				"slides", "+update-slide",
-				"--presentation", presentationID,
-				"--slide-id", slideID,
-				"--content", content,
-			},
-			DefaultAs: "user",
-		})
-		require.NoError(t, err)
-		return result
-	}
-
-	var presentationID, targetSlideID string
-
-	t.Run("create a two-page presentation as user", func(t *testing.T) {
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{
-			Args: []string{
-				"slides", "+create",
-				"--title", title,
-				"--slides", jsonArray(page(controlText), page(originalText)),
-			},
-			DefaultAs: "user",
-		})
-		require.NoError(t, err)
-		result.AssertExitCode(t, 0)
-		result.AssertStdoutStatus(t, true)
-
-		presentationID = gjson.Get(result.Stdout, "data.xml_presentation_id").String()
-		require.NotEmpty(t, presentationID, "stdout:\n%s", result.Stdout)
-		slideIDs := gjson.Get(result.Stdout, "data.slide_ids").Array()
-		require.Len(t, slideIDs, 2, "stdout:\n%s", result.Stdout)
-		targetSlideID = slideIDs[1].String()
-
-		parentT.Cleanup(func() {
-			cleanupCtx, cancel := clie2e.CleanupContext()
-			defer cancel()
-
-			deleteResult, deleteErr := clie2e.RunCmd(cleanupCtx, clie2e.Request{
-				Args: []string{
-					"drive", "+delete",
-					"--file-token", presentationID,
-					"--type", "slides",
-					"--yes",
-				},
-				DefaultAs: "user",
-			})
-			// Deleting needs space:document:delete, which a token scoped only
-			// for slides does not carry; report rather than fail so a scope gap
-			// does not mask the workflow result. The deck is named with the
-			// run suffix so a leftover is identifiable.
-			clie2e.ReportCleanupFailure(parentT, "delete presentation "+presentationID, deleteResult, deleteErr)
-		})
-	})
-
-	t.Run("restyle an element: one replace part", func(t *testing.T) {
-		require.NotEmpty(t, targetSlideID, "presentation should be created first")
-
-		// Change the font on every element, which is the edit the command
-		// exists for. Only <content> is touched, so exactly one element differs.
-		current := readPage(t, presentationID, targetSlideID)
-		wanted := regexp.MustCompile(`fontFamily="[^"]*"`).ReplaceAllString(current, `fontFamily="楷体"`)
-		require.NotEqual(t, current, wanted, "the page should have had a fontFamily to change:\n%s", current)
-
-		result := update(t, presentationID, targetSlideID, wanted)
-		result.AssertExitCode(t, 0)
-		result.AssertStdoutStatus(t, true)
-		require.Equal(t, int64(1), gjson.Get(result.Stdout, "data.replaced").Int(), result.Stdout)
-		require.Equal(t, int64(1), gjson.Get(result.Stdout, "data.parts_count").Int(), result.Stdout)
-		require.Equal(t, targetSlideID, gjson.Get(result.Stdout, "data.slide_id").String(),
-			"the page keeps its slide_id\n%s", result.Stdout)
-
-		after := readPage(t, presentationID, targetSlideID)
-		require.Contains(t, after, `fontFamily="楷体"`, "the restyle must be live:\n%s", after)
-		require.Contains(t, after, originalText, "restyling must not change the text:\n%s", after)
-	})
-
-	t.Run("writing the same page again is a no-op", func(t *testing.T) {
-		current := readPage(t, presentationID, targetSlideID)
-		result := update(t, presentationID, targetSlideID, current)
-		result.AssertExitCode(t, 0)
-		require.True(t, gjson.Get(result.Stdout, "data.unchanged").Bool(),
-			"an identical page must not be written\n%s", result.Stdout)
-		require.Equal(t, int64(0), gjson.Get(result.Stdout, "data.parts_count").Int(), result.Stdout)
-	})
-
-	t.Run("add an element without an id: one insert part", func(t *testing.T) {
-		current := readPage(t, presentationID, targetSlideID)
-		added := `<shape type="text" topLeftX="80" topLeftY="300" width="400" height="80"><content><p>Added ` + suffix + `</p></content></shape>`
-		wanted := strings.Replace(current, "</data>", added+"</data>", 1)
-
-		result := update(t, presentationID, targetSlideID, wanted)
-		result.AssertExitCode(t, 0)
-		require.Equal(t, int64(1), gjson.Get(result.Stdout, "data.inserted").Int(), result.Stdout)
-
-		after := readPage(t, presentationID, targetSlideID)
-		require.Contains(t, after, "Added "+suffix, "the new element must be live:\n%s", after)
-		require.Contains(t, after, originalText, "the existing element must survive:\n%s", after)
-	})
-
-	t.Run("drop an element: one delete part", func(t *testing.T) {
-		current := readPage(t, presentationID, targetSlideID)
-		// Remove the original title shape, keeping the one added above.
-		wanted := regexp.MustCompile(`(?s)\s*<shape[^>]*>\s*<content[^>]*>\s*<p>`+regexp.QuoteMeta(originalText)+`</p>.*?</shape>`).
-			ReplaceAllString(current, "")
-		require.NotEqual(t, current, wanted, "the title shape should have been removable:\n%s", current)
-
-		result := update(t, presentationID, targetSlideID, wanted)
-		result.AssertExitCode(t, 0)
-		require.Equal(t, int64(1), gjson.Get(result.Stdout, "data.deleted").Int(), result.Stdout)
-
-		after := readPage(t, presentationID, targetSlideID)
-		require.NotContains(t, after, originalText, "the dropped element must be gone:\n%s", after)
-		require.Contains(t, after, "Added "+suffix, "the kept element must remain:\n%s", after)
-	})
-
-	t.Run("a background change is refused, not dropped", func(t *testing.T) {
-		current := readPage(t, presentationID, targetSlideID)
-		// Matches both the self-closing <style/> a plain page comes back with
-		// and a populated <style>…</style>.
-		styleBlock := regexp.MustCompile(`(?s)<style\s*/>|<style[^>]*>.*?</style>`)
-		require.True(t, styleBlock.MatchString(current), "page should carry a <style> block:\n%s", current)
-		wanted := styleBlock.ReplaceAllString(current,
-			`<style><fill><fillColor color="rgba(255, 0, 0, 1)"/></fill></style>`)
-
-		result := update(t, presentationID, targetSlideID, wanted)
-		require.NotEqual(t, 0, result.ExitCode,
-			"the background cannot be expressed, so it must fail loudly\nstdout:\n%s\nstderr:\n%s", result.Stdout, result.Stderr)
-		require.Contains(t, result.Stderr, "background", "stderr:\n%s", result.Stderr)
-
-		// And nothing may have been written: the page is still what it was.
-		require.Equal(t, current, readPage(t, presentationID, targetSlideID),
-			"a refused background change must leave the page untouched")
-	})
-
-	t.Run("the other page and the page order are untouched", func(t *testing.T) {
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{
-			Args:      []string{"api", "get", "/open-apis/slides_ai/v1/xml_presentations/" + presentationID},
-			DefaultAs: "user",
-			Params:    map[string]any{"revision_id": -1},
-		})
-		require.NoError(t, err)
-		result.AssertExitCode(t, 0)
-
-		content := gjson.Get(result.Stdout, "data.xml_presentation.content").String()
-		require.Contains(t, content, controlText, "the control page must be untouched\n%s", content)
-
-		controlAt := strings.Index(content, controlText)
-		editedAt := strings.Index(content, "Added "+suffix)
-		require.GreaterOrEqual(t, controlAt, 0, content)
-		require.GreaterOrEqual(t, editedAt, 0, content)
-		require.Less(t, controlAt, editedAt, "the deck order must not change\n%s", content)
-	})
-}