test(sheets): cover undo shortcut edge cases

The refactored + commands have been the default for over a month. Hide the
deprecated pre-refactor aliases from `sheets --help` via a custom cobra
usage template that skips the deprecated group. Aliases stay registered
and executable: their own `sheets <alias> --help` still shows the
(→ +new-command) pointer, unknown-subcommand suggestions still span them,
and execution still returns the _notice.

.gitignore

@@ -27,9 +27,6 @@ Thumbs.db
 # Go
 docs/ref
 docs/
-!tests/cli_e2e/docs/
-!tests/cli_e2e/docs/*.go
-!tests/cli_e2e/docs/*.md
 vendor/
 
 

CHANGELOG.md

@@ -2,22 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [v1.0.65] - 2026-07-03
-
-### Features
-
-- **doc**: Add `+history-list`, `+history-revert`, and `+history-revert-status` shortcuts for document version history (#1612)
-
-### Bug Fixes
-
-- **minutes**: `+speaker-replace` no longer refetches the speaker list — `--from-speaker-id` is passed through as-is (#1731)
-
-### Documentation
-
-- **drive**: Document 30-char query limit for `+search` (#1560)
-- **doc**: Add mindnote guidance to lark-doc skill (#1581)
-- **doc**: Sync lark-doc skill content from online-doc (#1701)
-
 ## [v1.0.64] - 2026-07-02
 
 ### Features
@@ -1371,7 +1355,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
-[v1.0.65]: https://github.com/larksuite/cli/releases/tag/v1.0.65
 [v1.0.64]: https://github.com/larksuite/cli/releases/tag/v1.0.64
 [v1.0.62]: https://github.com/larksuite/cli/releases/tag/v1.0.62
 [v1.0.61]: https://github.com/larksuite/cli/releases/tag/v1.0.61

cmd/api/api_test.go

@@ -20,28 +20,13 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func newTestApiCmd(f *cmdutil.Factory, runF func(*APIOptions) error) *cobra.Command {
-	cmd := NewCmdApi(f, runF)
-	cmd.SilenceErrors = true
-	cmd.SilenceUsage = true
-	return cmd
-}
-
-func newTestRootCmd() *cobra.Command {
-	return &cobra.Command{
-		Use:           "lark-cli",
-		SilenceErrors: true,
-		SilenceUsage:  true,
-	}
-}
-
 func TestApiCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
 	var gotOpts *APIOptions
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -69,7 +54,7 @@ func TestApiCmd_DryRun(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--dry-run"})
 	err := cmd.Execute()
 	if err != nil {
@@ -92,7 +77,7 @@ func TestApiCmd_NullParamsWithPageSize(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--params", "null", "--page-size", "50", "--as", "bot", "--dry-run"})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("--params null with --page-size should not error, got: %v", err)
@@ -113,7 +98,7 @@ func TestApiCmd_BotMode(t *testing.T) {
 		Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"result": "success"}},
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -140,7 +125,7 @@ func TestApiCmd_MissingArgs(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET"}) // missing path
 	err := cmd.Execute()
 	if err == nil {
@@ -153,7 +138,7 @@ func TestApiCmd_InvalidParamsJSON(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--params", "{bad"})
 	err := cmd.Execute()
 	if err == nil {
@@ -166,7 +151,7 @@ func TestApiValidArgsFunction(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	fn := cmd.ValidArgsFunction
 
 	tests := []struct {
@@ -232,7 +217,7 @@ func TestNewCmdApi_StrictModeHidesAsFlag(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu, SupportedIdentities: 2,
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	flag := cmd.Flags().Lookup("as")
 	if flag == nil {
 		t.Fatal("expected --as flag to be registered")
@@ -251,7 +236,7 @@ func TestApiCmd_PageLimitDefault(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -270,7 +255,7 @@ func TestApiCmd_ParamsAndDataBothStdinConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--params", "-", "--data", "-"})
 	err := cmd.Execute()
 	if err == nil {
@@ -287,7 +272,7 @@ func TestApiCmd_OutputAndPageAllConflict(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return apiRun(opts)
 	})
@@ -312,7 +297,7 @@ func TestApiCmd_BinaryResponse_AutoSave(t *testing.T) {
 		ContentType: "application/octet-stream",
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/drive/v1/files/xxx/download", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -343,7 +328,7 @@ func TestApiCmd_PageAll_NonBatchAPI_FallbackToJSON(t *testing.T) {
 		},
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users/u123", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err != nil {
@@ -383,7 +368,7 @@ func TestApiCmd_PageAll_NonBatchAPI_ErrorStillOutputsJSON(t *testing.T) {
 		},
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/im/v1/chats/oc_xxx/announcement", "--as", "bot", "--page-all"})
 	err := cmd.Execute()
 	// Should return an error
@@ -424,7 +409,7 @@ func TestApiCmd_PageAll_BatchAPI_StreamsItems(t *testing.T) {
 		},
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err != nil {
@@ -463,7 +448,7 @@ func TestApiCmd_PageAll_StreamBusinessErrorDoesNotDumpJSON(t *testing.T) {
 		},
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err == nil {
@@ -498,7 +483,7 @@ func TestApiCmd_PageAll_BatchAPI_DefaultJSONEnvelope(t *testing.T) {
 		},
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -564,8 +549,8 @@ func TestApiCmd_PageAll_DefaultJSONRunsContentSafety(t *testing.T) {
 		},
 	})
 
-	root := newTestRootCmd()
-	root.AddCommand(newTestApiCmd(f, nil))
+	root := &cobra.Command{Use: "lark-cli"}
+	root.AddCommand(NewCmdApi(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
 	if err := root.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -615,8 +600,8 @@ func TestApiCmd_PageAll_StreamFormatRunsContentSafety(t *testing.T) {
 		},
 	})
 
-	root := newTestRootCmd()
-	root.AddCommand(newTestApiCmd(f, nil))
+	root := &cobra.Command{Use: "lark-cli"}
+	root.AddCommand(NewCmdApi(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	if err := root.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -671,8 +656,8 @@ func TestApiCmd_PageAll_StreamFormatBlockSkipsBlockedPage(t *testing.T) {
 		},
 	})
 
-	root := newTestRootCmd()
-	root.AddCommand(newTestApiCmd(f, nil))
+	root := &cobra.Command{Use: "lark-cli"}
+	root.AddCommand(NewCmdApi(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := root.Execute()
 	if err == nil {
@@ -736,7 +721,7 @@ func TestApiCmd_JqFlag_Parsing(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -756,7 +741,7 @@ func TestApiCmd_JqFlag_ShortForm(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -775,7 +760,7 @@ func TestApiCmd_JqAndOutputConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--output", "file.bin"})
@@ -806,7 +791,7 @@ func TestApiCmd_JqFilter_AppliesExpression(t *testing.T) {
 		},
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test/jq", "--as", "bot", "--jq", ".data.items[].name"})
 	err := cmd.Execute()
 	if err != nil {
@@ -827,7 +812,7 @@ func TestApiCmd_JqAndFormatConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--format", "ndjson"})
@@ -845,7 +830,7 @@ func TestApiCmd_JqInvalidExpression(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", "invalid["})
@@ -874,7 +859,7 @@ func TestApiCmd_PageAll_WithJq(t *testing.T) {
 		},
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--jq", ".data.items[].id"})
 	err := cmd.Execute()
 	if err != nil {
@@ -895,7 +880,7 @@ func TestApiCmd_MethodUppercase(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -914,7 +899,7 @@ func TestApiCmd_FileFlagParsing(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 	var gotOpts *APIOptions
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -932,7 +917,7 @@ func TestApiCmd_FileAndOutputConflict(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--file", "photo.jpg", "--output", "out.json"})
@@ -949,7 +934,7 @@ func TestApiCmd_FileWithGET(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--file", "photo.jpg"})
@@ -966,7 +951,7 @@ func TestApiCmd_FileStdinConflictWithData(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--file", "-", "--data", "-"})
@@ -989,7 +974,7 @@ func TestApiCmd_DryRunWithFile(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"POST", "/open-apis/im/v1/images", "--file", "image=" + tmpFile, "--data", `{"image_type":"message"}`, "--dry-run", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -1030,7 +1015,7 @@ func TestApiCmd_PermissionError_DerivesFirstClassFields(t *testing.T) {
 		},
 	})
 
-	cmd := newTestApiCmd(f, nil)
+	cmd := NewCmdApi(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/docx/v1/documents/test", "--as", "bot"})
 	err := cmd.Execute()
 	if err == nil {
@@ -1056,7 +1041,7 @@ func TestApiCmd_JsonFlag_Accepted(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
+	cmd := NewCmdApi(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})

cmd/auth/status.go

@@ -27,9 +27,6 @@ func NewCmdAuthStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobr
 	cmd := &cobra.Command{
 		Use:   "status",
 		Short: "View current auth status",
-		Long: `Show OAuth user login, token validity, and granted scopes.
-For token-validity checks, run lark-cli auth status --json --verify.
-This is not profile/app selection diagnostics; use lark-cli whoami for the effective app/profile identity used by an invocation.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if runF != nil {
 				return runF(opts)

cmd/auth/status_test.go

@@ -6,7 +6,6 @@ package auth
 import (
 	"encoding/json"
 	"net/http"
-	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -14,20 +13,6 @@ import (
 	"github.com/larksuite/cli/internal/httpmock"
 )
 
-func TestAuthStatusHelpDistinguishesFromWhoami(t *testing.T) {
-	cmd := NewCmdAuthStatus(nil, nil)
-	for _, want := range []string{
-		"OAuth user login",
-		"auth status --json --verify",
-		"not profile/app selection diagnostics",
-		"lark-cli whoami",
-	} {
-		if !strings.Contains(cmd.Long, want) {
-			t.Errorf("auth status --help Long missing %q; got:\n%s", want, cmd.Long)
-		}
-	}
-}
-
 func TestAuthStatusRun_SplitsBotAndUserIdentity(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,

cmd/bootstrap.go

@@ -6,10 +6,8 @@ package cmd
 import (
 	"errors"
 	"io"
-	"os"
 
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/envvars"
 	"github.com/spf13/pflag"
 )
 
@@ -28,13 +26,5 @@ func BootstrapInvocationContext(args []string) (cmdutil.InvocationContext, error
 	if err := fs.Parse(args); err != nil && !errors.Is(err, pflag.ErrHelp) {
 		return cmdutil.InvocationContext{}, err
 	}
-
-	profileFromFlag := globals.Profile != ""
-	if !profileFromFlag {
-		globals.Profile = os.Getenv(envvars.CliProfile)
-	}
-	return cmdutil.InvocationContext{
-		Profile:         globals.Profile,
-		ProfileFromFlag: profileFromFlag,
-	}, nil
+	return cmdutil.InvocationContext{Profile: globals.Profile}, nil
 }

cmd/bootstrap_test.go

@@ -3,11 +3,7 @@
 
 package cmd
 
-import (
-	"testing"
-
-	"github.com/larksuite/cli/internal/envvars"
-)
+import "testing"
 
 func TestBootstrapInvocationContext_ProfileFlag(t *testing.T) {
 	inv, err := BootstrapInvocationContext([]string{"--profile", "target", "auth", "status"})
@@ -74,45 +70,3 @@ func TestBootstrapInvocationContext_HelpWithProfile(t *testing.T) {
 		t.Fatalf("profile = %q, want %q", inv.Profile, "target")
 	}
 }
-
-func TestBootstrapProfileEnvFallback(t *testing.T) {
-	t.Run("flag wins over env", func(t *testing.T) {
-		t.Setenv(envvars.CliProfile, "tenant_env")
-		inv, err := BootstrapInvocationContext([]string{"--profile", "tenant_flag", "whoami"})
-		if err != nil {
-			t.Fatalf("unexpected err: %v", err)
-		}
-		if inv.Profile != "tenant_flag" {
-			t.Errorf("got %q, want tenant_flag", inv.Profile)
-		}
-		if !inv.ProfileFromFlag {
-			t.Errorf("ProfileFromFlag = false, want true")
-		}
-	})
-	t.Run("env used when flag absent", func(t *testing.T) {
-		t.Setenv(envvars.CliProfile, "tenant_env")
-		inv, err := BootstrapInvocationContext([]string{"whoami"})
-		if err != nil {
-			t.Fatalf("unexpected err: %v", err)
-		}
-		if inv.Profile != "tenant_env" {
-			t.Errorf("got %q, want tenant_env", inv.Profile)
-		}
-		if inv.ProfileFromFlag {
-			t.Errorf("ProfileFromFlag = true, want false")
-		}
-	})
-	t.Run("empty when neither set", func(t *testing.T) {
-		t.Setenv(envvars.CliProfile, "")
-		inv, err := BootstrapInvocationContext([]string{"whoami"})
-		if err != nil {
-			t.Fatalf("unexpected err: %v", err)
-		}
-		if inv.Profile != "" {
-			t.Errorf("got %q, want empty", inv.Profile)
-		}
-		if inv.ProfileFromFlag {
-			t.Errorf("ProfileFromFlag = true, want false")
-		}
-	})
-}

cmd/profile/profile.go

@@ -14,13 +14,6 @@ func NewCmdProfile(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "profile",
 		Short: "Manage configuration profiles",
-		Long: `Profiles are named app identities managed by lark-cli.
-
-Profile selection:
-  --profile <name>             Use a profile for this command only.
-  LARKSUITE_CLI_PROFILE        Use a profile for the current shell / agent session.
-  lark-cli whoami --json       Show which identity is actually used.
-  unset LARKSUITE_CLI_PROFILE  Clear the session profile and fall back to direct app env or configured default.`,
 	}
 	cmdutil.DisableAuthCheck(cmd)
 	cmdutil.SetTips(cmd, []string{

cmd/profile/profile_test.go

@@ -627,19 +627,6 @@ func TestProfileRemoveRun_ValidationErrors(t *testing.T) {
 	})
 }
 
-// TestProfileHelpHasSelectionSection asserts `profile --help` documents the
-// per-invocation flag and session-scoped env var for selecting a profile, so
-// users and AI agents can find LARKSUITE_CLI_PROFILE without reading source.
-func TestProfileHelpHasSelectionSection(t *testing.T) {
-	cmd := NewCmdProfile(nil)
-	if !strings.Contains(cmd.Long, "Profile selection:") {
-		t.Errorf("profile --help missing Profile selection section")
-	}
-	if !strings.Contains(cmd.Long, "LARKSUITE_CLI_PROFILE") {
-		t.Errorf("profile --help missing LARKSUITE_CLI_PROFILE")
-	}
-}
-
 func TestProfileListRun_InvalidConfigReturnsValidationError(t *testing.T) {
 	dir := setupProfileConfigDir(t)
 	if err := os.WriteFile(filepath.Join(dir, "config.json"), []byte("{invalid json"), 0600); err != nil {

cmd/whoami/whoami.go

@@ -10,7 +10,6 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/identitydiag"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -34,15 +33,6 @@ type whoamiResult struct {
 	TokenStatus    string         `json:"tokenStatus"`
 	OnBehalfOf     *delegatedUser `json:"onBehalfOf,omitempty"`
 	Hint           string         `json:"hint,omitempty"`
-
-	// CredentialSource, Explicit, and DirectCredentialEnv surface the cached
-	// credential.IdentitySelection computed during resolution (not re-inferred
-	// here). CredentialSource can be empty ("") on the non-env
-	// extension-provider path (e.g. sidecar mode), where no selection kind
-	// applies; this is a documented, valid state, not an error.
-	CredentialSource    string                         `json:"credentialSource"`
-	Explicit            bool                           `json:"explicit"`
-	DirectCredentialEnv credential.DirectCredentialEnv `json:"directCredentialEnv"`
 }
 
 // delegatedUser is the user a user-identity acts on behalf of.
@@ -68,10 +58,6 @@ func NewCmdWhoami(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "whoami",
 		Short: "Show the current effective identity, app, profile, and token status (JSON)",
-		Long: `Show the effective app identity used by this invocation. This is not OAuth login status;
-use ` + "`lark-cli auth status --json`" + ` for OAuth user/token state.
-The JSON output includes credentialSource, appId, brand, and whether direct app credential
-env is present and matches the selected profile.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return whoamiRun(cmd, opts)
 		},
@@ -111,17 +97,7 @@ func whoamiRun(cmd *cobra.Command, opts *Options) error {
 		f.ResolveStrictMode(ctx).ForcedIdentity(),
 	)
 	diag := identitydiag.Diagnose(ctx, f, cfg, false)
-	// Read the cached selection computed during resolution; never re-infer it
-	// here. A resolution failure (e.g. under a non-env extension provider that
-	// doesn't populate a selection) degrades to the zero value rather than
-	// regressing whoami's own error/diagnostic path above.
-	var selection credential.IdentitySelection
-	if f.Credential != nil {
-		if sel, err := f.Credential.Selection(ctx); err == nil {
-			selection = sel
-		}
-	}
-	res := buildResult(cfg, as, source, diag, selection)
+	res := buildResult(cfg, as, source, diag)
 	output.PrintJson(f.IOStreams.Out, res)
 	return nil
 }
@@ -146,23 +122,18 @@ func resolveSource(changedAs bool, flagAs core.Identity, autoDetected bool, stri
 
 // buildResult maps the resolved identity and local diagnostics into the output.
 // ResolveAs only ever returns user or bot, so the default branch handles user.
-// selection is the cached credential.IdentitySelection from resolution; it is
-// read as-is, never recomputed.
-func buildResult(cfg *core.CliConfig, as core.Identity, source string, diag identitydiag.Result, selection credential.IdentitySelection) *whoamiResult {
+func buildResult(cfg *core.CliConfig, as core.Identity, source string, diag identitydiag.Result) *whoamiResult {
 	defaultAs := cfg.DefaultAs
 	if defaultAs == "" {
 		defaultAs = core.AsAuto
 	}
 	res := &whoamiResult{
-		Profile:             cfg.ProfileName,
-		AppID:               cfg.AppID,
-		Brand:               cfg.Brand,
-		DefaultAs:           string(defaultAs),
-		Identity:            string(as),
-		IdentitySource:      source,
-		CredentialSource:    string(selection.Source),
-		Explicit:            selection.Explicit(),
-		DirectCredentialEnv: selection.DirectCredentialEnv,
+		Profile:        cfg.ProfileName,
+		AppID:          cfg.AppID,
+		Brand:          cfg.Brand,
+		DefaultAs:      string(defaultAs),
+		Identity:       string(as),
+		IdentitySource: source,
 	}
 	// Use the diagnosed hint as-is: it is tailored to the credential source, so
 	// it never says "auth login" when that is blocked under an external provider.

cmd/whoami/whoami_test.go

@@ -15,13 +15,10 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	extcred "github.com/larksuite/cli/extension/credential"
-	envprovider "github.com/larksuite/cli/extension/credential/env"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/internal/identitydiag"
-	"github.com/larksuite/cli/internal/keychain"
 )
 
 func TestResolveSource(t *testing.T) {
@@ -55,7 +52,7 @@ func TestBuildResult_UserValid(t *testing.T) {
 	diag := identitydiag.Result{
 		User: identitydiag.Identity{Available: true, Status: "ready", TokenStatus: "valid", OpenID: "ou_x", UserName: "Alice"},
 	}
-	r := buildResult(cfg, core.AsUser, "auto_detect", diag, credential.IdentitySelection{})
+	r := buildResult(cfg, core.AsUser, "auto_detect", diag)
 
 	if r.Identity != "user" || r.IdentitySource != "auto_detect" {
 		t.Fatalf("identity/source = %q/%q", r.Identity, r.IdentitySource)
@@ -80,7 +77,7 @@ func TestBuildResult_UserMissingToken(t *testing.T) {
 	diag := identitydiag.Result{
 		User: identitydiag.Identity{Available: false, Status: "missing", Hint: "run: lark-cli auth login --help"}, // never logged in
 	}
-	r := buildResult(cfg, core.AsUser, "auto_detect", diag, credential.IdentitySelection{})
+	r := buildResult(cfg, core.AsUser, "auto_detect", diag)
 
 	if r.Available {
 		t.Fatalf("available = true, want false")
@@ -103,7 +100,7 @@ func TestBuildResult_BotReady(t *testing.T) {
 	diag := identitydiag.Result{
 		Bot: identitydiag.Identity{Available: true, Status: "ready"},
 	}
-	r := buildResult(cfg, core.AsBot, "default_as", diag, credential.IdentitySelection{})
+	r := buildResult(cfg, core.AsBot, "default_as", diag)
 
 	if r.Identity != "bot" || r.IdentitySource != "default_as" {
 		t.Fatalf("identity/source = %q/%q", r.Identity, r.IdentitySource)
@@ -124,7 +121,7 @@ func TestBuildResult_BotNotConfigured(t *testing.T) {
 	diag := identitydiag.Result{
 		Bot: identitydiag.Identity{Available: false, Status: "not_configured", Hint: "run: lark-cli config --help"},
 	}
-	r := buildResult(cfg, core.AsBot, "auto_detect", diag, credential.IdentitySelection{})
+	r := buildResult(cfg, core.AsBot, "auto_detect", diag)
 
 	if r.Available {
 		t.Fatalf("available = true, want false")
@@ -321,94 +318,3 @@ func TestWhoami_ExternalProvider_UserHintNotKeychain(t *testing.T) {
 		t.Fatalf("hint should explain external management: %q", got.Hint)
 	}
 }
-
-// noopWhoamiKeychain is a no-op KeychainAccess; the profile below uses a
-// plaintext secret, so no keychain lookup is actually required.
-type noopWhoamiKeychain struct{}
-
-func (noopWhoamiKeychain) Get(service, account string) (string, error) { return "", nil }
-func (noopWhoamiKeychain) Set(service, account, value string) error    { return nil }
-func (noopWhoamiKeychain) Remove(service, account string) error        { return nil }
-
-// credentialSourceSecret is the profile secret written to config for
-// TestWhoamiIncludesCredentialSource. It must never leak into whoami's output
-// (security §5.1).
-const credentialSourceSecret = "test-secret"
-
-// profileSelectionFactory builds a Factory whose CredentialProvider resolves
-// an explicit profile ("tenant_a") supplied via the LARKSUITE_CLI_PROFILE env
-// fallback (not --profile), so Selection().Source resolves to
-// env:LARKSUITE_CLI_PROFILE and Explicit() is true, with no direct
-// app-credential env vars present.
-func profileSelectionFactory(t *testing.T) (*cmdutil.Factory, *bytes.Buffer) {
-	t.Helper()
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, "")
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	multi := &core.MultiAppConfig{
-		CurrentApp: "tenant_a",
-		Apps: []core.AppConfig{{
-			Name:      "tenant_a",
-			AppId:     "cli_a",
-			AppSecret: core.PlainSecret(credentialSourceSecret),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	if err := core.SaveMultiAppConfig(multi); err != nil {
-		t.Fatalf("SaveMultiAppConfig: %v", err)
-	}
-
-	defaultAcct := credential.NewDefaultAccountProvider(func() keychain.KeychainAccess { return noopWhoamiKeychain{} }, "tenant_a")
-	cred := credential.NewCredentialProvider([]extcred.Provider{&envprovider.Provider{}}, defaultAcct, nil, nil)
-	cred.WithProfile("tenant_a", false) // fromFlag=false -> env:LARKSUITE_CLI_PROFILE
-
-	cfg := &core.CliConfig{ProfileName: "tenant_a", AppID: "cli_a", AppSecret: credentialSourceSecret, Brand: core.BrandFeishu}
-	out := &bytes.Buffer{}
-	f := &cmdutil.Factory{
-		Config:     func() (*core.CliConfig, error) { return cfg, nil },
-		Credential: cred,
-		IOStreams:  &cmdutil.IOStreams{Out: out, ErrOut: &bytes.Buffer{}},
-	}
-	return f, out
-}
-
-// TestWhoamiIncludesCredentialSource locks in the diagnostic fields surfaced
-// from the cached credential.IdentitySelection (Task 6): credentialSource,
-// explicit, and directCredentialEnv. whoami must read the cached selection
-// as-is, not re-infer it.
-func TestWhoamiIncludesCredentialSource(t *testing.T) {
-	f, out := profileSelectionFactory(t)
-
-	cmd := NewCmdWhoami(f)
-	cmd.SetArgs([]string{})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("Execute() error = %v", err)
-	}
-
-	raw := out.String()
-	if strings.Contains(raw, credentialSourceSecret) {
-		t.Fatalf("whoami output leaked the profile secret: %s", raw)
-	}
-
-	var got whoamiResult
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatalf("json.Unmarshal() error = %v\n%s", err, raw)
-	}
-	if got.CredentialSource != string(credential.SourceEnvProfile) {
-		t.Fatalf("credentialSource = %q, want %q", got.CredentialSource, credential.SourceEnvProfile)
-	}
-	if !got.Explicit {
-		t.Fatalf("explicit = false, want true")
-	}
-	if got.DirectCredentialEnv.Present {
-		t.Fatalf("directCredentialEnv.present = true, want false: %#v", got.DirectCredentialEnv)
-	}
-	if !strings.Contains(raw, `"credentialSource": "env:LARKSUITE_CLI_PROFILE"`) {
-		t.Fatalf("raw JSON missing credentialSource literal: %s", raw)
-	}
-	if got.DirectCredentialEnv.Present || len(got.DirectCredentialEnv.Keys) != 0 ||
-		got.DirectCredentialEnv.AppID != "" || got.DirectCredentialEnv.Matched || got.DirectCredentialEnv.ConflictsWithProfile {
-		t.Fatalf("directCredentialEnv = %#v, want only present:false set", got.DirectCredentialEnv)
-	}
-}

errs/marshal_test.go

@@ -136,77 +136,6 @@ func TestConfigError_MarshalJSON(t *testing.T) {
 	}
 }
 
-func TestConfigError_ProfileFieldsMarshalJSON(t *testing.T) {
-	ce := NewConfigError(SubtypeAppCredentialIncomplete, "incomplete").
-		WithMissingKeys("LARKSUITE_CLI_APP_ID", "LARKSUITE_CLI_APP_SECRET").
-		WithProfile("work").
-		WithAppID("cli_abc").
-		WithCredentialSource("flag:--profile")
-	b, err := json.Marshal(ce)
-	if err != nil {
-		t.Fatal(err)
-	}
-	s := string(b)
-	for _, want := range []string{
-		`"type":"config"`,
-		`"subtype":"app_credential_incomplete"`,
-		`"missing_keys":["LARKSUITE_CLI_APP_ID","LARKSUITE_CLI_APP_SECRET"]`,
-		`"profile":"work"`,
-		`"app_id":"cli_abc"`,
-		`"credential_source":"flag:--profile"`,
-	} {
-		if !strings.Contains(s, want) {
-			t.Errorf("missing %q in %s", want, s)
-		}
-	}
-
-	// omitempty: unset fields must not appear on the wire.
-	empty := NewConfigError(SubtypeProfileNotFound, "x")
-	b2, err := json.Marshal(empty)
-	if err != nil {
-		t.Fatal(err)
-	}
-	s2 := string(b2)
-	for _, notWant := range []string{`"missing_keys"`, `"profile"`, `"app_id"`, `"credential_source"`} {
-		if strings.Contains(s2, notWant) {
-			t.Errorf("%q should be omitted when empty; got %s", notWant, s2)
-		}
-	}
-}
-
-func TestValidationError_ProfileConflictMarshalJSON(t *testing.T) {
-	ve := NewValidationError(SubtypeProfileAppCredentialConflict, "conflict").
-		WithProfileAppConflict("cli_profile", "cli_env")
-	b, err := json.Marshal(ve)
-	if err != nil {
-		t.Fatal(err)
-	}
-	s := string(b)
-	for _, want := range []string{
-		`"type":"validation"`,
-		`"subtype":"profile_app_credential_conflict"`,
-		`"profile_app_id":"cli_profile"`,
-		`"env_app_id":"cli_env"`,
-	} {
-		if !strings.Contains(s, want) {
-			t.Errorf("missing %q in %s", want, s)
-		}
-	}
-
-	// omitempty: unset conflict fields must not appear on the wire.
-	empty := NewValidationError(SubtypeInvalidArgument, "x")
-	b2, err := json.Marshal(empty)
-	if err != nil {
-		t.Fatal(err)
-	}
-	s2 := string(b2)
-	for _, notWant := range []string{`"profile_app_id"`, `"env_app_id"`} {
-		if strings.Contains(s2, notWant) {
-			t.Errorf("%q should be omitted when empty; got %s", notWant, s2)
-		}
-	}
-}
-
 func TestNetworkError_MarshalJSON(t *testing.T) {
 	ne := &NetworkError{
 		Problem: Problem{Category: CategoryNetwork, Subtype: SubtypeNetworkTimeout, Message: "dial timeout"},

errs/subtypes.go

@@ -12,9 +12,8 @@ const (
 
 // CategoryValidation subtypes
 const (
-	SubtypeInvalidArgument              Subtype = "invalid_argument"                // user-supplied flag / arg failed validation (gRPC INVALID_ARGUMENT alignment)
-	SubtypeFailedPrecondition           Subtype = "failed_precondition"             // request is valid but the system/resource state is not in the state required to execute; caller must change state (not retry) — e.g. ambiguous remote mapping (gRPC FAILED_PRECONDITION alignment)
-	SubtypeProfileAppCredentialConflict Subtype = "profile_app_credential_conflict" // profile and direct app env both set but app_id differs
+	SubtypeInvalidArgument    Subtype = "invalid_argument"    // user-supplied flag / arg failed validation (gRPC INVALID_ARGUMENT alignment)
+	SubtypeFailedPrecondition Subtype = "failed_precondition" // request is valid but the system/resource state is not in the state required to execute; caller must change state (not retry) — e.g. ambiguous remote mapping (gRPC FAILED_PRECONDITION alignment)
 )
 
 // CategoryAuthentication subtypes
@@ -42,13 +41,9 @@ const (
 
 // CategoryConfig subtypes
 const (
-	SubtypeInvalidClient           Subtype = "invalid_client"            // app_id / app_secret incorrect (RFC 6749 §5.2 alignment)
-	SubtypeNotConfigured           Subtype = "not_configured"            // local config file absent (user has not run `config init`)
-	SubtypeInvalidConfig           Subtype = "invalid_config"            // local config file present but malformed
-	SubtypeProfileNotFound         Subtype = "profile_not_found"         // --profile / LARKSUITE_CLI_PROFILE points to a nonexistent profile
-	SubtypeNoActiveProfile         Subtype = "no_active_profile"         // no active identity input and no usable default profile
-	SubtypeAppCredentialIncomplete Subtype = "app_credential_incomplete" // direct app env missing app_id or app_secret
-	SubtypeProfileSecretInvalid    Subtype = "profile_secret_invalid"    // profile exists but its secret cannot be resolved locally
+	SubtypeInvalidClient Subtype = "invalid_client" // app_id / app_secret incorrect (RFC 6749 §5.2 alignment)
+	SubtypeNotConfigured Subtype = "not_configured" // local config file absent (user has not run `config init`)
+	SubtypeInvalidConfig Subtype = "invalid_config" // local config file present but malformed
 )
 
 // CategoryNetwork subtypes

errs/types.go

@@ -61,11 +61,9 @@ type TypedError interface {
 // it is intentionally not serialized.
 type ValidationError struct {
 	Problem
-	Param        string         `json:"param,omitempty"`
-	Params       []InvalidParam `json:"params,omitempty"`
-	ProfileAppID string         `json:"profile_app_id,omitempty"`
-	EnvAppID     string         `json:"env_app_id,omitempty"`
-	Cause        error          `json:"-"`
+	Param  string         `json:"param,omitempty"`
+	Params []InvalidParam `json:"params,omitempty"`
+	Cause  error          `json:"-"`
 }
 
 // InvalidParam is one structured validation diagnostic: the parameter that
@@ -152,12 +150,6 @@ func (e *ValidationError) WithCause(cause error) *ValidationError {
 	return e
 }
 
-func (e *ValidationError) WithProfileAppConflict(profileAppID, envAppID string) *ValidationError {
-	e.ProfileAppID = profileAppID
-	e.EnvAppID = envAppID
-	return e
-}
-
 // =========================== AuthenticationError =============================
 
 // AuthenticationError is the typed error for CategoryAuthentication.
@@ -323,17 +315,8 @@ func (e *PermissionError) WithCause(cause error) *PermissionError {
 // intentionally not serialized.
 type ConfigError struct {
 	Problem
-	Field       string   `json:"field,omitempty"`
-	MissingKeys []string `json:"missing_keys,omitempty"`
-	Profile     string   `json:"profile,omitempty"`
-	AppID       string   `json:"app_id,omitempty"`
-	// CredentialSource is the machine-readable App/credential selection source
-	// that produced this config error (e.g. "flag:--profile",
-	// "env:LARKSUITE_CLI_PROFILE", "config"). It is required on
-	// profile_not_found and no_active_profile (spec §5) so an agent can branch
-	// on how the identity was (or was not) chosen. It is never a secret.
-	CredentialSource string `json:"credential_source,omitempty"`
-	Cause            error  `json:"-"`
+	Field string `json:"field,omitempty"`
+	Cause error  `json:"-"`
 }
 
 // Unwrap is nil-receiver safe; see ValidationError.Unwrap.
@@ -387,29 +370,6 @@ func (e *ConfigError) WithField(field string) *ConfigError {
 	return e
 }
 
-func (e *ConfigError) WithMissingKeys(keys ...string) *ConfigError {
-	e.MissingKeys = slices.Clone(keys)
-	return e
-}
-
-func (e *ConfigError) WithProfile(name string) *ConfigError {
-	e.Profile = name
-	return e
-}
-
-func (e *ConfigError) WithAppID(appID string) *ConfigError {
-	e.AppID = appID
-	return e
-}
-
-// WithCredentialSource records the machine-readable credential-selection source
-// on the wire (snake_case credential_source). The value is an enum string
-// (e.g. "flag:--profile", "config"), never a secret.
-func (e *ConfigError) WithCredentialSource(source string) *ConfigError {
-	e.CredentialSource = source
-	return e
-}
-
 func (e *ConfigError) WithCause(cause error) *ConfigError {
 	e.Cause = cause
 	return e

errs/types_test.go

@@ -643,29 +643,3 @@ func TestBuilderSetter_DefensiveCopy(t *testing.T) {
 		}
 	})
 }
-
-// ======================= Profile selection error subtypes =======================
-
-func TestConfigErrorProfileFields(t *testing.T) {
-	e := errs.NewConfigError(errs.SubtypeAppCredentialIncomplete, "incomplete").
-		WithMissingKeys("LARKSUITE_CLI_APP_ID").
-		WithCredentialSource("env:LARKSUITE_CLI_PROFILE")
-	p, ok := errs.ProblemOf(e)
-	if !ok || p.Subtype != errs.SubtypeAppCredentialIncomplete {
-		t.Fatalf("subtype mismatch: %+v", p)
-	}
-	if len(e.MissingKeys) != 1 || e.MissingKeys[0] != "LARKSUITE_CLI_APP_ID" {
-		t.Errorf("missing_keys not set: %v", e.MissingKeys)
-	}
-	if e.CredentialSource != "env:LARKSUITE_CLI_PROFILE" {
-		t.Errorf("credential_source not set: %q", e.CredentialSource)
-	}
-}
-
-func TestValidationErrorProfileConflict(t *testing.T) {
-	e := errs.NewValidationError(errs.SubtypeProfileAppCredentialConflict, "conflict").
-		WithProfileAppConflict("cli_profile", "cli_env")
-	if e.ProfileAppID != "cli_profile" || e.EnvAppID != "cli_env" {
-		t.Errorf("conflict fields not set: %q %q", e.ProfileAppID, e.EnvAppID)
-	}
-}

internal/cmdutil/factory.go

@@ -27,11 +27,6 @@ import (
 // In tests, replace any field to stub out external dependencies.
 type InvocationContext struct {
 	Profile string
-	// ProfileFromFlag is true when Profile was set via the --profile flag,
-	// and false when it came from the LARKSUITE_CLI_PROFILE env fallback
-	// (or neither was set). Downstream credential resolution uses this to
-	// report the correct profile source.
-	ProfileFromFlag bool
 }
 
 type Factory struct {

internal/cmdutil/factory_default.go

@@ -61,11 +61,10 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 	// Phase 2: Credential (sole data source)
 	// Keychain is read via closure so callers can replace f.Keychain after construction.
 	f.Credential = buildCredentialProvider(credentialDeps{
-		Keychain:        func() keychain.KeychainAccess { return f.Keychain },
-		Profile:         inv.Profile,
-		ProfileFromFlag: inv.ProfileFromFlag,
-		HttpClient:      f.HttpClient,
-		ErrOut:          f.IOStreams.ErrOut,
+		Keychain:   func() keychain.KeychainAccess { return f.Keychain },
+		Profile:    inv.Profile,
+		HttpClient: f.HttpClient,
+		ErrOut:     f.IOStreams.ErrOut,
 	})
 
 	// Phase 3: Config derived from Credential via an explicit conversion boundary.
@@ -163,11 +162,10 @@ func buildSDKTransport() http.RoundTripper {
 }
 
 type credentialDeps struct {
-	Keychain        func() keychain.KeychainAccess
-	Profile         string
-	ProfileFromFlag bool
-	HttpClient      func() (*http.Client, error)
-	ErrOut          io.Writer
+	Keychain   func() keychain.KeychainAccess
+	Profile    string
+	HttpClient func() (*http.Client, error)
+	ErrOut     io.Writer
 }
 
 func buildCredentialProvider(deps credentialDeps) *credential.CredentialProvider {
@@ -180,6 +178,5 @@ func buildCredentialProvider(deps credentialDeps) *credential.CredentialProvider
 	// depend on. enrichUserInfo failures are already non-fatal (the
 	// provider clears unverified identity fields), so silencing the
 	// warning is safe.
-	return credential.NewCredentialProvider(providers, defaultAcct, defaultToken, deps.HttpClient).
-		WithProfile(deps.Profile, deps.ProfileFromFlag)
+	return credential.NewCredentialProvider(providers, defaultAcct, defaultToken, deps.HttpClient)
 }

internal/credential/credential_provider.go

@@ -9,21 +9,13 @@ import (
 	"fmt"
 	"io"
 	"net/http"
-	"os"
 	"sync"
 
-	"github.com/larksuite/cli/errs"
 	extcred "github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/envvars"
 )
 
-// directCredentialProviderName is the Name() of the env provider, the source
-// of direct app credentials (LARKSUITE_CLI_APP_ID / _APP_SECRET). Only its
-// incomplete blocks map to app_credential_incomplete (spec §3 step 1).
-const directCredentialProviderName = "env"
-
 // DefaultAccountResolver is implemented by the default account provider.
 type DefaultAccountResolver interface {
 	ResolveAccount(ctx context.Context) (*Account, error)
@@ -144,18 +136,10 @@ type CredentialProvider struct {
 	httpClient   func() (*http.Client, error)
 	warnOut      io.Writer
 
-	// profile is the active profile (from --profile or LARKSUITE_CLI_PROFILE).
-	// profileFromFlag discriminates the source for the reported selection.
-	profile         string
-	profileFromFlag bool
-
 	accountOnce    sync.Once
 	account        *Account
 	accountErr     error
 	selectedSource credentialSource
-	// selection is the explainable credential-selection result, populated by
-	// doResolveAccount under accountOnce. It never carries a secret (§5.1).
-	selection IdentitySelection
 
 	hintOnce sync.Once
 	hint     *IdentityHint
@@ -177,15 +161,6 @@ func (p *CredentialProvider) SetWarnOut(warnOut io.Writer) *CredentialProvider {
 	return p
 }
 
-// WithProfile records the active profile and whether it came from the
-// --profile flag (as opposed to the LARKSUITE_CLI_PROFILE env fallback).
-// It governs credential arbitration and the reported selection source.
-func (p *CredentialProvider) WithProfile(profile string, fromFlag bool) *CredentialProvider {
-	p.profile = profile
-	p.profileFromFlag = fromFlag
-	return p
-}
-
 // ResolveAccount resolves app credentials. Result is cached after first call.
 // NOTE: Uses sync.Once — only the context from the first call is used for resolution.
 // Subsequent calls return the cached result regardless of their context.
@@ -197,273 +172,40 @@ func (p *CredentialProvider) ResolveAccount(ctx context.Context) (*Account, erro
 	return p.account, p.accountErr
 }
 
-// doResolveAccount arbitrates the credential/App selection per the spec
-// resolution order (§3): env-partial → profile → env-complete → config default.
-// It populates p.selection (no secret; §5.1) and p.selectedSource on every
-// success path.
 func (p *CredentialProvider) doResolveAccount(ctx context.Context) (*Account, error) {
-	// Step 1 (spec §3): consult the extension providers. The env provider is
-	// the "direct app credential" source. An incomplete direct credential
-	// (only APP_ID or only APP_SECRET set) short-circuits to
-	// app_credential_incomplete regardless of the active profile.
-	var envAcct *Account
-	var envSource extensionTokenSource
 	for _, prov := range p.providers {
 		acct, err := prov.ResolveAccount(ctx)
 		if err != nil {
-			var blockErr *extcred.BlockError
-			// Only the env (direct-credential) provider maps an incomplete
-			// block to app_credential_incomplete. Other providers' blocks
-			// propagate unchanged so they still stop the chain (§3 step 1
-			// is specifically about direct app credential env vars).
-			if errors.As(err, &blockErr) && prov.Name() == directCredentialProviderName {
-				if missing := missingDirectCredentialKeys(); len(missing) > 0 {
-					return nil, errs.NewConfigError(errs.SubtypeAppCredentialIncomplete,
-						"direct app credential is incomplete").
-						WithMissingKeys(missing...).
-						WithHint("set both %s and %s, or unset both and use --profile / a config default.",
-							envvars.CliAppID, envvars.CliAppSecret)
-				}
-				// Block for a reason other than incompleteness (e.g. an
-				// invalid identity/strict-mode value); preserve prior behavior.
-				return nil, err
-			}
 			return nil, err
 		}
 		if acct != nil {
-			// Only the env (direct-credential) provider feeds profile
-			// arbitration / conflict detection / DirectCredentialEnv reporting.
-			// This mirrors the block-path guard above. A non-env extension
-			// provider (e.g. sidecar) is NOT a direct-credential env account:
-			// it wins outright here, returning its account + token source
-			// unchanged (pre-diff behavior), without being misreported as a
-			// direct env credential (§4.2: Present = direct env vars actually
-			// set) or triggering a spurious profile_app_credential_conflict.
-			if prov.Name() != directCredentialProviderName {
-				internal := convertAccount(acct)
-				source := extensionTokenSource{provider: prov}
-				if err := p.enrichUserInfo(ctx, internal, source); err != nil {
-					if p.warnOut != nil {
-						_, _ = fmt.Fprintf(p.warnOut, "warning: unable to verify user identity from credential source %q: %v\n", source.Name(), err)
-					}
-					// enrichUserInfo failure is non-fatal: SupportedIdentities
-					// (used for strict mode) is already set by the provider.
-					// Clear unverified user identity for safety.
-					internal.UserOpenId = ""
-					internal.UserName = ""
+			internal := convertAccount(acct)
+			source := extensionTokenSource{provider: prov}
+			if err := p.enrichUserInfo(ctx, internal, source); err != nil {
+				if p.warnOut != nil {
+					_, _ = fmt.Fprintf(p.warnOut, "warning: unable to verify user identity from credential source %q: %v\n", source.Name(), err)
 				}
-				p.selectedSource = source
-				return internal, nil
+				// enrichUserInfo failure is non-fatal: SupportedIdentities
+				// (used for strict mode) is already set by the provider.
+				// Clear unverified user identity for safety.
+				internal.UserOpenId = ""
+				internal.UserName = ""
 			}
-			envAcct = convertAccount(acct)
-			envSource = extensionTokenSource{provider: prov}
-			break
+			p.selectedSource = source
+			return internal, nil
 		}
 	}
-
-	// Step 2 (spec §3): an explicit profile was requested.
-	if p.profile != "" {
-		multi, loadErr := core.LoadMultiAppConfig()
-		if errors.Is(loadErr, core.ErrMalformedConfig) {
-			// A malformed config must not be masked as profile_not_found (which
-			// would tell the user to run `profile list` and hide a real config
-			// problem). Pass the underlying error through unchanged so
-			// errors.Is / errors.Unwrap keep working. An absent config is not
-			// malformed and still falls through to the friendly
-			// profile_not_found below, since the requested profile cannot exist.
-			return nil, loadErr
-		}
-		var app *core.AppConfig
-		if loadErr == nil && multi != nil {
-			app = multi.FindApp(p.profile)
-		}
-		if app == nil {
-			return nil, errs.NewConfigError(errs.SubtypeProfileNotFound,
-				"profile %q not found", p.profile).
-				WithProfile(p.profile).
-				WithCredentialSource(string(p.profileSource())).
-				WithHint("run `lark-cli profile list` to see available profiles.")
-		}
-		if envAcct != nil {
-			// E == complete: the direct env app_id must match the profile.
-			if app.AppId != envAcct.AppID {
-				return nil, errs.NewValidationError(errs.SubtypeProfileAppCredentialConflict,
-					"profile %q app_id does not match %s", p.profile, envvars.CliAppID).
-					WithProfileAppConflict(app.AppId, envAcct.AppID).
-					WithHint("unset %s/%s, or select a profile whose app_id matches the environment.",
-						envvars.CliAppID, envvars.CliAppSecret)
-			}
-			p.selection = IdentitySelection{
-				Source: p.profileSource(),
-				DirectCredentialEnv: DirectCredentialEnv{
-					Present: true,
-					Keys:    presentDirectCredentialKeys(),
-					AppID:   envAcct.AppID,
-					Matched: true,
-				},
-			}
-		} else {
-			p.selection = IdentitySelection{
-				Source:              p.profileSource(),
-				DirectCredentialEnv: DirectCredentialEnv{Present: false},
-			}
-		}
-		// Resolve the profile's own (keychain-backed) credential locally.
-		acct, err := p.defaultAcct.ResolveAccount(ctx)
-		if err != nil {
-			// SECURITY (§5.1): generic message — never embed the underlying
-			// error or any secret material.
-			p.selection = IdentitySelection{}
-			return nil, errs.NewConfigError(errs.SubtypeProfileSecretInvalid,
-				"profile %q credential could not be resolved locally", p.profile).
-				WithProfile(p.profile).
-				WithAppID(app.AppId).
-				WithHint("verify the profile's app secret or re-add the profile with `lark-cli config`.")
-		}
-		p.selectedSource = defaultTokenSource{resolver: p.defaultToken}
-		return acct, nil
-	}
-
-	// Step 3 (spec §3): no explicit profile — direct env credential wins.
-	if envAcct != nil {
-		if err := p.enrichUserInfo(ctx, envAcct, envSource); err != nil {
-			if p.warnOut != nil {
-				_, _ = fmt.Fprintf(p.warnOut, "warning: unable to verify user identity from credential source %q: %v\n", envSource.Name(), err)
-			}
-			// enrichUserInfo failure is non-fatal: SupportedIdentities
-			// (used for strict mode) is already set by the provider.
-			// Clear unverified user identity for safety.
-			envAcct.UserOpenId = ""
-			envAcct.UserName = ""
-		}
-		p.selectedSource = envSource
-		p.selection = IdentitySelection{
-			Source: SourceEnvAppID,
-			DirectCredentialEnv: DirectCredentialEnv{
-				Present: true,
-				Keys:    presentDirectCredentialKeys(),
-				AppID:   envAcct.AppID,
-			},
-		}
-		return envAcct, nil
-	}
-
-	// No direct env credential and no profile → the config default.
 	if p.defaultAcct != nil {
 		acct, err := p.defaultAcct.ResolveAccount(ctx)
 		if err != nil {
-			// The config default failed to resolve. Distinguish (spec §3 step
-			// 3.2): a default profile that EXISTS (has an app_id) but whose
-			// secret cannot be resolved locally is a profile_secret_invalid —
-			// "identity is configured, its secret is broken" is more actionable
-			// than "no active profile". Only when there is genuinely no usable
-			// default profile do we report no_active_profile. Other typed
-			// failures (e.g. a specific config error) pass through unchanged.
-			if prob, ok := errs.ProblemOf(err); ok && prob.Subtype == errs.SubtypeNotConfigured {
-				if name, appID, ok := defaultProfileIdentity(); ok {
-					// SECURITY (§5.1): generic message — never embed the
-					// underlying error or any secret material. app_id is
-					// plaintext and safe to echo.
-					return nil, errs.NewConfigError(errs.SubtypeProfileSecretInvalid,
-						"profile %q credential could not be resolved locally", name).
-						WithProfile(name).
-						WithAppID(appID).
-						WithHint("verify the profile's app secret or re-add the profile with `lark-cli config`.")
-				}
-				return nil, errs.NewConfigError(errs.SubtypeNoActiveProfile, "no active profile").
-					WithCredentialSource(noActiveProfileCredentialSource).
-					WithHint("run `lark-cli config init` / `lark-cli profile add`, or set %s.", envvars.CliProfile)
-			}
 			return nil, err
 		}
-		multi, _ := core.LoadMultiAppConfig()
 		p.selectedSource = defaultTokenSource{resolver: p.defaultToken}
-		p.selection = IdentitySelection{Source: selectionSourceForDefault(multi)}
 		return acct, nil
 	}
 	return nil, core.NotConfiguredError()
 }
 
-// profileSource reports the credential source kind for a profile-backed
-// selection, discriminating the --profile flag from the env fallback.
-func (p *CredentialProvider) profileSource() CredentialSourceKind {
-	if p.profileFromFlag {
-		return SourceFlagProfile
-	}
-	return SourceEnvProfile
-}
-
-// noActiveProfileCredentialSource is the credential_source reported on the
-// no_active_profile error. Spec §5 fixes this to the literal "config": there is
-// no resolved default profile at all, so the more specific config:currentApp /
-// config:firstApp source values (used on successful config-default selections)
-// would be misleading. It is an enum string, never a secret.
-const noActiveProfileCredentialSource = "config"
-
-// defaultProfileIdentity reports the config default profile's display name and
-// app_id when a usable default profile actually EXISTS (currentApp > firstApp
-// resolves to an app with a non-empty app_id). It never touches the keychain or
-// any secret, so it can distinguish "default profile exists but its secret is
-// broken" (→ profile_secret_invalid) from "no usable default profile at all"
-// (→ no_active_profile), without risking a secret leak (§5.1).
-func defaultProfileIdentity() (name, appID string, ok bool) {
-	multi, err := core.LoadMultiAppConfig()
-	if err != nil || multi == nil {
-		return "", "", false
-	}
-	app := multi.CurrentAppConfig("")
-	if app == nil || app.AppId == "" {
-		return "", "", false
-	}
-	return app.ProfileName(), app.AppId, true
-}
-
-// selectionSourceForDefault reports whether the config default resolved to the
-// explicit currentApp or fell back to the first app (spec §3 step 3.2).
-func selectionSourceForDefault(multi *core.MultiAppConfig) CredentialSourceKind {
-	if multi != nil && multi.CurrentApp != "" {
-		return SourceConfigCurrentApp
-	}
-	return SourceConfigFirstApp
-}
-
-// missingDirectCredentialKeys returns the NAMES (never values) of the direct
-// app credential env vars that are absent. Used only when the env provider
-// blocks, to map an incomplete direct credential to app_credential_incomplete.
-func missingDirectCredentialKeys() []string {
-	var missing []string
-	if os.Getenv(envvars.CliAppID) == "" {
-		missing = append(missing, envvars.CliAppID)
-	}
-	if os.Getenv(envvars.CliAppSecret) == "" {
-		missing = append(missing, envvars.CliAppSecret)
-	}
-	return missing
-}
-
-// presentDirectCredentialKeys returns the NAMES (never values) of the direct
-// app credential env vars that are set. Used to annotate DirectCredentialEnv.
-func presentDirectCredentialKeys() []string {
-	var keys []string
-	if os.Getenv(envvars.CliAppID) != "" {
-		keys = append(keys, envvars.CliAppID)
-	}
-	if os.Getenv(envvars.CliAppSecret) != "" {
-		keys = append(keys, envvars.CliAppSecret)
-	}
-	return keys
-}
-
-// Selection resolves the account (once) and returns the cached, secret-free
-// explanation of how the credential/App was selected. It mirrors
-// selectedCredentialSource: resolve-then-return.
-func (p *CredentialProvider) Selection(ctx context.Context) (IdentitySelection, error) {
-	if _, err := p.ResolveAccount(ctx); err != nil {
-		return IdentitySelection{}, err
-	}
-	return p.selection, nil
-}
-
 // enrichUserInfo resolves user identity when extension provides a UAT.
 // If UAT is available, user_info API call is mandatory (security: verify token validity).
 // If no UAT from extension, falls back to provider-supplied OpenID.

internal/credential/credential_provider_selection_test.go

@@ -1,554 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package credential_test
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-	"slices"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	extcred "github.com/larksuite/cli/extension/credential"
-	envprovider "github.com/larksuite/cli/extension/credential/env"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/envvars"
-	"github.com/larksuite/cli/internal/keychain"
-)
-
-func asConfigError(t *testing.T, err error) *errs.ConfigError {
-	t.Helper()
-	var ce *errs.ConfigError
-	if !errors.As(err, &ce) {
-		t.Fatalf("expected *errs.ConfigError, got %T: %v", err, err)
-	}
-	return ce
-}
-
-func asValidationError(t *testing.T, err error) *errs.ValidationError {
-	t.Helper()
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	return ve
-}
-
-// secretValue is the profile secret written to config. It must NEVER appear in
-// any error message or IdentitySelection (security §5.1).
-const secretValue = "your-secret"
-
-// envSecretValue is the direct env app secret. Same no-leak guarantee.
-const envSecretValue = "your-password"
-
-// writeConfigTenantA writes a config with a single profile "tenant_a" (app_id
-// "cli_a"). The secret is a plaintext secret stored in config, which resolves
-// locally without a keychain lookup.
-func writeConfigTenantA(t *testing.T) {
-	t.Helper()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	multi := &core.MultiAppConfig{
-		CurrentApp: "tenant_a",
-		Apps: []core.AppConfig{{
-			Name:      "tenant_a",
-			AppId:     "cli_a",
-			AppSecret: core.PlainSecret(secretValue),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	if err := core.SaveMultiAppConfig(multi); err != nil {
-		t.Fatalf("SaveMultiAppConfig: %v", err)
-	}
-}
-
-// writeConfigTenantABroken writes tenant_a with a keychain-backed secret ref
-// that cannot be resolved (noop keychain returns empty), so profile secret
-// resolution fails locally.
-func writeConfigTenantABroken(t *testing.T) {
-	t.Helper()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	// A keychain SecretRef whose key does NOT match app_id cli_a. Local secret
-	// resolution fails (ValidateSecretKeyMatch), exercising profile_secret_invalid.
-	multi := &core.MultiAppConfig{
-		CurrentApp: "tenant_a",
-		Apps: []core.AppConfig{{
-			Name:      "tenant_a",
-			AppId:     "cli_a",
-			AppSecret: core.SecretInput{Ref: &core.SecretRef{Source: "keychain", ID: "appsecret:wrong_key"}},
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	if err := core.SaveMultiAppConfig(multi); err != nil {
-		t.Fatalf("SaveMultiAppConfig: %v", err)
-	}
-}
-
-func newProvider(t *testing.T, profile string, fromFlag bool) *credential.CredentialProvider {
-	t.Helper()
-	ep := &envprovider.Provider{}
-	defaultAcct := credential.NewDefaultAccountProvider(func() keychain.KeychainAccess { return &noopKC{} }, profile)
-	cp := credential.NewCredentialProvider([]extcred.Provider{ep}, defaultAcct, nil, nil)
-	cp.WithProfile(profile, fromFlag)
-	return cp
-}
-
-// assertNoSecretLeak fails if any secret value appears in the given strings.
-func assertNoSecretLeak(t *testing.T, where string, vals ...string) {
-	t.Helper()
-	for _, v := range vals {
-		if v == "" {
-			continue
-		}
-		if strings.Contains(v, secretValue) {
-			t.Errorf("%s leaked profile secret: %q", where, v)
-		}
-		if strings.Contains(v, envSecretValue) {
-			t.Errorf("%s leaked env secret: %q", where, v)
-		}
-	}
-}
-
-func subtypeOf(t *testing.T, err error) errs.Subtype {
-	t.Helper()
-	if err == nil {
-		t.Fatalf("expected error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("error is not a typed problem: %v", err)
-	}
-	return p.Subtype
-}
-
-// State #2: P none, E none, C none -> no_active_profile.
-func TestSelection_State2_NoActiveProfile(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, "")
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir()) // empty dir -> no config
-	cp := newProvider(t, "", false)
-
-	sel, err := cp.Selection(context.Background())
-	if got := subtypeOf(t, err); got != errs.SubtypeNoActiveProfile {
-		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeNoActiveProfile)
-	}
-	// Defect 1 (spec §5): no_active_profile must carry credential_source=config.
-	ce := asConfigError(t, err)
-	if ce.CredentialSource != "config" {
-		t.Errorf("credential_source = %q, want %q", ce.CredentialSource, "config")
-	}
-	assertNoSecretLeak(t, "state2", err.Error(), string(sel.Source))
-}
-
-// Config-default profile with a broken secret: P none, E none, C present but the
-// default profile's keychain secret ref is corrupted. Per spec §3 step 3.2 this
-// must be profile_secret_invalid (the identity IS configured, only its secret is
-// broken) — NOT no_active_profile (which is reserved for "no usable default").
-func TestSelection_ConfigDefaultBrokenSecret_ProfileSecretInvalid(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, "")
-	writeConfigTenantABroken(t) // CurrentApp = tenant_a (app_id cli_a), broken keychain ref
-	cp := newProvider(t, "", false)
-
-	_, err := cp.Selection(context.Background())
-	if got := subtypeOf(t, err); got != errs.SubtypeProfileSecretInvalid {
-		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileSecretInvalid)
-	}
-	ce := asConfigError(t, err)
-	if ce.Profile != "tenant_a" {
-		t.Errorf("profile = %q, want tenant_a", ce.Profile)
-	}
-	if ce.AppID != "cli_a" {
-		t.Errorf("app_id = %q, want cli_a", ce.AppID)
-	}
-	// §5.1: generic message, no cause, no secret anywhere.
-	if errors.Unwrap(ce) != nil {
-		t.Errorf("profile_secret_invalid must not attach a cause, got %v", errors.Unwrap(ce))
-	}
-	assertNoSecretLeak(t, "config-default-broken", ce.Message, ce.Hint, ce.AppID)
-}
-
-// Explicit profile requested but the config file is malformed. The load error
-// must be propagated (errors.Is ErrMalformedConfig) rather than masked as
-// profile_not_found, which would hide a real config problem and misdirect the
-// user to `profile list`. An absent config is separately still profile_not_found.
-func TestSelection_ExplicitProfile_MalformedConfig_PropagatesError(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, "")
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := os.MkdirAll(core.GetConfigDir(), 0o700); err != nil {
-		t.Fatalf("mkdir config dir: %v", err)
-	}
-	if err := os.WriteFile(core.GetConfigPath(), []byte("{ this is not valid json"), 0o600); err != nil {
-		t.Fatalf("write malformed config: %v", err)
-	}
-	cp := newProvider(t, "tenant_a", true)
-
-	_, err := cp.Selection(context.Background())
-	if err == nil {
-		t.Fatalf("expected error for malformed config, got nil")
-	}
-	if !errors.Is(err, core.ErrMalformedConfig) {
-		t.Fatalf("malformed config error not propagated: %v", err)
-	}
-	if prob, ok := errs.ProblemOf(err); ok && prob.Subtype == errs.SubtypeProfileNotFound {
-		t.Fatalf("malformed config masked as profile_not_found")
-	}
-}
-
-// State #3: P none, E partial (only APP_ID) -> app_credential_incomplete.
-func TestSelection_State3_EnvPartial(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "cli_env")
-	t.Setenv(envvars.CliAppSecret, "")
-	writeConfigTenantA(t)
-	cp := newProvider(t, "", false)
-
-	_, err := cp.Selection(context.Background())
-	if got := subtypeOf(t, err); got != errs.SubtypeAppCredentialIncomplete {
-		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeAppCredentialIncomplete)
-	}
-	prob, _ := errs.ProblemOf(err)
-	ce := asConfigError(t, err)
-	if !slices.Contains(ce.MissingKeys, envvars.CliAppSecret) {
-		t.Errorf("missing_keys = %v, want to contain %q", ce.MissingKeys, envvars.CliAppSecret)
-	}
-	// missing_keys must be NAMES only, never values.
-	for _, k := range ce.MissingKeys {
-		if strings.Contains(k, envSecretValue) || strings.Contains(k, secretValue) {
-			t.Errorf("missing_keys contains a value, not a name: %q", k)
-		}
-	}
-	assertNoSecretLeak(t, "state3", prob.Message, prob.Hint)
-}
-
-// State #4: P none, E complete -> env:LARKSUITE_CLI_APP_ID.
-func TestSelection_State4_EnvComplete(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "cli_env")
-	t.Setenv(envvars.CliAppSecret, envSecretValue)
-	writeConfigTenantA(t)
-	cp := newProvider(t, "", false)
-
-	sel, err := cp.Selection(context.Background())
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if sel.Source != credential.SourceEnvAppID {
-		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceEnvAppID)
-	}
-	if !sel.DirectCredentialEnv.Present {
-		t.Errorf("DirectCredentialEnv.Present = false, want true")
-	}
-	assertNoSecretLeak(t, "state4", string(sel.Source), sel.DirectCredentialEnv.AppID)
-	assertNoSecretLeak(t, "state4-keys", sel.DirectCredentialEnv.Keys...)
-}
-
-// State #5: P valid, E none -> flag:--profile (fromFlag) source.
-func TestSelection_State5_ProfileOnly(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, "")
-	writeConfigTenantA(t)
-	cp := newProvider(t, "tenant_a", true)
-
-	sel, err := cp.Selection(context.Background())
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if sel.Source != credential.SourceFlagProfile {
-		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceFlagProfile)
-	}
-	if sel.DirectCredentialEnv.Present {
-		t.Errorf("DirectCredentialEnv.Present = true, want false")
-	}
-	assertNoSecretLeak(t, "state5", string(sel.Source))
-}
-
-// State #5b: P valid from env (not flag) -> env:LARKSUITE_CLI_PROFILE source.
-func TestSelection_State5_ProfileFromEnv(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, "")
-	writeConfigTenantA(t)
-	cp := newProvider(t, "tenant_a", false)
-
-	sel, err := cp.Selection(context.Background())
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if sel.Source != credential.SourceEnvProfile {
-		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceEnvProfile)
-	}
-}
-
-// State #6: P missing (nonexistent), E complete -> profile_not_found.
-func TestSelection_State6_ProfileNotFound(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "cli_env")
-	t.Setenv(envvars.CliAppSecret, envSecretValue)
-	writeConfigTenantA(t)
-	cp := newProvider(t, "does_not_exist", true)
-
-	sel, err := cp.Selection(context.Background())
-	if got := subtypeOf(t, err); got != errs.SubtypeProfileNotFound {
-		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileNotFound)
-	}
-	prob, _ := errs.ProblemOf(err)
-	// Defect 1 (spec §5): profile_not_found must carry the credential_source that
-	// named the profile — here the --profile flag.
-	ce := asConfigError(t, err)
-	if ce.CredentialSource != string(credential.SourceFlagProfile) {
-		t.Errorf("credential_source = %q, want %q", ce.CredentialSource, credential.SourceFlagProfile)
-	}
-	assertNoSecretLeak(t, "state6", err.Error(), prob.Hint, string(sel.Source))
-}
-
-// State #7: P valid but secret broken, E none -> profile_secret_invalid.
-func TestSelection_State7_ProfileSecretInvalid(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, "")
-	writeConfigTenantABroken(t)
-	cp := newProvider(t, "tenant_a", true)
-
-	_, err := cp.Selection(context.Background())
-	if got := subtypeOf(t, err); got != errs.SubtypeProfileSecretInvalid {
-		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileSecretInvalid)
-	}
-	ce := asConfigError(t, err)
-	if ce.Profile != "tenant_a" {
-		t.Errorf("profile = %q, want tenant_a", ce.Profile)
-	}
-	if ce.AppID != "cli_a" {
-		t.Errorf("app_id = %q, want cli_a", ce.AppID)
-	}
-	assertNoSecretLeak(t, "state7", ce.Message, ce.Hint)
-}
-
-// secretMarkerValue is a distinctive string used to prove that the
-// profile_secret_invalid path drops the underlying error entirely, even when
-// that underlying error's own message CONTAINS a secret. Unlike
-// writeConfigTenantABroken (whose noop-keychain failure is a harmless empty
-// error), this uses a custom DefaultAccountResolver whose error text embeds
-// the marker, closing the gap where a leak could hide in a cause chain that
-// happens to be empty in the noop-keychain case.
-const secretMarkerValue = "your-access-token"
-
-// leakingSecretResolver is a DefaultAccountResolver stub whose ResolveAccount
-// fails with an error whose message contains secretMarkerValue, simulating a
-// real keychain/secret-resolution failure that echoes back sensitive material
-// (e.g. a keychain library including the attempted secret in its error text).
-type leakingSecretResolver struct{}
-
-func (leakingSecretResolver) ResolveAccount(ctx context.Context) (*credential.Account, error) {
-	return nil, fmt.Errorf("keychain decode failed for secret %s", secretMarkerValue)
-}
-
-// State #7 (secret-bearing underlying error): P valid, but the underlying
-// account/secret resolution fails with an error that itself contains a
-// secret. This locks the §5.1 design: doResolveAccount emits a generic
-// profile_secret_invalid ConfigError WITHOUT attaching the underlying cause,
-// so a secret embedded in that underlying error can never surface through
-// err.Error(), Message, Hint, the unwrapped cause chain, or Selection().
-func TestSelection_State7_UnderlyingErrorContainingSecret_NotLeaked(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, "")
-	writeConfigTenantA(t) // profile "tenant_a" exists with app_id "cli_a"
-
-	ep := &envprovider.Provider{}
-	cp := credential.NewCredentialProvider([]extcred.Provider{ep}, leakingSecretResolver{}, nil, nil)
-	cp.WithProfile("tenant_a", true)
-
-	sel, err := cp.Selection(context.Background())
-	if got := subtypeOf(t, err); got != errs.SubtypeProfileSecretInvalid {
-		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileSecretInvalid)
-	}
-	ce := asConfigError(t, err)
-	if ce.Profile != "tenant_a" {
-		t.Errorf("profile = %q, want tenant_a", ce.Profile)
-	}
-	if ce.AppID != "cli_a" {
-		t.Errorf("app_id = %q, want cli_a", ce.AppID)
-	}
-
-	// Walk the full unwrap chain. This is the assertion that would catch a
-	// regression where the profile_secret_invalid branch starts attaching the
-	// underlying error via WithCause: if it did, this loop would find the
-	// marker in a wrapped link even though err.Error()/Message/Hint (which
-	// only reflect the top-level ConfigError, not the chain) might look clean.
-	for cur := error(ce); cur != nil; cur = errors.Unwrap(cur) {
-		if strings.Contains(cur.Error(), secretMarkerValue) {
-			t.Errorf("cause chain leaked secret marker: %v", cur)
-		}
-	}
-
-	if strings.Contains(err.Error(), secretMarkerValue) {
-		t.Errorf("err.Error() leaked secret marker: %q", err.Error())
-	}
-	if strings.Contains(ce.Message, secretMarkerValue) {
-		t.Errorf("Message leaked secret marker: %q", ce.Message)
-	}
-	if strings.Contains(ce.Hint, secretMarkerValue) {
-		t.Errorf("Hint leaked secret marker: %q", ce.Hint)
-	}
-	if strings.Contains(string(sel.Source), secretMarkerValue) {
-		t.Errorf("Selection.Source leaked secret marker: %q", sel.Source)
-	}
-	if strings.Contains(sel.DirectCredentialEnv.AppID, secretMarkerValue) {
-		t.Errorf("Selection.DirectCredentialEnv.AppID leaked secret marker: %q", sel.DirectCredentialEnv.AppID)
-	}
-	for _, k := range sel.DirectCredentialEnv.Keys {
-		if strings.Contains(k, secretMarkerValue) {
-			t.Errorf("Selection.DirectCredentialEnv.Keys leaked secret marker: %q", k)
-		}
-	}
-	// State #7 always clears p.selection on the secret-invalid path (see
-	// doResolveAccount); assert it is zero-valued, which trivially implies no
-	// marker anywhere in it and guards against a future field being populated
-	// from the failed resolution.
-	if sel.Source != "" || sel.DirectCredentialEnv.Present ||
-		sel.DirectCredentialEnv.AppID != "" || len(sel.DirectCredentialEnv.Keys) != 0 {
-		t.Errorf("Selection() = %+v, want zero value on profile_secret_invalid", sel)
-	}
-}
-
-// State #8: P valid, E complete, app_id matches -> profile source, env present+matched.
-func TestSelection_State8_ProfileMatchesEnv(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "cli_a") // matches profile app_id
-	t.Setenv(envvars.CliAppSecret, envSecretValue)
-	writeConfigTenantA(t)
-	cp := newProvider(t, "tenant_a", true)
-
-	sel, err := cp.Selection(context.Background())
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if sel.Source != credential.SourceFlagProfile {
-		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceFlagProfile)
-	}
-	if !sel.DirectCredentialEnv.Present || !sel.DirectCredentialEnv.Matched {
-		t.Fatalf("DirectCredentialEnv = %+v, want Present && Matched", sel.DirectCredentialEnv)
-	}
-	if sel.DirectCredentialEnv.AppID != "cli_a" {
-		t.Errorf("DirectCredentialEnv.AppID = %q, want cli_a", sel.DirectCredentialEnv.AppID)
-	}
-	assertNoSecretLeak(t, "state8", string(sel.Source), sel.DirectCredentialEnv.AppID)
-	assertNoSecretLeak(t, "state8-keys", sel.DirectCredentialEnv.Keys...)
-}
-
-// State #9: P valid, E complete, app_id mismatches -> profile_app_credential_conflict.
-func TestSelection_State9_Conflict(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "cli_x") // mismatches profile app_id cli_a
-	t.Setenv(envvars.CliAppSecret, envSecretValue)
-	writeConfigTenantA(t)
-	cp := newProvider(t, "tenant_a", true)
-
-	_, err := cp.Selection(context.Background())
-	if got := subtypeOf(t, err); got != errs.SubtypeProfileAppCredentialConflict {
-		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileAppCredentialConflict)
-	}
-	ve := asValidationError(t, err)
-	if ve.ProfileAppID != "cli_a" {
-		t.Errorf("profile_app_id = %q, want cli_a", ve.ProfileAppID)
-	}
-	if ve.EnvAppID != "cli_x" {
-		t.Errorf("env_app_id = %q, want cli_x", ve.EnvAppID)
-	}
-	assertNoSecretLeak(t, "state9", ve.Message, ve.Hint)
-}
-
-// State #10: P valid, E partial -> app_credential_incomplete (env-partial wins).
-func TestSelection_State10_ProfileWithEnvPartial(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, envSecretValue) // only secret set
-	writeConfigTenantA(t)
-	cp := newProvider(t, "tenant_a", true)
-
-	_, err := cp.Selection(context.Background())
-	if got := subtypeOf(t, err); got != errs.SubtypeAppCredentialIncomplete {
-		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeAppCredentialIncomplete)
-	}
-	ce := asConfigError(t, err)
-	if !slices.Contains(ce.MissingKeys, envvars.CliAppID) {
-		t.Errorf("missing_keys = %v, want to contain %q", ce.MissingKeys, envvars.CliAppID)
-	}
-	assertNoSecretLeak(t, "state10", ce.Message, ce.Hint)
-	assertNoSecretLeak(t, "state10-keys", ce.MissingKeys...)
-}
-
-// fakeSidecarProvider is a NON-env extension provider (Priority 0, Name !=
-// directCredentialProviderName) that always returns a non-nil account. It
-// stands in for the sidecar extension provider without needing a build tag.
-type fakeSidecarProvider struct {
-	appID string
-}
-
-func (f *fakeSidecarProvider) Name() string  { return "sidecar" }
-func (f *fakeSidecarProvider) Priority() int { return 0 }
-func (f *fakeSidecarProvider) ResolveAccount(ctx context.Context) (*extcred.Account, error) {
-	return &extcred.Account{AppID: f.appID, Brand: extcred.Brand("feishu")}, nil
-}
-func (f *fakeSidecarProvider) ResolveToken(ctx context.Context, req extcred.TokenSpec) (*extcred.Token, error) {
-	return &extcred.Token{Value: "sidecar-tok", Source: "sidecar"}, nil
-}
-
-// Regression: a NON-env extension provider (sidecar) that returns an account
-// must win outright even when a profile is set. It must NOT be treated as a
-// direct-credential env account: no profile arbitration, no
-// profile_app_credential_conflict (even though its app_id differs from the
-// profile's cli_a), and DirectCredentialEnv.Present must stay false (§4.2 —
-// no direct env vars are set). This proves the success-account provider gating
-// mirrors the block-path guard.
-func TestSelection_NonEnvExtensionProviderWinsOverProfile(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")     // no direct env credential
-	t.Setenv(envvars.CliAppSecret, "") // no direct env credential
-	writeConfigTenantA(t)              // profile tenant_a exists, app_id cli_a
-
-	sidecar := &fakeSidecarProvider{appID: "sidecar_app"} // differs from cli_a
-	defaultAcct := credential.NewDefaultAccountProvider(func() keychain.KeychainAccess { return &noopKC{} }, "tenant_a")
-	cp := credential.NewCredentialProvider([]extcred.Provider{sidecar}, defaultAcct, nil, nil)
-	cp.WithProfile("tenant_a", true)
-
-	acct, err := cp.ResolveAccount(context.Background())
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	// The sidecar account is used as-is, NOT overridden by profile arbitration.
-	if acct == nil || acct.AppID != "sidecar_app" {
-		t.Fatalf("account = %+v, want AppID sidecar_app (sidecar wins outright)", acct)
-	}
-
-	sel, err := cp.Selection(context.Background())
-	if err != nil {
-		t.Fatalf("unexpected Selection error: %v", err)
-	}
-	// No misreported direct env credential (§4.2).
-	if sel.DirectCredentialEnv.Present {
-		t.Errorf("DirectCredentialEnv.Present = true, want false (no direct env vars set)")
-	}
-	// The mismatched app_id (sidecar_app vs profile cli_a) must NOT trigger a
-	// profile_app_credential_conflict: both ResolveAccount and Selection above
-	// returned nil errors, so no conflict (or any other) error was produced.
-	// Guard against a future regression that surfaces a conflict via Selection.
-	if _, selErr := cp.Selection(context.Background()); selErr != nil {
-		if subtypeOf(t, selErr) == errs.SubtypeProfileAppCredentialConflict {
-			t.Errorf("got profile_app_credential_conflict, want none for non-env provider")
-		}
-	}
-	assertNoSecretLeak(t, "nonenv-sidecar", string(sel.Source), sel.DirectCredentialEnv.AppID)
-}
-
-// State #1: P none, E none, C present -> config default (currentApp).
-func TestSelection_State1_ConfigDefault(t *testing.T) {
-	t.Setenv(envvars.CliAppID, "")
-	t.Setenv(envvars.CliAppSecret, "")
-	writeConfigTenantA(t) // CurrentApp = tenant_a
-	cp := newProvider(t, "", false)
-
-	sel, err := cp.Selection(context.Background())
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if sel.Source != credential.SourceConfigCurrentApp {
-		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceConfigCurrentApp)
-	}
-}

internal/credential/identity_selection.go

@@ -1,43 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package credential
-
-// CredentialSourceKind is the wire-stable App/credential selection source.
-type CredentialSourceKind string
-
-const (
-	SourceFlagProfile      CredentialSourceKind = "flag:--profile"
-	SourceEnvProfile       CredentialSourceKind = "env:LARKSUITE_CLI_PROFILE"
-	SourceEnvAppID         CredentialSourceKind = "env:LARKSUITE_CLI_APP_ID"
-	SourceConfigCurrentApp CredentialSourceKind = "config:currentApp"
-	SourceConfigFirstApp   CredentialSourceKind = "config:firstApp"
-)
-
-// DirectCredentialEnv describes the state of direct app credential env vars.
-// It never carries a secret value — only names and the non-sensitive app_id.
-type DirectCredentialEnv struct {
-	Present              bool     `json:"present"`
-	Keys                 []string `json:"keys,omitempty"`
-	AppID                string   `json:"appId,omitempty"`
-	Matched              bool     `json:"matched,omitempty"`
-	ConflictsWithProfile bool     `json:"conflictsWithProfile,omitempty"`
-}
-
-// IdentitySelection is the explainable result of credential selection.
-// It carries NO secret value (security: §5.1).
-type IdentitySelection struct {
-	Source              CredentialSourceKind
-	DirectCredentialEnv DirectCredentialEnv
-}
-
-// Explicit reports whether the identity was actively specified by the
-// user/agent (flag or env), which governs no-fallback behavior.
-func (s IdentitySelection) Explicit() bool {
-	switch s.Source {
-	case SourceFlagProfile, SourceEnvProfile, SourceEnvAppID:
-		return true
-	default:
-		return false
-	}
-}

internal/credential/identity_selection_test.go

@@ -1,25 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package credential
-
-import "testing"
-
-func TestIdentitySelectionExplicit(t *testing.T) {
-	cases := []struct {
-		src      CredentialSourceKind
-		explicit bool
-	}{
-		{SourceFlagProfile, true},
-		{SourceEnvProfile, true},
-		{SourceEnvAppID, true},
-		{SourceConfigCurrentApp, false},
-		{SourceConfigFirstApp, false},
-	}
-	for _, c := range cases {
-		sel := IdentitySelection{Source: c.src}
-		if sel.Explicit() != c.explicit {
-			t.Errorf("source %q: Explicit()=%v want %v", c.src, sel.Explicit(), c.explicit)
-		}
-	}
-}

internal/envvars/envvars.go

@@ -10,7 +10,6 @@ const (
 	CliUserAccessToken   = "LARKSUITE_CLI_USER_ACCESS_TOKEN"
 	CliTenantAccessToken = "LARKSUITE_CLI_TENANT_ACCESS_TOKEN"
 	CliDefaultAs         = "LARKSUITE_CLI_DEFAULT_AS"
-	CliProfile           = "LARKSUITE_CLI_PROFILE"
 	CliStrictMode        = "LARKSUITE_CLI_STRICT_MODE"
 
 	// Sidecar proxy (auth proxy mode)

package.json

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

shortcuts/calendar/calendar_create.go

@@ -67,26 +67,6 @@ func parseAttendees(attendeesStr string, currentUserId string) ([]map[string]str
 	return attendees, nil
 }
 
-func attendeesIncludeRoom(attendees []map[string]string) bool {
-	for _, attendee := range attendees {
-		if attendee["type"] == "resource" || attendee["room_id"] != "" {
-			return true
-		}
-	}
-	return false
-}
-
-func guideApprovalRoomReasonError(err error, attendees []map[string]string) error {
-	if err == nil || !attendeesIncludeRoom(attendees) {
-		return err
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || !strings.Contains(strings.ToLower(p.Hint), "approval_reason") {
-		return err
-	}
-	return withStepContext(err, "approval meeting rooms require attendees[].approval_reason; calendar +create does not expose this low-frequency field. Create the event with the raw API flow, then use `lark-cli calendar event.attendees create --as user` with attendees[].approval_reason for the room attendee.")
-}
-
 var CalendarCreate = common.Shortcut{
 	Service:     "calendar",
 	Command:     "+create",
@@ -245,7 +225,6 @@ var CalendarCreate = common.Shortcut{
 					"need_notification": true,
 				})
 			if err != nil {
-				err = guideApprovalRoomReasonError(err, attendees)
 				// Rollback: delete the event
 				_, rollbackErr := runtime.CallAPITyped("DELETE",
 					fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s", validate.EncodePathSegment(calendarId), validate.EncodePathSegment(eventId)),

shortcuts/calendar/calendar_test.go

@@ -673,76 +673,6 @@ func TestCreate_WithAttendees_InvalidParamsWithDetail_RollsBack(t *testing.T) {
 	}
 }
 
-func TestCreate_ApprovalRoomMissingReason_GuidesRawAttendeesAPI(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
-
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"event": map[string]interface{}{
-					"event_id":   "evt_approval_room",
-					"summary":    "Approval Room",
-					"start_time": map[string]interface{}{"timestamp": "1742515200"},
-					"end_time":   map[string]interface{}{"timestamp": "1742518800"},
-				},
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/events/evt_approval_room/attendees",
-		Body: map[string]interface{}{
-			"code": codeInvalidParamsWithDetail,
-			"msg":  "invalid params",
-			"error": map[string]interface{}{
-				"details": []interface{}{
-					map[string]interface{}{"value": "attendees[0].approval_reason is required for approval meeting rooms"},
-				},
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "DELETE",
-		URL:    "/events/evt_approval_room",
-		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
-	})
-
-	err := mountAndRun(t, CalendarCreate, []string{
-		"+create",
-		"--summary", "Approval Room",
-		"--start", "2025-03-21T00:00:00+08:00",
-		"--end", "2025-03-21T01:00:00+08:00",
-		"--calendar-id", "cal_test123",
-		"--attendee-ids", "omm_room1",
-		"--as", "user",
-	}, f, nil)
-
-	if err == nil {
-		t.Fatal("expected error for approval room missing approval_reason, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("ProblemOf returned !ok for %T", err)
-	}
-	if p.Category != errs.CategoryAPI {
-		t.Errorf("category=%q, want %q", p.Category, errs.CategoryAPI)
-	}
-	if p.Subtype != errs.SubtypeInvalidParameters {
-		t.Errorf("subtype=%q, want %q", p.Subtype, errs.SubtypeInvalidParameters)
-	}
-	if p.Code != codeInvalidParamsWithDetail {
-		t.Errorf("code=%d, want %d", p.Code, codeInvalidParamsWithDetail)
-	}
-	for _, want := range []string{"approval_reason", "calendar event.attendees create", "--as user", "rolled back successfully"} {
-		if !strings.Contains(p.Hint, want) {
-			t.Errorf("hint should contain %q, got: %q", want, p.Hint)
-		}
-	}
-}
-
 // When the add-attendees call fails AND the rollback DELETE also fails, the
 // primary error stays the add failure (classification preserved) and the Hint
 // must surface BOTH the rollback failure reason and the orphan event_id so the

shortcuts/doc/docs_history.go

@@ -1,261 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"context"
-	"fmt"
-	"net/http"
-	"strconv"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-type docsHistoryListSpec struct {
-	Doc       documentRef
-	PageSize  int
-	PageToken string
-}
-
-type docsHistoryRevertSpec struct {
-	Doc              documentRef
-	HistoryVersionID string
-	WaitTimeoutMs    int
-}
-
-type docsHistoryRevertStatusSpec struct {
-	Doc    documentRef
-	TaskID string
-}
-
-func parseDocsHistoryDocRef(raw, shortcut string) (documentRef, error) {
-	ref, err := parseDocumentRef(raw)
-	if err != nil {
-		return documentRef{}, err
-	}
-	if ref.Kind == "doc" {
-		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "docs %s only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx", shortcut).WithParam("--doc")
-	}
-	return ref, nil
-}
-
-func validateDocsHistoryPageSize(pageSize int) error {
-	if pageSize < 1 || pageSize > 20 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --page-size %d: must be between 1 and 20", pageSize).WithParam("--page-size")
-	}
-	return nil
-}
-
-func validateDocsHistoryVersionID(historyVersionID string) error {
-	version, err := strconv.ParseInt(strings.TrimSpace(historyVersionID), 10, 64)
-	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--history-version-id must be a positive integer string returned by docs +history-list").WithParam("--history-version-id").WithCause(err)
-	}
-	if version <= 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--history-version-id must be a positive integer string returned by docs +history-list").WithParam("--history-version-id")
-	}
-	return nil
-}
-
-func validateDocsHistoryWaitTimeout(timeoutMs int) error {
-	if timeoutMs < 0 || timeoutMs > 30000 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --wait-timeout-ms %d: must be between 0 and 30000", timeoutMs).WithParam("--wait-timeout-ms")
-	}
-	return nil
-}
-
-func docsHistoryListParams(spec docsHistoryListSpec) map[string]interface{} {
-	params := map[string]interface{}{
-		"page_size": spec.PageSize,
-	}
-	if spec.PageToken != "" {
-		params["page_token"] = spec.PageToken
-	}
-	return params
-}
-
-func docsHistoryRevertBody(spec docsHistoryRevertSpec) map[string]interface{} {
-	return map[string]interface{}{
-		"history_version_id": spec.HistoryVersionID,
-		"wait_timeout_ms":    spec.WaitTimeoutMs,
-	}
-}
-
-func docsHistoryStatusParams(spec docsHistoryRevertStatusSpec) map[string]interface{} {
-	return map[string]interface{}{
-		"task_id": spec.TaskID,
-	}
-}
-
-func docsHistoryAPIPath(docToken, suffix string) string {
-	return fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/%s", validate.EncodePathSegment(docToken), suffix)
-}
-
-var DocsHistoryList = common.Shortcut{
-	Service:     "docs",
-	Command:     "+history-list",
-	Description: "List Lark document history versions",
-	Risk:        "read",
-	Scopes:      []string{"docx:document:readonly"},
-	AuthTypes:   []string{"user", "bot"},
-	PostMount:   installDocsShortcutHelp("+history-list"),
-	Flags: []common.Flag{
-		{Name: "doc", Desc: "document URL or token", Required: true},
-		{Name: "page-size", Type: "int", Default: "20", Desc: "history entries to return, range 1-20"},
-		{Name: "page-token", Desc: "pagination token from the previous page's page_token"},
-	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list"); err != nil {
-			return err
-		}
-		return validateDocsHistoryPageSize(runtime.Int("page-size"))
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list")
-		spec := docsHistoryListSpec{
-			Doc:       ref,
-			PageSize:  runtime.Int("page-size"),
-			PageToken: strings.TrimSpace(runtime.Str("page-token")),
-		}
-		return common.NewDryRunAPI().
-			Desc("OpenAPI: list document history versions").
-			GET("/open-apis/docs_ai/v1/documents/:document_id/histories").
-			Set("document_id", spec.Doc.Token).
-			Params(docsHistoryListParams(spec))
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list")
-		spec := docsHistoryListSpec{
-			Doc:       ref,
-			PageSize:  runtime.Int("page-size"),
-			PageToken: strings.TrimSpace(runtime.Str("page-token")),
-		}
-
-		data, err := runtime.CallAPITyped(
-			http.MethodGet,
-			docsHistoryAPIPath(spec.Doc.Token, "histories"),
-			docsHistoryListParams(spec),
-			nil,
-		)
-		if err != nil {
-			return err
-		}
-		runtime.OutRaw(data, nil)
-		return nil
-	},
-}
-
-var DocsHistoryRevert = common.Shortcut{
-	Service:     "docs",
-	Command:     "+history-revert",
-	Description: "Revert a Lark document to a historical version",
-	Risk:        "write",
-	Scopes:      []string{"docx:document:write_only", "docx:document:readonly"},
-	AuthTypes:   []string{"user", "bot"},
-	PostMount:   installDocsShortcutHelp("+history-revert"),
-	Flags: []common.Flag{
-		{Name: "doc", Desc: "document URL or token", Required: true},
-		{Name: "history-version-id", Desc: "history_version_id from docs +history-list to revert to", Required: true},
-		{Name: "wait-timeout-ms", Type: "int", Default: "30000", Desc: "milliseconds to wait for revert completion before returning, range 0-30000"},
-	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert"); err != nil {
-			return err
-		}
-		if err := validateDocsHistoryVersionID(runtime.Str("history-version-id")); err != nil {
-			return err
-		}
-		return validateDocsHistoryWaitTimeout(runtime.Int("wait-timeout-ms"))
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert")
-		spec := docsHistoryRevertSpec{
-			Doc:              ref,
-			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
-			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
-		}
-		return common.NewDryRunAPI().
-			Desc("OpenAPI: revert document history").
-			POST("/open-apis/docs_ai/v1/documents/:document_id/history/revert").
-			Set("document_id", spec.Doc.Token).
-			Body(docsHistoryRevertBody(spec))
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert")
-		spec := docsHistoryRevertSpec{
-			Doc:              ref,
-			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
-			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
-		}
-
-		data, err := runtime.CallAPITyped(
-			http.MethodPost,
-			docsHistoryAPIPath(spec.Doc.Token, "history/revert"),
-			nil,
-			docsHistoryRevertBody(spec),
-		)
-		if err != nil {
-			return err
-		}
-		runtime.OutRaw(data, nil)
-		return nil
-	},
-}
-
-var DocsHistoryRevertStatus = common.Shortcut{
-	Service:     "docs",
-	Command:     "+history-revert-status",
-	Description: "Get Lark document history revert task status",
-	Risk:        "read",
-	Scopes:      []string{"docx:document:readonly"},
-	AuthTypes:   []string{"user", "bot"},
-	PostMount:   installDocsShortcutHelp("+history-revert-status"),
-	Flags: []common.Flag{
-		{Name: "doc", Desc: "document URL or token", Required: true},
-		{Name: "task-id", Desc: "task_id returned by docs +history-revert", Required: true},
-	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status"); err != nil {
-			return err
-		}
-		if strings.TrimSpace(runtime.Str("task-id")) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--task-id is required").WithParam("--task-id")
-		}
-		return nil
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status")
-		spec := docsHistoryRevertStatusSpec{
-			Doc:    ref,
-			TaskID: strings.TrimSpace(runtime.Str("task-id")),
-		}
-		return common.NewDryRunAPI().
-			Desc("OpenAPI: get document history revert status").
-			GET("/open-apis/docs_ai/v1/documents/:document_id/history/revert_status").
-			Set("document_id", spec.Doc.Token).
-			Params(docsHistoryStatusParams(spec))
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status")
-		spec := docsHistoryRevertStatusSpec{
-			Doc:    ref,
-			TaskID: strings.TrimSpace(runtime.Str("task-id")),
-		}
-
-		data, err := runtime.CallAPITyped(
-			http.MethodGet,
-			docsHistoryAPIPath(spec.Doc.Token, "history/revert_status"),
-			docsHistoryStatusParams(spec),
-			nil,
-		)
-		if err != nil {
-			return err
-		}
-		runtime.OutRaw(data, nil)
-		return nil
-	},
-}

shortcuts/doc/docs_history_test.go

@@ -1,340 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/shortcuts/common"
-	"github.com/spf13/cobra"
-)
-
-func TestDocsHistoryValidation(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name      string
-		shortcut  common.Shortcut
-		args      []string
-		param     string
-		category  errs.Category
-		subtype   errs.Subtype
-		wantCause bool
-	}{
-		{
-			name:     "list rejects legacy doc URL",
-			shortcut: DocsHistoryList,
-			args:     []string{"+history-list", "--doc", "https://example.feishu.cn/doc/old_doc", "--as", "bot"},
-			param:    "--doc",
-			category: errs.CategoryValidation,
-			subtype:  errs.SubtypeInvalidArgument,
-		},
-		{
-			name:     "list rejects invalid page size",
-			shortcut: DocsHistoryList,
-			args:     []string{"+history-list", "--doc", "doxcnHistory", "--page-size", "0", "--as", "bot"},
-			param:    "--page-size",
-			category: errs.CategoryValidation,
-			subtype:  errs.SubtypeInvalidArgument,
-		},
-		{
-			name:      "revert rejects non-numeric history version id",
-			shortcut:  DocsHistoryRevert,
-			args:      []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "abc", "--as", "bot"},
-			param:     "--history-version-id",
-			category:  errs.CategoryValidation,
-			subtype:   errs.SubtypeInvalidArgument,
-			wantCause: true,
-		},
-		{
-			name:     "revert rejects non-positive history version id",
-			shortcut: DocsHistoryRevert,
-			args:     []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "0", "--as", "bot"},
-			param:    "--history-version-id",
-			category: errs.CategoryValidation,
-			subtype:  errs.SubtypeInvalidArgument,
-		},
-		{
-			name:     "revert rejects invalid wait timeout",
-			shortcut: DocsHistoryRevert,
-			args:     []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "10", "--wait-timeout-ms", "30001", "--as", "bot"},
-			param:    "--wait-timeout-ms",
-			category: errs.CategoryValidation,
-			subtype:  errs.SubtypeInvalidArgument,
-		},
-		{
-			name:     "status rejects empty task id",
-			shortcut: DocsHistoryRevertStatus,
-			args:     []string{"+history-revert-status", "--doc", "doxcnHistory", "--task-id", "", "--as", "bot"},
-			param:    "--task-id",
-			category: errs.CategoryValidation,
-			subtype:  errs.SubtypeInvalidArgument,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-validation"))
-			err := mountAndRunDocs(t, tt.shortcut, tt.args, f, stdout)
-			if err == nil {
-				t.Fatal("expected validation error, got nil")
-			}
-			problem, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("error is not typed: %T %v", err, err)
-			}
-			if problem.Category != tt.category {
-				t.Fatalf("category = %q, want %q (err: %v)", problem.Category, tt.category, err)
-			}
-			if problem.Subtype != tt.subtype {
-				t.Fatalf("subtype = %q, want %q (err: %v)", problem.Subtype, tt.subtype, err)
-			}
-			var validationErr *errs.ValidationError
-			if !errors.As(err, &validationErr) {
-				t.Fatalf("expected validation error, got %T: %v", err, err)
-			}
-			if validationErr.Param != tt.param {
-				t.Fatalf("param = %q, want %q (err: %v)", validationErr.Param, tt.param, err)
-			}
-			if tt.wantCause && errors.Unwrap(err) == nil {
-				t.Fatalf("expected wrapped cause, got nil (err: %v)", err)
-			}
-		})
-	}
-}
-
-func TestDocsHistoryDryRun(t *testing.T) {
-	t.Parallel()
-
-	listCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryList, map[string]string{
-		"doc":        "doxcnHistoryDryRun",
-		"page-size":  "5",
-		"page-token": "page_token_1",
-	})
-	listDry := decodeDocDryRun(t, DocsHistoryList.DryRun(context.Background(), common.TestNewRuntimeContext(listCmd, nil)))
-	if got, want := listDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/histories"; got != want {
-		t.Fatalf("list dry-run URL = %q, want %q", got, want)
-	}
-	if got := int(listDry.API[0].Params["page_size"].(float64)); got != 5 {
-		t.Fatalf("list page_size = %d, want 5", got)
-	}
-	if got := listDry.API[0].Params["page_token"]; got != "page_token_1" {
-		t.Fatalf("list page_token = %#v, want page_token_1", got)
-	}
-
-	revertCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryRevert, map[string]string{
-		"doc":                "doxcnHistoryDryRun",
-		"history-version-id": "42",
-		"wait-timeout-ms":    "30000",
-	})
-	revertDry := decodeDocDryRun(t, DocsHistoryRevert.DryRun(context.Background(), common.TestNewRuntimeContext(revertCmd, nil)))
-	if got, want := revertDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/history/revert"; got != want {
-		t.Fatalf("revert dry-run URL = %q, want %q", got, want)
-	}
-	if got := revertDry.API[0].Body["history_version_id"]; got != "42" {
-		t.Fatalf("revert history_version_id = %#v, want 42", got)
-	}
-	if got := int(revertDry.API[0].Body["wait_timeout_ms"].(float64)); got != 30000 {
-		t.Fatalf("revert wait_timeout_ms = %d, want 30000", got)
-	}
-
-	statusCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryRevertStatus, map[string]string{
-		"doc":     "doxcnHistoryDryRun",
-		"task-id": "task_1",
-	})
-	statusDry := decodeDocDryRun(t, DocsHistoryRevertStatus.DryRun(context.Background(), common.TestNewRuntimeContext(statusCmd, nil)))
-	if got, want := statusDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/history/revert_status"; got != want {
-		t.Fatalf("status dry-run URL = %q, want %q", got, want)
-	}
-	if got := statusDry.API[0].Params["task_id"]; got != "task_1" {
-		t.Fatalf("status task_id = %#v, want task_1", got)
-	}
-}
-
-func TestDocsHistoryExecuteList(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-list"))
-	stub := &httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/histories",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"data": map[string]interface{}{
-				"entries": []interface{}{
-					map[string]interface{}{
-						"revision_id":        float64(42),
-						"history_version_id": "11",
-						"edit_time":          "1780000000",
-						"type":               float64(1),
-						"editor_ids":         []interface{}{"ou_1"},
-					},
-				},
-				"has_more":   true,
-				"page_token": "page_token_2",
-			},
-		},
-	}
-	reg.Register(stub)
-
-	err := mountAndRunDocs(t, DocsHistoryList, []string{
-		"+history-list",
-		"--doc", "doxcnHistory",
-		"--page-size", "5",
-		"--page-token", "page_token_1",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data := decodeDocsHistoryEnvelope(t, stdout)
-	if got := data["page_token"]; got != "page_token_2" {
-		t.Fatalf("page_token = %#v, want page_token_2", got)
-	}
-	entries, _ := data["entries"].([]interface{})
-	if len(entries) != 1 {
-		t.Fatalf("entries = %#v, want one entry", data["entries"])
-	}
-}
-
-func TestDocsHistoryExecuteRevert(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-revert"))
-	stub := &httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/history/revert",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"data": map[string]interface{}{
-				"task_id":            "task_1",
-				"status":             "running",
-				"history_version_id": "42",
-				"poll_after_ms":      float64(10000),
-			},
-		},
-	}
-	reg.Register(stub)
-
-	err := mountAndRunDocs(t, DocsHistoryRevert, []string{
-		"+history-revert",
-		"--doc", "doxcnHistory",
-		"--history-version-id", "42",
-		"--wait-timeout-ms", "0",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	var body map[string]interface{}
-	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
-		t.Fatalf("decode revert body: %v\nraw=%s", err, stub.CapturedBody)
-	}
-	if got := body["history_version_id"]; got != "42" {
-		t.Fatalf("history_version_id = %#v, want 42", got)
-	}
-	if got := int(body["wait_timeout_ms"].(float64)); got != 0 {
-		t.Fatalf("wait_timeout_ms = %d, want 0", got)
-	}
-
-	data := decodeDocsHistoryEnvelope(t, stdout)
-	if got := data["task_id"]; got != "task_1" {
-		t.Fatalf("task_id = %#v, want task_1", got)
-	}
-}
-
-func TestDocsHistoryExecuteRevertStatus(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-status"))
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/history/revert_status",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"data": map[string]interface{}{
-				"status":              "partial_failed",
-				"history_version_id":  "11",
-				"failed_block_tokens": []interface{}{"blk_1"},
-			},
-		},
-	})
-
-	err := mountAndRunDocs(t, DocsHistoryRevertStatus, []string{
-		"+history-revert-status",
-		"--doc", "doxcnHistory",
-		"--task-id", "task_1",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data := decodeDocsHistoryEnvelope(t, stdout)
-	if got := data["status"]; got != "partial_failed" {
-		t.Fatalf("status = %#v, want partial_failed", got)
-	}
-	if got := data["history_version_id"]; got != "11" {
-		t.Fatalf("history_version_id = %#v, want 11", got)
-	}
-	failed, _ := data["failed_block_tokens"].([]interface{})
-	if len(failed) != 1 || failed[0] != "blk_1" {
-		t.Fatalf("failed_block_tokens = %#v, want [blk_1]", data["failed_block_tokens"])
-	}
-}
-
-func newDocsHistoryRuntimeCmd(t *testing.T, shortcut common.Shortcut, values map[string]string) *cobra.Command {
-	t.Helper()
-
-	cmd := &cobra.Command{Use: shortcut.Command}
-	for _, flag := range shortcut.Flags {
-		switch flag.Type {
-		case "int":
-			cmd.Flags().Int(flag.Name, 0, flag.Desc)
-		default:
-			cmd.Flags().String(flag.Name, flag.Default, flag.Desc)
-		}
-	}
-	for name, value := range values {
-		if err := cmd.Flags().Set(name, value); err != nil {
-			t.Fatalf("set --%s: %v", name, err)
-		}
-	}
-	return cmd
-}
-
-func decodeDocsHistoryEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
-	t.Helper()
-
-	var envelope map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-		t.Fatalf("decode envelope: %v\nraw=%s", err, stdout.String())
-	}
-	data, _ := envelope["data"].(map[string]interface{})
-	if data == nil {
-		t.Fatalf("missing data in envelope: %#v", envelope)
-	}
-	return data
-}
-
-func TestDocsHistoryURLValidationMessage(t *testing.T) {
-	t.Parallel()
-
-	_, err := parseDocsHistoryDocRef("https://example.feishu.cn/doc/old_doc", "+history-list")
-	if err == nil {
-		t.Fatal("expected error")
-	}
-	if !strings.Contains(err.Error(), "only supports docx documents") {
-		t.Fatalf("unexpected error: %v", err)
-	}
-}

shortcuts/doc/shortcuts.go

@@ -31,8 +31,6 @@ func docsSkillReadCommandForShortcut(shortcut string) string {
 		return docsSkillReadCommand + " references/lark-doc-fetch.md"
 	case "update":
 		return docsSkillReadCommand + " references/lark-doc-update.md"
-	case "history-list", "history-revert", "history-revert-status":
-		return docsSkillReadCommand + " references/lark-doc-history.md"
 	default:
 		return docsSkillReadCommand
 	}
@@ -46,12 +44,6 @@ func docsHelpCommandForShortcut(shortcut string) string {
 		return "lark-cli docs +fetch --help"
 	case "update":
 		return "lark-cli docs +update --help"
-	case "history-list":
-		return "lark-cli docs +history-list --help"
-	case "history-revert":
-		return "lark-cli docs +history-revert --help"
-	case "history-revert-status":
-		return "lark-cli docs +history-revert-status --help"
 	default:
 		return "lark-cli docs --help"
 	}
@@ -64,9 +56,6 @@ func Shortcuts() []common.Shortcut {
 		DocsCreate,
 		DocsFetch,
 		DocsUpdate,
-		DocsHistoryList,
-		DocsHistoryRevert,
-		DocsHistoryRevertStatus,
 		DocMediaInsert,
 		DocMediaUpload,
 		DocMediaPreview,

shortcuts/drive/drive_import_common.go

@@ -8,7 +8,6 @@ import (
 	"encoding/json"
 	"fmt"
 	"path/filepath"
-	"strconv"
 	"strings"
 	"time"
 
@@ -29,8 +28,6 @@ const (
 	driveImport500MBFileSizeLimit int64 = 500 * 1024 * 1024
 	driveImport600MBFileSizeLimit int64 = 600 * 1024 * 1024
 	driveImport800MBFileSizeLimit int64 = 800 * 1024 * 1024
-
-	driveImportConcurrentOperationHint = "This import conflict means another operation is running in the same Drive location. Run batch imports to the same folder/root or target bitable serially. Wait a few seconds before retrying each failed import; retry each failed item at most 3 times, then stop and report the conflict."
 )
 
 // driveImportExtToDocTypes defines which source file extensions can be imported
@@ -50,8 +47,6 @@ var driveImportExtToDocTypes = map[string][]string{
 	"pptx":     {"slides"},
 }
 
-var driveImportConcurrentOperationCodes = []int{232140101, 232140100, 233523001}
-
 // driveImportSpec contains the user-facing import inputs after normalization.
 type driveImportSpec struct {
 	FilePath    string
@@ -432,7 +427,11 @@ func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveIm
 			return status, true, nil
 		}
 		if status.Failed() {
-			return status, false, driveImportFailureError(status)
+			msg := strings.TrimSpace(status.JobErrorMsg)
+			if msg == "" {
+				msg = status.StatusLabel()
+			}
+			return status, false, errs.NewAPIError(errs.SubtypeServerError, "import failed with status %d: %s", status.JobStatus, msg)
 		}
 	}
 	if !hadSuccessfulPoll && lastErr != nil {
@@ -441,40 +440,3 @@ func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveIm
 
 	return lastStatus, false, nil
 }
-
-func driveImportFailureError(status driveImportStatus) *errs.APIError {
-	msg := strings.TrimSpace(status.JobErrorMsg)
-	if msg == "" {
-		msg = status.StatusLabel()
-	}
-
-	apiErr := errs.NewAPIError(errs.SubtypeServerError, "import failed with status %d: %s", status.JobStatus, msg)
-	if code, ok := driveImportConcurrentOperationCode(msg); ok {
-		apiErr = apiErr.WithCode(code).WithRetryable().WithHint(driveImportConcurrentOperationHint)
-	}
-	return apiErr
-}
-
-func driveImportConcurrentOperationCode(msg string) (int, bool) {
-	for _, code := range driveImportConcurrentOperationCodes {
-		codeText := strconv.Itoa(code)
-		for idx := strings.Index(msg, codeText); idx >= 0; {
-			end := idx + len(codeText)
-			if (idx == 0 || !isASCIIDigit(msg[idx-1])) && (end == len(msg) || !isASCIIDigit(msg[end])) {
-				return code, true
-			}
-
-			nextStart := idx + 1
-			next := strings.Index(msg[nextStart:], codeText)
-			if next < 0 {
-				break
-			}
-			idx = nextStart + next
-		}
-	}
-	return 0, false
-}
-
-func isASCIIDigit(ch byte) bool {
-	return ch >= '0' && ch <= '9'
-}

shortcuts/drive/drive_import_common_test.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"errors"
 	"os"
-	"strconv"
 	"strings"
 	"testing"
 
@@ -212,82 +211,6 @@ func TestDriveImportStatusPendingWithoutToken(t *testing.T) {
 	}
 }
 
-func TestDriveImportFailureErrorAddsConcurrentOperationGuidance(t *testing.T) {
-	t.Parallel()
-
-	for _, code := range driveImportConcurrentOperationCodes {
-		t.Run(strconv.Itoa(code), func(t *testing.T) {
-			t.Parallel()
-
-			err := driveImportFailureError(driveImportStatus{
-				JobStatus:   3,
-				JobErrorMsg: "call CreateObjNode return error code, code: " + strconv.Itoa(code) + ", message:",
-			})
-			problem, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("expected typed error, got %T", err)
-			}
-			if problem.Category != errs.CategoryAPI {
-				t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryAPI)
-			}
-			if problem.Subtype != errs.SubtypeServerError {
-				t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeServerError)
-			}
-			if problem.Code != code {
-				t.Fatalf("code = %d, want %d", problem.Code, code)
-			}
-			if !problem.Retryable {
-				t.Fatal("expected retryable error")
-			}
-			if problem.Hint != driveImportConcurrentOperationHint {
-				t.Fatalf("hint = %q, want %q", problem.Hint, driveImportConcurrentOperationHint)
-			}
-		})
-	}
-}
-
-func TestDriveImportFailureErrorLeavesOtherFailuresUnchanged(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name string
-		msg  string
-	}{
-		{
-			name: "ordinary failure",
-			msg:  "unsupported conversion",
-		},
-		{
-			name: "longer numeric code containing known code",
-			msg:  "call CreateObjNode return error code, code: 12321401012, message:",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			err := driveImportFailureError(driveImportStatus{
-				JobStatus:   3,
-				JobErrorMsg: tt.msg,
-			})
-			problem, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("expected typed error, got %T", err)
-			}
-			if problem.Code != 0 {
-				t.Fatalf("code = %d, want 0", problem.Code)
-			}
-			if problem.Retryable {
-				t.Fatal("expected non-concurrency failure to remain non-retryable")
-			}
-			if problem.Hint != "" {
-				t.Fatalf("hint = %q, want empty", problem.Hint)
-			}
-		})
-	}
-}
-
 func TestDriveImportTimeoutReturnsFollowUpCommand(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	reg.Register(&httpmock.Stub{

shortcuts/drive/drive_search.go

@@ -75,7 +75,7 @@ var DriveSearch = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags: []common.Flag{
-		{Name: "query", Desc: "search keyword (may be empty to browse by filter only); max 30 characters by Unicode code point (CJK counts 1 each), over 30 the server rejects with 99992402 field validation failed"},
+		{Name: "query", Desc: "search keyword (may be empty to browse by filter only)"},
 
 		{Name: "mine", Type: "bool", Desc: "restrict to docs I own (server-side owner semantic, NOT original creator; uses current user's open_id)"},
 		{Name: "creator-ids", Desc: "comma-separated owner open_ids (API field is creator_ids but matched by owner); mutually exclusive with --mine"},

shortcuts/minutes/minutes_speaker_replace.go

@@ -66,24 +66,31 @@ var MinutesSpeakerReplace = common.Shortcut{
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
-		return common.NewDryRunAPI().
-			PUT(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken))).
+		dr := common.NewDryRunAPI()
+		if strings.TrimSpace(runtime.Str("from-speaker-id")) != "" && strings.TrimSpace(runtime.Str("from-user-id")) == "" {
+			dr.GET(minuteTranscriptSpeakerlistPath(minuteToken)).Desc("Resolve --from-speaker-id when it is a display name")
+		}
+		return dr.PUT(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken))).
 			Body(buildSpeakerReplaceRequestBody(runtime))
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
-		fromSpeakerID := strings.TrimSpace(runtime.Str("from-speaker-id"))
-		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
+		fromSpeakerInput := strings.TrimSpace(runtime.Str("from-speaker-id"))
 		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
 
-		_, err := runtime.CallAPITyped(http.MethodPut,
+		fromSpeakerID, fromUserID, err := resolveSpeakerReplaceFrom(runtime, minuteToken)
+		if err != nil {
+			return err
+		}
+
+		_, err = runtime.CallAPITyped(http.MethodPut,
 			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken)),
 			map[string]interface{}{"user_id_type": "open_id"}, buildSpeakerReplaceRequestBodyResolved(fromSpeakerID, fromUserID, toUserID))
 		if err != nil {
-			return minutesSpeakerReplaceError(err, minuteToken, speakerReplaceSourceLabel(fromSpeakerID, fromUserID))
+			return minutesSpeakerReplaceError(err, minuteToken, speakerReplaceSourceLabel(fromSpeakerInput, fromSpeakerID, fromUserID))
 		}
 
-		runtime.OutFormat(buildSpeakerReplaceOutputData(minuteToken, fromSpeakerID, fromUserID, toUserID), nil, nil)
+		runtime.OutFormat(buildSpeakerReplaceOutputData(fromSpeakerInput, minuteToken, fromSpeakerID, fromUserID, toUserID), nil, nil)
 		return nil
 	},
 }
@@ -107,20 +114,26 @@ func buildSpeakerReplaceRequestBodyResolved(fromSpeakerID, fromUserID, toUserID
 	return body
 }
 
-func buildSpeakerReplaceOutputData(minuteToken, fromSpeakerID, fromUserID, toUserID string) map[string]interface{} {
+func buildSpeakerReplaceOutputData(fromSpeakerInput, minuteToken, fromSpeakerID, fromUserID, toUserID string) map[string]interface{} {
 	out := map[string]interface{}{
 		"minute_token": minuteToken,
 		"to_user_id":   toUserID,
 	}
 	if fromSpeakerID != "" {
 		out["from_speaker_id"] = fromSpeakerID
+		if fromSpeakerInput != "" && fromSpeakerInput != fromSpeakerID {
+			out["from_speaker_input"] = fromSpeakerInput
+		}
 	} else {
 		out["from_user_id"] = fromUserID
 	}
 	return out
 }
 
-func speakerReplaceSourceLabel(fromSpeakerID, fromUserID string) string {
+func speakerReplaceSourceLabel(fromSpeakerInput, fromSpeakerID, fromUserID string) string {
+	if fromSpeakerInput != "" {
+		return fromSpeakerInput
+	}
 	if fromSpeakerID != "" {
 		return fromSpeakerID
 	}

shortcuts/minutes/minutes_speaker_replace_test.go

@@ -153,14 +153,58 @@ func TestMinutesSpeakerReplace_DryRun(t *testing.T) {
 	}
 }
 
-func TestMinutesSpeakerReplace_Execute_OpaqueSpeakerIDNoPrefetch(t *testing.T) {
+func TestMinutesSpeakerReplace_DryRun_ResolveFromSpeakerID(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	err := mountAndRun(t, MinutesSpeakerReplace, []string{
+		"+speaker-replace",
+		"--minute-token", minutesSpeakerReplaceTestToken,
+		"--from-speaker-id", "说话人1",
+		"--to-user-id", "ou_new_speaker",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, "GET") {
+		t.Errorf("expected GET for internal speaker list, got:\n%s", out)
+	}
+	if !strings.Contains(out, "/transcript/speakerlist") {
+		t.Errorf("expected speakerlist path, got:\n%s", out)
+	}
+	if !strings.Contains(out, "PUT") {
+		t.Errorf("expected PUT for speaker replace, got:\n%s", out)
+	}
+	if !strings.Contains(out, "ou_new_speaker") {
+		t.Errorf("expected to_user_id in body, got:\n%s", out)
+	}
+}
+
+func TestMinutesSpeakerReplace_Execute_ResolveFromSpeakerID(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	warmTokenCache(t)
 
-	// Only the PUT is registered on purpose: an opaque speaker_id must be passed
-	// straight through without a second speakerlist call. If the code still
-	// prefetched speakerlist, the unregistered GET would fail the request.
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speakerlist",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"speakers": []interface{}{
+					map[string]interface{}{
+						"speaker_id": "ENCRYPTED_TOKEN_ABC",
+						"name":       "说话人1",
+					},
+				},
+			},
+		},
+	})
 	reg.Register(&httpmock.Stub{
 		Method: http.MethodPut,
 		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speaker",
@@ -174,7 +218,7 @@ func TestMinutesSpeakerReplace_Execute_OpaqueSpeakerIDNoPrefetch(t *testing.T) {
 	err := mountAndRun(t, MinutesSpeakerReplace, []string{
 		"+speaker-replace",
 		"--minute-token", minutesSpeakerReplaceTestToken,
-		"--from-speaker-id", "ENCRYPTED_TOKEN_ABC",
+		"--from-speaker-id", "说话人1",
 		"--to-user-id", "ou_new_speaker",
 		"--format", "json", "--as", "user",
 	}, f, stdout)
@@ -184,19 +228,21 @@ func TestMinutesSpeakerReplace_Execute_OpaqueSpeakerIDNoPrefetch(t *testing.T) {
 
 	var envelope struct {
 		Data struct {
-			FromSpeakerID string `json:"from_speaker_id"`
-			ToUserID      string `json:"to_user_id"`
+			MinuteToken      string `json:"minute_token"`
+			FromSpeakerInput string `json:"from_speaker_input"`
+			FromSpeakerID    string `json:"from_speaker_id"`
+			ToUserID         string `json:"to_user_id"`
 		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
 		t.Fatalf("unmarshal stdout: %v", err)
 	}
+	if envelope.Data.FromSpeakerInput != "说话人1" {
+		t.Errorf("data.from_speaker_input = %q, want 说话人1", envelope.Data.FromSpeakerInput)
+	}
 	if envelope.Data.FromSpeakerID != "ENCRYPTED_TOKEN_ABC" {
 		t.Errorf("data.from_speaker_id = %q, want ENCRYPTED_TOKEN_ABC", envelope.Data.FromSpeakerID)
 	}
-	if envelope.Data.ToUserID != "ou_new_speaker" {
-		t.Errorf("data.to_user_id = %q, want ou_new_speaker", envelope.Data.ToUserID)
-	}
 }
 
 func TestMinutesSpeakerReplace_DryRun_FromSpeakerID(t *testing.T) {
@@ -216,11 +262,8 @@ func TestMinutesSpeakerReplace_DryRun_FromSpeakerID(t *testing.T) {
 	}
 
 	out := stdout.String()
-	if strings.Contains(out, "/transcript/speakerlist") {
-		t.Errorf("opaque speaker_id should not prefetch speakerlist, got:\n%s", out)
-	}
-	if !strings.Contains(out, "PUT") {
-		t.Errorf("expected PUT for speaker replace, got:\n%s", out)
+	if !strings.Contains(out, "GET") {
+		t.Errorf("expected GET for internal speaker list, got:\n%s", out)
 	}
 	if !strings.Contains(out, "from_speaker_id") || !strings.Contains(out, "ENCRYPTED_TOKEN_ABC") {
 		t.Errorf("expected from_speaker_id in body, got:\n%s", out)

shortcuts/minutes/minutes_speakers.go

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type minuteSpeaker struct {
+	SpeakerID string
+	Name      string
+}
+
+func minuteTranscriptSpeakerlistPath(minuteToken string) string {
+	return fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speakerlist", validate.EncodePathSegment(minuteToken))
+}
+
+func fetchMinuteSpeakers(runtime *common.RuntimeContext, minuteToken string) ([]minuteSpeaker, error) {
+	data, err := runtime.CallAPITyped(http.MethodGet, minuteTranscriptSpeakerlistPath(minuteToken), nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if data == nil {
+		return nil, nil
+	}
+
+	items := common.GetSlice(data, "speakers")
+	speakers := make([]minuteSpeaker, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		if item == nil {
+			continue
+		}
+		id := strings.TrimSpace(common.GetString(item, "speaker_id"))
+		name := strings.TrimSpace(common.GetString(item, "name"))
+		if id == "" {
+			continue
+		}
+		speakers = append(speakers, minuteSpeaker{SpeakerID: id, Name: name})
+	}
+	return speakers, nil
+}
+
+func resolveSpeakerIDByName(speakers []minuteSpeaker, name string) (string, error) {
+	name = strings.TrimSpace(name)
+	var matches []minuteSpeaker
+	for _, s := range speakers {
+		if s.Name == name {
+			matches = append(matches, s)
+		}
+	}
+	switch len(matches) {
+	case 0:
+		return "", errs.NewValidationError(errs.SubtypeNotFound,
+			"no speaker named %q in minute transcript", name).
+			WithParam("--from-speaker-id").
+			WithHint("Check the speaker name spelling or open the minute to see transcript speaker labels")
+	case 1:
+		return matches[0].SpeakerID, nil
+	default:
+		ids := make([]string, len(matches))
+		for i, m := range matches {
+			ids[i] = m.SpeakerID
+		}
+		return "", errs.NewValidationError(errs.SubtypeFailedPrecondition,
+			"multiple speakers named %q (%d matches); pass the exact --from-speaker-id", name, len(matches)).
+			WithParam("--from-speaker-id").
+			WithHint(fmt.Sprintf("Matching speaker_ids: %s. Review each speaker's utterances in the minute, then retry with the exact speaker_id", strings.Join(ids, ", ")))
+	}
+}
+
+// resolveFromSpeakerID resolves --from-speaker-id to an API speaker_id.
+// The input may already be an opaque speaker_id, or a display name that requires
+// an internal speaker-list fetch.
+func resolveFromSpeakerID(runtime *common.RuntimeContext, minuteToken, input string) (string, error) {
+	input = strings.TrimSpace(input)
+	speakers, err := fetchMinuteSpeakers(runtime, minuteToken)
+	if err != nil {
+		return "", err
+	}
+	for _, s := range speakers {
+		if s.SpeakerID == input {
+			return input, nil
+		}
+	}
+	return resolveSpeakerIDByName(speakers, input)
+}
+
+func resolveSpeakerReplaceFrom(runtime *common.RuntimeContext, minuteToken string) (fromSpeakerID, fromUserID string, err error) {
+	fromUserID = strings.TrimSpace(runtime.Str("from-user-id"))
+	if fromUserID != "" {
+		return "", fromUserID, nil
+	}
+
+	fromSpeakerID, err = resolveFromSpeakerID(runtime, minuteToken, runtime.Str("from-speaker-id"))
+	return fromSpeakerID, "", err
+}

shortcuts/minutes/minutes_speakers_test.go

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+func TestResolveSpeakerIDByName(t *testing.T) {
+	speakers := []minuteSpeaker{
+		{SpeakerID: "id_a", Name: "Alice"},
+		{SpeakerID: "id_b", Name: "Bob"},
+		{SpeakerID: "id_c", Name: "Alice"},
+	}
+
+	id, err := resolveSpeakerIDByName(speakers, "Bob")
+	if err != nil || id != "id_b" {
+		t.Fatalf("resolve Bob: id=%q err=%v", id, err)
+	}
+
+	_, err = resolveSpeakerIDByName(speakers, "Carol")
+	if err == nil {
+		t.Fatal("expected not found error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Subtype != errs.SubtypeNotFound {
+		t.Fatalf("want not-found validation error, got %T: %v", err, err)
+	}
+
+	_, err = resolveSpeakerIDByName(speakers, "Alice")
+	if err == nil {
+		t.Fatal("expected duplicate name error")
+	}
+	if !errors.As(err, &ve) || ve.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("want failed-precondition validation error, got %T: %v", err, err)
+	}
+	if !strings.Contains(ve.Hint, "id_a") || !strings.Contains(ve.Hint, "id_c") {
+		t.Errorf("hint should list matching speaker_ids, got: %s", ve.Hint)
+	}
+}

shortcuts/register.go

@@ -205,16 +205,18 @@ func installBrandRestrictionGuard(svc *cobra.Command, service string, brand core
 	svc.Long = fmt.Sprintf("The %q feature is not yet supported on the %s brand.", service, brand)
 }
 
-// Sheets backward-compatibility help grouping.
+// Sheets backward-compatibility grouping.
 //
 // shortcuts/sheets/backward keeps the pre-refactor command names alive so that
 // users whose lark-sheets skill predates the refactor keep working even after
-// upgrading only the binary. In `sheets --help` those aliases would otherwise
-// sort alphabetically into the same flat list as the current commands,
-// indistinguishable from them. applySheetsCompatGroups splits them into a
-// dedicated cobra group whose heading tells the user to update their skill, and
-// appends a "(→ +new-command)" pointer to each alias so the migration target is
-// obvious. Pure presentation — the aliases stay fully executable.
+// upgrading only the binary. applySheetsCompatGroups tags each alias into a
+// dedicated deprecated cobra group. The refactored commands have been the
+// default for over a month, so `sheets --help` no longer lists these aliases:
+// sheetsUsageTemplate renders every group except the deprecated one. The
+// grouping is still applied for two reasons — the unknown-subcommand path
+// (cmd/root.go) keys off it to classify a mistyped legacy alias, and each
+// alias's own `sheets <alias> --help` still surfaces the "(→ +new-command)"
+// migration pointer appended below. The aliases stay fully executable.
 const (
 	sheetsCurrentGroupID = "sheets-current"
 	// sheetsDeprecatedGroupID aliases the shared deprecated-group id so both
@@ -224,9 +226,10 @@ const (
 )
 
 // sheetsAliasReplacement maps each pre-refactor sheets alias to the current
-// command(s) that replace it, shown as a "(→ ...)" suffix in --help. Aliases
-// absent from this map still land in the deprecated group, just without a
-// pointer, so a missing entry degrades gracefully rather than misgrouping.
+// command(s) that replace it, shown as a "(→ ...)" suffix in the alias's own
+// --help and reused by wrapSheetsBackwardDeprecation for the on-execution
+// _notice. Aliases absent from this map still land in the deprecated group,
+// just without a pointer, so a missing entry degrades gracefully.
 var sheetsAliasReplacement = map[string]string{
 	// spreadsheet / sheet management
 	"+create":       "+workbook-create",
@@ -279,6 +282,43 @@ var sheetsAliasReplacement = map[string]string{
 	"+delete-float-image": "+float-image-delete",
 }
 
+// sheetsUsageTemplate is cobra v1.10.2's stock usage template with a single
+// change: the group loop is guarded by {{if ne $group.ID "deprecated"}} so the
+// deprecated pre-refactor aliases are omitted from `sheets --help` altogether.
+// Everything else — current commands, ungrouped metaapi subcommands under
+// "Additional Commands", flags — renders exactly as cobra's default. Keep in
+// sync with cobra's defaultUsageTemplate on upgrade.
+var sheetsUsageTemplate = fmt.Sprintf(`Usage:{{if .Runnable}}
+  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}
+  {{.CommandPath}} [command]{{end}}{{if gt (len .Aliases) 0}}
+
+Aliases:
+  {{.NameAndAliases}}{{end}}{{if .HasExample}}
+
+Examples:
+{{.Example}}{{end}}{{if .HasAvailableSubCommands}}{{$cmds := .Commands}}{{if eq (len .Groups) 0}}
+
+Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{else}}{{range $group := .Groups}}{{if ne $group.ID %q}}
+
+{{.Title}}{{range $cmds}}{{if (and (eq .GroupID $group.ID) (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}}
+
+Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
+
+Flags:
+{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
+
+Global Flags:
+{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
+
+Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
+  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
+
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}
+`, sheetsDeprecatedGroupID)
+
 func applySheetsCompatGroups(svc *cobra.Command) {
 	svc.AddGroup(
 		&cobra.Group{ID: sheetsCurrentGroupID, Title: "Available Commands:"},
@@ -310,6 +350,11 @@ func applySheetsCompatGroups(svc *cobra.Command) {
 			c.GroupID = sheetsCurrentGroupID
 		}
 	}
+
+	// Refactored commands have been the default for over a month: drop the
+	// deprecated group from `sheets --help` (see sheetsUsageTemplate). The
+	// aliases remain grouped and executable, just no longer advertised here.
+	svc.SetUsageTemplate(sheetsUsageTemplate)
 }
 
 // wrapSheetsBackwardDeprecation decorates each backward-compatibility sheets

shortcuts/register_test.go

@@ -170,27 +170,6 @@ func TestRegisterShortcutsMountsDocsMediaPreview(t *testing.T) {
 	}
 }
 
-func TestRegisterShortcutsMountsDocsHistoryCommands(t *testing.T) {
-	program := &cobra.Command{Use: "root"}
-	RegisterShortcuts(program, newRegisterTestFactory(t))
-
-	for _, name := range []string{"+history-list", "+history-revert", "+history-revert-status"} {
-		cmd, _, err := program.Find([]string{"docs", name})
-		if err != nil {
-			t.Fatalf("find docs %s shortcut: %v", name, err)
-		}
-		if cmd == nil || cmd.Name() != name {
-			t.Fatalf("docs %s shortcut not mounted: %#v", name, cmd)
-		}
-		if cmd.Flags().Lookup("api-version") != nil {
-			t.Fatalf("docs %s should not expose --api-version", name)
-		}
-		if !strings.Contains(cmd.Long, "lark-cli skills read lark-doc references/lark-doc-history.md") {
-			t.Fatalf("docs %s help missing history skill guidance:\n%s", name, cmd.Long)
-		}
-	}
-}
-
 func TestRegisterShortcutsDocsHelpAddsSkillReadGuidance(t *testing.T) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))
@@ -532,10 +511,11 @@ func TestApplySheetsCompatGroups(t *testing.T) {
 	}
 }
 
-// End-to-end: the rendered `sheets --help` must surface the deprecated-group
-// heading (telling users to update their skill) plus the per-alias migration
-// pointers, while keeping the refactored shortcuts under Available Commands.
-func TestRegisterShortcutsSheetsHelpGroupsDeprecatedAliases(t *testing.T) {
+// End-to-end: `sheets --help` must list refactored shortcuts under Available
+// Commands, but no longer advertise the deprecated pre-refactor aliases or the
+// deprecated group heading (sheetsUsageTemplate skips that group). The aliases
+// stay registered and executable — hidden from the parent listing, not removed.
+func TestRegisterShortcutsSheetsHelpHidesDeprecatedAliases(t *testing.T) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))
 
@@ -551,19 +531,25 @@ func TestRegisterShortcutsSheetsHelpGroupsDeprecatedAliases(t *testing.T) {
 	}
 	got := out.String()
 
-	for _, want := range []string{
-		"Available Commands:",
-		"Deprecated pre-refactor commands",
-		"update your lark-sheets skill",
-		"+read",
-		"(→ +cells-get)",
-		"+write",
-		"(→ +cells-set)",
-	} {
+	for _, want := range []string{"Available Commands:", "+cells-get"} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("sheets help missing %q:\n%s", want, got)
 		}
 	}
+	for _, unwanted := range []string{
+		"Deprecated pre-refactor commands",
+		"update your lark-sheets skill",
+		"+read",
+		"+write",
+	} {
+		if strings.Contains(got, unwanted) {
+			t.Fatalf("sheets help still shows deprecated content %q:\n%s", unwanted, got)
+		}
+	}
+
+	if alias, _, ferr := sheetsCmd.Find([]string{"+read"}); ferr != nil || alias == nil {
+		t.Fatalf("deprecated alias +read should stay registered, got err=%v cmd=%v", ferr, alias)
+	}
 }
 
 // wrapSheetsBackwardDeprecation must decorate each alias's Execute so that

shortcuts/sheets/backward/lark_sheets_float_images.go

@@ -5,6 +5,7 @@ package backward
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"path/filepath"
 	"strings"
@@ -17,20 +18,30 @@ import (
 
 // Drive media parent_type values for uploading an image into a spreadsheet.
 // Native spreadsheets use "sheet_image"; imported "office" spreadsheets carry a
-// synthetic token prefixed with "fake_office_" and the backend requires
-// "office_sheet_file" instead.
+// synthetic token prefixed with "fake_office_" (being renamed to
+// "local_office_") and the backend requires "office_sheet_file" instead.
 const (
 	sheetImageParentType      = "sheet_image"
 	officeSheetFileParentType = "office_sheet_file"
 	fakeOfficeTokenPrefix     = "fake_office_"
+	localOfficeTokenPrefix    = "local_office_"
 )
 
+// officeTokenPrefixes are the synthetic token prefixes an imported "office"
+// spreadsheet may carry. The prefix is being renamed from "fake_office_" to
+// "local_office_"; accept either so image uploads keep working across the
+// rename.
+var officeTokenPrefixes = []string{fakeOfficeTokenPrefix, localOfficeTokenPrefix}
+
 // sheetMediaParentType returns the drive media parent_type to use when
-// uploading an image whose parent_node is spreadsheetToken, mapping the
-// "fake_office_" imported-spreadsheet token prefix to "office_sheet_file".
+// uploading an image whose parent_node is spreadsheetToken, mapping either the
+// "fake_office_" or "local_office_" imported-spreadsheet token prefix to
+// "office_sheet_file".
 func sheetMediaParentType(spreadsheetToken string) string {
-	if strings.HasPrefix(spreadsheetToken, fakeOfficeTokenPrefix) {
-		return officeSheetFileParentType
+	for _, prefix := range officeTokenPrefixes {
+		if strings.HasPrefix(spreadsheetToken, prefix) {
+			return officeSheetFileParentType
+		}
 	}
 	return sheetImageParentType
 }
@@ -135,7 +146,8 @@ func validateSheetMediaUploadFile(runtime *common.RuntimeContext, filePath strin
 	stat, err := runtime.FileIO().Stat(filePath)
 	if err != nil {
 		wrapped := common.WrapInputStatErrorTyped(err, "file not found")
-		if v, ok := wrapped.(*errs.ValidationError); ok {
+		var v *errs.ValidationError
+		if errors.As(wrapped, &v) {
 			return "", nil, v.WithParam("--file")
 		}
 		return "", nil, wrapped

shortcuts/sheets/batch_op_dispatch.go

@@ -332,11 +332,21 @@ func translateBatchOp(raw interface{}, token string, index int) (map[string]inte
 	}, nil
 }
 
+// maxBatchOperations caps how many sub-operations a single +batch-update may
+// carry. Every translated op (with its own cells/properties payload) is held in
+// the out slice at once before the whole batch is marshaled, so an unbounded
+// operation count is the same unbounded-materialization hazard as the fan-out
+// matrix, on the operations axis.
+const maxBatchOperations = 100
+
 // translateBatchOperations 翻译整个 ops 数组；fail-fast，遇错立即返回。
 func translateBatchOperations(rawOps []interface{}, token string) ([]interface{}, error) {
 	if len(rawOps) == 0 {
 		return nil, sheetsValidationForFlag("operations", "--operations must be a non-empty JSON array")
 	}
+	if len(rawOps) > maxBatchOperations {
+		return nil, sheetsValidationForFlag("operations", "--operations accepts at most %d entries; got %d", maxBatchOperations, len(rawOps))
+	}
 	out := make([]interface{}, 0, len(rawOps))
 	for i, raw := range rawOps {
 		translated, err := translateBatchOp(raw, token, i)

shortcuts/sheets/data/flag-defs.json

@@ -1,4 +1,59 @@
 {
+  "+formula-verify": {
+    "risk": "read",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet token (XOR with `--url`)"
+      },
+      {
+        "name": "sheet-id",
+        "kind": "public",
+        "type": "string_slice",
+        "required": "optional",
+        "desc": "Sheet reference_id(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."
+      },
+      {
+        "name": "sheet-name",
+        "kind": "public",
+        "type": "string_slice",
+        "required": "optional",
+        "desc": "Sheet name(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."
+      },
+      {
+        "name": "range",
+        "kind": "own",
+        "type": "string_slice",
+        "required": "optional",
+        "desc": "Optional A1 ranges (e.g. `A1:Z200`); repeat or comma-separate for multiple ranges. Omit to scan each sheet's current_region."
+      },
+      {
+        "name": "max-locations",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "Max locations / samples per error type; default 20.",
+        "default": "20"
+      },
+      {
+        "name": "exit-on-error",
+        "kind": "own",
+        "type": "bool",
+        "required": "optional",
+        "desc": "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."
+      }
+    ]
+  },
   "+workbook-info": {
     "risk": "read",
     "flags": [
@@ -25,6 +80,32 @@
       }
     ]
   },
+  "+revision-get": {
+    "risk": "read",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
   "+sheet-create": {
     "risk": "write",
     "flags": [
@@ -73,6 +154,14 @@
         "desc": "Initial column count (default 20, max 200)",
         "default": "20"
       },
+      {
+        "name": "type",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "New sub-sheet type: sheet (spreadsheet) | bitable; default sheet. bitable creates an empty table only — edit its content via lark-base commands",
+        "default": "sheet"
+      },
       {
         "name": "dry-run",
         "kind": "system",
@@ -219,7 +308,7 @@
         "kind": "own",
         "type": "int",
         "required": "optional",
-        "desc": "Source position (0-based); optional. If omitted, the CLI runtime derives it from the current workbook index of `--sheet-id` / `--sheet-name`",
+        "desc": "Source position (0-based); optional for standalone calls — if omitted, the CLI runtime derives it from the current workbook index of `--sheet-id` / `--sheet-name`. Inside `+batch-update` it must be passed explicitly, since batch cannot issue a structure query mid-run to derive it",
         "default": "-1"
       },
       {
@@ -515,7 +604,7 @@
         "kind": "own",
         "type": "string",
         "required": "optional",
-        "desc": "Untyped initial data as one 2D JSON array (`[[\"alice\",95]]`); values are written as-is with their type auto-detected, through the same batched set_cell_range path as --sheets — pair with --styles for number formats, colors, merges, and row/col sizes",
+        "desc": "Untyped initial data as one 2D JSON array (`[[\"alice\",95]]`); values are written as-is with their type auto-detected (dates / numbers land as text — use --sheets to preserve types), through the same batched set_cell_range path as --sheets — pair with --styles for number formats, colors, merges, and row/col sizes",
         "input": [
           "file",
           "stdin"
@@ -1069,7 +1158,7 @@
         "kind": "own",
         "type": "int",
         "required": "optional",
-        "desc": "Group nesting level to ungroup; default 1 (outermost)",
+        "desc": "Group nesting level to ungroup; default 1 (1 = outermost, larger = deeper)",
         "default": "1"
       },
       {
@@ -1711,6 +1800,13 @@
         "required": "optional",
         "desc": "Font color (hex, e.g. `#000000`)"
       },
+      {
+        "name": "font-family",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Font family name (e.g. `Arial`, `Microsoft YaHei`)"
+      },
       {
         "name": "font-size",
         "kind": "own",
@@ -2739,7 +2835,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A1:B2\",\"'Sheet2'!D1:D10\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id; ranges may target different sheets; the same style is applied to every range",
+        "desc": "Target ranges as a JSON array (e.g. `[\"Sheet1!A1:B2\",\"Sheet2!D1:D10\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same style is applied to every range",
         "input": [
           "file",
           "stdin"
@@ -2759,6 +2855,13 @@
         "required": "optional",
         "desc": "Font color (hex, e.g. `#000000`)"
       },
+      {
+        "name": "font-family",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Font family name (e.g. `Arial`, `Microsoft YaHei`)"
+      },
       {
         "name": "font-size",
         "kind": "own",
@@ -2885,7 +2988,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A2:A100\",\"'Sheet1'!C2:C100\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id",
+        "desc": "Target ranges as a JSON array (e.g. `[\"Sheet1!A2:A100\",\"Sheet1!C2:C100\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id",
         "input": [
           "file",
           "stdin"
@@ -2965,7 +3068,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Target ranges as a JSON array (up to 100 items, e.g. `[\"'Sheet1'!E2:E6\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id",
+        "desc": "Target ranges as a JSON array (up to 100 items, e.g. `[\"Sheet1!E2:E6\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id",
         "input": [
           "file",
           "stdin"
@@ -3009,7 +3112,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A2:Z1000\",\"'Sheet2'!A2:Z1000\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id; ranges may target different sheets; the same scope is cleared from every range",
+        "desc": "Target ranges as a JSON array (e.g. `[\"Sheet1!A2:Z1000\",\"Sheet2!A2:Z1000\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same scope is cleared from every range",
         "input": [
           "file",
           "stdin"
@@ -3127,7 +3230,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Full chart config JSON. Top-level keys: `position` / `offset` / `size` / `snapshot` (no top-level `data`, no extra nested `properties`); chart data config lives under `snapshot.data` (`refs` / `headerMode` / `dim1` / `dim2`). Deeply nested — run `--print-schema --flag-name properties` for the full structure.",
+        "desc": "Full chart config JSON. Top-level keys: `position` / `offset` / `size` / `snapshot` (no top-level `data`, no extra nested `properties`); chart data config lives under `snapshot.data` (`refs` / `headerMode` / `dim1` / `dim2`); must include at least one of `snapshot.data.dim1.serie.index` or `dim2.series[].index`, otherwise the server rejects it. Deeply nested — run `--print-schema --flag-name properties` for the full structure.",
         "input": [
           "file",
           "stdin"
@@ -4066,7 +4169,7 @@
         "kind": "own",
         "type": "string",
         "required": "optional",
-        "desc": "Filter-view name; auto-assigned by the server when omitted on create, kept unchanged when omitted on update; takes precedence over the same-named field inside `--properties`"
+        "desc": "Filter-view name; auto-assigned by the server when omitted; takes precedence over the same-named field inside `--properties`"
       },
       {
         "name": "dry-run",
@@ -4747,5 +4850,172 @@
         "desc": ""
       }
     ]
+  },
+  "+history-list": {
+    "risk": "read",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "end-version",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "Max version to query (descending pagination). Omit on the first call; pass next_end_version from the previous response."
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
+  "+history-revert": {
+    "risk": "write",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "history-version-id",
+        "kind": "own",
+        "type": "string",
+        "required": "required",
+        "desc": "History version to revert to (from +history-list)."
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
+  "+history-revert-status": {
+    "risk": "read",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "transaction-id",
+        "kind": "own",
+        "type": "string",
+        "required": "required",
+        "desc": "Async revert transaction id (from +history-revert)."
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
+  "+undo": {
+    "risk": "write",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "count",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "Number of user undo stack entries to undo sequentially. Defaults to 1, maximum 20. Entries are undone from newest to oldest; the actual count is returned in undone.",
+        "default": "1"
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
+  "+changeset-get": {
+    "risk": "read",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet token (XOR with `--url`)"
+      },
+      {
+        "name": "start-revision",
+        "kind": "own",
+        "type": "int",
+        "required": "required",
+        "desc": "Start version (CS revision); the before baseline for review (must be >= 1)"
+      },
+      {
+        "name": "end-revision",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "End version (CS revision); defaults to the latest revision. Gap (end-start+1) must be <= 20",
+        "default": "-1"
+      }
+    ]
   }
 }

shortcuts/sheets/flag_defs_gen.go

@@ -27,7 +27,7 @@ var flagDefs = map[string]commandDef{
 		Flags: []flagDef{
 			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
-			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A2:Z1000\",\"'Sheet2'!A2:Z1000\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id; ranges may target different sheets; the same scope is cleared from every range", Input: []string{"file", "stdin"}},
+			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"Sheet1!A2:Z1000\",\"Sheet2!A2:Z1000\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same scope is cleared from every range", Input: []string{"file", "stdin"}},
 			{Name: "scope", Kind: "own", Type: "string", Required: "optional", Desc: "Clear scope: `content` (default, values only) / `formats` (formats only) / `all` (values and formats)", Default: "content", Enum: []string{"content", "formats", "all"}},
 			{Name: "yes", Kind: "system", Type: "bool", Required: "required", Desc: "Confirm destructive write (exit code 10 without this flag); batch clear is irreversible"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
@@ -38,9 +38,10 @@ var flagDefs = map[string]commandDef{
 		Flags: []flagDef{
 			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
-			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A1:B2\",\"'Sheet2'!D1:D10\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id; ranges may target different sheets; the same style is applied to every range", Input: []string{"file", "stdin"}},
+			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"Sheet1!A1:B2\",\"Sheet2!D1:D10\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same style is applied to every range", Input: []string{"file", "stdin"}},
 			{Name: "background-color", Kind: "own", Type: "string", Required: "optional", Desc: "Background color (hex, e.g. `#ffffff`)"},
 			{Name: "font-color", Kind: "own", Type: "string", Required: "optional", Desc: "Font color (hex, e.g. `#000000`)"},
+			{Name: "font-family", Kind: "own", Type: "string", Required: "optional", Desc: "Font family name (e.g. `Arial`, `Microsoft YaHei`)"},
 			{Name: "font-size", Kind: "own", Type: "float64", Required: "optional", Desc: "Font size in px (e.g. 10, 12, 14)"},
 			{Name: "font-style", Kind: "own", Type: "string", Required: "optional", Desc: "Font style", Enum: []string{"normal", "italic"}},
 			{Name: "font-weight", Kind: "own", Type: "string", Required: "optional", Desc: "Font weight", Enum: []string{"normal", "bold"}},
@@ -165,6 +166,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "range", Kind: "own", Type: "string", Required: "required", Desc: "Target range (A1 notation, e.g. `A1:B2`)"},
 			{Name: "background-color", Kind: "own", Type: "string", Required: "optional", Desc: "Background color (hex, e.g. `#ffffff`)"},
 			{Name: "font-color", Kind: "own", Type: "string", Required: "optional", Desc: "Font color (hex, e.g. `#000000`)"},
+			{Name: "font-family", Kind: "own", Type: "string", Required: "optional", Desc: "Font family name (e.g. `Arial`, `Microsoft YaHei`)"},
 			{Name: "font-size", Kind: "own", Type: "float64", Required: "optional", Desc: "Font size in px (e.g. 10, 12, 14)"},
 			{Name: "font-style", Kind: "own", Type: "string", Required: "optional", Desc: "Font style", Enum: []string{"normal", "italic"}},
 			{Name: "font-weight", Kind: "own", Type: "string", Required: "optional", Desc: "Font weight", Enum: []string{"normal", "bold"}},
@@ -188,6 +190,15 @@ var flagDefs = map[string]commandDef{
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
+	"+changeset-get": {
+		Risk: "read",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
+			{Name: "start-revision", Kind: "own", Type: "int", Required: "required", Desc: "Start version (CS revision); the before baseline for review (must be >= 1)"},
+			{Name: "end-revision", Kind: "own", Type: "int", Required: "optional", Desc: "End version (CS revision); defaults to the latest revision. Gap (end-start+1) must be <= 20", Default: "-1"},
+		},
+	},
 	"+chart-create": {
 		Risk: "write",
 		Flags: []flagDef{
@@ -195,7 +206,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
 			{Name: "sheet-id", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet reference_id (XOR with `--sheet-name`)"},
 			{Name: "sheet-name", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet name (XOR with `--sheet-id`)"},
-			{Name: "properties", Kind: "own", Type: "string", Required: "required", Desc: "Full chart config JSON. Top-level keys: `position` / `offset` / `size` / `snapshot` (no top-level `data`, no extra nested `properties`); chart data config lives under `snapshot.data` (`refs` / `headerMode` / `dim1` / `dim2`). Deeply nested — run `--print-schema --flag-name properties` for the full structure.", Input: []string{"file", "stdin"}},
+			{Name: "properties", Kind: "own", Type: "string", Required: "required", Desc: "Full chart config JSON. Top-level keys: `position` / `offset` / `size` / `snapshot` (no top-level `data`, no extra nested `properties`); chart data config lives under `snapshot.data` (`refs` / `headerMode` / `dim1` / `dim2`); must include at least one of `snapshot.data.dim1.serie.index` or `dim2.series[].index`, otherwise the server rejects it. Deeply nested — run `--print-schema --flag-name properties` for the full structure.", Input: []string{"file", "stdin"}},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional", Desc: "Print the request template; no side effects"},
 		},
 	},
@@ -405,7 +416,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
 			{Name: "sheet-id", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet reference_id (XOR with `--sheet-name`)"},
 			{Name: "sheet-name", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet name (XOR with `--sheet-id`)"},
-			{Name: "depth", Kind: "own", Type: "int", Required: "optional", Desc: "Group nesting level to ungroup; default 1 (outermost)", Default: "1"},
+			{Name: "depth", Kind: "own", Type: "int", Required: "optional", Desc: "Group nesting level to ungroup; default 1 (1 = outermost, larger = deeper)", Default: "1"},
 			{Name: "range", Kind: "own", Type: "string", Required: "required", Desc: "Row/column closed range to ungroup; rows use 1-based numbers like `3:7`, columns use letters like `C:F`"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
@@ -426,7 +437,7 @@ var flagDefs = map[string]commandDef{
 		Flags: []flagDef{
 			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
-			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (up to 100 items, e.g. `[\"'Sheet1'!E2:E6\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id", Input: []string{"file", "stdin"}},
+			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (up to 100 items, e.g. `[\"Sheet1!E2:E6\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id", Input: []string{"file", "stdin"}},
 			{Name: "yes", Kind: "system", Type: "bool", Required: "required", Desc: "Confirm high-risk write (exit code 10 without this flag)"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
@@ -463,7 +474,7 @@ var flagDefs = map[string]commandDef{
 		Flags: []flagDef{
 			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
-			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A2:A100\",\"'Sheet1'!C2:C100\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id", Input: []string{"file", "stdin"}},
+			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"Sheet1!A2:A100\",\"Sheet1!C2:C100\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id", Input: []string{"file", "stdin"}},
 			{Name: "options", Kind: "own", Type: "string", Required: "xor", Desc: "Options as a JSON array, e.g. `[\"opt1\",\"opt2\"]`. Server enforces no item-count cap and no per-item length cap; values containing commas are accepted (they are escape-encoded on the wire). For very large lists prefer `--source-range`.", Input: []string{"file", "stdin"}},
 			{Name: "colors", Kind: "own", Type: "string", Required: "optional", Desc: "Per-option pill colors, RGB hex array (e.g. `[\"#1FB6C1\",\"#F006C2\"]`). Length may be shorter than the source (`--options` items / `--source-range` cells) — extras cycle through a 10-color palette — but never longer (CLI Validate rejects: `--colors length (N) must not exceed dropdown source size (M)`). **Applies on its own**; ignored when `--highlight=false`.", Input: []string{"file", "stdin"}},
 			{Name: "multiple", Kind: "own", Type: "bool", Required: "optional", Desc: "Enable multi-select"},
@@ -526,7 +537,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "sheet-name", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet name (XOR with `--sheet-id`)"},
 			{Name: "properties", Kind: "own", Type: "string", Required: "required", Desc: "Filter-view rule JSON: `rules?` (per-column rule array), `filtered_columns?`. `range` and `view_name` are separate flags", Input: []string{"file", "stdin"}},
 			{Name: "range", Kind: "own", Type: "string", Required: "required", Desc: "Range the filter view applies to (A1 notation, e.g. `A1:F1000`); takes precedence over the same-named field inside `--properties`; required on create and must cover the header row"},
-			{Name: "view-name", Kind: "own", Type: "string", Required: "optional", Desc: "Filter-view name; auto-assigned by the server when omitted on create, kept unchanged when omitted on update; takes precedence over the same-named field inside `--properties`"},
+			{Name: "view-name", Kind: "own", Type: "string", Required: "optional", Desc: "Filter-view name; auto-assigned by the server when omitted; takes precedence over the same-named field inside `--properties`"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -632,6 +643,45 @@ var flagDefs = map[string]commandDef{
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
+	"+formula-verify": {
+		Risk: "read",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
+			{Name: "sheet-id", Kind: "public", Type: "string_slice", Required: "optional", Desc: "Sheet reference_id(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."},
+			{Name: "sheet-name", Kind: "public", Type: "string_slice", Required: "optional", Desc: "Sheet name(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."},
+			{Name: "range", Kind: "own", Type: "string_slice", Required: "optional", Desc: "Optional A1 ranges (e.g. `A1:Z200`); repeat or comma-separate for multiple ranges. Omit to scan each sheet's current_region."},
+			{Name: "max-locations", Kind: "own", Type: "int", Required: "optional", Desc: "Max locations / samples per error type; default 20.", Default: "20"},
+			{Name: "exit-on-error", Kind: "own", Type: "bool", Required: "optional", Desc: "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."},
+		},
+	},
+	"+history-list": {
+		Risk: "read",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "end-version", Kind: "own", Type: "int", Required: "optional", Desc: "Max version to query (descending pagination). Omit on the first call; pass next_end_version from the previous response."},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
+	"+history-revert": {
+		Risk: "write",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "history-version-id", Kind: "own", Type: "string", Required: "required", Desc: "History version to revert to (from +history-list)."},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
+	"+history-revert-status": {
+		Risk: "read",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "transaction-id", Kind: "own", Type: "string", Required: "required", Desc: "Async revert transaction id (from +history-revert)."},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
 	"+pivot-create": {
 		Risk: "write",
 		Flags: []flagDef{
@@ -734,6 +784,14 @@ var flagDefs = map[string]commandDef{
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
+	"+revision-get": {
+		Risk: "read",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
 	"+rows-resize": {
 		Risk: "write",
 		Flags: []flagDef{
@@ -768,6 +826,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "index", Kind: "own", Type: "int", Required: "optional", Desc: "Insert position (0-based); appended to the end when omitted", Default: "-1"},
 			{Name: "row-count", Kind: "own", Type: "int", Required: "optional", Desc: "Initial row count (default 200, max 50000)", Default: "200"},
 			{Name: "col-count", Kind: "own", Type: "int", Required: "optional", Desc: "Initial column count (default 20, max 200)", Default: "20"},
+			{Name: "type", Kind: "own", Type: "string", Required: "optional", Desc: "New sub-sheet type: sheet (spreadsheet) | bitable; default sheet. bitable creates an empty table only — edit its content via lark-base commands", Default: "sheet"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -822,7 +881,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "sheet-id", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet reference_id (XOR with `--sheet-name`)"},
 			{Name: "sheet-name", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet name (XOR with `--sheet-id`)"},
 			{Name: "index", Kind: "own", Type: "int", Required: "required", Desc: "Target position (0-based)"},
-			{Name: "source-index", Kind: "own", Type: "int", Required: "optional", Desc: "Source position (0-based); optional. If omitted, the CLI runtime derives it from the current workbook index of `--sheet-id` / `--sheet-name`", Default: "-1"},
+			{Name: "source-index", Kind: "own", Type: "int", Required: "optional", Desc: "Source position (0-based); optional for standalone calls — if omitted, the CLI runtime derives it from the current workbook index of `--sheet-id` / `--sheet-name`. Inside `+batch-update` it must be passed explicitly, since batch cannot issue a structure query mid-run to derive it", Default: "-1"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -936,12 +995,21 @@ var flagDefs = map[string]commandDef{
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
+	"+undo": {
+		Risk: "write",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "count", Kind: "own", Type: "int", Required: "optional", Desc: "Number of user undo stack entries to undo sequentially. Defaults to 1, maximum 20. Entries are undone from newest to oldest; the actual count is returned in undone.", Default: "1"},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
 	"+workbook-create": {
 		Risk: "write",
 		Flags: []flagDef{
 			{Name: "title", Kind: "own", Type: "string", Required: "required", Desc: "Spreadsheet title"},
 			{Name: "folder-token", Kind: "own", Type: "string", Required: "optional", Desc: "Target folder token; placed at the drive root when omitted"},
-			{Name: "values", Kind: "own", Type: "string", Required: "optional", Desc: "Untyped initial data as one 2D JSON array (`[[\"alice\",95]]`); values are written as-is with their type auto-detected, through the same batched set_cell_range path as --sheets — pair with --styles for number formats, colors, merges, and row/col sizes", Input: []string{"file", "stdin"}},
+			{Name: "values", Kind: "own", Type: "string", Required: "optional", Desc: "Untyped initial data as one 2D JSON array (`[[\"alice\",95]]`); values are written as-is with their type auto-detected (dates / numbers land as text — use --sheets to preserve types), through the same batched set_cell_range path as --sheets — pair with --styles for number formats, colors, merges, and row/col sizes", Input: []string{"file", "stdin"}},
 			{Name: "sheets", Kind: "own", Type: "string", Required: "optional", Desc: "Typed table payload as JSON (same shape as `+table-put`): top-level `{\"sheets\":[...]}`, with each array item a sub-sheet `{name, start_cell?, mode?, header?, allow_overwrite?, columns:[\"colA\",\"colB\",...], data:[[...]], dtypes?:{colA:pandasDtype, ...}, formats?:{colA:numberFormat, ...}}` — `name` and the outer `sheets` envelope are both required. Agents typically use `df_to_sheet(df, name)` from `scripts/sheets_df.py` to pack each DataFrame into one item, then wrap the list in `{\"sheets\":[...]}`. Mutually exclusive with --values. Creates the workbook, then writes typed type-faithful data (dates land as real dates, numbers keep precision).", Input: []string{"file", "stdin"}},
 			{Name: "styles", Kind: "own", Type: "string", Required: "optional", Desc: "Initial visual operations as JSON: top-level `{styles:[...]}`. Each item corresponds to one target sheet and must include `name`, plus at least one of `cell_styles` / `row_sizes` / `col_sizes` / `cell_merges`. `cell_styles` entries use +cells-set-style fields with a cell range; row/col sizes use dimension ranges plus type/size; merges use cell ranges plus optional merge_type. With --sheets, styles array length/order/name must match --sheets.sheets. With --values, pass exactly one styles item for the initial sheet (its name is ignored).", Input: []string{"file", "stdin"}},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},

shortcuts/sheets/flag_schema.go

@@ -6,7 +6,6 @@ package sheets
 import (
 	_ "embed"
 	"encoding/json"
-	"fmt"
 	"sort"
 	"sync"
 
@@ -54,7 +53,7 @@ func loadFlagSchemas() (*flagSchemaIndex, error) {
 	flagSchemasOnce.Do(func() {
 		var idx flagSchemaIndex
 		if err := json.Unmarshal(flagSchemasJSON, &idx); err != nil {
-			parseFlagErr = fmt.Errorf("flag-schemas.json: %w", err)
+			parseFlagErr = errs.NewInternalError(errs.SubtypeUnknown, "flag-schemas.json: %v", err).WithCause(err)
 			return
 		}
 		if idx.Flags == nil {

shortcuts/sheets/flag_schema_validate.go

@@ -243,7 +243,7 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 
 	if schema.Type != "" {
 		if !matchesJSONType(value, schema.Type) {
-			return fmt.Errorf("%sexpected type %q, got %q", pathPrefix(path), schema.Type, jsType(value))
+			return fmt.Errorf("%sexpected type %q, got %q", pathPrefix(path), schema.Type, jsType(value)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 	}
 
@@ -251,20 +251,20 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 	// already reported above). Apply to both `number` and `integer` types.
 	if num, ok := value.(float64); ok {
 		if schema.Minimum != nil && num < *schema.Minimum {
-			return fmt.Errorf("%svalue %v is below minimum %v", pathPrefix(path), num, *schema.Minimum)
+			return fmt.Errorf("%svalue %v is below minimum %v", pathPrefix(path), num, *schema.Minimum) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 		if schema.Maximum != nil && num > *schema.Maximum {
-			return fmt.Errorf("%svalue %v is above maximum %v", pathPrefix(path), num, *schema.Maximum)
+			return fmt.Errorf("%svalue %v is above maximum %v", pathPrefix(path), num, *schema.Maximum) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 	}
 
 	// Array length bounds — only checked when value is an array.
 	if arr, ok := value.([]interface{}); ok {
 		if schema.MinItems != nil && len(arr) < *schema.MinItems {
-			return fmt.Errorf("%sarray has %d items, minimum is %d", pathPrefix(path), len(arr), *schema.MinItems)
+			return fmt.Errorf("%sarray has %d items, minimum is %d", pathPrefix(path), len(arr), *schema.MinItems) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 		if schema.MaxItems != nil && len(arr) > *schema.MaxItems {
-			return fmt.Errorf("%sarray has %d items, maximum is %d", pathPrefix(path), len(arr), *schema.MaxItems)
+			return fmt.Errorf("%sarray has %d items, maximum is %d", pathPrefix(path), len(arr), *schema.MaxItems) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 	}
 
@@ -282,7 +282,7 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 			if hint := suggestEnumMatch(value, schema.Enum); hint != "" {
 				msg += fmt.Sprintf(` (did you mean %q?)`, hint)
 			}
-			return fmt.Errorf("%s", msg)
+			return fmt.Errorf("%s", msg) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 	}
 
@@ -295,7 +295,7 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 			}
 		}
 		if !matched {
-			return fmt.Errorf("%svalue does not match any of oneOf alternatives", pathPrefix(path))
+			return fmt.Errorf("%svalue does not match any of oneOf alternatives", pathPrefix(path)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 	}
 
@@ -305,7 +305,7 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 	if obj, ok := value.(map[string]interface{}); ok {
 		for _, key := range schema.Required {
 			if _, present := obj[key]; !present {
-				return fmt.Errorf("required property %q is missing at %s", key, pathOrRoot(path))
+				return fmt.Errorf("required property %q is missing at %s", key, pathOrRoot(path)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 			}
 		}
 		if schema.Properties != nil {
@@ -357,7 +357,7 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 			sort.Strings(extras)
 			for _, key := range extras {
 				if schema.AdditionalProperties.Strict {
-					return fmt.Errorf("%sunexpected property %q (not declared in schema)", pathPrefix(path), key)
+					return fmt.Errorf("%sunexpected property %q (not declared in schema)", pathPrefix(path), key) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 				}
 				if schema.AdditionalProperties.Schema != nil {
 					child := key

shortcuts/sheets/flag_view.go

@@ -281,18 +281,18 @@ func (m mapFlagView) validateRawTypes() error {
 			// parse time; reject here too to keep batch/standalone parity.
 			f, isNum := val.(float64)
 			if !isNum {
-				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val))
+				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
 			}
 			if math.Trunc(f) != f {
-				return fmt.Errorf("--%s must be an integer, got %s", name, strconv.FormatFloat(f, 'g', -1, 64))
+				return fmt.Errorf("--%s must be an integer, got %s", name, strconv.FormatFloat(f, 'g', -1, 64)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
 			}
 		case "float64":
 			if _, isNum := val.(float64); !isNum {
-				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val))
+				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
 			}
 		case "bool":
 			if _, isBool := val.(bool); !isBool {
-				return fmt.Errorf("--%s must be a boolean, got %s", name, jsonTypeName(val))
+				return fmt.Errorf("--%s must be a boolean, got %s", name, jsonTypeName(val)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
 			}
 		}
 	}

shortcuts/sheets/helpers.go

@@ -10,6 +10,7 @@ package sheets
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	neturl "net/url"
 	"strings"
@@ -44,7 +45,8 @@ func sheetsValidationCauseForFlag(name string, cause error) *errs.ValidationErro
 // classification and only adds the domain's flag param.
 func sheetsInputStatError(flag string, err error) error {
 	wrapped := common.WrapInputStatErrorTyped(err)
-	if v, ok := wrapped.(*errs.ValidationError); ok {
+	var v *errs.ValidationError
+	if errors.As(wrapped, &v) {
 		return v.WithParam(sheetsFlagParam(flag))
 	}
 	return wrapped
@@ -52,21 +54,30 @@ func sheetsInputStatError(flag string, err error) error {
 
 // Drive media parent_type values for uploading an image into a spreadsheet.
 // Native spreadsheets use "sheet_image"; imported "office" spreadsheets carry a
-// synthetic token prefixed with "fake_office_" and the backend requires
-// "office_sheet_file" instead.
+// synthetic token prefixed with "fake_office_" (being renamed to
+// "local_office_") and the backend requires "office_sheet_file" instead.
 const (
 	sheetImageParentType      = "sheet_image"
 	officeSheetFileParentType = "office_sheet_file"
 	fakeOfficeTokenPrefix     = "fake_office_"
+	localOfficeTokenPrefix    = "local_office_"
 )
 
+// officeTokenPrefixes are the synthetic token prefixes an imported "office"
+// spreadsheet may carry. The prefix is being renamed from "fake_office_" to
+// "local_office_"; accept either so image uploads keep working across the
+// rename.
+var officeTokenPrefixes = []string{fakeOfficeTokenPrefix, localOfficeTokenPrefix}
+
 // sheetMediaParentType returns the drive media parent_type to use when
 // uploading an image whose parent_node is spreadsheetToken. It is the single
 // place that maps a spreadsheet token to its parent_type so every image-upload
 // entry point (and its dry-run preview) stays consistent.
 func sheetMediaParentType(spreadsheetToken string) string {
-	if strings.HasPrefix(spreadsheetToken, fakeOfficeTokenPrefix) {
-		return officeSheetFileParentType
+	for _, prefix := range officeTokenPrefixes {
+		if strings.HasPrefix(spreadsheetToken, prefix) {
+			return officeSheetFileParentType
+		}
 	}
 	return sheetImageParentType
 }
@@ -440,7 +451,7 @@ func requireJSONArray(runtime flagView, name string) ([]interface{}, error) {
 
 // ─── style flags (shared by +cells-set-style and +cells-batch-set-style) ─
 
-// buildCellStyleFromFlags reads the 11 flat style flags and returns the
+// buildCellStyleFromFlags reads the 12 flat style flags and returns the
 // cell_styles map expected by set_cell_range. Skips any flag the user
 // didn't set so partial styles work.
 func buildCellStyleFromFlags(runtime flagView) map[string]interface{} {
@@ -451,6 +462,9 @@ func buildCellStyleFromFlags(runtime flagView) map[string]interface{} {
 	if v := runtime.Str("font-color"); v != "" {
 		style["font_color"] = v
 	}
+	if v := runtime.Str("font-family"); v != "" {
+		style["font_family"] = v
+	}
 	if runtime.Changed("font-size") && runtime.Float64("font-size") > 0 {
 		style["font_size"] = runtime.Float64("font-size")
 	}

shortcuts/sheets/lark_sheet_batch_update.go

@@ -215,7 +215,8 @@ func cellsBatchSetStyleInput(runtime *common.RuntimeContext, token string) (map[
 	if borderStyles != nil {
 		prototype["border_styles"] = borderStyles
 	}
-	var ops []interface{}
+	ops := make([]interface{}, 0, len(ranges))
+	var totalCells int64
 	for _, rng := range ranges {
 		sheet, sub, err := splitSheetPrefixedRange(rng)
 		if err != nil {
@@ -225,6 +226,13 @@ func cellsBatchSetStyleInput(runtime *common.RuntimeContext, token string) (map[
 		if err != nil {
 			return nil, sheetsValidationForFlag("range", "range %q: %v", rng, err)
 		}
+		if err := checkStampMatrixBudget("ranges", rng, rows, cols); err != nil {
+			return nil, err
+		}
+		totalCells += int64(rows) * int64(cols)
+		if err := checkBatchStampBudget(totalCells); err != nil {
+			return nil, err
+		}
 		cells := fillCellsMatrix(rows, cols, prototype)
 		ops = append(ops, map[string]interface{}{
 			"tool_name": "set_cell_range",
@@ -299,7 +307,7 @@ func cellsBatchClearInput(runtime *common.RuntimeContext, token string) (map[str
 		return nil, err
 	}
 	clearType := normalizeClearType(runtime.Str("scope"))
-	var ops []interface{}
+	ops := make([]interface{}, 0, len(ranges))
 	for _, rng := range ranges {
 		sheet, sub, err := splitSheetPrefixedRange(rng)
 		if err != nil {
@@ -382,13 +390,10 @@ var DropdownDelete = common.Shortcut{
 		if _, err := resolveSpreadsheetToken(runtime); err != nil {
 			return err
 		}
-		ranges, err := validateDropdownRanges(runtime)
-		if err != nil {
+		// validateDropdownRanges enforces the shared maxBatchRanges cap.
+		if _, err := validateDropdownRanges(runtime); err != nil {
 			return err
 		}
-		if len(ranges) > 100 {
-			return sheetsValidationForFlag("ranges", "--ranges accepts at most 100 entries; got %d", len(ranges))
-		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -432,7 +437,8 @@ func dropdownBatchInput(runtime *common.RuntimeContext, token string, clear bool
 		}
 		prototype = map[string]interface{}{"data_validation": validation}
 	}
-	var ops []interface{}
+	ops := make([]interface{}, 0, len(ranges))
+	var totalCells int64
 	for _, rng := range ranges {
 		sheet, sub, err := splitSheetPrefixedRange(rng)
 		if err != nil {
@@ -442,6 +448,13 @@ func dropdownBatchInput(runtime *common.RuntimeContext, token string, clear bool
 		if err != nil {
 			return nil, sheetsValidationForFlag("range", "range %q: %v", rng, err)
 		}
+		if err := checkStampMatrixBudget("ranges", rng, rows, cols); err != nil {
+			return nil, err
+		}
+		totalCells += int64(rows) * int64(cols)
+		if err := checkBatchStampBudget(totalCells); err != nil {
+			return nil, err
+		}
 		cells := fillCellsMatrix(rows, cols, prototype)
 		ops = append(ops, map[string]interface{}{
 			"tool_name": "set_cell_range",
@@ -461,6 +474,25 @@ func dropdownBatchInput(runtime *common.RuntimeContext, token string, clear bool
 
 // ─── helpers resurrected from B3 (used here + future skills) ──────────
 
+// maxBatchRanges caps how many ranges a fan-out batch (+cells-batch-set-style /
+// +cells-batch-clear / +dropdown-update / +dropdown-delete) may carry, bounding
+// the number of ops materialized into one batch_update.
+const maxBatchRanges = 100
+
+// checkBatchStampBudget rejects a fan-out batch whose ranges materialize more
+// than maxStampMatrixCells cells in aggregate. A batch builds every range's
+// cells matrix up front, so the SUM across ranges is the real peak-memory bound
+// — the per-range checkStampMatrixBudget alone can't stop many ranges from
+// summing past it. totalCells is int64 to stay overflow-safe.
+func checkBatchStampBudget(totalCells int64) error {
+	if totalCells > maxStampMatrixCells {
+		return sheetsValidationForFlag("ranges",
+			"ranges expand to %d cells total, over the %d-cell safety cap; reduce the number or size of ranges",
+			totalCells, maxStampMatrixCells)
+	}
+	return nil
+}
+
 // validateDropdownRanges parses --ranges, requires every entry to carry a
 // sheet prefix, and returns the parsed list.
 func validateDropdownRanges(runtime *common.RuntimeContext) ([]string, error) {
@@ -490,6 +522,9 @@ func validateDropdownRanges(runtime *common.RuntimeContext) ([]string, error) {
 		}
 		out = append(out, s)
 	}
+	if len(out) > maxBatchRanges {
+		return nil, sheetsValidationForFlag("ranges", "--ranges accepts at most %d entries; got %d", maxBatchRanges, len(out))
+	}
 	return out, nil
 }
 

shortcuts/sheets/lark_sheet_changeset.go

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ─── lark_sheet_changeset ─────────────────────────────────────────────
+//
+// +changeset-get wraps the get_changeset read tool: fetch the raw changeset
+// (the list of edit actions) between two CS revisions of a spreadsheet, so a
+// human or reviewing agent can verify whether an AI edit actually fulfilled
+// the user's request.
+//
+//   - --start-revision is the "before" baseline (required, >= 1).
+//   - --end-revision is optional; when omitted it defaults to the latest
+//     revision, returning every changeset from start up to now.
+//   - The version gap is capped at 20 (end - start + 1 <= 20); the same cap
+//     is enforced server-side (sheet-facade-agg maxChangesetRevGap).
+
+const changesetMaxRevGap = 20
+
+// ChangesetGet fetches the raw changesets between two spreadsheet versions.
+var ChangesetGet = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+changeset-get",
+	Description: "Fetch the raw changeset (edit actions) between two versions, to review whether an AI edit fulfilled the request.",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       flagsFor("+changeset-get"),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := resolveSpreadsheetToken(runtime); err != nil {
+			return err
+		}
+		_, _, err := changesetRevisions(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		input, _ := changesetInput(runtime)
+		return invokeToolDryRun(token, ToolKindRead, "get_changeset", input)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetToken(runtime)
+		if err != nil {
+			return err
+		}
+		input, err := changesetInput(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindRead, "get_changeset", input)
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+	Tips: []string{
+		"Pass only --start-revision to diff against the latest version; add --end-revision to bound the range.",
+		"The version gap is capped at 20 revisions (end - start + 1 <= 20).",
+	},
+}
+
+// changesetRevisions reads and validates the start / end revision flags.
+// end <= 0 means "not provided" (default to latest, resolved server-side); a
+// provided end must be >= start and within the 20-revision gap.
+func changesetRevisions(runtime flagView) (start int, end int, err error) {
+	start = runtime.Int("start-revision")
+	end = runtime.Int("end-revision")
+	if start < 1 {
+		return 0, 0, sheetsValidationForFlag("start-revision", "--start-revision must be >= 1")
+	}
+	if end > 0 {
+		if end < start {
+			return 0, 0, sheetsValidationForFlag("end-revision", "--end-revision (%d) must be >= --start-revision (%d)", end, start)
+		}
+		if end-start+1 > changesetMaxRevGap {
+			return 0, 0, sheetsValidationForFlag("end-revision", "version gap exceeds limit %d (start=%d, end=%d)", changesetMaxRevGap, start, end)
+		}
+	}
+	return start, end, nil
+}
+
+// changesetInput builds the get_changeset tool input. end_revision is only
+// sent when explicitly provided; otherwise the server defaults to latest.
+func changesetInput(runtime flagView) (map[string]interface{}, error) {
+	start, end, err := changesetRevisions(runtime)
+	if err != nil {
+		return nil, err
+	}
+	input := map[string]interface{}{
+		"start_revision": start,
+	}
+	if end > 0 {
+		input["end_revision"] = end
+	}
+	return input, nil
+}

shortcuts/sheets/lark_sheet_changeset_test.go

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestChangesetGet_DryRun locks the get_changeset tool input: --end-revision
+// is only sent when explicitly provided, otherwise the server defaults to the
+// latest revision.
+func TestChangesetGet_DryRun(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		args      []string
+		wantInput map[string]interface{}
+	}{
+		{
+			name: "start + end bounded range",
+			args: []string{"--url", testURL, "--start-revision", "120", "--end-revision", "135"},
+			wantInput: map[string]interface{}{
+				"start_revision": float64(120),
+				"end_revision":   float64(135),
+			},
+		},
+		{
+			name: "start only → end omitted (server defaults to latest)",
+			args: []string{"--url", testURL, "--start-revision", "120"},
+			wantInput: map[string]interface{}{
+				"start_revision": float64(120),
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			body := parseDryRunBody(t, ChangesetGet, tt.args)
+			got := decodeToolInput(t, body, "get_changeset")
+			assertInputEquals(t, got, tt.wantInput)
+		})
+	}
+}
+
+// TestChangesetGet_Validation covers the client-side revision guards, which
+// mirror the server cap (sheet-facade-agg maxChangesetRevGap = 20).
+func TestChangesetGet_Validation(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name    string
+		args    []string
+		wantSub string
+	}{
+		{
+			name:    "start-revision must be >= 1",
+			args:    []string{"--url", testURL, "--start-revision", "0"},
+			wantSub: "start-revision must be >= 1",
+		},
+		{
+			name:    "end before start rejected",
+			args:    []string{"--url", testURL, "--start-revision", "100", "--end-revision", "50"},
+			wantSub: "end-revision",
+		},
+		{
+			name:    "gap over 20 rejected",
+			args:    []string{"--url", testURL, "--start-revision", "1", "--end-revision", "30"},
+			wantSub: "version gap exceeds limit",
+		},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+			stdout, stderr, err := runShortcutCapturingErr(t, ChangesetGet, append(c.args, "--dry-run"))
+			if err == nil {
+				t.Fatalf("expected validation error; stdout=%s stderr=%s", stdout, stderr)
+			}
+			if !strings.Contains(stdout+stderr+err.Error(), c.wantSub) {
+				t.Errorf("expected %q; got=%s|%s|%v", c.wantSub, stdout, stderr, err)
+			}
+		})
+	}
+}

shortcuts/sheets/lark_sheet_formula_verify.go

@@ -0,0 +1,167 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ─── lark_sheet_formula_verify ───────────────────────────────────────
+//
+// Wraps verify_formula (read): scan formulas + cell error states across one
+// or more sub-sheets and aggregate Excel errors (#REF! / #DIV/0! / #VALUE! /
+// #NAME? / #NULL! / #NUM! / #N/A) plus compile failures (formula_errors)
+// into a recalc.py-shaped JSON status report. The contract is the single
+// AI self-check entry point for the R10 "write → verify zero-error"
+// invariant — see canonical-spec/references/lark_sheet_formula_verify/.
+
+// FormulaVerify wraps verify_formula. Sheet selection is optional (both
+// --sheet-id and --sheet-name are repeatable); when omitted, the tool scans
+// every visible sub-sheet's current_region.
+var FormulaVerify = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+formula-verify",
+	Description: "Scan formulas / cell errors and return a recalc.py-shaped status report (success / errors_found / partial).",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       flagsFor("+formula-verify"),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := resolveSpreadsheetToken(runtime); err != nil {
+			return err
+		}
+		if err := validateFormulaVerifySheetSelector(runtime); err != nil {
+			return err
+		}
+		return validateFormulaVerifyLimits(runtime)
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		return invokeToolDryRun(token, ToolKindRead, "verify_formula", formulaVerifyInput(runtime, token))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindRead, "verify_formula", formulaVerifyInput(runtime, token))
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		if runtime.Bool("exit-on-error") {
+			return formulaVerifyExitOnError(out)
+		}
+		return nil
+	},
+}
+
+// validateFormulaVerifySheetSelector enforces XOR-like guarantees on the
+// two multi-value selectors: at most one of --sheet-id / --sheet-name may be
+// non-empty (passing both is the high-frequency reflex confusion when the
+// caller cargo-cults the single-sheet shortcut signature). Both empty is the
+// documented "scan every visible sub-sheet" path. Control-char checks reuse
+// requireSheetSelector's logic on each item.
+func validateFormulaVerifySheetSelector(runtime *common.RuntimeContext) error {
+	ids := nonEmptySliceItems(runtime.StrSlice("sheet-id"))
+	names := nonEmptySliceItems(runtime.StrSlice("sheet-name"))
+	if len(ids) > 0 && len(names) > 0 {
+		return common.ValidationErrorf("--sheet-id and --sheet-name are mutually exclusive; pick one selector to identify sub-sheets").
+			WithParams(
+				sheetsInvalidParam("sheet-id", "mutually exclusive"),
+				sheetsInvalidParam("sheet-name", "mutually exclusive"),
+			)
+	}
+	for _, id := range ids {
+		if err := requireSheetSelector(id, ""); err != nil {
+			return err
+		}
+	}
+	for _, name := range names {
+		if err := requireSheetSelector("", name); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// validateFormulaVerifyLimits rejects non-positive caps so a misplaced 0 or
+// negative flag value can't silently degrade the scan (the server-side
+// default would otherwise mask the typo).
+func validateFormulaVerifyLimits(runtime *common.RuntimeContext) error {
+	if runtime.Changed("max-locations") && runtime.Int("max-locations") <= 0 {
+		return sheetsValidationForFlag("max-locations", "--max-locations must be > 0")
+	}
+	return nil
+}
+
+// nonEmptySliceItems trims and drops blanks from a repeated-flag value so
+// `--sheet-id ""` doesn't masquerade as a real entry.
+func nonEmptySliceItems(in []string) []string {
+	out := make([]string, 0, len(in))
+	for _, v := range in {
+		if trimmed := strings.TrimSpace(v); trimmed != "" {
+			out = append(out, trimmed)
+		}
+	}
+	return out
+}
+
+// formulaVerifyInput builds the verify_formula tool input map from CLI flags.
+// excel_id is required; everything else is optional per the schema.
+func formulaVerifyInput(runtime *common.RuntimeContext, token string) map[string]interface{} {
+	input := map[string]interface{}{
+		"excel_id": token,
+	}
+	if ids := nonEmptySliceItems(runtime.StrSlice("sheet-id")); len(ids) > 0 {
+		input["sheet_ids"] = ids
+	} else if names := nonEmptySliceItems(runtime.StrSlice("sheet-name")); len(names) > 0 {
+		// The verify_formula schema only declares sheet_ids; the facade
+		// accepts sheet_names as a parallel optional field so name-based
+		// selection works without forcing the caller to pre-resolve. Mirrors
+		// how the other read shortcuts pack both fields via
+		// sheetSelectorForToolInput.
+		input["sheet_names"] = names
+	}
+	if ranges := nonEmptySliceItems(runtime.StrSlice("range")); len(ranges) > 0 {
+		input["ranges"] = ranges
+	}
+	if runtime.Changed("max-locations") {
+		input["max_locations_per_error"] = runtime.Int("max-locations")
+	}
+	return input
+}
+
+// formulaVerifyExitOnError converts a verify_formula status into a non-zero
+// CLI exit when the caller passed --exit-on-error. status="errors_found"
+// is the only failure mode for this flag: "partial" means truncated but the
+// scanned slice is clean, and "success" is obviously clean. A missing /
+// unknown status is treated as a typed internal error because the tool's
+// schema guarantees the field and we don't want a silent zero-exit.
+func formulaVerifyExitOnError(out interface{}) error {
+	m, ok := out.(map[string]interface{})
+	if !ok {
+		return errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"verify_formula: missing status field in tool output")
+	}
+	status, _ := m["status"].(string)
+	switch status {
+	case "success", "partial":
+		return nil
+	case "errors_found":
+		total, _ := util.ToFloat64(m["total_errors"])
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
+			"verify_formula: %d formula error(s) detected; resolve and re-run", int(total)).
+			WithHint("inspect error_summary[*] / compile_errors[*] in the JSON output, fix or wrap with IFERROR, then re-run +formula-verify until status=success")
+	default:
+		return errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"verify_formula: unexpected status %q", status)
+	}
+}

shortcuts/sheets/lark_sheet_formula_verify_test.go

@@ -0,0 +1,213 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// TestFormulaVerify_DryRun pins the wire shape verify_formula sends for the
+// common input combinations: no selector (workbook-wide scan), explicit
+// sheet_ids, explicit ranges, and the optional max_locations_per_error
+// field. The test exercises the One-OpenAPI body
+// directly so the schema field names stay locked to the canonical
+// tool-schemas.json verify_formula node.
+func TestFormulaVerify_DryRun(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		args      []string
+		wantInput map[string]interface{}
+	}{
+		{
+			name: "no selector — workbook-wide scan defaults",
+			args: []string{"--url", testURL},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+			},
+		},
+		{
+			name: "sheet_ids multi via repeat",
+			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--sheet-id", testSheetID2},
+			wantInput: map[string]interface{}{
+				"excel_id":  testToken,
+				"sheet_ids": []interface{}{testSheetID, testSheetID2},
+			},
+		},
+		{
+			name: "sheet_names multi via comma",
+			args: []string{"--url", testURL, "--sheet-name", "Sheet1,Sheet2"},
+			wantInput: map[string]interface{}{
+				"excel_id":    testToken,
+				"sheet_names": []interface{}{"Sheet1", "Sheet2"},
+			},
+		},
+		{
+			name: "ranges + max_locations",
+			args: []string{
+				"--url", testURL,
+				"--range", "A1:Z200",
+				"--range", "AA1:AZ100",
+				"--max-locations", "5",
+			},
+			wantInput: map[string]interface{}{
+				"excel_id":                testToken,
+				"ranges":                  []interface{}{"A1:Z200", "AA1:AZ100"},
+				"max_locations_per_error": float64(5),
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			body := parseDryRunBody(t, FormulaVerify, tt.args)
+			got := decodeToolInput(t, body, "verify_formula")
+			assertInputEquals(t, got, tt.wantInput)
+		})
+	}
+}
+
+// TestFormulaVerify_DryRunInvokeReadPath confirms the request hits
+// invoke_read (read scope) and not invoke_write — a scope mismatch here would
+// surface as a 403 from the gateway.
+func TestFormulaVerify_DryRunInvokeReadPath(t *testing.T) {
+	t.Parallel()
+	calls := parseDryRunAPI(t, FormulaVerify, []string{"--url", testURL})
+	if len(calls) == 0 {
+		t.Fatalf("dry-run produced no api calls")
+	}
+	call, _ := calls[0].(map[string]interface{})
+	url, _ := call["url"].(string)
+	if !strings.HasSuffix(url, "/tools/invoke_read") {
+		t.Errorf("verify_formula must hit invoke_read; got url=%q", url)
+	}
+	if want := "/open-apis/sheet_ai/v2/spreadsheets/" + testToken + "/tools/invoke_read"; url != want {
+		t.Errorf("url = %q, want %q", url, want)
+	}
+}
+
+// TestFormulaVerify_RejectsBothSelectors locks the "at most one selector"
+// rule on the two multi-value flags. Both empty is the documented
+// workbook-wide scan path, so we only reject the both-supplied case.
+func TestFormulaVerify_RejectsBothSelectors(t *testing.T) {
+	t.Parallel()
+	_, _, err := runShortcutCapturingErr(t, FormulaVerify, []string{
+		"--url", testURL,
+		"--sheet-id", testSheetID,
+		"--sheet-name", "Sheet1",
+		"--dry-run",
+	})
+	ve := requireValidation(t, err, "mutually exclusive")
+	gotParams := map[string]bool{}
+	for _, p := range ve.Params {
+		gotParams[p.Name] = true
+	}
+	if !gotParams["--sheet-id"] || !gotParams["--sheet-name"] {
+		t.Errorf("params = %#v, want both --sheet-id and --sheet-name flagged", ve.Params)
+	}
+}
+
+// TestFormulaVerify_RejectsNonPositiveLimits guards against typos like
+// `--max-locations 0`, which would otherwise be silently swallowed by the
+// "explicit value but unset" comparison in the input builder.
+func TestFormulaVerify_RejectsNonPositiveLimits(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "max-locations=0",
+			args: []string{"--url", testURL, "--max-locations", "0"},
+			want: "--max-locations must be > 0",
+		},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+			_, _, err := runShortcutCapturingErr(t, FormulaVerify, append(c.args, "--dry-run"))
+			requireValidation(t, err, c.want)
+		})
+	}
+}
+
+// TestFormulaVerifyExitOnError_StatusMatrix locks the --exit-on-error
+// contract: success/partial → no error; errors_found → typed validation
+// error with SubtypeFailedPrecondition; missing or unknown status →
+// typed internal error so a silent zero-exit can never happen.
+func TestFormulaVerifyExitOnError_StatusMatrix(t *testing.T) {
+	t.Parallel()
+
+	t.Run("success returns no error", func(t *testing.T) {
+		t.Parallel()
+		if err := formulaVerifyExitOnError(map[string]interface{}{"status": "success"}); err != nil {
+			t.Fatalf("success path returned err: %v", err)
+		}
+	})
+
+	t.Run("partial returns no error", func(t *testing.T) {
+		t.Parallel()
+		if err := formulaVerifyExitOnError(map[string]interface{}{"status": "partial", "has_more": true}); err != nil {
+			t.Fatalf("partial path returned err: %v", err)
+		}
+	})
+
+	t.Run("errors_found yields failed_precondition with count", func(t *testing.T) {
+		t.Parallel()
+		err := formulaVerifyExitOnError(map[string]interface{}{
+			"status":       "errors_found",
+			"total_errors": float64(7),
+		})
+		if err == nil {
+			t.Fatal("expected error, got nil")
+		}
+		var ve *errs.ValidationError
+		if !errors.As(err, &ve) {
+			t.Fatalf("error = %T %v, want *errs.ValidationError", err, err)
+		}
+		if ve.Subtype != errs.SubtypeFailedPrecondition {
+			t.Errorf("subtype = %q, want %q", ve.Subtype, errs.SubtypeFailedPrecondition)
+		}
+		if !strings.Contains(ve.Message, "7 formula error") {
+			t.Errorf("message %q must surface the error count", ve.Message)
+		}
+		if ve.Hint == "" {
+			t.Errorf("hint must be set so AI agents know to re-run after fixes")
+		}
+	})
+
+	t.Run("unknown status maps to internal/invalid_response", func(t *testing.T) {
+		t.Parallel()
+		err := formulaVerifyExitOnError(map[string]interface{}{"status": "weird"})
+		if err == nil {
+			t.Fatal("expected error, got nil")
+		}
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("expected typed problem, got %T %v", err, err)
+		}
+		if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+			t.Errorf("category/subtype = %q/%q, want internal/invalid_response", p.Category, p.Subtype)
+		}
+	})
+
+	t.Run("non-object output maps to internal/invalid_response", func(t *testing.T) {
+		t.Parallel()
+		err := formulaVerifyExitOnError("oops")
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("expected typed problem, got %T %v", err, err)
+		}
+		if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+			t.Errorf("category/subtype = %q/%q, want internal/invalid_response", p.Category, p.Subtype)
+		}
+	})
+}

shortcuts/sheets/lark_sheet_history_list.go

@@ -0,0 +1,97 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ─── lark_sheet_history (BE-1: +history-list) ─────────────────────────
+//
+// Wraps the facade-agg `history_list` tool (read) behind the One-OpenAPI
+// invoke_read endpoint. The tool returns a sheet's version history. The
+// facade-agg tool already performs the response transform (minor_histories
+// trim / id → history_version_id / 4-field projection / RFC3339 create_time),
+// so the CLI passes the tool output straight through and does NOT re-implement
+// the transform client-side.
+//
+// History is workbook-level (no sheet selector), mirroring +workbook-info:
+// the only locator is --url / --spreadsheet-token (XOR), with --token accepted
+// as a parse-time alias for --spreadsheet-token via the shared PostMount hook.
+//
+// Flags are declared inline here rather than via flagsFor(): the generated
+// flag_defs_gen.go / data/flag-defs.json are synced from sheet-skill-spec
+// (BE-3) and must not be hand-edited, so this hand-written shortcut owns its
+// own flag set. The two locator flags match +workbook-info's shape exactly.
+
+// historyLocatorFlags is the --url / --spreadsheet-token XOR locator pair
+// shared by the three history shortcuts. Mirrors +workbook-info's flag-defs
+// entry; XOR is enforced in Validate via parseSpreadsheetRef, not by Required.
+func historyLocatorFlags() []common.Flag {
+	return []common.Flag{
+		{Name: "url", Type: "string", Desc: "Spreadsheet locator (a /sheets/ or /wiki/ URL)."},
+		{Name: "spreadsheet-token", Type: "string", Desc: "Spreadsheet locator (raw spreadsheet token)."},
+	}
+}
+
+// HistoryList wraps the history_list tool: list a spreadsheet's history
+// versions. Each item carries history_version_id / create_time / action /
+// all_block_revision (projected server-side). An empty sheet yields an empty
+// list and exit 0.
+//
+// Backward pagination: --end-version (optional int) maps to the tool's
+// `end_version` parameter. Omit on the first call to fetch the latest page.
+// On subsequent pages pass the previous response's next_end_version as
+// --end-version. The tool returns next_end_version + has_more only when
+// more history exists; both fields are absent at the earliest page.
+var HistoryList = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+history-list",
+	Description: "List a spreadsheet's edit history versions (history_version_id, create_time, action, all_block_revision).",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: append(historyLocatorFlags(),
+		common.Flag{Name: "end-version", Type: "int", Desc: "Max version to query (descending pagination). Omit on the first call; pass the previous response's next_end_version on subsequent pages."},
+	),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := resolveSpreadsheetToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		return invokeToolDryRun(token, ToolKindRead, "history_list", historyListInput(runtime, token))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindRead, "history_list", historyListInput(runtime, token))
+		if err != nil {
+			return err
+		}
+		// Pass the tool output through verbatim — facade-agg already shaped it.
+		runtime.Out(out, nil)
+		return nil
+	},
+	Tips: []string{
+		"Capture a history_version_id from the result to feed +history-revert.",
+		"For older history, capture next_end_version from the response and pass it as --end-version on the next call (omitted by the server when the earliest page is reached).",
+	},
+}
+
+// historyListInput composes the history_list tool input. --end-version is
+// optional: include it only when explicitly set so the server treats absence
+// as "first page (latest)".
+func historyListInput(runtime *common.RuntimeContext, token string) map[string]interface{} {
+	in := map[string]interface{}{"excel_id": token}
+	if runtime.Changed("end-version") {
+		in["end_version"] = runtime.Int("end-version")
+	}
+	return in
+}

shortcuts/sheets/lark_sheet_history_revert.go

@@ -0,0 +1,197 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ─── lark_sheet_history (BE-2: +history-revert / +history-revert-status) ──
+//
+// Two thin callTool wrappers over the facade-agg history tools:
+//   - +history-revert        → history_revert        (write) — async revert
+//   - +history-revert-status → history_revert_status (read)  — poll outcome
+//
+// Both target a single history version via --history-version-id (the id
+// surfaced by +history-list). Revert is asynchronous: it returns a receipt /
+// transaction id that +history-revert-status then polls, distinguishing
+// in-progress / success / failure from the tool output (passed through
+// verbatim — no client-side shaping).
+//
+// ⚠️ Backend state: the facade-agg history_revert / history_revert_status
+// tools are registered but their downstream RPC wiring is a DEFERRED
+// follow-up; today they return a "not wired yet" guard error from the gateway,
+// which surfaces here as a normal tool error. These CLI shortcuts are correct
+// thin wrappers and will work end-to-end once the backend follow-up lands —
+// this is NOT a CLI blocker. See self_check.md.
+//
+// Flags are declared inline (historyLocatorFlags + history-version-id) rather
+// than via flagsFor(), because flag_defs_gen.go / data/flag-defs.json are
+// synced from sheet-skill-spec (BE-3) and must not be hand-edited.
+
+// historyVersionIDFlag is the target-version selector shared by +history-revert.
+// Required at the cli surface (cobra MarkFlagRequired): a missing value yields
+// cobra's standard "required flag(s) \"history-version-id\" not set" message
+// before Validate runs. We still trim + reject control-chars in Validate to
+// reject empty strings ("--history-version-id "" "), which cobra accepts.
+func historyVersionIDFlag() common.Flag {
+	return common.Flag{
+		Name:     "history-version-id",
+		Type:     "string",
+		Required: true,
+		Desc:     "History version to act on (from +history-list).",
+	}
+}
+
+func historyRevertFlags() []common.Flag {
+	return append(historyLocatorFlags(), historyVersionIDFlag())
+}
+
+// validateHistoryVersionID enforces the required, control-char-clean
+// --history-version-id. Returns the trimmed value so callers reuse it.
+func validateHistoryVersionID(runtime *common.RuntimeContext) (string, error) {
+	id := strings.TrimSpace(runtime.Str("history-version-id"))
+	if id == "" {
+		return "", sheetsValidationForFlag("history-version-id", "--history-version-id is required")
+	}
+	return id, nil
+}
+
+func historyRevertInput(token, versionID string) map[string]interface{} {
+	return map[string]interface{}{
+		"excel_id":           token,
+		"history_version_id": versionID,
+	}
+}
+
+// transactionIDFlag is the async-revert receipt selector used by
+// +history-revert-status: the transaction_id returned by +history-revert (NOT a
+// history version id — the facade-agg status tool keys on transaction_id).
+// Required at the cli surface (cobra MarkFlagRequired) — same gating model as
+// historyVersionIDFlag. Validate still trims + rejects empty/control-char
+// values to catch the case where cobra accepts --transaction-id with an
+// empty-string value.
+func transactionIDFlag() common.Flag {
+	return common.Flag{
+		Name:     "transaction-id",
+		Type:     "string",
+		Required: true,
+		Desc:     "Async revert transaction id (from +history-revert).",
+	}
+}
+
+func historyRevertStatusFlags() []common.Flag {
+	return append(historyLocatorFlags(), transactionIDFlag())
+}
+
+// validateTransactionID enforces the required, trimmed --transaction-id and
+// returns it for reuse.
+func validateTransactionID(runtime *common.RuntimeContext) (string, error) {
+	id := strings.TrimSpace(runtime.Str("transaction-id"))
+	if id == "" {
+		return "", sheetsValidationForFlag("transaction-id", "--transaction-id is required")
+	}
+	return id, nil
+}
+
+func historyRevertStatusInput(token, transactionID string) map[string]interface{} {
+	return map[string]interface{}{
+		"excel_id":       token,
+		"transaction_id": transactionID,
+	}
+}
+
+// HistoryRevert wraps the history_revert tool (write): asynchronously revert a
+// spreadsheet to the given history version. --history-version-id is required
+// at the cli surface (cobra MarkFlagRequired); a missing flag fails before
+// Validate runs with cobra's standard "required flag(s)" error (which the
+// dispatcher classifies as a typed *errs.ValidationError, exit 2). We still
+// trim + reject empty / control-char values in Validate to catch the
+// case where cobra accepts --history-version-id with an empty-string value.
+var HistoryRevert = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+history-revert",
+	Description: "Revert a spreadsheet to a given history version (asynchronous; poll with +history-revert-status).",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       historyRevertFlags(),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := resolveSpreadsheetToken(runtime); err != nil {
+			return err
+		}
+		_, err := validateHistoryVersionID(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		versionID := strings.TrimSpace(runtime.Str("history-version-id"))
+		return invokeToolDryRun(token, ToolKindWrite, "history_revert", historyRevertInput(token, versionID))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		versionID, err := validateHistoryVersionID(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindWrite, "history_revert", historyRevertInput(token, versionID))
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+	Tips: []string{
+		"Revert is asynchronous — pass the returned id to +history-revert-status to track in-progress / success / failure.",
+	},
+}
+
+// HistoryRevertStatus wraps the history_revert_status tool (read): poll the
+// outcome of a prior +history-revert. The tool output distinguishes
+// in-progress / success / failure and is passed through verbatim.
+var HistoryRevertStatus = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+history-revert-status",
+	Description: "Poll the status of a history revert (in-progress / success / failure).",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       historyRevertStatusFlags(),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := resolveSpreadsheetToken(runtime); err != nil {
+			return err
+		}
+		_, err := validateTransactionID(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		txnID := strings.TrimSpace(runtime.Str("transaction-id"))
+		return invokeToolDryRun(token, ToolKindRead, "history_revert_status", historyRevertStatusInput(token, txnID))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		txnID, err := validateTransactionID(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindRead, "history_revert_status", historyRevertStatusInput(token, txnID))
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}

shortcuts/sheets/lark_sheet_history_test.go

@@ -0,0 +1,167 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// TestHistoryShortcuts_DryRun asserts each history shortcut targets the right
+// facade-agg tool, routes through the correct read/write invoke endpoint, and
+// builds the expected tool input (excel_id always; history_version_id for the
+// revert pair).
+func TestHistoryShortcuts_DryRun(t *testing.T) {
+	t.Parallel()
+
+	const versionID = "histVER123"
+	const txnID = "txn-abc-123"
+
+	tests := []struct {
+		name      string
+		sc        common.Shortcut
+		args      []string
+		toolName  string
+		wantPath  string // invoke_read | invoke_write suffix
+		wantInput map[string]interface{}
+	}{
+		{
+			name:     "+history-list via --url",
+			sc:       HistoryList,
+			args:     []string{"--url", testURL},
+			toolName: "history_list",
+			wantPath: "invoke_read",
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+			},
+		},
+		{
+			name:     "+history-list via --spreadsheet-token",
+			sc:       HistoryList,
+			args:     []string{"--spreadsheet-token", testToken},
+			toolName: "history_list",
+			wantPath: "invoke_read",
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+			},
+		},
+		{
+			name:     "+history-list paginates with --end-version",
+			sc:       HistoryList,
+			args:     []string{"--url", testURL, "--end-version", "12345"},
+			toolName: "history_list",
+			wantPath: "invoke_read",
+			wantInput: map[string]interface{}{
+				"excel_id":    testToken,
+				"end_version": float64(12345), // post-JSON-unmarshal numeric type
+			},
+		},
+		{
+			name:     "+history-revert routes to invoke_write with version id",
+			sc:       HistoryRevert,
+			args:     []string{"--url", testURL, "--history-version-id", versionID},
+			toolName: "history_revert",
+			wantPath: "invoke_write",
+			wantInput: map[string]interface{}{
+				"excel_id":           testToken,
+				"history_version_id": versionID,
+			},
+		},
+		{
+			name:     "+history-revert-status routes to invoke_read with transaction id",
+			sc:       HistoryRevertStatus,
+			args:     []string{"--url", testURL, "--transaction-id", txnID},
+			toolName: "history_revert_status",
+			wantPath: "invoke_read",
+			wantInput: map[string]interface{}{
+				"excel_id":       testToken,
+				"transaction_id": txnID,
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			callURL := dryRunFirstCallURL(t, tt.sc, tt.args)
+			if !containsSuffix(callURL, tt.wantPath) {
+				t.Errorf("invoke url = %q, want suffix %q", callURL, tt.wantPath)
+			}
+			body := parseDryRunBody(t, tt.sc, tt.args)
+			got := decodeToolInput(t, body, tt.toolName)
+			assertInputEquals(t, got, tt.wantInput)
+		})
+	}
+}
+
+// TestHistoryRevert_MissingRequiredFlag asserts each shortcut rejects a
+// missing required selector before any request is sent, with two distinct
+// gates by design:
+//
+//   - +history-revert: --history-version-id is cobra-required (Required=true
+//     in the flag def → MarkFlagRequired). cobra refuses the call before
+//     Validate runs with a plain "required flag(s)" error; the cmd dispatcher
+//     classifies it as a typed *errs.ValidationError (invalid_argument, exit 2).
+//     The test rig invokes the shortcut via cmd.Execute and observes the raw
+//     cobra error directly (no dispatcher wrap), so we assert the cobra text
+//     contract instead of the typed envelope.
+//
+//   - +history-revert-status: --transaction-id is cobra-optional;
+//     requiredness is enforced inside Validate so we still get a typed,
+//     flag-tagged *errs.ValidationError with Param="--transaction-id".
+func TestHistoryRevert_MissingRequiredFlag(t *testing.T) {
+	t.Parallel()
+
+	t.Run(HistoryRevert.Command, func(t *testing.T) {
+		t.Parallel()
+		_, _, err := runShortcutCapturingErr(t, HistoryRevert, []string{"--url", testURL})
+		if err == nil {
+			t.Fatalf("%s: expected error for missing --history-version-id", HistoryRevert.Command)
+		}
+		msg := err.Error()
+		if !strings.Contains(msg, "required flag(s)") || !strings.Contains(msg, "history-version-id") {
+			t.Fatalf("%s: cobra error = %q, want substrings 'required flag(s)' and 'history-version-id'", HistoryRevert.Command, msg)
+		}
+	})
+
+	t.Run(HistoryRevertStatus.Command, func(t *testing.T) {
+		t.Parallel()
+		_, _, err := runShortcutCapturingErr(t, HistoryRevertStatus, []string{"--url", testURL})
+		if err == nil {
+			t.Fatalf("%s: expected error for missing --transaction-id", HistoryRevertStatus.Command)
+		}
+		msg := err.Error()
+		if !strings.Contains(msg, "required flag(s)") || !strings.Contains(msg, "transaction-id") {
+			t.Fatalf("%s: cobra error = %q, want substrings 'required flag(s)' and 'transaction-id'", HistoryRevertStatus.Command, msg)
+		}
+	})
+}
+
+// dryRunFirstCallURL runs the shortcut in --dry-run and returns the first
+// api call's url, so tests can assert read vs. write endpoint routing.
+func dryRunFirstCallURL(t *testing.T, sc common.Shortcut, args []string) string {
+	t.Helper()
+	out, err := runShortcut(t, sc, append(args, "--dry-run"))
+	if err != nil {
+		t.Fatalf("dry-run failed: %v\noutput=%s", err, out)
+	}
+	dryRun := decodeDryRunRaw(t, out)
+	calls, ok := dryRun["api"].([]interface{})
+	if !ok || len(calls) == 0 {
+		t.Fatalf("dry-run api array empty or wrong shape: %#v", dryRun)
+	}
+	call, _ := calls[0].(map[string]interface{})
+	url, _ := call["url"].(string)
+	return url
+}
+
+func containsSuffix(s, sub string) bool {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}

shortcuts/sheets/lark_sheet_revision_get.go

@@ -0,0 +1,83 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ─── lark_sheet_revision_get ───────────────────────────────────────────
+//
+// RevisionGet is a read-only derivative over get_workbook_structure that
+// projects out only the document revision (version number). The backend
+// surfaces `revision` on every read/write tool response, so this shortcut
+// needs no dedicated backend tool — it issues the lightest existing read
+// (no range, just the workbook token) and narrows the payload to the single
+// field callers want.
+//
+// The revision is the anchor for recover / undo. Callers that have just run a
+// write already have it in that write's response; +revision-get is the
+// explicit, zero-side-effect way to fetch the current value on its own.
+var RevisionGet = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+revision-get",
+	Description: "Get the spreadsheet's current document revision (version number).",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       flagsFor("+revision-get"),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := resolveSpreadsheetToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		return invokeToolDryRun(token, ToolKindRead, "get_workbook_structure", map[string]interface{}{
+			"excel_id": token,
+		})
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetToken(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindRead, "get_workbook_structure", map[string]interface{}{
+			"excel_id": token,
+		})
+		if err != nil {
+			return err
+		}
+		rev, err := projectRevision(out)
+		if err != nil {
+			return err
+		}
+		runtime.Out(map[string]interface{}{"revision": rev}, nil)
+		return nil
+	},
+	Tips: []string{
+		"The revision is the version anchor for recover / undo; every read and write tool response already carries it.",
+	},
+}
+
+// projectRevision narrows a get_workbook_structure response to its `revision`
+// field. An absent revision means the backend predates revision injection on
+// read responses; surface that as an explicit error rather than emitting a
+// silent null.
+func projectRevision(out interface{}) (interface{}, error) {
+	obj, ok := out.(map[string]interface{})
+	if !ok {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"get_workbook_structure returned non-object output")
+	}
+	rev, ok := obj["revision"]
+	if !ok {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"get_workbook_structure did not return a revision (backend may not support it yet)")
+	}
+	return rev, nil
+}

shortcuts/sheets/lark_sheet_revision_get_test.go

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import "testing"
+
+func TestRevisionGetProjectRevision(t *testing.T) {
+	t.Parallel()
+
+	t.Run("extracts revision from a workbook-structure object", func(t *testing.T) {
+		out := map[string]interface{}{
+			"revision": float64(60),
+			"sheets":   []interface{}{map[string]interface{}{"sheet_id": "Nh34WX"}},
+		}
+		got, err := projectRevision(out)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != float64(60) {
+			t.Errorf("revision = %v, want 60", got)
+		}
+	})
+
+	t.Run("errors when revision is absent", func(t *testing.T) {
+		out := map[string]interface{}{"sheets": []interface{}{}}
+		if _, err := projectRevision(out); err == nil {
+			t.Error("expected an error when revision is missing, got nil")
+		}
+	})
+
+	t.Run("errors on a non-object output", func(t *testing.T) {
+		if _, err := projectRevision("not-an-object"); err == nil {
+			t.Error("expected an error for non-object output, got nil")
+		}
+	})
+}

shortcuts/sheets/lark_sheet_sheet_structure.go

@@ -483,11 +483,11 @@ func dimGroupInput(runtime flagView, token, sheetID, sheetName, op string) (map[
 func parseA1Range(s string) (dimension string, startIdx, endIdx int, err error) {
 	s = strings.TrimSpace(s)
 	if s == "" {
-		return "", 0, 0, fmt.Errorf("range is empty")
+		return "", 0, 0, fmt.Errorf("range is empty") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
 	}
 	parts := strings.Split(s, ":")
 	if len(parts) > 2 {
-		return "", 0, 0, fmt.Errorf("expected \"start:end\" or single element")
+		return "", 0, 0, fmt.Errorf("expected \"start:end\" or single element") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
 	}
 	dim1, idx1, err := parseA1Position(parts[0])
 	if err != nil {
@@ -501,10 +501,10 @@ func parseA1Range(s string) (dimension string, startIdx, endIdx int, err error)
 		return "", 0, 0, err
 	}
 	if dim1 != dim2 {
-		return "", 0, 0, fmt.Errorf("cannot mix row (digits) and column (letters) in one range")
+		return "", 0, 0, fmt.Errorf("cannot mix row (digits) and column (letters) in one range") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
 	}
 	if idx2 < idx1 {
-		return "", 0, 0, fmt.Errorf("end position is before start")
+		return "", 0, 0, fmt.Errorf("end position is before start") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
 	}
 	return dim1, idx1, idx2, nil
 }
@@ -515,7 +515,7 @@ func parseA1Range(s string) (dimension string, startIdx, endIdx int, err error)
 func parseA1Position(s string) (dimension string, idx int, err error) {
 	s = strings.TrimSpace(s)
 	if s == "" {
-		return "", 0, fmt.Errorf("position is empty")
+		return "", 0, fmt.Errorf("position is empty") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
 	}
 	isDigits := true
 	isLetters := true
@@ -530,14 +530,14 @@ func parseA1Position(s string) (dimension string, idx int, err error) {
 	if isDigits {
 		n, _ := strconv.Atoi(s)
 		if n <= 0 {
-			return "", 0, fmt.Errorf("row number must be >= 1 (got %q)", s)
+			return "", 0, fmt.Errorf("row number must be >= 1 (got %q)", s) //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
 		}
 		return "row", n - 1, nil
 	}
 	if isLetters {
 		return "column", letterToColumnIndex(s), nil
 	}
-	return "", 0, fmt.Errorf("expected pure digits (row number) or letters (column letter), got %q", s)
+	return "", 0, fmt.Errorf("expected pure digits (row number) or letters (column letter), got %q", s) //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
 }
 
 // columnIndexToLetter converts a 0-based column index to the spreadsheet

shortcuts/sheets/lark_sheet_table_io.go

@@ -382,6 +382,32 @@ func (p *tablePayload) validate() error {
 			return common.ValidationErrorf("--sheets[%d] %q: mode %q is invalid (want \"overwrite\" or \"append\")", i, s.Name, s.Mode)
 		}
 	}
+	return p.checkCellBudget()
+}
+
+// maxTablePutCells bounds how many cells a single +table-put / +workbook-create
+// write may materialize. Unlike the fan-out stamp cap (maxStampMatrixCells),
+// these cells come from the caller's own --sheets/--values payload rather than a
+// range blow-up, so this is a generous OOM guardrail, not a usability limit:
+// buildSheetMatrix builds the whole rows×cols matrix of per-cell maps in memory
+// before slicing it into tablePutMaxCellsPerWrite-sized writes, so an unbounded
+// payload (2.6M cells ≈ 900MB heap, doubled again by json.Marshal) OOMs the
+// process before the first write leaves.
+const maxTablePutCells = 1_000_000
+
+// checkCellBudget rejects a payload whose total materialized cell count across
+// all sheets exceeds maxTablePutCells. Counted in int64 to stay overflow-safe on
+// pathological row/column counts.
+func (p *tablePayload) checkCellBudget() error {
+	var total int64
+	for i := range p.Sheets {
+		total += int64(len(p.Sheets[i].Rows)) * int64(len(p.Sheets[i].Columns))
+	}
+	if total > maxTablePutCells {
+		return common.ValidationErrorf(
+			"--sheets/--values cover %d cells total, over the %d-cell safety cap; split the write across smaller payloads",
+			total, maxTablePutCells)
+	}
 	return nil
 }
 
@@ -643,7 +669,8 @@ func writeSheetData(ctx context.Context, runtime *common.RuntimeContext, token,
 	if err != nil {
 		return nil, err
 	}
-	if err := applyWorkbookCreateStylesToMatrix(matrix, styles, col0, baseRow, fmt.Sprintf("--styles for sheet %q", s.Name)); err != nil {
+	matrix, err = applyWorkbookCreateStylesToMatrix(matrix, styles, col0, baseRow, fmt.Sprintf("--styles for sheet %q", s.Name))
+	if err != nil {
 		return nil, err
 	}
 
@@ -655,11 +682,15 @@ func writeSheetData(ctx context.Context, runtime *common.RuntimeContext, token,
 		}, nil
 	}
 
+	// styles can pad the matrix wider than the declared columns (cell_styles on
+	// blank cells past the data extent), so the written width comes from the
+	// padded matrix, not ncols.
+	writeCols := len(matrix[0])
 	startCol := columnIndexToLetter(col0)
-	endCol := columnIndexToLetter(col0 + ncols - 1)
+	endCol := columnIndexToLetter(col0 + writeCols - 1)
 	allowOverwrite := s.AllowOverwrite == nil || *s.AllowOverwrite
 
-	rowsPerBatch := tablePutMaxCellsPerWrite / ncols
+	rowsPerBatch := tablePutMaxCellsPerWrite / writeCols
 	if rowsPerBatch < 1 {
 		rowsPerBatch = 1
 	}
@@ -693,7 +724,7 @@ func writeSheetData(ctx context.Context, runtime *common.RuntimeContext, token,
 		"sheet_id":  sheetID,
 		"range":     fmt.Sprintf("%s%d:%s%d", startCol, baseRow+1, endCol, baseRow+len(matrix)),
 		"data_rows": len(s.Rows),
-		"columns":   ncols,
+		"columns":   writeCols,
 		"writes":    writes,
 		"mode":      writeModeName(s),
 	}, nil
@@ -785,7 +816,7 @@ func writeTypedSheets(ctx context.Context, runtime *common.RuntimeContext, token
 		s := &payload.Sheets[i]
 		sheetID, ok := byName[s.Name]
 		if !ok {
-			rows, cols := sheetCreateDims(s)
+			rows, cols := sheetCreateDims(s, styles.styleFor(i))
 			sheetID, err = createSheet(ctx, runtime, token, s.Name, rows, cols)
 			if err != nil {
 				return written, fmt.Errorf("creating sheet %q failed: %w", s.Name, err) //nolint:forbidigo // intermediate error; surfaced as a partial_success message string via tablePutPartial, not a typed final error
@@ -864,10 +895,12 @@ func createSheet(ctx context.Context, runtime *common.RuntimeContext, token, nam
 
 // sheetCreateDims sizes a to-be-created sheet to the spec's write range so the
 // follow-up set_cell_range can't exceed sheet bounds. It accounts for the
-// start_cell offset and the optional header row. The backend's 20×200 defaults
-// are kept as floors (ordinary small tables are created exactly as before) and
-// its hard limits (200 cols, 50000 rows) as ceilings.
-func sheetCreateDims(s *tableSheetSpec) (rows, cols int) {
+// start_cell offset, the optional header row, and any --styles extent (so a
+// cell_styles / merge / resize op past the data still fits the grid). The
+// backend's 20×200 defaults are kept as floors (ordinary small tables are
+// created exactly as before) and its hard limits (200 cols, 50000 rows) as
+// ceilings.
+func sheetCreateDims(s *tableSheetSpec, styles *workbookCreateStylePayload) (rows, cols int) {
 	_, col0, row0, _ := sheetAnchor(s)
 	cols = col0 + len(s.Columns)
 	rows = row0 + len(s.Rows)
@@ -882,6 +915,19 @@ func sheetCreateDims(s *tableSheetSpec) (rows, cols int) {
 	if headerOn(s) || (s.Mode == "append" && s.Header == nil) {
 		rows++
 	}
+	// --styles can reach past the data (cell_styles on blank cells get padded
+	// into the matrix and written; merges / resizes run as separate ops). Size
+	// the grid to cover them too. workbookCreateStyleDimensions returns the
+	// extent relative to the anchor, so add the anchor offset back.
+	if styles != nil {
+		styleRows, styleCols := workbookCreateStyleDimensions(styles, col0, row0)
+		if col0+styleCols > cols {
+			cols = col0 + styleCols
+		}
+		if row0+styleRows > rows {
+			rows = row0 + styleRows
+		}
+	}
 	if cols < 20 {
 		cols = 20
 	}
@@ -979,8 +1025,6 @@ func tablePutDryRun(runtime *common.RuntimeContext) *common.DryRunAPI {
 	for i := range payload.Sheets {
 		s := &payload.Sheets[i]
 		matrix, _ := buildSheetMatrix(s, headerOn(s))
-		desc := fmt.Sprintf("write sheet %q (%d data rows × %d cols, mode=%s) via set_cell_range",
-			s.Name, len(s.Rows), len(s.Columns), writeModeName(s))
 		rng := tablePutFullRange(s, len(matrix))
 		if s.Mode == "append" {
 			rng = "<append below existing data>"
@@ -988,10 +1032,23 @@ func tablePutDryRun(runtime *common.RuntimeContext) *common.DryRunAPI {
 			// cell_styles are merged into the matrix only for overwrite mode,
 			// where the anchor row is known statically; append's base row is
 			// resolved at execute time, so the preview leaves the matrix bare
-			// (the merges / sizes ops below still render).
+			// (the merges / sizes ops below still render). Padding can widen /
+			// lengthen the matrix past the data, so recompute the range from the
+			// padded dims to match what Execute writes.
 			_, col0, row0, _ := sheetAnchor(s)
-			_ = applyWorkbookCreateStylesToMatrix(matrix, sheetStyles.styleFor(i), col0, row0, fmt.Sprintf("--styles for sheet %q", s.Name))
+			matrix, _ = applyWorkbookCreateStylesToMatrix(matrix, sheetStyles.styleFor(i), col0, row0, fmt.Sprintf("--styles for sheet %q", s.Name))
+			if len(matrix) > 0 {
+				rng = fmt.Sprintf("%s%d:%s%d",
+					columnIndexToLetter(col0), row0+1,
+					columnIndexToLetter(col0+len(matrix[0])-1), row0+len(matrix))
+			}
 		}
+		writeCols := len(s.Columns)
+		if len(matrix) > 0 {
+			writeCols = len(matrix[0])
+		}
+		desc := fmt.Sprintf("write sheet %q (%d data rows × %d cols, mode=%s) via set_cell_range",
+			s.Name, len(s.Rows), writeCols, writeModeName(s))
 		input := map[string]interface{}{
 			"excel_id":   token,
 			"sheet_name": s.Name,

shortcuts/sheets/lark_sheet_table_io_test.go

@@ -537,14 +537,15 @@ func TestTablePut_SheetCreateDims(t *testing.T) {
 	cases := []struct {
 		name               string
 		spec               tableSheetSpec
+		styles             *workbookCreateStylePayload
 		wantRows, wantCols int
 	}{
-		{"small table keeps 20x200 floor", tableSheetSpec{Columns: cols(3), Rows: rows(5)}, 200, 20},
-		{"wide table grows columns", tableSheetSpec{Columns: cols(37), Rows: rows(22)}, 200, 37},
-		{"long table grows rows", tableSheetSpec{Columns: cols(3), Rows: rows(500)}, 501, 20},
-		{"start_cell offset adds to both", tableSheetSpec{StartCell: "C5", Columns: cols(40), Rows: rows(5)}, 200, 42},
-		{"header:false drops the header row", tableSheetSpec{Header: bp(false), Columns: cols(3), Rows: rows(500)}, 500, 20},
-		{"columns clamp at backend max 200", tableSheetSpec{Columns: cols(250), Rows: rows(5)}, 200, 200},
+		{"small table keeps 20x200 floor", tableSheetSpec{Columns: cols(3), Rows: rows(5)}, nil, 200, 20},
+		{"wide table grows columns", tableSheetSpec{Columns: cols(37), Rows: rows(22)}, nil, 200, 37},
+		{"long table grows rows", tableSheetSpec{Columns: cols(3), Rows: rows(500)}, nil, 501, 20},
+		{"start_cell offset adds to both", tableSheetSpec{StartCell: "C5", Columns: cols(40), Rows: rows(5)}, nil, 200, 42},
+		{"header:false drops the header row", tableSheetSpec{Header: bp(false), Columns: cols(3), Rows: rows(500)}, nil, 500, 20},
+		{"columns clamp at backend max 200", tableSheetSpec{Columns: cols(250), Rows: rows(5)}, nil, 200, 200},
 		// Default headerOn() is false for append mode, but writeSheetData forces
 		// a header when append hits an empty sheet with no explicit Header
 		// choice (so column names aren't lost). sheetCreateDims runs only on
@@ -552,14 +553,22 @@ func TestTablePut_SheetCreateDims(t *testing.T) {
 		// match: append + Header=nil ⇒ +1 row. Otherwise an append-near-50000
 		// payload would be created one row short.
 		{"append on new sheet sizes for the forced header row (49999 data rows + 1 header = 50000)",
-			tableSheetSpec{Mode: "append", Columns: cols(3), Rows: rows(49999)}, 50000, 20},
+			tableSheetSpec{Mode: "append", Columns: cols(3), Rows: rows(49999)}, nil, 50000, 20},
 		{"append + Header=false (explicit) does NOT add the forced header row",
-			tableSheetSpec{Mode: "append", Header: bp(false), Columns: cols(3), Rows: rows(50)}, 200, 20},
+			tableSheetSpec{Mode: "append", Header: bp(false), Columns: cols(3), Rows: rows(50)}, nil, 200, 20},
+		// --styles reaching past the data grows the grid so a cell_styles op on a
+		// blank cell (or a merge / resize) still fits after the create.
+		{"styles past the data grow the grid",
+			tableSheetSpec{Columns: cols(3), Rows: rows(5)},
+			&workbookCreateStylePayload{CellStyles: []workbookCreateCellStyleOp{{Range: "A1:Z400"}}}, 400, 26},
+		{"styles inside the data don't shrink the grid",
+			tableSheetSpec{Columns: cols(3), Rows: rows(5)},
+			&workbookCreateStylePayload{CellStyles: []workbookCreateCellStyleOp{{Range: "A1:B2"}}}, 200, 20},
 	}
 	for _, tt := range cases {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-			gotRows, gotCols := sheetCreateDims(&tt.spec)
+			gotRows, gotCols := sheetCreateDims(&tt.spec, tt.styles)
 			if gotRows != tt.wantRows || gotCols != tt.wantCols {
 				t.Errorf("sheetCreateDims = (%d rows, %d cols), want (%d, %d)", gotRows, gotCols, tt.wantRows, tt.wantCols)
 			}

shortcuts/sheets/lark_sheet_undo.go

@@ -0,0 +1,59 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var Undo = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+undo",
+	Description: "Undo the current user's latest spreadsheet write.",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	// History shortcuts keep locator flags hand-written because they share
+	// revision/revert helpers; keep --count here in sync with sheet-skill-spec.
+	Flags: append(historyLocatorFlags(),
+		common.Flag{Name: "count", Type: "int", Default: "1", Desc: "Number of user undo stack entries to undo sequentially (1-20)."},
+	),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := resolveSpreadsheetToken(runtime); err != nil {
+			return err
+		}
+		if runtime.Int("count") < 1 || runtime.Int("count") > 20 {
+			return sheetsValidationForFlag("count", "--count must be between 1 and 20")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		return invokeToolDryRun(token, ToolKindWrite, "undo_last", undoInput(runtime, token))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindWrite, "undo_last", undoInput(runtime, token))
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+func undoInput(runtime *common.RuntimeContext, token string) map[string]interface{} {
+	// Always send count, including the default 1, so dry-run mirrors the exact
+	// request body sent by Execute.
+	return map[string]interface{}{
+		"excel_id": token,
+		"count":    runtime.Int("count"),
+	}
+}

shortcuts/sheets/lark_sheet_undo_test.go

@@ -0,0 +1,141 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestUndo_DryRun(t *testing.T) {
+	t.Parallel()
+
+	args := []string{"--url", testURL, "--as", "user"}
+	callURL := dryRunFirstCallURL(t, Undo, args)
+	if !containsSuffix(callURL, "invoke_write") {
+		t.Errorf("invoke url = %q, want invoke_write", callURL)
+	}
+
+	body := parseDryRunBody(t, Undo, args)
+	got := decodeToolInput(t, body, "undo_last")
+	assertInputEquals(t, got, map[string]interface{}{
+		"excel_id": testToken,
+		"count":    float64(1),
+	})
+}
+
+func TestExecute_Undo(t *testing.T) {
+	t.Parallel()
+
+	stub := toolOutputStub(testToken, "write", `{"undone":3,"op_id":"op-3","top_doc_revision":30,"new_revision":31,"op_ids":["op-3","op-2","op-1"],"results":[{"op_id":"op-3","top_doc_revision":30,"new_revision":31},{"op_id":"op-2","top_doc_revision":20,"new_revision":32},{"op_id":"op-1","top_doc_revision":10,"new_revision":33}]}`)
+	out, err := runShortcutWithStubs(t, Undo, []string{"--url", testURL, "--count", "3", "--as", "user"}, stub)
+	if err != nil {
+		t.Fatalf("execute failed: %v\nout=%s", err, out)
+	}
+
+	body := decodeRawEnvelopeBody(t, stub.CapturedBody)
+	input := decodeToolInput(t, body, "undo_last")
+	assertInputEquals(t, input, map[string]interface{}{
+		"excel_id": testToken,
+		"count":    float64(3),
+	})
+
+	data := decodeEnvelopeData(t, out)
+	if data["undone"].(float64) != 3 {
+		t.Fatalf("unexpected output data: %#v", data)
+	}
+	results := data["results"].([]interface{})
+	first := results[0].(map[string]interface{})
+	if data["op_id"] != first["op_id"] ||
+		data["top_doc_revision"] != first["top_doc_revision"] ||
+		data["new_revision"] != first["new_revision"] {
+		t.Fatalf("legacy fields are not aligned with first result: %#v", data)
+	}
+}
+
+func TestUndo_ValidateCount(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		count   string
+		wantSub string
+	}{
+		{name: "zero", count: "0", wantSub: "--count must be between 1 and 20"},
+		{name: "negative", count: "-1", wantSub: "--count must be between 1 and 20"},
+		{name: "too large", count: "21", wantSub: "--count must be between 1 and 20"},
+		{name: "non integer", count: "1.5", wantSub: "invalid argument"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			_, err := runShortcutWithStubs(t, Undo, []string{"--url", testURL, "--count", tt.count, "--as", "user"})
+			if err == nil {
+				t.Fatal("expected count validation error")
+			}
+			if !strings.Contains(err.Error(), tt.wantSub) {
+				t.Fatalf("unexpected error: %v", err)
+			}
+		})
+	}
+}
+
+func TestExecute_UndoReasonOutputs(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name       string
+		outputJSON string
+		wantReason string
+		wantUndone float64
+	}{
+		{
+			name:       "partial success because requested count exceeds stack",
+			outputJSON: `{"undone":2,"reason":"undo_stack_empty","op_ids":["op-2","op-1"],"results":[{"op_id":"op-2"},{"op_id":"op-1"}],"warning_message":"Requested 3 undo step(s), but only 2 active undo entries were available."}`,
+			wantReason: "undo_stack_empty",
+			wantUndone: 2,
+		},
+		{
+			name:       "raw undo changeset missing or expired",
+			outputJSON: `{"undone":0,"reason":"undo_entry_missing","warning_message":"The undo stack entry points to raw undo changeset data that is missing or expired. Use history_list/history_revert to roll the spreadsheet back via history."}`,
+			wantReason: "undo_entry_missing",
+			wantUndone: 0,
+		},
+		{
+			name:       "unsupported object undo",
+			outputJSON: `{"undone":0,"reason":"unsupported_object_undo","warning_message":"The top undo entry contains changes this undo implementation cannot replay."}`,
+			wantReason: "unsupported_object_undo",
+			wantUndone: 0,
+		},
+		{
+			name:       "apply failed",
+			outputJSON: `{"undone":0,"reason":"undo_apply_failed","warning_message":"Failed to apply the top undo entry."}`,
+			wantReason: "undo_apply_failed",
+			wantUndone: 0,
+		},
+		{
+			name:       "marker persist failed after apply",
+			outputJSON: `{"undone":1,"reason":"undo_state_persist_failed","op_ids":["op-1"],"results":[{"op_id":"op-1","reason":"undo_state_persist_failed","warning_message":"Undo was applied, but the marker was not persisted."}]}`,
+			wantReason: "undo_state_persist_failed",
+			wantUndone: 1,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			stub := toolOutputStub(testToken, "write", tt.outputJSON)
+			out, err := runShortcutWithStubs(t, Undo, []string{"--url", testURL, "--as", "user"}, stub)
+			if err != nil {
+				t.Fatalf("execute failed: %v\nout=%s", err, out)
+			}
+			data := decodeEnvelopeData(t, out)
+			if data["undone"].(float64) != tt.wantUndone || data["reason"] != tt.wantReason {
+				t.Fatalf("unexpected output data: %#v", data)
+			}
+			if tt.wantReason == "undo_entry_missing" && !strings.Contains(data["warning_message"].(string), "history_list/history_revert") {
+				t.Fatalf("missing history fallback hint: %#v", data)
+			}
+		})
+	}
+}

shortcuts/sheets/lark_sheet_workbook.go

@@ -123,6 +123,26 @@ func sheetCreateInput(runtime flagView, token string) (map[string]interface{}, e
 	if strings.TrimSpace(runtime.Str("title")) == "" {
 		return nil, common.ValidationErrorf("--title is required")
 	}
+	// --type bitable 建一张空白多维表格子表（operation=create_bitable）；默认 sheet 为普通
+	// 电子表格子表。bitable 子表内容编辑走 lark-base 命令，row-count/col-count 不适用。
+	sheetType := strings.TrimSpace(runtime.Str("type"))
+	if sheetType == "" {
+		sheetType = "sheet"
+	}
+	if sheetType != "sheet" && sheetType != "bitable" {
+		return nil, common.ValidationErrorf("--type must be 'sheet' or 'bitable'")
+	}
+	if sheetType == "bitable" {
+		input := map[string]interface{}{
+			"excel_id":   token,
+			"operation":  "create_bitable",
+			"sheet_name": strings.TrimSpace(runtime.Str("title")),
+		}
+		if runtime.Changed("index") {
+			input["target_index"] = runtime.Int("index")
+		}
+		return input, nil
+	}
 	if n := runtime.Int("row-count"); n < 0 || n > 50000 {
 		return nil, common.ValidationErrorf("--row-count must be between 0 and 50000")
 	}
@@ -634,16 +654,26 @@ var WorkbookCreate = common.Shortcut{
 			s := &payload.Sheets[i]
 			matrix, _ := buildSheetMatrix(s, headerOn(s))
 			_, col0, row0, _ := sheetAnchor(s)
-			_ = applyWorkbookCreateStylesToMatrix(matrix, sheetStyles.styleFor(i), col0, row0, fmt.Sprintf("--styles for sheet %q", s.Name))
+			matrix, _ = applyWorkbookCreateStylesToMatrix(matrix, sheetStyles.styleFor(i), col0, row0, fmt.Sprintf("--styles for sheet %q", s.Name))
+			// Padding can widen / lengthen the matrix past the data, so build the
+			// range from the padded dims to match what Execute writes.
+			rng := tablePutFullRange(s, len(matrix))
+			writeCols := len(s.Columns)
+			if len(matrix) > 0 {
+				writeCols = len(matrix[0])
+				rng = fmt.Sprintf("%s%d:%s%d",
+					columnIndexToLetter(col0), row0+1,
+					columnIndexToLetter(col0+writeCols-1), row0+len(matrix))
+			}
 			input := map[string]interface{}{
 				"excel_id":   "<new-token>",
 				"sheet_name": s.Name,
-				"range":      tablePutFullRange(s, len(matrix)),
+				"range":      rng,
 				"cells":      matrix,
 			}
 			wireBody, _ := buildToolBody("set_cell_range", input)
 			dry.POST("/open-apis/sheet_ai/v2/spreadsheets/<new-token>/tools/invoke_write").
-				Desc(fmt.Sprintf("write sheet %q (%d data rows × %d cols) via set_cell_range", s.Name, len(s.Rows), len(s.Columns))).
+				Desc(fmt.Sprintf("write sheet %q (%d data rows × %d cols) via set_cell_range", s.Name, len(s.Rows), writeCols)).
 				Body(wireBody)
 			appendWorkbookCreateVisualOpsDryRun(dry, "<new-token>", "", s.Name, sheetStyles.styleFor(i))
 		}
@@ -836,13 +866,19 @@ func buildValuesPayload(runtime flagView, sheetStyles *workbookCreateSheetStyles
 		cols[i] = tableColumnSpec{Name: fmt.Sprintf("col%d", i+1)} // type-less
 	}
 	noHeader := false
-	return &tablePayload{Sheets: []tableSheetSpec{{
+	payload := &tablePayload{Sheets: []tableSheetSpec{{
 		Name:    valuesSheetName,
 		Mode:    "overwrite",
 		Header:  &noHeader,
 		Columns: cols,
 		Rows:    rows,
-	}}}, nil
+	}}}
+	// --values bypasses tablePayload.validate(), so enforce the cell budget here
+	// too — otherwise a giant --values array materializes unbounded.
+	if err := payload.checkCellBudget(); err != nil {
+		return nil, err
+	}
+	return payload, nil
 }
 
 // parseValuesRows decodes --values (JSON 2D array, with @file/stdin already
@@ -1246,7 +1282,7 @@ func normalizeWorkbookCreateStyleObject(in map[string]interface{}, path string)
 
 func workbookCreateCellStyleField(name string) bool {
 	switch name {
-	case "font_color", "font_size", "font_weight", "font_style", "font_line",
+	case "font_color", "font_family", "font_size", "font_weight", "font_style", "font_line",
 		"background_color", "horizontal_alignment", "vertical_alignment",
 		"number_format", "word_wrap":
 		return true
@@ -1357,20 +1393,79 @@ func workbookCreateStyleDimensions(styles *workbookCreateStylePayload, baseCol,
 	return rows, cols
 }
 
-func applyWorkbookCreateStylesToMatrix(rows [][]interface{}, styles *workbookCreateStylePayload, baseCol, baseRow int, label string) error {
+// padMatrixForStyles grows the matrix down and right so it covers every
+// cell_styles range, appending empty cells for the positions the data doesn't
+// reach. cell_styles are applied by writing into the matrix in place (see
+// applyWorkbookCreateStylesToMatrix), so a style on a cell past the data extent
+// needs a real — if empty — cell to attach to. This lets a create/write set
+// styles on blank cells (reserved regions, decorative headers, empty borders).
+//
+// Only cell_styles contribute to the extent: cell_merges / row_sizes / col_sizes
+// run as separate API calls (see workbookCreateVisualOps) and never touch the
+// matrix. Ranges that start left of baseCol or above baseRow are skipped here
+// (the matrix can only extend down/right) and left for the caller to reject.
+// The (possibly reallocated) matrix is returned; callers must use the result.
+func padMatrixForStyles(rows [][]interface{}, styles *workbookCreateStylePayload, baseCol, baseRow int) [][]interface{} {
 	if styles == nil {
-		return nil
+		return rows
 	}
+	needRows := len(rows)
+	needCols := 0
+	if len(rows) > 0 {
+		needCols = len(rows[0])
+	}
+	for _, op := range styles.CellStyles {
+		startCol, startRow, endCol, endRow, err := workbookCreateStyleRangeBounds(op.Range)
+		if err != nil || startCol < baseCol || startRow < baseRow {
+			continue // unparsable, or up/left of the anchor: not paddable
+		}
+		if endCol-baseCol+1 > needCols {
+			needCols = endCol - baseCol + 1
+		}
+		if endRow-baseRow+1 > needRows {
+			needRows = endRow - baseRow + 1
+		}
+	}
+	// Widen existing rows to needCols.
+	for r := range rows {
+		for len(rows[r]) < needCols {
+			rows[r] = append(rows[r], map[string]interface{}{})
+		}
+	}
+	// Append full empty rows to reach needRows.
+	for len(rows) < needRows {
+		row := make([]interface{}, needCols)
+		for c := range row {
+			row[c] = map[string]interface{}{}
+		}
+		rows = append(rows, row)
+	}
+	return rows
+}
+
+// applyWorkbookCreateStylesToMatrix pads the matrix to cover the cell_styles
+// ranges (see padMatrixForStyles), merges each op's style into the covered
+// cells, and returns the padded matrix. A range that starts left of / above the
+// write anchor can't be padded to and is rejected.
+func applyWorkbookCreateStylesToMatrix(rows [][]interface{}, styles *workbookCreateStylePayload, baseCol, baseRow int, label string) ([][]interface{}, error) {
+	if styles == nil {
+		return rows, nil
+	}
+	rows = padMatrixForStyles(rows, styles, baseCol, baseRow)
 	for i, op := range styles.CellStyles {
 		startCol, startRow, endCol, endRow, err := workbookCreateStyleRangeBounds(op.Range)
 		if err != nil {
-			return common.ValidationErrorf("%s[%d].range %q: %v", label, i, op.Range, err)
+			return rows, common.ValidationErrorf("%s[%d].range %q: %v", label, i, op.Range, err)
 		}
-		if startCol < baseCol || startRow < baseRow || endRow-baseRow >= len(rows) || len(rows) == 0 || endCol-baseCol >= len(rows[0]) {
-			return common.ValidationErrorf("%s[%d].range %q is outside the write range %s%d:%s%d",
+		// After padding, the matrix reaches every range that starts at or after
+		// the anchor; a start left of / above it can't be covered. The endRow /
+		// endCol checks stay as a defensive backstop (padding should have made
+		// them unreachable).
+		if startCol < baseCol || startRow < baseRow || len(rows) == 0 ||
+			endRow-baseRow >= len(rows) || endCol-baseCol >= len(rows[0]) {
+			return rows, common.ValidationErrorf("%s[%d].range %q starts outside the write range (its top-left must be at or after %s%d)",
 				label, i, op.Range,
-				columnIndexToLetter(baseCol), baseRow+1,
-				columnIndexToLetter(baseCol+len(rows[0])-1), baseRow+len(rows))
+				columnIndexToLetter(baseCol), baseRow+1)
 		}
 		for r := startRow - baseRow; r <= endRow-baseRow; r++ {
 			for c := startCol - baseCol; c <= endCol-baseCol; c++ {
@@ -1378,7 +1473,7 @@ func applyWorkbookCreateStylesToMatrix(rows [][]interface{}, styles *workbookCre
 			}
 		}
 	}
-	return nil
+	return rows, nil
 }
 
 func appendWorkbookCreateVisualOpsDryRun(dry *common.DryRunAPI, token, sheetID, sheetName string, styles *workbookCreateStylePayload) {

shortcuts/sheets/lark_sheet_workbook_test.go

@@ -396,6 +396,37 @@ func TestWorkbookCreate_DryRun(t *testing.T) {
 			t.Errorf("horizontal_alignment occurrences = %d, want 4 in 2x2 range; cells=%s", got, raw)
 		}
 	})
+
+	t.Run("cell style past the data pads empty cells so blank cells can be styled", func(t *testing.T) {
+		t.Parallel()
+		// Data is a single cell (A1), but the style targets A1:C3 — the matrix is
+		// padded to 3x3 with empty cells so the style range fits, letting blank
+		// cells carry styling. The written range must reflect the padded extent.
+		calls := parseDryRunAPI(t, WorkbookCreate, []string{
+			"--title", "X",
+			"--values", `[["a"]]`,
+			"--styles", `{"styles":[{"name":"Sheet1","cell_styles":[{"range":"A1:C3","background_color":"#FFEEAA"}]}]}`,
+		})
+		body, _ := calls[1].(map[string]interface{})["body"].(map[string]interface{})
+		input := decodeToolInput(t, body, "set_cell_range")
+		if input["range"] != "A1:C3" {
+			t.Errorf("range = %v, want A1:C3 (padded to the style extent)", input["range"])
+		}
+		cells, _ := input["cells"].([]interface{})
+		if len(cells) != 3 {
+			t.Fatalf("cells rows = %d, want 3 (padded); cells=%#v", len(cells), input["cells"])
+		}
+		lastRow, _ := cells[2].([]interface{})
+		if len(lastRow) != 3 {
+			t.Fatalf("last row width = %d, want 3 (padded)", len(lastRow))
+		}
+		// A blank padded cell (C3) still carries the style.
+		c3, _ := lastRow[2].(map[string]interface{})
+		c3s, _ := c3["cell_styles"].(map[string]interface{})
+		if c3s["background_color"] != "#FFEEAA" {
+			t.Errorf("padded blank cell C3 style = %#v, want background_color", c3)
+		}
+	})
 	t.Run("style-only payload (cell_merges) still fills and emits merge_cells", func(t *testing.T) {
 		t.Parallel()
 		// Previously workbookCreateStyleDimensions only counted cell_styles, so a
@@ -595,3 +626,60 @@ func deepEqualJSON(a, b interface{}) bool {
 	}
 	return a == b
 }
+
+// TestApplyWorkbookCreateStylesToMatrix covers the pad-then-style behavior
+// directly: a style range past the data grows the matrix with empty cells (so
+// blank cells can be styled), an in-range style leaves the matrix size alone,
+// and a range up/left of the anchor — which padding can't reach — is rejected.
+func TestApplyWorkbookCreateStylesToMatrix(t *testing.T) {
+	t.Parallel()
+	cell := func() interface{} { return map[string]interface{}{} }
+
+	t.Run("pads down and right for a style past the data", func(t *testing.T) {
+		t.Parallel()
+		matrix := [][]interface{}{{cell()}} // 1x1 data
+		styles := &workbookCreateStylePayload{CellStyles: []workbookCreateCellStyleOp{
+			{Range: "A1:C3", Style: map[string]interface{}{"cell_styles": map[string]interface{}{"background_color": "#FFEEAA"}}},
+		}}
+		out, err := applyWorkbookCreateStylesToMatrix(matrix, styles, 0, 0, "--styles")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(out) != 3 || len(out[0]) != 3 || len(out[2]) != 3 {
+			t.Fatalf("padded matrix = %d rows x %v cols, want 3x3", len(out), out)
+		}
+		// A blank padded corner (C3) carries the style.
+		c3, _ := out[2][2].(map[string]interface{})
+		c3s, _ := c3["cell_styles"].(map[string]interface{})
+		if c3s["background_color"] != "#FFEEAA" {
+			t.Errorf("padded cell C3 = %#v, want background_color", c3)
+		}
+	})
+
+	t.Run("no pad when the style is within the data", func(t *testing.T) {
+		t.Parallel()
+		matrix := [][]interface{}{{cell(), cell()}, {cell(), cell()}} // 2x2 data
+		styles := &workbookCreateStylePayload{CellStyles: []workbookCreateCellStyleOp{
+			{Range: "A1:B2", Style: map[string]interface{}{"cell_styles": map[string]interface{}{"font_weight": "bold"}}},
+		}}
+		out, err := applyWorkbookCreateStylesToMatrix(matrix, styles, 0, 0, "--styles")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(out) != 2 || len(out[0]) != 2 {
+			t.Errorf("matrix = %dx%d, want 2x2 (no pad)", len(out), len(out[0]))
+		}
+	})
+
+	t.Run("rejects a range up/left of the anchor", func(t *testing.T) {
+		t.Parallel()
+		matrix := [][]interface{}{{cell()}} // anchored at C3 (col 2, row 2)
+		styles := &workbookCreateStylePayload{CellStyles: []workbookCreateCellStyleOp{
+			{Range: "A1", Style: map[string]interface{}{"cell_styles": map[string]interface{}{"font_weight": "bold"}}},
+		}}
+		_, err := applyWorkbookCreateStylesToMatrix(matrix, styles, 2, 2, "--styles")
+		if err == nil || !strings.Contains(err.Error(), "starts outside the write range") {
+			t.Errorf("err = %v, want 'starts outside the write range'", err)
+		}
+	})
+}

shortcuts/sheets/lark_sheet_write_cells.go

@@ -111,10 +111,10 @@ func cellsSetInput(runtime flagView, token, sheetID, sheetName string) (map[stri
 
 // CellsSetStyle stamps a single style block across every cell in --range.
 // Style is composed from a dozen flat flags (background-color, font-color,
-// font-size, font-style, font-weight, font-line, horizontal-alignment,
-// vertical-alignment, word-wrap, number-format) plus --border-styles for
-// the only field that still needs a nested object. At least one flag must
-// be set.
+// font-family, font-size, font-style, font-weight, font-line,
+// horizontal-alignment, vertical-alignment, word-wrap, number-format) plus
+// --border-styles for the only field that still needs a nested object. At
+// least one flag must be set.
 var CellsSetStyle = common.Shortcut{
 	Service:     "sheets",
 	Command:     "+cells-set-style",
@@ -165,6 +165,9 @@ func cellsSetStyleInput(runtime flagView, token, sheetID, sheetName string) (map
 	if err != nil {
 		return nil, sheetsValidationForFlag("range", "--range %q: %v", rangeStr, err)
 	}
+	if err := checkStampMatrixBudget("range", rangeStr, rows, cols); err != nil {
+		return nil, err
+	}
 	if err := requireAnyStyleFlag(runtime); err != nil {
 		return nil, err
 	}
@@ -450,6 +453,9 @@ func dropdownSetInput(runtime flagView, token, sheetID, sheetName string) (map[s
 	if err != nil {
 		return nil, sheetsValidationForFlag("range", "--range %q: %v", rangeStr, err)
 	}
+	if err := checkStampMatrixBudget("range", rangeStr, rows, cols); err != nil {
+		return nil, err
+	}
 	validation, err := buildDropdownValidation(runtime)
 	if err != nil {
 		return nil, err
@@ -625,23 +631,23 @@ func rangeDimensions(rangeStr string) (rows, cols int, err error) {
 	}
 	rangeStr = strings.TrimSpace(rangeStr)
 	if rangeStr == "" {
-		return 0, 0, fmt.Errorf("empty range")
+		return 0, 0, fmt.Errorf("empty range") //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
 	}
 	parts := strings.SplitN(rangeStr, ":", 2)
 	if len(parts) == 1 {
 		// single cell, e.g. "A1"
 		if _, _, ok := splitCellRef(parts[0]); !ok {
-			return 0, 0, fmt.Errorf("invalid cell ref %q", parts[0])
+			return 0, 0, fmt.Errorf("invalid cell ref %q", parts[0]) //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
 		}
 		return 1, 1, nil
 	}
 	startCol, startRow, ok1 := splitCellRef(parts[0])
 	endCol, endRow, ok2 := splitCellRef(parts[1])
 	if !ok1 || !ok2 {
-		return 0, 0, fmt.Errorf("unsupported range form %q (need rectangular A1:B2)", rangeStr)
+		return 0, 0, fmt.Errorf("unsupported range form %q (need rectangular A1:B2)", rangeStr) //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
 	}
 	if endRow < startRow || endCol < startCol {
-		return 0, 0, fmt.Errorf("end %q must be at or after start %q", parts[1], parts[0])
+		return 0, 0, fmt.Errorf("end %q must be at or after start %q", parts[1], parts[0]) //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
 	}
 	return endRow - startRow + 1, endCol - startCol + 1, nil
 }
@@ -692,9 +698,30 @@ func letterToColumnIndex(letters string) int {
 	return n - 1
 }
 
+// maxStampMatrixCells bounds how many per-cell maps a fan-out / stamp shortcut
+// will materialize from a single A1 range. The backing tools take an explicit
+// cells matrix, so the CLI must expand a range like "A1:Z100000" into rows×cols
+// maps before sending it — an unbounded blow-up (2.6M cells ≈ 900MB heap, then
+// doubled again by json.Marshal) that OOMs the process before the request even
+// leaves. 200000 matches the documented --max-cells safety cap.
+const maxStampMatrixCells = 200000
+
+// checkStampMatrixBudget rejects a range whose materialized cell count would
+// exceed maxStampMatrixCells, before fillCellsMatrix allocates it. rows*cols is
+// computed in int64 to stay safe against overflow on pathological ranges.
+func checkStampMatrixBudget(flagName, rangeStr string, rows, cols int) error {
+	if total := int64(rows) * int64(cols); total > maxStampMatrixCells {
+		return sheetsValidationForFlag(flagName,
+			"range %q covers %d cells, over the %d-cell safety cap; narrow the range or split it across smaller ranges",
+			rangeStr, total, maxStampMatrixCells)
+	}
+	return nil
+}
+
 // fillCellsMatrix returns a rows×cols matrix where every cell is the same
 // (shallow-copied) prototype map. Use for fan-out shortcuts that stamp a
 // single attribute (style / data_validation) across an entire range.
+// Callers MUST gate the dimensions through checkStampMatrixBudget first.
 func fillCellsMatrix(rows, cols int, prototype map[string]interface{}) [][]interface{} {
 	cells := make([][]interface{}, rows)
 	for r := range cells {

shortcuts/sheets/sheet_media_parent_type_test.go

@@ -25,8 +25,8 @@ import (
 
 // TestSheetMediaParentType pins the token→parent_type mapping that every
 // sheets image-upload entry point funnels through. Native spreadsheet tokens
-// use "sheet_image"; imported "office" spreadsheets carry a "fake_office_"
-// synthetic token and must upload with "office_sheet_file".
+// use "sheet_image"; imported "office" spreadsheets carry a "fake_office_" or
+// "local_office_" synthetic token and must upload with "office_sheet_file".
 func TestSheetMediaParentType(t *testing.T) {
 	t.Parallel()
 	cases := []struct {
@@ -36,9 +36,12 @@ func TestSheetMediaParentType(t *testing.T) {
 	}{
 		{"native spreadsheet token", "shtcnABC123", sheetImageParentType},
 		{"empty token", "", sheetImageParentType},
-		{"office imported token", "fake_office_abc123", officeSheetFileParentType},
-		{"office token, only the prefix", fakeOfficeTokenPrefix, officeSheetFileParentType},
-		{"prefix mid-string is not matched", "shtfake_office_abc", sheetImageParentType},
+		{"fake_office imported token", "fake_office_abc123", officeSheetFileParentType},
+		{"fake_office token, only the prefix", fakeOfficeTokenPrefix, officeSheetFileParentType},
+		{"local_office imported token", "local_office_abc123", officeSheetFileParentType},
+		{"local_office token, only the prefix", localOfficeTokenPrefix, officeSheetFileParentType},
+		{"fake_office prefix mid-string is not matched", "shtfake_office_abc", sheetImageParentType},
+		{"local_office prefix mid-string is not matched", "shtlocal_office_abc", sheetImageParentType},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
@@ -62,7 +65,8 @@ func TestUploadSheetImage_ParentType(t *testing.T) {
 		wantParentType string
 	}{
 		{"native spreadsheet", "shtcnTOK123", sheetImageParentType},
-		{"office imported spreadsheet", "fake_office_abc123", officeSheetFileParentType},
+		{"fake_office imported spreadsheet", "fake_office_abc123", officeSheetFileParentType},
+		{"local_office imported spreadsheet", "local_office_abc123", officeSheetFileParentType},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {

shortcuts/sheets/sheets_perf_bench_test.go

@@ -0,0 +1,272 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+// These benchmarks back the memory review of the sheets fan-out / download
+// paths. They measure two hot spots:
+//
+//   1. fillCellsMatrix — fan-out shortcuts (+cells-set-style, +dropdown-set,
+//      +cells-batch-set-style, +dropdown-update) expand one A1 range into a
+//      rows×cols matrix of per-cell maps. A tiny input string ("A1:Z100000")
+//      explodes into millions of heap maps with no upper bound.
+//
+//   2. the export-download reader — strings.NewReader(string(rawBody)) copies
+//      the whole downloaded file once more before saving it.
+//
+// Run: go test ./shortcuts/sheets -run XXX -bench 'FillCellsMatrix|DownloadReader' -benchmem
+
+var styleProto = map[string]interface{}{
+	"cell_styles":   map[string]interface{}{"bold": true, "fg_color": "#FF0000"},
+	"border_styles": map[string]interface{}{"top": map[string]interface{}{"style": "solid"}},
+}
+
+func benchFillCellsMatrix(b *testing.B, rows, cols int) {
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		m := fillCellsMatrix(rows, cols, styleProto)
+		if len(m) != rows {
+			b.Fatalf("bad matrix")
+		}
+	}
+}
+
+func BenchmarkFillCellsMatrix_100(b *testing.B)   { benchFillCellsMatrix(b, 10, 10) }     // A1:J10
+func BenchmarkFillCellsMatrix_10K(b *testing.B)   { benchFillCellsMatrix(b, 1000, 10) }   // A1:J1000
+func BenchmarkFillCellsMatrix_100K(b *testing.B)  { benchFillCellsMatrix(b, 10000, 10) }  // A1:J10000
+func BenchmarkFillCellsMatrix_2600K(b *testing.B) { benchFillCellsMatrix(b, 100000, 26) } // A1:Z100000
+
+// TestFanoutMatrixPeakMemory reports the concrete resident-heap delta of
+// materializing a large fan-out matrix, so the review doc can quote real MB.
+// Not an assertion — it prints numbers under `go test -v -run PeakMemory`.
+func TestFanoutMatrixPeakMemory(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping memory probe in -short")
+	}
+	cases := []struct {
+		name       string
+		rows, cols int
+	}{
+		{"A1:Z10000 (260K cells)", 10000, 26},
+		{"A1:Z100000 (2.6M cells)", 100000, 26},
+	}
+	for _, c := range cases {
+		var before, after runtime.MemStats
+		runtime.GC()
+		runtime.ReadMemStats(&before)
+		m := fillCellsMatrix(c.rows, c.cols, styleProto)
+		runtime.ReadMemStats(&after)
+		runtime.KeepAlive(m)
+		t.Logf("%-26s heap +%6.1f MB  (%d total allocs)",
+			c.name,
+			float64(after.HeapAlloc-before.HeapAlloc)/(1024*1024),
+			after.Mallocs-before.Mallocs)
+	}
+}
+
+// --- +table-put / +workbook-create matrix materialization (sibling #1 path) ---
+//
+// buildSheetMatrix turns the caller's --sheets/--values into a rows×cols matrix
+// of per-cell maps, the same unbounded blow-up as fillCellsMatrix but on the
+// table-put ingress (tablePutMaxCellsPerWrite only slices the *write*, not this
+// in-memory build). checkCellBudget rejects oversized payloads before this runs.
+
+func makeTypelessSpec(rows, cols int) *tableSheetSpec {
+	c := make([]tableColumnSpec, cols)
+	r := make([][]interface{}, rows)
+	for i := range r {
+		row := make([]interface{}, cols)
+		for j := range row {
+			row[j] = "x"
+		}
+		r[i] = row
+	}
+	return &tableSheetSpec{Columns: c, Rows: r}
+}
+
+func benchBuildSheetMatrix(b *testing.B, rows, cols int) {
+	spec := makeTypelessSpec(rows, cols)
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		m, err := buildSheetMatrix(spec, true)
+		if err != nil || len(m) != rows+1 {
+			b.Fatalf("bad matrix")
+		}
+	}
+}
+
+func BenchmarkBuildSheetMatrix_100K(b *testing.B)  { benchBuildSheetMatrix(b, 10000, 10) }  // 100K cells
+func BenchmarkBuildSheetMatrix_2600K(b *testing.B) { benchBuildSheetMatrix(b, 100000, 26) } // 2.6M cells
+
+// TestTablePutMatrixPeakMemory reports the resident-heap delta of materializing
+// a large table-put matrix (the cost checkCellBudget now prevents), so the
+// review doc can quote real MB. Not an assertion — prints under -v -run PeakMemory.
+func TestTablePutMatrixPeakMemory(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping memory probe in -short")
+	}
+	for _, c := range []struct {
+		name       string
+		rows, cols int
+	}{
+		{"100000×26 (2.6M cells)", 100000, 26},
+	} {
+		spec := makeTypelessSpec(c.rows, c.cols)
+		var before, after runtime.MemStats
+		runtime.GC()
+		runtime.ReadMemStats(&before)
+		m, _ := buildSheetMatrix(spec, true)
+		runtime.ReadMemStats(&after)
+		runtime.KeepAlive(m)
+		t.Logf("%-24s buildSheetMatrix heap +%6.1f MB  (%d total allocs)",
+			c.name,
+			float64(after.HeapAlloc-before.HeapAlloc)/(1024*1024),
+			after.Mallocs-before.Mallocs)
+	}
+}
+
+// --- export-download reader copy ---
+
+func benchDownloadReader(b *testing.B, size int, useStringCopy bool) {
+	raw := bytes.Repeat([]byte("x"), size)
+	sink := make([]byte, 32*1024)
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		var r io.Reader
+		if useStringCopy {
+			r = strings.NewReader(string(raw)) // current code: extra full-size copy
+		} else {
+			r = bytes.NewReader(raw) // fix: no copy
+		}
+		for {
+			if _, err := r.Read(sink); err != nil {
+				break
+			}
+		}
+	}
+}
+
+// --- fan-out cell-budget cap (fix for the unbounded matrix blow-up) ---
+
+func TestStampMatrixBudgetCap(t *testing.T) {
+	// 199992 cells (7692×26) sits just under the 200000 cap → allowed.
+	if err := checkStampMatrixBudget("range", "A1:Z7692", 7692, 26); err != nil {
+		t.Fatalf("199992 cells should pass, got: %v", err)
+	}
+	// Exactly at the cap → allowed.
+	if err := checkStampMatrixBudget("range", "A1:A200000", 200000, 1); err != nil {
+		t.Fatalf("200000 cells (== cap) should pass, got: %v", err)
+	}
+	// Just over the cap → rejected.
+	if err := checkStampMatrixBudget("range", "A1:A200001", 200001, 1); err == nil {
+		t.Fatal("200001 cells should be rejected")
+	}
+	// The pathological case from the review (2.6M cells) → rejected.
+	if err := checkStampMatrixBudget("ranges", "Sheet1!A1:Z100000", 100000, 26); err == nil {
+		t.Fatal("2.6M-cell fan-out should be rejected")
+	}
+}
+
+// --- sibling cap gaps: +table-put/+workbook-create payload, batch aggregate,
+//     batch-update operation count (follow-up to the single fan-out cap) ---
+
+// TestTablePutCellBudgetCap covers the --sheets/--values materialization cap:
+// buildSheetMatrix builds the whole matrix in memory, so the total cell count is
+// bounded before that allocation, summed across all sheets.
+func TestTablePutCellBudgetCap(t *testing.T) {
+	// 1000×1000 = 1,000,000 == cap → allowed.
+	atCap := &tablePayload{Sheets: []tableSheetSpec{{
+		Columns: make([]tableColumnSpec, 1000),
+		Rows:    make([][]interface{}, 1000),
+	}}}
+	if err := atCap.checkCellBudget(); err != nil {
+		t.Fatalf("1,000,000 cells (== cap) should pass, got: %v", err)
+	}
+	// 1000×1001 = 1,001,000 > cap → rejected.
+	over := &tablePayload{Sheets: []tableSheetSpec{{
+		Columns: make([]tableColumnSpec, 1000),
+		Rows:    make([][]interface{}, 1001),
+	}}}
+	if err := over.checkCellBudget(); err == nil {
+		t.Fatal("1,001,000 cells should be rejected")
+	}
+	// Budget is summed across sheets, not per-sheet: 600k + 600k = 1.2M > cap.
+	twoSheets := &tablePayload{Sheets: []tableSheetSpec{
+		{Columns: make([]tableColumnSpec, 1000), Rows: make([][]interface{}, 600)},
+		{Columns: make([]tableColumnSpec, 1000), Rows: make([][]interface{}, 600)},
+	}}
+	if err := twoSheets.checkCellBudget(); err == nil {
+		t.Fatal("1.2M cells across two sheets should be rejected")
+	}
+}
+
+// TestBatchStampAggregateCap covers the batch fan-out aggregate budget — the
+// per-range cap can't stop many ranges from summing past the matrix ceiling.
+func TestBatchStampAggregateCap(t *testing.T) {
+	if err := checkBatchStampBudget(maxStampMatrixCells); err != nil {
+		t.Fatalf("aggregate == cap should pass, got: %v", err)
+	}
+	if err := checkBatchStampBudget(maxStampMatrixCells + 1); err == nil {
+		t.Fatal("aggregate over cap should be rejected")
+	}
+}
+
+// TestBatchFanoutRangeCountCap drives a fan-out shortcut with > maxBatchRanges
+// ranges and expects the shared validateDropdownRanges cap to reject it.
+func TestBatchFanoutRangeCountCap(t *testing.T) {
+	ranges := make([]string, maxBatchRanges+1)
+	for i := range ranges {
+		ranges[i] = "sheet1!A1"
+	}
+	rangesJSON, _ := json.Marshal(ranges)
+	_, _, err := runShortcutCapturingErr(t, CellsBatchSetStyle, []string{
+		"--url", testURL,
+		"--ranges", string(rangesJSON),
+		"--font-weight", "bold",
+		"--dry-run",
+	})
+	requireValidation(t, err, "at most")
+}
+
+// TestBatchOperationsCountCap covers the +batch-update sub-operation count cap.
+func TestBatchOperationsCountCap(t *testing.T) {
+	ops := make([]interface{}, maxBatchOperations+1)
+	for i := range ops {
+		ops[i] = map[string]interface{}{"shortcut": "+cells-set", "input": map[string]interface{}{}}
+	}
+	_, err := translateBatchOperations(ops, testURL)
+	if err == nil || !strings.Contains(err.Error(), "at most") {
+		t.Fatalf("expected operations count cap error, got: %v", err)
+	}
+}
+
+// BenchmarkStampBudget_RejectsOversized is the "after" side of the fix: the same
+// A1:Z100000 input that BenchmarkFillCellsMatrix_2600K shows costing ~917MB /
+// 5.3M allocs is now rejected up front, allocating only the error string.
+func BenchmarkStampBudget_RejectsOversized(b *testing.B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		if err := checkStampMatrixBudget("range", "A1:Z100000", 100000, 26); err == nil {
+			b.Fatal("expected rejection")
+		}
+	}
+}
+
+func BenchmarkDownloadReader_StringCopy_1MB(b *testing.B)  { benchDownloadReader(b, 1<<20, true) }
+func BenchmarkDownloadReader_BytesNoCopy_1MB(b *testing.B) { benchDownloadReader(b, 1<<20, false) }
+func BenchmarkDownloadReader_StringCopy_16MB(b *testing.B) { benchDownloadReader(b, 16<<20, true) }
+func BenchmarkDownloadReader_BytesNoCopy_16MB(b *testing.B) {
+	benchDownloadReader(b, 16<<20, false)
+}

shortcuts/sheets/shortcuts.go

@@ -70,6 +70,7 @@ func shortcutList() []common.Shortcut {
 	return []common.Shortcut{
 		// lark_sheet_workbook
 		WorkbookInfo,
+		RevisionGet,
 		SheetCreate,
 		SheetDelete,
 		SheetRename,
@@ -95,6 +96,9 @@ func shortcutList() []common.Shortcut {
 		DimUngroup,
 		DimMove,
 
+		// lark_sheet_changeset
+		ChangesetGet,
+
 		// lark_sheet_read_data
 		CellsGet,
 		CsvGet,
@@ -105,6 +109,9 @@ func shortcutList() []common.Shortcut {
 		CellsSearch,
 		CellsReplace,
 
+		// lark_sheet_formula_verify
+		FormulaVerify,
+
 		// lark_sheet_write_cells
 		CellsSet,
 		CellsSetStyle,
@@ -148,5 +155,11 @@ func shortcutList() []common.Shortcut {
 		CellsBatchClear,
 		DropdownUpdate,
 		DropdownDelete,
+
+		// lark_sheet_history
+		HistoryList,
+		HistoryRevert,
+		HistoryRevertStatus,
+		Undo,
 	}
 }

skill-template/domains/drive.md

@@ -6,7 +6,6 @@
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
-- 批量执行 `drive +import` 且目标是同一个位置（同一 `--folder-token`、默认根目录，或同一 `--target-token`）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
 - 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 
@@ -195,7 +194,6 @@ lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "
 | `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
 | `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable） |
-| `232140101` / `232140100` / `233523001`（常见于 `drive +import` 的 `job_error_msg`） | 同一位置下存在并发导入 / 创建操作 | 批量导入到同一文件夹、根目录或同一 `--target-token` 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突 |
 
 ### 授权当前应用访问文档
 

skills/lark-calendar/SKILL.md

@@ -45,15 +45,13 @@ lark-cli calendar +agenda --as user
 | 场景 | 前置要求 |
 |------|----------|
 | 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
-| 编辑已有日程 | 先定位目标日程 `event_id` |
-| 编辑/删除重复性日程 | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，按操作范围（仅此次/全部/此次及后续）执行 |
+| 编辑已有日程 | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
 | 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
 | 调用任何 Shortcut | 先读其对应 reference 文档 |
 
 ## 核心概念
 
-- **日程实例（Instance）**：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 `event_id`；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 `event_id`），并按需处理例外。
-- **重复性日程例外（Exception）**：对重复性日程某次实例做过「仅此次」编辑后产生的独立日程（拥有独立 `event_id`）。删除/更新「全部」时必须同时处理例外，否则例外会残留。
+- **日程实例（Instance）**：重复性日程展开后的具体时间实例。操作重复日程的某次实例时，必须先定位该实例的 `event_id`，禁止使用原重复日程的 `event_id`。
 - **全天日程（All-day Event）**：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
 - **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
 - **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
@@ -73,7 +71,6 @@ lark-cli calendar +agenda --as user
 | 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
 | 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再 [`vc +detail`](../lark-vc/references/lark-vc-detail.md) → [`note +detail`](../lark-note/references/lark-note-detail.md) / [`minutes +detail`](../lark-minutes/references/lark-minutes-detail.md) |
 | 预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
-| 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |
 
 ## 任务类型分流
 

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

@@ -47,7 +47,6 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 > 自动设置 `reminders: [{"minutes": 5}]`，默认日程开始前 5 分钟提醒。
 > 自动设置 `vchat: {"vc_type": "vc"}`，默认日程包含飞书视频会议。如需其他视频会议类型或不含视频会议，请使用完整 API 命令。
 > 失败保护：若添加参会人失败（如 open_id 错误），CLI 会自动删除刚创建的空日程（回滚，不通知参会人）。
-> 审批会议室：`+create` 不暴露低频字段 `attendees[].approval_reason`。如果会议室要求审批，请使用用户身份先创建日程，再用完整 API `calendar event.attendees create --as user` 添加会议室并传 `approval_reason`。
 
 ## 高级用法（完整 API 命令）
 
@@ -73,16 +72,9 @@ lark-cli calendar events create \
 lark-cli schema calendar.event.attendees.create
 ## 添加参会人
 lark-cli calendar event.attendees create \
-  --as user \
   --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
   --data '{"attendees": [{"type": "user", "user_id": "ou_xxx"}]}'
 
-## 添加需要审批的会议室（approval_reason 最大 200 字符）
-lark-cli calendar event.attendees create \
-  --as user \
-  --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
-  --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
-
 # 可选第三步（推荐）：若第二步失败，回滚删除空日程
 ## 查看完整参数定义
 lark-cli schema calendar.events.delete

skills/lark-calendar/references/lark-calendar-recurring.md

@@ -1,90 +0,0 @@
-# 重复性日程操作规范
-
-重复性日程的编辑/删除分为三种范围：「仅此次」「全部」「此次及后续」。用户未明确范围时，**必须询问确认**。
-
-## 关键概念
-
-- **event_id 结构**：`event_id` 的格式为 `{event_uid}_{originalTime}`。普通日程或重复性日程本体的 `originalTime` 为 `0`；例外的 `originalTime > 0`，代表该例外在原重复性序列中本来的时间位置。因此 `{event_uid}_0` 即为原重复性日程的 `event_id`。
-- **原重复性日程**：携带 `rrule` 的日程本体，`event_id` 形如 `{event_uid}_0`。系列的所有属性（标题、时间、rrule、描述等）都挂在本体上。
-- **例外（Exception）**：对某次实例做过「仅此次」编辑后产生的独立日程，`event_id` 形如 `{event_uid}_{originalTime}`（`originalTime > 0`）。通过 `event_uid` 部分即可关联回原重复性日程。
-- 删除/更新原重复性日程 **不会** 级联处理例外——必须手动逐个处理。
-
-## 前置步骤（所有范围通用）
-
-1. 通过 `+agenda` 或 `+search-event` 定位重复性日程，获取原重复性日程的 `event_id`。
-2. 通过 `events instance_view` 或 `+agenda` 列出实例，识别哪些是例外（`event_id` 中 `originalTime > 0` 的即为例外）。
-3. 确认用户的操作范围。
-
-## 编辑全部（更新时间）
-
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --start ... --end ...` | 更新原重复性日程的时间 |
-| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 时间变更后例外已无意义，必须删除 |
-
-> 理由：更新时间会改变重复起止点，例外日程的原始占位已变，若保留会导致时间冲突或残留。
-
-## 编辑全部（更新非时间字段）
-
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --summary ... --description ...` | 更新原重复性日程的标题/描述等 |
-| 2 | `lark-cli calendar +update --event-id <例外ID> --summary ... --description ...` （逐个） | 同步更新例外日程的对应字段 |
-
-> 理由：例外已脱离原重复性日程独立存在，不会自动继承原日程的更新。
-
-## 删除全部
-
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<原重复日程ID>","need_notification":true}'` | 删除重复性日程本体 |
-| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 删除所有例外日程 |
-
-> 理由：例外是独立实体，删除原重复性日程不会级联删除例外。
-
-## 编辑此次及后续
-
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
-| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
-| 3 | `lark-cli calendar +create --summary ... --start <指定时间> --end ... --rrule "FREQ=..." --attendee-ids ...` | 从指定时间开始创建新的重复性日程（即「后续」部分，携带编辑后的内容） |
-
-> UNTIL 计算规则：若用户选择「从第 N 次开始编辑」，UNTIL 应设置为第 N-1 次实例的日期（即保留到指定时间之前的最后一次）。
-> 新日程应继承原日程的参会人、会议室等配置（除非用户明确要修改）。
-
-## 删除此次及后续
-
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
-| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
-
-> 与「编辑此次及后续」的区别：不需要步骤 3（创建新的重复性日程），因为目标是删除后续而非替换。
-
-## 仅此次
-
-- **编辑仅此次**：通过 `+agenda` / `+search-event` 定位到具体实例的 `event_id`，然后正常调用 `+update`。
-- **删除仅此次**：定位到具体实例的 `event_id`，调用 `events delete`。
-
-## 用户意图映射
-
-| 用户表达 | 操作范围 |
-|----------|----------|
-| 「改这个重复日程的标题」「全部改」「每次都改」 | 编辑全部 |
-| 「删掉这个重复日程」「取消所有」 | 删除全部 |
-| 「从下周开始改时间」「后面的都改」 | 编辑此次及后续 |
-| 「从下周开始不要了」「后面的都删」 | 删除此次及后续 |
-| 「就改这一次」「只删这一次」 | 仅此次 |
-| 未明确范围 | **必须询问用户** |
-
-## 注意事项
-
-- 涉及时间戳计算（如推算 UNTIL 日期）时，必须调用系统命令或脚本，禁止心算。
-
-## 参考
-
-- [lark-calendar](../SKILL.md) — 日历全部命令
-- [lark-calendar-update](lark-calendar-update.md) — 更新日程 Shortcut
-- [lark-calendar-create](lark-calendar-create.md) — 创建日程 Shortcut
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -43,7 +43,7 @@ lark-cli calendar +update \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程请根据操作范围选择 ID，详见 [重复性日程操作规范](lark-calendar-recurring.md) |
+| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程要先定位到目标实例的 `event_id`，不要直接使用原重复日程 ID |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用 `primary`） |
 | `--summary <text>` | 否 | 新日程标题。仅在显式传入 `--summary` 时更新；若传空字符串，会把标题清空 |
 | `--description <text>` | 否 | 新日程描述。目前 API 方式不支持编辑富文本描述；如果日程描述通过客户端编辑为富文本内容，则使用 API 更新描述会导致富文本格式丢失。仅在显式传入 `--description` 时更新；若传空字符串，会把描述清空 |
@@ -65,7 +65,7 @@ lark-cli calendar +update \
 - 只想修改标题、描述、时间或重复规则时，不需要同时传 `--add-attendee-ids` 或 `--remove-attendee-ids`。
 - 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。
 - 会议室是 resource attendee，必须使用 `omm_` ID 添加到参会人列表，不能脱离日程单独预定。
-- 更新重复性日程时，必须先确定操作范围（仅此次/全部/此次及后续），然后按 [重复性日程操作规范](lark-calendar-recurring.md) 执行。
+- 更新重复性日程的某一次实例时，必须先通过 `+agenda`、`+search-event` 或实例视图定位该实例的 `event_id`。
 - 如果需要验证更新结果，等待至少 2 秒后再查询，避免同步延迟导致读到旧数据。
 - 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。
 

skills/lark-doc/SKILL.md

@@ -5,7 +5,7 @@ description: "飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文
 metadata:
   requires:
     bins: ["lark-cli"]
-  cliHelp: "lark-cli docs --help;lark-cli mindnotes --help"
+  cliHelp: "lark-cli docs --help; lark-cli docs +create --help; lark-cli docs +fetch --help; lark-cli docs +update --help; lark-cli docs +resource-download --help; lark-cli docs +resource-update --help; lark-cli docs +resource-delete --help; lark-cli mindnotes nodes list --help; lark-cli mindnotes nodes create --help"
 ---
 
 # docs
@@ -24,12 +24,12 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>
 **CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
 1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
 2. **读取文档（`docs +fetch`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
-3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）和必读 [`lark-doc-style.md`](references/style/lark-doc-style.md)（写作原则：默认段落、按体裁、组件克制）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update.md`](references/lark-doc-update.md) 和 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
+3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）和 [`lark-doc-style.md`](references/style/lark-doc-style.md)（元素选择、丰富度规则、颜色语义）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update.md`](references/lark-doc-update.md) 和 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
 
 **未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**
 
 > **格式选择规则（全局）：**
-> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML。
+> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。
 > - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
 
 ## 快速决策
@@ -39,10 +39,9 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>
 - 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID
 - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
 - 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
-- 新增或更新画板时，按 [`lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 选型；Mermaid 可由主 Agent 直接插入，SVG / 复杂图 / 已有画板更新按其中流程隔离到 SubAgent
+- 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入
 - 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview`
 - 用户明确说"下载素材" → 用 `lark-cli docs +media-download`
-- 用户想把文档回滚到某个 `revision_id` 或某一时刻 → 先读 [`lark-doc-history.md`](references/lark-doc-history.md)，按其中流程操作
 - 用户明确说"下载/更新/删除文档封面图" → 用 `lark-cli docs +resource-download/+resource-update/+resource-delete --type cover`
 - `resource-*` 目前仅支持 Docx 封面资源；其他图片、附件或素材请走 `+media-*`
 - 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）
@@ -70,7 +69,6 @@ Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）
 | [`+create`](references/lark-doc-create.md) | Create a Lark document (XML / Markdown) |
 | [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown / im-markdown; `im-markdown` only after fetch for `lark-im`) |
 | [`+update`](references/lark-doc-update.md) | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
-| [`+history-list` / `+history-revert` / `+history-revert-status`](references/lark-doc-history.md) | List document history, revert to a `history_version_id`, and query revert task status |
 | [`+media-insert`](references/lark-doc-media-insert.md) | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback). Prefer `--from-clipboard` when the image is already on the system clipboard (screenshots, copy from Feishu/browser); use `--file` only for on-disk sources. |
 | [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) |
 | [`+media-preview`](references/lark-doc-media-preview.md) | Preview document media file (auto-detects extension) |

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

@@ -2,14 +2,14 @@
 
 > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
 > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
-> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
+> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
+> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
 >
 > **未读完以上文件就生成内容会导致格式错误。**
 
 从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。
 
-> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，可承载更丰富的结构化内容）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
+> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，支持 callout、grid、checkbox 等富 block 类型）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
 
 ## 命令
 
@@ -72,8 +72,8 @@ lark-cli docs +create --doc-format markdown --title "项目计划" --content $'#
 
 ## 参考
 
-- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
-- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
+- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
+- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）
 - [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
 - [`lark-doc-update.md`](lark-doc-update.md) — 更新文档

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

@@ -1,107 +0,0 @@
-# docs history（历史版本与回滚）
-
-用于查看 Docx 历史版本、按 `history_version_id` 回滚，以及查询回滚任务状态。
-
-## 安全流程
-
-1. 先用分页接口 `+history-list` 找到目标版本的 `history_version_id`。
-2. 如果用户指定的是 `revision_id`，不要假设它唯一，也不要把 `revision_id` 直接传给 `+history-revert`。先拉一页并在 `entries[]` 中筛选 `revision_id` 相同的候选；如果未匹配到且 `has_more=true`，继续用 `page_token` 翻页；如果已匹配到候选，最多额外再拉一页补齐可能跨页的相邻候选。最终优先根据用户目标时间与 `edit_time` 的接近程度选择最合适的一条，取同一条的 `history_version_id`；如果没有目标时间，或多个候选无法可靠区分，再向用户展示候选版本（`history_version_id`、`revision_id`、`edit_time`、`name/description`）并确认后回滚。
-3. 如果用户指定的是某一时刻但没有指定 `revision_id`，按 `entries[].edit_time` 匹配；优先选择不晚于目标时刻的最近一条历史记录，无法明确匹配时先向用户确认候选版本。
-4. 再用 `+history-revert --history-version-id <history_version_id>` 发起回滚。默认最多等待 30 秒；如果返回 `status: running`，记录 `task_id`。
-5. 用 `+history-revert-status` 轮询 `task_id`，直到状态不再是 `running`。
-6. 回滚完成后，用 `docs +fetch` 读取文档确认内容。
-
-## 按 revision_id 或时间点回滚
-
-当用户说“回滚到 revision_id=42”“恢复到昨天下午 3 点的版本”这类需求时，流程是：
-
-1. 执行 `docs +history-list --doc <doc>` 获取第一页历史记录；`+history-list` 是分页接口，只有 `has_more=true` 且还需要更多候选时才继续传 `--page-token` 翻页。
-2. 如果用户给出 `revision_id`：先筛选当前页中 `entries[].revision_id == 用户给出的 revision_id`。如果未命中且 `has_more=true`，继续拉下一页；如果已经命中候选，最多额外再拉一页，补齐同一个 `revision_id` 可能跨页出现的相邻 `history_version_id`。若用户同时给出目标时间，在候选里选择 `edit_time` 与目标时间最接近的一条；若未给目标时间但候选只有一条，可直接使用；若多个候选无法可靠区分，不要自行取第一条，向用户展示候选并确认。
-3. 如果用户只给出时间：用 `entries[].edit_time` 匹配，选择目标时刻之前最近的一条；如果用户表达的是“最接近某时刻”，则选择绝对时间差最小的一条。
-4. 从最终匹配条目读取 `history_version_id`。`history_version_id` 对应服务端 `minor_history.version`，这是回滚接口需要的 ID。
-5. 执行 `docs +history-revert --doc <doc> --history-version-id <history_version_id>`。
-
-候选确认时使用类似格式：
-
-```text
-同一个 revision_id 命中多个历史版本，请确认要回滚哪一条：
-- history_version_id=11 revision_id=42 edit_time=2026-06-22T12:24:45Z name=...
-- history_version_id=12 revision_id=42 edit_time=2026-06-22T12:25:14Z name=...
-```
-
-## 命令
-
-```bash
-# 列出历史版本
-lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20
-
-# 翻页
-lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20 --page-token "<page_token>"
-
-# 回滚到指定 history_version_id（默认等待 30000ms）
-lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42
-
-# 只发起任务，不等待
-lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42 --wait-timeout-ms 0
-
-# 查询回滚任务状态
-lark-cli docs +history-revert-status --doc "<docx_url_or_token>" --task-id "<task_id>"
-```
-
-## 参数
-
-| 命令 | 参数 | 必填 | 说明 |
-|-|-|-|-|
-| `+history-list` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
-| `+history-list` | `--page-size` | 否 | 返回条数，范围 `1-20`，默认 `20` |
-| `+history-list` | `--page-token` | 否 | 上一页返回的 `page_token` |
-| `+history-revert` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
-| `+history-revert` | `--history-version-id` | 是 | `+history-list` 返回的 `history_version_id`，必须大于 0 |
-| `+history-revert` | `--wait-timeout-ms` | 否 | 等待回滚完成的毫秒数，范围 `0-30000`，默认 `30000` |
-| `+history-revert-status` | `--doc` | 是 | 同一个文档 |
-| `+history-revert-status` | `--task-id` | 是 | `+history-revert` 返回的 `task_id` |
-
-## 返回值要点
-
-`+history-list` 返回：
-
-```json
-{
-  "entries": [
-    {
-      "revision_id": 42,
-      "history_version_id": "11",
-      "edit_time": "1780000000",
-      "type": 1,
-      "name": "版本名",
-      "description": "版本说明",
-      "editor_ids": ["ou_xxx"]
-    }
-  ],
-  "has_more": true,
-  "page_token": "page_token"
-}
-```
-
-`+history-revert` 返回：
-
-```json
-{
-  "task_id": "task_xxx",
-  "status": "running",
-  "history_version_id": "11",
-  "poll_after_ms": 10000
-}
-```
-
-`+history-revert-status` 返回：
-
-```json
-{
-  "status": "partial_failed",
-  "history_version_id": "11",
-  "failed_block_tokens": ["blk_xxx"]
-}
-```
-
-`status` 可能是 `running`、`done`、`partial_failed`、`failed`。当状态是 `partial_failed` 或 `failed` 时，优先检查 `failed_block_tokens`。

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

@@ -3,8 +3,8 @@
 
 > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
 > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
-> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
+> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
+> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
 >
 > **未读完以上文件就生成内容会导致格式错误。**
 
@@ -232,7 +232,7 @@ lark-cli docs +update --doc "<doc_id>" --command str_replace \
 
 > **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch` 取到 `<whiteboard token="...">`，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。
 
-画板的语法选型与插入示例见 [`lark-doc-xml.md`](lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md)。
+画板的语法选型与插入示例见 [`lark-doc-style.md`](style/lark-doc-style.md) 的「画板语法与插入」章节。
 
 ## 最佳实践
 
@@ -252,8 +252,8 @@ lark-cli docs +update --doc "<doc_id>" --command str_replace \
 
 ## 参考
 
-- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
-- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
+- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
+- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）
 - [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
 - [`lark-doc-create.md`](lark-doc-create.md) — 创建文档

skills/lark-doc/references/lark-doc-word-stat.md

@@ -13,13 +13,6 @@ lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \
 
 `$URL` 可以是用户给出的 docx/wiki URL，也可以是可被 `docs +fetch` 解析的 token。
 
-## 统计范围
-
-先判断用户要求的是**整篇文档**还是**局部内容**：
-
-- 整篇文档的总字数 / 总字符数：按上方「调用方式」抓取 `full` 内容后统计。
-- 本次新增 / 替换 / 改写片段的字数：优先统计拟写内容本身；内容已写入文档时，只 fetch 对应 block / range 后统计。不得用整篇文档字数对比局部目标。
-
 如需在自动化或回归验证中发现未覆盖块类型，追加严格参数：
 
 ```bash
@@ -43,15 +36,6 @@ lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \
 
 如果 `unknown_blocks` 或 `unsupported_blocks` 非空，回复用户时要说明“已统计可提取文本，但存在未覆盖块，结果可能偏低”，并列出对应块类型。为空时可直接给出结果。
 
-## 字数遵循校验
-
-当用户给了明确字数要求（写 N 字 / x-y 字 / x 字左右 / 上下浮动）时执行；没有明确字数要求则跳过。字数必须按本文流程用脚本统计，不要自己估。
-
-1. 先按「统计范围」确认统计对象，再把要求归一成目标区间：`>x`→`[x+1, +∞)`；`<y`→`(-∞, y-1]`；`x-y`→`[x, y]`；`x 字左右`→`[round(0.9x), round(1.1x)]`
-2. 按统计对象选择对应输入并调用脚本统计实际字数，读取输出里的 `word_count`
-3. 对比 `word_count` 与目标区间：区间内即通过；低于下限 → 补充**实质内容**（非注水）；高于上限 → 删减冗余内容。改完重新统计
-4. **最多 2 轮**。2 轮后仍不达标：停止，不得为达标而注水或删关键内容；如实汇报【目标区间 / 当前字数 / 差值与方向 / 已试 2 轮 / 未达原因】，**禁止谎称达标**
-
 ## 输出示例
 
 输入正文等价于：`标题` + `一个苹果是 an apple。` 时，输出形态如下：

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

@@ -7,7 +7,7 @@
 通过自适应的 **Code-Act Loop** 驱动文档创作，而非固定模板式的工作流。每次任务都循环执行：
 
 1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
-2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进正文；仅画板渲染按需隔离到 SubAgent（见步骤三）
+2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进
 3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
 4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
 
@@ -16,31 +16,44 @@
 
 ## 典型 Code-Act Loop 流程
 
-### 步骤一：规划与撰写（单 Agent 串行）
-
-正文由主 Agent 串行维护，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效。
+### 步骤一：规划与初始创建（串行）
 
 1. 分析用户需求：受众、目的、范围
 2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
-3. `docs +create` 创建并撰写：
-   - **短文档**：一次写入完整内容
-   - **长文档**：先建骨架（标题 + 各级标题），再由主 Agent **顺序逐节**用 `block_insert_after --block-id <章节标题 block_id>` 补全正文；写完一节再写下一节，始终带着已写内容的上下文，保证衔接、不重复
-   - ⚠️ 不要一次性把超长完整内容塞进 `--content`，容易触发字符/参数限制；长文按节分次写入
-   - ⚠️ 同一节内多次插入时，要锚到**上一个新插入的 block**（按 [`lark-doc-update.md`](../lark-doc-update.md) 的「Block ID 生命周期」），否则反复锚同一个标题会让段落顺序颠倒
-   - ⚠️ 若先建骨架写了占位摘要，补正文时**删除占位摘要**，不要留残渣
-   - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理
+3. `docs +create` 创建文档。长文档可**只建骨架**：标题 + 各级标题 + 每节一句占位摘要；短文档可以一次写入完整内容
+   - ⚠️ 创建较长文档时，**不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
+   - 完整内容留到步骤二，由各 Agent 用 `block_insert_after --block-id <章节标题 block_id>` 分段写入。
+   - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理。
 
-### 步骤二：整合审查与画板识别（串行）
+### 步骤二：分段撰写（并行 Agent）
 
-4. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
-5. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材；检查跨节有无重复、矛盾或断流。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题就地定向修正
-6. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
+4. Spawn Agent 并行撰写各章节。每个 Agent 需收到：
+   - 文档 token、负责的章节范围、用户目标、目标读者和已有风格线索
+   - `lark-doc-xml.md` 和 `lark-doc-style.md` 的完整路径（Agent 须先读取）
+   - 使用 `block_insert_after --block-id <章节标题 block_id>` 写入对应章节内容
 
-### 步骤三：画板处理与润色
+### 步骤三：整合审查与画板识别（串行）
 
-7. **优先处理步骤二识别出的画板需求**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
-8. 由**主 Agent 自行润色**（不另起内容子 Agent，正文始终一人维护）：文字密集且不易读时，优先拆段、加小标题或调整顺序——叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）；只有确实存在行列数据时才用 `<table>`。其余富 block 的取舍一律遵循 `lark-doc-style.md` 的写作原则，不主动堆叠。需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用。本地图片使用 `docs +media-insert` 插入
+5. `docs +fetch --detail with-ids` 获取文档，审查整体效果
+6. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材
+7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
 
-### 步骤四：专项校验（按需执行）
+### 步骤四：画板处理与润色（并行 Agent）
 
-9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果
+8. **优先处理步骤三识别出的画板需求**：
+   参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
+9. Spawn 内容改写 Agent 定向润色：
+   - 文字密集且不易读时，优先拆段、改列表、增加小标题或调整顺序；只有确实存在行列数据、并列对比或强提醒信息时，才考虑 `<table>` / `<grid>` / `<callout>`
+   - 需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用
+   - 本地图片使用 `docs +media-insert` 插入
+
+
+## Agent 子任务要求
+
+内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、用户目标/风格要求、具体的 `docs +update` command 和 `--block-id`。
+
+Mermaid 图由主 Agent 直接插入 `<whiteboard type="mermaid">...</whiteboard>`，无需 SubAgent。
+
+SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
+
+已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。

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

@@ -1,68 +1,86 @@
-# 飞书文档写作原则
+# 文档表达组件参考
 
-写飞书文档，像一个该领域资深的人类作者那样写，而不是把内容"装配"成组件。
-本文只讲"何时用、什么风格"；具体标签 / 命令语法见 [`lark-doc-xml.md`](../lark-doc-xml.md)。
+本文件说明飞书文档可用的结构化表达方式，供模型在需要时选择。它不是固定模板，也不是强制排版规范。
 
-## 一、用户明确要求优先
+默认原则：优先理解用户目标、受众、素材形态和已有文档风格，由模型自主决定结构、语气和视觉呈现。只有当用户明确要求“美化、重排版、做成报告/方案/看起来更专业”等，或内容本身明显需要结构化承载时，才主动使用下列组件。
 
-用户点名要某种格式——高亮块、分栏、列表、某编号体例、表格、画板、某模板、某已有文档的风格——**一律照用户的来，下面的"默认克制"全部让位**。用户给了样例或已有文档，就沿用它的结构与语气。
+## 一、核心原则
 
-## 二、默认写连贯段落
+1. **服务内容，而非套模板**：先判断信息最自然的表达方式，再选择段落、列表、表格、分栏、画板等元素
+2. **尊重用户风格**：用户给出样例、语气、结构或已有文档时，优先沿用；没有要求时不强行使用固定开头、固定章节或固定视觉组件
+3. **适度结构化**：结构化 block 用于降低理解成本，不为了“丰富”而堆叠
+4. **保持一致但不过度统一**：同类信息可使用相近表达，但允许因内容差异采用不同形式
+5. **图示服务理解**：流程、架构、对比、风险、路线图、指标趋势等内容在图示明显降低理解成本时，可使用画板表达
 
-用户没指定时，**默认是连贯段落**；其余按内容类型分流，别一律"少用结构"，也别什么都升标题：
+## 二、元素选择指南
 
-| 内容 | 用什么 | ❌ 别 |
-|---|---|---|
-| 叙述、论证、分析、说明 | **连贯段落** | 拆成列举 |
-| 真·行列数据（预算、指标、对比、排期、字段说明） | **表格** | 写成段落或把字段堆成一行 |
-| 字段:值（主题、时长、负责人等，少量） | **加粗标签行**或一句话 | 每字段一个标题 |
-| 方法 / 措施 + 每项一段描述 | **加粗引导句段落**（「**全程督导。**…」） | 每项升标题 |
-| 任务清单 / 检查项 / 待办事项 | **`<checkbox>`** | 用普通列表替代可交互待办 |
-| 纯短并列项（无描述，如材料清单） | 列表 | — |
-| 章节（内容成块、需在目录导航） | 标题层级 | — |
+需要图表时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图可用 `<whiteboard type="mermaid">` 直接内嵌；其他新图表可启动 SubAgent 插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。
 
-- 判断标准：**去掉结构后能顺成段落，就用段落；成行成列的数据，就用表格。**
-- **红线一：标题层级只给"章节"。** "小标题 + 一两句话"的小项（字段、方法、要点）不该占标题层级——按上表降成标签行 / 加粗引导句段落（否则目录里全是没信息量的条目）。
-- **红线二：列举（「一是 / 二是」「第一 / 第二」「(1)(2)(3)」）只给真正并列的具体项，且别每节都用。**
-  - 「一是 / 二是」是党务列举的措辞——只用在列具体的**问题 / 措施**那一处；背景、现状、认识、分析、过渡、总结**一律成段**。
-  - **整篇每段 / 每节都"一是 / 二是"，和"每段一个 bullet"是同一个骨架化的错——不因为是党务就变对**（纯清单 / 台账类除外）。
+| 场景                                         | 可选表达方式                                |
+|--------------------------------------------|---------------------------------------|
+| 少数需要视觉提醒的短句，如风险、限制、待确认事项或关键提醒          | 需要视觉提醒时可用 `<callout>`；普通结论、摘要或章节导语优先使用段落、列表、小标题或加粗 |
+| 方案对比 / 优劣势 / Before vs After                | 简短对比可用段落、列表或 `<grid>`；维度较多且需要逐项比较时再考虑 `<table>` 或画板 |
+| 简短低风险对比                                    | `<grid>` 2 列分栏                        |
+| 需要按行列精确比较或查阅的数据，如指标、清单、字段说明、排期           | 可用 `<table>`；短要点、步骤、摘要或普通说明优先使用段落、列表或小标题 |
+| 任务清单 / 检查项                                 | `<checkbox>`                          |
+| 代码片段                                       | `<pre lang="x" caption="说明">`         |
+| 引用 / 公式                                    | `<blockquote>` / `<latex>`            |
+| 操作入口 / 跳转链接                                | `<button>` / `<a type="url-preview">` |
+| 流程图 / 时间线 / 示意图 / 自定义图形 / 架构图 / 数据图 / 思维导图等 | 画板图表                                  |
 
-## 三、按体裁写
 
-- **公文 / 法律 / 学术 / 申报 / 项目方案等严肃正式提交物**：靠规范的标题层级、段落与编号体系表达；**默认不用高亮块、分栏**，要强调用加粗或规范小标题。
-- **面向公众号、微信等外部平台粘贴 / 发布的内容**：不用飞书特有富 block（高亮块、分栏等），粘出去会丢样式 / 错乱；改用标准标题、段落、列表、引用。
-- **一般文档**：以可读为先，不堆砌结构。
+### 画板意图识别
 
-## 四、编号与层级
+撰写或审查每个段落/章节时，**必须判断该内容是否适合用图表达**。满足以下任一特征时，应使用画板而非纯文本；如果该内容承载章节核心结论、关键决策或主要论据，即使结构较简单也优先画板化：
 
-- **一套编号体例、全篇一致；最忌中文大层级与阿拉伯小数编号混用。**
-  - 公文 / 正式材料常用：「一、→（一）→ 1.→（1）」（中文大层级 + 阿拉伯细分层级）。
-  - 学术 / 技术 / 商业报告：「1 → 1.1 → 1.1.1」或「一、→（一）→ 1.」，**择一**。
-  - ⚠️ **「一、」只能配「（一）」；要用阿拉伯小数就从顶层全用「1 / 1.1」。绝不「一、」配「1.1 / 2.1」**——这是最常见的混用。
-  - **不混用**多套（别"第X部分"+"一、"+"1."混着来）；**同级不跳号**；**不跳级**。
-- **编号 / 标题层级只给"章节"**，不要为了凑齐体例把每个小项都编上「（一）」、升成标题（小项处理方式见上文「二、默认写连贯段落」）。
-- 简单的 1.2.3 并列项用原生 `<ol><li seq="auto">…</li></ol>` 让飞书自动编号、自动对齐；「一、(一)」原生产不出，才手打成文字——此时用标题级别表达层次，**不靠手动缩进**、各级顶格（全角括号「（）」叠手动缩进会视觉错位）。
-
-## 五、飞书特有组件，克制使用
-
-- **高亮块 `<callout>`**：很重的强提醒信号，**默认不用**；只给"不提醒就会出错 / 遗漏"的关键项，全文极少（0~1 个），不要每节导语 / 结论都做成高亮块。
-- **分栏 `<grid>`**：仅左右信息量相当、确需并排对照的短内容；否则用段落或表格。
-- **画板**：默认用文字，只在**图示明显比文字更易懂**（流程、架构、时间线、对比、占比等）或用户要求时才用。怎么插、用哪种类型见 [`lark-doc-xml.md`](../lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](../lark-doc-whiteboard.md)。
-- **颜色**：默认朴素、不上色；需要时保持语义一致，按下表选择对应颜色，不为装饰上色。可用色见 [`lark-doc-xml.md`](../lark-doc-xml.md) 的「美化系统」。
-
-| 语义 | 背景色 | 文字色 |
+| 内容特征 | 信号词 / 模式 | 推荐画板类型 |
 |-|-|-|
-| 信息、说明 | `light-blue` | `blue` |
-| 成功、推荐 | `light-green` | `green` |
-| 警告 / 错误 / 风险 | `light-red` | `red` |
-| 注意、待确认 | `light-yellow` | `yellow` |
-| 中性、辅助 | `light-gray` | — |
+| 多步骤的操作流程或决策路径 | "先…然后…最后"、"步骤 1/2/3"、"如果…则…否则" | 流程图 / 泳道图 |
+| 系统或模块间的依赖与交互 | "调用"、"依赖"、"上游/下游"、"请求→响应" | 架构图 |
+| 上下级或从属关系 | "汇报给"、"下属"、"隶属"、"团队结构" | 组织架构图 |
+| 时间线或阶段演进 | "Q1/Q2"、"里程碑"、"阶段一→阶段二"、日期序列 | 时间线 / 里程碑 |
+| 因果分析或问题归因 | "根因"、"原因"、"导致"、"影响因素" | 鱼骨图 |
+| 两个及以上方案/对象的多维度对比 | "vs"、"方案 A/B"、"优劣"、"对比" | 对比图 |
+| 层级递进或优先级排序 | "基础→进阶→高级"、"L1/L2/L3"、"核心→外围" | 金字塔图 |
+| 数值趋势或周期变化 | 带数字的时间序列、"增长/下降"、百分比变化 | 折线图 / 柱状图 |
+| 漏斗或转化率 | "转化率"、"漏斗"、"从…到…留存" | 漏斗图 |
+| 发散或归纳的思维结构 | "要点"、"维度"、"分支"、多层嵌套列表 | 思维导图 |
+| 循环或飞轮效应 | "正循环"、"飞轮"、"闭环"、"A 驱动 B 驱动 C" | 飞轮图 |
+| 占比分布 | "占比"、"份额"、"分布"、百分比加总 ≈100% | 饼图 / 树状图 |
 
-## 六、写完自检
+**判断规则：**
+- 重要信息能图示就图示；不要为了省步骤把关键流程、架构、对比、风险链路写成纯文本
+- 低重要度、局部辅助信息才用 `<table>` / `<grid>` / `<callout>` 承载
+- 确定需要插入哪些图表后，参照 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的方式，插入图表画板。
 
-交付前快速回看：
-- **叙述是否被列举化**：背景 / 现状 / 认识 / 分析 / 成效 / 过渡 / 总结等应成段；列举只用于同层级、可并列处理的信息，如问题、措施、步骤、任务或材料清单。若正文反复使用连续编号、项目符号或固定并列句式，导致内容缺少叙述，应把背景 / 认识 / 分析 / 过渡改写成有承接关系的段落（纯清单 / 台账类除外）。
-- **数据是否正确呈现**：成行成列的数据应使用表格呈现，不要写成段落，也不要用分隔符把多个字段硬串在一起。
-- **标题是否滥用**："小标题 + 一句话"的小项不要升成标题；应改成标签行、加粗引导句段落或普通段落。
-- **编号是否统一**：全篇一套、不跳号、不跳级，尤其不要中文 + 阿拉伯混用（如「一、」配「1.1」）。
-- **组件是否克制且保真**：高亮块 / 分栏 / 画板 / 颜色应符合体裁和用户要求；引用 / 图片 / 资源块必须保留。
+## 三、颜色语义
+
+如果使用颜色，建议保持语义一致；不需要颜色时可以保持朴素文本风格：
+
+| 语义 | emoji 前缀 | callout 背景色 | 文字色 |
+|-|-|-|-|
+| 信息、说明 | ℹ️ "说明：" | `light-blue` | `blue` |
+| 成功、推荐 | ✅ "推荐：" | `light-green` | `green` |
+| 警告 / 错误 / 风险 | ⚠️❌ | `light-red` | `red` |
+| 注意、待确认 | ❗"注意：" | `light-yellow` | `yellow` |
+| 中性、辅助 | — | `light-gray` | — |
+
+- 表头可使用 `background-color="light-gray"`，也可以保持默认样式
+- 关键指标如使用 `<span text-color="green/red">` 突出，建议同时用 ↑↓ 或 +/- 标注方向（色觉无障碍）
+
+## 四、排版规范
+
+- 标题层级、段落长度、列表嵌套和 Grid 列数应以可读性为准，避免过深层级和过宽分栏
+- 文档开头可以是结论、背景、摘要、问题陈述、目录或直接正文，不强制使用 `<callout>`
+
+## 五、质量自检
+
+生成内容后可以从以下角度自检，但不要把这些项当作硬性比例或固定模板：
+
+| 指标 | 自检问题 |
+|-|-|
+| 信息表达 | 当前结构是否符合用户目标，而不是套用固定报告模板？ |
+| 阅读负担 | 是否有段落过长、层级过深、表格过宽或组件过多的问题？ |
+| 风格匹配 | 是否延续了用户给定样例或已有文档风格？ |
+| 组件必要性 | callout、grid、table、whiteboard 等是否真的提升理解？ |
+| 保真度 | 改写时是否保留了原文事实、引用、图片、附件和资源块？ |

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

@@ -5,7 +5,7 @@
 ## 核心方法论 — Code-Act Loop
 通过自适应的 **Code-Act Loop** 驱动文档改写，而非固定模板式的工作流。每次任务都循环执行：
 1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
-2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进改写；仅画板渲染按需隔离到 SubAgent（见步骤二）
+2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进
 3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
 4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
 
@@ -23,26 +23,33 @@
    - 需要精确跨节区间 → `docs +fetch --scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾）
    - 用户只给了模糊关键词 → `docs +fetch --scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`
    - 用户明确要改整篇 → `docs +fetch --detail with-ids`
-   - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) 中「选 `--scope`（读取范围）」小节
+   - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) "意图引导：选择正确的 --scope"
 2. 系统性评估：用户想改什么、现有文档风格是什么、哪些内容需要保留、哪些问题影响理解
-3. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段
+3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。重要信息优先画板化，记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段
 4. 向用户简要说明改进计划（包含识别出的画板机会）
 
-### 步骤二：定向改写（单 Agent 串行）
+### 步骤二：定向改写（并行 Agent）
 
-5. **优先处理步骤一识别出的画板候选段落**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
-6. 由主 Agent **顺序逐节**改写，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效：
+5. **优先处理步骤一识别出的画板候选段落**：
+   参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
+6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID：
    - 沿用或轻微调整已有文档风格，除非用户要求彻底重排版
-   - 优先通过重写段落、调整标题、补充小标题提升可读性；叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）
-   - 富 block 是可选表达手段，不因固定比例而添加，取舍遵循 `lark-doc-style.md` 的写作原则；画板类需求只走第 5 步
+   - 优先通过重写段落、调整标题、拆分列表或补充小标题提升可读性
+   - 富 block 是可选表达手段，不因固定比例而添加；画板类需求只走第 5 步
 
 ### 步骤三：验证（串行）
 
 7. 获取更新后文档局部内容，检查是否符合用户目标和已有风格
-8. 检查是否满足用户目标并保留原有关键内容。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题则定向修正
+8. 检查是否满足用户目标并保留原有关键内容；如仍有明显问题则定向修正，向用户呈现结果
 
-### 步骤四：专项校验（按需执行）
+## Agent 子任务要求
 
-9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果
+内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、用户目标/风格要求、具体的 `docs +update` command 和 `--block-id`。
 
-**上下文节省提示**：主 Agent 改某节时如需重新读取，优先用 `docs +fetch --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉当前章节，不要重复拉全文。
+Mermaid 图由主 Agent 直接插入 `<whiteboard type="mermaid">...</whiteboard>`，无需 SubAgent。
+
+SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
+
+已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
+
+**上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。

skills/lark-drive/SKILL.md

@@ -29,7 +29,6 @@ metadata:
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
-- 批量执行 `drive +import` 且目标是同一个位置（同一 `--folder-token`、默认根目录，或同一 `--target-token`）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
 - 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
 - 用户要比较原生 `.md` 文件的**历史版本差异**，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
 - 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
@@ -103,7 +102,6 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 | `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
 | `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable） |
-| `232140101` / `232140100` / `233523001`（常见于 `drive +import` 的 `job_error_msg`） | 同一位置下存在并发导入 / 创建操作 | 批量导入到同一文件夹、根目录或同一 `--target-token` 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突 |
 
 ### 权限能力入口
 

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

@@ -14,13 +14,6 @@
 > [!IMPORTANT]
 > 当用户**未传 `--name`** 时，文档标题默认取源文件名（去掉扩展名）。在执行导入前，先友好提示用户：「当前未指定文档标题，默认将使用"xxx"作为标题。如果文件内容中也包含相同标题，导入后可能造成视觉重复。是否需要重命名？」让用户确认后再继续。
 
-## 批量导入串行规则
-
-> [!IMPORTANT]
-> 批量执行 `drive +import` 且目标是同一个位置时，必须串行执行，不要并发发起导入任务。这里的“相同位置”包括同一个 `--folder-token`、都省略 `--folder-token` 导入到默认根目录，或使用同一个 `--target-token` 导入到已有 bitable。
->
-> 如果在同一位置下并发导入，服务端可能返回并发冲突错误。看到错误信息或 `job_error_msg` 中包含 `232140101`、`232140100`、`233523001` 任一错误码时，按同位置并发操作处理：停止并发导入，改为串行处理失败项；每个失败项每次重试前等待几秒，总共最多重试 3 次；仍失败就停止并向用户报告冲突。
-
 ## 命令
 
 ```bash
@@ -150,7 +143,6 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
 - “超过 20MB 自动切换分片上传”只表示上传链路会切到 multipart，不代表所有格式都允许导入超过 20MB 的文件。
 
 - 若导入任务执行失败，会返回失败时的 `job_status` 及错误信息。
-- 若导入失败信息包含 `232140101`、`232140100`、`233523001`，通常表示同一位置下存在并发导入 / 创建操作；批量场景请改为串行执行，每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突。
 - 若内置轮询超时但任务仍在处理中，shortcut 会成功返回，并带上：
   - `ready=false`
   - `timed_out=true`

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

@@ -23,8 +23,6 @@
 > 错误：`lark-cli drive +search 方案`
 > `+search` 不接受位置参数；空 `--query` 或省略 `--query` 表示纯靠 filter 浏览（合法）。
 >
-> **`--query` 最长 30 个字符**：按字符数（Unicode 码点）算，中文每字算 1 个，与 ASCII 同口径；超过 30 会被服务端拒绝（`99992402 field validation failed`，**是报错不是截断**）。长关键词必须先压缩成核心实体 + 主题词（如把整句问题压成「项目名 + 主题」再搜），不要把整句原问塞进 `--query`。
->
 > **列表型请求不要硬塞关键词**：如果用户只是要求"我这月创建的所有文档"、"最近半年我编辑过的文档"、"按类型分类统计"这类范围浏览 / 汇总请求，且没有给出标题片段或业务关键词，应使用 `--query ""` 搭配 `--created-by-me`、`--mine`、`--created-*`、`--edited-*`、`--doc-types` 等过滤条件。不要把"查找"、"所有文档"、"最近更新过"、"按类型分类统计"这类动作词或统计意图放进 `--query`，否则会把本来应靠 filter 命中的结果过度收窄。
 
 ### 自然语言 → 命令映射速查
@@ -103,7 +101,7 @@ lark-cli drive +search --query 方案 --page-token '<PAGE_TOKEN>'
 
 | 参数 | 必填 | 说明 |
 |---|---|---|
-| `--query <text>` | 否 | 搜索关键词；支持服务端高级语法（`intitle:`、`""`、`OR`、`-`）。空字符串或省略表示纯 filter 浏览。**长度上限 30 个字符（按 Unicode 码点算，中文每字算 1 个，与 ASCII 同口径）；超过 30 服务端直接报 `99992402 field validation failed`，不会截断** |
+| `--query <text>` | 否 | 搜索关键词；支持服务端高级语法（`intitle:`、`""`、`OR`、`-`）。空字符串或省略表示纯 filter 浏览 |
 | `--page-size <n>` | 否 | 每页数量，默认 15，最大 20。超过 20 自动 clamp；非正数（≤0）回落 15；**非数字值直接返回 validation 错误** |
 | `--page-token <token>` | 否 | 上一次响应里的 `page_token`，用于翻页 |
 | `--format` | 否 | `json`（默认）/ `pretty` |

skills/lark-minutes/references/lark-minutes-speaker-replace.md

@@ -81,8 +81,6 @@ lark-cli minutes +speaker-replace \
 
 Agent 必须先 `lark-cli api GET .../speakerlist`，再 `+speaker-replace`；`--from-speaker-id` 只接受 `speaker_id`。
 
-`+speaker-replace` **不会**自己请求 speakerlist：`--from-speaker-id` 的值会原样发给替换接口。整条链路只在 Agent 一开始查一次 speakerlist，务必传入上一步拿到的 `speaker_id`（不要传展示名，否则替换接口会返回 speaker-not-found）。
-
 ### 2. 新说话人必须是 open_id
 
 `--to-user-id` 仅支持 `ou_` 开头的 open_id，**不支持直接传姓名**；如果用户只给了姓名，请先用 [lark-contact](../../lark-contact/SKILL.md) 把姓名解析成 `open_id`。

skills/lark-shared/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-shared
 version: 1.0.0
-description: "Use for lark-cli setup/auth/profile-selection tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, handling _notice JSON, profile/tenant/app-identity selection, or any request to make this task/session (or all following lark-cli commands) run under a specific profile/tenant — via LARKSUITE_CLI_PROFILE, --profile, unset LARKSUITE_CLI_PROFILE, or whoami identity diagnostics."
+description: "Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling _notice JSON."
 ---
 
 # lark-cli 共享规则
@@ -32,7 +32,7 @@ lark-cli config init --new
 | 获取全部权限 | `lark-cli auth login --domain all --no-wait --json` |
 | 按业务域授权 | `lark-cli auth login --domain docs --domain drive --no-wait --json`；`--domain` 可重复，也可用逗号分隔 |
 | 指定单个 scope 授权 | `lark-cli auth login --scope "<scope>" --no-wait --json` |
-| 检查当前登录态、是谁登录、token 是否有效 | 必须运行 `lark-cli auth status --json --verify`；回答时引用 `identity`、`verified`、`identities.user.status`、`identities.user.userName`、`identities.user.openId`（用户 open id）、`identities.user.tokenStatus`、`identities.user.scope` |
+| 检查当前登录态、是谁登录、token 是否有效 | `lark-cli auth status --json --verify`；回答时引用 `identity`、`verified`、`identities.user.status`、`identities.user.userName`、`identities.user.openId`（用户 open id）、`identities.user.tokenStatus`、`identities.user.scope` |
 | 快速查看当前身份状态 | `lark-cli whoami`；实际生效的那一个身份 |
 | 退出当前机器的用户登录态 | `lark-cli auth logout --json`；`loggedOut:true` 表示注销成功 |
 | bot 缺少权限 | 不要执行 `auth login`；引导用户在开发者后台开通 bot scope，优先复用错误里的 `console_url` |
@@ -126,10 +126,6 @@ lark-cli auth login --device-code <device_code>
 - **不要在同一轮中展示 URL 后立刻执行 `--device-code`**，这会导致用户看不到 URL
 - **禁止缓存 `verification_url` 或 `device_code`**：每次需要授权时，必须重新执行 `lark-cli auth login --no-wait --json` 生成新的链接。不要将授权链接和 device code 存入上下文供后续复用
 
-## Profile 选择
-
-Profile selection: use `--profile <profile-or-appId>` for one command; for a task/session, prefix later `lark-cli` commands with `LARKSUITE_CLI_PROFILE=<profile-or-appId>` unless shell env persists, where you may `export` once and later `unset`. Ask if the selector is unknown; do not merely promise. Use `whoami` for the effective app/profile identity and `auth status --json --verify` for OAuth token state. Do not run `lark-cli profile use` unless changing the long-term default, and do not set `LARKSUITE_CLI_APP_ID`/`LARKSUITE_CLI_APP_SECRET` unless direct credentials are provided.
-
 ## 更新检查
 
 lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段（含 `message`、`command` 等）。

skills/lark-sheets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-sheets
-version: 3.0.0
+version: 3.0.1
 description: "飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作原子批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）、金融/财务建模（DCF、三张表、预算、Sensitivity 等）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
@@ -32,57 +32,124 @@ metadata:
 | 透视表 pivot | `--pivot-table-id` | 迷你图（按组） | `--group-id` |
 | 浮动图片 | `--float-image-id` | | |
 
+## 飞书表格编辑准则（动手前必守，所有编辑类任务一律生效）
+
+下列准则横切所有飞书表格任务，**动手前先过一遍**——即使你是被索引直接路由进某个工具参考也一律生效。每条只给一句话纲要，展开与边界见括注的 reference。
+
+1. **最小改动**：除任务要改的单元格 / 列外，原表其它单元格、行列结构、Sheet 名、合并区、格式 1:1 保持；中间结果放原数据右侧或新建空白 Sheet，**禁止删 / 改名 / 隐藏 / 移动已存在 Sheet**；改写类任务精确圈定行列，不该转的原值 1:1 保留。
+2. **真实写回 + 回读校验**：交付必须是对在线表格的真实写入，写完用 `+csv-get` / `+cells-get` / `+<对象>-list` 回读确认实际生效——**写操作返回 `ok` 只代表请求被接受、不代表结果符合预期**；写公式后查错误码、筛选 / 排序后核对前几行、删除 / 清空后确认已空。禁止只在文本里声称"已完成"。
+3. **读全再写**：批量填充 / 补齐 / 修正类任务先确认真实数据末行再写，只探前 N 行会漏写表尾（确定末行流程见 `lark-sheets-read-data`）。
+4. **公式优先于硬编码**：能用公式表达的计算（总计 / 占比 / 增长率 / 提取 / 查找）一律写公式而非静态值；**凡可由表内其它单元格推导的派生值默认就用公式，即使用户没说"联动 / 自动更新"**；写任何飞书公式前先读 `lark-sheets-formula-translation`，而且**只要公式真实写入表格，收尾默认就要继续跑 `lark-sheets-formula-verify` 的 `+formula-verify`，直到 `status='success'`**。
+5. **续写 / 扩展继承样式**：续写、补齐、复制区块、新增行列时禁止只读值只写值，必须连带 `cell_styles` + `border_styles` + 合并 + 行高一起继承（清单见 `lark-sheets-write-cells`，四边框最易漏）。
+6. **多步写入合并 `+batch-update`**：多个连续写入、或同一工具对多区域重复调用，合并为单次原子 `+batch-update`（语义见 `lark-sheets-batch-update`）。
+7. **分组汇总用透视表**："按 X 统计 Y / 分组汇总 / 各类数量金额"用 `+pivot-{create|update|delete}`，禁止用 SUMIF / 本地脚本拼一张假透视表。
+8. **拆成可验证 checklist**：落地前把指令拆成所有"独立可验证子要点"，逐点 `assert` 全过才交付（多维排序每维一点、多目标每目标一点、范围类核起 / 末 / 边界）；只做第一个要点属违规。
+9. **全量处理前置断言条数**：翻译 / 打标 / 批量公式落地等逐条任务，先把预期条数硬编码再 `assert actual == expected`，禁止输出"已完成前 N 条，剩余继续"的半成品。
+
+> 上述准则的实操展开——读取路径、原生工具优先级、脚本配合、易漏陷阱——见下方「执行要点」节；端到端工作流为：了解结构（`+workbook-info`）→ 读数据 → 理解语义 → 原生工具优先 → 写入 → 回读验证。
+
 ## 场景 → 命令速查（拿不准命令名先查这里，别按直觉拼）
 
-把高频意图映射到**真实存在**的 shortcut / flag。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。
+把高频意图映射到**真实存在**的 shortcut / flag。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。**选定命令后别急着写——先读「动手前读」列指向的 reference 再动手**：命令名对得上不代表用法对，写入 / 清除 / 透视类尤其容易漏掉 reference 里的防错、类型与样式继承规则。
 
-| 你要做的事 | ✅ 正确写法 | ❌ 不存在（会被 cobra 拒） |
-| --- | --- | --- |
-| 读数据（纯值 / CSV） | `+csv-get`（范围用 `--range`） | `+get-range`、`+range-get`、`+cells-read` |
-| 读值 + 公式 / 样式 / 批注 | `+cells-get --include value,formula,style,comment,data_validation` | `+get-cell`、`+cell-get`、`--with-styles`、`--with-merges`、`--include-merged-cells` |
-| 写纯文本值（整块 CSV 平铺，列里没有需保留的数值 / 日期语义） | `+csv-put`（定位用 `--start-cell`，单个左上角锚点格；也接受 `--range` 别名，区间自动取左上角） | — |
-| 写带类型的数据到**已有**表（列里有数字 / 金额 / 百分比 / 日期 / 计数，要可排序 / 求和 / 入图表 / 透视） | `+table-put --sheets` 完整 payload `{"sheets":[{...}]}`（列名走 `columns`、二维数据走 `data`、列 pandas dtype 走 `dtypes`、列展示格式走 `formats`；来源不限 DataFrame——Counter / dict / list 同理，详见 write-cells） | 在本地把数字拼成 `"$1,234"` / `"30.5%"` 字符串再 `+csv-put`（会落成文本、丢失计算能力） |
-| **新建**电子表格并写带类型的数据（类型保真需求同上，但目标表还不存在） | `+workbook-create --sheets`（协议与 `+table-put` 同构、一步建表 + typed 写入，无需先建空表再 `+table-put`；date / number 不丢，详见 workbook） | 用 `--values` 灌日期 / 数字（会落成文本、丢类型） |
-| 写值 / 公式 / 样式 | `+cells-set`（定位用 `--range`） | — |
-| 插图：图片**绑定到某条记录**、随行走（凭证 / 证件照 / 商品图 / 头像 / 二维码 / 每行配图） | `+cells-set-image`（单格 `--range`，嵌入单元格内） | — |
-| 插图：**自由摆放、不绑数据**的装饰 / 标识（logo / 水印 / 封面大图 / banner） | `+float-image-create`（浮动图片，自由定位 + 尺寸 + 层级） | — |
-| 查找单元格 | `+cells-search`（关键字用 `--find`） | `+cells-find`、`+find`、`--query` |
-| 查找并替换 | `+cells-replace` | — |
-| 看子表结构（合并 / 行高列宽 / 冻结 / 隐藏） | `+sheet-info` | `+sheet-get`、`+structure-get`、`+sheet-structure-get` |
-| 看工作簿 / 子表清单 | `+workbook-info` | `+sheet-list`、`+workbook-get`、`+workbook-list` |
-| 导出 xlsx / 单表 csv | `+workbook-export` | — |
-| 导入本地 xlsx/xls/csv 文件为飞书电子表格 | `+workbook-import --file ./x.xlsx`（本地表格文件 → 飞书电子表格的正解；仅要导成多维表格 bitable 时才用 `drive +import --type bitable`） | `drive +import`（导电子表格时绕了 drive 通道、还要多给 `--type`，应直接用 `+workbook-import`）、把 .xlsx 在本地读成数据再 `+workbook-create` 重灌 |
-| 清除内容 / 格式 | `+cells-clear`（范围维度用 `--scope`，取值 content / formats / all） | `--type` |
-| 批量清除多区域 | `+cells-batch-clear`（`--scope`） | `--target` |
-| 调整列宽 / 行高 | `+cols-resize` / `+rows-resize`（行、列是两个独立命令） | `--dimension`（无此 flag） |
-| 分组汇总 / 透视 | `+pivot-create`（默认不传落点 flag → 自动新建子表，零覆盖） | 用 SUMIF / 本地脚本拼一张假透视表 |
+| 你要做的事 | ✅ 正确写法 | 动手前读 | ❌ 不存在（会被 cobra 拒） |
+| --- | --- | --- | --- |
+| 读数据（纯值 / CSV） | `+csv-get`（范围用 `--range`） | `lark-sheets-read-data` | `+get-range`、`+range-get`、`+cells-read` |
+| 读值 + 公式 / 样式 / 批注 | `+cells-get --include value,formula,style,comment,data_validation` | `lark-sheets-read-data` | `+get-cell`、`+cell-get`、`--with-styles`、`--with-merges`、`--include-merged-cells` |
+| 写纯文本值（整块 CSV 平铺；列里**没有**需字面保真的数值 / 日期标签 / 编号——点分日期 `12.10`、编号 `001` 会被 csv-put 数值化，不算纯文本） | `+csv-put`（定位用 `--start-cell`，单个左上角锚点格；也接受 `--range` 别名，区间自动取左上角） | `lark-sheets-write-cells` | 把含点分日期(`12.10`)/编号(`001`)的列裸灌 `+csv-put`——会被数值化（`12.10`→`12.1`、`001`→`1`，尾零/前导零丢失），改用 `+table-put` 声明 `dtypes:object` |
+| 写带类型的数据到**已有**表（列里有数字 / 金额 / 百分比 / 日期 / 计数等**本质是量值**的数据——不看当下要不要排序 / 求和，量值一律走这里） | `+table-put --sheets` 完整 payload `{"sheets":[{...}]}`（列名走 `columns`、二维数据走 `data`、列 pandas dtype 走 `dtypes`、列展示格式走 `formats`；来源不限 DataFrame——Counter / dict / list 同理；要同时美化加 `--styles` 一步带样式（区域底色 / 边框 / 列宽 / 行高 / 合并），不必事后再刷；payload 里不存在的 sheet 名会自动建子表，详见 write-cells） | `lark-sheets-write-cells` | 在本地把数字拼成 `"$1,234"` / `"30.5%"` 字符串再 `+csv-put`（会落成文本、丢失计算能力；常见借口见下方 ⚠️） |
+| **新建**电子表格并写带类型的数据（类型保真需求同上，但目标表还不存在） | `+workbook-create --sheets`（协议与 `+table-put` 同构、一步建表 + typed 写入，无需先建空表再 `+table-put`；date / number 不丢；`--styles` 同样可在建表同一步带全套样式，详见 workbook） | `lark-sheets-workbook` | 用 `--values` 灌日期 / 数字（会落成文本、丢类型） |
+| 写公式 / 富写入（样式 · 批注 · 图片 · 富文本），或需精确矩形定位的值 | `+cells-set`（定位用 `--range`；批注 / 图片 / 富文本只能用它，公式也可；**公式落表后继续 `+formula-verify` 收尾**） | `lark-sheets-write-cells` | — |
+| 插图：图片**绑定到某条记录**、随行走（凭证 / 证件照 / 商品图 / 头像 / 二维码 / 每行配图） | `+cells-set-image`（单格 `--range`，嵌入单元格内） | `lark-sheets-write-cells` | — |
+| 插图：**自由摆放、不绑数据**的装饰 / 标识（logo / 水印 / 封面大图 / banner） | `+float-image-create`（浮动图片，自由定位 + 尺寸 + 层级） | `lark-sheets-float-image` | — |
+| 查找 / 替换文本 | `+cells-search`（找，关键字用 `--find`）、`+cells-replace`（替换） | `lark-sheets-search-replace` | `+cells-find`、`+find`、`--query` |
+| 看子表结构（合并 / 行高列宽 / 冻结 / 隐藏） | `+sheet-info` | `lark-sheets-sheet-structure` | `+sheet-get`、`+structure-get`、`+sheet-structure-get` |
+| 看工作簿 / 子表清单 | `+workbook-info` | `lark-sheets-workbook` | `+sheet-list`、`+workbook-get`、`+workbook-list` |
+| 复核某次（AI）编辑改了什么 / 取两个版本间的变更 | `+changeset-get --start-revision <编辑前版本>`（省略 `--end-revision` 取到最新；版本差 ≤ 20） | — |
+| 取当前文档 revision（版本号） | `+revision-get` | `lark-sheets-workbook` | — |
+| 导出 xlsx / 单表 csv | `+workbook-export` | `lark-sheets-workbook` | — |
+| 导入本地 xlsx/xls/csv 文件为飞书电子表格 | `+workbook-import --file ./x.xlsx`（本地表格文件 → 飞书电子表格的正解；仅要导成多维表格 bitable 时才用 `drive +import --type bitable`） | `lark-sheets-workbook` | `drive +import`（导电子表格时绕了 drive 通道、还要多给 `--type`，应直接用 `+workbook-import`）、把 .xlsx 在本地读成数据再 `+workbook-create` 重灌（多此一举，应直接 `+workbook-import`）、要把文件并入某个**已有在线工作簿**（给它加子表）却用它——import 只会新建独立表，加子表应走 `+sheet-copy` / `+sheet-create` |
+| 参考某个**已有在线表**、把多个本地文件 / 数据各作为一张子表**追加**进去（不另起独立表） | 先 `+workbook-info` 拿模板子表 `sheet_id` → `+sheet-copy` 逐张复制模板子表（公式 / 合并 / 分组底色 / 列宽 / 条件格式全继承）再用 `+cells-*` 只改数据；无模板可继承时 `+sheet-create` 建空子表 + `+table-put --sheets/--styles` 写入 | `lark-sheets-workbook` | 把文件 `+workbook-import` / `+workbook-create` 另起一张**独立新表**（目标是并入已有工作簿时就跑偏了；这两条只产新表、不接受已有表定位） |
+| 清除内容 / 格式 | `+cells-clear`（范围维度用 `--scope`，取值 content / formats / all） | `lark-sheets-range-operations` | `--type` |
+| 批量清除多区域 | `+cells-batch-clear`（`--scope`） | `lark-sheets-batch-update` | `--target` |
+| 调整列宽 / 行高 | `+cols-resize` / `+rows-resize`（行、列是两个独立命令） | `lark-sheets-range-operations` | `--dimension`（无此 flag） |
+| 分组汇总 / 透视 | `+pivot-create`（默认不传落点 flag → 自动新建子表，零覆盖） | `lark-sheets-pivot-table` | 用 SUMIF / 本地脚本拼一张假透视表 |
+| 画图表 / 可视化（柱 / 折线 / 饼 / 条 / 散点 / 组合…） | `+chart-create` | `lark-sheets-chart` | matplotlib / 本地画图再贴图（原生图表可交互、随数据更新） |
+| 条件高亮 / 数据条 / 色阶 / 重复值标记 | `+cond-format-create` | `lark-sheets-conditional-format` | `+highlight`、`+conditional-format`、逐格 `+cells-set-style` 硬凑 |
+| 筛选 / 只看符合条件的行 | `+filter-create` | `lark-sheets-filter` | pandas filter 后覆盖写回（会毁原数据；要保存多份筛选状态用 `+filter-view-create`） |
 
+> ⚠️ **动手前的触发式必读（按动作判定，不看主场景）**：本次操作只要**涉及样式 / 美化**（底色 / 边框 / 字号 / 对齐 / 数字格式 / 汇总行 / 配色 / 列宽行高），动手前先读 `lark-sheets-visual-standards`；只要**要写飞书公式**，动手前先读 `lark-sheets-formula-translation`（飞书函数与 Excel 有差异，凭直觉迁移易错），**写完后再读 `lark-sheets-formula-verify` 并执行 `+formula-verify` 收尾**。哪怕主任务是"建表 / 展开数据 / 录入"，只要动作里含美化或写公式就适用——别因"这不算专门的美化 / 公式任务"而跳过。
 > ⚠️ **两种图片别选错**：图若**绑定某条记录、要随行排序 / 筛选 / 增删**（凭证 / 证件照 / 每行配图，话里带「对应 / 每行 / 这列」等绑定词）→ 单元格图片 `+cells-set-image`；只是自由摆放的装饰（logo / 水印 / 封面）→ 浮动图片 `+float-image-create`。别因「浮动图更好控制 / 更熟」默认选浮动图。
-> ⚠️ **纯文本还是数值语义**：要写的列里有数字 / 金额 / 百分比 / 日期 / 计数 → `+table-put`（写入已有表；外层 `{"sheets":[...]}` 包裹、列 pandas dtype 用 `dtypes`、展示格式用 `formats`，保留排序 / 求和 / 图表 / 透视能力；**目标表还不存在就用 `+workbook-create --sheets`**，同 typed 协议、一步建表 + 写入，别先建空表再 `+table-put`）；只有纯文本才用 `+csv-put`。两者写完显示可以完全相同，但 `+csv-put` 落的是文本、不能参与计算——别把数值在本地拼成带 `$` / `%` 的字符串再走 `+csv-put`。
+> ⚠️ **纯文本还是数值语义（看数据本质，不看当下用途）**：金额 / 百分比 / 比率 / 计数 / 日期等**本质是量值**的数据 → 一律数值写入，常规二维表用 `+table-put`（`dtypes` 声明类型 + `formats` 设展示格式），版式装不下（多级 / 合并表头的宽表 leaderboard 等）改用 `+cells-set` 传数字（百分比传小数 `0.4`）+ `number_format`，照样显示 `40%` 且数值无损。只有编号 / 身份证 / 单据号这类**本质是标识符**、要字面保真的才用 `+csv-put` 平铺。**几个常见借口都不成立**——"只是 leaderboard / 报表展示不用算""版式复杂""样式以后再刷、先铺文本"都不是把百分比写成 `"40%"` 字符串灌 `+csv-put` 的理由（展示不改变它是数值；类型不能后补，落成文本就回不来）。判据与操作展开见 `lark-sheets-write-cells`「数字还是文本」。
+> ⚠️ **要新建子表 / 整表美化 → 别默认「`+csv-put` 写值再事后刷样式」**：`+table-put` / `+workbook-create` 的 `--styles` 能在写数据的**同一步**带全套样式（区域底色 / 边框 / 列宽 / 行高 / 合并），且 `+table-put` 的 payload 里若 sheet 名不在工作簿中会自动新建子表——**纯文本表要新建子表 + 美化时同样走这里**（`--styles` 与列是否 typed 无关），比「`+csv-put` 写值 + 多次 `+cells-batch-set-style` / `+*-resize` 刷样式」少好几次调用（冻结行列等 sheet 级属性仍需 `+dim-freeze` 单独一步）。
 > ⚠️ **定位 flag**：`+cells-get` / `+cells-set` / `+csv-get` 用 `--range`；`+csv-put` 规范用 `--start-cell`（单个左上角锚点格），也接受 `--range` 别名（区间自动取左上角），二者择一即可。
 > ⚠️ **读取附加信息**一律走 `+cells-get --include …`，**没有** `--with-styles` 这类 flag；**看合并单元格**用 `+sheet-info` 的 `merged_cells`，不要在 `+cells-get` 里找 merge flag。
 
+## 执行要点（读取 / 原生工具 / 陷阱）
+
+准则的实操展开。端到端工作流：了解结构 → 读数据 → 理解语义 → 原生工具优先 → 写入 → 回读验证。
+
+### 读取：按需求选路径（细则见 `lark-sheets-read-data`）
+
+| 用户需求 | 读取路径 |
+|---|---|
+| "完善 / 补齐 / 填空 / 修正所有 XX"、分析 / 清洗 / 大数据 | 原生优先（公式 / `+pivot` / `+filter`）；表达不了再分批 `+csv-get` 导出 + 脚本处理 + 分批回写（默认覆盖所有对应数据行，不以用户选区为准） |
+| "查一下 / 看看 / 统计 / 汇总"等只读 | `+csv-get` 读到上下文 |
+| 需要公式 / 样式 / 批注 | `+cells-get` |
+| 续写 / 扩展已有内容 | `+csv-get` 看结构 + `+cells-get` 读源区样式 + `+sheet-info --include row_heights,merges`（见准则 5） |
+
+> "补齐 / 填空"类用只读路径探 10 行就写会漏写表尾——写入前先按 `lark-sheets-read-data` 确认真实数据末行（准则 3）。
+
+### 计算：原生工具优先，代码兜底（强化准则 7）
+
+| 用户需求 | 用原生 | 禁止的替代 |
+|---|---|---|
+| 按 X 统计 Y、分组汇总 | `+pivot-{create\|update\|delete}` | pandas groupby → 写值 |
+| 求和 / 计数 / 平均 / 占比 | 公式 | Python 算 → 写静态值 |
+| 图表 / 可视化 | `+chart-*` | matplotlib |
+| 条件高亮 / 色阶 | `+cond-format-*` | 逐格设样式 |
+| 筛选 | `+filter-*` | pandas filter → 覆盖写入 |
+| 文本提取 / 转换 / 查找 | 公式（REGEXEXTRACT / TEXT / VLOOKUP 等） | Python → 写静态值 |
+
+只有多步清洗、统计建模、公式试错 3 次仍失败时才用代码。
+
+### 用脚本配合 CLI 时
+
+- **只读 stdout**：CLI 数据走 stdout、诊断走 stderr；解析 JSON 别 `2>&1`（警告混入会解析失败），用管道或单独重定向 stdout。
+- **喂 CLI 的 CSV / JSON 用 UTF-8 无 BOM**；临时文件放系统临时目录、勿落项目目录。
+- **命令失败先读 stderr 再调整**，别原样重发。
+- **回写纯单元格值**：剥离 `值(V-Align: bottom)` 这类"值(样式)"串与残留引号再写；排序优先 `+range-sort` 原生工具，别"读出本地排完再整列写回"。
+
+### 易漏陷阱
+
+- **`+dim-insert` 不继承行高**：只继承值 / 公式 / 边框，新行回落默认高度截断长文本；插行填长文本前读相邻行 `row_height`，用 `+batch-update` 合 `+rows-resize` 补齐。
+- **公式容错**：日期 / 查找 / 数值转换公式用 `IFERROR` 包裹；写完读结果列首末各 5 行查 `#VALUE!` / `#REF!` / `#DIV/0!`，然后继续跑 `+formula-verify` 直到 `status='success'`；同一方案试错上限 3 次。
+- **循环引用**：聚合公式引用范围不能含目标 cell 自身或其传递依赖。
+- **隐藏行列**：`+csv-get` 默认含隐藏行列；设 `--skip-hidden=true` 只看可见，但返回行序号与实际行号不再对应。
+- **跨 sheet 对象**：图表 / 条件格式 / 透视表 / 浮动图片可能分布在多个子表，操作前先 `+workbook-info` 掌握全局。
+- **NLP 任务分批**：语义理解 / 翻译 / 改写 / 分类等用 NLP 处理（代码只做分批 / 行号映射 / 写回）；数据量大必须分批（通常 30 行 / 批），每批处理完即时写回，单批生成通常 ≤ 300 行，多批用 `+batch-update`。
+
 ## References
 
-本 skill 的 reference 分两组：先读**通用方法与规范**（横切所有任务的工作流、铁律、样式、公式规则，不含具体 shortcut），它们规定了"怎么做对"；再按操作对象进入**工具参考**查具体 shortcut 与调用细节。编辑类任务务必先过一遍通用方法与规范，其中的铁律对所有工具参考一律生效。
+本 skill 的 reference 分两组：先读**通用方法与规范**（横切所有任务的样式、公式规则，不含具体 shortcut），它们规定了"怎么做对"；再按操作对象进入**工具参考**查具体 shortcut 与调用细节。编辑类任务务必先过一遍通用方法与规范，连同上方「飞书表格编辑准则」对所有工具参考一律生效。
 
 ### 通用方法与规范（先读，横切所有任务，不含具体 shortcut）
 
 | Reference | 描述 |
 | --- | --- |
-| [飞书表格核心操作：分析、编辑与可视化](references/lark-sheets-core-operations.md) | 飞书表格核心操作工作流。当用户需要对已有的飞书表格进行查看、分析、编辑或可视化时使用。适用场景：数据查询与统计、公式计算、表格美化、创建图表/透视表、筛选排序、批量修改数据、调整表格结构等。即使用户没有明确说"飞书表格"，只要操作对象是已有的在线表格，都应触发此工作流。 |
-| [飞书表格样式与配色规范](references/lark-sheets-visual-standards.md) | 飞书表格样式与配色规范：表头/数据区/汇总行的颜色、字号、对齐、边框等取值标准，以及新增汇总行、追加行列继承原表风格、已有区域美化等典型场景的决策流程与样式要点。工具调用参数细节请参考对应的 lark-sheets-write-cells / lark-sheets-range-operations / lark-sheets-batch-update。条件格式（高亮、标红、数据条、色阶）请使用 lark-sheets-conditional-format。 |
-| [飞书表格公式生成规则](references/lark-sheets-formula-translation.md) | Excel 公式到飞书表格公式的迁移与生成规则。核心目标不是保留 Excel 原语法，而是按飞书表格可执行规则重写公式，并在结果上尽量对齐 Excel。当用户要求把 Excel 公式改写成飞书表格公式，或需要生成飞书公式（尤其涉及 ARRAYFORMULA、原生数组函数、INDEX/OFFSET、MAP/LAMBDA、日期差、多层范围结果与二次展开）时使用。 |
+| [飞书表格样式与配色规范](references/lark-sheets-visual-standards.md) | 飞书表格样式与配色规范：表头/数据区/汇总行的颜色、字号、对齐、边框、数字格式等取值标准，以及从零新建表格的版式美化、新增汇总行、追加行列继承原表风格、已有区域美化等典型场景的决策流程与样式要点。工具调用参数细节请参考对应的 lark-sheets-write-cells / lark-sheets-range-operations / lark-sheets-batch-update。条件格式（高亮、标红、数据条、色阶）请使用 lark-sheets-conditional-format。 |
+| [飞书表格公式生成规则](references/lark-sheets-formula-translation.md) | Excel 公式到飞书表格公式的迁移与生成规则。核心目标不是保留 Excel 原语法，而是按飞书表格可执行规则重写公式，并在结果上尽量对齐 Excel。当用户要求把 Excel 公式改写成飞书表格公式，或需要生成飞书公式（尤其涉及 ARRAYFORMULA、原生数组函数、INDEX/OFFSET、MAP/LAMBDA、日期差、多层范围结果与二次展开）时使用。本文只负责把公式写对，落表后的强制收尾请接 `lark-sheets-formula-verify`。 |
 
 ### 按对象的工具参考（含 shortcut）
 
 | Reference | 描述 |
 | --- | --- |
+| [Lark Sheet Formula Verify](references/lark-sheets-formula-verify.md) | 公式写入 / 批量填充 / `--copy-to-range` 扩展 / 导入含公式工作簿后的强制自检入口。对指定子表（或整本工作簿）扫描公式与单元格值，聚合所有 Excel 错误（#REF! / #DIV/0! / #VALUE! / #NAME? / #NULL! / #NUM! / #N/A），同时合并最近一次写入留下的编译失败（formula_errors），输出统一 JSON 让 AI 一次拿到完整健康度报告。只要任务涉及写公式，落表后就应调用 +formula-verify 收敛到 zero-error；`status='errors_found'` 或 `status='partial'` 时禁止把链路标为完成。 |
 | [Lark Sheet Workbook](references/lark-sheets-workbook.md) | 管理飞书表格的工作簿结构（子表列表及元数据）。当用户提到"看看这个表格有什么"、"表格结构"、"有哪些 sheet"、"新建一个 sheet"、"删除这个工作表"、"重命名"、"复制一份"、"移动到前面"时使用。 |
 | [Lark Sheet Sheet Structure](references/lark-sheets-sheet-structure.md) | 管理飞书表格的子表结构与布局。适用场景：查看行高、列宽、隐藏行列、合并单元格等布局信息，以及"插入一行"、"删除这列"、"隐藏行"、"冻结表头"、行列分组（大纲折叠/展开）等操作。行列大纲仅在用户明确提到"行分组"、"列分组"、"大纲"、"outline"时才触发，"按XXX分组"等数据分组场景请使用 lark-sheets-pivot-table。如需在表尾追加数据，应先通过此 skill 插入行，再通过 lark-sheets-write-cells 写入。 |
 | [Lark Sheet Read Data](references/lark-sheets-read-data.md) | 读取飞书表格中的单元格数据。当用户需要"看看数据"、"分析数据"、"统计/汇总"时使用；也适用于需要查看公式、样式、批注等详细信息的场景。 |
 | [Lark Sheet Search & Replace](references/lark-sheets-search-replace.md) | 在飞书表格中搜索和替换文本，支持限定范围、大小写匹配、精确匹配、正则表达式。当用户需要"查找"、"搜索"、"定位"某个值，或"替换"、"批量修改文本"、"把 A 改成 B"时使用。不要用于理解表格结构（应读取数据）、不要用于数据分析（应读取数据后计算）、不要把用户操作动作中的关键词（如"汇总金额""统计数量"）当作搜索词。 |
-| [Lark Sheet Write Cells](references/lark-sheets-write-cells.md) | 向飞书表格的指定区域批量写入值、公式、样式、批注或单元格图片。适用场景：填写数据、设置公式、修改格式、添加批注、嵌入单元格图片（如需操作浮动图片，请使用 lark-sheets-float-image）；若只需把一块 CSV 批量铺到表格上（值或公式，不带样式/批注），直接使用 `+csv-put` 更短更快。追加数据需先通过 lark-sheets-sheet-structure 插入行列。 |
+| [Lark Sheet Write Cells](references/lark-sheets-write-cells.md) | 向飞书表格的指定区域批量写入值、公式、样式、批注或单元格图片。适用场景：填写数据、设置公式、修改格式、添加批注、嵌入单元格图片（如需操作浮动图片，请使用 lark-sheets-float-image）；若只需把一块 CSV 批量铺到表格上（值或公式，不带样式/批注），直接使用 `+csv-put` 更短更快。追加数据需先通过 lark-sheets-sheet-structure 插入行列。只要这次写入真实落了公式，收尾默认继续执行 `lark-sheets-formula-verify`。 |
 | [Lark Sheet Range Operations](references/lark-sheets-range-operations.md) | 对飞书表格中指定区域执行结构性操作（不涉及写入单元格数据值）。适用场景：清除内容或格式（"清空"、"删除内容"、"去掉格式"）、合并/取消合并单元格、调整行高列宽（"加宽列"、"自适应列宽"）、移动/复制/填充/排序数据（"移动数据"、"复制到"、"自动填充"、"按某列排序"）。写入单元格数据请使用 lark-sheets-write-cells。 |
 | [Lark Sheet Batch Update](references/lark-sheets-batch-update.md) | 将多个飞书表格写入操作合并为一次批量执行，按顺序依次完成。适合需要连续执行多个写入操作的场景（如先修改结构再写入数据）。 |
 | [Lark Sheet Chart](references/lark-sheets-chart.md) | 管理飞书表格中的图表（柱形图、折线图、饼图、条形图、面积图、散点图、组合图、雷达图等）。当用户需要创建图表、修改图表样式或数据源、查看已有图表配置、删除图表时使用。也适用于用户提到"数据可视化"、"画个图"、"趋势分析"、"对比图"、"占比分析"、"做个图表"等数据可视化相关场景。 |
@@ -92,6 +159,8 @@ metadata:
 | [Lark Sheet Filter View](references/lark-sheets-filter-view.md) | 管理飞书表格中的筛选视图（filter view）。当用户需要"建一个 XX 视图"、"保存这个筛选状态"、"切换不同筛选"、维护一个 sheet 上多份独立筛选配置时使用。视图与筛选器（filter）相互独立，可在同一 sheet 共存；视图的隐藏行仅在用户进入该视图时本地生效，不影响其他协作者。 |
 | [Lark Sheet Sparkline](references/lark-sheets-sparkline.md) | 管理飞书表格中的迷你图（折线迷你图、柱形迷你图、胜负迷你图）。当用户需要在单元格内嵌入小型图表来展示数据趋势时使用。也适用于"趋势线"、"单元格内图表"、"迷你图"等场景。注意：不等同于被禁用的 SPARKLINE() 公式函数。 |
 | [Lark Sheet Float Image](references/lark-sheets-float-image.md) | 管理飞书表格中的浮动图片。当用户需要在表格中插入浮动图片、调整图片位置和大小、查看已有浮动图片、删除图片时使用。也适用于"插入图片"、"添加 logo"、"放一张图"等场景。注意：如果用户需要将图片嵌入到某个单元格内部（单元格图片），请阅读 lark-sheets-write-cells。 |
+| [Lark Sheet History](references/lark-sheets-history.md) | 查询飞书表格的历史版本、回滚到指定版本，或撤销当前用户最近一次 AI 工具写入。当用户需要查看编辑历史、回滚历史版本、查询回滚状态，或说“撤销我刚才的修改 / undo 上一步 AI 写入”时使用。历史回滚为异步全表恢复；用户维度 undo 只撤当前用户自己的 undo 栈顶。仅针对飞书表格。 |
+| [Lark Sheet Changeset](references/lark-sheets-changeset.md) | 读取两个版本（CS revision）之间的 changeset（原始变更操作清单），用于复核某次编辑——尤其是 AI 编辑——是否真实满足用户诉求。传入起始版本（编辑前基线），可选结束版本（省略取最新），版本差上限 20；返回里最外层带当前表格最新版本号。当用户需要"看看这次改了什么"、"核对 AI 改动"、"对比两个版本的变更"时使用。 |
 
 ## 公共 flag 速查
 

skills/lark-sheets/references/lark-sheets-batch-update.md

@@ -8,6 +8,8 @@
 2. **批次完成后必须回读校验**：整个 `+batch-update` 执行成功后，用 `+csv-get` 或 `+cells-get` 抽样回读受影响区域，至少校验 3-5 个代表性单元格（首 / 中 / 末），与本地脚本预先计算的预期值对照。
 3. **预期条数前置断言**：涉及"批量填充 N 行"或"对 M 个区域分别写入"时，先把 N、M 硬编码进代码，回读后断言实际等于预期；不一致就再发一轮 `+batch-update` 补齐，禁止交付半成品。
 
+若本次 `+batch-update` 的任一子操作写入了公式、复制了公式模板、或导入了含公式的数据块，**回读校验之后还必须继续执行 `+formula-verify`**。`+batch-update` 的原子提交只保证“写入动作都执行了”，不保证整批公式运行结果 zero-error。
+
 ## 使用场景
 
 写入。批量执行多个写入工具操作。将多个工具调用合并为一次请求，按顺序依次执行。适合需要连续执行多个写入操作的场景（如先修改结构再写入数据）。注意：不支持嵌套 `+batch-update`。
@@ -22,6 +24,11 @@
 
 当同一工具需要对多个区域重复调用时，**必须**改用 `+batch-update` 合并为单次请求——`+batch-update` 是原子提交（要么全成功要么整批回滚）；逐个调用非原子，中途失败会留下半成品。
 
+**公式相关批处理的默认闭环**：
+- 写前：先读 `lark-sheets-formula-translation`，把公式改写成飞书可执行语义。
+- 写时：用 `+batch-update` 一次性完成插行/写公式/复制模板等原子动作。
+- 写后：抽样回读之外，继续跑 `lark-sheets-formula-verify`，直到 `+formula-verify` 返回 `status='success'`。
+
 **`+dropdown-update` 的选项模式（`--options` / `--source-range` 二选一）+ 配色规则**（`--colors` 长度可短不能长、必须配 `--highlight=true` 才生效、不传按内置 10 色色板循环补色）见 [`lark-sheets-write-cells`](./lark-sheets-write-cells.md) 的「Dropdown 选项 + 配色」节，本文不重复。`+dropdown-delete` 不涉及这些 flag。
 
 ## Shortcuts
@@ -51,9 +58,10 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组，每项必须带 sheet 前缀（如 `["'Sheet1'!A1:B2","'Sheet2'!D1:D10"]`）；前缀必须是 sheet 显示名（如 `Sheet1`），不接受 sheet reference_id；支持跨 sheet；所有 range 应用同一组 style |
+| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组，每项必须带 sheet 前缀（如 `["Sheet1!A1:B2","Sheet2!D1:D10"]`，前缀裸写不加引号）；前缀必须与 sheet 真实显示名完全一致（含大小写），不接受 sheet reference_id；支持跨 sheet；所有 range 应用同一组 style |
 | `--background-color` | string | optional | 背景颜色（十六进制，如 `#ffffff`） |
 | `--font-color` | string | optional | 字体颜色（十六进制，如 `#000000`） |
+| `--font-family` | string | optional | 字体名称（如 `Arial`、`微软雅黑`） |
 | `--font-size` | float64 | optional | 字体大小（px，例：10、12、14） |
 | `--font-style` | string | optional | 字体样式（可选值：`normal` / `italic`） |
 | `--font-weight` | string | optional | 字重（可选值：`normal` / `bold`） |
@@ -70,7 +78,7 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["'Sheet1'!A2:A100","'Sheet1'!C2:C100"]`），每项必须带 sheet 前缀；前缀必须是 sheet 显示名（如 `Sheet1`），不接受 sheet reference_id |
+| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["Sheet1!A2:A100","Sheet1!C2:C100"]`，前缀裸写不加引号），每项必须带 sheet 前缀；前缀必须与 sheet 真实显示名完全一致（含大小写），不接受 sheet reference_id |
 | `--options` | string + File + Stdin（复合 JSON） | xor | 下拉选项 JSON 数组，例如 `["opt1","opt2"]`。服务端不限制选项数量，也不限制单个选项长度；含逗号的选项可以接受（写入时会自动转义）。大量选项建议改用 `--source-range`。 |
 | `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉胶囊背景色，RGB hex 数组（如 `["#1FB6C1","#F006C2"]`）。长度可短不可长——超长 Validate 拦截（`--colors length (N) must not exceed dropdown source size (M)`），未指定项按内置 10 色色板循环补色。**单独传即生效**；`--highlight=false` 时被忽略。 |
 | `--multiple` | bool | optional | 启用多选 |
@@ -83,7 +91,7 @@ _公共：URL/token（无 sheet 定位） · 系统：`--yes`、`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（最多 100 个，如 `["'Sheet1'!E2:E6"]`），每项必须带 sheet 前缀；前缀必须是 sheet 显示名（如 `Sheet1`），不接受 sheet reference_id |
+| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（最多 100 个，如 `["Sheet1!E2:E6"]`，前缀裸写不加引号），每项必须带 sheet 前缀；前缀必须与 sheet 真实显示名完全一致（含大小写），不接受 sheet reference_id |
 
 ### `+cells-batch-clear`
 
@@ -91,7 +99,7 @@ _公共：URL/token（无 sheet 定位） · 系统：`--yes`、`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组，每项必须带 sheet 前缀（如 `["'Sheet1'!A2:Z1000","'Sheet2'!A2:Z1000"]`）；前缀必须是 sheet 显示名（如 `Sheet1`），不接受 sheet reference_id；支持跨 sheet；对所有 range 执行同一 scope 的清除 |
+| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组，每项必须带 sheet 前缀（如 `["Sheet1!A2:Z1000","Sheet2!A2:Z1000"]`，前缀裸写不加引号）；前缀必须与 sheet 真实显示名完全一致（含大小写），不接受 sheet reference_id；支持跨 sheet；对所有 range 执行同一 scope 的清除 |
 | `--scope` | string | optional | 清除范围 enum：`content`（默认，仅清内容）/ `formats`（仅清格式）/ `all`（清内容 + 格式）（可选值：`content` / `formats` / `all`） |
 
 ## Schemas
@@ -137,7 +145,7 @@ lark-cli sheets +batch-update --url "https://example.feishu.cn/sheets/shtXXX" --
 
 # ops.json （array<{shortcut, input}>，shortcut 用 CLI 名）:
 # [
-#   {"shortcut": "+dim-insert", "input": {"sheet_id":"...","dimension":"row","start":10,"end":12}},
+#   {"shortcut": "+dim-insert", "input": {"sheet_id":"...","position":10,"count":3}},
 #   {"shortcut": "+cells-set",  "input": {"sheet_id":"...","range":"A11:B12","cells":[[{"value":"a"},{"value":"b"}],[{"value":"c"},{"value":"d"}]]}}
 # ]
 ```
@@ -145,7 +153,7 @@ lark-cli sheets +batch-update --url "https://example.feishu.cn/sheets/shtXXX" --
 > ⚠️ **子操作定位规则**：
 > - spreadsheet 定位（`--url` / `--spreadsheet-token`）**只在顶层给一次**；`+batch-update` 顶层**没有** `--sheet-id` / `--sheet-name`，在顶层传不生效。
 > - **每个子操作的子表定位 `sheet_id`（或 `sheet_name`）写进它自己的 `input`**（见上方 ops.json 每个 item）。
-> - `input` 的键是该 shortcut 的 flag **展平**成 JSON（`"range":"A11:B12"`、`"dimension":"row"`），不要把整组 `--operations` 再套一层嵌套 JSON。
+> - `input` 的键是该 shortcut 的 flag **展平**成 JSON（`"range":"A11:B12"`、`"position":11`），不要把整组 `--operations` 再套一层嵌套 JSON。
 
 > **常见组合：插列 + 写表头 + 整列回填**——一次原子提交，不要拆成 N 次独立调用。批量回填同一列 **只需一次** `+cells-set`（range 写整列范围、cells 写 N×1 矩阵），不需要逐行循环。
 >
@@ -153,9 +161,9 @@ lark-cli sheets +batch-update --url "https://example.feishu.cn/sheets/shtXXX" --
 > // 在 C 列前插入新列 → 写表头 C1 → 回填 C2:C100 共 99 行
 > [
 >   {"shortcut": "+dim-insert",
->    "input": {"sheet_id": "...", "dimension": "column", "start": 3, "end": 4}},
+>    "input": {"sheet_name": "Sheet1", "position": "C", "count": 1}},
 >   {"shortcut": "+cells-set",
->    "input": {"sheet_id": "...", "range": "C1:C100",
+>    "input": {"sheet_name": "Sheet1", "range": "C1:C100",
 >              "cells": [[{"value":"score"}], [{"value":95}], [{"value":87}], /* ... 97 more rows ... */ ]}}
 > ]
 > ```

skills/lark-sheets/references/lark-sheets-changeset.md

@@ -0,0 +1,105 @@
+# Lark Sheet Changeset
+
+## 使用场景
+
+读取两个版本之间的 **changeset（变更操作清单）**，用于**复核某次编辑（尤其是 AI 编辑）是否真实满足用户诉求**。
+
+典型场景：AI agent 对表格做了一批编辑后，想确认它"说做的"和"真正落到表格上的"是否一致——拉取编辑前版本到编辑后版本之间的 changeset，逐条核对 action 是否覆盖了用户要求的修改、有没有多改 / 漏改。
+
+## 版本（revision）语义
+
+- 这里的"版本"指表格的 **CS revision**（每次提交单调递增的修订号），不是文档历史里的命名版本。
+- `--start-revision` 是复核基线，即你认定的"编辑前"版本。
+- `--end-revision` 是"编辑后"版本；**省略时默认取最新 revision**，返回从 start 到最新的全部 changeset。
+- **版本差上限 20**：`end - start + 1 ≤ 20`，超出会被拒绝（服务端同样以 20 兜底）。复核大跨度变更时请分段拉取。
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+changeset-get` | read | 变更记录 |
+
+## Flags
+
+### `+changeset-get`
+
+_公共：URL/token（无 sheet 定位）_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--start-revision` | int | required | 起始版本（编辑前基线，>= 1） |
+| `--end-revision` | int | optional | 结束版本（省略取最新） |
+
+## 返回结构
+
+返回一个 JSON 对象，`changesets` 数组按版本顺序排列，每个元素是一次提交的**原始 action 列表**与元信息：
+
+```json
+{
+  "spreadsheet_token": "shtcnXXXX",
+  "latest_revision": 142,
+  "start_revision": 120,
+  "end_revision": 135,
+  "changesets": [
+    {
+      "revision": 121,
+      "create_time": "2026-06-12T10:00:00Z",
+      "actions": [
+        { "action": "setCellRange", "sheetId": "...", "value": { /* ... */ } }
+      ],
+      "is_self_edit": false,
+      "is_ai_edit": true
+    }
+  ]
+}
+```
+
+- 最外层 `latest_revision` 是**当前表格的最新版本号**（与查询区间无关），便于判断表格当前停在哪个版本、`--start-revision` 该取多少。
+- `actions` 是**未经语义渲染的原始操作对象**，按提交内的执行顺序排列。复核时逐条比对：每个 action 改了哪个 sheet、哪个区域、改成什么，是否对应用户的诉求。
+- `revision` / `create_time` 用于判断"这次改动属于哪个版本、什么时候做的"。
+- `is_self_edit` 表示该 changeset 是否由当前请求用户提交（committer 与请求用户相同），即"是不是我自己提交的编辑"。
+- `is_ai_edit` 表示该 changeset 是否由 AI 客户端提交（`member_id` 为 10 / 11）。复核时 `is_ai_edit=true` 即为 AI 写入的编辑（而非用户手动编辑），是核对 AI 是否完成诉求的主要对象。
+
+## 复核工作流（判断 AI 是否真实完成诉求）
+
+1. 记下 AI 开始编辑前的 revision（编辑前 `+workbook-info` 或上一次工具返回的 revision 即可作为 `--start-revision`）。
+2. AI 编辑完成后，跑 `+changeset-get --url <表格> --start-revision <编辑前版本>`（不传 end → 取到最新）。
+3. 遍历 `changesets[].actions`，核对：
+   - 用户要求的每一处修改是否都有对应 action；
+   - 有没有越权 / 多余的修改（动了用户没让动的 sheet / 区域）；
+   - action 的目标区域、值是否与诉求一致。
+4. 若版本跨度可能 > 20，分段拉取（如 `start..start+19`、`start+20..` …）。
+
+## 注意
+
+- `+changeset-get` 是**只读**操作，不改动表格。
+- 大跨度 / 大批量编辑的 changeset 可能体积较大；输出在传输层已 gzip。必要时缩小版本区间。
+- 该工具走只读 scope `sheets:spreadsheet:read`，需要对表格有查看权限。
+
+## Examples
+
+### `+changeset-get`
+
+公共：`--url` / `--spreadsheet-token`（二选一，无 sheet 定位）。changeset 是工作簿级历史，不接受 sheet 定位 flag。
+
+示例：
+
+```bash
+# 只传起始版本 → 返回从该版本到最新的全部 changeset（最常用：复核 AI 编辑前后的差异）
+lark-cli sheets +changeset-get --url "https://example.feishu.cn/sheets/shtXXX" --start-revision 120
+
+# 传起始 + 结束版本（版本差 end-start+1 ≤ 20）
+lark-cli sheets +changeset-get --spreadsheet-token shtXXX --start-revision 120 --end-revision 135
+```
+
+输出契约（envelope.data）：
+
+- `latest_revision` — 当前表格最新版本号（与查询区间无关）
+- `start_revision` / `end_revision` — 实际查询区间（省略 `--end-revision` 时 `end_revision` = 最新版本）
+- `changesets[]` — 按版本顺序排列；每项含 `revision` / `create_time` / `actions`（原始操作列表）/ `is_self_edit` / `is_ai_edit`
+
+### Validate / DryRun / Execute 约束
+
+- `Validate` 阶段只做 XOR 检查（`--url` / `--spreadsheet-token` 二选一）与版本上限校验（`--start-revision ≥ 1`，传了 `--end-revision` 时 `end ≥ start` 且 `end - start + 1 ≤ 20`）；**禁止**联网。
+- `DryRun` 输出请求模板，不实际拉取 changeset。
+- `Execute` 阶段才发起 changeset 查询；省略 `--end-revision` 时由服务端解析为最新 revision。

skills/lark-sheets/references/lark-sheets-chart.md

@@ -31,7 +31,9 @@
 
 **常见配置错误（必须注意）**：
 - **图表类型选择错误**：用户说"堆积柱形图/百分比堆积"时，应在 `properties.snapshot.plotArea.plot.extra.stack` 中配置堆叠；百分比堆叠需在该 stack 下设置 `percentage: true`。用户说"占比/比例"时，优先考虑饼图或百分比堆积图。注意区分 `column`（柱形图，纵向）与 `bar`（条形图，横向）是两个不同的 type 取值，"对比/各 XX" 类纵向柱默认用 `column`
-- **数据标签缺失**：用户需要看到具体数值时，需配置 `properties.snapshot.plotArea.plot.labels`（数据标签）相关字段
+- **数据标签开关**：`plotArea.plot.labels` 对象的**存在性即开关**——
+  - 用户需要看到具体数值/类别时：传入 `labels` 并配置 `value` / `category` / `series` / `percentage` 等显示位。
+  - 用户明确说"不要数据标签 / 关掉标签"时：**整个 `labels` 字段省略**。不要用 `labels: { value: false, category: false, series: false }` 这种"全部置 false"的写法关闭——只要传了 `labels`，系统就会显示数据标签（且默认兜底显示 value）。
 - **数据源范围与系列名来源要对齐**：
   - **默认情况（inline 模式）**：`refs` 范围**应包含表头行**（首行/首列即系列名），且范围要精确覆盖目标数据，不要多选或少选。
   - **合并标题行要跳过**：如果表格在表头上方存在合并的标题行（如"员工统计表"横跨多列的大标题），`refs` 必须跳过标题行、从真正的列标题行开始。例如表头在第 3 行、数据在第 4-20 行，则 `refs` 应为 `A3:G20` 而非 `A1:G20`。包含合并标题行会导致列名识别错误、表头被当作数据参与聚合计算。
@@ -122,7 +124,7 @@ _公共四件套 · 系统：`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--properties` | string + File + Stdin（复合 JSON） | required | 图表完整配置 JSON。顶层字段为 `position` / `offset` / `size` / `snapshot`（无顶层 `data`，也无再嵌一层 `properties`）；图表数据配置在 `snapshot.data` 下（含 `refs` / `headerMode` / `dim1` / `dim2`）。结构嵌套深，完整结构跑 `--print-schema --flag-name properties` |
+| `--properties` | string + File + Stdin（复合 JSON） | required | 图表完整配置 JSON。顶层字段为 `position` / `offset` / `size` / `snapshot`（无顶层 `data`，也无再嵌一层 `properties`）；图表数据配置在 `snapshot.data` 下（含 `refs` / `headerMode` / `dim1` / `dim2`）；必须至少含 `snapshot.data.dim1.serie.index` 或 `dim2.series[].index` 之一，否则 server 拒。结构嵌套深，完整结构跑 `--print-schema --flag-name properties` |
 
 ### `+chart-update`
 

skills/lark-sheets/references/lark-sheets-conditional-format.md

@@ -43,6 +43,8 @@
 
 **正确做法（两步走）**：
 
+Step 1 的 `+cells-set` 及 `--copy-to-range` 等 flag 以 `lark-sheets-write-cells` 为准。
+
 ```
 Step 1: `+cells-set` 在新列写判断公式（形成"是/否"或布尔辅助列）
   range="H2", cells=[[{formula: "=IF(A2>B2, \"是\", \"否\")"}]], --copy-to-range="H2:H100"

skills/lark-sheets/references/lark-sheets-core-operations.md

@@ -1,103 +0,0 @@
-# 飞书表格核心操作：分析、编辑与可视化
-
-## 概览
-
-面向"已有飞书表格"的核心工作流，核心原则：**先了解，再分析或写入，最后验证**。本文是方法论总纲；具体工具的参数细节、边界陷阱在对应 reference，本文用指针引到那里，不重复展开。
-
-**三份「通用方法与规范」如何分工**（都不含 shortcut，按主题单一归属）：
-
-- **本文（core-operations）= 流程与铁律**：端到端工作流 + 全局铁律 + 横切陷阱，是读取入口与枢纽。
-- **`lark-sheets-visual-standards` = 样式知识**：配色 / 表头 / 数值格式 / 斑马纹 / 美化决策等"正确视觉输出"的全部标准。
-- **`lark-sheets-formula-translation` = 公式知识**：飞书公式书写与 Excel 迁移的全部正确性规则（绝对引用、范围语法、数组语义、不支持函数等）。
-
-> **下面的铁律对所有任务一律生效**，即使你是被索引直接路由进 visual 或 formula 而没经过本文——编辑类任务务必先回到这里过一遍铁律。
-
-## 铁律（所有编辑类任务必须满足，各 reference 不得放宽）
-
-1. **最小改动**：除用户明示要改的单元格 / 列外，原表其它单元格、行列结构、Sheet 名、合并区、格式必须 1:1 保持。中间结果优先放原数据**右侧**；会与原数据混淆或要承载透视表 / 图表时才**新建空白 Sheet**。**禁止**擅自删 / 改名 / 隐藏 / 移动**已存在**的 Sheet（新建允许，节制使用）。**改写 / 转换类任务要精确圈定适用行列**：只对任务真正要求的对象做变换，**不该转的行 / 列保持原值 1:1**（典型反例：要求"统一翻译"时把本就是中文、应原样保留的评论也重新翻译；要求"改写某列格式"时连原始测量值也一并改动 → 应保留的原文被篡改）。
-2. **真实写回 + 回读校验**：交付必须是对在线表格的真实写入，并 `+csv-get` / `+cells-get` / `+<对象>-list` 回读校验。**严禁**只在文本里描述"已完成"、用普通公式 / 文本假装结构化对象、或只给占位而无真实写入。**收尾前必须确认产物文件真实存在 / 可导出**——别在没真正生成产物时只凭文本"已完成"就结束（反例：文本称已完成，实际没生成产物文件，等于没交付）。
-3. **读全再写，禁止只探前 N 行**：批量填充 / 补齐 / 修正类任务必须先确认**真实数据末行**再写，否则会漏写表尾。完整的"按表格形态分流读取 + `current_region` / `has_more` 兜底 + 真实末行确认"流程见 `lark-sheets-read-data` 的「确定数据范围的正确流程」。
-4. **公式优先于硬编码**：能用飞书公式表达的计算（总计 / 占比 / 增长率 / 提取 / 查找等）一律写公式而非静态值，源数据变化才能自动重算。用户口头的"分列 / 排序 / 求和 / 提取"也要落地为公式或原生工具（SORT / `TEXTBEFORE` / `MID` / 透视表 等）。Excel 公式迁移、数组语义、不支持函数清单一律以 `lark-sheets-formula-translation` 为唯一权威。**即使用户没说"联动 / 自动更新"，凡是可由表内其它单元格推导的派生值（年龄=当年-出生年、占比=本类数/总数、达标=阈值判断、排名、各类分组汇总）默认就必须用公式**——用户默认期望派生列能随源数据重算，**离线 Python / 脚本算完写静态值，即便当前数值正确，改了源数据也不会自动更新，等于没满足"派生"的本意**（反例：年龄、月度汇总、占比、分组求和等派生列写死值，源数据一改结果就过时）。
-5. **续写 / 扩展必须继承样式**：续写、补齐、复制区块、新增行列时，**禁止**只读值只写值。必须连带 `cell_styles` + `border_styles` + 合并 + 行高一起继承。完整继承清单与做法见 `lark-sheets-write-cells` 的「新增列 / 新增行的样式继承」（`border_styles` 四边最易漏）。
-6. **多步写入优先 `+batch-update`**：多个连续写入、或同一工具对多个区域重复调用（多次 merge / resize / cells-set），必须合并为单次原子 `+batch-update`。语义与不可嵌套的限制见 `lark-sheets-batch-update`。
-7. **分组汇总必须用透视表**："按 X 统计 Y / 分组汇总 / 各部门数量金额"必须用 `+pivot-{create|update|delete}`（推荐省略 sheet_id 自动新建子表），**禁止**用 SUMIF / COUNTIF 或本地脚本覆盖原表替代。
-8. **任务拆成可验证 checklist**：落地前把指令拆成所有"独立可验证子要点"，每点一个 `assert`，全部通过才交付：多维度操作（按部门一/二/三级排序）每维一个 assert；多目标（删 N 行）每目标一个；多格式兼容（多种日期格式）每种至少一个样本；范围类（A1:H11 加边框）起 / 末行 / 末列三边界都核。只完成第一个要点（只排一级、只删 1 行）属违规。**题面 / 表头里写明的格式规范也是子要点**：表头注明"需标注某字段"就必须给对应单元格加规定前缀并逐条 assert 前缀存在（反例：漏加规定前缀，该要点即不达标）；"相同编号连续行合并"必须遍历所有相同编号组全部合并（反例：只合并了其中一部分组）。
-9. **全量处理要前置断言条数**：翻译 / 打标 / 批量公式落地等逐条任务，落地前把"预期处理条数"硬编码进代码，处理完 `assert actual == expected`。**严禁**输出"已完成前 N 条，剩余将继续"的半成品。
-
-## 推荐工作流程
-
-1. **规划 reference 清单**：开工前一次性列出本任务要读的 reference（避免读一个调一个），本轮已读过的不重复读。本文 + `lark-sheets-workbook` 几乎每次都要。
-2. **了解结构**：先 `+workbook-info` 拿子表列表 / 行列数 / 冻结位置（不可猜测，猜错会越界覆盖）；涉及合并 / 隐藏 / 分组 / 行高列宽再用 `lark-sheets-sheet-structure` 的 `+sheet-info`。
-3. **读取数据（按任务类型选路径，细则见 `lark-sheets-read-data`）**：
-
-   | 用户需求语义 | 路径 |
-   |---|---|
-   | "完善 / 补齐 / 填空 / 修正所有 XX" / 数据分析 / 清洗 / 大数据集 | **A：原生优先**（公式 / `+pivot` / `+filter`，见第 5 步）；原生表达不了或更复杂时**分批 `+csv-get` 导出 + 本地脚本处理 + 分批回写**（默认覆盖所有对应数据行，不以用户选区为准；脚本与 CLI 配合见下方「CLI 配合要点」） |
-   | "查一下 / 看看 / 统计 / 汇总" 等只读 | B：`+csv-get` 读到上下文 |
-   | 需要公式 / 样式 / 批注 | C：`+cells-get` |
-   | 续写 / 扩展 / 完善已有内容 | D：`+csv-get` 看结构 + `+cells-get` 读源区样式 + `+sheet-info --include row_heights,merges`（见铁律 5） |
-
-   **注意**：对"完善 / 补齐 / 填空"类任务用路径 B 探 10 行就写入，实测会漏写表尾多行。写入前必须按 `lark-sheets-read-data`「确定数据范围的正确流程」确认真实数据末行。按关键字定位区域用 `lark-sheets-search-replace` 的 `+cells-search`。
-
-4. **理解数据语义（写入前必做）**：读表头 + 3-5 行样本确认各列含义与格式（文本 / 数字 / 日期 / 混合）；写公式前先分析样本值格式模式再选提取策略；建透视表前先列清"行字段=分组维度、值字段=聚合指标"。需求模糊时（如"加入加减乘除"未说逻辑）基于表头与已有公式推断，不确定就问用户，禁止臆造业务逻辑。
-
-5. **分析与计算（原生工具优先，代码兜底）**：飞书原生能力能随数据自动更新，**必须优先**：
-
-   | 用户需求 | 必须用的原生工具 | 禁止用代码替代 |
-   |---|---|---|
-   | 按 X 统计 Y、分组汇总 | `+pivot-{create\|update\|delete}` | pandas groupby → `+cells-set` |
-   | 求和 / 计数 / 平均 / 占比 | 公式（SUM/COUNT/AVERAGE） | Python 算 → 写静态值 |
-   | 画图表 / 可视化 | `+chart-{create\|update\|delete}` | matplotlib 画图 |
-   | 条件高亮 / 色阶 | `+cond-format-{create\|update\|delete}` | 逐单元格设样式 |
-   | 数据筛选 | `+filter-{create\|update\|delete}` | pandas filter → 覆盖写入 |
-   | 文本提取 / 转换 | 公式（REGEXEXTRACT/TEXT/VALUE） | Python 正则 → 写静态值 |
-   | 查找匹配 | 公式（VLOOKUP/INDEX+MATCH） | pandas merge → 写静态值 |
-
-   **只有以下才用代码**：多步清洗流水线、统计建模、公式试错 3 次仍失败的降级。代码结果回写：大块纯值用 `+csv-put`（+ `--start-cell`，必要时自动扩容）；少量或需公式 / 样式用 `+cells-set`；能用飞书公式表达的写飞书公式。
-
-6. **写入与修改（细节见 `lark-sheets-write-cells`）**：`+cells-set` 的 `range` 必须落在已有行列范围内、`cells` 二维数组与 `range` 严格同维；表尾追加先用 `+dim-insert` 插行列再写；整列 / 整行同结构的值 / 公式 / 格式用模板单元格 + `--copy-to-range`，禁止逐行 `+cells-set`；多步写入合并为 `+batch-update`；改尺寸先读相邻可见行列当前尺寸再决定 `pixel` / `standard` / `auto`，不要猜数值。
-
-7. **验证**：重新读取受影响区域确认值 / 公式 / 样式 / 批注符合预期；对象类（图表 / 透视表 / 条件格式 / 筛选 / 迷你图 / 浮动图片）重新读对象配置确认；出错先定位错误类型 / 受影响区域 / 根因再修复重验。
-
-## 用本地代码 / 脚本时的 CLI 配合要点
-
-复杂处理——多步清洗、统计建模、批量转换、语义任务的分批编排等——用代码（`python` / `node` 等）解决是完全正当的。原生能力（公式 / `+pivot` / `+filter`）能表达就优先用（可随源数据自动重算）；原生表达不了或逻辑更复杂时，放手用代码。下面几条让脚本与 CLI 顺畅配合：
-
-- **解析输出时只读 stdout**：CLI 把数据 JSON 写到 stdout、把诊断与警告写到 stderr。解析 JSON 时**不要合并这两条流**（即不要 `2>&1`），否则警告行混进 JSON 会让解析失败。用管道（`lark-cli … | jq …`）或先把 stdout 单独重定向到文件再读；需要诊断信息时把 stderr 另导到一个文件。
-- **喂给 CLI 的 CSV / JSON 用 UTF-8、不带 BOM**：BOM 会污染首格的值或触发 `invalid character` 解析错；脚本读写文件时显式指定 `encoding='utf-8'`。
-- **临时文件交给运行时的标准库**：用 `tempfile.gettempdir()` / `os.tmpdir()` 等取临时目录，不要硬编码固定路径；放在用户项目目录之外。
-- **命令失败先读错误再调整**：同一条命令失败后不要原样重发；先看 stderr 的报错（参数错误、缺依赖、解释器不可用等）定位原因，再决定换写法、补依赖或退回原生工具。
-- **写回的必须是纯单元格值，禁止把"值+样式标注"串当值写回**：本地脚本或某些 xlsx 解析库会把单元格渲染成 `甲方支行(V-Align: bottom)` 这种"值(样式)"字符串，CSV 字段还可能带包裹双引号。回写前必须**剥离括号样式标注、去掉残留引号**，只写原始值——否则样式描述会变成单元格的字面文本污染原数据（反例：排序后单元格值里被写进 `(V-Align: bottom)` 这类样式后缀文本，末尾还多一个双引号）。**排序本身优先用 `+range-sort` 原生工具**，不要"读出来本地排完再整列写回"，从根上避免这类回写污染。
-
-## 公式策略
-
-- **公式优先于硬编码**（同铁律 4）：能用公式表达的计算一律写公式，源数据变化才能自动重算。
-- **写任何公式前先读 `lark-sheets-formula-translation`**：它是公式正确性的唯一权威，覆盖绝对引用（`$`）、飞书范围语法（`H:H` 与工具 A1 表示法的区别）、ARRAYFORMULA / 数组语义、Excel 迁移、不支持函数清单等全部规则。本文不再单列这些细则。
-
-## 常见陷阱（铁律已覆盖的不再重复，仅列易漏点）
-
-- **合并单元格**：合并区只有左上角存数据，其余读为空是正常行为；写入只能写左上角，写其它位置会报 `cell ... is inside a merged region`。改合并区先取消再操作。安全操作 5 条与"批量取消用大 range 一次调用"见 `lark-sheets-range-operations`。
-- **`+dim-insert` 不继承行高**：`--inherit-style before/after` 只继承值 / 公式 / 边框，不继承 `row_height`，新行会回落默认高度截断长文本；中间插行填文本前先读相邻行 `row_height`，用 `+batch-update` 合 `+rows-resize` 补齐。
-- **公式容错**：日期 / 查找 / 数值转换公式用 `IFERROR` 包裹；写完读结果列首 5 + 末 5 行查 `#VALUE!` / `#NAME?` / `#REF!` / `#DIV/0!`；同一方案试错上限 3 次，超了改代码以值写入。
-- **循环引用**：聚合公式（SUM/AVERAGE）引用范围不能含目标 cell 自身或其传递依赖。
-- **NaN / 空值 / 除零**：空值不直接参与运算；除法用 `IF` / `IFERROR` 防零。
-- **排序 / 筛选混合文本列**：带货币符 / 单位 / 表达式的文本列直接排序 / 筛选会按字典序出错，先抽数值到辅助列再处理（细则见 `lark-sheets-range-operations` / `lark-sheets-filter`）。
-- **隐藏行列**：`+csv-get` 默认 `--skip-hidden=false`（含隐藏行列）；设 `true` 只看可见数据，但返回行序号与实际行号不再对应。
-- **行号一律取 `[row=N]` 前缀**：`+csv-get` 的 CSV 中双引号内换行是单元格内换行不是新行；禁止数 `\n`、禁止用"序号列"当行号（细则见 `lark-sheets-read-data`）。
-- **列字母取 `col_indices[j]`**：禁止手数表头逗号定位列（>10 列极易 off-by-one）。
-- **跨 sheet 对象**：图表 / 条件格式 / 透视表 / 浮动图片可能分布在多个子表，操作前先 `+workbook-info` 掌握全局。
-- **`+cells-search` 不是万能**：用户说"汇总金额"是操作动作（求和），不是搜索该文本；只在确需定位某文本位置时才用。
-
-## 特殊场景
-
-### 续写 / 复制已有区块格式
-
-核心要求见铁律 5。机制（带齐哪些样式字段、怎么采样写入）见 `lark-sheets-write-cells` 的「新增列 / 新增行的样式继承」；样式标准（斑马纹奇偶 / 配色 / 边框层级）见 `lark-sheets-visual-standards` 场景二。本文不再展开。
-
-### NLP 任务处理
-
-任务涉及语义理解、翻译、改写、摘要、分类、抽取、多行聚合时，以 NLP 方式处理，不要用纯规则代码替代语义理解（但可用代码做分批、行号映射、结果拼装与写回）。数据量大时**必须**分批（通常 30 行一批），每批处理完立即写回，不要全处理完再一次写入；单批生成通常不超 300 行，超出时按性质抽样或分批并向用户说明范围；多批写入优先用 `+batch-update` 合并为原子提交。
-
-### 格式处理优先公式
-
-"去除多余零 / 提取数字 / 文本格式转换 / 日期格式化"等清洗，**必须优先用公式**（`SUBSTITUTE` / `TEXT` / `VALUE` / `LEFT` / `RIGHT` / `MID` 等）：写一个模板 + `--copy-to-range` 即可整列处理，远比逐行修改高效。

skills/lark-sheets/references/lark-sheets-filter-view.md

@@ -50,7 +50,7 @@ _公共四件套 · 系统：`--dry-run`_
 | --- | --- | --- | --- |
 | `--properties` | string + File + Stdin（复合 JSON） | required | 筛选视图规则 JSON，含 `rules?`（列级筛选规则数组）和 `filtered_columns?`。`range` 和 `view_name` 是独立 flag |
 | `--range` | string | required | 筛选视图作用的单元格范围（A1 表示法，如 `A1:F1000`）；优先级高于 `--properties` 中同名字段；create 必填，必须覆盖表头行 |
-| `--view-name` | string | optional | 筛选视图名称；create 不传时系统自动分配，update 不传时保留原名；优先级高于 `--properties` 中同名字段 |
+| `--view-name` | string | optional | 筛选视图名称；不传时系统自动分配；优先级高于 `--properties` 中同名字段 |
 
 ### `+filter-view-update`
 

skills/lark-sheets/references/lark-sheets-float-image.md

@@ -29,9 +29,9 @@
 
 - **`--image <本地路径>`（首选，最省事）**：直接给本地图片文件路径（PNG/JPEG/GIF/BMP/HEIC 等）。CLI 会自动把它以 `parent_type=sheet_image` 上传，拿到 file_token 后创建浮动图，**不用你手动上传 / 取 token**。路径规则同其它本地文件 flag：必须是当前工作目录内的相对路径（绝对路径会被 Validate 拒，`--dry-run` 也会拦）。
 - `--image-token`：复用**已存在**的图片 file_token。常见来源：① `+float-image-list` 返回的 `image_token`（适合"换皮不换位置"复用同一张图）；② `+cells-set-image` 成功返回里的 `file_token`（它也是 `sheet_image` 上传句柄）。适合"同一张图复用到多处"，省去重复上传。
-- `--image-uri`：图片 reference_id（image URI），由系统自动转 file_token。
+- `--image-uri`：图片 URI（上传链路返回的句柄），**非**表内对象 reference_id；由系统自动转 file_token。
 
-> ⚠️ **`--image` 仅 `+float-image-create` 支持**。`+float-image-update` 换图仍只接受 `--image-token` / `--image-uri`，而且**图片源是 update 唯一可省的部分**——三者全不传则保留原图。但 `--image-name` / `--position-{row,col}` / `--size-{width,height}` 在 update 时和 create 一样**必填**（`+float-image-update` 强制要求这套核心字段，且 `+float-image-list` 不回传 `image_name` 供 CLI 回填）。要在 update 里换一张本地新图，先用 `+cells-set-image` 上传到任意临时单元格、从返回取 `file_token`，再把它传给 update 的 `--image-token`。
+> ⚠️ **`--image` 仅 `+float-image-create` 支持**。`+float-image-update` 换图仍只接受 `--image-token` / `--image-uri`，而且**图片源是 update 唯一可省的部分**——三者全不传则保留原图。但 `--image-name` / `--position-{row,col}` / `--size-{width,height}` 在 update 时和 create 一样**必填**（`+float-image-update` 强制要求这套核心字段，且 `+float-image-list` 不回传 `image_name` 供 CLI 回填）。要在 update 里换一张本地新图，先用 `+cells-set-image` 上传到任意临时单元格、从返回取 `file_token`，再把它传给 update 的 `--image-token`；用完清除该临时单元格，避免残留多余图片。
 
 ## Shortcuts
 
@@ -122,7 +122,7 @@ lark-cli sheets +float-image-create --url "..." --sheet-id "$SID" \
   --image-name "logo.png" --image-token "$TOKEN" \
   --position-row 0 --position-col A --size-width 200 --size-height 150
 
-# 用 reference_id（图片上传链路返回的 image reference_id；与 --image-token 二选一）
+# 用 image URI（上传链路返回的句柄，非表内对象 reference_id；与 --image-token 二选一）
 lark-cli sheets +float-image-create --url "..." --sheet-id "$SID" \
   --image-name "logo.png" --image-uri "$IMAGE_URI" \
   --position-row 2 --position-col B --size-width 300 --size-height 200 --z-index 1

skills/lark-sheets/references/lark-sheets-formula-translation.md

@@ -1,14 +1,14 @@
 # 飞书表格公式生成规则
 
 > **本文定位**：飞书公式正确性的**唯一权威**——书写任何飞书公式、或把 Excel 公式迁移到飞书前，先读本文。涵盖公式书写约定（绝对引用、范围语法）、投影 vs spill、ARRAYFORMULA / 数组语义、高风险引用函数、日期差、不支持函数清单。
-> **边界**：本文只讲"公式怎么写对"；公式**怎么写入表格**（`+cells-set` / 模板单元格 + `--copy-to-range` / 容错回读）见 `lark-sheets-write-cells` 与 `lark-sheets-core-operations`。本文不含 shortcut，铁律见 `lark-sheets-core-operations`。
+> **边界**：本文只讲"公式怎么写对"；公式**怎么写入表格**（`+cells-set` / 模板单元格 + `--copy-to-range` / 容错回读）见 `lark-sheets-write-cells`。**公式写入完成后的强制收尾**见 `lark-sheets-formula-verify`：不要把"翻译对了"误当成"已经交付完成"。本文不含 shortcut，通用编辑准则见主 SKILL.md「飞书表格编辑准则」。
 
 **核心原则：飞书不像 Excel 365 那样默认 spill（溢出展开）。飞书普通公式遇到区域时默认"投影"（只取当前行/列对应的单个值），必须显式使用 `ARRAYFORMULA` 或原生数组函数才能逐项展开。**
 
 ## 公式书写约定（写任何公式都先满足）
 
 - **绝对引用 `$`**：向下 / 向右填充前判断哪些引用要锁定——用户指定的固定 cell（`$C$3`）、要固定的数据范围（`$A$2:$B$5`）、锁列不锁行（`$A2`）、锁行不锁列（`B$1`）。填充前检查是否需固定汇率 / 税率 / 查找表 / 权重表，以及同列 / 同行公式结构是否一致。
-- **公式字符串用飞书范围语法**：写 `H:H`、`A2:B5`，**禁止** `H2:H` / `2:2`。这与 CLI 工具参数（如 `--range`）的 A1 表示法（`A1:D3`、`1:1`）写法不同，两者混淆会导致调用失败或公式报错。
+- **公式字符串用飞书范围语法**：写 `H:H`、`A2:B5`，**禁止** `H2:H` / `2:2`。要在公式里引用整行，用显式范围（如 `$A2:$Z2`）替代禁用的 `2:2`。这与 CLI 工具参数（如 `--range` / `--copy-to-range`）的 A1 表示法写法不同：参数侧合法的 `D3:D`、`1:1`、`3:6` 在公式串里反而非法。**公式串 ≠ CLI 参数**，两套规则别互相照搬，混用会导致调用失败或公式报错。
 
 ## 翻译后必做：代码复现校验
 
@@ -21,6 +21,14 @@
 
 **理由**：Excel→飞书的语法翻译很容易在 spill / 数组 / 日期差 / 范围引用上出现等价性偏差，仅靠语法转换通过不足以保证业务结果正确。
 
+## 落表后的默认交接
+
+本文解决的是"公式怎么写对"，不是"写进表里后一定能零错误运行"。因此：
+
+1. 按本文完成公式改写后，用 `lark-sheets-write-cells` / `lark-sheets-batch-update` 把公式真实写入表格。
+2. 公式一旦落表，就默认进入 `lark-sheets-formula-verify` 的收尾阶段。
+3. 最终必须跑 `+formula-verify` 收敛到 `status='success'`；`errors_found` / `partial` 都不算完成。
+
 ## 决策流程
 
 1. 最终结果是**标量**（单值）→ 通常不需要 `ARRAYFORMULA`
@@ -224,7 +232,7 @@ Excel：`{=A1:A10*B1:B10}`（Ctrl+Shift+Enter 输入）
 
 ## 飞书不支持的函数
 
-> 本段是"飞书不支持函数"的**唯一权威清单**（`lark-sheets-core-operations` 不再单列，统一指向这里）。以下函数在飞书里不存在或被禁用，禁止主动使用；用户明确要求时应拒绝并提供替代方案：
+> 本段是"飞书不支持函数"的**唯一权威清单**。以下函数在飞书里不存在或被禁用，禁止主动使用；用户明确要求时应拒绝并提供替代方案：
 
 - `STOCKHISTORY` — 实时股票数据，飞书无等价函数，需手动导入数据
 - `WEBSERVICE` — 外部 HTTP 请求，飞书无等价函数
@@ -234,6 +242,7 @@ Excel：`{=A1:A10*B1:B10}`（Ctrl+Shift+Enter 输入）
 - `INFO`、`RTD` — 系统信息 / 实时数据函数，飞书不支持
 - `PIVOT` — 用 `+pivot-{create|update|delete}` 透视表对象替代
 - `AMORDEGRC`、`PHONETIC`、`DETECTLANGUAGE` — 飞书不支持
+- `LET`、命名自定义函数（名称管理器里定义的 LAMBDA）、独立调用的 `LAMBDA`（如 `=LAMBDA(x,x+1)(5)`）— 会报 `#NAME?`；改用嵌套 IF / 辅助列。**例外**：`LAMBDA` 作为 `MAP` / `REDUCE` / `BYROW` / `BYCOL` / `SCAN` / `MAKEARRAY` 的内联参数时**支持**（见上方「飞书原生数组函数清单」）
 
 ## 代表性改写示例
 

skills/lark-sheets/references/lark-sheets-formula-verify.md

@@ -0,0 +1,77 @@
+# Lark Sheet Formula Verify（+formula-verify）
+
+> **本文定位**：飞书表格"公式写入后是否真的零错误"的自检入口，也是所有写公式任务的**强制收尾步骤**。公式的书写规则与 Excel→飞书迁移的语义规则一律以 `lark-sheets-formula-translation` 为唯一权威，本文不重复；本文聚焦"写完了之后怎么用一次调用确认 zero-error"。
+>
+> **边界**：本文不讲公式怎么写（去 `lark-sheets-formula-translation`），也不讲公式怎么写入表格（去 `lark-sheets-write-cells` / `lark-sheets-batch-update`）。本文只讲一件事：**只要任务里发生了公式落表、批量填充公式、`--copy-to-range` 扩展公式、导入含公式 workbook，收尾就必须用 `+formula-verify` 自检到 zero-error 才能交付**。
+
+## 为什么需要自检
+
+飞书在线表格已经实时算好结果，但"算出来"和"算对了"是两件事。常见缺口：
+
+- 公式编译失败 → 单元格落成文本（写入类 shortcut 返回的 `formula_errors[]` 是**编译失败**信号）。
+- 公式编译成功但**运行时错误**：`#REF!` / `#DIV/0!` / `#VALUE!` / `#NAME?` / `#NULL!` / `#NUM!` / `#N/A`——这一类只看 `formula_errors[]` 看不到，必须扫单元格值。
+
+`+formula-verify` 把两路信号合并成一份统一 JSON：一次调用聚合全表错误清单 + 编译失败清单 + 每类错误的定位与样本，AI 一眼就能定位修复，链路也能据 `status` 强制收敛到 `success`。
+
+## 调用契约
+
+最小调用形态：
+
+| 入参 | 含义 |
+|---|---|
+| `--url` / `--spreadsheet-token` | 表格定位（XOR 二选一，必填） |
+| `--sheet-id` / `--sheet-name` | 限定子表（mutually exclusive；省略则扫全部可见子表） |
+| `--range` | 限定 A1 范围；省略则用各 sheet 的 `current_region` |
+| `--max-locations` | 每类错误样本上限，默认 20 |
+| `--exit-on-error` | `status='errors_found'` 时返回非 0 退出码（CI 网关用） |
+
+返回核心字段：
+
+- `status` ∈ `success` / `errors_found` / `partial`——**唯一可机读的健康度判据**。
+- `total_errors` / `total_formulas` / `scanned_cells`——本次扫描规模指标。
+- `has_more`——为 true 表示扫描被内部上限截断（详见后文「截断与续读」），未覆盖完整范围。
+- `error_summary[<错误类型>]`——每类错误的 `count` / `locations[]` / `samples[].{address,formula,depends_on}`。
+- `compile_errors[]`——合并最近一次写入留下的编译失败清单，与运行时错误并存时同时出现。
+- `warning_message`——仅在 `has_more=true` 时出现，告知调用方需要缩小 `--range` / 拆 `--sheet-id` 续读。
+
+## 写入收尾收敛规则
+
+任何批量公式 / 含公式列写入完成后调用 `+formula-verify` 直到 `status='success'` 才能交付。不要等用户显式说"校验一下公式"才想到这里；**只要任务动作包含写公式，这一步默认就该做**。触发场景：
+
+- `+cells-set` / `+cells-csv-set`
+- `+cells-set --copy-to-range` / 模板单元格向整列或整块扩展公式
+- `+sandbox-import`
+- `+batch-update` 中含写入子操作
+- `+table-put`（任意列含公式时）
+- `+workbook-import`（导入的 xlsx 含公式时）
+
+收敛规则：
+
+1. `status='success'` → 通过；可以把链路标完成。
+2. `status='partial'` → 扫描被内部上限截断。先缩小 `--range` 或拆 `--sheet-id` 续扫，**不允许**把 `partial` 当作 `success`。
+3. `status='errors_found'` 且 `compile_errors[]` 非空 → **先解决编译失败**：根据 `compile_errors[].reason` 修正公式语法（飞书函数名 / 范围语法 / 引用样式），用 `+cells-set` 重写后再调一次 `+formula-verify`。
+4. `status='errors_found'` 且只剩运行时错误 → 按 `error_summary` 的 `samples[].formula` + `depends_on` 排查根因（零除？空值参与运算？引用越界？日期差写法？数组语义？），修复后重新自检。
+5. 同一处错误连续修复 3 次仍未通过 → 改用 `IFERROR` 包裹兜底，或退回纯值写入；不要在 `errors_found` 状态下扩展 `+cells-set --copy-to-range`、追加批量写入。
+
+注意：
+
+- 在 `status='errors_found'` 的状态下调用 `+cells-set --copy-to-range` 继续扩展会把错误复制放大。
+- "编译失败但运行时无报错"不是 zero-error（编译失败的单元格此刻是文本不是公式，源数据一变就再也算不出值）。
+- 跳过自检直接交付、靠肉眼读首末 5 行确认是不可靠的——表中段、隐藏行、合并区里的错误这样根本看不到。
+
+## 截断与续读
+
+后端有一个内部硬上限对总扫描单元格数做截断（不暴露给调用方），超过后立即返回 `has_more=true` + `warning_message`，`error_summary` / `compile_errors` 仅覆盖已扫描部分。处理路径：
+
+- 把工作簿按 `--sheet-id` / `--sheet-name` 拆成多次调用。
+- 同 sheet 内按 `--range` 切片（如先 `A1:Z200` 再 `AA1:AZ200`），逐块自检。
+- 每块都跑到 `has_more=false` 且 `status='success'` 才算通过。
+
+## 常见陷阱
+
+| 坑 | 应对 |
+|---|---|
+| 错误字符串本地化 | 后端按内部 `error_kind` / `compute_status` 字段识别错误类别，不走字符串匹配；调用方拿到的 7 类英文错误代码由后端统一规范输出，与 locale 无关。 |
+| `formatted_value` 可能隐藏错误 | 某些条件格式 / 自定义数字格式会把 `#DIV/0!` 显示成空白。后端直接读 cell `error_kind`，不依赖 `formatted_value`，绕开此类被遮蔽。 |
+| 把 `partial` 当 `success` | `partial` 仅表示**已扫描部分**无错误，剩余区域未知。必须续扫直到 `has_more=false` 且 `status='success'` 才能算通过。 |
+| 编译失败 vs 运行时错误 | 同一份报告里 `compile_errors[]` 与 `error_summary` 并存。语义层先解决 `compile_errors[]`、再做运行时自检。 |

skills/lark-sheets/references/lark-sheets-history.md

@@ -0,0 +1,124 @@
+# Lark Sheet History
+
+## 概念回顾
+
+每张飞书电子表格保留一串历史版本（`minor_histories`）。每个版本由 `history_version_id` 标识，并附带创建时间（`create_time`）、动作（`action`）与块修订信息（`all_block_revision`）。历史是**工作簿级**的（针对整张电子表格，不针对单个子表）。
+
+回滚（revert）把电子表格的当前内容覆盖回某个历史版本——这是一个**写入 / 不可逆**操作，且为**异步**：发起后立即返回受理标识，真正的回滚在后台进行，需通过状态查询轮询最终结果（进行中 / 成功 / 失败）。
+
+`+undo` 是另一类撤销：撤销当前 CLI 用户在该电子表格里最近一次或最近多次由 AI 工具产生、且尚未撤销的写入。每个用户有独立 undo 栈；多人编辑同一篇文档时，只撤当前用户自己的 undo 栈，不撤其他用户的操作。它和历史版本回滚不同，不需要选择 `history_version_id`，也不是把整表恢复到某个历史快照。
+
+`+history-list` 读取版本列表以挑选目标；`+history-revert` 发起回滚；`+history-revert-status` 轮询回滚结果；`+undo` 撤销当前用户最近的 AI 工具写入。若只是想拿**当前文档版本号（revision）**当作 recover / undo / `+changeset-get` 的起点锚点，直接用 `+revision-get` 更轻量。
+
+## 使用场景
+
+读取历史版本、发起回滚、查询回滚状态，或撤销当前用户最近一次 AI 工具写入。本 reference 覆盖 4 个 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看历史版本列表 | `+history-list` | 返回 `minor_histories`，每条含 `history_version_id` / `create_time` / `action` / `all_block_revision` 四个字段；支持向前分页（可选 `--end-version`） |
+| 回滚到指定历史版本 | `+history-revert` | 传入 `--history-version-id`；异步受理，返回可查询标识 |
+| 查询回滚状态 | `+history-revert-status` | 传入 `--transaction-id`（取自 `+history-revert` 的异步受理标识）；轮询某次回滚的进行中 / 成功 / 失败状态 |
+| 撤销自己最近的 AI 写入 | `+undo` | 只需 spreadsheet 定位；默认撤当前用户 undo 栈顶；可用 `--count` 连续撤销多步；支持普通单元格/结构写入，以及图表、透视表 update 的反向操作 |
+
+典型工作流：`+history-list` 拿到目标版本的 `history_version_id`（必要时翻页拉取更早历史）→ `+history-revert` 发起回滚并取回 `transaction_id` → `+history-revert-status --transaction-id <transaction_id>` 轮询直到成功或失败。
+
+`+undo` 的典型工作流更短：执行某个 AI 写入工具后，如果用户要求撤销刚才自己的修改，直接运行 `+undo`。返回 `undone=1` 表示已撤销一条当前用户栈顶；传 `--count N` 时会按当前用户栈顶从新到旧连续撤销，返回的 `undone` 是实际撤销数量。返回 `undone=0` 且 `reason=undo_stack_empty` 表示当前用户没有可撤销项。
+
+**注意事项（必须了解）**：
+- **回滚是写入 / 不可逆操作**：会用历史版本内容覆盖当前表格，发起前请确认目标 `history_version_id` 正确。
+- **回滚是异步的**：`+history-revert` 返回的是 `transaction_id`（受理标识），不代表回滚已完成；必须用 `+history-revert-status --transaction-id <transaction_id>` 确认最终结果。
+- **`history_version_id` 与 `transaction_id` 不是同一个**：`history_version_id` 用于 `+history-revert`（取自 `+history-list`）；`transaction_id` 用于 `+history-revert-status`（取自 `+history-revert` 的输出）。
+- **历史是工作簿级**：定位只需 `--url` / `--spreadsheet-token`（XOR），不需要子表选择器。
+- **`+history-list` 倒序分页**：首次查省略 `--end-version`，返回最新一页；若响应里附带 `next_end_version` 与 `has_more=true`，把 `next_end_version` 作为下一次的 `--end-version` 即可继续向更早翻页；当响应**不包含**这两个字段时表示已到最早一页，不必再翻。
+- **`+undo` 是用户维度**：只撤当前登录用户的 undo 栈顶；同一文档里其他用户的写入不会被撤销。
+- **`+undo --count` 是顺序多步撤销**：从当前用户最新栈项开始逐条撤销，最多 20 步；如果可撤销项不足或中途遇到不可撤销项，会停止并返回实际 `undone` 数量与 `reason`。
+- **`+undo` 不区分 session / agent**：同一用户的不同 CLI 会话或 agent 共用同一个用户 undo 栈。
+- **`+undo` 不进入 `+batch-update`**：撤销本身依赖用户栈状态，不能作为批量子操作嵌套执行。
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+history-list` | read | 历史版本 |
+| `+history-revert` | write | 历史版本 |
+| `+history-revert-status` | read | 历史版本 |
+| `+undo` | write | 历史版本 |
+
+## Flags
+
+### `+history-list`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--end-version` | int | optional | 分页查询的最大版本（倒序）；首次查询省略，下一页传上一页返回的 next_end_version。 |
+
+### `+history-revert`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--history-version-id` | string | required | 要回滚到的历史版本（取自 +history-list） |
+
+### `+history-revert-status`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--transaction-id` | string | required | 异步回滚的受理标识（取自 +history-revert） |
+
+### `+undo`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--count` | int | optional | 连续撤销的用户 undo 栈项数量，默认 1，最大 20。按当前用户栈顶从新到旧顺序撤销，实际撤销数量以返回的 undone 为准。 |
+
+## Examples
+
+公共定位：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token`（XOR，二选一）。`+history-revert` 用 `--history-version-id`（取自 `+history-list`）；`+history-revert-status` 用 `--transaction-id`（取自 `+history-revert` 的异步受理标识）。`+undo` 不需要 sheet-id，也不需要 history version；连续撤销多步时传 `--count`。
+
+### `+history-list`
+
+```bash
+# 列出某张电子表格的最新一页历史版本
+lark-cli sheets +history-list --url "https://sample.feishu.cn/sheets/SHTxxxxxx"
+
+# 用原始 spreadsheet token 定位
+lark-cli sheets +history-list --spreadsheet-token "SHTxxxxxx"
+
+# 翻到下一页：把上次响应里的 next_end_version 作为 --end-version 传入
+lark-cli sheets +history-list --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --end-version 12345
+```
+
+### `+history-revert`
+
+```bash
+# 回滚到指定历史版本（异步受理）
+lark-cli sheets +history-revert --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --history-version-id "<id-from-history-list>"
+```
+
+### `+history-revert-status`
+
+```bash
+# 查询某次回滚的当前状态（进行中 / 成功 / 失败）
+lark-cli sheets +history-revert-status --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --transaction-id "<transaction-id-from-history-revert>"
+```
+
+### `+undo`
+
+```bash
+# 撤销当前用户最近一次 AI 工具写入
+lark-cli sheets +undo --url "https://sample.feishu.cn/sheets/SHTxxxxxx"
+
+# 连续撤销当前用户最近 3 次 AI 工具写入；实际撤销数量以返回的 undone 为准
+lark-cli sheets +undo --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --count 3
+
+# 先预览将调用的底层 undo_last 请求
+lark-cli sheets +undo --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --count 3 --dry-run
+```

skills/lark-sheets/references/lark-sheets-pivot-table.md

@@ -32,9 +32,10 @@
 **常见配置错误（必须注意）**：
 - **数据源范围必须精确**：透视表的数据源范围必须包含表头行，且精确覆盖全部数据行列。范围过大（包含空行/空列）或过小（遗漏数据列）都会导致透视表结果错误
 - **行列字段选择要匹配用户意图**：用户说"按商品统计金额"→ 行字段=商品，值字段=金额（`summarize_by: "sum"`）。不要把行列字段搞反
-- **聚合类型要匹配**：用户说"统计数量"→ `summarize_by: "count"`；"统计总额"→ `"sum"`；"统计平均"→ `"average"`。完整合法值：`sum` / `count` / `average` / `max` / `min` / `product` / `countNums` / `stdDev` / `stdDevp` / `var` / `varp` / `distinct` / `median`。默认不要用 `count` 替代 `sum`
+- **聚合类型要匹配**：用户说"统计数量"→ `summarize_by: "count"`；"统计总额"→ `"sum"`；"统计平均"→ `"average"`。完整合法值：`sum` / `count` / `average` / `max` / `min` / `product` / `countNums` / `stdDev` / `stdDevp` / `var` / `varp` / `distinct` / `median`。按用户意图选聚合方式，不要拿 `count` 顶替 `sum`
 - **参数长度限制**：如果透视表配置 JSON 过长（数据源范围跨越大量行列），可能导致工具调用失败。此时应先确认数据范围的精确边界，避免传入过大的 range
-- **创建后必须验证**：调用 `+pivot-list` 确认透视表结构正确
+- **落点不能覆盖任何已有数据（不只是 `--source` 范围）**：透视表创建后会向右下**展开**，展开区域哪怕只盖到一个已有单元格（即便已避开源数据），也会报「目标位置不能与数据源重叠」并产生 `#REF!`。创建前无法精确预知展开尺寸，故**强烈优先默认策略**（不传 `--target-sheet-id/-name` 与 `--target-position`/`--range`，后端自动新建空白子表），零覆盖风险；非要落到已有子表，必须挑一片足够大的纯空白区
+- **创建后必须校验（用 `info` 读取展开后的真实占用区域）**：创建后调用 `+pivot-list` 读 `info.error_state` 与 `info.content_range`/`page_range`——`error_state` 非 `None`（如 `Cover` 盖到其它内容 / `Shrink` 展不开）说明落点冲突，应删除后重建到空白区；`content_range`/`page_range` 是展开后**实际占用区域**，可用 `+csv-get` 抽查其边缘外有没有盖掉原有数据，确认结构正确
 
 ## Shortcuts
 
@@ -120,6 +121,10 @@ _创建/更新的透视表属性_
 lark-cli sheets +pivot-list --url "..." --sheet-id "$SID"
 ```
 
+> **返回值含 `info`（展开后的占用区域与状态）**：每个透视表对象除 `position` / `snapshot` 外，还返回 `info`，标明它在 sheet 上的平铺区域与状态——`info.page_range`（筛选/分页区 A1）、`info.content_range`（主体数据区 A1）、`info.span_range`（空表合并区 A1）、`info.error_state`（错误状态，如 `None`/`Cover`/`Shrink`/`Loading`）、`info.is_empty` / `info.is_hidden`、`info.row`/`info.col`（锚点）等。
+> **用途 1（判断改值还是改配置）**：当用户描述某个单元格要改动时，先 `+pivot-list` 拿到 `info`，判断该单元格是否落在 `page_range` / `content_range` 内——**落在区域内 = 属于透视表，应走 `+pivot-update` 改配置**（透视表单元格不能直接 `+cells-set` 改值）；**落在区域外 = 普通单元格，正常 `+cells-set` 改值**。
+> **用途 2（创建后校验覆盖）**：建完透视表用 `info.error_state` 判断有没有冲突（非 `None` 即落点/展开区与已有数据重叠或展不开），用 `info.content_range`/`page_range` 拿到展开后真实占用区域再核对是否盖到原有数据。
+
 ### `+pivot-create`
 
 > 数据源 `--source` 必须从表头行开始；空行 / 汇总行会被当作数据参与聚合，需提前用 `+csv-get` 确认起止边界。`--source` 和 `--range` 是独立 flag（不要再放 `--properties`）；`rows` / `columns` / `values` 等数组字段走 `--properties`。

skills/lark-sheets/references/lark-sheets-range-operations.md

@@ -22,6 +22,7 @@
 
 注意：
 
+- **`--range` 两种语法别混**：`+cells-clear` / `+cells-{merge|unmerge}` / `+range-*` 用单元格 A1 矩形（如 `A2:A10`）；`+rows-resize` / `+cols-resize` 用纯行 / 列区间（行 `2:10`、列 `A:C`），不要给 resize 传 `A2:A10`
 - 用户说"这行 / 整行 / 首行"时，优先使用整行范围如 `1:1`；"这列 / 整列"时使用 `J:J`。不要截断为局部矩形
 - 合并后只保留左上角单元格的内容，其余清除。写入合并区域用 `+cells-set` 对左上角单元格操作
 - 调整行高列宽时，先读取相邻行列尺寸再决定像素值，不要随意猜测
@@ -35,7 +36,7 @@
 2. **判定阈值**：当前列宽（用 `+sheet-info --include row_heights,col_widths` 拿）≥ 最长字符数 × 字体宽度系数 + buffer 才算适配。默认列宽 11 通常只够 11 个半角字符或 5-6 个汉字，写长文本前必扩宽。
 3. **修复二选一**：
    - **扩列宽**：用 `+rows-resize / +cols-resize` 把目标列宽设为 `max(表头字符数, 内容采样最长字符数) × 8 + 16` 像素（经验值）
-   - **自动换行**：在 `+cells-set` 时给单元格设置 `cell_styles.word_wrap="auto-wrap"`（可选值：`overflow` / `auto-wrap` / `word-clip`），并用 `+rows-resize / +cols-resize` 调高对应行的行高
+   - **自动换行**：在 `+cells-set` 时给单元格设置 `cell_styles.word_wrap="auto-wrap"`（可选值：`overflow` / `auto-wrap` / `word-clip`；`cell_styles` 字段见 `lark-sheets-write-cells`），并用 `+rows-resize / +cols-resize` 调高对应行的行高
 4. **新增列默认列宽规则**：新增列宽度 ≥ `max(表头字符数, 内容采样最长字符数) × 8 + 16` 像素，**禁止**用默认 11 直接交付。
 
 **典型反例**：默认列宽 11 但内容含 12+ 字符的中文 / 含单位的数值（如 `109.10μmol/L`）/ 长数字未设 `number_format` 显示为科学计数法 —— 用户在结果表里看不到完整原值。
@@ -202,6 +203,8 @@ _排序条件列表（仅 sort 操作）_
 
 ### `+cells-clear`
 
+> ⚠️ **`--scope all` 清整表是不可逆的大范围破坏**：会一并抹掉该区域的合并单元格、原公式，以及图表 / 透视表引用的数据源列（这类列常在主数据区右侧，视觉上"看着没用"却被图例 / 系列引用）。**"美化 / 规范化一张已有表"永远不需要 clear 原表再重写**——若你打算"清空原表 → 写入重排后的版本"，说明走错了路径，应改为原地只刷样式（见 `lark-sheets-visual-standards` 场景三）。
+
 > **删不掉嵌入对象**：`+cells-clear`（任何 `--scope`，含 `all`）只清单元格的值 / 格式，**删不掉**压在范围内的透视表 / 图表等嵌入对象——后端会报 `can not find embedded block`。删透视表用 `+pivot-delete`、删图表用 `+chart-delete`（先用 `+pivot-list` / `+chart-list` 拿对象 id）。
 
 > 需要一次清除**多个不连续 range**（如把内容搬走后批量去掉散落各处的边框/底色）时，改用 `lark-sheets-batch-update` 的 `+cells-batch-clear`，避免对 `+cells-clear` 逐个 range 调用。

skills/lark-sheets/references/lark-sheets-read-data.md

@@ -2,7 +2,7 @@
 
 ## 列格式多样性预探（写公式 / 排序 / 筛选前必做）
 
-> 对应 `lark-sheets-core-operations` 的 **R3 计算复现**——本节是 R3 在 read_data 工具层的具体落地。
+> 本节给出"写公式 / 排序 / 筛选前先探清列格式多样性"的正确流程，是主 SKILL.md「飞书表格编辑准则」准则 3（读全再写）在 read_data 工具层的落地。
 
 对参与后续**计算 / 排序 / 筛选 / 公式提取**的列，**必须**先 sample **至少 50 行**（小表则全量），识别该列所有值类型变体后再设计公式 / 条件。只看前 10 行不够，因为下列差异通常潜伏在表尾或中段：
 
@@ -22,7 +22,7 @@
 | 读取目的 | 用这个 shortcut | 数据去向 | 说明 |
 |---------|----------------|---------|------|
 | 快速查看纯值数据、批量处理 | `+csv-get` | 对话上下文 | 返回 CSV 文本（每行带 `[row=N]` 前缀）；大表请按 `--range` 行窗口分批读（截断时看 `has_more`） |
-| 按列类型结构化读出（喂 DataFrame / round-trip 回 `+table-put`） | `+table-get` | 对话上下文 | 返回 typed 协议（`columns:[列名]` + `data` + `dtypes`/`formats` + `range`），输出形状对齐 pandas split；可一行 `pd.DataFrame(sheet["data"], columns=sheet["columns"]).astype(sheet["dtypes"])` 还原 DataFrame，或直接 round-trip 回 `+table-put`。不带 `--range` 时读**完整 used range**（跨过表中部空行 / 空列），每个子表回传实际读取范围 `range` 供完整性校验 |
+| 按列类型结构化读出（喂 DataFrame / round-trip 回 `+table-put`） | `+table-get` | 对话上下文 | 返回 typed 协议（`columns:[列名]` + `data` + `dtypes`/`formats` + `range`），输出形状对齐 pandas split；可一行 `pd.DataFrame(sheet["data"], columns=sheet["columns"]).astype(sheet["dtypes"])` 还原 DataFrame，或直接 round-trip 回 `+table-put`。不带 `--range` 时读**完整 used range**（跨过表中部空行 / 空列），每个子表回传实际读取范围 `range` 供完整性校验。注意这与下文 `current_region` "遇表中部空行截断"不矛盾：`+table-get` 读的是子表物理 used range（飞书记录的已用矩形，含中间空行），`current_region` 是从锚点连通扩展、遇整行空行就断 |
 | 查看公式、样式、批注、数据验证 | `+cells-get` | 对话上下文 | 返回单元格完整信息，token 开销较大 |
 | 查看某区域的下拉框（数据验证）选项 | `+dropdown-get` | 对话上下文 | 返回该 A1 范围已配置的下拉列表选项 |
 
@@ -42,7 +42,7 @@
 
 注意：
 
-- `+csv-get` 和 `+cells-get` 支持分页/截断，注意检查 `has_more` / `truncated` 标志；使用 `+cells-get` 时，在读取 `cells` 之前还必须先看 `warning_message`，并用每个 range 的 `actual_range` / `row_indices` / `col_indices` 判断真实位置
+- `+csv-get` 和 `+cells-get` 支持分页/截断，注意检查 `has_more` / `truncated` 标志；两者在处理返回数据之前都必须先读 `warning_message`（上游 schema 要求先读它再用其它字段，内含定位与截断续读提示），`+cells-get` 还要用每个 range 的 `actual_range` / `row_indices` / `col_indices` 判断真实位置
 - 隐藏行列默认包含在返回结果中（`--skip-hidden=false`），如需只看可见数据设为 `true`。读取原语本身不标注哪些行列被隐藏：若要识别隐藏区间（以决定是否过滤、或如何解读混入的隐藏数据），用 `+sheet-info --include hidden_rows,hidden_cols` 取隐藏行列集合，再结合 `+csv-get` / `+cells-get` 返回的 `row_indices` / `col_indices` 判断每行 / 每列是否隐藏
 
 **常见配置错误（必须注意）**：

skills/lark-sheets/references/lark-sheets-sheet-structure.md

@@ -39,7 +39,7 @@
 **常见配置错误（必须注意）**：
 - **插入列直接用字母**：`+dim-insert` 的 `--position` 在列场景直接传字母（如 `C`），不要把列字母换算成 0-based 索引
 - **插入后引用偏移**：插入行/列后，原有数据的行号 / 列字母会发生偏移。如果插入后还需要对原有区域执行写入操作，必须重新计算偏移后的位置
-- **删除行列前先确认范围**：删除操作不可逆，执行前应确认 `--range` 精确无误。可先用 `+csv-get` 读取目标区域验证内容
+- **删除行列前先确认范围**：删除操作不可逆，执行前应确认 `--range` 精确无误。可先用 `+csv-get` 读取目标区域验证内容（`+csv-get` / `+cells-get` 见 `lark-sheets-read-data`）
 - **"在 D 列左侧新增一列"的正确写法**：`--position D --count 1`（新列插在 D 列之前）；要继承左侧列样式加 `--inherit-style before`
 - **`+dim-move` 同维度约束**：`--source-range` 是行区间时 `--target` 必须是行号（数字），是列区间时 `--target` 必须是列字母——不可一行一列混用
 - **插入列后必须检查多行表头合并区域**：很多表格有 2-3 行的合并表头。插入列后，原有的合并区域不会自动扩展到新列。必须先用 `+sheet-info --include merges` 读取合并区域，插入后将跨越插入位置的合并区域重新设置（用 `+cells-{merge|unmerge}`），否则新列的表头会是空的、格式不连续
@@ -129,7 +129,7 @@ _公共四件套 · 系统：`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--depth` | int | optional | 要取消的分组层级，默认 1（最外层） |
+| `--depth` | int | optional | 要取消的分组层级，默认 1（1=最外层，数字越大越内层） |
 | `--range` | string | required | 要取消分组的行/列闭区间；行如 `3:7`，列如 `C:F` |
 
 ### `+dim-move`