docs: align formula verify refs with file names

main introduced the errs-no-bare-wrap forbidigo rule and errorlint
coverage that flag 27 issues in existing sheets code after the merge:

- Replace direct *errs.ValidationError type assertions with errors.As
  in sheetsInputStatError and validateSheetMediaUploadFile so wrapped
  errors still match (errorlint).
- Type the embedded flag-schemas.json parse failure as an InternalError
  with cause; it reaches the user directly via --print-schema.
- Annotate genuine intermediate errors (recursive schema validator,
  batch sub-op raw type checks, A1 range/position parsers) with
  //nolint:forbidigo; every caller wraps them into typed flag
  validation errors.

CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.64] - 2026-07-02
+
+### Features
+
+- **im**: Upgrade card send to Card 2.0 with full component reference (#1688)
+- **im**: Add `+chat-members-list` shortcut for member listing (#1398)
+- **okr**: Semi-plain text format with mention position preservation and `patch` shortcut (#1671)
+
+### Bug Fixes
+
+- **cli**: Point permission-apply link at official `/page/scope-apply` entry (#1722)
+- **cli**: Improve secure label error handling (#1707)
+- **cli**: Reduce public content token false positives
+- **cli**: Increase npm registry fetch timeout to 15s during update check (#1724)
+- **doc**: Align word statistics compound tokens (#1706)
+
+### Documentation
+
+- **approval**: Add detailed command-to-reference mapping for the approval skill (#1630)
+- **doc**: Support `reference_map` in docs (#1690)
+- **slides**: Refresh generation guidance — add constraints, drop template toolchain, and inline lint XML fixtures
+
 ## [v1.0.62] - 2026-07-01
 
 ### Features
@@ -1333,6 +1355,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[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
 [v1.0.60]: https://github.com/larksuite/cli/releases/tag/v1.0.60

internal/update/update.go

@@ -25,7 +25,7 @@ import (
 const (
 	registryURL  = "https://registry.npmjs.org/@larksuite/cli/latest"
 	cacheTTL     = 24 * time.Hour
-	fetchTimeout = 5 * time.Second
+	fetchTimeout = 15 * time.Second
 	stateFile    = "update-state.json"
 	maxBody      = 256 << 10 // 256 KB
 

package.json

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

shortcuts/doc/doc_media_upload.go

@@ -23,8 +23,8 @@ var DocMediaUpload = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "file", Desc: "local file path (files > 20MB use multipart upload automatically)", Required: true},
-		{Name: "parent-type", Desc: "parent type: docx_image | docx_file | whiteboard", Required: true},
-		{Name: "parent-node", Desc: "parent node ID (block_id for docx, board_token for whiteboard)", Required: true},
+		{Name: "parent-type", Desc: "parent type: docx_image | docx_file | whiteboard | mindnote_image", Required: true},
+		{Name: "parent-node", Desc: "parent node ID (block_id for docx, board_token for whiteboard, mindnote token for mindnote)", Required: true},
 		{Name: "doc-id", Desc: "document ID (for drive_route_token)"},
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {

shortcuts/sheets/backward/lark_sheets_float_images.go

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

shortcuts/sheets/batch_op_dispatch.go

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

shortcuts/sheets/data/flag-defs.json

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

@@ -241,6 +241,10 @@
                     "description": "字体颜色（十六进制，例如 \"#000000\"）",
                     "type": "string"
                   },
+                  "font_family": {
+                    "description": "字体名称/字族（例如 \"Arial\"、\"微软雅黑\"、\"宋体\"）",
+                    "type": "string"
+                  },
                   "font_size": {
                     "description": "字体大小（单位：px/像素，例如 10、12、14）",
                     "type": "number"
@@ -6498,6 +6502,9 @@
                   "font_color": {
                     "type": "string"
                   },
+                  "font_family": {
+                    "type": "string"
+                  },
                   "font_line": {
                     "enum": [
                       "none",
@@ -6867,6 +6874,9 @@
                   "font_color": {
                     "type": "string"
                   },
+                  "font_family": {
+                    "type": "string"
+                  },
                   "font_line": {
                     "enum": [
                       "none",

shortcuts/sheets/flag_defs_gen.go

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

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

shortcuts/sheets/flag_schema_validate.go

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

shortcuts/sheets/flag_view.go

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

shortcuts/sheets/helpers.go

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

shortcuts/sheets/lark_sheet_batch_update.go

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

shortcuts/sheets/lark_sheet_changeset.go

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

shortcuts/sheets/lark_sheet_changeset_test.go

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

shortcuts/sheets/lark_sheet_formula_verify.go

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

shortcuts/sheets/lark_sheet_formula_verify_test.go

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

shortcuts/sheets/lark_sheet_history_list.go

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

shortcuts/sheets/lark_sheet_history_revert.go

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

shortcuts/sheets/lark_sheet_history_test.go

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

shortcuts/sheets/lark_sheet_revision_get.go

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

shortcuts/sheets/lark_sheet_revision_get_test.go

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

shortcuts/sheets/lark_sheet_sheet_structure.go

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

shortcuts/sheets/lark_sheet_table_io.go

@@ -382,6 +382,32 @@ func (p *tablePayload) validate() error {
 			return common.ValidationErrorf("--sheets[%d] %q: mode %q is invalid (want \"overwrite\" or \"append\")", i, s.Name, s.Mode)
 		}
 	}
+	return p.checkCellBudget()
+}
+
+// maxTablePutCells bounds how many cells a single +table-put / +workbook-create
+// write may materialize. Unlike the fan-out stamp cap (maxStampMatrixCells),
+// these cells come from the caller's own --sheets/--values payload rather than a
+// range blow-up, so this is a generous OOM guardrail, not a usability limit:
+// buildSheetMatrix builds the whole rows×cols matrix of per-cell maps in memory
+// before slicing it into tablePutMaxCellsPerWrite-sized writes, so an unbounded
+// payload (2.6M cells ≈ 900MB heap, doubled again by json.Marshal) OOMs the
+// process before the first write leaves.
+const maxTablePutCells = 1_000_000
+
+// checkCellBudget rejects a payload whose total materialized cell count across
+// all sheets exceeds maxTablePutCells. Counted in int64 to stay overflow-safe on
+// pathological row/column counts.
+func (p *tablePayload) checkCellBudget() error {
+	var total int64
+	for i := range p.Sheets {
+		total += int64(len(p.Sheets[i].Rows)) * int64(len(p.Sheets[i].Columns))
+	}
+	if total > maxTablePutCells {
+		return common.ValidationErrorf(
+			"--sheets/--values cover %d cells total, over the %d-cell safety cap; split the write across smaller payloads",
+			total, maxTablePutCells)
+	}
 	return nil
 }
 

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")
 	}
@@ -836,13 +856,19 @@ func buildValuesPayload(runtime flagView, sheetStyles *workbookCreateSheetStyles
 		cols[i] = tableColumnSpec{Name: fmt.Sprintf("col%d", i+1)} // type-less
 	}
 	noHeader := false
-	return &tablePayload{Sheets: []tableSheetSpec{{
+	payload := &tablePayload{Sheets: []tableSheetSpec{{
 		Name:    valuesSheetName,
 		Mode:    "overwrite",
 		Header:  &noHeader,
 		Columns: cols,
 		Rows:    rows,
-	}}}, nil
+	}}}
+	// --values bypasses tablePayload.validate(), so enforce the cell budget here
+	// too — otherwise a giant --values array materializes unbounded.
+	if err := payload.checkCellBudget(); err != nil {
+		return nil, err
+	}
+	return payload, nil
 }
 
 // parseValuesRows decodes --values (JSON 2D array, with @file/stdin already
@@ -1246,7 +1272,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

shortcuts/sheets/lark_sheet_write_cells.go

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

shortcuts/sheets/sheet_media_parent_type_test.go

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

shortcuts/sheets/sheets_perf_bench_test.go

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

shortcuts/sheets/shortcuts.go

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

skills/lark-doc/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: lark-doc
 version: 2.0.0
-description: "飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。"
+description: "飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。当用户明确要操作飞书思维笔记时，也使用本 skill。"
 metadata:
   requires:
     bins: ["lark-cli"]
-  cliHelp: "lark-cli docs --help; lark-cli docs +create --help; lark-cli docs +fetch --help; lark-cli docs +update --help; lark-cli docs +resource-download --help; lark-cli docs +resource-update --help; lark-cli docs +resource-delete --help"
+  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
@@ -45,6 +45,7 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>
 - 用户明确说"下载/更新/删除文档封面图" → 用 `lark-cli docs +resource-download/+resource-update/+resource-delete --type cover`
 - `resource-*` 目前仅支持 Docx 封面资源；其他图片、附件或素材请走 `+media-*`
 - 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）
+- 用户明确要操作思维笔记时；已有**思维笔记**，走 [思维笔记链路](references/lark-doc-mindnote.md)；新建**思维笔记**，走 [lark-doc-whiteboard](references/lark-doc-whiteboard.md)
 - 拿到 spreadsheet URL/token 后 → 切到 `lark-sheets` 做对象内部操作
 - 用户需要统计文档的**总字数 / 总字符数**（word count / character count）时，先读取 [`lark-doc-word-stat.md`](references/lark-doc-word-stat.md)，并按其中流程调用 [`scripts/doc_word_stat.py`](scripts/doc_word_stat.py)；统计口径以该脚本为准，不要改用其他方式自行计算。
 - 用户说"给文档加评论""查看评论""回复评论""给评论加/删除表情 reaction" → 切到 `lark-drive` 处理

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

@@ -0,0 +1,113 @@
+# 飞书思维笔记（Mindnote）
+
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 和 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和路由规则。
+
+当用户要操作思维笔记时，入口属于 `lark-doc`，但实际执行命令使用 `lark-cli mindnotes nodes list/create`，不是 `docs +...`。
+
+> [!IMPORTANT]
+> 当前这条链路只支持**读取已有思维笔记**，以及在**已有思维笔记**里读取节点、创建子节点。
+> `mindnotes nodes create` 是新增/更新节点命令，**不是**新建一个新的思维笔记。
+> 如果用户要**新建思维笔记**，不要走本链路，改走 [lark-doc-whiteboard](lark-doc-whiteboard.md)。
+
+## 命令
+
+```bash
+# 先看命令帮助
+lark-cli mindnotes nodes list --help
+lark-cli mindnotes nodes create --help
+
+# 读取节点列表
+lark-cli mindnotes nodes list --mindnote-id "<mindnote_token>"
+
+# 创建子节点
+lark-cli mindnotes nodes create \
+  --mindnote-id "<mindnote_token>" \
+  --data '{"client_token":"<client_token>","nodes":[{"parent_id":"node_parent123","texts":[{"element_type":"text","text":{"content":"子节点内容"}}],"highlight":"yellow","finish":false}]}'
+
+# 更新已有节点
+lark-cli mindnotes nodes create \
+  --mindnote-id "<mindnote_token>" \
+  --data '{"client_token":"<client_token>","nodes":[{"node_id":"node_existing123","texts":[{"element_type":"text","text":{"content":"更新后的节点内容"}}],"highlight":"blue","finish":true}]}'
+```
+
+## 参数
+
+### `mindnotes nodes list`
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--mindnote-id` | 是 | 思维笔记 token / 唯一标识 |
+
+返回重点：`data.nodes` 中常见字段有 `node_id`、`parent_id`、`texts`、`notes`、`images`、`finish`、`highlight`。
+
+### `mindnotes nodes create`
+
+命令参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--mindnote-id` | 是 | 思维笔记 token / 唯一标识 |
+| `--data` | 是 | JSON 请求体 |
+
+请求体字段：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `client_token` | 否 | 幂等 token，建议写操作传入；推荐使用时间戳或 UUID |
+| `nodes` | 是 | 待创建或更新的节点数组 |
+| `nodes[].node_id` | 否 | 节点 ID；传入已有 `node_id` 时表示更新对应节点 |
+| `nodes[].parent_id` | 否 | 父节点 ID；创建子节点时传入 |
+| `nodes[].texts` | 否 | 节点正文富文本数组 |
+| `nodes[].notes` | 否 | 节点备注富文本数组 |
+| `nodes[].images` | 否 | 节点图片列表 |
+| `nodes[].highlight` | 否 | `red` / `yellow` / `pink` / `blue` / `cyan` / `olive` / `grey` |
+| `nodes[].finish` | 否 | 节点完成状态 |
+
+富文本字段 `texts` / `notes` 是元素数组。最常见的是：
+
+```json
+[{"element_type":"text","text":{"content":"节点内容"}}]
+```
+
+### 节点图片（`nodes[].images`）
+
+`nodes[].images` 接收的是**图片 token**，不是本地文件路径，也不是 URL。
+
+```bash
+# 先上传图片，拿到 token
+lark-cli docs +media-upload --file ./image.png --parent-type mindnote_image --parent-node <mindnote_token>
+
+# 再把 token 写进节点
+lark-cli mindnotes nodes create \
+  --mindnote-id "<mindnote_token>" \
+  --data '{"client_token":"<client_token>","nodes":[{"node_id":"node_existing123","images":[{"token":"canonical_token"}]}]}'
+```
+
+参数说明：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file` | 是 | 本地图片路径 |
+| `--parent-type` | 是 | 上传目标类型；图片使用 `mindnote_image` |
+| `--parent-node` | 是 | 传 Mindnote 的 token |
+| `nodes[].images[].token` | 是 | 上传后返回的图片 token |
+
+## 推荐工作流
+
+1. 先判断用户目标是不是“新建一个思维笔记”。
+2. 如果是新建思维笔记，切到 [lark-doc-whiteboard](lark-doc-whiteboard.md)。
+3. 如果是操作已有思维笔记，先通过 token 类别判断。
+4. 确认是 **Mindnote** 后再拿到 `mindnote_id`。
+5. 先执行 `mindnotes nodes list`，确认目标 `parent_id`。
+6. 新增子节点时，在 `nodes[]` 里传 `parent_id`；更新已有节点时，在 `nodes[]` 里传已有 `node_id`。
+7. 再执行 `mindnotes nodes create`。
+8. 写操作优先带 `client_token`，推荐使用时间戳或 UUID，避免重试时重复创建或重复更新。
+
+> [!CAUTION]
+> `mindnotes nodes create` 是写操作。创建时确认插入位置，更新时确认 `node_id` 指向的就是目标节点。
+
+## 参考
+
+- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容
+- [lark-doc-whiteboard](lark-doc-whiteboard.md) — 新建思维笔记走画板链路
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-sheets/SKILL.md

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

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

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

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

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

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

@@ -122,7 +122,7 @@ _公共四件套 · 系统：`--dry-run`_
 
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `--properties` | string + File + Stdin（复合 JSON） | required | 图表完整配置 JSON。顶层字段为 `position` / `offset` / `size` / `snapshot`（无顶层 `data`，也无再嵌一层 `properties`）；图表数据配置在 `snapshot.data` 下（含 `refs` / `headerMode` / `dim1` / `dim2`）。结构嵌套深，完整结构跑 `--print-schema --flag-name properties` |
+| `--properties` | string + File + Stdin（复合 JSON） | required | 图表完整配置 JSON。顶层字段为 `position` / `offset` / `size` / `snapshot`（无顶层 `data`，也无再嵌一层 `properties`）；图表数据配置在 `snapshot.data` 下（含 `refs` / `headerMode` / `dim1` / `dim2`）；必须至少含 `snapshot.data.dim1.serie.index` 或 `dim2.series[].index` 之一，否则 server 拒。结构嵌套深，完整结构跑 `--print-schema --flag-name properties` |
 
 ### `+chart-update`
 

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,93 @@
+# Lark Sheet History
+
+## 概念回顾
+
+每张飞书电子表格保留一串历史版本（`minor_histories`）。每个版本由 `history_version_id` 标识，并附带创建时间（`create_time`）、动作（`action`）与块修订信息（`all_block_revision`）。历史是**工作簿级**的（针对整张电子表格，不针对单个子表）。
+
+回滚（revert）把电子表格的当前内容覆盖回某个历史版本——这是一个**写入 / 不可逆**操作，且为**异步**：发起后立即返回受理标识，真正的回滚在后台进行，需通过状态查询轮询最终结果（进行中 / 成功 / 失败）。
+
+`+history-list` 读取版本列表以挑选目标；`+history-revert` 发起回滚；`+history-revert-status` 轮询回滚结果。若只是想拿**当前文档版本号（revision）**当作 recover / undo / `+changeset-get` 的起点锚点，直接用 `+revision-get` 更轻量。
+
+## 使用场景
+
+读取历史版本、发起回滚、查询回滚状态。本 reference 覆盖 3 个 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看历史版本列表 | `+history-list` | 返回 `minor_histories`，每条含 `history_version_id` / `create_time` / `action` / `all_block_revision` 四个字段；支持向前分页（可选 `--end-version`） |
+| 回滚到指定历史版本 | `+history-revert` | 传入 `--history-version-id`；异步受理，返回可查询标识 |
+| 查询回滚状态 | `+history-revert-status` | 传入 `--transaction-id`（取自 `+history-revert` 的异步受理标识）；轮询某次回滚的进行中 / 成功 / 失败状态 |
+
+典型工作流：`+history-list` 拿到目标版本的 `history_version_id`（必要时翻页拉取更早历史）→ `+history-revert` 发起回滚并取回 `transaction_id` → `+history-revert-status --transaction-id <transaction_id>` 轮询直到成功或失败。
+
+**注意事项（必须了解）**：
+- **回滚是写入 / 不可逆操作**：会用历史版本内容覆盖当前表格，发起前请确认目标 `history_version_id` 正确。
+- **回滚是异步的**：`+history-revert` 返回的是 `transaction_id`（受理标识），不代表回滚已完成；必须用 `+history-revert-status --transaction-id <transaction_id>` 确认最终结果。
+- **`history_version_id` 与 `transaction_id` 不是同一个**：`history_version_id` 用于 `+history-revert`（取自 `+history-list`）；`transaction_id` 用于 `+history-revert-status`（取自 `+history-revert` 的输出）。
+- **历史是工作簿级**：定位只需 `--url` / `--spreadsheet-token`（XOR），不需要子表选择器。
+- **`+history-list` 倒序分页**：首次查省略 `--end-version`，返回最新一页；若响应里附带 `next_end_version` 与 `has_more=true`，把 `next_end_version` 作为下一次的 `--end-version` 即可继续向更早翻页；当响应**不包含**这两个字段时表示已到最早一页，不必再翻。
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+history-list` | read | 历史版本 |
+| `+history-revert` | write | 历史版本 |
+| `+history-revert-status` | read | 历史版本 |
+
+## Flags
+
+### `+history-list`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--end-version` | int | optional | 分页查询的最大版本（倒序）；首次查询省略，下一页传上一页返回的 next_end_version。 |
+
+### `+history-revert`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--history-version-id` | string | required | 要回滚到的历史版本（取自 +history-list） |
+
+### `+history-revert-status`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--transaction-id` | string | required | 异步回滚的受理标识（取自 +history-revert） |
+
+## Examples
+
+公共定位：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token`（XOR，二选一）。`+history-revert` 用 `--history-version-id`（取自 `+history-list`）；`+history-revert-status` 用 `--transaction-id`（取自 `+history-revert` 的异步受理标识）。
+
+### `+history-list`
+
+```bash
+# 列出某张电子表格的最新一页历史版本
+lark-cli sheets +history-list --url "https://sample.feishu.cn/sheets/SHTxxxxxx"
+
+# 用原始 spreadsheet token 定位
+lark-cli sheets +history-list --spreadsheet-token "SHTxxxxxx"
+
+# 翻到下一页：把上次响应里的 next_end_version 作为 --end-version 传入
+lark-cli sheets +history-list --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --end-version 12345
+```
+
+### `+history-revert`
+
+```bash
+# 回滚到指定历史版本（异步受理）
+lark-cli sheets +history-revert --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --history-version-id "<id-from-history-list>"
+```
+
+### `+history-revert-status`
+
+```bash
+# 查询某次回滚的当前状态（进行中 / 成功 / 失败）
+lark-cli sheets +history-revert-status --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --transaction-id "<transaction-id-from-history-revert>"
+```

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

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

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

@@ -22,6 +22,7 @@
 
 注意：
 
+- **`--range` 两种语法别混**：`+cells-clear` / `+cells-{merge|unmerge}` / `+range-*` 用单元格 A1 矩形（如 `A2:A10`）；`+rows-resize` / `+cols-resize` 用纯行 / 列区间（行 `2:10`、列 `A:C`），不要给 resize 传 `A2:A10`
 - 用户说"这行 / 整行 / 首行"时，优先使用整行范围如 `1:1`；"这列 / 整列"时使用 `J:J`。不要截断为局部矩形
 - 合并后只保留左上角单元格的内容，其余清除。写入合并区域用 `+cells-set` 对左上角单元格操作
 - 调整行高列宽时，先读取相邻行列尺寸再决定像素值，不要随意猜测
@@ -35,7 +36,7 @@
 2. **判定阈值**：当前列宽（用 `+sheet-info --include row_heights,col_widths` 拿）≥ 最长字符数 × 字体宽度系数 + buffer 才算适配。默认列宽 11 通常只够 11 个半角字符或 5-6 个汉字，写长文本前必扩宽。
 3. **修复二选一**：
    - **扩列宽**：用 `+rows-resize / +cols-resize` 把目标列宽设为 `max(表头字符数, 内容采样最长字符数) × 8 + 16` 像素（经验值）
-   - **自动换行**：在 `+cells-set` 时给单元格设置 `cell_styles.word_wrap="auto-wrap"`（可选值：`overflow` / `auto-wrap` / `word-clip`），并用 `+rows-resize / +cols-resize` 调高对应行的行高
+   - **自动换行**：在 `+cells-set` 时给单元格设置 `cell_styles.word_wrap="auto-wrap"`（可选值：`overflow` / `auto-wrap` / `word-clip`；`cell_styles` 字段见 `lark-sheets-write-cells`），并用 `+rows-resize / +cols-resize` 调高对应行的行高
 4. **新增列默认列宽规则**：新增列宽度 ≥ `max(表头字符数, 内容采样最长字符数) × 8 + 16` 像素，**禁止**用默认 11 直接交付。
 
 **典型反例**：默认列宽 11 但内容含 12+ 字符的中文 / 含单位的数值（如 `109.10μmol/L`）/ 长数字未设 `number_format` 显示为科学计数法 —— 用户在结果表里看不到完整原值。

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

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

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

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

skills/lark-sheets/references/lark-sheets-visual-standards.md

@@ -1,7 +1,7 @@
 # 飞书表格样式与配色规范
 
 > **本文定位**：飞书表格"正确视觉输出"的取值标准与美化决策流——配色、表头、对齐、数值格式、斑马纹、列宽行高、图表展示，以及新增 / 继承 / 美化已有区域三类场景的做法。
-> **边界**：本文只讲"样式长什么样、怎么决策"；**怎么调用工具写入样式**（`cell_styles` / `border_styles` 字段、合并、resize 等参数）见 `lark-sheets-write-cells` / `lark-sheets-range-operations` / `lark-sheets-batch-update`。**条件格式**（高亮 / 标红 / 数据条 / 色阶）见 `lark-sheets-conditional-format`。本文不含 shortcut，铁律见 `lark-sheets-core-operations`。
+> **边界**：本文只讲"样式长什么样、怎么决策"；**怎么调用工具写入样式**（`cell_styles` / `border_styles` 字段、合并、resize 等参数）见 `lark-sheets-write-cells` / `lark-sheets-range-operations` / `lark-sheets-batch-update`。**条件格式**（高亮 / 标红 / 数据条 / 色阶）见 `lark-sheets-conditional-format`。本文不含 shortcut，通用编辑准则见主 SKILL.md「飞书表格编辑准则」。
 
 ## 最高优先级原则
 
@@ -64,7 +64,7 @@
   - 若追加位置紧邻汇总行、说明区或空白分隔区，先判断真实数据区域边界再操作，避免破坏原有结构。
   - **Zebra Stripes 维护**：插入或删除行后若影响后续行奇偶性，须从受影响行往后重建条纹（先清理再重设）。少量增删用局部重建，大量变动用全局清理+统一重建。
   - 具体采样与复制流程见下方「场景二：从已有区域继承美化」。
-- **列宽调整**（飞书 `+rows-resize / +cols-resize` 按 pixel 传值）：
+- **列宽 / 行高调整**（飞书 `+rows-resize / +cols-resize` 按 pixel 传值）：
   - 禁止硬编码固定列宽，须根据该列实际内容长度估算像素。
   - 经验估算：中文每字约 15-18px，英文/数字每字约 7-9px，外加 10-16px padding。
   - 上下限建议 80~400px；超上限启用自动换行（`word_wrap: auto-wrap`）+ 调整行高，而非无限加宽。
@@ -82,7 +82,7 @@
 - 包含必要元素：标题、图例、数据标签、坐标轴标题。
 - 调整至合适大小，避免数据和标签过多堆叠。
 - **图表放置防重叠**：新增图表前须计算放置区域，避免与已有图表重叠。具体步骤：
-  1. 调用 `+chart-list` 获取当前工作表所有已有图表的 `position`（锚点单元格：`row` 行索引、`col` 列索引如 "A"/"B"）、`offset`（锚点内偏移：`row_offset`、`col_offset`，单位像素）以及 `size`（`width`、`height`，单位像素）。
+  1. 调用 `+chart-list` 获取当前工作表所有已有图表的 `position`（锚点单元格：`col` 是列字母如 "A"/"B"、`row` 是 1-based 行号；以 `+chart-list` 实际返回字段为准）、`offset`（锚点内偏移：`row_offset`、`col_offset`，单位像素）以及 `size`（`width`、`height`，单位像素）。
   2. 获取工作表的行高和列宽信息（像素）。
   3. 根据每个图表的锚点 `position.row`/`position.col` + 偏移 `offset.row_offset`/`offset.col_offset` + 尺寸 `size.width`/`size.height`，结合行高列宽，计算出每个已有图表覆盖的像素矩形区域 `(x_min, y_min, x_max, y_max)`。
   4. 为新图表选定大小后，候选放置位置应避开所有已有矩形区域；若存在重叠则向下或向右偏移，直至找到无冲突位置。

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

@@ -15,7 +15,12 @@
 | 操作需求 | 使用工具 | 说明 |
 |---------|---------|------|
 | 查看工作簿结构 | `+workbook-info` | 获取子表列表、名称、行列数、冻结位置等元数据 |
+| 获取当前 revision | `+revision-get` | 获取当前文档 revision（版本号），可作为 recover / undo / changeset 复核的版本锚点 |
+| 新建工作簿（可预填数据） | `+workbook-create` | 从内存数据建一张新表（`--values` / `--sheets` typed） |
+| 导入本地文件为新表 | `+workbook-import` | 把本地 `.xlsx` / `.xls` / `.csv` 导入为新的飞书电子表格 |
+| 导出工作簿到本地 | `+workbook-export` | 导出为本地 `.xlsx`（整簿）或单子表 `.csv` |
 | 变更工作簿结构 | `+sheet-{create|delete|rename|move|copy|hide|unhide|set-tab-color}` | 新建/删除/移动/重命名/复制/隐藏子表、修改标签颜色 |
+| 切换子表网格线显隐 | `+sheet-show-gridline` / `+sheet-hide-gridline` | 显示 / 隐藏单个子表的网格线 |
 
 注意：
 
@@ -33,6 +38,7 @@
 | Shortcut | Risk | 分组 |
 | --- | --- | --- |
 | `+workbook-info` | read | 工作簿 |
+| `+revision-get` | read | 工作簿 |
 | `+sheet-create` | write | 工作簿 |
 | `+sheet-delete` | high-risk-write | 工作簿 |
 | `+sheet-rename` | write | 工作簿 |
@@ -55,6 +61,12 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
 
 _仅含公共 / 系统 flag。_
 
+### `+revision-get`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+_仅含公共 / 系统 flag。_
+
 ### `+sheet-create`
 
 _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
@@ -65,6 +77,7 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
 | `--index` | int | optional | 插入位置（0-based）；省略时附加到末尾 |
 | `--row-count` | int | optional | 初始行数（默认 200，上限 50000） |
 | `--col-count` | int | optional | 初始列数（默认 20，上限 200） |
+| `--type` | string | optional | 新子表类型：sheet（电子表格）\| bitable（多维表格）；默认 sheet。bitable 只建空表，内容编辑改用 lark-base 命令 |
 
 ### `+sheet-delete`
 
@@ -87,7 +100,7 @@ _公共四件套 · 系统：`--dry-run`_
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `--index` | int | required | 目标位置（0-based） |
-| `--source-index` | int | optional | 源位置（0-based）；可选，未传时由 CLI runtime 根据 `--sheet-id` / `--sheet-name` 当前在工作簿中的 index 自动派生 |
+| `--source-index` | int | optional | 源位置（0-based）；standalone 调用时可选，未传时由 CLI runtime 根据 `--sheet-id` / `--sheet-name` 当前在工作簿中的 index 自动派生。但在 `+batch-update` 内不可省（须显式传）——batch 中途无法发起结构查询自动派生 |
 
 ### `+sheet-copy`
 
@@ -138,7 +151,7 @@ _系统：`--dry-run`_
 | --- | --- | --- | --- |
 | `--title` | string | required | 新 spreadsheet 标题 |
 | `--folder-token` | string | optional | 目标文件夹 token；省略时放在云空间根目录 |
-| `--values` | string + File + Stdin（简单 JSON） | optional | untyped 初始数据，一个 JSON 二维数组（表头并入第一行）：`[["列A","列B"],["alice",95]]`；值原样写入、类型由飞书自动识别，走与 --sheets 相同的分批 `+cells-set`；配 --styles 控制格式/颜色/合并/行列尺寸 |
+| `--values` | string + File + Stdin（简单 JSON） | optional | untyped 初始数据，一个 JSON 二维数组（表头并入第一行）：`[["列A","列B"],["alice",95]]`；值原样写入、类型由飞书自动识别（日期 / 数字会落成文本，需类型保真改用 --sheets），走与 --sheets 相同的分批 `+cells-set`；配 --styles 控制格式/颜色/合并/行列尺寸 |
 | `--sheets` | string + File + Stdin（复合 JSON） | optional | 建表后写入的 typed 表格协议 JSON（同 +table-put）：顶层 `{"sheets":[...]}`，每个数组项是一张子表 `{name, start_cell?, mode?, header?, allow_overwrite?, columns:["colA","colB",...], data:[[...]], dtypes?:{colA:pandasDtype, ...}, formats?:{colA:numberFormat, ...}}` —— `name` 与外层 `sheets` 数组都不可省。Agents 用 `scripts/sheets_df.py` 的 `df_to_sheet(df, name)` 把 DataFrame 转成一项再包 `{"sheets":[...]}`。与 --values 互斥；新表默认子表复用为第一个子表，日期/数字类型保真。 |
 | `--styles` | string + File + Stdin（复合 JSON） | optional | 建表时同时写入的视觉处理操作 JSON：顶层 `{styles:[...]}`，每项对应一个目标子表、含 `name`，并至少给 `cell_styles` / `row_sizes` / `col_sizes` / `cell_merges` 之一。`cell_styles` 用 A1 单元格 range + 扁平样式字段（字段同 +cells-set-style，含 number_format / 颜色 / 对齐 / border_styles）；row/col sizes 用行/列范围 + type/size；merges 用单元格 range + 可选 merge_type。与 --sheets 搭配时 styles 数组长度/顺序/name 必须与 --sheets.sheets 对应；与 --values 搭配时只给一个 styles 项（其 name 忽略）。完整 cell_styles 字段结构跑 `+workbook-create --print-schema --flag-name styles`。 |
 
@@ -184,7 +197,7 @@ _一个或多个子表的 typed 数据，每个数组元素写入一张子表；
 
 **数组项**（类型 object）：
 - `cell_merges` (array<object>?) — 单元格合并操作数组；range 使用 A1 单元格范围，merge_type 默认 all each: { merge_type?: enum, range: string }
-- `cell_styles` (array<object>?) — 单元格样式操作数组；每项用 A1 单元格 range 指定范围，字段名与 +cells-set-style 对齐 each: { background_color?: string, border_styles?: object, font_color?: string, font_line?: enum, font_size?: number, …共 12 项 }
+- `cell_styles` (array<object>?) — 单元格样式操作数组；每项用 A1 单元格 range 指定范围，字段名与 +cells-set-style 对齐 each: { background_color?: string, border_styles?: object, font_color?: string, font_family?: string, font_line?: enum, …共 13 项 }
 - `col_sizes` (array<object>?) — 列宽操作数组；range 使用列范围如 A:C，type 为 pixel/standard，pixel 需要 size each: { range: string, size?: number, type: enum }
 - `name` (string) — 子表名
 - `row_sizes` (array<object>?) — 行高操作数组；range 使用行范围如 1:3，type 为 pixel/standard/auto，pixel 需要 size each: { range: string, size?: number, type: enum }
@@ -195,7 +208,17 @@ _一个或多个子表的 typed 数据，每个数组元素写入一张子表；
 
 ### `+workbook-info`
 
-输出契约：返回 `sheets[]`，每个含 `sheet_id` / `title`（工作表显示名；旧 payload 用 `sheet_name`，读取时优先取 `title`、缺失再回退 `sheet_name`）/ `row_count` / `column_count` / `index` / `is_hidden`，以及计数字段 `merged_cells_count` / `chart_count` / `pivot_table_count` / `float_image_count`（无 `frozen_*` 字段，冻结信息请用 `+sheet-info` 读取）。是操作飞书表格的第一步——任何后续 sheet 级动作都需要先拿这里的 sheet_id。
+输出契约：返回 `sheets[]`，每个含 `sheet_id` / `title`（工作表显示名；旧 payload 用 `sheet_name`，读取时优先取 `title`、缺失再回退 `sheet_name`）/ `index` / `resource_type` / `row_count` / `column_count` / `is_hidden`，以及计数字段 `merged_cells_count` / `chart_count` / `pivot_table_count` / `float_image_count`（无 `frozen_*` 字段，冻结信息请用 `+sheet-info` 读取）。是操作飞书表格的第一步——任何后续 sheet 级动作都需要先拿这里的 sheet_id。
+
+> **子表类型 `resource_type`**：`sheet`（普通网格子表）/ `bitable`（内嵌的多维表格子表）/ `#UNSUPPORTED_TYPE`（其它暂不支持的嵌入子表）。
+> - 网格类操作（读写单元格 / 区域 / 样式 / CSV / 筛选 / 透视 / 图表等）**仅适用于 `sheet`**。对 `bitable` / `#UNSUPPORTED_TYPE` 子表执行网格操作会被直接拒绝并返回明确报错，不再静默出错。
+> - 要操作 `bitable` 子表里的数据：该子表条目会附带 `bitable_app_token` + `bitable_table_id` 两个字段，直接用多维表格命令操作，例如 `lark-cli base +record-list --base-token <bitable_app_token> --table-id <bitable_table_id>`（记录增删改查、字段、视图等整套 `lark-cli base` 命令均可用）。不要走 sheets 网格命令。
+> - `bitable` / `#UNSUPPORTED_TYPE` 子表条目**只含** `sheet_id` / `sheet_name` / `index` / `resource_type`（bitable 另加上述两个 token）以及 `is_hidden` / `tab_color`；**不输出** `row_count` / `column_count` / `merged_cells_count` / `chart_count` / `pivot_table_count` / `float_image_count` / `frozen_*` 等网格指标（对非网格子表无意义）。
+> - tab 管理类操作（`+sheet-rename` / `+sheet-move` / `+sheet-delete` / `+sheet-hide` 等）对任意 `resource_type` 的子表都合法，不受此限制。
+
+### `+revision-get`
+
+输出契约：返回单个 `revision` 字段，即当前文档版本号。它是 recover / undo / `+changeset-get` 的版本锚点：如果刚执行过一次读写操作，也可以直接复用那次响应里的 `revision`；当只想单独取当前版本号、且不需要其它结构信息时，用 `+revision-get` 最直接。
 
 ### `+workbook-create`
 
@@ -341,8 +364,17 @@ lark-cli sheets +sheet-create --url "https://example.feishu.cn/sheets/shtXXX" \
   --title "汇总" --index 0
 ```
 
+新建一张**多维表格（bitable）子表**：加 `--type bitable`（默认 `sheet`，即普通电子表格子表）。
+
+```bash
+lark-cli sheets +sheet-create --url "https://example.feishu.cn/sheets/shtXXX" \
+  --title "任务表" --type bitable
+```
+
 > 💡 `+sheet-create` 只建一张**空子表**。要在已有工作簿里建子表并一步写入 typed 数据和/或样式，用 `+table-put`（payload 里命名的子表缺则自动新建）配合它的 `--sheets` / `--styles`，省掉先建表再 `+cells-set` / `+cells-set-style` 的二次往返。
 
+> 💡 `--type bitable` 只建一张**空的多维表格子表**（默认表 + 网格视图 + 默认字段）。它的内容编辑（字段、记录、视图）走 `lark-cli base`：先用 `+workbook-info` 拿到该子表的 `bitable_app_token` + `bitable_table_id`，再用 `lark-cli base +record-list` / `+record-create` 等操作；sheets 侧的网格类命令（`+cells-get` / `+cells-set` 等）对 bitable 子表会被拒。
+
 ### `+sheet-delete`
 
 > ⚠️ 工作表删除不可逆；先 `--dry-run` 看输出 sheet_id + title 确认是要删的那张。

skills/lark-sheets/references/lark-sheets-write-cells.md

@@ -5,7 +5,7 @@
 1. **明确写入边界**：写入前必须能回答"目标 range 的起止行列号是多少？是否落在用户授权范围内？"。除用户明示要修改的区域外，禁止扩张到原数据列以外或新建 Sheet。
 2. **完整性断言**：批量写入前先把"预期写入条数"硬编码到代码里（如要填 106 条翻译 → `expected = 106`），写完后回读断言 `actual == expected`。少于预期就继续写，禁止交付半成品。
 3. **回读抽样校验**：写完关键值 / 公式后，用 `+csv-get` 或 `+cells-get` 重新读取写入区域，至少抽样 3-5 个代表性单元格（首 / 中 / 末），核对值与预期一致（与本地脚本计算的预期值对照）。公式特定的"先验证模板再 --copy-to-range / 修完再读回"细则见下方相关章节。
-4. **护原表 · 派生产物落点（写排名 / 标记 / 汇总 / 改写列时易丢数据）**：派生结果一律写到**真实末列 +1 的全新空列**或新建子表，**禁止复用任何已有原数据列**——哪怕该列看起来"空"，也要先 `+csv-get` 回读确认整列无原始数据再写。三条铁律：① 不把新公式 / 新值写进原数据列（典型反例：把新算的排名公式写进了原本存放另一份原始数据的列，整列原始数据被覆盖丢失）；② 不改写、不合并原表头字段名（典型反例：把几个独立表头字段合并成一列，原字段名丢失）；③ 慎用 `--allow-overwrite`：它一旦让写入区盖到相邻原始列 / 行就是不可逆数据丢失，加它之前必须用 `+sheet-info` / `+csv-get` 核清目标 range 不含任何原始数据。
+4. **护原表 · 派生产物落点（写排名 / 标记 / 汇总 / 改写列时易丢数据）**：派生结果一律写到**真实末列 +1 的全新空列**或新建子表，**禁止复用任何已有原数据列**——哪怕该列看起来"空"，也要先 `+csv-get` 回读确认整列无原始数据再写。三条准则：① 不把新公式 / 新值写进原数据列（典型反例：把新算的排名公式写进了原本存放另一份原始数据的列，整列原始数据被覆盖丢失）；② 不改写、不合并原表头字段名（典型反例：把几个独立表头字段合并成一列，原字段名丢失）；③ 慎用 `--allow-overwrite`：它一旦让写入区盖到相邻原始列 / 行就是不可逆数据丢失，加它之前必须用 `+sheet-info` / `+csv-get` 核清目标 range 不含任何原始数据。
 
 ## 新增列 / 新增行的样式继承（防止视觉风格不一致）
 
@@ -13,7 +13,7 @@
 
 **完整继承清单**（写新列 / 新行时 cells 数组必须同时携带）：
 
-1. `cell_styles.font_size` / `cell_styles.font_weight` / `cell_styles.font_color` / `cell_styles.font_style`（字号 / 粗细 / 颜色 / 斜体等）
+1. `cell_styles.font_family` / `cell_styles.font_size` / `cell_styles.font_weight` / `cell_styles.font_color` / `cell_styles.font_style`（字体名称 / 字号 / 粗细 / 颜色 / 斜体等）
 2. `cell_styles.horizontal_alignment` / `cell_styles.vertical_alignment`（H-Align / V-Align）—— 漏继承会导致新列对齐与原列不一致（常见）
 3. `cell_styles.number_format`（小数位 / 千分位 / 百分比 / 日期格式）—— 漏继承会导致同列数值格式混乱
 4. `cell_styles.background_color`（背景色）
@@ -43,6 +43,8 @@
 
 **典型反例**：长数字列（如审批单号、流水号）未设 `number_format`，飞书显示为 `1.23E+15`，用户复制出来已经丢失精度。
 
+> **数字还是文本，按"数据本质是量值还是标识符"二选一 —— 不看当下要不要计算**：金额 / 百分比 / 比率 / 计数 / 度量这类**本质是量值**的数据，一律以**数字类型**写入（百分比存小数 `0.54` 配 `number_format:"0%"`），**不要**设 `@` 文本格式。**这与"用户当下是否要排序 / 求和"无关**——数据类型由数据本质决定、不由当下用途决定：表格数据几乎总会被后续排序 / 图表 / 二次计算复用，`"54%"` 文本与数值列混排本就破坏一致性，且数字 + `number_format` 显示效果与文本**完全相同**，没有任何理由选文本。**最常见的误判就是"这只是 leaderboard / 报表 / 看板展示，又不用算，写成 `54%` 字符串就行"——这是错的，展示用途不改变"百分比是数值"的事实。**（`+table-put` 用 `dtypes` 声明 `int64` / `float64`；版式 `+table-put` 装不下时用 `+cells-set` 传数字 + `number_format`；都别在本地拼成带 `$` / `%` 的字符串走 `+csv-put`。）反过来，编号 `001`、规格 `3-1`、身份证 / 电话 / 单据号等**本质是标识符 / 标签**、要原样保留不被飞书自动解释的内容（否则 `001`→`1`、`3-1`→日期、长号→科学计数），才以**字符串类型**写入（`dtypes` 设 `object`）并把 `number_format` 设为 `"@"`（文本格式），字面保真。
+
 ## 使用场景
 
 写入。向飞书表格的单元格区域写入值、公式、样式、批注、图片或下拉，也可批量写入 CSV / DataFrame。本 reference 覆盖 6 个 shortcut，按数据来源 + 内容形态选：
@@ -50,23 +52,24 @@
 | 场景 | 用这个 shortcut | 原因 |
 |------|----------------|------|
 | 模型手里已经有 CSV 文本（小规模手动构造、从 `+csv-get` 取到后简单加工） | `+csv-put` | 直接传 CSV 文本 + `--start-cell`，不用自己拼二维 cells 数组；必要时自动扩容行列 |
-| 列里有数值语义的数据（数字 / 金额 / 百分比 / 日期 / 计数）→ 飞书，要类型保真（来源不限：DataFrame、Counter、dict、list 都算） | `+table-put` | typed 协议（外层 `{"sheets":[{"name":"…","columns":[...],"data":[[...]],"dtypes":{...},"formats":{...}}]}`，**只有这四件套字段**）：`dtypes` 用 pandas dtype 串声明列类型（`int64` / `float64` / `datetime64[ns]` / `bool` / `object`），`formats` 给每列展示格式（千分位 / 百分比 / 日期）。**date 落真日期、金额 / 百分比 / 计数等数值列保精度且带 `number_format`（可排序 / 求和 / 入图表）**、string 保前导零，多 sheet 一次写。**只要列有数值语义就走这里**，不要在本地把数字拼成带 `$` / `%` 的字符串再走 `+csv-put` |
+| 列里有数值语义的数据（数字 / 金额 / 百分比 / 日期 / 计数）→ 飞书，要类型保真（来源不限：DataFrame、Counter、dict、list 都算） | `+table-put` | typed 协议（外层 `{"sheets":[{"name":"…","columns":[...],"data":[[...]],"dtypes":{...},"formats":{...}}]}`，**只有这四件套字段**）：`dtypes` 用 pandas dtype 串声明列类型（`int64` / `float64` / `datetime64[ns]` / `bool` / `object`），`formats` 给每列展示格式（千分位 / 百分比 / 日期）。**date 落真日期、金额 / 百分比 / 计数等数值列保精度且带 `number_format`（可排序 / 求和 / 入图表）**、string 保前导零，多 sheet 一次写 |
 | 写入含样式、批注、图片、数据校验等任意富写入 | `+cells-set` | 唯一支持完整富字段的 shortcut（公式 `+csv-put` 也能写） |
 | 只改已有 cell 的样式，不动 value/formula | `+cells-set-style` | 拍平 10 个样式字段为独立 flag；不触发不必要的值写入 |
 | 单 cell 嵌入图片 | `+cells-set-image` | 比 `+cells-set` 参数更简短 |
-| 大量纯值 + 需要表头样式/边框 | 先用 `+csv-put` 写值，再用 `+cells-set-style` 补样式 | 分工配合，入参最短 |
+| 在**已有区域**局部补表头样式/边框 | 先用 `+csv-put` 写值，再用 `+cells-set-style` 补样式 | 分工配合，入参最短 |
+| **新建子表 / 整表成套美化**（哪怕全是纯文本） | `+table-put --sheets … --styles …` 一步带值 + 全套样式（区域底色 / 边框 / 列宽 / 行高 / 合并；payload 里不存在的 sheet 名自动建子表） | `--styles` 与列是否 typed 无关，纯文本同样适用；比「写值 + 多次刷样式」少好几次调用 |
 
-**优先级**：常规批量写入（纯值或公式）优先 `+csv-put`（最短入参，直接传 CSV 文本）；含样式/批注/图片才用 `+cells-set`。⚠️ 这里"纯值"特指**已是文本、无需保留数值语义**的内容；只要列里是金额 / 百分比 / 日期 / 计数等有数值语义的数据，应优先 `+table-put`（用 typed 协议的 `dtypes` 声明列类型 + `formats` 设展示格式），而不是 `+csv-put`。
+**选命令按内容形态分流（不设"默认首选"）**：① 列有数值语义（金额 / 百分比 / 日期 / 计数）→ `+table-put`（`dtypes` 声明类型 + `formats` 设展示格式），版式装不下时 → `+cells-set` 传数字 + `number_format`；② 要样式 / 批注 / 图片 / 富文本 → `+cells-set`；③ **仅**全文本、无数值语义的内容平铺 → `+csv-put`（入参最短）。判据详见上方「数字还是文本」。
 
 ⚠️ `+csv-put` 可写值或公式：以 `=` 开头的单元格会被当作公式计算（读回时 `formula` 字段保留、`value` 为计算结果）。**公式内部含逗号 / 引号 / 换行时必须按 RFC 4180 转义**——含逗号的字段整格用双引号包裹、字段内部的引号再翻倍：如 `=COUNTIF(D5:D22,"及格")` 必须写成 `"=COUNTIF(D5:D22,""及格"")"`（外层双引号包裹整格，内部 `"及格"` 的引号翻倍成 `""及格""`）。漏转义会被 CSV 解析器按逗号拆列、整块写入区域错位（如本该 `G4:H6` 错成 `G4:K4`），详见下方 `+csv-put` 示例。**因此含逗号 / 引号 / 换行的公式优先改用 `+cells-set`（JSON 二维数组）写入——`cells[r][c].formula` 字段直接放公式串，零 CSV 转义负担，从根上避免拆列错位**（`+table-put` 的 typed 协议只接受 `columns / data / dtypes / formats` 四件套、没有 `formula` 字段，公式写入只能走 `+cells-set` / `+csv-put`）。此外 `+csv-put` **不会**携带样式/批注/图片，也无法把 `=` 开头的内容当字面量文本写入；需要样式/批注/图片用 `+cells-set`（或"写值 + 补样式"两步法）。
 
-⚠️ **别把本该是数值的列格式化成字符串用 `+csv-put` 写入**：金额 / 百分比 / 市值 / 计数等列，若在本地拼成带 `$` / `%` / 千分位的字符串（如 `"$1,234.50"` / `"+30.5%"`）再 `+csv-put` 灌进去，单元格会变成**文本**——丢失排序 / 求和 / 图表 / 透视能力，且与 `number` 列混排时无法参与计算。正解是 `+table-put --sheets` 完整 payload（外层一定要带 `{"sheets":[...]}`、列名走 `columns`、二维数据走 `data`、列 pandas dtype 走 `dtypes`、列展示格式走 `formats`），数值列用 pandas dtype 串如 `dtypes:{"价格":"float64"}`（百分比同样存小数 `0.305`），并配 `formats:{"价格":"$#,##0.00","完成率":"0.0%"}` 做展示格式，**显示效果完全相同、数值无损**。判断信号：**当你准备把一个数字 format 成字符串再写时，几乎总该用 `+table-put` 而非 `+csv-put`**。
+⚠️ **`+csv-put` 会把数值落成文本**：把金额 / 百分比 / 计数等在本地拼成带 `$` / `%` / 千分位的字符串（如 `"$1,234.50"` / `"+30.5%"`）再 `+csv-put` 灌进去，单元格就是**文本**——丢失排序 / 求和 / 图表能力，且与数值列混排无法参与计算。数值该怎么写、何时 `+table-put`、版式装不下时何时退 `+cells-set` 传数字 + `number_format`，判据与分流见上方「数字还是文本」；核心一句：**准备把数字 format 成字符串再写时就是走错了路，数值一律以数字写入 + `number_format` 控制显示。**
 
 ⚠️ 大数据回写走"`+csv-get` 按 `--range` 行窗口分批读到本地 + 本地脚本处理 + `+csv-put` 分批回写"。
 
 ## `+cells-set` 写入要点（常用模式 / 公式 / 样式）
 
-> 以下是用 `+cells-set`（及 `+cells-set-style`）做富写入时的常用模式与铁律；选哪个 shortcut 见上方「使用场景」。
+> 以下是用 `+cells-set`（及 `+cells-set-style`）做富写入时的常用模式与准则；选哪个 shortcut 见上方「使用场景」。
 
 `+cells-set` 为一块区域设置值 / 公式 / 批注 / 样式，也支持 `rich_text` 的 `type: "embed-image"` 嵌入单元格图片。**关键：`cells` 二维数组的行列维度必须与 `range`（闭区间）严格一致，否则触发 `InvalidCellRangeError`**——维度计算示例见文末 `## Schemas` 的 `--cells`。
 
@@ -80,12 +83,14 @@
 - 用户说”这列 / 整列 / 这行 / 首行 / 向下复制”时，**必须**使用模板单元格 + `--copy-to-range`
 - 多区域写入相同格式/公式结构时，优先写一个模板，再用 `--copy-to-range` 复制到所有目标区域
 
+⚠️ **模板 `--range` 从数据行起算、别把表头圈进去**：`--copy-to-range` 会把 `--range` 模板按目标区尺寸周期性平铺，模板里若含了表头行，表头会每隔几行重复铺进数据区。整列填充时模板只取一格数据样式（如 `H2`），不要取成 `H1:H2`。
+
 ⚠️ **逐行写入公式是常见低效写法**：对每一行单独调用 `+cells-set` 写公式（如 26 次）既慢又易错，且不会自动平移公式引用。正确做法是 1 次模板写入 + 1 次 `--copy-to-range`（公式引用自动平移）。
 
 💡 **写入公式前先按迁移规则改写**：如果公式来自 Excel 或包含数组场景，先读取并遵循 `lark-sheets-formula-translation` 的规则完成改写，再把最终公式写入 `formula` 字段。
 
 💡 **内容与样式分离写入（推荐）**：当需要同时写入内容和样式时，`cells` 中每个单元格都带上 `cell_styles` / `border_styles` 会导致入参非常冗长。由于同一区域的样式通常高度重复（如整列统一背景色、统一边框），推荐拆成两步：
-1. **先写内容**：`+cells-set` 只传 `value` / `formula`，不带样式，`cells` 入参精简
+1. **先写内容**：`+cells-set` 只传 `value` / `formula`，不带样式，`cells` 入参精简。⚠️ 这里"不带样式"指暂不带 `cell_styles`，**不是**降级用 `+csv-put` 铺文本——数值列（百分比 / 金额 / 计数）仍必须以数字写入（百分比传 `0.44`）：样式能后补，数据类型不能后补（见上方「数字还是文本」）。
 2. **再批量刷样式**：对区域中的一个单元格写入目标样式作为模板，再用 `--copy-to-range` 将样式扩展到整列 / 整行 / 整个区域（`--copy-to-range` 会复制值、公式和样式，所以模板单元格应已包含正确的值）
 
 示例：要对 A2:A100 写入数据并统一设置蓝色背景 + 边框：
@@ -120,6 +125,8 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl
 7. **公式范围与用户指令字面对齐**：用户说"对 F 至 L 列求和"就必须写 `SUM(F2:L2)` 或 `F2+G2+H2+I2+J2+K2+L2`，**不能漏列、多列、错列**。写完用 `+cells-get` 拿回 `formula` 字符串，与用户原话逐字对照（参与求和的列名一致 / 起止列号一致 / 运算符一致），不一致就是违规
 8. **量纲 / 单位换算 / 数量乘项预检（公式不报错但结果整体偏倍数）**：从文本提取数字做计算前，先核对**单位是否统一、是否漏乘数量、口径是否一致**——这类错误公式能跑通、无 `#` 报错，回读也看不出（值"像对的"）。必须用本地脚本对 3–5 个代表行**离线手算一遍预期值**，与公式结果逐格比对量级：① 单位不一致先统一再算（典型反例：尺寸 `320CM*337CM` 直接取数相乘除以 1e6 得 0.11，正确是 CM→MM 换算后得 10.78，**差 100 倍**）；② 按"单件×数量"的量必须乘数量列（典型反例：侧面板面积漏乘 F 列数量，F=2 的行只算了一半）；③ 标准值口径对齐（典型反例：营养成分 mg/kg 与 g/100g 口径混用，整列放大 100 倍）。**口径 / 单位 / 数量任一项错，整列计算结果就是错的；这类错误公式不报错、回读也不易看出，必须靠离线手算对照。**
 
+⚠️ **公式写入的默认收尾不是停在回读，而是继续跑 `+formula-verify`**：`+csv-get` / `+cells-get` 的抽样回读只能帮你快速发现明显错误，但它覆盖不到整列中段、隐藏行、被条件格式遮蔽的错误，也看不到 `partial` 截断。**只要这次 `+cells-set` / `--copy-to-range` / `+csv-put` 实际写入了公式，收尾默认就是转到 `lark-sheets-formula-verify` 跑 `+formula-verify`，直到 `status='success'`。** 不要等用户补一句“再验证下公式”才做。
+
 ⚠️ **收到 `formula_errors` 反馈后不要只打补丁**：`+cells-set` 返回值里若出现 `formula_errors: [{cell, formula, error_type, detail}]`，说明某些 cell 公式编译失败（`error_type=compile_failed` 通常是函数语法错如 `SPLIT(x)[1]` 的下标取值飞书不支持（SPLIT 本身支持，取第 N 项用 `INDEX(SPLIT(...),N)`）；`non_formula` 是 `=` 开头但解析不通过）。此时**禁止只聚焦修报错点的局部语法**（如仅把 `[1]` 换成 `INDEX(..,1)`），必须：
 
 1. **重新审视整条公式的完整性**：被 formula_errors 标出的那一行，公式除了下标语法错，还可能有其他先天缺陷（字符清洗不全、IFERROR 兜底漏条件、引用列写错），修完语法错后立即整体复核
@@ -227,7 +234,7 @@ lark-cli sheets +dropdown-set \
 
 > ⚠️ **`--source-range` 必须带 sheet 前缀**（即使跟 `--range` 同 sheet）。注意一个坑：回读这种 listFromRange 下拉单元格时，`data_validation.range` 看起来不带 sheet 前缀（形如 `$T$1:$T$3`），如果要把读出来的 range 反过来写回 `--source-range`，**必须自己重新补上 sheet 前缀**，否则会被拒。
 >
-> ⚠️ **sheet 前缀里的表名一律「裸写」，不要加引号**——这条对所有带 sheet 前缀的 range 入参通用（`--source-range`、`+cells-batch-set-style` / `+cells-batch-clear` / `+dropdown-update` 的 `--ranges` 等）。即使表名含点或空格（如 `2025.9`、`一月份 `），也直接写 `2025.9!A1`；**不要**按电子表格习惯写成 `'2025.9'!A1`——引号会被当成表名的一部分，导致 `sheet "'2025.9'" not found`。
+> ⚠️ **`--ranges` 类批量 flag 的 sheet 前缀必须「裸写」**——`+cells-batch-set-style` / `+cells-batch-clear` / `+dropdown-update` / `+dropdown-delete` 的 `--ranges` 解析器不接受引号：表名含点或空格（如 `2025.9`、`一月份`）也直接写 `2025.9!A1`，写成 `'2025.9'!A1` 会被当成表名一部分、报 `sheet not found`。**但 `--source-range`、透视表 `--source`、`--range` 走 A1 标准**：sheet 名带单引号（如 `'Sheet1'!A1:B2`）是标准写法、裸写也接受，回读统一返回带引号形式——别把 `--ranges` 的裸写要求套到这些 flag 上。
 
 `+dropdown-update`（多 range 批量更新）的所有 flag 语义与 `+dropdown-set` 完全一致；只是目标 `--ranges` 由单值变成 JSON 数组（每项带 sheet 前缀），同一份选项 + 配色应用到所有 range。
 
@@ -265,6 +272,7 @@ _公共四件套 · 系统：`--dry-run`_
 | `--range` | string | required | 目标范围（A1 格式，如 `A1:B2`） |
 | `--background-color` | string | optional | 背景颜色（十六进制，如 `#ffffff`） |
 | `--font-color` | string | optional | 字体颜色（十六进制，如 `#000000`） |
+| `--font-family` | string | optional | 字体名称（如 `Arial`、`微软雅黑`） |
 | `--font-size` | float64 | optional | 字体大小（px，例：10、12、14） |
 | `--font-style` | string | optional | 字体样式（可选值：`normal` / `italic`） |
 | `--font-weight` | string | optional | 字重（可选值：`normal` / `bold`） |
@@ -330,7 +338,7 @@ _【维度】行列数必须与 range 完全一致：'A1:C2'→[[_,_,_],[_,_,_]]
 - `value` (oneOf?) — 静态单元格值（文本、数字、布尔）
 - `formula` (string?) — 以 '=' 开头的单元格公式（例如：'=SUM(A1:A10)'）
 - `note` (string?) — 单元格批注/备注
-- `cell_styles` (object?) — 单元格样式属性，包括字体、颜色、对齐方式和数字格式 { font_color?: string, font_size?: number, font_weight?: enum, font_style?: enum, font_line?: enum, …共 10 项 }
+- `cell_styles` (object?) — 单元格样式属性，包括字体、颜色、对齐方式和数字格式 { font_color?: string, font_family?: string, font_size?: number, font_weight?: enum, font_style?: enum, …共 11 项 }
 - `border_styles` (object?) — 单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top） { top?: object, bottom?: object, left?: object, right?: object }
 - `rich_text` (array<object>?) — 富文本内容 each: { type: enum, text: string, style?: object, link?: string, mention_token?: string, …共 17 项 }
 - `multiple_values` (array<object>?) — 多值内容，用于支持多选的列表验证单元格 each: { value: oneOf, format?: string }
@@ -373,7 +381,7 @@ _一个或多个子表的 typed 数据，每个数组元素写入一张子表；
 
 **数组项**（类型 object）：
 - `cell_merges` (array<object>?) — 单元格合并操作数组；range 使用 A1 单元格范围，merge_type 默认 all each: { merge_type?: enum, range: string }
-- `cell_styles` (array<object>?) — 单元格样式操作数组；每项用 A1 单元格 range 指定范围，字段名与 +cells-set-style 对齐 each: { background_color?: string, border_styles?: object, font_color?: string, font_line?: enum, font_size?: number, …共 12 项 }
+- `cell_styles` (array<object>?) — 单元格样式操作数组；每项用 A1 单元格 range 指定范围，字段名与 +cells-set-style 对齐 each: { background_color?: string, border_styles?: object, font_color?: string, font_family?: string, font_line?: enum, …共 13 项 }
 - `col_sizes` (array<object>?) — 列宽操作数组；range 使用列范围如 A:C，type 为 pixel/standard，pixel 需要 size each: { range: string, size?: number, type: enum }
 - `name` (string) — 子表名
 - `row_sizes` (array<object>?) — 行高操作数组；range 使用行范围如 1:3，type 为 pixel/standard/auto，pixel 需要 size each: { range: string, size?: number, type: enum }

skills/lark-slides/SKILL.md

@@ -4,7 +4,7 @@ version: 1.0.0
 description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
 metadata:
   requires:
-    bins: [ "lark-cli" ]
+    bins: ["lark-cli"]
   cliHelp: "lark-cli slides --help"
 ---
 
@@ -12,36 +12,198 @@ metadata:
 
 ## Quick Reference
 
-| 用户需求 | 指引 |
-|----------|------|
-| 读取 / 分析本地 PPTX 内容 | 文本用 `python -m markitdown presentation.pptx`；视觉总览用 `python3 scripts/thumbnail.py presentation.pptx`；原始 OOXML 用 `python3 scripts/office/unpack.py presentation.pptx unpacked/` |
-| 从模板创建或编辑已有本地 PPTX | 先读 `lark-slides-pptx-template-workflows.md` |
-| 从零新建飞书在线 PPT | 先读 `lark-slides-create-workflows.md` |
-| 获取在线 slides 内容、读取 / 分析已有在线 PPT | XML 内容优先用 `slides +xml-get` 保存到文件；页面视觉内容用 `slides +screenshot`，详见 `lark-slides-screenshot.md` |
+| 用户需求 | 优先动作 | 关键文档 / 命令 |
+|----------|----------|-----------------|
+| 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
+| 已有 PPT 大幅改写 | 多页整页重建用 `+replace-pages`，单页局部编辑用 `+replace-slide` | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
+| 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
+| 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
+| 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面 | `slides +screenshot`、`lark-slides-screenshot.md` |
+| 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 |
+| 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表 | 使用原生 `<chart>` 元素 | `xml-schema-quick-ref.md` |
+| 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `<whiteboard>` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) |
+| 使用语义图标 | 先检索 IconPark，再写 `<icon iconType="...">` | `iconpark_tool.py search → resolve`、`iconpark.md` |
+| 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
 
-## 读取 / 分析内容
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
 
-### 在线 Slides
+**CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
+
+**CRITICAL — PPT 生成与模板编辑硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。多用生图，辅助搜图，必须要图文并茂。不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。生成背景图时必须在 prompt 中明确要求不要出现任何文字。用户指定 PPT 模板时，用 lark-drive 技能导入成 lark slides，回读理解每页版式后，直接在该 slides 上编辑，可以填改文字和图片、按需增删模板页，必须严格沿用原版式和字体，只改内容不做设计，完成后回读并微调，凝练文字或缩减字号消除文字溢出，调整 shape 顺序或位置避免文字遮挡。**
+
+**CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。**
+
+**CRITICAL — 新建演示文稿或大幅改写页面时，生成 XML 前 MUST 读取 [visual-planning.md](references/visual-planning.md)，确保 `layout_type`、`visual_focus`、`text_density` 实际改变页面几何、主视觉和文本量。**
+
+**CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。**
+
+**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险；XML 语法和文本重叠静态检查优先使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)。**
+
+**CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
+
+**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；已有 Slides 的多页大改优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内批量重建页面，避免 `slides +create` 生成新链接。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
+
+## 身份选择
+
+飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。
+
+- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权：
 
 ```bash
-# 读取完整 XML 内容，优先保存到文件再分析
-lark-cli slides +xml-get --as user --presentation slides_example_presentation_id --output presentation.xml --json
-
-# 获取页面截图；必须指定 --slide-number 或 --slide-id，多个页面可重复传 --slide-number
-lark-cli slides +screenshot --as user --presentation slides_example_presentation_id --slide-number 1 --output-dir screenshots --json
+lark-cli auth login --domain slides
 ```
 
-在线 Slides 的截图参数和页码语义详见 [`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)；需要继续编辑在线 Slides 时，按 `lark-slides-create-workflows.md` / `lark-slides-replace-workflows.md` 选择创建或替换流程。
+- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。
 
-## 编辑 PPTX 工作流
+**执行规则**：
 
-**完整流程先读 [`lark-slides-pptx-template-workflows.md`](references/lark-slides-pptx-template-workflows.md)。**
+1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。
+2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。
+3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。
 
-## 从零创建
+## 执行前必做
 
-**完整流程先读 [`lark-slides-create-workflows.md`](references/lark-slides-create-workflows.md)。**
+> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。
 
-当没有本地 PPTX 模板 / 参考演示文稿，或目标是新建飞书 / Lark 在线 Slides 而不是本地 `.pptx` 文件时，使用该流程。
+高频只读：
+
+- [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)
+- [planning-layer.md](references/planning-layer.md)（新建 / 大幅改写）
+- [visual-planning.md](references/visual-planning.md)（新建 / 大幅改写）
+- [asset-planning.md](references/asset-planning.md)（新建 / 大幅改写）
+- [validation-checklist.md](references/validation-checklist.md)（创建 / 大幅改写后）
+
+按需再读：
+
+- 创建：[`lark-slides-create.md`](references/lark-slides-create.md)
+- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md)
+- 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)
+- 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
+- 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
+- 图标：[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py)
+- 排障：[`troubleshooting.md`](references/troubleshooting.md)
+- 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml)
+
+## Workflow
+
+> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。
+
+### Design Ideas
+
+不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。
+
+开始写 XML 前，先在 `slide_plan.json` 里确定 deck 级视觉策略：
+
+- **主题化配色**：配色必须服务本次主题、行业和受众，不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立，说明配色不够具体。
+- **主次比例**：选择 1 个主色承担约 60-70% 视觉权重，1-2 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。
+- **背景一致性**：先确定全 deck 的背景策略，默认保持同一明暗基调和底色体系；只有分节、转场或强调页才有意改变背景，并必须通过相同主色、纹理、边栏或 motif 让变化看起来属于同一套设计。无论深浅，都要保证正文、图标和线条对比充足。
+- **统一 motif**：选择一个可复用视觉母题贯穿全文，例如粗侧边栏、圆形图标底、半出血图片区、编号节点、卡片左上角色块或大号数字。不要每页换一套装饰语言。
+
+每页至少要有一个视觉元素：图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉。文本框本身不算主视觉。
+
+可优先考虑这些页面形态：
+
+- **双栏结构**：左文右图或左图右文，视觉区域占 35-45% 宽度。
+- **图标行**：图标在色块或圆形底中，右侧是短标题和一句解释。
+- **2x2 / 2x3 网格**：适合能力、模块、风险、行动项，每格内容保持同等层级。
+- **半出血视觉**：图片或抽象形状占据左/右半屏，文字覆盖或贴边排布。
+- **大数字卡片**：关键指标用 60-72pt 数字，下面配 10-14pt 标签。
+- **对比列**：before/after、方案 A/B、问题/解法用左右并列，标题和基线严格对齐。
+- **时间线/流程图**：步骤用节点和箭头表达，流程方向必须一眼可见。
+
+字体和间距建议：
+
+- 标题 36-44pt，关键结论可更大；正文 14-18pt；注释 10-12pt。
+- 正文默认左对齐；只在封面、结尾或大号数字场景中使用居中。
+- 页面边距至少 40px；内容块之间保持 24-40px 间距，并在同一 deck 内保持一致。
+- 卡片内边距要真实留出空间，不要让文字贴边；对齐 shape 和文字时要考虑文本框 padding。
+
+常见错误必须避免：
+
+- 不要所有页面复用同一种标题 + 三 bullets 版式。
+- 不要用低对比文字或低对比图标，例如浅灰字压在浅色背景上。
+- 不要让装饰线穿过文字，或让页脚、来源、编号挤压主体内容。
+- 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。
+- 不要留下占位文案、示例公司名、示例日期或与用户主题无关的内容。
+
+### 创建方式选择
+
+| 场景 | 推荐方式 |
+|------|----------|
+| 简单 XML（1-3 页、结构简单、几乎无复杂中文和特殊字符） | `slides +create --slides '[...]'` 一步创建 |
+| 复杂 XML（多页、含中文、大段文本、复杂布局、嵌套引号、特殊字符较多） | **两步创建**：先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide create` 逐页添加 |
+| 已有 PPT 继续追加或插入页面 | 使用 `xml_presentation.slide create`，必要时配合 `before_slide_id` |
+
+> [!WARNING]
+> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议使用两步创建法。
+
+> [!IMPORTANT]
+> `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
+
+```text
+Step 1: 需求澄清 & 读取知识
+  - 澄清主题、受众、页数、风格
+  - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
+
+Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json
+  - 生成结构化大纲供用户确认
+  - 新建 / 大幅改写必须先创建目录并写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`
+  - plan 字段、路径命名和 `asset_need` 结构按 planning-layer.md / asset-planning.md 执行
+
+Step 3: 按 slide_plan.json 生成 XML → 创建
+  - 逐页消费 plan：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
+  - 缺少真实素材时必须用 `fallback_if_missing` 生成 XML-native 兜底视觉；不要留空
+  - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
+
+Step 4: 审查 & 交付
+  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
+  - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
+  - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
+```
+
+### jq 命令模板（编辑已有 PPT 时使用）
+
+新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
+
+```bash
+# 追加到末尾
+lark-cli slides xml_presentation.slide create \
+  --as user \
+  --params '{"xml_presentation_id":"YOUR_ID"}' \
+  --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
+  <data>
+    在这里放置 shape、line、table、chart、whiteboard 等元素
+  </data>
+</slide>' '{slide:{content:$content}}')"
+
+# 插到指定页之前：before_slide_id 必须在 --data body 里，与 slide 同级
+# ⚠️ 不要把 before_slide_id 写进 --params —— CLI 会当未知 query 参数静默下发，服务端忽略，新页跑到末尾
+lark-cli slides xml_presentation.slide create \
+  --as user \
+  --params '{"xml_presentation_id":"YOUR_ID"}' \
+  --data "$(jq -n --arg content '<slide ...>...</slide>' --arg before 'TARGET_SLIDE_ID' \
+    '{slide:{content:$content}, before_slide_id:$before}')"
+```
+
+> 渐变色必须使用 `rgba()` 格式并带百分比停靠点，如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端回退为白色。
+
+### 大纲模板
+
+生成大纲时使用以下格式，交给用户确认：
+
+```text
+[PPT 标题] — [定位描述]，面向 [目标受众]
+
+页面结构（N 页）：
+1. 封面页：[标题文案]
+2. [页面主题]：[要点1]、[要点2]、[要点3]
+3. [页面主题]：[要点描述]
+...
+N. 结尾页：[结尾文案]
+
+风格：[配色方案]，[排版风格]
+```
 
 ## 核心概念
 
@@ -78,98 +240,35 @@ Slides (演示文稿)
     └── slide_id (页面唯一标识)
 ```
 
-## 身份选择
+## Shortcuts 与 API
 
-飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。
+Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`）。有 Shortcut 的操作优先使用。
 
-- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权：
+| Shortcut | 说明 |
+|----------|------|
+| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传） |
+| [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
+| [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
+| [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面：先创建新页到旧页前，再删除旧页；适合已有 Slides 的多页大改，不新建链接 |
+
+没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
 
 ```bash
-lark-cli auth login --domain slides
+lark-cli schema slides.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli slides <resource> <method> [flags] # 调用 API
 ```
 
-- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
 
-**执行规则**：
+## 核心规则
 
-1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。
-2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。
-3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。
+1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；风格和大纲只能作为规划输入，不能绕过规划层
+2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
+3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
+4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
+5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
+6. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
+7. **编辑已有页面优先原链接更新**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；已有 Slides 的多页整页重建用 `+replace-pages`，不要用 `slides +create` 新建整份 PPT；只有没有 shortcut 覆盖的特殊单页整页操作才手动 `slide.create` + `slide.delete`
+8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
 
-## 设计思路
-
-### 内容先行
-
-- 每页只服务一个核心观点。内容页标题应写成带判断的结论句，而不是主题标签；读者只看标题就能知道这一页要证明什么。
-- 受众和交付方式决定密度：演讲型 deck 更适合少字、强节奏、分步呈现；自读型 deck 必须在没有讲解和点击的情况下完整可读。
-- 并列观点要互不重叠、没有明显缺口，通常控制在 3-5 个，最多不要超过 7 个；排序只选一种逻辑：时间、结构或重要性。
-- 封面、章节页、内容页、结尾页承担不同任务。章节页只做过渡，不承载多点论证；短 deck 不要机械加入 agenda、Q&A 或多个收尾页。
-
-### 视觉系统
-
-- 先根据主题、行业、受众和交付方式推导视觉方向，再确定配色、字体、图形语言和页面密度；不要让用户在一堆抽象风格词里做选择。
-- 同一份 deck 要锁定一套视觉系统，并贯穿所有页面：主色、背景、正文颜色、强调色、标题处理、留白密度、图标/图形风格都要稳定。
-- 配色要有角色分工：`primary` 承担品牌/结构，`background` 承担页面基底，`text_primary` / `text_body` 保证阅读，`accent` 只用于关键数字、结论或行动点。
-- 不要默认蓝色商务风；如果一套配色换到完全不同主题仍然成立，说明它不够具体。
-- 背景策略要克制：纯色、渐变或图片三选一作为主背景，不要叠多层全页色块。深色、发光或科技感页面，应使用平整深色背景 + 局部发光元素，而不是半透明大渐变把页面洗白。
-- 所有文字、图标、线条和图表都必须与背景保持足够对比；弱化信息可以降低饱和度或透明度，但不能牺牲可读性。
-
-### 字体与字号
-
-- 标题字体可以有性格，正文字体必须清晰耐读；不要整份 deck 都默认 Arial。
-- 中英文混排时，字体族先写英文/拉丁字体，再写中文/CJK 字体，最后写通用 fallback；标题和正文各用一套稳定组合。
-- 字体选择要匹配视觉系统的类别和处理方式：衬线、无衬线、圆体、等宽、粗窄标题、全大写等风格不要随意互换。
-- 常用标题方向：`Playfair Display` / `EB Garamond` / `Lora` 适合编辑感和高级感；`Anton` / `Bebas Neue` / `Oswald` 适合强冲击标题；`DM Sans` / `Montserrat` / `Poppins` 适合现代产品和商业正文。
-- 常用中文方向：`思源宋体` 适合长文和编辑感；`思源黑体` / `黑体` 适合中性现代；`寒蝉德黑体` 适合工业和科技；`寒蝉全圆体` / `资源圆体` 适合温暖亲和；书法类字体只用于少量标题。
-
-| 元素 | 建议字号 |
-|------|----------|
-| 封面标题 | 40-56px；纯标题页可到 64-96px |
-| 内容页标题 | 28-40px |
-| 副标题 / 分区标题 | 20-26px |
-| 正文一级 | 16-20px |
-| 正文二级 | 13-16px |
-| 注释 / 来源 | 11-13px |
-| Hero number | 80-140px |
-
-不要为了填满空页面而盲目放大字体；页面显得空时，优先补充有意义的信息、调整构图或强化边缘对齐。
-
-### 布局
-
-- 先判断内容关系，再设计版式。比较、流程、时间线、循环、层级、矩阵、漏斗、整体-部分、因果等关系，应通过位置、对齐、分组、比例和流向直接表达。
-- 版式本身要承载逻辑：比较用并列和基线对齐，流程用方向和连接，层级用尺度和嵌套，矩阵用坐标和象限，因果用箭头和阅读顺序。
-- 每页都应围绕该页内容重新组织，不要从固定模板里盖章；同一 deck 可以复用视觉母题，但不要所有页面都是标题 + 三 bullets。
-- 页面要留呼吸感。内容块之间保持稳定间距，卡片内边距要真实存在；文字不要贴边，也不要被装饰线、图片或页脚挤压。
-- 正文默认左对齐；只有封面、章节页、结尾页、大号数字或少量仪式感页面适合居中。
-
-### 视觉元素与图表
-
-- 视觉元素必须承载意义或引导注意力，不做填空装饰。图片、图标、图表、表格、色块、连线都要解释内容关系、强调重点或改善阅读节奏。
-- 每个内容页至少应有一个非纯文本视觉锚点：图片、图标、图表、表格、流程、对比结构、大号数字、示意图或抽象 shape 组合。
-- 信息图、截图、图表等素材要保持原始比例；不要为了塞进版面强行裁切或拉伸。装饰性照片可以更自由，但仍要服务主题和构图。
-- 有真实数据序列时，先写清图表要证明的 takeaway，再选择图表类型；一张图只表达一个核心结论。单个数字或两项简单对比，优先用大号数字 callout，不必硬画图。
-- 饼图 / 环图只适合表达明确的整体构成；不确定时优先使用排序条形图。多系列数据要控制数量，必要时合并为 Other。
-- 封面和结尾页的图片不要自带文字；文字应由 slide 渲染，避免图片中文字不可控、不可编辑或与语言风格冲突。
-
-### 动效
-
-- 动效服务节奏和注意力，不做炫技。只有在逐步解释、引导关键元素、展示流程 / 时间 / 变化时才使用。
-- 演讲型 deck 可以用少量 build 控制听众视线；自读型、正式汇报型、董事会/咨询风格 deck 应尽量静态，最多使用统一的页面转场。
-- 封面、章节页和结尾页默认静态。单页动效不超过 3 个 build，且同页尽量只使用一种效果；如果需要更多步骤，优先拆页。
-- 动效要让观众注意内容出现，而不是注意效果本身。优先使用淡入、出现、轻微上浮、擦入；避免旋转、弹跳、闪烁、远距离飞入等抢戏效果。
-
-### 基于模板或已有 PPT 编辑
-
-- 如果用户要求继续编辑、补页或修改已有 PPT，默认保留原页面内容、结构、字体、配色和视觉资产，只改用户要求的部分。
-- 除非用户明确要求重做，不要擅自美化、重排、加封面、换背景或从零复刻。
-- 如果用户把上传文件作为“参考风格”而不是“继续编辑原文件”，才可以抽取其视觉语言后重新创作。
-
-### 避免事项
-
-- 不要让版式先于内容；先判断这一页的逻辑关系，再决定几何结构。
-- 不要创建纯文本页；plain title + bullets 只能作为草稿，不是正式交付。
-- 不要只设计一页，其余页面保持 plain；视觉系统必须全篇贯彻，或者全篇保持有意克制。
-- 不要混用太多字体、字号、圆角、阴影和强调色；变化必须有层级意义。
-- 不要使用低对比文字、低对比图标或难以阅读的背景图。
-- 不要用图表承载多个结论，也不要因为有数字就机械画图。
-- 不要在标题下方画装饰强调线作为默认设计手法；优先用留白、背景色块、尺度、分区和对齐建立层级。
+> **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。

skills/lark-slides/references/asset-planning.md

@@ -0,0 +1,124 @@
+# Asset Planning
+
+新建演示文稿或大幅改写页面时，在写入 `slide_plan.json` 前后都可以参考本文件。目标是让 agent 主动识别有价值的图、图标、图表、流程图、时序图、架构图、装饰图案、截图或示意图需求，同时保持 deck 在没有真实素材时也能完整执行。
+
+本文件只定义轻量资产规划。不要把它理解成素材采集流程。
+
+## Core Rules
+
+- `asset_need` is metadata only. It can guide page design, but it must not require web search, local download, media upload, or external tools.
+- Every planned asset must include a fallback visual plan so the slide can be generated with XML shapes, text, arrows, tables, simple charts, whiteboard diagrams, or placeholder regions.
+- Asset needs must serve the page's `key_message` and `visual_focus`. Do not add decorative assets that do not clarify the page.
+- Prefer a few high-value asset plans over one asset on every page. For a 6-page technical or business deck, plan assets on at least 3 pages when the content allows.
+- If a real local asset already exists or the user provides one, it can be used through the normal media-upload workflow. Still keep `fallback_if_missing` in the plan.
+- Do not leave blank image boxes in final XML. If the asset is missing, render the fallback visual.
+
+## JSON Shape
+
+Use an object for one planned asset, or an array when a page genuinely needs multiple assets. Keep each item compact.
+
+```json
+{
+  "asset_type": "architecture_diagram",
+  "purpose": "Show how API gateway, planner, XML generator, and Slides API interact.",
+  "suggested_query": "agent native slides runtime architecture diagram",
+  "fallback_if_missing": "Draw grouped boxes connected by arrows with short labels."
+}
+```
+
+For a page without a meaningful asset need, use:
+
+```json
+{
+  "asset_type": "none",
+  "purpose": "No external or simulated asset needed; the page is text-led.",
+  "suggested_query": "",
+  "fallback_if_missing": "Use typography, spacing, and simple accent shapes only."
+}
+```
+
+## Supported Asset Types
+
+- `paper_figure`: figure from a paper or technical article.
+- `architecture_diagram`: system components, data flow, dependency map, or model structure.
+- `icon`: small semantic symbol for a concept, step, role, or status.
+- `logo`: brand, product, team, or customer mark.
+- `chart`: line, bar, pie, radar, area, or combo data visual. Note: `<chart>` does not support funnel or scatter — map those to `<whiteboard>` SVG at generation time.
+- `infographic`: composed visual explanation, usually combining labels, numbers, and simple shapes.
+- `screenshot`: product UI, terminal output, workflow state, or page capture.
+- `flow_diagram`: process, sequence, decision tree, or mechanism diagram.
+- `none`: explicitly no asset needed.
+
+Do not invent new asset types unless the user asks for a special visual format. If a need is close to these types, choose the closest one and explain the detail in `purpose`.
+
+## Planning Guidance
+
+Match asset type to slide role:
+
+- `architecture-diagram` layout usually pairs with `architecture_diagram` or `flow_diagram`.
+- `process-flow` layout usually pairs with `flow_diagram`, `icon`, or `infographic`.
+- `comparison` layout often works with `icon`, `chart`, or `infographic`.
+- `timeline` layout often works with `icon`, `chart`, or shape-based milestone markers.
+- `big-number` layout often works with `chart` or `infographic`, but only if it supports the metric.
+- `image-left-text-right` and `image-right-text-left` can use `screenshot`, `paper_figure`, `logo`, or `infographic`; if missing, use a large placeholder diagram or stylized panel.
+
+`suggested_query` is only a future lookup hint. Write it as a short phrase a human or later workflow could search, but do not execute the search unless the user separately requests real assets.
+
+`fallback_if_missing` must be concrete enough to turn into XML, for example:
+
+- "Draw a simplified attention matrix with 5 token labels, semi-transparent cells, and arrows to output token."
+- "Use three grouped boxes with arrows from client to gateway to service; add small protocol labels."
+- "Render a mini bar chart with 4 bars using shapes and value labels."
+- "Use a bordered placeholder panel with product area labels, not an empty image."
+
+Weak fallbacks to avoid:
+
+- "Use a placeholder."
+- "Find another image."
+- "Leave blank if unavailable."
+- "Use generic decoration."
+
+## Examples
+
+Transformer Self-Attention page:
+
+```json
+{
+  "asset_type": "paper_figure",
+  "purpose": "Explain token-to-token attention and why each output token mixes context.",
+  "suggested_query": "Transformer self attention attention matrix diagram",
+  "fallback_if_missing": "Draw a simplified attention matrix with token labels, colored weights, and arrows from input tokens to one highlighted output token."
+}
+```
+
+System architecture page:
+
+```json
+{
+  "asset_type": "architecture_diagram",
+  "purpose": "Show the runtime path from user prompt to plan, XML generation, Slides API creation, and fetch verification.",
+  "suggested_query": "slides generation runtime architecture planner XML API verification",
+  "fallback_if_missing": "Draw four grouped boxes connected left-to-right with arrows; put verification as a return arrow from Slides API to agent."
+}
+```
+
+Business comparison page:
+
+```json
+{
+  "asset_type": "infographic",
+  "purpose": "Make before/after differences scannable without dense bullet lists.",
+  "suggested_query": "before after product workflow comparison infographic",
+  "fallback_if_missing": "Use two side-by-side panels with matching icon circles and three parallel rows of concise labels."
+}
+```
+
+## Plan To XML Contract
+
+When generating XML:
+
+1. If an asset exists and the workflow supports it, place it in the planned visual region.
+2. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, whiteboard diagrams, or chart-like elements.
+3. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
+4. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
+5. After creation, fetch the presentation and verify asset pages are not blank and that each planned fallback is visible when no real asset was used.

skills/lark-slides/references/design-rules.md

@@ -1,155 +0,0 @@
-# 设计规则
-
-这份规则用于生成或大幅改写演示文稿时做布局、组件、视觉层级和 XML 决策。它不是审美评论清单，而是生成前必须落到坐标、字号、颜色、组件和校验动作里的约束。
-
-默认画布按 `960 x 540` 规划。模板可以覆盖具体坐标，但不能覆盖这些原则：页面要有清晰主视觉区域，文本要受密度约束，不同页型必须产生明显不同的几何结构。
-
-## 生成前先定的事
-
-- 先定页面角色：封面、章节页、观点页、证据页、数据页、对比页、流程页、时间线页、结论页。
-- 先定一个主锚点：标题、关键数字、图表、截图、结论句或对比差异。主锚点必须是页面最大、最靠前或最高对比的区域。
-- 先定结构令牌：外边距、标题区、主体区、栏宽、模块间距、组件内边距、圆角、线条粗细、色彩令牌和字体角色。
-- 先定文本密度，再写文本。不要先塞满内容，再靠缩字号抢救。
-- 先定组件类型。只有当内容确实是同级可比对象时才用卡片；只有当顺序有意义时才用流程或时间线。
-
-## 核心规则
-
-- `layout_type` 必须改变几何：不同页型的元素位置、区域大小、对齐方式和视觉节奏都要明显不同。
-- `visual_focus` 必须成为最大或最高对比区域。它可以是图片、图表、指标、引语、表格或形状占位视觉。
-- `text_density` 用来限制可见文本量：
-  - `low`：标题加一句短陈述，或 1-3 个标签。
-  - `medium`：标题加 2-4 条短要点，或若干带标签的信息区。
-  - `high`：使用表格、分栏、分组标签或注释。不要用一个长 bullet 框承载所有信息。
-- 不要把整份演示文稿做成“标题加 bullet”。当页面数不少于 4 页且内容允许时，至少使用 4 种不同布局结构。
-- 优先使用少量大对象，不要堆很多小文本框。
-- 每页只允许 1 个主锚点。次级锚点必须解释、证明或补充主锚点，不能与它争抢注意力。
-
-## 布局与间距
-
-- 常规内容页使用 `60-80` px 外边距，除非有意使用全出血图片或封面式处理。
-- 常规内容页标题区通常为 `y=36..90`，主体内容通常从 `y>=110` 开始。标题文本框要足够宽，避免意外换行。
-- 非背景内容应尽量位于 `y=500` 以上，页脚除外。
-- 优先把主体拆成 2-3 个大区域，而不是很多碎片。常见结构包括：左文右图、左图右文、上标题下模块、指标锚点加证据区。
-- 同级模块必须共享 x/y、宽高、内边距和槽位顺序。不同尺寸只在差异本身就是信息时使用。
-- 相关元素之间的距离应小于不相关元素之间的距离；主锚点周围留更大呼吸空间，次要信息可以更紧凑但必须对齐。
-- 间距令牌要显式：`margin`、`titleGap`、`moduleGap`、`innerPadding`。重复模块用令牌生成坐标，不要手工逐个摆放。
-
-## 背景与视觉母题一致性
-
-- 为普通内容页选择一个默认背景，并精确复用。避免多个近似但不一致的背景色，除非它明确表示章节变化。
-- 封面、强调页、结论页可以使用深色、图片主导或高对比背景，但仍必须共享整套文稿的主色、视觉母题、边缘处理、字体或几何语言。
-- 如果封面使用左右或分区构图，背景或版式中必须看得出分区；为文字区和视觉区保留各自空间。
-- 复用少量视觉装置：侧边栏、卡片圆角、节点样式、线条粗细、图标容器或页脚处理。
-- 背景和视觉母题形状应先于内容元素插入，避免遮住文字、图片或图示。
-
-## 视觉层级
-
-- 用位置、大小、字重、留白和颜色共同建立层级，不要只靠颜色。
-- 至少定义 3 个清晰文本层级：标题/主张、模块标题或标签、正文/注释。复杂页可增加指标和来源角色。
-- 指标、结论或关键差异如果是页面主旨，必须放在专用区域中，不能埋在段落、图例或小卡片里。
-- 颜色只用于确认已经由尺寸和位置建立的层级。到处使用强调色会让页面失去重点。
-- 装饰不能成为第一视觉停点；分割线、网格线、卡片边框应低对比，除非它们表示选择、风险或状态。
-
-## 字体与文本框
-
-把字体当作角色系统，而不是逐个文本框随机调样式。推荐先定义这些角色：`deckTitle`、`slideTitle`、`sectionLabel`、`moduleTitle`、`body`、`caption`、`metric`、`source`。
-
-| 文本用途 | 常见字号 | 最小高度 |
-|----------|----------|----------|
-| 注释，1 行 | 10-12 | 18 |
-| 注释，2 行 | 10-12 | 30 |
-| 正文，1 行 | 13-16 | 24 |
-| 正文，2 行 | 13-16 | 40 |
-| 正文，2 行，加粗 | 15-18 | 48 |
-| 小标题，1 行 | 24-32 | 42 |
-| 大标题，2 行 | 34-44 | 110 |
-| 核心指标 | 64-110 | 110 |
-
-补充规则：
-
-- 同一角色在同一页和同一组组件中必须使用相同 `fontFamily`、`fontSize`、`fontWeight` 和颜色。
-- 加粗文本、中文文本、中英混排、较大行距，或包含多个段落的文本块，都需要增加高度。
-- 不要把较长中文句子或英文短语放进 `height=18` 或 `height=22` 的文本框。这类高度只适合短标签。
-- 不要通过把正文缩到不可读来解决拥挤。优先缩短文案、拆分模块、扩大文本框或换成表格/卡片/图示结构。
-- 页脚和来源说明通常只放一行短文本。如果需要更多内容，应放成页脚上方的正式注释块。
-- 底部结论条承载一行强调文本时至少 `40` px 高，承载两行时至少 `54` px 高。
-
-## 色彩
-
-- 从中性底色、高对比正文色、低对比分割色、一个强调色开始。只有在表达正负、风险、阶段、类别等语义时才增加语义色。
-- 普通内容页避免给每个模块不同填充色。模块填充用于分组，强调色用于标记重要项或当前项。
-- 图表配色应克制：大多数系列保持柔和，只高亮支持页面结论的系列、行、列或单元格。
-- 同一套演示文稿中强调色的含义要稳定。不要在一页表示推荐，下一页又表示风险。
-- 长正文不要放在高饱和背景上。深色或图片背景必须保证标题和正文对比度。
-
-## 页型规则
-
-把这些高频页型当作几何承诺，而不是名称。
-
-| `layout_type` | 几何承诺 | 文本限制 |
-|---------------|----------|----------|
-| `title-cover` | 一个主导性标题块，可配全出血背景、侧边大图、强调带或分区视觉区域。 | 只用 `low`：标题加副标题/背景句，不放 bullets。 |
-| `section-opener` | 大章节编号、标签或标题成为主锚点，其他内容只做定位。 | 只放章节名、短引导句和必要元信息。 |
-| `image-left-text-right` | 左侧视觉区占约 `35-45%` 宽度；密集截图或论文图可放大到 `50-65%`；右侧文本通常从 `x=420` 开始。 | 一个主标题加最多 4 条要点，或 2-3 张解读卡片/标注。 |
-| `image-right-text-left` | 左侧文本区通常从 `x=60..90` 开始，宽 `400..460`；右侧视觉区占约 `35-45%` 宽度，并与主文本块对齐。 | 一个核心判断加 2-3 条支撑点；标注要短且结构平行。 |
-| `two-column` | 主区域拆成两个均衡栏，例如 `x=60,width=400` 和 `x=500,width=400`；每栏都需要自己的标题或视觉锚点。 | `medium`：每栏 2-3 条短内容。`high`：使用分组行或小表格。 |
-| `big-number` | 最大对象必须留给指标：字号常为 `64-110`，区域至少 `300 x 120`。 | `low` 或 `medium`；数字周围只放紧凑标签、图例或小卡片。 |
-| `comparison` | 使用两个或三个对齐的面板、列、表格或小倍图；用一个明确线索突出推荐项或关键差异。 | 使用平行表述；避免长短不一的 bullet 列表。 |
-| `cards` | 2-6 个同级模块共享宽高、内边距、标题位置和槽位顺序。 | 每张卡片只承载一个短观点，不放段落。 |
-| `process` | 重复节点加连接线，形成单一路径；连接线在节点和标签下方。 | 步骤标签比描述更突出，描述短且平行。 |
-| `timeline` | 里程碑沿时间轴排列；时间差重要时按时间比例，否则按序列均分。 | 日期/阶段标签优先，说明文字短。 |
-| `data` | 结论区与证据区分离，指标或洞察先于图表细节。 | 图表标题写洞察，不只写指标名。 |
-| `conclusion` | 使用一个主导性的结论句或行动号召，最多搭配 3 个下一步卡片、检查项或负责人/日期标签。 | 保持易记，不要堆总结。 |
-
-## 组件规则
-
-- **封面/章节页**：只保留标题组、主视觉和少量元信息。不要把封面做成执行摘要、仪表盘或多卡片汇总。
-- **指标组件**：包含 value、unit、label、explanation、optional delta。数值是最大文本，单位和限定词靠近数值但更小。
-- **数据图表**：先给图表/表格留足边界，再放标注。优先用直接标签减少视线往返；网格线和坐标轴低对比。
-- **对比组件**：被比较对象必须共享槽位顺序，例如 label、metric、visual、description、emphasis marker。只高亮一个推荐项、变化项或风险项。
-- **卡片组件**：卡片只用于真实同级对象。标题长度和字号要平行，正文用一句话，推荐或选中卡片最多增加一个强调线索。
-- **流程/时间线**：节点从数组或索引生成位置，连接线先画、节点后画、标签最后画。不要让连接线穿过文字。
-- **截图/论文图/产品图**：真实素材必须足够大到可读；若过密，应裁切关键区域、做局部放大，或用原生形状重画核心信息。
-
-## 截图与真实素材页面
-
-- 根据页面角色决定放置方式，不按固定页码套模板。方法概览、证据页、对比页和失败分析页通常更适合放真实图片。
-- 只有在图片以幻灯片尺寸展示仍可读时，才直接使用真实素材。如果图过密，应裁切关键区域、做局部放大，或用原生形状重画核心信息。
-- 截图或真实图片通常应成为视觉焦点。不要把它缩成装饰性缩略图，同时在周围堆大量文字。
-- 配少量解释性标注，告诉观众应该看哪里。
-- 使用外部素材或论文图时，始终添加简短来源说明。
-
-## XML / Slides 生成规则
-
-- 先定义画布、边距、标题区、主体区、栏宽、间距、颜色、字体角色和组件 token，再生成具体对象。
-- 每个文本框必须先有语义角色，再分配坐标、字号、字重和颜色。
-- 所有形状、文本、图片、图表都使用显式 `x/y/width/height`，不要依赖默认位置或自适应猜测。
-- 重复组件必须从同一数据数组和同一几何函数生成，避免手写出微小不一致。
-- z-order 顺序通常是：背景、分区形状、连接线、图片/图表/卡片、文本、标注/强调层。
-- 颜色通过 `base`、`text`、`muted`、`accent`、`positive`、`negative`、`risk` 等 token 引用，不要在每个对象里临时硬编码。
-- 生成后必须检查重叠、裁切、异常换行、标题意外换行、底部溢出、来源说明缺失和主锚点不清。
-
-## 常见错误
-
-- 页面没有主锚点，所有内容都像同级说明。
-- 把视觉稿变成标题加长 bullet，或者把研究材料原文直接塞进文本框。
-- 用很多颜色和边框填满空白，却没有表达语义。
-- 同级卡片尺寸、标题位置、槽位顺序不一致。
-- 数据页只有图表没有结论，或结论离证据太远。
-- 流程线穿过标签，时间线里程碑太多且描述过长。
-- 字号层级过平，标题、标签、正文看起来差不多大。
-- 为了装下文字持续缩字号，而不是删减、拆分或换结构。
-
-## 证据来源
-
-这些规则来自典型ppt案例的主题化提炼。核心跨文稿模式包括：
-
-- 顶部标题先锚定页面，再组织主体内容。
-- 左右文本/视觉分区是最稳定的解释结构之一。
-- 结构化文本页使用重复对齐模块，而不是自由散落文本框。
-- 数据页通常用数字锚点配合图表或表格表达结论。
-- 字体尺度分离标题、标签和正文。
-- 中性底色配有限强调色比多色装饰更可靠。
-- 封面和章节页使用更少文本对象和更强视觉框架。
-- 多个同级对象应规范化为卡片或同构模块。
-- 流程和时间线通过重复节点加克制连接线表达顺序。

skills/lark-slides/references/lark-slides-create-workflows.md

@@ -1,266 +0,0 @@
----
-name: lark-slides
-version: 1.0.0
-description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。"
-metadata:
-  requires:
-    bins: ["lark-cli"]
-  cliHelp: "lark-cli slides --help"
----
-
-# slides (v1)
-
-## Quick Reference
-
-| 用户需求                                | 优先动作 | 关键文档 / 命令 |
-|-------------------------------------|----------|-----------------|
-| 新建 PPT                              | 先确定叙事、页序和视觉策略，再按复杂度选择一步或两步创建 | `design-rules.md`、`slides +create` |
-| 已有 PPT 大幅改写                         | 多页整页重建用 `+replace-pages`，单页局部编辑用 `+replace-slide` | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
-| 编辑单个标题、文本块、图片或局部元素                  | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
-| 读取或分析已有 PPT                         | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
-| 获取幻灯片页面截图                           | 用 `slide_id` 或页号指定页面 | `slides +screenshot`、`lark-slides-screenshot.md` |
-| 上传或使用图片                             | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 |
-| 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表  | 使用原生 `<chart>` 元素 | `xml-schema-quick-ref.md` |
-| 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `<whiteboard>` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) |
-| 使用语义图标 | 先检索 IconPark，再写 `<icon iconType="...">` | `iconpark_tool.py search → resolve`、`iconpark.md` |
-| 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
-
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
-
-**CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
-
-**CRITICAL — PPT 生成与模板编辑硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。多用生图，辅助搜图，必须要图文并茂。不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。生成背景图时必须在 prompt 中明确要求不要出现任何文字。用户指定 PPT 模板时，用 lark-drive 技能导入成 lark slides，回读理解每页版式后，直接在该 slides 上编辑，可以填改文字和图片、按需增删模板页，必须严格沿用原版式和字体，只改内容不做设计，完成后回读并微调，凝练文字或缩减字号消除文字溢出，调整 shape 顺序或位置避免文字遮挡。**
-
-**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险；XML 语法和文本重叠静态检查优先使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)。**
-
-**CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
-
-**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；已有 Slides 的多页大改优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内批量重建页面，避免 `slides +create` 生成新链接。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
-
-## 身份选择
-
-飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。
-
-- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权：
-
-```bash
-lark-cli auth login --domain slides
-```
-
-- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。
-
-**执行规则**：
-
-1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。
-2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。
-3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。
-
-## 执行前必做
-
-> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。
-
-高频只读：
-
-- [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)
-- [design-rules.md](references/design-rules.md)（新建 / 大幅改写）
-- [validation-checklist.md](references/validation-checklist.md)（创建 / 大幅改写后）
-
-按需再读：
-
-- 创建：[`lark-slides-create.md`](references/lark-slides-create.md)
-- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md)
-- 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)
-- 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
-- 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
-- 图标：[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py)
-- 排障：[`troubleshooting.md`](references/troubleshooting.md)
-- 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml)
-
-## Workflow
-
-> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。
-
-### Design Ideas
-
-不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。
-
-开始写 XML 前，先确定 deck 级视觉策略：
-
-- **主题化配色**：配色必须服务本次主题、行业和受众，不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立，说明配色不够具体。
-- **主次比例**：选择 1 个主色承担约 60-70% 视觉权重，1-2 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。
-- **背景一致性**：先确定全 deck 的背景策略，默认保持同一明暗基调和底色体系；只有分节、转场或强调页才有意改变背景，并必须通过相同主色、纹理、边栏或 motif 让变化看起来属于同一套设计。无论深浅，都要保证正文、图标和线条对比充足。
-- **统一 motif**：选择一个可复用视觉母题贯穿全文，例如粗侧边栏、圆形图标底、半出血图片区、编号节点、卡片左上角色块或大号数字。不要每页换一套装饰语言。
-
-每页至少要有一个视觉元素：图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉。文本框本身不算主视觉。
-
-可优先考虑这些页面形态：
-
-- **双栏结构**：左文右图或左图右文，视觉区域占 35-45% 宽度。
-- **图标行**：图标在色块或圆形底中，右侧是短标题和一句解释。
-- **2x2 / 2x3 网格**：适合能力、模块、风险、行动项，每格内容保持同等层级。
-- **半出血视觉**：图片或抽象形状占据左/右半屏，文字覆盖或贴边排布。
-- **大数字卡片**：关键指标用 60-72pt 数字，下面配 10-14pt 标签。
-- **对比列**：before/after、方案 A/B、问题/解法用左右并列，标题和基线严格对齐。
-- **时间线/流程图**：步骤用节点和箭头表达，流程方向必须一眼可见。
-
-字体和间距建议：
-
-- 标题 36-44pt，关键结论可更大；正文 14-18pt；注释 10-12pt。
-- 正文默认左对齐；只在封面、结尾或大号数字场景中使用居中。
-- 页面边距至少 40px；内容块之间保持 24-40px 间距，并在同一 deck 内保持一致。
-- 卡片内边距要真实留出空间，不要让文字贴边；对齐 shape 和文字时要考虑文本框 padding。
-
-常见错误必须避免：
-
-- 不要所有页面复用同一种标题 + 三 bullets 版式。
-- 不要用低对比文字或低对比图标，例如浅灰字压在浅色背景上。
-- 不要让装饰线穿过文字，或让页脚、来源、编号挤压主体内容。
-- 不要把素材缺失表现为空白图片框；必须用 XML-native 形状、图表、表格或 whiteboard 生成兜底视觉。
-- 不要留下占位文案、示例公司名、示例日期或与用户主题无关的内容。
-
-### 创建方式选择
-
-| 场景 | 推荐方式 |
-|------|----------|
-| 简单 XML（1-3 页、结构简单、几乎无复杂中文和特殊字符） | `slides +create --slides '[...]'` 一步创建 |
-| 复杂 XML（多页、含中文、大段文本、复杂布局、嵌套引号、特殊字符较多） | **两步创建**：先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide create` 逐页添加 |
-| 已有 PPT 继续追加或插入页面 | 使用 `xml_presentation.slide create`，必要时配合 `before_slide_id` |
-
-> [!WARNING]
-> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议使用两步创建法。
-
-> [!IMPORTANT]
-> `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
-
-```text
-Step 1: 需求澄清 & 读取知识
-  - 澄清主题、受众、页数、风格
-  - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 design-rules.md
-
-Step 2: 生成大纲 → 用户确认
-  - 生成结构化大纲供用户确认
-  - 新建 / 大幅改写必须先明确 deck 目标、受众、页序、视觉系统和每页关键消息
-  - 每页确定 `key_message`、`layout_type`、`visual_focus`、`text_density`；素材需求只作为设计意图
-
-Step 3: 按已确认大纲生成 XML → 创建
-  - 逐页生成 XML：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
-  - 缺少真实素材时必须用 XML-native 形状、图表、表格或 whiteboard 生成兜底视觉；不要留空
-  - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
-
-Step 4: 审查 & 交付
-  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
-  - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
-  - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
-```
-
-### jq 命令模板（编辑已有 PPT 时使用）
-
-新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
-
-```bash
-# 追加到末尾
-lark-cli slides xml_presentation.slide create \
-  --as user \
-  --params '{"xml_presentation_id":"YOUR_ID"}' \
-  --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
-  <data>
-    在这里放置 shape、line、table、chart、whiteboard 等元素
-  </data>
-</slide>' '{slide:{content:$content}}')"
-
-# 插到指定页之前：before_slide_id 必须在 --data body 里，与 slide 同级
-# ⚠️ 不要把 before_slide_id 写进 --params —— CLI 会当未知 query 参数静默下发，服务端忽略，新页跑到末尾
-lark-cli slides xml_presentation.slide create \
-  --as user \
-  --params '{"xml_presentation_id":"YOUR_ID"}' \
-  --data "$(jq -n --arg content '<slide ...>...</slide>' --arg before 'TARGET_SLIDE_ID' \
-    '{slide:{content:$content}, before_slide_id:$before}')"
-```
-
-> 渐变色必须使用 `rgba()` 格式并带百分比停靠点，如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端回退为白色。
-
-### 大纲模板
-
-生成大纲时使用以下格式，交给用户确认：
-
-```text
-[PPT 标题] — [定位描述]，面向 [目标受众]
-
-页面结构（N 页）：
-1. 封面页：[标题文案]
-2. [页面主题]：[要点1]、[要点2]、[要点3]
-3. [页面主题]：[要点描述]
-...
-N. 结尾页：[结尾文案]
-
-风格：[配色方案]，[排版风格]
-```
-
-## 核心概念
-
-### URL 格式与 Token
-
-| URL 格式 | 示例 | Token 类型 | 处理方式 |
-|----------|------|-----------|----------|
-| `/slides/` | `https://example.larkoffice.com/slides/xxxxxxxxxxxxx` | `xml_presentation_id` | URL 路径中的 token 直接作为 `xml_presentation_id` 使用 |
-| `/wiki/` | `https://example.larkoffice.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
-
-> `+replace-slide` 和 `+media-upload` shortcut 会自动解析以上两种 URL；直接调用原生 API 时仍需手动解析 wiki 链接。
-
-### Wiki 链接特殊处理（关键！）
-
-知识库链接（`/wiki/TOKEN`）不能直接当 `xml_presentation_id`。直接调用原生 API 前，先查询 wiki 节点，确认 `node.obj_type == "slides"`，再用 `node.obj_token` 作为真实 presentation ID。
-
-```bash
-lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}'
-```
-
-Shortcut `+replace-slide` 和 `+media-upload` 会自动解析 `/wiki/` URL；手动调用 `xml_presentations.*` / `xml_presentation.slide.*` 时才需要自己做这一步。
-
-### 资源关系
-
-```text
-Wiki Space (知识空间)
-└── Wiki Node (知识库节点, obj_type: slides)
-    └── obj_token → xml_presentation_id
-
-Slides (演示文稿)
-├── xml_presentation_id (演示文稿唯一标识)
-├── revision_id (版本号)
-└── Slide (幻灯片页面)
-    └── slide_id (页面唯一标识)
-```
-
-## Shortcuts 与 API
-
-Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`）。有 Shortcut 的操作优先使用。
-
-| Shortcut | 说明 |
-|----------|------|
-| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传） |
-| [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
-| [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
-| [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面：先创建新页到旧页前，再删除旧页；适合已有 Slides 的多页大改，不新建链接 |
-
-没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
-
-```bash
-lark-cli schema slides.<resource>.<method>   # 调用 API 前必须先查看参数结构
-lark-cli slides <resource> <method> [flags] # 调用 API
-```
-
-> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
-
-## 核心规则
-
-1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，先确定 deck 目标、受众、页序、视觉系统和每页关键消息；不要从用户提示直接跳到 XML
-2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
-3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
-4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
-5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
-6. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
-7. **编辑已有页面优先原链接更新**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；已有 Slides 的多页整页重建用 `+replace-pages`，不要用 `slides +create` 新建整份 PPT；只有没有 shortcut 覆盖的特殊单页整页操作才手动 `slide.create` + `slide.delete`
-8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
-
-> **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。

skills/lark-slides/references/lark-slides-pptx-template-workflows.md

@@ -1,77 +0,0 @@
-# PPT Template Rewrite Principles
-
-本页只约束“用户指定 PPT 模板、底稿、已有 PPTX/PDF/Slides，并要求基于它二次创作”的场景。核心原则：模板不是风格参考，而是必须沿用的编辑底稿。
-
-## Import First
-
-用户指定 PPT 模板时，先使用 `lark-drive` 技能把模板导入成 Lark Slides。后续写入目标是导入后的 Slides，不是新建一个脱离模板的 deck，也不是先在本地重画 PPTX 再导入。
-
-导入后必须回读 Slides 内容，理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。回读结果是模板二创的事实来源。
-
-## Read Before Editing
-
-编辑任何 PPT 页面前，必须先阅读该页面。
-
-如果当前上下文中没有该页内容，必须重新读取页面；这里的“当前上下文”不包含 System Prompt。不能只凭记忆、文件名、缩略图印象或模板整体风格判断来编辑具体页面。
-
-阅读页面时至少判断：
-
-- 该页原本承担的角色，例如封面、章节页、目录、流程、对比、数据、总结。
-- 该页的主要版式结构，例如图文关系、箭头、时间线、节点、表格、图表、左右对照、背景图或产品图。
-- 哪些文本框、shape 标签、表格单元格或图表标签承载内容。
-- 原页面的字体、字号、颜色、对齐、层级和留白关系。
-
-## Edit The Imported Slides Directly
-
-理解页面后，直接在导入后的 Slides 上编辑。允许的操作包括：
-
-- 填写、替换、凝练或删除文字。
-- 替换或补充图片。
-- 更新图表、表格、数字标签或节点标签里的内容。
-- 按需复制、删除或重排模板页。
-- 在源页面没有合适承载位置时，做局部、小范围新增元素。
-
-新增元素只能补足内容缺口，不能成为新的主版式。页面主体仍应由模板原有版式承载。
-
-## Preserve Design
-
-模板二创必须严格沿用原版式和字体，只改内容，不做设计。
-
-默认保留：
-
-- 页面布局、视觉层级、留白和对齐关系。
-- 原字体、字号体系、颜色、文本框位置和 shape 顺序。
-- 背景图、图片、logo、图表、表格、装饰形状、线条、图标和页面结构。
-- 模板中不同页型之间的差异。
-
-不要把模板页改造成统一的通用卡片、白板、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。
-
-## Content Only
-
-内容必须优先进入原页面已有的文本框、shape 标签、节点、表格单元格、图表标签或注释容器。
-
-如果原容器空间不足，优先：
-
-- 凝练文字。
-- 降低字号但保持原字体体系。
-- 拆分到页面已有的邻近容器。
-- 使用模板已有的注释、标签或补充说明区域。
-- 复制同页或同模板中的原生容器样式做局部补充。
-
-不要为了容纳长文案而重画页面主体结构。不要用新增大卡片遮住原图表、箭头、图片、背景或关键 shape。
-
-## Readback And Tune
-
-完成编辑后必须回读结果，并逐页微调。
-
-回读时重点检查：
-
-- 文字是否溢出、截断、压线或超出容器。
-- 文本是否遮挡图片、图表、shape、箭头、节点或其他文字。
-- shape 顺序是否导致内容被覆盖或遮住。
-- 新内容是否仍然落在模板原有版式中，而不是覆盖模板结构。
-- 字体、字号、颜色、对齐和层级是否仍贴近原页。
-
-发现文字溢出时，优先凝练文字或缩减字号。发现遮挡时，调整 shape 顺序、局部位置或复用原有空白区域解决。只有在这些方法都不能满足内容表达时，才做局部新增或删除。
-
-模板二创的完成标准不是“生成了一套看起来统一的新 PPT”，而是“原模板的版式、字体和视觉结构仍清晰存在，内容已经被准确替换，并且回读后没有溢出和遮挡”。

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

@@ -237,4 +237,4 @@ lark-cli slides +replace-slide --as user \
 - [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 读原页拿 `block_id` / `revision_id`
 - [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
 - [+media-upload](lark-slides-media-upload.md) — 上传图片拿 `file_token`
-- [lark-slides-edit-workflows.md](lark-slides-block-replace-workflows) — 读-改-写闭环 + 决策树
+- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环 + 决策树

skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md

@@ -67,7 +67,7 @@ lark-cli slides xml_presentation.slide create --as user --params '<json_params>'
 </slide>
 ```
 
-详细格式请参考 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
+详细格式请参考 [xml-format-guide.md](xml-format-guide.md) 和 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
 
 ## 使用示例
 
@@ -216,4 +216,5 @@ done
 - [slides +create](lark-slides-create.md) - 创建空白 PPT
 - [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
 - [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
-- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - XML 格式和 Schema 唯一 Markdown 入口
+- [xml-format-guide.md](xml-format-guide.md) - XML 格式详细规范
+- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - Schema 快速参考

skills/lark-slides/references/lark-slides-xml-presentation-slide-get.md

@@ -107,4 +107,4 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 - [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐）
 - [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
 - [xml_presentations get](lark-slides-xml-presentations-get.md) — 读整个 PPT
-- [lark-slides-edit-workflows.md](lark-slides-block-replace-workflows) — 读-改-写闭环
+- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环

skills/lark-slides/references/lark-slides-xml-presentation-slide-replace.md

@@ -184,4 +184,4 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 - [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐，自动注入 id）
 - [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 读原页拿 block short ID
 - [slides +media-upload](lark-slides-media-upload.md) — 上传图片拿 file_token
-- [lark-slides-edit-workflows.md](lark-slides-block-replace-workflows) — 读-改-写闭环 + 决策树
+- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环 + 决策树

skills/lark-slides/references/planning-layer.md

@@ -0,0 +1,216 @@
+# Planning Layer
+
+新建演示文稿或大幅改写页面时，必须先写 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。这个文件是 deck 的设计中间层，用来把叙事、页面角色、布局、视觉重点和文字密度固定下来，避免从用户提示直接跳到 XML。
+
+小型已有页编辑可豁免，例如只替换一个标题、改一个数字、插入一个块、上传并插入一张图。只要任务会重排多页、生成新 deck、替换整页结构，仍然需要规划层。
+
+## Required Flow
+
+1. 理解用户需求，必要时澄清主题、受众、页数、风格。
+2. 选择唯一 plan 目录：`.lark-slides/plan/<deck-or-task-id>/`。
+3. 先创建目录：`mkdir -p .lark-slides/plan/<deck-or-task-id>`。
+4. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
+5. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
+6. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。
+7. 创建 PPT 后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
+
+## Plan Path
+
+Use a separate plan directory per deck or task so multiple presentations in the same workspace cannot overwrite each other.
+
+Recommended IDs:
+
+- New deck before creation: title slug plus date/time, such as `q3-review-20260507-1805`.
+- Existing PPT rewrite: the `xml_presentation_id`.
+- Ambiguous or untitled task: short task slug plus date/time.
+
+Rules:
+
+- Do not reuse `.lark-slides/plan/slide_plan.json` as a shared path.
+- Create the directory before writing the file.
+- Reuse the same plan path for XML generation and post-create verification for that deck.
+
+## Artifact Lifecycle
+
+`.lark-slides/` is local agent state. It supports recovery, iteration, and later edits, but it should not be treated as source code or committed by default.
+
+Keep:
+
+- `.lark-slides/plan/<deck-or-task-id>/slide_plan.json` after successful creation or major rewrite. The plan is the editable design state for the deck.
+- A small manifest when useful for follow-up work, such as `xml_presentation_id`, slide IDs, `revision_id`, plan path, and verification status.
+
+Clean or avoid keeping:
+
+- Transient XML payloads after successful creation and verification. Prefer `/tmp` for throwaway XML, or delete generated XML files after success.
+- Stale XML drafts that no longer match the current presentation state.
+
+Exception:
+
+- If creation fails or partially succeeds, keep the relevant XML/debug payloads until recovery is complete. Record `xml_presentation_id` first, then fetch current state before retrying.
+
+## JSON Shape
+
+```json
+{
+  "presentation_goal": "Explain the proposal and secure approval for the next phase.",
+  "audience": "Product and engineering leaders who know the domain but need a concise decision narrative.",
+  "theme_style": "Clean business style, light background, restrained blue accent, strong visual hierarchy.",
+  "visual_system": {
+    "background_strategy": "Content pages use one light base; cover and closing may use a related dark treatment with the same accent system.",
+    "motif": "A reusable left accent bar and consistent card/header treatments.",
+    "color_roles": {
+      "primary": "Used for the dominant structural motif and about 60-70% of visual weight.",
+      "secondary": "Used for grouped regions, comparison panels, or supporting categories.",
+      "accent": "Used only for key numbers, conclusions, or focus markers."
+    }
+  },
+  "typography_constraints": {
+    "title_max_lines": 2,
+    "body_max_lines_per_box": 2,
+    "footer_max_lines": 1,
+    "long_text_handling": "Shorten, split into multiple boxes, or move detail to speaker notes instead of shrinking into a tight box."
+  },
+  "verification_plan": {
+    "check_background_consistency": true,
+    "check_text_fit": true,
+    "check_visual_focus": true,
+    "check_asset_rendering": true
+  },
+  "slides": [
+    {
+      "page": 1,
+      "title": "Proposal Title",
+      "key_message": "The initiative is ready for a focused pilot.",
+      "layout_type": "title-cover",
+      "visual_focus": "Large title area with one concise supporting statement.",
+      "asset_need": {
+        "asset_type": "logo",
+        "purpose": "Signal product or team identity on the opening page.",
+        "suggested_query": "product logo",
+        "fallback_if_missing": "Use a small text badge and abstract shape motif instead of a real logo."
+      },
+      "text_density": "low",
+      "speaker_intent": "Frame the decision and establish the deck's point of view."
+    }
+  ]
+}
+```
+
+## Required Fields
+
+Top-level fields:
+
+- `presentation_goal`: what the whole deck is trying to achieve.
+- `audience`: target readers or listeners and their assumed background.
+- `theme_style`: visual tone, palette direction, and professional style.
+- `visual_system`: deck-level visual rules that must stay stable across pages, including background strategy, recurring motif, and color roles.
+- `typography_constraints`: deck-level limits for line count, text box density, and how to handle long text before XML generation.
+- `verification_plan`: explicit checks to perform after creation or major edits; include background consistency, text fit, visual focus, and asset rendering when relevant.
+- `slides`: ordered page plans.
+
+Each slide must include:
+
+- `page`: 1-based page number.
+- `title`: slide title.
+- `key_message`: the one idea this page must land.
+- `layout_type`: planned page structure.
+- `visual_focus`: dominant visual object or region.
+- `asset_need`: planning-only structured asset metadata; no search, download, or upload required. Follow `asset-planning.md`.
+- `text_density`: `low`, `medium`, or `high`.
+- `speaker_intent`: why the speaker needs this page and how it advances the story.
+
+## Layout Vocabulary
+
+Use one of these `layout_type` values unless the user explicitly needs a custom structure:
+
+- `title-cover`
+- `section-divider`
+- `two-column`
+- `image-left-text-right`
+- `image-right-text-left`
+- `big-number`
+- `timeline`
+- `comparison`
+- `architecture-diagram`
+- `process-flow`
+- `quote-highlight`
+- `conclusion`
+
+The value must affect XML geometry, not just appear as a label. For example, `timeline` should create a horizontal or vertical sequence, `comparison` should create distinct side-by-side regions, and `big-number` should reserve dominant space for a large metric.
+
+## Text Density Rules
+
+- `low`: title plus 1 short statement, or 1-3 very short labels.
+- `medium`: title plus 2-4 concise bullets or labeled regions.
+- `high`: allowed only when the user needs detail; use tables, columns, or grouped regions instead of a long bullet list.
+
+Do not let all pages become title + bullet slides. For decks of 4 or more pages, aim for at least 4 different `layout_type` values when the content allows it.
+
+Text density must be realistic for the planned geometry. If a page needs long titles, bilingual labels, paper figure captions, legal disclaimers, or dense technical wording, record how the text will be shortened, split, or moved to speaker notes. Do not rely on small font sizes or tight boxes to make text fit.
+
+## Visual System Planning
+
+Before generating XML, define a visual system that can survive the whole deck:
+
+- `background_strategy`: specify the default background for normal content pages, and which page roles may intentionally differ. Do not let pages drift through near-identical but inconsistent background colors.
+- `motif`: choose one or two reusable structural devices, such as a side bar, header rail, numbered node, card treatment, diagram lane, or section band. The motif should appear consistently enough that pages feel related.
+- `color_roles`: assign primary, secondary, and accent roles. The same color must not mean unrelated things across pages.
+- `cover_content_relationship`: if the cover uses a different dark or image-led treatment, state how it connects to content pages through shared colors, motifs, or geometry.
+- `closing_relationship`: if the closing page mirrors the cover, state that explicitly so it looks intentional rather than like a new theme.
+
+These are planning constraints, not decoration notes. They must affect coordinates, background fills, shape styles, and text placement in generated XML.
+
+## Iterative Deck State
+
+When continuing an existing deck, update the same plan path rather than creating a new disconnected plan. Keep the plan aligned with what has actually been created.
+
+Recommended optional fields for long-running work:
+
+- `deck_status`: current slide count, target slide count if known, and last verified revision or timestamp.
+- `created_slides`: page number, slide id when known, and the page role.
+- `assets_used`: source, local path when applicable, uploaded token when known, and which page uses it.
+- `open_issues`: known layout, text fit, asset, or consistency risks that still need correction.
+
+Do not hard-code a page number just because a previous deck used that pattern. Plan by page role and evidence need, such as "method overview pages should use a figure when the source has a readable figure" instead of binding screenshots, charts, or diagrams to a fixed page index. The plan should describe decision rules, not a rigid template sequence.
+
+## Asset Planning
+
+`asset_need` is metadata. It can describe a desired figure, diagram, chart, icon, logo, screenshot, or fallback shape-based visual, but it must not require web search, local download, or media upload.
+
+Use an object for one planned asset, an array for multiple real needs, or `asset_type: "none"` when no asset is useful. Each planned asset must include:
+
+- `asset_type`: one of `paper_figure`, `architecture_diagram`, `icon`, `logo`, `chart`, `infographic`, `screenshot`, `flow_diagram`, or `none`.
+- `purpose`: why this asset helps the page's key message.
+- `suggested_query`: short future lookup hint only; do not execute it unless separately requested.
+- `fallback_if_missing`: concrete XML-native visual plan using shapes, labels, tables, whiteboard diagrams, or placeholder panels.
+
+For detailed rules and examples, read `asset-planning.md`.
+
+Good examples:
+
+- `{"asset_type":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Draw a component diagram with grouped boxes, connector arrows, and short labels."}`
+- `{"asset_type":"logo","purpose":"Identify the customer context.","suggested_query":"customer logo","fallback_if_missing":"Use a text label in a small badge."}`
+- `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Draw a simple trend line chart with axis labels and data points."}`
+
+## XML Generation Contract
+
+Before writing each slide XML, map the plan fields to concrete decisions:
+
+- `key_message` determines the headline, dominant claim, or main takeaway.
+- `layout_type` determines the coordinate structure and element types. Use `visual-planning.md` for concrete layout rules.
+- `visual_focus` determines the largest visual region or emphasized object.
+- `text_density` caps visible text volume.
+- `asset_need` informs placeholder diagrams, icons, charts, screenshots, or shape-based fallback visuals only. Missing real assets must use `fallback_if_missing`, not blank regions.
+
+After creating the PPT, fetch the presentation and verify:
+
+- Page count matches the plan.
+- Every page has the planned title and key message represented.
+- At least several pages have visibly different XML layout structures.
+- Planned `visual_focus` appears as a dominant visual region or object.
+- Asset planning is proportional to the deck topic and length: technical, research, product, and analytical decks should include meaningful planned visuals where they clarify the story, and each planned asset has a visible fallback if no real asset was used.
+- `text_density` is reflected in the amount of visible text.
+- Pages are not crowded, and any planned `timeline`, `comparison`, or `architecture-diagram` page uses its matching visual structure.
+- The actual backgrounds match `visual_system.background_strategy`; any dark, image-led, or emphasis page has an intentional relationship to the rest of the deck.
+- Text boxes respect `typography_constraints`; long labels, captions, footer text, and conclusion bars are not squeezed into boxes that are too short for the intended line count.
+- If real assets are used, the final XML contains renderable asset tokens or supported local placeholders for creation, not http URLs, stale local paths, or blank image boxes.

skills/lark-slides/references/slides_template_workflow.md

@@ -1,64 +0,0 @@
-# Slides Template Workflow
-
-当用户提到"模板""套用模板""参考某种主题/风格/版式"，或需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），使用本文。
-
-## 核心规则
-
-- 必须先用 `scripts/template_tool.py search` 做模板检索，默认给出 2-3 个最匹配模板候选供用户选择。
-- 锁定模板后用 `summarize` 获取主题和布局摘要。
-- 只有需要具体布局骨架时才用 `extract` 裁切目标页型 XML。
-- 不要直接读取完整模板 XML。
-- 不要照搬模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。
-
-`scripts/template_tool.py` 需要 Python 3。`references/template-index.json` 是脚本缓存/轻量路由索引，不是默认给 agent 阅读的文档；`assets/templates/*.xml` 是机器资源，只应通过脚本摘要或裁切，不要全文读取。
-
-模板细则见 [template-catalog.md](template-catalog.md)。主流程只记住：先 `search`，锁定后 `summarize`，需要骨架时才 `extract`。
-
-```bash
-python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3
-python3 skills/lark-slides/scripts/template_tool.py summarize --template <template-id> --label <封面|目录|分节|内容|结尾>
-python3 skills/lark-slides/scripts/template_tool.py extract --template <template-id> --label <页型> --out /tmp/template-slice.xml
-```
-
-## 生成流程
-
-```text
-Step 1: 需求澄清 & 读取知识
-  - 澄清主题、受众、页数、风格
-  - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 design-rules.md
-  - 按本文检索模板并给出候选
-
-Step 2: 生成大纲 -> 用户确认
-  - 生成结构化大纲供用户确认；如使用模板，标明基于哪个模板改写
-  - 新建 / 大幅改写必须先明确 deck 目标、受众、页序、视觉系统和每页关键消息
-  - 模板只提供风格和局部布局骨架，不要照搬无关占位内容
-
-Step 3: 按已确认大纲生成 XML -> 创建
-  - 逐页生成 XML：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
-  - 缺少真实素材时必须用 `fallback_if_missing` 生成 XML-native 兜底视觉；不要留空
-  - 创建方式按 SKILL.md 的"创建方式选择"判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
-
-Step 4: 审查 & 交付
-  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
-  - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
-  - 没问题 -> 交付：告知用户演示文稿 ID 和访问方式
-```
-
-## 大纲格式
-
-生成大纲时使用以下格式，交给用户确认：
-
-```text
-[PPT 标题] - [定位描述]，面向 [目标受众]
-
-模板：[未使用模板 / <category>/<template>.xml（推荐原因）]
-
-页面结构（N 页）：
-1. 封面页：[标题文案]
-2. [页面主题]：[要点1]、[要点2]、[要点3]
-3. [页面主题]：[要点描述]
-...
-N. 结尾页：[结尾文案]
-
-风格：[配色方案]，[排版风格]
-```

skills/lark-slides/references/validation-checklist.md

@@ -1,6 +1,6 @@
 # Validation Checklist
 
-创建或大幅改写演示文稿后，必须做一次显式验证，如果只创建空白ppt则不用验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
+创建或大幅改写演示文稿后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
 
 小型已有页编辑也要做对应范围的验证：至少读取被改页面或全文 XML，确认目标元素已更新且未破坏周边结构。
 
@@ -46,7 +46,7 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 
 ## Page Count And Structure
 
-- 实际页数必须等于用户要求或已确认大纲的页数。
+- 实际页数必须等于用户要求或 `slide_plan.json` 的页数。
 - 如果创建过程部分失败，先记录已创建的 `xml_presentation_id`，再回读确认哪些页已写入。
 - 每页都应包含 `<data>`，且 `<data>` 内至少有一个非背景主体元素。
 - 封面、章节页、总结页可以文字较少，但不能只有空背景。
@@ -54,7 +54,7 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 
 ## Expected Elements
 
-按已确认大纲和用户要求逐页核对：
+按 `slide_plan.json` 和用户要求逐页核对：
 
 - 标题或主结论存在，并能对应 `key_message`。
 - `layout_type` 对应的主要结构已生成。

skills/lark-slides/references/visual-planning.md

@@ -0,0 +1,254 @@
+# Visual Planning
+
+新建演示文稿或大幅改写页面时，在 `slide_plan.json` 完成后、生成 XML 前读取本文件。目标是让 `layout_type`、`visual_focus`、`text_density` 变成实际页面几何，而不是只写在 plan 里。
+
+默认画布按 `960 x 540` 规划。已有页面回读 XML 可以影响具体坐标，但不能覆盖这些原则：页面要有主视觉区域、文本要受密度约束、不同 `layout_type` 必须产生明显不同的坐标结构。
+
+## Core Rules
+
+- `layout_type` must change geometry: element positions, region sizes, alignment, and visual rhythm must differ across page types.
+- `visual_focus` determines the largest or highest-contrast region. It can be an image, diagram, metric, quote, table, or shape-based placeholder.
+- `text_density` caps visible text:
+  - `low`: title plus one short statement, or 1-3 labels.
+  - `medium`: title plus 2-4 concise bullets or labeled regions.
+  - `high`: use a table, columns, grouped labels, or annotations. Do not use one long bullet box.
+- Do not create a deck where every content page is title plus bullets. For 4 or more pages, use at least 4 different layout structures when the content allows.
+- Keep generous margins. Use `60-80` px outer margins on standard content pages unless a full-bleed image or cover treatment is intentional.
+- Reserve vertical space for titles. A typical content title area is `y=36..90`; main content should usually start at `y>=110`.
+- Avoid crowding the bottom edge. Keep non-background content above `y=500` unless it is a footer.
+- Prefer fewer, larger objects over many small text boxes.
+- Keep backgrounds consistent with the deck's `visual_system.background_strategy`. Normal content pages should use the same base background unless there is a clear page-role reason to change.
+- Treat text fit as a layout constraint, not a cleanup step. If a text box is too small for the intended line count, shorten the text, split it, or allocate more space before creating XML.
+
+## Background And Motif Consistency
+
+Decks can vary page backgrounds, but variation must be intentional and legible:
+
+- Pick one default background for ordinary content pages and reuse it exactly. Avoid near-identical drift such as several slightly different off-white values unless it encodes a clear section change.
+- Cover, section divider, emphasis, and conclusion pages may use a dark, image-led, or high-contrast background. They must still share the deck's primary color, motif, edge treatment, typography, or geometry.
+- If a cover uses a split composition, make the split visible in the background or layout. For example, reserve a darker text region and a related but distinct visual region instead of placing all elements on one flat field.
+- Reuse a small number of visual devices: side bar, card radius, node style, line weight, icon container, or footer treatment. Do not introduce a new decorative language on each page.
+- Insert background and motif shapes before content elements so they do not cover text, images, or diagrams.
+
+## Text Fit Guardrails
+
+Use these as conservative minimums on a 960 x 540 canvas. Increase height when using bold text, Chinese text, mixed Chinese/English, or line spacing above default.
+
+| Text use | Typical font size | Minimum height |
+|----------|-------------------|----------------|
+| Caption, 1 line | 10-12 | 18 |
+| Caption, 2 lines | 10-12 | 30 |
+| Body, 1 line | 13-16 | 24 |
+| Body, 2 lines | 13-16 | 40 |
+| Body, 2 lines, bold | 15-18 | 48 |
+| Headline, 1 line | 24-32 | 42 |
+| Title, 2 lines | 34-44 | 110 |
+
+Additional rules:
+
+- Do not put long Chinese sentences or long English phrases into `height=18` or `height=22` boxes. Those heights are for short labels only.
+- Footer/source text should usually be one short line. If it needs more, make it a real caption block above the footer area.
+- Bottom conclusion bars should be at least `40` px tall for one emphasized line and at least `54` px tall for two lines.
+- Diagram labels should be short enough to fit the shape. Prefer two short lines over one cramped long line.
+- When a text block has more than one `<p>`, size the box for multiple lines explicitly. Do not assume the renderer will auto-expand.
+- If a line contains mixed Chinese and English, budget more width than either language alone; mixed text wraps less predictably.
+
+## Layout Types
+
+### `title-cover`
+
+Purpose: introduce the deck's point of view.
+
+Geometry:
+- Use one dominant title block, usually `x=70..120`, `y=150..250`, `width=700..820`.
+- Add one subtitle or context line, not a bullet list.
+- Optional visual focus can be a full-bleed background, large side image, accent band, or abstract shape motif.
+- If the cover has a right-side diagram, screenshot, or motif cluster, use a split layout: keep the title/subtitle region within the left or central text region, and reserve a separate visual region so labels and connectors do not cross the title.
+- For split covers, make the background reinforce the composition, such as a darker text side and a related visual panel. Avoid one flat field where title and diagram compete for attention.
+- Keep source metadata to one short line where possible. If it wraps, shorten author lists or move details to notes.
+- The main title should be controlled, normally one or two lines. Do not let it occupy both the text region and the visual region.
+
+Text:
+- `low` only unless the user explicitly asks for detail.
+
+### `section-divider`
+
+Purpose: reset rhythm and mark a new chapter.
+
+Geometry:
+- Use a large section number, chapter label, or single centered claim.
+- Keep the page sparse. A divider is not a content page.
+- Visual focus can be one oversized number, a vertical accent bar, or a full-width band.
+
+Text:
+- Title plus one phrase. No bullets.
+
+### `two-column`
+
+Purpose: compare two related ideas or pair explanation with evidence.
+
+Geometry:
+- Split main region into two balanced columns, for example left `x=60,width=400`, right `x=500,width=400`.
+- Each column needs its own heading or visual anchor.
+- Do not place one full-width bullet box under a normal title; that is not a two-column layout.
+
+Text:
+- `medium`: 2-3 short items per column.
+- `high`: use grouped rows or mini table structure inside columns.
+
+### `image-left-text-right`
+
+Purpose: let a visual establish context, with text explaining implication.
+
+Geometry:
+- Left visual region should occupy roughly `35-45%` of slide width, often full height or tall crop.
+- Right text region starts around `x=420` and should have a strong headline plus short support.
+- If no real image is available, create a shape-based placeholder visual that matches `asset_need`.
+- For dense screenshots, paper figures, or product captures with small labels, allocate a larger visual region when possible: often `50-65%` of slide width or at least `320` px height.
+- Place screenshots in a deliberate frame or panel, and leave enough margin so axes, captions, and edge labels are not cropped by the slide boundary.
+
+Text:
+- Keep right-side text short. Avoid more than 4 bullets.
+- For screenshot explanation pages, prefer 2-3 interpretation cards or callouts instead of a paragraph block.
+
+### `image-right-text-left`
+
+Purpose: lead with a message, then reinforce it with a visual.
+
+Geometry:
+- Left text region starts around `x=60..90`, width `400..460`.
+- Right visual region occupies roughly `35-45%` of slide width.
+- Align the image or placeholder with the main text block, not only with the title.
+- For dense screenshots, paper figures, or product captures with small labels, increase the visual region and reduce text. A readable image is more valuable than a fully populated text column.
+
+Text:
+- Use one main claim and 2-3 supporting points.
+- Keep callouts parallel and short. If a callout needs more than two lines, split it into a separate note or a new slide.
+
+### `big-number`
+
+Purpose: make one metric or fact memorable.
+
+Geometry:
+- Reserve the largest object for the metric: font size often `64-110`, region at least `300 x 120`.
+- Pair the number with one explanation and optional 2-3 small supporting labels.
+- Do not bury the number in a bullet list or small card.
+
+Text:
+- `low` or `medium`. If detail is needed, add small annotations around the metric.
+- Supporting labels must not compete with the number. Use compact labels, legends, or mini-cards rather than long explanatory bars.
+
+### `timeline`
+
+Purpose: show sequence, roadmap, history, or phases.
+
+Geometry:
+- Create a horizontal or vertical spine with 3-6 milestones.
+- Each milestone should have a dot/card/date label connected by a line or arrow.
+- Title is separate from the sequence. The sequence is the visual focus.
+
+Text:
+- Each milestone gets a short label and optional one-line explanation.
+- Do not use paragraph-length milestone descriptions.
+
+### `comparison`
+
+Purpose: make a choice, before/after, old/new, or option tradeoff clear.
+
+Geometry:
+- Use two or three distinct panels, columns, or a table-like structure.
+- Headings must be visually aligned so differences are easy to scan.
+- Use color, border, icon, or label treatment to highlight the preferred option or key difference.
+
+Text:
+- Use parallel wording across columns.
+- Avoid uneven long bullet lists that destroy comparability.
+
+### `architecture-diagram`
+
+Purpose: explain components, dependencies, or system flow.
+
+Implementation: prefer `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` only as fallback.
+
+Geometry:
+- Main visual area should be a diagram, not prose.
+- Use grouped boxes, lanes, arrows or lines, and short labels.
+- Keep diagram labels concise. Put explanation in notes or a small side caption if needed.
+
+Text:
+- Prefer labels of 1-5 words.
+- Use no more than one short explanatory text block.
+- If a node label needs two lines, size the node and the text box for two lines. Do not let labels overlap connectors.
+
+### `process-flow`
+
+Purpose: show operational steps, workflow, or cause-effect path.
+
+Implementation: prefer `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` only as fallback.
+
+Geometry:
+- Use numbered steps connected by arrows or lines.
+- 3-5 steps is ideal for one slide. If there are more, group them into phases.
+- The flow direction must be visually obvious.
+
+Text:
+- Each step gets a verb-led label and one short descriptor at most.
+- Step labels should be parallel in length and grammar. If one step needs a long explanation, move the explanation to a side note or speaker notes.
+
+### `quote-highlight`
+
+Purpose: emphasize a customer voice, principle, thesis, or decision statement.
+
+Geometry:
+- Quote or claim is the dominant text object.
+- Use large type, generous whitespace, and optional attribution or context badge.
+- Do not combine a quote-highlight page with a normal bullet section.
+
+Text:
+- One quote or statement, plus optional attribution. No bullets.
+
+### `conclusion`
+
+Purpose: close with decision, recommendation, or next action.
+
+Geometry:
+- Use one dominant closing statement or call to action.
+- Add up to 3 next-step cards, checklist items, or owner/date labels.
+- Visual focus should be the recommendation or action, not decorative filler.
+
+Text:
+- Keep the final page easy to remember. Avoid recap overload.
+- Conclusion pages may mirror the cover background, but must clearly reuse the deck's motif or color roles so the ending feels intentional.
+
+## Screenshot And Paper Figure Pages
+
+When a page uses a real screenshot, chart, paper figure, or product capture:
+
+- Choose screenshot placement based on page role, not a fixed slide number. Method overview, evidence, comparison, and failure-analysis pages are common candidates; title, agenda, and conclusion pages usually are not.
+- Use the real asset only when it is readable at slide size. If the figure is too dense, crop to the relevant region, create a zoomed detail, or redraw the core message with native shapes.
+- A screenshot should normally be the visual focus. Do not shrink it into a decorative thumbnail while surrounding it with dense text.
+- Pair the image with a small number of interpretive annotations that tell the audience what to notice.
+- Always include a short source caption when using external or paper-derived visuals.
+- Verify the final XML contains a supported image token or creation-time local placeholder, not an unsupported external URL.
+
+## Plan To XML Checklist
+
+Before creating XML for each page, answer these checks:
+
+1. Which region is the visual focus, and is it the largest or most prominent object?
+2. Does the XML geometry match the `layout_type` description above?
+3. Does `text_density` limit the number of paragraphs, bullets, labels, and text boxes?
+4. Would this page still be recognizable if the `layout_type` label were removed from the plan?
+5. Across the deck, do multiple pages use genuinely different structures?
+6. Does the background follow the planned deck strategy, and are any deviations intentional?
+7. Are all text boxes large enough for their intended font size and line count?
+8. If the page uses a screenshot or paper figure, is it large enough to read and accompanied by concise interpretation?
+
+After fetching the created presentation, verify:
+
+- Use `timeline`, `comparison`, and `architecture-diagram` only when the content calls for them; do not force irrelevant page types.
+- Any planned `timeline`, `comparison`, or `architecture-diagram` page uses the matching sequence, side-by-side comparison, or component-and-connection structure.
+- Pages are not crowded and do not rely on long bullet boxes.
+- Main claim, supporting detail, and visual focus have clear hierarchy.
+- Static XML inspection should include text-fit risk: very short text boxes containing long text, multi-paragraph boxes with insufficient height, footer text that may wrap, and labels placed directly over connectors.
+- Background and motif consistency should be checked across pages, not only within one slide.

skills/lark-slides/references/xml-format-guide.md

@@ -0,0 +1,369 @@
+# XML 格式指南
+
+本文档基于 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 整理，说明飞书 Slides XML Schema（SML 2.0）的核心结构和常用写法。
+
+## 基本结构
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+  <title>演示文稿标题</title>
+  <slide>
+    <style>
+      <fill>
+        <fillColor color="rgb(245, 245, 245)"/>
+      </fill>
+    </style>
+    <data>
+      <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+        <content textType="title">
+          <p>主标题</p>
+        </content>
+      </shape>
+    </data>
+    <note>
+      <content textType="body">
+        <p>这是演讲者备注。</p>
+      </content>
+    </note>
+  </slide>
+</presentation>
+```
+
+## 根元素
+
+### `<presentation>`
+
+协议标准写法应带命名空间 `http://www.larkoffice.com/sml/2.0`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证。
+
+**属性：**
+
+| 属性 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `width` | positiveInteger | 是 | 演示文稿宽度，如 `960` |
+| `height` | positiveInteger | 是 | 演示文稿高度，如 `540` |
+| `id` | string | 否 | 演示文稿标识 |
+
+**子元素：**
+
+| 元素 | 必需 | 说明 |
+|------|------|------|
+| `<title>` | 否 | 演示文稿标题 |
+| `<theme>` | 否 | 全局主题 |
+| `<slide>` | 是 | 幻灯片页面，至少 1 页，最多 100 页 |
+
+## 主题
+
+### `<theme>`
+
+`<theme>` 当前包含两部分：
+
+- `<background>`：演示文稿级背景填充
+- `<textStyles>`：主题文本样式集合
+
+`<textStyles>` 下可选子元素：
+
+- `<title>`
+- `<headline>`
+- `<sub-headline>`
+- `<body>`
+- `<caption>`
+
+这些元素定义的是主题默认样式，不是页面结构。常用属性：
+
+| 属性 | 说明 |
+|------|------|
+| `fontFamily` | 字体 |
+| `fontSize` | 字号 |
+| `fontColor` | 字体颜色 |
+
+## 幻灯片元素
+
+### `<slide>`
+
+单张幻灯片的结构比较严格。
+
+**属性：**
+
+| 属性 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `id` | string | 否 | 幻灯片标识 |
+
+**直接子元素只有：**
+
+| 元素 | 必需 | 说明 |
+|------|------|------|
+| `<style>` | 否 | 页面样式 |
+| `<data>` | 否 | 页面元素容器 |
+| `<note>` | 否 | 演讲者备注 |
+
+这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
+
+## 文本内容模型
+
+### `<content>`
+
+实际页面文本通常通过 `<content>` 表达，常见位置有：
+
+- `shape` 内部
+- `table/td` 内部
+- `note` 内部
+
+**常用属性：**
+
+| 属性 | 说明 |
+|------|------|
+| `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
+| `verticalAlign` | 垂直对齐 |
+| `textAlign` | 水平对齐 |
+| `lineSpacing` | 行间距 |
+| `fontSize` | 字号 |
+| `fontFamily` | 字体 |
+| `color` | 字体颜色 |
+| `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 |
+| `wrap` | 是否自动换行 |
+
+**可包含的子元素：**
+
+- `<p>`
+- `<ul>`
+- `<ol>`
+
+### `<p>`
+
+`<p>` 是段落元素，可混排纯文本和内联标签：
+
+- `<br/>`
+- `<strong>`
+- `<em>`
+- `<u>`
+- `<span>`
+- `<del>`
+- `<a>`
+- `<shadow>`
+- `<outline>`
+
+示例：
+
+```xml
+<content textType="body" textAlign="left">
+  <p>普通文本 <strong>加粗</strong> <em>斜体</em> <a href="https://example.com">链接</a></p>
+  <ul>
+    <li><p>列表项 1</p></li>
+    <li><p>列表项 2</p></li>
+  </ul>
+</content>
+```
+
+## 常用页面元素
+
+所有页面元素都放在 `<data>` 中。
+
+### `<shape>`
+
+`shape` 可表示普通形状，也可表示文本框。文本框推荐使用 `type="text"`。
+
+```xml
+<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+  <content textType="title">
+    <p>主标题</p>
+  </content>
+</shape>
+```
+
+```xml
+<shape type="rect" topLeftX="700" topLeftY="120" width="180" height="120">
+  <fill>
+    <fillColor color="rgba(100, 149, 237, 0.25)"/>
+  </fill>
+  <border color="rgb(100, 149, 237)" width="2"/>
+</shape>
+```
+
+**属性：**
+
+| 属性 | 必需 | 说明 |
+|------|------|------|
+| `type` | 是 | 形状类型，`text` 表示文本框 |
+| `topLeftX` | 是 | 左上角 X 坐标 |
+| `topLeftY` | 是 | 左上角 Y 坐标 |
+| `width` | 是 | 宽度 |
+| `height` | 是 | 高度 |
+| `rotation` | 否 | 旋转角度 |
+| `flipX` / `flipY` | 否 | 翻转 |
+| `alpha` | 否 | 透明度 |
+
+**可选子元素：**
+
+- `<fill>`
+- `<border>`
+- `<reflection>`
+- `<shadow>`
+- `<content>`
+
+### `<line>`
+
+```xml
+<line startX="100" startY="200" endX="420" endY="200">
+  <border color="rgb(43, 47, 54)" width="2"/>
+</line>
+```
+
+`line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。
+
+### `<img>`
+
+```xml
+<img src="file_token_or_url" topLeftX="100" topLeftY="220" width="320" height="180"/>
+```
+
+`img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
+
+`src` 只接受两种值：
+
+| `src` 形式 | 说明 |
+|---|---|
+| `file_token`（如 `boxcnXXXXXXXXXXXXXXXXXXXXXX`） | 通过 `slides +media-upload` 上传后返回的 token |
+| `@<本地路径>`（如 `@./assets/chart.png`） | **仅在 `slides +create --slides` 中可用**：CLI 会自动上传该文件并替换为 file_token |
+
+> **禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，`src="https://..."` 在 PPT 里通常显示破图。要用网图必须先 `curl`/下载到 CWD 内，再走上传流程拿 `file_token`。
+
+本地图片的两种姿势：
+
+- **新建带图 PPT**：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
+- **给已有 PPT 加带图新页**：先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token，再用 token 写进 `xml_presentation.slide create` 的 XML
+
+### `<icon>`
+
+```xml
+<icon iconType="iconpark/Base/setting.svg" topLeftX="440" topLeftY="220" width="32" height="32"/>
+```
+
+### `<table>`
+
+表格结构为：
+
+- `<table>`
+- `<colgroup>` / `<tr>`
+- `<tr>` 内为 `<td>`
+- `<td>` 内可放 `<content>`
+
+### `<chart>`
+
+图表元素必须至少包含：
+
+- `<chartPlotArea>`
+- `<chartData>`
+
+同时还可以包含：
+
+- `<chartTitle>`
+- `<chartSubTitle>`
+- `<chartStyle>`
+- `<chartLegend>`
+- `<chartTooltip>`
+
+如果要写图表 XML，建议直接以 XSD 为准，不要自行发明更简化的 chart DSL。
+
+## 样式元素
+
+### `<fill>`
+
+```xml
+<fill>
+  <fillColor color="rgb(100, 149, 237)"/>
+</fill>
+```
+
+### `<border>`
+
+```xml
+<border color="rgb(0, 0, 0)" width="2" dashArray="solid"/>
+```
+
+### 颜色格式
+
+```xml
+<fillColor color="rgb(255, 0, 0)"/>
+<fillColor color="rgba(255, 0, 0, 0.5)"/>
+<fillColor color="linear-gradient(90deg, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
+<fillColor color="radial-gradient(circle at 50% 50%, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
+```
+
+## 演讲者备注
+
+### `<note>`
+
+```xml
+<note>
+  <content textType="body">
+    <p>这是演讲者备注内容。</p>
+  </content>
+</note>
+```
+
+## 完整示例
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+  <title>季度报告</title>
+  <theme>
+    <textStyles>
+      <title fontFamily="思源黑体" fontSize="54" fontColor="rgba(0, 0, 0, 1)"/>
+      <body fontFamily="思源黑体" fontSize="18" fontColor="rgba(43, 47, 54, 1)"/>
+    </textStyles>
+  </theme>
+  <slide>
+    <style>
+      <fill>
+        <fillColor color="rgb(245, 245, 245)"/>
+      </fill>
+    </style>
+    <data>
+      <shape type="text" topLeftX="80" topLeftY="72" width="760" height="100">
+        <content textType="title">
+          <p>2024 年第一季度报告</p>
+        </content>
+      </shape>
+      <shape type="text" topLeftX="80" topLeftY="200" width="520" height="180">
+        <content textType="body">
+          <p>核心指标</p>
+          <ul>
+            <li><p>用户增长：+25%</p></li>
+            <li><p>收入增长：+30%</p></li>
+            <li><p>市场份额：15%</p></li>
+          </ul>
+        </content>
+      </shape>
+      <shape type="rect" topLeftX="660" topLeftY="180" width="180" height="140">
+        <fill>
+          <fillColor color="rgba(100, 149, 237, 0.25)"/>
+        </fill>
+        <border color="rgb(100, 149, 237)" width="2"/>
+      </shape>
+    </data>
+    <note>
+      <content textType="body">
+        <p>讲到增长率时补充样本范围。</p>
+      </content>
+    </note>
+  </slide>
+</presentation>
+```
+
+## 最佳实践
+
+1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"`
+2. 用 `shape type="text"` + `content` 表达页面文本
+3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名
+4. 优先使用 `rgb` / `rgba` 颜色格式
+5. 特殊字符按 XML 规则转义
+6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"`
+
+## 参考文档
+
+- [xml-schema-quick-ref.md](xml-schema-quick-ref.md)
+- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
+- [examples.md](examples.md)
+- [slides_demo.xml](slides_demo.xml)

skills/lark-slides/references/xml-schema-quick-ref.md

@@ -8,8 +8,6 @@
 2. `<presentation>` 直接子元素只有 `<title>`、`<theme>`、`<slide>`
 3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`
 4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下
-5. 文本中的特殊字符必须按 XML 规则转义，例如 `&` 写成 `&amp;`，`<` / `>` 写成 `&lt;` / `&gt;`
-6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"`
 
 ## 最小可用示例
 
@@ -38,8 +36,6 @@
 
 **子元素：** `<title>?`, `<theme>?`, `<slide>+`
 
-`<slide>` 至少 1 页，最多 100 页。
-
 ## slide 元素
 
 | 属性 | 必需 | 说明 |
@@ -58,19 +54,6 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 - `<theme><textStyles>...</textStyles></theme>` 中，作为主题文本样式
 - `<content textType="...">` 中，作为内容的文本类型
 
-`<theme>` 当前可包含：
-
-- `<background>` - 演示文稿级背景填充
-- `<textStyles>` - 主题文本样式集合
-
-主题文本样式常用属性：
-
-| 属性 | 说明 |
-|------|------|
-| `fontFamily` | 字体 |
-| `fontSize` | 字号 |
-| `fontColor` | 字体颜色 |
-
 `textStyles` 的 schema 默认值如下：
 
 | textType | 默认字号 |
@@ -88,14 +71,12 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | 属性 | 说明 |
 |------|------|
 | `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
-| `verticalAlign` | 垂直对齐方式 |
 | `textAlign` | 文本对齐方式 |
 | `lineSpacing` | 行间距，schema 默认 `multiple:1.5` |
 | `fontSize` | 字号 |
 | `fontFamily` | 字体 |
 | `color` | 字体颜色 |
 | `bold` / `italic` / `underline` / `strikethrough` | 文本样式 |
-| `wrap` | 是否自动换行 |
 
 `<content>` 的子元素只能是：
 
@@ -103,8 +84,6 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 - `<ul>`
 - `<ol>`
 
-`<p>` 可混排纯文本和内联标签：`<br/>`、`<strong>`、`<em>`、`<u>`、`<span>`、`<del>`、`<a>`、`<shadow>`、`<outline>`。
-
 ### content 示例
 
 ```xml
@@ -138,10 +117,6 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | `width` | 是 | 宽度 |
 | `height` | 是 | 高度 |
 | `rotation` | 否 | 旋转角度 |
-| `flipX` / `flipY` | 否 | 翻转 |
-| `alpha` | 否 | 透明度 |
-
-可选子元素：`<fill>`、`<border>`、`<reflection>`、`<shadow>`、`<content>`。
 
 ### line
 
@@ -151,16 +126,12 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 </line>
 ```
 
-`line` 使用 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。
-
 ### img
 
 ```xml
 <img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
 ```
 
-`img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
-
 `src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（仅 `+create --slides` 自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
 
 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
@@ -173,14 +144,6 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 `iconType` 必须来自已验证的 IconPark 路径。需要语义图标时，先运行 `scripts/iconpark_tool.py search --query "<语义>"`，不要凭记忆拼路径。更多规则见 [iconpark.md](iconpark.md)。
 
-### table
-
-表格结构为 `<table>`，内部可包含 `<colgroup>` / `<tr>`，`<tr>` 内为 `<td>`，`<td>` 内可放 `<content>`。
-
-### chart
-
-图表元素必须至少包含 `<chartPlotArea>` 和 `<chartData>`；还可包含 `<chartTitle>`、`<chartSubTitle>`、`<chartStyle>`、`<chartLegend>`、`<chartTooltip>`。复杂 chart XML 以 XSD 为准，不要自行发明简化 DSL。
-
 ### whiteboard
 
 ```xml
@@ -268,6 +231,13 @@ Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->`
 </note>
 ```
 
+## 详细参考
+
+- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
+- [xml-format-guide.md](xml-format-guide.md)
+- [examples.md](examples.md)
+- [slides_demo.xml](slides_demo.xml)
+
 ## Schema 版本信息
 
 - **版本**: 2.0.0