fix: add type attribute when inferred from file extension

When the whiteboard type is inferred from file extension (e.g. .puml →
plantuml), the type attribute must be explicitly added to the tag attrs
so the server receives a valid <whiteboard type="plantuml"> tag.

Change-Id: Icfb4ec349ba47992be02ff90587e281fda143c73

.gitignore

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

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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
@@ -1355,6 +1371,7 @@ 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

README.md

@@ -233,6 +233,24 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # Comma-separated values
 ```
 
+### JSON Output Contract
+
+With `--format json` (the default), success and error envelopes are distinct.
+
+Success goes to **stdout**, exit code `0`:
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+Errors go to **stderr**, non-zero exit code:
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+To check whether a command succeeded, test `ok == true` (or the exit code) — **not** `code == 0`. Unlike raw OpenAPI responses (`{"code": 0, "msg": "ok", ...}`), the success envelope carries no `code` or `msg` field; `code` appears only inside `error` as the upstream OpenAPI code. See [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md) for the full error taxonomy.
+
 ### Pagination
 
 ```bash

README.zh.md

@@ -234,6 +234,24 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # 逗号分隔值
 ```
 
+### JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同。
+
+成功信封写入 **stdout**，退出码 0：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**，退出码非 0：
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+判断命令是否成功，请检查 `ok == true`（或进程退出码），**不要用 `code == 0`**。与原始 OpenAPI 响应（`{"code": 0, "msg": "ok", ...}`）不同，成功信封没有 `code` 和 `msg` 字段；`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。完整错误分类见 [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md)。
+
 ### 分页
 
 ```bash

cmd/api/api_test.go

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

cmd/schema/schema.go

@@ -65,13 +65,13 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	return cmd
 }
 
-// completeSchemaPath is a thin adapter over the embedded catalog's Complete.
-// It uses the embedded source so completion candidates match what `schema`
-// execution can resolve (both overlay-free).
+// completeSchemaPath is a thin adapter over the schema catalog's Complete.
+// It uses the same source as schema execution so completion candidates match
+// what `schema` can resolve.
 func completeSchemaPath(f *cmdutil.Factory) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
 	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		mode := f.ResolveStrictMode(cmd.Context())
-		completions, noSpace := registry.EmbeddedCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
+		completions, noSpace := registry.SchemaCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
 		directive := cobra.ShellCompDirectiveNoFileComp
 		if noSpace {
 			directive |= cobra.ShellCompDirectiveNoSpace
@@ -86,13 +86,19 @@ func schemaRun(opts *SchemaOptions) error {
 	return runSchema(out, apicatalog.ParsePath(opts.Args), mode)
 }
 
-// runSchema resolves the path through the embedded catalog and renders the
+// runSchema resolves the path through the schema catalog and renders the
 // matching envelope(s). The catalog owns navigation (Resolve + MethodRefs) and
 // schema owns rendering (Envelope/Envelopes); this adapter only chooses the
 // output shape — a single resolved method renders as one envelope object,
 // anything broader as an array — and maps resolve failures to hints.
 func runSchema(out io.Writer, parts []string, mode core.StrictMode) error {
-	catalog := registry.EmbeddedCatalog()
+	catalog := registry.SchemaCatalog()
+	if len(catalog.Services()) == 0 {
+		// No embedded metadata and the runtime fallback is empty too: offline
+		// with a cold cache, remote meta off, or an unwritable cache dir.
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "No API metadata available").
+			WithHint("this binary has no embedded API metadata; run any command with network access to the open platform once so metadata can be fetched and cached")
+	}
 	target, err := catalog.Resolve(parts)
 	if err != nil {
 		return resolveError(err)

cmd/update/update.go

@@ -102,7 +102,8 @@ func NewCmdUpdate(f *cmdutil.Factory) *cobra.Command {
 		Long: `Update lark-cli to the latest version.
 
 Detects the installation method automatically:
-  - npm install: runs npm install -g @larksuite/cli@<version>
+  - npm install:  runs npm install -g @larksuite/cli@<version>
+  - pnpm install: runs pnpm add -g @larksuite/cli@<version>
   - manual/other: shows GitHub Releases download URL
 
 Use --json for structured output (for AI agents and scripts).
@@ -164,7 +165,7 @@ func updateRun(opts *UpdateOptions) error {
 	if !detect.CanAutoUpdate() {
 		return doManualUpdate(opts, io, cur, latest, detect, updater)
 	}
-	return doNpmUpdate(opts, io, cur, latest, updater)
+	return doAutoUpdate(opts, io, cur, latest, detect, updater)
 }
 
 // --- Output helpers ---
@@ -226,12 +227,23 @@ func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest stri
 	fmt.Fprintf(io.ErrOut, "To update manually, download the latest release:\n")
 	fmt.Fprintf(io.ErrOut, "  Release:   %s\n", releaseURL(latest))
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
-	fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
+	if detect.Method == selfupdate.InstallPnpm {
+		fmt.Fprintf(io.ErrOut, "\nOr install via pnpm (note: skills will not be synced):\n  pnpm add -g %s@%s\n  pnpm dlx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
+	} else {
+		fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
+	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
-func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, updater *selfupdate.Updater) error {
+func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
+	pm := "npm"
+	install := updater.RunNpmInstall
+	if detect.Method == selfupdate.InstallPnpm {
+		pm = "pnpm"
+		install = updater.RunPnpmInstall
+	}
+
 	restore, err := updater.PrepareSelfReplace()
 	if err != nil {
 		return reportError(opts, io, "update_error",
@@ -239,19 +251,19 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 	}
 
 	if !opts.JSON {
-		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via npm ...\n", cur, symArrow(), latest)
+		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via %s ...\n", cur, symArrow(), latest, pm)
 	}
 
-	npmResult := updater.RunNpmInstall(latest)
+	npmResult := install(latest)
 	if npmResult.Err != nil {
 		restore()
 		combined := npmResult.CombinedOutput()
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok": false, "error": map[string]interface{}{
-					"type": "update_error", "message": fmt.Sprintf("npm install failed: %s", npmResult.Err),
+					"type": "update_error", "message": fmt.Sprintf("%s install failed: %s", pm, npmResult.Err),
 					"detail": selfupdate.Truncate(combined, maxNpmOutput),
-					"hint":   permissionHint(combined),
+					"hint":   permissionHint(combined, pm),
 				},
 			})
 			return output.ErrBare(output.ExitAPI)
@@ -263,7 +275,7 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 			fmt.Fprint(io.ErrOut, npmResult.Stderr.String())
 		}
 		fmt.Fprintf(io.ErrOut, "\n%s Update failed: %s\n", symFail(), npmResult.Err)
-		if hint := permissionHint(combined); hint != "" {
+		if hint := permissionHint(combined, pm); hint != "" {
 			fmt.Fprintf(io.ErrOut, "  %s\n", hint)
 		}
 		return output.ErrBare(output.ExitAPI)
@@ -274,7 +286,7 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 	if err := updater.VerifyBinary(latest); err != nil {
 		restore()
 		msg := fmt.Sprintf("new binary verification failed: %s", err)
-		hint := verificationFailureHint(updater, latest)
+		hint := verificationFailureHint(updater, latest, pm)
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok":    false,
@@ -304,23 +316,33 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 	fmt.Fprintf(io.ErrOut, "\n%s Successfully updated lark-cli from %s to %s\n", symOK(), cur, latest)
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
 	if skillsResult != nil {
-		fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
+		skillsPM := "npx"
+		if detect.Method == selfupdate.InstallPnpm && detect.PnpmAvailable {
+			skillsPM = "pnpm dlx"
+		}
+		fmt.Fprintf(io.ErrOut, "\nUpdating skills via %s ...\n", skillsPM)
 	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
-func permissionHint(npmOutput string) string {
-	if strings.Contains(npmOutput, "EACCES") && !isWindows() {
-		return "Permission denied. Try: sudo lark-cli update, or adjust your npm global prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors"
+func permissionHint(pmOutput, pm string) string {
+	if !strings.Contains(pmOutput, "EACCES") || isWindows() {
+		return ""
 	}
-	return ""
+	if pm == "pnpm" {
+		return "Permission denied. Ensure your pnpm global directory is writable — re-run `pnpm setup`, or see https://pnpm.io/pnpm-cli"
+	}
+	return "Permission denied. Try: sudo lark-cli update, or adjust your npm global prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors"
 }
 
-func verificationFailureHint(updater *selfupdate.Updater, latest string) string {
+func verificationFailureHint(updater *selfupdate.Updater, latest, pm string) string {
 	if updater.CanRestorePreviousVersion() {
 		return "the previous version has been restored"
 	}
+	if pm == "pnpm" {
+		return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): pnpm add -g %s@%s && pnpm dlx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
+	}
 	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): npm install -g %s@%s && npx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
 }
 

cmd/update/update_test.go

@@ -57,6 +57,27 @@ func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult, npmFn func(s
 	t.Cleanup(func() { newUpdater = origNew })
 }
 
+// mockDetectAndPnpm mirrors mockDetectAndNpm but wires the pnpm install path
+// and fails the test if the npm install path is invoked.
+func mockDetectAndPnpm(t *testing.T, result selfupdate.DetectResult, pnpmFn func(string) *selfupdate.NpmResult) {
+	t.Helper()
+	origNew := newUpdater
+	newUpdater = func() *selfupdate.Updater {
+		u := selfupdate.New()
+		u.DetectOverride = func() selfupdate.DetectResult { return result }
+		u.PnpmInstallOverride = pnpmFn
+		u.NpmInstallOverride = func(string) *selfupdate.NpmResult {
+			t.Errorf("npm install must not be called for a pnpm install")
+			return &selfupdate.NpmResult{}
+		}
+		u.VerifyOverride = func(string) error { return nil }
+		u.SkillsIndexFetchOverride = successfulSkillsIndexFetch()
+		u.SkillsCommandOverride = successfulSkillsCommand()
+		return u
+	}
+	t.Cleanup(func() { newUpdater = origNew })
+}
+
 func successfulSkillsIndexFetch() func() *selfupdate.NpmResult {
 	return func() *selfupdate.NpmResult {
 		r := &selfupdate.NpmResult{}
@@ -81,6 +102,110 @@ func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
 	}
 }
 
+func TestUpdatePnpm_JSON(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _ := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{"--json"})
+	origFetch := fetchLatest
+	fetchLatest = func() (string, error) { return "2.0.0", nil }
+	defer func() { fetchLatest = origFetch }()
+	origVersion := currentVersion
+	currentVersion = func() string { return "1.0.0" }
+	defer func() { currentVersion = origVersion }()
+	mockDetectAndPnpm(t,
+		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
+		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
+	)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if out := stdout.String(); !strings.Contains(out, `"action": "updated"`) {
+		t.Errorf("expected updated in output, got: %s", out)
+	}
+}
+
+func TestUpdatePnpm_Human(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, stderr := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{})
+	origFetch := fetchLatest
+	fetchLatest = func() (string, error) { return "2.0.0", nil }
+	defer func() { fetchLatest = origFetch }()
+	origVersion := currentVersion
+	currentVersion = func() string { return "1.0.0" }
+	defer func() { currentVersion = origVersion }()
+	mockDetectAndPnpm(t,
+		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
+		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
+	)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stderr.String()
+	if !strings.Contains(out, "via pnpm") {
+		t.Errorf("expected 'via pnpm' in stderr, got: %s", out)
+	}
+	if !strings.Contains(out, "Updating skills via pnpm dlx ...") {
+		t.Errorf("expected skills sync to report pnpm dlx launcher, got: %s", out)
+	}
+	if !strings.Contains(out, "Successfully updated") {
+		t.Errorf("expected success message, got: %s", out)
+	}
+}
+
+func TestUpdatePnpm_InstallError_JSON(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _ := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{"--json"})
+	origFetch := fetchLatest
+	fetchLatest = func() (string, error) { return "2.0.0", nil }
+	defer func() { fetchLatest = origFetch }()
+	origVersion := currentVersion
+	currentVersion = func() string { return "1.0.0" }
+	defer func() { currentVersion = origVersion }()
+	mockDetectAndPnpm(t,
+		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
+		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{Err: errors.New("pnpm boom")} },
+	)
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error exit")
+	}
+	if out := stdout.String(); !strings.Contains(out, `"ok": false`) || !strings.Contains(out, "update_error") {
+		t.Errorf("expected failure envelope, got: %s", out)
+	}
+	if out := stdout.String(); !strings.Contains(out, "pnpm install failed") {
+		t.Errorf("expected message to report pnpm as the package manager, got: %s", out)
+	}
+}
+
+func TestUpdatePnpm_Unavailable_ManualFallback(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, stderr := newTestFactory(t)
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{})
+	origFetch := fetchLatest
+	fetchLatest = func() (string, error) { return "2.0.0", nil }
+	defer func() { fetchLatest = origFetch }()
+	origVersion := currentVersion
+	currentVersion = func() string { return "1.0.0" }
+	defer func() { currentVersion = origVersion }()
+	mockDetect(t, selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: false})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stderr.String()
+	if !strings.Contains(out, "installed via pnpm, but pnpm is not available in PATH") {
+		t.Errorf("expected pnpm manual reason, got: %s", out)
+	}
+	if !strings.Contains(out, "pnpm add -g") {
+		t.Errorf("expected pnpm add -g hint, got: %s", out)
+	}
+}
+
 func TestNormalizeVersion(t *testing.T) {
 	tests := []struct {
 		input string
@@ -266,6 +391,9 @@ func TestUpdateNpm_Human(t *testing.T) {
 	if !strings.Contains(out, "Successfully updated") {
 		t.Errorf("expected success message in stderr, got: %s", out)
 	}
+	if !strings.Contains(out, "Updating skills via npx ...") {
+		t.Errorf("expected skills sync to report npx launcher for npm install, got: %s", out)
+	}
 }
 
 func TestUpdateForce_JSON(t *testing.T) {
@@ -739,9 +867,9 @@ func TestPermissionHint(t *testing.T) {
 	origOS := currentOS
 	defer func() { currentOS = origOS }()
 
-	// Linux: EACCES should produce a hint with npm prefix guidance.
+	// Linux + npm: EACCES should produce a hint with npm prefix guidance.
 	currentOS = "linux"
-	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'")
+	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'", "npm")
 	if !strings.Contains(hint, "npm global prefix") {
 		t.Errorf("expected npm prefix hint on linux, got: %s", hint)
 	}
@@ -749,16 +877,25 @@ func TestPermissionHint(t *testing.T) {
 		t.Errorf("should not suggest raw sudo npm install, got: %s", hint)
 	}
 
+	// Linux + pnpm: EACCES should point at pnpm setup, not npm prefix/sudo.
+	pnpmHint := permissionHint("EACCES: permission denied, access '/Users/x/Library/pnpm'", "pnpm")
+	if !strings.Contains(pnpmHint, "pnpm setup") {
+		t.Errorf("expected pnpm setup hint, got: %s", pnpmHint)
+	}
+	if strings.Contains(pnpmHint, "npm global prefix") || strings.Contains(pnpmHint, "sudo") {
+		t.Errorf("pnpm hint must not reference npm prefix or sudo, got: %s", pnpmHint)
+	}
+
 	// Windows: EACCES hint is suppressed (no EACCES on Windows).
 	currentOS = "windows"
-	hint = permissionHint("EACCES: permission denied")
+	hint = permissionHint("EACCES: permission denied", "npm")
 	if hint != "" {
 		t.Errorf("expected empty hint on Windows, got: %s", hint)
 	}
 
 	// Non-EACCES error: always empty.
 	currentOS = "linux"
-	if got := permissionHint("some other error"); got != "" {
+	if got := permissionHint("some other error", "npm"); got != "" {
 		t.Errorf("expected empty hint for non-EACCES, got: %s", got)
 	}
 }

errs/ERROR_CONTRACT.md

@@ -72,6 +72,28 @@ other category. `error.type` is `"policy"`, `error.subtype` is one of
 `challenge_required` / `access_denied`, and process exit is `6` via
 `CategoryPolicy`.
 
+### Success envelope (stdout)
+
+For contrast: success responses render to **stdout** as an
+`output.Envelope` (`internal/output/envelope.go`), exit code `0`:
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": { "guid": "e297d3d0-..." },
+  "meta": { "count": 1 }
+}
+```
+
+Consumers must branch on `ok` (or the process exit code). The success
+envelope has **no top-level `code` or `msg` field** — `code` exists only
+inside `error`, where it is the upstream numeric code (invariant 4).
+Wrappers that follow the raw OpenAPI convention and test `code == 0`
+will misclassify every successful call as a failure, which is
+especially dangerous around write commands (e.g. retrying a create that
+already succeeded).
+
 ## Categories
 
 | Category | When | Exit | Typed struct |

internal/affordance/affordance.go

@@ -77,14 +77,10 @@ func loadService(service string) map[string]json.RawMessage {
 // space→dot fallback covers domains where the two already coincide.
 func commandFormResolver(service string) func(string) string {
 	byForm := map[string]string{}
-	for _, svc := range registry.EmbeddedServicesTyped() {
-		if svc.Name != service {
-			continue
-		}
+	if svc, ok := registry.SchemaCatalog().Service(service); ok {
 		for _, ref := range apicatalog.ServiceMethods(svc, nil) {
 			byForm[strings.Join(ref.CommandPath()[1:], " ")] = ref.Method.ID
 		}
-		break
 	}
 	return func(h string) string {
 		h = strings.TrimSpace(h)

internal/cmdutil/secheader.go

@@ -6,12 +6,10 @@ package cmdutil
 import (
 	"context"
 	"net/http"
-	"os"
 	"reflect"
 	"runtime/debug"
 	"strings"
 	"sync"
-	"unicode"
 
 	"github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/extension/fileio"
@@ -40,8 +38,6 @@ const (
 	BuildKindUnknown  = "unknown"
 
 	officialModulePath = "github.com/larksuite/cli"
-
-	agentTraceMaxLen = 1024
 )
 
 // UserAgentValue returns the User-Agent value: "lark-cli/{version}".
@@ -49,25 +45,6 @@ func UserAgentValue() string {
 	return SourceValue + "/" + build.Version
 }
 
-// AgentTraceValue returns a header-safe value from the
-// LARKSUITE_CLI_AGENT_TRACE environment variable. It trims
-// surrounding whitespace, rejects values containing any Unicode
-// control character or exceeding agentTraceMaxLen, and returns ""
-// for any invalid or empty value. Callers can use the result
-// directly in HTTP headers without further sanitisation.
-func AgentTraceValue() string {
-	v := strings.TrimSpace(os.Getenv(envvars.CliAgentTrace))
-	if v == "" || len(v) > agentTraceMaxLen {
-		return ""
-	}
-	for _, r := range v {
-		if unicode.IsControl(r) {
-			return ""
-		}
-	}
-	return v
-}
-
 // BaseSecurityHeaders returns headers that every request must carry.
 func BaseSecurityHeaders() http.Header {
 	h := make(http.Header)
@@ -75,7 +52,7 @@ func BaseSecurityHeaders() http.Header {
 	h.Set(HeaderVersion, build.Version)
 	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
-	if v := AgentTraceValue(); v != "" {
+	if v := envvars.AgentTrace(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}
 	return h

internal/cmdutil/secheader_test.go

@@ -6,7 +6,6 @@ package cmdutil
 import (
 	"context"
 	"net/http"
-	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/extension/credential"
@@ -264,88 +263,9 @@ func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// AgentTraceValue / HeaderAgentTrace
+// HeaderAgentTrace injection (via BaseSecurityHeaders)
 // ---------------------------------------------------------------------------
 
-func TestAgentTraceValue_EmptyWhenEnvUnset(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty when env unset", got)
-	}
-}
-
-func TestAgentTraceValue_ReturnsCleanValue(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "trace-abc-123")
-	if got := AgentTraceValue(); got != "trace-abc-123" {
-		t.Fatalf("AgentTraceValue() = %q, want %q", got, "trace-abc-123")
-	}
-}
-
-func TestAgentTraceValue_TrimsWhitespace(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "  trace-trim  ")
-	if got := AgentTraceValue(); got != "trace-trim" {
-		t.Fatalf("AgentTraceValue() = %q, want %q (whitespace trimmed)", got, "trace-trim")
-	}
-}
-
-func TestAgentTraceValue_OnlyWhitespace_ReturnsEmpty(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "   ")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for whitespace-only value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsCRLF(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\r\nX-Evil: attack")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for CR/LF value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsLF(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\nX-Evil: attack")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for LF value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsTab(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\tinjected")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for tab value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsControlChar(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\x01injected")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for control char value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsDEL(t *testing.T) {
-	t.Setenv(envvars.CliAgentTrace, "val\x7finjected")
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() = %q, want empty for DEL value", got)
-	}
-}
-
-func TestAgentTraceValue_RejectsOverlongValue(t *testing.T) {
-	longVal := strings.Repeat("a", agentTraceMaxLen+1)
-	t.Setenv(envvars.CliAgentTrace, longVal)
-	if got := AgentTraceValue(); got != "" {
-		t.Fatalf("AgentTraceValue() returned non-empty for %d-byte value (max %d)", len(longVal), agentTraceMaxLen)
-	}
-}
-
-func TestAgentTraceValue_AcceptsMaxLengthValue(t *testing.T) {
-	val := strings.Repeat("a", agentTraceMaxLen)
-	t.Setenv(envvars.CliAgentTrace, val)
-	if got := AgentTraceValue(); got != val {
-		t.Fatalf("AgentTraceValue() = %q, want %d-byte value accepted", got, agentTraceMaxLen)
-	}
-}
-
 func TestBaseSecurityHeaders_NoAgentTraceHeaderWhenEnvUnset(t *testing.T) {
 	t.Setenv(envvars.CliAgentTrace, "")
 	h := BaseSecurityHeaders()

internal/envvars/envvars.go

@@ -19,6 +19,7 @@ const (
 	// Content safety scanning mode
 	CliContentSafetyMode = "LARKSUITE_CLI_CONTENT_SAFETY_MODE"
 
+	CliAgentName  = "LARKSUITE_CLI_AGENT_NAME"
 	CliAgentTrace = "LARKSUITE_CLI_AGENT_TRACE"
 
 	CliProxyEnable  = "LARKSUITE_CLI_PROXY_ENABLE"

internal/envvars/read.go

@@ -0,0 +1,36 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package envvars
+
+import (
+	"os"
+	"strings"
+	"unicode"
+)
+
+const (
+	agentNameMaxLen  = 128
+	agentTraceMaxLen = 1024
+)
+
+func AgentName() string {
+	return sanitizeSingleLine(os.Getenv(CliAgentName), agentNameMaxLen)
+}
+
+func AgentTrace() string {
+	return sanitizeSingleLine(os.Getenv(CliAgentTrace), agentTraceMaxLen)
+}
+
+func sanitizeSingleLine(raw string, maxLen int) string {
+	v := strings.TrimSpace(raw)
+	if v == "" || len(v) > maxLen {
+		return ""
+	}
+	for _, r := range v {
+		if unicode.IsControl(r) {
+			return ""
+		}
+	}
+	return v
+}

internal/envvars/read_test.go

@@ -0,0 +1,131 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package envvars
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestAgentName_EmptyWhenEnvUnset(t *testing.T) {
+	t.Setenv(CliAgentName, "")
+	if got := AgentName(); got != "" {
+		t.Fatalf("AgentName() = %q, want empty when env unset", got)
+	}
+}
+
+func TestAgentName_ReturnsCleanValue(t *testing.T) {
+	t.Setenv(CliAgentName, "claude-code")
+	if got := AgentName(); got != "claude-code" {
+		t.Fatalf("AgentName() = %q, want %q", got, "claude-code")
+	}
+}
+
+func TestAgentName_TrimsWhitespace(t *testing.T) {
+	t.Setenv(CliAgentName, "  cursor  ")
+	if got := AgentName(); got != "cursor" {
+		t.Fatalf("AgentName() = %q, want %q (whitespace trimmed)", got, "cursor")
+	}
+}
+
+func TestAgentName_RejectsCRLFInjection(t *testing.T) {
+	t.Setenv(CliAgentName, "agent\r\nX-Evil: attack")
+	if got := AgentName(); got != "" {
+		t.Fatalf("AgentName() = %q, want empty for CR/LF value", got)
+	}
+}
+
+func TestAgentName_RejectsControlChar(t *testing.T) {
+	t.Setenv(CliAgentName, "agent\x01injected")
+	if got := AgentName(); got != "" {
+		t.Fatalf("AgentName() = %q, want empty for control char value", got)
+	}
+}
+
+func TestAgentName_RejectsOverlongValue(t *testing.T) {
+	longVal := strings.Repeat("a", agentNameMaxLen+1)
+	t.Setenv(CliAgentName, longVal)
+	if got := AgentName(); got != "" {
+		t.Fatalf("AgentName() returned non-empty for %d-byte value (max %d)", len(longVal), agentNameMaxLen)
+	}
+}
+
+func TestAgentTrace_EmptyWhenEnvUnset(t *testing.T) {
+	t.Setenv(CliAgentTrace, "")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty when env unset", got)
+	}
+}
+
+func TestAgentTrace_ReturnsCleanValue(t *testing.T) {
+	t.Setenv(CliAgentTrace, "trace-abc-123")
+	if got := AgentTrace(); got != "trace-abc-123" {
+		t.Fatalf("AgentTrace() = %q, want %q", got, "trace-abc-123")
+	}
+}
+
+func TestAgentTrace_TrimsWhitespace(t *testing.T) {
+	t.Setenv(CliAgentTrace, "  trace-trim  ")
+	if got := AgentTrace(); got != "trace-trim" {
+		t.Fatalf("AgentTrace() = %q, want %q (whitespace trimmed)", got, "trace-trim")
+	}
+}
+
+func TestAgentTrace_OnlyWhitespace_ReturnsEmpty(t *testing.T) {
+	t.Setenv(CliAgentTrace, "   ")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for whitespace-only value", got)
+	}
+}
+
+func TestAgentTrace_RejectsCRLF(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\r\nX-Evil: attack")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for CR/LF value", got)
+	}
+}
+
+func TestAgentTrace_RejectsLF(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\nX-Evil: attack")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for LF value", got)
+	}
+}
+
+func TestAgentTrace_RejectsTab(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\tinjected")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for tab value", got)
+	}
+}
+
+func TestAgentTrace_RejectsControlChar(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\x01injected")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for control char value", got)
+	}
+}
+
+func TestAgentTrace_RejectsDEL(t *testing.T) {
+	t.Setenv(CliAgentTrace, "val\x7finjected")
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() = %q, want empty for DEL value", got)
+	}
+}
+
+func TestAgentTrace_RejectsOverlongValue(t *testing.T) {
+	longVal := strings.Repeat("a", agentTraceMaxLen+1)
+	t.Setenv(CliAgentTrace, longVal)
+	if got := AgentTrace(); got != "" {
+		t.Fatalf("AgentTrace() returned non-empty for %d-byte value (max %d)", len(longVal), agentTraceMaxLen)
+	}
+}
+
+func TestAgentTrace_AcceptsMaxLengthValue(t *testing.T) {
+	val := strings.Repeat("a", agentTraceMaxLen)
+	t.Setenv(CliAgentTrace, val)
+	if got := AgentTrace(); got != val {
+		t.Fatalf("AgentTrace() = %q, want %d-byte value accepted", got, agentTraceMaxLen)
+	}
+}

internal/registry/catalog.go

@@ -6,8 +6,7 @@ package registry
 import "github.com/larksuite/cli/internal/apicatalog"
 
 // EmbeddedCatalog returns a navigation catalog over the embedded (overlay-free)
-// metadata — deterministic across machines, for `lark-cli schema`, golden tests
-// and schema lint.
+// metadata — deterministic across machines, for golden tests and schema lint.
 func EmbeddedCatalog() apicatalog.Catalog {
 	return apicatalog.New(apicatalog.SourceEmbedded, EmbeddedServicesTyped())
 }
@@ -18,3 +17,14 @@ func EmbeddedCatalog() apicatalog.Catalog {
 func RuntimeCatalog() apicatalog.Catalog {
 	return apicatalog.New(apicatalog.SourceRuntime, ServicesTyped())
 }
+
+// SchemaCatalog returns the embedded catalog when metadata is compiled in,
+// otherwise the merged runtime catalog. Binaries built from the bare Go module
+// embed only the empty meta_data_default.json stub, so the embedded view has
+// nothing to resolve; the merged view is the only data such binaries have.
+func SchemaCatalog() apicatalog.Catalog {
+	if len(EmbeddedServicesTyped()) > 0 {
+		return EmbeddedCatalog()
+	}
+	return RuntimeCatalog()
+}

internal/registry/catalog_test.go

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package registry
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/larksuite/cli/internal/apicatalog"
+)
+
+// swapEmbeddedMeta replaces the compiled-in metadata bytes for one test and
+// restores them (with a full state reset) on cleanup.
+func swapEmbeddedMeta(t *testing.T, data []byte) {
+	t.Helper()
+	resetInit()
+	orig := embeddedMetaJSON
+	embeddedMetaJSON = data
+	t.Cleanup(func() {
+		waitBackgroundRefresh()
+		embeddedMetaJSON = orig
+		resetInit()
+	})
+}
+
+func TestSchemaCatalog_EmbeddedWhenCompiledIn(t *testing.T) {
+	swapEmbeddedMeta(t, testCacheJSON("embedded_svc"))
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
+
+	c := SchemaCatalog()
+
+	if c.Source() != apicatalog.SourceEmbedded {
+		t.Fatalf("Source = %q, want %q", c.Source(), apicatalog.SourceEmbedded)
+	}
+	if _, ok := c.Service("embedded_svc"); !ok {
+		t.Fatal("expected embedded_svc from embedded metadata")
+	}
+}
+
+// TestSchemaCatalog_FallsBackToRuntimeWhenNoEmbedded simulates a binary built
+// from the bare Go module (plugin builds): only the empty meta_data_default.json
+// stub is compiled in, so SchemaCatalog must serve the merged runtime view that
+// Init seeds via sync fetch.
+func TestSchemaCatalog_FallsBackToRuntimeWhenNoEmbedded(t *testing.T) {
+	swapEmbeddedMeta(t, embeddedMetaDataDefaultJSON)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
+
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(200)
+		w.Write(testEnvelopeJSON("remote_svc"))
+	}))
+	defer ts.Close()
+	testMetaURL = ts.URL
+
+	c := SchemaCatalog()
+
+	if c.Source() != apicatalog.SourceRuntime {
+		t.Fatalf("Source = %q, want %q", c.Source(), apicatalog.SourceRuntime)
+	}
+	if _, ok := c.Service("remote_svc"); !ok {
+		t.Fatal("expected remote_svc from runtime fallback")
+	}
+}

internal/registry/loader.go

@@ -15,6 +15,7 @@ import (
 
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/meta"
+	"github.com/larksuite/cli/internal/update"
 )
 
 //go:embed scope_priorities.json scope_overrides.json
@@ -85,7 +86,9 @@ func InitWithBrand(brand core.LarkBrand) {
 			brandChanged := metaErr == nil && cm.Brand != "" && cm.Brand != string(brand)
 
 			if !brandChanged {
-				if cached, err := loadCachedMerged(); err == nil {
+				// After a CLI upgrade the embedded data can be fresher than an old
+				// cache; an equal/older cache must not shadow it.
+				if cached, err := loadCachedMerged(); err == nil && update.IsNewer(cached.Version, embeddedVersion) {
 					overlayMergedServices(cached)
 				}
 			}

internal/registry/loader_test.go

@@ -0,0 +1,102 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package registry
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/meta"
+)
+
+// seedCache writes a cache file + cache meta for one service whose Title is
+// marker, tagged with the given top-level data version and brand.
+func seedCache(t *testing.T, dir, name, marker, version, brand string) {
+	t.Helper()
+	cDir := filepath.Join(dir, "cache")
+	if err := os.MkdirAll(cDir, 0700); err != nil {
+		t.Fatal(err)
+	}
+	reg := MergedRegistry{
+		Version:  version,
+		Services: []meta.Service{{Name: name, Version: "cache", Title: marker}},
+	}
+	data, _ := json.Marshal(reg)
+	if err := os.WriteFile(filepath.Join(cDir, "remote_meta.json"), data, 0644); err != nil {
+		t.Fatal(err)
+	}
+	cm := CacheMeta{LastCheckAt: time.Now().Unix(), Version: version, Brand: brand}
+	mData, _ := json.Marshal(cm)
+	if err := os.WriteFile(filepath.Join(cDir, "remote_meta.meta.json"), mData, 0644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// initWithCache runs a fresh feishu-brand init with remote on, a high TTL and a
+// recent LastCheckAt (so no refresh fires), embedded meta at embeddedVer and a
+// pre-seeded cache at cacheVer — the overlay version gate is the only variable.
+func initWithCache(t *testing.T, embeddedVer, cacheVer string) {
+	t.Helper()
+	embedded, _ := json.Marshal(MergedRegistry{
+		Version:  embeddedVer,
+		Services: []meta.Service{{Name: "svc", Version: "embedded", Title: "EMBEDDED"}},
+	})
+	swapEmbeddedMeta(t, embedded)
+	tmp := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
+	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
+	t.Setenv("LARKSUITE_CLI_META_TTL", "3600")
+	seedCache(t, tmp, "svc", "CACHE", cacheVer, "feishu")
+	InitWithBrand(core.BrandFeishu)
+}
+
+func titleOf(t *testing.T, name string) string {
+	t.Helper()
+	svc, ok := ServiceTyped(name)
+	if !ok {
+		t.Fatalf("service %q not loaded", name)
+	}
+	return svc.Title
+}
+
+func TestOverlayGate_EqualVersion_UsesEmbedded(t *testing.T) {
+	initWithCache(t, "1.0.0", "1.0.0")
+	if got := titleOf(t, "svc"); got != "EMBEDDED" {
+		t.Errorf("equal version: got %q, want EMBEDDED (cache must not overlay)", got)
+	}
+}
+
+func TestOverlayGate_OlderCache_UsesEmbedded(t *testing.T) {
+	initWithCache(t, "2.0.0", "1.0.0")
+	if got := titleOf(t, "svc"); got != "EMBEDDED" {
+		t.Errorf("older cache: got %q, want EMBEDDED", got)
+	}
+}
+
+func TestOverlayGate_NewerCache_OverlaysCache(t *testing.T) {
+	initWithCache(t, "1.0.0", "2.0.0")
+	if got := titleOf(t, "svc"); got != "CACHE" {
+		t.Errorf("newer cache: got %q, want CACHE", got)
+	}
+}
+
+func TestOverlayGate_UnparseableCacheVersion_UsesEmbedded(t *testing.T) {
+	initWithCache(t, "1.0.0", "not-a-semver")
+	if got := titleOf(t, "svc"); got != "EMBEDDED" {
+		t.Errorf("unparseable cache version: got %q, want EMBEDDED", got)
+	}
+}
+
+func TestOverlayGate_StubEmbedded_OverlaysRealCache(t *testing.T) {
+	// The bare-module stub baseline is "0.0.0"; a real cache version must win so
+	// plugin builds without compiled meta_data.json still get remote data.
+	initWithCache(t, "0.0.0", "1.0.0")
+	if got := titleOf(t, "svc"); got != "CACHE" {
+		t.Errorf("stub-embedded baseline: got %q, want CACHE", got)
+	}
+}

internal/registry/remote_test.go

@@ -72,9 +72,11 @@ func hasEmbeddedServices() bool {
 }
 
 // testRegistry returns a minimal MergedRegistry with one service.
+// The version is a real semver newer than the embedded stub baseline ("0.0.0")
+// so cache overlay passes the version gate in InitWithBrand.
 func testRegistry(name string) MergedRegistry {
 	return MergedRegistry{
-		Version: "test-1.0",
+		Version: "1.0.0",
 		Services: []meta.Service{
 			{
 				Name:        name,
@@ -160,7 +162,7 @@ func TestRemoteOff_SkipsRemoteLogic(t *testing.T) {
 }
 
 func TestCacheHit_WithinTTL(t *testing.T) {
-	resetInit()
+	swapEmbeddedMeta(t, nil) // overlay must depend only on the cache version, not the ambient embedded meta
 	tmp := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
@@ -197,7 +199,7 @@ func TestCacheHit_WithinTTL(t *testing.T) {
 }
 
 func TestNetworkError_SilentDegradation(t *testing.T) {
-	resetInit()
+	swapEmbeddedMeta(t, nil) // overlay must depend only on the cache version, not the ambient embedded meta
 	tmp := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
@@ -371,8 +373,8 @@ func TestFetchRemoteMerged_200(t *testing.T) {
 	if data == nil {
 		t.Fatal("expected non-nil data")
 	}
-	if reg.Version != "test-1.0" {
-		t.Errorf("expected version test-1.0, got %s", reg.Version)
+	if reg.Version != "1.0.0" {
+		t.Errorf("expected version 1.0.0, got %s", reg.Version)
 	}
 }
 

internal/selfupdate/updater.go

@@ -32,6 +32,7 @@ type InstallMethod int
 
 const (
 	InstallNpm InstallMethod = iota
+	InstallPnpm
 	InstallManual
 )
 
@@ -53,22 +54,32 @@ var (
 
 // DetectResult holds installation detection results.
 type DetectResult struct {
-	Method       InstallMethod
-	ResolvedPath string
-	NpmAvailable bool
+	Method        InstallMethod
+	ResolvedPath  string
+	NpmAvailable  bool
+	PnpmAvailable bool
 }
 
 // CanAutoUpdate returns true if the CLI can update itself automatically.
 func (d DetectResult) CanAutoUpdate() bool {
-	return d.Method == InstallNpm && d.NpmAvailable
+	switch d.Method {
+	case InstallNpm:
+		return d.NpmAvailable
+	case InstallPnpm:
+		return d.PnpmAvailable
+	}
+	return false
 }
 
 // ManualReason returns a human-readable explanation of why auto-update is unavailable.
 func (d DetectResult) ManualReason() string {
-	if d.Method == InstallNpm && !d.NpmAvailable {
+	switch {
+	case d.Method == InstallNpm && !d.NpmAvailable:
 		return "installed via npm, but npm is not available in PATH"
+	case d.Method == InstallPnpm && !d.PnpmAvailable:
+		return "installed via pnpm, but pnpm is not available in PATH"
 	}
-	return "not installed via npm"
+	return "not installed via npm or pnpm"
 }
 
 // NpmResult holds the result of an npm install or skills update execution.
@@ -92,6 +103,7 @@ func (r *NpmResult) CombinedOutput() string {
 type Updater struct {
 	DetectOverride           func() DetectResult
 	NpmInstallOverride       func(version string) *NpmResult
+	PnpmInstallOverride      func(version string) *NpmResult
 	SkillsIndexFetchOverride func() *NpmResult
 	SkillsCommandOverride    func(args ...string) *NpmResult
 	VerifyOverride           func(expectedVersion string) error
@@ -101,17 +113,38 @@ type Updater struct {
 	// running binary is successfully renamed to .old. Used by
 	// CanRestorePreviousVersion to report whether rollback is possible.
 	backupCreated bool
+
+	// detectCache memoizes the first real DetectInstallMethod result. How this
+	// binary was installed cannot change during a single process, so caching is
+	// the correct semantics — and it is required for correctness: the update
+	// flow mutates the install (pnpm add -g / npm install -g) before syncing
+	// skills, so a re-detection at skills time could resolve a now-stale
+	// os.Executable path and misclassify. Seeded pre-update by the first call
+	// (updateRun), it keeps the post-update skills launcher consistent with the
+	// launcher reported to the user. Not goroutine-safe; the update flow is
+	// sequential.
+	detectCache *DetectResult
 }
 
 // New creates an Updater with default (real) behavior.
 func New() *Updater { return &Updater{} }
 
-// DetectInstallMethod determines how the CLI was installed and whether
-// npm is available for auto-update.
+// DetectInstallMethod determines how the CLI was installed and whether the
+// owning package manager is available for auto-update.
 func (u *Updater) DetectInstallMethod() DetectResult {
 	if u.DetectOverride != nil {
 		return u.DetectOverride()
 	}
+	if u.detectCache != nil {
+		return *u.detectCache
+	}
+	result := u.detectInstallMethod()
+	u.detectCache = &result
+	return result
+}
+
+// detectInstallMethod performs the real (uncached) detection.
+func (u *Updater) detectInstallMethod() DetectResult {
 	exe, err := vfs.Executable()
 	if err != nil {
 		return DetectResult{Method: InstallManual}
@@ -120,24 +153,54 @@ func (u *Updater) DetectInstallMethod() DetectResult {
 	if err != nil {
 		return DetectResult{Method: InstallManual, ResolvedPath: exe}
 	}
+	_, npmErr := exec.LookPath("npm")
+	_, pnpmErr := exec.LookPath("pnpm")
+	return detectFromResolved(resolved, npmErr == nil, pnpmErr == nil)
+}
 
+// detectFromResolved classifies the resolved binary path into an install
+// method and records package-manager availability. Split out from
+// DetectInstallMethod so the classification is unit-testable without touching
+// the filesystem or PATH.
+func detectFromResolved(resolved string, npmOnPath, pnpmOnPath bool) DetectResult {
 	method := InstallManual
 	if strings.Contains(resolved, "node_modules") {
-		method = InstallNpm
-	}
-
-	npmAvailable := false
-	if method == InstallNpm {
-		if _, err := exec.LookPath("npm"); err == nil {
-			npmAvailable = true
+		if containsPnpmMarker(resolved) {
+			method = InstallPnpm
+		} else {
+			method = InstallNpm
 		}
 	}
-
-	return DetectResult{
-		Method:       method,
-		ResolvedPath: resolved,
-		NpmAvailable: npmAvailable,
+	d := DetectResult{Method: method, ResolvedPath: resolved}
+	switch method {
+	case InstallNpm:
+		d.NpmAvailable = npmOnPath
+	case InstallPnpm:
+		d.PnpmAvailable = pnpmOnPath
 	}
+	return d
+}
+
+// containsPnpmMarker reports whether the resolved binary path belongs to a
+// pnpm-managed install. pnpm exposes two layouts: the classic virtual store
+// (a ".pnpm" directory segment) and the global content-addressable store,
+// whose resolved path runs through pnpm's home directory (e.g.
+// "~/Library/pnpm/store/v11/links/...") — a "pnpm" segment immediately
+// followed by "store". Matching only these two shapes (rather than any bare
+// "pnpm" segment) avoids misclassifying an npm install that merely lives under
+// a directory named "pnpm". Windows separators are normalized to "/" so the
+// classification is OS-independent and unit-testable anywhere.
+func containsPnpmMarker(p string) bool {
+	parts := strings.Split(strings.ReplaceAll(p, `\`, "/"), "/")
+	for i, part := range parts {
+		if part == ".pnpm" {
+			return true
+		}
+		if part == "pnpm" && i+1 < len(parts) && parts[i+1] == "store" {
+			return true
+		}
+	}
+	return false
 }
 
 // RunNpmInstall executes npm install -g @larksuite/cli@<version>.
@@ -163,6 +226,29 @@ func (u *Updater) RunNpmInstall(version string) *NpmResult {
 	return r
 }
 
+// RunPnpmInstall executes pnpm add -g @larksuite/cli@<version>.
+func (u *Updater) RunPnpmInstall(version string) *NpmResult {
+	if u.PnpmInstallOverride != nil {
+		return u.PnpmInstallOverride(version)
+	}
+	r := &NpmResult{}
+	pnpmPath, err := exec.LookPath("pnpm")
+	if err != nil {
+		r.Err = fmt.Errorf("pnpm not found in PATH: %w", err)
+		return r
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), npmInstallTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, pnpmPath, "add", "-g", NpmPackage+"@"+version)
+	cmd.Stdout = &r.Stdout
+	cmd.Stderr = &r.Stderr
+	r.Err = cmd.Run()
+	if ctx.Err() == context.DeadlineExceeded {
+		r.Err = fmt.Errorf("pnpm install timed out after %s", npmInstallTimeout)
+	}
+	return r
+}
+
 func (u *Updater) ListOfficialSkillsIndex() *NpmResult {
 	if u.SkillsIndexFetchOverride != nil {
 		return u.SkillsIndexFetchOverride()
@@ -261,19 +347,40 @@ func (u *Updater) runSkillsInstall(source string, nameList []string) *NpmResult
 	return u.runSkillsCommand(args...)
 }
 
+// skillsInvocation decides how to launch the `skills` CLI. When the lark-cli
+// itself was installed via pnpm and pnpm is available, it uses `pnpm dlx` so
+// pnpm-only environments (pnpm's standalone installer bundles Node without
+// putting npm/npx on PATH) can still sync skills after a self-update.
+// Otherwise it uses `npx`. The npx auto-confirm flag "-y", when present as the
+// leading arg, maps to `pnpm dlx`'s default non-interactive behavior and is
+// dropped for the pnpm launcher. Kept pure (no exec/PATH access) so the
+// launcher selection is unit-testable on any platform.
+func skillsInvocation(method InstallMethod, pnpmAvailable bool, args []string) (launcher string, rest []string) {
+	if method == InstallPnpm && pnpmAvailable {
+		r := args
+		if len(r) > 0 && r[0] == "-y" {
+			r = r[1:]
+		}
+		return "pnpm", append([]string{"dlx"}, r...)
+	}
+	return "npx", args
+}
+
 func (u *Updater) runSkillsCommand(args ...string) *NpmResult {
 	if u.SkillsCommandOverride != nil {
 		return u.SkillsCommandOverride(args...)
 	}
 	r := &NpmResult{}
-	npxPath, err := exec.LookPath("npx")
+	det := u.DetectInstallMethod()
+	launcher, cmdArgs := skillsInvocation(det.Method, det.PnpmAvailable, args)
+	binPath, err := exec.LookPath(launcher)
 	if err != nil {
-		r.Err = fmt.Errorf("npx not found in PATH: %w", err)
+		r.Err = fmt.Errorf("%s not found in PATH: %w", launcher, err)
 		return r
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), skillsUpdateTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, npxPath, args...)
+	cmd := exec.CommandContext(ctx, binPath, cmdArgs...)
 	cmd.Stdout = &r.Stdout
 	cmd.Stderr = &r.Stderr
 	r.Err = cmd.Run()

internal/selfupdate/updater_test.go

@@ -371,3 +371,147 @@ func TestListOfficialSkillsFallsBack(t *testing.T) {
 		t.Fatalf("fallback call = %q, want larksuite/cli --list", called[1])
 	}
 }
+
+func TestContainsPnpmMarker(t *testing.T) {
+	cases := []struct {
+		path string
+		want bool
+	}{
+		// Classic virtual-store layout (.pnpm segment).
+		{"/Users/x/Library/pnpm/global/5/node_modules/.pnpm/@larksuite+cli@1.0.44/node_modules/@larksuite/cli/bin/lark-cli", true},
+		{`C:\Users\x\AppData\Local\pnpm\global\5\node_modules\.pnpm\@larksuite+cli@1.0.44\node_modules\@larksuite\cli\bin\lark-cli.exe`, true},
+		// Global content-addressable store layout (pnpm 11): resolved path runs
+		// through the pnpm home store, a "pnpm" segment with no ".pnpm".
+		{"/Users/x/Library/pnpm/store/v11/links/@larksuite/cli/1.0.59/abc123/node_modules/@larksuite/cli/bin/lark-cli", true},
+		{"/home/x/.local/share/pnpm/store/v10/@larksuite/cli/node_modules/@larksuite/cli/bin/lark-cli", true},
+		{`C:\Users\x\AppData\Local\pnpm\store\v11\links\@larksuite\cli\node_modules\@larksuite\cli\bin\lark-cli.exe`, true},
+		// npm and non-package installs — no pnpm/.pnpm segment.
+		{"/usr/local/lib/node_modules/@larksuite/cli/bin/lark-cli", false},
+		{"/usr/local/bin/lark-cli", false},
+		// Substrings that must NOT match: segment must be exactly .pnpm, or
+		// "pnpm" immediately followed by "store".
+		{"/opt/homebrew/.pnpmfoo/node_modules/@larksuite/cli/bin/lark-cli", false},
+		{"/opt/pnpmfoo/node_modules/@larksuite/cli/bin/lark-cli", false},
+		// A bare "pnpm" directory NOT followed by "store" (e.g. an npm install
+		// living under a dir named pnpm) must not be misclassified as pnpm.
+		{"/opt/pnpm/lib/node_modules/@larksuite/cli/bin/lark-cli", false},
+	}
+	for _, c := range cases {
+		if got := containsPnpmMarker(c.path); got != c.want {
+			t.Errorf("containsPnpmMarker(%q) = %v, want %v", c.path, got, c.want)
+		}
+	}
+}
+
+func TestDetectInstallMethod_Pnpm(t *testing.T) {
+	u := &Updater{DetectOverride: nil}
+	u.DetectOverride = func() DetectResult {
+		// Exercise the real classification by feeding a resolved path via a small shim.
+		return detectFromResolved("/x/node_modules/.pnpm/@larksuite+cli@1.0.44/node_modules/@larksuite/cli/bin/lark-cli", true, true)
+	}
+	got := u.DetectInstallMethod()
+	if got.Method != InstallPnpm {
+		t.Errorf("Method = %v, want InstallPnpm", got.Method)
+	}
+	if !got.PnpmAvailable {
+		t.Errorf("PnpmAvailable = false, want true")
+	}
+}
+
+func TestDetectInstallMethod_NpmVsManual(t *testing.T) {
+	if m := detectFromResolved("/usr/local/lib/node_modules/@larksuite/cli/bin/lark-cli", true, false).Method; m != InstallNpm {
+		t.Errorf("npm path Method = %v, want InstallNpm", m)
+	}
+	if m := detectFromResolved("/usr/local/bin/lark-cli", false, false).Method; m != InstallManual {
+		t.Errorf("manual path Method = %v, want InstallManual", m)
+	}
+}
+
+func TestCanAutoUpdate_Pnpm(t *testing.T) {
+	if !(DetectResult{Method: InstallPnpm, PnpmAvailable: true}).CanAutoUpdate() {
+		t.Error("pnpm available should CanAutoUpdate")
+	}
+	if (DetectResult{Method: InstallPnpm, PnpmAvailable: false}).CanAutoUpdate() {
+		t.Error("pnpm unavailable should not CanAutoUpdate")
+	}
+}
+
+func TestManualReason_Pnpm(t *testing.T) {
+	if got := (DetectResult{Method: InstallPnpm, NpmAvailable: false, PnpmAvailable: false}).ManualReason(); got != "installed via pnpm, but pnpm is not available in PATH" {
+		t.Errorf("pnpm reason = %q", got)
+	}
+	if got := (DetectResult{Method: InstallManual}).ManualReason(); got != "not installed via npm or pnpm" {
+		t.Errorf("manual reason = %q", got)
+	}
+}
+
+func TestRunPnpmInstall_Override(t *testing.T) {
+	u := &Updater{PnpmInstallOverride: func(version string) *NpmResult {
+		r := &NpmResult{}
+		r.Stdout.WriteString("added @larksuite/cli@" + version)
+		return r
+	}}
+	got := u.RunPnpmInstall("2.0.0")
+	if got.Err != nil {
+		t.Fatalf("unexpected err: %v", got.Err)
+	}
+	if !strings.Contains(got.CombinedOutput(), "2.0.0") {
+		t.Errorf("output = %q, want version echoed", got.CombinedOutput())
+	}
+}
+
+func TestRunPnpmInstall_Error(t *testing.T) {
+	wantErr := errors.New("boom")
+	u := &Updater{PnpmInstallOverride: func(string) *NpmResult { return &NpmResult{Err: wantErr} }}
+	if got := u.RunPnpmInstall("2.0.0"); !errors.Is(got.Err, wantErr) {
+		t.Errorf("err = %v, want %v", got.Err, wantErr)
+	}
+}
+
+func TestSkillsInvocation(t *testing.T) {
+	addArgs := []string{"-y", "skills", "add", "https://open.feishu.cn", "-g", "-y"}
+	cases := []struct {
+		name          string
+		method        InstallMethod
+		pnpmAvailable bool
+		args          []string
+		wantLauncher  string
+		wantRest      []string
+	}{
+		{"pnpm install + pnpm available → pnpm dlx, drop leading -y", InstallPnpm, true, addArgs,
+			"pnpm", []string{"dlx", "skills", "add", "https://open.feishu.cn", "-g", "-y"}},
+		{"pnpm install but pnpm unavailable → npx unchanged", InstallPnpm, false, addArgs,
+			"npx", addArgs},
+		{"npm install → npx unchanged", InstallNpm, false, addArgs,
+			"npx", addArgs},
+		{"manual install → npx unchanged", InstallManual, false, []string{"-y", "skills", "ls", "-g"},
+			"npx", []string{"-y", "skills", "ls", "-g"}},
+		{"pnpm without a leading -y → prepend dlx only", InstallPnpm, true, []string{"skills", "ls", "-g"},
+			"pnpm", []string{"dlx", "skills", "ls", "-g"}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			gotLauncher, gotRest := skillsInvocation(c.method, c.pnpmAvailable, c.args)
+			if gotLauncher != c.wantLauncher {
+				t.Errorf("launcher = %q, want %q", gotLauncher, c.wantLauncher)
+			}
+			if strings.Join(gotRest, " ") != strings.Join(c.wantRest, " ") {
+				t.Errorf("rest = %v, want %v", gotRest, c.wantRest)
+			}
+		})
+	}
+}
+
+// TestDetectInstallMethod_Caches locks the fix for the post-update re-detection
+// hazard: DetectInstallMethod must return the first (pre-update) detection on
+// subsequent calls, so the skills launcher chosen after the binary is replaced
+// stays consistent with what was detected — and reported — before the update.
+func TestDetectInstallMethod_Caches(t *testing.T) {
+	u := New()
+	cached := DetectResult{Method: InstallPnpm, PnpmAvailable: true, ResolvedPath: "/x/pnpm/store/v11/links/@larksuite/cli/1.0.0/node_modules/@larksuite/cli/bin/lark-cli"}
+	u.detectCache = &cached
+	got := u.DetectInstallMethod()
+	if got.Method != InstallPnpm || !got.PnpmAvailable {
+		t.Errorf("expected cached pnpm result to be returned, got %+v", got)
+	}
+}

package.json

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

shortcuts/calendar/calendar_create.go

@@ -67,6 +67,26 @@ 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",
@@ -225,6 +245,7 @@ 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,6 +673,76 @@ 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

@@ -0,0 +1,261 @@
+// 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

@@ -0,0 +1,340 @@
+// 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/html5_block_resources.go

@@ -119,6 +119,13 @@ func prepareDocsV2WriteInput(runtime *common.RuntimeContext, input docsV2WriteIn
 	if err != nil {
 		return docsV2WriteInput{}, err
 	}
+	if err := validateWhiteboardWriteElementBodies(runtime.Str("doc-format"), content); err != nil {
+		return docsV2WriteInput{}, err
+	}
+	content, err = prepareWhiteboardInlineContent(runtime, runtime.Str("doc-format"), content)
+	if err != nil {
+		return docsV2WriteInput{}, err
+	}
 	if err := resolveReferenceMapPaths(runtime, html5RefMap); err != nil {
 		return docsV2WriteInput{}, err
 	}

shortcuts/doc/shortcuts.go

@@ -31,6 +31,8 @@ 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
 	}
@@ -44,6 +46,12 @@ 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"
 	}
@@ -56,6 +64,9 @@ func Shortcuts() []common.Shortcut {
 		DocsCreate,
 		DocsFetch,
 		DocsUpdate,
+		DocsHistoryList,
+		DocsHistoryRevert,
+		DocsHistoryRevertStatus,
 		DocMediaInsert,
 		DocMediaUpload,
 		DocMediaPreview,

shortcuts/doc/whiteboard_inline.go

@@ -0,0 +1,275 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	whiteboardTag = "whiteboard"
+)
+
+var (
+	whiteboardStartTagPattern = regexp.MustCompile(`(?is)<whiteboard\b[^>]*>`)
+	whiteboardElementPattern  = regexp.MustCompile(`(?is)<whiteboard\b[^>]*>(.*?)</whiteboard>`)
+	whiteboardElementReplacer = regexp.MustCompile(`(?is)<whiteboard\b[^>]*>.*?</whiteboard>`)
+)
+
+type whiteboardAttr struct {
+	Name  string
+	Value string
+}
+
+type whiteboardStartTag struct {
+	Attrs       []whiteboardAttr
+	SelfClosing bool
+}
+
+func prepareWhiteboardInlineContent(runtime *common.RuntimeContext, format string, content string) (string, error) {
+	if !strings.Contains(content, "<"+whiteboardTag) {
+		return content, nil
+	}
+	if strings.TrimSpace(format) == "markdown" {
+		// whiteboard tags are only used in XML format
+		return content, nil
+	}
+
+	var rewriteErr error
+	out := whiteboardElementReplacer.ReplaceAllStringFunc(content, func(raw string) string {
+		if rewriteErr != nil {
+			return raw
+		}
+		// Extract the opening tag part
+		openTagMatch := whiteboardStartTagPattern.FindString(raw)
+		if openTagMatch == "" {
+			return raw
+		}
+		tag, err := parseWhiteboardStartTag(openTagMatch)
+		if err != nil {
+			rewriteErr = common.ValidationErrorf("invalid whiteboard tag: %v", err).WithParam("whiteboard")
+			return raw
+		}
+
+		pathValue, hasPath := tag.attr("path")
+		if !hasPath {
+			// no path attribute, leave as-is
+			return raw
+		}
+
+		data, err := readWhiteboardPath(runtime, pathValue, "whiteboard path")
+		if err != nil {
+			rewriteErr = err
+			return raw
+		}
+
+		// Infer type from extension if not present
+		var docType string
+		if docType, hasType := tag.attr("type"); hasType {
+			docType = strings.TrimSpace(docType)
+			if !isValidWhiteboardType(docType) {
+				rewriteErr = common.ValidationErrorf("invalid whiteboard type %q; valid types: raw | plantuml | mermaid | svg", docType).WithParam("type")
+				return raw
+			}
+		} else {
+			cleanPath := filepath.Clean(strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(pathValue), "@")))
+			ext := strings.ToLower(filepath.Ext(cleanPath))
+			switch ext {
+			case ".puml", ".plantuml":
+				docType = "plantuml"
+			case ".mmd", ".mermaid":
+				docType = "mermaid"
+			case ".svg":
+				docType = "svg"
+			default:
+				docType = "raw"
+			}
+		}
+
+		tag.removeAttrs("path")
+		if docType != "" {
+			if !tag.hasAttr("type") {
+				tag.Attrs = append(tag.Attrs, whiteboardAttr{Name: "type", Value: docType})
+			}
+		} else {
+			tag.removeAttrs("type")
+		}
+
+		var result strings.Builder
+		result.WriteString(tag.render(false))
+		result.WriteString(data)
+		result.WriteString("</whiteboard>")
+		return result.String()
+	})
+
+	if rewriteErr != nil {
+		return "", rewriteErr
+	}
+	return out, nil
+}
+
+// validateWhiteboardWriteElementBodies ensures that whiteboard tags with path attribute
+// don't contain inner content (like html5-block). This prevents ambiguity: you must either
+// have the path attribute resolved by CLI OR have content inline, not both.
+func validateWhiteboardWriteElementBodies(format string, content string) error {
+	validateSegment := func(segment string) error {
+		matches := whiteboardElementPattern.FindAllStringSubmatchIndex(segment, -1)
+		for _, match := range matches {
+			if len(match) < 4 || match[2] < 0 || match[3] < 0 {
+				continue
+			}
+			inner := strings.TrimSpace(segment[match[2]:match[3]])
+			if inner != "" {
+				// inner content is non-empty — check if there's a path attribute in the opening tag
+				raw := segment[match[0]:match[1]]
+				tag, err := parseWhiteboardStartTag(raw)
+				if err != nil {
+					continue // already validated during rewrite; ignore here
+				}
+				if _, hasPath := tag.attr("path"); hasPath {
+					return common.ValidationErrorf("whiteboard with path=\"@...\" cannot contain inner content; remove the content between <whiteboard> and </whiteboard>").WithParam("whiteboard")
+				}
+			}
+		}
+		return nil
+	}
+
+	if strings.TrimSpace(format) != "markdown" {
+		return validateSegment(content)
+	}
+
+	var validateErr error
+	_ = applyOutsideCodeFences(content, func(segment string) string {
+		if validateErr != nil {
+			return segment
+		}
+		if err := validateSegment(segment); err != nil {
+			validateErr = err
+		}
+		return segment
+	})
+	return validateErr
+}
+
+func isValidWhiteboardType(typ string) bool {
+	switch typ {
+	case "raw", "plantuml", "mermaid", "svg":
+		return true
+	default:
+		return false
+	}
+}
+
+func readWhiteboardPath(runtime *common.RuntimeContext, pathValue, label string) (string, error) {
+	pathRaw := strings.TrimSpace(pathValue)
+	if !strings.HasPrefix(pathRaw, "@") {
+		return "", common.ValidationErrorf("%s %q must start with @, for example @diagram.puml", label, pathValue).WithParam("path")
+	}
+	relPath := strings.TrimSpace(strings.TrimPrefix(pathRaw, "@"))
+	if relPath == "" {
+		return "", common.ValidationErrorf("%s cannot be empty after @", label).WithParam("path")
+	}
+	clean := filepath.Clean(relPath)
+	if filepath.IsAbs(clean) || clean == "." || clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
+		return "", common.ValidationErrorf("%s %q must be a relative path within the current working directory", label, pathValue).WithParam("path")
+	}
+	data, err := cmdutil.ReadInputFile(runtime.FileIO(), clean)
+	if err != nil {
+		return "", fmt.Errorf("%s %q cannot be read from the current working directory; check that the file exists: %w", label, clean, err)
+	}
+	return string(data), nil
+}
+
+func parseWhiteboardStartTag(raw string) (whiteboardStartTag, error) {
+	trimmed := strings.TrimSpace(raw)
+	selfClosing := strings.HasSuffix(trimmed, "/>")
+	decoder := xml.NewDecoder(strings.NewReader(raw))
+	for {
+		tok, err := decoder.Token()
+		if err != nil {
+			if errors.Is(err, io.EOF) {
+				break
+			}
+			return whiteboardStartTag{}, err
+		}
+		start, ok := tok.(xml.StartElement)
+		if !ok {
+			continue
+		}
+		if start.Name.Local != whiteboardTag {
+			return whiteboardStartTag{}, fmt.Errorf("expected <%s>, got <%s>", whiteboardTag, start.Name.Local)
+		}
+		attrs := make([]whiteboardAttr, 0, len(start.Attr))
+		for _, attr := range start.Attr {
+			attrs = append(attrs, whiteboardAttr{Name: attr.Name.Local, Value: attr.Value})
+		}
+		return whiteboardStartTag{Attrs: attrs, SelfClosing: selfClosing}, nil
+	}
+	return whiteboardStartTag{}, fmt.Errorf("missing start element")
+}
+
+func (t *whiteboardStartTag) attr(name string) (string, bool) {
+	for _, attr := range t.Attrs {
+		if attr.Name == name {
+			return attr.Value, true
+		}
+	}
+	return "", false
+}
+
+func (t *whiteboardStartTag) hasAttr(name string) bool {
+	_, ok := t.attr(name)
+	return ok
+}
+
+func (t *whiteboardStartTag) removeAttrs(names ...string) {
+	newAttrs := make([]whiteboardAttr, 0, len(t.Attrs))
+	for _, attr := range t.Attrs {
+		keep := true
+		for _, name := range names {
+			if attr.Name == name {
+				keep = false
+				break
+			}
+		}
+		if keep {
+			newAttrs = append(newAttrs, attr)
+		}
+	}
+	t.Attrs = newAttrs
+}
+
+func (t whiteboardStartTag) render(selfClosing bool) string {
+	var b strings.Builder
+	b.WriteByte('<')
+	b.WriteString(whiteboardTag)
+	for _, attr := range t.Attrs {
+		b.WriteByte(' ')
+		b.WriteString(attr.Name)
+		b.WriteString(`="`)
+		b.WriteString(escapeXMLAttr(attr.Value))
+		b.WriteByte('"')
+	}
+	if selfClosing {
+		b.WriteString("/>")
+	} else {
+		b.WriteByte('>')
+	}
+	if t.SelfClosing && !selfClosing {
+		b.WriteString("</")
+		b.WriteString(whiteboardTag)
+		b.WriteByte('>')
+	}
+	return b.String()
+}
+

shortcuts/doc/whiteboard_inline_test.go

@@ -0,0 +1,118 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"testing"
+)
+
+func TestIsValidWhiteboardType(t *testing.T) {
+	tests := []struct {
+		typ  string
+		want bool
+	}{
+		{"raw", true},
+		{"plantuml", true},
+		{"mermaid", true},
+		{"svg", true},
+		{"", false},
+		{"unknown", false},
+		{"RAW", false},
+		{"PlantUML", false},
+	}
+	for _, tt := range tests {
+		got := isValidWhiteboardType(tt.typ)
+		if got != tt.want {
+			t.Errorf("isValidWhiteboardType(%q) = %v, want %v", tt.typ, got, tt.want)
+		}
+	}
+}
+
+func TestParseWhiteboardStartTag(t *testing.T) {
+	tests := []struct {
+		name    string
+		raw     string
+		wantErr bool
+		attrs   map[string]string
+	}{
+		{
+			name:    "path attribute",
+			raw:     `<whiteboard type="plantuml" path="@./diagram.puml">`,
+			wantErr: false,
+			attrs:   map[string]string{"type": "plantuml", "path": "@./diagram.puml"},
+		},
+		{
+			name:    "self-closing",
+			raw:     `<whiteboard token="abc"/>`,
+			wantErr: false,
+			attrs:   map[string]string{"token": "abc"},
+		},
+		{
+			name:    "no attributes",
+			raw:     `<whiteboard>`,
+			wantErr: false,
+			attrs:   map[string]string{},
+		},
+	}
+	for _, tt := range tests {
+		got, err := parseWhiteboardStartTag(tt.raw)
+		if (err != nil) != tt.wantErr {
+			t.Errorf("%s: parseWhiteboardStartTag(%q) error = %v, wantErr = %v", tt.name, tt.raw, err, tt.wantErr)
+			continue
+		}
+		if err != nil {
+			continue
+		}
+		for k, want := range tt.attrs {
+			gotVal, ok := got.attr(k)
+			if !ok {
+				t.Errorf("%s: expected attr %q not found", tt.name, k)
+			} else if gotVal != want {
+				t.Errorf("%s: attr %q = %q, want %q", tt.name, k, gotVal, want)
+			}
+		}
+	}
+}
+
+func TestRemoveAttrs(t *testing.T) {
+	tag := whiteboardStartTag{
+		Attrs: []whiteboardAttr{
+			{Name: "type", Value: "plantuml"},
+			{Name: "path", Value: "@./diagram.puml"},
+		},
+	}
+	tag.removeAttrs("path")
+	if _, ok := tag.attr("path"); ok {
+		t.Error("path attribute should have been removed")
+	}
+	if _, ok := tag.attr("type"); !ok {
+		t.Error("type attribute should still exist")
+	}
+}
+
+func TestRenderWhiteboardStartTag(t *testing.T) {
+	tag := whiteboardStartTag{
+		Attrs: []whiteboardAttr{
+			{Name: "type", Value: "plantuml"},
+		},
+	}
+	result := tag.render(false)
+	if result != `<whiteboard type="plantuml">` {
+		t.Errorf("render() = %q, want %q", result, `<whiteboard type="plantuml">`)
+	}
+}
+
+func TestWhiteboardStartTagHasAttr(t *testing.T) {
+	tag := whiteboardStartTag{
+		Attrs: []whiteboardAttr{
+			{Name: "type", Value: "plantuml"},
+		},
+	}
+	if !tag.hasAttr("type") {
+		t.Error("should have type attr")
+	}
+	if tag.hasAttr("path") {
+		t.Error("should not have path attr")
+	}
+}

shortcuts/drive/drive_import_common.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 
@@ -28,6 +29,8 @@ 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
@@ -47,6 +50,8 @@ 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
@@ -427,11 +432,7 @@ func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveIm
 			return status, true, nil
 		}
 		if status.Failed() {
-			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)
+			return status, false, driveImportFailureError(status)
 		}
 	}
 	if !hadSuccessfulPoll && lastErr != nil {
@@ -440,3 +441,40 @@ 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,6 +7,7 @@ import (
 	"bytes"
 	"errors"
 	"os"
+	"strconv"
 	"strings"
 	"testing"
 
@@ -211,6 +212,82 @@ 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)"},
+		{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: "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,31 +66,24 @@ var MinutesSpeakerReplace = common.Shortcut{
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
-		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))).
+		return common.NewDryRunAPI().
+			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"))
-		fromSpeakerInput := strings.TrimSpace(runtime.Str("from-speaker-id"))
+		fromSpeakerID := strings.TrimSpace(runtime.Str("from-speaker-id"))
+		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
 		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
 
-		fromSpeakerID, fromUserID, err := resolveSpeakerReplaceFrom(runtime, minuteToken)
-		if err != nil {
-			return err
-		}
-
-		_, err = runtime.CallAPITyped(http.MethodPut,
+		_, 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(fromSpeakerInput, fromSpeakerID, fromUserID))
+			return minutesSpeakerReplaceError(err, minuteToken, speakerReplaceSourceLabel(fromSpeakerID, fromUserID))
 		}
 
-		runtime.OutFormat(buildSpeakerReplaceOutputData(fromSpeakerInput, minuteToken, fromSpeakerID, fromUserID, toUserID), nil, nil)
+		runtime.OutFormat(buildSpeakerReplaceOutputData(minuteToken, fromSpeakerID, fromUserID, toUserID), nil, nil)
 		return nil
 	},
 }
@@ -114,26 +107,20 @@ func buildSpeakerReplaceRequestBodyResolved(fromSpeakerID, fromUserID, toUserID
 	return body
 }
 
-func buildSpeakerReplaceOutputData(fromSpeakerInput, minuteToken, fromSpeakerID, fromUserID, toUserID string) map[string]interface{} {
+func buildSpeakerReplaceOutputData(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(fromSpeakerInput, fromSpeakerID, fromUserID string) string {
-	if fromSpeakerInput != "" {
-		return fromSpeakerInput
-	}
+func speakerReplaceSourceLabel(fromSpeakerID, fromUserID string) string {
 	if fromSpeakerID != "" {
 		return fromSpeakerID
 	}

shortcuts/minutes/minutes_speaker_replace_test.go

@@ -153,58 +153,14 @@ func TestMinutesSpeakerReplace_DryRun(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) {
+func TestMinutesSpeakerReplace_Execute_OpaqueSpeakerIDNoPrefetch(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	warmTokenCache(t)
 
-	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",
-					},
-				},
-			},
-		},
-	})
+	// 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.MethodPut,
 		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speaker",
@@ -218,7 +174,7 @@ func TestMinutesSpeakerReplace_Execute_ResolveFromSpeakerID(t *testing.T) {
 	err := mountAndRun(t, MinutesSpeakerReplace, []string{
 		"+speaker-replace",
 		"--minute-token", minutesSpeakerReplaceTestToken,
-		"--from-speaker-id", "说话人1",
+		"--from-speaker-id", "ENCRYPTED_TOKEN_ABC",
 		"--to-user-id", "ou_new_speaker",
 		"--format", "json", "--as", "user",
 	}, f, stdout)
@@ -228,21 +184,19 @@ func TestMinutesSpeakerReplace_Execute_ResolveFromSpeakerID(t *testing.T) {
 
 	var envelope struct {
 		Data struct {
-			MinuteToken      string `json:"minute_token"`
-			FromSpeakerInput string `json:"from_speaker_input"`
-			FromSpeakerID    string `json:"from_speaker_id"`
-			ToUserID         string `json:"to_user_id"`
+			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) {
@@ -262,8 +216,11 @@ func TestMinutesSpeakerReplace_DryRun_FromSpeakerID(t *testing.T) {
 	}
 
 	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("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, "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

@@ -1,104 +0,0 @@
-// 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

@@ -1,45 +0,0 @@
-// 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,18 +205,16 @@ 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 grouping.
+// Sheets backward-compatibility help 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. 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.
+// 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.
 const (
 	sheetsCurrentGroupID = "sheets-current"
 	// sheetsDeprecatedGroupID aliases the shared deprecated-group id so both
@@ -226,10 +224,9 @@ const (
 )
 
 // sheetsAliasReplacement maps each pre-refactor sheets alias to the current
-// 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.
+// 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.
 var sheetsAliasReplacement = map[string]string{
 	// spreadsheet / sheet management
 	"+create":       "+workbook-create",
@@ -282,43 +279,6 @@ 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:"},
@@ -350,11 +310,6 @@ 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,6 +170,27 @@ 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))
@@ -511,11 +532,10 @@ func TestApplySheetsCompatGroups(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) {
+// 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) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))
 
@@ -531,25 +551,19 @@ func TestRegisterShortcutsSheetsHelpHidesDeprecatedAliases(t *testing.T) {
 	}
 	got := out.String()
 
-	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{
+	for _, want := range []string{
+		"Available Commands:",
 		"Deprecated pre-refactor commands",
 		"update your lark-sheets skill",
 		"+read",
+		"(→ +cells-get)",
 		"+write",
+		"(→ +cells-set)",
 	} {
-		if strings.Contains(got, unwanted) {
-			t.Fatalf("sheets help still shows deprecated content %q:\n%s", unwanted, got)
+		if !strings.Contains(got, want) {
+			t.Fatalf("sheets help missing %q:\n%s", want, 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,7 +5,6 @@ package backward
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"path/filepath"
 	"strings"
@@ -18,30 +17,20 @@ 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_" (being renamed to
-// "local_office_") and the backend requires "office_sheet_file" instead.
+// synthetic token prefixed with "fake_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 either the
-// "fake_office_" or "local_office_" imported-spreadsheet token prefix to
-// "office_sheet_file".
+// uploading an image whose parent_node is spreadsheetToken, mapping the
+// "fake_office_" imported-spreadsheet token prefix to "office_sheet_file".
 func sheetMediaParentType(spreadsheetToken string) string {
-	for _, prefix := range officeTokenPrefixes {
-		if strings.HasPrefix(spreadsheetToken, prefix) {
-			return officeSheetFileParentType
-		}
+	if strings.HasPrefix(spreadsheetToken, fakeOfficeTokenPrefix) {
+		return officeSheetFileParentType
 	}
 	return sheetImageParentType
 }
@@ -146,8 +135,7 @@ func validateSheetMediaUploadFile(runtime *common.RuntimeContext, filePath strin
 	stat, err := runtime.FileIO().Stat(filePath)
 	if err != nil {
 		wrapped := common.WrapInputStatErrorTyped(err, "file not found")
-		var v *errs.ValidationError
-		if errors.As(wrapped, &v) {
+		if v, ok := wrapped.(*errs.ValidationError); ok {
 			return "", nil, v.WithParam("--file")
 		}
 		return "", nil, wrapped

shortcuts/sheets/batch_op_contract_test.go

@@ -102,8 +102,8 @@ func TestBatchOp_BodyMatchesStandalone(t *testing.T) {
 		{
 			shortcut: "+rows-resize",
 			sc:       RowsResize,
-			args:     []string{"--sheet-id", "sh1", "--range", "1", "--height", "30"},
-			subInput: `{"sheet-id":"sh1","range":"1","height":30}`,
+			args:     []string{"--sheet-id", "sh1", "--range", "1", "--type", "pixel", "--size", "30"},
+			subInput: `{"sheet-id":"sh1","range":"1","type":"pixel","size":30}`,
 		},
 		{
 			shortcut: "+cols-resize",
@@ -409,12 +409,12 @@ func TestBatchOp_ErrorEquivalence(t *testing.T) {
 			wantContains: "--count must be > 0",
 		},
 		{
-			name:         "+rows-resize --height with --type standard",
+			name:         "+rows-resize --type pixel without --size",
 			shortcut:     RowsResize,
-			args:         []string{"--sheet-id", "sh1", "--range", "1:2", "--height", "30", "--type", "standard"},
+			args:         []string{"--sheet-id", "sh1", "--range", "1:2", "--type", "pixel"},
 			subShortcut:  "+rows-resize",
-			subInput:     `{"sheet-id":"sh1","range":"1:2","height":30,"type":"standard"}`,
-			wantContains: "--height cannot be combined with --type standard",
+			subInput:     `{"sheet-id":"sh1","range":"1:2","type":"pixel"}`,
+			wantContains: "--type pixel requires --size",
 		},
 		{
 			name:         "+sheet-delete missing sheet selector",
@@ -469,34 +469,6 @@ func TestBatchOp_ErrorEquivalence(t *testing.T) {
 	}
 }
 
-// TestBatchOp_RejectsResizeMapForm locks the nesting guard: the map form
-// (--widths/--heights) expands into its own batch_update, and batch_update
-// cannot nest, so a +batch-update sub-op carrying `widths`/`heights` must be
-// rejected with a pointer to the standalone form — it is standalone-valid,
-// so this case cannot live in the standalone-vs-batch equivalence table.
-func TestBatchOp_RejectsResizeMapForm(t *testing.T) {
-	t.Parallel()
-	cases := []struct {
-		shortcut string
-		input    string
-	}{
-		{"+cols-resize", `{"sheet-id":"sh1","widths":{"A":100}}`},
-		{"+rows-resize", `{"sheet-id":"sh1","heights":{"1":50}}`},
-	}
-	for _, tc := range cases {
-		t.Run(tc.shortcut, func(t *testing.T) {
-			t.Parallel()
-			var subInput map[string]interface{}
-			if err := json.Unmarshal([]byte(tc.input), &subInput); err != nil {
-				t.Fatalf("bad input JSON: %v", err)
-			}
-			rawOp := map[string]interface{}{"shortcut": tc.shortcut, "input": subInput}
-			_, err := translateBatchOp(rawOp, testToken, 0)
-			requireValidation(t, err, "not supported inside +batch-update")
-		})
-	}
-}
-
 // TestBatchOp_RejectsWrongScalarType locks the type-check that closes the
 // silent-coercion gap: `operations` skips parse-time schema validation, and
 // mapFlagView coerces a mismatched scalar to its zero value, so a sub-op field
@@ -639,10 +611,10 @@ func TestBatchOp_RejectsBadSubOpInput(t *testing.T) {
 			"--position is required",
 		},
 		{
-			"+rows-resize missing both --height and --type",
+			"+rows-resize missing --type",
 			"+rows-resize",
 			`{"sheet-id":"sh1","range":"1:1"}`,
-			"give --height <px> for a pixel size, or --type standard / auto",
+			"--type is required",
 		},
 		{
 			"+range-copy missing --target-range",
@@ -830,7 +802,7 @@ func TestBatchOp_DispatchCoversReportedBugs(t *testing.T) {
 	// bare single-element ranges.
 	body = parseDryRunBody(t, BatchUpdate, []string{
 		"--url", testURL,
-		"--operations", `[{"shortcut":"+rows-resize","input":{"sheet-id":"sh1","range":"23","height":40}}]`,
+		"--operations", `[{"shortcut":"+rows-resize","input":{"sheet-id":"sh1","range":"23","type":"pixel","size":40}}]`,
 		"--yes",
 	})
 	ops = decodeToolInput(t, body, "batch_update")["operations"].([]interface{})

shortcuts/sheets/batch_op_dispatch.go

@@ -118,19 +118,10 @@ var batchOpDispatch = map[string]batchOpMapping{
 	}},
 
 	// ─── 行高列宽 (resize_range, 无 operation 字段) ─────────────────
-	// The map form (--heights/--widths) fans out into its own batch_update
-	// and cannot nest inside +batch-update; sub-ops must use the uniform
-	// single-range form (range + height/width or type).
 	"+rows-resize": {"resize_range", func(fv flagView, token, sid, sname string) (map[string]interface{}, error) {
-		if err := rejectResizeMapInBatch(fv, "row"); err != nil {
-			return nil, err
-		}
 		return resizeInput(fv, token, sid, sname, "row")
 	}},
 	"+cols-resize": {"resize_range", func(fv flagView, token, sid, sname string) (map[string]interface{}, error) {
-		if err := rejectResizeMapInBatch(fv, "column"); err != nil {
-			return nil, err
-		}
 		return resizeInput(fv, token, sid, sname, "column")
 	}},
 
@@ -341,21 +332,11 @@ 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/csv_put_stdin_fallback_test.go

@@ -1,92 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package sheets
-
-import (
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-)
-
-// +csv-put lets a piped CSV satisfy an omitted --csv: agents routinely redirect
-// a file into stdin but forget the `--csv -`. PostMount relaxes the required
-// gate and installs a PreRunE that, when stdin is a non-interactive pipe,
-// defaults an absent --csv to "-" so the standard stdin path reads it. On an
-// interactive terminal the fallback stays off so the command never blocks.
-func mountCsvPut(t *testing.T) *cobra.Command {
-	t.Helper()
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	parent := &cobra.Command{Use: "sheets"}
-	CsvPut.Mount(parent, f)
-	cmd, _, err := parent.Find([]string{"+csv-put"})
-	if err != nil {
-		t.Fatalf("Find(+csv-put) error = %v", err)
-	}
-	return cmd
-}
-
-func csvRequiredAnnotationPresent(cmd *cobra.Command) bool {
-	fl := cmd.Flags().Lookup("csv")
-	if fl == nil {
-		return false
-	}
-	_, ok := fl.Annotations[cobra.BashCompOneRequiredFlag]
-	return ok
-}
-
-// withStdinIsPipe swaps the package-level pipe detector for the duration of a
-// test so behavior does not depend on the real process stdin.
-func withStdinIsPipe(t *testing.T, piped bool) {
-	t.Helper()
-	prev := csvPutStdinIsPipe
-	csvPutStdinIsPipe = func() bool { return piped }
-	t.Cleanup(func() { csvPutStdinIsPipe = prev })
-}
-
-func TestCsvPutPostMount_RelaxesCsvRequired(t *testing.T) {
-	cmd := mountCsvPut(t)
-	if csvRequiredAnnotationPresent(cmd) {
-		t.Error("--csv required annotation should be relaxed so csvPutInput reports the typed error")
-	}
-	if cmd.PreRunE == nil {
-		t.Fatal("PostMount should install a PreRunE for the stdin fallback")
-	}
-}
-
-func TestCsvPutPreRunE_PipedAbsentDefaultsToDash(t *testing.T) {
-	withStdinIsPipe(t, true)
-	cmd := mountCsvPut(t)
-	if err := cmd.PreRunE(cmd, nil); err != nil {
-		t.Fatalf("PreRunE error = %v", err)
-	}
-	if got, _ := cmd.Flags().GetString("csv"); got != "-" {
-		t.Errorf("csv = %q, want %q (piped + absent should default to '-')", got, "-")
-	}
-}
-
-func TestCsvPutPreRunE_InteractiveAbsentStaysEmpty(t *testing.T) {
-	withStdinIsPipe(t, false)
-	cmd := mountCsvPut(t)
-	if err := cmd.PreRunE(cmd, nil); err != nil {
-		t.Fatalf("PreRunE error = %v", err)
-	}
-	if got, _ := cmd.Flags().GetString("csv"); got != "" {
-		t.Errorf("csv = %q, want empty (interactive stdin must not be consumed / must not hang)", got)
-	}
-}
-
-func TestCsvPutPreRunE_ExplicitValueUnchanged(t *testing.T) {
-	withStdinIsPipe(t, true)
-	cmd := mountCsvPut(t)
-	if err := cmd.Flags().Set("csv", "x,y"); err != nil {
-		t.Fatalf("Set(csv) error = %v", err)
-	}
-	if err := cmd.PreRunE(cmd, nil); err != nil {
-		t.Fatalf("PreRunE error = %v", err)
-	}
-	if got, _ := cmd.Flags().GetString("csv"); got != "x,y" {
-		t.Errorf("csv = %q, want %q (explicit value must not be overridden)", got, "x,y")
-	}
-}

shortcuts/sheets/data/flag-defs.json

@@ -1,59 +1,4 @@
 {
-  "+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": [
@@ -80,32 +25,6 @@
       }
     ]
   },
-  "+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": [
@@ -154,18 +73,6 @@
         "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",
-        "enum": [
-          "sheet",
-          "bitable"
-        ]
-      },
       {
         "name": "dry-run",
         "kind": "system",
@@ -312,7 +219,7 @@
         "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",
+        "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"
       },
       {
@@ -608,7 +515,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 (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",
+        "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": [
           "file",
           "stdin"
@@ -1162,7 +1069,7 @@
         "kind": "own",
         "type": "int",
         "required": "optional",
-        "desc": "Group nesting level to ungroup; default 1 (1 = outermost, larger = deeper)",
+        "desc": "Group nesting level to ungroup; default 1 (outermost)",
         "default": "1"
       },
       {
@@ -1804,13 +1711,6 @@
         "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",
@@ -2394,43 +2294,32 @@
         "required": "xor",
         "desc": "Sheet name (XOR with `--sheet-id`)"
       },
-      {
-        "name": "height",
-        "kind": "own",
-        "type": "int",
-        "required": "xor",
-        "desc": "Uniform row height in pixels (e.g. 30 / 40 / 60; NOT points), used with `--range`. Passing --height implies pixel mode; --type may be omitted (or set to `pixel` — equivalent). For per-row heights use `--heights`",
-        "default": "0"
-      },
-      {
-        "name": "heights",
-        "kind": "own",
-        "type": "string",
-        "required": "xor",
-        "desc": "Per-row height map — set different heights for many rows in one atomic call. Keys: single row (`\"1\"`) or closed range (`\"2:20\"`); values: pixel height (e.g. 30 / 50), `\"auto\"` (fit content) or `\"standard\"` (reset to default). Units are pixels, NOT points. Mutually exclusive with `--range` / `--height` / `--type`",
-        "input": [
-          "file",
-          "stdin"
-        ]
-      },
       {
         "name": "type",
         "kind": "own",
         "type": "string",
-        "required": "xor",
-        "desc": "Sizing mode: `pixel` (requires `--height`) / `standard` (reset to default row height) / `auto` (fit content). Passing --height alone is the common form; `--type standard` / `--type auto` cannot be combined with `--height`",
+        "required": "required",
+        "desc": "Sizing mode: `pixel` (explicit px value, requires `--size`) / `standard` (reset to default row height) / `auto` (fit content)",
         "enum": [
           "pixel",
           "standard",
           "auto"
         ]
       },
+      {
+        "name": "size",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "Row height in pixels (e.g. 30 / 40 / 60); required when `--type pixel`, ignored otherwise",
+        "default": "0"
+      },
       {
         "name": "range",
         "kind": "own",
         "type": "string",
-        "required": "xor",
-        "desc": "Row closed range to resize; 1-based row numbers like `2:10` or `5` (single row). Required for the uniform form (with `--height` or `--type`); omit with the map form (`--heights`)"
+        "required": "required",
+        "desc": "Row closed range to resize; 1-based row numbers like `2:10` or `5` (single row)"
       },
       {
         "name": "dry-run",
@@ -2472,42 +2361,31 @@
         "required": "xor",
         "desc": "Sheet name (XOR with `--sheet-id`)"
       },
-      {
-        "name": "width",
-        "kind": "own",
-        "type": "int",
-        "required": "xor",
-        "desc": "Uniform column width in pixels (e.g. 80 / 120 / 200; NOT Excel character units), used with `--range`. Passing --width implies pixel mode; --type may be omitted (or set to `pixel` — equivalent). For per-column widths use `--widths`",
-        "default": "0"
-      },
-      {
-        "name": "widths",
-        "kind": "own",
-        "type": "string",
-        "required": "xor",
-        "desc": "Per-column width map — set different widths for many columns in one atomic call. Keys: single column (`\"A\"`) or closed range (`\"C:E\"`); values: pixel width (e.g. 80 / 120 / 200) or `\"standard\"` (reset to default). Units are pixels, NOT Excel character units (px ≈ chars × 8 + 16). Mutually exclusive with `--range` / `--width` / `--type`",
-        "input": [
-          "file",
-          "stdin"
-        ]
-      },
       {
         "name": "type",
         "kind": "own",
         "type": "string",
-        "required": "xor",
-        "desc": "Sizing mode: `pixel` (requires `--width`) / `standard` (reset to default column width). Passing --width alone is the common form; `--type standard` cannot be combined with `--width`",
+        "required": "required",
+        "desc": "Sizing mode: `pixel` (explicit px value, requires `--size`) / `standard` (reset to default column width)",
         "enum": [
           "pixel",
           "standard"
         ]
       },
+      {
+        "name": "size",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "Column width in pixels (e.g. 80 / 120 / 200); required when `--type pixel`, ignored otherwise",
+        "default": "0"
+      },
       {
         "name": "range",
         "kind": "own",
         "type": "string",
-        "required": "xor",
-        "desc": "Column closed range to resize; column letters like `A:E` or `C` (single column). Required for the uniform form (with `--width` or `--type`); omit with the map form (`--widths`)"
+        "required": "required",
+        "desc": "Column closed range to resize; column letters like `A:E` or `C` (single column)"
       },
       {
         "name": "dry-run",
@@ -2861,7 +2739,7 @@
         "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",
+        "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": [
           "file",
           "stdin"
@@ -2881,13 +2759,6 @@
         "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",
@@ -3014,7 +2885,7 @@
         "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",
+        "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": [
           "file",
           "stdin"
@@ -3094,7 +2965,7 @@
         "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",
+        "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": [
           "file",
           "stdin"
@@ -3138,7 +3009,7 @@
         "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",
+        "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": [
           "file",
           "stdin"
@@ -3256,7 +3127,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`); 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.",
+        "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": [
           "file",
           "stdin"
@@ -4195,7 +4066,7 @@
         "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`"
+        "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": "dry-run",
@@ -4876,138 +4747,5 @@
         "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": ""
-      }
-    ]
-  },
-  "+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\"]`, 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: "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: "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,10 +38,9 @@ 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\"]`, 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: "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: "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"}},
@@ -166,7 +165,6 @@ 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"}},
@@ -190,15 +188,6 @@ 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{
@@ -206,7 +195,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`); 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: "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: "dry-run", Kind: "system", Type: "bool", Required: "optional", Desc: "Print the request template; no side effects"},
 		},
 	},
@@ -252,10 +241,9 @@ 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: "width", Kind: "own", Type: "int", Required: "xor", Desc: "Uniform column width in pixels (e.g. 80 / 120 / 200; NOT Excel character units), used with `--range`. Passing --width implies pixel mode; --type may be omitted (or set to `pixel` — equivalent). For per-column widths use `--widths`", Default: "0"},
-			{Name: "widths", Kind: "own", Type: "string", Required: "xor", Desc: "Per-column width map — set different widths for many columns in one atomic call. Keys: single column (`\"A\"`) or closed range (`\"C:E\"`); values: pixel width (e.g. 80 / 120 / 200) or `\"standard\"` (reset to default). Units are pixels, NOT Excel character units (px ≈ chars × 8 + 16). Mutually exclusive with `--range` / `--width` / `--type`", Input: []string{"file", "stdin"}},
-			{Name: "type", Kind: "own", Type: "string", Required: "xor", Desc: "Sizing mode: `pixel` (requires `--width`) / `standard` (reset to default column width). Passing --width alone is the common form; `--type standard` cannot be combined with `--width`", Enum: []string{"pixel", "standard"}},
-			{Name: "range", Kind: "own", Type: "string", Required: "xor", Desc: "Column closed range to resize; column letters like `A:E` or `C` (single column). Required for the uniform form (with `--width` or `--type`); omit with the map form (`--widths`)"},
+			{Name: "type", Kind: "own", Type: "string", Required: "required", Desc: "Sizing mode: `pixel` (explicit px value, requires `--size`) / `standard` (reset to default column width)", Enum: []string{"pixel", "standard"}},
+			{Name: "size", Kind: "own", Type: "int", Required: "optional", Desc: "Column width in pixels (e.g. 80 / 120 / 200); required when `--type pixel`, ignored otherwise", Default: "0"},
+			{Name: "range", Kind: "own", Type: "string", Required: "required", Desc: "Column closed range to resize; column letters like `A:E` or `C` (single column)"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -417,7 +405,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 (1 = outermost, larger = deeper)", Default: "1"},
+			{Name: "depth", Kind: "own", Type: "int", Required: "optional", Desc: "Group nesting level to ungroup; default 1 (outermost)", 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"},
 		},
@@ -438,7 +426,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\"]`, 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: "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: "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"},
 		},
@@ -475,7 +463,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\"]`, 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: "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: "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"},
@@ -538,7 +526,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; 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 on create, kept unchanged when omitted on update; takes precedence over the same-named field inside `--properties`"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -644,45 +632,6 @@ 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{
@@ -785,14 +734,6 @@ 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{
@@ -800,10 +741,9 @@ 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: "height", Kind: "own", Type: "int", Required: "xor", Desc: "Uniform row height in pixels (e.g. 30 / 40 / 60; NOT points), used with `--range`. Passing --height implies pixel mode; --type may be omitted (or set to `pixel` — equivalent). For per-row heights use `--heights`", Default: "0"},
-			{Name: "heights", Kind: "own", Type: "string", Required: "xor", Desc: "Per-row height map — set different heights for many rows in one atomic call. Keys: single row (`\"1\"`) or closed range (`\"2:20\"`); values: pixel height (e.g. 30 / 50), `\"auto\"` (fit content) or `\"standard\"` (reset to default). Units are pixels, NOT points. Mutually exclusive with `--range` / `--height` / `--type`", Input: []string{"file", "stdin"}},
-			{Name: "type", Kind: "own", Type: "string", Required: "xor", Desc: "Sizing mode: `pixel` (requires `--height`) / `standard` (reset to default row height) / `auto` (fit content). Passing --height alone is the common form; `--type standard` / `--type auto` cannot be combined with `--height`", Enum: []string{"pixel", "standard", "auto"}},
-			{Name: "range", Kind: "own", Type: "string", Required: "xor", Desc: "Row closed range to resize; 1-based row numbers like `2:10` or `5` (single row). Required for the uniform form (with `--height` or `--type`); omit with the map form (`--heights`)"},
+			{Name: "type", Kind: "own", Type: "string", Required: "required", Desc: "Sizing mode: `pixel` (explicit px value, requires `--size`) / `standard` (reset to default row height) / `auto` (fit content)", Enum: []string{"pixel", "standard", "auto"}},
+			{Name: "size", Kind: "own", Type: "int", Required: "optional", Desc: "Row height in pixels (e.g. 30 / 40 / 60); required when `--type pixel`, ignored otherwise", Default: "0"},
+			{Name: "range", Kind: "own", Type: "string", Required: "required", Desc: "Row closed range to resize; 1-based row numbers like `2:10` or `5` (single row)"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -828,7 +768,6 @@ 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", Enum: []string{"sheet", "bitable"}},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -883,7 +822,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 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: "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: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -1002,7 +941,7 @@ var flagDefs = map[string]commandDef{
 		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 (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: "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: "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,6 +6,7 @@ package sheets
 import (
 	_ "embed"
 	"encoding/json"
+	"fmt"
 	"sort"
 	"sync"
 
@@ -53,7 +54,7 @@ func loadFlagSchemas() (*flagSchemaIndex, error) {
 	flagSchemasOnce.Do(func() {
 		var idx flagSchemaIndex
 		if err := json.Unmarshal(flagSchemasJSON, &idx); err != nil {
-			parseFlagErr = errs.NewInternalError(errs.SubtypeUnknown, "flag-schemas.json: %v", err).WithCause(err)
+			parseFlagErr = fmt.Errorf("flag-schemas.json: %w", 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)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
+			return fmt.Errorf("%sexpected type %q, got %q", pathPrefix(path), schema.Type, jsType(value))
 		}
 	}
 
@@ -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) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
+			return fmt.Errorf("%svalue %v is below minimum %v", pathPrefix(path), num, *schema.Minimum)
 		}
 		if schema.Maximum != nil && 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
+			return fmt.Errorf("%svalue %v is above maximum %v", pathPrefix(path), num, *schema.Maximum)
 		}
 	}
 
 	// 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) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
+			return fmt.Errorf("%sarray has %d items, minimum is %d", pathPrefix(path), len(arr), *schema.MinItems)
 		}
 		if schema.MaxItems != nil && 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
+			return fmt.Errorf("%sarray has %d items, maximum is %d", pathPrefix(path), len(arr), *schema.MaxItems)
 		}
 	}
 
@@ -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) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
+			return fmt.Errorf("%s", msg)
 		}
 	}
 
@@ -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)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
+			return fmt.Errorf("%svalue does not match any of oneOf alternatives", pathPrefix(path))
 		}
 	}
 
@@ -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)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
+				return fmt.Errorf("required property %q is missing at %s", key, pathOrRoot(path))
 			}
 		}
 		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) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
+					return fmt.Errorf("%sunexpected property %q (not declared in schema)", pathPrefix(path), key)
 				}
 				if schema.AdditionalProperties.Schema != nil {
 					child := key

shortcuts/sheets/flag_schemas_gen.go

@@ -19,7 +19,6 @@ var commandsWithSchema = map[string]struct{}{
 	"+cells-set-style":       {},
 	"+chart-create":          {},
 	"+chart-update":          {},
-	"+cols-resize":           {},
 	"+cond-format-create":    {},
 	"+cond-format-update":    {},
 	"+dropdown-set":          {},
@@ -31,7 +30,6 @@ var commandsWithSchema = map[string]struct{}{
 	"+pivot-create":          {},
 	"+pivot-update":          {},
 	"+range-sort":            {},
-	"+rows-resize":           {},
 	"+sparkline-create":      {},
 	"+sparkline-update":      {},
 	"+table-put":             {},

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)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
+				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val))
 			}
 			if math.Trunc(f) != f {
-				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
+				return fmt.Errorf("--%s must be an integer, got %s", name, strconv.FormatFloat(f, 'g', -1, 64))
 			}
 		case "float64":
 			if _, isNum := val.(float64); !isNum {
-				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
+				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val))
 			}
 		case "bool":
 			if _, isBool := val.(bool); !isBool {
-				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
+				return fmt.Errorf("--%s must be a boolean, got %s", name, jsonTypeName(val))
 			}
 		}
 	}

shortcuts/sheets/helpers.go

@@ -10,7 +10,6 @@ package sheets
 import (
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
 	neturl "net/url"
 	"strings"
@@ -45,8 +44,7 @@ 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)
-	var v *errs.ValidationError
-	if errors.As(wrapped, &v) {
+	if v, ok := wrapped.(*errs.ValidationError); ok {
 		return v.WithParam(sheetsFlagParam(flag))
 	}
 	return wrapped
@@ -54,30 +52,21 @@ 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_" (being renamed to
-// "local_office_") and the backend requires "office_sheet_file" instead.
+// synthetic token prefixed with "fake_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 {
-	for _, prefix := range officeTokenPrefixes {
-		if strings.HasPrefix(spreadsheetToken, prefix) {
-			return officeSheetFileParentType
-		}
+	if strings.HasPrefix(spreadsheetToken, fakeOfficeTokenPrefix) {
+		return officeSheetFileParentType
 	}
 	return sheetImageParentType
 }
@@ -451,7 +440,7 @@ func requireJSONArray(runtime flagView, name string) ([]interface{}, error) {
 
 // ─── style flags (shared by +cells-set-style and +cells-batch-set-style) ─
 
-// buildCellStyleFromFlags reads the 12 flat style flags and returns the
+// buildCellStyleFromFlags reads the 11 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{} {
@@ -462,9 +451,6 @@ 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,8 +215,7 @@ func cellsBatchSetStyleInput(runtime *common.RuntimeContext, token string) (map[
 	if borderStyles != nil {
 		prototype["border_styles"] = borderStyles
 	}
-	ops := make([]interface{}, 0, len(ranges))
-	var totalCells int64
+	var ops []interface{}
 	for _, rng := range ranges {
 		sheet, sub, err := splitSheetPrefixedRange(rng)
 		if err != nil {
@@ -226,13 +225,6 @@ 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",
@@ -307,7 +299,7 @@ func cellsBatchClearInput(runtime *common.RuntimeContext, token string) (map[str
 		return nil, err
 	}
 	clearType := normalizeClearType(runtime.Str("scope"))
-	ops := make([]interface{}, 0, len(ranges))
+	var ops []interface{}
 	for _, rng := range ranges {
 		sheet, sub, err := splitSheetPrefixedRange(rng)
 		if err != nil {
@@ -390,10 +382,13 @@ var DropdownDelete = common.Shortcut{
 		if _, err := resolveSpreadsheetToken(runtime); err != nil {
 			return err
 		}
-		// validateDropdownRanges enforces the shared maxBatchRanges cap.
-		if _, err := validateDropdownRanges(runtime); err != nil {
+		ranges, err := validateDropdownRanges(runtime)
+		if 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 {
@@ -437,8 +432,7 @@ func dropdownBatchInput(runtime *common.RuntimeContext, token string, clear bool
 		}
 		prototype = map[string]interface{}{"data_validation": validation}
 	}
-	ops := make([]interface{}, 0, len(ranges))
-	var totalCells int64
+	var ops []interface{}
 	for _, rng := range ranges {
 		sheet, sub, err := splitSheetPrefixedRange(rng)
 		if err != nil {
@@ -448,13 +442,6 @@ 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",
@@ -474,25 +461,6 @@ 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) {
@@ -522,9 +490,6 @@ 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_batch_update_test.go

@@ -447,7 +447,7 @@ func TestBatchUpdate_ResizeNoOperationField(t *testing.T) {
 	t.Parallel()
 	body := parseDryRunBody(t, BatchUpdate, []string{
 		"--url", testURL,
-		"--operations", `[{"shortcut":"+rows-resize","input":{"sheet_id":"sh1","range":"1:3","height":30}}]`,
+		"--operations", `[{"shortcut":"+rows-resize","input":{"sheet_id":"sh1","range":"1:3","type":"pixel","size":30}}]`,
 		"--yes",
 	})
 	input := decodeToolInput(t, body, "batch_update")

shortcuts/sheets/lark_sheet_changeset.go

@@ -1,105 +0,0 @@
-// 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

@@ -1,86 +0,0 @@
-// 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

@@ -1,167 +0,0 @@
-// 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

@@ -1,213 +0,0 @@
-// 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

@@ -1,97 +0,0 @@
-// 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

@@ -1,197 +0,0 @@
-// 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

@@ -1,167 +0,0 @@
-// 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_range_operations.go

@@ -5,8 +5,6 @@ package sheets
 
 import (
 	"context"
-	"fmt"
-	"sort"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
@@ -210,81 +208,37 @@ func mergeInput(runtime flagView, token, sheetID, sheetName, op string, withMerg
 	return input, nil
 }
 
-// resize_range exposes two CLI shortcuts, each with two input forms:
+// resize_range exposes two CLI shortcuts:
 //
-//   +rows-resize / +cols-resize — set row heights / column widths.
-//
-//   Uniform form: --range + --height/--width <px>; the pixel mode is implied
-//   so --type can be omitted (or set to `pixel` — equivalent). Non-pixel
-//   modes go through --type standard / --type auto (rows only) and cannot be
-//   combined with the pixel flag. --range is an A1 closed range ("2:10" /
-//   "5" rows or "A:E" / "C" columns); single-element form is expanded to
-//   "N:N" before send because resize_range rejects bare single-element
-//   ranges.
-//
-//   Map form: --heights / --widths carries a JSON object of per-row/column
-//   sizes ({"A": 100, "C:E": 120, "G": "standard"}) and fans out into one
-//   atomic batch_update of resize_range ops — different sizes for many
-//   rows/columns in a single CLI call, no +batch-update needed. Mutually
-//   exclusive with --range/--height/--width/--type, and not accepted as a
-//   +batch-update sub-op (nested batch_update is unsupported upstream).
+//   +rows-resize / +cols-resize — set row heights / column widths. --type
+//   enum (pixel / standard / [auto]) controls how: --type pixel needs --size,
+//   --type standard restores the sheet default, --type auto auto-fits row
+//   heights (rows only). --range is an A1 closed range ("2:10" / "5" rows or
+//   "A:E" / "C" columns); single-element form is expanded to "N:N" before
+//   send because resize_range rejects bare single-element ranges.
 //
 // Wire shape: resize_height / resize_width carries { type, value? }, e.g.
 //   { "type": "pixel", "value": 30 }  or  { "type": "standard" }.
-//
-// Units are pixels. Column widths in Excel character units (openpyxl /
-// xlsxwriter mental model, px ≈ chars × 8 + 16) are a real agent trap, so
-// widths below minSaneColumnWidthPx are rejected with a conversion hint.
 
-// RowsResize wraps resize_range for row heights. Pass --range + --height
-// <px> for a uniform pixel height, --heights '{"1":50,"2:20":30}' for
-// per-row heights, or --type standard/auto for non-pixel modes.
+// RowsResize wraps resize_range for row heights. --type auto enables
+// auto-fit (rows only); --type pixel requires --size.
 var RowsResize = common.Shortcut{
 	Service:     "sheets",
 	Command:     "+rows-resize",
-	Description: "Resize rows in pixels: --range + --height <px> for one uniform height, --heights '{\"1\":50,\"2:20\":30,\"21\":\"auto\"}' for per-row heights in one atomic call, or --type standard/auto (--range is 1-based A1 like \"2:10\" or \"5\").",
+	Description: "Resize rows by pixel / standard / auto (--type pixel needs --size; --range is 1-based A1 like \"2:10\" or \"5\").",
 	Risk:        "write",
 	Scopes:      []string{"sheets:spreadsheet:write_only"},
 	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags:       flagsFor("+rows-resize"),
 	Validate:    validateViaResize("row"),
-	DryRun:      resizeDryRun("row"),
-	Execute:     resizeExecute("row"),
-}
-
-// ColsResize wraps resize_range for column widths. Pass --range + --width
-// <px> for a uniform pixel width, --widths '{"A":100,"C:E":120}' for
-// per-column widths, or --type standard for the default width. Column
-// widths do not support auto-fit — --type does not accept auto.
-var ColsResize = common.Shortcut{
-	Service:     "sheets",
-	Command:     "+cols-resize",
-	Description: "Resize columns in pixels (NOT Excel char units): --range + --width <px> for one uniform width, --widths '{\"A\":100,\"C:E\":120}' for per-column widths in one atomic call, or --type standard to reset (--range is column letters like \"A:E\" or \"C\"; no auto for cols).",
-	Risk:        "write",
-	Scopes:      []string{"sheets:spreadsheet:write_only"},
-	AuthTypes:   []string{"user", "bot"},
-	HasFormat:   true,
-	Flags:       flagsFor("+cols-resize"),
-	Validate:    validateViaResize("column"),
-	DryRun:      resizeDryRun("column"),
-	Execute:     resizeExecute("column"),
-}
-
-// resizeDryRun / resizeExecute route a resize shortcut through resizeToolCall
-// so the uniform form hits resize_range and the map form hits batch_update
-// with identical inputs in preview and execution.
-func resizeDryRun(dimension string) func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	return func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		token, _ := resolveSpreadsheetToken(runtime)
 		sheetID, sheetName, _ := resolveSheetSelector(runtime)
-		toolName, input, _ := resizeToolCall(runtime, token, sheetID, sheetName, dimension)
-		return invokeToolDryRun(token, ToolKindWrite, toolName, input)
-	}
-}
-
-func resizeExecute(dimension string) func(ctx context.Context, runtime *common.RuntimeContext) error {
-	return func(ctx context.Context, runtime *common.RuntimeContext) error {
+		input, _ := resizeInput(runtime, token, sheetID, sheetName, "row")
+		return invokeToolDryRun(token, ToolKindWrite, "resize_range", input)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, err := resolveSpreadsheetTokenExec(runtime)
 		if err != nil {
 			return err
@@ -293,21 +247,62 @@ func resizeExecute(dimension string) func(ctx context.Context, runtime *common.R
 		if err != nil {
 			return err
 		}
-		toolName, input, err := resizeToolCall(runtime, token, sheetID, sheetName, dimension)
+		input, err := resizeInput(runtime, token, sheetID, sheetName, "row")
 		if err != nil {
 			return err
 		}
-		out, err := callTool(ctx, runtime, token, ToolKindWrite, toolName, input)
+		out, err := callTool(ctx, runtime, token, ToolKindWrite, "resize_range", input)
 		if err != nil {
 			return err
 		}
 		runtime.Out(out, nil)
 		return nil
-	}
+	},
 }
 
-// validateViaResize wires the standalone Validate to resizeToolCall so both
-// forms (uniform + map) are fully validated before execution.
+// ColsResize wraps resize_range for column widths. Column widths do not
+// support auto-fit — --type only accepts pixel / standard.
+var ColsResize = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+cols-resize",
+	Description: "Resize columns by pixel / standard (--type pixel needs --size; --range is column letters like \"A:E\" or \"C\"; no auto for cols).",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       flagsFor("+cols-resize"),
+	Validate:    validateViaResize("column"),
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		sheetID, sheetName, _ := resolveSheetSelector(runtime)
+		input, _ := resizeInput(runtime, token, sheetID, sheetName, "column")
+		return invokeToolDryRun(token, ToolKindWrite, "resize_range", input)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		sheetID, sheetName, err := resolveSheetSelector(runtime)
+		if err != nil {
+			return err
+		}
+		input, err := resizeInput(runtime, token, sheetID, sheetName, "column")
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindWrite, "resize_range", input)
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+// validateViaResize wires the standalone Validate to resizeInput so both
+// paths (standalone + batch sub-op) emit the same error for missing --type,
+// malformed --range, or --type auto on columns.
 func validateViaResize(dimension string) func(ctx context.Context, runtime *common.RuntimeContext) error {
 	return func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, err := resolveSpreadsheetToken(runtime)
@@ -316,82 +311,17 @@ func validateViaResize(dimension string) func(ctx context.Context, runtime *comm
 		}
 		sheetID := strings.TrimSpace(runtime.Str("sheet-id"))
 		sheetName := strings.TrimSpace(runtime.Str("sheet-name"))
-		_, _, err = resizeToolCall(runtime, token, sheetID, sheetName, dimension)
+		_, err = resizeInput(runtime, token, sheetID, sheetName, dimension)
 		return err
 	}
 }
 
-// resizeToolCall picks the input form: map form (--heights/--widths) builds a
-// batch_update of resize_range ops; uniform form builds a single resize_range
-// input. Returns the tool name to invoke alongside its input.
-func resizeToolCall(runtime flagView, token, sheetID, sheetName, dimension string) (string, map[string]interface{}, error) {
-	if runtime.Changed(sizeMapFlag(dimension)) {
-		input, err := resizeMapInput(runtime, token, sheetID, sheetName, dimension)
-		return "batch_update", input, err
-	}
-	input, err := resizeInput(runtime, token, sheetID, sheetName, dimension)
-	return "resize_range", input, err
-}
-
-// nonPixelTypes lists the --type values a given dimension accepts (rows also
-// accept auto; columns only accept standard). Used to shape the hint printed
-// when --type is missing or invalid.
-func nonPixelTypes(dimension string) string {
+// autoSuffix appends " / auto" to the enum hint for rows.
+func autoSuffix(dimension string) string {
 	if dimension == "row" {
-		return "standard / auto"
+		return " / auto"
 	}
-	return "standard"
-}
-
-// pixelFlag maps a dimension to its pixel-value flag name (--height for rows,
-// --width for cols). The wire block always emits "pixel" as the mode; the
-// per-dimension flag name is just the surface knob.
-func pixelFlag(dimension string) string {
-	if dimension == "row" {
-		return "height"
-	}
-	return "width"
-}
-
-// sizeMapFlag maps a dimension to its map-form flag name (--heights for rows,
-// --widths for cols).
-func sizeMapFlag(dimension string) string {
-	return pixelFlag(dimension) + "s"
-}
-
-// rejectResizeMapInBatch blocks the map form inside +batch-update sub-ops:
-// it expands into its own batch_update and nesting batch_update is
-// unsupported upstream. Called by the batch dispatch closures only — the
-// standalone path routes the map form through resizeMapInput instead.
-func rejectResizeMapInBatch(fv flagView, dimension string) error {
-	mapFlag := sizeMapFlag(dimension)
-	if !fv.Changed(mapFlag) {
-		return nil
-	}
-	return sheetsValidationForFlag(mapFlag,
-		"%q is not supported inside +batch-update (it expands into its own atomic batch); call %s --%s standalone, or give each sub-op the single-range form (range + %s/type)",
-		mapFlag, commandForDimension(dimension), mapFlag, pixelFlag(dimension))
-}
-
-// minSaneColumnWidthPx is the floor below which a column width almost
-// certainly means the caller thought in Excel character units (openpyxl /
-// xlsxwriter widths run 8-30 chars) instead of pixels. 10px columns are
-// unusable; real pixel spacer columns start around 20px.
-const minSaneColumnWidthPx = 20
-
-// checkPixelSize validates a pixel value for one dimension. label names the
-// offending input in the error ("--width" for the uniform flag, "--widths
-// key \"A\"" for a map entry).
-func checkPixelSize(dimension, flagName, label string, px int) error {
-	if px <= 0 {
-		return sheetsValidationForFlag(flagName, "%s must be > 0", label)
-	}
-	if dimension == "column" && px < minSaneColumnWidthPx {
-		return sheetsValidationForFlag(flagName,
-			"%s = %dpx is below %dpx and looks like an Excel character-unit width — column widths here are pixels (px ≈ chars × 8 + 16, so %d chars ≈ %dpx)",
-			label, px, minSaneColumnWidthPx, px, px*8+16)
-	}
-	return nil
+	return ""
 }
 
 // commandForDimension returns the shortcut command name a given dimension
@@ -409,11 +339,6 @@ func commandForDimension(dimension string) string {
 // dimension (row → digits like "2:10" / "5"; column → letters like "A:E" /
 // "C"). Single-element form is expanded to "N:N" because resize_range
 // rejects bare single-element ranges.
-//
-// Surface: pixel size goes through --height / --width (dimension-specific).
-// --type is optional when the pixel flag is present (defaults to "pixel");
-// explicit --type pixel is accepted and equivalent. --type standard / auto
-// select non-pixel modes and cannot be combined with the pixel flag.
 func resizeInput(runtime flagView, token, sheetID, sheetName, dimension string) (map[string]interface{}, error) {
 	if err := requireSheetSelector(sheetID, sheetName); err != nil {
 		return nil, err
@@ -436,42 +361,29 @@ func resizeInput(runtime flagView, token, sheetID, sheetName, dimension string)
 	if !strings.Contains(rangeStr, ":") {
 		rangeStr = rangeStr + ":" + rangeStr
 	}
-
-	sizeFlag := pixelFlag(dimension)
-	hasSize := runtime.Changed(sizeFlag)
 	typ := strings.TrimSpace(runtime.Str("type"))
-	hasType := typ != ""
-
-	if !hasSize && !hasType {
-		return nil, common.ValidationErrorf("give --%s <px> for a pixel size, or --type %s", sizeFlag, nonPixelTypes(dimension)).WithParams(sheetsInvalidParam(sizeFlag, "required"), sheetsInvalidParam("type", "required"))
+	if typ == "" {
+		return nil, sheetsValidationForFlag("type", "--type is required (pixel / standard%s)", autoSuffix(dimension))
 	}
-	if hasSize && hasType && typ != "pixel" {
-		return nil, common.ValidationErrorf("--%s cannot be combined with --type %s", sizeFlag, typ).WithParams(sheetsInvalidParam(sizeFlag, "mutually exclusive"), sheetsInvalidParam("type", "mutually exclusive"))
-	}
-	if hasType && dimension == "column" && typ == "auto" {
+	if dimension == "column" && typ == "auto" {
 		return nil, sheetsValidationForFlag("type", "--type auto is rows-only (column widths do not support auto-fit); use +rows-resize")
 	}
-	if hasType && typ == "pixel" && !hasSize {
-		return nil, common.ValidationErrorf("--type pixel requires --%s <px>", sizeFlag).WithParams(sheetsInvalidParam("type", "required"), sheetsInvalidParam(sizeFlag, "required"))
+	hasSize := runtime.Changed("size") && runtime.Int("size") > 0
+	if typ == "pixel" && !hasSize {
+		return nil, common.ValidationErrorf("--type pixel requires --size <px>").WithParams(sheetsInvalidParam("type", "required"), sheetsInvalidParam("size", "required"))
 	}
-
-	sizeBlock := map[string]interface{}{}
-	if hasSize {
-		px := runtime.Int(sizeFlag)
-		if err := checkPixelSize(dimension, sizeFlag, "--"+sizeFlag, px); err != nil {
-			return nil, err
-		}
-		sizeBlock["type"] = "pixel"
-		sizeBlock["value"] = px
-	} else {
-		sizeBlock["type"] = typ
+	if typ != "pixel" && hasSize {
+		return nil, common.ValidationErrorf("--size is only valid with --type pixel").WithParams(sheetsInvalidParam("size", "mutually exclusive"), sheetsInvalidParam("type", "mutually exclusive"))
 	}
-
 	input := map[string]interface{}{
 		"excel_id": token,
 		"range":    rangeStr,
 	}
 	sheetSelectorForToolInput(input, sheetID, sheetName)
+	sizeBlock := map[string]interface{}{"type": typ}
+	if typ == "pixel" {
+		sizeBlock["value"] = runtime.Int("size")
+	}
 	if dimension == "row" {
 		input["resize_height"] = sizeBlock
 	} else {
@@ -480,122 +392,6 @@ func resizeInput(runtime flagView, token, sheetID, sheetName, dimension string)
 	return input, nil
 }
 
-// resizeMapInput builds the batch_update input for the map form: every
-// --heights/--widths entry becomes one resize_range op inside a single atomic
-// batch. Keys are single rows/columns ("5" / "A") or closed ranges ("2:8" /
-// "C:E") matching the command's dimension; values are positive pixel ints or
-// the non-pixel mode strings ("standard", and "auto" for rows). Ops are
-// sorted by start position so dry-run output and execution order are
-// deterministic (JSON object order is not preserved by Go maps).
-func resizeMapInput(runtime flagView, token, sheetID, sheetName, dimension string) (map[string]interface{}, error) {
-	if err := requireSheetSelector(sheetID, sheetName); err != nil {
-		return nil, err
-	}
-	mapFlag := sizeMapFlag(dimension)
-	for _, other := range []string{"range", pixelFlag(dimension), "type"} {
-		if runtime.Changed(other) {
-			return nil, common.ValidationErrorf("--%s is a self-contained map; do not combine it with --%s", mapFlag, other).WithParams(sheetsInvalidParam(mapFlag, "mutually exclusive"), sheetsInvalidParam(other, "mutually exclusive"))
-		}
-	}
-	parsed, err := parseJSONFlag(runtime, mapFlag)
-	if err != nil {
-		return nil, err
-	}
-	entries, ok := parsed.(map[string]interface{})
-	if !ok || parsed == nil {
-		return nil, sheetsValidationForFlag(mapFlag, "--%s must be a JSON object like {\"%s\": 100}", mapFlag, exampleMapKey(dimension))
-	}
-	if len(entries) == 0 {
-		return nil, sheetsValidationForFlag(mapFlag, "--%s must contain at least one entry", mapFlag)
-	}
-
-	type resizeOp struct {
-		start int
-		input map[string]interface{}
-	}
-	ops := make([]resizeOp, 0, len(entries))
-	seen := make(map[string]string, len(entries)) // normalized range → original key
-	for key, raw := range entries {
-		parsedDim, startIdx, _, err := parseA1Range(key)
-		if err != nil {
-			return nil, sheetsValidationForFlag(mapFlag, "--%s key %q: %v", mapFlag, key, err)
-		}
-		if parsedDim != dimension {
-			want := "row numbers (e.g. \"2:10\")"
-			if dimension == "column" {
-				want = "column letters (e.g. \"A:E\")"
-			}
-			return nil, sheetsValidationForFlag(mapFlag, "--%s key %q is a %s range; %s expects %s", mapFlag, key, parsedDim, commandForDimension(dimension), want)
-		}
-		normalized := strings.TrimSpace(key)
-		if !strings.Contains(normalized, ":") {
-			normalized = normalized + ":" + normalized
-		}
-		if prev, dup := seen[normalized]; dup {
-			return nil, sheetsValidationForFlag(mapFlag, "--%s keys %q and %q target the same range %s; merge them into one entry", mapFlag, prev, key, normalized)
-		}
-		seen[normalized] = key
-
-		sizeBlock := map[string]interface{}{}
-		switch v := raw.(type) {
-		case float64:
-			px := int(v)
-			if float64(px) != v {
-				return nil, sheetsValidationForFlag(mapFlag, "--%s[%q] must be an integer pixel value, got %v", mapFlag, key, v)
-			}
-			if err := checkPixelSize(dimension, mapFlag, fmt.Sprintf("--%s[%q]", mapFlag, key), px); err != nil {
-				return nil, err
-			}
-			sizeBlock["type"] = "pixel"
-			sizeBlock["value"] = px
-		case string:
-			mode := strings.TrimSpace(v)
-			if mode == "auto" && dimension == "column" {
-				return nil, sheetsValidationForFlag(mapFlag, "--%s[%q]: \"auto\" is rows-only (column widths do not support auto-fit); estimate a pixel width instead (px ≈ chars × 8 + 16)", mapFlag, key)
-			}
-			if mode != "standard" && !(mode == "auto" && dimension == "row") {
-				return nil, sheetsValidationForFlag(mapFlag, "--%s[%q] = %q is invalid; use a pixel integer or %s", mapFlag, key, v, nonPixelTypes(dimension))
-			}
-			sizeBlock["type"] = mode
-		default:
-			return nil, sheetsValidationForFlag(mapFlag, "--%s[%q] must be a pixel integer or a mode string (%s), got %s", mapFlag, key, nonPixelTypes(dimension), jsonTypeName(raw))
-		}
-
-		opInput := map[string]interface{}{
-			"excel_id": token,
-			"range":    normalized,
-		}
-		sheetSelectorForToolInput(opInput, sheetID, sheetName)
-		if dimension == "row" {
-			opInput["resize_height"] = sizeBlock
-		} else {
-			opInput["resize_width"] = sizeBlock
-		}
-		ops = append(ops, resizeOp{start: startIdx, input: opInput})
-	}
-
-	sort.Slice(ops, func(i, j int) bool { return ops[i].start < ops[j].start })
-	operations := make([]interface{}, 0, len(ops))
-	for _, op := range ops {
-		operations = append(operations, map[string]interface{}{
-			"tool_name": "resize_range",
-			"input":     op.input,
-		})
-	}
-	return map[string]interface{}{
-		"excel_id":   token,
-		"operations": operations,
-	}, nil
-}
-
-// exampleMapKey renders a dimension-appropriate sample key for error hints.
-func exampleMapKey(dimension string) string {
-	if dimension == "row" {
-		return "2:10"
-	}
-	return "A"
-}
-
 // ─── transform_range (4 shortcuts) ────────────────────────────────────
 //
 // move / copy take --source-range + --target-range (+ optional cross-sheet

shortcuts/sheets/lark_sheet_range_operations_test.go

@@ -113,9 +113,9 @@ func TestRangeOperationsShortcuts_DryRun(t *testing.T) {
 			},
 		},
 		{
-			name:     "+rows-resize --range 1:5 --height 200",
+			name:     "+rows-resize --range 1:5 pixel 200",
 			sc:       RowsResize,
-			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--height", "200"},
+			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--type", "pixel", "--size", "200"},
 			toolName: "resize_range",
 			wantInput: map[string]interface{}{
 				"excel_id": testToken,
@@ -138,7 +138,7 @@ func TestRangeOperationsShortcuts_DryRun(t *testing.T) {
 			},
 		},
 		{
-			name:     "+cols-resize --range B:D --type standard",
+			name:     "+cols-resize --range B:D standard",
 			sc:       ColsResize,
 			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "B:D", "--type", "standard"},
 			toolName: "resize_range",
@@ -152,22 +152,9 @@ func TestRangeOperationsShortcuts_DryRun(t *testing.T) {
 			},
 		},
 		{
-			name:     "+cols-resize --range A:C --width 120",
+			name:     "+cols-resize --range A:C pixel 120",
 			sc:       ColsResize,
-			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A:C", "--width", "120"},
-			toolName: "resize_range",
-			wantInput: map[string]interface{}{
-				"range": "A:C",
-				"resize_width": map[string]interface{}{
-					"type":  "pixel",
-					"value": float64(120),
-				},
-			},
-		},
-		{
-			name:     "+cols-resize --type pixel with --width 120 (explicit == implicit)",
-			sc:       ColsResize,
-			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A:C", "--type", "pixel", "--width", "120"},
+			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A:C", "--type", "pixel", "--size", "120"},
 			toolName: "resize_range",
 			wantInput: map[string]interface{}{
 				"range": "A:C",
@@ -309,163 +296,6 @@ func TestRangeSort_RejectsMalformedKeys(t *testing.T) {
 	}
 }
 
-// TestResize_MapForm covers the --widths/--heights map form: entries fan out
-// into one atomic batch_update of resize_range ops, sorted by start position
-// regardless of JSON key order.
-func TestResize_MapForm(t *testing.T) {
-	t.Parallel()
-
-	t.Run("+cols-resize --widths mixes pixels, ranges and standard", func(t *testing.T) {
-		t.Parallel()
-		body := parseDryRunBody(t, ColsResize, []string{
-			"--url", testURL, "--sheet-id", testSheetID,
-			"--widths", `{"G": "standard", "A": 100, "C:E": 120}`,
-		})
-		input := decodeToolInput(t, body, "batch_update")
-		wantOps := []interface{}{
-			map[string]interface{}{"tool_name": "resize_range", "input": map[string]interface{}{
-				"excel_id": testToken, "sheet_id": testSheetID, "range": "A:A",
-				"resize_width": map[string]interface{}{"type": "pixel", "value": float64(100)},
-			}},
-			map[string]interface{}{"tool_name": "resize_range", "input": map[string]interface{}{
-				"excel_id": testToken, "sheet_id": testSheetID, "range": "C:E",
-				"resize_width": map[string]interface{}{"type": "pixel", "value": float64(120)},
-			}},
-			map[string]interface{}{"tool_name": "resize_range", "input": map[string]interface{}{
-				"excel_id": testToken, "sheet_id": testSheetID, "range": "G:G",
-				"resize_width": map[string]interface{}{"type": "standard"},
-			}},
-		}
-		assertInputEquals(t, input, map[string]interface{}{
-			"excel_id":   testToken,
-			"operations": wantOps,
-		})
-	})
-
-	t.Run("+rows-resize --heights mixes pixels, auto and standard", func(t *testing.T) {
-		t.Parallel()
-		body := parseDryRunBody(t, RowsResize, []string{
-			"--url", testURL, "--sheet-id", testSheetID,
-			"--heights", `{"21": "auto", "1": 50, "2:20": 30}`,
-		})
-		input := decodeToolInput(t, body, "batch_update")
-		wantOps := []interface{}{
-			map[string]interface{}{"tool_name": "resize_range", "input": map[string]interface{}{
-				"excel_id": testToken, "sheet_id": testSheetID, "range": "1:1",
-				"resize_height": map[string]interface{}{"type": "pixel", "value": float64(50)},
-			}},
-			map[string]interface{}{"tool_name": "resize_range", "input": map[string]interface{}{
-				"excel_id": testToken, "sheet_id": testSheetID, "range": "2:20",
-				"resize_height": map[string]interface{}{"type": "pixel", "value": float64(30)},
-			}},
-			map[string]interface{}{"tool_name": "resize_range", "input": map[string]interface{}{
-				"excel_id": testToken, "sheet_id": testSheetID, "range": "21:21",
-				"resize_height": map[string]interface{}{"type": "auto"},
-			}},
-		}
-		assertInputEquals(t, input, map[string]interface{}{
-			"excel_id":   testToken,
-			"operations": wantOps,
-		})
-	})
-}
-
-// TestResize_MapFormGuards covers map-form validation: exclusivity with the
-// uniform flags, key/value shape errors, the char-unit width floor, and the
-// +batch-update nesting rejection.
-func TestResize_MapFormGuards(t *testing.T) {
-	t.Parallel()
-	cases := []struct {
-		name string
-		sc   common.Shortcut
-		args []string
-		want string
-	}{
-		{
-			name: "--widths rejects --range",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--widths", `{"A": 100}`, "--range", "A:C"},
-			want: "--widths is a self-contained map; do not combine it with --range",
-		},
-		{
-			name: "--widths rejects --width",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--widths", `{"A": 100}`, "--width", "120"},
-			want: "--widths is a self-contained map; do not combine it with --width",
-		},
-		{
-			name: "--heights rejects --type",
-			sc:   RowsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--heights", `{"1": 50}`, "--type", "auto"},
-			want: "--heights is a self-contained map; do not combine it with --type",
-		},
-		{
-			name: "--widths empty object",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--widths", `{}`},
-			want: "must contain at least one entry",
-		},
-		{
-			name: "--widths row key on cols command",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--widths", `{"2:8": 100}`},
-			want: "+cols-resize expects column letters",
-		},
-		{
-			name: "--heights column key on rows command",
-			sc:   RowsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--heights", `{"A": 50}`},
-			want: "+rows-resize expects row numbers",
-		},
-		{
-			name: "--widths duplicate keys A and A:A",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--widths", `{"A": 100, "A:A": 120}`},
-			want: "target the same range A:A",
-		},
-		{
-			name: "--widths char-unit width rejected with conversion hint",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--widths", `{"A": 10}`},
-			want: "looks like an Excel character-unit width",
-		},
-		{
-			// The embedded schema (enum ["standard"]) rejects "auto" before the
-			// Go-level rows-only hint; the error steers to --print-schema whose
-			// description explains columns don't support auto.
-			name: "--widths rejects auto (rows-only) via schema",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--widths", `{"A": "auto"}`},
-			want: "does not match any of oneOf alternatives",
-		},
-		{
-			name: "--heights rejects unknown mode string via schema",
-			sc:   RowsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--heights", `{"1": "fit"}`},
-			want: "does not match any of oneOf alternatives",
-		},
-		{
-			name: "--heights rejects boolean value via schema",
-			sc:   RowsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--heights", `{"1": true}`},
-			want: "does not match any of oneOf alternatives",
-		},
-		{
-			name: "--widths bad key syntax",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--widths", `{"A1:B2": 100}`},
-			want: "expected pure digits (row number) or letters",
-		},
-	}
-	for _, tt := range cases {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-			_, _, err := runShortcutCapturingErr(t, tt.sc, append(tt.args, "--dry-run"))
-			requireValidation(t, err, tt.want)
-		})
-	}
-}
-
 func TestResize_TypeAndSizeGuards(t *testing.T) {
 	t.Parallel()
 	cases := []struct {
@@ -475,58 +305,22 @@ func TestResize_TypeAndSizeGuards(t *testing.T) {
 		want string
 	}{
 		{
-			name: "+rows-resize missing both --height and --type",
-			sc:   RowsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5"},
-			want: "give --height <px> for a pixel size, or --type standard / auto",
-		},
-		{
-			name: "+cols-resize missing both --width and --type",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A:C"},
-			want: "give --width <px> for a pixel size, or --type standard",
-		},
-		{
-			name: "+rows-resize --height rejects --type standard",
-			sc:   RowsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--height", "30", "--type", "standard"},
-			want: "--height cannot be combined with --type standard",
-		},
-		{
-			name: "+cols-resize --width rejects --type standard",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A:C", "--width", "120", "--type", "standard"},
-			want: "--width cannot be combined with --type standard",
-		},
-		{
-			name: "+rows-resize --type pixel without --height",
+			name: "+rows-resize --type pixel without --size",
 			sc:   RowsResize,
 			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--type", "pixel"},
-			want: "--type pixel requires --height",
+			want: "--type pixel requires --size",
 		},
 		{
-			name: "+cols-resize --type pixel without --width",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A:C", "--type", "pixel"},
-			want: "--type pixel requires --width",
-		},
-		{
-			name: "+rows-resize --height must be positive",
+			name: "+rows-resize --type standard with --size",
 			sc:   RowsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--height", "0"},
-			want: "--height must be > 0",
-		},
-		{
-			name: "+cols-resize --width below 20px rejected with char-unit hint",
-			sc:   ColsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A:C", "--width", "12"},
-			want: "looks like an Excel character-unit width",
+			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--type", "standard", "--size", "30"},
+			want: "--size is only valid with --type pixel",
 		},
 		{
 			name: "+cols-resize rejects --type auto",
 			sc:   ColsResize,
 			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A:C", "--type", "auto"},
-			want: "auto", // cobra Enum gate kicks first with "valid values are: standard"
+			want: "auto", // cobra Enum gate kicks first with "valid values are: pixel, standard"
 		},
 		{
 			name: "+rows-resize given column range",

shortcuts/sheets/lark_sheet_revision_get.go

@@ -1,83 +0,0 @@
-// 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

@@ -1,37 +0,0 @@
-// 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") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
+		return "", 0, 0, fmt.Errorf("range is empty")
 	}
 	parts := strings.Split(s, ":")
 	if len(parts) > 2 {
-		return "", 0, 0, fmt.Errorf("expected \"start:end\" or single element") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
+		return "", 0, 0, fmt.Errorf("expected \"start:end\" or single element")
 	}
 	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") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
+		return "", 0, 0, fmt.Errorf("cannot mix row (digits) and column (letters) in one range")
 	}
 	if idx2 < idx1 {
-		return "", 0, 0, fmt.Errorf("end position is before start") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
+		return "", 0, 0, fmt.Errorf("end position is before start")
 	}
 	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") //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
+		return "", 0, fmt.Errorf("position is empty")
 	}
 	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) //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
+			return "", 0, fmt.Errorf("row number must be >= 1 (got %q)", s)
 		}
 		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) //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
+	return "", 0, fmt.Errorf("expected pure digits (row number) or letters (column letter), got %q", s)
 }
 
 // columnIndexToLetter converts a 0-based column index to the spreadsheet

shortcuts/sheets/lark_sheet_table_io.go

@@ -382,32 +382,6 @@ 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
 }
 
@@ -669,8 +643,7 @@ func writeSheetData(ctx context.Context, runtime *common.RuntimeContext, token,
 	if err != nil {
 		return nil, err
 	}
-	matrix, err = applyWorkbookCreateStylesToMatrix(matrix, styles, col0, baseRow, fmt.Sprintf("--styles for sheet %q", s.Name))
-	if err != nil {
+	if err := applyWorkbookCreateStylesToMatrix(matrix, styles, col0, baseRow, fmt.Sprintf("--styles for sheet %q", s.Name)); err != nil {
 		return nil, err
 	}
 
@@ -682,15 +655,11 @@ 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 + writeCols - 1)
+	endCol := columnIndexToLetter(col0 + ncols - 1)
 	allowOverwrite := s.AllowOverwrite == nil || *s.AllowOverwrite
 
-	rowsPerBatch := tablePutMaxCellsPerWrite / writeCols
+	rowsPerBatch := tablePutMaxCellsPerWrite / ncols
 	if rowsPerBatch < 1 {
 		rowsPerBatch = 1
 	}
@@ -724,7 +693,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":   writeCols,
+		"columns":   ncols,
 		"writes":    writes,
 		"mode":      writeModeName(s),
 	}, nil
@@ -816,7 +785,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, styles.styleFor(i))
+			rows, cols := sheetCreateDims(s)
 			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
@@ -895,12 +864,10 @@ 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, 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) {
+// 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) {
 	_, col0, row0, _ := sheetAnchor(s)
 	cols = col0 + len(s.Columns)
 	rows = row0 + len(s.Rows)
@@ -915,19 +882,6 @@ func sheetCreateDims(s *tableSheetSpec, styles *workbookCreateStylePayload) (row
 	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
 	}
@@ -1025,6 +979,8 @@ 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>"
@@ -1032,23 +988,10 @@ 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). Padding can widen /
-			// lengthen the matrix past the data, so recompute the range from the
-			// padded dims to match what Execute writes.
+			// (the merges / sizes ops below still render).
 			_, col0, row0, _ := sheetAnchor(s)
-			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))
-			}
+			_ = applyWorkbookCreateStylesToMatrix(matrix, sheetStyles.styleFor(i), col0, row0, fmt.Sprintf("--styles for sheet %q", s.Name))
 		}
-		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,15 +537,14 @@ 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)}, 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},
+		{"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},
 		// 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
@@ -553,22 +552,14 @@ 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)}, nil, 50000, 20},
+			tableSheetSpec{Mode: "append", Columns: cols(3), Rows: rows(49999)}, 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)}, 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},
+			tableSheetSpec{Mode: "append", Header: bp(false), Columns: cols(3), Rows: rows(50)}, 200, 20},
 	}
 	for _, tt := range cases {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-			gotRows, gotCols := sheetCreateDims(&tt.spec, tt.styles)
+			gotRows, gotCols := sheetCreateDims(&tt.spec)
 			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_workbook.go

@@ -123,26 +123,6 @@ 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")
 	}
@@ -654,26 +634,16 @@ var WorkbookCreate = common.Shortcut{
 			s := &payload.Sheets[i]
 			matrix, _ := buildSheetMatrix(s, headerOn(s))
 			_, col0, row0, _ := sheetAnchor(s)
-			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))
-			}
+			_ = applyWorkbookCreateStylesToMatrix(matrix, sheetStyles.styleFor(i), col0, row0, fmt.Sprintf("--styles for sheet %q", s.Name))
 			input := map[string]interface{}{
 				"excel_id":   "<new-token>",
 				"sheet_name": s.Name,
-				"range":      rng,
+				"range":      tablePutFullRange(s, len(matrix)),
 				"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), writeCols)).
+				Desc(fmt.Sprintf("write sheet %q (%d data rows × %d cols) via set_cell_range", s.Name, len(s.Rows), len(s.Columns))).
 				Body(wireBody)
 			appendWorkbookCreateVisualOpsDryRun(dry, "<new-token>", "", s.Name, sheetStyles.styleFor(i))
 		}
@@ -866,19 +836,13 @@ func buildValuesPayload(runtime flagView, sheetStyles *workbookCreateSheetStyles
 		cols[i] = tableColumnSpec{Name: fmt.Sprintf("col%d", i+1)} // type-less
 	}
 	noHeader := false
-	payload := &tablePayload{Sheets: []tableSheetSpec{{
+	return &tablePayload{Sheets: []tableSheetSpec{{
 		Name:    valuesSheetName,
 		Mode:    "overwrite",
 		Header:  &noHeader,
 		Columns: cols,
 		Rows:    rows,
-	}}}
-	// --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
+	}}}, nil
 }
 
 // parseValuesRows decodes --values (JSON 2D array, with @file/stdin already
@@ -1175,14 +1139,10 @@ func parseWorkbookCreateResizeOps(v interface{}, path, dimension string) ([]work
 			}
 			return nil, common.ValidationErrorf("%s[%d].range %q must use %s", path, i, rangeStr, want)
 		}
-		typeHint := "pixel/standard"
-		if dimension == "row" {
-			typeHint = "pixel/standard/auto"
-		}
 		resizeType, _ := op["type"].(string)
 		resizeType = strings.TrimSpace(resizeType)
 		if resizeType == "" {
-			return nil, common.ValidationErrorf("%s[%d].type is required (%s)", path, i, typeHint)
+			return nil, common.ValidationErrorf("%s[%d].type is required (pixel/standard%s)", path, i, autoSuffix(dimension))
 		}
 		if dimension == "column" && resizeType == "auto" {
 			return nil, common.ValidationErrorf("%s[%d].type auto is rows-only", path, i)
@@ -1190,7 +1150,7 @@ func parseWorkbookCreateResizeOps(v interface{}, path, dimension string) ([]work
 		switch resizeType {
 		case "pixel", "standard", "auto":
 		default:
-			return nil, common.ValidationErrorf("%s[%d].type %q is invalid (want %s)", path, i, resizeType, typeHint)
+			return nil, common.ValidationErrorf("%s[%d].type %q is invalid (want pixel/standard%s)", path, i, resizeType, autoSuffix(dimension))
 		}
 		size := 0
 		if raw, ok := op["size"]; ok {
@@ -1286,7 +1246,7 @@ func normalizeWorkbookCreateStyleObject(in map[string]interface{}, path string)
 
 func workbookCreateCellStyleField(name string) bool {
 	switch name {
-	case "font_color", "font_family", "font_size", "font_weight", "font_style", "font_line",
+	case "font_color", "font_size", "font_weight", "font_style", "font_line",
 		"background_color", "horizontal_alignment", "vertical_alignment",
 		"number_format", "word_wrap":
 		return true
@@ -1397,79 +1357,20 @@ func workbookCreateStyleDimensions(styles *workbookCreateStylePayload, baseCol,
 	return rows, cols
 }
 
-// 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{} {
+func applyWorkbookCreateStylesToMatrix(rows [][]interface{}, styles *workbookCreateStylePayload, baseCol, baseRow int, label string) error {
 	if styles == nil {
-		return rows
+		return nil
 	}
-	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 rows, common.ValidationErrorf("%s[%d].range %q: %v", label, i, op.Range, err)
+			return common.ValidationErrorf("%s[%d].range %q: %v", label, i, op.Range, err)
 		}
-		// 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)",
+		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",
 				label, i, op.Range,
-				columnIndexToLetter(baseCol), baseRow+1)
+				columnIndexToLetter(baseCol), baseRow+1,
+				columnIndexToLetter(baseCol+len(rows[0])-1), baseRow+len(rows))
 		}
 		for r := startRow - baseRow; r <= endRow-baseRow; r++ {
 			for c := startCol - baseCol; c <= endCol-baseCol; c++ {
@@ -1477,7 +1378,7 @@ func applyWorkbookCreateStylesToMatrix(rows [][]interface{}, styles *workbookCre
 			}
 		}
 	}
-	return rows, nil
+	return nil
 }
 
 func appendWorkbookCreateVisualOpsDryRun(dry *common.DryRunAPI, token, sheetID, sheetName string, styles *workbookCreateStylePayload) {

shortcuts/sheets/lark_sheet_workbook_test.go

@@ -396,37 +396,6 @@ 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
@@ -626,60 +595,3 @@ 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

@@ -11,7 +11,6 @@ import (
 	_ "image/gif"
 	_ "image/jpeg"
 	_ "image/png"
-	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
@@ -112,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-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.
+// 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",
@@ -166,9 +165,6 @@ 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
 	}
@@ -204,19 +200,6 @@ func cellsSetStyleInput(runtime flagView, token, sheetID, sheetName string) (map
 	return input, nil
 }
 
-// csvPutStdinIsPipe reports whether process stdin is a non-interactive pipe or
-// redirect (rather than an interactive terminal), so an omitted --csv can be
-// satisfied from it without risking a hang on a real terminal. Overridable in
-// tests. A char device is a terminal; anything else (pipe, redirect, /dev/null)
-// counts as piped input.
-var csvPutStdinIsPipe = func() bool {
-	fi, err := os.Stdin.Stat()
-	if err != nil {
-		return false
-	}
-	return fi.Mode()&os.ModeCharDevice == 0
-}
-
 // CsvPut wraps set_range_from_csv: dump a CSV blob into a sheet. A cell whose
 // text starts with = is evaluated as a formula; use +cells-set for styles / notes / images.
 var CsvPut = common.Shortcut{
@@ -239,27 +222,6 @@ var CsvPut = common.Shortcut{
 		}
 		cmd.MarkFlagsOneRequired("start-cell", "range")
 		cmd.MarkFlagsMutuallyExclusive("start-cell", "range")
-
-		// Let a piped CSV satisfy --csv when the flag is omitted: agents
-		// routinely redirect a file into stdin but forget the `--csv -`, so
-		// `+csv-put ... < data.csv` would otherwise fail its first try on a
-		// missing --csv. Relax the required-gate (flag-defs marks --csv
-		// required) so an absent value surfaces csvPutInput's own typed error
-		// instead of cobra's bare "required flag(s) ... not set"; then, in
-		// PreRunE (which cobra runs before it validates required flags), default
-		// an omitted --csv to "-" when stdin is a non-interactive pipe so the
-		// standard stdin-resolution path reads it. The pipe guard means an
-		// interactive terminal never blocks waiting on stdin — a real miss still
-		// errors.
-		if fl := cmd.Flags().Lookup("csv"); fl != nil {
-			delete(fl.Annotations, cobra.BashCompOneRequiredFlag)
-		}
-		cmd.PreRunE = func(c *cobra.Command, _ []string) error {
-			if v, _ := c.Flags().GetString("csv"); strings.TrimSpace(v) == "" && csvPutStdinIsPipe() {
-				_ = c.Flags().Set("csv", "-")
-			}
-			return nil
-		}
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if err := guardCSVValueIsNotFilePath(runtime); err != nil {
@@ -488,9 +450,6 @@ 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
@@ -666,23 +625,23 @@ func rangeDimensions(rangeStr string) (rows, cols int, err error) {
 	}
 	rangeStr = strings.TrimSpace(rangeStr)
 	if rangeStr == "" {
-		return 0, 0, fmt.Errorf("empty range") //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
+		return 0, 0, fmt.Errorf("empty range")
 	}
 	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]) //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
+			return 0, 0, fmt.Errorf("invalid cell ref %q", parts[0])
 		}
 		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) //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
+		return 0, 0, fmt.Errorf("unsupported range form %q (need rectangular A1:B2)", rangeStr)
 	}
 	if endRow < startRow || endCol < startCol {
-		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 0, 0, fmt.Errorf("end %q must be at or after start %q", parts[1], parts[0])
 	}
 	return endRow - startRow + 1, endCol - startCol + 1, nil
 }
@@ -733,30 +692,9 @@ 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_" or
-// "local_office_" synthetic token and must upload with "office_sheet_file".
+// use "sheet_image"; imported "office" spreadsheets carry a "fake_office_"
+// synthetic token and must upload with "office_sheet_file".
 func TestSheetMediaParentType(t *testing.T) {
 	t.Parallel()
 	cases := []struct {
@@ -36,12 +36,9 @@ func TestSheetMediaParentType(t *testing.T) {
 	}{
 		{"native spreadsheet token", "shtcnABC123", sheetImageParentType},
 		{"empty token", "", 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},
+		{"office imported token", "fake_office_abc123", officeSheetFileParentType},
+		{"office token, only the prefix", fakeOfficeTokenPrefix, officeSheetFileParentType},
+		{"prefix mid-string is not matched", "shtfake_office_abc", sheetImageParentType},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
@@ -65,8 +62,7 @@ func TestUploadSheetImage_ParentType(t *testing.T) {
 		wantParentType string
 	}{
 		{"native spreadsheet", "shtcnTOK123", sheetImageParentType},
-		{"fake_office imported spreadsheet", "fake_office_abc123", officeSheetFileParentType},
-		{"local_office imported spreadsheet", "local_office_abc123", officeSheetFileParentType},
+		{"office imported spreadsheet", "fake_office_abc123", officeSheetFileParentType},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {

shortcuts/sheets/sheets_perf_bench_test.go

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

skill-template/domains/drive.md

@@ -6,6 +6,7 @@
 - 用户要把本地 `.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`。
 
@@ -194,6 +195,7 @@ 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,13 +45,15 @@ lark-cli calendar +agenda --as user
 | 场景 | 前置要求 |
 |------|----------|
 | 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
-| 编辑已有日程 | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
+| 编辑已有日程 | 先定位目标日程 `event_id` |
+| 编辑/删除重复性日程 | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，按操作范围（仅此次/全部/此次及后续）执行 |
 | 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
 | 调用任何 Shortcut | 先读其对应 reference 文档 |
 
 ## 核心概念
 
-- **日程实例（Instance）**：重复性日程展开后的具体时间实例。操作重复日程的某次实例时，必须先定位该实例的 `event_id`，禁止使用原重复日程的 `event_id`。
+- **日程实例（Instance）**：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 `event_id`；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 `event_id`），并按需处理例外。
+- **重复性日程例外（Exception）**：对重复性日程某次实例做过「仅此次」编辑后产生的独立日程（拥有独立 `event_id`）。删除/更新「全部」时必须同时处理例外，否则例外会残留。
 - **全天日程（All-day Event）**：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
 - **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
 - **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
@@ -71,6 +73,7 @@ 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,6 +47,7 @@ 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 命令）
 
@@ -72,9 +73,16 @@ 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

@@ -0,0 +1,90 @@
+# 重复性日程操作规范
+
+重复性日程的编辑/删除分为三种范围：「仅此次」「全部」「此次及后续」。用户未明确范围时，**必须询问确认**。
+
+## 关键概念
+
+- **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。重复性日程要先定位到目标实例的 `event_id`，不要直接使用原重复日程 ID |
+| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程请根据操作范围选择 ID，详见 [重复性日程操作规范](lark-calendar-recurring.md) |
 | `--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 添加到参会人列表，不能脱离日程单独预定。
-- 更新重复性日程的某一次实例时，必须先通过 `+agenda`、`+search-event` 或实例视图定位该实例的 `event_id`。
+- 更新重复性日程时，必须先确定操作范围（仅此次/全部/此次及后续），然后按 [重复性日程操作规范](lark-calendar-recurring.md) 执行。
 - 如果需要验证更新结果，等待至少 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 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"
+  cliHelp: "lark-cli docs --help;lark-cli mindnotes --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（可用 callout、grid、checkbox 等富 block）。
+> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML。
 > - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
 
 ## 快速决策
@@ -39,9 +39,10 @@ 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) 的「三、资源块」章节
 - 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
-- 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入
+- 新增或更新画板时，按 [`lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 选型；Mermaid 可由主 Agent 直接插入，SVG / 复杂图 / 已有画板更新按其中流程隔离到 SubAgent
 - 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `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`）
@@ -69,6 +70,7 @@ 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、并行执行策略）
+> 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 串行撰写）
 >
 > **未读完以上文件就生成内容会导致格式错误。**
 
 从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。
 
-> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，支持 callout、grid、checkbox 等富 block 类型）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
+> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，可承载更丰富的结构化内容）。不要在用户没要求的情况下主动从 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、并行执行策略）
-- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）
+- [`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-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

@@ -0,0 +1,107 @@
+# 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、并行执行策略）
+> 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 串行改写）
 >
 > **未读完以上文件就生成内容会导致格式错误。**
 
@@ -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-style.md`](style/lark-doc-style.md) 的「画板语法与插入」章节。
+画板的语法选型与插入示例见 [`lark-doc-xml.md`](lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.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、并行执行策略）
-- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）
+- [`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-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,6 +13,13 @@ 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
@@ -36,6 +43,15 @@ 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（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进
+2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进正文；仅画板渲染按需隔离到 SubAgent（见步骤三）
 3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
 4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
 
@@ -16,44 +16,32 @@
 
 ## 典型 Code-Act Loop 流程
 
-### 步骤一：规划与初始创建（串行）
+### 步骤一：规划与撰写（单 Agent 串行）
+
+正文由主 Agent 串行维护，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效。
 
 1. 分析用户需求：受众、目的、范围
 2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
-3. `docs +create` 创建文档。长文档可**只建骨架**：标题 + 各级标题 + 每节一句占位摘要；短文档可以一次写入完整内容
-   - ⚠️ 创建较长文档时，**不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
-   - 完整内容留到步骤二，由各 Agent 用 `block_insert_after --block-id <章节标题 block_id>` 分段写入。
-   - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理。
+3. `docs +create` 创建并撰写：
+   - **短文档**：一次写入完整内容。使用 Markdown 时，避免同时传入 `--title` 和同名 `# 标题`
+   - **长文档**：先建骨架（标题 + 各级标题），再由主 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 下，用完自行清理
 
-### 步骤二：分段撰写（并行 Agent）
+### 步骤二：整合审查与画板识别（串行）
 
-4. Spawn Agent 并行撰写各章节。每个 Agent 需收到：
-   - 文档 token、负责的章节范围、用户目标、目标读者和已有风格线索
-   - `lark-doc-xml.md` 和 `lark-doc-style.md` 的完整路径（Agent 须先读取）
-   - 使用 `block_insert_after --block-id <章节标题 block_id>` 写入对应章节内容
+4. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
+5. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材；检查跨节有无重复、矛盾或断流。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题就地定向修正
+6. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
 
-### 步骤三：整合审查与画板识别（串行）
+### 步骤三：画板处理与润色
 
-5. `docs +fetch --detail with-ids` 获取文档，审查整体效果
-6. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材
-7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
+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` 插入
 
-### 步骤四：画板处理与润色（并行 Agent）
+### 步骤四：专项校验
 
-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) 路径。它只负责写入画板，不改文档正文。
+9. **字数门禁**：如果用户给出任何明确字数要求（如“700-800 字”“1000 字左右”“不少于 500 字”“控制在 800 字以内”），本步骤必须执行，不属于按需项。读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；未得到脚本统计结果前，不得向用户声明“符合字数要求”。若没有明确字数要求，则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现目标区间、`word_count` 和达标结论
+10. **重复标题检查**：文档生成后，检查文档标题和正文第一个标题块是否重复；若重复，删除或改写正文第一个标题块，避免读者看到同一标题连续出现

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

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

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

@@ -5,7 +5,7 @@
 ## 核心方法论 — Code-Act Loop
 通过自适应的 **Code-Act Loop** 驱动文档改写，而非固定模板式的工作流。每次任务都循环执行：
 1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
-2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进
+2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进改写；仅画板渲染按需隔离到 SubAgent（见步骤二）
 3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
 4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
 
@@ -23,33 +23,26 @@
    - 需要精确跨节区间 → `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)中的方式，插入图表画板。
-6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID：
+5. **优先处理步骤一识别出的画板候选段落**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
+6. 由主 Agent **顺序逐节**改写，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效：
    - 沿用或轻微调整已有文档风格，除非用户要求彻底重排版
-   - 优先通过重写段落、调整标题、拆分列表或补充小标题提升可读性
-   - 富 block 是可选表达手段，不因固定比例而添加；画板类需求只走第 5 步
+   - 优先通过重写段落、调整标题、补充小标题提升可读性；叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）
+   - 富 block 是可选表达手段，不因固定比例而添加，取舍遵循 `lark-doc-style.md` 的写作原则；画板类需求只走第 5 步
 
 ### 步骤三：验证（串行）
 
 7. 获取更新后文档局部内容，检查是否符合用户目标和已有风格
-8. 检查是否满足用户目标并保留原有关键内容；如仍有明显问题则定向修正，向用户呈现结果
+8. 检查是否满足用户目标并保留原有关键内容。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题则定向修正
 
-## Agent 子任务要求
+### 步骤四：专项校验（按需执行）
 
-内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、用户目标/风格要求、具体的 `docs +update` command 和 `--block-id`。
+9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果
 
-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` 精确区间，只拉自己的章节，不要重复拉全文。
+**上下文节省提示**：主 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,6 +29,7 @@ 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`。
@@ -102,6 +103,7 @@ 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,6 +14,13 @@
 > [!IMPORTANT]
 > 当用户**未传 `--name`** 时，文档标题默认取源文件名（去掉扩展名）。在执行导入前，先友好提示用户：「当前未指定文档标题，默认将使用"xxx"作为标题。如果文件内容中也包含相同标题，导入后可能造成视觉重复。是否需要重命名？」让用户确认后再继续。
 
+## 批量导入串行规则
+
+> [!IMPORTANT]
+> 批量执行 `drive +import` 且目标是同一个位置时，必须串行执行，不要并发发起导入任务。这里的“相同位置”包括同一个 `--folder-token`、都省略 `--folder-token` 导入到默认根目录，或使用同一个 `--target-token` 导入到已有 bitable。
+>
+> 如果在同一位置下并发导入，服务端可能返回并发冲突错误。看到错误信息或 `job_error_msg` 中包含 `232140101`、`232140100`、`233523001` 任一错误码时，按同位置并发操作处理：停止并发导入，改为串行处理失败项；每个失败项每次重试前等待几秒，总共最多重试 3 次；仍失败就停止并向用户报告冲突。
+
 ## 命令
 
 ```bash
@@ -143,6 +150,7 @@ 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,6 +23,8 @@
 > 错误：`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 命中的结果过度收窄。
 
 ### 自然语言 → 命令映射速查
@@ -101,7 +103,7 @@ lark-cli drive +search --query 方案 --page-token '<PAGE_TOKEN>'
 
 | 参数 | 必填 | 说明 |
 |---|---|---|
-| `--query <text>` | 否 | 搜索关键词；支持服务端高级语法（`intitle:`、`""`、`OR`、`-`）。空字符串或省略表示纯 filter 浏览 |
+| `--query <text>` | 否 | 搜索关键词；支持服务端高级语法（`intitle:`、`""`、`OR`、`-`）。空字符串或省略表示纯 filter 浏览。**长度上限 30 个字符（按 Unicode 码点算，中文每字算 1 个，与 ASCII 同口径）；超过 30 服务端直接报 `99992402 field validation failed`，不会截断** |
 | `--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,6 +81,8 @@ 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

@@ -146,6 +146,24 @@ lark-cli update
 
 **重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
 
+## JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同：
+
+成功信封写入 **stdout**（退出码 0）：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**（退出码非 0）：
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+**判断成功必须用 `ok == true`（或进程退出码 0），不要用 `code == 0`**：成功信封没有顶层 `code` / `msg` 字段，`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。按 OpenAPI 老格式 `{"code": 0, "msg": "ok"}` 判断会把所有成功调用误判为失败；封装写入类命令（如 `task +create`）时尤其危险，误判会绕过幂等逻辑导致重复创建。
+
 ## 安全规则
 
 - **禁止输出密钥**（appSecret、accessToken）到终端明文。

skills/lark-sheets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-sheets
-version: 3.0.2
+version: 3.0.0
 description: "飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作原子批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）、金融/财务建模（DCF、三张表、预算、Sensitivity 等）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
@@ -32,124 +32,57 @@ 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 见各工具参考。**选定命令后别急着写——先读「动手前读」列指向的 reference 再动手**：命令名对得上不代表用法对，写入 / 清除 / 透视类尤其容易漏掉 reference 里的防错、类型与样式继承规则。
+把高频意图映射到**真实存在**的 shortcut / flag。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。
 
-| 你要做的事 | ✅ 正确写法 | 动手前读 | ❌ 不存在（会被 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`） |
+| 你要做的事 | ✅ 正确写法 | ❌ 不存在（会被 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 / 本地脚本拼一张假透视表 |
 
-> ⚠️ **动手前的触发式必读（按动作判定，不看主场景）**：本次操作只要**涉及样式 / 美化**（底色 / 边框 / 字号 / 对齐 / 数字格式 / 汇总行 / 配色 / 列宽行高），动手前先读 `lark-sheets-visual-standards`；只要**要写飞书公式**，动手前先读 `lark-sheets-formula-translation`（飞书函数与 Excel 有差异，凭直觉迁移易错），**写完后再读 `lark-sheets-formula-verify` 并执行 `+formula-verify` 收尾**。哪怕主任务是"建表 / 展开数据 / 录入"，只要动作里含美化或写公式就适用——别因"这不算专门的美化 / 公式任务"而跳过。
 > ⚠️ **两种图片别选错**：图若**绑定某条记录、要随行排序 / 筛选 / 增删**（凭证 / 证件照 / 每行配图，话里带「对应 / 每行 / 这列」等绑定词）→ 单元格图片 `+cells-set-image`；只是自由摆放的装饰（logo / 水印 / 封面）→ 浮动图片 `+float-image-create`。别因「浮动图更好控制 / 更熟」默认选浮动图。
-> ⚠️ **纯文本还是数值语义（看数据本质，不看当下用途）**：金额 / 百分比 / 比率 / 计数 / 日期等**本质是量值**的数据 → 一律数值写入，常规二维表用 `+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` 单独一步）。
+> ⚠️ **纯文本还是数值语义**：要写的列里有数字 / 金额 / 百分比 / 日期 / 计数 → `+table-put`（写入已有表；外层 `{"sheets":[...]}` 包裹、列 pandas dtype 用 `dtypes`、展示格式用 `formats`，保留排序 / 求和 / 图表 / 透视能力；**目标表还不存在就用 `+workbook-create --sheets`**，同 typed 协议、一步建表 + 写入，别先建空表再 `+table-put`）；只有纯文本才用 `+csv-put`。两者写完显示可以完全相同，但 `+csv-put` 落的是文本、不能参与计算——别把数值在本地拼成带 `$` / `%` 的字符串再走 `+csv-put`。
 > ⚠️ **定位 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-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`。 |
+| [飞书表格核心操作：分析、编辑与可视化](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、日期差、多层范围结果与二次展开）时使用。 |
 
 ### 按对象的工具参考（含 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-sheets-formula-verify`。 |
+| [Lark Sheet Write Cells](references/lark-sheets-write-cells.md) | 向飞书表格的指定区域批量写入值、公式、样式、批注或单元格图片。适用场景：填写数据、设置公式、修改格式、添加批注、嵌入单元格图片（如需操作浮动图片，请使用 lark-sheets-float-image）；若只需把一块 CSV 批量铺到表格上（值或公式，不带样式/批注），直接使用 `+csv-put` 更短更快。追加数据需先通过 lark-sheets-sheet-structure 插入行列。 |
 | [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) | 管理飞书表格中的图表（柱形图、折线图、饼图、条形图、面积图、散点图、组合图、雷达图等）。当用户需要创建图表、修改图表样式或数据源、查看已有图表配置、删除图表时使用。也适用于用户提到"数据可视化"、"画个图"、"趋势分析"、"对比图"、"占比分析"、"做个图表"等数据可视化相关场景。 |
@@ -159,8 +92,6 @@ 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) | 查询飞书表格的历史版本并回滚到指定版本。当用户需要查看一张表的编辑历史版本列表、回滚到某个历史版本、或查询回滚的异步状态（进行中/成功/失败）时使用。回滚为异步操作，发起后通过状态查询轮询结果。仅针对飞书表格。 |
-| [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,8 +8,6 @@
 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`。
@@ -18,18 +16,12 @@
 
 **⚠️ 何时必须使用 `+batch-update`（硬性要求）**：
 - 需要对**多个**不同区域执行 `+cells-{merge|unmerge}` 时（如按分组合并多列相同内容）
+- 需要对**多个**不同区域执行 `+rows-resize / +cols-resize` 时（如统一调整多列列宽或多行行高）
 - 需要先插入行列再写入数据时（`+dim-{insert|delete|hide|unhide|freeze|group|ungroup}` + `+cells-set`）
 - 需要对多个区域执行不同写入操作时（多次 `+cells-set` + `+cells-clear` 等组合）
 
-**行高列宽批量不走这里**：多行 / 多列不同尺寸直接用 `+rows-resize --heights` / `+cols-resize --widths` 的 map 形态（如 `--widths '{"A":100,"C:E":120}'`，见 `lark-sheets-range-operations`），一次调用原子完成；map 形态不可作为 `--operations` 子操作嵌入（子操作里仍可用单区间形态 `range` + `height`/`width`）。
-
 当同一工具需要对多个区域重复调用时，**必须**改用 `+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
@@ -59,10 +51,9 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组，每项必须带 sheet 前缀（如 `["Sheet1!A1:B2","Sheet2!D1:D10"]`，前缀裸写不加引号）；前缀必须与 sheet 真实显示名完全一致（含大小写），不接受 sheet reference_id；支持跨 sheet；所有 range 应用同一组 style |
+| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组，每项必须带 sheet 前缀（如 `["'Sheet1'!A1:B2","'Sheet2'!D1:D10"]`）；前缀必须是 sheet 显示名（如 `Sheet1`），不接受 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`） |
@@ -79,7 +70,7 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["Sheet1!A2:A100","Sheet1!C2:C100"]`，前缀裸写不加引号），每项必须带 sheet 前缀；前缀必须与 sheet 真实显示名完全一致（含大小写），不接受 sheet reference_id |
+| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["'Sheet1'!A2:A100","'Sheet1'!C2:C100"]`），每项必须带 sheet 前缀；前缀必须是 sheet 显示名（如 `Sheet1`），不接受 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 | 启用多选 |
@@ -92,7 +83,7 @@ _公共：URL/token（无 sheet 定位） · 系统：`--yes`、`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（最多 100 个，如 `["Sheet1!E2:E6"]`，前缀裸写不加引号），每项必须带 sheet 前缀；前缀必须与 sheet 真实显示名完全一致（含大小写），不接受 sheet reference_id |
+| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（最多 100 个，如 `["'Sheet1'!E2:E6"]`），每项必须带 sheet 前缀；前缀必须是 sheet 显示名（如 `Sheet1`），不接受 sheet reference_id |
 
 ### `+cells-batch-clear`
 
@@ -100,7 +91,7 @@ _公共：URL/token（无 sheet 定位） · 系统：`--yes`、`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组，每项必须带 sheet 前缀（如 `["Sheet1!A2:Z1000","Sheet2!A2:Z1000"]`，前缀裸写不加引号）；前缀必须与 sheet 真实显示名完全一致（含大小写），不接受 sheet reference_id；支持跨 sheet；对所有 range 执行同一 scope 的清除 |
+| `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组，每项必须带 sheet 前缀（如 `["'Sheet1'!A2:Z1000","'Sheet2'!A2:Z1000"]`）；前缀必须是 sheet 显示名（如 `Sheet1`），不接受 sheet reference_id；支持跨 sheet；对所有 range 执行同一 scope 的清除 |
 | `--scope` | string | optional | 清除范围 enum：`content`（默认，仅清内容）/ `formats`（仅清格式）/ `all`（清内容 + 格式）（可选值：`content` / `formats` / `all`） |
 
 ## Schemas
@@ -146,7 +137,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":"...","position":10,"count":3}},
+#   {"shortcut": "+dim-insert", "input": {"sheet_id":"...","dimension":"row","start":10,"end":12}},
 #   {"shortcut": "+cells-set",  "input": {"sheet_id":"...","range":"A11:B12","cells":[[{"value":"a"},{"value":"b"}],[{"value":"c"},{"value":"d"}]]}}
 # ]
 ```
@@ -154,7 +145,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"`、`"position":11`），不要把整组 `--operations` 再套一层嵌套 JSON。
+> - `input` 的键是该 shortcut 的 flag **展平**成 JSON（`"range":"A11:B12"`、`"dimension":"row"`），不要把整组 `--operations` 再套一层嵌套 JSON。
 
 > **常见组合：插列 + 写表头 + 整列回填**——一次原子提交，不要拆成 N 次独立调用。批量回填同一列 **只需一次** `+cells-set`（range 写整列范围、cells 写 N×1 矩阵），不需要逐行循环。
 >
@@ -162,9 +153,9 @@ lark-cli sheets +batch-update --url "https://example.feishu.cn/sheets/shtXXX" --
 > // 在 C 列前插入新列 → 写表头 C1 → 回填 C2:C100 共 99 行
 > [
 >   {"shortcut": "+dim-insert",
->    "input": {"sheet_name": "Sheet1", "position": "C", "count": 1}},
+>    "input": {"sheet_id": "...", "dimension": "column", "start": 3, "end": 4}},
 >   {"shortcut": "+cells-set",
->    "input": {"sheet_name": "Sheet1", "range": "C1:C100",
+>    "input": {"sheet_id": "...", "range": "C1:C100",
 >              "cells": [[{"value":"score"}], [{"value":95}], [{"value":87}], /* ... 97 more rows ... */ ]}}
 > ]
 > ```

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

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

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

@@ -43,8 +43,6 @@
 
 **正确做法（两步走）**：
 
-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

@@ -0,0 +1,103 @@
+# 飞书表格核心操作：分析、编辑与可视化
+
+## 概览
+
+面向"已有飞书表格"的核心工作流，核心原则：**先了解，再分析或写入，最后验证**。本文是方法论总纲；具体工具的参数细节、边界陷阱在对应 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 | 筛选视图名称；不传时系统自动分配；优先级高于 `--properties` 中同名字段 |
+| `--view-name` | string | optional | 筛选视图名称；create 不传时系统自动分配，update 不传时保留原名；优先级高于 `--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`：图片 URI（上传链路返回的句柄），**非**表内对象 reference_id；由系统自动转 file_token。
+- `--image-uri`：图片 reference_id（image URI），由系统自动转 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
 
-# 用 image URI（上传链路返回的句柄，非表内对象 reference_id；与 --image-token 二选一）
+# 用 reference_id（图片上传链路返回的 image 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