chore: split slides creator skill

Change-Id: I2d3d47ef999a88b9aa8c22147e5a78d469889e5f

CHANGELOG.md

@@ -2,22 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [v1.0.30] - 2026-05-13
-
-### Features
-
-- **im**: Add `--chat-mode topic` to `+chat-create` (#790)
-
-### Bug Fixes
-
-- **auth**: Support comma-separated `--scope` in `auth login` (#764)
-- **auth**: Clarify URL handling in auth messages and docs (#856)
-- **bind**: Accept `~/` paths in OpenClaw secret references (#839)
-
-### Tests
-
-- **update**: Isolate stamp writes from real `~/.lark-cli/skills.stamp` (#858)
-
 ## [v1.0.29] - 2026-05-12
 
 ### Features
@@ -692,7 +676,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
-[v1.0.30]: https://github.com/larksuite/cli/releases/tag/v1.0.30
 [v1.0.29]: https://github.com/larksuite/cli/releases/tag/v1.0.29
 [v1.0.28]: https://github.com/larksuite/cli/releases/tag/v1.0.28
 [v1.0.27]: https://github.com/larksuite/cli/releases/tag/v1.0.27

README.md

@@ -6,14 +6,14 @@
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, Markdown, and more, with 200+ commands and 24 AI Agent [Skills](./skills/).
+The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, Markdown, and more, with 200+ commands and 25 AI Agent [Skills](./skills/).
 
 [Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Commands](#three-layer-command-system) · [Advanced](#advanced-usage) · [Security](#security--risk-warnings-read-before-use) · [Contributing](#contributing)
 
 ## Why lark-cli?
 
-- **Agent-Native Design** — 24 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
-- **Wide Coverage** — 17 business domains, 200+ curated commands, 24 AI Agent [Skills](./skills/)
+- **Agent-Native Design** — 25 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
+- **Wide Coverage** — 17 business domains, 200+ curated commands, 25 AI Agent [Skills](./skills/)
 - **AI-Friendly & Optimized** — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output to maximize Agent call success rates
 - **Open Source, Zero Barriers** — MIT license, ready to use, just `npm install`
 - **Up and Running in 3 Minutes** — One-click app creation, interactive login, from install to first API call in just 3 steps
@@ -142,7 +142,8 @@ lark-cli auth status
 | `lark-drive`                    | Upload, download files, manage permissions & comments                                                          |
 | `lark-markdown`                 | Create, fetch, and overwrite Drive-native Markdown files                                                       |
 | `lark-sheets`                   | Create, read, write, append, find, export spreadsheets                                                         |
-| `lark-slides`                   | Create and manage presentations, read presentation content, and add or remove slides                          |
+| `lark-slides-creator`           | Create polished presentations with planning, design, asset, template, and validation workflows                |
+| `lark-slides`                   | Low-level Slides XML/API read/write operations                                                               |
 | `lark-base`                     | Tables, fields, records, views, dashboards, data aggregation & analytics                                       |
 | `lark-task`                     | Tasks, task lists, subtasks, reminders, member assignment                                                      |
 | `lark-mail`                     | Browse, search, read emails, send, reply, forward, draft management, watch new mail                            |

cmd/auth/login.go

@@ -30,7 +30,6 @@ type LoginOptions struct {
 	Scope      string
 	Recommend  bool
 	Domains    []string
-	Exclude    []string
 	NoWait     bool
 	DeviceCode string
 }
@@ -63,13 +62,11 @@ browser. Run it in the background and retrieve the verification URL from its out
 	}
 	cmdutil.SetSupportedIdentities(cmd, []string{"user"})
 
-	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space- or comma-separated). Combines additively with --domain/--recommend")
+	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space-separated)")
 	cmd.Flags().BoolVar(&opts.Recommend, "recommend", false, "request only recommended (auto-approve) scopes")
 	available := sortedKnownDomains()
 	cmd.Flags().StringSliceVar(&opts.Domains, "domain", nil,
 		fmt.Sprintf("domain (repeatable or comma-separated, e.g. --domain calendar,task)\navailable: %s, all", strings.Join(available, ", ")))
-	cmd.Flags().StringSliceVar(&opts.Exclude, "exclude", nil,
-		"scopes to exclude from the request (repeatable or comma-separated, e.g. --exclude drive:file:download)")
 	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmd.Flags().BoolVar(&opts.NoWait, "no-wait", false, "initiate device authorization and return immediately; use --device-code to complete")
 	cmd.Flags().StringVar(&opts.DeviceCode, "device-code", "", "poll and complete authorization with a device code from a previous --no-wait call")
@@ -161,10 +158,6 @@ func authLoginRun(opts *LoginOptions) error {
 
 	hasAnyOption := opts.Scope != "" || opts.Recommend || len(selectedDomains) > 0
 
-	if len(opts.Exclude) > 0 && !hasAnyOption {
-		return output.ErrValidation("--exclude requires --scope, --domain, or --recommend to be specified")
-	}
-
 	if !hasAnyOption {
 		if !opts.JSON && f.IOStreams.IsTerminal {
 			result, err := runInteractiveLogin(f.IOStreams, lang, msg)
@@ -192,17 +185,14 @@ func authLoginRun(opts *LoginOptions) error {
 		}
 	}
 
-	// Normalize --scope so users can pass either OAuth-standard space-separated
-	// values or the more natural comma-separated list. RFC 6749 §3.3 mandates
-	// space-delimited scopes in the wire request, so the device authorization
-	// endpoint rejects raw "a,b" strings as a single malformed scope.
-	finalScope := normalizeScopeInput(opts.Scope)
+	finalScope := opts.Scope
 
-	// Resolve scopes from domain/permission filters and merge with --scope.
-	// --scope, --domain, and --recommend combine additively so callers can,
-	// for example, request all `docs` scopes plus a few specific `drive`
-	// scopes in a single command.
+	// Resolve scopes from domain/permission filters
 	if len(selectedDomains) > 0 || opts.Recommend {
+		if opts.Scope != "" {
+			return output.ErrValidation("cannot use --scope together with --domain/--recommend")
+		}
+
 		var candidateScopes []string
 		if len(selectedDomains) > 0 {
 			candidateScopes = collectScopesForDomains(selectedDomains, "user")
@@ -216,35 +206,11 @@ func authLoginRun(opts *LoginOptions) error {
 			candidateScopes = registry.FilterAutoApproveScopes(candidateScopes)
 		}
 
-		if len(candidateScopes) == 0 && opts.Scope == "" {
+		if len(candidateScopes) == 0 {
 			return output.ErrValidation("no matching scopes found, check domain/scope options")
 		}
 
-		// Merge --scope additively with the resolved domain scopes.
-		merged := make(map[string]bool, len(candidateScopes)+len(strings.Fields(finalScope)))
-		for _, s := range candidateScopes {
-			merged[s] = true
-		}
-		for _, s := range strings.Fields(finalScope) {
-			merged[s] = true
-		}
-		finalScope = joinSortedScopeSet(merged)
-	}
-
-	// Apply --exclude on top of the resolved scope set. We honour exclude
-	// regardless of whether scopes came from --scope, --domain, --recommend,
-	// or any combination thereof.
-	if len(opts.Exclude) > 0 {
-		excluded, unknown := applyExcludeScopes(finalScope, opts.Exclude)
-		if len(unknown) > 0 {
-			return output.ErrValidation(
-				"these --exclude scopes are not present in the requested set: %s",
-				strings.Join(unknown, ", "))
-		}
-		finalScope = excluded
-		if strings.TrimSpace(finalScope) == "" {
-			return output.ErrValidation("no scopes left after applying --exclude; nothing to authorize")
-		}
+		finalScope = strings.Join(candidateScopes, " ")
 	}
 
 	// Step 1: Request device authorization
@@ -566,40 +532,6 @@ func shortcutSupportsIdentity(sc common.Shortcut, identity string) bool {
 	return false
 }
 
-// normalizeScopeInput accepts a user-supplied --scope value that may use
-// commas, spaces, tabs, or newlines (or any mix) as separators and returns the
-// canonical OAuth 2.0 wire form: a single space-joined string with empties
-// trimmed and duplicates removed (first occurrence wins; order preserved).
-//
-// Examples:
-//
-//	"vc:note:read,vc:meeting.meetingevent:read" -> "vc:note:read vc:meeting.meetingevent:read"
-//	"a, b ,  c"                                 -> "a b c"
-//	"a b a"                                     -> "a b"
-//	""                                          -> ""
-func normalizeScopeInput(raw string) string {
-	if raw == "" {
-		return ""
-	}
-	// Treat both commas and any whitespace as separators.
-	fields := strings.FieldsFunc(raw, func(r rune) bool {
-		return r == ',' || r == ' ' || r == '\t' || r == '\n' || r == '\r'
-	})
-	if len(fields) == 0 {
-		return ""
-	}
-	seen := make(map[string]struct{}, len(fields))
-	out := make([]string, 0, len(fields))
-	for _, f := range fields {
-		if _, ok := seen[f]; ok {
-			continue
-		}
-		seen[f] = struct{}{}
-		out = append(out, f)
-	}
-	return strings.Join(out, " ")
-}
-
 // suggestDomain finds the best "did you mean" match for an unknown domain.
 func suggestDomain(input string, known map[string]bool) string {
 	// Check common cases: prefix match or input is a substring
@@ -610,58 +542,3 @@ func suggestDomain(input string, known map[string]bool) string {
 	}
 	return ""
 }
-
-// joinSortedScopeSet returns a deterministic, space-separated scope string
-// from a set, sorted alphabetically. Empty/blank scopes are dropped.
-func joinSortedScopeSet(set map[string]bool) string {
-	out := make([]string, 0, len(set))
-	for s := range set {
-		if strings.TrimSpace(s) == "" {
-			continue
-		}
-		out = append(out, s)
-	}
-	sort.Strings(out)
-	return strings.Join(out, " ")
-}
-
-// applyExcludeScopes removes the provided exclude entries from the requested
-// scope string. Each --exclude flag value may itself contain comma- or
-// whitespace-separated scopes. Returns the filtered scope string and any
-// exclude entries that were not present in the requested set (callers can
-// surface those as a validation error to catch typos like
-// `--exclude drive:file:downlod`).
-func applyExcludeScopes(requested string, excludes []string) (string, []string) {
-	requestedSet := make(map[string]bool)
-	for _, s := range strings.Fields(requested) {
-		requestedSet[s] = true
-	}
-
-	excludeSet := make(map[string]bool)
-	for _, raw := range excludes {
-		// --exclude already splits on commas (StringSliceVar), but also
-		// tolerate whitespace-separated entries inside a single value.
-		for _, s := range strings.Fields(strings.ReplaceAll(raw, ",", " ")) {
-			excludeSet[s] = true
-		}
-	}
-
-	var unknown []string
-	for s := range excludeSet {
-		if !requestedSet[s] {
-			unknown = append(unknown, s)
-		}
-	}
-	if len(unknown) > 0 {
-		sort.Strings(unknown)
-		return requested, unknown
-	}
-
-	kept := make(map[string]bool, len(requestedSet))
-	for s := range requestedSet {
-		if !excludeSet[s] {
-			kept[s] = true
-		}
-	}
-	return joinSortedScopeSet(kept), nil
-}

cmd/auth/login_test.go

@@ -70,32 +70,6 @@ func TestSuggestDomain_ExactMatch(t *testing.T) {
 	}
 }
 
-func TestNormalizeScopeInput(t *testing.T) {
-	cases := []struct {
-		name string
-		in   string
-		want string
-	}{
-		{"empty", "", ""},
-		{"single", "vc:note:read", "vc:note:read"},
-		{"comma", "vc:note:read,vc:meeting.meetingevent:read", "vc:note:read vc:meeting.meetingevent:read"},
-		{"space", "vc:note:read vc:meeting.meetingevent:read", "vc:note:read vc:meeting.meetingevent:read"},
-		{"comma_and_spaces", "vc:note:read, vc:meeting.meetingevent:read", "vc:note:read vc:meeting.meetingevent:read"},
-		{"mixed_separators", "a, b\tc\nd  e", "a b c d e"},
-		{"trim_and_dedup", "  a , b , a  ", "a b"},
-		{"trailing_separators", "a,b,,", "a b"},
-		{"only_separators", " , , ", ""},
-		{"tab_separated", "im:message:send\toffline_access", "im:message:send offline_access"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			if got := normalizeScopeInput(tc.in); got != tc.want {
-				t.Errorf("normalizeScopeInput(%q) = %q, want %q", tc.in, got, tc.want)
-			}
-		})
-	}
-}
-
 func TestShortcutSupportsIdentity_DefaultUser(t *testing.T) {
 	// Empty AuthTypes defaults to ["user"]
 	sc := common.Shortcut{AuthTypes: nil}

package.json

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

shortcuts/drive/drive_duplicate_remote_test.go

@@ -15,7 +15,6 @@ import (
 	"strconv"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -626,94 +625,6 @@ func TestChooseRemoteFileSortsByParsedTimes(t *testing.T) {
 	}
 }
 
-// TestChooseRemoteFileSortsMixedUnitEpochsByActualTime verifies duplicate
-// resolution compares actual timestamps rather than raw integer magnitudes when
-// Drive mixes second- and millisecond-resolution epoch strings.
-func TestChooseRemoteFileSortsMixedUnitEpochsByActualTime(t *testing.T) {
-	files := []driveRemoteEntry{
-		{FileToken: "token_seconds", CreatedTime: "1715594881", ModifiedTime: "1715594881"},
-		{FileToken: "token_millis", CreatedTime: "1715594880123", ModifiedTime: "1715594880123"},
-	}
-	gotNewest, err := chooseRemoteFile(files, driveDuplicateRemoteNewest)
-	if err != nil {
-		t.Fatalf("chooseRemoteFile newest: %v", err)
-	}
-	if gotNewest.FileToken != "token_seconds" {
-		t.Fatalf("newest token = %q, want token_seconds", gotNewest.FileToken)
-	}
-	gotOldest, err := chooseRemoteFile(files, driveDuplicateRemoteOldest)
-	if err != nil {
-		t.Fatalf("chooseRemoteFile oldest: %v", err)
-	}
-	if gotOldest.FileToken != "token_millis" {
-		t.Fatalf("oldest token = %q, want token_millis", gotOldest.FileToken)
-	}
-}
-
-// TestDrivePushDeleteRemoteKeepsActualNewestDuplicateAcrossMixedEpochUnits
-// proves the duplicate selector and delete pass agree on the true newest file
-// even when remote timestamps use mixed epoch units.
-func TestDrivePushDeleteRemoteKeepsActualNewestDuplicateAcrossMixedEpochUnits(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	if err := os.WriteFile(filepath.Join("local", "dup.txt"), []byte("hello"), 0o644); err != nil {
-		t.Fatalf("WriteFile: %v", err)
-	}
-
-	registerRemoteListing(reg, "folder_root", []map[string]interface{}{
-		{"token": duplicateRemoteFileIDFirst, "name": "dup.txt", "type": "file", "size": 5, "created_time": "1715594880123", "modified_time": "1715594880123"},
-		{"token": duplicateRemoteFileIDSecond, "name": "dup.txt", "type": "file", "size": 6, "created_time": "1715594881", "modified_time": "1715594881"},
-	})
-	uploadStub := &httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/files/upload_all",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"file_token": "dup-new-token",
-				"version":    "v7",
-			},
-		},
-	}
-	reg.Register(uploadStub)
-	deleteStub := &httpmock.Stub{
-		Method: "DELETE",
-		URL:    "/open-apis/drive/v1/files/" + duplicateRemoteFileIDFirst,
-		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
-	}
-	reg.Register(deleteStub)
-
-	err := mountAndRunDrive(t, DrivePush, []string{
-		"+push",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--if-exists", "overwrite",
-		"--on-duplicate-remote", "newest",
-		"--delete-remote",
-		"--yes",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
-	}
-
-	body := decodeDriveMultipartBody(t, uploadStub)
-	if got := body.Fields["file_token"]; got != duplicateRemoteFileIDSecond {
-		t.Fatalf("upload_all form file_token = %q, want %q", got, duplicateRemoteFileIDSecond)
-	}
-	assertPushItemAction(t, stdout.Bytes(), "dup.txt", "deleted_remote", duplicateRemoteFileIDFirst)
-	if deleteStub.CapturedHeaders == nil {
-		t.Fatal("DELETE for older mixed-unit duplicate sibling was never issued")
-	}
-
-	reg.Verify(t)
-}
-
 func TestChooseRemoteFileFallsBackToFileTokenOnTimeParseFailure(t *testing.T) {
 	files := []driveRemoteEntry{
 		{FileToken: "token_a", CreatedTime: "bad", ModifiedTime: "bad"},
@@ -735,46 +646,6 @@ func TestChooseRemoteFileRejectsEmptyCandidates(t *testing.T) {
 	}
 }
 
-func TestCompareDriveRemoteModifiedToLocalSupportsSecondAndMillisecondEpochs(t *testing.T) {
-	t.Run("second resolution truncates local mtime", func(t *testing.T) {
-		cmp, ok := compareDriveRemoteModifiedToLocal("100", time.Unix(100, 900*int64(time.Millisecond)))
-		if !ok {
-			t.Fatal("expected second-resolution timestamp to parse")
-		}
-		if cmp != 0 {
-			t.Fatalf("cmp = %d, want 0 when local only differs below second resolution", cmp)
-		}
-	})
-
-	t.Run("millisecond resolution stays precise", func(t *testing.T) {
-		const remoteMillis = int64(1715594880123)
-		cmp, ok := compareDriveRemoteModifiedToLocal(strconv.FormatInt(remoteMillis, 10), time.UnixMilli(remoteMillis))
-		if !ok {
-			t.Fatal("expected millisecond-resolution timestamp to parse")
-		}
-		if cmp != 0 {
-			t.Fatalf("cmp = %d, want 0 for equal millisecond timestamps", cmp)
-		}
-	})
-
-	t.Run("microsecond resolution stays precise", func(t *testing.T) {
-		const remoteMicros = int64(1715594880123456)
-		cmp, ok := compareDriveRemoteModifiedToLocal(strconv.FormatInt(remoteMicros, 10), time.UnixMicro(remoteMicros))
-		if !ok {
-			t.Fatal("expected microsecond-resolution timestamp to parse")
-		}
-		if cmp != 0 {
-			t.Fatalf("cmp = %d, want 0 for equal microsecond timestamps", cmp)
-		}
-	})
-
-	t.Run("invalid timestamp is rejected", func(t *testing.T) {
-		if _, ok := compareDriveRemoteModifiedToLocal("not-a-time", time.Now()); ok {
-			t.Fatal("expected invalid remote timestamp to be rejected")
-		}
-	})
-}
-
 func TestDrivePullRemoteViewsRejectsUnknownStrategy(t *testing.T) {
 	_, _, err := drivePullRemoteViews([]driveRemoteEntry{
 		{RelPath: "dup.txt", Type: driveTypeFile, FileToken: duplicateRemoteFileIDFirst},

shortcuts/drive/drive_pull.go

@@ -11,7 +11,6 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
-	"time"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
@@ -21,18 +20,8 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-var drivePullChtimes = drivePullApplyChtimes
-
-// drivePullApplyChtimes is a tiny indirection that keeps the production path on
-// os.Chtimes while still letting tests inject mtime failures without requiring a
-// custom filesystem implementation.
-func drivePullApplyChtimes(path string, atime, mtime time.Time) error {
-	return os.Chtimes(path, atime, mtime) //nolint:forbidigo // FileIO exposes no mtime mutation API yet; callers resolve and bound the path first.
-}
-
 const (
 	drivePullIfExistsOverwrite = "overwrite"
-	drivePullIfExistsSmart     = "smart"
 	drivePullIfExistsSkip      = "skip"
 )
 
@@ -48,7 +37,6 @@ type drivePullTarget struct {
 	DownloadToken string
 	ItemFileToken string
 	ItemSourceID  string
-	ModifiedTime  string
 }
 
 // DrivePull performs a one-way file-level mirror from a Drive folder onto
@@ -72,7 +60,7 @@ var DrivePull = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "local-dir", Desc: "local root directory (relative to cwd)", Required: true},
 		{Name: "folder-token", Desc: "source Drive folder token", Required: true},
-		{Name: "if-exists", Desc: "policy when a local file already exists (skip = never touch existing files; smart = skip when local mtime is already up to date; overwrite = always replace)", Default: drivePullIfExistsOverwrite, Enum: []string{drivePullIfExistsOverwrite, drivePullIfExistsSmart, drivePullIfExistsSkip}},
+		{Name: "if-exists", Desc: "policy when a local file already exists", Default: drivePullIfExistsOverwrite, Enum: []string{drivePullIfExistsOverwrite, drivePullIfExistsSkip}},
 		{Name: "on-duplicate-remote", Desc: "policy when multiple remote Drive entries map to the same rel_path", Default: driveDuplicateRemoteFail, Enum: []string{driveDuplicateRemoteFail, driveDuplicateRemoteRename, driveDuplicateRemoteNewest, driveDuplicateRemoteOldest}},
 		{Name: "delete-local", Type: "bool", Desc: "delete local regular files absent from Drive (file-level mirror; empty directories are NOT pruned); requires --yes"},
 		{Name: "yes", Type: "bool", Desc: "confirm --delete-local before deleting local files"},
@@ -80,7 +68,6 @@ var DrivePull = common.Shortcut{
 	Tips: []string{
 		"Only entries with type=file are downloaded; online docs (docx, sheet, bitable, mindnote, slides) and shortcuts are skipped.",
 		"Subfolders recurse and are reproduced as local directories under --local-dir; missing parents are created automatically.",
-		"For repeat syncs, --if-exists=smart is the recommended best-effort incremental mode: it compares local mtime with Drive modified_time and skips downloads when the local copy is already up to date.",
 		"Duplicate remote rel_path conflicts fail by default. Use --on-duplicate-remote=rename to download duplicate files with stable hashed suffixes.",
 		"--delete-local requires --yes; without --yes the command is rejected upfront so a stray flag never deletes anything.",
 	},
@@ -215,14 +202,14 @@ var DrivePull = common.Shortcut{
 					downloadFailed++
 					continue
 				}
-				if ifExists == drivePullIfExistsSkip || drivePullShouldSkipSmart(target, targetFile, ifExists, runtime) {
+				if ifExists == drivePullIfExistsSkip {
 					items = append(items, drivePullItem{RelPath: rel, FileToken: itemFileToken, SourceID: itemSourceID, Action: "skipped"})
 					skipped++
 					continue
 				}
 			}
 
-			if err := drivePullDownload(ctx, runtime, downloadToken, target, targetFile.ModifiedTime); err != nil {
+			if err := drivePullDownload(ctx, runtime, downloadToken, target); err != nil {
 				items = append(items, drivePullItem{RelPath: rel, FileToken: itemFileToken, SourceID: itemSourceID, Action: "failed", Error: err.Error()})
 				failed++
 				downloadFailed++
@@ -318,9 +305,7 @@ var DrivePull = common.Shortcut{
 	},
 }
 
-// drivePullDownload streams one Drive file into the local mirror target and
-// then best-effort aligns the local mtime to Drive's modified_time.
-func drivePullDownload(ctx context.Context, runtime *common.RuntimeContext, fileToken, target, remoteModifiedTime string) error {
+func drivePullDownload(ctx context.Context, runtime *common.RuntimeContext, fileToken, target string) error {
 	resp, err := runtime.DoAPIStream(ctx, &larkcore.ApiReq{
 		HttpMethod: "GET",
 		ApiPath:    fmt.Sprintf("/open-apis/drive/v1/files/%s/download", validate.EncodePathSegment(fileToken)),
@@ -335,53 +320,9 @@ func drivePullDownload(ctx context.Context, runtime *common.RuntimeContext, file
 	}, resp.Body); err != nil {
 		return common.WrapSaveErrorByCategory(err, "io")
 	}
-	if err := drivePullApplyRemoteModifiedTime(target, remoteModifiedTime, runtime); err != nil {
-		fmt.Fprintf(runtime.IO().ErrOut, "Downloaded %s but could not preserve remote modified_time: %s\n", target, err)
-	}
 	return nil
 }
 
-// drivePullApplyRemoteModifiedTime preserves Drive's modified_time on a local
-// file when the remote timestamp is parseable and the target path is safe.
-func drivePullApplyRemoteModifiedTime(target, remoteModifiedTime string, runtime *common.RuntimeContext) error {
-	remoteTime, _, ok := parseDriveEpoch(remoteModifiedTime)
-	if !ok {
-		return nil
-	}
-	resolved, err := runtime.FileIO().ResolvePath(target)
-	if err != nil {
-		return output.ErrValidation("unsafe output path: %s", err)
-	}
-	if err := drivePullChtimes(resolved, remoteTime, remoteTime); err != nil {
-		return output.Errorf(output.ExitInternal, "io", "cannot preserve remote modified_time on local file: %s", err)
-	}
-	return nil
-}
-
-func drivePullShouldSkipSmart(target string, remoteFile drivePullTarget, ifExists string, runtime *common.RuntimeContext) bool {
-	if ifExists != drivePullIfExistsSmart {
-		return false
-	}
-	if remoteFile.ModifiedTime == "" {
-		return false
-	}
-	resolved, err := runtime.FileIO().ResolvePath(target)
-	if err != nil {
-		return false
-	}
-	info, err := os.Stat(resolved) //nolint:forbidigo // FileIO exposes no ModTime-capable Stat; ResolvePath already bounded the path.
-	if err != nil {
-		return false
-	}
-	cmp, ok := compareDriveRemoteModifiedToLocal(remoteFile.ModifiedTime, info.ModTime())
-	if !ok {
-		return false
-	}
-	// Local is already at least as new as the remote file, so another
-	// download would be redundant.
-	return cmp <= 0
-}
-
 func drivePullRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (map[string]drivePullTarget, map[string]struct{}, error) {
 	remoteFiles := make(map[string]drivePullTarget, len(entries))
 	remotePaths := make(map[string]struct{}, len(entries))
@@ -405,7 +346,7 @@ func drivePullRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (m
 	for _, rel := range relPaths {
 		files := fileGroups[rel]
 		if len(files) == 1 {
-			remoteFiles[rel] = drivePullTarget{DownloadToken: files[0].FileToken, ItemFileToken: files[0].FileToken, ModifiedTime: files[0].ModifiedTime}
+			remoteFiles[rel] = drivePullTarget{DownloadToken: files[0].FileToken, ItemFileToken: files[0].FileToken}
 			remotePaths[rel] = struct{}{}
 			continue
 		}
@@ -425,7 +366,6 @@ func drivePullRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (m
 				remoteFiles[targetRel] = drivePullTarget{
 					DownloadToken: file.FileToken,
 					ItemSourceID:  stableTokenIdentifier(file.FileToken),
-					ModifiedTime:  file.ModifiedTime,
 				}
 				remotePaths[targetRel] = struct{}{}
 			}
@@ -434,7 +374,7 @@ func drivePullRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (m
 			if err != nil {
 				return nil, nil, err
 			}
-			remoteFiles[rel] = drivePullTarget{DownloadToken: chosen.FileToken, ItemFileToken: chosen.FileToken, ModifiedTime: chosen.ModifiedTime}
+			remoteFiles[rel] = drivePullTarget{DownloadToken: chosen.FileToken, ItemFileToken: chosen.FileToken}
 			remotePaths[rel] = struct{}{}
 		default:
 			return nil, nil, fmt.Errorf("unsupported duplicate remote strategy %q", duplicateRemote)

shortcuts/drive/drive_pull_test.go

@@ -4,23 +4,17 @@
 package drive
 
 import (
-	"context"
 	"encoding/json"
 	"errors"
-	"fmt"
 	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/shortcuts/common"
-	"github.com/spf13/cobra"
 )
 
 // TestDrivePullDownloadsAndCreatesParents verifies the happy path: a remote
@@ -157,322 +151,6 @@ func TestDrivePullSkipsExistingWhenSkipPolicy(t *testing.T) {
 	mustReadFile(t, filepath.Join("local", "keep.txt"), "local-original")
 }
 
-// TestDrivePullSkipsExistingWhenSmartPolicyAndLocalIsUpToDate verifies the
-// smart fast path for Drive → local mirrors: when the local copy is already
-// at least as new as the remote file, +pull skips the download.
-func TestDrivePullSkipsExistingWhenSmartPolicyAndLocalIsUpToDate(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	localPath := filepath.Join("local", "keep.txt")
-	if err := os.WriteFile(localPath, []byte("hello"), 0o644); err != nil {
-		t.Fatalf("WriteFile: %v", err)
-	}
-	localMTime := time.Unix(200, 500*int64(time.Millisecond))
-	if err := os.Chtimes(localPath, localMTime, localMTime); err != nil {
-		t.Fatalf("Chtimes: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_keep", "name": "keep.txt", "type": "file", "size": 5, "modified_time": "100"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-
-	// Intentionally NO download stub: smart mode should skip the transfer.
-	err := mountAndRunDrive(t, DrivePull, []string{
-		"+pull",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--if-exists", "smart",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"skipped": 1`) {
-		t.Errorf("expected skipped=1, got: %s", out)
-	}
-	if !strings.Contains(out, `"downloaded": 0`) {
-		t.Errorf("expected downloaded=0, got: %s", out)
-	}
-	mustReadFile(t, localPath, "hello")
-}
-
-// TestDrivePullDownloadsWhenSmartPolicyAndRemoteIsNewer verifies the smart
-// policy still downloads when the remote file is newer than the local copy.
-func TestDrivePullDownloadsWhenSmartPolicyAndRemoteIsNewer(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	localPath := filepath.Join("local", "keep.txt")
-	if err := os.WriteFile(localPath, []byte("hello"), 0o644); err != nil {
-		t.Fatalf("WriteFile: %v", err)
-	}
-	localMTime := time.Unix(100, 500*int64(time.Millisecond))
-	if err := os.Chtimes(localPath, localMTime, localMTime); err != nil {
-		t.Fatalf("Chtimes: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_keep", "name": "keep.txt", "type": "file", "size": 5, "modified_time": "200"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/tok_keep/download",
-		Status:  200,
-		Body:    []byte("WORLD"),
-		Headers: http.Header{"Content-Type": []string{"application/octet-stream"}},
-	})
-
-	err := mountAndRunDrive(t, DrivePull, []string{
-		"+pull",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--if-exists", "smart",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"downloaded": 1`) {
-		t.Errorf("expected downloaded=1, got: %s", out)
-	}
-	mustReadFile(t, localPath, "WORLD")
-	info, err := os.Stat(localPath)
-	if err != nil {
-		t.Fatalf("Stat: %v", err)
-	}
-	if got, want := info.ModTime(), time.Unix(200, 0); !got.Equal(want) {
-		t.Fatalf("local mtime = %v, want %v", got, want)
-	}
-}
-
-// TestDrivePullTreatsModifiedTimePreservationFailureAsNotice verifies a local
-// write that succeeds but cannot preserve remote modified_time still reports a
-// successful download and only emits an operator-facing notice on stderr.
-func TestDrivePullTreatsModifiedTimePreservationFailureAsNotice(t *testing.T) {
-	f, stdout, stderrBuf, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-
-	prevChtimes := drivePullChtimes
-	drivePullChtimes = func(string, time.Time, time.Time) error {
-		return fmt.Errorf("mtime mutation unsupported")
-	}
-	t.Cleanup(func() {
-		drivePullChtimes = prevChtimes
-	})
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_keep", "name": "keep.txt", "type": "file", "size": 5, "modified_time": "200"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/tok_keep/download",
-		Status:  200,
-		Body:    []byte("WORLD"),
-		Headers: http.Header{"Content-Type": []string{"application/octet-stream"}},
-	})
-
-	err := mountAndRunDrive(t, DrivePull, []string{
-		"+pull",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--delete-local",
-		"--yes",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s\nstderr: %s", err, stdout.String(), stderrBuf.String())
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"downloaded": 1`) {
-		t.Errorf("expected downloaded=1, got: %s", out)
-	}
-	if !strings.Contains(out, `"failed": 0`) {
-		t.Errorf("expected failed=0, got: %s", out)
-	}
-	mustReadFile(t, filepath.Join("local", "keep.txt"), "WORLD")
-	if !strings.Contains(stderrBuf.String(), "could not preserve remote modified_time") {
-		t.Errorf("expected stderr notice about modified_time preservation failure, got: %s", stderrBuf.String())
-	}
-
-	reg.Verify(t)
-}
-
-func TestDrivePullShouldSkipSmartFallsBackWhenMetadataCannotBeTrusted(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	localPath := filepath.Join("local", "keep.txt")
-	if err := os.WriteFile(localPath, []byte("hello"), 0o644); err != nil {
-		t.Fatalf("WriteFile: %v", err)
-	}
-	localMTime := time.Unix(100, 500*int64(time.Millisecond))
-	if err := os.Chtimes(localPath, localMTime, localMTime); err != nil {
-		t.Fatalf("Chtimes: %v", err)
-	}
-
-	runtime := common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "test"}, driveTestConfig(), f, core.AsBot)
-
-	for _, tt := range []struct {
-		name       string
-		ifExists   string
-		remoteFile drivePullTarget
-	}{
-		{
-			name:       "non-smart policy",
-			ifExists:   drivePullIfExistsOverwrite,
-			remoteFile: drivePullTarget{ModifiedTime: "100"},
-		},
-		{
-			name:       "missing remote timestamp",
-			ifExists:   drivePullIfExistsSmart,
-			remoteFile: drivePullTarget{ModifiedTime: ""},
-		},
-		{
-			name:       "invalid remote timestamp",
-			ifExists:   drivePullIfExistsSmart,
-			remoteFile: drivePullTarget{ModifiedTime: "not-a-time"},
-		},
-	} {
-		t.Run(tt.name, func(t *testing.T) {
-			if got := drivePullShouldSkipSmart(localPath, tt.remoteFile, tt.ifExists, runtime); got {
-				t.Fatalf("drivePullShouldSkipSmart() = true, want false for %s", tt.name)
-			}
-		})
-	}
-}
-
-func TestDrivePullShouldSkipSmartFallsBackWhenPathCannotBeResolved(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	runtime := common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "test"}, driveTestConfig(), f, core.AsBot)
-
-	if got := drivePullShouldSkipSmart("../escape.txt", drivePullTarget{ModifiedTime: "100"}, drivePullIfExistsSmart, runtime); got {
-		t.Fatal("drivePullShouldSkipSmart() = true, want false when ResolvePath rejects the target")
-	}
-}
-
-func TestDrivePullShouldSkipSmartFallsBackWhenLocalFileDisappeared(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	runtime := common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "test"}, driveTestConfig(), f, core.AsBot)
-
-	if got := drivePullShouldSkipSmart(filepath.Join("local", "missing.txt"), drivePullTarget{ModifiedTime: "100"}, drivePullIfExistsSmart, runtime); got {
-		t.Fatal("drivePullShouldSkipSmart() = true, want false when os.Stat cannot find the local file")
-	}
-}
-
-func TestDrivePullSkipsWhenSmartIgnoresRemoteSize(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	localPath := filepath.Join("local", "keep.txt")
-	if err := os.WriteFile(localPath, []byte("hello"), 0o644); err != nil {
-		t.Fatalf("WriteFile: %v", err)
-	}
-	localMTime := time.Unix(200, 500*int64(time.Millisecond))
-	if err := os.Chtimes(localPath, localMTime, localMTime); err != nil {
-		t.Fatalf("Chtimes: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_keep", "name": "keep.txt", "type": "file", "size": 999, "modified_time": "100"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-
-	err := mountAndRunDrive(t, DrivePull, []string{
-		"+pull",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--if-exists", "smart",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"skipped": 1`) {
-		t.Errorf("expected skipped=1, got: %s", out)
-	}
-	if !strings.Contains(out, `"downloaded": 0`) {
-		t.Errorf("expected downloaded=0, got: %s", out)
-	}
-	mustReadFile(t, localPath, "hello")
-}
-
 // TestDrivePullSurfacesDirectoryFileMirrorConflict pins the contract
 // for the case where Drive ships a regular file at a rel_path that is
 // already a directory locally. SafeOutputPath would refuse to overwrite

shortcuts/drive/drive_push.go

@@ -15,7 +15,6 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
-	"time"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
@@ -26,7 +25,6 @@ import (
 
 const (
 	drivePushIfExistsOverwrite = "overwrite"
-	drivePushIfExistsSmart     = "smart"
 	drivePushIfExistsSkip      = "skip"
 )
 
@@ -93,7 +91,7 @@ var DrivePush = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "local-dir", Desc: "local root directory (relative to cwd)", Required: true},
 		{Name: "folder-token", Desc: "target Drive folder token", Required: true},
-		{Name: "if-exists", Desc: "policy when a Drive file already exists at the same rel_path (skip = never touch existing remote files; smart = skip when remote modified_time already matches or is newer, otherwise fall through to overwrite semantics; overwrite = always replace)", Default: drivePushIfExistsSkip, Enum: []string{drivePushIfExistsOverwrite, drivePushIfExistsSmart, drivePushIfExistsSkip}},
+		{Name: "if-exists", Desc: "policy when a Drive file already exists at the same rel_path (default: skip — safe; opt into overwrite explicitly while the backend version field is rolling out)", Default: drivePushIfExistsSkip, Enum: []string{drivePushIfExistsOverwrite, drivePushIfExistsSkip}},
 		{Name: "on-duplicate-remote", Desc: "policy when multiple remote Drive entries map to the same rel_path", Default: driveDuplicateRemoteFail, Enum: []string{driveDuplicateRemoteFail, driveDuplicateRemoteNewest, driveDuplicateRemoteOldest}},
 		{Name: "delete-remote", Type: "bool", Desc: "delete Drive files absent locally (file-level mirror; remote-only directories are not removed); requires --yes"},
 		{Name: "yes", Type: "bool", Desc: "confirm --delete-remote before deleting Drive files"},
@@ -101,9 +99,8 @@ var DrivePush = common.Shortcut{
 	Tips: []string{
 		"This is a file-level mirror: only type=file entries are uploaded, overwritten or deleted. Online docs (docx, sheet, bitable, mindnote, slides), shortcuts, and remote-only directories are never touched.",
 		"Local directory structure (including empty directories) is mirrored to Drive via create_folder; existing remote folders are reused.",
-		"For repeat syncs, --if-exists=smart is a best-effort incremental mode: it compares local mtime with Drive modified_time and skips uploads when the remote copy is already up to date; otherwise it falls through to the same overwrite path as --if-exists=overwrite.",
 		"Duplicate remote rel_path conflicts fail by default before upload, overwrite, or delete. Use --on-duplicate-remote=newest|oldest only when the conflict is duplicate files and you explicitly want to target one.",
-		"Default --if-exists=skip is the safe choice while the upload_all overwrite-version field is rolling out. Pass --if-exists=overwrite to replace remote bytes; on tenants without the field it surfaces a structured api_error and the run exits non-zero. The same caveat applies when --if-exists=smart decides the remote file is older and falls through to overwrite.",
+		"Default --if-exists=skip is the safe choice while the upload_all overwrite-version field is rolling out. Pass --if-exists=overwrite to replace remote bytes; on tenants without the field it surfaces a structured api_error and the run exits non-zero.",
 		"--delete-remote requires --yes; without --yes the command is rejected upfront so a stray flag never deletes anything.",
 		"--delete-remote --yes also requires the space:document:delete scope. Validate runs a dynamic pre-flight check when the flag is on, so a missing grant fails the run before any upload — preventing a half-synced state where files were uploaded but the cleanup pass cannot delete.",
 		"Item-level failures (upload, overwrite, folder, delete) bump summary.failed and the run exits non-zero. If any upload or folder step fails, the --delete-remote phase is skipped entirely so a partial upload never triggers remote deletion.",
@@ -154,7 +151,7 @@ var DrivePush = common.Shortcut{
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
-			Desc("Walk --local-dir, recursively list --folder-token, then upload new files, skip existing, skip up-to-date files when --if-exists=smart, overwrite when --if-exists=overwrite, and (when --delete-remote --yes is set) delete Drive files absent locally.").
+			Desc("Walk --local-dir, recursively list --folder-token, then upload new files, overwrite (when --if-exists=overwrite) or skip existing, and (when --delete-remote --yes is set) delete Drive files absent locally.").
 			GET("/open-apis/drive/v1/files").
 			Set("folder_token", runtime.Str("folder-token"))
 	},
@@ -270,7 +267,7 @@ var DrivePush = common.Shortcut{
 			localFile := localFiles[rel]
 
 			if entry, ok := remoteFiles[rel]; ok {
-				if drivePushShouldSkipExisting(localFile, entry, ifExists) {
+				if ifExists == drivePushIfExistsSkip {
 					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "skipped", SizeBytes: localFile.Size})
 					skipped++
 					continue
@@ -397,7 +394,6 @@ type drivePushLocalFile struct {
 	OpenPath string
 	FileName string
 	Size     int64
-	ModTime  time.Time
 }
 
 // drivePushWalkLocal walks the canonical absolute root produced by
@@ -454,7 +450,6 @@ func drivePushWalkLocal(root, cwdCanonical string) (map[string]drivePushLocalFil
 			OpenPath: relToCwd,
 			FileName: filepath.Base(rel),
 			Size:     info.Size(),
-			ModTime:  info.ModTime(),
 		}
 		return nil
 	})
@@ -478,30 +473,6 @@ func drivePushWalkLocal(root, cwdCanonical string) (map[string]drivePushLocalFil
 	return files, dirs, nil
 }
 
-func drivePushShouldSkipExisting(localFile drivePushLocalFile, remoteFile driveRemoteEntry, ifExists string) bool {
-	switch ifExists {
-	case drivePushIfExistsSkip:
-		return true
-	case drivePushIfExistsSmart:
-		return drivePushShouldSkipSmart(localFile, remoteFile)
-	default:
-		return false
-	}
-}
-
-func drivePushShouldSkipSmart(localFile drivePushLocalFile, remoteFile driveRemoteEntry) bool {
-	cmp, ok := compareDriveRemoteModifiedToLocal(remoteFile.ModifiedTime, localFile.ModTime)
-	if !ok {
-		// Smart mode is an optimization. If the timestamp is missing or
-		// malformed, fall back to the safe transfer path instead of silently
-		// skipping an update we could not compare.
-		return false
-	}
-	// Remote is already at least as new as the local file, so another
-	// upload would be redundant.
-	return cmp >= 0
-}
-
 func drivePushRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (map[string]driveRemoteEntry, map[string]driveRemoteEntry, map[string][]driveRemoteEntry, error) {
 	remoteFiles := make(map[string]driveRemoteEntry, len(entries))
 	remoteFolders := make(map[string]driveRemoteEntry, len(entries))

shortcuts/drive/drive_push_test.go

@@ -12,7 +12,6 @@ import (
 	"strings"
 	"sync/atomic"
 	"testing"
-	"time"
 
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -325,203 +324,6 @@ func TestDrivePushSkipsWhenIfExistsSkip(t *testing.T) {
 	// would 404 against the registry and the run would have errored above.
 }
 
-// TestDrivePushSkipsWhenIfExistsSmartAndRemoteIsUpToDate verifies the smart
-// fast path for local → Drive mirrors: when the remote copy is already at
-// least as new as the local file, +push skips the upload.
-func TestDrivePushSkipsWhenIfExistsSmartAndRemoteIsUpToDate(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	localPath := filepath.Join("local", "keep.txt")
-	if err := os.WriteFile(localPath, []byte("hello"), 0o644); err != nil {
-		t.Fatalf("WriteFile: %v", err)
-	}
-	localMTime := time.Unix(100, 500*int64(time.Millisecond))
-	if err := os.Chtimes(localPath, localMTime, localMTime); err != nil {
-		t.Fatalf("Chtimes: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_keep", "name": "keep.txt", "type": "file", "size": 5, "modified_time": "200"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-
-	// Intentionally NO upload_all stub: smart mode should skip the transfer.
-	err := mountAndRunDrive(t, DrivePush, []string{
-		"+push",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--if-exists", "smart",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"skipped": 1`) {
-		t.Errorf("expected skipped=1, got: %s", out)
-	}
-	if !strings.Contains(out, `"uploaded": 0`) {
-		t.Errorf("expected uploaded=0, got: %s", out)
-	}
-}
-
-// TestDrivePushOverwritesWhenIfExistsSmartAndLocalIsNewer verifies the smart
-// path still uploads when the local file is newer than the remote one.
-func TestDrivePushOverwritesWhenIfExistsSmartAndLocalIsNewer(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	localPath := filepath.Join("local", "keep.txt")
-	if err := os.WriteFile(localPath, []byte("hello"), 0o644); err != nil {
-		t.Fatalf("WriteFile: %v", err)
-	}
-	localMTime := time.Unix(200, 500*int64(time.Millisecond))
-	if err := os.Chtimes(localPath, localMTime, localMTime); err != nil {
-		t.Fatalf("Chtimes: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_keep_old", "name": "keep.txt", "type": "file", "size": 5, "modified_time": "100"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-	uploadStub := &httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/files/upload_all",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{"file_token": "tok_keep_new", "version": "v43"},
-		},
-	}
-	reg.Register(uploadStub)
-
-	err := mountAndRunDrive(t, DrivePush, []string{
-		"+push",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--if-exists", "smart",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"uploaded": 1`) {
-		t.Errorf("expected uploaded=1, got: %s", out)
-	}
-	if !strings.Contains(out, `"action": "overwritten"`) {
-		t.Errorf("expected overwritten action, got: %s", out)
-	}
-	body := decodeDriveMultipartBody(t, uploadStub)
-	if got := body.Fields["file_token"]; got != "tok_keep_old" {
-		t.Fatalf("upload_all form file_token = %q, want tok_keep_old", got)
-	}
-}
-
-func TestDrivePushShouldSkipSmartFallsBackWhenMetadataCannotBeTrusted(t *testing.T) {
-	t.Parallel()
-
-	localFile := drivePushLocalFile{
-		Size:    5,
-		ModTime: time.Unix(100, 500*int64(time.Millisecond)),
-	}
-
-	for _, tt := range []struct {
-		name       string
-		remoteFile driveRemoteEntry
-	}{
-		{
-			name:       "invalid remote timestamp",
-			remoteFile: driveRemoteEntry{ModifiedTime: "not-a-time"},
-		},
-	} {
-		t.Run(tt.name, func(t *testing.T) {
-			if got := drivePushShouldSkipSmart(localFile, tt.remoteFile); got {
-				t.Fatalf("drivePushShouldSkipSmart() = true, want false for %s", tt.name)
-			}
-		})
-	}
-}
-
-func TestDrivePushSkipsWhenSmartIgnoresRemoteSize(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	localPath := filepath.Join("local", "keep.txt")
-	if err := os.WriteFile(localPath, []byte("hello"), 0o644); err != nil {
-		t.Fatalf("WriteFile: %v", err)
-	}
-	localMTime := time.Unix(100, 500*int64(time.Millisecond))
-	if err := os.Chtimes(localPath, localMTime, localMTime); err != nil {
-		t.Fatalf("Chtimes: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_keep", "name": "keep.txt", "type": "file", "size": 999, "modified_time": "200"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-
-	err := mountAndRunDrive(t, DrivePush, []string{
-		"+push",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--if-exists", "smart",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"skipped": 1`) {
-		t.Errorf("expected skipped=1, got: %s", out)
-	}
-	if !strings.Contains(out, `"uploaded": 0`) {
-		t.Errorf("expected uploaded=0, got: %s", out)
-	}
-}
-
 // TestDrivePushDeleteRemoteRequiresYes locks in the upfront safety guard:
 // --delete-remote without --yes must be refused before any list / upload
 // happens, so a stray flag never silently deletes anything.

shortcuts/drive/drive_status.go

@@ -13,7 +13,6 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
-	"time"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
@@ -27,24 +26,8 @@ type driveStatusEntry struct {
 	FileToken string `json:"file_token,omitempty"`
 }
 
-type driveStatusLocalFile struct {
-	PathToCwd string
-	ModTime   time.Time
-}
-
-type driveStatusRemoteFile struct {
-	FileToken    string
-	ModifiedTime string
-}
-
-const (
-	driveStatusDetectionExact = "exact"
-	driveStatusDetectionQuick = "quick"
-)
-
 // DriveStatus walks --local-dir, recursively lists --folder-token, and reports
-// four buckets (new_local, new_remote, modified, unchanged) either by exact
-// SHA-256 hash (default) or by a quick modified_time comparison (--quick).
+// four buckets (new_local, new_remote, modified, unchanged) by SHA-256 hash.
 //
 // Only Drive entries with type=file are compared; online docs (docx, sheet,
 // bitable, mindnote, slides) and shortcuts are skipped because there is no
@@ -56,19 +39,17 @@ const (
 var DriveStatus = common.Shortcut{
 	Service:     "drive",
 	Command:     "+status",
-	Description: "Compare a local directory with a Drive folder by exact hash or quick modified_time",
+	Description: "Compare a local directory with a Drive folder by content hash",
 	Risk:        "read",
 	Scopes:      []string{"drive:drive.metadata:readonly", "drive:file:download"},
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "local-dir", Desc: "local root directory (relative to cwd)", Required: true},
 		{Name: "folder-token", Desc: "Drive folder token", Required: true},
-		{Name: "quick", Type: "bool", Desc: "compare modified_time only and skip remote downloads for files present on both sides"},
 	},
 	Tips: []string{
 		"Only entries with type=file are compared; online docs (docx, sheet, bitable, mindnote, slides) and shortcuts are skipped.",
-		"Default detection=exact downloads files present on both sides and SHA-256 hashes them in memory; expect noticeable I/O on large folders.",
-		"Pass --quick for the recommended fast preflight mode: it compares local mtime with Drive modified_time, skips remote downloads, and reports detection=quick as a best-effort diff.",
+		"Files present on both sides are downloaded and SHA-256 hashed in memory to decide modified vs unchanged; expect noticeable I/O on large folders.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		localDir := strings.TrimSpace(runtime.Str("local-dir"))
@@ -99,22 +80,14 @@ var DriveStatus = common.Shortcut{
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		desc := "Walk --local-dir, recursively list --folder-token, and download files present on both sides to compare SHA-256."
-		if runtime.Bool("quick") {
-			desc = "Walk --local-dir, recursively list --folder-token, and compare local mtime with Drive modified_time for files present on both sides without downloading remote bytes."
-		}
 		return common.NewDryRunAPI().
-			Desc(desc).
+			Desc("Walk --local-dir, recursively list --folder-token, and download files present on both sides to compare SHA-256.").
 			GET("/open-apis/drive/v1/files").
 			Set("folder_token", runtime.Str("folder-token"))
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		localDir := strings.TrimSpace(runtime.Str("local-dir"))
 		folderToken := strings.TrimSpace(runtime.Str("folder-token"))
-		detection := driveStatusDetectionExact
-		if runtime.Bool("quick") {
-			detection = driveStatusDetectionQuick
-		}
 
 		// Resolve --local-dir to its canonical absolute path before walking.
 		// SafeInputPath fully evaluates symlinks across the entire path,
@@ -139,7 +112,7 @@ var DriveStatus = common.Shortcut{
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Walking local: %s\n", localDir)
-		localFiles, err := walkLocalForStatus(safeRoot, cwdCanonical)
+		localHashes, err := walkLocalForStatus(runtime, safeRoot, cwdCanonical)
 		if err != nil {
 			return err
 		}
@@ -157,42 +130,30 @@ var DriveStatus = common.Shortcut{
 		// hashable bytes and are intentionally absent from the diff
 		// view (a docx living next to a same-named local file is a
 		// known no-op).
-		remoteFiles := make(map[string]driveStatusRemoteFile, len(entries))
+		remoteFiles := make(map[string]string, len(entries))
 		for _, entry := range entries {
 			if entry.Type == driveTypeFile {
-				remoteFiles[entry.RelPath] = driveStatusRemoteFile{FileToken: entry.FileToken, ModifiedTime: entry.ModifiedTime}
+				remoteFiles[entry.RelPath] = entry.FileToken
 			}
 		}
 
-		paths := mergeStatusPaths(localFiles, remoteFiles)
+		paths := mergeStatusPaths(localHashes, remoteFiles)
 
 		var newLocal, newRemote, modified, unchanged []driveStatusEntry
 		for _, relPath := range paths {
-			localFile, hasLocal := localFiles[relPath]
-			remoteFile, hasRemote := remoteFiles[relPath]
+			localHash, hasLocal := localHashes[relPath]
+			remoteToken, hasRemote := remoteFiles[relPath]
 			switch {
 			case hasLocal && !hasRemote:
 				newLocal = append(newLocal, driveStatusEntry{RelPath: relPath})
 			case !hasLocal && hasRemote:
-				newRemote = append(newRemote, driveStatusEntry{RelPath: relPath, FileToken: remoteFile.FileToken})
+				newRemote = append(newRemote, driveStatusEntry{RelPath: relPath, FileToken: remoteToken})
 			default:
-				entry := driveStatusEntry{RelPath: relPath, FileToken: remoteFile.FileToken}
-				if detection == driveStatusDetectionQuick {
-					if driveStatusShouldTreatAsUnchangedQuick(remoteFile.ModifiedTime, localFile.ModTime) {
-						unchanged = append(unchanged, entry)
-					} else {
-						modified = append(modified, entry)
-					}
-					continue
-				}
-				localHash, err := hashLocalForStatus(runtime, localFile.PathToCwd)
-				if err != nil {
-					return err
-				}
-				remoteHash, err := hashRemoteForStatus(ctx, runtime, remoteFile.FileToken)
+				remoteHash, err := hashRemoteForStatus(ctx, runtime, remoteToken)
 				if err != nil {
 					return err
 				}
+				entry := driveStatusEntry{RelPath: relPath, FileToken: remoteToken}
 				if localHash == remoteHash {
 					unchanged = append(unchanged, entry)
 				} else {
@@ -202,7 +163,6 @@ var DriveStatus = common.Shortcut{
 		}
 
 		runtime.Out(map[string]interface{}{
-			"detection":  detection,
 			"new_local":  emptyIfNil(newLocal),
 			"new_remote": emptyIfNil(newRemote),
 			"modified":   emptyIfNil(modified),
@@ -220,8 +180,8 @@ var DriveStatus = common.Shortcut{
 // hit, we report rel_path relative to root for the JSON output, and
 // convert the absolute path to a cwd-relative form so FileIO.Open's
 // SafeInputPath check (which rejects absolute paths) still applies.
-func walkLocalForStatus(root, cwdCanonical string) (map[string]driveStatusLocalFile, error) {
-	files := make(map[string]driveStatusLocalFile)
+func walkLocalForStatus(runtime *common.RuntimeContext, root, cwdCanonical string) (map[string]string, error) {
+	files := make(map[string]string)
 	// FileIO has no walker today and shortcuts can't import internal/vfs.
 	// The walk root is the canonical absolute path returned by
 	// validate.SafeInputPath, so it is no longer a symlink itself, and
@@ -242,11 +202,11 @@ func walkLocalForStatus(root, cwdCanonical string) (map[string]driveStatusLocalF
 		if err != nil {
 			return err
 		}
-		info, err := d.Info()
+		sum, err := hashLocalForStatus(runtime, relToCwd)
 		if err != nil {
 			return err
 		}
-		files[filepath.ToSlash(rel)] = driveStatusLocalFile{PathToCwd: relToCwd, ModTime: info.ModTime()}
+		files[filepath.ToSlash(rel)] = sum
 		return nil
 	})
 	if err != nil {
@@ -255,11 +215,6 @@ func walkLocalForStatus(root, cwdCanonical string) (map[string]driveStatusLocalF
 	return files, nil
 }
 
-func driveStatusShouldTreatAsUnchangedQuick(remoteModified string, local time.Time) bool {
-	cmp, ok := compareDriveRemoteModifiedToLocal(remoteModified, local)
-	return ok && cmp == 0
-}
-
 func hashLocalForStatus(runtime *common.RuntimeContext, path string) (string, error) {
 	f, err := runtime.FileIO().Open(path)
 	if err != nil {
@@ -289,7 +244,7 @@ func hashRemoteForStatus(ctx context.Context, runtime *common.RuntimeContext, fi
 	return hex.EncodeToString(h.Sum(nil)), nil
 }
 
-func mergeStatusPaths(local map[string]driveStatusLocalFile, remote map[string]driveStatusRemoteFile) []string {
+func mergeStatusPaths(local, remote map[string]string) []string {
 	seen := make(map[string]struct{}, len(local)+len(remote))
 	for p := range local {
 		seen[p] = struct{}{}

shortcuts/drive/drive_status_test.go

@@ -9,7 +9,6 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -106,9 +105,6 @@ func TestDriveStatusCategorizesByHash(t *testing.T) {
 	}
 
 	out := stdout.String()
-	if !strings.Contains(out, `"detection": "exact"`) {
-		t.Fatalf("output missing detection=exact\noutput: %s", out)
-	}
 	checks := []struct {
 		bucket string
 		path   string
@@ -138,152 +134,6 @@ func TestDriveStatusCategorizesByHash(t *testing.T) {
 	reg.Verify(t)
 }
 
-func TestDriveStatusQuickCategorizesByModifiedTimeWithoutDownloads(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-
-	if err := os.MkdirAll("local/sub", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	if err := os.WriteFile("local/a.txt", []byte("local-a"), 0o644); err != nil {
-		t.Fatalf("WriteFile a.txt: %v", err)
-	}
-	if err := os.WriteFile("local/b.txt", []byte("local-b"), 0o644); err != nil {
-		t.Fatalf("WriteFile b.txt: %v", err)
-	}
-	if err := os.WriteFile("local/sub/c.txt", []byte("local-c"), 0o644); err != nil {
-		t.Fatalf("WriteFile sub/c.txt: %v", err)
-	}
-
-	matchTime := time.Unix(1715594880, 0)
-	changedTime := time.Unix(1715594940, 0)
-	if err := os.Chtimes("local/a.txt", matchTime, matchTime); err != nil {
-		t.Fatalf("Chtimes a.txt: %v", err)
-	}
-	if err := os.Chtimes("local/sub/c.txt", changedTime, changedTime); err != nil {
-		t.Fatalf("Chtimes sub/c.txt: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_a", "name": "a.txt", "type": "file", "modified_time": "1715594880"},
-					map[string]interface{}{"token": "tok_sub", "name": "sub", "type": "folder"},
-					map[string]interface{}{"token": "tok_d", "name": "d.txt", "type": "file", "modified_time": "1715595000"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=tok_sub",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_c", "name": "c.txt", "type": "file", "modified_time": "1715594880"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-
-	err := mountAndRunDrive(t, DriveStatus, []string{
-		"+status",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--quick",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"detection": "quick"`) {
-		t.Fatalf("output missing detection=quick\noutput: %s", out)
-	}
-	checks := []struct {
-		bucket string
-		path   string
-		token  string
-	}{
-		{"new_local", "b.txt", ""},
-		{"new_remote", "d.txt", "tok_d"},
-		{"modified", "sub/c.txt", "tok_c"},
-		{"unchanged", "a.txt", "tok_a"},
-	}
-	for _, c := range checks {
-		if !strings.Contains(out, `"`+c.bucket+`":`) {
-			t.Errorf("output missing bucket %q\noutput: %s", c.bucket, out)
-		}
-		if !strings.Contains(out, `"rel_path": "`+c.path+`"`) {
-			t.Errorf("output missing rel_path %q (expected in %s)\noutput: %s", c.path, c.bucket, out)
-		}
-		if c.token != "" && !strings.Contains(out, `"file_token": "`+c.token+`"`) {
-			t.Errorf("output missing file_token %q (expected in %s)\noutput: %s", c.token, c.bucket, out)
-		}
-	}
-
-	reg.Verify(t)
-}
-
-func TestDriveStatusQuickMarksUntrustedTimestampAsModified(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-
-	tmpDir := t.TempDir()
-	withDriveWorkingDir(t, tmpDir)
-
-	if err := os.MkdirAll("local", 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-	if err := os.WriteFile("local/a.txt", []byte("local"), 0o644); err != nil {
-		t.Fatalf("WriteFile a.txt: %v", err)
-	}
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_a", "name": "a.txt", "type": "file", "modified_time": "not-a-timestamp"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-
-	err := mountAndRunDrive(t, DriveStatus, []string{
-		"+status",
-		"--local-dir", "local",
-		"--folder-token", "folder_root",
-		"--quick",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, `"detection": "quick"`) {
-		t.Fatalf("output missing detection=quick\noutput: %s", out)
-	}
-	if !strings.Contains(out, `"modified":`) || !strings.Contains(out, `"rel_path": "a.txt"`) {
-		t.Fatalf("invalid remote modified_time must fall back to modified\noutput: %s", out)
-	}
-
-	reg.Verify(t)
-}
-
 // TestDriveStatusPaginatesRemoteListing pins multi-page handling end-to-end
 // AND the dual-field tolerance of common.PaginationMeta. Page 1 surfaces
 // `next_page_token` (Drive's historical name); page 2 surfaces `page_token`

shortcuts/drive/list_remote.go

@@ -11,7 +11,6 @@ import (
 	"path"
 	"sort"
 	"strconv"
-	"time"
 
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -196,9 +195,6 @@ const (
 	driveDuplicateRemoteOldest = "oldest"
 )
 
-// sortRemoteFiles orders duplicate Drive files according to the conflict
-// strategy, using parsed Drive timestamps so mixed second/millisecond/
-// microsecond epochs compare by actual time rather than raw integer width.
 func sortRemoteFiles(files []driveRemoteEntry, strategy string) {
 	sort.SliceStable(files, func(i, j int) bool {
 		a, b := files[i], files[j]
@@ -230,61 +226,16 @@ func sortRemoteFiles(files []driveRemoteEntry, strategy string) {
 	})
 }
 
-// compareDriveTimes compares two Drive epoch strings after normalizing their
-// unit (seconds, milliseconds, or microseconds) into time.Time values.
 func compareDriveTimes(a, b string) (int, bool) {
-	at, _, aOK := parseDriveEpoch(a)
-	bt, _, bOK := parseDriveEpoch(b)
-	if !aOK || !bOK {
+	av, aErr := strconv.ParseInt(a, 10, 64)
+	bv, bErr := strconv.ParseInt(b, 10, 64)
+	if aErr != nil || bErr != nil {
 		return 0, false
 	}
 	switch {
-	case at.Before(bt):
+	case av < bv:
 		return -1, true
-	case at.After(bt):
-		return 1, true
-	default:
-		return 0, true
-	}
-}
-
-func parseDriveEpoch(raw string) (time.Time, time.Duration, bool) {
-	v, err := strconv.ParseInt(raw, 10, 64)
-	if err != nil {
-		return time.Time{}, 0, false
-	}
-	// Drive timestamps are epoch strings. The API currently returns
-	// milliseconds, but tests and older payloads may still use seconds.
-	// Infer the unit conservatively from magnitude and compare local mtimes
-	// at the same resolution so sub-second filesystem noise does not force
-	// a transfer in smart mode.
-	switch {
-	case v > 1e14 || v < -1e14:
-		return time.UnixMicro(v), time.Microsecond, true
-	case v > 1e11 || v < -1e11:
-		return time.UnixMilli(v), time.Millisecond, true
-	default:
-		return time.Unix(v, 0), time.Second, true
-	}
-}
-
-// compareDriveRemoteModifiedToLocal compares one Drive modified_time string to a
-// local file mtime.
-//   - returns -1 when remote < local
-//   - returns  0 when remote == local at the remote timestamp resolution
-//   - returns  1 when remote > local
-//
-// The bool reports whether the remote timestamp was parseable.
-func compareDriveRemoteModifiedToLocal(remoteModified string, local time.Time) (int, bool) {
-	remoteTime, resolution, ok := parseDriveEpoch(remoteModified)
-	if !ok {
-		return 0, false
-	}
-	localAtRemoteResolution := local.Truncate(resolution)
-	switch {
-	case remoteTime.Before(localAtRemoteResolution):
-		return -1, true
-	case remoteTime.After(localAtRemoteResolution):
+	case av > bv:
 		return 1, true
 	default:
 		return 0, true

shortcuts/im/builders_test.go

@@ -15,7 +15,6 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// mustMarshalDryRun marshals v to a JSON string, calling t.Fatalf on error.
 func mustMarshalDryRun(t *testing.T, v interface{}) string {
 	t.Helper()
 
@@ -26,9 +25,6 @@ func mustMarshalDryRun(t *testing.T, v interface{}) string {
 	return string(b)
 }
 
-// newTestRuntimeContext builds a *common.RuntimeContext backed by a cobra
-// command whose flags are populated from the provided string and bool maps,
-// for unit-testing shortcut bodies, validators, and dry-run shapes.
 func newTestRuntimeContext(t *testing.T, stringFlags map[string]string, boolFlags map[string]bool) *common.RuntimeContext {
 	t.Helper()
 
@@ -59,9 +55,6 @@ func newTestRuntimeContext(t *testing.T, stringFlags map[string]string, boolFlag
 	return &common.RuntimeContext{Cmd: cmd}
 }
 
-// newMessagesSearchTestRuntimeContext is the messages-search variant of
-// newTestRuntimeContext: registers the search-specific --page-size flag
-// before applying caller-provided values.
 func newMessagesSearchTestRuntimeContext(t *testing.T, stringFlags map[string]string, boolFlags map[string]bool) *common.RuntimeContext {
 	t.Helper()
 
@@ -93,8 +86,6 @@ func newMessagesSearchTestRuntimeContext(t *testing.T, stringFlags map[string]st
 	return &common.RuntimeContext{Cmd: cmd}
 }
 
-// TestBuildCreateChatBody verifies the request body assembled when every
-// flag is populated, including the default chat_mode="group".
 func TestBuildCreateChatBody(t *testing.T) {
 	runtime := newTestRuntimeContext(t, map[string]string{
 		"type":        "public",
@@ -103,13 +94,11 @@ func TestBuildCreateChatBody(t *testing.T) {
 		"users":       "ou_1, ou_2",
 		"bots":        "cli_1, cli_2",
 		"owner":       "ou_owner",
-		"chat-mode":   "group",
 	}, nil)
 
 	got := buildCreateChatBody(runtime)
 	want := map[string]interface{}{
 		"chat_type":   "public",
-		"chat_mode":   "group",
 		"name":        "Team Chat",
 		"description": "daily sync",
 		"user_id_list": []string{
@@ -127,43 +116,6 @@ func TestBuildCreateChatBody(t *testing.T) {
 	}
 }
 
-// TestBuildCreateChatBody_TopicMode verifies that --chat-mode topic produces
-// chat_mode="topic" in the request body, the topic-chat creation path.
-func TestBuildCreateChatBody_TopicMode(t *testing.T) {
-	runtime := newTestRuntimeContext(t, map[string]string{
-		"type":      "public",
-		"name":      "Topic Group",
-		"chat-mode": "topic",
-	}, nil)
-
-	got := buildCreateChatBody(runtime)
-	want := map[string]interface{}{
-		"chat_type": "public",
-		"chat_mode": "topic",
-		"name":      "Topic Group",
-	}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("buildCreateChatBody() = %#v, want %#v", got, want)
-	}
-}
-
-// TestBuildCreateChatBody_EmptyChatModeFallsBack pins the defensive fallback:
-// explicit `--chat-mode ""` slips past validateEnumFlags (which skips empty
-// values), but buildCreateChatBody must still emit chat_mode="group" rather
-// than an empty string with unspecified server semantics.
-func TestBuildCreateChatBody_EmptyChatModeFallsBack(t *testing.T) {
-	runtime := newTestRuntimeContext(t, map[string]string{
-		"type":      "public",
-		"name":      "Fallback Test",
-		"chat-mode": "",
-	}, nil)
-
-	got := buildCreateChatBody(runtime)
-	if got["chat_mode"] != "group" {
-		t.Fatalf("buildCreateChatBody() chat_mode = %#v, want \"group\"", got["chat_mode"])
-	}
-}
-
 // TestSplitMembers verifies the delegation wrapper; core logic is tested in TestSplitCSV. [#17]
 func TestSplitMembers(t *testing.T) {
 	got := common.SplitCSV(" ou_1, ,ou_2 ,, ou_3 ")
@@ -639,12 +591,10 @@ func TestMessagesSearchPaginationConfig(t *testing.T) {
 	})
 }
 
-// TestShortcutDryRunShapes verifies that each shortcut's DryRun function
-// produces the expected API path, query parameters, and request body.
 func TestShortcutDryRunShapes(t *testing.T) {
 	t.Run("ImChatCreate dry run includes params and body", func(t *testing.T) {
 		cmd := &cobra.Command{Use: "test"}
-		for _, name := range []string{"type", "name", "users", "owner", "chat-mode"} {
+		for _, name := range []string{"type", "name", "users", "owner"} {
 			cmd.Flags().String(name, "", "")
 		}
 		cmd.Flags().Bool("set-bot-manager", false, "")
@@ -654,10 +604,9 @@ func TestShortcutDryRunShapes(t *testing.T) {
 		_ = cmd.Flags().Set("users", "ou_1,ou_2")
 		_ = cmd.Flags().Set("owner", "ou_owner")
 		_ = cmd.Flags().Set("set-bot-manager", "true")
-		_ = cmd.Flags().Set("chat-mode", "group")
 		runtime := common.TestNewRuntimeContextWithIdentity(cmd, nil, "bot")
 		got := mustMarshalDryRun(t, ImChatCreate.DryRun(context.Background(), runtime))
-		if !strings.Contains(got, `"/open-apis/im/v1/chats"`) || !strings.Contains(got, `"set_bot_manager":true`) || !strings.Contains(got, `"chat_type":"public"`) || !strings.Contains(got, `"chat_mode":"group"`) {
+		if !strings.Contains(got, `"/open-apis/im/v1/chats"`) || !strings.Contains(got, `"set_bot_manager":true`) || !strings.Contains(got, `"chat_type":"public"`) {
 			t.Fatalf("ImChatCreate.DryRun() = %s", got)
 		}
 	})

shortcuts/im/im_chat_create.go

@@ -16,14 +16,10 @@ import (
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
 
-// ImChatCreate is the +chat-create shortcut: creates a group chat or topic
-// chat via POST /open-apis/im/v1/chats. Supports user and bot identities;
-// --chat-mode selects group (default) or topic; --type selects private
-// (default) or public; --users/--bots invite members at creation.
 var ImChatCreate = common.Shortcut{
 	Service:     "im",
 	Command:     "+chat-create",
-	Description: "Create a group chat or topic chat; user/bot; --chat-mode group|topic; private/public; invites users/bots; optionally sets bot manager",
+	Description: "Create a group chat; user/bot; creates private/public chats, invites users/bots, optionally sets bot manager",
 	Risk:        "write",
 	UserScopes:  []string{"im:chat:create_by_user"},
 	BotScopes:   []string{"im:chat:create"},
@@ -36,7 +32,6 @@ var ImChatCreate = common.Shortcut{
 		{Name: "bots", Desc: "comma-separated bot app IDs (cli_xxx) to invite, max 5"},
 		{Name: "owner", Desc: "owner open_id (ou_xxx); defaults to bot (--as bot) or authorized user (--as user)"},
 		{Name: "type", Default: "private", Desc: "chat type", Enum: []string{"private", "public"}},
-		{Name: "chat-mode", Default: "group", Desc: "group mode (\"topic\" creates a topic chat; differs from a normal group in topic-message mode)", Enum: []string{"group", "topic"}},
 		{Name: "set-bot-manager", Type: "bool", Desc: "set the bot that creates this chat as manager (bot identity only)"},
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -146,18 +141,9 @@ var ImChatCreate = common.Shortcut{
 	},
 }
 
-// buildCreateChatBody assembles the POST /open-apis/im/v1/chats request
-// body. chat_mode is always emitted; an empty value (which can slip past
-// validateEnumFlags, since that helper skips empty strings) is pinned to
-// "group" so the wire never carries an unspecified chat_mode value.
 func buildCreateChatBody(runtime *common.RuntimeContext) map[string]interface{} {
-	chatMode := runtime.Str("chat-mode")
-	if chatMode == "" {
-		chatMode = "group"
-	}
 	body := map[string]interface{}{
 		"chat_type": runtime.Str("type"),
-		"chat_mode": chatMode,
 	}
 	if name := runtime.Str("name"); name != "" {
 		body["name"] = name

skills/lark-drive/SKILL.md

@@ -229,8 +229,8 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+upload`](references/lark-drive-upload.md) | Upload a local file to a Drive folder or wiki node |
 | [`+create-folder`](references/lark-drive-create-folder.md) | Create a Drive folder, optionally under a parent folder, with bot auto-grant support |
 | [`+download`](references/lark-drive-download.md) | Download a file from Drive to local |
-| [`+status`](references/lark-drive-status.md) | Compare a local directory with a Drive folder by exact SHA-256 hash by default, or use `--quick` for a best-effort modified-time diff that skips remote downloads; reports `new_local` / `new_remote` / `modified` / `unchanged` plus `detection=exact|quick`. Duplicate remote `rel_path` conflicts fail fast with `error.type=duplicate_remote_path` and list every conflicting entry; do not proceed as if one was chosen. `--local-dir` 必须是 cwd 内的相对路径，越界路径 CLI 会直接拒绝；目标在 cwd 外时引导用户切换 agent 工作目录，不要私自 `cd` 绕过。 |
-| [`+pull`](references/lark-drive-pull.md) | File-level Drive → local mirror. Duplicate remote `rel_path` conflicts fail by default; for duplicate files, `rename` downloads all copies with stable hashed suffixes, while `newest` / `oldest` pick one. `--if-exists` supports `overwrite` / `smart` / `skip` (`smart` is a best-effort modified-time incremental mode for repeat syncs). `--delete-local` requires `--yes`, only removes regular files, and is skipped after item failures. `--local-dir` must stay inside cwd. |
+| [`+status`](references/lark-drive-status.md) | Compare a local directory with a Drive folder by SHA-256 content hash; reports `new_local` / `new_remote` / `modified` / `unchanged` (read-only diff primitive for sync workflows). Duplicate remote `rel_path` conflicts fail fast with `error.type=duplicate_remote_path` and list every conflicting entry; do not proceed as if one was chosen. `--local-dir` 必须是 cwd 内的相对路径，越界路径 CLI 会直接拒绝；目标在 cwd 外时引导用户切换 agent 工作目录，不要私自 `cd` 绕过。 |
+| [`+pull`](references/lark-drive-pull.md) | One-way **file-level** mirror of a Drive folder onto a local directory (Drive → local). Duplicate remote `rel_path` conflicts fail by default before writing; for duplicate files only, `--on-duplicate-remote rename` downloads all copies with stable hashed suffixes, while `newest` / `oldest` explicitly choose one. Supports `--if-exists` (overwrite/skip) and `--delete-local` for orphan cleanup; the destructive `--delete-local` requires `--yes` and only unlinks regular files — empty local directories left behind by remote folder deletes are NOT pruned. Item-level failures exit non-zero (`error.type=partial_failure`) and skip the `--delete-local` pass to avoid half-synced state. `--local-dir` is bounded to cwd by CLI path validation; tell the user to switch the agent's working directory if the target is outside cwd. |
 | [`+create-shortcut`](references/lark-drive-create-shortcut.md) | Create a shortcut to an existing Drive file in another folder |
 | [`+add-comment`](references/lark-drive-add-comment.md) | Add a comment to doc/docx/sheet/slides, also supports wiki URL resolving to doc/docx/sheet/slides |
 | [`+export`](references/lark-drive-export.md) | Export a doc/docx/sheet/bitable to a local file with limited polling; supports `--file-name` for local naming |
@@ -238,7 +238,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+import`](references/lark-drive-import.md) | Import a local file to Drive as a cloud document (docx, sheet, bitable) |
 | [`+move`](references/lark-drive-move.md) | Move a file or folder to another location in Drive |
 | [`+delete`](references/lark-drive-delete.md) | Delete a Drive file or folder with limited polling for folder deletes |
-| [`+push`](references/lark-drive-push.md) | File-level local → Drive mirror. Duplicate remote `rel_path` conflicts fail by default; `newest` / `oldest` only apply to duplicate files when you explicitly want to target one remote file. `--if-exists` supports `skip` / `smart` / `overwrite` (`smart` skips files whose remote `modified_time` is already up to date, but falls through to the same overwrite path when the remote is older, so it inherits overwrite's rollout caveat). `--delete-remote` requires `--yes`. `--local-dir` must stay inside cwd. |
+| [`+push`](references/lark-drive-push.md) | Mirror a local directory onto a Drive folder (local → Drive). Duplicate remote `rel_path` conflicts fail by default before upload / overwrite / delete; use `--on-duplicate-remote newest\|oldest` only when the conflict is duplicate files and you explicitly want to target one existing remote file. Supports `--if-exists` (overwrite/skip) and `--delete-remote` for one-way mirror sync; the destructive `--delete-remote` requires `--yes`. `--local-dir` is bounded to cwd by CLI path validation; tell the user to switch the agent's working directory if the source is outside cwd. |
 | [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations |
 | [`+apply-permission`](references/lark-drive-apply-permission.md) | Apply to the document owner for view/edit access (user-only; 5/day per document) |
 

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

@@ -12,7 +12,7 @@
 | 字段 | 含义 |
 |------|------|
 | `summary.downloaded` | 成功下载的文件数 |
-| `summary.skipped` | 因 `--if-exists=skip` 或 `--if-exists=smart` 命中“无需下载”而跳过的文件数 |
+| `summary.skipped` | 按 `--if-exists=skip` 跳过的文件数 |
 | `summary.failed` | 下载或写盘失败的文件数 |
 | `summary.deleted_local` | 启用 `--delete-local --yes` 时删除的本地文件数 |
 | `items[]` | 每个文件的明细（`rel_path` / `file_token` / `source_id` / `action` / 失败时的 `error`） |
@@ -38,10 +38,6 @@
 # 基础用法 —— 把云端 fldcXXX 镜像到 ./repo
 lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx
 
-# 推荐的重复同步用法：smart 会按 modified_time 跳过已经对齐的本地文件
-lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
-  --if-exists smart
-
 # 已存在的本地文件保持不动
 lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
   --if-exists skip
@@ -62,7 +58,7 @@ lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 |------|------|------|------|
 | `--local-dir` | 是 | path | 本地根目录（**必须是 cwd 的相对路径**；绝对路径或逃出 cwd 的相对路径会被 CLI 直接拒绝） |
 | `--folder-token` | 是 | string | 源 Drive 文件夹 token |
-| `--if-exists` | 否 | enum | 本地文件已存在时的策略：`overwrite`（**默认**，Drive 作为权威源时使用）/ `smart`（**推荐用于重复增量同步**；当本地 mtime 已与远端 `modified_time` 匹配或更新时跳过下载）/ `skip` |
+| `--if-exists` | 否 | enum | 本地文件已存在时的策略：`overwrite`（默认）/ `skip` |
 | `--on-duplicate-remote` | 否 | enum | 云端多个条目映射到同一个 `rel_path` 时的策略：`fail`（默认）；如果冲突全是 `type=file`，还可选 `rename` / `newest` / `oldest` |
 | `--delete-local` | 否 | bool | 删除本地"云端没有的常规文件"（**不删空目录**，因此是 file-level mirror）；**必须配合 `--yes`** |
 | `--yes` | 否 | bool | 确认 `--delete-local`；不传时该破坏性操作在 Validate 阶段被拒绝 |
@@ -71,7 +67,7 @@ lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 
 - **只下载 Drive `type=file` 的二进制文件**。在线文档（`docx` / `sheet` / `bitable` / `mindnote` / `slides`）和快捷方式（`shortcut`）会被跳过 —— 它们没有等价的本地二进制可写盘，否则会变成产生噪声的"假"下载。
 - 子文件夹会递归遍历；rel_path 形如 `sub1/sub2/file.txt`，本地缺失的父目录会被自动创建。
-- 已存在的本地文件按 `--if-exists` 决定 `overwrite` / `smart` / `skip`。其中 **`smart` 是推荐的重复同步模式**：只要本地 mtime 在远端时间精度下已经等于或晚于远端 `modified_time`，就跳过下载；时间戳缺失/非法时会退回安全路径继续下载，不会盲跳。想做 `keep-both` 这类的仍需自己改名再 pull。
+- 已存在的本地文件按 `--if-exists` 决定 `overwrite` 还是 `skip`，没有第三种选择 —— 想做 `keep-both` 这类的请自己改名再 pull。
 - 云端同名冲突默认失败；只有“冲突全是 `type=file`”且传了 `--on-duplicate-remote rename|newest|oldest` 时才会继续。
 
 ## --delete-local 的安全行为
@@ -110,8 +106,8 @@ lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 
 ## 性能注意
 
-- 默认 `overwrite` 下，重复跑会重新下载所有命中的同名文件；`skip` 下则完全不碰已存在文件；**`smart` 下才会按 `modified_time` 跳过已经对齐的本地文件**，适合重复增量同步。
-- 想更精细地控制下载量，可以先 `+status` 找出 `new_remote` 和 `modified`，再只对这些文件单独 `+download`；或者直接在整目录同步时使用 `--if-exists smart`。
+- 下载流量 ≈ 云端待下载文件的总字节数。pull 是**全量**写盘 —— 跟 `+status` 不一样，不会跳过"内容相同"的文件（status 是按 hash 比较，pull 是按 `--if-exists`），所以一次跑可能很重。
+- 想避免重跑全量，可以先 `+status` 找出 `new_remote` 和 `modified`，再只对这些文件单独 `+download`。
 - 大文件会用 SDK 的流式下载（不会把整个 body 读进内存），但本地磁盘空间需要够。
 
 ## 所需 scope

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

@@ -12,7 +12,7 @@
 | 字段 | 含义 |
 |------|------|
 | `summary.uploaded` | 成功新建或覆盖的文件数 |
-| `summary.skipped` | 因 `--if-exists=skip` 或 `--if-exists=smart` 命中“无需传输”而跳过的文件数 |
+| `summary.skipped` | 按 `--if-exists=skip` 跳过的文件数 |
 | `summary.failed` | 上传 / 覆盖 / 建目录 / 删除失败的条目数；**只要不为 0，命令就以非零状态退出**（结构化 `items[]` 仍在 stdout 上） |
 | `summary.deleted_remote` | 启用 `--delete-remote --yes` 时删除的云端文件数 |
 | `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error`） |
@@ -36,14 +36,10 @@
 ## 命令
 
 ```bash
-# 基础用法 —— 把本地 ./repo 推送到云端 fldcXXX
+# 基础用法 —— 把本地 ./repo 增量推送到云端 fldcXXX
 # 默认 --if-exists=skip：已经存在的远端文件保持不动，只新增、不覆盖。
 lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx
 
-# 重复同步时可用 smart 做增量优化：它会按 modified_time 跳过已对齐的远端文件；但如果远端更旧，仍会继续走覆盖路径
-lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
-  --if-exists smart
-
 # 显式覆盖远端同名文件（依赖 upload_all 的灰度协议字段，详见下文"覆盖语义"）
 lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
   --if-exists overwrite
@@ -66,7 +62,7 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 |------|------|------|------|
 | `--local-dir` | 是 | path | 本地根目录（**必须是 cwd 的相对路径**；绝对路径或逃出 cwd 的相对路径会被 CLI 直接拒绝） |
 | `--folder-token` | 是 | string | 目标 Drive 文件夹 token |
-| `--if-exists` | 否 | enum | 远端文件已存在时的策略：`skip`（**默认**，安全）/ `smart`（用于重复增量同步；当远端 `modified_time` 已匹配或更新时跳过上传，否则继续走覆盖路径）/ `overwrite`（依赖灰度后端协议，详见"覆盖语义"） |
+| `--if-exists` | 否 | enum | 远端文件已存在时的策略：`skip`（**默认**，安全）/ `overwrite`（依赖灰度后端协议，详见"覆盖语义"） |
 | `--on-duplicate-remote` | 否 | enum | 云端多个条目映射到同一个 `rel_path` 时的策略：`fail`（默认）；如果冲突全是 `type=file`，还可选 `newest` / `oldest` |
 | `--delete-remote` | 否 | bool | 删除云端本地不存在的文件（文件级镜像；**不会**清理远端只有的目录）；**必须配合 `--yes`**，且 Validate 阶段会动态检查 `space:document:delete` scope |
 | `--yes` | 否 | bool | 确认 `--delete-remote`；不传时该破坏性操作在 Validate 阶段被拒绝 |
@@ -75,15 +71,13 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 
 - **只上传 / 覆盖 / 删除 Drive `type=file`**。在线文档（`docx` / `sheet` / `bitable` / `mindnote` / `slides`）和快捷方式（`shortcut`）即使在同一 rel_path 下出现，也不会被覆盖或删除 —— 它们没有等价的本地二进制。
 - **本地目录结构整体被镜像**：所有子目录（含**空目录**）会按需在 Drive 上 `create_folder`；同名远端目录复用其 token，不重建。空目录不计入 `summary.uploaded`，但会在 `items[]` 里以 `folder_created` 形式留痕。
-- 已存在的远端文件按 `--if-exists` 决定 `overwrite` / `smart` / `skip`。其中 `smart` 是**增量优化模式**：只要远端 `modified_time` 在同等时间精度下已经等于或晚于本地 mtime，就跳过上传；时间戳缺失/非法时会退回安全路径继续上传，不会盲跳。**但如果远端更旧，`smart` 会继续走和 `overwrite` 相同的覆盖路径，因此也继承同样的 rollout / version 返回 caveat。** 想做 `keep-both` 这类的仍需自行改名再 push。
+- 已存在的远端文件按 `--if-exists` 决定 `overwrite` 还是 `skip`，没有第三种选择 —— 想做 `keep-both` 这类的请自行改名再 push。
 - 云端同名冲突默认失败；只有“冲突全是 `type=file`”且传了 `--on-duplicate-remote newest|oldest` 时才会选择一个远端文件继续。启用 `--delete-remote` 时，未被选中的 duplicate sibling 也会被删除，最终远端只保留一个被选中的文件副本；只有在 `--if-exists=overwrite` 成功时，才能保证该副本内容与本地对齐。
 
 ## 覆盖语义
 
 `--if-exists=overwrite` 走 `POST /open-apis/drive/v1/files/upload_all`，并在 form 中带上现有文件的 `file_token`，由后端原地更新内容并返回新版本号。`items[].version` 字段会回填该版本号。
 
-`--if-exists=smart` 是给“重复跑同步”的场景增加的增量优化：当远端 `modified_time` 在同等时间精度下已经等于或晚于本地 mtime 时，命令会把该文件计为 `skipped`；时间戳缺失、非法或更旧时，则继续走正常上传/覆盖路径。**也就是说，只要 smart 判定“远端不够新”，它就会进入与 `--if-exists=overwrite` 相同的覆盖实现，因此在未 rollout version 字段的 tenant 上仍可能非零失败。**
-
 > **为什么默认是 `skip` 而不是 `overwrite`：** `upload_all` 接受 `file_token` 字段、并在响应里返回 `version` 是设计文档（Drive 同步盘）规定的协议；此后端尚在灰度发布。在还未开通该字段的 tenant 上，`--if-exists=overwrite` 会因"无 version 返回"而把对应文件标成 `failed`，整次 `+push` 也会因此非零退出。所以默认值故意定为 `skip`：第一次往一个已经有内容的目录里 push，不会因为协议没到位就把整次运行打挂；要真的覆盖远端，必须显式带 `--if-exists overwrite`。新建上传不依赖该字段，不受影响。
 
 大文件（>20MB）会自动切到三段式 `upload_prepare` / `upload_part` / `upload_finish`；该路径下 `version` 暂未在响应中返回，覆盖结果中 `items[].version` 会留空，但 `file_token` 与 `action: overwritten` 仍会正确产出。
@@ -128,8 +122,8 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 
 ## 性能注意
 
-- 默认 `skip` 下，已存在的远端文件一律不碰；`overwrite` 下，重复跑会重传所有命中的同名文件；`smart` 下会按 `modified_time` 跳过已对齐的远端文件，但对“远端更旧”的文件仍会进入覆盖路径，因此它减少的是**不必要的重传**，不是把覆盖风险完全拿掉。
-- 想更精细地控制传输量，可以先 `+status` 找出 `new_local` 和 `modified`，再只对这些文件单独上传 / 覆盖；或者直接在整目录同步时使用 `--if-exists smart`。
+- 上传流量 ≈ 本地待上传文件的总字节数。push 是**全量**上传 —— 跟 `+status` 不一样，不会按 hash 跳过"内容相同"的文件（status 是按 hash 比较，push 是按 `--if-exists`），所以一次跑可能很重。
+- 想避免重跑全量，可以先 `+status` 找出 `new_local` 和 `modified`，再只对这些文件单独上传 / 覆盖。
 - 大文件会用三段式分片上传（不会把整个 body 读进内存），但本地磁盘和上行带宽需要够。
 
 ## 所需 scope

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

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-按 **精确 SHA-256**（默认）或 **快速 modified_time**（`--quick`）比较本地目录与飞书云空间文件夹，输出四类差异：
+按 SHA-256 内容哈希比较本地目录与飞书云空间文件夹，输出四类差异：
 
 | 字段 | 含义 |
 |------|------|
@@ -12,10 +12,7 @@
 | `modified` | 双端都存在但 hash 不一致 |
 | `unchanged` | 双端都存在且 hash 一致 |
 
-只读命令：
-
-- 默认 `detection=exact`：双端都有的文件会从云端拉一份字节流过来在内存里算 hash，不下载落盘，但大目录 / 大文件会有可观的网络流量。
-- 传 `--quick` 后 `detection=quick`：只比较本地 mtime 与远端 `modified_time`，**不下载远端文件内容**，适合先做快速预检查；它是 best-effort，不等同于严格内容一致性判断。
+只读命令：流式 hash，不下载落盘；但双端都有的文件会从云端拉一份字节流过来在内存里算 hash，大目录 / 大文件会有可观的网络流量。
 
 ## 远端同名文件冲突
 
@@ -29,12 +26,6 @@ lark-cli drive +status \
   --local-dir ./repo \
   --folder-token fldcnxxxxxxxxx
 
-# 快速模式 —— 只比较 modified_time，不下载远端文件内容
-lark-cli drive +status \
-  --local-dir ./repo \
-  --folder-token fldcnxxxxxxxxx \
-  --quick
-
 # 只看 hash 不一致的项（结合 --jq 过滤）
 lark-cli drive +status \
   --local-dir ./repo \
@@ -48,7 +39,6 @@ lark-cli drive +status \
 |------|------|------|------|
 | `--local-dir` | 是 | path | 本地根目录（**必须是 cwd 的相对路径**；绝对路径或逃逸到 cwd 外的相对路径会被 CLI 直接拒绝） |
 | `--folder-token` | 是 | string | Drive 文件夹 token |
-| `--quick` | 否 | bool | 快速模式：只比较本地 mtime 与远端 `modified_time`，跳过远端下载和 SHA-256 计算；输出里的 `detection` 会变成 `quick` |
 
 ## 输出 schema
 
@@ -56,7 +46,6 @@ lark-cli drive +status \
 
 ```json
 {
-  "detection":  "exact",
   "new_local":  [{"rel_path": "..."}],
   "new_remote": [{"rel_path": "...", "file_token": "..."}],
   "modified":   [{"rel_path": "...", "file_token": "..."}],
@@ -64,11 +53,6 @@ lark-cli drive +status \
 }
 ```
 
-其中：
-
-- `detection=exact`：默认模式，双端都有的文件会下载远端字节流并做 SHA-256 比较。
-- `detection=quick`：`--quick` 模式，只按本地 mtime 与远端 `modified_time` 做 best-effort 判断。
-
 `rel_path` 始终用 `/` 作为分隔符（跨平台一致），相对于 `--local-dir` 或 `--folder-token` 的根。仅本地存在时没有 `file_token` 字段。
 
 远端同名文件冲突时：
@@ -100,7 +84,6 @@ lark-cli drive +status \
 - 子文件夹会递归遍历；rel_path 形如 `sub1/sub2/file.txt`。
 - 多个远端条目映射到同一个 rel_path 时不做隐式选择，默认失败。
 - 本地侧只比对常规文件（regular file）；符号链接、设备文件等被忽略。
-- `--quick` 模式下，双端都有的文件只在 **远端时间精度** 下比较 `modified_time` / 本地 mtime：相等才记为 `unchanged`，否则记为 `modified`；远端时间戳缺失或非法时，走保守路径记为 `modified`，不会盲判 `unchanged`。
 
 ## 范围限制
 
@@ -116,10 +99,9 @@ lark-cli drive +status \
 
 ## 性能注意
 
-- 默认 `detection=exact` 下，`unchanged` + `modified` 的总字节数 = 本次需从云端下载的流量。100GB 的双端共享内容意味着 100GB 网络往返。
-- `--quick` / `detection=quick` 下，不会下载双端共有文件的远端内容，执行时间更接近 `O(文件数量)`，而不是 `O(总文件大小)`。
+- `unchanged` + `modified` 的总字节数 = 本次需从云端下载的流量。100GB 的双端共享内容意味着 100GB 网络往返。
 - 仅一侧存在的文件不会被下载。
-- 默认模式的 hash 计算在内存里流式做（io.Copy → sha256.New），不会把云端文件落到磁盘。
+- Hash 计算在内存里流式做（io.Copy → sha256.New），不会把云端文件落到磁盘。
 
 ## 所需 scope
 

skills/lark-im/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-im
 version: 1.0.0
-description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据时使用。"
+description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、管理标记数据时使用。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -68,7 +68,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 
 | Shortcut | 说明 |
 |----------|------|
-| [`+chat-create`](references/lark-im-chat-create.md) | Create a group chat or topic chat; user/bot; --chat-mode group|topic; private/public; invites users/bots; optionally sets bot manager |
+| [`+chat-create`](references/lark-im-chat-create.md) | Create a group chat; user/bot; creates private/public chats, invites users/bots, optionally sets bot manager |
 | [`+chat-messages-list`](references/lark-im-chat-messages-list.md) | List messages in a chat or P2P conversation; user/bot; accepts --chat-id or --user-id, resolves P2P chat_id, supports time range/sort/pagination |
 | [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by `--query` keyword and/or `--member-ids`; user/bot; e.g. look up chat_id by group name; supports type filters, sorting, and pagination |
 | [`+chat-update`](references/lark-im-chat-update.md) | Update group chat name or description; user/bot; updates a chat's name or description |

skills/lark-im/references/lark-im-chat-create.md

@@ -2,7 +2,7 @@
 
 > **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
 
-Create a group chat. Supports both user identity (`--as user`) and bot identity (`--as bot`). You can specify the group name, description, members (users/bots), owner, chat type (private/public), and group mode. Set `--chat-mode topic` to create a topic chat.
+Create a group chat. Supports both user identity (`--as user`) and bot identity (`--as bot`). You can specify the group name, description, members (users/bots), owner, and chat type (private/public).
 
 This skill maps to the shortcut: `lark-cli im +chat-create` (internally calls `POST /open-apis/im/v1/chats`).
 
@@ -18,9 +18,6 @@ lark-cli im +chat-create --name "My Group"
 # Create a public group (name is required and must be at least 2 characters)
 lark-cli im +chat-create --name "Public Group" --type public
 
-# Create a topic chat
-lark-cli im +chat-create --name "Topic Group" --chat-mode topic
-
 # Specify the group owner
 lark-cli im +chat-create --name "My Group" --owner ou_xxx
 
@@ -58,15 +55,12 @@ lark-cli im +chat-create --name "My Group" --dry-run
 | `--users <ids>` | No | Up to 50, format `ou_xxx` | Comma-separated user open_ids |
 | `--bots <ids>` | No | Up to 5, format `cli_xxx` | Comma-separated bot app IDs |
 | `--owner <open_id>` | No | Format `ou_xxx` | Owner open_id (defaults to the bot when using `--as bot`, or the authorized user when using `--as user`) |
-| `--type <type>` | No | `private` (default) or `public` | Group type. Default to `private`; pass `public` only when the user explicitly asks for a discoverable/public group. |
-| `--chat-mode <mode>` | No | `group` (default) or `topic` | Group mode; `topic` creates a topic chat (not the same as `group_message_type=thread`). When the user asks for a topic chat, pass `topic` explicitly — do not rely on the default. |
+| `--type <type>` | No | `private` (default) or `public` | Group type |
 | `--set-bot-manager` | No | - | Set the creating bot as a group manager (only effective with `--as bot`) |
 | `--format json` | No | - | Output as JSON |
 | `--as <identity>` | No | `bot` or `user` | Identity type |
 | `--dry-run` | No | - | Preview the request without executing it |
 
-> **`--chat-mode topic` vs "normal group with topic-message mode"**: `--chat-mode topic` here creates a 话题群 — the entire group is a topic chat. This is different from "normal group (`chat_mode=group`) + topic-message mode (`group_message_type=thread`)". This CLI exposes only `chat_mode`; `group_message_type` is intentionally not surfaced.
-
 ## AI Usage Guidance
 
 ### When using `--as bot`

skills/lark-slides-creator/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: lark-slides-creator
+version: 1.0.0
+description: "飞书幻灯片创作工作流：从自然语言需求创建、重构、美化完整 PPT，覆盖规划、模板选择、视觉风格、素材规划和创建后验证。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli slides --help"
+---
+
+# slides creator workflow
+
+> 执行 XML/API 前必须读取 ../lark-slides/SKILL.md 和对应 reference。
+
+This skill is the natural-language entry point for creating polished presentations. It owns planning, design, template, asset, and quality-validation workflows. It delegates all XML/API execution to [`../lark-slides/SKILL.md`](../lark-slides/SKILL.md).
+
+## When To Use
+
+Use this skill when the user asks for:
+
+- A new complete presentation from a topic, notes, outline, document, meeting, or rough prompt.
+- Beautification, restructuring, major rewrite, or formal-report polishing.
+- Template selection or a deck based on a theme, scene, industry, or visual style.
+- Visual direction, palette, typography, layout system, or executive-ready presentation quality.
+- Asset planning, image search/download/upload planning, or deciding where visuals belong.
+- Creation-time and post-creation validation for content completeness and visual quality.
+
+For a narrow raw XML/API operation, use `lark-slides` directly.
+
+## Required Execution Dependency
+
+Before running any `lark-cli slides` command or writing final XML:
+
+1. Read [`../lark-slides/SKILL.md`](../lark-slides/SKILL.md).
+2. Read [`../lark-slides/references/xml-schema-quick-ref.md`](../lark-slides/references/xml-schema-quick-ref.md).
+3. Read the relevant execution reference, such as `lark-slides-create.md`, `lark-slides-media-upload.md`, `lark-slides-replace-slide.md`, or an `xml_presentation.*` API reference.
+
+Use the execution skill's lint tool from here when XML is available:
+
+```bash
+python3 skills/lark-slides-creator/scripts/layout_lint.py --input /tmp/presentation.xml
+```
+
+## Workflow
+
+1. Understand the deck goal.
+   Capture topic, audience, page count, source material, language, formality, delivery setting, and any brand/style constraints. If the user gives enough information, proceed with explicit assumptions instead of blocking on questions.
+
+2. Choose template or custom direction.
+   If the request mentions templates, style, theme, or a common deck scenario, search templates first:
+
+   ```bash
+   python3 skills/lark-slides-creator/scripts/template_tool.py search --query "<用户需求原文>" --limit 3
+   ```
+
+   Offer 2-3 concise candidates when user choice matters. If one template is clearly best for a lightweight request, state the default and continue unless the user asked to choose.
+
+3. Plan the deck.
+   Build a page-by-page outline with title, role, key message, and intended layout for each slide. For formal reports, make the argument flow explicit: context, evidence, analysis, recommendation, next steps.
+
+4. Design the visual system.
+   Define palette, typography hierarchy, spacing, page rhythm, chart/table treatment, and recurring elements. Keep slides visual and low-density; do not produce document-like pages.
+
+5. Plan assets.
+   Decide which pages need screenshots, photos, diagrams, icons, or charts. External images must become local files first, then execution uses `+media-upload` or `@./path` placeholders as described in `lark-slides`.
+
+6. Generate XML and execute through `lark-slides`.
+   Use template summaries or extracted page slices when helpful, but rewrite all placeholder copy into the user's real content. For complex decks, prefer the two-step create flow from `lark-slides`.
+
+7. Validate after creation.
+   Read the created presentation XML with `xml_presentations get`, confirm page count and expected content, run lint when possible, then fix issues with `+replace-slide` or raw slide APIs.
+
+## Template Workflow
+
+Template assets live in this skill:
+
+- [`references/template-catalog.md`](references/template-catalog.md)
+- [`references/template-index.json`](references/template-index.json)
+- [`assets/templates/`](assets/templates/)
+- [`scripts/template_tool.py`](scripts/template_tool.py)
+
+Machine-first commands:
+
+```bash
+python3 skills/lark-slides-creator/scripts/template_tool.py search --query "工作汇报" --tone light --limit 3
+python3 skills/lark-slides-creator/scripts/template_tool.py summarize --template office--work_report --label 内容
+python3 skills/lark-slides-creator/scripts/template_tool.py extract --template office--work_report --label 封面 --out /tmp/work-report-cover.xml
+```
+
+Rules:
+
+- Search using the user's original wording.
+- Show only 2-3 candidate templates unless the user asks for the full catalog.
+- Summarize a target page type before extracting XML.
+- Do not read entire template XML files by default.
+- Reuse theme, spacing, and structure; do not copy placeholder text.
+
+## References
+
+| Reference | Purpose |
+| --- | --- |
+| [planning-layer.md](references/planning-layer.md) | Deck planning and outline workflow. |
+| [visual-planning.md](references/visual-planning.md) | Visual style and layout design guidance. |
+| [asset-planning.md](references/asset-planning.md) | Asset selection, local-file, and upload planning. |
+| [template-catalog.md](references/template-catalog.md) | Template matching catalog. |
+| [slide-templates.md](references/slide-templates.md) | Copyable slide XML patterns for creation. |
+| [validation-checklist.md](references/validation-checklist.md) | Creation quality and post-create validation checklist. |

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

@@ -0,0 +1,21 @@
+# Asset Planning
+
+Use this when a deck needs screenshots, photos, diagrams, logos, icons, or chart data.
+
+## Asset Plan
+
+For each asset, record:
+
+- Slide number and purpose.
+- Asset type: screenshot, product image, chart, diagram, logo, icon, photo.
+- Source: provided file, generated file, downloaded file, or chart from data.
+- Local path under the current working directory.
+- Intended placement and dimensions.
+
+## Rules
+
+- Slides XML cannot use HTTP(S) image URLs directly.
+- For a new deck using `+create --slides`, local image placeholders can use `src="@./path.png"`.
+- For existing decks or raw slide APIs, upload first with `slides +media-upload`, then use the returned `file_token`.
+- Keep source files inside the current working directory or a safe project subdirectory.
+- Check image dimensions and file size before upload; slides media upload limit is 20 MB.

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

@@ -0,0 +1,32 @@
+# Slides Planning Layer
+
+Use this before writing XML for a full presentation or a major rewrite.
+
+## Inputs
+
+- Goal: what decision, update, teaching outcome, or story the deck must support.
+- Audience: executives, customers, internal team, interview panel, students, or general readers.
+- Constraints: page count, language, source material, deadline, brand rules, required sections.
+- Success criteria: what the user should be able to inspect after creation.
+
+## Output Outline
+
+Use this compact structure:
+
+```text
+Title: <deck title>
+Audience: <audience>
+Style: <visual direction or selected template>
+Slides:
+1. <slide title> - <message> - <layout intent>
+2. ...
+```
+
+For formal reports, prefer this flow: cover, context, key findings, supporting evidence, implications, recommendations, next steps, closing.
+
+## Rules
+
+- Each slide gets one primary message.
+- Avoid document-like density; split overloaded pages.
+- Make charts or tables serve a stated point.
+- Confirm template choice when multiple good candidates would lead to materially different decks.

skills/lark-slides-creator/references/template-catalog.md

@@ -10,26 +10,26 @@
 
 ## 使用方法
 
-1. 先运行 `python3 skills/lark-slides/scripts/template_tool.py search --query "<主题>" --limit 3`，根据用户描述的 **场景、风格、色调** 做初筛
+1. 先运行 `python3 skills/lark-slides-creator/scripts/template_tool.py search --query "<主题>" --limit 3`，根据用户描述的 **场景、风格、色调** 做初筛
 2. 整理出 **2-3 个**最匹配的用户可选模板候选；优先选场景强相关模板，没有明显场景模板时再用标 ⭐ 的通用模板兜底
 3. 用户选定后，再锁定 **1-2 个**最匹配的模板作为实际参考
 4. 先看模板下方的 **页型索引**，锁定你真正需要的页型：封面 / 目录 / 分节 / 内容 / 结尾
 5. 优先运行 `template_tool.py summarize` 查看 `<theme>` / 页型摘要；只有需要具体布局骨架时，再运行 `template_tool.py extract`
 6. 从模板中提取并复用：`<theme>` 配色、页面流、shape 排列布局、装饰元素风格
 7. 将用户的实际内容填充到模板的结构框架中，**不要照搬模板的占位文字**
-8. 创建前运行 `layout_lint.py --input <file>`；它检查 XML well-formed 和布局风险，不等价于完整 XSD schema 校验
+8. 创建前运行 `python3 skills/lark-slides-creator/scripts/layout_lint.py --input <file>`；它检查 XML well-formed 和布局风险，不等价于完整 XSD schema 校验
 
 ### 脚本快捷命令
 
 ```bash
 # 先找候选模板
-python3 skills/lark-slides/scripts/template_tool.py search --query "工作汇报" --tone light --limit 3
+python3 skills/lark-slides-creator/scripts/template_tool.py search --query "工作汇报" --tone light --limit 3
 
 # 看指定页型的紧凑摘要
-python3 skills/lark-slides/scripts/template_tool.py summarize --template office--work_report --label 内容
+python3 skills/lark-slides-creator/scripts/template_tool.py summarize --template office--work_report --label 内容
 
 # 只裁切目标页型，避免把整份 XML 拉进上下文
-python3 skills/lark-slides/scripts/template_tool.py extract --template office--work_report --label 封面 --out /tmp/work-report-cover.xml
+python3 skills/lark-slides-creator/scripts/template_tool.py extract --template office--work_report --label 封面 --out /tmp/work-report-cover.xml
 ```
 
 如果脚本路径不可用，按这个顺序手动降级：

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

@@ -0,0 +1,25 @@
+# Slides Creation Validation Checklist
+
+Use this after generating XML and again after creating or editing the deck.
+
+## Before API Execution
+
+- XML is well-formed.
+- User text is escaped: `&`, `<`, and `>` are safe.
+- Each slide has one clear message.
+- Text boxes are sized for expected content.
+- Images use `@./local-path` only where `+create --slides` supports it; otherwise they use `file_token`.
+- Run execution-layer lint when XML is in a file:
+
+```bash
+python3 skills/lark-slides-creator/scripts/layout_lint.py --input /tmp/presentation.xml
+```
+
+## After Creation
+
+- Record `xml_presentation_id`.
+- Read the full deck with `xml_presentations get`.
+- Confirm expected page count and page order.
+- Confirm key titles, body text, metrics, and image elements exist.
+- Check for blank pages, missing text, truncated shell arguments, unresolved `@` paths, and wrong image `src`.
+- Fix localized issues with `+replace-slide`; only delete/recreate a page when the whole structure is wrong.

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

@@ -0,0 +1,22 @@
+# Visual Planning
+
+Use this to define the deck's visual system before generating slide XML.
+
+## Decisions
+
+- Palette: background, primary accent, secondary accent, text, muted text, border.
+- Typography: title, section heading, body, caption, metric number.
+- Layout rhythm: margins, grid, recurring title position, footer treatment.
+- Components: cards, callouts, timelines, charts, tables, quote blocks, section dividers.
+
+## Guidance
+
+- Business reports should be quiet, readable, and scannable.
+- Product or technology decks can use stronger contrast, but keep hierarchy clear.
+- Use repeated structure across related slides.
+- Keep text inside predictable bounds; leave enough whitespace for rendering variance.
+- Do not rely on external image URLs in XML. Images must become `file_token` values through the execution workflow.
+
+## XML Note
+
+Before writing XML, read `../lark-slides/references/xml-schema-quick-ref.md`. Gradient fills must use `rgba()` stops with percentages.

skills/lark-slides/SKILL.md

@@ -1,525 +1,163 @@
 ---
 name: lark-slides
 version: 1.0.0
-description: "飞书幻灯片：创建和编辑幻灯片，接口通过 XML 协议通信。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。"
+description: "飞书幻灯片执行层：通过 Slides XML/API 读取、创建、删除、替换幻灯片页面，处理 URL/wiki token、媒体上传、XML schema、格式校验与排障。"
 metadata:
   requires:
     bins: ["lark-cli"]
   cliHelp: "lark-cli slides --help"
 ---
 
-# slides (v1)
+# slides execution layer
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+> 创建完整 PPT、设计、美化、模板、素材、正式汇报场景请使用 lark-slides-creator。本 skill 只负责 XML/API 执行层。
 
-**CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理。**
 
-**CRITICAL — 如果用户提到“模板”“套用模板”“参考某种主题/风格/版式”，或用户需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），MUST 先用 [`scripts/template_tool.py`](scripts/template_tool.py) 的 `search` 做模板检索；默认给出 2-3 个最匹配模板候选供用户选择。锁定模板后用 `summarize` 获取主题和布局摘要；只有需要布局骨架时才用 `extract` 裁切目标页型 XML。不要直接读取完整模板 XML。**
+**CRITICAL — 生成或修改任何 XML 之前，MUST 先读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)。不要凭记忆猜测 XML 结构。**
 
-> [!NOTE]
-> `scripts/template_tool.py` 需要 Python 3。`references/template-index.json` 是脚本缓存/轻量路由索引，不是默认给 agent 阅读的文档；`assets/templates/*.xml` 是机器资源，只应通过脚本摘要或裁切，不要全文读取。
+**CRITICAL — `references/slides_xml_schema_definition.xml` 是 Slides XML 协议的唯一权威来源；Markdown reference 只是摘要。若两者或 `lark-cli schema` 输出不一致，以 schema 和 CLI 为准。**
 
-**CRITICAL — 使用模板生成或改写页面时，MUST 先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。生成本地 XML 后，如可运行 Python，MUST 先用 [`scripts/layout_lint.py`](scripts/layout_lint.py) 检查 XML well-formed、重叠/越界/文本高度风险，再创建或追加页面。它不是完整 XSD schema 校验。**
+## Scope
 
-**编辑已有幻灯片页面**：优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
+Use this skill for low-level execution tasks:
 
-## 身份选择
+- Create an empty presentation or add raw slide XML.
+- Read presentation or slide XML.
+- Delete slides.
+- Replace or insert existing slide blocks.
+- Upload local media and use returned `file_token` in XML.
+- Resolve `/slides/` URL tokens and `/wiki/` tokens.
+- Check XML format, schema rules, and common API errors.
 
-飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。
+Do not use this skill as the primary entry for planning, visual design, template selection, asset planning, or full-deck creation. Route those requests to `lark-slides-creator`, then return here only for XML/API execution.
 
-- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权：
+## Identity
+
+Slides are usually user-owned content. Default to explicit `--as user` for slides commands.
 
 ```bash
 lark-cli auth login --domain slides
 ```
 
-- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。
+Use `--as bot` only when the user explicitly asks for app/bot identity or the workflow intentionally creates bot-owned resources. If access fails, first check that the command did not accidentally use the wrong identity.
 
-**执行规则**：
+## URL And Wiki Tokens
 
-1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。
-2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。
-3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。
-
-## 快速开始
-
-一条命令创建包含页面内容的 PPT（推荐）：
+| URL | Token | Handling |
+| --- | --- | --- |
+| `/slides/<token>` | `xml_presentation_id` | Use the path token directly. |
+| `/wiki/<token>` | `wiki_token` | Resolve first with `wiki.spaces.get_node`; use `node.obj_token` only when `node.obj_type` is `slides`. |
 
 ```bash
-lark-cli slides +create --title "演示文稿标题" --slides '[
-  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(245,245,245)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"100\"><content textType=\"title\"><p>页面标题</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"200\"><content textType=\"body\"><p>正文内容</p><ul><li><p>要点一</p></li><li><p>要点二</p></li></ul></content></shape></data></slide>"
+lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}'
+lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"obj_token"}'
+```
+
+`+replace-slide` and `+media-upload` can parse slides/wiki URLs. Raw API commands still require the real `xml_presentation_id`.
+
+## Shortcuts
+
+| Shortcut | Reference | Purpose |
+| --- | --- | --- |
+| `slides +create` | [lark-slides-create.md](references/lark-slides-create.md) | Create a presentation; optionally add pages with `--slides`; supports local image placeholders in `+create --slides`. |
+| `slides +media-upload` | [lark-slides-media-upload.md](references/lark-slides-media-upload.md) | Upload a local image to a presentation and return a `file_token`. |
+| `slides +replace-slide` | [lark-slides-replace-slide.md](references/lark-slides-replace-slide.md) | Replace or insert blocks on an existing slide without changing page order. |
+
+Prefer shortcuts when they cover the operation, especially `+replace-slide` for existing-slide edits.
+
+## API Commands
+
+Always inspect schema before raw API calls:
+
+```bash
+lark-cli schema slides.<resource>.<method>
+lark-cli slides <resource> <method> --as user --params '{}' --data '{}'
+```
+
+Core resources:
+
+| Resource | Method | Purpose |
+| --- | --- | --- |
+| `xml_presentations` | `get` | Read full presentation XML and metadata. |
+| `xml_presentation.slide` | `create` | Add one slide XML page. |
+| `xml_presentation.slide` | `delete` | Delete a slide; a presentation must keep at least one page. |
+| `xml_presentation.slide` | `get` | Read one slide XML. |
+| `xml_presentation.slide` | `replace` | Low-level block replace/insert API; prefer `+replace-slide` unless you need raw control. |
+
+## Creation Paths
+
+For simple XML, `+create --slides` is concise:
+
+```bash
+lark-cli slides +create --as user --title "Demo" --slides '[
+  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(248,250,252)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"100\"><content textType=\"title\"><p>Title</p></content></shape></data></slide>"
 ]'
 ```
 
-也可以分两步（先创建空白 PPT，再逐页添加），详见 [+create 参考文档](references/lark-slides-create.md)。
-
-> [!WARNING]
-> `--slides '[...]'` 适合简单页面批量创建，但并不等同于“10 页以内都安全”。如果 slide XML 含中文、大段文本、复杂布局、嵌套引号或较多特殊字符，shell 传参时可能出现转义或截断问题，导致内容丢失、页面空白或布局异常。遇到复杂页面时，优先改用“两步创建法”。
-
-> [!IMPORTANT]
-> `slides +create --slides` 底层是“先创建空白 PPT，再逐页调用 `xml_presentation.slide.create`”。这不是原子操作；中途某一页失败时，前面已创建成功的页面会保留。skill 必须把这种“部分成功”风险提前告诉用户，并在失败后先记录 `xml_presentation_id`，回读确认当前状态，再决定是否在现有 PPT 上继续修复或追加。
-
-> 以上是最小可用示例。更丰富的页面效果（渐变背景、卡片、图表、表格等），参考下方 Workflow 和 XML 模板。
-
-## 执行前必做
-
-> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。
-
-### 必读（每次创建前）
-
-| 文档 | 说明 |
-|------|------|
-| [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md) | **XML 元素和属性速查，必读** |
-
-### 选读（需要时查阅）
-
-| 场景 | 文档 |
-|------|------|
-| 需要了解详细 XML 结构 | [xml-format-guide.md](references/xml-format-guide.md) |
-| 需要快速筛模板、做低成本路由 | [`scripts/template_tool.py search`](scripts/template_tool.py) |
-| 需要匹配 PPT 模板/主题风格 | [template-catalog.md](references/template-catalog.md) |
-| 需要按页型抽摘要或裁切 XML 片段 | [`scripts/template_tool.py`](scripts/template_tool.py) |
-| 需要做本地布局风险检查 | [`scripts/layout_lint.py`](scripts/layout_lint.py) |
-| 需要 CLI 调用示例 | [examples.md](references/examples.md) |
-| 需要参考真实 PPT 的 XML | [slides_demo.xml](references/slides_demo.xml) |
-| 需要用 table/chart 等复杂元素 | [slides_xml_schema_definition.xml](references/slides_xml_schema_definition.xml)（完整 Schema） |
-| 需要编辑已有 PPT 的单个页面 | [lark-slides-edit-workflows.md](references/lark-slides-edit-workflows.md) |
-| 需要了解某个命令的详细参数 | 对应命令的 reference 文档（见下方参考文档章节） |
-
-## Workflow
-
-> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。
-
-### 创建方式选择
-
-| 场景 | 推荐方式 |
-|------|----------|
-| 简单 XML（1-3 页、结构简单、几乎无复杂中文和特殊字符） | `slides +create --slides '[...]'` 一步创建 |
-| 复杂 XML（多页、含中文、大段文本、复杂布局、嵌套引号、特殊字符较多） | **两步创建**：先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide create` 逐页添加 |
-| 已有 PPT 继续追加或插入页面 | 使用 `xml_presentation.slide create`，必要时配合 `before_slide_id` |
-
-> [!WARNING]
-> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议使用两步创建法。
-
-### 模板与脚本优先流程
+For complex XML, long text, many special characters, Chinese paragraphs, images, or many pages, create an empty presentation first and add slides one by one. `+create --slides` is not atomic; if a later slide fails, earlier slides may already exist. Record `xml_presentation_id` and read the deck before continuing.
 
 ```bash
-# 1. 搜索候选：把用户原始需求整句放进 --query，不要只放手动提炼的短词
-python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3
+lark-cli slides +create --as user --title "Demo"
 
-# 2. 锁定模板后先看页型摘要
-python3 skills/lark-slides/scripts/template_tool.py summarize --template <template-id> --label <封面|目录|分节|内容|结尾>
-
-# 3. 只有需要复用布局骨架时才裁切 XML
-python3 skills/lark-slides/scripts/template_tool.py extract --template <template-id> --label <页型> --out /tmp/template-slice.xml
-
-# 4. 生成待创建 XML 后先做布局风险检查
-python3 skills/lark-slides/scripts/layout_lint.py --input /tmp/presentation.xml
-```
-
-执行规则：
-
-1. `search --query` 使用用户原始描述；如用户明确风格，再额外加 `--tone light|dark|colorful` 或 `--formality formal|casual|creative`。
-2. 候选展示只给 2-3 个，包含模板名、适用场景、风格/色调、推荐理由；不要把完整目录贴给用户。
-3. 锁定模板后，复用 `<theme>`、配色、页面流、布局骨架；所有占位文案都必须改写为用户真实内容。
-4. `layout_lint.py` 有 error 时先修 XML，不要提交创建；只有 warning 时，检查是否是可接受的装饰/背景误报。
-
-```text
-Step 1: 需求澄清 & 读取知识
-  - 澄清用户需求：主题、受众、页数、风格偏好
-  - 如果需求明显落在已有模板场景内，主动提示用户“可以直接基于现成模板生成”，并给出 2-3 个最匹配模板候选（模板名 + 适用场景 + 风格/色调 + 简短推荐理由）
-  - 默认不要把完整模板目录直接贴给用户；除非用户明确要求看更多，否则只展示 2-3 个候选
-  - 候选优先选场景强相关模板；只有没有明显场景模板时，才用 `light_general.xml` / `dark_general.xml` 这类通用模板兜底
-  - 如果用户没有明确风格，根据主题推荐（见下方风格判断表）
-  - 如果用户要求“模板/主题/风格参考”，或主题属于常见模板场景：
-    · 优先运行 `python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3` 做低成本模板匹配
-    · 需要人类可读说明时，再读 template-catalog.md 组织候选文案
-    · 锁定模板后，优先运行 `template_tool.py summarize` 看 `<theme>` / 页型摘要；需要具体布局时，再用 `template_tool.py extract`
-    · 复用模板的 theme、配色、页面流、布局骨架，不要照搬占位文案
-    · `references/template-index.json` 只是脚本缓存/轻量路由索引，`assets/templates/*.xml` 是机器资源；除非用户明确要求审计原始模板，否则不要直接读取
-  - 读取 XML Schema 参考：
-    · xml-schema-quick-ref.md — 元素和属性速查
-    · xml-format-guide.md — 详细结构与示例
-    · slides_demo.xml — 真实 XML 示例
-
-Step 2: 生成大纲 → 用户确认 → 创建
-  - 生成大纲前，先确认用户是否采用推荐模板；轻量任务且候选中有明显最佳匹配时，可在大纲里声明“默认基于 <template-id> 改写”并继续，但正式创建前必须给用户改选机会
-  - 生成结构化大纲（每页标题 + 要点 + 布局描述），交给用户确认
-  - 如果已选模板，大纲和页面布局要明确标注“基于哪个模板/哪些模板改写”
-  - 如果用户明确不要模板，直接按自定义风格继续，不要重复推动模板选择
-  - 先判断创建方式：
-    · 简单 XML：可用 `slides +create --slides '[...]'` 一步创建
-    · 复杂 XML：优先先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
-    · 超过 10 页：默认使用两步创建，避免单次输入过长
-  - 含本地图片：
-    · 新建带图 PPT —— 在 slide XML 里写 <img src="@./pic.png" .../>，
-      +create 会自动上传并替换为 file_token（详见 lark-slides-create.md）
-    · 给已有 PPT 加带图新页 —— 先 `slides +media-upload --file ./pic.png --presentation $PID`
-      拿到 file_token，再用它写进 slide XML 调 xml_presentation.slide.create
-    · 给已有页加图 —— 两步：① `slides +media-upload` 拿 file_token
-      ② `slides +replace-slide --parts '[{"action":"block_insert","insertion":"<img src=\"<file_token>\" .../>"}]'`
-      不动其他元素，不要再整页重建（完整示例见 lark-slides-edit-workflows.md 的 block_insert 章节）
-    · 路径必须是 CWD 内的相对路径（如 ./pic.png 或 ./assets/x.png）；
-      绝对路径会被 CLI 拒绝，先 cd 到素材所在目录再执行
-  - 每页 slide 需要完整的 XML：背景、文本、图形、配色
-  - 复杂元素（table、chart）需参考 XSD 原文
-  - 创建前必须做 XML 自检：
-    · 检查特殊字符是否按 XML 规则转义：文本节点和属性值里的裸 `& -> &amp;`；文本里的 `< -> &lt;`、`> -> &gt;`。例如 `Q&A -> Q&amp;A`，URL 属性 `a=1&b=2 -> a=1&amp;b=2`
-    · 属性值里的双引号必须转义或改为外层安全包装，避免 shell 和 JSON 双重截断
-    · 确认所有标签闭合，且 `<slide>` 直接子元素只包含 `<style>`、`<data>`、`<note>`
-    · 如果内容里同时出现中文、大段文本、复杂布局、较多特殊字符，默认不要走 `--slides '[...]'`，直接改用两步创建法
-    · 如果 XML 已落到本地文件且可运行 Python，先执行 `layout_lint.py --input <file>`；它会先检查 XML well-formed 再检查布局风险，但不等价于完整 XSD schema 校验；有 error 先修复再创建
-  - 如果使用模板生成页面，先复用模板骨架再填内容，不要直接复制模板中的长段占位文本
-
-Step 3: 审查 & 交付
-  - 创建完成后，必须用 xml_presentations.get 读取全文 XML 做创建后验证，确认：
-    · 页数是否正确？
-    · 每页 `<data>` 是否包含预期的 `<shape>` / `<img>` / 其他元素？
-    · 文本内容是否完整，是否有被截断、丢失、空白区域？
-    · 关键布局坐标和尺寸是否合理，是否出现明显重叠？
-    · 配色是否统一？字号层级是否合理？
-  - 如果本地有 Python 3，运行
-    `python3 skills/lark-slides/scripts/layout_lint.py --input presentation.xml`
-    做重叠、越界、页脚碰撞、文本高度风险检查；有 error 先修复再交付
-  - 如果创建过程中失败：
-    · 先保留并记录 `xml_presentation_id`，不要假设失败代表什么都没创建
-    · 先判断是否已有部分页面写入，再决定是否在现有 PPT 上修复后继续追加
-    · 优先排查当前失败页：先看该页 XML，再检查是否存在未转义 `&`、错误引号、标签未闭合、shell 传参截断
-  - 局部问题 → 用 `+replace-slide` 块级修正；整页结构要改 → `slide.delete` 旧页 + `slide.create` 新页
-  - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
-```
-
-### 创建后验证
-
-创建成功不等于内容正确。创建完 PPT 后，**必须**读取全文 XML 校验结果：
-
-```bash
-lark-cli slides xml_presentations get --as user \
-  --params '{"xml_presentation_id":"YOUR_ID"}'
-```
-
-重点检查：
-
-- [ ] 页数是否与预期一致
-- [ ] 每页 `<data>` 中是否包含所有预期元素
-- [ ] 文本内容是否完整，没有被 shell 截断或转义损坏
-- [ ] 白底内容区、卡片区、图文区等关键布局是否实际生成
-- [ ] 坐标、宽高是否合理，是否出现堆叠或越界
-
-发现问题时：
-
-1. 不要假设“创建成功就代表渲染正确”
-2. 先读取问题页的 XML，确认是生成问题还是传参损坏
-3. 删除问题页后重新添加；复杂页面优先改用两步创建法
-
-### 最小验收清单
-
-创建完成后，默认按下面顺序验收，不要省略：
-
-1. 记录 `xml_presentation_id`
-2. 确认返回的 `slides_added` 或实际页数是否符合预期
-3. 立即执行 `xml_presentations get`
-4. 检查标题、关键页面、关键文本是否存在
-5. 检查是否有明显空白页、内容缺失、页序错误
-6. 再决定是否向用户交付 URL 和后续编辑建议
-
-推荐最小闭环：
-
-```bash
-# 创建
-lark-cli slides +create --as user --title "Demo" --slides '[...]'
-
-# 立即回读
-lark-cli slides xml_presentations get --as user \
-  --params '{"xml_presentation_id":"YOUR_ID"}'
-```
-
-## XML 自检与排障
-
-在真正创建前，至少做下面 4 项检查：
-
-- [ ] 特殊字符已转义：正文和标题里的 `&`、`<`、`>` 不能裸写；属性值里的裸 `&` 也必须写成 `&amp;`
-- [ ] 属性引号安全：XML 属性、shell 引号、JSON 字符串包装之间没有互相打断
-- [ ] 结构合法：`<slide>` 下只放 `<style>`、`<data>`、`<note>`，文本都在 `<content>` 内
-- [ ] 路径正确：`<img src="@...">` 只在 `+create --slides` 的支持链路中使用
-
-高频失败信号和处理顺序：
-
-1. `invalid param` / 某一页创建失败
-2. 先检查失败页是否含未转义 `&` / `<` / `>`：`Q&A -> Q&amp;A`，属性 URL `a=1&b=2 -> a=1&amp;b=2`
-3. 再检查标签闭合、属性引号、`<content>` 结构
-4. 如果是 `--slides '[...]'`，怀疑 shell 截断时直接切两步创建法
-5. 创建后无论成功失败，都优先记录 `xml_presentation_id` 并回读确认是否已有部分页面写入
-
-### jq 命令模板（编辑已有 PPT 时使用）
-
-新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
-
-```bash
-# 追加到末尾
-lark-cli slides xml_presentation.slide create \
-  --as user \
+lark-cli slides xml_presentation.slide create --as user \
   --params '{"xml_presentation_id":"YOUR_ID"}' \
-  --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
-  <data>
-    在这里放置 shape、line、table、chart 等元素
-  </data>
-</slide>' '{slide:{content:$content}}')"
-
-# 插到指定页之前：before_slide_id 必须在 --data body 里，与 slide 同级
-# ⚠️ 不要把 before_slide_id 写进 --params —— CLI 会当未知 query 参数静默下发，服务端忽略，新页跑到末尾
-lark-cli slides xml_presentation.slide create \
-  --as user \
-  --params '{"xml_presentation_id":"YOUR_ID"}' \
-  --data "$(jq -n --arg content '<slide ...>...</slide>' --arg before 'TARGET_SLIDE_ID' \
-    '{slide:{content:$content}, before_slide_id:$before}')"
+  --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data/></slide>' '{slide:{content:$content}}')"
 ```
 
-### 风格快速判断表
+To insert before an existing page, put `before_slide_id` in `--data`, not in `--params`.
 
-> **注意**：渐变色必须使用 `rgba()` 格式并带百分比停靠点，如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端回退为白色。
+## Media Upload
 
-| 场景/主题 | 推荐风格 | 背景 | 主色 | 文字色 |
-|----------|---------|------|------|-------|
-| 科技/AI/产品 | 深色科技风 | 深蓝渐变 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)` | 蓝色系 `rgb(59,130,246)` | 白色 |
-| 商务汇报/季度总结 | 浅色商务风 | 浅灰 `rgb(248,250,252)` | 深蓝 `rgb(30,60,114)` | 深灰 `rgb(30,41,59)` |
-| 教育/培训 | 清新明亮风 | 白色 `rgb(255,255,255)` | 绿色系 `rgb(34,197,94)` | 深灰 `rgb(51,65,85)` |
-| 创意/设计 | 渐变活力风 | 紫粉渐变 `linear-gradient(135deg,rgba(88,28,135,1) 0%,rgba(190,24,93,1) 100%)` | 粉紫色系 | 白色 |
-| 周报/日常汇报 | 简约专业风 | 浅灰 `rgb(248,250,252)` + 顶部彩色渐变条 | 蓝色 `rgb(59,130,246)` | 深色 `rgb(15,23,42)` |
-| 用户未指定 | 默认简约专业风 | 同上 | 同上 | 同上 |
+Slides XML image `src` must be a Lark `file_token`; do not use external HTTP(S) URLs.
 
-### 页面布局建议
+- New deck with `+create --slides`: `src="@./local.png"` is allowed and the shortcut uploads it.
+- Existing deck or raw `slide.create`: run `slides +media-upload` first, then write `src="<file_token>"`.
+- Existing slide edit: upload first, then use `+replace-slide` with `block_insert` or `block_replace`.
 
-| 页面类型 | 布局要点 |
-|---------|---------|
-| 封面页 | 居中大标题 + 副标题 + 底部信息，背景用渐变或深色 |
-| 数据概览页 | 指标卡片横排（rect 背景 + 大号数字 + 小号说明），下方列表或图表 |
-| 内容页 | 左侧竖线装饰 + 标题，下方分栏或列表 |
-| 对比/表格页 | table 元素或并列卡片，表头深色背景白字 |
-| 图表页 | chart 元素（column/line/pie），配合文字说明 |
-| 结尾页 | 居中感谢语 + 装饰线，风格与封面呼应 |
+Local paths must be safe paths under the current working directory. The upload limit is 20 MB.
 
-### 大纲模板
+## XML Rules
 
-生成大纲时使用以下格式，交给用户确认：
+- `<slide>` direct children are only `<style>`, `<data>`, and `<note>`.
+- Text belongs inside `<content><p>...</p></content>`.
+- Escape raw text before writing XML: `&` becomes `&amp;`, text `<` becomes `&lt;`, and text `>` becomes `&gt;`.
+- Gradient fills require `rgba()` stops with percentages, for example `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`.
+- For `xml_presentation.slide.replace`, `block_replace` needs the target block id and text shapes need `<content/>`; `+replace-slide` injects the required wrapper details.
 
-```text
-[PPT 标题] — [定位描述]，面向 [目标受众]
+## Validation
 
-模板：[未使用模板 / <category>/<template>.xml（推荐原因）]
+This execution skill validates at the XML/API layer. Before execution, check XML well-formedness, escaping, request body shape, and `lark-cli schema` output. Visual layout quality checks belong to creator workflows, not this execution layer.
 
-页面结构（N 页）：
-1. 封面页：[标题文案]
-2. [页面主题]：[要点1]、[要点2]、[要点3]
-3. [页面主题]：[要点描述]
-...
-N. 结尾页：[结尾文案]
+## Troubleshooting
 
-风格：[配色方案]，[排版风格]
-```
+| Symptom | Likely Cause | Next Action |
+| --- | --- | --- |
+| `400` XML or wrapper error | Bad XML or wrong `--data` shape | Check escaping, tag closure, and `lark-cli schema`. |
+| `403` permission denied | Wrong identity or missing scope | Confirm `--as user` vs `--as bot`; re-run auth for slides scope. |
+| `404` presentation/slide not found | Wrong token or unresolved wiki URL | Resolve wiki token or re-read current presentation. |
+| `1061002` media params error | Raw upload API used incorrectly | Use `slides +media-upload`; slides parent type is `slide_file`. |
+| `1061004` forbidden | Current identity cannot edit target deck | Use the owner identity or share the deck with the bot/user. |
+| `3350001` catch-all validation failure | XML not well-formed, bad replace wrapper, missing `<content/>`, or unescaped text | Run lint, inspect failed page XML, and prefer `+replace-slide` for block edits. |
+| `3350002` stale revision | `revision_id` is newer than current | Use `-1` or re-read the presentation and retry. |
+| Created deck has blank/missing pages | Shell/JSON argument truncation or escaping issue | Read back XML, then continue with two-step `slide.create`. |
+| Image does not show | `src` is URL or unresolved `@path` | Upload and replace with a `file_token`. |
 
-### 常用 Slide XML 模板
+## References
 
-可直接复制使用的模板（封面页、内容页、数据卡片页、结尾页）：[slide-templates.md](references/slide-templates.md)
-
----
-
-## 核心概念
-
-### URL 格式与 Token
-
-| URL 格式 | 示例 | Token 类型 | 处理方式 |
-|----------|------|-----------|----------|
-| `/slides/` | `https://example.larkoffice.com/slides/xxxxxxxxxxxxx` | `xml_presentation_id` | URL 路径中的 token 直接作为 `xml_presentation_id` 使用 |
-| `/wiki/` | `https://example.larkoffice.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
-
-> `+replace-slide` 和 `+media-upload` shortcut 会自动解析以上两种 URL；直接调用原生 API 时仍需手动解析 wiki 链接。
-
-### Wiki 链接特殊处理（关键！）
-
-知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、幻灯片等不同类型的文档。**不能直接假设 URL 中的 token 就是 `xml_presentation_id`**，必须先查询实际类型和真实 token。
-
-#### 处理流程
-
-1. **使用 `wiki.spaces.get_node` 查询节点信息**
-   ```bash
-   lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}'
-   ```
-
-2. **从返回结果中提取关键信息**
-   - `node.obj_type`：文档类型，幻灯片对应 `slides`
-   - `node.obj_token`：**真实的演示文稿 token**（用于后续操作）
-   - `node.title`：文档标题
-
-3. **确认 `obj_type` 为 `slides` 后，使用 `obj_token` 作为 `xml_presentation_id`**
-
-#### 查询示例
-
-```bash
-# 查询 wiki 节点
-lark-cli wiki spaces get_node --as user --params '{"token":"wikcnxxxxxxxxx"}'
-```
-
-返回结果示例：
-```json
-{
-   "node": {
-      "obj_type": "slides",
-      "obj_token": "xxxxxxxxxxxx",
-      "title": "2026 产品年度总结",
-      "node_type": "origin",
-      "space_id": "1234567890"
-   }
-}
-```
-
-```bash
-# 用 obj_token 读取幻灯片内容
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"xxxxxxxxxxxx"}'
-```
-
-### 资源关系
-
-```text
-Wiki Space (知识空间)
-└── Wiki Node (知识库节点, obj_type: slides)
-    └── obj_token → xml_presentation_id
-
-Slides (演示文稿)
-├── xml_presentation_id (演示文稿唯一标识)
-├── revision_id (版本号)
-└── Slide (幻灯片页面)
-    └── slide_id (页面唯一标识)
-```
-
-## Shortcuts（推荐优先使用）
-
-Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`）。有 Shortcut 的操作优先使用。
-
-| Shortcut | 说明 |
-|----------|------|
-| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传），bot 模式自动授权 |
-| [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
-| [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
-
-## API Resources
-
-```bash
-lark-cli schema slides.<resource>.<method>   # 调用 API 前必须先查看参数结构
-lark-cli slides <resource> <method> [flags] # 调用 API
-```
-
-> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
-
-### xml_presentations
-
-  - `get` — 读取演示文稿全文信息，XML 格式返回
-
-### xml_presentation.slide
-
-  - `create` — 在指定 XML 演示文稿下创建页面
-  - `delete` — 在指定 XML 演示文稿下删除页面
-  - `get` — 获取指定 XML 演示文稿的单个页面 XML 内容
-  - `replace` — 对指定 XML 演示文稿页面进行元素级别的局部替换
-
-## 核心规则
-
-1. **先定模板/风格并出大纲再动手**：如果需求可匹配模板，先给用户 2-3 个模板候选；模板或自定义风格确定后，再生成大纲交给用户确认，避免返工
-2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
-3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
-4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
-5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
-6. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
-7. **编辑已有页面优先块级替换**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；只有需要替换整页结构时才用 `slide.delete` + `slide.create`
-8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
-
-## 权限表
-
-| 方法 | 所需 scope |
-|------|-----------|
-| `slides +create` | `slides:presentation:create`, `slides:presentation:write_only`（含 `@` 占位符时还需 `docs:document.media:upload`） |
-| `slides +media-upload` | `docs:document.media:upload`（wiki URL 解析还需 `wiki:node:read`） |
-| `slides +replace-slide` | `slides:presentation:update`（wiki URL 解析还需 `wiki:node:read`） |
-| `xml_presentations.get` | `slides:presentation:read` |
-| `xml_presentation.slide.create` | `slides:presentation:update` 或 `slides:presentation:write_only` |
-| `xml_presentation.slide.delete` | `slides:presentation:update` 或 `slides:presentation:write_only` |
-| `xml_presentation.slide.get` | `slides:presentation:read` |
-| `xml_presentation.slide.replace` | `slides:presentation:update` |
-
-## 常见错误速查
-
-| 错误码 | 含义 | 解决方案 |
-|--------|------|----------|
-| 400 | XML 格式错误 | 检查 XML 语法，确保标签闭合 |
-| 400 | 请求包装错误 | 检查 `--data` 是否按 schema 传入 `xml_presentation.content` 或 `slide.content` |
-| 创建成功但页面空白/内容缺失/布局错乱 | 常见于 `--slides '[...]'` 的 shell 转义或长参数传递问题 | 改用两步创建：先 `slides +create`，再用 `jq -n` 包装 `xml_presentation.slide.create` 逐页添加，并在创建后立即读取 XML 验证 |
-| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
-| 404 | 幻灯片不存在 | 检查 `slide_id` 是否正确 |
-| 403 | 权限不足 | 检查是否拥有对应的 scope |
-| 400 | 无法删除唯一幻灯片 | 演示文稿至少保留一页幻灯片 |
-| 1061002 | params error（媒体上传时） | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
-| 1061004 | forbidden：当前身份对演示文稿无编辑权限 | 确认 user/bot 对目标 PPT 有编辑权限；bot 常见于 PPT 非该 bot 创建，需先授权或用 `+create --as bot` 新建 |
-| 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 `xml_presentation.slide.replace` 失败（catch-all） | 优先检查未转义 `&` / `<` / `>`：`Q&A -> Q&amp;A`，属性 URL `a=1&b=2 -> a=1&amp;b=2`；运行 `layout_lint.py --input <file>` 定位行列和上下文；再检查 replace 场景的 `block_id` / `<content/>` / 坐标 |
-| 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新读 `xml_presentations.get` 取最新 `revision_id` |
-| validation: unsafe file path | `--file` 给了绝对路径或上层路径 | `--file` 必须是 CWD 内相对路径；先 `cd` 到素材目录再执行 |
-
-## 创建前自查
-
-逐页生成 XML 前，快速检查：
-
-- [ ] 每页背景色/渐变是否设置？风格是否与整体一致？
-- [ ] 标题用大字号（28-48），正文用小字号（13-16），层级分明？
-- [ ] 同类元素配色一致？（如所有指标卡片同色系、所有正文同色）
-- [ ] 装饰元素（分割线、色块、竖线）颜色是否与主色协调？
-- [ ] 文本框尺寸是否足够容纳内容？（宽度 × 高度）
-- [ ] shape 的 `type` 是否正确？（文本框用 `text`，装饰用 `rect`）
-- [ ] XML 标签是否全部正确闭合？特殊字符（`&`、`<`、`>`）是否转义？
-
-## 症状 → 修复表
-
-| 看到的问题 | 改什么 |
-|-----------|--------|
-| 文字被截断/看不全 | 增大 shape 的 `width` 或 `height` |
-| 元素重叠 | 调整 `topLeftX`/`topLeftY`，拉开间距 |
-| 页面大面积空白 | 缩小元素间距，或增加内容填充 |
-| 文字和背景色太接近 | 深色背景用浅色文字，浅色背景用深色文字 |
-| 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
-| 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1`/`dim2` 数据数量是否匹配 |
-| 图片被裁掉一部分 | `<img>` 的 `width`/`height` 是裁剪后尺寸，比例和原图不一致时会自动裁剪；要整图显示就让 `width:height` 对齐原图比例 |
-| 只想改某页的单个元素（文字/图片/形状） | 用 `+replace-slide` 块级替换，不要整页重建 |
-| 想给已有页加一张图（不动原有元素） | ① `+media-upload` 拿 `file_token` ② `+replace-slide` 用 `block_insert` 插入 `<img src="<file_token>" .../>`；不要再用 "整页 create + delete" 的老流程 |
-| 新插入的 `<img>` 挡住/重叠原有元素 | `slide.get` 读原页，对照已有块的 `topLeftX/Y/width/height` 挑空白位置；空间不够就在同一批 `--parts` 里先 `block_replace` 缩小/挪动现有块再 `block_insert` 图片 |
-| 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)`；用 `rgb()` 或省略停靠点会被回退为白色 |
-| 渐变方向不对 | 调整 `linear-gradient` 的角度（`90deg` 水平、`180deg` 垂直、`135deg` 对角线） |
-| 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
-| API 返回 400 | 检查 XML 语法：标签闭合、属性引号、特殊字符转义 |
-| API 返回 3350001 | `block_replace` 根元素缺 `id=<block_id>` 或 `<shape>` 缺 `<content/>`，详见 replace-slide 文档 |
-| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符**只在 `+create --slides` 中替换**；直接调 `xml_presentation.slide.create` 必须先用 `+media-upload` 拿 `file_token` 写进 src |
-| 上传图片报 1061002 params error | `parent_type` 必须是 `slide_file`（slides 唯一接受值）；不要手拼，用 `slides +media-upload` |
-
-## 参考文档
-
-| 文档 | 说明 |
-|------|------|
-| [lark-slides-create.md](references/lark-slides-create.md) | **+create Shortcut：创建 PPT（支持 `--slides` 一步添加页面，含 `@` 占位符自动上传图片）** |
-| [lark-slides-media-upload.md](references/lark-slides-media-upload.md) | **+media-upload Shortcut：上传本地图片，返回 `file_token`** |
-| [lark-slides-replace-slide.md](references/lark-slides-replace-slide.md) | **+replace-slide Shortcut：块级替换/插入，含合法根元素速查与 3350001 排错** |
-| [lark-slides-edit-workflows.md](references/lark-slides-edit-workflows.md) | 编辑已有页面的读-改-写流程与 action 决策树 |
-| [template-index.json](references/template-index.json) | **脚本缓存/轻量路由索引：由 `template_tool.py search` 使用，不是默认阅读入口** |
-| [template-catalog.md](references/template-catalog.md) | **按场景/色调匹配现成 PPT 模板，并定位到页型范围** |
-| [`scripts/template_tool.py`](scripts/template_tool.py) | **可选 Python 辅助脚本：`search` / `summarize` / `extract`，支持 `--layout-tag` 与 `extract --with-summary`** |
-| [`scripts/layout_lint.py`](scripts/layout_lint.py) | **本地预检脚本：先检查 XML well-formed，再检测重叠、越界、页脚碰撞、文本高度风险；不是完整 XSD schema 校验** |
-| [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md) | **XML Schema 精简速查（必读）** |
-| [slide-templates.md](references/slide-templates.md) | 可复制的 Slide XML 模板 |
-| [xml-format-guide.md](references/xml-format-guide.md) | XML 详细结构与示例 |
-| [examples.md](references/examples.md) | CLI 调用示例 |
-| [slides_demo.xml](references/slides_demo.xml) | 真实 PPT 的完整 XML |
-| [slides_xml_schema_definition.xml](references/slides_xml_schema_definition.xml) | **完整 Schema 定义**（唯一协议依据） |
-| [lark-slides-xml-presentations-get.md](references/lark-slides-xml-presentations-get.md) | 读取 PPT 命令详情 |
-| [lark-slides-xml-presentation-slide-create.md](references/lark-slides-xml-presentation-slide-create.md) | 添加幻灯片命令详情 |
-| [lark-slides-xml-presentation-slide-delete.md](references/lark-slides-xml-presentation-slide-delete.md) | 删除幻灯片命令详情 |
-| [lark-slides-xml-presentation-slide-get.md](references/lark-slides-xml-presentation-slide-get.md) | 读取单个幻灯片命令详情 |
-| [lark-slides-xml-presentation-slide-replace.md](references/lark-slides-xml-presentation-slide-replace.md) | 原生 slide.replace API 命令详情 |
-
-> **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。
+| Reference | Purpose |
+| --- | --- |
+| [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md) | Required XML element and attribute quick reference. |
+| [xml-format-guide.md](references/xml-format-guide.md) | Detailed XML structure and examples. |
+| [slides_xml_schema_definition.xml](references/slides_xml_schema_definition.xml) | Full XML schema definition. |
+| [lark-slides-create.md](references/lark-slides-create.md) | `+create` shortcut. |
+| [lark-slides-media-upload.md](references/lark-slides-media-upload.md) | `+media-upload` shortcut. |
+| [lark-slides-replace-slide.md](references/lark-slides-replace-slide.md) | `+replace-slide` shortcut. |
+| [lark-slides-edit-workflows.md](references/lark-slides-edit-workflows.md) | Existing-slide read/modify/write workflows. |
+| [lark-slides-xml-presentations-get.md](references/lark-slides-xml-presentations-get.md) | Raw presentation read API. |
+| [lark-slides-xml-presentation-slide-create.md](references/lark-slides-xml-presentation-slide-create.md) | Raw slide create API. |
+| [lark-slides-xml-presentation-slide-delete.md](references/lark-slides-xml-presentation-slide-delete.md) | Raw slide delete API. |
+| [lark-slides-xml-presentation-slide-get.md](references/lark-slides-xml-presentation-slide-get.md) | Raw slide get API. |
+| [lark-slides-xml-presentation-slide-replace.md](references/lark-slides-xml-presentation-slide-replace.md) | Raw slide replace API. |
+| [examples.md](references/examples.md) | CLI examples. |
+| [slides_demo.xml](references/slides_demo.xml) | Example presentation XML. |

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

@@ -178,7 +178,7 @@ lark-cli slides xml_presentation.slide create --as user \
 | 400 | XML 格式错误 | 检查 `slide.content` 是否是完整 `<slide>` 元素 |
 | 400 | 请求体结构错误 | 检查是否按 `slide.content` 和 `before_slide_id` 包装 |
 | 403 | 权限不足 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope |
-| 3350001 | XML 非 well-formed 或服务端参数校验失败 | 优先检查未转义字符：文本 `Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`；创建前运行 `python3 skills/lark-slides/scripts/layout_lint.py --input <file>` 获取行列和上下文 |
+| 3350001 | XML 非 well-formed 或服务端参数校验失败 | 优先检查未转义字符：文本 `Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`；再检查标签闭合、命名空间、`<content>` 结构和请求体包装 |
 
 ## 注意事项
 
@@ -188,7 +188,7 @@ lark-cli slides xml_presentation.slide create --as user \
 4. **fill / border 写法**: 颜色填充使用 `<fill><fillColor color="..."/></fill>`，边框常用 `<border color="..." width="2"/>`
 5. **插入位置**: 通过 `before_slide_id` 指定插入目标，而不是用 `position`
 6. **JSON 转义**: 如果直接内联 XML，需要正确转义双引号
-7. **本地预检**: 创建前运行 `layout_lint.py --input <file>`；它检查 XML well-formed 和布局风险，不等价于完整 XSD schema 校验
+7. **执行层预检**: 检查 XML well-formed、特殊字符转义、`slide.content` 包装和 `before_slide_id` 位置；布局质量检查不属于本执行层
 8. **建议**: 先使用 `xml_presentations.get` 获取现有结构，再添加新页面
 
 ## 批量添加建议

tests/cli_e2e/drive/drive_pull_dryrun_test.go

@@ -212,40 +212,3 @@ func TestDrive_PullDryRunAcceptsDuplicateRemoteStrategies(t *testing.T) {
 		})
 	}
 }
-
-func TestDrive_PullDryRunAcceptsIfExistsSmart(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
-	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
-	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
-
-	workDir := t.TempDir()
-	if err := os.MkdirAll(filepath.Join(workDir, "local"), 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"drive", "+pull",
-			"--local-dir", "local",
-			"--folder-token", "fldcnE2E001",
-			"--if-exists", "smart",
-			"--dry-run",
-		},
-		WorkDir:   workDir,
-		DefaultAs: "user",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-
-	out := result.Stdout
-	if got := gjson.Get(out, "api.0.method").String(); got != "GET" {
-		t.Fatalf("method = %q, want GET\nstdout:\n%s", got, out)
-	}
-	if got := gjson.Get(out, "folder_token").String(); got != "fldcnE2E001" {
-		t.Fatalf("folder_token = %q, want fldcnE2E001\nstdout:\n%s", got, out)
-	}
-}

tests/cli_e2e/drive/drive_push_dryrun_test.go

@@ -282,40 +282,3 @@ func TestDrive_PushDryRunAcceptsDuplicateRemoteStrategies(t *testing.T) {
 		})
 	}
 }
-
-func TestDrive_PushDryRunAcceptsIfExistsSmart(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
-	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
-	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
-
-	workDir := t.TempDir()
-	if err := os.MkdirAll(filepath.Join(workDir, "local"), 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"drive", "+push",
-			"--local-dir", "local",
-			"--folder-token", "fldcnE2E001",
-			"--if-exists", "smart",
-			"--dry-run",
-		},
-		WorkDir:   workDir,
-		DefaultAs: "user",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-
-	out := result.Stdout
-	if got := gjson.Get(out, "api.0.method").String(); got != "GET" {
-		t.Fatalf("method = %q, want GET\nstdout:\n%s", got, out)
-	}
-	if got := gjson.Get(out, "folder_token").String(); got != "fldcnE2E001" {
-		t.Fatalf("folder_token = %q, want fldcnE2E001\nstdout:\n%s", got, out)
-	}
-}

tests/cli_e2e/drive/drive_status_dryrun_test.go

@@ -70,50 +70,6 @@ func TestDrive_StatusDryRun(t *testing.T) {
 	}
 }
 
-func TestDrive_StatusDryRunQuick(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
-	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
-	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
-
-	workDir := t.TempDir()
-	if err := os.MkdirAll(filepath.Join(workDir, "local"), 0o755); err != nil {
-		t.Fatalf("MkdirAll: %v", err)
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"drive", "+status",
-			"--local-dir", "local",
-			"--folder-token", "fldcnE2E001",
-			"--quick",
-			"--dry-run",
-		},
-		WorkDir:   workDir,
-		DefaultAs: "user",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-
-	out := result.Stdout
-	if got := gjson.Get(out, "api.0.method").String(); got != "GET" {
-		t.Fatalf("method = %q, want GET\nstdout:\n%s", got, out)
-	}
-	if got := gjson.Get(out, "api.0.url").String(); got != "/open-apis/drive/v1/files" {
-		t.Fatalf("url = %q, want /open-apis/drive/v1/files\nstdout:\n%s", got, out)
-	}
-	if got := gjson.Get(out, "folder_token").String(); got != "fldcnE2E001" {
-		t.Fatalf("folder_token = %q, want fldcnE2E001\nstdout:\n%s", got, out)
-	}
-	desc := gjson.Get(out, "description").String()
-	if !strings.Contains(desc, "modified_time") || strings.Contains(desc, "SHA-256") {
-		t.Fatalf("quick description must mention modified_time and skip SHA-256 wording, got %q\nstdout:\n%s", desc, out)
-	}
-}
-
 // TestDrive_StatusDryRunRejectsAbsoluteLocalDir confirms that the
 // --local-dir path validator runs in the real binary's Validate stage and
 // surfaces a structured error referencing --local-dir (not the framework

tests/cli_e2e/drive/drive_status_workflow_test.go

@@ -5,10 +5,8 @@ package drive
 
 import (
 	"context"
-	"fmt"
 	"os"
 	"path/filepath"
-	"strconv"
 	"testing"
 	"time"
 
@@ -185,266 +183,4 @@ func TestDrive_StatusWorkflow(t *testing.T) {
 			t.Errorf("data.%s length=%d want %d\nstdout:\n%s", b.bucket, got, b.want, out)
 		}
 	}
-
-	quickResult, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"drive", "+status",
-			"--local-dir", "local",
-			"--folder-token", folderToken,
-			"--quick",
-		},
-		WorkDir:   workDir,
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	quickResult.AssertExitCode(t, 0)
-	quickResult.AssertStdoutStatus(t, true)
-
-	quickOut := quickResult.Stdout
-	if got := gjson.Get(quickOut, "data.detection").String(); got != "quick" {
-		t.Fatalf("quick detection=%q want quick\nstdout:\n%s", got, quickOut)
-	}
-	if got := int(gjson.Get(quickOut, "data.new_local.#").Int()); got != 1 {
-		t.Fatalf("quick new_local length=%d want 1\nstdout:\n%s", got, quickOut)
-	}
-	if got := int(gjson.Get(quickOut, "data.new_remote.#").Int()); got != 1 {
-		t.Fatalf("quick new_remote length=%d want 1\nstdout:\n%s", got, quickOut)
-	}
-	if got := gjson.Get(quickOut, "data.new_local.0.rel_path").String(); got != "local-only.txt" {
-		t.Fatalf("quick new_local path=%q want local-only.txt\nstdout:\n%s", got, quickOut)
-	}
-	if got := gjson.Get(quickOut, "data.new_remote.0.rel_path").String(); got != "remote-only.txt" {
-		t.Fatalf("quick new_remote path=%q want remote-only.txt\nstdout:\n%s", got, quickOut)
-	}
-	sharedCount := int(gjson.Get(quickOut, "data.modified.#").Int() + gjson.Get(quickOut, "data.unchanged.#").Int())
-	if sharedCount != 2 {
-		t.Fatalf("quick shared file count=%d want 2 across modified+unchanged\nstdout:\n%s", sharedCount, quickOut)
-	}
-	for _, path := range []string{"unchanged.txt", "modified.txt"} {
-		if !gjson.Get(quickOut, `data.modified.#(rel_path="`+path+`")`).Exists() && !gjson.Get(quickOut, `data.unchanged.#(rel_path="`+path+`")`).Exists() {
-			t.Fatalf("quick output missing shared path %q\nstdout:\n%s", path, quickOut)
-		}
-	}
-}
-
-// TestDrive_StatusQuickWorkflow proves that --quick really follows modified_time
-// semantics on the live backend instead of silently behaving like the default
-// exact hash mode.
-//
-// The fixture intentionally makes the two shared files diverge in opposite ways:
-// - same-mtime.txt:   bytes differ, mtime matches remote   → quick=unchanged / exact=modified
-// - remote-newer.txt: bytes match, local mtime is older    → quick=modified  / exact=unchanged
-//
-// This locks in the best-effort nature of quick mode with real Drive
-// modified_time values fetched from the list API, plus the expected new_local /
-// new_remote buckets.
-func TestDrive_StatusQuickWorkflow(t *testing.T) {
-	parentT := t
-	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
-	t.Cleanup(cancel)
-
-	suffix := clie2e.GenerateSuffix()
-	folderName := "lark-cli-e2e-drive-status-quick-" + suffix
-	folderToken := createDriveFolder(t, parentT, ctx, folderName, "")
-
-	workDir := t.TempDir()
-	if err := os.MkdirAll(filepath.Join(workDir, "local"), 0o755); err != nil {
-		t.Fatalf("mkdir local: %v", err)
-	}
-
-	writeLocal := func(rel, content string) {
-		t.Helper()
-		full := filepath.Join(workDir, rel)
-		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
-			t.Fatalf("mkdir parent of %s: %v", rel, err)
-		}
-		if err := os.WriteFile(full, []byte(content), 0o644); err != nil {
-			t.Fatalf("write %s: %v", rel, err)
-		}
-	}
-
-	uploadDriveFile := func(name, content string) string {
-		t.Helper()
-		stage := "_upload_" + name
-		writeLocal(stage, content)
-		t.Cleanup(func() { _ = os.Remove(filepath.Join(workDir, stage)) })
-
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{
-			Args: []string{
-				"drive", "+upload",
-				"--file", stage,
-				"--folder-token", folderToken,
-				"--name", name,
-			},
-			WorkDir:   workDir,
-			DefaultAs: "bot",
-		})
-		require.NoError(t, err)
-		result.AssertExitCode(t, 0)
-		result.AssertStdoutStatus(t, true)
-
-		fileToken := gjson.Get(result.Stdout, "data.file_token").String()
-		require.NotEmpty(t, fileToken, "uploaded file should have a token, stdout:\n%s", result.Stdout)
-
-		parentT.Cleanup(func() {
-			cleanupCtx, cleanupCancel := clie2e.CleanupContext()
-			defer cleanupCancel()
-			deleteResult, deleteErr := clie2e.RunCmdWithRetry(cleanupCtx, clie2e.Request{
-				Args:      []string{"drive", "+delete", "--file-token", fileToken, "--type", "file", "--yes"},
-				DefaultAs: "bot",
-			}, clie2e.RetryOptions{})
-			clie2e.ReportCleanupFailure(parentT, "delete drive file "+fileToken, deleteResult, deleteErr)
-		})
-		return fileToken
-	}
-
-	tokSameMtime := uploadDriveFile("same-mtime.txt", "remote bytes A")
-	tokRemoteNewer := uploadDriveFile("remote-newer.txt", "remote bytes B")
-	tokRemoteOnly := uploadDriveFile("remote-only.txt", "remote only")
-
-	remoteFiles := listDriveFolderFilesByName(t, ctx, folderToken)
-	sameMtimeRemote := remoteFiles["same-mtime.txt"]
-	remoteNewer := remoteFiles["remote-newer.txt"]
-	if sameMtimeRemote.ModifiedTime == "" || remoteNewer.ModifiedTime == "" {
-		t.Fatalf("expected modified_time for shared remote files, got: %#v", remoteFiles)
-	}
-
-	writeLocal("local/same-mtime.txt", "local bytes A")    // bytes differ from remote
-	writeLocal("local/remote-newer.txt", "remote bytes B") // bytes match remote
-	writeLocal("local/local-only.txt", "local only")       // local-only bucket
-
-	sameMtimePath := filepath.Join(workDir, "local", "same-mtime.txt")
-	remoteNewerPath := filepath.Join(workDir, "local", "remote-newer.txt")
-	sameMtimeAt := mustParseDriveEpochForE2E(t, sameMtimeRemote.ModifiedTime)
-	remoteNewerAt := mustParseDriveEpochForE2E(t, remoteNewer.ModifiedTime)
-	if err := os.Chtimes(sameMtimePath, sameMtimeAt, sameMtimeAt); err != nil {
-		t.Fatalf("chtimes same-mtime.txt: %v", err)
-	}
-	localOlder := remoteNewerAt.Add(-2 * time.Second)
-	if err := os.Chtimes(remoteNewerPath, localOlder, localOlder); err != nil {
-		t.Fatalf("chtimes remote-newer.txt: %v", err)
-	}
-
-	quickResult, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"drive", "+status",
-			"--local-dir", "local",
-			"--folder-token", folderToken,
-			"--quick",
-		},
-		WorkDir:   workDir,
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	quickResult.AssertExitCode(t, 0)
-	quickResult.AssertStdoutStatus(t, true)
-
-	quickOut := quickResult.Stdout
-	if got := gjson.Get(quickOut, "data.detection").String(); got != "quick" {
-		t.Fatalf("quick detection=%q want quick\nstdout:\n%s", got, quickOut)
-	}
-	assertStatusBucketEntry(t, quickOut, "unchanged", "same-mtime.txt", tokSameMtime)
-	assertStatusBucketEntry(t, quickOut, "modified", "remote-newer.txt", tokRemoteNewer)
-	assertStatusBucketEntry(t, quickOut, "new_local", "local-only.txt", "")
-	assertStatusBucketEntry(t, quickOut, "new_remote", "remote-only.txt", tokRemoteOnly)
-	assertStatusBucketLen(t, quickOut, "unchanged", 1)
-	assertStatusBucketLen(t, quickOut, "modified", 1)
-	assertStatusBucketLen(t, quickOut, "new_local", 1)
-	assertStatusBucketLen(t, quickOut, "new_remote", 1)
-
-	exactResult, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"drive", "+status",
-			"--local-dir", "local",
-			"--folder-token", folderToken,
-		},
-		WorkDir:   workDir,
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	exactResult.AssertExitCode(t, 0)
-	exactResult.AssertStdoutStatus(t, true)
-
-	exactOut := exactResult.Stdout
-	if got := gjson.Get(exactOut, "data.detection").String(); got != "exact" {
-		t.Fatalf("exact detection=%q want exact\nstdout:\n%s", got, exactOut)
-	}
-	assertStatusBucketEntry(t, exactOut, "modified", "same-mtime.txt", tokSameMtime)
-	assertStatusBucketEntry(t, exactOut, "unchanged", "remote-newer.txt", tokRemoteNewer)
-	assertStatusBucketEntry(t, exactOut, "new_local", "local-only.txt", "")
-	assertStatusBucketEntry(t, exactOut, "new_remote", "remote-only.txt", tokRemoteOnly)
-	assertStatusBucketLen(t, exactOut, "unchanged", 1)
-	assertStatusBucketLen(t, exactOut, "modified", 1)
-	assertStatusBucketLen(t, exactOut, "new_local", 1)
-	assertStatusBucketLen(t, exactOut, "new_remote", 1)
-}
-
-type driveStatusListedFile struct {
-	Token        string
-	ModifiedTime string
-}
-
-func listDriveFolderFilesByName(t *testing.T, ctx context.Context, folderToken string) map[string]driveStatusListedFile {
-	t.Helper()
-	params := fmt.Sprintf(`{"folder_token":"%s","page_size":200}`, folderToken)
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args:      []string{"drive", "files", "list", "--params", params},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-
-	files := make(map[string]driveStatusListedFile)
-	gjson.Get(result.Stdout, "data.files").ForEach(func(_, entry gjson.Result) bool {
-		name := entry.Get("name").String()
-		if name == "" {
-			return true
-		}
-		files[name] = driveStatusListedFile{
-			Token:        entry.Get("token").String(),
-			ModifiedTime: entry.Get("modified_time").String(),
-		}
-		return true
-	})
-	return files
-}
-
-func mustParseDriveEpochForE2E(t *testing.T, raw string) time.Time {
-	t.Helper()
-	v, err := strconv.ParseInt(raw, 10, 64)
-	if err != nil {
-		t.Fatalf("parse Drive epoch %q: %v", raw, err)
-	}
-	switch {
-	case v > 1e14 || v < -1e14:
-		return time.UnixMicro(v)
-	case v > 1e11 || v < -1e11:
-		return time.UnixMilli(v)
-	default:
-		return time.Unix(v, 0)
-	}
-}
-
-func assertStatusBucketEntry(t *testing.T, stdout, bucket, relPath, fileToken string) {
-	t.Helper()
-	entry := gjson.Get(stdout, `data.`+bucket+`.#(rel_path="`+relPath+`")`)
-	if !entry.Exists() {
-		t.Fatalf("bucket %s missing rel_path %q\nstdout:\n%s", bucket, relPath, stdout)
-	}
-	if fileToken == "" {
-		if got := entry.Get("file_token").String(); got != "" {
-			t.Fatalf("bucket %s rel_path %q unexpectedly carried file_token=%q\nstdout:\n%s", bucket, relPath, got, stdout)
-		}
-		return
-	}
-	if got := entry.Get("file_token").String(); got != fileToken {
-		t.Fatalf("bucket %s rel_path %q file_token=%q want %q\nstdout:\n%s", bucket, relPath, got, fileToken, stdout)
-	}
-}
-
-func assertStatusBucketLen(t *testing.T, stdout, bucket string, want int) {
-	t.Helper()
-	if got := int(gjson.Get(stdout, "data."+bucket+".#").Int()); got != want {
-		t.Fatalf("bucket %s length=%d want %d\nstdout:\n%s", bucket, got, want, stdout)
-	}
 }