refactor(sheets): drop +recover flag/shortcut registration (split to PR #1414)

+recover (方案B) moved to its own PR (#1414). This PR (方案A) keeps +undo and
the read/write transaction_id split. The recover_to_revision server impl lives
in the facade recover MR.

shortcuts/drive/drive_export.go

@@ -39,230 +39,296 @@ var DriveExport = common.Shortcut{
 		{Name: "overwrite", Type: "bool", Desc: "overwrite existing output file"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateDriveExportSpec(driveExportSpec{
-			Token:         runtime.Str("token"),
-			DocType:       runtime.Str("doc-type"),
-			FileExtension: runtime.Str("file-extension"),
-			SubID:         runtime.Str("sub-id"),
-		})
+		return ValidateExport(exportParamsFromFlags(runtime))
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		spec := driveExportSpec{
-			Token:         runtime.Str("token"),
-			DocType:       runtime.Str("doc-type"),
-			FileExtension: runtime.Str("file-extension"),
-			SubID:         runtime.Str("sub-id"),
-		}
-		// Markdown export is a special case: docx markdown comes from the V2
-		// docs_ai fetch API directly instead of the Drive export task API.
-		if spec.FileExtension == "markdown" {
-			apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/fetch", validate.EncodePathSegment(spec.Token))
-			dr := common.NewDryRunAPI().
-				Desc("2-step orchestration: fetch docx markdown -> write local file").
-				POST(apiPath).
-				Body(map[string]interface{}{
-					"format": "markdown",
-				}).
-				Set("output_dir", runtime.Str("output-dir"))
-			if name := strings.TrimSpace(runtime.Str("file-name")); name != "" {
-				dr.Set("file_name", ensureExportFileExtension(sanitizeExportFileName(name, spec.Token), spec.FileExtension))
-			}
-			return dr
-		}
+		return PlanExportDryRun(runtime, exportParamsFromFlags(runtime))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return RunExport(ctx, runtime, exportParamsFromFlags(runtime))
+	},
+}
 
-		body := map[string]interface{}{
-			"token":          spec.Token,
-			"type":           spec.DocType,
-			"file_extension": spec.FileExtension,
-		}
-		if strings.TrimSpace(spec.SubID) != "" {
-			body["sub_id"] = spec.SubID
-		}
+// ExportParams holds the user-facing inputs for an export flow, decoupled from
+// cobra flags so other command groups (e.g. sheets +workbook-export) can reuse
+// the drive export implementation. An empty OutputDir means "create the export
+// task and poll, but do not download" — callers that only need the ready file
+// token / status get it back without writing a local file.
+type ExportParams struct {
+	Token         string
+	DocType       string
+	FileExtension string
+	SubID         string
+	OutputDir     string
+	FileName      string
+	Overwrite     bool
+}
 
+func (p ExportParams) spec() driveExportSpec {
+	return driveExportSpec{
+		Token:         p.Token,
+		DocType:       p.DocType,
+		FileExtension: p.FileExtension,
+		SubID:         p.SubID,
+	}
+}
+
+// exportParamsFromFlags reads the standard drive +export flag set.
+func exportParamsFromFlags(runtime *common.RuntimeContext) ExportParams {
+	// drive +export always downloads; an empty --output-dir historically means
+	// the current directory (saveContentToOutputDir maps "" -> "."), so normalize
+	// it here to keep behavior identical and stay off the export-only ("" => skip
+	// download) path that only sheets +workbook-export uses.
+	outputDir := runtime.Str("output-dir")
+	if outputDir == "" {
+		outputDir = "."
+	}
+	return ExportParams{
+		Token:         runtime.Str("token"),
+		DocType:       runtime.Str("doc-type"),
+		FileExtension: runtime.Str("file-extension"),
+		SubID:         runtime.Str("sub-id"),
+		OutputDir:     outputDir,
+		FileName:      strings.TrimSpace(runtime.Str("file-name")),
+		Overwrite:     runtime.Bool("overwrite"),
+	}
+}
+
+// ValidateExport runs the CLI-level export constraint checks.
+func ValidateExport(p ExportParams) error {
+	return validateDriveExportSpec(p.spec())
+}
+
+// PlanExportDryRun builds the dry-run plan for an export without performing I/O.
+func PlanExportDryRun(runtime *common.RuntimeContext, p ExportParams) *common.DryRunAPI {
+	spec := p.spec()
+	// Markdown export is a special case: docx markdown comes from the V2
+	// docs_ai fetch API directly instead of the Drive export task API.
+	if spec.FileExtension == "markdown" {
+		apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/fetch", validate.EncodePathSegment(spec.Token))
 		dr := common.NewDryRunAPI().
-			Desc("3-step orchestration: create export task -> limited polling -> download file").
-			POST("/open-apis/drive/v1/export_tasks").
-			Body(body).
-			Set("output_dir", runtime.Str("output-dir"))
-		if name := strings.TrimSpace(runtime.Str("file-name")); name != "" {
+			Desc("2-step orchestration: fetch docx markdown -> write local file").
+			POST(apiPath).
+			Body(map[string]interface{}{
+				"format": "markdown",
+			}).
+			Set("output_dir", p.OutputDir)
+		if name := strings.TrimSpace(p.FileName); name != "" {
 			dr.Set("file_name", ensureExportFileExtension(sanitizeExportFileName(name, spec.Token), spec.FileExtension))
 		}
 		return dr
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		spec := driveExportSpec{
-			Token:         runtime.Str("token"),
-			DocType:       runtime.Str("doc-type"),
-			FileExtension: runtime.Str("file-extension"),
-			SubID:         runtime.Str("sub-id"),
+	}
+
+	body := map[string]interface{}{
+		"token":          spec.Token,
+		"type":           spec.DocType,
+		"file_extension": spec.FileExtension,
+	}
+	if strings.TrimSpace(spec.SubID) != "" {
+		body["sub_id"] = spec.SubID
+	}
+
+	dr := common.NewDryRunAPI().
+		Desc("3-step orchestration: create export task -> limited polling -> download file").
+		POST("/open-apis/drive/v1/export_tasks").
+		Body(body).
+		Set("output_dir", p.OutputDir)
+	if name := strings.TrimSpace(p.FileName); name != "" {
+		dr.Set("file_name", ensureExportFileExtension(sanitizeExportFileName(name, spec.Token), spec.FileExtension))
+	}
+	return dr
+}
+
+// RunExport drives create export task -> bounded poll -> optional download. It
+// is the shared core behind both drive +export and sheets +workbook-export. An
+// empty p.OutputDir skips the download step and returns the ready file token.
+func RunExport(ctx context.Context, runtime *common.RuntimeContext, p ExportParams) error {
+	spec := p.spec()
+	outputDir := p.OutputDir
+	preferredFileName := strings.TrimSpace(p.FileName)
+	overwrite := p.Overwrite
+
+	// Markdown export bypasses the async export task and writes the fetched
+	// markdown content directly to disk. Uses the V2 docs_ai fetch API for
+	// higher-quality Lark-flavored Markdown output.
+	if spec.FileExtension == "markdown" {
+		fmt.Fprintf(runtime.IO().ErrOut, "Exporting docx as markdown: %s\n", common.MaskToken(spec.Token))
+		apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/fetch", validate.EncodePathSegment(spec.Token))
+		data, err := runtime.CallAPITyped(
+			"POST",
+			apiPath,
+			nil,
+			map[string]interface{}{
+				"format": "markdown",
+			},
+		)
+		if err != nil {
+			return err
 		}
-		outputDir := runtime.Str("output-dir")
-		preferredFileName := strings.TrimSpace(runtime.Str("file-name"))
-		overwrite := runtime.Bool("overwrite")
 
-		// Markdown export bypasses the async export task and writes the fetched
-		// markdown content directly to disk. Uses the V2 docs_ai fetch API for
-		// higher-quality Lark-flavored Markdown output.
-		if spec.FileExtension == "markdown" {
-			fmt.Fprintf(runtime.IO().ErrOut, "Exporting docx as markdown: %s\n", common.MaskToken(spec.Token))
-			apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/fetch", validate.EncodePathSegment(spec.Token))
-			data, err := runtime.CallAPITyped(
-				"POST",
-				apiPath,
-				nil,
-				map[string]interface{}{
-					"format": "markdown",
-				},
-			)
+		// Extract content from the V2 response: data.document.content
+		doc, ok := data["document"].(map[string]interface{})
+		if !ok {
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "invalid markdown fetch response: missing document object")
+		}
+		content, ok := doc["content"].(string)
+		if !ok {
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "invalid markdown fetch response: missing document.content")
+		}
+
+		fileName := preferredFileName
+		if fileName == "" {
+			// Prefer the remote title for the exported file name, but still fall
+			// back to the token if metadata is empty.
+			title, err := common.FetchDriveMetaTitle(runtime, spec.Token, spec.DocType)
 			if err != nil {
-				return err
+				fmt.Fprintf(runtime.IO().ErrOut, "Title lookup failed, using token as filename: %v\n", err)
+				title = spec.Token
 			}
+			fileName = title
+		}
+		fileName = ensureExportFileExtension(sanitizeExportFileName(fileName, spec.Token), spec.FileExtension)
+		savedPath, err := saveContentToOutputDir(runtime.FileIO(), outputDir, fileName, []byte(content), overwrite)
+		if err != nil {
+			return err
+		}
 
-			// Extract content from the V2 response: data.document.content
-			doc, ok := data["document"].(map[string]interface{})
-			if !ok {
-				return errs.NewInternalError(errs.SubtypeInvalidResponse, "invalid markdown fetch response: missing document object")
+		runtime.Out(map[string]interface{}{
+			"token":          spec.Token,
+			"doc_type":       spec.DocType,
+			"file_extension": spec.FileExtension,
+			"file_name":      filepath.Base(savedPath),
+			"saved_path":     savedPath,
+			"size_bytes":     len(content),
+		}, nil)
+		return nil
+	}
+
+	ticket, err := createDriveExportTask(runtime, spec)
+	if err != nil {
+		return err
+	}
+	fmt.Fprintf(runtime.IO().ErrOut, "Created export task: %s\n", ticket)
+
+	var lastStatus driveExportStatus
+	var lastPollErr error
+	hasObservedStatus := false
+	// Keep the command responsive by polling for a bounded window. If the task
+	// is still running after that, return a resume command instead of blocking.
+	for attempt := 1; attempt <= driveExportPollAttempts; attempt++ {
+		if attempt > 1 {
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-time.After(driveExportPollInterval):
 			}
-			content, ok := doc["content"].(string)
-			if !ok {
-				return errs.NewInternalError(errs.SubtypeInvalidResponse, "invalid markdown fetch response: missing document.content")
+		}
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+
+		status, err := getDriveExportStatus(runtime, spec.Token, ticket)
+		if err != nil {
+			// Treat polling failures as transient so short-lived backend hiccups
+			// do not immediately fail an otherwise healthy export task.
+			lastPollErr = err
+			fmt.Fprintf(runtime.IO().ErrOut, "Export status attempt %d/%d failed: %v\n", attempt, driveExportPollAttempts, err)
+			continue
+		}
+		lastStatus = status
+		hasObservedStatus = true
+
+		if status.Ready() {
+			fmt.Fprintf(runtime.IO().ErrOut, "Export task completed: %s\n", common.MaskToken(status.FileToken))
+
+			// Export-only mode: caller wants the ready file token / metadata but
+			// no local download (e.g. sheets +workbook-export without an output
+			// path). Skip the download and return the status envelope.
+			if strings.TrimSpace(outputDir) == "" {
+				runtime.Out(map[string]interface{}{
+					"ticket":         ticket,
+					"token":          spec.Token,
+					"doc_type":       spec.DocType,
+					"file_extension": spec.FileExtension,
+					"file_token":     status.FileToken,
+					"file_name":      status.FileName,
+					"file_size":      status.FileSize,
+					"ready":          true,
+					"downloaded":     false,
+				}, nil)
+				return nil
 			}
 
 			fileName := preferredFileName
 			if fileName == "" {
-				// Prefer the remote title for the exported file name, but still fall
-				// back to the token if metadata is empty.
-				title, err := common.FetchDriveMetaTitle(runtime, spec.Token, spec.DocType)
-				if err != nil {
-					fmt.Fprintf(runtime.IO().ErrOut, "Title lookup failed, using token as filename: %v\n", err)
-					title = spec.Token
-				}
-				fileName = title
+				fileName = status.FileName
 			}
 			fileName = ensureExportFileExtension(sanitizeExportFileName(fileName, spec.Token), spec.FileExtension)
-			savedPath, err := saveContentToOutputDir(runtime.FileIO(), outputDir, fileName, []byte(content), overwrite)
+			out, err := downloadDriveExportFile(ctx, runtime, status.FileToken, outputDir, fileName, overwrite)
 			if err != nil {
-				return err
+				recoveryCommand := driveExportDownloadCommand(status.FileToken, fileName, outputDir, overwrite)
+				hint := fmt.Sprintf(
+					"the export artifact is already ready (ticket=%s, file_token=%s)\nretry download with: %s",
+					ticket,
+					status.FileToken,
+					recoveryCommand,
+				)
+				return appendDriveExportRecoveryHint(err, hint)
 			}
-
-			runtime.Out(map[string]interface{}{
-				"token":          spec.Token,
-				"doc_type":       spec.DocType,
-				"file_extension": spec.FileExtension,
-				"file_name":      filepath.Base(savedPath),
-				"saved_path":     savedPath,
-				"size_bytes":     len(content),
-			}, nil)
+			out["ticket"] = ticket
+			out["doc_type"] = spec.DocType
+			out["file_extension"] = spec.FileExtension
+			runtime.Out(out, nil)
 			return nil
 		}
 
-		ticket, err := createDriveExportTask(runtime, spec)
-		if err != nil {
-			return err
-		}
-		fmt.Fprintf(runtime.IO().ErrOut, "Created export task: %s\n", ticket)
-
-		var lastStatus driveExportStatus
-		var lastPollErr error
-		hasObservedStatus := false
-		// Keep the command responsive by polling for a bounded window. If the task
-		// is still running after that, return a resume command instead of blocking.
-		for attempt := 1; attempt <= driveExportPollAttempts; attempt++ {
-			if attempt > 1 {
-				select {
-				case <-ctx.Done():
-					return ctx.Err()
-				case <-time.After(driveExportPollInterval):
-				}
+		if status.Failed() {
+			msg := strings.TrimSpace(status.JobErrorMsg)
+			if msg == "" {
+				msg = status.StatusLabel()
 			}
-			if err := ctx.Err(); err != nil {
-				return err
-			}
-
-			status, err := getDriveExportStatus(runtime, spec.Token, ticket)
-			if err != nil {
-				// Treat polling failures as transient so short-lived backend hiccups
-				// do not immediately fail an otherwise healthy export task.
-				lastPollErr = err
-				fmt.Fprintf(runtime.IO().ErrOut, "Export status attempt %d/%d failed: %v\n", attempt, driveExportPollAttempts, err)
-				continue
-			}
-			lastStatus = status
-			hasObservedStatus = true
-
-			if status.Ready() {
-				fmt.Fprintf(runtime.IO().ErrOut, "Export task completed: %s\n", common.MaskToken(status.FileToken))
-				fileName := preferredFileName
-				if fileName == "" {
-					fileName = status.FileName
-				}
-				fileName = ensureExportFileExtension(sanitizeExportFileName(fileName, spec.Token), spec.FileExtension)
-				out, err := downloadDriveExportFile(ctx, runtime, status.FileToken, outputDir, fileName, overwrite)
-				if err != nil {
-					recoveryCommand := driveExportDownloadCommand(status.FileToken, fileName, outputDir, overwrite)
-					hint := fmt.Sprintf(
-						"the export artifact is already ready (ticket=%s, file_token=%s)\nretry download with: %s",
-						ticket,
-						status.FileToken,
-						recoveryCommand,
-					)
-					return appendDriveExportRecoveryHint(err, hint)
-				}
-				out["ticket"] = ticket
-				out["doc_type"] = spec.DocType
-				out["file_extension"] = spec.FileExtension
-				runtime.Out(out, nil)
-				return nil
-			}
-
-			if status.Failed() {
-				msg := strings.TrimSpace(status.JobErrorMsg)
-				if msg == "" {
-					msg = status.StatusLabel()
-				}
-				return errs.NewAPIError(errs.SubtypeServerError, "export task failed: %s (ticket=%s)", msg, ticket)
-			}
-
-			fmt.Fprintf(runtime.IO().ErrOut, "Export status %d/%d: %s\n", attempt, driveExportPollAttempts, status.StatusLabel())
+			return errs.NewAPIError(errs.SubtypeServerError, "export task failed: %s (ticket=%s)", msg, ticket)
 		}
 
-		nextCommand := driveExportTaskResultCommand(ticket, spec.Token)
-		if !hasObservedStatus && lastPollErr != nil {
-			hint := fmt.Sprintf(
-				"the export task was created but every status poll failed (ticket=%s)\nretry status lookup with: %s",
-				ticket,
-				nextCommand,
-			)
-			return appendDriveExportRecoveryHint(lastPollErr, hint)
-		}
+		fmt.Fprintf(runtime.IO().ErrOut, "Export status %d/%d: %s\n", attempt, driveExportPollAttempts, status.StatusLabel())
+	}
 
-		failed := false
-		var jobStatus interface{}
-		jobStatusLabel := "unknown"
-		if hasObservedStatus {
-			failed = lastStatus.Failed()
-			jobStatus = lastStatus.JobStatus
-			jobStatusLabel = lastStatus.StatusLabel()
-		}
-		// Return the last observed status so callers can resume from a known task
-		// state instead of losing all progress information on timeout.
-		result := map[string]interface{}{
-			"ticket":           ticket,
-			"token":            spec.Token,
-			"doc_type":         spec.DocType,
-			"file_extension":   spec.FileExtension,
-			"ready":            false,
-			"failed":           failed,
-			"job_status":       jobStatus,
-			"job_status_label": jobStatusLabel,
-			"timed_out":        true,
-			"next_command":     nextCommand,
-		}
-		if preferredFileName != "" {
-			result["file_name"] = ensureExportFileExtension(sanitizeExportFileName(preferredFileName, spec.Token), spec.FileExtension)
-		}
-		runtime.Out(result, nil)
-		fmt.Fprintf(runtime.IO().ErrOut, "Export task is still in progress. Continue with: %s\n", nextCommand)
-		return nil
-	},
+	nextCommand := driveExportTaskResultCommand(ticket, spec.Token)
+	if !hasObservedStatus && lastPollErr != nil {
+		hint := fmt.Sprintf(
+			"the export task was created but every status poll failed (ticket=%s)\nretry status lookup with: %s",
+			ticket,
+			nextCommand,
+		)
+		return appendDriveExportRecoveryHint(lastPollErr, hint)
+	}
+
+	failed := false
+	var jobStatus interface{}
+	jobStatusLabel := "unknown"
+	if hasObservedStatus {
+		failed = lastStatus.Failed()
+		jobStatus = lastStatus.JobStatus
+		jobStatusLabel = lastStatus.StatusLabel()
+	}
+	// Return the last observed status so callers can resume from a known task
+	// state instead of losing all progress information on timeout.
+	result := map[string]interface{}{
+		"ticket":           ticket,
+		"token":            spec.Token,
+		"doc_type":         spec.DocType,
+		"file_extension":   spec.FileExtension,
+		"ready":            false,
+		"failed":           failed,
+		"job_status":       jobStatus,
+		"job_status_label": jobStatusLabel,
+		"timed_out":        true,
+		"next_command":     nextCommand,
+	}
+	if preferredFileName != "" {
+		result["file_name"] = ensureExportFileExtension(sanitizeExportFileName(preferredFileName, spec.Token), spec.FileExtension)
+	}
+	runtime.Out(result, nil)
+	fmt.Fprintf(runtime.IO().ErrOut, "Export task is still in progress. Continue with: %s\n", nextCommand)
+	return nil
 }

shortcuts/drive/drive_export_test.go

@@ -488,6 +488,72 @@ func TestDriveExportAsyncSuccess(t *testing.T) {
 	}
 }
 
+// TestDriveExportEmptyOutputDirDownloadsToCwd guards the export refactor: an
+// explicit empty --output-dir must still download to the current directory
+// (normalized to "."), not trigger the export-only no-download path that the
+// shared RunExport core uses for sheets +workbook-export.
+func TestDriveExportEmptyOutputDirDownloadsToCwd(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/export_tasks",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"ticket": "tk_e"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/export_tasks/tk_e",
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"result": map[string]interface{}{
+				"job_status": 0, "file_token": "box_e", "file_name": "report",
+				"file_extension": "pdf", "type": "docx", "file_size": 3,
+			},
+		}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/export_tasks/file/box_e/download",
+		Status:  200,
+		RawBody: []byte("pdf"),
+		Headers: http.Header{
+			"Content-Type":        []string{"application/pdf"},
+			"Content-Disposition": []string{`attachment; filename="report.pdf"`},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	prevAttempts, prevInterval := driveExportPollAttempts, driveExportPollInterval
+	driveExportPollAttempts, driveExportPollInterval = 1, 0
+	t.Cleanup(func() {
+		driveExportPollAttempts, driveExportPollInterval = prevAttempts, prevInterval
+	})
+
+	err := mountAndRunDrive(t, DriveExport, []string{
+		"+export",
+		"--token", "docx123",
+		"--doc-type", "docx",
+		"--file-extension", "pdf",
+		"--output-dir", "",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Empty --output-dir must still write to cwd, not skip the download.
+	data, err := os.ReadFile(filepath.Join(tmpDir, "report.pdf"))
+	if err != nil {
+		t.Fatalf("empty --output-dir should still download to cwd: %v", err)
+	}
+	if string(data) != "pdf" {
+		t.Fatalf("downloaded content = %q", string(data))
+	}
+	if strings.Contains(stdout.String(), `"downloaded": false`) {
+		t.Fatalf("export-only path must not trigger for drive +export: %s", stdout.String())
+	}
+}
+
 func TestDriveExportAsyncUsesProvidedFileName(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	reg.Register(&httpmock.Stub{

shortcuts/drive/drive_import.go

@@ -34,128 +34,160 @@ var DriveImport = common.Shortcut{
 		{Name: "target-token", Desc: "existing token to import data into (only for type=bitable); when set, data is mounted into this bitable instead of creating a new one"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateDriveImportSpec(driveImportSpec{
-			FilePath:    runtime.Str("file"),
-			DocType:     strings.ToLower(runtime.Str("type")),
-			FolderToken: runtime.Str("folder-token"),
-			Name:        runtime.Str("name"),
-			TargetToken: runtime.Str("target-token"),
-		})
+		return ValidateImport(importParamsFromFlags(runtime))
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		spec := driveImportSpec{
-			FilePath:    runtime.Str("file"),
-			DocType:     strings.ToLower(runtime.Str("type")),
-			FolderToken: runtime.Str("folder-token"),
-			Name:        runtime.Str("name"),
-			TargetToken: runtime.Str("target-token"),
-		}
-		fileSize, err := preflightDriveImportFile(runtime.FileIO(), &spec)
-		if err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
-		}
-		if valErr := validateDriveImportSpec(spec); valErr != nil {
-			return common.NewDryRunAPI().Set("error", valErr.Error())
-		}
-
-		dry := common.NewDryRunAPI()
-		dry.Desc("Upload file (single-part or multipart) -> create import task -> poll status")
-
-		appendDriveImportUploadDryRun(dry, spec, fileSize)
-
-		dry.POST("/open-apis/drive/v1/import_tasks").
-			Desc("[2] Create import task").
-			Body(spec.CreateTaskBody("<file_token>"))
-
-		dry.GET("/open-apis/drive/v1/import_tasks/:ticket").
-			Desc("[3] Poll import task result").
-			Set("ticket", "<ticket>")
-		if runtime.IsBot() {
-			dry.Desc("After the import result returns the final cloud document target in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on it.")
-		}
-
-		return dry
+		return PlanImportDryRun(runtime, importParamsFromFlags(runtime))
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		spec := driveImportSpec{
-			FilePath:    runtime.Str("file"),
-			DocType:     strings.ToLower(runtime.Str("type")),
-			FolderToken: runtime.Str("folder-token"),
-			Name:        runtime.Str("name"),
-			TargetToken: runtime.Str("target-token"),
-		}
-		if _, err := preflightDriveImportFile(runtime.FileIO(), &spec); err != nil {
-			return err
-		}
-
-		// Step 1: Upload file as media
-		fileToken, uploadErr := uploadMediaForImport(ctx, runtime, spec.FilePath, spec.SourceFileName(), spec.DocType)
-		if uploadErr != nil {
-			return uploadErr
-		}
-
-		fmt.Fprintf(runtime.IO().ErrOut, "Creating import task for %s as %s...\n", spec.TargetFileName(), spec.DocType)
-
-		// Step 2: Create import task
-		ticket, err := createDriveImportTask(runtime, spec, fileToken)
-		if err != nil {
-			return err
-		}
-
-		// Step 3: Poll task
-		fmt.Fprintf(runtime.IO().ErrOut, "Polling import task %s...\n", ticket)
-
-		status, ready, err := pollDriveImportTask(runtime, ticket)
-		if err != nil {
-			return err
-		}
-
-		// Some intermediate responses omit the final type, so fall back to the
-		// requested type to keep the output shape stable.
-		resultType := status.DocType
-		if resultType == "" {
-			resultType = spec.DocType
-		}
-		out := map[string]interface{}{
-			"ticket":           ticket,
-			"type":             resultType,
-			"ready":            ready,
-			"job_status":       status.JobStatus,
-			"job_status_label": status.StatusLabel(),
-		}
-		if status.Token != "" {
-			out["token"] = status.Token
-		}
-		if statusURL := strings.TrimSpace(status.URL); statusURL != "" {
-			out["url"] = statusURL
-		} else if status.Token != "" {
-			if u := common.BuildResourceURL(runtime.Config.Brand, normalizeDriveImportKindForURL(resultType, spec.DocType), status.Token); u != "" {
-				out["url"] = u
-			}
-		}
-		if status.JobErrorMsg != "" {
-			out["job_error_msg"] = status.JobErrorMsg
-		}
-		if status.Extra != nil {
-			out["extra"] = status.Extra
-		}
-		if !ready {
-			nextCommand := driveImportTaskResultCommand(ticket)
-			fmt.Fprintf(runtime.IO().ErrOut, "Import task is still in progress. Continue with: %s\n", nextCommand)
-			out["timed_out"] = true
-			out["next_command"] = nextCommand
-		}
-		if ready {
-			if grant := common.AutoGrantCurrentUserDrivePermission(runtime, common.GetString(out, "token"), resultType); grant != nil {
-				out["permission_grant"] = grant
-			}
-		}
-
-		runtime.Out(out, nil)
-		return nil
+		return RunImport(ctx, runtime, importParamsFromFlags(runtime))
 	},
 }
 
+// ImportParams holds the user-facing inputs for an import flow, decoupled from
+// cobra flags so other command groups (e.g. sheets +workbook-import) can reuse
+// the drive import implementation without taking a dependency on a --type flag.
+type ImportParams struct {
+	File        string
+	DocType     string
+	FolderToken string
+	Name        string
+	TargetToken string
+}
+
+func (p ImportParams) spec() driveImportSpec {
+	return driveImportSpec{
+		FilePath:    p.File,
+		DocType:     strings.ToLower(p.DocType),
+		FolderToken: p.FolderToken,
+		Name:        p.Name,
+		TargetToken: p.TargetToken,
+	}
+}
+
+// importParamsFromFlags reads the standard drive +import flag set.
+func importParamsFromFlags(runtime *common.RuntimeContext) ImportParams {
+	return ImportParams{
+		File:        runtime.Str("file"),
+		DocType:     runtime.Str("type"),
+		FolderToken: runtime.Str("folder-token"),
+		Name:        runtime.Str("name"),
+		TargetToken: runtime.Str("target-token"),
+	}
+}
+
+// ValidateImport runs the CLI-level compatibility checks for an import.
+func ValidateImport(p ImportParams) error {
+	return validateDriveImportSpec(p.spec())
+}
+
+// PlanImportDryRun builds the dry-run plan (upload -> create task -> poll) for
+// an import without performing any network or file I/O beyond a local stat.
+func PlanImportDryRun(runtime *common.RuntimeContext, p ImportParams) *common.DryRunAPI {
+	spec := p.spec()
+	fileSize, err := preflightDriveImportFile(runtime.FileIO(), &spec)
+	if err != nil {
+		return common.NewDryRunAPI().Set("error", err.Error())
+	}
+	if valErr := validateDriveImportSpec(spec); valErr != nil {
+		return common.NewDryRunAPI().Set("error", valErr.Error())
+	}
+
+	dry := common.NewDryRunAPI()
+	dry.Desc("Upload file (single-part or multipart) -> create import task -> poll status")
+
+	appendDriveImportUploadDryRun(dry, spec, fileSize)
+
+	dry.POST("/open-apis/drive/v1/import_tasks").
+		Desc("[2] Create import task").
+		Body(spec.CreateTaskBody("<file_token>"))
+
+	dry.GET("/open-apis/drive/v1/import_tasks/:ticket").
+		Desc("[3] Poll import task result").
+		Set("ticket", "<ticket>")
+	if runtime.IsBot() {
+		dry.Desc("After the import result returns the final cloud document target in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on it.")
+	}
+
+	return dry
+}
+
+// RunImport executes the full import flow: upload media -> create import task ->
+// bounded poll, then writes the result envelope to the runtime output. It is
+// the shared core behind both drive +import and sheets +workbook-import.
+func RunImport(ctx context.Context, runtime *common.RuntimeContext, p ImportParams) error {
+	spec := p.spec()
+	if _, err := preflightDriveImportFile(runtime.FileIO(), &spec); err != nil {
+		return err
+	}
+
+	// Step 1: Upload file as media
+	fileToken, uploadErr := uploadMediaForImport(ctx, runtime, spec.FilePath, spec.SourceFileName(), spec.DocType)
+	if uploadErr != nil {
+		return uploadErr
+	}
+
+	fmt.Fprintf(runtime.IO().ErrOut, "Creating import task for %s as %s...\n", spec.TargetFileName(), spec.DocType)
+
+	// Step 2: Create import task
+	ticket, err := createDriveImportTask(runtime, spec, fileToken)
+	if err != nil {
+		return err
+	}
+
+	// Step 3: Poll task
+	fmt.Fprintf(runtime.IO().ErrOut, "Polling import task %s...\n", ticket)
+
+	status, ready, err := pollDriveImportTask(runtime, ticket)
+	if err != nil {
+		return err
+	}
+
+	// Some intermediate responses omit the final type, so fall back to the
+	// requested type to keep the output shape stable.
+	resultType := status.DocType
+	if resultType == "" {
+		resultType = spec.DocType
+	}
+	out := map[string]interface{}{
+		"ticket":           ticket,
+		"type":             resultType,
+		"ready":            ready,
+		"job_status":       status.JobStatus,
+		"job_status_label": status.StatusLabel(),
+	}
+	if status.Token != "" {
+		out["token"] = status.Token
+	}
+	if statusURL := strings.TrimSpace(status.URL); statusURL != "" {
+		out["url"] = statusURL
+	} else if status.Token != "" {
+		if u := common.BuildResourceURL(runtime.Config.Brand, normalizeDriveImportKindForURL(resultType, spec.DocType), status.Token); u != "" {
+			out["url"] = u
+		}
+	}
+	if status.JobErrorMsg != "" {
+		out["job_error_msg"] = status.JobErrorMsg
+	}
+	if status.Extra != nil {
+		out["extra"] = status.Extra
+	}
+	if !ready {
+		nextCommand := driveImportTaskResultCommand(ticket)
+		fmt.Fprintf(runtime.IO().ErrOut, "Import task is still in progress. Continue with: %s\n", nextCommand)
+		out["timed_out"] = true
+		out["next_command"] = nextCommand
+	}
+	if ready {
+		if grant := common.AutoGrantCurrentUserDrivePermission(runtime, common.GetString(out, "token"), resultType); grant != nil {
+			out["permission_grant"] = grant
+		}
+	}
+
+	runtime.Out(out, nil)
+	return nil
+}
+
 func preflightDriveImportFile(fio fileio.FileIO, spec *driveImportSpec) (int64, error) {
 	// Keep dry-run and execution aligned on path normalization, file existence,
 	// and format-specific size limits before planning the upload path.

shortcuts/sheets/batch_op_contract_test.go

@@ -177,6 +177,18 @@ func TestBatchOp_BodyMatchesStandalone(t *testing.T) {
 			args:     []string{"--sheet-id", "sh1", "--color", "#FF0000"},
 			subInput: `{"sheet-id":"sh1","color":"#FF0000"}`,
 		},
+		{
+			shortcut: "+sheet-show-gridline",
+			sc:       SheetShowGridline,
+			args:     []string{"--sheet-id", "sh1"},
+			subInput: `{"sheet-id":"sh1"}`,
+		},
+		{
+			shortcut: "+sheet-hide-gridline",
+			sc:       SheetHideGridline,
+			args:     []string{"--sheet-id", "sh1"},
+			subInput: `{"sheet-id":"sh1"}`,
+		},
 		{
 			shortcut: "+dropdown-set",
 			sc:       DropdownSet,

shortcuts/sheets/batch_op_dispatch.go

@@ -152,6 +152,12 @@ var batchOpDispatch = map[string]batchOpMapping{
 		return sheetVisibilityInput(fv, t, sid, sn, "unhide")
 	}},
 	"+sheet-set-tab-color": {"modify_workbook_structure", sheetSetTabColorInput},
+	"+sheet-show-gridline": {"modify_workbook_structure", func(fv flagView, t, sid, sn string) (map[string]interface{}, error) {
+		return sheetVisibilityInput(fv, t, sid, sn, "show_gridline")
+	}},
+	"+sheet-hide-gridline": {"modify_workbook_structure", func(fv flagView, t, sid, sn string) (map[string]interface{}, error) {
+		return sheetVisibilityInput(fv, t, sid, sn, "hide_gridline")
+	}},
 
 	// ─── 对象族 CRUD (manage_*_object, operation 区分) ─────────────
 	"+chart-create": {"manage_chart_object", objCreateTranslate(chartSpec)},

shortcuts/sheets/data/flag-defs.json

@@ -1,4 +1,45 @@
 {
+  "+undo": {
+    "risk": "write",
+    "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": "steps",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "Undo the most recent N edits made through this CLI link (default 1); one step = one prior write call",
+        "default": "1"
+      },
+      {
+        "name": "rev",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "Undo anchor: the document revision returned by a prior write's response (`data.revision`). Omit to undo the latest edit. Doubles as an optimistic-concurrency check — rejected if the document has moved past this revision"
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
   "+workbook-info": {
     "risk": "read",
     "flags": [
@@ -413,6 +454,86 @@
       }
     ]
   },
+  "+sheet-hide-gridline": {
+    "risk": "write",
+    "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",
+        "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": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
+  "+sheet-show-gridline": {
+    "risk": "write",
+    "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",
+        "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": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
   "+workbook-create": {
     "risk": "write",
     "flags": [
@@ -452,6 +573,25 @@
           "stdin"
         ]
       },
+      {
+        "name": "sheets",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Typed table payload as JSON (same shape as `+table-put`): a top-level `sheets` array, each item `{name, start_cell?, mode?, header?, allow_overwrite?, columns:[{name,type,format?}], rows:[[...]]}`; column `type` is one of string/number/date/bool. Mutually exclusive with --headers/--values. Creates the workbook, then writes typed type-faithful data (dates land as real dates, numbers keep precision).",
+        "input": [
+          "file",
+          "stdin"
+        ]
+      },
+      {
+        "name": "header-style",
+        "kind": "own",
+        "type": "bool",
+        "required": "optional",
+        "desc": "Bold the typed header row (only with --sheets; default true)",
+        "default": "true"
+      },
       {
         "name": "dry-run",
         "kind": "system",
@@ -513,6 +653,32 @@
       }
     ]
   },
+  "+workbook-import": {
+    "risk": "write",
+    "flags": [
+      {
+        "name": "file",
+        "kind": "own",
+        "type": "string",
+        "required": "required",
+        "desc": "Local file path (.xlsx / .xls / .csv)"
+      },
+      {
+        "name": "folder-token",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Target folder token; imported to the cloud drive root when omitted"
+      },
+      {
+        "name": "name",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Imported spreadsheet name; defaults to the local file name without its extension"
+      }
+    ]
+  },
   "+sheet-info": {
     "risk": "read",
     "flags": [
@@ -1212,19 +1378,65 @@
         "desc": "Skip hidden rows and columns; default `false`"
       },
       {
-        "name": "rows-json",
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": "Print the request path and parameters without executing"
+      }
+    ]
+  },
+  "+table-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": "sheet-id",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Read only this sheet (by id); omit to read all sheets"
+      },
+      {
+        "name": "sheet-name",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Read only this sheet (by name); omit to read all sheets"
+      },
+      {
+        "name": "range",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "A1 range to read; omit to read each sheet current region"
+      },
+      {
+        "name": "no-header",
         "kind": "own",
         "type": "bool",
         "required": "optional",
-        "desc": "Return structured rows ({row_number, values:{col→cell}}) instead of CSV text; default false",
-        "default": "false"
+        "desc": "Treat the first row as data instead of a header (columns get positional names col1, col2, ...)"
       },
       {
         "name": "dry-run",
         "kind": "system",
         "type": "bool",
         "required": "optional",
-        "desc": "Print the request path and parameters without executing"
+        "desc": ""
       }
     ]
   },
@@ -1880,6 +2092,51 @@
       }
     ]
   },
+  "+table-put": {
+    "risk": "write",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet URL to write into (XOR with `--spreadsheet-token`)"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet token to write into (XOR with `--url`)"
+      },
+      {
+        "name": "sheets",
+        "kind": "own",
+        "type": "string",
+        "required": "required",
+        "desc": "Typed table payload as JSON: a top-level `sheets` array, each item `{name, start_cell?, mode?, header?, allow_overwrite?, columns:[{name,type,format?}], rows:[[...]]}`; column `type` is one of string/number/date/bool",
+        "input": [
+          "file",
+          "stdin"
+        ]
+      },
+      {
+        "name": "header-style",
+        "kind": "own",
+        "type": "bool",
+        "required": "optional",
+        "desc": "Bold the header row written from column names (default true)",
+        "default": "true"
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
   "+cells-clear": {
     "risk": "high-risk-write",
     "flags": [

shortcuts/sheets/data/flag-schemas.json

@@ -1787,11 +1787,7 @@
               "data"
             ]
           }
-        },
-        "required": [
-          "position",
-          "size"
-        ]
+        }
       }
     },
     "+chart-update": {
@@ -2826,11 +2822,7 @@
               "data"
             ]
           }
-        },
-        "required": [
-          "position",
-          "size"
-        ]
+        }
       }
     },
     "+cond-format-create": {
@@ -6249,6 +6241,190 @@
           }
         }
       }
+    },
+    "+table-put": {
+      "sheets": {
+        "type": "array",
+        "minItems": 1,
+        "description": "一个或多个子表的 typed 数据，每个数组元素写入一张子表；支持多 DataFrame → 多子表一次写入。可由 pandas DataFrame 经薄 helper 生成（NaN→null、Timestamp→ISO、numpy 标量→原生）。",
+        "items": {
+          "type": "object",
+          "required": [
+            "name",
+            "columns",
+            "rows"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "目标子表名。按名匹配已有子表；不存在则新建该子表。同一次调用内子表名不可重复。"
+            },
+            "start_cell": {
+              "type": "string",
+              "default": "A1",
+              "description": "写入起点单元格（A1 记法，如 \"B2\"），默认 \"A1\"。mode=append 时忽略其行号、仅沿用其列。"
+            },
+            "mode": {
+              "type": "string",
+              "enum": [
+                "overwrite",
+                "append"
+              ],
+              "default": "overwrite",
+              "description": "overwrite（默认）：从 start_cell 起写「表头 + 数据」块；append：把数据追加到子表已有数据下方（默认不重复表头）。"
+            },
+            "header": {
+              "type": "boolean",
+              "description": "是否写一行列名表头。省略时按 mode 取默认：overwrite→true、append→false（避免在已有表头下重复）；显式给值可覆盖。"
+            },
+            "allow_overwrite": {
+              "type": "boolean",
+              "default": true,
+              "description": "为 false 时，若写入会落在非空单元格则拒写以保护原数据（返回 partial_success）。默认 true。"
+            },
+            "columns": {
+              "type": "array",
+              "minItems": 1,
+              "description": "列定义，顺序与 rows 中每行的取值一一对应。",
+              "items": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "type"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "列名（写入表头行的文本）。"
+                  },
+                  "type": {
+                    "type": "string",
+                    "enum": [
+                      "string",
+                      "number",
+                      "date",
+                      "bool"
+                    ],
+                    "description": "列的声明类型，显式声明、不由 CLI 猜测（避免邮编 / 订单号 / 手机号等「像数字的文本」被误判为数字）。string 列由 +table-put 自动套文本格式（number_format `@`），数字样字符串（含前导零，如「00123」）读写两侧都保真——+table-get 读回时仍判为 string、不会塌缩成数字。date 列取 ISO yyyy-mm-dd 字符串，CLI 转成 Excel 序列号 + 日期 number_format（真日期，可排序 / 透视 / 筛选）。"
+                  },
+                  "format": {
+                    "type": "string",
+                    "description": "可选的单元格 number_format，如 \"yyyy-mm-dd\" / \"0.00%\" / \"#,##0.00\"。percent 列的数值尺度由调用方负责（0.0469 配 \"0.00%\"，helper 不自动乘 100）。"
+                  }
+                }
+              }
+            },
+            "rows": {
+              "type": "array",
+              "description": "数据行；每行是一个数组，长度必须等于 columns 数。元素按对应列的类型取值，null 表示空单元格。",
+              "items": {
+                "type": "array",
+                "items": {
+                  "type": [
+                    "string",
+                    "number",
+                    "boolean",
+                    "null"
+                  ],
+                  "description": "单元格值，按所在列的 type 取值（string→文本 / number→数值 / date→ISO yyyy-mm-dd 文本 / bool→布尔）；null 表示空单元格。具体类型由该列在 columns 里声明的 type 决定，故此处仅约束为标量或 null。"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "+workbook-create": {
+      "sheets": {
+        "type": "array",
+        "minItems": 1,
+        "description": "一个或多个子表的 typed 数据，每个数组元素写入一张子表；支持多 DataFrame → 多子表一次写入。可由 pandas DataFrame 经薄 helper 生成（NaN→null、Timestamp→ISO、numpy 标量→原生）。",
+        "items": {
+          "type": "object",
+          "required": [
+            "name",
+            "columns",
+            "rows"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "目标子表名。按名匹配已有子表；不存在则新建该子表。同一次调用内子表名不可重复。"
+            },
+            "start_cell": {
+              "type": "string",
+              "default": "A1",
+              "description": "写入起点单元格（A1 记法，如 \"B2\"），默认 \"A1\"。mode=append 时忽略其行号、仅沿用其列。"
+            },
+            "mode": {
+              "type": "string",
+              "enum": [
+                "overwrite",
+                "append"
+              ],
+              "default": "overwrite",
+              "description": "overwrite（默认）：从 start_cell 起写「表头 + 数据」块；append：把数据追加到子表已有数据下方（默认不重复表头）。"
+            },
+            "header": {
+              "type": "boolean",
+              "description": "是否写一行列名表头。省略时按 mode 取默认：overwrite→true、append→false（避免在已有表头下重复）；显式给值可覆盖。"
+            },
+            "allow_overwrite": {
+              "type": "boolean",
+              "default": true,
+              "description": "为 false 时，若写入会落在非空单元格则拒写以保护原数据（返回 partial_success）。默认 true。"
+            },
+            "columns": {
+              "type": "array",
+              "minItems": 1,
+              "description": "列定义，顺序与 rows 中每行的取值一一对应。",
+              "items": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "type"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "列名（写入表头行的文本）。"
+                  },
+                  "type": {
+                    "type": "string",
+                    "enum": [
+                      "string",
+                      "number",
+                      "date",
+                      "bool"
+                    ],
+                    "description": "列的声明类型，显式声明、不由 CLI 猜测（避免邮编 / 订单号 / 手机号等「像数字的文本」被误判为数字）。string 列由 +table-put 自动套文本格式（number_format `@`），数字样字符串（含前导零，如「00123」）读写两侧都保真——+table-get 读回时仍判为 string、不会塌缩成数字。date 列取 ISO yyyy-mm-dd 字符串，CLI 转成 Excel 序列号 + 日期 number_format（真日期，可排序 / 透视 / 筛选）。"
+                  },
+                  "format": {
+                    "type": "string",
+                    "description": "可选的单元格 number_format，如 \"yyyy-mm-dd\" / \"0.00%\" / \"#,##0.00\"。percent 列的数值尺度由调用方负责（0.0469 配 \"0.00%\"，helper 不自动乘 100）。"
+                  }
+                }
+              }
+            },
+            "rows": {
+              "type": "array",
+              "description": "数据行；每行是一个数组，长度必须等于 columns 数。元素按对应列的类型取值，null 表示空单元格。",
+              "items": {
+                "type": "array",
+                "items": {
+                  "type": [
+                    "string",
+                    "number",
+                    "boolean",
+                    "null"
+                  ],
+                  "description": "单元格值，按所在列的 type 取值（string→文本 / number→数值 / date→ISO yyyy-mm-dd 文本 / bool→布尔）；null 表示空单元格。具体类型由该列在 columns 里声明的 type 决定，故此处仅约束为标量或 null。"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 }

shortcuts/sheets/flag_defs_gen.go

@@ -308,7 +308,6 @@ var flagDefs = map[string]commandDef{
 			{Name: "max-chars", Kind: "own", Type: "int", Required: "optional", Desc: "Safety cap; default 200000", Default: "200000", Hidden: true},
 			{Name: "include-row-prefix", Kind: "own", Type: "bool", Required: "optional", Desc: "Whether to prefix each row with `[row=N]`; default `true`", Default: "true"},
 			{Name: "skip-hidden", Kind: "own", Type: "bool", Required: "optional", Desc: "Skip hidden rows and columns; default `false`"},
-			{Name: "rows-json", Kind: "own", Type: "bool", Required: "optional", Desc: "Return structured rows ({row_number, values:{col→cell}}) instead of CSV text; default false", Default: "false"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional", Desc: "Print the request path and parameters without executing"},
 		},
 	},
@@ -793,6 +792,16 @@ var flagDefs = map[string]commandDef{
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
+	"+sheet-hide-gridline": {
+		Risk: "write",
+		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", 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: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
 	"+sheet-info": {
 		Risk: "read",
 		Flags: []flagDef{
@@ -839,6 +848,16 @@ var flagDefs = map[string]commandDef{
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
+	"+sheet-show-gridline": {
+		Risk: "write",
+		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", 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: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
 	"+sheet-unhide": {
 		Risk: "write",
 		Flags: []flagDef{
@@ -895,6 +914,38 @@ var flagDefs = map[string]commandDef{
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
+	"+table-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: "sheet-id", Kind: "own", Type: "string", Required: "optional", Desc: "Read only this sheet (by id); omit to read all sheets"},
+			{Name: "sheet-name", Kind: "own", Type: "string", Required: "optional", Desc: "Read only this sheet (by name); omit to read all sheets"},
+			{Name: "range", Kind: "own", Type: "string", Required: "optional", Desc: "A1 range to read; omit to read each sheet current region"},
+			{Name: "no-header", Kind: "own", Type: "bool", Required: "optional", Desc: "Treat the first row as data instead of a header (columns get positional names col1, col2, ...)"},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
+	"+table-put": {
+		Risk: "write",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL to write into (XOR with `--spreadsheet-token`)"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token to write into (XOR with `--url`)"},
+			{Name: "sheets", Kind: "own", Type: "string", Required: "required", Desc: "Typed table payload as JSON: a top-level `sheets` array, each item `{name, start_cell?, mode?, header?, allow_overwrite?, columns:[{name,type,format?}], rows:[[...]]}`; column `type` is one of string/number/date/bool", Input: []string{"file", "stdin"}},
+			{Name: "header-style", Kind: "own", Type: "bool", Required: "optional", Desc: "Bold the header row written from column names (default true)", Default: "true"},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
+	"+undo": {
+		Risk: "write",
+		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: "steps", Kind: "own", Type: "int", Required: "optional", Desc: "Undo the most recent N edits made through this CLI link (default 1); one step = one prior write call", Default: "1"},
+			{Name: "rev", Kind: "own", Type: "int", Required: "optional", Desc: "Undo anchor: the document revision returned by a prior write's response (`data.revision`). Omit to undo the latest edit. Doubles as an optimistic-concurrency check — rejected if the document has moved past this revision"},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
 	"+workbook-create": {
 		Risk: "write",
 		Flags: []flagDef{
@@ -902,6 +953,8 @@ var flagDefs = map[string]commandDef{
 			{Name: "folder-token", Kind: "own", Type: "string", Required: "optional", Desc: "Target folder token; placed at the drive root when omitted"},
 			{Name: "headers", Kind: "own", Type: "string", Required: "optional", Desc: "Header row as a JSON array: `[\"Col A\",\"Col B\"]`", Input: []string{"file", "stdin"}},
 			{Name: "values", Kind: "own", Type: "string", Required: "optional", Desc: "Initial data as a 2D JSON array: `[[\"alice\",95]]`", Input: []string{"file", "stdin"}},
+			{Name: "sheets", Kind: "own", Type: "string", Required: "optional", Desc: "Typed table payload as JSON (same shape as `+table-put`): a top-level `sheets` array, each item `{name, start_cell?, mode?, header?, allow_overwrite?, columns:[{name,type,format?}], rows:[[...]]}`; column `type` is one of string/number/date/bool. Mutually exclusive with --headers/--values. Creates the workbook, then writes typed type-faithful data (dates land as real dates, numbers keep precision).", Input: []string{"file", "stdin"}},
+			{Name: "header-style", Kind: "own", Type: "bool", Required: "optional", Desc: "Bold the typed header row (only with --sheets; default true)", Default: "true"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -916,6 +969,14 @@ var flagDefs = map[string]commandDef{
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
+	"+workbook-import": {
+		Risk: "write",
+		Flags: []flagDef{
+			{Name: "file", Kind: "own", Type: "string", Required: "required", Desc: "Local file path (.xlsx / .xls / .csv)"},
+			{Name: "folder-token", Kind: "own", Type: "string", Required: "optional", Desc: "Target folder token; imported to the cloud drive root when omitted"},
+			{Name: "name", Kind: "own", Type: "string", Required: "optional", Desc: "Imported spreadsheet name; defaults to the local file name without its extension"},
+		},
+	},
 	"+workbook-info": {
 		Risk: "read",
 		Flags: []flagDef{

shortcuts/sheets/flag_schemas_gen.go

@@ -32,4 +32,6 @@ var commandsWithSchema = map[string]struct{}{
 	"+range-sort":            {},
 	"+sparkline-create":      {},
 	"+sparkline-update":      {},
+	"+table-put":             {},
+	"+workbook-create":       {},
 }

shortcuts/sheets/lark_sheet_object_crud.go

@@ -688,7 +688,7 @@ func newFloatImageWriteShortcut(command, description, op string, withIDFlag, isH
 			// With a local --image, Execute first uploads the file; surface that
 			// extra step in the preview (mirrors +cells-set-image's dry-run).
 			if img := strings.TrimSpace(runtime.Str("image")); img != "" {
-				manageBody, _ := buildToolBody("manage_float_image_object", input)
+				manageBody, _ := buildToolBody(ToolKindWrite, "manage_float_image_object", input)
 				return common.NewDryRunAPI().
 					POST("/open-apis/drive/v1/medias/upload_all").
 					Desc("upload local image to drive (parent_type=sheet_image)").

shortcuts/sheets/lark_sheet_read_data.go

@@ -5,8 +5,6 @@ package sheets
 
 import (
 	"context"
-	"encoding/csv"
-	"regexp"
 	"strconv"
 	"strings"
 
@@ -164,12 +162,7 @@ var CsvGet = common.Shortcut{
 		if err != nil {
 			return err
 		}
-		switch {
-		case runtime.Bool("rows-json"):
-			// --rows-json reshapes the CSV response into structured rows
-			// ({row_number, values:{col→cell}}); see assembleRowsJSON.
-			out = assembleRowsJSON(out, strings.TrimSpace(runtime.Str("range")))
-		case !runtime.Bool("include-row-prefix"):
+		if !runtime.Bool("include-row-prefix") {
 			out = stripRowPrefixFromCsvOutput(out)
 		}
 		runtime.Out(out, nil)
@@ -219,141 +212,6 @@ func stripRowPrefixFromCsvOutput(out interface{}) interface{} {
 	return m
 }
 
-// rowPrefixRe matches the leading "[row=N] " (or "[row=N],") annotation that
-// the tool prepends to the first physical line of each logical CSV record.
-var rowPrefixRe = regexp.MustCompile(`^\[row=(\d+)\][ ,]?`)
-
-// assembleRowsJSON reshapes the tool's annotated_csv string into structured
-// rows so callers never have to regex-parse "[row=N]" or RFC-4180 CSV by hand:
-//
-//	{
-//	  "range": "A1:K3380",
-//	  "current_region": "...",        // passthrough, if the tool returned it
-//	  "rows": [{"row_number":1,"values":{"A":"姓名", ..., "K":"时间差_分钟"}},
-//	           {"row_number":2,"values":{"A":"张三", ..., "K":"8.5"}}, ...]
-//	}
-//
-// Every logical row is emitted, including the first — no row is assumed to be a
-// header, since sheet data is not always tabular. Each cell is keyed by its
-// column letter (from the tool's col_indices when present, else derived from the
-// requested range's start column). On any parsing trouble it returns the
-// original output unchanged.
-func assembleRowsJSON(out interface{}, requestedRange string) interface{} {
-	m, ok := out.(map[string]interface{})
-	if !ok {
-		return out
-	}
-	csvStr, ok := m["annotated_csv"].(string)
-	if !ok {
-		return out
-	}
-
-	// Group physical lines into logical records by [row=N] boundaries; lines
-	// without a prefix are embedded-newline continuations of the current record.
-	type logicalRow struct {
-		num  int
-		text string
-	}
-	var groups []logicalRow
-	for _, line := range strings.Split(csvStr, "\n") {
-		if mm := rowPrefixRe.FindStringSubmatch(line); mm != nil {
-			n, _ := strconv.Atoi(mm[1])
-			groups = append(groups, logicalRow{num: n, text: line[len(mm[0]):]})
-		} else if len(groups) > 0 {
-			groups[len(groups)-1].text += "\n" + line
-		}
-	}
-	if len(groups) == 0 {
-		return out
-	}
-
-	// Parse every logical row; widest row sets the column count. No row is
-	// singled out as a header — that would assume the data is tabular, which it
-	// often is not. The model reads row 1 like any other row and decides for
-	// itself whether it is a header.
-	parsed := make([][]string, len(groups))
-	maxCols := 0
-	for i, g := range groups {
-		parsed[i] = parseCSVRecord(g.text)
-		if len(parsed[i]) > maxCols {
-			maxCols = len(parsed[i])
-		}
-	}
-	if maxCols == 0 {
-		return out
-	}
-
-	// Column letters key each cell. Prefer the tool's col_indices (authoritative,
-	// length == col_count); otherwise derive from the requested range's start col.
-	letters := coerceStringSlice(m["col_indices"])
-	if len(letters) < maxCols {
-		start := csvStartColIndex(requestedRange)
-		letters = make([]string, maxCols)
-		for j := 0; j < maxCols; j++ {
-			letters[j] = csvColLetter(start + j)
-		}
-	}
-
-	rows := make([]map[string]interface{}, 0, len(groups))
-	for i := range groups {
-		fields := parsed[i]
-		values := make(map[string]interface{}, len(letters))
-		for j := range letters {
-			v := ""
-			if j < len(fields) {
-				v = fields[j]
-			}
-			values[letters[j]] = v
-		}
-		rows = append(rows, map[string]interface{}{
-			"row_number": groups[i].num,
-			"values":     values,
-		})
-	}
-
-	result := map[string]interface{}{}
-	for k, v := range m {
-		result[k] = v
-	}
-	result["range"] = requestedRange
-	result["rows"] = rows
-
-	// Surface the backend's "数据没读全" signal structurally instead of leaving it
-	// buried in warning_message prose. The tool flags it when current_region (the
-	// true data extent) reaches past actual_range (what was actually read) — the
-	// single most important anti-under-read hint. Mirror that same comparison
-	// (regionEndRow > actualEndRow) from the already-passthrough A1 ranges so the
-	// model gets the real data range as a first-class field, never having to
-	// parse it out of prose.
-	if cr, _ := m["current_region"].(string); cr != "" {
-		ar, _ := m["actual_range"].(string)
-		regionEnd := a1EndRow(cr)
-		readEnd := a1EndRow(ar)
-		if regionEnd > 0 && readEnd > 0 && regionEnd > readEnd {
-			result["data_not_fully_read"] = map[string]interface{}{
-				"read_through_row":         readEnd,
-				"data_extends_through_row": regionEnd,
-				"unread_rows":              regionEnd - readEnd,
-				"reread_range":             cr,
-			}
-		}
-	}
-
-	// Drop the fields whose information rows-json fully carries elsewhere:
-	//   - annotated_csv / row_indices / col_indices → reconstructed into
-	//     columns + rows (with integer row_number), losslessly.
-	//   - warning_message → its two halves are both handled: the static
-	//     "[row=N] / col_indices[j]" parse nag is moot once those fields exist,
-	//     and the dynamic "数据没读全" half is now the structured
-	//     data_not_fully_read field above. (Confirmed against the backend's
-	//     get-range-as-csv.ts — warning_message has no other content.)
-	delete(result, "annotated_csv")
-	delete(result, "row_indices")
-	delete(result, "col_indices")
-	delete(result, "warning_message")
-	return result
-}
-
 // a1EndRow extracts the ending row number from an A1 range, e.g. "A1:N51" → 51,
 // "Sheet1!B2:D9" → 9, "C5" → 5. Returns 0 when no row number is present.
 func a1EndRow(rng string) int {
@@ -377,89 +235,6 @@ func a1EndRow(rng string) int {
 	return n
 }
 
-// parseCSVRecord parses a single logical CSV record (which may span multiple
-// physical lines via quoted embedded newlines) into its fields. An empty record
-// yields no fields; a malformed record falls back to a naive comma split so a
-// stray quote never drops a whole row.
-func parseCSVRecord(text string) []string {
-	if strings.TrimSpace(text) == "" {
-		return nil
-	}
-	r := csv.NewReader(strings.NewReader(text))
-	r.FieldsPerRecord = -1
-	fields, err := r.Read()
-	if err != nil {
-		return strings.Split(text, ",")
-	}
-	return fields
-}
-
-// coerceStringSlice returns v as []string when it is a homogeneous []interface{}
-// of strings (the shape of the tool's col_indices), else nil.
-func coerceStringSlice(v interface{}) []string {
-	arr, ok := v.([]interface{})
-	if !ok {
-		return nil
-	}
-	out := make([]string, 0, len(arr))
-	for _, e := range arr {
-		s, ok := e.(string)
-		if !ok {
-			return nil
-		}
-		out = append(out, s)
-	}
-	return out
-}
-
-// csvStartColIndex returns the 0-based column index of a range's start column,
-// e.g. "A1:K3380" → 0, "C5:F9" → 2, "Sheet1!D2" → 3. Unparseable input → 0.
-func csvStartColIndex(rng string) int {
-	rng = strings.TrimSpace(rng)
-	if i := strings.LastIndex(rng, "!"); i >= 0 {
-		rng = rng[i+1:]
-	}
-	var letters strings.Builder
-	for _, c := range rng {
-		if (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') {
-			letters.WriteRune(c)
-			continue
-		}
-		break
-	}
-	if letters.Len() == 0 {
-		return 0
-	}
-	return csvColToIndex(letters.String())
-}
-
-// csvColToIndex converts a column letter to its 0-based index ("A"→0, "K"→10,
-// "AA"→26). Non-letter input → -1.
-func csvColToIndex(s string) int {
-	n := 0
-	for _, c := range strings.ToUpper(s) {
-		if c < 'A' || c > 'Z' {
-			break
-		}
-		n = n*26 + int(c-'A'+1)
-	}
-	return n - 1
-}
-
-// csvColLetter converts a 0-based column index back to its letter (0→"A",
-// 25→"Z", 26→"AA"). Negative input → "".
-func csvColLetter(idx int) string {
-	if idx < 0 {
-		return ""
-	}
-	var b []byte
-	for idx >= 0 {
-		b = append([]byte{byte('A' + idx%26)}, b...)
-		idx = idx/26 - 1
-	}
-	return string(b)
-}
-
 // DropdownGet wraps get_cell_ranges scoped to data_validation: read the
 // dropdown configuration on a range. Aligned with its sibling +cells-get
 // — sheet selection is via --sheet-id / --sheet-name (XOR), and --range

shortcuts/sheets/lark_sheet_read_data_test.go

@@ -63,20 +63,6 @@ func TestReadDataShortcuts_DryRun(t *testing.T) {
 				"value_render_option": "formatted_value",
 			},
 		},
-		{
-			// --rows-json is post-processing on +csv-get's response; it must
-			// NOT leak into the get_range_as_csv input.
-			name:     "+csv-get --rows-json builds the same input (flag is post-process)",
-			sc:       CsvGet,
-			args:     []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A1:C10", "--rows-json"},
-			toolName: "get_range_as_csv",
-			wantInput: map[string]interface{}{
-				"excel_id": testToken,
-				"sheet_id": testSheetID,
-				"range":    "A1:C10",
-				"max_rows": float64(unboundedReadLimit),
-			},
-		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -179,113 +165,3 @@ func TestCsvGet_StripRowPrefix(t *testing.T) {
 		t.Errorf("other field corrupted: %v", out["other"])
 	}
 }
-
-// TestAssembleRowsJSON covers the --rows-json reshaping: every logical row
-// emitted (no header singled out), integer row_number, column-letter keyed
-// values, embedded newlines inside quoted fields, and current_region passthrough.
-func TestAssembleRowsJSON(t *testing.T) {
-	t.Parallel()
-	in := map[string]interface{}{
-		"annotated_csv":   "[row=1] 姓名,备注,时间差_分钟\n[row=2] 张三,\"line1\nline2\",8.5\n[row=3] 李四,ok,3",
-		"current_region":  "A1:C3",
-		"col_indices":     []interface{}{"A", "B", "C"},
-		"row_indices":     []interface{}{1, 2, 3},
-		"warning_message": "①定位行号…②定位列字母…",
-	}
-	out, ok := assembleRowsJSON(in, "A1:C3").(map[string]interface{})
-	if !ok {
-		t.Fatalf("assembleRowsJSON did not return a map")
-	}
-
-	// Fields whose info rows-json carries elsewhere are dropped (annotated_csv /
-	// indices → rows; warning_message → moot static nag + structured
-	// data_not_fully_read). Unrelated metadata like current_region is preserved.
-	if _, exists := out["annotated_csv"]; exists {
-		t.Errorf("annotated_csv should be dropped")
-	}
-	if _, exists := out["col_indices"]; exists {
-		t.Errorf("col_indices should be dropped")
-	}
-	if _, exists := out["warning_message"]; exists {
-		t.Errorf("warning_message should be dropped in rows-json mode")
-	}
-	if _, exists := out["columns"]; exists {
-		t.Errorf("columns field should not exist (no header assumption)")
-	}
-	if out["current_region"] != "A1:C3" {
-		t.Errorf("current_region passthrough lost: %v", out["current_region"])
-	}
-
-	rows, _ := out["rows"].([]map[string]interface{})
-	if len(rows) != 3 {
-		t.Fatalf("want all 3 rows (incl. row 1), got %d: %+v", len(rows), rows)
-	}
-	// Row 1 is emitted as a normal row, not consumed as a header.
-	if rows[0]["row_number"].(int) != 1 {
-		t.Errorf("first row_number = %v, want 1", rows[0]["row_number"])
-	}
-	if v := rows[0]["values"].(map[string]interface{}); v["A"] != "姓名" || v["C"] != "时间差_分钟" {
-		t.Errorf("row 1 values wrong: %+v", v)
-	}
-	// Row 2 keeps its embedded newline inside a single cell.
-	v1 := rows[1]["values"].(map[string]interface{})
-	if rows[1]["row_number"].(int) != 2 || v1["A"] != "张三" || v1["B"] != "line1\nline2" || v1["C"] != "8.5" {
-		t.Errorf("row 2 wrong (embedded newline?): %+v", rows[1])
-	}
-}
-
-// TestAssembleRowsJSON_DerivedLetters verifies cell letters are derived from the
-// range start when the tool omits col_indices (e.g. a C-anchored read).
-func TestAssembleRowsJSON_DerivedLetters(t *testing.T) {
-	t.Parallel()
-	in := map[string]interface{}{
-		"annotated_csv": "[row=5] h1,h2\n[row=6] a,b",
-	}
-	out := assembleRowsJSON(in, "C5:D6").(map[string]interface{})
-	rows := out["rows"].([]map[string]interface{})
-	if len(rows) != 2 {
-		t.Fatalf("want 2 rows, got %d", len(rows))
-	}
-	if rows[0]["row_number"].(int) != 5 {
-		t.Errorf("first row_number = %v, want 5", rows[0]["row_number"])
-	}
-	if v := rows[0]["values"].(map[string]interface{}); v["C"] != "h1" || v["D"] != "h2" {
-		t.Errorf("derived-letter values wrong: %+v", v)
-	}
-	if v := rows[1]["values"].(map[string]interface{}); v["C"] != "a" || v["D"] != "b" {
-		t.Errorf("row 6 values wrong: %+v", v)
-	}
-}
-
-// TestAssembleRowsJSON_DataNotFullyRead verifies the structured under-read hint:
-// when current_region extends past actual_range, rows-json surfaces the true data
-// range as a first-class field (mirroring the backend's prose warning).
-func TestAssembleRowsJSON_DataNotFullyRead(t *testing.T) {
-	t.Parallel()
-	// Read only A1:D2, but the data region reaches D4 → 2 rows unread.
-	in := map[string]interface{}{
-		"annotated_csv":  "[row=1] 序号,姓名\n[row=2] 101,张三",
-		"actual_range":   "A1:D2",
-		"current_region": "A1:D4",
-	}
-	out := assembleRowsJSON(in, "A1:D2").(map[string]interface{})
-	hint, ok := out["data_not_fully_read"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("data_not_fully_read missing; out=%+v", out)
-	}
-	if hint["read_through_row"] != 2 || hint["data_extends_through_row"] != 4 ||
-		hint["unread_rows"] != 2 || hint["reread_range"] != "A1:D4" {
-		t.Errorf("data_not_fully_read wrong: %+v", hint)
-	}
-
-	// Fully-read case: no hint emitted.
-	in2 := map[string]interface{}{
-		"annotated_csv":  "[row=1] 序号,姓名\n[row=2] 101,张三",
-		"actual_range":   "A1:D2",
-		"current_region": "A1:D2",
-	}
-	out2 := assembleRowsJSON(in2, "A1:D2").(map[string]interface{})
-	if _, exists := out2["data_not_fully_read"]; exists {
-		t.Errorf("data_not_fully_read should be absent when fully read")
-	}
-}

shortcuts/sheets/lark_sheet_table_io_test.go

@@ -0,0 +1,991 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+// ─── pure helpers: date serial, typed cell mapping ────────────────────
+
+func TestTablePut_IsoDateToSerial(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		in   string
+		want int
+		ok   bool
+	}{
+		{"2024-01-15", 45306, true}, // the empirically verified anchor
+		{"2024-01-01", 45292, true},
+		{"2024-02-29", 45351, true}, // 2024 is a leap year
+		{"1899-12-31", 1, true},     // one day after the epoch
+		{"not-a-date", 0, false},
+		{"2024/01/15", 0, false}, // wrong separator
+	}
+	for _, tt := range cases {
+		got, err := isoDateToSerial(tt.in)
+		if tt.ok {
+			if err != nil {
+				t.Errorf("isoDateToSerial(%q) unexpected error: %v", tt.in, err)
+				continue
+			}
+			if got != tt.want {
+				t.Errorf("isoDateToSerial(%q) = %d, want %d", tt.in, got, tt.want)
+			}
+		} else if err == nil {
+			t.Errorf("isoDateToSerial(%q) = %d, want error", tt.in, got)
+		}
+	}
+}
+
+func TestTablePut_BuildTypedCell(t *testing.T) {
+	t.Parallel()
+
+	t.Run("string keeps literal + text format so digit-like ids survive read-back", func(t *testing.T) {
+		t.Parallel()
+		cell, err := buildTypedCell(&tableColumnSpec{Name: "id", Type: "string"}, "00123")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if cell["value"] != "00123" {
+			t.Errorf("value = %#v, want \"00123\"", cell["value"])
+		}
+		if nf := numberFormatOf(cell); nf != "@" {
+			t.Errorf("number_format = %q, want @ (text format so +table-get infers string, not number)", nf)
+		}
+	})
+
+	t.Run("string stringifies a json.Number without scientific notation", func(t *testing.T) {
+		t.Parallel()
+		cell, _ := buildTypedCell(&tableColumnSpec{Name: "code", Type: "string"}, json.Number("123456789012345"))
+		if cell["value"] != "123456789012345" {
+			t.Errorf("value = %#v, want literal digits", cell["value"])
+		}
+	})
+
+	t.Run("number preserves json.Number", func(t *testing.T) {
+		t.Parallel()
+		cell, err := buildTypedCell(&tableColumnSpec{Name: "amt", Type: "number", Format: "#,##0"}, json.Number("259874"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if n, ok := cell["value"].(json.Number); !ok || n.String() != "259874" {
+			t.Errorf("value = %#v, want json.Number 259874", cell["value"])
+		}
+		if nf := numberFormatOf(cell); nf != "#,##0" {
+			t.Errorf("number_format = %q, want #,##0", nf)
+		}
+	})
+
+	t.Run("date converts to serial + default format", func(t *testing.T) {
+		t.Parallel()
+		cell, err := buildTypedCell(&tableColumnSpec{Name: "d", Type: "date"}, "2024-01-15")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if cell["value"] != 45306 {
+			t.Errorf("value = %#v, want serial 45306", cell["value"])
+		}
+		if nf := numberFormatOf(cell); nf != "yyyy-mm-dd" {
+			t.Errorf("number_format = %q, want default yyyy-mm-dd", nf)
+		}
+	})
+
+	t.Run("date honors explicit format", func(t *testing.T) {
+		t.Parallel()
+		cell, _ := buildTypedCell(&tableColumnSpec{Name: "d", Type: "date", Format: "yyyy-mm"}, "2024-01-15")
+		if nf := numberFormatOf(cell); nf != "yyyy-mm" {
+			t.Errorf("number_format = %q, want yyyy-mm", nf)
+		}
+	})
+
+	t.Run("bool maps to boolean", func(t *testing.T) {
+		t.Parallel()
+		cell, err := buildTypedCell(&tableColumnSpec{Name: "b", Type: "bool"}, true)
+		if err != nil || cell["value"] != true {
+			t.Errorf("value = %#v (err=%v), want true", cell["value"], err)
+		}
+	})
+
+	t.Run("null is an empty cell that still carries format", func(t *testing.T) {
+		t.Parallel()
+		cell, err := buildTypedCell(&tableColumnSpec{Name: "d", Type: "date"}, nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, has := cell["value"]; has {
+			t.Errorf("null cell should have no value: %#v", cell)
+		}
+		if nf := numberFormatOf(cell); nf != "yyyy-mm-dd" {
+			t.Errorf("null date cell should still carry format, got %q", nf)
+		}
+	})
+
+	t.Run("type mismatches are rejected", func(t *testing.T) {
+		t.Parallel()
+		if _, err := buildTypedCell(&tableColumnSpec{Type: "number"}, "abc"); err == nil {
+			t.Error("number column accepting a string should error")
+		}
+		if _, err := buildTypedCell(&tableColumnSpec{Type: "date"}, json.Number("1")); err == nil {
+			t.Error("date column accepting a number should error")
+		}
+		if _, err := buildTypedCell(&tableColumnSpec{Type: "bool"}, "true"); err == nil {
+			t.Error("bool column accepting a string should error")
+		}
+	})
+}
+
+// numberFormatOf digs the number_format out of a built cell's cell_styles, or
+// "" when absent.
+func numberFormatOf(cell map[string]interface{}) string {
+	styles, ok := cell["cell_styles"].(map[string]interface{})
+	if !ok {
+		return ""
+	}
+	nf, _ := styles["number_format"].(string)
+	return nf
+}
+
+// ─── payload validation ───────────────────────────────────────────────
+
+func TestTablePut_PayloadValidation(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name string
+		json string
+		want string
+	}{
+		{"empty sheets", `{"sheets":[]}`, "at least one sheet"},
+		{"missing name", `{"sheets":[{"columns":[{"name":"a","type":"string"}],"rows":[]}]}`, "name is required"},
+		{"duplicate name", `{"sheets":[{"name":"S","columns":[{"name":"a","type":"string"}],"rows":[]},{"name":"S","columns":[{"name":"a","type":"string"}],"rows":[]}]}`, "duplicate sheet name"},
+		{"no columns", `{"sheets":[{"name":"S","columns":[],"rows":[]}]}`, "columns must be non-empty"},
+		{"bad column type", `{"sheets":[{"name":"S","columns":[{"name":"a","type":"timestamp"}],"rows":[]}]}`, "invalid type"},
+		{"column missing name", `{"sheets":[{"name":"S","columns":[{"type":"string"}],"rows":[]}]}`, "columns[0].name is required"},
+		{"row width mismatch", `{"sheets":[{"name":"S","columns":[{"name":"a","type":"string"},{"name":"b","type":"string"}],"rows":[["x"]]}]}`, "column count"},
+		{"bad start_cell", `{"sheets":[{"name":"S","start_cell":"A","columns":[{"name":"a","type":"string"}],"rows":[]}]}`, "start_cell"},
+		{"bad date value", `{"sheets":[{"name":"S","columns":[{"name":"d","type":"date"}],"rows":[["2025/03/31"]]}]}`, "must be ISO"},
+		{"number expects numeric", `{"sheets":[{"name":"S","columns":[{"name":"n","type":"number"}],"rows":[["abc"]]}]}`, "number expects"},
+		{"invalid json", `{not json`, "invalid JSON"},
+	}
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			_, err := parseTablePutPayload(stubFlagView{"sheets": tt.json})
+			if err == nil || !strings.Contains(err.Error(), tt.want) {
+				t.Errorf("want error containing %q, got %v", tt.want, err)
+			}
+		})
+	}
+}
+
+// stubFlagView is a minimal flagView backed by a map, for unit-testing the
+// payload parser without a cobra command.
+type stubFlagView map[string]string
+
+func (s stubFlagView) Str(name string) string        { return s[name] }
+func (s stubFlagView) Bool(name string) bool         { return s[name] == "true" }
+func (s stubFlagView) Int(name string) int           { return 0 }
+func (s stubFlagView) Float64(name string) float64   { return 0 }
+func (s stubFlagView) Changed(name string) bool      { _, ok := s[name]; return ok }
+func (s stubFlagView) StrArray(name string) []string { return nil }
+func (s stubFlagView) StrSlice(name string) []string { return nil }
+func (s stubFlagView) Command() string               { return "+table-put" }
+
+// ─── dry-run: create + write rendering ────────────────────────────────
+
+const tablePutSheetsJSON = `{"sheets":[{"name":"月度","columns":[` +
+	`{"name":"门店","type":"string"},` +
+	`{"name":"月份","type":"date","format":"yyyy-mm"},` +
+	`{"name":"销售额","type":"number","format":"#,##0"}` +
+	`],"rows":[["北京","2024-01-15",259874]]}]}`
+
+func TestTablePut_DryRunWrite(t *testing.T) {
+	t.Parallel()
+	calls := parseDryRunAPI(t, TablePut, []string{"--url", testURL, "--sheets", tablePutSheetsJSON})
+	if len(calls) != 1 {
+		t.Fatalf("api calls = %d, want 1 (set_cell_range only)", len(calls))
+	}
+	body, _ := calls[0].(map[string]interface{})["body"].(map[string]interface{})
+	input := decodeToolInput(t, body, "set_cell_range")
+	if input["excel_id"] != testToken {
+		t.Errorf("excel_id = %v, want %s", input["excel_id"], testToken)
+	}
+	if input["sheet_name"] != "月度" {
+		t.Errorf("sheet_name = %v, want 月度", input["sheet_name"])
+	}
+	if input["range"] != "A1:C2" {
+		t.Errorf("range = %v, want A1:C2 (1 header + 1 data row × 3 cols)", input["range"])
+	}
+	rows := input["cells"].([]interface{})
+	header := rows[0].([]interface{})
+	if hs := cellStyles(header[0]); hs["font_weight"] != "bold" {
+		t.Errorf("header cell should be bold, got %#v", header[0])
+	}
+	data := rows[1].([]interface{})
+	// 月份 (date) → serial 45306, number_format yyyy-mm
+	if v := cellValue(data[1]); v != float64(45306) {
+		t.Errorf("date cell value = %#v, want 45306 serial", v)
+	}
+	if nf := cellStyles(data[1])["number_format"]; nf != "yyyy-mm" {
+		t.Errorf("date number_format = %v, want yyyy-mm", nf)
+	}
+	// 销售额 (number) → 259874 preserved
+	if v := cellValue(data[2]); v != float64(259874) {
+		t.Errorf("number cell value = %#v, want 259874", v)
+	}
+}
+
+func cellValue(c interface{}) interface{} {
+	m, _ := c.(map[string]interface{})
+	return m["value"]
+}
+
+func cellStyles(c interface{}) map[string]interface{} {
+	m, _ := c.(map[string]interface{})
+	s, _ := m["cell_styles"].(map[string]interface{})
+	return s
+}
+
+// ─── validation through the cobra surface ─────────────────────────────
+
+func TestTablePut_Validation(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "missing spreadsheet locator rejected",
+			args: []string{"--sheets", tablePutSheetsJSON},
+			want: "at least one",
+		},
+		{
+			name: "url and token are mutually exclusive",
+			args: []string{"--url", testURL, "--spreadsheet-token", testToken, "--sheets", tablePutSheetsJSON},
+			want: "mutually exclusive",
+		},
+		{
+			name: "bad column type rejected",
+			args: []string{"--url", testURL, "--sheets", `{"sheets":[{"name":"S","columns":[{"name":"a","type":"foo"}],"rows":[]}]}`},
+			want: "invalid type",
+		},
+		{
+			name: "row width mismatch rejected",
+			args: []string{"--url", testURL, "--sheets", `{"sheets":[{"name":"S","columns":[{"name":"a","type":"string"},{"name":"b","type":"string"}],"rows":[["only-one"]]}]}`},
+			want: "column count",
+		},
+	}
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			stdout, stderr, err := runShortcutCapturingErr(t, TablePut, append(tt.args, "--dry-run"))
+			if err == nil {
+				t.Fatalf("expected validation error; got nil. stdout=%s stderr=%s", stdout, stderr)
+			}
+			if !strings.Contains(stdout+stderr+err.Error(), tt.want) {
+				t.Errorf("error missing %q; got=%s|%s|%v", tt.want, stdout, stderr, err)
+			}
+		})
+	}
+}
+
+// ─── execute paths with stubbed tools ─────────────────────────────────
+
+// TestTablePut_ExecuteWrite drives the write path: a structure read maps the
+// existing sheet by name, then a set_cell_range write fills it.
+func TestTablePut_ExecuteWrite(t *testing.T) {
+	t.Parallel()
+	structure := toolOutputStub(testToken, "read", `{"sheets":[{"sheet_id":"`+testSheetID+`","sheet_name":"数据","index":0}]}`)
+	write := toolOutputStub(testToken, "write", `{"updated_cells_count":2}`)
+	out, err := runShortcutWithStubs(t, TablePut,
+		[]string{"--url", testURL, "--sheets",
+			`{"sheets":[{"name":"数据","columns":[{"name":"a","type":"string"},{"name":"b","type":"number"}],"rows":[["x",1]]}]}`},
+		structure, write)
+	if err != nil {
+		t.Fatalf("execute failed: %v\nout=%s", err, out)
+	}
+	data := decodeEnvelopeData(t, out)
+	sheets, _ := data["sheets"].([]interface{})
+	if len(sheets) != 1 {
+		t.Fatalf("result sheets = %d, want 1: %#v", len(sheets), data)
+	}
+	s0, _ := sheets[0].(map[string]interface{})
+	if s0["name"] != "数据" || s0["sheet_id"] != testSheetID {
+		t.Errorf("sheet summary = %#v, want name=数据 sheet_id=%s", s0, testSheetID)
+	}
+	if s0["range"] != "A1:B2" {
+		t.Errorf("range = %v, want A1:B2", s0["range"])
+	}
+}
+
+// TestTablePut_ExecuteWriteCreatesMissingSheet covers the branch where the
+// named sheet does not yet exist: a create precedes the write.
+func TestTablePut_ExecuteWriteCreatesMissingSheet(t *testing.T) {
+	t.Parallel()
+	// First structure read sees only "Sheet1"; the payload targets "新表", so
+	// createSheet runs, and the follow-up read (FIFO: second stub) resolves the
+	// newly created sheet's id.
+	structBefore := toolOutputStub(testToken, "read", `{"sheets":[{"sheet_id":"`+testSheetID+`","sheet_name":"Sheet1","index":0}]}`)
+	structAfter := toolOutputStub(testToken, "read", `{"sheets":[{"sheet_id":"`+testSheetID+`","sheet_name":"Sheet1","index":0},{"sheet_id":"`+testSheetID2+`","sheet_name":"新表","index":1}]}`)
+	write := toolOutputStub(testToken, "write", `{"ok":true}`)
+	write.Reusable = true // modify_workbook_structure create + set_cell_range
+	out, err := runShortcutWithStubs(t, TablePut,
+		[]string{"--url", testURL, "--sheets",
+			`{"sheets":[{"name":"新表","columns":[{"name":"a","type":"string"}],"rows":[["x"]]}]}`},
+		structBefore, structAfter, write)
+	if err != nil {
+		t.Fatalf("execute failed: %v\nout=%s", err, out)
+	}
+	data := decodeEnvelopeData(t, out)
+	sheets, _ := data["sheets"].([]interface{})
+	if len(sheets) != 1 {
+		t.Fatalf("result sheets = %d, want 1", len(sheets))
+	}
+	if s0, _ := sheets[0].(map[string]interface{}); s0["sheet_id"] != testSheetID2 {
+		t.Errorf("created sheet id = %v, want %s", s0["sheet_id"], testSheetID2)
+	}
+}
+
+// TestTablePut_SheetCreateDims checks new-sheet sizing: small tables keep the
+// 20×200 floor (unchanged behavior), wide/long tables grow past it (the fix for
+// set_cell_range "exceeds sheet bounds"), and start_cell offset + header row are
+// accounted for, with columns clamped to the backend's 200 ceiling.
+func TestTablePut_SheetCreateDims(t *testing.T) {
+	t.Parallel()
+	bp := func(b bool) *bool { return &b }
+	cols := func(n int) []tableColumnSpec { return make([]tableColumnSpec, n) }
+	rows := func(n int) [][]interface{} { return make([][]interface{}, n) }
+	cases := []struct {
+		name               string
+		spec               tableSheetSpec
+		wantRows, wantCols int
+	}{
+		{"small table keeps 20x200 floor", tableSheetSpec{Columns: cols(3), Rows: rows(5)}, 200, 20},
+		{"wide table grows columns", tableSheetSpec{Columns: cols(37), Rows: rows(22)}, 200, 37},
+		{"long table grows rows", tableSheetSpec{Columns: cols(3), Rows: rows(500)}, 501, 20},
+		{"start_cell offset adds to both", tableSheetSpec{StartCell: "C5", Columns: cols(40), Rows: rows(5)}, 200, 42},
+		{"header:false drops the header row", tableSheetSpec{Header: bp(false), Columns: cols(3), Rows: rows(500)}, 500, 20},
+		{"columns clamp at backend max 200", tableSheetSpec{Columns: cols(250), Rows: rows(5)}, 200, 200},
+	}
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			gotRows, gotCols := sheetCreateDims(&tt.spec)
+			if gotRows != tt.wantRows || gotCols != tt.wantCols {
+				t.Errorf("sheetCreateDims = (%d rows, %d cols), want (%d, %d)", gotRows, gotCols, tt.wantRows, tt.wantCols)
+			}
+		})
+	}
+}
+
+// TestTablePut_ExecuteCreatesWideSheetWithDims is the regression test for the
+// wide-table bug: a 25-column payload targeting a not-yet-existing sheet must
+// create it with 25 columns (past the 20-column default) so the follow-up
+// set_cell_range fits instead of failing with "exceeds sheet bounds".
+func TestTablePut_ExecuteCreatesWideSheetWithDims(t *testing.T) {
+	t.Parallel()
+	structBefore := toolOutputStub(testToken, "read", `{"sheets":[{"sheet_id":"`+testSheetID+`","sheet_name":"Sheet1","index":0}]}`)
+	createStub := toolOutputStub(testToken, "write", `{"ok":true}`) // modify_workbook_structure create
+	structAfter := toolOutputStub(testToken, "read", `{"sheets":[{"sheet_id":"`+testSheetID+`","sheet_name":"Sheet1","index":0},{"sheet_id":"`+testSheetID2+`","sheet_name":"宽表","index":1}]}`)
+	writeStub := toolOutputStub(testToken, "write", `{"ok":true}`) // set_cell_range
+	const n = 25
+	cols := strings.TrimRight(strings.Repeat(`{"name":"c","type":"string"},`, n), ",")
+	vals := strings.TrimRight(strings.Repeat(`"x",`, n), ",")
+	payload := `{"sheets":[{"name":"宽表","columns":[` + cols + `],"rows":[[` + vals + `]]}]}`
+	out, err := runShortcutWithStubs(t, TablePut,
+		[]string{"--url", testURL, "--sheets", payload},
+		structBefore, createStub, structAfter, writeStub)
+	if err != nil {
+		t.Fatalf("execute failed: %v\nout=%s", err, out)
+	}
+	var wire map[string]interface{}
+	if err := json.Unmarshal(createStub.CapturedBody, &wire); err != nil {
+		t.Fatalf("decode create body: %v", err)
+	}
+	var input map[string]interface{}
+	if err := json.Unmarshal([]byte(wire["input"].(string)), &input); err != nil {
+		t.Fatalf("decode create tool input: %v", err)
+	}
+	if input["operation"] != "create" {
+		t.Fatalf("first write should be the create op, got %#v", input["operation"])
+	}
+	if input["columns"] != float64(n) {
+		t.Errorf("create columns = %#v, want %d (sized to the wide payload)", input["columns"], n)
+	}
+	if input["rows"] != float64(200) {
+		t.Errorf("create rows = %#v, want 200 (floor)", input["rows"])
+	}
+}
+
+// TestTablePut_ExecutePartialFailure covers the partial-success error path:
+// a set_cell_range write fails mid-import and the structured error surfaces.
+// TestTablePut_ExecuteTotalFailure: a single sheet whose write fails landed
+// nothing — it must be a plain failure, NOT partial_success.
+func TestTablePut_ExecuteTotalFailure(t *testing.T) {
+	t.Parallel()
+	structure := toolOutputStub(testToken, "read", `{"sheets":[{"sheet_id":"`+testSheetID+`","sheet_name":"数据","index":0}]}`)
+	writeErr := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/sheet_ai/v2/spreadsheets/" + testToken + "/tools/invoke_write",
+		Body:   map[string]interface{}{"code": 1254000, "msg": "boom"},
+	}
+	out, err := runShortcutWithStubs(t, TablePut,
+		[]string{"--url", testURL, "--sheets",
+			`{"sheets":[{"name":"数据","columns":[{"name":"a","type":"string"}],"rows":[["x"]]}]}`},
+		structure, writeErr)
+	if err == nil {
+		t.Fatalf("expected failure; got nil. out=%s", out)
+	}
+	if strings.Contains(err.Error(), "partially applied") || strings.Contains(out, "partially applied") {
+		t.Errorf("single-sheet failure must NOT be partial_success; got err=%v out=%s", err, out)
+	}
+	if !strings.Contains(err.Error(), "failed") && !strings.Contains(out, "no sheets were written") {
+		t.Errorf("expected plain-failure message; got err=%v out=%s", err, out)
+	}
+}
+
+// TestTablePut_ExecutePartialFailure: first sheet's write lands, second fails →
+// partial_success carrying the first sheet in written_sheets.
+func TestTablePut_ExecutePartialFailure(t *testing.T) {
+	t.Parallel()
+	structure := toolOutputStub(testToken, "read",
+		`{"sheets":[{"sheet_id":"`+testSheetID+`","sheet_name":"汇总","index":0},{"sheet_id":"`+testSheetID2+`","sheet_name":"明细","index":1}]}`)
+	writeOK := toolOutputStub(testToken, "write", `{"updated_cells_count":2}`)
+	writeErr := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/sheet_ai/v2/spreadsheets/" + testToken + "/tools/invoke_write",
+		Body:   map[string]interface{}{"code": 1254000, "msg": "boom"},
+	}
+	out, err := runShortcutWithStubs(t, TablePut,
+		[]string{"--url", testURL, "--sheets",
+			`{"sheets":[{"name":"汇总","columns":[{"name":"a","type":"string"}],"rows":[["x"]]},{"name":"明细","columns":[{"name":"a","type":"string"}],"rows":[["y"]]}]}`},
+		structure, writeOK, writeErr)
+	if err == nil {
+		t.Fatalf("expected partial-success error; got nil. out=%s", out)
+	}
+	if !strings.Contains(err.Error(), "partially applied") && !strings.Contains(out, "partially applied") {
+		t.Errorf("expected partial_success (not total failure); got err=%v out=%s", err, out)
+	}
+	// The failing sheet is named in the message; the written one lives in the
+	// structured written_sheets detail.
+	if !strings.Contains(err.Error(), "明细") {
+		t.Errorf("partial_success should name the failed sheet 明细; got err=%v", err)
+	}
+}
+
+// ─── +workbook-create typed --sheets path ─────────────────────────────
+
+// TestWorkbookCreate_TypedMutualExclusion locks the Validate contract: the typed
+// --sheets entry can't be combined with the untyped --headers/--values.
+func TestWorkbookCreate_TypedMutualExclusion(t *testing.T) {
+	t.Parallel()
+	typed := `{"sheets":[{"name":"S","columns":[{"name":"a","type":"string"}],"rows":[["x"]]}]}`
+	for _, tc := range []struct {
+		name string
+		args []string
+	}{
+		{"sheets+headers", []string{"--title", "X", "--sheets", typed, "--headers", `["a"]`}},
+		{"sheets+values", []string{"--title", "X", "--sheets", typed, "--values", `[["x"]]`}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			_, stderr, err := runShortcutCapturingErr(t, WorkbookCreate, tc.args)
+			if err == nil {
+				t.Fatalf("expected mutual-exclusion error; got nil (stderr=%s)", stderr)
+			}
+			if !strings.Contains(err.Error(), "mutually exclusive") {
+				t.Errorf("want 'mutually exclusive' error; got %v", err)
+			}
+		})
+	}
+}
+
+// TestWorkbookCreate_EmptySheetsErrors locks the fix for an explicitly-given but
+// empty --sheets (e.g. empty stdin / file): it must error, not silently fall
+// through to creating an empty workbook.
+func TestWorkbookCreate_EmptySheetsErrors(t *testing.T) {
+	t.Parallel()
+	_, stderr, err := runShortcutCapturingErr(t, WorkbookCreate, []string{"--title", "X", "--sheets", ""})
+	if err == nil {
+		t.Fatalf("expected error for empty --sheets; got nil (stderr=%s)", stderr)
+	}
+	if !strings.Contains(err.Error(), "empty") {
+		t.Errorf("want 'empty' error; got %v", err)
+	}
+}
+
+// TestWorkbookCreate_TypedAdoptsDefaultSheet covers the one-step typed create:
+// the new workbook's default sheet is renamed to the first payload sheet's name
+// and reused (no empty Sheet1 left behind), then written type-faithfully (the
+// date lands as an Excel serial, not text).
+func TestWorkbookCreate_TypedAdoptsDefaultSheet(t *testing.T) {
+	t.Parallel()
+	create := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/sheets/v3/spreadsheets",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"spreadsheet": map[string]interface{}{"spreadsheet_token": "shtTYPED", "title": "Demo"},
+			},
+		},
+	}
+	// lookupFirstSheetID and writeTypedSheets' listSheetIDsByName both read the
+	// structure; one reusable stub serves both, reporting only the default sheet.
+	structure := toolOutputStub("shtTYPED", "read", `{"sheets":[{"sheet_id":"shtDef","sheet_name":"Sheet1","index":0}]}`)
+	structure.Reusable = true
+	rename := &httpmock.Stub{
+		Method:     "POST",
+		URL:        "/open-apis/sheet_ai/v2/spreadsheets/shtTYPED/tools/invoke_write",
+		BodyFilter: func(b []byte) bool { return strings.Contains(string(b), "modify_workbook_structure") },
+		Body:       map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"output": `{"ok":true}`}},
+	}
+	write := &httpmock.Stub{
+		Method:     "POST",
+		URL:        "/open-apis/sheet_ai/v2/spreadsheets/shtTYPED/tools/invoke_write",
+		BodyFilter: func(b []byte) bool { return strings.Contains(string(b), "set_cell_range") },
+		Body:       map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"output": `{"updated_cells_count":4}`}},
+	}
+	out, err := runShortcutWithStubs(t, WorkbookCreate, []string{
+		"--title", "Demo",
+		"--sheets", `{"sheets":[{"name":"Sales","columns":[{"name":"d","type":"date"},{"name":"amt","type":"number"}],"rows":[["2024-01-15",1234.5]]}]}`,
+	}, create, structure, rename, write)
+	if err != nil {
+		t.Fatalf("typed create failed: %v\nout=%s", err, out)
+	}
+	data := decodeEnvelopeData(t, out)
+	if ss, _ := data["spreadsheet"].(map[string]interface{}); ss["spreadsheet_token"] != "shtTYPED" {
+		t.Errorf("spreadsheet_token = %v, want shtTYPED", data["spreadsheet"])
+	}
+	if sheets, _ := data["sheets"].([]interface{}); len(sheets) != 1 {
+		t.Fatalf("want 1 written sheet, got %#v", data["sheets"])
+	}
+	// Default sheet adopted: rename targets shtDef → "Sales" (no new sheet, no
+	// stray Sheet1).
+	renameInput := decodeToolInput(t, decodeRawEnvelopeBody(t, rename.CapturedBody), "modify_workbook_structure")
+	if renameInput["operation"] != "rename" || renameInput["sheet_id"] != "shtDef" || renameInput["new_name"] != "Sales" {
+		t.Errorf("rename should adopt default shtDef→Sales; got %#v", renameInput)
+	}
+	// The data write carries the date as serial 45306, proving the type-faithful path.
+	writeInput := decodeToolInput(t, decodeRawEnvelopeBody(t, write.CapturedBody), "set_cell_range")
+	cellsJSON, _ := json.Marshal(writeInput["cells"])
+	if !strings.Contains(string(cellsJSON), "45306") {
+		t.Errorf("date 2024-01-15 should be written as serial 45306; cells=%s", cellsJSON)
+	}
+}
+
+// TestWorkbookCreate_TypedDryRun verifies the dry-run previews create + a typed
+// set_cell_range write with the date already converted to a serial.
+func TestWorkbookCreate_TypedDryRun(t *testing.T) {
+	t.Parallel()
+	calls := parseDryRunAPI(t, WorkbookCreate, []string{
+		"--title", "Demo",
+		"--sheets", `{"sheets":[{"name":"S","columns":[{"name":"d","type":"date"}],"rows":[["2024-01-15"]]}]}`,
+	})
+	if len(calls) != 2 {
+		t.Fatalf("want 2 dry-run calls (create + typed write), got %d", len(calls))
+	}
+	raw, _ := json.Marshal(calls[1])
+	if !strings.Contains(string(raw), "45306") {
+		t.Errorf("typed dry-run write should contain serial 45306; got %s", raw)
+	}
+}
+
+func TestTablePut_StringifyCellValue(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		in   interface{}
+		want string
+	}{
+		{"plain", "plain"},
+		{json.Number("12345678901234"), "12345678901234"},
+		{true, "TRUE"},
+		{false, "FALSE"},
+		{3.5, "3.5"},
+	}
+	for _, tt := range cases {
+		if got := stringifyCellValue(tt.in); got != tt.want {
+			t.Errorf("stringifyCellValue(%#v) = %q, want %q", tt.in, got, tt.want)
+		}
+	}
+}
+
+func TestTablePut_DescribeJSONType(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		in   interface{}
+		want string
+	}{
+		{"x", "a string"},
+		{json.Number("1"), "a number"},
+		{true, "a boolean"},
+		{[]interface{}{}, "an array"},
+		{map[string]interface{}{}, "an object"},
+		{3.14, "float64"},
+	}
+	for _, tt := range cases {
+		if got := describeJSONType(tt.in); got != tt.want {
+			t.Errorf("describeJSONType(%#v) = %q, want %q", tt.in, got, tt.want)
+		}
+	}
+}
+
+func TestTablePut_HeaderAndMode(t *testing.T) {
+	t.Parallel()
+	bp := func(b bool) *bool { return &b }
+	// headerOn: overwrite writes header, append omits it by default, explicit wins
+	if !headerOn(&tableSheetSpec{}) {
+		t.Error("overwrite default should write header")
+	}
+	if headerOn(&tableSheetSpec{Mode: "append"}) {
+		t.Error("append should omit header by default")
+	}
+	if !headerOn(&tableSheetSpec{Mode: "append", Header: bp(true)}) {
+		t.Error("explicit header:true should override append default")
+	}
+	if headerOn(&tableSheetSpec{Header: bp(false)}) {
+		t.Error("explicit header:false should be honored")
+	}
+	// writeModeName
+	if writeModeName(&tableSheetSpec{}) != "overwrite" || writeModeName(&tableSheetSpec{Mode: "append"}) != "append" {
+		t.Error("writeModeName normalization wrong")
+	}
+	// buildSheetMatrix header toggle
+	s := &tableSheetSpec{Columns: []tableColumnSpec{{Name: "a", Type: "string"}}, Rows: [][]interface{}{{"x"}}}
+	if m, _ := buildSheetMatrix(s, true, false); len(m) != 1 {
+		t.Errorf("header off → 1 data row, got %d", len(m))
+	}
+	if m, _ := buildSheetMatrix(s, true, true); len(m) != 2 {
+		t.Errorf("header on → header + 1 data row, got %d", len(m))
+	}
+}
+
+func TestTablePut_BadModeRejected(t *testing.T) {
+	t.Parallel()
+	_, err := parseTablePutPayload(stubFlagView{"sheets": `{"sheets":[{"name":"S","mode":"upsert","columns":[{"name":"a","type":"string"}],"rows":[]}]}`})
+	if err == nil || !strings.Contains(err.Error(), "invalid") {
+		t.Errorf("mode \"upsert\" should be rejected, got %v", err)
+	}
+}
+
+// TestTablePut_AppendEmptySheetWritesHeader: appending to an EMPTY sheet still
+// writes the header row, so column names aren't lost (and a later +table-get
+// won't consume the first data row as the header).
+func TestTablePut_AppendEmptySheetWritesHeader(t *testing.T) {
+	t.Parallel()
+	structure := toolOutputStub(testToken, "read", `{"sheets":[{"sheet_id":"`+testSheetID+`","sheet_name":"新","index":0}]}`)
+	region := toolOutputStub(testToken, "read", `{}`) // empty sheet: no current_region → lastRow 0
+	write := toolOutputStub(testToken, "write", `{"ok":true}`)
+	out, err := runShortcutWithStubs(t, TablePut,
+		[]string{"--url", testURL, "--sheets",
+			`{"sheets":[{"name":"新","mode":"append","columns":[{"name":"列A","type":"string"}],"rows":[["x"],["y"]]}]}`},
+		structure, region, write)
+	if err != nil {
+		t.Fatalf("execute failed: %v\nout=%s", err, out)
+	}
+	var wire map[string]interface{}
+	if err := json.Unmarshal(write.CapturedBody, &wire); err != nil {
+		t.Fatalf("decode captured write body: %v", err)
+	}
+	var input map[string]interface{}
+	if err := json.Unmarshal([]byte(wire["input"].(string)), &input); err != nil {
+		t.Fatalf("decode tool input: %v", err)
+	}
+	cells, _ := input["cells"].([]interface{})
+	if len(cells) != 3 {
+		t.Fatalf("empty-sheet append should write header + 2 data rows = 3, got %d", len(cells))
+	}
+	if header, _ := cells[0].([]interface{}); len(header) > 0 {
+		if h0, _ := header[0].(map[string]interface{}); h0["value"] != "列A" {
+			t.Errorf("first row should be the header 列A; got %#v", h0)
+		}
+	}
+	if input["range"] != "A1:A3" {
+		t.Errorf("range = %v, want A1:A3 (header + 2 rows at top of empty sheet)", input["range"])
+	}
+}
+
+// TestTablePut_ExecuteAppend verifies append placement: data lands below the
+// sheet's existing data (current_region A1:B5 → start at row 6) with no repeated
+// header.
+func TestTablePut_ExecuteAppend(t *testing.T) {
+	t.Parallel()
+	structure := toolOutputStub(testToken, "read", `{"sheets":[{"sheet_id":"`+testSheetID+`","sheet_name":"日志","index":0}]}`)
+	region := toolOutputStub(testToken, "read", `{"current_region":"A1:B5","actual_range":"A1:B5"}`)
+	write := toolOutputStub(testToken, "write", `{"ok":true}`)
+	out, err := runShortcutWithStubs(t, TablePut,
+		[]string{"--url", testURL, "--sheets",
+			`{"sheets":[{"name":"日志","mode":"append","columns":[{"name":"时间","type":"string"},{"name":"值","type":"number"}],"rows":[["t1",1],["t2",2]]}]}`},
+		structure, region, write)
+	if err != nil {
+		t.Fatalf("execute failed: %v\nout=%s", err, out)
+	}
+	// inspect the set_cell_range request the append produced
+	var wire map[string]interface{}
+	if err := json.Unmarshal(write.CapturedBody, &wire); err != nil {
+		t.Fatalf("decode captured write body: %v", err)
+	}
+	var input map[string]interface{}
+	if err := json.Unmarshal([]byte(wire["input"].(string)), &input); err != nil {
+		t.Fatalf("decode tool input: %v", err)
+	}
+	if input["range"] != "A6:B7" {
+		t.Errorf("append range = %v, want A6:B7 (2 rows below last data row 5, no header)", input["range"])
+	}
+	if cells, _ := input["cells"].([]interface{}); len(cells) != 2 {
+		t.Errorf("append should write 2 data rows (no header), got %d", len(cells))
+	}
+	data := decodeEnvelopeData(t, out)
+	if s0, _ := data["sheets"].([]interface{})[0].(map[string]interface{}); s0["mode"] != "append" {
+		t.Errorf("summary mode = %v, want append", s0["mode"])
+	}
+}
+
+// TestTablePut_HeaderFalseAndAllowOverwrite checks header:false drops the
+// header row and allow_overwrite:false reaches the tool input.
+func TestTablePut_HeaderFalseAndAllowOverwrite(t *testing.T) {
+	t.Parallel()
+	calls := parseDryRunAPI(t, TablePut, []string{"--url", testURL, "--sheets",
+		`{"sheets":[{"name":"S","header":false,"allow_overwrite":false,"columns":[{"name":"a","type":"string"}],"rows":[["x"],["y"]]}]}`})
+	body, _ := calls[0].(map[string]interface{})["body"].(map[string]interface{})
+	input := decodeToolInput(t, body, "set_cell_range")
+	if input["allow_overwrite"] != false {
+		t.Errorf("allow_overwrite = %v, want false", input["allow_overwrite"])
+	}
+	rows, _ := input["cells"].([]interface{})
+	if len(rows) != 2 {
+		t.Fatalf("header:false → 2 data rows only, got %d", len(rows))
+	}
+	first, _ := rows[0].([]interface{})[0].(map[string]interface{})
+	if first["value"] != "x" {
+		t.Errorf("header:false first cell = %v, want data 'x' (no header row)", first["value"])
+	}
+}
+
+// ─── +table-get ───────────────────────────────────────────────────────
+
+func TestTableGet_SerialRoundTrip(t *testing.T) {
+	t.Parallel()
+	for _, iso := range []string{"2024-01-15", "2024-02-29", "2000-01-01", "1899-12-31"} {
+		s, err := isoDateToSerial(iso)
+		if err != nil {
+			t.Fatalf("isoDateToSerial(%s): %v", iso, err)
+		}
+		if back := serialToISO(float64(s)); back != iso {
+			t.Errorf("roundtrip %s → %d → %s", iso, s, back)
+		}
+	}
+}
+
+func TestTableGet_IsDateNumberFormat(t *testing.T) {
+	t.Parallel()
+	for _, nf := range []string{"yyyy-mm-dd", "yyyy-mm", "yyyy/m/d", "YYYY/MM/DD"} {
+		if !isDateNumberFormat(nf) {
+			t.Errorf("%q should be a date format", nf)
+		}
+	}
+	for _, nf := range []string{"#,##0", "0.00", "0.00%", "@", ""} {
+		if isDateNumberFormat(nf) {
+			t.Errorf("%q should not be a date format", nf)
+		}
+	}
+}
+
+func TestTableGet_InferColumnType(t *testing.T) {
+	t.Parallel()
+	mk := func(v interface{}, nf string) map[string]interface{} {
+		c := map[string]interface{}{"value": v}
+		if nf != "" {
+			c["cell_styles"] = map[string]interface{}{"number_format": nf}
+		}
+		return c
+	}
+	col := func(cells ...map[string]interface{}) [][]map[string]interface{} {
+		rows := make([][]map[string]interface{}, len(cells))
+		for i, c := range cells {
+			rows[i] = []map[string]interface{}{c}
+		}
+		return rows
+	}
+	if typ, f := inferColumnType(col(mk(45306.0, "yyyy-mm-dd")), 0); typ != "date" || f != "yyyy-mm-dd" {
+		t.Errorf("date col → %s/%s", typ, f)
+	}
+	if typ, f := inferColumnType(col(mk(100.0, "#,##0")), 0); typ != "number" || f != "#,##0" {
+		t.Errorf("number col → %s/%s", typ, f)
+	}
+	if typ, _ := inferColumnType(col(mk(true, "")), 0); typ != "bool" {
+		t.Errorf("bool col → %s", typ)
+	}
+	if typ, _ := inferColumnType(col(mk("x", "")), 0); typ != "string" {
+		t.Errorf("string col → %s", typ)
+	}
+	// digit-like value carrying text format (@) infers as string, not number —
+	// this is what makes +table-put's string columns (ids/postcodes) survive read-back.
+	if typ, _ := inferColumnType(col(mk(123.0, "@")), 0); typ != "string" {
+		t.Errorf("@-format numeric-looking col → %s, want string", typ)
+	}
+	if typ, _ := inferColumnType([][]map[string]interface{}{}, 0); typ != "string" {
+		t.Errorf("empty col → %s (want string)", typ)
+	}
+
+	// Mixed number+text degrades to string (self-consistent: every value is then
+	// a string), so the column round-trips and pandas doesn't choke. Numeric
+	// coercion of the dirty cells is left to the caller (pandas to_numeric).
+	if typ, _ := inferColumnType(col(mk(100.0, ""), mk("暂无", ""), mk(200.0, "")), 0); typ != "string" {
+		t.Errorf("mixed number+text col → %s, want string", typ)
+	}
+	// A bare number mixed into a date column must NOT stay date (would serial-
+	// convert the number into a bogus date) — degrades to string.
+	if typ, _ := inferColumnType(col(mk(45306.0, "yyyy-mm-dd"), mk(5.0, "")), 0); typ != "string" {
+		t.Errorf("date+bare-number col → %s, want string", typ)
+	}
+}
+
+func TestTableGet_CellToTyped(t *testing.T) {
+	t.Parallel()
+	mk := func(v interface{}) map[string]interface{} { return map[string]interface{}{"value": v} }
+	if v := cellToTyped(mk(45306.0), "date"); v != "2024-01-15" {
+		t.Errorf("date serial → %v, want 2024-01-15", v)
+	}
+	if v := cellToTyped(mk(100.0), "number"); v != 100.0 {
+		t.Errorf("number → %v", v)
+	}
+	if v := cellToTyped(mk(true), "bool"); v != true {
+		t.Errorf("bool → %v", v)
+	}
+	if v := cellToTyped(mk(""), "string"); v != nil {
+		t.Errorf("empty string → %v, want nil", v)
+	}
+	if v := cellToTyped(nil, "string"); v != nil {
+		t.Errorf("nil → %v, want nil", v)
+	}
+	if v := cellToTyped(mk("hi"), "string"); v != "hi" {
+		t.Errorf("string → %v", v)
+	}
+}
+
+// TestTableGet_DigitStringRoundTrip: a column +table-put wrote as string (text
+// format @) reads back as string, not number — so leading-zero ids / postcodes
+// survive instead of collapsing to a number.
+func TestTableGet_DigitStringRoundTrip(t *testing.T) {
+	t.Parallel()
+	region := toolOutputStub(testToken, "read", `{"current_region":"A1:A2"}`)
+	cells := toolOutputStub(testToken, "read", `{"ranges":[{"cells":[`+
+		`[{"value":"邮编"}],`+
+		`[{"value":"00123","cell_styles":{"number_format":"@"}}]`+
+		`]}]}`)
+	out, err := runShortcutWithStubs(t, TableGet,
+		[]string{"--url", testURL, "--sheet-name", "S"}, region, cells)
+	if err != nil {
+		t.Fatalf("execute failed: %v\nout=%s", err, out)
+	}
+	data := decodeEnvelopeData(t, out)
+	sheets, _ := data["sheets"].([]interface{})
+	s0, _ := sheets[0].(map[string]interface{})
+	cols, _ := s0["columns"].([]interface{})
+	if c0, _ := cols[0].(map[string]interface{}); c0["type"] != "string" {
+		t.Errorf("@-format col 邮编 → type %v, want string", c0["type"])
+	}
+	rows, _ := s0["rows"].([]interface{})
+	if r0, _ := rows[0].([]interface{}); r0[0] != "00123" {
+		t.Errorf("value = %v, want \"00123\" (leading zero preserved)", r0[0])
+	}
+}
+
+// TestTableGet_ExecuteRoundTrip reads a sheet back and checks the output is the
+// same typed protocol +table-put consumes: date serial → ISO, number preserved,
+// types inferred from number_format.
+func TestTableGet_ExecuteRoundTrip(t *testing.T) {
+	t.Parallel()
+	region := toolOutputStub(testToken, "read", `{"current_region":"A1:C2"}`)
+	cells := toolOutputStub(testToken, "read", `{"ranges":[{"cells":[`+
+		`[{"value":"门店"},{"value":"月份"},{"value":"销售额"}],`+
+		`[{"value":"北京"},{"value":45306,"cell_styles":{"number_format":"yyyy-mm"}},{"value":259874,"cell_styles":{"number_format":"#,##0"}}]`+
+		`]}]}`)
+	out, err := runShortcutWithStubs(t, TableGet,
+		[]string{"--url", testURL, "--sheet-name", "销售"}, region, cells)
+	if err != nil {
+		t.Fatalf("execute failed: %v\nout=%s", err, out)
+	}
+	data := decodeEnvelopeData(t, out)
+	sheets, _ := data["sheets"].([]interface{})
+	if len(sheets) != 1 {
+		t.Fatalf("want 1 sheet, got %d", len(sheets))
+	}
+	s0, _ := sheets[0].(map[string]interface{})
+	if s0["name"] != "销售" {
+		t.Errorf("name = %v, want 销售", s0["name"])
+	}
+	cols, _ := s0["columns"].([]interface{})
+	if len(cols) != 3 {
+		t.Fatalf("want 3 columns, got %d", len(cols))
+	}
+	c1, _ := cols[1].(map[string]interface{})
+	if c1["name"] != "月份" || c1["type"] != "date" || c1["format"] != "yyyy-mm" {
+		t.Errorf("col 月份 = %#v, want name=月份 date yyyy-mm", c1)
+	}
+	c2, _ := cols[2].(map[string]interface{})
+	if c2["type"] != "number" || c2["format"] != "#,##0" {
+		t.Errorf("col 销售额 = %#v, want number #,##0", c2)
+	}
+	rows, _ := s0["rows"].([]interface{})
+	r0, _ := rows[0].([]interface{})
+	if r0[1] != "2024-01-15" {
+		t.Errorf("date roundtrip = %v, want 2024-01-15 (serial 45306 → ISO)", r0[1])
+	}
+	if r0[2] != float64(259874) {
+		t.Errorf("number = %v, want 259874", r0[2])
+	}
+}
+
+func TestTableGet_DryRunIncludesCellRead(t *testing.T) {
+	t.Parallel()
+	calls := parseDryRunAPI(t, TableGet, []string{"--url", testURL, "--sheet-name", "S"})
+	found := false
+	for _, c := range calls {
+		body, _ := c.(map[string]interface{})["body"].(map[string]interface{})
+		if body == nil {
+			continue
+		}
+		if tn, _ := body["tool_name"].(string); tn == "get_cell_ranges" {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("dry-run should include a get_cell_ranges read")
+	}
+}
+
+// TestTableGet_AllSheets covers the "read every sheet" path (no --sheet-name):
+// get_workbook_structure lists sheets, then each is read in order.
+func TestTableGet_AllSheets(t *testing.T) {
+	t.Parallel()
+	structure := toolOutputStub(testToken, "read", `{"sheets":[{"sheet_id":"s1","sheet_name":"A","index":0},{"sheet_id":"s2","sheet_name":"B","index":1}]}`)
+	regionA := toolOutputStub(testToken, "read", `{"current_region":"A1:A2"}`)
+	cellsA := toolOutputStub(testToken, "read", `{"ranges":[{"cells":[[{"value":"项"}],[{"value":"x"}]]}]}`)
+	regionB := toolOutputStub(testToken, "read", `{"current_region":"A1:A2"}`)
+	cellsB := toolOutputStub(testToken, "read", `{"ranges":[{"cells":[[{"value":"项"}],[{"value":"y"}]]}]}`)
+	out, err := runShortcutWithStubs(t, TableGet,
+		[]string{"--url", testURL}, structure, regionA, cellsA, regionB, cellsB)
+	if err != nil {
+		t.Fatalf("execute failed: %v\nout=%s", err, out)
+	}
+	data := decodeEnvelopeData(t, out)
+	sheets, _ := data["sheets"].([]interface{})
+	if len(sheets) != 2 {
+		t.Fatalf("want 2 sheets (all), got %d", len(sheets))
+	}
+	got := []string{
+		sheets[0].(map[string]interface{})["name"].(string),
+		sheets[1].(map[string]interface{})["name"].(string),
+	}
+	if got[0] != "A" || got[1] != "B" {
+		t.Errorf("sheet names = %v, want [A B] in workbook order", got)
+	}
+}

shortcuts/sheets/lark_sheet_undo.go

@@ -0,0 +1,108 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ─── lark_sheet_undo ──────────────────────────────────────────────────
+//
+// Wraps:
+//   - undo_last (write) — powers +undo
+//
+// Reverses the most recent edits this CLI link made to a spreadsheet, addressed
+// by document revision. Every write response carries `data.revision`; that
+// number is the undo anchor. The backend records an inverse changeset for every
+// write and indexes it by the revision it produced (see the undo design doc,
+// "方案 A · rev 寻址"); +undo asks the backend executor to locate that inverse
+// data through the revision pointer, verify nobody else changed the document
+// since (tip / continuity / object-version / identity checks), re-apply it in
+// reverse order on the node Workbook, and push the result upstream as a
+// collaboration change. The CLI only triggers the tool — the read-back endpoint
+// is space-internal and not reachable through the /open-apis gateway, so all
+// the heavy lifting stays server-side.
+//
+// +undo carries no sheet selector: undo is scoped to the spreadsheet + this
+// link's edit history, not a single sub-sheet. Selection:
+//   - (no flags)  : undo the latest edit, if it was made by this caller
+//   - --rev N     : undo anchored at revision N (from a prior write response);
+//                   rejected when the document has moved past N
+//   - --steps N   : undo the last N edits in one atomic call (default 1)
+
+// Undo wraps undo_last: reverse the most recent edits made through this CLI
+// link, anchored by the revision a prior write returned (--rev), defaulting
+// to the latest edit.
+var Undo = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+undo",
+	Description: "Undo the most recent edits this CLI link made to a spreadsheet (anchored by a write's returned revision).",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       flagsFor("+undo"),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetToken(runtime)
+		if err != nil {
+			return err
+		}
+		_, err = undoInput(runtime, token)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		input, _ := undoInput(runtime, token)
+		return invokeToolDryRun(token, ToolKindWrite, "undo_last", input)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetToken(runtime)
+		if err != nil {
+			return err
+		}
+		input, err := undoInput(runtime, token)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindWrite, "undo_last", input)
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+	Tips: []string{
+		"Every write response carries data.revision — remember it; +undo --rev <that> undoes exactly that edit, and +recover --to-revision <that-1> is the full-rollback fallback.",
+		"Without --rev, +undo targets the document's latest edit — it succeeds only when that edit was made through this CLI link by you.",
+		"Repeated +undo steps back one edit at a time; --steps N undoes the last N edits in one atomic call. Already-undone edits are skipped automatically.",
+		"If anyone else edited the document after (or between) the edits you want to undo, +undo refuses entirely and suggests +recover — it never partially undoes or overwrites others' changes.",
+		"A success response with undone:0 plus warning_message means nothing was actually undone — the targeted revision wasn't produced by this caller, or was already undone.",
+		"Use --dry-run to preview the request before running it.",
+	},
+}
+
+// undoInput builds the undo_last tool body. --rev anchors the undo at the
+// revision a prior write returned (omitted = latest); --steps selects how many
+// edits to reverse in one atomic call. Network-free; shared by Validate,
+// DryRun, and Execute.
+func undoInput(runtime flagView, token string) (map[string]interface{}, error) {
+	input := map[string]interface{}{"excel_id": token}
+
+	if runtime.Changed("rev") {
+		rev := runtime.Int("rev")
+		if rev < 1 {
+			return nil, common.FlagErrorf("--rev must be a positive revision number (from a prior write's data.revision)")
+		}
+		input["rev"] = rev
+	}
+
+	steps := runtime.Int("steps")
+	if steps < 1 {
+		return nil, common.FlagErrorf("--steps must be >= 1")
+	}
+	input["steps"] = steps
+	return input, nil
+}

shortcuts/sheets/lark_sheet_undo_test.go

@@ -0,0 +1,107 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestUndo_DryRun asserts the undo_last body for the three selection shapes:
+// default (latest, steps=1), explicit --steps, and a --rev anchor. Numbers
+// round-trip through the wire JSON as float64, matching the other dry-run
+// body tests.
+func TestUndo_DryRun(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		args      []string
+		wantInput map[string]interface{}
+	}{
+		{
+			name: "default undoes the latest edit",
+			args: []string{"--url", testURL},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+				"steps":    float64(1),
+			},
+		},
+		{
+			name: "explicit --steps",
+			args: []string{"--url", testURL, "--steps", "3"},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+				"steps":    float64(3),
+			},
+		},
+		{
+			name: "--rev anchors at a write's returned revision",
+			args: []string{"--spreadsheet-token", testToken, "--rev", "123"},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+				"rev":      float64(123),
+				"steps":    float64(1),
+			},
+		},
+		{
+			name: "--rev composes with --steps",
+			args: []string{"--url", testURL, "--rev", "123", "--steps", "2"},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+				"rev":      float64(123),
+				"steps":    float64(2),
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			body := parseDryRunBody(t, Undo, tt.args)
+			got := decodeToolInput(t, body, "undo_last")
+			assertInputEquals(t, got, tt.wantInput)
+		})
+	}
+}
+
+// TestUndo_Validation covers the XOR token check, the --rev lower bound, and
+// the --steps lower bound.
+func TestUndo_Validation(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name    string
+		args    []string
+		wantMsg string
+	}{
+		{
+			name:    "needs --url or --spreadsheet-token",
+			args:    []string{},
+			wantMsg: "at least one of --url or --spreadsheet-token",
+		},
+		{
+			name:    "--rev must be positive",
+			args:    []string{"--url", testURL, "--rev", "0"},
+			wantMsg: "--rev must be a positive revision number",
+		},
+		{
+			name:    "--steps must be >= 1",
+			args:    []string{"--url", testURL, "--steps", "0"},
+			wantMsg: "--steps must be >= 1",
+		},
+	}
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			stdout, stderr, err := runShortcutCapturingErr(t, Undo, append(tt.args, "--dry-run"))
+			if err == nil {
+				t.Fatalf("expected validation error; got nil. stdout=%s stderr=%s", stdout, stderr)
+			}
+			combined := stdout + stderr + err.Error()
+			if !strings.Contains(combined, tt.wantMsg) {
+				t.Errorf("error message missing %q; got=%s", tt.wantMsg, combined)
+			}
+		})
+	}
+}

shortcuts/sheets/lark_sheet_workbook.go

@@ -6,19 +6,14 @@ package sheets
 import (
 	"context"
 	"fmt"
-	"net/http"
 	"path/filepath"
 	"strings"
-	"time"
-
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/util"
-	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/larksuite/cli/shortcuts/drive"
 )
 
 // ─── lark_sheet_workbook ──────────────────────────────────────────────
@@ -540,6 +535,18 @@ var SheetSetTabColor = common.Shortcut{
 	},
 }
 
+// SheetShowGridline / SheetHideGridline toggle a sub-sheet's gridline display.
+// Gridline show/hide is the same two-state-via-operation shape as
+// +sheet-hide/+sheet-unhide (no --visible flag), so they reuse
+// newSheetVisibilityShortcut; only the operation enum differs.
+var SheetShowGridline = newSheetVisibilityShortcut(
+	"+sheet-show-gridline", "Show gridlines on a sub-sheet.", "show_gridline",
+)
+
+var SheetHideGridline = newSheetVisibilityShortcut(
+	"+sheet-hide-gridline", "Hide gridlines on a sub-sheet.", "hide_gridline",
+)
+
 // ─── +workbook-create (legacy OAPI, cli_status: cli-only) ────────────
 //
 // Creates a brand-new spreadsheet via POST /sheets/v3/spreadsheets, then
@@ -553,7 +560,7 @@ var SheetSetTabColor = common.Shortcut{
 var WorkbookCreate = common.Shortcut{
 	Service:     "sheets",
 	Command:     "+workbook-create",
-	Description: "Create a new spreadsheet (optionally pre-filled with --headers and --values).",
+	Description: "Create a new spreadsheet, optionally pre-filled with untyped --headers/--values or typed --sheets (type-faithful one-step create + write).",
 	Risk:        "write",
 	Scopes:      []string{"sheets:spreadsheet:create", "sheets:spreadsheet:write_only"},
 	AuthTypes:   []string{"user", "bot"},
@@ -563,6 +570,20 @@ var WorkbookCreate = common.Shortcut{
 		if strings.TrimSpace(runtime.Str("title")) == "" {
 			return common.FlagErrorf("--title is required")
 		}
+		// --sheets (typed) is an alternative, mutually exclusive data entry to the
+		// untyped --headers/--values. Gated on Changed (not just non-empty): an
+		// explicitly-given but empty --sheets (e.g. empty stdin / file) is an
+		// error, not a silent fall-through to creating an empty workbook.
+		if runtime.Changed("sheets") {
+			if strings.TrimSpace(runtime.Str("sheets")) == "" {
+				return common.FlagErrorf("--sheets was given but resolved to empty (empty stdin/file?); pass a typed payload, or drop --sheets to create an empty workbook")
+			}
+			if runtime.Str("headers") != "" || runtime.Str("values") != "" {
+				return common.FlagErrorf("--sheets is mutually exclusive with --headers/--values")
+			}
+			_, err := parseTablePutPayload(runtime)
+			return err
+		}
 		if runtime.Str("headers") != "" {
 			v, err := parseJSONFlag(runtime, "headers")
 			if err != nil {
@@ -598,10 +619,33 @@ var WorkbookCreate = common.Shortcut{
 			POST("/open-apis/sheets/v3/spreadsheets").
 			Desc("create spreadsheet").
 			Body(body)
+		// Typed --sheets path: preview the create POST, then one set_cell_range
+		// write per sheet (the first adopts the new workbook's default sheet).
+		// Mirrors +table-put's dry-run, against a placeholder token.
+		if runtime.Changed("sheets") {
+			if payload, err := parseTablePutPayload(runtime); err == nil {
+				headerStyle := runtime.Bool("header-style")
+				for i := range payload.Sheets {
+					s := &payload.Sheets[i]
+					matrix, _ := buildSheetMatrix(s, headerStyle, headerOn(s))
+					input := map[string]interface{}{
+						"excel_id":   "<new-token>",
+						"sheet_name": s.Name,
+						"range":      tablePutFullRange(s, len(matrix)),
+						"cells":      matrix,
+					}
+					wireBody, _ := buildToolBody(ToolKindWrite, "set_cell_range", input)
+					dry.POST("/open-apis/sheet_ai/v2/spreadsheets/<new-token>/tools/invoke_write").
+						Desc(fmt.Sprintf("write typed sheet %q (%d data rows × %d cols) via set_cell_range", s.Name, len(s.Rows), len(s.Columns))).
+						Body(wireBody)
+				}
+			}
+			return dry
+		}
 		if fill, _ := buildInitialFillInput(runtime); fill != nil {
 			fill["excel_id"] = "<new-token>"
 			fill["sheet_id"] = "<first-sheet-id>" // resolved from the workbook at execute time
-			wireBody, _ := buildToolBody("set_cell_range", fill)
+			wireBody, _ := buildToolBody(ToolKindWrite, "set_cell_range", fill)
 			dry.POST("/open-apis/sheet_ai/v2/spreadsheets/<new-token>/tools/invoke_write").
 				Desc("fill headers + data via set_cell_range (sheet_id resolved after create)").
 				Body(wireBody)
@@ -628,6 +672,30 @@ var WorkbookCreate = common.Shortcut{
 
 		result := map[string]interface{}{"spreadsheet": ss}
 
+		// Typed --sheets path: write type-faithful data into the brand-new
+		// workbook, adopting its default sheet as the first payload sheet so no
+		// empty "Sheet1" is left behind. Mutually exclusive with --headers/--values
+		// (enforced in Validate).
+		if runtime.Changed("sheets") {
+			payload, err := parseTablePutPayload(runtime)
+			if err != nil {
+				return err // already validated; defensive
+			}
+			firstSheetID, err := lookupFirstSheetID(ctx, runtime, token)
+			if err != nil {
+				return workbookCreatedButFillFailed(token, ss,
+					fmt.Sprintf("resolving its default sheet for the typed write failed: %v", err))
+			}
+			written, err := writeTypedSheets(ctx, runtime, token, payload, runtime.Bool("header-style"), firstSheetID)
+			if err != nil {
+				return workbookCreatedButFillFailed(token, ss,
+					fmt.Sprintf("typed write failed: %v", err))
+			}
+			result["sheets"] = written
+			runtime.Out(result, nil)
+			return nil
+		}
+
 		// --headers / --values are optional. buildInitialFillInput returns
 		// (nil, nil) when both are absent or empty, in which case we skip the
 		// fill entirely rather than dereferencing a nil map.
@@ -657,6 +725,7 @@ var WorkbookCreate = common.Shortcut{
 	},
 	Tips: []string{
 		"--headers and --values are optional follow-up writes. They use the same set_cell_range tool as +cells-set; partial failure leaves the spreadsheet created but empty.",
+		"--sheets writes typed, type-faithful data (dates → real dates, numbers keep precision) in one step — the create + typed write that +table-put can't do on its own. Mutually exclusive with --headers/--values; the new workbook's default sheet becomes the first typed sheet (no empty Sheet1 left behind).",
 	},
 }
 
@@ -770,178 +839,62 @@ var WorkbookExport = common.Shortcut{
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		token, _ := resolveSpreadsheetToken(runtime)
-		ext := runtime.Str("file-extension")
-		if ext == "" {
-			ext = "xlsx"
-		}
-		body := map[string]interface{}{
-			"token":          token,
-			"type":           "sheet",
-			"file_extension": ext,
-		}
-		if sid := strings.TrimSpace(runtime.Str("sheet-id")); sid != "" {
-			body["sub_id"] = sid
-		}
-		dry := common.NewDryRunAPI().
-			POST("/open-apis/drive/v1/export_tasks").
-			Desc("create export task").
-			Body(body).
-			GET("/open-apis/drive/v1/export_tasks/<ticket>").
-			Desc("poll task status").
-			Params(map[string]interface{}{"token": token})
-		if strings.TrimSpace(runtime.Str("output-path")) != "" {
-			dry.GET("/open-apis/drive/v1/export_tasks/file/<file_token>/download").
-				Desc("download exported file")
-		}
-		return dry
+		p, _ := workbookExportParams(runtime)
+		p.OutputDir = strings.TrimSpace(runtime.Str("output-path"))
+		return drive.PlanExportDryRun(runtime, p)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		token, err := resolveSpreadsheetToken(runtime)
+		p, err := workbookExportParams(runtime)
 		if err != nil {
 			return err
 		}
-		ext := runtime.Str("file-extension")
-		if ext == "" {
-			ext = "xlsx"
-		}
-		body := map[string]interface{}{
-			"token":          token,
-			"type":           "sheet",
-			"file_extension": ext,
-		}
-		if sid := strings.TrimSpace(runtime.Str("sheet-id")); sid != "" {
-			body["sub_id"] = sid
-		}
-		taskData, err := runtime.CallAPI("POST", "/open-apis/drive/v1/export_tasks", nil, body)
-		if err != nil {
-			return err
-		}
-		ticket := common.GetString(taskData, "ticket")
-		if ticket == "" {
-			return output.Errorf(output.ExitAPI, "api_error", "export task created but ticket missing")
-		}
-
-		result := map[string]interface{}{
-			"ticket":         ticket,
-			"file_extension": ext,
-		}
-
-		// Poll up to ~30s for completion.
-		var fileToken, fileName string
-		for attempt := 0; attempt < 15; attempt++ {
-			status, err := pollExportTask(runtime, token, ticket)
-			if err != nil {
-				return err
-			}
-			switch status.JobStatus {
-			case 0: // success
-				fileToken = status.FileToken
-				fileName = status.FileName
-				result["file_token"] = fileToken
-				result["file_name"] = fileName
-				result["file_size"] = status.FileSize
-				attempt = 999 // break outer loop
-			case 1, 2: // pending / in progress
-				time.Sleep(2 * time.Second)
-				continue
-			default: // any non-zero status outside the in-progress window is a failure
-				if status.JobErrorMsg != "" {
-					return output.Errorf(output.ExitAPI, "api_error", "export task %s failed: %s", ticket, status.JobErrorMsg)
-				}
-				return output.Errorf(output.ExitAPI, "api_error", "export task %s failed with job_status=%d", ticket, status.JobStatus)
-			}
-		}
-		if fileToken == "" {
-			result["status"] = "polling_timeout"
-			runtime.Out(result, nil)
-			return nil
-		}
-
-		outPath := strings.TrimSpace(runtime.Str("output-path"))
-		if outPath == "" {
-			runtime.Out(result, nil)
-			return nil
-		}
-
-		saved, err := downloadExportFile(ctx, runtime, fileToken, outPath, fileName)
-		if err != nil {
-			return err
-		}
-		result["saved_path"] = saved
-		runtime.Out(result, nil)
-		return nil
+		applyWorkbookOutputPath(&p, runtime.FileIO(), runtime.Str("output-path"))
+		return drive.RunExport(ctx, runtime, p)
 	},
 	Tips: []string{
-		"Polls up to ~30s (15 × 2s). For very large workbooks rerun and pass --output-path to capture the file once status flips to success.",
+		"Polls for a bounded window; if the export is still running it returns a resume reference instead of blocking. Pass --output-path to download the file once ready (omit it to only create the export task and get the file token back).",
 	},
 }
 
-type exportTaskStatus struct {
-	JobStatus     int
-	JobErrorMsg   string
-	FileToken     string
-	FileName      string
-	FileSize      int64
-	FileExtension string
-}
-
-func pollExportTask(runtime *common.RuntimeContext, token, ticket string) (exportTaskStatus, error) {
-	data, err := runtime.CallAPI(
-		"GET",
-		fmt.Sprintf("/open-apis/drive/v1/export_tasks/%s", validate.EncodePathSegment(ticket)),
-		map[string]interface{}{"token": token},
-		nil,
-	)
+// workbookExportParams builds the shared drive export request for
+// +workbook-export: spreadsheet token + sheet locator, pinned to type=sheet.
+// workbook-export has always overwritten the target, so Overwrite is set. The
+// --output-path → OutputDir/FileName split (which needs a Stat) is applied
+// separately by applyWorkbookOutputPath so Validate/DryRun stay I/O-free.
+func workbookExportParams(runtime *common.RuntimeContext) (drive.ExportParams, error) {
+	token, err := resolveSpreadsheetToken(runtime)
 	if err != nil {
-		return exportTaskStatus{}, err
+		return drive.ExportParams{}, err
 	}
-	result := common.GetMap(data, "result")
-	if result == nil {
-		return exportTaskStatus{}, output.Errorf(output.ExitAPI, "api_error", "export task %s: empty result", ticket)
+	ext := runtime.Str("file-extension")
+	if ext == "" {
+		ext = "xlsx"
 	}
-	js, _ := util.ToFloat64(result["job_status"])
-	fs, _ := util.ToFloat64(result["file_size"])
-	return exportTaskStatus{
-		JobStatus:     int(js),
-		JobErrorMsg:   common.GetString(result, "job_error_msg"),
-		FileToken:     common.GetString(result, "file_token"),
-		FileName:      common.GetString(result, "file_name"),
-		FileSize:      int64(fs),
-		FileExtension: common.GetString(result, "file_extension"),
+	return drive.ExportParams{
+		Token:         token,
+		DocType:       "sheet",
+		FileExtension: ext,
+		SubID:         strings.TrimSpace(runtime.Str("sheet-id")),
+		Overwrite:     true,
 	}, nil
 }
 
-func downloadExportFile(ctx context.Context, runtime *common.RuntimeContext, fileToken, outPath, preferredName string) (string, error) {
-	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
-		HttpMethod: http.MethodGet,
-		ApiPath:    fmt.Sprintf("/open-apis/drive/v1/export_tasks/file/%s/download", validate.EncodePathSegment(fileToken)),
-	}, larkcore.WithFileDownload())
-	if err != nil {
-		return "", output.ErrNetwork("download failed: %s", err)
+// applyWorkbookOutputPath maps the single --output-path flag onto the drive
+// export OutputDir/FileName pair, preserving the legacy behavior: empty = no
+// download (return the ready file token only); an existing directory = download
+// into it under the server-provided name; otherwise treat it as a file path and
+// split into dir + base name.
+func applyWorkbookOutputPath(p *drive.ExportParams, fio fileio.FileIO, outputPath string) {
+	outputPath = strings.TrimSpace(outputPath)
+	if outputPath == "" {
+		return
 	}
-	if apiResp.StatusCode >= 400 {
-		return "", output.ErrNetwork("download failed: HTTP %d: %s", apiResp.StatusCode, string(apiResp.RawBody))
+	if info, err := fio.Stat(outputPath); err == nil && info.IsDir() {
+		p.OutputDir = outputPath
+		return
 	}
-	target := outPath
-	if info, statErr := runtime.FileIO().Stat(outPath); statErr == nil && info.IsDir() {
-		name := strings.TrimSpace(preferredName)
-		if name == "" {
-			name = client.ResolveFilename(apiResp)
-		}
-		target = filepath.Join(outPath, name)
-	}
-	if _, err := runtime.FileIO().Save(target, fileio.SaveOptions{
-		ContentType:   apiResp.Header.Get("Content-Type"),
-		ContentLength: int64(len(apiResp.RawBody)),
-	}, strings.NewReader(string(apiResp.RawBody))); err != nil {
-		return "", common.WrapSaveErrorByCategory(err, "io")
-	}
-	resolved, _ := runtime.FileIO().ResolvePath(target)
-	if resolved == "" {
-		resolved = target
-	}
-	return resolved, nil
+	p.OutputDir = filepath.Dir(outputPath)
+	p.FileName = filepath.Base(outputPath)
 }
 
 // lookupSheetIndex finds a sub-sheet by id or name and returns its canonical
@@ -1033,3 +986,45 @@ func lookupFirstSheetID(ctx context.Context, runtime *common.RuntimeContext, tok
 	}
 	return bestID, nil
 }
+
+// ─── +workbook-import (reuses drive import core, cli_status: cli-only) ──
+//
+// Imports a local xlsx/xls/csv file as a brand-new spreadsheet. The full
+// upload → create-task → poll flow is the shared drive import core
+// (drive.RunImport); this shortcut only pins the target type to "sheet" and
+// omits the bitable-only --target-token. Symmetric with +workbook-export.
+// Not exposed as an MCP tool.
+
+// WorkbookImport imports a local spreadsheet file as a new Feishu spreadsheet
+// by delegating to the shared drive import core with type fixed to "sheet".
+var WorkbookImport = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+workbook-import",
+	Description: "Import a local xlsx/xls/csv file as a new spreadsheet (async + poll). Reuses the drive import core with type fixed to sheet.",
+	Risk:        "write",
+	Scopes:      []string{"docs:document.media:upload", "docs:document:import"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       flagsFor("+workbook-import"),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return drive.ValidateImport(workbookImportParams(runtime))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		return drive.PlanImportDryRun(runtime, workbookImportParams(runtime))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return drive.RunImport(ctx, runtime, workbookImportParams(runtime))
+	},
+}
+
+// workbookImportParams builds the drive import request for +workbook-import,
+// pinning DocType to "sheet". The bitable-only --target-token is intentionally
+// not exposed here — use drive +import for non-sheet import targets.
+func workbookImportParams(runtime *common.RuntimeContext) drive.ImportParams {
+	return drive.ImportParams{
+		File:        runtime.Str("file"),
+		DocType:     "sheet",
+		FolderToken: runtime.Str("folder-token"),
+		Name:        runtime.Str("name"),
+	}
+}

shortcuts/sheets/lark_sheet_workbook_export_test.go

@@ -0,0 +1,72 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+// TestWorkbookExport_ExecuteExportOnly covers the no-download path: without
+// --output-path, +workbook-export delegates to the shared drive export core
+// with OutputDir="" so it creates + polls the export task and returns the ready
+// file token without writing a local file (downloaded=false).
+func TestWorkbookExport_ExecuteExportOnly(t *testing.T) {
+	stubs := []*httpmock.Stub{
+		{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/export_tasks",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "ok",
+				"data": map[string]interface{}{"ticket": "tk_export"},
+			},
+		},
+		{
+			Method: "GET",
+			URL:    "/open-apis/drive/v1/export_tasks/tk_export",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "ok",
+				"data": map[string]interface{}{"result": map[string]interface{}{
+					"job_status": float64(0),
+					"file_token": "ftk_xlsx",
+					"file_name":  "report.xlsx",
+					"file_size":  float64(2048),
+				}},
+			},
+		},
+	}
+
+	out, err := runShortcutWithStubs(t, WorkbookExport, []string{
+		"--url", testURL, "--file-extension", "xlsx", "--as", "user",
+	}, stubs...)
+	if err != nil {
+		t.Fatalf("export-only execute failed: %v\n%s", err, out)
+	}
+
+	idx := strings.Index(out, "{")
+	if idx < 0 {
+		t.Fatalf("no JSON envelope:\n%s", out)
+	}
+	var env struct {
+		Data map[string]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(out[idx:]), &env); err != nil {
+		t.Fatalf("decode envelope: %v\nraw=%s", err, out)
+	}
+	if env.Data["ready"] != true {
+		t.Errorf("ready = %v, want true", env.Data["ready"])
+	}
+	if env.Data["downloaded"] != false {
+		t.Errorf("downloaded = %v, want false (no --output-path)", env.Data["downloaded"])
+	}
+	if env.Data["file_token"] != "ftk_xlsx" {
+		t.Errorf("file_token = %v, want ftk_xlsx", env.Data["file_token"])
+	}
+	if env.Data["doc_type"] != "sheet" {
+		t.Errorf("doc_type = %v, want sheet", env.Data["doc_type"])
+	}
+}

shortcuts/sheets/lark_sheet_workbook_import_test.go

@@ -0,0 +1,135 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"encoding/json"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+	_ "github.com/larksuite/cli/internal/vfs/localfileio"
+)
+
+// chdirTemp switches into a fresh temp dir for the duration of the test and
+// restores the original cwd afterwards. +workbook-import is the first sheets
+// shortcut that stat()s a real local file, so these tests need a working dir.
+func chdirTemp(t *testing.T) {
+	t.Helper()
+	orig, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	if err := os.Chdir(t.TempDir()); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(orig) })
+}
+
+// TestWorkbookImport_DryRunPinsSheetType verifies the shortcut delegates to the
+// shared drive import core and hard-codes the import target type to "sheet".
+func TestWorkbookImport_DryRunPinsSheetType(t *testing.T) {
+	chdirTemp(t)
+	if err := os.WriteFile("data.xlsx", []byte("fake-xlsx"), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	calls := parseDryRunAPI(t, WorkbookImport, []string{"--file", "./data.xlsx"})
+
+	var createBody map[string]interface{}
+	for _, c := range calls {
+		cm, _ := c.(map[string]interface{})
+		if u, _ := cm["url"].(string); u == "/open-apis/drive/v1/import_tasks" {
+			createBody, _ = cm["body"].(map[string]interface{})
+		}
+	}
+	if createBody == nil {
+		t.Fatalf("no import_tasks create call in dry-run: %#v", calls)
+	}
+	if createBody["type"] != "sheet" {
+		t.Errorf("import type = %v, want sheet (must be pinned regardless of file)", createBody["type"])
+	}
+	if createBody["file_extension"] != "xlsx" {
+		t.Errorf("file_extension = %v, want xlsx", createBody["file_extension"])
+	}
+}
+
+// TestWorkbookImport_RejectsNonSheetFile ensures a file that cannot become a
+// spreadsheet (e.g. .docx) is rejected up front by the pinned-sheet validation.
+func TestWorkbookImport_RejectsNonSheetFile(t *testing.T) {
+	chdirTemp(t)
+	if err := os.WriteFile("notes.docx", []byte("fake-docx"), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	// Validate runs before DryRun, so the pinned-sheet check rejects .docx up
+	// front and the error surfaces through the normal envelope/err path.
+	stdout, stderr, err := runShortcutCapturingErr(t, WorkbookImport, []string{"--file", "./notes.docx", "--dry-run"})
+	if err == nil || !strings.Contains(stdout+stderr+err.Error(), "can only be imported") {
+		t.Errorf("expected .docx → sheet type-mismatch rejection; got stdout=%s stderr=%s err=%v", stdout, stderr, err)
+	}
+}
+
+// TestWorkbookImport_ExecuteCreatesSheet runs the full upload → create → poll
+// flow against stubs and asserts the resulting URL is a /sheets/ link.
+func TestWorkbookImport_ExecuteCreatesSheet(t *testing.T) {
+	chdirTemp(t)
+	if err := os.WriteFile("data.csv", []byte("a,b\n1,2\n"), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	stubs := []*httpmock.Stub{
+		{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/medias/upload_all",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "ok",
+				"data": map[string]interface{}{"file_token": "file_import_media"},
+			},
+		},
+		{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/import_tasks",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "ok",
+				"data": map[string]interface{}{"ticket": "tk_sheet"},
+			},
+		},
+		{
+			Method: "GET",
+			URL:    "/open-apis/drive/v1/import_tasks/tk_sheet",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "ok",
+				"data": map[string]interface{}{"result": map[string]interface{}{
+					"token":      "shtcn_imported",
+					"type":       "sheet",
+					"job_status": float64(0),
+				}},
+			},
+		},
+	}
+
+	out, err := runShortcutWithStubs(t, WorkbookImport, []string{"--file", "./data.csv", "--as", "user"}, stubs...)
+	if err != nil {
+		t.Fatalf("import execute failed: %v\n%s", err, out)
+	}
+
+	idx := strings.Index(out, "{")
+	if idx < 0 {
+		t.Fatalf("execute output has no JSON envelope:\n%s", out)
+	}
+	var env struct {
+		Data map[string]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(out[idx:]), &env); err != nil {
+		t.Fatalf("decode envelope: %v\nraw=%s", err, out)
+	}
+	if url, _ := env.Data["url"].(string); !strings.Contains(url, "/sheets/") {
+		t.Errorf("imported url = %q, want a /sheets/ link", url)
+	}
+	if tok, _ := env.Data["token"].(string); tok != "shtcn_imported" {
+		t.Errorf("token = %q, want shtcn_imported", tok)
+	}
+}

shortcuts/sheets/lark_sheet_workbook_test.go

@@ -140,6 +140,28 @@ func TestWorkbookShortcuts_DryRun(t *testing.T) {
 				"tab_color": "",
 			},
 		},
+		{
+			name:     "+sheet-show-gridline",
+			sc:       SheetShowGridline,
+			args:     []string{"--url", testURL, "--sheet-id", testSheetID},
+			toolName: "modify_workbook_structure",
+			wantInput: map[string]interface{}{
+				"excel_id":  testToken,
+				"operation": "show_gridline",
+				"sheet_id":  testSheetID,
+			},
+		},
+		{
+			name:     "+sheet-hide-gridline",
+			sc:       SheetHideGridline,
+			args:     []string{"--url", testURL, "--sheet-id", testSheetID},
+			toolName: "modify_workbook_structure",
+			wantInput: map[string]interface{}{
+				"excel_id":  testToken,
+				"operation": "hide_gridline",
+				"sheet_id":  testSheetID,
+			},
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -339,21 +361,21 @@ func TestWorkbookCreate_DataValidation(t *testing.T) {
 	}
 }
 
-// TestWorkbookExport_DryRun checks the 2-or-3 step plan depending on
-// --output-path. The order should be: POST → GET (poll) → optional GET
-// (download).
+// TestWorkbookExport_DryRun verifies the export dry-run now delegates to the
+// shared drive export core: a single create-task POST (poll + download are
+// described inline rather than as separate api entries).
 func TestWorkbookExport_DryRun(t *testing.T) {
 	t.Parallel()
 
-	t.Run("xlsx without --output-path → 2 steps", func(t *testing.T) {
+	t.Run("xlsx create-task body pins type=sheet", func(t *testing.T) {
 		t.Parallel()
 		calls := parseDryRunAPI(t, WorkbookExport, []string{"--url", testURL, "--file-extension", "xlsx"})
-		if len(calls) != 2 {
-			t.Fatalf("api calls = %d, want 2 (create + poll)", len(calls))
+		if len(calls) != 1 {
+			t.Fatalf("api calls = %d, want 1 (create export task)", len(calls))
 		}
 		create := calls[0].(map[string]interface{})
 		if create["url"] != "/open-apis/drive/v1/export_tasks" {
-			t.Errorf("first url = %v", create["url"])
+			t.Errorf("url = %v", create["url"])
 		}
 		body, _ := create["body"].(map[string]interface{})
 		if body["type"] != "sheet" || body["file_extension"] != "xlsx" || body["token"] != testToken {
@@ -361,22 +383,18 @@ func TestWorkbookExport_DryRun(t *testing.T) {
 		}
 	})
 
-	t.Run("csv → 3 steps, with sub_id", func(t *testing.T) {
+	t.Run("csv includes sub_id from --sheet-id", func(t *testing.T) {
 		t.Parallel()
 		calls := parseDryRunAPI(t, WorkbookExport, []string{
 			"--url", testURL, "--file-extension", "csv", "--sheet-id", "sh1",
 			"--output-path", "/tmp/out.csv",
 		})
-		if len(calls) != 3 {
-			t.Fatalf("api calls = %d, want 3", len(calls))
+		if len(calls) != 1 {
+			t.Fatalf("api calls = %d, want 1", len(calls))
 		}
 		body, _ := calls[0].(map[string]interface{})["body"].(map[string]interface{})
-		if body["sub_id"] != "sh1" {
-			t.Errorf("csv export missing sub_id: %#v", body)
-		}
-		dl := calls[2].(map[string]interface{})
-		if !strings.Contains(dl["url"].(string), "/export_tasks/file/") {
-			t.Errorf("download url = %v", dl["url"])
+		if body["type"] != "sheet" || body["sub_id"] != "sh1" {
+			t.Errorf("csv export body = %#v (want type=sheet, sub_id=sh1)", body)
 		}
 	})
 

shortcuts/sheets/lark_sheet_write_cells.go

@@ -727,7 +727,7 @@ var CellsSetImage = common.Shortcut{
 		if fileName == "" {
 			fileName = filepath.Base(imgPath)
 		}
-		setCellBody, _ := buildToolBody("set_cell_range", map[string]interface{}{
+		setCellBody, _ := buildToolBody(ToolKindWrite, "set_cell_range", map[string]interface{}{
 			"excel_id": token,
 			"range":    strings.TrimSpace(runtime.Str("range")),
 			"sheet_id": sheetSelectorPlaceholder(sheetID, sheetName),

shortcuts/sheets/sheet_ai_api.go

@@ -7,6 +7,8 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"os"
+	"strings"
 
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/util"
@@ -14,6 +16,26 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+// sheetTxnIDEnv is the env var carrying a caller-provided, session-stable
+// transaction id for sheet tool calls.
+const sheetTxnIDEnv = "LARK_CLI_SHEET_TRANSACTION_ID"
+
+// sheetTransactionID returns the optional per-session transaction id from the
+// environment, or "" when unset.
+//
+// NOTE: +undo does NOT use this id to locate edits — the server addresses undo
+// by document revision (the `rev` a write returns; see +undo --rev), not by
+// transaction id. This env var's only purpose is optional concurrency
+// isolation: write tools persist their reverse ("undo") changeset keyed by the
+// request's transaction id, and the server mints a fresh uuid per request when
+// none is supplied, so each invocation lands in its own undo stack by default.
+// Set a stable id across commands only to deliberately share one isolated undo
+// stack across a group of edits; empty preserves the per-request default and is
+// the norm.
+func sheetTransactionID() string {
+	return strings.TrimSpace(os.Getenv(sheetTxnIDEnv))
+}
+
 // ToolKind selects the One-OpenAPI endpoint and its rate-limit bucket.
 //
 //   - ToolKindRead  → POST .../tools/invoke_read   (scope sheets:spreadsheet:read,       10 qps)
@@ -39,15 +61,27 @@ func toolInvokePath(token string, kind ToolKind) string {
 // buildToolBody constructs the One-OpenAPI request body for a tool invocation.
 // `input` is serialized to a JSON string per the API contract; callers pass
 // a typed Go map and never need to handle JSON encoding themselves.
-func buildToolBody(toolName string, input map[string]interface{}) (map[string]interface{}, error) {
+func buildToolBody(kind ToolKind, toolName string, input map[string]interface{}) (map[string]interface{}, error) {
 	inputJSON, err := json.Marshal(input)
 	if err != nil {
 		return nil, fmt.Errorf("encode tool input: %w", err)
 	}
-	return map[string]interface{}{
+	body := map[string]interface{}{
 		"tool_name": toolName,
 		"input":     string(inputJSON),
-	}, nil
+	}
+	// Thread a session-stable transaction id (when provided) so a group of
+	// edits and a later +undo share one undo stack. Omitted when unset, leaving
+	// the server to mint a per-request id as before. Only write tools join the
+	// undo transaction; reads must never carry it — a read scoped to a
+	// transaction id resolves against that transaction's (often empty) snapshot
+	// instead of the live document, so it would read back blank.
+	if kind == ToolKindWrite {
+		if txID := sheetTransactionID(); txID != "" {
+			body["extra"] = map[string]interface{}{"transaction_id": txID}
+		}
+	}
+	return body, nil
 }
 
 // callTool invokes a sheet-ai tool via the One-OpenAPI endpoint and decodes
@@ -65,7 +99,7 @@ func callTool(
 	toolName string,
 	input map[string]interface{},
 ) (interface{}, error) {
-	body, err := buildToolBody(toolName, input)
+	body, err := buildToolBody(kind, toolName, input)
 	if err != nil {
 		return nil, err
 	}
@@ -109,7 +143,7 @@ func invokeToolDryRun(
 	toolName string,
 	input map[string]interface{},
 ) *common.DryRunAPI {
-	wireBody, _ := buildToolBody(toolName, input)
+	wireBody, _ := buildToolBody(kind, toolName, input)
 	return common.NewDryRunAPI().
 		POST(toolInvokePath(token, kind)).
 		Body(wireBody).

shortcuts/sheets/sheet_ai_api_test.go

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import "testing"
+
+// cellsSetArgs is a minimal valid +cells-set invocation used to inspect the
+// tool-call request body.
+func cellsSetArgs() []string {
+	return []string{
+		"--spreadsheet-token", testToken,
+		"--sheet-id", testSheetID,
+		"--range", "A1",
+		"--cells", `[[{"value":"x"}]]`,
+	}
+}
+
+// TestBuildToolBody_ThreadsTransactionID verifies that a session-stable
+// transaction id from the environment is threaded into the request body's
+// extra.transaction_id, so a group of edits and a later +undo share one undo
+// stack.
+func TestBuildToolBody_ThreadsTransactionID(t *testing.T) {
+	t.Setenv(sheetTxnIDEnv, "tx_test_123")
+	body := parseDryRunBody(t, CellsSet, cellsSetArgs())
+	extra, ok := body["extra"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("extra missing from body: %#v", body)
+	}
+	if extra["transaction_id"] != "tx_test_123" {
+		t.Errorf("transaction_id = %#v, want tx_test_123", extra["transaction_id"])
+	}
+}
+
+// TestBuildToolBody_OmitsTransactionIDWhenUnset verifies the body carries no
+// extra when the env var is empty, preserving the per-request default.
+func TestBuildToolBody_OmitsTransactionIDWhenUnset(t *testing.T) {
+	t.Setenv(sheetTxnIDEnv, "")
+	body := parseDryRunBody(t, CellsSet, cellsSetArgs())
+	if _, ok := body["extra"]; ok {
+		t.Errorf("extra should be absent when %s is unset: %#v", sheetTxnIDEnv, body)
+	}
+}
+
+// TestBuildToolBody_OmitsTransactionIDForReads verifies that read tools never
+// carry a transaction id even when one is set: a read scoped to a transaction
+// resolves against that transaction's snapshot (often empty) instead of the
+// live document, so threading it would make reads return blank cells.
+func TestBuildToolBody_OmitsTransactionIDForReads(t *testing.T) {
+	t.Setenv(sheetTxnIDEnv, "tx_test_123")
+	body := parseDryRunBody(t, CellsGet, []string{
+		"--url", testURL, "--sheet-id", testSheetID, "--range", "A1",
+	})
+	if _, ok := body["extra"]; ok {
+		t.Errorf("read tool must not carry extra.transaction_id: %#v", body)
+	}
+}

shortcuts/sheets/shortcuts.go

@@ -38,8 +38,11 @@ func shortcutList() []common.Shortcut {
 		SheetHide,
 		SheetUnhide,
 		SheetSetTabColor,
+		SheetShowGridline,
+		SheetHideGridline,
 		WorkbookCreate,
 		WorkbookExport,
+		WorkbookImport,
 
 		// lark_sheet_sheet_structure
 		SheetInfo,
@@ -56,6 +59,10 @@ func shortcutList() []common.Shortcut {
 		CellsGet,
 		CsvGet,
 		DropdownGet,
+		TableGet,
+
+		// lark_sheet_undo
+		Undo,
 
 		// lark_sheet_search_replace
 		CellsSearch,
@@ -67,6 +74,7 @@ func shortcutList() []common.Shortcut {
 		CellsSetImage,
 		CsvPut,
 		DropdownSet,
+		TablePut,
 
 		// lark_sheet_range_operations
 		CellsClear,

skill-template/domains/contact.md

@@ -0,0 +1,33 @@
+## 选哪个命令
+
+**user 身份和 bot 身份是两条完全独立的路径**。先确定当前身份,再按下表选命令:
+
+| 想做什么 | user 身份 | bot 身份 |
+|---|---|---|
+| 按姓名 / 邮箱搜员工拿 open_id | [`+search-user`](references/lark-contact-search-user.md) | 不支持 |
+| 已知 open_id 取他人资料 | `+search-user --user-ids <id>` | [`+get-user --user-id <id>`](references/lark-contact-get-user.md) |
+| 查看自己 | `+get-user` 或 `+search-user --user-ids me` | 不支持 |
+
+已知 open_id 只是想发消息 / 排日程,不必经过 contact —— 直接 [`lark-im`](../lark-im/SKILL.md) / [`lark-calendar`](../lark-calendar/SKILL.md)。
+
+## 典型场景
+
+```bash
+# 找张三给他发消息:先搜,确认 open_id,再发
+lark-cli contact +search-user --query "张三" --has-chatted --as user
+lark-cli im +messages-send --user-id ou_xxx --text "Hi!"
+```
+
+搜索命中多条且后续操作有副作用(发消息、邀请会议等),把候选列给用户挑;不要擅自选第一条。
+
+## 注意事项
+
+- **41050 / Permission denied** 受当前身份的可见范围限制(两条命令都可能遇到)。换 bot 身份或让管理员调整可见范围,细节见 [`lark-shared`](../lark-shared/SKILL.md)。
+- **跨租户用户**(`is_cross_tenant=true`)多数业务字段为空字符串,这是飞书可见性规则,下游做空值兜底。
+- **ID 类型**:默认 `open_id`。`+get-user` 可改 `--user-id-type union_id|user_id`;`+search-user` 只接受 `open_id`。
+
+## 不在本 skill 范围
+
+- 发消息 / 查聊天记录 → [`lark-im`](../lark-im/SKILL.md)
+- 排日程 / 邀请会议 → [`lark-calendar`](../lark-calendar/SKILL.md)
+- 部门树 / 按部门列员工 / 组织架构 → [`lark-openapi-explorer`](../lark-openapi-explorer/SKILL.md) 查找原生接口

skills/lark-contact/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: lark-contact
 version: 1.0.0
-description: "飞书 / Lark 通讯录,用于按姓名 / 邮箱把员工解析成 open_id,以及按 open_id 反查员工的姓名 / 部门 / 邮箱 / 联系方式。当用户说出某人姓名而下一步需要发消息 / 加群 / 排日程时,先用本 skill 把姓名换成 ID;当输出里出现 open_id 需要展示成姓名给用户看,或用户直接询问某人的部门 / 邮箱 / 联系方式时,用本 skill 查。不负责部门树遍历、按部门列员工、组织架构图,这类需求走原生 OpenAPI。"
+description: "飞书 / Lark 通讯录:按姓名 / 邮箱解析成 open_id,或按 open_id 反查姓名 / 部门 / 邮箱 / 联系方式 / 个人状态 / 签名。当用户提到某人姓名要下一步发消息 / 排日程,或拿到 open_id 想查具体信息时使用。不负责部门树遍历、按部门列员工、组织架构图,这类需求走原生 OpenAPI。"
 metadata:
   requires:
     bins: ["lark-cli"]
   cliHelp: "lark-cli contact --help"
 ---
 
-# lark-contact
+# contact (v2)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
 ## 选哪个命令
 
@@ -19,17 +21,29 @@ metadata:
 | 按姓名 / 邮箱搜员工拿 open_id | [`+search-user`](references/lark-contact-search-user.md) | 不支持 |
 | 已知 open_id 取他人资料 | `+search-user --user-ids <id>` | [`+get-user --user-id <id>`](references/lark-contact-get-user.md) |
 | 查看自己 | `+get-user` 或 `+search-user --user-ids me` | 不支持 |
+| 查同事的个人状态 / 签名 | `user_profiles batch_query` | 不支持 |
 
 已知 open_id 只是想发消息 / 排日程,不必经过 contact —— 直接 [`lark-im`](../lark-im/SKILL.md) / [`lark-calendar`](../lark-calendar/SKILL.md)。
 
 ## 典型场景
 
+找张三给他发消息:先搜,确认 open_id,再发:
+
 ```bash
-# 找张三给他发消息:先搜,确认 open_id,再发
 lark-cli contact +search-user --query "张三" --has-chatted --as user
 lark-cli im +messages-send --user-id ou_xxx --text "Hi!"
 ```
 
+批量查同事的个人状态 / 个性签名(先用 schema 看参数)。
+
+```bash
+lark-cli schema contact.user_profiles.batch_query
+lark-cli contact user_profiles batch_query \
+  --params '{"user_id_type":"open_id"}' \
+  --data '{"user_ids":["ou_xxx","ou_yyy"],"query_option":{"include_personal_status":true,"include_description":true}}' \
+  --as user
+```
+
 搜索命中多条且后续操作有副作用(发消息、邀请会议等),把候选列给用户挑;不要擅自选第一条。
 
 ## 注意事项
@@ -42,4 +56,4 @@ lark-cli im +messages-send --user-id ou_xxx --text "Hi!"
 
 - 发消息 / 查聊天记录 → [`lark-im`](../lark-im/SKILL.md)
 - 排日程 / 邀请会议 → [`lark-calendar`](../lark-calendar/SKILL.md)
-- 部门树 / 按部门列员工 / 组织架构 ,通过 [`lark-openapi-explorer`](../lark-openapi-explorer/SKILL.md) 查找原生接口
+- 部门树 / 按部门列员工 / 组织架构 → [`lark-openapi-explorer`](../lark-openapi-explorer/SKILL.md) 查找原生接口

skills/lark-drive/SKILL.md

@@ -295,12 +295,14 @@ lark-cli drive <resource> <method> [flags] # 调用 API
 ```
 
 > **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+>
+> **高频原生命令：** 读取 Drive 文件夹清单时使用 `drive files list`，必须按 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md) 的模板通过 `--params` 传 `folder_token` / `page_token`，并手动处理分页；不要把 `--page-all` 输出直接交给 JSON 解析脚本。
 
 ### files
 
   - `copy` — 复制文件
   - `create_folder` — 新建文件夹
-  - `list` — 获取文件夹下的清单
+  - `list` — 获取文件夹下的清单；使用前阅读 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md)
   - `patch` — 修改文件标题
 
 ### file.comments

skills/lark-drive/references/lark-drive-files-list.md

@@ -0,0 +1,158 @@
+# drive files list（原生 API：读取 Drive 文件夹清单）
+
+`drive files list` 是原生 API 命令，不是 shortcut。它用于读取 Drive 根目录或某个 Drive 文件夹的直接子项；如果要递归盘点目录树，Agent 必须基于返回的子文件夹 token 继续调用本命令。
+
+## 什么时候使用
+
+| 场景 | 是否使用 | 说明 |
+|------|----------|------|
+| 盘点一个已确认的 Drive 文件夹树 | 使用 | 从目标 `folder_token` 开始递归列取 |
+| 盘点用户明确确认的 Drive 根目录 | 使用 | 第一层用空 `folder_token`，子文件夹继续按普通文件夹递归 |
+| 验证移动 / 创建后的实际位置 | 使用 | 读取目标目录直接子项，再按需递归验证 |
+| 根据关键词、标题、时间、owner 找资源 | 不使用 | 优先用 `drive +search` |
+| 读取 Docx 正文内容 | 不使用 | 用 `docs +fetch --api-version v2` |
+| 读取 Sheet / Base 内部数据 | 不使用 | 切到 `lark-sheets` / `lark-base` |
+
+## 标准命令模板
+
+读取普通文件夹：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","page_size":200}' \
+  --format json
+```
+
+继续翻页：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","page_size":200,"page_token":"<PAGE_TOKEN>"}' \
+  --format json
+```
+
+读取当前用户 Drive 根目录的直接子项：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"","page_size":200}' \
+  --format json
+```
+
+也可以省略 `folder_token` 字段来请求根目录，但在 Agent 编排中建议显式传空字符串，避免把“忘记传参数”和“确认请求根目录”混在一起。
+
+## 参数规则
+
+1. `folder_token` 必须放在 `--params` JSON 里；不要使用不存在的 `--folder-token` flag。
+2. `page_token` 必须放在 `--params` JSON 里；不要依赖 shell 变量拼接不完整的 JSON。
+3. `page_size` 建议显式设置为 `200`。如果服务端或环境返回参数错误，再降级到服务端允许的值，并记录降级原因。
+4. 调用前如果不确定字段结构，先运行 `lark-cli schema drive.files.list` 查看 `--params` 结构。
+
+## 返回结构与解析
+
+`--format json` 输出中，Agent 只使用 `data` 中符合 `schema drive.files.list` 的 API 返回字段。
+
+常用字段：
+
+| 字段 | 用途 |
+|------|------|
+| `data.files` | 当前页直接子项列表 |
+| `data.has_more` | 当前目录是否还有下一页 |
+| `data.next_page_token` | 下一页 token；当 `has_more=true` 时放回 `--params.page_token` |
+| `data.files[].type` | 文件类型；等于 `folder` 时可递归 |
+| `data.files[].token` | 当前资源 token；文件夹递归时作为下一层 `folder_token` |
+| `data.files[].name` | 生成路径和展示标题 |
+| `data.files[].url` | 资源浏览器链接 |
+| `data.files[].owner_id` | 资源所有者 |
+| `data.files[].created_time` / `data.files[].modified_time` | 创建 / 更新时间 |
+
+字段名以 `schema drive.files.list` 为准。Agent MUST 以实际返回为准；如果字段缺失，先用 `schema drive.files.list` 或一页样本确认结构，不要猜测。
+
+## 根目录语义
+
+1. `folder_token` 为空字符串或省略时，请求的是当前调用用户的 Drive 根目录直接子项。
+2. 根目录返回值不是递归结果；不能把根目录第一页或直接子项数量当作整个云空间资源总量。
+3. 根目录只作为目录树起点。返回的子文件夹必须用其自己的 `folder_token` 继续调用 `drive files list`。
+4. 根据 schema 描述，根目录第一层清单不支持分页且不返回快捷方式；不要基于根目录响应推断子文件夹内容、根目录第一层快捷方式或无法分页的根目录剩余项已经被覆盖。
+
+## 递归盘点规则
+
+1. 只对返回项中的 `folder` 类型继续递归。
+2. 每个目录独立维护分页状态；一个目录的 `page_token` 不可复用于其他目录。
+3. 对每个目录持续请求，直到返回 `has_more=false`。非根目录的普通文件夹清单可能返回 `type=shortcut` 条目；不要假设这些条目会携带 `shortcut_info` 目标信息。
+4. 递归过程中生成稳定 `path`；不要只保存标题，否则同名资源无法区分。
+5. URL、owner、创建时间和更新时间优先使用 `files.list` 返回字段；如果字段缺失或需要批量补齐，再使用 `drive metas batch_query`。不要从标题或路径猜元数据。
+6. 深度、数量、每目录页数等限制只能作为内部批次 checkpoint；不能作为递归完成条件。
+7. 达到深度 checkpoint 时，把更深层子文件夹加入 continuation queue，并在下一批从这些子文件夹继续，保留原始 `path`。
+8. 达到数量 checkpoint 时，保存当前目录、当前页 token、剩余目录队列和已收集资源计数，并立即继续下一批；不要进入分析或规划阶段。
+
+### 递归算法
+
+Agent 盘点 Drive 文件夹树时，按以下顺序执行：
+
+1. 初始化待处理队列，放入起点目录：
+   - 普通文件夹：`{folder_token:"<folder_token>", path:"<folder_name>"}`
+   - Drive 根目录：`{folder_token:"", path:""}`
+2. 从队列取出一个目录，请求第一页。
+3. 用 `(folder_token, page_token)` 生成当前页 key；同一页 key 只允许追加一次，避免 retry 时重复计数。
+4. 从 `data.files` 取当前页直接子项，按 `dedupe_key` 去重后生成 `path` 并加入结果集。
+5. 如果新追加的子项是 `folder`，把子文件夹 token、子路径和 depth 加入队列。
+6. 如果 `has_more=true`，取 `data.next_page_token` 继续请求同一目录下一页。
+7. 同一目录分页结束后，再处理队列中的下一个目录。
+8. 如果达到深度、数量或每目录页数 checkpoint，把当前目录 / 页 token / 剩余队列 / 已访问页 key / dedupe key 写入 continuation queue，并继续下一批。
+9. 普通队列和 continuation queue 都为空，且没有分页 blocker 时，才可以认为本次确认范围盘点完成。
+
+简化伪代码：
+
+```text
+queue = [root_or_start_folder]
+visited_pages = set()
+dedupe_keys = set()
+while queue not empty:
+  folder = queue.pop()
+  page_token = folder.page_token or ""
+  retry_without_token = 0
+  while true:
+    page_key = (folder.folder_token, page_token or "first")
+    page = drive files list(folder.folder_token, page_token)
+    if page_key not in visited_pages:
+      append only files whose dedupe_key is not in dedupe_keys
+      enqueue newly appended child folders with folder_token, path, and depth
+      add page_key to visited_pages
+    if page.has_more != true:
+      break
+    next = page.next_page_token
+    if next is empty:
+      retry_without_token += 1
+      if retry_without_token >= 3:
+        record pagination blocker for folder
+        break
+      continue
+    page_token = next
+    retry_without_token = 0
+```
+
+## 分页与异常
+
+1. 默认手动处理 `has_more` 和返回中的 `next_page_token`。
+2. 不要使用 `--page-all` 作为脚本 JSON 解析输入；自动翻页输出可能不适合直接 `json.loads`。
+3. 如果 `has_more=true` 但没有可用的 `next_page_token`，重试同一页最多 3 次。
+4. 重试后仍无 continuation token 时，记录受影响的目录和 pagination blocker，停止扩展该目录；不要无限循环，也不要宣称该目录已完整覆盖。
+5. 如果触发深度、数量或每目录页数限制，把它视为批处理 checkpoint；在确认范围内继续下一批，而不是把当前结果说成完整。
+6. 不要因为达到 `max_depth=3`、`max_items=500` 或类似单批阈值就结束盘点；只有队列耗尽或遇到权限 / API / 工具预算 blocker 才能结束当前确认范围的盘点。
+
+## JSON 解析规则
+
+1. stdout 是数据通道。脚本解析 JSON 时只读取 stdout。
+2. stderr 可能包含刷新 token、进度、warning 或其他提示；不要把 stderr 合并进 JSON 输入，例如不要用 `2>&1` 后再 `json.loads`。
+3. 使用 `--format json` 保持 stdout 为结构化 JSON；解析 Drive 文件清单时只读取 `data.files` / `data.has_more` / `data.next_page_token` 等 schema 字段。
+4. 不要用根目录响应数量或当前页数量推断递归总量；递归总量必须由实际遍历并去重后的资源集合计算。
+
+## 常见错误
+
+| 错误用法 | 问题 | 正确做法 |
+|----------|------|----------|
+| `lark-cli drive files list --folder-token <token>` | `files.list` 不提供 `--folder-token` flag | 使用 `--params '{"folder_token":"<token>"}'` |
+| 根目录返回 N 项就认为云空间只有 N 项 | 根目录只返回直接子项，不是递归结果 | 对返回的子文件夹继续递归 |
+| `--page-all \| python json.loads(...)` | 自动翻页输出不适合作为单个 JSON 对象解析 | 手动使用 `page_token` 翻页并逐页解析 |
+| `cmd 2>&1` 后解析 JSON | stderr 提示污染 JSON 输入 | 只解析 stdout，stderr 作为日志处理 |

skills/lark-drive/references/lark-drive-workflow-knowledge-organize-analysis.md

@@ -24,7 +24,8 @@ MUST:
 4. Switch to `lark-sheets` / `lark-base` only when sheet / bitable title and path are insufficient.
 5. Record read evidence for classification.
 6. Continue reading low-confidence resources in internal batches until all supported low-confidence resources in the current inventory are processed or a blocker occurs.
-7. Output progress / summary without asking the user to continue between batches.
+7. Apply `Analysis Progress Reporting`.
+8. Output progress / summary without asking the user to continue between batches.
 
 Exit: low-confidence items are classified or marked `needs_review=true`.
 
@@ -93,6 +94,30 @@ Output this summary:
 
 - After every 50 processed low-confidence resources.
 - Once after low-confidence reading finishes.
+- About every 60 seconds during long-running reads, even if fewer than 50 additional resources were processed.
+
+### Analysis Progress Reporting
+
+Applies to `CONTENT_READ`, `ISSUE_ANALYSIS`, and `RULE_GENERATION`.
+
+Rules:
+
+1. For `CONTENT_READ`, use `Low-Confidence Read Summary` as the progress report format.
+2. For `ISSUE_ANALYSIS`, if analysis runs longer than about 60 seconds, output progress about every 60 seconds with current stage, processed resource count when known, detected problem type count when known, and the next analysis step.
+3. For `RULE_GENERATION`, if classification rule or target-tree generation runs longer than about 60 seconds, output progress about every 60 seconds with current stage, classified item count when known, unresolved item count when known, and target category / path count when known.
+4. Progress reports MUST be factual and stage-specific. Do not output generic "still running" messages without counts or the current stage.
+5. Do not ask the user to continue between internal batches unless auth, permission, API, target scope, or environment blockers occur.
+6. Do not expose internal chain-of-thought, raw tokens, or intermediate rule drafts.
+
+Examples:
+
+```text
+分析进度：正在归纳整理问题，已处理 <processed_count>/<resource_count> 项资源，已识别 <problem_type_count> 类问题。继续生成整理思路，不会执行移动或创建。
+```
+
+```text
+规则生成进度：正在生成分类规则和目标目录，已归类 <classified_count> 项，待人工确认 <needs_review_count> 项。继续生成完整计划前置数据。
+```
 
 ## State: ISSUE_ANALYSIS
 
@@ -103,8 +128,9 @@ MUST:
 1. Detect problems from organization perspective only. Do not generate research conclusions.
 2. Generate an organization approach based on inventory, low-confidence read evidence, and detected problems.
 3. Include how non-reused source containers will be handled after their contents are moved.
-4. Output `Inventory And Organization Approach Decision`.
-5. Stop and wait for the user to confirm the approach before `RULE_GENERATION`.
+4. Apply `Analysis Progress Reporting`.
+5. Output `Inventory And Organization Approach Decision`.
+6. Stop and wait for the user to confirm the approach before `RULE_GENERATION`.
 
 Problem rules:
 
@@ -161,10 +187,10 @@ MUST output evidence count or example paths. Do not output only abstract judgmen
 是否基于这个整理思路生成目标目录和移动 / 创建计划？
 
 你可以选择：
-A. 基于这个思路生成目标目录和计划
-B. 调整整理思路
-C. 查看问题详情
-D. 取消本次整理
+1. 基于这个思路生成目标目录和计划
+2. 调整整理思路
+3. 查看问题详情
+4. 取消本次整理
 ```
 
 ## State: RULE_GENERATION
@@ -181,7 +207,8 @@ MUST:
 6. For non-reused source containers, ensure `target_tree` includes a source-container cleanup target, defaulting to `待人工确认/待清理旧目录`, unless the user explicitly asks to keep source containers in place.
 7. Ensure target tree can contain every planned `target_path`.
 8. Ensure the target tree contains a manual confirmation target named `待人工确认` unless the user explicitly provides an equivalent name.
-9. Continue to `PLAN_GENERATION` without a separate target-tree-only confirmation.
+9. Apply `Analysis Progress Reporting`.
+10. Continue to `PLAN_GENERATION` without a separate target-tree-only confirmation.
 
 ### Classification
 

skills/lark-drive/references/lark-drive-workflow-knowledge-organize-discovery.md

@@ -10,8 +10,9 @@ Before executing rules in this file:
 
 1. Follow [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) for identity, auth, and permission handling.
 2. For Wiki / personal library targets, follow [`../../lark-wiki/SKILL.md`](../../lark-wiki/SKILL.md).
-3. For Drive search targets, follow [`lark-drive-search.md`](lark-drive-search.md).
-4. For URL / token inspection, follow [`lark-drive-inspect.md`](lark-drive-inspect.md) and [`../../lark-wiki/references/lark-wiki-node-get.md`](../../lark-wiki/references/lark-wiki-node-get.md).
+3. For Drive folder inventory, follow [`lark-drive-files-list.md`](lark-drive-files-list.md).
+4. For Drive search targets, follow [`lark-drive-search.md`](lark-drive-search.md).
+5. For URL / token inspection, follow [`lark-drive-inspect.md`](lark-drive-inspect.md) and [`../../lark-wiki/references/lark-wiki-node-get.md`](../../lark-wiki/references/lark-wiki-node-get.md).
 
 ## State: PARSE_SCOPE
 
@@ -87,6 +88,10 @@ Clarification template:
 请确认是否按这个范围继续？
 ```
 
+Scope confirmation is user-facing. It MUST confirm only the business scope, environment / profile, identity, and whether write operations will run.
+
+Do not display internal batching controls in scope confirmation, including `max_depth`, `max_items`, `page_size`, page tokens, retry counts, or `partial=true`. For example, when the user confirms Drive root, say the scope is the Drive root tree; do not append "recursive depth at most 3" or "at most 500 resources".
+
 ## State: INVENTORY
 
 Entry: `target_scope` confirmed.
@@ -96,20 +101,57 @@ MUST:
 1. Recursively list resources according to target type.
 2. Generate `path` during traversal.
 3. Normalize all results to `ResourceItem`.
-4. Track pagination, depth, and item limits.
-5. Set `partial=true` when limits are hit.
-6. Output `Inventory Summary`.
-7. Continue to `CONTENT_READ` without asking the user unless auth, permission, API, target scope, or environment blockers occur.
+4. Track pagination, depth, item limits, and continuation checkpoints.
+5. Treat pagination, depth, item, and per-folder page limits as batching checkpoints; continue inventory in the confirmed scope unless blocked.
+6. Set `partial=true` only when inventory cannot continue because of auth, permission, API / pagination failure after retries, API coverage limitations, tool budget, target scope, or environment blockers.
+7. Apply `Inventory Progress Reporting`.
+8. Output `Inventory Summary`.
+9. Do not leave `INVENTORY` while `inventory_continuation_state` has queued folders, nodes, pages, or slices that can still be fetched.
+10. Continue to `CONTENT_READ` without asking the user only after the confirmed scope is exhausted or blocked.
 
-### Inventory Limits
+### Inventory Batch Checkpoints
 
-| Scope | Default Limit | If Limit Is Hit |
-|-------|---------------|-----------------|
-| Wiki recursion | `max_depth=3`, `max_items=500`; follow `lark-wiki-node-list` pagination | Set `partial=true`; list covered paths and suggested next first-level directories |
-| Drive folder recursion | `max_depth=3`, `max_items=500`, max 10 pages per folder, `page_size=50` | Set `partial=true`; list folders not drilled into |
-| Search discovery | `page_size=20`, `max_items=500`; continue pages until `has_more=false` or `max_items` is reached | Set `partial=true`; report collected_count, service_total when available, page_count, and continuation information |
+| Scope | Internal Batch Checkpoint | Required Continuation |
+|-------|---------------------------|-----------------------|
+| Wiki recursion | `max_depth=3`, `max_items=500`; follow `lark-wiki-node-list` pagination | Record queued nodes / paths in `inventory_continuation_state` and immediately continue the next internal batch within the confirmed scope unless blocked |
+| Drive folder tree | `max_depth=3`, `max_items=500`, max 10 pages per folder, `page_size=200` | Record queued folders / pages in `inventory_continuation_state` and immediately continue the next internal batch within the confirmed scope unless blocked |
+| Search discovery | `page_size=20`, `max_items=500`; continue pages until `has_more=false` | Record remaining pages / slices in `inventory_continuation_state` and immediately continue the next internal batch within the confirmed scope unless blocked |
 
-If the user explicitly asks for full processing, batch by first-level directory, Wiki space, or time window. Do not remove all limits in one run.
+These checkpoints are pacing controls, not coverage limits. If the confirmed scope still has queued work after a checkpoint, continue with the next internal batch instead of presenting the current `resource_items` as final inventory or moving to content analysis.
+
+When a depth checkpoint is reached, enqueue the child folders / nodes that would exceed the current batch depth; the next batch starts from those queued children with their original paths preserved. When an item checkpoint is reached, persist the current folder / node / page cursor plus the remaining queue, visited page keys, and resource dedupe keys, then continue from that checkpoint before analysis or planning.
+
+If tool budget would be exceeded for a very large confirmed scope, stop only at that blocker, report that the inventory is incomplete, and suggest batching by first-level directory, Wiki space, or time window. Do not stop merely because a depth or item checkpoint was reached.
+
+### Inventory Continuation Rules
+
+1. Pagination, depth, item, and per-folder page limits are internal batching checkpoints.
+2. When a checkpoint is reached, record `inventory_continuation_state` with `scope`, `queue`, `current_cursor`, `visited_page_keys`, `dedupe_keys`, and `blockers`; Drive queue entries MUST contain `folder_token`, `path`, `depth`, and `page_token`; Wiki queue entries MUST contain `space_id` / `node_token`, `path`, `depth`, and pagination cursor; search entries MUST contain query / filters and pagination cursor.
+3. A depth checkpoint MUST enqueue deeper folders / nodes; it MUST NOT discard them or treat the current depth as final coverage.
+4. An item-count checkpoint MUST persist the current cursor and queue; it MUST NOT transition to `CONTENT_READ`, `ISSUE_ANALYSIS`, or `PLAN_GENERATION` while fetchable work remains.
+5. If `inventory_continuation_state` is missing, corrupt, or lacks required fields for the current scope, set `partial=true`, record the checkpoint blocker, and do not claim full coverage.
+6. Do not set `partial=true` solely because a valid batching checkpoint was reached.
+7. Set `partial=true` only when continuation is blocked by auth, permission, API / pagination failure after retries, API coverage limitations, tool budget, target scope, or environment blockers.
+8. Do not claim full coverage until the continuation queue for the confirmed scope is exhausted or blocked.
+
+### Inventory Progress Reporting
+
+Inventory can be long-running when a Drive root, large folder tree, Wiki space, or broad search scope is confirmed.
+
+Rules:
+
+1. When inventory starts, output one concise stage notice with the confirmed scope type and the fact that no write operation will be executed.
+2. If inventory runs longer than about 60 seconds, output progress about every 60 seconds.
+3. Progress reports SHOULD include only fields that are currently known: scanned folders / nodes, collected resources, current depth, queued folders / nodes, current search page / slice, and current blocker if any.
+4. When a batching checkpoint is reached and continuation will proceed automatically, report it as continuing inventory, not as a user action request.
+5. Do not output filler such as "still running" without current counts or current stage.
+6. Do not expose raw folder tokens, page tokens, retry logs, or `partial=true` unless the user explicitly asks to view inventory coverage details.
+
+Example:
+
+```text
+盘点进度：已扫描 <scanned_container_count> 个目录 / 节点，收集 <resource_count> 项资源，队列剩余 <queued_container_count> 个目录 / 节点。继续盘点，不会执行移动或创建。
+```
 
 ### Wiki Inventory Rules
 
@@ -120,11 +162,13 @@ If the user explicitly asks for full processing, batch by first-level directory,
 
 ### Drive Inventory Rules
 
-1. Use CLI command family `drive files list` according to `lark-drive` API rules; its schema path is `drive.files.list`.
-2. Recurse only into `folder` items.
-3. Use `drive metas batch_query` when URL, owner, created time, or updated time is needed.
-4. Continue pages by feeding `next_page_token` into request param `page_token`.
-5. Prefer explicit `folder_token`; querying root with empty `folder_token` may return broad root data and may not paginate as expected.
+1. Use `drive files list` according to [`lark-drive-files-list.md`](lark-drive-files-list.md); its schema path is `drive.files.list`.
+2. Use the same Drive folder-tree traversal for Drive root and ordinary folders after the first request. Drive root differs only for the first-level request: it uses omitted or empty `folder_token`, does not support pagination, and does not return root-level shortcuts according to schema; returned child folders MUST still be listed by their own folder tokens like ordinary folders, and those ordinary folder lists may return `type=shortcut` entries. For a Drive root target, record this root-level shortcut coverage caveat, set `partial=true` only if the user requested full root-level shortcut coverage or root pagination cannot continue, and do not claim root-level shortcut coverage as complete.
+3. Recurse only into `folder` items within the confirmed scope.
+4. For each directory, continue pages manually by feeding the returned `next_page_token` into request param `page_token`. Do not rely on `--page-all` for inventory.
+5. If a page returns `has_more=true` but no usable `next_page_token`, retry the same page request up to 3 times. If retries still cannot produce a continuation token, set `partial=true` for that directory and record the pagination blocker.
+6. Use `drive metas batch_query` when URL, owner, created time, or updated time is needed.
+7. Pagination blocker details such as `partial=true`, folder token, page token, and retry logs are internal by default. Do not show them to the user unless the user explicitly asks to view inventory coverage details.
 
 ### Search Inventory Rules
 
@@ -132,10 +176,11 @@ If the user explicitly asks for full processing, batch by first-level directory,
 2. If a search result is a Wiki item and lacks `node_token`, resolve it with `drive +inspect` or `wiki +node-get` before dedupe.
 3. If Wiki identity still cannot be resolved, keep the item, set `needs_review=true`, and record `needs_review_reason`.
 4. For search scope, use `page_size=20` unless a lower value is required by the command.
-5. Continue fetching pages until `has_more=false` or `max_items` is reached.
-6. Do not stop at an arbitrary sample size such as first 5 pages unless the user explicitly asks for sampling or auth, permission, API, environment, or tool-budget blockers occur.
-7. If `service_total` / result total is greater than collected items, set `partial=true` and show collected_count, service_total, page_count, and continuation information.
-8. Do not present a partial search sample as complete inventory. Before generating a full organization plan from partial search results, ask whether to continue fetching more pages or proceed with sample-based planning.
+5. Continue fetching pages until `has_more=false`.
+6. If `max_items=500` is reached in one batch, record the current search cursor in `inventory_continuation_state` and continue the next internal batch without asking the user.
+7. Do not stop at an arbitrary sample size such as first 5 pages unless the user explicitly asks for sampling or auth, permission, API, environment, or tool-budget blockers occur.
+8. If `service_total` / result total is greater than collected items, treat it as continuation evidence: continue fetching when a cursor / page is available; set `partial=true` only if continuation is blocked.
+9. Do not present a partial search sample as complete inventory. Before generating a full organization plan from partial search results, continue fetching available pages unless the user explicitly asked for sampling or a blocker prevents continuation.
 
 ## ResourceItem
 
@@ -179,7 +224,9 @@ ResourceItem rules:
 ## Inventory Summary
 
 ```text
-已完成盘点。
+已完成当前可覆盖范围盘点。
+
+<仅当适用：覆盖说明：Drive 根目录第一层清单不返回快捷方式；本次盘点不包含根目录第一层快捷方式。根目录下子文件夹会按普通文件夹继续盘点，普通文件夹内返回的 `type=shortcut` 条目仍会被纳入资源清单。>
 
 | 指标 | 数量 |
 |------|------|
@@ -202,4 +249,5 @@ ResourceItem rules:
 | Environment / profile is ambiguous | Ask user to confirm prod / BOE / PRE and profile | Do not cross environment boundaries |
 | Missing API scope | Follow `lark-shared` permission handling and stop | Do not retry the same command repeatedly |
 | Resource access denied | Stop and follow the main workflow `Permission Request Gate` | Do not request permission automatically or in batch |
-| Pagination / depth / item limit reached | Set `partial=true`; record uncovered range and continuation command | Do not claim full coverage |
+| Pagination / depth / item checkpoint reached | Record `inventory_continuation_state` and continue inventory in the confirmed scope | Do not set `partial=true` solely because a batching checkpoint was reached |
+| Pagination cursor missing after retries / API pagination failure | Set `partial=true`; record the affected directory and blocker | Do not loop indefinitely or claim full coverage |

skills/lark-drive/references/lark-drive-workflow-knowledge-organize-planning.md

@@ -24,7 +24,8 @@ MUST:
 4. Apply `Plan Pagination`.
 5. Set `active_plan_items` to the latest complete plan.
 6. Keep complete plan internally even if only one page is displayed.
-7. Output `Target Tree And Plan Overview` or requested plan page, then wait.
+7. Apply `Plan Generation Progress Reporting`.
+8. Output `Target Tree And Plan Overview` or requested plan page, then wait.
 
 ### Plan Generation
 
@@ -44,6 +45,25 @@ MUST:
 | Target parent token unresolved | Keep plan item but block execution until token is resolved |
 | Resource title is poor or inconsistent | Report the naming issue only; do not create rename or title-patch plan items |
 
+### Plan Generation Progress Reporting
+
+Plan generation can be long-running when `resource_items` is large or source-container parent / child move ordering is complex.
+
+Rules:
+
+1. If plan generation starts with more than 500 `resource_items`, output one concise start notice with the resource count and that no write operation is being executed.
+2. If plan generation runs longer than about 60 seconds, output progress about every 60 seconds.
+3. Progress reports SHOULD include only fields currently known: processed resource count, generated plan item count, create count, move count, source-container move count, review count, and current step.
+4. Do not display unpaginated plan details as progress. Complete `plan_items` remain internal until the normal paginated output.
+5. Do not ask the user to continue during plan generation unless auth, permission, API, target scope, or environment blockers occur.
+6. Do not output filler such as "still running" without current counts or current step.
+
+Example:
+
+```text
+计划生成进度：已处理 <processed_count>/<resource_count> 项资源，生成 <plan_item_count> 项计划，其中创建 <create_count> 项、移动 <move_count> 项。继续计算父子目录移动顺序，不会执行创建或移动。
+```
+
 ## PlanItem
 
 `PlanItem` is for internal execution. It may contain tokens and internal enums.
@@ -167,11 +187,11 @@ Confidence display map:
 - 低置信度：<low_count> 项
 
 你可以选择：
-- 查看第 1 页明细
-- 只看将创建的目录 / 节点
-- 只看待人工确认项
-- 只看高置信度移动项
-- 进入执行确认
+1. 查看第 1 页明细
+2. 只看将创建的目录 / 节点
+3. 只看待人工确认项
+4. 只看高置信度移动项
+5. 进入下一步：确认执行计划
 ```
 
 If `total_count > 500`, say:
@@ -224,10 +244,10 @@ User-facing output:
 说明：后续执行默认基于这份完整修正版计划，不是只执行刚才的修正项。
 
 你可以选择：
-A. 查看修正版计划总览
-B. 查看本次修改涉及的资源
-C. 进入执行确认
-D. 继续调整
+1. 查看修正版计划总览
+2. 查看本次修改涉及的资源
+3. 进入下一步：确认执行计划
+4. 继续调整
 ```
 
 If the user explicitly asks to execute only the corrected items, ask for confirmation before execution:
@@ -248,15 +268,15 @@ If the user explicitly asks to execute only the corrected items, ask for confirm
 还有 <remaining_pages> 页未展示。
 
 你可以回复：
-- 继续看下一页
-- 只看待人工确认项
-- 只看低置信度项
-- 进入执行确认
+1. 继续看下一页
+2. 只看待人工确认项
+3. 只看低置信度项
+4. 进入下一步：确认执行计划
 ```
 
 ## State: EXEC_CONFIRM
 
-Entry: user asks to execute.
+Entry: user asks to view execution confirmation or continue toward execution.
 
 MUST:
 
@@ -284,17 +304,17 @@ Before execution confirmation, MUST show this notice:
 
 When the user wants execution, ask for execution scope:
 
-Execution confirmation options MUST be renumbered by currently available choices. Do not show disabled choices, and do not ask the user to reply with skipped letters.
+Execution confirmation options MUST be numbered by currently available choices. Do not show disabled choices, and do not ask the user to reply with skipped numbers.
 
 If a plan detail page is currently active:
 
 ```text
 请确认执行范围：
 
-A. 执行完整计划：<total_count> 项
-B. 只执行当前页：<current_page_count> 项
-C. 只执行高置信度项：<high_confidence_count> 项
-D. 暂不执行，只保留方案
+1. 执行完整计划：<total_count> 项
+2. 只执行当前页：<current_page_count> 项
+3. 只执行高置信度项：<high_confidence_count> 项
+4. 暂不执行，只保留方案
 
 本 workflow 只执行已确认范围内的创建、移动和必要的单资源权限申请；不会重命名任何资源。
 ```
@@ -304,9 +324,9 @@ If no plan detail page is currently active:
 ```text
 请确认执行范围：
 
-A. 执行完整计划：<total_count> 项
-B. 只执行高置信度项：<high_confidence_count> 项
-C. 暂不执行，只保留方案
+1. 执行完整计划：<total_count> 项
+2. 只执行高置信度项：<high_confidence_count> 项
+3. 暂不执行，只保留方案
 
 如需只执行某一页，请先查看计划明细页。
 

skills/lark-drive/references/lark-drive-workflow-knowledge-organize.md

@@ -89,7 +89,8 @@ Agent MUST maintain these internal fields during one workflow run:
 | `environment_profile` | Current environment and CLI profile, such as prod / BOE / PRE and config profile |
 | `identity` | `user` by default unless user explicitly asks for app / bot perspective |
 | `resource_items` | Complete normalized resource list from discovery |
-| `partial` | Whether inventory or content-read limits were hit |
+| `partial` | Whether inventory or content read cannot fully continue because of auth, permission, API / pagination failure after retries, API coverage limitations, tool budget, or scope blockers; batching checkpoints alone are not partial |
+| `inventory_continuation_state` | Structured checkpoint for continuing inventory batches within the confirmed scope. Must preserve `scope`, `queue`, `current_cursor`, `visited_page_keys`, `dedupe_keys`, and `blockers`; Drive queue entries carry `folder_token`, `path`, `depth`, and `page_token`; Wiki queue entries carry `space_id` / `node_token`, `path`, `depth`, and pagination cursor; search entries carry query / filters and pagination cursor. Missing or corrupt state is a blocker, not a completed inventory. |
 | `low_confidence_items` | Items requiring mandatory partial content read |
 | `issue_summary` | Problem types, counts, evidence paths, and suggested handling |
 | `classification_rules` | Rules used to map resources to target paths |
@@ -211,6 +212,7 @@ Never request permission automatically, never batch permission requests, and nev
 - [Rollback phase](lark-drive-workflow-knowledge-organize-rollback.md)
 - [lark-shared](../../lark-shared/SKILL.md)
 - [lark-drive](../SKILL.md)
+- [lark-drive-files-list](lark-drive-files-list.md)
 - [lark-drive-search](lark-drive-search.md)
 - [lark-drive-inspect](lark-drive-inspect.md)
 - [lark-drive-apply-permission](lark-drive-apply-permission.md)

skills/lark-sheets/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-sheets
 version: 2.0.0
-description: "飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作原子批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。仅针对飞书在线电子表格，不适用于本地 Excel 文件。"
+description: "飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作原子批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -40,18 +40,22 @@ metadata:
 | --- | --- | --- |
 | 读数据（纯值 / CSV） | `+csv-get`（范围用 `--range`） | — |
 | 读值 + 公式 / 样式 / 批注 | `+cells-get --include value,formula,style,comment,data_validation` | `--with-styles`、`--with-merges`、`--include-merged-cells` |
-| 写纯值（整块 CSV 平铺） | `+csv-put`（定位用 `--start-cell`，单个左上角锚点格；也接受 `--range` 别名，区间自动取左上角） | — |
+| 写纯文本值（整块 CSV 平铺，列里没有需保留的数值 / 日期语义） | `+csv-put`（定位用 `--start-cell`，单个左上角锚点格；也接受 `--range` 别名，区间自动取左上角） | — |
+| 写带类型的数据到**已有**表（列里有数字 / 金额 / 百分比 / 日期 / 计数，要可排序 / 求和 / 入图表 / 透视） | `+table-put`（列显式声明 `type` + `format`，类型保真；来源不限 DataFrame——Counter / dict / list 同理，详见 write-cells） | 在本地把数字拼成 `"$1,234"` / `"30.5%"` 字符串再 `+csv-put`（会落成文本、丢失计算能力） |
+| **新建**电子表格并写带类型的数据（类型保真需求同上，但目标表还不存在） | `+workbook-create --sheets`（协议与 `+table-put` 同构、一步建表 + typed 写入，无需先建空表再 `+table-put`；date / number 不丢，详见 workbook） | 用 `--headers` / `--values` 灌日期 / 数字（会落成文本、丢类型） |
 | 写值 / 公式 / 样式 | `+cells-set`（定位用 `--range`） | — |
 | 查找单元格 | `+cells-search`（关键字用 `--find`） | `+cells-find`、`+find`、`--query` |
 | 查找并替换 | `+cells-replace` | — |
 | 看子表结构（合并 / 行高列宽 / 冻结 / 隐藏） | `+sheet-info` | `+sheet-get`、`+structure-get`、`+sheet-structure-get` |
 | 看工作簿 / 子表清单 | `+workbook-info` | — |
 | 导出 xlsx / 单表 csv | `+workbook-export` | — |
+| 导入本地 xlsx/xls/csv 文件为新表格 | `+workbook-import --file ./x.xlsx`（仅导入为电子表格；要导成多维表格走 `drive +import --type bitable`） | 把 .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 / 本地脚本拼一张假透视表 |
 
+> ⚠️ **纯文本还是数值语义**：要写的列里有数字 / 金额 / 百分比 / 日期 / 计数 → `+table-put`（写入已有表；声明 `type` + `format`，保留排序 / 求和 / 图表 / 透视能力；**目标表还不存在就用 `+workbook-create --sheets`**，同 typed 协议、一步建表 + 写入，别先建空表再 `+table-put`）；只有纯文本才用 `+csv-put`。两者写完显示可以完全相同，但 `+csv-put` 落的是文本、不能参与计算——别把数值在本地拼成带 `$` / `%` 的字符串再走 `+csv-put`。
 > ⚠️ **定位 flag**：`+cells-get` / `+cells-set` / `+csv-get` 用 `--range`；`+csv-put` 规范用 `--start-cell`（单个左上角锚点格），也接受 `--range` 别名（区间自动取左上角），二者择一即可。
 > ⚠️ **读取附加信息**一律走 `+cells-get --include …`，**没有** `--with-styles` 这类 flag；**看合并单元格**用 `+sheet-info` 的 `merged_cells`，不要在 `+cells-get` 里找 merge flag。
 
@@ -63,28 +67,28 @@ metadata:
 
 | Reference | 描述 |
 | --- | --- |
-| [飞书表格核心操作：分析、编辑与可视化](references/lark-sheets-core-operations.md) | 飞书表格核心操作工作流。当用户需要对已有的飞书表格进行查看、分析、编辑或可视化时使用。适用场景：数据查询与统计、公式计算、表格美化、创建图表/透视表、筛选排序、批量修改数据、调整表格结构等。即使用户没有明确说"飞书表格"，只要操作对象是已有的在线表格，都应触发此工作流。不适用于本地 Excel 文件操作。 |
-| [飞书表格样式与配色规范](references/lark-sheets-visual-standards.md) | 飞书表格样式与配色规范：表头/数据区/汇总行的颜色、字号、对齐、边框等取值标准，以及新增汇总行、追加行列继承原表风格、已有区域美化等典型场景的决策流程与样式要点。工具调用参数细节请参考对应的 lark-sheets-write-cells / lark-sheets-range-operations / lark-sheets-batch-update。条件格式（高亮、标红、数据条、色阶）请使用 lark-sheets-conditional-format。仅针对飞书表格，不适用于本地 Excel 文件。 |
-| [飞书表格公式生成规则](references/lark-sheets-formula-translation.md) | Excel 公式到飞书表格公式的迁移与生成规则。核心目标不是保留 Excel 原语法，而是按飞书表格可执行规则重写公式，并在结果上尽量对齐 Excel。当用户要求把 Excel 公式改写成飞书表格公式，或需要生成飞书公式（尤其涉及 ARRAYFORMULA、原生数组函数、INDEX/OFFSET、MAP/LAMBDA、日期差、多层范围结果与二次展开）时使用。仅针对飞书在线表格，不适用于本地 Excel 文件执行。 |
+| [飞书表格核心操作：分析、编辑与可视化](references/lark-sheets-core-operations.md) | 飞书表格核心操作工作流。当用户需要对已有的飞书表格进行查看、分析、编辑或可视化时使用。适用场景：数据查询与统计、公式计算、表格美化、创建图表/透视表、筛选排序、批量修改数据、调整表格结构等。即使用户没有明确说"飞书表格"，只要操作对象是已有的在线表格，都应触发此工作流。 |
+| [飞书表格样式与配色规范](references/lark-sheets-visual-standards.md) | 飞书表格样式与配色规范：表头/数据区/汇总行的颜色、字号、对齐、边框等取值标准，以及新增汇总行、追加行列继承原表风格、已有区域美化等典型场景的决策流程与样式要点。工具调用参数细节请参考对应的 lark-sheets-write-cells / lark-sheets-range-operations / lark-sheets-batch-update。条件格式（高亮、标红、数据条、色阶）请使用 lark-sheets-conditional-format。 |
+| [飞书表格公式生成规则](references/lark-sheets-formula-translation.md) | Excel 公式到飞书表格公式的迁移与生成规则。核心目标不是保留 Excel 原语法，而是按飞书表格可执行规则重写公式，并在结果上尽量对齐 Excel。当用户要求把 Excel 公式改写成飞书表格公式，或需要生成飞书公式（尤其涉及 ARRAYFORMULA、原生数组函数、INDEX/OFFSET、MAP/LAMBDA、日期差、多层范围结果与二次展开）时使用。 |
 
 ### 按对象的工具参考（含 shortcut）
 
 | Reference | 描述 |
 | --- | --- |
-| [Lark Sheet 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 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) | 管理飞书表格中的图表（柱形图、折线图、饼图、条形图、面积图、散点图、组合图、雷达图等）。当用户需要创建图表、修改图表样式或数据源、查看已有图表配置、删除图表时使用。也适用于用户提到"数据可视化"、"画个图"、"趋势分析"、"对比图"、"占比分析"、"做个图表"等数据可视化相关场景。仅针对飞书表格。 |
-| [Lark Sheet Pivot Table](references/lark-sheets-pivot-table.md) | 管理飞书表格中的数据透视表。当用户需要创建透视表、修改透视表的行列字段/聚合方式/筛选条件、查看已有透视表配置、删除透视表时使用。也适用于用户提到"分组汇总"、"交叉分析"、"按XXX统计"、"按字段分组"、"再分下组"、"多维分析"、"数据透视"等场景。仅针对飞书表格。 |
-| [Lark Sheet Conditional Format](references/lark-sheets-conditional-format.md) | 管理飞书表格中的条件格式规则（重复值高亮、单元格值比较、数据条、色阶、排名、自定义公式等）。当用户需要创建条件格式、修改已有规则的范围或样式、查看当前条件格式配置、删除规则时使用。也适用于用户提到"高亮"、"标红"、"颜色标记"、"数据条"、"色阶"、"条件样式"等场景。仅针对飞书表格。 |
-| [Lark Sheet Filter](references/lark-sheets-filter.md) | 管理飞书表格中的筛选器（filter）。当用户需要筛选数据（按文本/数值/颜色/日期条件过滤行）、查看已有筛选配置、修改或删除筛选器时使用。也适用于"只看"、"筛选出"、"仅保留符合条件的"等场景。仅针对飞书表格。 |
-| [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 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 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) | 管理飞书表格中的图表（柱形图、折线图、饼图、条形图、面积图、散点图、组合图、雷达图等）。当用户需要创建图表、修改图表样式或数据源、查看已有图表配置、删除图表时使用。也适用于用户提到"数据可视化"、"画个图"、"趋势分析"、"对比图"、"占比分析"、"做个图表"等数据可视化相关场景。 |
+| [Lark Sheet Pivot Table](references/lark-sheets-pivot-table.md) | 管理飞书表格中的数据透视表。当用户需要创建透视表、修改透视表的行列字段/聚合方式/筛选条件、查看已有透视表配置、删除透视表时使用。也适用于用户提到"分组汇总"、"交叉分析"、"按XXX统计"、"按字段分组"、"再分下组"、"多维分析"、"数据透视"等场景。 |
+| [Lark Sheet Conditional Format](references/lark-sheets-conditional-format.md) | 管理飞书表格中的条件格式规则（重复值高亮、单元格值比较、数据条、色阶、排名、自定义公式等）。当用户需要创建条件格式、修改已有规则的范围或样式、查看当前条件格式配置、删除规则时使用。也适用于用户提到"高亮"、"标红"、"颜色标记"、"数据条"、"色阶"、"条件样式"等场景。 |
+| [Lark Sheet Filter](references/lark-sheets-filter.md) | 管理飞书表格中的筛选器（filter）。当用户需要筛选数据（按文本/数值/颜色/日期条件过滤行）、查看已有筛选配置、修改或删除筛选器时使用。也适用于"只看"、"筛选出"、"仅保留符合条件的"等场景。 |
+| [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。 |
 
 ## 公共 flag 速查
 
@@ -102,7 +106,7 @@ metadata:
 1. **spreadsheet 定位（必填）**：`--url` 与 `--spreadsheet-token` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --url or --spreadsheet-token`；两个都给 → 互斥冲突。
    - **`--url` 只解析 `/sheets/` 与 `/spreadsheets/` 两种链接**（从路径里抽出 token；也可以直接把裸 token 传给 `--spreadsheet-token`）。其它形态的链接不会被解析成表格 token。
    - ⚠️ **`/wiki/` 知识库链接不能直接当表格定位用**：wiki 链接背后可能是电子表格，也可能是文档 / 多维表格等其它类型，`--url` **不会**自动把 wiki token 解析成 spreadsheet token，直接传会失败。必须先把它解析成真实文档 token —— `lark-cli wiki +node-get --node-token "<wiki 链接或 token>"`，确认返回的 `obj_type` 为 `sheet` 后，取其 `obj_token` 作为 `--spreadsheet-token` 传入（解析细节见 [`../lark-wiki/SKILL.md`](../lark-wiki/SKILL.md)）。
-   - **例外**：`+workbook-create` 是新建一个还不存在的表格，**不接受任何 spreadsheet / sheet 定位 flag**（只有 `--title` / `--folder-token` / `--headers` / `--values`）。
+   - **例外**：`+workbook-create`（新建表 + 可选写入数据）与 `+workbook-import`（把本地文件导入为新表）都产出一张**还不存在**的表格，**不接受任何 spreadsheet / sheet 定位 flag**——`+workbook-create` 只有 `--title` / `--folder-token` / `--headers` / `--values` / `--sheets`，`+workbook-import` 只有 `--file`（必填）/ `--folder-token` / `--name`。
 2. **sheet 定位（公共四件套 shortcut 必填）**：`--sheet-id` 与 `--sheet-name` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --sheet-id or --sheet-name`。
    - ⚠️ **不确定 sheet 名时禁止直接猜 `Sheet1`**：除非用户对话明确说出 sheet 名 / id，或上下文（之前的工具调用 / URL 锚点 `?sheet=xxx`）已经出现过具体值，否则**第一步先调 `+workbook-info --url "..."`**（或 `--spreadsheet-token`）拿 `sheets[].sheet_id` / `sheets[].title` 列表再选。中文环境下子表常叫"数据" / "Sheet"（无数字）/ "工作表 1" / 业务名，猜 `Sheet1` 大概率撞 `sheet not found`，比先查多耗一次失败调用 + 重试。
    - ⚠️ **`--range` 里的 `Sheet1!` 前缀不能替代 sheet 定位**：即使写了 `--range 'Sheet1!A1:B2'`，仍**必须**额外传 `--sheet-id` 或 `--sheet-name`，否则照样报上面的错。

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

@@ -147,9 +147,9 @@ _公共四件套 · 系统：`--yes`、`--dry-run`_
 _创建/更新的图表属性_
 
 **顶层字段**：
-- `position` (object) — 必填 { row: number, col: string }
+- `position` (object?) — 必填 { row: number, col: string }
 - `offset` (object?) — 可选 { row_offset?: number, col_offset?: number }
-- `size` (object) — 必填 { width: number, height: number }
+- `size` (object?) — 必填 { width: number, height: number }
 - `snapshot` (object?) — 图表快照配置 { title?: object, subTitle?: object, style?: object, legend?: oneOf, plotArea: object, …共 6 项 }
 
 ## Examples

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

@@ -15,17 +15,18 @@
 
 ## 使用场景
 
-读取。从飞书表格中读取单元格数据。本 reference 覆盖 3 个 shortcut，按读取目的选择：
+读取。从飞书表格中读取单元格数据。本 reference 覆盖 4 个 shortcut，按读取目的选择：
 
 | 读取目的 | 用这个 shortcut | 数据去向 | 说明 |
 |---------|----------------|---------|------|
-| 快速查看纯值数据、批量处理 | `+csv-get` | 对话上下文 | 返回 CSV 文本（加 `--rows-json` 改为结构化 rows `{row_number, values:{列字母→值}}`）；大表请按 `--range` 行窗口分批读（截断时看 `has_more`） |
+| 快速查看纯值数据、批量处理 | `+csv-get` | 对话上下文 | 返回 CSV 文本（每行带 `[row=N]` 前缀）；大表请按 `--range` 行窗口分批读（截断时看 `has_more`） |
+| 按列类型结构化读出（喂 DataFrame / round-trip 回 `+table-put`） | `+table-get` | 对话上下文 | 返回 typed 协议（`columns:[{name,type}]` + `rows`），列类型由 `number_format` 推断、混合列无损降 `string`；类型保真往返 |
 | 查看公式、样式、批注、数据验证 | `+cells-get` | 对话上下文 | 返回单元格完整信息，token 开销较大 |
 | 查看某区域的下拉框（数据验证）选项 | `+dropdown-get` | 对话上下文 | 返回该 A1 范围已配置的下拉列表选项 |
 
 **选择原则**：
 - 只看值或做数据处理 → `+csv-get`；大表分批读取，避免一次拉全表撑爆上下文
-- 要结构化、按 `row_number` / 列字母定位的输出 → `+csv-get --rows-json`（默认 CSV 串更省 token，超大表批量仍用默认）
+- 要按列类型结构化读出（喂 DataFrame / round-trip 回 `+table-put`）→ `+table-get`
 - 需要公式/样式/批注 → `+cells-get`
 - 只想知道某区域下拉框有哪些选项 → `+dropdown-get`
 
@@ -83,6 +84,7 @@
 | `+cells-get` | read | 单元格 |
 | `+dropdown-get` | read | 对象 |
 | `+csv-get` | read | 单元格 |
+| `+table-get` | read | 单元格 |
 
 ## Flags
 
@@ -115,7 +117,17 @@ _公共四件套 · 系统：`--dry-run`_
 | `--max-chars` | int | optional | 防爆，默认 200000（隐藏 flag：不在 `--help` 列出，但可正常传入） |
 | `--include-row-prefix` | bool | optional | 是否在每行前加 `[row=N]` 前缀，默认 `true` |
 | `--skip-hidden` | bool | optional | 跳过隐藏行列，默认 `false` |
-| `--rows-json` | bool | optional | 返回结构化 rows（`{row_number, values:{列字母→值}}`）而非 CSV 文本，默认 `false` |
+
+### `+table-get`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--sheet-id` | string | optional | 只读该子表（按 id）；省略则读所有子表 |
+| `--sheet-name` | string | optional | 只读该子表（按名）；省略则读所有子表 |
+| `--range` | string | optional | 读取的 A1 范围；省略则读每个子表的当前数据区 |
+| `--no-header` | bool | optional | 把第一行当数据而非表头（列名取 col1/col2 …） |
 
 ## Examples
 
@@ -140,17 +152,7 @@ lark-cli sheets +csv-get --spreadsheet-token shtXXX --sheet-name "销售明细"
 - `current_region` — 自动扩展到非空连续区域的 A1 范围。它是**真实数据边界**，**优先于 `+workbook-info` 的 `row_count`**（`row_count` 是网格物理行数，常是 200 / 1000 等默认值、远大于实际数据；按它盲读会拉回大片空行）
 - `has_more` — 是否截断；截断后续读用 `--range` 接着读
 
-**加 `--rows-json`：返回结构化 rows（而非 CSV 字符串）**
-
-```bash
-lark-cli sheets +csv-get --url "https://example.feishu.cn/sheets/shtXXX" --sheet-name "Sheet1" --range "A1:G20" --rows-json
-```
-
-`--rows-json` 下的输出契约（替换 `annotated_csv` / `col_indices` / `row_indices`）：
-
-- `rows` — 数组，每元素 `{row_number, values}`。`row_number` 是真实表格行号（整数，下游需要行号的操作直接取它）；`values` 按**列字母** key（如 `values["D"]`，绝对列字母）。**所有逻辑行都在 `rows` 里**。引号内换行已解析进单元格值，无需自己按 RFC-4180 拆行。
-- `data_not_fully_read` — **仅当没读全时出现**：`{read_through_row, data_extends_through_row, unread_rows, reread_range}`。出现即表示真实数据超出本次读取范围；批量写入前必须按 `reread_range` 重读全区，否则漏行。
-- 其余字段（`current_region` / `actual_range` / `has_more`）同上。
+> 要按列类型结构化读出（喂 DataFrame、或 round-trip 回 `+table-put`）用 `+table-get`（见下）；`+csv-get` 给的是带 `[row=N]` 前缀的纯值快照，下游需要行号/列坐标时直接从前缀与 `col_indices` 取。
 
 ### `+cells-get`
 
@@ -164,6 +166,27 @@ lark-cli sheets +cells-get --url "https://example.feishu.cn/sheets/shtXXX" --she
 
 > ⚠️ 调用方在 `cells[i][j]` 中**不能**用下标推真实行列：必须读 `ranges[n].row_indices[i]` / `ranges[n].col_indices[j]`。
 
+### `+table-get`（飞书 → DataFrame，类型保真读出）
+
+`+table-put`（写入侧，见 write-cells reference）的镜像：把表格读回与 `--sheets` 同构的 typed 协议（`sheets[]` + `columns:[{name,type}]` + `rows`），可直接喂回 `+table-put` 或转 DataFrame。列 `type` 从每列 `number_format` 推断（日期格式→`date`、数值→`number`），`date` 列的序列号转回 ISO `yyyy-mm-dd`——日期、数字往返不丢类型。**列类型只在该列所有非空值一致时才定（`number` / `date` / `bool`）；一列混了类型（如数字列混入「暂无」、日期列混入裸数字）会降为 `string`，让 `columns[].type` 与 `rows` 里每个值自洽——能 round-trip 回 `+table-put`、不让 pandas 崩。降级是无损的（脏值原样保留为文本）；若要把零星脏值转成数值列，交给调用方在 pandas 侧做（`to_numeric(errors='coerce')`），那里原始值仍在、可追溯。** 底层复用 `get_cell_ranges` / `get_range_as_csv`。默认读所有子表、第一行当表头（`--no-header` 把首行当数据、列名取 `col1` / `col2` …）。
+
+```bash
+# 默认读所有子表 → sheets[]（与 +table-put 的 --sheets 同构，可喂回或转 DataFrame）
+lark-cli sheets +table-get --url "<表URL>"
+# 可选：--sheet-name / --sheet-id 限定只读某一个子表（不给则读全部）
+lark-cli sheets +table-get --url "<表URL>" --sheet-name "销售"
+```
+
+`+table-get` 输出 → DataFrame（按读回的 `type` 还原 dtype）：
+
+```python
+sheet = out["data"]["sheets"][0]
+df = pd.DataFrame(sheet["rows"], columns=[c["name"] for c in sheet["columns"]])
+for c in sheet["columns"]:
+    if c["type"] == "date":     df[c["name"]] = pd.to_datetime(df[c["name"]])
+    elif c["type"] == "number": df[c["name"]] = pd.to_numeric(df[c["name"]])
+```
+
 ### Validate / DryRun / Execute 约束
 
 - `Validate` 阶段只做 XOR 检查、Enum 合法性、防爆参数上限校验；**禁止**联网（如不能用 `--sheet-name` 提前去查 `sheet-id`）。

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

@@ -10,7 +10,7 @@
 
 ## 使用场景
 
-读写。管理工作簿结构。本 reference 覆盖 11 个 shortcut：
+读写。管理工作簿结构。本 reference 覆盖 14 个 shortcut：
 
 | 操作需求 | 使用工具 | 说明 |
 |---------|---------|------|
@@ -41,8 +41,11 @@
 | `+sheet-hide` | write | 工作簿 |
 | `+sheet-unhide` | write | 工作簿 |
 | `+sheet-set-tab-color` | write | 工作簿 |
+| `+sheet-hide-gridline` | write | 工作簿 |
+| `+sheet-show-gridline` | write | 工作簿 |
 | `+workbook-create` | write | 工作簿 |
 | `+workbook-export` | read | 工作簿 |
+| `+workbook-import` | write | 工作簿 |
 
 ## Flags
 
@@ -115,6 +118,18 @@ _公共四件套 · 系统：`--dry-run`_
 | --- | --- | --- | --- |
 | `--color` | string | required | Hex 色值如 `#FF0000`，传空 `""` 清除 |
 
+### `+sheet-hide-gridline`
+
+_公共四件套 · 系统：`--dry-run`_
+
+_仅含公共 / 系统 flag。_
+
+### `+sheet-show-gridline`
+
+_公共四件套 · 系统：`--dry-run`_
+
+_仅含公共 / 系统 flag。_
+
 ### `+workbook-create`
 
 _系统：`--dry-run`_
@@ -125,6 +140,8 @@ _系统：`--dry-run`_
 | `--folder-token` | string | optional | 目标文件夹 token；省略时放在云空间根目录 |
 | `--headers` | string + File + Stdin（简单 JSON） | optional | 表头行 JSON 数组：`["列A","列B"]` |
 | `--values` | string + File + Stdin（简单 JSON） | optional | 初始数据 JSON 二维数组：`[["alice",95]]` |
+| `--sheets` | string + File + Stdin（复合 JSON） | optional | 建表后写入的 typed 表格协议 JSON（同 +table-put）：顶层 sheets 数组，每项 {name, start_cell?, mode?, header?, allow_overwrite?, columns:[{name,type,format?}], rows:[[...]]}；type 为 string/number/date/bool。与 --headers/--values 互斥；新表默认子表复用为第一个子表，日期/数字类型保真。 |
+| `--header-style` | bool | optional | 把 typed 表头行加粗（仅 --sheets 时生效，默认 true） |
 
 ### `+workbook-export`
 
@@ -136,6 +153,31 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
 | `--sheet-id` | string | optional | 仅 csv 模式必填：指定要导出哪张 sheet 为 CSV。这是 `+workbook-export` 专有 flag，与公共四件套的 sheet 定位无关（本 shortcut 不接受公共 sheet 定位） |
 | `--output-path` | string | optional | 本地保存路径；省略时只触发导出不下载 |
 
+### `+workbook-import`
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--file` | string | required | 本地文件路径（.xlsx / .xls / .csv） |
+| `--folder-token` | string | optional | 目标文件夹 token；省略则导入到云空间根目录 |
+| `--name` | string | optional | 导入后表格名称；省略则用本地文件名（去掉扩展名） |
+
+## Schemas
+
+> 复合 JSON flag 字段速查（只列顶层 + 一层嵌套）。深层结构看下方 `## Examples`，或用 `--print-schema` 读完整 JSON Schema（用法见 SKILL.md「公共 flag 速查」与「Agent 使用提示」）。
+
+### `+workbook-create` `--sheets`
+
+_一个或多个子表的 typed 数据，每个数组元素写入一张子表；支持多 DataFrame → 多子表一次写入_
+
+**数组项**（类型 object）：
+- `name` (string) — 目标子表名
+- `start_cell` (string?) — 写入起点单元格（A1 记法，如 "B2"），默认 "A1"
+- `mode` (enum?) — overwrite（默认）：从 start_cell 起写「表头 + 数据」块；append：把数据追加到子表已有数据下方（默认不重复表头） [overwrite / append]
+- `header` (boolean?) — 是否写一行列名表头
+- `allow_overwrite` (boolean?) — 为 false 时，若写入会落在非空单元格则拒写以保护原数据（返回 partial_success）
+- `columns` (array<object>) — 列定义，顺序与 rows 中每行的取值一一对应 each: { name: string, type: enum, format?: string }
+- `rows` (array<array<string|number|boolean|null>>) — 数据行；每行是一个数组，长度必须等于 columns 数
+
 ## Examples
 
 公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。`+workbook-info` 只用前两者；`+sheet-*` 系列对单个工作表操作，需 `--sheet-id` 或 `--sheet-name`。
@@ -144,6 +186,47 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
 
 输出契约：返回 `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。
 
+### `+workbook-create`
+
+新建电子表格，可选预填数据。两种数据入口**互斥**，按需二选一：
+
+```bash
+# 1) untyped：--headers + --values（纯值；类型由飞书自动识别，日期会落成文本）
+lark-cli sheets +workbook-create --title "销售" \
+  --headers '["门店","销售额"]' --values '[["北京",259874]]'
+
+# 2) typed：--sheets（一步建表 + 类型保真）。date 列落成真日期（可排序/透视）、
+#    number 不丢精度、string 列保前导零（如订单号 00123）；多子表一次建。
+lark-cli sheets +workbook-create --title "交易" --sheets '{
+  "sheets":[
+    {"name":"明细","columns":[
+      {"name":"日期","type":"date"},
+      {"name":"金额","type":"number","format":"#,##0.00"},
+      {"name":"单号","type":"string"}
+    ],"rows":[["2024-01-15",1234.5,"00123"]]}
+  ]}'
+```
+
+`--sheets` 协议与 `+table-put` 完全同构（字段含义见 lark-sheets-write-cells 的 `+table-put`，大 payload 走 stdin / `@file`）。关键差异：**新建工作簿的默认子表会被复用为第一个子表**（重命名后承载数据），不会残留空 `Sheet1`；其余子表按需新建。它把 `+table-put` 单独做不到的"建表 + typed 写入"合到一条命令，是「pandas 算完直接落地一张带真日期的新表」的首选。回读校验用 `+table-get`（与 `--sheets` 同构、可 round-trip）。
+
+> ⚠️ **`+workbook-create` 是把内存里的数据写成新表；要把已有的本地 Excel/CSV 文件原样导入成新表，用 `+workbook-import`**（见下），不要先在本地读出文件再 `+workbook-create` 重灌。
+
+### `+workbook-import`
+
+把已有的本地 `.xlsx` / `.xls` / `.csv` 文件导入为一个**新的**飞书电子表格（异步任务 + 内置轮询），与 `+workbook-export`（导出）对称。底层复用 drive 的导入实现，固定导入为电子表格类型。
+
+```bash
+# 导入到云空间根目录；表格名默认取本地文件名（去掉扩展名）
+lark-cli sheets +workbook-import --file ./data.xlsx
+
+# 指定目标文件夹与导入后表格名
+lark-cli sheets +workbook-import --file ./report.csv --folder-token <FOLDER_TOKEN> --name "月度报表"
+```
+
+- **不接受任何 spreadsheet / sheet 定位 flag**（它是新建，不操作已有表）：只有 `--file`（必填）/ `--folder-token` / `--name`。
+- 仅导入为电子表格（sheet）。若要把本地表格导入成多维表格（bitable），改用 `lark-cli drive +import --type bitable`。
+- 返回 `token` / `url`（导入完成的新表格）/ `ticket` / `ready` / `job_status`；未在内置轮询窗口内完成时返回 `timed_out=true` 与续查命令 `next_command`。
+
 ### `+sheet-create`
 
 示例：
@@ -190,8 +273,16 @@ lark-cli sheets +sheet-unhide --url "..." --sheet-id "$SID"
 lark-cli sheets +sheet-set-tab-color --url "..." --sheet-id "$SID" --color "#FF0000"
 ```
 
+### `+sheet-show-gridline` / `+sheet-hide-gridline`
+
+```bash
+# 切换子表网格线显隐；二态语义在命令名里，无需额外参数（同 +sheet-hide/+sheet-unhide）
+lark-cli sheets +sheet-show-gridline --url "..." --sheet-id "$SID"
+lark-cli sheets +sheet-hide-gridline --url "..." --sheet-id "$SID"
+```
+
 ### Validate / DryRun / Execute 约束
 
-- `Validate`：XOR 公共四件套；`+sheet-create` 校验 `--title` 非空、`--row-count` ≤ 50000、`--col-count` ≤ 200；`+sheet-delete` 必须 `--yes` 或 `--dry-run`。
+- `Validate`：XOR 公共四件套；`+sheet-create` 校验 `--title` 非空、`--row-count` ≤ 50000、`--col-count` ≤ 200；`+sheet-delete` 必须 `--yes` 或 `--dry-run`；`+workbook-create` 的 `--sheets` 与 `--headers`/`--values` **互斥**，给了 `--sheets` 则按 typed 协议校验 payload（其余约束同 `+table-put`）。
 - `DryRun`：`+sheet-*` 写操作输出"将要 PATCH 的 sheet metadata"；`--sheet-name` 在 dry-run 输出里生成为 `<resolve:Sheet1>` 占位符，不实际解析为 sheet-id。
 - `Execute`：写操作不自动回读；如需确认目标 sheet 的新状态，自行调用 `+workbook-info`。

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

@@ -44,7 +44,30 @@
 
 ## 使用场景
 
-写入。为一块单元格区域设置值、公式、批注/备注和/或格式。也支持通过 `rich_text` 中 `type: "embed-image"` 在单元格内嵌入图片（单元格图片）。关键：数组维度必须严格匹配——`cells` 二维数组必须与 `range` 的行列维度完全一致，range 是闭区间，否则会触发 `InvalidCellRangeError`。计算示例：区域 `A1:D3` = 3 行 × 4 列 = `[[r1c1,r1c2,r1c3,r1c4],[r2c1,r2c2,r2c3,r2c4],[r3c1,r3c2,r3c3,r3c4]]`；区域 `A41:N48` = 8 行 × 14 列 = 8 个数组且每个数组 14 个单元；单个单元格 `A1` = `[[cell]]`；单列区域 `B5:B7` = `[[cell1],[cell2],[cell3]]`。空单元请使用 `{}`。**如果填写的区域存在大量重复内容，务必优先使用 `--copy-to-range` 字段复制，可大幅减少 `cells` 长度。**
+写入。向飞书表格的单元格区域写入值、公式、样式、批注、图片或下拉，也可批量写入 CSV / DataFrame。本 reference 覆盖 6 个 shortcut，按数据来源 + 内容形态选：
+
+| 场景 | 用这个 shortcut | 原因 |
+|------|----------------|------|
+| 模型手里已经有 CSV 文本（小规模手动构造、从 `+csv-get` 取到后简单加工） | `+csv-put` | 直接传 CSV 文本 + `--start-cell`，不用自己拼二维 cells 数组；必要时自动扩容行列 |
+| 列里有数值语义的数据（数字 / 金额 / 百分比 / 日期 / 计数）→ 飞书，要类型保真（来源不限：DataFrame、Counter、dict、list 都算） | `+table-put` | 列显式声明 `type`：date 落真日期、**金额 / 百分比 / 计数等数值列保精度且带 `number_format`（可排序 / 求和 / 入图表）**、string 保前导零，多 sheet 一次写。**只要列有数值语义就走这里**，不要在本地把数字拼成带 `$` / `%` 的字符串再走 `+csv-put` |
+| 写入含公式、样式、批注、图片、数据校验等任意富写入 | `+cells-set` | 唯一支持完整字段的 shortcut |
+| 只改已有 cell 的样式，不动 value/formula | `+cells-set-style` | 拍平 10 个样式字段为独立 flag；不触发不必要的值写入 |
+| 单 cell 嵌入图片 | `+cells-set-image` | 比 `+cells-set` 参数更简短 |
+| 大量纯值 + 需要表头样式/边框 | 先用 `+csv-put` 写值，再用 `+cells-set-style` 补样式 | 分工配合，入参最短 |
+
+**优先级**：常规纯值写入优先 `+csv-put`（最短入参，直接传 CSV 文本）；含公式/样式/批注/图片才用 `+cells-set`。⚠️ 这里"纯值"特指**已是文本、无需保留数值语义**的内容；只要列里是金额 / 百分比 / 日期 / 计数等有数值语义的数据，应优先 `+table-put`（声明 `number` / `date` 类型 + `number_format`），而不是 `+csv-put`。
+
+⚠️ `+csv-put` 只写纯值，**不会**携带公式/样式/批注/图片；公式字符串以 `=` 开头会被当作字面量文本落地。如果数据里需要公式或样式，**必须**用 `+cells-set`（或"写值 + 补样式"两步法）。
+
+⚠️ **别把本该是数值的列格式化成字符串用 `+csv-put` 写入**（高频反模式）：金额 / 百分比 / 市值 / 计数等列，若在本地拼成带 `$` / `%` / 千分位的字符串（如 `"$1,234.50"` / `"+30.5%"`）再 `+csv-put` 灌进去，单元格会变成**文本**——丢失排序 / 求和 / 图表 / 透视能力，且与 `number` 列混排时无法参与计算。正解是 `+table-put` 声明该列 `type:"number"`（百分比存小数，如 `0.305`）+ `format`（如 `"$#,##0.00"` / `"0.0%"` / `"#,##0"`），**显示效果完全相同、数值无损**。判断信号：**当你准备把一个数字 format 成字符串再写时，几乎总该用 `+table-put` 而非 `+csv-put`**。
+
+⚠️ 大数据回写走"`+csv-get` 按 `--range` 行窗口分批读到本地 + 本地脚本处理 + `+csv-put` 分批回写"。
+
+## `+cells-set` 写入要点（高频模式 / 公式 / 样式）
+
+> 以下是用 `+cells-set`（及 `+cells-set-style`）做富写入时的高频模式与铁律；选哪个 shortcut 见上方「使用场景」。
+
+`+cells-set` 为一块区域设置值 / 公式 / 批注 / 样式，也支持 `rich_text` 的 `type: "embed-image"` 嵌入单元格图片。**关键：`cells` 二维数组的行列维度必须与 `range`（闭区间）严格一致，否则触发 `InvalidCellRangeError`**——维度计算示例见文末 `## Schemas` 的 `--cells`。
 
 > **单元格图片 vs 浮动图片**：
 > - **单元格图片**（本工具）：图片嵌入在单元格内部，属于单元格内容，随单元格移动。通过 `rich_text` 中 `type: "embed-image"` 写入。
@@ -208,24 +231,6 @@ lark-cli sheets +dropdown-set \
 
 `+dropdown-update`（多 range 批量更新）的所有 flag 语义与 `+dropdown-set` 完全一致；只是目标 `--ranges` 由单值变成 JSON 数组（每项带 sheet 前缀），同一份选项 + 配色应用到所有 range。
 
-## 工具选择
-
-本 skill 提供以下 CLI shortcut，按数据来源 + 内容形态选：
-
-| 场景 | 用这个 shortcut | 原因 |
-|------|----------------|------|
-| 模型手里已经有 CSV 文本（小规模手动构造、从 `+csv-get` 取到后简单加工） | `+csv-put` | 直接传 CSV 文本 + `--start-cell`，不用自己拼二维 cells 数组；必要时自动扩容行列 |
-| 写入含公式、样式、批注、图片、数据校验等任意富写入 | `+cells-set` | 唯一支持完整字段的 shortcut |
-| 只改已有 cell 的样式，不动 value/formula | `+cells-set-style` | 拍平 10 个样式字段为独立 flag；不触发不必要的值写入 |
-| 单 cell 嵌入图片 | `+cells-set-image` | 比 `+cells-set` 参数更简短 |
-| 大量纯值 + 需要表头样式/边框 | 先用 `+csv-put` 写值，再用 `+cells-set-style` 补样式 | 分工配合，入参最短 |
-
-**优先级**：常规纯值写入优先 `+csv-put`（最短入参，直接传 CSV 文本）；含公式/样式/批注/图片才用 `+cells-set`。
-
-⚠️ `+csv-put` 只写纯值，**不会**携带公式/样式/批注/图片；公式字符串以 `=` 开头会被当作字面量文本落地。如果数据里需要公式或样式，**必须**用 `+cells-set`（或"写值 + 补样式"两步法）。
-
-⚠️ 大数据回写走"`+csv-get` 按 `--range` 行窗口分批读到本地 + 本地脚本处理 + `+csv-put` 分批回写"。
-
 ## Shortcuts
 
 | Shortcut | Risk | 分组 |
@@ -235,6 +240,7 @@ lark-cli sheets +dropdown-set \
 | `+cells-set-image` | write | 单元格 |
 | `+dropdown-set` | write | 对象 |
 | `+csv-put` | write | 单元格 |
+| `+table-put` | write | 单元格 |
 
 ## Flags
 
@@ -303,6 +309,15 @@ _公共四件套 · 系统：`--dry-run`_
 | `--allow-overwrite` | bool | optional | 允许覆盖（默认 true）；设为 false 时若目标非空报错 |
 | `--range` | string | optional | --start-cell 的别名（与 +csv-get / +cells-set 一致，用 --range 定位）；传区间（如 A1:H17）时自动取其左上角单元格（隐藏 flag：不在 `--help` 列出，但可正常传入） |
 
+### `+table-put`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--sheets` | string + File + Stdin（复合 JSON） | required | typed 表格协议 JSON：顶层 sheets 数组，每项 {name, start_cell?, mode?, header?, allow_overwrite?, columns:[{name,type,format?}], rows:[[...]]}；type 为 string/number/date/bool |
+| `--header-style` | bool | optional | 把列名表头行加粗（默认 true） |
+
 ## Schemas
 
 > 复合 JSON flag 字段速查（只列顶层 + 一层嵌套）。深层结构看下方 `## Examples`，或用 `--print-schema` 读完整 JSON Schema（用法见 SKILL.md「公共 flag 速查」与「Agent 使用提示」）。
@@ -338,6 +353,19 @@ _列表选项_
 **数组项**（类型 string）：
 - 标量：string
 
+### `+table-put` `--sheets`
+
+_一个或多个子表的 typed 数据，每个数组元素写入一张子表；支持多 DataFrame → 多子表一次写入_
+
+**数组项**（类型 object）：
+- `name` (string) — 目标子表名
+- `start_cell` (string?) — 写入起点单元格（A1 记法，如 "B2"），默认 "A1"
+- `mode` (enum?) — overwrite（默认）：从 start_cell 起写「表头 + 数据」块；append：把数据追加到子表已有数据下方（默认不重复表头） [overwrite / append]
+- `header` (boolean?) — 是否写一行列名表头
+- `allow_overwrite` (boolean?) — 为 false 时，若写入会落在非空单元格则拒写以保护原数据（返回 partial_success）
+- `columns` (array<object>) — 列定义，顺序与 rows 中每行的取值一一对应 each: { name: string, type: enum, format?: string }
+- `rows` (array<array<string|number|boolean|null>>) — 数据行；每行是一个数组，长度必须等于 columns 数
+
 ## Examples
 
 公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。
@@ -430,6 +458,44 @@ lark-cli sheets +csv-put --spreadsheet-token shtXXX --sheet-id "$SID" \
 > - dry-run 与成功响应都回显 `writes_range`（实际落区，如 `B2:D4`）：**写前先 `--dry-run` 看一眼落区**，确认不会盖到相邻数据。
 > - 要保护非空 cell：`--allow-overwrite=false`（落区内出现非空 cell 即报错）。
 
+### `+table-put`（DataFrame → 飞书，类型保真写入）
+
+把带类型的结构化数据（DataFrame）类型保真地写入**已有**表，底层复用 `set_cell_range`（同 `+cells-set`）。typed 协议：顶层 `sheets[]`，每 sheet 带 `columns:[{name,type,format?}]` + `rows`（二维数组，`null`=空单元格），列 `type` ∈ `string` / `number` / `date` / `bool`（**显式声明**，不让 CLI 猜，避免邮编 / 订单号等"像数字的文本"被误判）。`date` 列的 ISO `yyyy-mm-dd` 字符串会转成 Excel 序列号 + 日期 `number_format`（真日期，可排序 / 透视 / 筛选）。
+
+只写入**已有**表（`--url` / `--spreadsheet-token` 二选一必填），不新建工作簿——**要新建表格直接用 `+workbook-create --sheets`**（同 typed 协议、一步建表 + 类型保真写入，无需先建空表再回来，详见 workbook reference）。读回用镜像命令 `+table-get`（见 read-data reference），输出与 `--sheets` 同构、可 round-trip。
+
+```bash
+# sheet 按 name 匹配、缺则新建；多 DataFrame 经 stdin 一次写多 sheet
+python export.py | lark-cli sheets +table-put --url "<表URL>" --sheets -
+# 某 sheet 带 "mode":"append" 追加到已有数据末尾、默认不重复表头
+lark-cli sheets +table-put --spreadsheet-token "<token>" --sheets @payload.json
+```
+
+每个 sheet 还可带 `"allow_overwrite": false`（遇非空拒写、保护原数据）、`"header": false`（只写数据不写表头）。完整字段跑 `+table-put --print-schema --flag-name sheets`。
+
+**前提：此 helper 需 pandas。** 注意一台机器常装多个 Python，`python3` 未必指向装了 pandas 的那个——撞 `ModuleNotFoundError` 就换个解释器（如 `/usr/bin/python3`）再试。**不想依赖 pandas 也行**：typed 协议就是纯 JSON，直接手写 `columns` + `rows`（不经 helper）一样喂给 `--sheets -`。DataFrame → 协议 的薄 helper（一次清洗：`NaN→null`、`Timestamp→ISO`、`numpy 标量→原生`）：
+
+```python
+import pandas as pd, numpy as np
+def df_to_sheet(df, name, formats=None):
+    formats = formats or {}
+    def coltype(s):
+        if pd.api.types.is_datetime64_any_dtype(s): return "date"
+        if pd.api.types.is_bool_dtype(s):           return "bool"
+        if pd.api.types.is_numeric_dtype(s):        return "number"
+        return "string"
+    def cell(v):
+        if pd.isna(v):                  return None
+        if isinstance(v, pd.Timestamp): return v.date().isoformat()
+        if isinstance(v, np.generic):   return v.item()
+        return v
+    columns = [{"name": str(c), "type": coltype(df[c]),
+                **({"format": formats[c]} if c in formats else {})} for c in df.columns]
+    rows = [[cell(v) for v in r] for r in df.itertuples(index=False, name=None)]
+    return {"name": name, "columns": columns, "rows": rows}
+# payload = {"sheets": [df_to_sheet(df, "销售", {"日期": "yyyy-mm-dd"})]}；json.dump 经 stdin 喂给 +table-put --sheets -
+```
+
 ### Validate / DryRun / Execute 约束
 
 - `Validate`：XOR 公共四件套；`+cells-set` 的 `--cells` 必须能解析为 JSON 二维矩阵且行列数与 `--range` 完全一致；`+cells-set-style` 的样式 flag 至少一个非空（或带 `--border-styles`）；`+cells-set-image` 的 `--range` 必须是单 cell（起止 cell 相同）；`+csv-put` 的 `--csv` 必须能按 RFC 4180 解析；防爆参数上限校验。

skills/lark-slides/SKILL.md

@@ -19,6 +19,8 @@ metadata:
 | 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `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` |
 | 上传或使用图片 | 先上传为 `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) |
 | 用户提到模板、主题、版式 | 先检索模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` |
 | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
 
@@ -80,6 +82,7 @@ lark-cli auth login --domain slides
 - 创建：[`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-media-upload.md`](references/lark-slides-media-upload.md)
+- 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
 - 模板：[`template-catalog.md`](references/template-catalog.md)、[`scripts/template_tool.py`](scripts/template_tool.py)
 - 排障：[`troubleshooting.md`](references/troubleshooting.md)
 - 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml)
@@ -183,7 +186,7 @@ lark-cli slides xml_presentation.slide create \
   --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 等元素
+    在这里放置 shape、line、table、chart、whiteboard 等元素
   </data>
 </slide>' '{slide:{content:$content}}')"
 

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

@@ -1,13 +1,13 @@
 # Asset Planning
 
-新建演示文稿或大幅改写页面时，在写入 `slide_plan.json` 前后都可以参考本文件。目标是让 agent 主动识别有价值的图、图标、图表、截图或示意图需求，同时保持 deck 在没有真实素材时也能完整执行。
+新建演示文稿或大幅改写页面时，在写入 `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, or placeholder regions.
+- 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.
@@ -22,7 +22,7 @@ Use an object for one planned asset, or an array when a page genuinely needs mul
   "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 and arrows with XML shapes; use labels instead of an image."
+  "fallback_if_missing": "Draw grouped boxes connected by arrows with short labels."
 }
 ```
 
@@ -43,7 +43,7 @@ For a page without a meaningful asset need, use:
 - `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, funnel, scatter, or chart-like data visual.
+- `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.
@@ -118,7 +118,7 @@ Business comparison page:
 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, or chart-like elements.
+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/lark-slides-replace-slide.md

@@ -88,10 +88,11 @@ lark-cli slides +replace-slide --as user \
 | `<table>` | 表格 | 整表替换会**重建内部 td id**，旧 td block_id 立即失效 |
 | `<td>` | 单元格局部替换 | 只能 `block_replace`，不能 `block_insert`；`block_id` 必须是最新 `slide.get` 拿到的 td id |
 | `<chart>` | 图表（line/bar/column/pie/area/radar/combo） | 必须嵌 `<chartPlotArea>` + `<chartData>` + `<dim1>/<dim2>/<chartField>` |
+| `<whiteboard>` | 画板（SVG 或 Mermaid） | 内嵌 `<svg>` 或 `<mermaid>`；`slide.get` 返回结构不含内部数据，但可直接写完整新 XML 做 `block_replace` 覆盖；详见 [`lark-slides-whiteboard.md`](lark-slides-whiteboard.md) |
 
 **不可作为根元素**：
 
-- `<video>` / `<audio>` / `<whiteboard>` —— SML 2.0 没有这三个原生元素；`<undefined type="video|audio|whiteboard">` 是**导出时**的占位符（服务端遇到不支持的类型时用它代替），**不能写入**。尝试 insert/replace 都会返回 3350001。
+- `<video>` / `<audio>` —— SML 2.0 没有这两个原生元素；`<undefined type="video|audio">` 是**导出时**的占位符（服务端遇到不支持的类型时用它代替），**不能写入**。尝试 insert/replace 都会返回 3350001。
 
 ### 最小 XML 片段（JSON 嵌入时记得把 `"` 转义成 `\"`）
 

skills/lark-slides/references/lark-slides-whiteboard.md

@@ -0,0 +1,330 @@
+# Whiteboard 画板元素
+
+`<whiteboard>` 放在 `<data>` 内，内部可放 **SVG** 或 **Mermaid**，用于绘制流程图、时序图、架构图、散点图、漏斗图、自定义图标、装饰图案等 `<chart>` 和 `<shape>` 难以覆盖的视觉内容。
+
+> 前置条件：使用本文档前先阅读 [lark-slides SKILL.md](../SKILL.md)。
+
+---
+
+## `<chart>` 还是 `<whiteboard>`？
+
+**先判断内容类型，再进入本文档：**
+
+| 场景 | 推荐元素 |
+|------|---------|
+| 有结构化数据序列的柱/条/折线/面积/雷达/饼/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
+| 散点图、漏斗图（`<chart>` 不支持） | `<whiteboard>` SVG |
+| 流程图、时序图、架构图、类图、ER 图等拓扑图 | `<whiteboard>` Mermaid 或 SVG |
+| 自定义图标、徽标、示意性图形（需要 path/polygon 精确控制） | `<whiteboard>` SVG |
+| 进度条、波浪背景、装饰图案、像素级自定义可视化 | `<whiteboard>` SVG |
+
+> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG 手绘——原生渲染更省力且质量更高。
+
+---
+
+## whiteboard 公共属性
+
+| 属性 | 必需 | 说明 |
+|------|------|------|
+| `topLeftX` | 是 | 左上角 X 坐标（slide 坐标系，slide 默认宽 960） |
+| `topLeftY` | 是 | 左上角 Y 坐标（slide 坐标系，slide 默认高 540） |
+| `width` | 是 | 画板宽度（像素） |
+| `height` | 是 | 画板高度（像素） |
+
+> SVG 模式下 `<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`；内容大小由子元素包围盒决定，`width`/`height`/`viewBox` 不影响渲染（仅当元素属性使用百分比值时需要 `viewBox` 提供计算基准）。Mermaid 模式不需要额外属性。
+
+SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标系无关。
+
+---
+
+## SVG 还是 Mermaid？
+
+选择分两步：**先看图表类型，再看当前模型身份**。
+
+### 第一步：图表类型优先判断
+
+以下类型**推荐 Mermaid**，自动布局、代码简洁；如需精确匹配品牌配色或自定义节点样式，可改用 SVG：
+
+| 图表类型 | Mermaid 关键字 |
+|----------|--------------|
+| 流程图、决策树、架构图 | `flowchart TD` / `flowchart LR` |
+| 时序图 | `sequenceDiagram` |
+| 类图 | `classDiagram` |
+| 饼图 | `pie` |
+| 甘特图 | `gantt` |
+| 状态图 | `stateDiagram-v2` |
+| 思维导图 | `mindmap` |
+| ER 图 | `erDiagram` |
+
+### 第二步：数据图表与装饰元素按模型身份选路径
+
+上表以外的场景（散点图、漏斗图、进度条、时间线、波浪背景、星点纹理等）需要精确控制坐标和配色，SVG 表达力更强，但各模型生成 SVG 的能力有差异：
+
+| 模型身份 | 路径 |
+|----------|------|
+| Claude / Gemini / GPT / GLM | **SVG** — 精确控制坐标、颜色、透明度 |
+| Doubao / Seed / Other | **Mermaid** — 用 `pie`、`gantt` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
+
+> **先自报身份再选路径**：在决定使用 SVG 之前，确认当前模型属于哪一类。不要跳过这一步。
+
+---
+
+## 模式一：SVG
+
+### ⚠️ 设计品质要求
+
+在 slide 里嵌入 `<whiteboard>` 的目的是**提升视觉质量**，不是把数字堆进去。
+
+- **不要只用矩形加文字应付**：通篇纯白底色 + 方块 + 黑字等于白做，这是不及格输出
+- **数据图表必须有坐标系**：坐标轴、网格线、数值标注缺一不可，不要只画柱子或点
+- **字号必须有层级**：标题 ≠ 标签 ≠ 数值，混用同一字号会消灭视觉焦点
+- **配色要与 slide 主题呼应**：深色 slide 背景下图表用透明底或深色卡片；浅色背景下避免再加纯白底块
+- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、折线面积、点装饰等细节拉开与默认模板的差距
+- **写 SVG 前先判断背景亮度**：背景亮度 < 30% 时，装饰元素"对比不足"比"过强"危害更大，宁重勿轻；
+- **装饰层次用亮度跳跃，不用线性叠透明度**：`α=0.04→0.08→0.12` 的等差递增在深色底上几乎看不出差异（相邻层亮度差 ≈20）；正确做法是非线性跳跃如 `0.10→0.40→0.70→1.0`，相邻层亮度差 ≥60。
+
+### 语法
+
+```xml
+<whiteboard width="400" height="300" topLeftX="500" topLeftY="120">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    <rect x="50" y="50" width="80" height="200" rx="4" fill="rgba(59,130,246,0.85)"/>
+    <text x="90" y="270" text-anchor="middle" font-size="12" fill="rgba(100,116,139,1)">ABC</text>
+  </svg>
+</whiteboard>
+```
+
+`<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`；`width`/`height`/`viewBox` 无需填写，若元素属性使用百分比值则需额外声明 `viewBox`。
+
+### ⚠️ 渲染包围盒规则
+
+whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内容区域，自适应缩放到容器。
+
+`<svg>` 上的 `width`、`height`、`viewBox` 不影响内容区域的计算，但 `viewBox` 有一个实际用途：**为百分比属性提供计算基准**。若元素使用 `width="50%"` 等百分比值，必须声明 `viewBox` 才能正确解析；绝对坐标元素则无需关心。推荐统一使用绝对坐标，避免引入百分比依赖。
+
+### 支持的 SVG 元素
+
+| 元素 | 说明 | 典型用途 |
+|------|------|---------|
+| `<rect>` | 矩形，支持 `rx` 圆角 | 柱图、卡片、进度条 |
+| `<circle>` | 圆 | 节点、装饰点、环形图 |
+| `<ellipse>` | 椭圆 | 自定义轮廓图形 |
+| `<line>` | 直线 | 坐标轴、分隔线 |
+| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、折线、弧形 |
+| `<text>` | 文本，支持中文 | 标签、数值 |
+| `<polygon>` | 多边形 | 箭头、星形、面积填充 |
+| `<g>` | 分组 | 批量变换、语义分组 |
+| `<linearGradient>` | 线性渐变定义，配合 `fill="url(#id)"` 使用 | 渐变背景、渐变填充 |
+
+**颜色：** 统一用 `rgba(R,G,B,A)`，对深浅背景都友好。  
+**虚线：** `stroke-dasharray="4,4"` 用于网格线 / 坐标轴。  
+**变换：** `transform="translate(x,y)"` / `rotate(deg cx cy)` / `scale(n)` 均支持。
+
+---
+### 元素计算
+
+SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围不限于数据图表——装饰性点阵、等间距圆、重复图案同样适用。
+
+> **主动去算**：写 SVG 之前先运行脚本，把输出当注释贴在 `<svg>` 开头，再照着填坐标。估值几乎每次都需要反复调整，跳过这步反而更慢。
+
+**数据图表（柱状图范式）**
+
+```python
+W, H = 360, 260
+origin_x, origin_y = 50, 216  # 左下角，SVG Y 轴向下
+cw, ch = 290, 184
+
+data, y_max = [120, 160, 90], 200
+bar_w = int(cw / len(data) * 0.62)
+for i, v in enumerate(data):
+    cx = round(origin_x + (i + 0.5) * cw / len(data))
+    y  = round(origin_y - v / y_max * ch)
+    print(f"bar-{i}: x={cx - bar_w//2} y={y} w={bar_w} h={round(origin_y - y)}")
+```
+
+折线图：`x = origin_x + i/(n-1)*cw`，`y = origin_y - (v-y_min)/(y_max-y_min)*ch`。
+
+**装饰性元素（等间距范式）**
+
+```python
+n, total_w, cy, r = 8, 340, 40, 4
+step = total_w / (n - 1)
+for i in range(n):
+    print(f"circle-{i}: cx={round(i * step)} cy={cy} r={r}")
+```
+
+**最大包围盒 → whiteboard 尺寸**
+
+所有元素坐标算完后，汇总出整体包围盒，直接作为 whiteboard 的 `width`/`height`：
+
+```python
+# 每个元素登记 (x, y, w, h)，含 stroke 外扩
+elements = [
+    (10, 20, 80, 160),   # bar-0
+    (107, 10, 80, 170),  # bar-1
+    (204, 40, 80, 140),  # bar-2
+    (0, 0, 300, 1),      # x-axis
+]
+
+xs = [x for x, y, w, h in elements]
+ys = [y for x, y, w, h in elements]
+x2 = [x + w for x, y, w, h in elements]
+y2 = [y + h for x, y, w, h in elements]
+
+wb_w = max(x2) - min(xs)
+wb_h = max(y2) - min(ys)
+print(f"whiteboard width={wb_w} height={wb_h}")
+```
+
+输出即 `<whiteboard width=... height=...>` 的值，无需手动估算。
+
+---
+### 布局模式
+
+**全屏装饰层**
+```xml
+<whiteboard width="960" height="540" topLeftX="0" topLeftY="0">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    ...
+  </svg>
+</whiteboard>
+```
+
+> ⚠️ 全屏装饰 whiteboard 必须放在所有 `<shape>` / `<img>` / `<table>` 之前，否则会遮挡文字内容。XML 中元素位置越靠后，渲染层级越高。
+
+**侧栏图表（与文字 shape 并排）**
+```xml
+<!-- 左侧文字 -->
+<shape type="text" topLeftX="60" topLeftY="120" width="500" height="340">...</shape>
+<!-- 右侧图表 -->
+<whiteboard width="340" height="340" topLeftX="580" topLeftY="120">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    ...
+  </svg>
+</whiteboard>
+```
+
+**底部装饰条**
+```xml
+<whiteboard width="960" height="100" topLeftX="0" topLeftY="440">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    ...
+  </svg>
+</whiteboard>
+```
+
+---
+
+### 禁止使用的 SVG 特性
+
+以下特性在 slide `<whiteboard>` 渲染端不支持或行为不可预测，必须避免：
+
+| 禁止 | 原因 | 替代方案 |
+|------|------|---------|
+| `<radialGradient>` | 渲染失败 | 用 `<linearGradient>` 或 `rgba()` 透明度模拟深浅层次 |
+| `<filter>`（阴影、模糊等） | 渲染失败 | 用半透明 `<rect>` 叠加模拟阴影 |
+| `<clipPath>` / `<mask>` | 渲染失败 | 调整元素坐标和尺寸自然裁切 |
+| `<pattern>` | 渲染失败 | 手动铺 `<circle>` / `<rect>` 点阵 |
+| `skewX` / `skewY` / `matrix(...)` | 空间扭曲，降级渲染 | 用 `rotate` + `translate` 替代 |
+| `<image>` 外链 URL | 不支持外链 | 先上传得到 file_token，再用 `<img>` 元素 |
+
+---
+
+
+## 模式二：Mermaid
+
+### 语法
+
+```xml
+<whiteboard topLeftX="72" topLeftY="60" width="816" height="360">
+  <mermaid>
+    <![CDATA[
+        flowchart TD
+            A[检查 lark-cli 与 jq] --> B[编写每页 slide XML]
+            B --> C[通过 jq 生成 slides JSON]
+            C --> D[执行 slides +create]
+            D --> E[读取 xml_presentation_id]
+            E --> F[回读并验证创建结果]
+    ]]>
+  </mermaid>
+</whiteboard>
+```
+
+**关键点：**
+- 内容用 `<![CDATA[...]]>` 包裹——Mermaid 语法里的 `[`、`>`、`-->` 是 XML 特殊字符，CDATA 避免转义问题
+- whiteboard 只需 `topLeftX`、`topLeftY`、`width`、`height`
+
+### 支持的 Mermaid 图表类型
+
+| 类型 | 关键字 | 适用场景 |
+|------|--------|---------|
+| 流程图 | `flowchart TD` / `flowchart LR` | 业务流程、决策树、工作流 |
+| 时序图 | `sequenceDiagram` | 系统交互、API 调用链 |
+| 甘特图 | `gantt` | 项目计划、里程碑 |
+| 饼图 | `pie` | 占比数据 |
+| 类图 | `classDiagram` | 对象关系、架构设计 |
+| ER 图 | `erDiagram` | 数据库结构 |
+| 状态图 | `stateDiagram-v2` | 状态机、生命周期 |
+| 思维导图 | `mindmap` | 主题梳理、知识架构 |
+| 用户旅程 | `journey` | 用户体验路径 |
+
+### Mermaid 布局建议
+
+Mermaid 图表会自动撑满 whiteboard 区域。建议：
+- 流程图留足高度，节点较多时适当增加 height（比如 400-480）
+- 避免一页放超过 15 个节点，内容太密时考虑分页
+- 推荐尺寸参考：
+
+| 图表类型 | 建议 width | 建议 height |
+|---------|-----------|------------|
+| 流程图（5-8 节点） | 720-816 | 300-400 |
+| 时序图（3-5 参与者） | 720-816 | 320-420 |
+| 饼图 | 500-600 | 300-360 |
+| 甘特图 | 816 | 280-360 |
+| 思维导图 | 816 | 380-480 |
+
+---
+
+## 注意事项 & 已知问题
+
+### z-order（SVG 模式）
+
+whiteboard 在 XML 中的位置决定渲染层级：在 shape 前 → 在下层；在 shape 后 → 在上层。全屏装饰 whiteboard 应放在所有 shape 之前。
+
+### Mermaid CDATA 必要性
+
+Mermaid 语法包含 `[`、`>`、`-->`，不用 CDATA 直接写会破坏 XML 解析。始终使用 `<![CDATA[ ... ]]>`。
+
+---
+
+## 快速自检清单
+
+**SVG 模式——结构检查：**
+- [ ] `<svg>` 声明了 `xmlns="http://www.w3.org/2000/svg"`
+- [ ] whiteboard 的 `width`/`height` 由所有元素的最大包围盒（含 stroke 外扩）计算得出，不手动估值
+- [ ] `topLeftX + width ≤ 960`，`topLeftY + height ≤ 540`
+- [ ] 无 `<radialGradient>` / `<filter>` / `<clipPath>`
+- [ ] 文字 `y` 坐标为 baseline 位置，最小值 ≥ font-size（避免被裁切）
+
+**SVG 模式——视觉品质检查：**
+- [ ] 坐标轴、网格线、数值标注齐全，没有"裸柱子"或"裸折线"
+- [ ] 字号有层级：标题 > 数值 > 轴标签，非全部相同
+- [ ] 单一数据系列用同一颜色，多系列用不同颜色且对比充足
+- [ ] 轴标签与图表元素互不遮挡，留有足够空间
+- [ ] 坐标推导有注释（写明 originX/Y、chartW/H、数据映射公式）
+
+**Mermaid 模式：**
+- [ ] 内容包在 `<![CDATA[...]]>` 内
+- [ ] CDATA 结束符 `]]>` 不出现在 Mermaid 代码本身中
+- [ ] `topLeftX + width ≤ 960`，`topLeftY + height ≤ 540`
+- [ ] 节点数量合理（单图不超过 15-20 个节点）
+
+**通用：**
+- [ ] XML 标签全部闭合，属性引号完整
+- [ ] 如果失败，检查是否是偶发 5001000，重试一次
+
+---
+
+## 参考
+
+- [lark-slides SKILL.md](../SKILL.md)

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

@@ -162,7 +162,7 @@ lark-cli slides xml_presentation.slide create --as user \
 | 元素 | 说明 |
 |------|------|
 | `<style>` | 页面样式（背景填充） |
-| `<data>` | 图形元素容器（shape、img、table、chart 等） |
+| `<data>` | 图形元素容器（shape、img、table、chart、whiteboard 等） |
 | `<note>` | 演讲者备注 |
 
 > [!IMPORTANT]

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

@@ -94,7 +94,7 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 ## 注意事项
 
 1. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.get` 查看最新参数结构
-2. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
+2. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table、chart、whiteboard 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
 
    ```bash
    lark-cli slides xml_presentation.slide get --as user \

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

@@ -171,12 +171,13 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 ## 注意事项
 
 1. **parts 原子事务**：任一条失败整批回滚，不会出现"前几条成功、后几条失败"的中间态。
-2. **block_id 的获取**：`slide.get` 返回的 XML 里每个块（shape、img、table、chart 等）会带 3 位 short element ID，用这个值填 `block_id` / `insert_before_block_id`。
+2. **block_id 的获取**：`slide.get` 返回的 XML 里每个块（shape、img、table、chart、whiteboard 等）会带 3 位 short element ID，用这个值填 `block_id` / `insert_before_block_id`。
 3. **`<img>` 必须用 file_token**：不能用外链 URL——先 [`slides +media-upload`](lark-slides-media-upload.md) 拿 token。
 4. **不能字段级 patch**：要改一个块的某个属性（比如只改 `topLeftX`），得写整块新 XML 走 `block_replace`；API 不支持"只改一个字段"。
 5. **`block_replace` 要求 `replacement` 根元素带 `id="<block_id>"`**：底层 API 的硬约束，缺失会返回 3350001。推荐走 shortcut [`+replace-slide`](lark-slides-replace-slide.md)——它会自动把 `id` 注入到 `replacement` 根元素上，用户写 XML 时不用自己加。
 6. **`<shape>` 必须有 `<content/>` 子元素**：SML 2.0 schema 要求，缺失同样触发 3350001。shortcut [`+replace-slide`](lark-slides-replace-slide.md) 会自动注入 `<content/>`，直接调底层 API 需要自己加。
-7. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。
+7. **`<whiteboard>` 返回结构不含内部数据**：`slide.get` 返回的 whiteboard 块只有外层标签和位置属性，SVG / Mermaid 内容不会随 XML 一起返回。但 `block_replace` 仍然可以强行覆盖——直接写入完整新 whiteboard XML 即可。
+8. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。
 
 ## 相关命令
 

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

@@ -185,15 +185,15 @@ Use an object for one planned asset, an array for multiple real needs, or `asset
 - `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, arrows, labels, tables, simple charts, or placeholder panels.
+- `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 grouped boxes and arrows with short labels."}`
+- `{"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 line chart with shapes and value labels."}`
+- `{"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
 

skills/lark-slides/references/slides_xml_schema_definition.xml

@@ -935,7 +935,7 @@
                 单页幻灯片结构
                 子元素:
                 - style: 页面样式(背景色等), style的fill默认颜色为白色rgba(255, 255, 255, 1)
-                - data: 页面元素容器(shape/line/polyline/img/table/icon/chart/undefined)
+                - data: 页面元素容器(shape/line/polyline/img/table/icon/chart/whiteboard/undefined)
                 - note: 演讲者备注
             </xs:documentation>
         </xs:annotation>
@@ -960,6 +960,7 @@
                         <xs:element ref="sml:table"/>
                         <xs:element ref="sml:icon"/>
                         <xs:element ref="sml:chart"/>
+                        <xs:element ref="sml:whiteboard"/>
                         <xs:element ref="sml:undefined"/>
                     </xs:choice>
                 </xs:complexType>
@@ -1206,7 +1207,7 @@
                 未定义元素, 用于处理不支持的形状类型, 当导出时遇到不支持的type数据时, 使用此元素替代
                 属性说明:
                 - id: 元素唯一标识符(可选)
-                - type: 原始的不支持的类型名称, 包括 video(视频), audio(音频), whiteboard(画板）
+                - type: 原始的不支持的类型名称, 包括 video(视频), audio(音频)
             </xs:documentation>
         </xs:annotation>
         <xs:complexType>
@@ -3001,4 +3002,48 @@
             <xs:attribute name="alpha" type="sml:AlphaType" use="optional" default="1"/>
         </xs:complexType>
     </xs:element>
+
+    <!-- 画板元素 -->
+    <xs:element name="whiteboard">
+      <xs:annotation>
+        <xs:documentation>
+          画板元素, 用于在幻灯片中嵌入 Mermaid 或 SVG 绘制内容。
+
+          属性说明:
+          - id: 画板唯一标识符(可选)
+          - topLeftX/topLeftY: 左上角坐标, 必须
+          - width/height: 宽高尺寸, 必须
+          - flipX/flipY: 水平/垂直翻转
+          - alpha: 不透明度[0,1]
+
+          子元素(mermaid 与 svg 二选一):
+          - mermaid: Mermaid 源码文本, 可使用 CDATA 包裹
+            适用场景: 流程图、时序图、思维导图、类图、甘特图、饼图等结构化图表
+            特点: 用简短的文本声明描述图表逻辑, 由渲染引擎自动布局, 无需手动计算坐标
+            示例: &lt;mermaid&gt;&lt;![CDATA[flowchart TD\n  A[开始] --&gt; B[结束]]]&gt;&lt;/mermaid&gt;
+          - svg: SVG 内容
+            适用场景: 需要精确控制坐标、配色、路径的自定义图形
+            特点: 像素级精确定位，支持 rect/circle/path/text/polygon/g/linearGradient 等元素；radialGradient/filter/clipPath/mask/pattern 不支持，需手动计算所有坐标
+            示例: &lt;svg xmlns="http://www.w3.org/2000/svg"&gt;...&lt;/svg&gt;（xmlns 必填；width/height/viewBox 不影响渲染，仅百分比属性值场景需声明 viewBox）
+          - border: 边框样式, 可选, 无border标签代表无边框, 空border标签代表使用默认样式
+        </xs:documentation>
+      </xs:annotation>
+      <xs:complexType>
+        <xs:sequence>
+          <xs:choice>
+            <xs:element name="mermaid" type="xs:string" />
+            <xs:any namespace="http://www.w3.org/2000/svg" processContents="skip"/>
+          </xs:choice>
+          <xs:element name="border" type="sml:BorderType" minOccurs="0"/>
+        </xs:sequence>
+        <xs:attribute name="id" type="xs:string" use="optional"/>
+        <xs:attribute name="topLeftX" type="sml:XType" use="required"/>
+        <xs:attribute name="topLeftY" type="sml:YType" use="required"/>
+        <xs:attribute name="width" type="sml:PositiveSize" use="required"/>
+        <xs:attribute name="height" type="sml:PositiveSize" use="required"/>
+        <xs:attribute name="flipX" type="xs:boolean" use="optional" default="false"/>
+        <xs:attribute name="flipY" type="xs:boolean" use="optional" default="false"/>
+        <xs:attribute name="alpha" type="sml:AlphaType" use="optional" default="1"/>
+      </xs:complexType>
+    </xs:element>
 </xs:schema>

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

@@ -76,6 +76,14 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - 大量形状坐标完全相同，导致主体内容重叠。
 - 渐变背景回退成空白或白底，导致文字不可读。
 
+## Whiteboard Elements
+
+`slide.get` 回读 XML 时，`<whiteboard>` 块只返回位置属性（`topLeftX`、`topLeftY`、`width`、`height`），SVG / Mermaid 内容**不随 XML 返回**。
+
+- whiteboard 验证只能核对坐标是否越界：`topLeftX + width ≤ 960`，`topLeftY + height ≤ 540`。
+- SVG 和 Mermaid 内容的正确性无法通过回读 XML 验证，需要人工视觉验收。
+- 不要在验证记录中声称 whiteboard 内容已验证，除非用户确认了视觉效果。
+
 ## Layout And Overflow Risk
 
 优先修复这些明显风险：

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

@@ -168,6 +168,8 @@ Text:
 
 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.
@@ -182,6 +184,8 @@ Text:
 
 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.

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

@@ -44,7 +44,7 @@
 
 **子元素：**
 - `<style>?` - 页面样式，目前可放 `<fill>`
-- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`undefined`
+- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`whiteboard`、`undefined`
 - `<note>?` - 演讲者备注，内部可放 `<content>`
 
 ## theme 与文本类型
@@ -142,6 +142,34 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 <icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="120" width="32" height="32"/>
 ```
 
+### whiteboard
+
+```xml
+<!-- SVG 模式：数据图表、装饰元素 -->
+<whiteboard topLeftX="580" topLeftY="120" width="340" height="280">
+  <svg xmlns="http://www.w3.org/2000/svg">
+    <rect x="60" y="80" width="40" height="140" rx="3" fill="rgba(59,130,246,0.85)"/>
+    <text x="80" y="238" text-anchor="middle" font-size="11" fill="rgba(100,116,139,1)">ABC</text>
+  </svg>
+</whiteboard>
+
+<!-- Mermaid 模式：流程图、时序图等结构化图表 -->
+<whiteboard topLeftX="72" topLeftY="100" width="816" height="340">
+  <mermaid>
+    <![CDATA[
+      flowchart LR
+          A[开始] --> B{判断}
+          B -- 是 --> C[执行]
+          B -- 否 --> D[结束]
+    ]]>
+  </mermaid>
+</whiteboard>
+```
+
+SVG 模式：`<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`，内容大小由子元素包围盒决定；`width`/`height`/`viewBox` 不影响渲染，仅当元素使用百分比属性值时需声明 `viewBox`。\
+Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->` 等字符破坏 XML 解析。\
+详细用法见 [lark-slides-whiteboard.md](lark-slides-whiteboard.md)。
+
 ## 颜色与样式
 
 ### fill

skills/lark-vc-agent/SKILL.md

@@ -36,7 +36,7 @@ metadata:
 | "会议现在还开着，谁刚加入了"、"会议里谁在发言"、"有人共享屏幕吗"（**进行中会议**，且**机器人已入会**） | **本 skill** `+meeting-events`                                                                                                                         |
 | "退出会议"、"让机器人离开"                                            | **本 skill** `+meeting-leave`                                                                                                                          |
 | "昨天那场会有谁参加过"、"搜昨天的会"、"查纪要/逐字稿/录制"                          | [`lark-vc`](../lark-vc/SKILL.md)                                                                                                                      |
-| "帮我参会，结束后把纪要发到群" 等跨阶段场景                                    | 按序编排：本 skill（入会 → 读事件 → 离会）→ [`lark-vc`](../lark-vc/SKILL.md) / [`lark-minutes`](../lark-minutes/SKILL.md)（拉纪要）→ [`lark-im`](../lark-im/SKILL.md)（发群） |
+| "帮我参会，结束后把纪要发到群" 等跨阶段场景                                    | 按序编排：本 skill（入会 → 读事件）→ 会议结束后用 [`lark-vc`](../lark-vc/SKILL.md) / [`lark-minutes`](../lark-minutes/SKILL.md) 拉纪要 → [`lark-im`](../lark-im/SKILL.md) 发群 |
 
 ## 核心场景
 
@@ -66,12 +66,12 @@ metadata:
 
 ### 3. 离开会议（写操作）
 
-1. 任务完成、或用户要求结束时，用 `+meeting-leave --meeting-id <从 +meeting-join 拿到的 meeting.id>`。
+1. 只有用户明确要求机器人退出 / 离开 / 结束参会时，才用 `+meeting-leave --meeting-id <从 +meeting-join 拿到的 meeting.id>`；不要把任务完成当作离会指令。
 2. `--meeting-id` **必须**是 `+meeting-join` 返回的长数字 `meeting.id`，**不接受 9 位会议号**。
 3. 离会**立即生效**，机器人从会议的参会人列表中消失，对其他参会人可见；若需要重新入会，再跑一次 `+meeting-join` 即可（非真正"不可逆"）。
 4. 仅支持 `user` 身份。
 
-### 4. Agent 参会最小闭环示范
+### 4. Agent 参会示范
 
 ```bash
 # 1. 入会，捕获 meeting.id
@@ -83,13 +83,12 @@ MID=$(echo "$JOIN" | jq -r '.data.meeting.id')
 #    典型间隔 10-30 秒
 lark-cli vc +meeting-events --meeting-id "$MID" --page-all --format pretty
 
-# 3. 任务完成或用户要求结束时离会
-lark-cli vc +meeting-leave --meeting-id "$MID"
-
-# 4. 会后可选：取纪要 / 逐字稿（跨到 lark-vc）
+# 3. 会后可选：取纪要 / 逐字稿（跨到 lark-vc）
 lark-cli vc +notes --meeting-ids "$MID"
 ```
 
+如果用户随后明确要求退出 / 离开 / 结束参会，再单独调用 `lark-cli vc +meeting-leave --meeting-id "$MID"`。
+
 ## Shortcuts
 
 Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。

skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md

@@ -238,7 +238,7 @@ lark-cli vc +meeting-events \
 ## 参考
 
 - [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 先真实入会
-- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 完成任务后离会
+- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 用户明确要求时离会
 - [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
 - [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
 - [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要

skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md

@@ -84,14 +84,14 @@ lark-cli vc +meeting-join --meeting-number 123456789 --dry-run
 
 ## Agent 组合场景
 
-### 场景 1：加入会议 → 离开会议（最小闭环）
+### 场景 1：加入会议 → 监听会中事件
 
 ```bash
 # 第 1 步：加入会议，记录返回的 meeting.id
 lark-cli vc +meeting-join --meeting-number 123456789
 
-# 第 2 步：完成任务后，使用上一步返回的 meeting.id 离开会议
-lark-cli vc +meeting-leave --meeting-id <meeting.id>
+# 第 2 步：使用返回的 meeting.id 查询会中事件
+lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty
 ```
 
 ### 场景 2：加入会议 → 会后拉取纪要 / 录制
@@ -100,13 +100,10 @@ lark-cli vc +meeting-leave --meeting-id <meeting.id>
 # 第 1 步：加入并参会
 lark-cli vc +meeting-join --meeting-number 123456789
 
-# 第 2 步：离会
-lark-cli vc +meeting-leave --meeting-id <meeting.id>
-
-# 第 3 步：会议结束后，查询录制（拿到 minute_token）
+# 第 2 步：会议结束后，查询录制（拿到 minute_token）
 lark-cli vc +recording --meeting-ids <meeting.id>
 
-# 第 4 步：查询会议纪要（总结 / 待办 / 章节 / 逐字稿）
+# 第 3 步：查询会议纪要（总结 / 待办 / 章节 / 逐字稿）
 lark-cli vc +notes --meeting-ids <meeting.id>
 ```
 
@@ -123,7 +120,7 @@ lark-cli vc +notes --meeting-ids <meeting.id>
 ## 提示
 
 - 仅在 Agent 需要**真实加入**会议（例如参会机器人、会中助手）时使用；只拉取会议数据不需要入会。
-- 入会会让机器人立即出现在参会列表；若要回退，直接 `+meeting-leave` 即可。参数格式不确定时可选 `--dry-run` 预览，但不是必经步骤。
+- 入会会让机器人立即出现在参会列表；若用户要求退出 / 离开 / 结束参会，直接 `+meeting-leave` 即可。参数格式不确定时可选 `--dry-run` 预览，但不是必经步骤。
 - 执行成功后，立即记录返回的 `meeting.id`，用于后续 `+meeting-leave` / `+meeting-events`。
 
 ## 参考

skills/lark-vc-agent/references/lark-vc-agent-meeting-leave.md

@@ -44,7 +44,7 @@ lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --dry-run
 
 ### 4. 离会立即生效，对其他参会人可见
 
-机器人会立刻从参会列表消失；若会议启用了录制/纪要，bot 的参会时段到此截止。确认任务完成再调用；如需要重新入会，再跑 `+meeting-join` 即可（非真正"不可逆"）。
+机器人会立刻从参会列表消失；若会议启用了录制/纪要，bot 的参会时段到此截止。只有在用户明确要求退出 / 离开 / 结束参会时才调用；如需要重新入会，再跑 `+meeting-join` 即可（非真正"不可逆"）。
 
 ## 输出结果
 
@@ -59,29 +59,28 @@ lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --dry-run
 
 ## Agent 组合场景
 
-### 场景 1：加入 → 完成任务 → 离开（最小闭环）
+### 场景 1：加入 → 用户明确要求时离开
 
 ```bash
 # 第 1 步：加入会议，记录 meeting.id
 lark-cli vc +meeting-join --meeting-number 123456789
 
-# 第 2 步：在会中完成任务（如监听发言、记录信息等）
+# 第 2 步：在会中处理用户请求（如监听发言、记录信息等）
 # ...
 
-# 第 3 步：使用上一步记录的 meeting.id 离会
+# 第 3 步：仅在用户明确要求退出 / 离开 / 结束参会时，使用上一步记录的 meeting.id 离会
 lark-cli vc +meeting-leave --meeting-id <meeting.id>
 ```
 
-### 场景 2：会后补拉产物
+### 场景 2：会后补拉产物（不需要离会）
+
+如果用户只是要求会议结束后拉录制、纪要或逐字稿，不要先调用 `+meeting-leave`；直接跨到 `lark-vc` 查询会后产物。
 
 ```bash
-# 第 1 步：离会后会议仍在进行或已结束
-lark-cli vc +meeting-leave --meeting-id <meeting.id>
-
-# 第 2 步：会议结束后查询录制
+# 第 1 步：会议结束后查询录制
 lark-cli vc +recording --meeting-ids <meeting.id>
 
-# 第 3 步：查询会议纪要
+# 第 2 步：查询会议纪要
 lark-cli vc +notes --meeting-ids <meeting.id>
 ```
 
@@ -95,9 +94,9 @@ lark-cli vc +notes --meeting-ids <meeting.id>
 
 ## 提示
 
-- 离会会让机器人从参会列表消失，对其他参会人可见；若需要重新入会直接再 `+meeting-join`，不是真正的"不可逆"。参数格式不确定时可选 `--dry-run` 预览。
-- 与 `+meeting-join` 成对使用：能 join 的身份才能 leave。
-- `meeting_id` 必须来自 `+meeting-join` 的返回值，不要用 9 位会议号。
+- 只有用户明确要求退出 / 离开 / 结束参会时才调用；离会会让机器人从参会列表消失，对其他参会人可见。若需要重新入会直接再 `+meeting-join`，不是真正的"不可逆"。参数格式不确定时可选 `--dry-run` 预览。
+- `+meeting-leave` 依赖 `+meeting-join` 返回的 `meeting.id`，但不是每次 join 后都必须调用 leave。
+- `meeting_id` 优先使用 `+meeting-join` 返回的 `meeting.id`；如果来自 `+search`，也必须先确认当前身份就在该会议中。不要用 9 位会议号。
 
 ## 参考
 

tests/cli_e2e/sheets/sheets_crud_workflow_test.go

@@ -143,14 +143,14 @@ func TestSheets_CRUDE2EWorkflow(t *testing.T) {
 		assert.True(t, len(matchedCells.Array()) > 0, "should find at least one cell containing 'Alice'")
 	})
 
-	t.Run("export spreadsheet with +export as bot", func(t *testing.T) {
+	t.Run("export spreadsheet with +workbook-export as bot", func(t *testing.T) {
 		require.NotEmpty(t, spreadsheetToken, "spreadsheet token is required")
 		outputDir := t.TempDir()
 		outputPath := filepath.Join(outputDir, "export.xlsx")
 
 		result, err := clie2e.RunCmd(ctx, clie2e.Request{
 			Args: []string{
-				"sheets", "+export",
+				"sheets", "+workbook-export",
 				"--spreadsheet-token", spreadsheetToken,
 				"--file-extension", "xlsx",
 				"--output-path", "./export.xlsx",