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

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) {

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{

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`
 - 本地文件名在未显式带扩展名时，会结合响应头自动补扩展名
 

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")