feat(sheets): enable bitable sheet creation

os.Stdin.Stat is intentional here - pipe detection needs the real
process fd; IOStreams.In is a plain io.Reader without Stat. Clears the
lint failure left by the stdin-fallback commit.

.gitignore

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

CHANGELOG.md

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

README.md

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

cmd/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 schema catalog's Complete.
-// It uses the same source as schema execution so completion candidates match
-// what `schema` can resolve.
+// 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).
 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.SchemaCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
+		completions, noSpace := registry.EmbeddedCatalog().Complete(args, toComplete, registry.FilterForStrictMode(mode))
 		directive := cobra.ShellCompDirectiveNoFileComp
 		if noSpace {
 			directive |= cobra.ShellCompDirectiveNoSpace
@@ -86,19 +86,13 @@ func schemaRun(opts *SchemaOptions) error {
 	return runSchema(out, apicatalog.ParsePath(opts.Args), mode)
 }
 
-// runSchema resolves the path through the schema catalog and renders the
+// runSchema resolves the path through the embedded 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.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")
-	}
+	catalog := registry.EmbeddedCatalog()
 	target, err := catalog.Resolve(parts)
 	if err != nil {
 		return resolveError(err)

cmd/update/update.go

@@ -86,13 +86,10 @@ func symArrow() string {
 
 // UpdateOptions holds inputs for the update command.
 type UpdateOptions struct {
-	Factory      *cmdutil.Factory
-	JSON         bool
-	Force        bool
-	Check        bool
-	SkillsLayout string
-	FlatSkills   string
-	FlatSet      bool
+	Factory *cmdutil.Factory
+	JSON    bool
+	Force   bool
+	Check   bool
 }
 
 // NewCmdUpdate creates the update command.
@@ -105,14 +102,12 @@ 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>
-  - pnpm install: runs pnpm add -g @larksuite/cli@<version>
+  - npm install: runs npm install -g @larksuite/cli@<version>
   - manual/other: shows GitHub Releases download URL
 
 Use --json for structured output (for AI agents and scripts).
 Use --check to only check for updates without installing.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			opts.FlatSet = cmd.Flags().Changed("flat-skills")
 			return updateRun(opts)
 		},
 	}
@@ -120,8 +115,6 @@ Use --check to only check for updates without installing.`,
 	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "force reinstall even if already up to date")
 	cmd.Flags().BoolVar(&opts.Check, "check", false, "only check for updates, do not install")
-	cmd.Flags().StringVar(&opts.SkillsLayout, "skills-layout", "", "skills layout: separate or hybrid")
-	cmd.Flags().StringVar(&opts.FlatSkills, "flat-skills", "", "comma-separated skills kept as top-level skills when the effective layout is hybrid")
 	cmdutil.SetRisk(cmd, "high-risk-write")
 
 	return cmd
@@ -129,9 +122,6 @@ Use --check to only check for updates without installing.`,
 
 func updateRun(opts *UpdateOptions) error {
 	io := opts.Factory.IOStreams
-	if err := validateSkillsLayoutOptions(opts); err != nil {
-		return reportError(opts, io, "validation_error", err)
-	}
 	cur := currentVersion()
 	updater := newUpdater()
 
@@ -157,7 +147,7 @@ func updateRun(opts *UpdateOptions) error {
 	if !opts.Force && !update.IsNewer(latest, cur) {
 		var skillsResult *skillscheck.SyncResult
 		if !opts.Check {
-			skillsResult = runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
+			skillsResult = runSkillsAndState(updater, io, cur, opts.Force)
 		}
 		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
@@ -174,7 +164,7 @@ func updateRun(opts *UpdateOptions) error {
 	if !detect.CanAutoUpdate() {
 		return doManualUpdate(opts, io, cur, latest, detect, updater)
 	}
-	return doAutoUpdate(opts, io, cur, latest, detect, updater)
+	return doNpmUpdate(opts, io, cur, latest, updater)
 }
 
 // --- Output helpers ---
@@ -218,7 +208,7 @@ func reportCheckResult(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest s
 }
 
 func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
-	skillsResult := runSkillsAndState(updater, io, cur, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
+	skillsResult := runSkillsAndState(updater, io, cur, opts.Force)
 
 	reason := detect.ManualReason()
 	if opts.JSON {
@@ -236,23 +226,12 @@ 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())
-	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", 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", selfupdate.NpmPackage, latest)
-	}
+	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 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
-	}
-
+func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, updater *selfupdate.Updater) error {
 	restore, err := updater.PrepareSelfReplace()
 	if err != nil {
 		return reportError(opts, io, "update_error",
@@ -260,19 +239,19 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 	}
 
 	if !opts.JSON {
-		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via %s ...\n", cur, symArrow(), latest, pm)
+		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via npm ...\n", cur, symArrow(), latest)
 	}
 
-	npmResult := install(latest)
+	npmResult := updater.RunNpmInstall(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("%s install failed: %s", pm, npmResult.Err),
+					"type": "update_error", "message": fmt.Sprintf("npm install failed: %s", npmResult.Err),
 					"detail": selfupdate.Truncate(combined, maxNpmOutput),
-					"hint":   permissionHint(combined, pm),
+					"hint":   permissionHint(combined),
 				},
 			})
 			return output.ErrBare(output.ExitAPI)
@@ -284,7 +263,7 @@ func doAutoUpdate(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, pm); hint != "" {
+		if hint := permissionHint(combined); hint != "" {
 			fmt.Fprintf(io.ErrOut, "  %s\n", hint)
 		}
 		return output.ErrBare(output.ExitAPI)
@@ -295,7 +274,7 @@ func doAutoUpdate(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, pm)
+		hint := verificationFailureHint(updater, latest)
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok":    false,
@@ -308,7 +287,7 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 		return output.ErrBare(output.ExitAPI)
 	}
 
-	skillsResult := runSkillsAndState(updater, io, latest, opts.Force, opts.SkillsLayout, opts.FlatSkills, opts.FlatSet)
+	skillsResult := runSkillsAndState(updater, io, latest, opts.Force)
 
 	if opts.JSON {
 		result := map[string]interface{}{
@@ -325,50 +304,36 @@ func doAutoUpdate(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 {
-		skillsPM := "npx"
-		if detect.Method == selfupdate.InstallPnpm && detect.PnpmAvailable {
-			skillsPM = "pnpm dlx"
-		}
-		fmt.Fprintf(io.ErrOut, "\nUpdating skills via %s ...\n", skillsPM)
+		fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
 	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
-func permissionHint(pmOutput, pm string) string {
-	if !strings.Contains(pmOutput, "EACCES") || isWindows() {
-		return ""
+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"
 	}
-	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"
+	return ""
 }
 
-func verificationFailureHint(updater *selfupdate.Updater, latest, pm string) string {
+func verificationFailureHint(updater *selfupdate.Updater, latest 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, 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, 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))
 }
 
-func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool, requestedLayout, requestedFlat string, flatSet bool) *skillscheck.SyncResult {
-	layout, flat := resolveSkillsSyncOptions(requestedLayout, requestedFlat, flatSet)
-	layoutExplicit := strings.TrimSpace(requestedLayout) != ""
-	if !force && !layoutExplicit && !flatSet {
-		if existing, existingLayout, ok := skillscheck.ReadSyncedVersionAndLayout(); ok && existingLayout != "" && normalizeVersion(existing) == normalizeVersion(stateVersion) {
+func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, stateVersion string, force bool) *skillscheck.SyncResult {
+	if !force {
+		if existing, ok := skillscheck.ReadSyncedVersion(); ok && normalizeVersion(existing) == normalizeVersion(stateVersion) {
 			return nil
 		}
 	}
 	result := syncSkills(skillscheck.SyncOptions{
-		Version:    stateVersion,
-		Layout:     layout,
-		FlatSkills: flat,
-		Force:      force,
-		Runner:     updater,
+		Version: stateVersion,
+		Force:   force,
+		Runner:  updater,
 	})
 	if result.Err != nil && strings.Contains(result.Err.Error(), "state not written") {
 		fmt.Fprintf(io.ErrOut, "warning: %v\n", result.Err)
@@ -376,38 +341,6 @@ func runSkillsAndState(updater *selfupdate.Updater, io *cmdutil.IOStreams, state
 	return result
 }
 
-func validateSkillsLayoutOptions(opts *UpdateOptions) errs.TypedError {
-	if _, ok := skillscheck.NormalizeLayout(opts.SkillsLayout); !ok {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--skills-layout must be one of separate or hybrid").WithParam("--skills-layout")
-	}
-	return nil
-}
-
-func resolveSkillsSyncOptions(requestedLayout, requestedFlat string, flatSet bool) (string, []string) {
-	state, readable, err := skillscheck.ReadState()
-	if err != nil {
-		readable = false
-		state = nil
-	}
-
-	layout := skillscheck.LayoutSeparate
-	if strings.TrimSpace(requestedLayout) != "" {
-		layout, _ = skillscheck.NormalizeLayout(requestedLayout)
-	} else if readable && state != nil {
-		if stateLayout, ok := skillscheck.NormalizeLayout(state.Layout); ok && state.Layout != "" {
-			layout = stateLayout
-		}
-	}
-
-	if flatSet {
-		return layout, skillscheck.ParseFlatSkills(requestedFlat)
-	}
-	if readable && state != nil {
-		return layout, state.FlatSkills
-	}
-	return layout, []string{}
-}
-
 // reportAlreadyUpToDate emits the JSON / pretty output for the
 // already-up-to-date branch, including any skills_action / skills_warning
 // fields derived from skillsResult. When check is true, this is the pure
@@ -454,12 +387,6 @@ func applySkillsStatus(env map[string]interface{}, target string) {
 	if len(state.SkippedDeletedSkills) > 0 {
 		status["skipped_deleted"] = state.SkippedDeletedSkills
 	}
-	if state.Layout != "" {
-		status["layout"] = state.Layout
-	}
-	if len(state.FlatSkills) > 0 {
-		status["flat_skills"] = state.FlatSkills
-	}
 	env["skills_status"] = status
 }
 
@@ -470,7 +397,6 @@ func applySkillsResult(env map[string]interface{}, r *skillscheck.SyncResult) {
 	case r.Err != nil:
 		env["skills_action"] = "failed"
 		env["skills_warning"] = fmt.Sprintf("skills update failed: %s", r.Err)
-		env["skills_hint"] = skillsFailureHint()
 		env["skills_summary"] = skillsSummary(r)
 	default:
 		env["skills_action"] = "synced"
@@ -484,17 +410,10 @@ func skillsSummary(r *skillscheck.SyncResult) map[string]interface{} {
 		"updated":         len(r.Updated),
 		"added":           len(r.Added),
 		"skipped_deleted": len(r.SkippedDeleted),
-		"layout":          r.Layout,
 	}
 	if len(r.Failed) > 0 {
 		summary["failed"] = r.Failed
 	}
-	if len(r.Collected) > 0 {
-		summary["collected"] = r.Collected
-	}
-	if len(r.Flat) > 0 {
-		summary["flat"] = r.Flat
-	}
 	return summary
 }
 
@@ -506,17 +425,13 @@ func emitSkillsTextHints(io *cmdutil.IOStreams, r *skillscheck.SyncResult) {
 		if len(r.Failed) > 0 {
 			fmt.Fprintf(io.ErrOut, "  Failed skills: %s\n", strings.Join(r.Failed, ", "))
 		}
-		fmt.Fprintf(io.ErrOut, "  %s\n", skillsFailureHint())
+		fmt.Fprintf(io.ErrOut, "  To retry all official skills: lark-cli update --force\n")
 	case r.Force:
-		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills (%s layout)\n", symOK(), len(r.Official), r.Layout)
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: restored all %d official skills\n", symOK(), len(r.Official))
 	default:
-		fmt.Fprintf(io.ErrOut, "%s Skills updated: %d official, %d updated, %d added, %d skipped because deleted locally (%s layout)\n", symOK(), len(r.Official), len(r.Updated), len(r.Added), len(r.SkippedDeleted), r.Layout)
+		fmt.Fprintf(io.ErrOut, "%s Skills updated: %d official, %d updated, %d added, %d skipped because deleted locally\n", symOK(), len(r.Official), len(r.Updated), len(r.Added), len(r.SkippedDeleted))
 		if len(r.SkippedDeleted) > 0 {
 			fmt.Fprintf(io.ErrOut, "  To restore all official skills: lark-cli update --force\n")
 		}
 	}
 }
-
-func skillsFailureHint() string {
-	return "Retry: lark-cli update --force. To switch to separate top-level skills: lark-cli update --skills-layout separate (this saves layout=separate and clears saved flat_skills)."
-}

cmd/update/update_test.go

@@ -57,27 +57,6 @@ 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{}
@@ -102,113 +81,6 @@ 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)
-	}
-	if strings.Contains(out, "pnpm dlx skills add larksuite/cli") {
-		t.Errorf("should not suggest standalone pnpm skills sync command, got: %s", out)
-	}
-}
-
 func TestNormalizeVersion(t *testing.T) {
 	tests := []struct {
 		input string
@@ -394,9 +266,6 @@ 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) {
@@ -731,8 +600,8 @@ func TestUpdateNpmVerifyFail_JSON_NoRestoreHintWhenBackupUnavailable(t *testing.
 	if !strings.Contains(out, "skills will not be synced") {
 		t.Errorf("expected skills-not-synced warning in rollback hint, got: %s", out)
 	}
-	if strings.Contains(out, "npx skills add larksuite/cli -y -g") {
-		t.Errorf("should not suggest standalone skills sync command, got: %s", out)
+	if !strings.Contains(out, "npx skills add larksuite/cli -y -g") {
+		t.Errorf("expected npx skills add hint for skills sync, got: %s", out)
 	}
 }
 
@@ -870,9 +739,9 @@ func TestPermissionHint(t *testing.T) {
 	origOS := currentOS
 	defer func() { currentOS = origOS }()
 
-	// Linux + npm: EACCES should produce a hint with npm prefix guidance.
+	// Linux: EACCES should produce a hint with npm prefix guidance.
 	currentOS = "linux"
-	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'", "npm")
+	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'")
 	if !strings.Contains(hint, "npm global prefix") {
 		t.Errorf("expected npm prefix hint on linux, got: %s", hint)
 	}
@@ -880,25 +749,16 @@ 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", "npm")
+	hint = permissionHint("EACCES: permission denied")
 	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", "npm"); got != "" {
+	if got := permissionHint("some other error"); got != "" {
 		t.Errorf("expected empty hint for non-EACCES, got: %s", got)
 	}
 }
@@ -1136,7 +996,7 @@ func newTestIO() *cmdutil.IOStreams {
 
 func TestRunSkillsAndState_DedupHit(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21", Layout: skillscheck.LayoutSeparate}); err != nil {
+	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
 		t.Fatal(err)
 	}
 	called := false
@@ -1146,7 +1006,7 @@ func TestRunSkillsAndState_DedupHit(t *testing.T) {
 			return &selfupdate.NpmResult{}
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got != nil {
 		t.Errorf("runSkillsAndState() = %+v, want nil for dedup hit", got)
 	}
@@ -1155,27 +1015,6 @@ func TestRunSkillsAndState_DedupHit(t *testing.T) {
 	}
 }
 
-func TestRunSkillsAndState_MissingLayoutDoesNotDedup(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
-		t.Fatal(err)
-	}
-	called := false
-	updater := &selfupdate.Updater{
-		SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
-			called = true
-			return successfulSkillsCommand()(args...)
-		},
-	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
-	if got == nil || got.Err != nil {
-		t.Fatalf("runSkillsAndState() = %+v, want successful sync when state lacks layout", got)
-	}
-	if !called {
-		t.Error("SkillsCommandOverride not called, want resync when state lacks layout")
-	}
-}
-
 func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	if err := skillscheck.WriteState(skillscheck.SkillsState{Version: "1.0.21"}); err != nil {
@@ -1188,7 +1027,7 @@ func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 			return successfulSkillsCommand()(args...)
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", true)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState(force=true) = %+v, want successful result", got)
 	}
@@ -1200,7 +1039,7 @@ func TestRunSkillsAndState_DedupForceBypass(t *testing.T) {
 func TestRunSkillsAndState_SuccessWritesState(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	updater := &selfupdate.Updater{SkillsCommandOverride: successfulSkillsCommand()}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got == nil || got.Err != nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with nil Err", got)
 	}
@@ -1211,12 +1050,6 @@ func TestRunSkillsAndState_SuccessWritesState(t *testing.T) {
 	if state.Version != "1.0.21" {
 		t.Errorf("state.Version = %q, want \"1.0.21\"", state.Version)
 	}
-	if state.Layout != skillscheck.LayoutSeparate {
-		t.Errorf("state.Layout = %q, want %q", state.Layout, skillscheck.LayoutSeparate)
-	}
-	if len(state.FlatSkills) != 0 {
-		t.Errorf("state.FlatSkills = %#v, want empty", state.FlatSkills)
-	}
 }
 
 func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
@@ -1231,7 +1064,7 @@ func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
 			return r
 		},
 	}
-	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false, "", "", false)
+	got := runSkillsAndState(updater, newTestIO(), "1.0.21", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with non-nil Err", got)
 	}
@@ -1244,50 +1077,6 @@ func TestRunSkillsAndState_FailureKeepsOldState(t *testing.T) {
 	}
 }
 
-func TestResolveSkillsSyncOptions_UsesStateAsFallback(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := skillscheck.WriteState(skillscheck.SkillsState{
-		Version:    "1.0.21",
-		Layout:     skillscheck.LayoutHybrid,
-		FlatSkills: []string{"lark-doc"},
-	}); err != nil {
-		t.Fatal(err)
-	}
-
-	layout, flat := resolveSkillsSyncOptions("", "", false)
-	if layout != skillscheck.LayoutHybrid {
-		t.Fatalf("layout = %q, want %q", layout, skillscheck.LayoutHybrid)
-	}
-	if len(flat) != 1 || flat[0] != "lark-doc" {
-		t.Fatalf("flat = %#v, want [lark-doc]", flat)
-	}
-}
-
-func TestValidateSkillsLayoutOptionsRejectsSuiteMode(t *testing.T) {
-	err := validateSkillsLayoutOptions(&UpdateOptions{SkillsLayout: "suite"})
-	if err == nil {
-		t.Fatal("validateSkillsLayoutOptions() err = nil, want validation error")
-	}
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) {
-		t.Fatalf("errors.As(err, *ValidationError) = false for %T", err)
-	}
-	if validation.Param != "--skills-layout" {
-		t.Fatalf("validation.Param = %q, want --skills-layout", validation.Param)
-	}
-}
-
-func TestValidateSkillsLayoutOptionsAllowsFlatSkillsFilteringAfterOfficialDiscovery(t *testing.T) {
-	err := validateSkillsLayoutOptions(&UpdateOptions{
-		SkillsLayout: skillscheck.LayoutHybrid,
-		FlatSkills:   "lark-shared,lark-unknown",
-		FlatSet:      true,
-	})
-	if err != nil {
-		t.Fatalf("validateSkillsLayoutOptions() err = %v, want nil", err)
-	}
-}
-
 func TestTruncate(t *testing.T) {
 	long := strings.Repeat("x", 3000)
 	got := selfupdate.Truncate(long, 2000)
@@ -1568,7 +1357,7 @@ func TestRunSkillsAndState_StateWriteFailureWarns(t *testing.T) {
 	t.Cleanup(func() { syncSkills = origSync })
 
 	f, _, stderr := newTestFactory(t)
-	got := runSkillsAndState(&selfupdate.Updater{}, f.IOStreams, "1.0.21", false, "", "", false)
+	got := runSkillsAndState(&selfupdate.Updater{}, f.IOStreams, "1.0.21", false)
 	if got == nil || got.Err == nil {
 		t.Fatalf("runSkillsAndState() = %+v, want non-nil with write error", got)
 	}

errs/ERROR_CONTRACT.md

@@ -72,28 +72,6 @@ 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,10 +77,14 @@ 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{}
-	if svc, ok := registry.SchemaCatalog().Service(service); ok {
+	for _, svc := range registry.EmbeddedServicesTyped() {
+		if svc.Name != service {
+			continue
+		}
 		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,10 +6,12 @@ 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"
@@ -38,6 +40,8 @@ const (
 	BuildKindUnknown  = "unknown"
 
 	officialModulePath = "github.com/larksuite/cli"
+
+	agentTraceMaxLen = 1024
 )
 
 // UserAgentValue returns the User-Agent value: "lark-cli/{version}".
@@ -45,6 +49,25 @@ 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)
@@ -52,7 +75,7 @@ func BaseSecurityHeaders() http.Header {
 	h.Set(HeaderVersion, build.Version)
 	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
-	if v := envvars.AgentTrace(); v != "" {
+	if v := AgentTraceValue(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}
 	return h

internal/cmdutil/secheader_test.go

@@ -6,6 +6,7 @@ package cmdutil
 import (
 	"context"
 	"net/http"
+	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/extension/credential"
@@ -263,9 +264,88 @@ func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// HeaderAgentTrace injection (via BaseSecurityHeaders)
+// AgentTraceValue / HeaderAgentTrace
 // ---------------------------------------------------------------------------
 
+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,7 +19,6 @@ 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

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

@@ -1,131 +0,0 @@
-// 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,7 +6,8 @@ package registry
 import "github.com/larksuite/cli/internal/apicatalog"
 
 // EmbeddedCatalog returns a navigation catalog over the embedded (overlay-free)
-// metadata — deterministic across machines, for golden tests and schema lint.
+// metadata — deterministic across machines, for `lark-cli schema`, golden tests
+// and schema lint.
 func EmbeddedCatalog() apicatalog.Catalog {
 	return apicatalog.New(apicatalog.SourceEmbedded, EmbeddedServicesTyped())
 }
@@ -17,14 +18,3 @@ 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

@@ -1,67 +0,0 @@
-// 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,7 +15,6 @@ 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
@@ -86,9 +85,7 @@ func InitWithBrand(brand core.LarkBrand) {
 			brandChanged := metaErr == nil && cm.Brand != "" && cm.Brand != string(brand)
 
 			if !brandChanged {
-				// 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) {
+				if cached, err := loadCachedMerged(); err == nil {
 					overlayMergedServices(cached)
 				}
 			}

internal/registry/loader_test.go

@@ -1,102 +0,0 @@
-// 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,11 +72,9 @@ 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: "1.0.0",
+		Version: "test-1.0",
 		Services: []meta.Service{
 			{
 				Name:        name,
@@ -162,7 +160,7 @@ func TestRemoteOff_SkipsRemoteLogic(t *testing.T) {
 }
 
 func TestCacheHit_WithinTTL(t *testing.T) {
-	swapEmbeddedMeta(t, nil) // overlay must depend only on the cache version, not the ambient embedded meta
+	resetInit()
 	tmp := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
@@ -199,7 +197,7 @@ func TestCacheHit_WithinTTL(t *testing.T) {
 }
 
 func TestNetworkError_SilentDegradation(t *testing.T) {
-	swapEmbeddedMeta(t, nil) // overlay must depend only on the cache version, not the ambient embedded meta
+	resetInit()
 	tmp := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", tmp)
 	t.Setenv("LARKSUITE_CLI_REMOTE_META", "on")
@@ -373,8 +371,8 @@ func TestFetchRemoteMerged_200(t *testing.T) {
 	if data == nil {
 		t.Fatal("expected non-nil data")
 	}
-	if reg.Version != "1.0.0" {
-		t.Errorf("expected version 1.0.0, got %s", reg.Version)
+	if reg.Version != "test-1.0" {
+		t.Errorf("expected version test-1.0, got %s", reg.Version)
 	}
 }
 

internal/selfupdate/updater.go

@@ -32,7 +32,6 @@ type InstallMethod int
 
 const (
 	InstallNpm InstallMethod = iota
-	InstallPnpm
 	InstallManual
 )
 
@@ -50,38 +49,26 @@ const (
 var (
 	skillsIndexFetchTimeout = 10 * time.Second
 	officialSkillsIndexURL  = "https://open.feishu.cn/.well-known/skills/index.json"
-	isolatedSkillsSourceURL = "https://open.feishu.cn/lark-cli/isolated-skills"
-	isolatedSkillsFallback  = "larksuite/cli/isolated-skills"
 )
 
 // DetectResult holds installation detection results.
 type DetectResult struct {
-	Method        InstallMethod
-	ResolvedPath  string
-	NpmAvailable  bool
-	PnpmAvailable bool
+	Method       InstallMethod
+	ResolvedPath string
+	NpmAvailable bool
 }
 
 // CanAutoUpdate returns true if the CLI can update itself automatically.
 func (d DetectResult) CanAutoUpdate() bool {
-	switch d.Method {
-	case InstallNpm:
-		return d.NpmAvailable
-	case InstallPnpm:
-		return d.PnpmAvailable
-	}
-	return false
+	return d.Method == InstallNpm && d.NpmAvailable
 }
 
 // ManualReason returns a human-readable explanation of why auto-update is unavailable.
 func (d DetectResult) ManualReason() string {
-	switch {
-	case d.Method == InstallNpm && !d.NpmAvailable:
+	if 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 or pnpm"
+	return "not installed via npm"
 }
 
 // NpmResult holds the result of an npm install or skills update execution.
@@ -105,7 +92,6 @@ 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
@@ -115,38 +101,17 @@ 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 the
-// owning package manager is available for auto-update.
+// DetectInstallMethod determines how the CLI was installed and whether
+// npm 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}
@@ -155,54 +120,24 @@ 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") {
-		if containsPnpmMarker(resolved) {
-			method = InstallPnpm
-		} else {
-			method = InstallNpm
-		}
+		method = InstallNpm
 	}
-	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
+	npmAvailable := false
+	if method == InstallNpm {
+		if _, err := exec.LookPath("npm"); err == nil {
+			npmAvailable = true
 		}
 	}
-	return false
+
+	return DetectResult{
+		Method:       method,
+		ResolvedPath: resolved,
+		NpmAvailable: npmAvailable,
+	}
 }
 
 // RunNpmInstall executes npm install -g @larksuite/cli@<version>.
@@ -228,29 +163,6 @@ 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()
@@ -330,14 +242,6 @@ func (u *Updater) InstallAllSkills() *NpmResult {
 	return r
 }
 
-func (u *Updater) InstallSuiteSkill() *NpmResult {
-	r := u.runSkillsInstall(isolatedSkillsSourceURL, []string{"lark-suite"})
-	if r.Err != nil {
-		r = u.runSkillsInstall(isolatedSkillsFallback, []string{"lark-suite"})
-	}
-	return r
-}
-
 func (u *Updater) runSkillsAdd(source string) *NpmResult {
 	return u.runSkillsCommand("-y", "skills", "add", source, "-g", "-y")
 }
@@ -357,40 +261,19 @@ 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{}
-	det := u.DetectInstallMethod()
-	launcher, cmdArgs := skillsInvocation(det.Method, det.PnpmAvailable, args)
-	binPath, err := exec.LookPath(launcher)
+	npxPath, err := exec.LookPath("npx")
 	if err != nil {
-		r.Err = fmt.Errorf("%s not found in PATH: %w", launcher, err)
+		r.Err = fmt.Errorf("npx not found in PATH: %w", err)
 		return r
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), skillsUpdateTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, binPath, cmdArgs...)
+	cmd := exec.CommandContext(ctx, npxPath, args...)
 	cmd.Stdout = &r.Stdout
 	cmd.Stderr = &r.Stderr
 	r.Err = cmd.Run()

internal/selfupdate/updater_test.go

@@ -208,13 +208,6 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 			},
 			want: "-y skills add https://open.feishu.cn -s lark-mail -g -y",
 		},
-		{
-			name: "install isolated suite skill",
-			run: func(u *Updater) *NpmResult {
-				return u.runSkillsInstall(isolatedSkillsSourceURL, []string{"lark-suite"})
-			},
-			want: "-y skills add https://open.feishu.cn/lark-cli/isolated-skills -s lark-suite -g -y",
-		},
 	}
 
 	for _, tt := range tests {
@@ -245,76 +238,6 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 	}
 }
 
-func TestInstallSuiteSkillFallsBackToIsolatedGitHubSource(t *testing.T) {
-	called := []string{}
-	u := &Updater{
-		SkillsCommandOverride: func(args ...string) *NpmResult {
-			called = append(called, strings.Join(args, " "))
-			r := &NpmResult{}
-			if strings.Contains(strings.Join(args, " "), isolatedSkillsSourceURL) {
-				r.Err = fmt.Errorf("isolated source unavailable")
-			}
-			return r
-		},
-	}
-
-	result := u.InstallSuiteSkill()
-	if result.Err != nil {
-		t.Fatalf("InstallSuiteSkill() err = %v, want nil", result.Err)
-	}
-	if len(called) != 2 {
-		t.Fatalf("calls = %#v, want primary and fallback", called)
-	}
-	if !strings.Contains(called[0], isolatedSkillsSourceURL) {
-		t.Fatalf("primary call = %q, want isolated source", called[0])
-	}
-	if !strings.Contains(called[1], isolatedSkillsFallback) {
-		t.Fatalf("fallback call = %q, want isolated GitHub fallback", called[1])
-	}
-}
-
-func TestInstallSuiteSkillUsesPnpmDlxForIsolatedSources(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("uses a POSIX shell script")
-	}
-	dir := t.TempDir()
-	logPath := filepath.Join(dir, "pnpm.log")
-	script := filepath.Join(dir, "pnpm")
-	scriptContent := fmt.Sprintf(`#!/bin/sh
-printf '%%s\n' "$*" >> %q
-case "$*" in
-  *%q*) exit 1 ;;
-  *) exit 0 ;;
-esac
-`, logPath, isolatedSkillsSourceURL)
-	if err := os.WriteFile(script, []byte(scriptContent), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
-
-	u := New()
-	u.DetectOverride = func() DetectResult {
-		return DetectResult{Method: InstallPnpm, PnpmAvailable: true}
-	}
-
-	result := u.InstallSuiteSkill()
-	if result.Err != nil {
-		t.Fatalf("InstallSuiteSkill() err = %v, want nil", result.Err)
-	}
-	raw, err := os.ReadFile(logPath)
-	if err != nil {
-		t.Fatal(err)
-	}
-	got := strings.Split(strings.TrimSpace(string(raw)), "\n")
-	want := []string{
-		"dlx skills add " + isolatedSkillsSourceURL + " -s lark-suite -g -y",
-		"dlx skills add " + isolatedSkillsFallback + " -s lark-suite -g -y",
-	}
-	if strings.Join(got, "\n") != strings.Join(want, "\n") {
-		t.Fatalf("pnpm calls = %#v, want %#v", got, want)
-	}
-}
-
 func TestListOfficialSkillsIndexSuccess(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		fmt.Fprint(w, `{"skills":[{"name":"lark-calendar"}]}`)
@@ -448,147 +371,3 @@ 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)
-	}
-}

internal/skillscheck/layout.go

@@ -1,389 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package skillscheck
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"os"
-	"path/filepath"
-	"sort"
-	"strings"
-
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-const (
-	LayoutSeparate = "separate"
-	LayoutHybrid   = "hybrid"
-
-	suiteSkillName         = "lark-suite"
-	sharedSkillName        = "lark-shared"
-	suiteRoutesPlaceholder = "<!-- LARK_SUITE_ROUTES -->"
-)
-
-type GlobalSkillInfo struct {
-	Name string
-	Path string
-}
-
-func NormalizeLayout(layout string) (string, bool) {
-	switch strings.TrimSpace(layout) {
-	case "", LayoutSeparate:
-		return LayoutSeparate, true
-	case LayoutHybrid:
-		return LayoutHybrid, true
-	default:
-		return "", false
-	}
-}
-
-func ParseFlatSkills(value string) []string {
-	seen := map[string]bool{}
-	for _, part := range strings.Split(value, ",") {
-		name := strings.TrimSpace(part)
-		if name != "" {
-			seen[name] = true
-		}
-	}
-	return sortedKeys(seen)
-}
-
-func ParseGlobalSkillInfosJSON(text string) []GlobalSkillInfo {
-	infos, _ := parseGlobalSkillInfosJSON(text)
-	return infos
-}
-
-func parseGlobalSkillInfosJSON(text string) ([]GlobalSkillInfo, bool) {
-	type globalSkill struct {
-		Name string `json:"name"`
-		Path string `json:"path"`
-	}
-
-	var skills []globalSkill
-	if err := json.Unmarshal([]byte(text), &skills); err != nil {
-		return nil, false
-	}
-
-	seen := map[string]GlobalSkillInfo{}
-	for _, skill := range skills {
-		name := strings.TrimSpace(skill.Name)
-		path := strings.TrimSpace(skill.Path)
-		if name == "" || path == "" || !skillNamePattern.MatchString(name) {
-			continue
-		}
-		seen[name] = GlobalSkillInfo{Name: name, Path: path}
-	}
-
-	out := make([]GlobalSkillInfo, 0, len(seen))
-	for _, info := range seen {
-		out = append(out, info)
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
-	return out, true
-}
-
-func installedSkillNamesFromInfos(infos []GlobalSkillInfo) []string {
-	seen := map[string]bool{}
-	for _, info := range infos {
-		seen[info.Name] = true
-		if info.Name == suiteSkillName {
-			for _, subskill := range listSuiteSubskills(info.Path) {
-				seen[subskill] = true
-			}
-		}
-	}
-	return sortedKeys(seen)
-}
-
-func listSuiteSubskills(suitePath string) []string {
-	entries, err := vfs.ReadDir(filepath.Join(suitePath, "references", "subskills"))
-	if err != nil {
-		return nil
-	}
-	seen := map[string]bool{}
-	for _, entry := range entries {
-		if !entry.IsDir() {
-			continue
-		}
-		name := strings.TrimSpace(entry.Name())
-		if name != "" && skillNamePattern.MatchString(name) {
-			seen[name] = true
-		}
-	}
-	return sortedKeys(seen)
-}
-
-func normalOfficialSkills(skills []string) []string {
-	out := []string{}
-	for _, skill := range uniqueSorted(skills) {
-		if skill != suiteSkillName {
-			out = append(out, skill)
-		}
-	}
-	return out
-}
-
-func deletedOfficialSkills(official, local []string, previous *SkillsState, stateReadable, force bool, layout string) []string {
-	if force || !stateReadable || previous == nil {
-		return []string{}
-	}
-	officialSet := toSet(official)
-	localSet := toSet(local)
-	deleted := map[string]bool{}
-	for _, skill := range previous.OfficialSkills {
-		if !officialSet[skill] || localSet[skill] {
-			continue
-		}
-		if layout != LayoutSeparate && skill == sharedSkillName {
-			continue
-		}
-		deleted[skill] = true
-	}
-	return sortedKeys(deleted)
-}
-
-func suiteEffectiveSkills(official []string, deleted map[string]bool) []string {
-	out := []string{}
-	for _, skill := range normalOfficialSkills(official) {
-		if !deleted[skill] {
-			out = append(out, skill)
-		}
-	}
-	return uniqueSorted(out)
-}
-
-func resolveHybridSkillSets(layout string, requestedFlat, official []string, skippedDeleted []string) ([]string, []string, error) {
-	if layout == LayoutSeparate {
-		return []string{}, []string{}, nil
-	}
-
-	officialSet := toSet(official)
-	deletedSet := toSet(skippedDeleted)
-	configuredFlat := map[string]bool{}
-	effectiveFlat := map[string]bool{}
-	for _, skill := range uniqueSorted(requestedFlat) {
-		if skill == sharedSkillName {
-			continue
-		}
-		if !officialSet[skill] {
-			continue
-		}
-		configuredFlat[skill] = true
-		if !deletedSet[skill] {
-			effectiveFlat[skill] = true
-		}
-	}
-
-	collected := []string{}
-	for _, skill := range normalOfficialSkills(official) {
-		if skill == sharedSkillName {
-			collected = append(collected, skill)
-			continue
-		}
-		if deletedSet[skill] || effectiveFlat[skill] {
-			continue
-		}
-		collected = append(collected, skill)
-	}
-	return sortedKeys(configuredFlat), uniqueSortedWithFirst(collected, sharedSkillName), nil
-}
-
-func uniqueSortedWithFirst(values []string, first string) []string {
-	seen := toSet(values)
-	if !seen[first] {
-		return sortedKeys(seen)
-	}
-	delete(seen, first)
-	return append([]string{first}, sortedKeys(seen)...)
-}
-
-func assembleSuiteLayout(layout string, collected []string, keepSharedTopLevel bool, infos []GlobalSkillInfo) error {
-	if layout == LayoutSeparate {
-		return nil
-	}
-
-	infoByName := map[string]GlobalSkillInfo{}
-	for _, info := range infos {
-		infoByName[info.Name] = info
-	}
-	suiteInfo, ok := infoByName[suiteSkillName]
-	if !ok {
-		return fmt.Errorf("%s was not installed from isolated skills source", suiteSkillName)
-	}
-
-	subskillsDir := filepath.Join(suiteInfo.Path, "references", "subskills")
-	if err := vfs.RemoveAll(subskillsDir); err != nil {
-		return err
-	}
-	if err := vfs.MkdirAll(subskillsDir, 0o755); err != nil {
-		return err
-	}
-
-	for _, skill := range collected {
-		info, ok := infoByName[skill]
-		if !ok {
-			return fmt.Errorf("suite subskill %q was not installed", skill)
-		}
-		dst := filepath.Join(subskillsDir, skill)
-		if keepSharedTopLevel && skill == sharedSkillName {
-			if err := copyDir(info.Path, dst); err != nil {
-				return err
-			}
-			continue
-		}
-		if err := moveDir(info.Path, dst); err != nil {
-			return err
-		}
-	}
-	return renderSuiteRoutes(suiteInfo.Path, collected)
-}
-
-func renderSuiteRoutes(suitePath string, collected []string) error {
-	skillPath := filepath.Join(suitePath, "SKILL.md")
-	data, err := vfs.ReadFile(skillPath)
-	if err != nil {
-		return err
-	}
-	text := normalizeSuiteTemplateText(string(data))
-	routes := []string{}
-	for _, skill := range collected {
-		desc := skillDescription(filepath.Join(suitePath, "references", "subskills", skill, "SKILL.md"))
-		if desc == "" {
-			desc = skill
-		}
-		routes = append(routes, fmt.Sprintf("- %s: %s", skill, desc))
-	}
-	if !strings.Contains(text, suiteRoutesPlaceholder) {
-		return fmt.Errorf("%s route placeholder not found", suiteSkillName)
-	}
-	text = strings.Replace(text, suiteRoutesPlaceholder, strings.Join(routes, "\n"), 1)
-	return vfs.WriteFile(skillPath, []byte(text), 0o644)
-}
-
-func normalizeSuiteTemplateText(text string) string {
-	text = strings.ReplaceAll(text, "--collected-skills", "--flat-skills")
-	oldShared := "`lark-shared` 是共享基础能力，不作为 `--flat-skills` 的可选项。为了保证 suite 内子能力可用，hybrid 布局会同时保留顶层 `lark-shared`，并在 `lark-suite/references/subskills/lark-shared/SKILL.md` 中维护一份副本。"
-	newShared := "`lark-shared` 是共享基础能力，不作为 `--flat-skills` 的可选项。为了保证 suite 内子能力可用，它始终会进入 `lark-suite/references/subskills/lark-shared/SKILL.md`；只有 hybrid 布局存在平铺 skill 时，顶层才会额外保留一份 `lark-shared`。"
-	return strings.ReplaceAll(text, oldShared, newShared)
-}
-
-func skillDescription(path string) string {
-	data, err := vfs.ReadFile(path)
-	if err != nil {
-		return ""
-	}
-	lines := strings.Split(string(data), "\n")
-	if len(lines) == 0 || strings.TrimSpace(lines[0]) != "---" {
-		return ""
-	}
-	for i, line := range lines[1:] {
-		trimmed := strings.TrimSpace(line)
-		if trimmed == "---" {
-			return ""
-		}
-		if strings.HasPrefix(trimmed, "description:") {
-			value := strings.TrimSpace(strings.TrimPrefix(trimmed, "description:"))
-			if value == ">" || value == "|" {
-				return foldedYAMLScalar(lines[i+2:])
-			}
-			return strings.Trim(value, `"'`)
-		}
-	}
-	return ""
-}
-
-func foldedYAMLScalar(lines []string) string {
-	parts := []string{}
-	for _, line := range lines {
-		trimmed := strings.TrimSpace(line)
-		if trimmed == "" {
-			continue
-		}
-		if trimmed == "---" || !isIndentedYAMLLine(line) {
-			break
-		}
-		parts = append(parts, trimmed)
-	}
-	return strings.Join(parts, " ")
-}
-
-func isIndentedYAMLLine(line string) bool {
-	return strings.HasPrefix(line, " ") || strings.HasPrefix(line, "\t")
-}
-
-func moveDir(src, dst string) error {
-	if err := vfs.RemoveAll(dst); err != nil {
-		return err
-	}
-	if err := vfs.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
-		return err
-	}
-	if err := vfs.Rename(src, dst); err == nil {
-		return nil
-	}
-	if err := copyDir(src, dst); err != nil {
-		return err
-	}
-	return vfs.RemoveAll(src)
-}
-
-func copyDir(src, dst string) error {
-	info, err := vfs.Stat(src)
-	if err != nil {
-		return err
-	}
-	if !info.IsDir() {
-		return fmt.Errorf("%s is not a directory", src)
-	}
-	if err := vfs.RemoveAll(dst); err != nil {
-		return err
-	}
-	return copyDirEntries(src, dst)
-}
-
-func copyDirEntries(src, dst string) error {
-	if err := vfs.MkdirAll(dst, 0o755); err != nil {
-		return err
-	}
-	entries, err := vfs.ReadDir(src)
-	if err != nil {
-		return err
-	}
-	for _, entry := range entries {
-		srcPath := filepath.Join(src, entry.Name())
-		dstPath := filepath.Join(dst, entry.Name())
-		if entry.IsDir() {
-			if err := copyDirEntries(srcPath, dstPath); err != nil {
-				return err
-			}
-			continue
-		}
-		if err := copyFile(srcPath, dstPath); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func copyFile(src, dst string) error {
-	in, err := vfs.Open(src)
-	if err != nil {
-		return err
-	}
-	defer in.Close()
-	if err := vfs.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
-		return err
-	}
-	out, err := vfs.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o644)
-	if err != nil {
-		return err
-	}
-	if _, err := io.Copy(out, in); err != nil {
-		_ = out.Close()
-		return err
-	}
-	return out.Close()
-}

internal/skillscheck/state.go

@@ -23,12 +23,10 @@ var ErrUnreadableState = errors.New("skills state is unreadable")
 
 type SkillsState struct {
 	Version              string   `json:"version"`
-	Layout               string   `json:"layout,omitempty"`
 	OfficialSkills       []string `json:"official_skills"`
 	UpdatedSkills        []string `json:"updated_skills"`
 	AddedOfficialSkills  []string `json:"added_official_skills"`
 	SkippedDeletedSkills []string `json:"skipped_deleted_skills"`
-	FlatSkills           []string `json:"flat_skills"`
 	UpdatedAt            string   `json:"updated_at"`
 }
 
@@ -78,14 +76,6 @@ func ReadSyncedVersion() (string, bool) {
 	return state.Version, true
 }
 
-func ReadSyncedVersionAndLayout() (version string, layout string, ok bool) {
-	state, readable, err := ReadState()
-	if err != nil || !readable || state.Version == "" {
-		return "", "", false
-	}
-	return state.Version, state.Layout, true
-}
-
 func (s *SkillsState) ensureNonNilSlices() {
 	if s.OfficialSkills == nil {
 		s.OfficialSkills = []string{}
@@ -99,7 +89,4 @@ func (s *SkillsState) ensureNonNilSlices() {
 	if s.SkippedDeletedSkills == nil {
 		s.SkippedDeletedSkills = []string{}
 	}
-	if s.FlatSkills == nil {
-		s.FlatSkills = []string{}
-	}
 }

internal/skillscheck/state_test.go

@@ -32,12 +32,10 @@ func TestReadState_Valid(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	want := SkillsState{
 		Version:              "1.2.3",
-		Layout:               LayoutHybrid,
 		OfficialSkills:       []string{"lark-doc", "lark-im"},
 		UpdatedSkills:        []string{"lark-doc"},
 		AddedOfficialSkills:  []string{"lark-task"},
 		SkippedDeletedSkills: []string{"custom-skill"},
-		FlatSkills:           []string{"lark-doc"},
 		UpdatedAt:            "2026-05-18T10:00:00Z",
 	}
 	data, err := json.Marshal(want)
@@ -117,9 +115,6 @@ func TestWriteState_CreatesDirAndWritesState(t *testing.T) {
 	if got.SkippedDeletedSkills == nil {
 		t.Fatal("skipped_deleted_skills decoded as nil, want empty slice")
 	}
-	if got.FlatSkills == nil {
-		t.Fatal("flat_skills decoded as nil, want empty slice")
-	}
 }
 
 func TestReadSyncedVersionFromState(t *testing.T) {
@@ -142,24 +137,3 @@ func TestReadSyncedVersionFromState(t *testing.T) {
 		t.Fatalf("ReadSyncedVersion() = (%q, %v), want (\"\", false) for empty version", got, ok)
 	}
 }
-
-func TestReadSyncedVersionAndLayoutFromState(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-
-	if version, layout, ok := ReadSyncedVersionAndLayout(); ok || version != "" || layout != "" {
-		t.Fatalf("ReadSyncedVersionAndLayout() = (%q, %q, %v), want empty result for missing state", version, layout, ok)
-	}
-	if err := WriteState(SkillsState{Version: "1.2.3", Layout: LayoutHybrid}); err != nil {
-		t.Fatal(err)
-	}
-	if version, layout, ok := ReadSyncedVersionAndLayout(); !ok || version != "1.2.3" || layout != LayoutHybrid {
-		t.Fatalf("ReadSyncedVersionAndLayout() = (%q, %q, %v), want (\"1.2.3\", %q, true)", version, layout, ok, LayoutHybrid)
-	}
-	if err := WriteState(SkillsState{Layout: LayoutHybrid}); err != nil {
-		t.Fatal(err)
-	}
-	if version, layout, ok := ReadSyncedVersionAndLayout(); ok || version != "" || layout != "" {
-		t.Fatalf("ReadSyncedVersionAndLayout() = (%q, %q, %v), want empty result for empty version", version, layout, ok)
-	}
-}

internal/skillscheck/sync.go

@@ -21,7 +21,6 @@ var (
 
 type SyncInput struct {
 	Version        string
-	Layout         string
 	OfficialSkills []string
 	LocalSkills    []string
 	PreviousState  *SkillsState
@@ -196,18 +195,7 @@ func parseOfficialSkillsList(lines []string) []string {
 }
 
 func PlanSync(input SyncInput) SyncPlan {
-	official := normalOfficialSkills(input.OfficialSkills)
-	layout, _ := NormalizeLayout(input.Layout)
-	skippedDeleted := deletedOfficialSkills(official, input.LocalSkills, input.PreviousState, input.StateReadable, input.Force, layout)
-	if layout != LayoutSeparate {
-		return SyncPlan{
-			Version:        input.Version,
-			OfficialSkills: official,
-			ToUpdate:       suiteEffectiveSkills(official, toSet(skippedDeleted)),
-			Added:          newlyOfficialSkills(official, input.PreviousState, input.StateReadable),
-			SkippedDeleted: skippedDeleted,
-		}
-	}
+	official := uniqueSorted(input.OfficialSkills)
 	if input.Force {
 		return SyncPlan{
 			Version:        input.Version,
@@ -220,7 +208,19 @@ func PlanSync(input SyncInput) SyncPlan {
 
 	officialSet := toSet(official)
 	installedOfficial := intersection(input.LocalSkills, officialSet)
-	newAddedOfficial := newlyOfficialSkills(official, input.PreviousState, input.StateReadable)
+
+	previousOfficial := []string{}
+	if input.StateReadable && input.PreviousState != nil {
+		previousOfficial = input.PreviousState.OfficialSkills
+	}
+	previousSet := toSet(previousOfficial)
+
+	newAddedOfficial := []string{}
+	for _, skill := range official {
+		if !previousSet[skill] {
+			newAddedOfficial = append(newAddedOfficial, skill)
+		}
+	}
 
 	updateSet := toSet(installedOfficial)
 	for _, skill := range newAddedOfficial {
@@ -229,12 +229,19 @@ func PlanSync(input SyncInput) SyncPlan {
 	toUpdate := sortedKeys(updateSet)
 	updateSet = toSet(toUpdate)
 
+	skipped := []string{}
+	for _, skill := range official {
+		if !updateSet[skill] {
+			skipped = append(skipped, skill)
+		}
+	}
+
 	return SyncPlan{
 		Version:        input.Version,
 		OfficialSkills: official,
 		ToUpdate:       toUpdate,
-		Added:          newAddedOfficial,
-		SkippedDeleted: skippedDeleted,
+		Added:          uniqueSorted(newAddedOfficial),
+		SkippedDeleted: skipped,
 	}
 }
 
@@ -245,16 +252,13 @@ type SkillsRunner interface {
 	ListGlobalSkills() *selfupdate.NpmResult
 	InstallSkill(nameList []string) *selfupdate.NpmResult
 	InstallAllSkills() *selfupdate.NpmResult
-	InstallSuiteSkill() *selfupdate.NpmResult
 }
 
 type SyncOptions struct {
-	Version    string
-	Layout     string
-	FlatSkills []string
-	Force      bool
-	Runner     SkillsRunner
-	Now        func() time.Time
+	Version string
+	Force   bool
+	Runner  SkillsRunner
+	Now     func() time.Time
 }
 
 type SyncResult struct {
@@ -267,9 +271,6 @@ type SyncResult struct {
 	Err            error
 	Detail         string
 	Force          bool
-	Layout         string
-	Flat           []string
-	Collected      []string
 }
 
 func SyncSkills(opts SyncOptions) *SyncResult {
@@ -279,26 +280,16 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	if opts.Runner == nil {
 		return &SyncResult{Action: "failed", Err: fmt.Errorf("skills runner is nil")}
 	}
-	layout, ok := NormalizeLayout(opts.Layout)
-	if !ok {
-		return &SyncResult{Action: "failed", Err: fmt.Errorf("unsupported skills layout %q", opts.Layout)}
-	}
 
 	// --- Step 1: List official skills ---
 	official, reason, ok := listOfficialSkills(opts.Runner)
 	if !ok {
-		if layout != LayoutSeparate {
-			return failedSync(layout, opts.Force, fmt.Errorf("failed to discover official skills for %s layout: %s", layout, reason), reason)
-		}
 		return fallbackFullInstall(opts, reason, nil)
 	}
 
 	// --- Step 2: List local (installed) skills ---
 	local, ok := listLocalSkills(opts.Runner)
 	if !ok {
-		if layout != LayoutSeparate {
-			return failedSync(layout, opts.Force, fmt.Errorf("failed to list local skills for %s layout", layout), "local skills list failed or parsed as empty")
-		}
 		return fallbackFullInstall(opts, "local skills list failed or parsed as empty", official)
 	}
 
@@ -311,17 +302,12 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 
 	plan := PlanSync(SyncInput{
 		Version:        opts.Version,
-		Layout:         layout,
 		OfficialSkills: official,
 		LocalSkills:    local,
 		PreviousState:  previous,
 		StateReadable:  readable,
 		Force:          opts.Force,
 	})
-	flat, collected, err := resolveHybridSkillSets(layout, opts.FlatSkills, plan.OfficialSkills, plan.SkippedDeleted)
-	if err != nil {
-		return &SyncResult{Action: "failed", Err: err, Official: plan.OfficialSkills, Force: opts.Force, Layout: layout}
-	}
 
 	result := &SyncResult{
 		Action:         "synced",
@@ -330,59 +316,25 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 		Added:          plan.Added,
 		SkippedDeleted: plan.SkippedDeleted,
 		Force:          opts.Force,
-		Layout:         layout,
-		Flat:           flat,
-		Collected:      collected,
 	}
 
 	if len(plan.ToUpdate) == 0 {
-		if layout != LayoutSeparate {
-			return failedSync(layout, opts.Force, fmt.Errorf("no target skills to assemble %s layout", layout), "toUpdate skills empty")
-		}
 		return fallbackFullInstall(opts, "toUpdate skills empty fallback", official)
 	}
 
 	if len(plan.ToUpdate) > 0 {
 		installResult := opts.Runner.InstallSkill(plan.ToUpdate)
 		if installResult == nil || installResult.Err != nil {
-			if layout != LayoutSeparate {
-				return failedSync(layout, opts.Force, fmt.Errorf("failed to install skills for %s layout: %s", layout, resultDetail(installResult)), resultDetail(installResult))
-			}
 			return fallbackFullInstall(opts, resultDetail(installResult), official)
 		}
 	}
-	if layout != LayoutSeparate {
-		installSuiteResult := opts.Runner.InstallSuiteSkill()
-		if installSuiteResult == nil || installSuiteResult.Err != nil {
-			result.Action = "failed"
-			result.Err = fmt.Errorf("failed to install %s from isolated skills source: %s", suiteSkillName, resultDetail(installSuiteResult))
-			result.Detail = resultDetail(installSuiteResult)
-			return result
-		}
-		infosResult := opts.Runner.ListGlobalSkillsJSON()
-		if infosResult == nil || infosResult.Err != nil {
-			result.Action = "failed"
-			result.Err = fmt.Errorf("failed to list installed skills for %s assembly: %s", suiteSkillName, resultDetail(infosResult))
-			result.Detail = resultDetail(infosResult)
-			return result
-		}
-		infos := ParseGlobalSkillInfosJSON(infosResult.Stdout.String())
-		keepSharedTopLevel := layout == LayoutHybrid && len(flat) > 0
-		if err := assembleSuiteLayout(layout, collected, keepSharedTopLevel, infos); err != nil {
-			result.Action = "failed"
-			result.Err = fmt.Errorf("failed to assemble %s layout: %w", layout, err)
-			return result
-		}
-	}
 
 	state := SkillsState{
 		Version:              opts.Version,
-		Layout:               layout,
 		OfficialSkills:       plan.OfficialSkills,
 		UpdatedSkills:        plan.ToUpdate,
 		AddedOfficialSkills:  plan.Added,
 		SkippedDeletedSkills: plan.SkippedDeleted,
-		FlatSkills:           stateFlatSkills(layout, flat),
 		UpdatedAt:            opts.Now().UTC().Format(time.RFC3339),
 	}
 	if err := WriteState(state); err != nil {
@@ -394,16 +346,6 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	return result
 }
 
-func failedSync(layout string, force bool, err error, detail string) *SyncResult {
-	return &SyncResult{
-		Action: "failed",
-		Err:    err,
-		Detail: detail,
-		Force:  force,
-		Layout: layout,
-	}
-}
-
 func listOfficialSkills(runner SkillsRunner) ([]string, string, bool) {
 	reasons := []string{}
 
@@ -441,9 +383,8 @@ func listOfficialSkills(runner SkillsRunner) ([]string, string, bool) {
 func listLocalSkills(runner SkillsRunner) ([]string, bool) {
 	jsonResult := runner.ListGlobalSkillsJSON()
 	if jsonResult != nil && jsonResult.Err == nil {
-		infos, valid := parseGlobalSkillInfosJSON(jsonResult.Stdout.String())
-		if valid {
-			return installedSkillNamesFromInfos(infos), true
+		if local := ParseGlobalSkillsJSON(jsonResult.Stdout.String()); len(local) > 0 {
+			return local, true
 		}
 	}
 
@@ -470,7 +411,6 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			Err:    fmt.Errorf("full skills install failed: empty result (reason: %s)", reason),
 			Detail: reason,
 			Force:  opts.Force,
-			Layout: LayoutSeparate,
 		}
 	}
 	if installResult.Err != nil {
@@ -479,13 +419,11 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			Err:    fmt.Errorf("full skills install failed: %w (reason: %s)", installResult.Err, reason),
 			Detail: reason + "\n" + resultDetail(installResult),
 			Force:  opts.Force,
-			Layout: LayoutSeparate,
 		}
 	}
 
 	state := SkillsState{
 		Version:              opts.Version,
-		Layout:               LayoutSeparate,
 		OfficialSkills:       official,
 		UpdatedSkills:        official,
 		AddedOfficialSkills:  official,
@@ -501,7 +439,6 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 			SkippedDeleted: []string{},
 			Detail:         reason + "\nstate write failed: " + writeErr.Error(),
 			Force:          opts.Force,
-			Layout:         LayoutSeparate,
 		}
 	}
 
@@ -513,38 +450,9 @@ func fallbackFullInstall(opts SyncOptions, reason string, official []string) *Sy
 		SkippedDeleted: []string{},
 		Detail:         reason,
 		Force:          opts.Force,
-		Layout:         LayoutSeparate,
 	}
 }
 
-func stateFlatSkills(layout string, requested []string) []string {
-	if layout != LayoutHybrid {
-		return []string{}
-	}
-	out := []string{}
-	for _, skill := range uniqueSorted(requested) {
-		if skill != sharedSkillName {
-			out = append(out, skill)
-		}
-	}
-	return out
-}
-
-func newlyOfficialSkills(official []string, previous *SkillsState, stateReadable bool) []string {
-	previousOfficial := []string{}
-	if stateReadable && previous != nil {
-		previousOfficial = previous.OfficialSkills
-	}
-	previousSet := toSet(previousOfficial)
-	added := []string{}
-	for _, skill := range official {
-		if !previousSet[skill] {
-			added = append(added, skill)
-		}
-	}
-	return uniqueSorted(added)
-}
-
 func resultDetail(result *selfupdate.NpmResult) string {
 	if result == nil {
 		return ""

internal/skillscheck/sync_test.go

@@ -8,7 +8,6 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
-	"sort"
 	"strings"
 	"testing"
 	"time"
@@ -44,14 +43,6 @@ func TestParseOfficialSkillsListAcceptsNonLarkOfficialNames(t *testing.T) {
 	}
 }
 
-func TestParseFlatSkillsTrimsDeduplicatesAndSorts(t *testing.T) {
-	got := ParseFlatSkills(" lark-doc, lark-im,,lark-doc, lark-base ")
-	want := []string{"lark-base", "lark-doc", "lark-im"}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("ParseFlatSkills() = %#v, want %#v", got, want)
-	}
-}
-
 func TestParseGlobalSkillsList(t *testing.T) {
 	input := `Global Skills
 
@@ -225,10 +216,8 @@ type fakeSkillsRunner struct {
 	globalErr        error
 	installErr       error
 	installAllErr    error
-	installSuiteErr  error
 	installed        [][]string
 	installedAll     int
-	installedSuite   int
 	listedIndex      int
 	listedOfficial   int
 	listedGlobalJSON int
@@ -330,13 +319,6 @@ func (f *fakeSkillsRunner) InstallAllSkills() *selfupdate.NpmResult {
 	return r
 }
 
-func (f *fakeSkillsRunner) InstallSuiteSkill() *selfupdate.NpmResult {
-	f.installedSuite++
-	r := &selfupdate.NpmResult{}
-	r.Err = f.installSuiteErr
-	return r
-}
-
 func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
@@ -490,34 +472,6 @@ func TestSyncSkills_OfficialDiscoveryEmptyFallsBackToFullInstallWithReasons(t *t
 	}
 }
 
-func TestSyncSkills_HybridOfficialDiscoveryFailureDoesNotFallback(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	runner := &fakeSkillsRunner{
-		officialIndexErr: fmt.Errorf("index unavailable"),
-		officialErr:      fmt.Errorf("list unavailable"),
-	}
-
-	result := SyncSkills(SyncOptions{
-		Version: "1.0.33",
-		Layout:  LayoutHybrid,
-		Runner:  runner,
-		Now:     time.Now,
-	})
-	if result.Action != "failed" {
-		t.Fatalf("SyncSkills() action = %q, want failed", result.Action)
-	}
-	if result.Layout != LayoutHybrid {
-		t.Fatalf("SyncSkills() layout = %q, want %q", result.Layout, LayoutHybrid)
-	}
-	if result.Err == nil || !strings.Contains(result.Err.Error(), "failed to discover official skills for hybrid layout") {
-		t.Fatalf("SyncSkills() err = %v, want hybrid discovery failure", result.Err)
-	}
-	if runner.installedAll != 0 {
-		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
-	}
-}
-
 func TestSyncSkills_ListOfficialFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
@@ -620,7 +574,7 @@ func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
 	}
 }
 
-func TestSyncSkills_EmptyGlobalJSONInstallsAllOfficialIncrementally(t *testing.T) {
+func TestSyncSkills_ParseEmptyLocalListsFallBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
@@ -631,15 +585,14 @@ func TestSyncSkills_EmptyGlobalJSONInstallsAllOfficialIncrementally(t *testing.T
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Action != "synced" {
-		t.Fatalf("SyncSkills() action = %q, want synced", result.Action)
+	if result.Action != "fallback_synced" {
+		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
 	}
-	if len(runner.installed) != 1 {
-		t.Fatalf("installed = %#v, want one incremental install", runner.installed)
+	if len(runner.installed) != 0 {
+		t.Fatalf("installed = %#v, want no incremental installs", runner.installed)
 	}
-	assertStrings(t, runner.installed[0], []string{"lark-calendar", "lark-mail"})
-	if runner.installedAll != 0 {
-		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
+	if runner.installedAll != 1 {
+		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
 	}
 }
 
@@ -744,200 +697,6 @@ func TestSyncSkills_NilRunnerFails(t *testing.T) {
 	}
 }
 
-func TestSyncSkills_HybridAssemblesSuiteAndMovesCollectedSkills(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	paths := map[string]string{}
-	for _, name := range []string{"lark-calendar", "lark-doc", "lark-shared", "lark-suite"} {
-		paths[name] = filepath.Join(dir, name)
-		writeTestSkill(t, paths[name], name)
-	}
-
-	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-doc", "lark-shared"),
-		globalJSONOut:    globalSkillsJSONFromPaths(paths),
-	}
-
-	result := SyncSkills(SyncOptions{
-		Version:    "1.0.33",
-		Layout:     LayoutHybrid,
-		FlatSkills: []string{"lark-calendar"},
-		Runner:     runner,
-		Now:        time.Now,
-	})
-
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
-	}
-	if runner.installedSuite != 1 {
-		t.Fatalf("installedSuite = %d, want 1", runner.installedSuite)
-	}
-	assertStrings(t, result.Flat, []string{"lark-calendar"})
-	assertStrings(t, result.Collected, []string{"lark-shared", "lark-doc"})
-	if _, err := os.Stat(filepath.Join(paths["lark-suite"], "references", "subskills", "lark-doc", "SKILL.md")); err != nil {
-		t.Fatalf("suite lark-doc missing: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-suite"], "references", "subskills", "lark-shared", "SKILL.md")); err != nil {
-		t.Fatalf("suite lark-shared missing: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-calendar"], "SKILL.md")); err != nil {
-		t.Fatalf("flat lark-calendar missing: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-doc"], "SKILL.md")); !os.IsNotExist(err) {
-		t.Fatalf("collected lark-doc still exists at top level or unexpected err: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-shared"], "SKILL.md")); err != nil {
-		t.Fatalf("lark-shared should stay top-level when flat set is non-empty: %v", err)
-	}
-
-	state, readable, err := ReadState()
-	if err != nil || !readable {
-		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
-	}
-	if state.Layout != LayoutHybrid {
-		t.Fatalf("state.Layout = %q, want %q", state.Layout, LayoutHybrid)
-	}
-	assertStrings(t, state.FlatSkills, []string{"lark-calendar"})
-}
-
-func TestSyncSkills_HybridCollectsNewOfficialSkillOnNextUpdate(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	paths := map[string]string{}
-	for _, name := range []string{"lark-calendar", "lark-doc", "lark-shared", "lark-suite"} {
-		paths[name] = filepath.Join(dir, name)
-		writeTestSkill(t, paths[name], name)
-	}
-
-	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-doc", "lark-shared"),
-		globalJSONOut:    globalSkillsJSONFromPaths(paths),
-	}
-	first := SyncSkills(SyncOptions{
-		Version:    "1.0.33",
-		Layout:     LayoutHybrid,
-		FlatSkills: []string{"lark-calendar"},
-		Runner:     runner,
-		Now:        time.Now,
-	})
-	if first.Err != nil {
-		t.Fatalf("first SyncSkills() err = %v, want nil", first.Err)
-	}
-
-	paths["lark-new"] = filepath.Join(dir, "lark-new")
-	for _, name := range []string{"lark-doc", "lark-new", "lark-shared", "lark-suite"} {
-		writeTestSkill(t, paths[name], name)
-	}
-	runner.officialIndexOut = officialSkillsIndexOutput("lark-calendar", "lark-doc", "lark-new", "lark-shared")
-	runner.globalJSONOut = globalSkillsJSONFromPaths(paths)
-
-	second := SyncSkills(SyncOptions{
-		Version:    "1.0.34",
-		Layout:     LayoutHybrid,
-		FlatSkills: []string{"lark-calendar"},
-		Runner:     runner,
-		Now:        time.Now,
-	})
-	if second.Err != nil {
-		t.Fatalf("second SyncSkills() err = %v, want nil", second.Err)
-	}
-	assertStrings(t, second.Added, []string{"lark-new"})
-	assertStrings(t, second.Flat, []string{"lark-calendar"})
-	assertStrings(t, second.Collected, []string{"lark-shared", "lark-doc", "lark-new"})
-
-	if _, err := os.Stat(filepath.Join(paths["lark-suite"], "references", "subskills", "lark-new", "SKILL.md")); err != nil {
-		t.Fatalf("suite lark-new missing: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-new"], "SKILL.md")); !os.IsNotExist(err) {
-		t.Fatalf("new official skill should be collected, top-level path err: %v", err)
-	}
-	data, err := os.ReadFile(filepath.Join(paths["lark-suite"], "SKILL.md"))
-	if err != nil {
-		t.Fatalf("read suite SKILL.md: %v", err)
-	}
-	if !strings.Contains(string(data), "- lark-new: lark-new description") {
-		t.Fatalf("suite SKILL.md missing lark-new route:\n%s", data)
-	}
-
-	state, readable, err := ReadState()
-	if err != nil || !readable {
-		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
-	}
-	assertStrings(t, state.OfficialSkills, []string{"lark-calendar", "lark-doc", "lark-new", "lark-shared"})
-	assertStrings(t, state.AddedOfficialSkills, []string{"lark-new"})
-	assertStrings(t, state.FlatSkills, []string{"lark-calendar"})
-}
-
-func TestSyncSkills_HybridWithNoFlatSkillsDoesNotKeepSharedTopLevel(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	paths := map[string]string{}
-	for _, name := range []string{"lark-shared", "lark-suite"} {
-		paths[name] = filepath.Join(dir, name)
-		writeTestSkill(t, paths[name], name)
-	}
-
-	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-shared"),
-		globalJSONOut:    globalSkillsJSONFromPaths(paths),
-	}
-
-	result := SyncSkills(SyncOptions{
-		Version: "1.0.33",
-		Layout:  LayoutHybrid,
-		Runner:  runner,
-		Now:     time.Now,
-	})
-
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
-	}
-	if _, err := os.Stat(filepath.Join(paths["lark-shared"], "SKILL.md")); !os.IsNotExist(err) {
-		t.Fatalf("lark-shared should not stay top-level when flat set is empty; err: %v", err)
-	}
-	if result.Flat == nil || len(result.Flat) != 0 {
-		t.Fatalf("result.Flat = %#v, want empty slice", result.Flat)
-	}
-}
-
-func TestSyncSkills_HybridFiltersNonFlatOfficialSkills(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	paths := map[string]string{}
-	for _, name := range []string{"lark-calendar", "lark-shared", "lark-suite"} {
-		paths[name] = filepath.Join(dir, name)
-		writeTestSkill(t, paths[name], name)
-	}
-
-	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-shared"),
-		globalJSONOut:    globalSkillsJSONFromPaths(paths),
-	}
-
-	result := SyncSkills(SyncOptions{
-		Version:    "1.0.33",
-		Layout:     LayoutHybrid,
-		FlatSkills: []string{"lark-calendar", "lark-missing", "lark-shared"},
-		Runner:     runner,
-		Now:        time.Now,
-	})
-
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
-	}
-	assertStrings(t, result.Flat, []string{"lark-calendar"})
-
-	state, readable, err := ReadState()
-	if err != nil || !readable {
-		t.Fatalf("ReadState() = (_, %v, %v), want readable", readable, err)
-	}
-	assertStrings(t, state.FlatSkills, []string{"lark-calendar"})
-}
-
 func TestSyncSkills_ParseEmptyWithNonEmptyStdoutFallsBack(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
@@ -974,81 +733,6 @@ func TestSyncSkills_ParseEmptyWithNonEmptyStdoutAndFullInstallFails(t *testing.T
 	}
 }
 
-func TestNormalizeSuiteTemplateTextRewritesLegacyFlatSkillWording(t *testing.T) {
-	input := "`lark-shared` 是共享基础能力，不作为 `--collected-skills` 的可选项。为了保证 suite 内子能力可用，hybrid 布局会同时保留顶层 `lark-shared`，并在 `lark-suite/references/subskills/lark-shared/SKILL.md` 中维护一份副本。"
-	got := normalizeSuiteTemplateText(input)
-	if strings.Contains(got, "--collected-skills") {
-		t.Fatalf("normalized text still contains legacy flag: %s", got)
-	}
-	if !strings.Contains(got, "--flat-skills") {
-		t.Fatalf("normalized text missing --flat-skills: %s", got)
-	}
-	if !strings.Contains(got, "只有 hybrid 布局存在平铺 skill 时，顶层才会额外保留一份") {
-		t.Fatalf("normalized text missing current lark-shared rule: %s", got)
-	}
-}
-
-func TestSkillDescriptionSupportsFoldedYAMLScalar(t *testing.T) {
-	dir := t.TempDir()
-	path := filepath.Join(dir, "SKILL.md")
-	content := `---
-name: lark-whiteboard
-description: >
-  飞书画板：查询和编辑飞书云文档中的画板。
-  当用户需要查看画板内容、导出画板图片、编辑画板时使用此 skill。
-metadata:
-  requires:
-    bins: ["lark-cli"]
----
-`
-	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	got := skillDescription(path)
-	want := "飞书画板：查询和编辑飞书云文档中的画板。 当用户需要查看画板内容、导出画板图片、编辑画板时使用此 skill。"
-	if got != want {
-		t.Fatalf("skillDescription() = %q, want %q", got, want)
-	}
-}
-
-func TestAssembleSuiteLayoutSeparateIsNoop(t *testing.T) {
-	if err := assembleSuiteLayout(LayoutSeparate, []string{"lark-doc"}, false, nil); err != nil {
-		t.Fatalf("assembleSuiteLayout(separate) err = %v, want nil", err)
-	}
-}
-
-func TestAssembleSuiteLayoutMissingSuiteReturnsError(t *testing.T) {
-	err := assembleSuiteLayout(LayoutHybrid, []string{"lark-doc"}, false, []GlobalSkillInfo{
-		{Name: "lark-doc", Path: filepath.Join(t.TempDir(), "lark-doc")},
-	})
-	if err == nil || !strings.Contains(err.Error(), "lark-suite") {
-		t.Fatalf("assembleSuiteLayout() err = %v, want missing lark-suite error", err)
-	}
-}
-
-func TestCopyDirCopiesNestedFiles(t *testing.T) {
-	root := t.TempDir()
-	src := filepath.Join(root, "src")
-	dst := filepath.Join(root, "dst")
-	if err := os.MkdirAll(filepath.Join(src, "nested"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(src, "nested", "file.txt"), []byte("hello"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-
-	if err := copyDir(src, dst); err != nil {
-		t.Fatalf("copyDir() err = %v, want nil", err)
-	}
-	got, err := os.ReadFile(filepath.Join(dst, "nested", "file.txt"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if string(got) != "hello" {
-		t.Fatalf("copied file = %q, want hello", string(got))
-	}
-}
-
 func assertStrings(t *testing.T, got, want []string) {
 	t.Helper()
 	if !reflect.DeepEqual(got, want) {
@@ -1056,38 +740,6 @@ func assertStrings(t *testing.T, got, want []string) {
 	}
 }
 
-func writeTestSkill(t *testing.T, dir, name string) {
-	t.Helper()
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	content := fmt.Sprintf("---\nname: %s\ndescription: %s description\n---\n", name, name)
-	if name == suiteSkillName {
-		content = "---\nname: lark-suite\ndescription: Lark suite\n---\n<!-- LARK_SUITE_ROUTES -->\n"
-	}
-	if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte(content), 0o644); err != nil {
-		t.Fatal(err)
-	}
-}
-
-func globalSkillsJSONFromPaths(paths map[string]string) string {
-	names := make([]string, 0, len(paths))
-	for name := range paths {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-	var b strings.Builder
-	b.WriteString("[")
-	for i, name := range names {
-		if i > 0 {
-			b.WriteString(",")
-		}
-		fmt.Fprintf(&b, `{"name":%q,"path":%q,"scope":"global","agents":["Codex"]}`, name, paths[name])
-	}
-	b.WriteString("]")
-	return b.String()
-}
-
 func TestSyncSkills_FallbackWithUnknownOfficialWritesMinimalState(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)

internal/vfs/localfileio/path.go

@@ -65,7 +65,7 @@ func safePath(raw, flagName string) (string, error) {
 	}
 
 	if isAbsolutePath(raw) {
-		return "", fmt.Errorf("%s must be a relative path within the current directory, got %q (hint: cd to the target directory first, or use a relative path like ./filename)", flagName, raw)
+		return "", fmt.Errorf("%s must be a relative path within the current directory, got %q (hint: use a relative path like ./filename; flags that support stdin can read an out-of-tree file via '-' instead)", flagName, raw)
 	}
 
 	path := filepath.Clean(raw)

isolated-skills/lark-suite/SKILL.md

@@ -1,33 +0,0 @@
----
-name: lark-suite
-version: 0.1.0
-description: 飞书/Lark 聚合能力入口：当用户需求涉及本文件列出的任一飞书能力时使用；仅负责选择并加载已安装到本 suite 的 lark-* 子能力，不替代具体子能力的操作细节。
-metadata:
-  requires:
-    bins:
-      - lark-cli
----
-
-# Lark Suite
-
-你是飞书/Lark 能力的聚合路由层。你的职责是先判断用户要使用哪个 `lark-*` 子能力，再读取并遵循对应子能力的说明。
-
-`lark-suite` 不直接承载具体 API 操作步骤。除非对应子能力已被读取，否则不要仅根据本文件拼命令、猜参数或执行复杂操作。
-
-## 使用流程
-
-1. 根据用户意图从下方路由表选择一个或多个子能力；即使用户尚未提供链接、ID 或具体工作表，也先选择能力，再由子能力询问缺失信息。
-2. 仅使用本文件列出的路由与对应子能力入口，不要遍历或探测其他技能目录。
-3. 如果目标能力未列出，返回无法路由的明确提示。
-4. 仅读取当前已选子能力明确要求的前置文件。
-5. 按目标子能力的说明执行；认证、租户、身份、权限和通用排障优先遵循 `lark-shared`。
-
-`lark-shared` 是共享基础能力，不作为 `--flat-skills` 的可选项。为了保证 suite 内子能力可用，它始终会进入 `lark-suite/references/subskills/lark-shared/SKILL.md`；只有 hybrid 布局存在平铺 skill 时，顶层才会额外保留一份 `lark-shared`。
-
-多步任务可以组合多个子能力，但每一步都应由具体子能力驱动。例如“查联系人并发消息”先用 `lark-contact` 解析身份，再用 `lark-im` 发消息。
-
-## 能力路由
-
-根据用户意图从以下条目选择对应子能力；如果一个任务涉及多个能力，按实际操作顺序逐步读取并使用对应子能力。
-
-<!-- LARK_SUITE_ROUTES -->

package.json

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

shortcuts/calendar/calendar_create.go

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

shortcuts/calendar/calendar_test.go

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

shortcuts/common/runner.go

@@ -1068,7 +1068,7 @@ func resolveInputFlags(rctx *RuntimeContext, flags []Flag) error {
 			if rctx.stdinConsumed {
 				return ValidationErrorf("--%s: stdin (-) can only be used by one flag", fl.Name).
 					WithParam("--"+fl.Name).
-					WithHint("a process has a single stdin, so only one flag per call may use '-'; pass the others as @file (e.g. --%s @/path/to/file)", fl.Name)
+					WithHint("a process has a single stdin, so only one flag per call may use '-'; pass the others inline or as @file with a relative path under the current directory (e.g. --%s @./payload.json)", fl.Name)
 			}
 			rctx.stdinConsumed = true
 			data, err := io.ReadAll(rctx.IO().In)
@@ -1102,9 +1102,16 @@ func resolveInputFlags(rctx *RuntimeContext, flags []Flag) error {
 			}
 			data, err := cmdutil.ReadInputFile(rctx.FileIO(), path)
 			if err != nil {
-				return ValidationErrorf("--%s: %v", fl.Name, err).
+				verr := ValidationErrorf("--%s: %v", fl.Name, err).
 					WithParam("--" + fl.Name).
 					WithCause(err)
+				if slices.Contains(fl.Input, Stdin) {
+					// Rejected @file paths are usually absolute (temp files under
+					// /tmp). Steer toward stdin rather than cd / copying the file
+					// into the project tree.
+					verr = verr.WithHint("this flag also reads stdin: --%s - < %s", fl.Name, path)
+				}
+				return verr
 			}
 			// strip a leading UTF-8 BOM so it
 			// can't corrupt the first CSV cell or break JSON parsing downstream.

shortcuts/common/runner_input_test.go

@@ -227,6 +227,35 @@ func TestResolveInputFlags_DuplicateStdin(t *testing.T) {
 	}
 }
 
+// TestResolveInputFlags_FileErrorSuggestsStdin pins the recovery hint when
+// an @file path is rejected (typically an absolute /tmp path): flags that
+// also accept stdin must point at `--flag - < path` — never at cd'ing into
+// the target directory or copying the file into the project tree.
+func TestResolveInputFlags_FileErrorSuggestsStdin(t *testing.T) {
+	rctx := newTestRuntimeWithStdin(map[string]string{"csv": "@/tmp/does-not-exist.csv"}, "")
+	flags := []Flag{{Name: "csv", Input: []string{File, Stdin}}}
+
+	err := resolveInputFlags(rctx, flags)
+	if err == nil {
+		t.Fatal("expected error for rejected @file path")
+	}
+	vErr := assertValidationParam(t, err, "--csv")
+	if !strings.Contains(vErr.Hint, "--csv - < /tmp/does-not-exist.csv") {
+		t.Errorf("hint %q should show the stdin form of the same call", vErr.Hint)
+	}
+
+	// A flag without stdin support must not get the stdin hint.
+	rctx = newTestRuntimeWithStdin(map[string]string{"file": "@/tmp/does-not-exist.xlsx"}, "")
+	err = resolveInputFlags(rctx, []Flag{{Name: "file", Input: []string{File}}})
+	if err == nil {
+		t.Fatal("expected error for rejected @file path")
+	}
+	vErr = assertValidationParam(t, err, "--file")
+	if strings.Contains(vErr.Hint, "stdin") {
+		t.Errorf("hint %q must not suggest stdin for a file-only flag", vErr.Hint)
+	}
+}
+
 func TestStripUTF8BOM(t *testing.T) {
 	cases := []struct{ name, in, want string }{
 		{"leading BOM removed", "\uFEFFhello", "hello"},

shortcuts/doc/docs_history.go

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

shortcuts/doc/docs_history_test.go

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

shortcuts/doc/shortcuts.go

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

shortcuts/drive/drive_import_common.go

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

shortcuts/drive/drive_import_common_test.go

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

shortcuts/drive/drive_search.go

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

shortcuts/minutes/minutes_speaker_replace.go

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

shortcuts/minutes/minutes_speaker_replace_test.go

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

shortcuts/minutes/minutes_speakers.go

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

shortcuts/minutes/minutes_speakers_test.go

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

shortcuts/register.go

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

shortcuts/register_test.go

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

shortcuts/sheets/backward/lark_sheets_float_images.go

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

shortcuts/sheets/batch_op_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", "--type", "pixel", "--size", "30"},
-			subInput: `{"sheet-id":"sh1","range":"1","type":"pixel","size":30}`,
+			args:     []string{"--sheet-id", "sh1", "--range", "1", "--height", "30"},
+			subInput: `{"sheet-id":"sh1","range":"1","height":30}`,
 		},
 		{
 			shortcut: "+cols-resize",
@@ -409,12 +409,12 @@ func TestBatchOp_ErrorEquivalence(t *testing.T) {
 			wantContains: "--count must be > 0",
 		},
 		{
-			name:         "+rows-resize --type pixel without --size",
+			name:         "+rows-resize --height with --type standard",
 			shortcut:     RowsResize,
-			args:         []string{"--sheet-id", "sh1", "--range", "1:2", "--type", "pixel"},
+			args:         []string{"--sheet-id", "sh1", "--range", "1:2", "--height", "30", "--type", "standard"},
 			subShortcut:  "+rows-resize",
-			subInput:     `{"sheet-id":"sh1","range":"1:2","type":"pixel"}`,
-			wantContains: "--type pixel requires --size",
+			subInput:     `{"sheet-id":"sh1","range":"1:2","height":30,"type":"standard"}`,
+			wantContains: "--height cannot be combined with --type standard",
 		},
 		{
 			name:         "+sheet-delete missing sheet selector",
@@ -469,6 +469,34 @@ 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
@@ -611,10 +639,10 @@ func TestBatchOp_RejectsBadSubOpInput(t *testing.T) {
 			"--position is required",
 		},
 		{
-			"+rows-resize missing --type",
+			"+rows-resize missing both --height and --type",
 			"+rows-resize",
 			`{"sheet-id":"sh1","range":"1:1"}`,
-			"--type is required",
+			"give --height <px> for a pixel size, or --type standard / auto",
 		},
 		{
 			"+range-copy missing --target-range",
@@ -802,7 +830,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","type":"pixel","size":40}}]`,
+		"--operations", `[{"shortcut":"+rows-resize","input":{"sheet-id":"sh1","range":"23","height":40}}]`,
 		"--yes",
 	})
 	ops = decodeToolInput(t, body, "batch_update")["operations"].([]interface{})

shortcuts/sheets/batch_op_dispatch.go

@@ -4,6 +4,7 @@
 package sheets
 
 import (
+	"sort"
 	"strings"
 )
 
@@ -118,10 +119,19 @@ 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")
 	}},
 
@@ -197,6 +207,54 @@ var batchOpDispatch = map[string]batchOpMapping{
 	"+float-image-delete": {"manage_float_image_object", objDeleteTranslate(floatImageDeleteSpec)},
 }
 
+// allowedBatchShortcuts lists every shortcut accepted inside +batch-update,
+// sorted, for the not-allowed error hint.
+func allowedBatchShortcuts() []string {
+	out := make([]string, 0, len(batchOpDispatch))
+	for sc := range batchOpDispatch {
+		out = append(out, sc)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// subOpInputContract renders one shortcut's complete sub-op key vocabulary
+// (wire-style underscore names) for the translator-failure hint: required
+// flags are marked, the sheet selector pair collapses to a choose-one, and
+// spreadsheet locators are omitted (reserved for the batch top level).
+// Returns "" for shortcuts without a flag-defs entry.
+func subOpInputContract(sc string) string {
+	defs, _ := loadFlagDefs()
+	spec, ok := defs[sc]
+	if !ok {
+		return ""
+	}
+	idFlag, nameFlag := sheetSelectorFlagsForSubOp(sc)
+	var keys []string
+	sheetSelector := ""
+	for _, df := range spec.Flags {
+		if df.Kind == "system" || df.Hidden {
+			continue
+		}
+		switch df.Name {
+		case "url", "spreadsheet-token":
+			continue // reserved: supplied by +batch-update top level
+		case idFlag, nameFlag:
+			sheetSelector = strings.ReplaceAll(idFlag, "-", "_") + "|" + strings.ReplaceAll(nameFlag, "-", "_") + " (choose one)"
+			continue
+		}
+		key := strings.ReplaceAll(df.Name, "-", "_")
+		if df.Required == "required" {
+			key += " (required)"
+		}
+		keys = append(keys, key)
+	}
+	if sheetSelector != "" {
+		keys = append([]string{sheetSelector}, keys...)
+	}
+	return strings.Join(keys, ", ")
+}
+
 // rejectLocalImageInBatch blocks the local-file --image source inside
 // +batch-update: a batch sub-op has no upload phase, so the file could not be
 // turned into a file_token. Callers must pass --image-token / --image-uri.
@@ -262,7 +320,8 @@ func translateBatchOp(raw interface{}, token string, index int) (map[string]inte
 	}
 	scRaw, present := op["shortcut"]
 	if !present {
-		return nil, sheetsValidationForFlag("operations", "operations[%d]: 'shortcut' field is required", index)
+		return nil, sheetsValidationForFlag("operations", "operations[%d]: 'shortcut' field is required", index).
+			WithHint(`each entry must look like {"shortcut":"+cells-set","input":{"sheet_name":"…","range":"A1:B2","cells":[[…]]}} — input uses the shortcut's own flag names`)
 	}
 	sc, ok := scRaw.(string)
 	if !ok || sc == "" {
@@ -270,13 +329,15 @@ func translateBatchOp(raw interface{}, token string, index int) (map[string]inte
 	}
 	mapping, ok := batchOpDispatch[sc]
 	if !ok {
+		// Inline the full allow-list: an agent that guessed a read op or a
+		// fan-out wrapper can pick the right shortcut immediately instead of
+		// spending a --print-schema round trip on the operations enum.
 		return nil, sheetsValidationForFlag(
 			"operations",
 			"operations[%d]: shortcut %q not allowed in +batch-update "+
-				"(read ops / fan-out wrappers like +batch-update / +cells-batch-set-style / +cells-batch-clear / +dropdown-{update,delete} are excluded; "+
-				"run `lark-cli sheets +batch-update --print-schema --flag-name operations` to see the full enum)",
+				"(read ops / fan-out wrappers like +batch-update / +cells-batch-set-style / +cells-batch-clear / +dropdown-{update,delete} are excluded)",
 			index, sc,
-		)
+		).WithHint("allowed shortcuts: %s", strings.Join(allowedBatchShortcuts(), ", "))
 	}
 	inputRaw, hasInput := op["input"]
 	var input map[string]interface{}
@@ -324,7 +385,14 @@ func translateBatchOp(raw interface{}, token string, index int) (map[string]inte
 	sheetName := strings.TrimSpace(fv.Str(sheetNameFlag))
 	body, err := mapping.translate(fv, token, sheetID, sheetName)
 	if err != nil {
-		return nil, sheetsValidationForFlag("operations", "operations[%d] (%s): %v", index, sc, err)
+		// The inner error names one problem at a time (first missing flag);
+		// the hint lists the sub-op's complete key contract so an agent fixes
+		// every gap in a single retry instead of iterating flag by flag.
+		verr := sheetsValidationForFlag("operations", "operations[%d] (%s): %v", index, sc, err)
+		if contract := subOpInputContract(sc); contract != "" {
+			verr = verr.WithHint("%s input keys: %s", sc, contract)
+		}
+		return nil, verr
 	}
 	return map[string]interface{}{
 		"tool_name": mapping.mcpToolName,
@@ -332,11 +400,23 @@ 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 {
+		batches := (len(rawOps) + maxBatchOperations - 1) / maxBatchOperations
+		return nil, sheetsValidationForFlag("operations", "--operations accepts at most %d entries; got %d", maxBatchOperations, len(rawOps)).
+			WithHint("split the operations into %d separate +batch-update calls of at most %d entries each", batches, maxBatchOperations)
+	}
 	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

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

shortcuts/sheets/flag_ergonomics.go

@@ -0,0 +1,238 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"fmt"
+	"slices"
+	"sort"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/suggest"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// ─── sheets flag ergonomics ─────────────────────────────────────────────
+//
+// Eval traces show two recovery loops that burn agent round-trips on the
+// sheets domain specifically: hallucinated flag names (--cols for --range,
+// --file for --csv) whose unknown-flag error only points at --help, and
+// enum values imported from CSS / Excel vocabulary ("center" for the
+// vertical alignment Lark spells "middle"). Both fixes are wired through
+// the existing PostMount hook — composed onto any prior PostMount in
+// Shortcuts(), same pattern as withTokenAlias — so the common framework
+// needs no change at all and no other domain's behavior shifts.
+
+// withFlagErgonomics wraps an optional PostMount so that, after it runs,
+// the command gets the sheets-specific unknown-flag error (valid flags
+// inlined) and enum-value normalization (canonical vocabulary auto-applied,
+// typos suggested).
+func withFlagErgonomics(prev func(cmd *cobra.Command)) func(cmd *cobra.Command) {
+	return func(cmd *cobra.Command) {
+		if prev != nil {
+			prev(cmd)
+		}
+		cmd.SetFlagErrorFunc(sheetsFlagErrorFunc)
+		chainEnumNormalization(cmd)
+	}
+}
+
+// sheetsFlagErrorFunc overrides the root FlagErrorFunc for sheets commands.
+// It keeps the root behavior (typed error, did-you-mean suggestions, the
+// offending flag on params) and additionally inlines the full valid-flag
+// set: hallucinated sheets flags are usually semantic guesses (--cols for
+// --range) that edit distance can't rank, and a --help round trip costs an
+// agent a full extra call. One line here lets it re-issue the command
+// immediately.
+func sheetsFlagErrorFunc(c *cobra.Command, ferr error) error {
+	name, isUnknown := unknownFlagFromParseError(ferr)
+	if !isUnknown {
+		return common.ValidationErrorf("%s", ferr.Error()).
+			WithHint("run `%s --help` for valid flags", c.CommandPath())
+	}
+	valid := visibleFlagNames(c)
+	suggestions := suggest.Closest(name, valid, 3)
+	for i := range suggestions {
+		suggestions[i] = "--" + suggestions[i]
+	}
+	hint := fmt.Sprintf("run `%s --help` to see valid flags", c.CommandPath())
+	if list := inlineFlagList(valid); list != "" {
+		hint = "valid flags: " + list
+		if len(suggestions) > 0 {
+			hint = fmt.Sprintf("did you mean %s? valid flags: %s",
+				strings.Join(suggestions, ", "), list)
+		}
+	}
+	return errs.NewValidationError(errs.SubtypeInvalidArgument,
+		"unknown flag %q for %q", "--"+name, c.CommandPath()).
+		WithParams(errs.InvalidParam{Name: "--" + name, Reason: "unknown flag", Suggestions: suggestions}).
+		WithHint("%s", hint)
+}
+
+// unknownFlagFromParseError extracts the offending long-flag name from
+// cobra's flag-parse error text ("unknown flag: --query" → "query").
+// Returns ok=false for anything else (missing argument, invalid value,
+// unknown shorthand) so those stay structured but generic. Mirrors the
+// root-level parser in cmd; the prefix contract is cobra's English wording.
+func unknownFlagFromParseError(err error) (string, bool) {
+	const p = "unknown flag: --"
+	msg := err.Error()
+	i := strings.Index(msg, p)
+	if i < 0 {
+		return "", false
+	}
+	rest := msg[i+len(p):]
+	if j := strings.IndexAny(rest, " \t"); j >= 0 {
+		rest = rest[:j]
+	}
+	return rest, true
+}
+
+// visibleFlagNames lists the non-hidden flag names registered on c, sorted.
+func visibleFlagNames(c *cobra.Command) []string {
+	var names []string
+	c.Flags().VisitAll(func(f *pflag.Flag) {
+		if !f.Hidden {
+			names = append(names, f.Name)
+		}
+	})
+	sort.Strings(names)
+	return names
+}
+
+// inlineFlagListLimit caps how many flag names ride inline on an
+// unknown-flag hint. Sheets shortcuts stay well under it.
+const inlineFlagListLimit = 25
+
+// inlineFlagList renders valid flag names as one comma-separated line for
+// the unknown-flag hint, truncating past inlineFlagListLimit. Empty when
+// there is nothing to list.
+func inlineFlagList(names []string) string {
+	if len(names) == 0 {
+		return ""
+	}
+	shown := names
+	var suffix string
+	if len(names) > inlineFlagListLimit {
+		shown = names[:inlineFlagListLimit]
+		suffix = fmt.Sprintf(", … (%d more; see --help)", len(names)-inlineFlagListLimit)
+	}
+	parts := make([]string, len(shown))
+	for i, n := range shown {
+		parts[i] = "--" + n
+	}
+	return strings.Join(parts, ", ") + suffix
+}
+
+// ─── enum vocabulary normalization ──────────────────────────────────────
+
+// enumAliases maps habitual values agents import from CSS / Excel / Google
+// Sheets onto the value the Lark API actually uses, keyed by the wrong
+// value. Applied only when the alias target is in the enum (and the wrong
+// value is not), so e.g. "center" still stands for horizontal alignment
+// (where it is valid) and only maps to "middle" for vertical alignment.
+var enumAliases = map[string]string{
+	"center": "middle", // CSS vertical-align: center → Lark "middle"
+	"centre": "center",
+	"middle": "center", // CSS-style middle → Lark horizontal "center"
+}
+
+// canonicalEnumValue returns the enum entry an off-vocabulary value
+// unambiguously means — exact case-insensitive match first, then the
+// cross-vocabulary alias table. Unlike an edit-distance guess, the result
+// is safe to apply on the caller's behalf. Returns "" when the value has
+// no unambiguous canonical form in this enum.
+func canonicalEnumValue(val string, enum []string) string {
+	lower := strings.ToLower(val)
+	for _, allowed := range enum {
+		if strings.ToLower(allowed) == lower {
+			return allowed
+		}
+	}
+	if target, ok := enumAliases[lower]; ok {
+		if slices.Contains(enum, target) {
+			return target
+		}
+	}
+	return ""
+}
+
+// closestEnumValue picks the best "did you mean" candidate for an invalid
+// enum value: the unambiguous canonical form first, then edit distance.
+// For prose suggestions only — an edit-distance match must never be
+// auto-applied. Returns "" when nothing is close.
+func closestEnumValue(val string, enum []string) string {
+	if canon := canonicalEnumValue(val, enum); canon != "" {
+		return canon
+	}
+	if match := suggest.Closest(val, enum, 1); len(match) > 0 {
+		return match[0]
+	}
+	return ""
+}
+
+// chainEnumNormalization installs a PreRunE stage (composed onto any
+// framework-set PreRunE, which runs first so OnInvoke side effects and the
+// --print-schema required-flag relaxation keep their contracts) that
+// normalizes the command's flat enum flags before the common runner
+// validates them:
+//
+//   - an unambiguous vocabulary mismatch (casing, or a known alias like CSS
+//     "center" for Lark's vertical "middle") IS the value the caller meant —
+//     rewrite it in place and proceed instead of failing the call just to
+//     have the agent retype the canonical spelling;
+//   - anything else fails here with the allowed list plus a "did you mean"
+//     hint for edit-distance typos — a guess is never auto-applied.
+//
+// No-op for commands whose flag defs declare no enums.
+func chainEnumNormalization(cmd *cobra.Command) {
+	defs, _ := loadFlagDefs()
+	spec, ok := defs[cmd.Name()]
+	if !ok {
+		return
+	}
+	var enumFlags []flagDef
+	for _, df := range spec.Flags {
+		if df.Kind != "system" && len(df.Enum) > 0 && df.Type == "string" {
+			enumFlags = append(enumFlags, df)
+		}
+	}
+	if len(enumFlags) == 0 {
+		return
+	}
+	prev := cmd.PreRunE
+	cmd.PreRunE = func(c *cobra.Command, args []string) error {
+		if prev != nil {
+			if err := prev(c, args); err != nil {
+				return err
+			}
+		}
+		// --print-schema is pure local introspection; the runner never enum-
+		// validates that path, so don't start here.
+		if want, err := c.Flags().GetBool("print-schema"); err == nil && want {
+			return nil
+		}
+		for _, df := range enumFlags {
+			val, err := c.Flags().GetString(df.Name)
+			if err != nil || val == "" || slices.Contains(df.Enum, val) {
+				continue
+			}
+			if canon := canonicalEnumValue(val, df.Enum); canon != "" {
+				c.Flags().Set(df.Name, canon)
+				continue
+			}
+			verr := common.ValidationErrorf("invalid value %q for --%s, allowed: %s",
+				val, df.Name, strings.Join(df.Enum, ", ")).
+				WithParam("--" + df.Name)
+			if match := suggest.Closest(val, df.Enum, 1); len(match) > 0 {
+				verr = verr.WithHint("did you mean %q?", match[0])
+			}
+			return verr
+		}
+		return nil
+	}
+}

shortcuts/sheets/flag_ergonomics_test.go

@@ -0,0 +1,296 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+func TestUnknownFlagFromParseError(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		in   string
+		name string
+		ok   bool
+	}{
+		{"unknown flag: --cols", "cols", true},
+		{"unknown flag: --with-styles", "with-styles", true},
+		{"unknown shorthand flag: 'z' in -z", "", false},
+		{"flag needs an argument: --find", "", false},
+		{`invalid argument "x" for "--count"`, "", false},
+	}
+	for _, c := range cases {
+		name, ok := unknownFlagFromParseError(errors.New(c.in))
+		if name != c.name || ok != c.ok {
+			t.Errorf("unknownFlagFromParseError(%q) = (%q,%v), want (%q,%v)", c.in, name, ok, c.name, c.ok)
+		}
+	}
+}
+
+// TestSheetsFlagErrorFunc_SemanticGuessListsValidFlags pins the sheets
+// override of the root unknown-flag error: --cols is a semantic guess for
+// --range that edit distance can't rank, so the hint must inline the full
+// valid-flag list instead of deferring to a --help round trip.
+func TestSheetsFlagErrorFunc_SemanticGuessListsValidFlags(t *testing.T) {
+	t.Parallel()
+	c := &cobra.Command{Use: "demo"}
+	c.Flags().String("range", "", "")
+	c.Flags().Int("width", 0, "")
+
+	err := sheetsFlagErrorFunc(c, errors.New("unknown flag: --cols"))
+	var verr *errs.ValidationError
+	if !errors.As(err, &verr) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if verr.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("subtype = %q, want invalid_argument", verr.Subtype)
+	}
+	if len(verr.Params) != 1 || verr.Params[0].Name != "--cols" {
+		t.Errorf("Params = %v, want one entry named --cols", verr.Params)
+	}
+	if strings.Contains(verr.Hint, "--help") {
+		t.Errorf("hint should not defer to --help when flags fit inline, got %q", verr.Hint)
+	}
+	for _, want := range []string{"--range", "--width"} {
+		if !strings.Contains(verr.Hint, want) {
+			t.Errorf("hint should inline valid flag %s, got %q", want, verr.Hint)
+		}
+	}
+}
+
+// TestSheetsFlagErrorFunc_TypoKeepsSuggestion pins that the root behavior
+// (did-you-mean suggestion, machine-readable Suggestions) is preserved by
+// the sheets override, with the valid-flag list appended.
+func TestSheetsFlagErrorFunc_TypoKeepsSuggestion(t *testing.T) {
+	t.Parallel()
+	c := &cobra.Command{Use: "demo"}
+	c.Flags().String("range", "", "")
+	c.Flags().Bool("dry-run", false, "")
+
+	err := sheetsFlagErrorFunc(c, errors.New("unknown flag: --rang"))
+	var verr *errs.ValidationError
+	if !errors.As(err, &verr) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	found := false
+	for _, s := range verr.Params[0].Suggestions {
+		if s == "--range" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("Suggestions should include --range, got %v", verr.Params[0].Suggestions)
+	}
+	for _, want := range []string{"did you mean", "--range", "--dry-run"} {
+		if !strings.Contains(verr.Hint, want) {
+			t.Errorf("hint should contain %q, got %q", want, verr.Hint)
+		}
+	}
+}
+
+func TestSheetsFlagErrorFunc_OtherErrorStaysGeneric(t *testing.T) {
+	t.Parallel()
+	c := &cobra.Command{Use: "demo"}
+	err := sheetsFlagErrorFunc(c, errors.New("flag needs an argument: --find"))
+	var verr *errs.ValidationError
+	if !errors.As(err, &verr) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if verr.Param != "" || len(verr.Params) != 0 {
+		t.Errorf("Param=%q Params=%v, want both empty for generic flag error", verr.Param, verr.Params)
+	}
+	if strings.Contains(verr.Hint, "did you mean") {
+		t.Errorf("generic flag error must not produce a did-you-mean hint, got %q", verr.Hint)
+	}
+}
+
+func TestInlineFlagList_TruncatesPastLimit(t *testing.T) {
+	t.Parallel()
+	if got := inlineFlagList(nil); got != "" {
+		t.Errorf("inlineFlagList(nil) = %q, want empty", got)
+	}
+	names := make([]string, inlineFlagListLimit+5)
+	for i := range names {
+		names[i] = fmt.Sprintf("flag-%02d", i)
+	}
+	got := inlineFlagList(names)
+	if !strings.Contains(got, "5 more") || !strings.Contains(got, "--help") {
+		t.Errorf("truncated list should count the overflow and defer to --help, got %q", got)
+	}
+	if strings.Contains(got, names[inlineFlagListLimit]) {
+		t.Errorf("list should stop at the limit, got %q", got)
+	}
+}
+
+func TestCanonicalEnumValue(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		val  string
+		enum []string
+		want string
+	}{
+		{"SUM", []string{"sum", "count"}, "sum"},                  // casing
+		{"center", []string{"top", "middle", "bottom"}, "middle"}, // alias: CSS vertical center
+		{"middle", []string{"left", "center", "right"}, "center"}, // alias: horizontal middle
+		{"overwite", []string{"append", "overwrite"}, ""},         // typo is NOT canonical
+		{"delete", []string{"append", "overwrite"}, ""},           // nothing close
+	}
+	for _, c := range cases {
+		if got := canonicalEnumValue(c.val, c.enum); got != c.want {
+			t.Errorf("canonicalEnumValue(%q, %v) = %q, want %q", c.val, c.enum, got, c.want)
+		}
+	}
+}
+
+func TestClosestEnumValue(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		val  string
+		enum []string
+		want string
+	}{
+		{"SUM", []string{"sum", "count"}, "sum"},                   // casing
+		{"center", []string{"top", "middle", "bottom"}, "middle"},  // alias
+		{"overwite", []string{"append", "overwrite"}, "overwrite"}, // edit distance
+		{"delete", []string{"append", "overwrite"}, ""},            // nothing close
+	}
+	for _, c := range cases {
+		if got := closestEnumValue(c.val, c.enum); got != c.want {
+			t.Errorf("closestEnumValue(%q, %v) = %q, want %q", c.val, c.enum, got, c.want)
+		}
+	}
+}
+
+// TestChainEnumNormalization_UnitContract pins the PreRunE stage in
+// isolation: canonical vocabulary is auto-applied, typos error with a
+// suggestion (never applied), the framework PreRunE keeps running first,
+// and --print-schema skips enum gating entirely.
+func TestChainEnumNormalization_UnitContract(t *testing.T) {
+	t.Parallel()
+	newCmd := func() (*cobra.Command, *bool) {
+		cmd := &cobra.Command{Use: "+cells-set-style"}
+		cmd.Flags().String("vertical-alignment", "", "")
+		cmd.Flags().Bool("print-schema", false, "")
+		prevCalled := false
+		cmd.PreRunE = func(*cobra.Command, []string) error {
+			prevCalled = true
+			return nil
+		}
+		chainEnumNormalization(cmd)
+		return cmd, &prevCalled
+	}
+
+	// Alias auto-applied, framework PreRunE preserved.
+	cmd, prevCalled := newCmd()
+	cmd.Flags().Set("vertical-alignment", "center")
+	if err := cmd.PreRunE(cmd, nil); err != nil {
+		t.Fatalf("center should normalize and pass, got: %v", err)
+	}
+	if got, _ := cmd.Flags().GetString("vertical-alignment"); got != "middle" {
+		t.Errorf("vertical-alignment = %q, want rewritten to %q", got, "middle")
+	}
+	if !*prevCalled {
+		t.Error("framework PreRunE must keep running first")
+	}
+
+	// Typo: error with suggestion, value untouched.
+	cmd, _ = newCmd()
+	cmd.Flags().Set("vertical-alignment", "botom")
+	err := cmd.PreRunE(cmd, nil)
+	var verr *errs.ValidationError
+	if !errors.As(err, &verr) {
+		t.Fatalf("typo should fail with *errs.ValidationError, got %T: %v", err, err)
+	}
+	if !strings.Contains(verr.Hint, `"bottom"`) {
+		t.Errorf("hint should suggest bottom for the typo, got %q", verr.Hint)
+	}
+	if got, _ := cmd.Flags().GetString("vertical-alignment"); got != "botom" {
+		t.Errorf("typo must not be rewritten, got %q", got)
+	}
+
+	// --print-schema skips enum gating (pure local introspection).
+	cmd, _ = newCmd()
+	cmd.Flags().Set("vertical-alignment", "not-a-value")
+	cmd.Flags().Set("print-schema", "true")
+	if err := cmd.PreRunE(cmd, nil); err != nil {
+		t.Errorf("--print-schema must skip enum gating, got: %v", err)
+	}
+}
+
+// shortcutFromRegistry returns the fully wired shortcut (PostMount
+// ergonomics included) as Shortcuts() exposes it to the framework.
+func shortcutFromRegistry(t *testing.T, command string) common.Shortcut {
+	t.Helper()
+	for _, sc := range Shortcuts() {
+		if sc.Command == command {
+			return sc
+		}
+	}
+	t.Fatalf("shortcut %q not found in Shortcuts()", command)
+	return common.Shortcut{}
+}
+
+// TestShortcuts_FlagErgonomicsMounted verifies the ergonomics ride every
+// mounted sheets command end-to-end: enum vocabulary normalizes on a real
+// invocation, and unknown flags answer with the inlined valid-flag list.
+func TestShortcuts_FlagErgonomicsMounted(t *testing.T) {
+	t.Parallel()
+
+	t.Run("enum alias normalizes through a real run", func(t *testing.T) {
+		t.Parallel()
+		sc := shortcutFromRegistry(t, "+cells-set-style")
+		stdout, _, err := runShortcutCapturingErr(t, sc, []string{
+			"--url", testURL,
+			"--sheet-name", "s",
+			"--range", "A1:A1",
+			"--vertical-alignment", "center",
+			"--dry-run",
+		})
+		if err != nil {
+			t.Fatalf("center should normalize to middle and pass, got: %v", err)
+		}
+		if !strings.Contains(stdout, "middle") || strings.Contains(stdout, "center") {
+			t.Errorf("dry-run body should carry the normalized value, got %q", stdout)
+		}
+	})
+
+	t.Run("enum typo errors with suggestion", func(t *testing.T) {
+		t.Parallel()
+		sc := shortcutFromRegistry(t, "+cells-set-style")
+		_, _, err := runShortcutCapturingErr(t, sc, []string{
+			"--url", testURL,
+			"--sheet-name", "s",
+			"--range", "A1:A1",
+			"--vertical-alignment", "botom",
+			"--dry-run",
+		})
+		ve := requireValidation(t, err, `invalid value "botom" for --vertical-alignment`)
+		if !strings.Contains(ve.Hint, `"bottom"`) {
+			t.Errorf("hint should suggest bottom, got %q", ve.Hint)
+		}
+	})
+
+	t.Run("unknown flag inlines valid flags", func(t *testing.T) {
+		t.Parallel()
+		sc := shortcutFromRegistry(t, "+cols-resize")
+		_, _, err := runShortcutCapturingErr(t, sc, []string{
+			"--url", testURL,
+			"--sheet-name", "s",
+			"--cols", "A:D",
+		})
+		ve := requireValidation(t, err, `unknown flag "--cols"`)
+		for _, want := range []string{"valid flags:", "--range", "--width", "--widths"} {
+			if !strings.Contains(ve.Hint, want) {
+				t.Errorf("hint should contain %q, got %q", want, ve.Hint)
+			}
+		}
+	})
+}

shortcuts/sheets/flag_schema.go

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

shortcuts/sheets/flag_schema_validate.go

@@ -5,6 +5,7 @@ package sheets
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"sort"
 	"strings"
@@ -97,11 +98,22 @@ func validateValueAgainstSchema(fv flagView, name string, value interface{}) err
 		// Composite-JSON shape errors (e.g. +cells-set --cells, chart
 		// --properties) are the highest-frequency usage-layer failure for
 		// sheets, and agents often burn several retries guessing the shape.
-		// Point them straight at --print-schema, which dumps the exact JSON
-		// Schema for this (command, flag) pair. The hint is always actionable:
-		// reaching this branch means entry[name] resolved a schema from the
-		// embedded index, and --print-schema reads that same index, so the
-		// suggested command is guaranteed to print it.
+		// A shallow type mismatch means the caller misremembered the overall
+		// container shape (the classic {"cells": ...} wrapper around what
+		// must be a bare 2D array), so inline a skeleton of the expected
+		// shape — that fixes the retry without a --print-schema round trip.
+		// Deeper failures keep the --print-schema pointer, which dumps the
+		// exact JSON Schema for this (command, flag) pair; reaching this
+		// branch means entry[name] resolved a schema from the embedded
+		// index, so the suggested command is guaranteed to print it.
+		var tm *typeMismatchError
+		if errors.As(vErr, &tm) && pathDepth(tm.path) <= skeletonPathDepthLimit {
+			if sk := schemaSkeleton(&schema, skeletonMaxDepth); sk != "" {
+				return sheetsValidationForFlag(name,
+					"--%s: %s; expected shape: %s (run `lark-cli sheets %s --print-schema --flag-name %s` for the full JSON Schema)",
+					name, vErr.Error(), sk, command, name).WithCause(vErr)
+			}
+		}
 		return sheetsValidationForFlag(name,
 			"--%s: %s; run `lark-cli sheets %s --print-schema --flag-name %s` to see the expected JSON Schema",
 			name, vErr.Error(), command, name).WithCause(vErr)
@@ -243,7 +255,7 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 
 	if schema.Type != "" {
 		if !matchesJSONType(value, schema.Type) {
-			return fmt.Errorf("%sexpected type %q, got %q", pathPrefix(path), schema.Type, jsType(value))
+			return &typeMismatchError{path: path, expected: schema.Type, got: jsType(value)}
 		}
 	}
 
@@ -251,20 +263,20 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 	// already reported above). Apply to both `number` and `integer` types.
 	if num, ok := value.(float64); ok {
 		if schema.Minimum != nil && num < *schema.Minimum {
-			return fmt.Errorf("%svalue %v is below minimum %v", pathPrefix(path), num, *schema.Minimum)
+			return fmt.Errorf("%svalue %v is below minimum %v", pathPrefix(path), num, *schema.Minimum) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 		if schema.Maximum != nil && num > *schema.Maximum {
-			return fmt.Errorf("%svalue %v is above maximum %v", pathPrefix(path), num, *schema.Maximum)
+			return fmt.Errorf("%svalue %v is above maximum %v", pathPrefix(path), num, *schema.Maximum) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 	}
 
 	// Array length bounds — only checked when value is an array.
 	if arr, ok := value.([]interface{}); ok {
 		if schema.MinItems != nil && len(arr) < *schema.MinItems {
-			return fmt.Errorf("%sarray has %d items, minimum is %d", pathPrefix(path), len(arr), *schema.MinItems)
+			return fmt.Errorf("%sarray has %d items, minimum is %d", pathPrefix(path), len(arr), *schema.MinItems) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 		if schema.MaxItems != nil && len(arr) > *schema.MaxItems {
-			return fmt.Errorf("%sarray has %d items, maximum is %d", pathPrefix(path), len(arr), *schema.MaxItems)
+			return fmt.Errorf("%sarray has %d items, maximum is %d", pathPrefix(path), len(arr), *schema.MaxItems) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 	}
 
@@ -279,10 +291,10 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 		if !matched {
 			msg := fmt.Sprintf("%svalue %s is not in enum %s",
 				pathPrefix(path), formatJSONValue(value), formatEnum(schema.Enum))
-			if hint := suggestEnumMatch(value, schema.Enum); hint != "" {
+			if hint := suggestEnumForError(value, schema.Enum); hint != "" {
 				msg += fmt.Sprintf(` (did you mean %q?)`, hint)
 			}
-			return fmt.Errorf("%s", msg)
+			return fmt.Errorf("%s", msg) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 	}
 
@@ -295,7 +307,7 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 			}
 		}
 		if !matched {
-			return fmt.Errorf("%svalue does not match any of oneOf alternatives", pathPrefix(path))
+			return fmt.Errorf("%svalue does not match any of oneOf alternatives", pathPrefix(path)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 		}
 	}
 
@@ -305,7 +317,7 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 	if obj, ok := value.(map[string]interface{}); ok {
 		for _, key := range schema.Required {
 			if _, present := obj[key]; !present {
-				return fmt.Errorf("required property %q is missing at %s", key, pathOrRoot(path))
+				return fmt.Errorf("required property %q is missing at %s", key, pathOrRoot(path)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 			}
 		}
 		if schema.Properties != nil {
@@ -357,7 +369,7 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 			sort.Strings(extras)
 			for _, key := range extras {
 				if schema.AdditionalProperties.Strict {
-					return fmt.Errorf("%sunexpected property %q (not declared in schema)", pathPrefix(path), key)
+					return fmt.Errorf("%sunexpected property %q (not declared in schema)", pathPrefix(path), key) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
 				}
 				if schema.AdditionalProperties.Schema != nil {
 					child := key
@@ -388,6 +400,126 @@ func validateAgainstSchema(value interface{}, schema *schemaProperty, path strin
 	return nil
 }
 
+// typeMismatchError is the type-check branch of validateAgainstSchema
+// as a typed error, so validateValueAgainstSchema can recognize shape
+// confusion (vs. deep value errors) and inline a skeleton of the
+// expected shape. Error() keeps the exact legacy wording.
+type typeMismatchError struct {
+	path     string
+	expected string
+	got      string
+}
+
+func (e *typeMismatchError) Error() string {
+	return fmt.Sprintf("%sexpected type %q, got %q", pathPrefix(e.path), e.expected, e.got)
+}
+
+// pathDepth counts how many levels below the flag root a JSON path
+// points at: "" → 0, "[0]" → 1, "[0][3]" → 2, "[0][3].value" → 3,
+// "legend" → 1, "snapshot.axes" → 2. Every "[" and "." starts a new
+// segment; a leading bare key (no bracket) is one segment of its own.
+func pathDepth(path string) int {
+	depth := strings.Count(path, "[") + strings.Count(path, ".")
+	if path != "" && path[0] != '[' {
+		depth++
+	}
+	return depth
+}
+
+// Skeleton rendering bounds: a mismatch at depth ≤ 2 is container-shape
+// confusion worth a skeleton; deeper mismatches are value-level and the
+// full schema pointer serves better. The skeleton itself stops after
+// four levels and eight keys per object so it stays one line; a wide
+// object (> skeletonWideObject keys) collapses its children to type
+// placeholders so every key stays visible instead of the first branch
+// eating the whole line.
+const (
+	skeletonPathDepthLimit = 2
+	skeletonMaxDepth       = 4
+	skeletonMaxKeys        = 8
+	skeletonWideObject     = 2
+)
+
+// schemaSkeleton renders a compact single-line sketch of the shape a
+// schema expects, e.g. [[{"value": …, "formula": "…", …}]] for
+// +cells-set --cells. Required keys come first, then alphabetical,
+// capped at skeletonMaxKeys with a trailing … marker. Values render as
+// their type placeholder; enum strings show the first allowed value.
+func schemaSkeleton(s *schemaProperty, depth int) string {
+	if s == nil {
+		return "…"
+	}
+	if len(s.OneOf) > 0 && s.Type == "" {
+		return schemaSkeleton(s.OneOf[0], depth)
+	}
+	switch s.Type {
+	case "array":
+		if depth <= 0 {
+			return "[…]"
+		}
+		return "[" + schemaSkeleton(s.Items, depth-1) + "]"
+	case "object":
+		if depth <= 0 || len(s.Properties) == 0 {
+			return "{…}"
+		}
+		keys := skeletonKeys(s)
+		childDepth := depth - 1
+		if len(s.Properties) > skeletonWideObject {
+			childDepth = 0
+		}
+		parts := make([]string, 0, len(keys)+1)
+		for _, k := range keys {
+			parts = append(parts, fmt.Sprintf("%q: %s", k, schemaSkeleton(s.Properties[k], childDepth)))
+		}
+		if len(s.Properties) > len(keys) {
+			parts = append(parts, "…")
+		}
+		return "{" + strings.Join(parts, ", ") + "}"
+	case "string":
+		if len(s.Enum) > 0 {
+			return formatJSONValue(s.Enum[0])
+		}
+		return `"…"`
+	case "number", "integer":
+		return "0"
+	case "boolean":
+		return "false"
+	}
+	return "…"
+}
+
+// skeletonKeys picks which object keys a skeleton shows: required keys
+// first (schema order), then remaining keys alphabetically, capped at
+// skeletonMaxKeys.
+func skeletonKeys(s *schemaProperty) []string {
+	keys := make([]string, 0, skeletonMaxKeys)
+	seen := make(map[string]struct{}, skeletonMaxKeys)
+	for _, k := range s.Required {
+		if _, ok := s.Properties[k]; !ok {
+			continue
+		}
+		if len(keys) == skeletonMaxKeys {
+			return keys
+		}
+		keys = append(keys, k)
+		seen[k] = struct{}{}
+	}
+	rest := make([]string, 0, len(s.Properties))
+	for k := range s.Properties {
+		if _, dup := seen[k]; !dup {
+			rest = append(rest, k)
+		}
+	}
+	sort.Strings(rest)
+	for _, k := range rest {
+		if len(keys) == skeletonMaxKeys {
+			break
+		}
+		keys = append(keys, k)
+	}
+	return keys
+}
+
 func matchesJSONType(value interface{}, expected string) bool {
 	switch expected {
 	case "object":
@@ -473,25 +605,48 @@ func joinFormatted(values []interface{}) string {
 	return strings.Join(parts, ", ")
 }
 
-// suggestEnumMatch returns a "did you mean" candidate when the user's
-// value differs from an allowed enum entry only in casing — the most
-// common real-world mistake ("SUM" vs "sum", "True" vs "true"). The
-// match is restricted to strings; non-string enums (numbers, etc.)
-// don't have a casing notion. Returns "" when no near-miss exists.
+// suggestEnumMatch returns the canonical enum entry when the user's
+// value unambiguously means one — casing ("SUM" vs "sum", "True" vs
+// "true") or a cross-vocabulary alias (CSS "center" for Lark's vertical
+// "middle"). Callers auto-apply the result, so it must stay restricted
+// to unambiguous matches (edit-distance guesses belong in
+// suggestEnumForError only). Non-string values have no vocabulary
+// notion. Returns "" when no unambiguous match exists.
 func suggestEnumMatch(value interface{}, values []interface{}) string {
 	s, ok := value.(string)
 	if !ok {
 		return ""
 	}
-	lower := strings.ToLower(s)
+	canon := canonicalEnumValue(s, stringEnumEntries(values))
+	if canon == "" || canon == s { // skip exact-equal (already would have matched).
+		return ""
+	}
+	return canon
+}
+
+// stringEnumEntries extracts the string members of a JSON-schema enum
+// list (mixed-type enums keep only their string entries).
+func stringEnumEntries(values []interface{}) []string {
+	out := make([]string, 0, len(values))
 	for _, v := range values {
-		if vs, ok := v.(string); ok && strings.ToLower(vs) == lower {
-			if vs != s { // skip exact-equal (already would have matched).
-				return vs
-			}
+		if vs, ok := v.(string); ok {
+			out = append(out, vs)
 		}
 	}
-	return ""
+	return out
+}
+
+// suggestEnumForError picks the "did you mean" candidate for an enum
+// error message. Unlike suggestEnumMatch (whose result is auto-applied,
+// so it must stay unambiguous), this one may also draw on edit distance
+// — the suggestion is only prose, the user still has to re-issue the
+// value explicitly.
+func suggestEnumForError(value interface{}, values []interface{}) string {
+	s, ok := value.(string)
+	if !ok {
+		return ""
+	}
+	return closestEnumValue(s, stringEnumEntries(values))
 }
 
 func pathPrefix(path string) string {

shortcuts/sheets/flag_schema_validate_test.go

@@ -360,6 +360,142 @@ func TestValidateInputAgainstSchema_RealEnumCaseNormalized(t *testing.T) {
 	}
 }
 
+// TestValidateAgainstSchema_EnumAliasNormalized pins the cross-vocabulary
+// auto-fix: CSS-habit "center" for a vertical alignment unambiguously means
+// Lark's "middle", so the payload is normalized in place and the call
+// proceeds — same treatment as the "SUM" vs "sum" casing class.
+func TestValidateAgainstSchema_EnumAliasNormalized(t *testing.T) {
+	t.Parallel()
+	schema := parseSchema(t, `{
+		"type":"object",
+		"properties":{"vertical_alignment":{"type":"string","enum":["top","middle","bottom"]}}
+	}`)
+	obj := map[string]interface{}{"vertical_alignment": "center"}
+	if err := validateAgainstSchema(obj, schema, ""); err != nil {
+		t.Fatalf("center should normalize to middle and pass, got: %v", err)
+	}
+	if got := obj["vertical_alignment"]; got != "middle" {
+		t.Errorf("vertical_alignment = %q, want normalized to %q", got, "middle")
+	}
+}
+
+// TestValidateAgainstSchema_EnumTypoSuggestedNotApplied pins the auto-apply
+// boundary on the error path: an edit-distance typo stays an error with a
+// "did you mean" suggestion, never a silent rewrite.
+func TestValidateAgainstSchema_EnumTypoSuggestedNotApplied(t *testing.T) {
+	t.Parallel()
+	schema := parseSchema(t, `{
+		"type":"object",
+		"properties":{"order":{"type":"string","enum":["asc","desc"]}}
+	}`)
+	obj := map[string]interface{}{"order": "ascc"}
+	err := validateAgainstSchema(obj, schema, "")
+	if err == nil {
+		t.Fatal("typo must be rejected")
+	}
+	if !strings.Contains(err.Error(), `did you mean "asc"?`) {
+		t.Errorf("enum error should suggest asc for the typo, got %q", err.Error())
+	}
+	if got := obj["order"]; got != "ascc" {
+		t.Errorf("typo must not be rewritten, got %q", got)
+	}
+}
+
+// TestValidateValueAgainstSchema_ShapeSkeletonOnShallowTypeMismatch
+// pins the highest-frequency eval failure: passing an object where
+// --cells expects a 2D array must inline a skeleton of the expected
+// shape (with the "value" key visible) so an agent fixes the retry
+// without a --print-schema round trip.
+func TestValidateValueAgainstSchema_ShapeSkeletonOnShallowTypeMismatch(t *testing.T) {
+	t.Parallel()
+	fv := mapFlagView{command: "+cells-set"}
+	err := validateValueAgainstSchema(fv, "cells",
+		map[string]interface{}{"cells": []interface{}{}})
+	if err == nil {
+		t.Fatal("object where array expected must fail")
+	}
+	msg := err.Error()
+	for _, want := range []string{`expected type "array", got "object"`, "expected shape: [[{", `"value"`} {
+		if !strings.Contains(msg, want) {
+			t.Errorf("error should contain %q, got %q", want, msg)
+		}
+	}
+
+	// Deep value-level mismatch keeps the plain --print-schema pointer
+	// (a whole-shape skeleton would not address the actual problem).
+	deep := []interface{}{[]interface{}{
+		map[string]interface{}{"note": 12.5},
+	}}
+	err = validateValueAgainstSchema(fv, "cells", deep)
+	if err == nil {
+		t.Fatal("wrong type for note must fail")
+	}
+	if strings.Contains(err.Error(), "expected shape:") {
+		t.Errorf("deep mismatch should not inline a skeleton, got %q", err.Error())
+	}
+	if !strings.Contains(err.Error(), "--print-schema") {
+		t.Errorf("deep mismatch should keep the --print-schema pointer, got %q", err.Error())
+	}
+}
+
+func TestPathDepth(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		path string
+		want int
+	}{
+		{"", 0},
+		{"[0]", 1},
+		{"[0][3]", 2},
+		{"[0][3].value", 3},
+		{"legend", 1},
+		{"snapshot.axes", 2},
+	}
+	for _, c := range cases {
+		if got := pathDepth(c.path); got != c.want {
+			t.Errorf("pathDepth(%q) = %d, want %d", c.path, got, c.want)
+		}
+	}
+}
+
+func TestSchemaSkeleton(t *testing.T) {
+	t.Parallel()
+	schema := parseSchema(t, `{
+		"type":"array",
+		"items":{
+			"type":"array",
+			"items":{
+				"type":"object",
+				"properties":{
+					"value":{},
+					"formula":{"type":"string"},
+					"align":{"type":"string","enum":["top","middle","bottom"]},
+					"styles":{"type":"object","properties":{"bold":{"type":"boolean"}}}
+				}
+			}
+		}
+	}`)
+	got := schemaSkeleton(schema, skeletonMaxDepth)
+	// Wide object (>2 keys) collapses nested containers to placeholders;
+	// enum strings surface their first allowed value.
+	want := `[[{"align": "top", "formula": "…", "styles": {…}, "value": …}]]`
+	if got != want {
+		t.Errorf("skeleton = %s, want %s", got, want)
+	}
+
+	narrow := parseSchema(t, `{
+		"type":"object",
+		"required":["sheets"],
+		"properties":{"sheets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"}}}}}
+	}`)
+	got = schemaSkeleton(narrow, skeletonMaxDepth)
+	// Narrow object (≤2 keys) keeps descending so the inner shape shows.
+	want = `{"sheets": [{"name": "…"}]}`
+	if got != want {
+		t.Errorf("narrow skeleton = %s, want %s", got, want)
+	}
+}
+
 // TestValidateAgainstSchema_NilSchemaSafe pins the defensive
 // `if schema == nil { return nil }` guard. Current production callers
 // always hand validator a real schema, but the guard means future

shortcuts/sheets/flag_schemas_gen.go

@@ -19,6 +19,7 @@ var commandsWithSchema = map[string]struct{}{
 	"+cells-set-style":       {},
 	"+chart-create":          {},
 	"+chart-update":          {},
+	"+cols-resize":           {},
 	"+cond-format-create":    {},
 	"+cond-format-update":    {},
 	"+dropdown-set":          {},
@@ -30,6 +31,7 @@ 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))
+				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
 			}
 			if math.Trunc(f) != f {
-				return fmt.Errorf("--%s must be an integer, got %s", name, strconv.FormatFloat(f, 'g', -1, 64))
+				return fmt.Errorf("--%s must be an integer, got %s", name, strconv.FormatFloat(f, 'g', -1, 64)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
 			}
 		case "float64":
 			if _, isNum := val.(float64); !isNum {
-				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val))
+				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
 			}
 		case "bool":
 			if _, isBool := val.(bool); !isBool {
-				return fmt.Errorf("--%s must be a boolean, got %s", name, jsonTypeName(val))
+				return fmt.Errorf("--%s must be a boolean, got %s", name, jsonTypeName(val)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
 			}
 		}
 	}

shortcuts/sheets/helpers.go

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

shortcuts/sheets/lark_sheet_batch_update.go

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

shortcuts/sheets/lark_sheet_batch_update_test.go

@@ -5,6 +5,7 @@ package sheets
 
 import (
 	"encoding/json"
+	"strings"
 	"testing"
 )
 
@@ -419,6 +420,94 @@ func TestBatchUpdate_TranslatorRejects(t *testing.T) {
 	}
 }
 
+// TestBatchUpdate_PrescriptiveHints pins the recovery hints that ride on the
+// highest-frequency batch failures, so an agent can repair its payload in a
+// single retry without --help / --print-schema round trips.
+func TestBatchUpdate_PrescriptiveHints(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name       string
+		opsJSON    string
+		wantMatch  string
+		wantInHint []string
+	}{
+		{
+			name:       "missing shortcut gets entry template",
+			opsJSON:    `[{"input":{"range":"A1"}}]`,
+			wantMatch:  "'shortcut' field is required",
+			wantInHint: []string{`{"shortcut":"+cells-set"`, `"input"`},
+		},
+		{
+			name:       "disallowed shortcut lists the allow-list inline",
+			opsJSON:    `[{"shortcut":"+cells-batch-set-style","input":{}}]`,
+			wantMatch:  "not allowed in +batch-update",
+			wantInHint: []string{"allowed shortcuts:", "+cells-set-style", "+range-copy"},
+		},
+		{
+			name:       "translator failure lists full key contract",
+			opsJSON:    `[{"shortcut":"+dim-insert","input":{"sheet_name":"s"}}]`,
+			wantMatch:  "--position is required",
+			wantInHint: []string{"+dim-insert input keys:", "sheet_id|sheet_name (choose one)", "position (required)", "count (required)", "inherit_style"},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			_, _, err := runShortcutCapturingErr(t, BatchUpdate, []string{
+				"--url", testURL,
+				"--operations", tc.opsJSON,
+				"--yes",
+				"--dry-run",
+			})
+			ve := requireValidation(t, err, tc.wantMatch)
+			for _, want := range tc.wantInHint {
+				if !strings.Contains(ve.Hint, want) {
+					t.Errorf("hint should contain %q, got %q", want, ve.Hint)
+				}
+			}
+		})
+	}
+}
+
+// TestTranslateBatchOperations_OverLimitSplitHint pins the split
+// prescription on the 100-entry cap: the hint must say how many batches
+// the caller should re-issue.
+func TestTranslateBatchOperations_OverLimitSplitHint(t *testing.T) {
+	t.Parallel()
+	ops := make([]interface{}, 185)
+	for i := range ops {
+		ops[i] = map[string]interface{}{"shortcut": "+cells-set", "input": map[string]interface{}{}}
+	}
+	_, err := translateBatchOperations(ops, "shtcnX")
+	ve := requireValidation(t, err, "accepts at most 100 entries; got 185")
+	for _, want := range []string{"2 separate +batch-update calls", "at most 100 entries each"} {
+		if !strings.Contains(ve.Hint, want) {
+			t.Errorf("hint should contain %q, got %q", want, ve.Hint)
+		}
+	}
+}
+
+// TestSubOpInputContract pins the contract line derivation from flag-defs:
+// reserved spreadsheet locators are omitted, the sheet selector collapses
+// to a choose-one, and required flags are marked.
+func TestSubOpInputContract(t *testing.T) {
+	t.Parallel()
+	got := subOpInputContract("+dim-insert")
+	for _, want := range []string{"sheet_id|sheet_name (choose one)", "position (required)", "count (required)", "inherit_style"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("contract should contain %q, got %q", want, got)
+		}
+	}
+	for _, banned := range []string{"url", "spreadsheet_token", "dry_run"} {
+		if strings.Contains(got, banned) {
+			t.Errorf("contract must not expose %q, got %q", banned, got)
+		}
+	}
+	if got := subOpInputContract("+no-such-shortcut"); got != "" {
+		t.Errorf("unknown shortcut should yield empty contract, got %q", got)
+	}
+}
+
 // TestBatchUpdate_DimFreezeInjectsFreeze covers the static-freeze-only
 // path: +dim-freeze always injects operation=freeze (count==0 unfreeze
 // path of the single shortcut is intentionally not supported in batch).
@@ -447,7 +536,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","type":"pixel","size":30}}]`,
+		"--operations", `[{"shortcut":"+rows-resize","input":{"sheet_id":"sh1","range":"1:3","height":30}}]`,
 		"--yes",
 	})
 	input := decodeToolInput(t, body, "batch_update")

shortcuts/sheets/lark_sheet_changeset.go

@@ -0,0 +1,106 @@
+// 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, token)
+		return invokeToolDryRun(token, ToolKindRead, "get_changeset", input)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		input, err := changesetInput(runtime, token)
+		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, token string) (map[string]interface{}, error) {
+	start, end, err := changesetRevisions(runtime)
+	if err != nil {
+		return nil, err
+	}
+	input := map[string]interface{}{
+		"excel_id":       token,
+		"start_revision": start,
+	}
+	if end > 0 {
+		input["end_revision"] = end
+	}
+	return input, nil
+}

shortcuts/sheets/lark_sheet_changeset_test.go

@@ -0,0 +1,88 @@
+// 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{}{
+				"excel_id":       testToken,
+				"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{}{
+				"excel_id":       testToken,
+				"start_revision": float64(120),
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			body := parseDryRunBody(t, ChangesetGet, tt.args)
+			got := decodeToolInput(t, body, "get_changeset")
+			assertInputEquals(t, got, tt.wantInput)
+		})
+	}
+}
+
+// TestChangesetGet_Validation covers the client-side revision guards, which
+// mirror the server cap (sheet-facade-agg maxChangesetRevGap = 20).
+func TestChangesetGet_Validation(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name    string
+		args    []string
+		wantSub string
+	}{
+		{
+			name:    "start-revision must be >= 1",
+			args:    []string{"--url", testURL, "--start-revision", "0"},
+			wantSub: "start-revision must be >= 1",
+		},
+		{
+			name:    "end before start rejected",
+			args:    []string{"--url", testURL, "--start-revision", "100", "--end-revision", "50"},
+			wantSub: "end-revision",
+		},
+		{
+			name:    "gap over 20 rejected",
+			args:    []string{"--url", testURL, "--start-revision", "1", "--end-revision", "30"},
+			wantSub: "version gap exceeds limit",
+		},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+			stdout, stderr, err := runShortcutCapturingErr(t, ChangesetGet, append(c.args, "--dry-run"))
+			if err == nil {
+				t.Fatalf("expected validation error; stdout=%s stderr=%s", stdout, stderr)
+			}
+			if !strings.Contains(stdout+stderr+err.Error(), c.wantSub) {
+				t.Errorf("expected %q; got=%s|%s|%v", c.wantSub, stdout, stderr, err)
+			}
+		})
+	}
+}

shortcuts/sheets/lark_sheet_formula_verify.go

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

shortcuts/sheets/lark_sheet_formula_verify_test.go

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

shortcuts/sheets/lark_sheet_history_list.go

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

shortcuts/sheets/lark_sheet_history_revert.go

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

shortcuts/sheets/lark_sheet_history_test.go

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

shortcuts/sheets/lark_sheet_range_operations.go

@@ -5,6 +5,8 @@ package sheets
 
 import (
 	"context"
+	"fmt"
+	"sort"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
@@ -208,77 +210,81 @@ func mergeInput(runtime flagView, token, sheetID, sheetName, op string, withMerg
 	return input, nil
 }
 
-// resize_range exposes two CLI shortcuts:
+// resize_range exposes two CLI shortcuts, each with two input forms:
 //
-//   +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.
+//   +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).
 //
 // 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. --type auto enables
-// auto-fit (rows only); --type pixel requires --size.
+// 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.
 var RowsResize = common.Shortcut{
 	Service:     "sheets",
 	Command:     "+rows-resize",
-	Description: "Resize rows by pixel / standard / auto (--type pixel needs --size; --range is 1-based A1 like \"2:10\" or \"5\").",
+	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\").",
 	Risk:        "write",
 	Scopes:      []string{"sheets:spreadsheet:write_only"},
 	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags:       flagsFor("+rows-resize"),
 	Validate:    validateViaResize("row"),
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		token, _ := resolveSpreadsheetToken(runtime)
-		sheetID, sheetName, _ := resolveSheetSelector(runtime)
-		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
-		}
-		sheetID, sheetName, err := resolveSheetSelector(runtime)
-		if err != nil {
-			return err
-		}
-		input, err := resizeInput(runtime, token, sheetID, sheetName, "row")
-		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
-	},
+	DryRun:      resizeDryRun("row"),
+	Execute:     resizeExecute("row"),
 }
 
-// ColsResize wraps resize_range for column widths. Column widths do not
-// support auto-fit — --type only accepts pixel / standard.
+// 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 by pixel / standard (--type pixel needs --size; --range is column letters like \"A:E\" or \"C\"; no auto for cols).",
+	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: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	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 {
 		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 {
+		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 {
 		token, err := resolveSpreadsheetTokenExec(runtime)
 		if err != nil {
 			return err
@@ -287,22 +293,21 @@ var ColsResize = common.Shortcut{
 		if err != nil {
 			return err
 		}
-		input, err := resizeInput(runtime, token, sheetID, sheetName, "column")
+		toolName, input, err := resizeToolCall(runtime, token, sheetID, sheetName, dimension)
 		if err != nil {
 			return err
 		}
-		out, err := callTool(ctx, runtime, token, ToolKindWrite, "resize_range", input)
+		out, err := callTool(ctx, runtime, token, ToolKindWrite, toolName, 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.
+// validateViaResize wires the standalone Validate to resizeToolCall so both
+// forms (uniform + map) are fully validated before execution.
 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)
@@ -311,17 +316,82 @@ 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 = resizeInput(runtime, token, sheetID, sheetName, dimension)
+		_, _, err = resizeToolCall(runtime, token, sheetID, sheetName, dimension)
 		return err
 	}
 }
 
-// autoSuffix appends " / auto" to the enum hint for rows.
-func autoSuffix(dimension string) string {
-	if dimension == "row" {
-		return " / auto"
+// 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
 	}
-	return ""
+	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 {
+	if dimension == "row" {
+		return "standard / 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
 }
 
 // commandForDimension returns the shortcut command name a given dimension
@@ -339,6 +409,11 @@ 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
@@ -361,29 +436,42 @@ 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"))
-	if typ == "" {
-		return nil, sheetsValidationForFlag("type", "--type is required (pixel / standard%s)", autoSuffix(dimension))
+	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 dimension == "column" && typ == "auto" {
+	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" {
 		return nil, sheetsValidationForFlag("type", "--type auto is rows-only (column widths do not support auto-fit); use +rows-resize")
 	}
-	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"))
+	if hasType && typ == "pixel" && !hasSize {
+		return nil, common.ValidationErrorf("--type pixel requires --%s <px>", sizeFlag).WithParams(sheetsInvalidParam("type", "required"), sheetsInvalidParam(sizeFlag, "required"))
 	}
-	if typ != "pixel" && hasSize {
-		return nil, common.ValidationErrorf("--size is only valid with --type pixel").WithParams(sheetsInvalidParam("size", "mutually exclusive"), sheetsInvalidParam("type", "mutually exclusive"))
+
+	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
 	}
+
 	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 {
@@ -392,6 +480,122 @@ 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 pixel 200",
+			name:     "+rows-resize --range 1:5 --height 200",
 			sc:       RowsResize,
-			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--type", "pixel", "--size", "200"},
+			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--height", "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 standard",
+			name:     "+cols-resize --range B:D --type standard",
 			sc:       ColsResize,
 			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "B:D", "--type", "standard"},
 			toolName: "resize_range",
@@ -152,9 +152,22 @@ func TestRangeOperationsShortcuts_DryRun(t *testing.T) {
 			},
 		},
 		{
-			name:     "+cols-resize --range A:C pixel 120",
+			name:     "+cols-resize --range A:C --width 120",
 			sc:       ColsResize,
-			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A:C", "--type", "pixel", "--size", "120"},
+			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"},
 			toolName: "resize_range",
 			wantInput: map[string]interface{}{
 				"range": "A:C",
@@ -296,6 +309,163 @@ 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 {
@@ -305,22 +475,58 @@ func TestResize_TypeAndSizeGuards(t *testing.T) {
 		want string
 	}{
 		{
-			name: "+rows-resize --type pixel without --size",
+			name: "+rows-resize missing both --height and --type",
 			sc:   RowsResize,
-			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--type", "pixel"},
-			want: "--type pixel requires --size",
+			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5"},
+			want: "give --height <px> for a pixel size, or --type standard / auto",
 		},
 		{
-			name: "+rows-resize --type standard with --size",
+			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", "--type", "standard", "--size", "30"},
-			want: "--size is only valid with --type pixel",
+			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",
+			sc:   RowsResize,
+			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "1:5", "--type", "pixel"},
+			want: "--type pixel requires --height",
+		},
+		{
+			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",
+			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",
 		},
 		{
 			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: pixel, standard"
+			want: "auto", // cobra Enum gate kicks first with "valid values are: standard"
 		},
 		{
 			name: "+rows-resize given column range",

shortcuts/sheets/lark_sheet_revision_get.go

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

shortcuts/sheets/lark_sheet_revision_get_test.go

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

shortcuts/sheets/lark_sheet_sheet_structure.go

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

shortcuts/sheets/lark_sheet_table_io.go

@@ -317,17 +317,52 @@ func (in *tableSheetIn) normalize(idx int) (tableSheetSpec, error) {
 	// compare against the canonical set.
 	for k := range in.Dtypes {
 		if !seenCol[k] {
-			return tableSheetSpec{}, common.ValidationErrorf("--sheets[%d] %q: dtypes references unknown column %q", idx, in.Name, k)
+			return tableSheetSpec{}, common.ValidationErrorf("--sheets[%d] %q: dtypes references unknown column %q", idx, in.Name, k).
+				WithHint("%s", columnKeyHint("dtypes", k, in.Columns))
 		}
 	}
 	for k := range in.Formats {
 		if !seenCol[k] {
-			return tableSheetSpec{}, common.ValidationErrorf("--sheets[%d] %q: formats references unknown column %q", idx, in.Name, k)
+			return tableSheetSpec{}, common.ValidationErrorf("--sheets[%d] %q: formats references unknown column %q", idx, in.Name, k).
+				WithHint("%s", columnKeyHint("formats", k, in.Columns))
 		}
 	}
 	return spec, nil
 }
 
+// columnKeyHint explains a dtypes/formats key that matched no column. The
+// dominant failure is Excel habit — keying by column letter (A/B/AA) instead
+// of the column name — so call that out explicitly; either way, inline the
+// declared column names so the retry needs no second look at the payload.
+func columnKeyHint(field, key string, columns []string) string {
+	shown := columns
+	const maxShown = 12
+	suffix := ""
+	if len(shown) > maxShown {
+		shown = shown[:maxShown]
+		suffix = ", …"
+	}
+	list := `"` + strings.Join(shown, `", "`) + `"` + suffix
+	if isColumnLetterKey(key) {
+		return fmt.Sprintf("%s keys must be column names from `columns`, not A1-style column letters; this sheet's columns: %s", field, list)
+	}
+	return fmt.Sprintf("%s keys must exactly match a name in `columns`: %s", field, list)
+}
+
+// isColumnLetterKey reports whether key looks like an A1-style column letter
+// (A, B, AA, …) rather than a real column name.
+func isColumnLetterKey(key string) bool {
+	if key == "" || len(key) > 3 {
+		return false
+	}
+	for _, r := range key {
+		if r < 'A' || r > 'Z' {
+			return false
+		}
+	}
+	return true
+}
+
 func (p *tablePayload) validate() error {
 	if len(p.Sheets) == 0 {
 		return common.ValidationErrorf("--sheets: must contain at least one sheet")
@@ -382,6 +417,32 @@ func (p *tablePayload) validate() error {
 			return common.ValidationErrorf("--sheets[%d] %q: mode %q is invalid (want \"overwrite\" or \"append\")", i, s.Name, s.Mode)
 		}
 	}
+	return p.checkCellBudget()
+}
+
+// maxTablePutCells bounds how many cells a single +table-put / +workbook-create
+// write may materialize. Unlike the fan-out stamp cap (maxStampMatrixCells),
+// these cells come from the caller's own --sheets/--values payload rather than a
+// range blow-up, so this is a generous OOM guardrail, not a usability limit:
+// buildSheetMatrix builds the whole rows×cols matrix of per-cell maps in memory
+// before slicing it into tablePutMaxCellsPerWrite-sized writes, so an unbounded
+// payload (2.6M cells ≈ 900MB heap, doubled again by json.Marshal) OOMs the
+// process before the first write leaves.
+const maxTablePutCells = 1_000_000
+
+// checkCellBudget rejects a payload whose total materialized cell count across
+// all sheets exceeds maxTablePutCells. Counted in int64 to stay overflow-safe on
+// pathological row/column counts.
+func (p *tablePayload) checkCellBudget() error {
+	var total int64
+	for i := range p.Sheets {
+		total += int64(len(p.Sheets[i].Rows)) * int64(len(p.Sheets[i].Columns))
+	}
+	if total > maxTablePutCells {
+		return common.ValidationErrorf(
+			"--sheets/--values cover %d cells total, over the %d-cell safety cap; split the write across smaller payloads",
+			total, maxTablePutCells)
+	}
 	return nil
 }
 
@@ -558,6 +619,12 @@ var excelEpoch = time.Date(1899, 12, 30, 0, 0, 0, 0, time.UTC)
 // parser still rejects it cleanly.
 func isoDateToSerial(s string) (int, error) {
 	s = strings.TrimSpace(s)
+	if s == "" {
+		// Empty cells in a date-typed column are the classic header/total-row
+		// clash with the column-wide dtype declaration; name the three ways
+		// out so the caller does not have to guess what "bad format" means.
+		return 0, fmt.Errorf("date column has an empty cell — drop the empty rows, fill real yyyy-mm-dd dates, or declare the column dtype as object (text)") //nolint:forbidigo // intermediate error; callers wrap it into a typed --sheets/--values validation error with row/column context
+	}
 	if i := strings.Index(s, "T"); i > 0 {
 		s = s[:i]
 	}
@@ -643,7 +710,8 @@ func writeSheetData(ctx context.Context, runtime *common.RuntimeContext, token,
 	if err != nil {
 		return nil, err
 	}
-	if err := applyWorkbookCreateStylesToMatrix(matrix, styles, col0, baseRow, fmt.Sprintf("--styles for sheet %q", s.Name)); err != nil {
+	matrix, err = applyWorkbookCreateStylesToMatrix(matrix, styles, col0, baseRow, fmt.Sprintf("--styles for sheet %q", s.Name))
+	if err != nil {
 		return nil, err
 	}
 
@@ -655,11 +723,15 @@ func writeSheetData(ctx context.Context, runtime *common.RuntimeContext, token,
 		}, nil
 	}
 
+	// styles can pad the matrix wider than the declared columns (cell_styles on
+	// blank cells past the data extent), so the written width comes from the
+	// padded matrix, not ncols.
+	writeCols := len(matrix[0])
 	startCol := columnIndexToLetter(col0)
-	endCol := columnIndexToLetter(col0 + ncols - 1)
+	endCol := columnIndexToLetter(col0 + writeCols - 1)
 	allowOverwrite := s.AllowOverwrite == nil || *s.AllowOverwrite
 
-	rowsPerBatch := tablePutMaxCellsPerWrite / ncols
+	rowsPerBatch := tablePutMaxCellsPerWrite / writeCols
 	if rowsPerBatch < 1 {
 		rowsPerBatch = 1
 	}
@@ -693,7 +765,7 @@ func writeSheetData(ctx context.Context, runtime *common.RuntimeContext, token,
 		"sheet_id":  sheetID,
 		"range":     fmt.Sprintf("%s%d:%s%d", startCol, baseRow+1, endCol, baseRow+len(matrix)),
 		"data_rows": len(s.Rows),
-		"columns":   ncols,
+		"columns":   writeCols,
 		"writes":    writes,
 		"mode":      writeModeName(s),
 	}, nil
@@ -785,7 +857,7 @@ func writeTypedSheets(ctx context.Context, runtime *common.RuntimeContext, token
 		s := &payload.Sheets[i]
 		sheetID, ok := byName[s.Name]
 		if !ok {
-			rows, cols := sheetCreateDims(s)
+			rows, cols := sheetCreateDims(s, styles.styleFor(i))
 			sheetID, err = createSheet(ctx, runtime, token, s.Name, rows, cols)
 			if err != nil {
 				return written, fmt.Errorf("creating sheet %q failed: %w", s.Name, err) //nolint:forbidigo // intermediate error; surfaced as a partial_success message string via tablePutPartial, not a typed final error
@@ -864,10 +936,12 @@ func createSheet(ctx context.Context, runtime *common.RuntimeContext, token, nam
 
 // sheetCreateDims sizes a to-be-created sheet to the spec's write range so the
 // follow-up set_cell_range can't exceed sheet bounds. It accounts for the
-// start_cell offset and the optional header row. The backend's 20×200 defaults
-// are kept as floors (ordinary small tables are created exactly as before) and
-// its hard limits (200 cols, 50000 rows) as ceilings.
-func sheetCreateDims(s *tableSheetSpec) (rows, cols int) {
+// start_cell offset, the optional header row, and any --styles extent (so a
+// cell_styles / merge / resize op past the data still fits the grid). The
+// backend's 20×200 defaults are kept as floors (ordinary small tables are
+// created exactly as before) and its hard limits (200 cols, 50000 rows) as
+// ceilings.
+func sheetCreateDims(s *tableSheetSpec, styles *workbookCreateStylePayload) (rows, cols int) {
 	_, col0, row0, _ := sheetAnchor(s)
 	cols = col0 + len(s.Columns)
 	rows = row0 + len(s.Rows)
@@ -882,6 +956,19 @@ func sheetCreateDims(s *tableSheetSpec) (rows, cols int) {
 	if headerOn(s) || (s.Mode == "append" && s.Header == nil) {
 		rows++
 	}
+	// --styles can reach past the data (cell_styles on blank cells get padded
+	// into the matrix and written; merges / resizes run as separate ops). Size
+	// the grid to cover them too. workbookCreateStyleDimensions returns the
+	// extent relative to the anchor, so add the anchor offset back.
+	if styles != nil {
+		styleRows, styleCols := workbookCreateStyleDimensions(styles, col0, row0)
+		if col0+styleCols > cols {
+			cols = col0 + styleCols
+		}
+		if row0+styleRows > rows {
+			rows = row0 + styleRows
+		}
+	}
 	if cols < 20 {
 		cols = 20
 	}
@@ -979,8 +1066,6 @@ func tablePutDryRun(runtime *common.RuntimeContext) *common.DryRunAPI {
 	for i := range payload.Sheets {
 		s := &payload.Sheets[i]
 		matrix, _ := buildSheetMatrix(s, headerOn(s))
-		desc := fmt.Sprintf("write sheet %q (%d data rows × %d cols, mode=%s) via set_cell_range",
-			s.Name, len(s.Rows), len(s.Columns), writeModeName(s))
 		rng := tablePutFullRange(s, len(matrix))
 		if s.Mode == "append" {
 			rng = "<append below existing data>"
@@ -988,10 +1073,23 @@ func tablePutDryRun(runtime *common.RuntimeContext) *common.DryRunAPI {
 			// cell_styles are merged into the matrix only for overwrite mode,
 			// where the anchor row is known statically; append's base row is
 			// resolved at execute time, so the preview leaves the matrix bare
-			// (the merges / sizes ops below still render).
+			// (the merges / sizes ops below still render). Padding can widen /
+			// lengthen the matrix past the data, so recompute the range from the
+			// padded dims to match what Execute writes.
 			_, col0, row0, _ := sheetAnchor(s)
-			_ = applyWorkbookCreateStylesToMatrix(matrix, sheetStyles.styleFor(i), col0, row0, fmt.Sprintf("--styles for sheet %q", s.Name))
+			matrix, _ = applyWorkbookCreateStylesToMatrix(matrix, sheetStyles.styleFor(i), col0, row0, fmt.Sprintf("--styles for sheet %q", s.Name))
+			if len(matrix) > 0 {
+				rng = fmt.Sprintf("%s%d:%s%d",
+					columnIndexToLetter(col0), row0+1,
+					columnIndexToLetter(col0+len(matrix[0])-1), row0+len(matrix))
+			}
 		}
+		writeCols := len(s.Columns)
+		if len(matrix) > 0 {
+			writeCols = len(matrix[0])
+		}
+		desc := fmt.Sprintf("write sheet %q (%d data rows × %d cols, mode=%s) via set_cell_range",
+			s.Name, len(s.Rows), writeCols, writeModeName(s))
 		input := map[string]interface{}{
 			"excel_id":   token,
 			"sheet_name": s.Name,

shortcuts/sheets/lark_sheet_table_io_test.go

@@ -54,6 +54,67 @@ func TestTablePut_IsoDateToSerial(t *testing.T) {
 	}
 }
 
+// TestTablePut_EmptyDatePrescription pins the empty-cell branch: the error
+// must name the three ways out (drop rows / fill dates / object dtype)
+// instead of the generic "must be ISO" parse failure.
+func TestTablePut_EmptyDatePrescription(t *testing.T) {
+	t.Parallel()
+	for _, in := range []string{"", "   "} {
+		_, err := isoDateToSerial(in)
+		if err == nil {
+			t.Fatalf("isoDateToSerial(%q) should fail", in)
+		}
+		for _, want := range []string{"empty cell", "object (text)"} {
+			if !strings.Contains(err.Error(), want) {
+				t.Errorf("isoDateToSerial(%q) error should contain %q, got %q", in, want, err.Error())
+			}
+		}
+	}
+}
+
+// TestTablePut_ColumnKeyHint pins the dtypes/formats unknown-column hint:
+// A1-style letter keys get the Excel-habit callout, and the declared column
+// names ride inline either way.
+func TestTablePut_ColumnKeyHint(t *testing.T) {
+	t.Parallel()
+	cols := []string{"姓名", "出生日期"}
+	got := columnKeyHint("dtypes", "A", cols)
+	for _, want := range []string{"not A1-style column letters", `"姓名", "出生日期"`} {
+		if !strings.Contains(got, want) {
+			t.Errorf("letter-key hint should contain %q, got %q", want, got)
+		}
+	}
+	got = columnKeyHint("formats", "出生 日期", cols)
+	if strings.Contains(got, "A1-style") {
+		t.Errorf("non-letter key must not get the letter callout, got %q", got)
+	}
+	if !strings.Contains(got, `"姓名", "出生日期"`) {
+		t.Errorf("hint should inline column names, got %q", got)
+	}
+
+	many := make([]string, 20)
+	for i := range many {
+		many[i] = fmt.Sprintf("col%02d", i)
+	}
+	got = columnKeyHint("dtypes", "X", many)
+	if !strings.Contains(got, ", …") || strings.Contains(got, "col19") {
+		t.Errorf("hint should truncate long column lists, got %q", got)
+	}
+}
+
+func TestIsColumnLetterKey(t *testing.T) {
+	t.Parallel()
+	cases := map[string]bool{
+		"A": true, "Z": true, "AA": true, "ABC": true,
+		"": false, "ABCD": false, "a": false, "A1": false, "姓名": false,
+	}
+	for in, want := range cases {
+		if got := isColumnLetterKey(in); got != want {
+			t.Errorf("isColumnLetterKey(%q) = %v, want %v", in, got, want)
+		}
+	}
+}
+
 func TestTablePut_BuildTypedCell(t *testing.T) {
 	t.Parallel()
 
@@ -537,14 +598,15 @@ func TestTablePut_SheetCreateDims(t *testing.T) {
 	cases := []struct {
 		name               string
 		spec               tableSheetSpec
+		styles             *workbookCreateStylePayload
 		wantRows, wantCols int
 	}{
-		{"small table keeps 20x200 floor", tableSheetSpec{Columns: cols(3), Rows: rows(5)}, 200, 20},
-		{"wide table grows columns", tableSheetSpec{Columns: cols(37), Rows: rows(22)}, 200, 37},
-		{"long table grows rows", tableSheetSpec{Columns: cols(3), Rows: rows(500)}, 501, 20},
-		{"start_cell offset adds to both", tableSheetSpec{StartCell: "C5", Columns: cols(40), Rows: rows(5)}, 200, 42},
-		{"header:false drops the header row", tableSheetSpec{Header: bp(false), Columns: cols(3), Rows: rows(500)}, 500, 20},
-		{"columns clamp at backend max 200", tableSheetSpec{Columns: cols(250), Rows: rows(5)}, 200, 200},
+		{"small table keeps 20x200 floor", tableSheetSpec{Columns: cols(3), Rows: rows(5)}, nil, 200, 20},
+		{"wide table grows columns", tableSheetSpec{Columns: cols(37), Rows: rows(22)}, nil, 200, 37},
+		{"long table grows rows", tableSheetSpec{Columns: cols(3), Rows: rows(500)}, nil, 501, 20},
+		{"start_cell offset adds to both", tableSheetSpec{StartCell: "C5", Columns: cols(40), Rows: rows(5)}, nil, 200, 42},
+		{"header:false drops the header row", tableSheetSpec{Header: bp(false), Columns: cols(3), Rows: rows(500)}, nil, 500, 20},
+		{"columns clamp at backend max 200", tableSheetSpec{Columns: cols(250), Rows: rows(5)}, nil, 200, 200},
 		// Default headerOn() is false for append mode, but writeSheetData forces
 		// a header when append hits an empty sheet with no explicit Header
 		// choice (so column names aren't lost). sheetCreateDims runs only on
@@ -552,14 +614,22 @@ func TestTablePut_SheetCreateDims(t *testing.T) {
 		// match: append + Header=nil ⇒ +1 row. Otherwise an append-near-50000
 		// payload would be created one row short.
 		{"append on new sheet sizes for the forced header row (49999 data rows + 1 header = 50000)",
-			tableSheetSpec{Mode: "append", Columns: cols(3), Rows: rows(49999)}, 50000, 20},
+			tableSheetSpec{Mode: "append", Columns: cols(3), Rows: rows(49999)}, nil, 50000, 20},
 		{"append + Header=false (explicit) does NOT add the forced header row",
-			tableSheetSpec{Mode: "append", Header: bp(false), Columns: cols(3), Rows: rows(50)}, 200, 20},
+			tableSheetSpec{Mode: "append", Header: bp(false), Columns: cols(3), Rows: rows(50)}, nil, 200, 20},
+		// --styles reaching past the data grows the grid so a cell_styles op on a
+		// blank cell (or a merge / resize) still fits after the create.
+		{"styles past the data grow the grid",
+			tableSheetSpec{Columns: cols(3), Rows: rows(5)},
+			&workbookCreateStylePayload{CellStyles: []workbookCreateCellStyleOp{{Range: "A1:Z400"}}}, 400, 26},
+		{"styles inside the data don't shrink the grid",
+			tableSheetSpec{Columns: cols(3), Rows: rows(5)},
+			&workbookCreateStylePayload{CellStyles: []workbookCreateCellStyleOp{{Range: "A1:B2"}}}, 200, 20},
 	}
 	for _, tt := range cases {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-			gotRows, gotCols := sheetCreateDims(&tt.spec)
+			gotRows, gotCols := sheetCreateDims(&tt.spec, tt.styles)
 			if gotRows != tt.wantRows || gotCols != tt.wantCols {
 				t.Errorf("sheetCreateDims = (%d rows, %d cols), want (%d, %d)", gotRows, gotCols, tt.wantRows, tt.wantCols)
 			}

shortcuts/sheets/lark_sheet_workbook.go

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

shortcuts/sheets/lark_sheet_workbook_test.go

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

shortcuts/sheets/lark_sheet_write_cells.go

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

shortcuts/sheets/sheet_media_parent_type_test.go

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

shortcuts/sheets/sheets_perf_bench_test.go

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

shortcuts/sheets/shortcuts.go

@@ -35,6 +35,10 @@ func Shortcuts() []common.Shortcut {
 		if hasFlag(all[i].Flags, "spreadsheet-token") {
 			all[i].PostMount = withTokenAlias(all[i].PostMount)
 		}
+		// Sheets-scoped flag ergonomics (unknown-flag hints with the valid
+		// flags inlined, enum vocabulary normalization) ride the same
+		// PostMount composition, so no other domain's behavior shifts.
+		all[i].PostMount = withFlagErgonomics(all[i].PostMount)
 	}
 	return all
 }
@@ -70,6 +74,7 @@ func shortcutList() []common.Shortcut {
 	return []common.Shortcut{
 		// lark_sheet_workbook
 		WorkbookInfo,
+		RevisionGet,
 		SheetCreate,
 		SheetDelete,
 		SheetRename,
@@ -95,6 +100,9 @@ func shortcutList() []common.Shortcut {
 		DimUngroup,
 		DimMove,
 
+		// lark_sheet_changeset
+		ChangesetGet,
+
 		// lark_sheet_read_data
 		CellsGet,
 		CsvGet,
@@ -105,6 +113,9 @@ func shortcutList() []common.Shortcut {
 		CellsSearch,
 		CellsReplace,
 
+		// lark_sheet_formula_verify
+		FormulaVerify,
+
 		// lark_sheet_write_cells
 		CellsSet,
 		CellsSetStyle,
@@ -148,5 +159,10 @@ func shortcutList() []common.Shortcut {
 		CellsBatchClear,
 		DropdownUpdate,
 		DropdownDelete,
+
+		// lark_sheet_history
+		HistoryList,
+		HistoryRevert,
+		HistoryRevertStatus,
 	}
 }

skill-template/domains/drive.md

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

skills/lark-calendar/SKILL.md

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

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

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

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

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

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

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

skills/lark-doc/SKILL.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

skills/lark-drive/SKILL.md

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

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

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

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

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

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

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