chore(release): v1.0.32 (#918)

Change-Id: I3d1a8ec4faf1ce585fb9eae45287bf02586e3e90

.gitignore

@@ -39,3 +39,4 @@ cmd/api/download.bin
 app.log
 /sidecar-server-demo
 /server-demo
+.tmp/

.gitleaks.toml

@@ -14,3 +14,4 @@ id = "lark-session-token"
 description = "Detect Lark session tokens"
 regex = '''\bXN0YXJ0-[A-Za-z0-9_-]+-WVuZA\b'''
 keywords = ["XN0YXJ0-", "-WVuZA"]
+

AGENTS.md

@@ -15,6 +15,22 @@ make unit-test      # Required before PR (runs with -race)
 make test           # Full: vet + unit + integration
 ```
 
+## Notification Opt-Outs
+
+`lark-cli` emits two notice types into JSON envelope `_notice` to nudge AI agents toward fixes:
+
+- `_notice.update` — a newer binary is available on npm
+- `_notice.skills` — locally installed skills are out of sync with the running binary
+
+To suppress them in non-CI scripts (CI envs are auto-skipped):
+
+| Env var | Effect |
+|---------|--------|
+| `LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1` | Suppress `_notice.update` |
+| `LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1` | Suppress `_notice.skills` |
+
+Both notices recommend the same fix command: `lark-cli update`. The skills notice's `current` field is `""` when skills have never been synced (cold start) and a version string when synced for an older binary (drift).
+
 ## Pre-PR Checks (match CI gates)
 
 1. `make unit-test`

CHANGELOG.md

@@ -2,6 +2,130 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.32] - 2026-05-15
+
+### Features
+
+- **doc**: Add `--width`/`--height` flags to `docs +media-insert` (#832)
+- **wiki**: Add `+space-list` / `+node-list` / `+node-copy` shortcuts (#392)
+
+### Bug Fixes
+
+- **drive**: Preserve parent token on nested overwrite (#908)
+- **selfupdate**: Use `LookPath` instead of `Executable` for binary verification (#886)
+- **registry**: Wait for background meta refresh before test reset (#894)
+
+### Documentation
+
+- **doc**: Add SVG whiteboard support to `lark-doc` v2 skill (#901)
+- **drive**: Add permission public patch error guidance (#863)
+
+## [v1.0.31] - 2026-05-14
+
+### Features
+
+- **install**: Skip interactive prompts in non-TTY environments (#888)
+- **update**: Recommend `lark-cli update` over `npm install` for AI agents (#884)
+- **im**: Add `--exclude-muted` to `+chat-search` and new `+chat-list` shortcut (#820)
+- **auth**: Add `--exclude` flag and allow combining `--scope` with `--domain`/`--recommend` (#844)
+- **drive**: Add modified-time smart sync mode (#859)
+- **approval**: Add `tasks.add_sign` and `tasks.rollback` methods (#867)
+
+## [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
+
+- **vc**: Add agent meeting join, leave, and events shortcuts (#824)
+- **mail**: Add unknown-flag fuzzy match for `lark-cli mail` commands (#806)
+- **whiteboard**: Pin `whiteboard-cli` to `v0.2.11` in `lark-whiteboard` skill (#850)
+
+### Bug Fixes
+
+- Silence misleading "skills not installed" startup notice (#801)
+
+### Documentation
+
+- **base**: Refine data analysis SOP wording (#784, #849)
+- Update README capability descriptions (#793)
+
+## [v1.0.28] - 2026-05-11
+
+### Features
+
+- **im**: Support UAT for `messages.forward` and add `threads.forward` (#689)
+- **im**: Add flag shortcuts `+flag-create` / `+flag-list` / `+flag-cancel` for message bookmarks (#770)
+
+### Bug Fixes
+
+- **drive**: Handle duplicate remote sync paths (#803)
+
+### Documentation
+
+- **im**: Name `--query` / `--member-ids` in `+chat-search` shortcut row (#812)
+
+## [v1.0.27] - 2026-05-09
+
+### Features
+
+- **config**: Add `lark-channel` as a bind source (#786)
+
+### Bug Fixes
+
+- **install**: Fix installation errors when PowerShell is disabled by Group Policy (#789)
+
+### Documentation
+
+- **task**: Clarify task member id types in references (#777)
+
+## [v1.0.26] - 2026-05-08
+
+### Features
+
+- **im**: Add `message_app_link` to message outputs (#668)
+- **auth**: Add scope hint for missing authorization errors (#776)
+
+### Bug Fixes
+
+- **base**: Clean error detail output (#783)
+- **whiteboard**: Reclassify `+update` as `write` risk (#775)
+
+### Documentation
+
+- **mail**: Add data integrity and write-confirmation rules (#749)
+
+## [v1.0.25] - 2026-05-07
+
+### Features
+
+- Add skills version drift notice and unify update flow (#723)
+
+### Bug Fixes
+
+- Remove misleading default value from `--as` flag help text (#769)
+- Handle negative truncate lengths (#744)
+- Reject invalid JSON pointer escapes (#741)
+- Migrate task shortcut errors to structured `output.Errorf`/`ErrValidation` (#740)
+
+### Documentation
+
+- Clarify base `user_open_id` guidance (#763)
+
 ## [v1.0.24] - 2026-05-06
 
 ### Features
@@ -597,6 +721,14 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.32]: https://github.com/larksuite/cli/releases/tag/v1.0.32
+[v1.0.31]: https://github.com/larksuite/cli/releases/tag/v1.0.31
+[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
+[v1.0.26]: https://github.com/larksuite/cli/releases/tag/v1.0.26
+[v1.0.25]: https://github.com/larksuite/cli/releases/tag/v1.0.25
 [v1.0.24]: https://github.com/larksuite/cli/releases/tag/v1.0.24
 [v1.0.23]: https://github.com/larksuite/cli/releases/tag/v1.0.23
 [v1.0.22]: https://github.com/larksuite/cli/releases/tag/v1.0.22

Makefile

@@ -8,7 +8,9 @@ DATE     := $(shell date +%Y-%m-%d)
 LDFLAGS  := -s -w -X $(MODULE)/internal/build.Version=$(VERSION) -X $(MODULE)/internal/build.Date=$(DATE)
 PREFIX   ?= /usr/local
 
-.PHONY: build vet test unit-test integration-test install uninstall clean fetch_meta
+.PHONY: all build vet test unit-test integration-test install uninstall clean fetch_meta gitleaks
+
+all: test
 
 fetch_meta:
 	python3 scripts/fetch_meta.py
@@ -37,3 +39,13 @@ uninstall:
 
 clean:
 	rm -f $(BINARY)
+
+# Run secret-leak checks locally before pushing.
+# Step 1: check-doc-tokens catches realistic-looking example tokens in reference
+#         docs and asks you to use _EXAMPLE_TOKEN placeholders instead.
+# Step 2: gitleaks scans the full repo for real leaked secrets.
+# Install gitleaks: https://github.com/gitleaks/gitleaks#installing
+gitleaks:
+	@bash scripts/check-doc-tokens.sh
+	@command -v gitleaks >/dev/null 2>&1 || { echo "gitleaks not found. Install: brew install gitleaks"; exit 1; }
+	gitleaks detect --redact -v --exit-code=2

README.md

@@ -24,7 +24,7 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 
 | Category      | Capabilities                                                                                                                      |
 | ------------- |-----------------------------------------------------------------------------------------------------------------------------------|
-| 📅 Calendar   | View agenda, create events, invite attendees, check free/busy status, time suggestions                                            |
+| 📅 Calendar   | View, create and update events, invite attendees, find meeting rooms, RSVP to invitations, check free/busy & time suggestions     |
 | 💬 Messenger  | Send/reply messages, create and manage group chats, view chat history & threads, search messages, download media                  |
 | 📄 Docs       | Create, read, update, and search documents, read/write media & whiteboards                                                        |
 | 📁 Drive      | Upload and download files, search docs & wiki, manage comments                                                                    |
@@ -36,7 +36,7 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 | 📚 Wiki       | Create and manage knowledge spaces, nodes, and documents                                                                          |
 | 👤 Contact    | Search users by name/email/phone, get user profiles                                                                               |
 | 📧 Mail       | Browse, search, read emails, send, reply, forward, manage drafts, watch new mail                                                  |
-| 🎥 Meetings   | Search meeting records, query meeting minutes & recordings                                                                        |
+| 🎥 Meetings   | Search meeting records, query meeting minutes artifacts and recordings                                                            |
 | 🕐 Attendance | Query personal attendance check-in records                                                                                        |
 | ✍️ Approval   | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                                      |
 | 🎯 OKR        | Query, create, update OKRs; manage objective & key results, alignments, indicators and progress.                                  |
@@ -62,11 +62,7 @@ Choose **one** of the following methods:
 **Option 1 — From npm (recommended):**
 
 ```bash
-# Install CLI
-npm install -g @larksuite/cli
-
-# Install CLI SKILL (required)
-npx skills add larksuite/cli -y -g
+npx @larksuite/cli@latest install
 ```
 
 **Option 2 — From source:**
@@ -102,11 +98,7 @@ lark-cli calendar +agenda
 **Step 1 — Install**
 
 ```bash
-# Install CLI
-npm install -g @larksuite/cli
-
-# Install CLI SKILL (required)
-npx skills add larksuite/cli -y -g
+npx @larksuite/cli@latest install
 ```
 
 **Step 2 — Configure app credentials**
@@ -136,7 +128,7 @@ lark-cli auth status
 | Skill                           | Description                                                                                                    |
 | ------------------------------- |----------------------------------------------------------------------------------------------------------------|
 | `lark-shared`                   | App config, auth login, identity switching, scope management, security rules (auto-loaded by all other skills) |
-| `lark-calendar`                 | Calendar events, agenda view, free/busy queries, time suggestions                                              |
+| `lark-calendar`                 | Calendar events (create/update), agenda view, free/busy queries, time suggestions, room finding, RSVP replies  |
 | `lark-im`                       | Send/reply messages, group chat management, message search, upload/download images & files, reactions          |
 | `lark-doc`                      | Create, read, update, search documents (Markdown-based)                                                        |
 | `lark-drive`                    | Upload, download files, manage permissions & comments                                                          |
@@ -151,7 +143,7 @@ lark-cli auth status
 | `lark-event`                    | Real-time event subscriptions (WebSocket), regex routing & agent-friendly format                               |
 | `lark-vc`                       | Search meeting records, query meeting minutes (summary, todos, transcript)                                     |
 | `lark-whiteboard`               | Whiteboard/chart DSL rendering                                                                                 |
-| `lark-minutes`                  | Minutes metadata & AI artifacts (summary, todos, chapters)                                                     |
+| `lark-minutes`                  | Minutes metadata & AI artifacts (summary, todos, chapters); upload audio/video to create minutes, download media |
 | `lark-openapi-explorer`         | Explore underlying APIs from official docs                                                                     |
 | `lark-skill-maker`              | Custom skill creation framework                                                                                |
 | `lark-attendance`               | Query personal attendance check-in records                                                                     |

README.zh.md

@@ -24,7 +24,7 @@
 
 | 类别        | 能力                                         |
 | ------------- |--------------------------------------------|
-| 📅 日历     | 查看日程、创建日程、邀请参会人、查询忙闲状态、时间建议                |
+| 📅 日历     | 查看、创建和更新日程，邀请参会人、查找会议室、回复日程邀请、查询忙闲与时间建议        |
 | 💬 即时通讯 | 发送/回复消息、创建和管理群聊、查看聊天记录与话题、搜索消息、下载媒体文件      |
 | 📄 云文档   | 创建、读取、更新文档、搜索文档、读写素材与画板                    |
 | 📁 云空间   | 上传和下载文件、搜索文档与知识库、管理评论                      |
@@ -36,7 +36,7 @@
 | 📚 知识库   | 创建和管理知识空间、节点和文档                            |
 | 👤 通讯录   | 按姓名/邮箱/手机号搜索用户、获取用户信息                      |
 | 📧 邮箱     | 浏览、搜索、阅读邮件，发送、回复、转发邮件，管理草稿，监听新邮件           |
-| 🎥 视频会议 | 搜索会议记录、查询会议纪要与录制                           |
+| 🎥 视频会议 | 搜索会议记录、查询会议纪要产物与会议录制                        |
 | 🕐 考勤打卡 | 查询个人考勤打卡记录                                |
 | ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
 | 🎯 OKR  | 查询、创建、更新 OKR，管理目标、关键结果、对齐、指标和进展记录        |
@@ -62,11 +62,7 @@
 **方式一 — 从 npm 安装（推荐）：**
 
 ```bash
-# 安装 CLI
-npm install -g @larksuite/cli
-
-# 安装 CLI SKILL（必需）
-npx skills add larksuite/cli -y -g
+npx @larksuite/cli@latest install
 ```
 
 **方式二 — 从源码安装：**
@@ -102,11 +98,7 @@ lark-cli calendar +agenda
 **第 1 步 — 安装**
 
 ```bash
-# 安装 CLI
-npm install -g @larksuite/cli
-
-# 安装 CLI SKILL（必需）
-npx skills add larksuite/cli -y -g
+npx @larksuite/cli@latest install
 ```
 
 **第 2 步 — 配置应用凭证**
@@ -137,7 +129,7 @@ lark-cli auth status
 | Skill                           | 说明                                        |
 | --------------------------------- |-------------------------------------------|
 | `lark-shared`                   | 应用配置、认证登录、身份切换、权限管理、安全规则（所有其他 skill 自动加载） |
-| `lark-calendar`                 | 日历日程、议程查看、忙闲查询、时间建议                       |
+| `lark-calendar`                 | 日历日程（创建/更新）、议程查看、忙闲查询、时间建议、会议室查找、回复邀请       |
 | `lark-im`                       | 发送/回复消息、群聊管理、消息搜索、上传下载图片与文件、表情回复          |
 | `lark-doc`                      | 创建、读取、更新、搜索文档（基于 Markdown）                |
 | `lark-drive`                    | 上传、下载文件，管理权限与评论                           |
@@ -152,7 +144,7 @@ lark-cli auth status
 | `lark-event`                    | 实时事件订阅（WebSocket），支持正则路由与 Agent 友好格式      |
 | `lark-vc`                       | 搜索会议记录、查询会议纪要产物（总结、待办、逐字稿）                |
 | `lark-whiteboard`               | 画板/图表 DSL 渲染                              |
-| `lark-minutes`                  | 妙记元数据与 AI 产物（总结、待办、章节）                    |
+| `lark-minutes`                  | 妙记元数据与 AI 产物（总结、待办、章节），上传音视频生成妙记，下载音视频文件 |
 | `lark-openapi-explorer`         | 从官方文档探索底层 API                             |
 | `lark-skill-maker`              | 自定义 skill 创建框架                            |
 | `lark-attendance`               | 查询个人考勤打卡记录                                |

cmd/auth/login.go

@@ -30,6 +30,7 @@ type LoginOptions struct {
 	Scope      string
 	Recommend  bool
 	Domains    []string
+	Exclude    []string
 	NoWait     bool
 	DeviceCode string
 }
@@ -62,11 +63,13 @@ 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-separated)")
+	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space- or comma-separated). Combines additively with --domain/--recommend")
 	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")
@@ -158,6 +161,10 @@ 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)
@@ -185,14 +192,17 @@ func authLoginRun(opts *LoginOptions) error {
 		}
 	}
 
-	finalScope := opts.Scope
+	// 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)
 
-	// Resolve scopes from domain/permission filters
+	// 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.
 	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")
@@ -206,11 +216,35 @@ func authLoginRun(opts *LoginOptions) error {
 			candidateScopes = registry.FilterAutoApproveScopes(candidateScopes)
 		}
 
-		if len(candidateScopes) == 0 {
+		if len(candidateScopes) == 0 && opts.Scope == "" {
 			return output.ErrValidation("no matching scopes found, check domain/scope options")
 		}
 
-		finalScope = strings.Join(candidateScopes, " ")
+		// 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")
+		}
 	}
 
 	// Step 1: Request device authorization
@@ -232,7 +266,7 @@ func authLoginRun(opts *LoginOptions) error {
 			"verification_url": authResp.VerificationUriComplete,
 			"device_code":      authResp.DeviceCode,
 			"expires_in":       authResp.ExpiresIn,
-			"hint":             fmt.Sprintf("Show verification_url to user, then immediately execute: lark-cli auth login --device-code %s (blocks until authorized or timeout). Do not instruct the user to run this command themselves.", authResp.DeviceCode),
+			"hint":             fmt.Sprintf("Show verification_url to the user exactly as returned by the CLI and treat it as an opaque string. Do not URL-encode or decode it, do not normalize or rewrite it, do not add %%20, spaces, or punctuation, and do not wrap it as Markdown link text; prefer a fenced code block containing only the raw URL. Then immediately execute: lark-cli auth login --device-code %s (blocks until authorized or timeout). Do not instruct the user to run this command themselves.", authResp.DeviceCode),
 		}
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
@@ -473,7 +507,7 @@ func collectScopesForDomains(domains []string, identity string) []string {
 	// 3. Shortcut scopes matching by Service (only include shortcuts supporting the identity)
 	for _, sc := range shortcuts.AllShortcuts() {
 		if domainSet[sc.Service] && shortcutSupportsIdentity(sc, identity) {
-			for _, s := range sc.ScopesForIdentity(identity) {
+			for _, s := range sc.DeclaredScopesForIdentity(identity) {
 				scopeSet[s] = true
 			}
 		}
@@ -532,6 +566,40 @@ 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
@@ -542,3 +610,58 @@ 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_messages.go

@@ -59,7 +59,7 @@ var loginMsgZh = &loginMsg{
 
 	OpenURL:            "在浏览器中打开以下链接进行认证:\n\n",
 	WaitingAuth:        "等待用户授权...",
-	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout ≥ 600s；如不支持长 timeout，请改用 `lark-cli auth login --no-wait --json` 拿到 device_code 后再用 `lark-cli auth login --device-code <code>` 续上轮询，**不要短 timeout 反复重试**——每次重启会作废上一轮的 device code，导致用户授权的链接失效。",
+	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout >= 600s；如不支持长 timeout，请改用 `lark-cli auth login --no-wait --json` 拿到 device_code 后再用 `lark-cli auth login --device-code <code>` 续上轮询。**不要短 timeout 反复重试**，每次重启会作废上一轮的 device code，导致用户授权链接失效。向用户展示授权链接时，必须逐字原样转发 CLI 返回的 URL，把它视为不可修改的 opaque string；不要做 URL 编码或解码，不要补 `%20`、空格或标点，不要改写成 Markdown 链接，建议用只包含该 URL 的代码块单独输出。",
 	AuthSuccess:        "已收到授权确认，正在获取用户信息并校验授权结果...",
 	LoginSuccess:       "授权成功! 用户: %s (%s)",
 	AuthorizedUser:     "当前授权账号: %s (%s)",
@@ -95,7 +95,7 @@ var loginMsgEn = &loginMsg{
 
 	OpenURL:            "Open this URL in your browser to authenticate:\n\n",
 	WaitingAuth:        "Waiting for user authorization...",
-	AgentTimeoutHint:   "[AI agent] This command blocks for up to ~10 minutes while waiting for the user to authorize in their browser. Make sure your runner's timeout is ≥ 600s. If long timeouts are not supported, use `lark-cli auth login --no-wait --json` to get a device_code, then `lark-cli auth login --device-code <code>` to resume polling. **Do NOT retry with a short timeout** — each restart invalidates the previous device code, so any URL the user already authorized becomes useless.",
+	AgentTimeoutHint:   "[AI agent] This command blocks for up to ~10 minutes while waiting for the user to authorize in their browser. Make sure your runner's timeout is >= 600s. If long timeouts are not supported, use `lark-cli auth login --no-wait --json` to get a device_code, then `lark-cli auth login --device-code <code>` to resume polling. **Do NOT retry with a short timeout**; each restart invalidates the previous device code and makes the earlier authorization URL useless. When showing the authorization URL to the user, copy the CLI-returned URL exactly as-is and treat it as an opaque string. Do not URL-encode or decode it, do not add `%20`, spaces, or punctuation, do not rewrite it as Markdown link text, and prefer a fenced code block containing only the raw URL.",
 	AuthSuccess:        "Authorization confirmed, fetching user info and validating granted scopes...",
 	LoginSuccess:       "Authorization successful! User: %s (%s)",
 	AuthorizedUser:     "Authorized account: %s (%s)",

cmd/auth/login_test.go

@@ -70,6 +70,32 @@ 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}
@@ -879,6 +905,57 @@ func TestAuthLoginRun_JSONWriteFailure_NoWaitReturnsWriterError(t *testing.T) {
 	}
 }
 
+func TestAuthLoginRun_NoWaitJSONHintIncludesRawURLGuidance(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		ProfileName: "default",
+		AppID:       "cli_test",
+		AppSecret:   "secret",
+		Brand:       core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    larkauth.PathDeviceAuthorization,
+		Body: map[string]interface{}{
+			"device_code":               "device-code",
+			"user_code":                 "user-code",
+			"verification_uri":          "https://example.com/verify",
+			"verification_uri_complete": "https://example.com/verify?code=123",
+			"expires_in":                240,
+			"interval":                  5,
+		},
+	})
+
+	err := authLoginRun(&LoginOptions{
+		Factory: f,
+		Ctx:     context.Background(),
+		Scope:   "im:message:send",
+		NoWait:  true,
+	})
+	if err != nil {
+		t.Fatalf("authLoginRun() error = %v", err)
+	}
+
+	dec := json.NewDecoder(strings.NewReader(stdout.String()))
+	var data map[string]interface{}
+	if err := dec.Decode(&data); err != nil {
+		t.Fatalf("Decode(stdout first event) error = %v, stdout=%q", err, stdout.String())
+	}
+	hint, _ := data["hint"].(string)
+	for _, want := range []string{
+		"exactly as returned by the CLI",
+		"opaque string",
+		"Do not URL-encode or decode it",
+		"do not add %20, spaces, or punctuation",
+		"do not wrap it as Markdown link text",
+		"fenced code block containing only the raw URL",
+	} {
+		if !strings.Contains(hint, want) {
+			t.Fatalf("hint missing %q, got:\n%s", want, hint)
+		}
+	}
+}
+
 func TestAuthLoginRun_JSONWriteFailure_DeviceAuthorizationReturnsWriterError(t *testing.T) {
 	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
 		ProfileName: "default",
@@ -917,6 +994,60 @@ func TestAuthLoginRun_JSONWriteFailure_DeviceAuthorizationReturnsWriterError(t *
 	}
 }
 
+func TestAuthLoginRun_JSONDeviceAuthorizationAgentHintIncludesRawURLGuidance(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		ProfileName: "default",
+		AppID:       "cli_test",
+		AppSecret:   "secret",
+		Brand:       core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    larkauth.PathDeviceAuthorization,
+		Body: map[string]interface{}{
+			"device_code":               "device-code",
+			"user_code":                 "user-code",
+			"verification_uri":          "https://example.com/verify",
+			"verification_uri_complete": "https://example.com/verify?code=123",
+			"expires_in":                240,
+			"interval":                  5,
+		},
+	})
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	err := authLoginRun(&LoginOptions{
+		Factory: f,
+		Ctx:     ctx,
+		Scope:   "im:message:send",
+		JSON:    true,
+	})
+	if err == nil {
+		t.Fatal("expected error from cancelled context")
+	}
+
+	dec := json.NewDecoder(strings.NewReader(stdout.String()))
+	var data map[string]interface{}
+	if err := dec.Decode(&data); err != nil {
+		t.Fatalf("Decode(stdout first event) error = %v, stdout=%q", err, stdout.String())
+	}
+	hint, _ := data["agent_hint"].(string)
+	for _, want := range []string{
+		"timeout >= 600s",
+		"逐字原样转发 CLI 返回的 URL",
+		"opaque string",
+		"不要做 URL 编码或解码",
+		"不要补 `%20`、空格或标点",
+		"不要改写成 Markdown 链接",
+		"只包含该 URL 的代码块单独输出",
+	} {
+		if !strings.Contains(hint, want) {
+			t.Fatalf("agent_hint missing %q, got:\n%s", want, hint)
+		}
+	}
+}
+
 func TestGetDomainMetadata_ExcludesEvent(t *testing.T) {
 	domains := getDomainMetadata("zh")
 	for _, dm := range domains {

cmd/build.go

@@ -109,6 +109,7 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	RegisterGlobalFlags(rootCmd.PersistentFlags(), &cfg.globals)
 	rootCmd.PersistentPreRun = func(cmd *cobra.Command, args []string) {
 		cmd.SilenceUsage = true
+		f.CurrentCommand = cmd
 	}
 
 	rootCmd.AddCommand(cmdconfig.NewCmdConfig(f))

cmd/config/bind.go

@@ -60,9 +60,9 @@ func NewCmdConfigBind(f *cmdutil.Factory, runF func(*BindOptions) error) *cobra.
 	cmd := &cobra.Command{
 		Use:   "bind",
 		Short: "Bind Agent config to a workspace (source / app-id / force)",
-		Long: `Bind an AI Agent's (OpenClaw / Hermes) Feishu credentials to a lark-cli workspace.
+		Long: `Bind an AI Agent's (OpenClaw / Hermes / Lark Channel) Feishu credentials to a lark-cli workspace.
 
---source is auto-detected from env (OPENCLAW_HOME / HERMES_HOME); pass it only to override.
+--source is auto-detected from env (OPENCLAW_HOME / HERMES_HOME / LARK_CHANNEL); pass it only to override.
 
 For AI agents — DO NOT bind without user confirmation. Binding may
 overwrite an existing one and locks in an identity policy. Ask the user:
@@ -85,6 +85,7 @@ Interactive terminal use: run with no flags to enter the TUI form.`,
 		Example: `  # AI flow: confirm intent + identity with user FIRST, then run:
   lark-cli config bind --source openclaw --app-id <id> --identity bot-only
   lark-cli config bind --source hermes --identity user-default
+  lark-cli config bind --source lark-channel
 
   # Interactive (terminal user) — TUI prompts for everything:
   lark-cli config bind`,
@@ -97,7 +98,7 @@ Interactive terminal use: run with no flags to enter the TUI form.`,
 		},
 	}
 
-	cmd.Flags().StringVar(&opts.Source, "source", "", "Agent source to bind from (openclaw|hermes); auto-detected from env signals when omitted")
+	cmd.Flags().StringVar(&opts.Source, "source", "", "Agent source to bind from (openclaw|hermes|lark-channel); auto-detected from env signals when omitted")
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID to bind (required for OpenClaw multi-account)")
 	cmd.Flags().StringVar(&opts.Identity, "identity", "", "identity preset (bot-only|user-default); defaults to bot-only in flag mode (safer: no impersonation)")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "confirm a risky transition (currently: bot-only → user-default identity change in flag mode)")
@@ -175,8 +176,8 @@ type existingBinding struct {
 //     fall back to a TUI prompt (TUI mode) or an error (flag mode).
 func finalizeSource(opts *BindOptions) (string, error) {
 	explicit := strings.TrimSpace(strings.ToLower(opts.Source))
-	if explicit != "" && explicit != "openclaw" && explicit != "hermes" {
-		return "", output.ErrValidation("invalid --source %q; valid values: openclaw, hermes", explicit)
+	if explicit != "" && explicit != "openclaw" && explicit != "hermes" && explicit != "lark-channel" {
+		return "", output.ErrValidation("invalid --source %q; valid values: openclaw, hermes, lark-channel", explicit)
 	}
 
 	var detected string
@@ -185,6 +186,8 @@ func finalizeSource(opts *BindOptions) (string, error) {
 		detected = "openclaw"
 	case core.WorkspaceHermes:
 		detected = "hermes"
+	case core.WorkspaceLarkChannel:
+		detected = "lark-channel"
 	}
 
 	// Explicit and env detection must agree when both are present. Reject
@@ -221,7 +224,7 @@ func finalizeSource(opts *BindOptions) (string, error) {
 	}
 	return "", output.ErrWithHint(output.ExitValidation, "bind",
 		"cannot determine Agent source: no --source flag and no Agent environment detected",
-		"pass --source openclaw|hermes, or run this command inside an OpenClaw or Hermes chat")
+		"pass --source openclaw|hermes|lark-channel, or run this command inside the corresponding Agent context")
 }
 
 // reconcileExistingBinding reads any existing config at configPath and decides
@@ -467,6 +470,8 @@ func tuiSelectSource(opts *BindOptions) (string, error) {
 		source = "openclaw"
 	case core.WorkspaceHermes:
 		source = "hermes"
+	case core.WorkspaceLarkChannel:
+		source = "lark-channel"
 	default:
 		source = "openclaw" // default first option
 	}
@@ -474,6 +479,7 @@ func tuiSelectSource(opts *BindOptions) (string, error) {
 	// Resolve actual paths for display
 	openclawPath := resolveOpenClawConfigPath()
 	hermesEnvPath := resolveHermesEnvPath()
+	larkChannelPath := resolveLarkChannelConfigPath()
 
 	form := huh.NewForm(
 		huh.NewGroup(
@@ -483,6 +489,7 @@ func tuiSelectSource(opts *BindOptions) (string, error) {
 				Options(
 					huh.NewOption(fmt.Sprintf(msg.SourceOpenClaw, openclawPath), "openclaw"),
 					huh.NewOption(fmt.Sprintf(msg.SourceHermes, hermesEnvPath), "hermes"),
+					huh.NewOption(fmt.Sprintf(msg.SourceLarkChannel, larkChannelPath), "lark-channel"),
 				).
 				Value(&source),
 		),

cmd/config/bind_messages.go

@@ -12,10 +12,11 @@ package config
 type bindMsg struct {
 	// Source selection.
 	// SelectSourceDesc format: brand.
-	SelectSource     string
-	SelectSourceDesc string
-	SourceOpenClaw   string // format: resolved config path.
-	SourceHermes     string // format: resolved dotenv path.
+	SelectSource      string
+	SelectSourceDesc  string
+	SourceOpenClaw    string // format: resolved config path.
+	SourceHermes      string // format: resolved dotenv path.
+	SourceLarkChannel string // format: resolved config path.
 
 	// Account selection (OpenClaw multi-account).
 	// Format: source display name ("OpenClaw" | "Hermes"), brand.
@@ -86,10 +87,11 @@ type bindMsg struct {
 }
 
 var bindMsgZh = &bindMsg{
-	SelectSource:     "你想在哪个 Agent 中使用 lark-cli?",
-	SelectSourceDesc: "从你选择的 Agent 中获取%s应用信息，并配置到 lark-cli 中",
-	SourceOpenClaw:   "OpenClaw — 配置文件: %s",
-	SourceHermes:     "Hermes — 配置文件: %s",
+	SelectSource:      "你想在哪个 Agent 中使用 lark-cli?",
+	SelectSourceDesc:  "从你选择的 Agent 中获取%s应用信息，并配置到 lark-cli 中",
+	SourceOpenClaw:    "OpenClaw — 配置文件: %s",
+	SourceHermes:      "Hermes — 配置文件: %s",
+	SourceLarkChannel: "Lark Channel — 配置文件: %s",
 
 	SelectAccount: "检测到 %s 中已配置多个%s应用，请选择一个",
 
@@ -117,10 +119,11 @@ var bindMsgZh = &bindMsg{
 }
 
 var bindMsgEn = &bindMsg{
-	SelectSource:     "Which Agent are you running?",
-	SelectSourceDesc: "lark-cli will read your %s app credentials from the selected Agent and apply them automatically.",
-	SourceOpenClaw:   "OpenClaw — config: %s",
-	SourceHermes:     "Hermes — config: %s",
+	SelectSource:      "Which Agent are you running?",
+	SelectSourceDesc:  "lark-cli will read your %s app credentials from the selected Agent and apply them automatically.",
+	SourceOpenClaw:    "OpenClaw — config: %s",
+	SourceHermes:      "Hermes — config: %s",
+	SourceLarkChannel: "Lark Channel — config: %s",
 
 	// Args order (source, brand) matches the Chinese template; %[N]s lets the
 	// English reading order differ while the caller passes args in one order.

cmd/config/bind_test.go

@@ -123,7 +123,7 @@ func TestConfigBindRun_InvalidSource(t *testing.T) {
 	err := configBindRun(&BindOptions{Factory: f, Source: "invalid"})
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
 		Type:    "validation",
-		Message: `invalid --source "invalid"; valid values: openclaw, hermes`,
+		Message: `invalid --source "invalid"; valid values: openclaw, hermes, lark-channel`,
 	})
 }
 
@@ -141,21 +141,29 @@ func TestConfigBindRun_MissingSourceNonTTY(t *testing.T) {
 	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
 		Type:    "bind",
 		Message: "cannot determine Agent source: no --source flag and no Agent environment detected",
-		Hint:    "pass --source openclaw|hermes, or run this command inside an OpenClaw or Hermes chat",
+		Hint:    "pass --source openclaw|hermes|lark-channel, or run this command inside the corresponding Agent context",
 	})
 }
 
-// clearAgentEnv removes all env vars that DetectWorkspaceFromEnv checks, so
-// tests exercising the "no signals" path are not affected by whatever the
-// host shell happens to have exported. t.Setenv restores them after the
-// test returns.
+// clearAgentEnv removes every env var that DetectWorkspaceFromEnv treats as
+// an Agent signal, so tests exercising the "no signals" path stay isolated
+// from whatever the host shell exported. Prefix-based instead of an explicit
+// list — when DetectWorkspaceFromEnv gains a new OPENCLAW_* / HERMES_* signal,
+// this helper does not need to be updated and tests do not silently misroute.
+// t.Setenv restores the original values after the test returns.
 func clearAgentEnv(t *testing.T) {
 	t.Helper()
-	for _, k := range []string{
-		"OPENCLAW_CLI", "OPENCLAW_HOME", "OPENCLAW_STATE_DIR", "OPENCLAW_CONFIG_PATH",
-		"HERMES_HOME", "HERMES_QUIET", "HERMES_EXEC_ASK", "HERMES_GATEWAY_TOKEN", "HERMES_SESSION_KEY",
-	} {
-		t.Setenv(k, "")
+	for _, kv := range os.Environ() {
+		idx := strings.IndexByte(kv, '=')
+		if idx < 0 {
+			continue
+		}
+		k := kv[:idx]
+		if strings.HasPrefix(k, "OPENCLAW_") ||
+			strings.HasPrefix(k, "HERMES_") ||
+			k == "LARK_CHANNEL" {
+			t.Setenv(k, "")
+		}
 	}
 }
 
@@ -339,6 +347,211 @@ func TestConfigBindRun_OpenClawMissingFile(t *testing.T) {
 	})
 }
 
+// writeLarkChannelFixture writes a ~/.lark-channel/config.json under fakeHome
+// and returns the config path. resolveLarkChannelConfigPath reads HOME via
+// os.UserHomeDir, so callers must `t.Setenv("HOME", fakeHome)`.
+func writeLarkChannelFixture(t *testing.T, fakeHome, body string) string {
+	t.Helper()
+	dir := filepath.Join(fakeHome, ".lark-channel")
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	path := filepath.Join(dir, "config.json")
+	if err := os.WriteFile(path, []byte(body), 0600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	return path
+}
+
+// Happy-path: --source lark-channel reads ~/.lark-channel/config.json,
+// writes the workspace config, emits a JSON envelope with workspace:
+// "lark-channel" and brand from accounts.app.tenant.
+func TestConfigBindRun_LarkChannel_Success(t *testing.T) {
+	saveWorkspace(t)
+	configDir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
+	clearAgentEnv(t)
+
+	fakeHome := t.TempDir()
+	t.Setenv("HOME", fakeHome)
+	writeLarkChannelFixture(t, fakeHome, `{"accounts":{"app":{"id":"cli_lc_main","secret":"lc_secret","tenant":"feishu"}}}`)
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"}); err != nil {
+		t.Fatalf("expected success, got error: %v", err)
+	}
+
+	envelope := map[string]any{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("invalid JSON output: %v", err)
+	}
+	if envelope["workspace"] != "lark-channel" {
+		t.Errorf("workspace = %v, want %q", envelope["workspace"], "lark-channel")
+	}
+	if envelope["app_id"] != "cli_lc_main" {
+		t.Errorf("app_id = %v, want %q", envelope["app_id"], "cli_lc_main")
+	}
+
+	// Brand is not in the stdout envelope — read it back from the persisted
+	// workspace config to verify accounts.app.tenant flowed through to the
+	// stored AppConfig.Brand field.
+	core.SetCurrentWorkspace(core.WorkspaceLarkChannel)
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("load workspace config: %v", err)
+	}
+	if len(multi.Apps) != 1 {
+		t.Fatalf("expected 1 app, got %d", len(multi.Apps))
+	}
+	if got := string(multi.Apps[0].Brand); got != "feishu" {
+		t.Errorf("Brand = %q, want %q", got, "feishu")
+	}
+}
+
+// Env template form: secret = "${VAR}" should resolve via the SecretInput
+// pipeline (same path openclaw uses), so the keychain receives the env value
+// not the literal template string.
+func TestConfigBindRun_LarkChannel_EnvTemplate(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	clearAgentEnv(t)
+
+	fakeHome := t.TempDir()
+	t.Setenv("HOME", fakeHome)
+	t.Setenv("LARK_APP_SECRET", "resolved_via_env")
+	writeLarkChannelFixture(t, fakeHome,
+		`{"accounts":{"app":{"id":"cli_lc_env","secret":"${LARK_APP_SECRET}","tenant":"feishu"}}}`)
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"}); err != nil {
+		t.Fatalf("expected success, got error: %v", err)
+	}
+}
+
+// tenant: "lark" should land as Brand("lark"), not normalized to "feishu".
+func TestConfigBindRun_LarkChannel_LarkTenant(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	clearAgentEnv(t)
+
+	fakeHome := t.TempDir()
+	t.Setenv("HOME", fakeHome)
+	writeLarkChannelFixture(t, fakeHome, `{"accounts":{"app":{"id":"cli_lc_lark","secret":"s","tenant":"lark"}}}`)
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"}); err != nil {
+		t.Fatalf("expected success, got error: %v", err)
+	}
+	core.SetCurrentWorkspace(core.WorkspaceLarkChannel)
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("load workspace config: %v", err)
+	}
+	if got := string(multi.Apps[0].Brand); got != "lark" {
+		t.Errorf("Brand = %q, want %q (tenant: lark must flow through to AppConfig.Brand)", got, "lark")
+	}
+}
+
+// LARK_CHANNEL=1 alone (no --source) auto-detects to the lark-channel
+// workspace, mirroring the OpenClaw/Hermes auto-detect flow.
+func TestConfigBindRun_AutoDetect_LarkChannelFromEnv(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	clearAgentEnv(t)
+	t.Setenv("LARK_CHANNEL", "1")
+
+	fakeHome := t.TempDir()
+	t.Setenv("HOME", fakeHome)
+	writeLarkChannelFixture(t, fakeHome, `{"accounts":{"app":{"id":"cli_auto_lc","secret":"s","tenant":"feishu"}}}`)
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f}); err != nil {
+		t.Fatalf("expected success, got error: %v", err)
+	}
+	envelope := map[string]any{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("invalid JSON output: %v", err)
+	}
+	if envelope["workspace"] != "lark-channel" {
+		t.Errorf("workspace = %v, want %q (auto-detection should pick lark-channel from LARK_CHANNEL=1)", envelope["workspace"], "lark-channel")
+	}
+}
+
+// --source lark-channel while the env signals OpenClaw must fail loud, same
+// rule as OpenClaw/Hermes mismatch (running in the wrong Agent context).
+func TestConfigBindRun_SourceEnvMismatch_LarkChannelFlagInOpenClawEnv(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	clearAgentEnv(t)
+	t.Setenv("OPENCLAW_HOME", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "bind",
+		Message: `--source "lark-channel" does not match detected Agent environment (openclaw)`,
+		Hint:    "remove --source to auto-detect, or run this command in the correct Agent context",
+	})
+}
+
+// Missing config.json → typed error with a hint pointing at bridge setup.
+func TestConfigBindRun_LarkChannelMissingFile(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	clearAgentEnv(t)
+
+	fakeHome := t.TempDir() // empty — no .lark-channel/config.json
+	t.Setenv("HOME", fakeHome)
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
+	configPath := filepath.Join(fakeHome, ".lark-channel", "config.json")
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "lark-channel",
+		Message: "cannot read " + configPath + ": open " + configPath + ": no such file or directory",
+		Hint:    "verify lark-channel-bridge is installed and configured",
+	})
+}
+
+// Empty accounts.app.id → typed error pointing at bridge setup. Distinct
+// from "missing file" so users know whether to install or to re-run setup.
+func TestConfigBindRun_LarkChannelEmptyAppID(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	clearAgentEnv(t)
+
+	fakeHome := t.TempDir()
+	t.Setenv("HOME", fakeHome)
+	configPath := writeLarkChannelFixture(t, fakeHome, `{"accounts":{"app":{"id":"","secret":"","tenant":"feishu"}}}`)
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "lark-channel",
+		Message: "accounts.app.id missing in " + configPath,
+		Hint:    "run lark-channel-bridge's setup to populate the app credential",
+	})
+}
+
+// app.id present but app.secret missing → typed error at the Build step.
+func TestConfigBindRun_LarkChannelEmptySecret(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	clearAgentEnv(t)
+
+	fakeHome := t.TempDir()
+	t.Setenv("HOME", fakeHome)
+	configPath := writeLarkChannelFixture(t, fakeHome, `{"accounts":{"app":{"id":"cli_no_secret","secret":"","tenant":"feishu"}}}`)
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"})
+	assertExitError(t, err, output.ExitValidation, output.ErrDetail{
+		Type:    "lark-channel",
+		Message: "accounts.app.secret is empty in " + configPath,
+		Hint:    "run lark-channel-bridge's setup to populate the app credential",
+	})
+}
+
 func TestConfigShowRun_WorkspaceField(t *testing.T) {
 	saveWorkspace(t)
 	configDir := t.TempDir()

cmd/config/binder.go

@@ -46,6 +46,8 @@ func newBinder(source string, opts *BindOptions) (SourceBinder, error) {
 		return &openclawBinder{opts: opts, path: resolveOpenClawConfigPath()}, nil
 	case "hermes":
 		return &hermesBinder{opts: opts, path: resolveHermesEnvPath()}, nil
+	case "lark-channel":
+		return &larkChannelBinder{opts: opts, path: resolveLarkChannelConfigPath()}, nil
 	default:
 		return nil, output.ErrValidation("unsupported source: %s", source)
 	}
@@ -270,6 +272,74 @@ func (b *hermesBinder) Build(appID string) (*core.AppConfig, error) {
 	}, nil
 }
 
+// ──────────────────────────────────────────────────────────────
+// larkChannelBinder
+// ──────────────────────────────────────────────────────────────
+
+type larkChannelBinder struct {
+	opts *BindOptions
+	path string
+
+	// Cached between ListCandidates and Build so we don't re-read the file.
+	cfg *binding.LarkChannelRoot
+}
+
+func (b *larkChannelBinder) Name() string       { return "lark-channel" }
+func (b *larkChannelBinder) ConfigPath() string { return b.path }
+
+func (b *larkChannelBinder) ListCandidates() ([]Candidate, error) {
+	cfg, err := binding.ReadLarkChannelConfig(b.path)
+	if err != nil {
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("cannot read %s: %v", b.path, err),
+			"verify lark-channel-bridge is installed and configured")
+	}
+	if cfg.Accounts.App.ID == "" {
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("accounts.app.id missing in %s", b.path),
+			"run lark-channel-bridge's setup to populate the app credential")
+	}
+	b.cfg = cfg
+	return []Candidate{{AppID: cfg.Accounts.App.ID, Label: "default"}}, nil
+}
+
+func (b *larkChannelBinder) Build(appID string) (*core.AppConfig, error) {
+	if b.cfg == nil {
+		return nil, output.Errorf(output.ExitInternal, "lark-channel",
+			"internal: Build called before ListCandidates")
+	}
+	if b.cfg.Accounts.App.ID != appID {
+		return nil, output.Errorf(output.ExitInternal, "lark-channel",
+			"internal: appID %q does not match config", appID)
+	}
+	if b.cfg.Accounts.App.Secret.IsZero() {
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("accounts.app.secret is empty in %s", b.path),
+			"run lark-channel-bridge's setup to populate the app credential")
+	}
+
+	// Resolve through the same SecretInput pipeline openclaw uses, so
+	// bridge configs can use ${VAR} / env / file / exec just like openclaw.
+	secret, err := binding.ResolveSecretInput(b.cfg.Accounts.App.Secret, b.cfg.Secrets, os.Getenv)
+	if err != nil {
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("failed to resolve appSecret for %s: %v", appID, err),
+			fmt.Sprintf("check appSecret configuration in %s", b.path))
+	}
+
+	stored, err := core.ForStorage(appID, core.PlainSecret(secret), b.opts.Factory.Keychain)
+	if err != nil {
+		return nil, output.Errorf(output.ExitInternal, "lark-channel",
+			"keychain unavailable: %v", err)
+	}
+
+	return &core.AppConfig{
+		AppId:     appID,
+		AppSecret: stored,
+		Brand:     core.LarkBrand(normalizeBrand(b.cfg.Accounts.App.Tenant)),
+	}, nil
+}
+
 // ──────────────────────────────────────────────────────────────
 // Source-specific helpers (path / dotenv / brand) — kept private to this package.
 // Moved here from bind.go so bind.go can focus on orchestration.
@@ -283,6 +353,8 @@ func sourceDisplayName(source string) string {
 		return "OpenClaw"
 	case "hermes":
 		return "Hermes"
+	case "lark-channel":
+		return "Lark Channel"
 	default:
 		return source
 	}
@@ -316,6 +388,18 @@ func resolveHermesEnvPath() string {
 	return filepath.Join(hermesHome, ".env")
 }
 
+// resolveLarkChannelConfigPath returns the path to lark-channel-bridge's
+// config.json. Mirrors the bridge's src/config/paths.ts which hardcodes
+// ~/.lark-channel/config.json with no env override — multi-instance is not
+// a supported scenario today.
+func resolveLarkChannelConfigPath() string {
+	home, err := vfs.UserHomeDir()
+	if err != nil || home == "" {
+		fmt.Fprintf(os.Stderr, "warning: unable to determine home directory: %v\n", err)
+	}
+	return filepath.Join(home, ".lark-channel", "config.json")
+}
+
 // resolveOpenClawConfigPath resolves openclaw.json path using the same priority
 // chain as OpenClaw's src/config/paths.ts:
 //  1. OPENCLAW_CONFIG_PATH env → exact file path

cmd/config/config_test.go

@@ -38,6 +38,7 @@ func (r *recordingConfigKeychain) Remove(service, account string) error {
 }
 
 func TestConfigInitCmd_FlagParsing(t *testing.T) {
+	clearAgentEnv(t) // assumes local workspace; guard refuses init in agent contexts
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 	f.IOStreams.In = strings.NewReader("secret123\n")
 
@@ -136,6 +137,7 @@ func TestConfigShowRun_NoActiveProfileReturnsStructuredError(t *testing.T) {
 }
 
 func TestConfigInitCmd_LangFlag(t *testing.T) {
+	clearAgentEnv(t) // assumes local workspace; guard refuses init in agent contexts
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 
 	var gotOpts *ConfigInitOptions
@@ -157,6 +159,7 @@ func TestConfigInitCmd_LangFlag(t *testing.T) {
 }
 
 func TestConfigInitCmd_LangDefault(t *testing.T) {
+	clearAgentEnv(t) // assumes local workspace; guard refuses init in agent contexts
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 
 	var gotOpts *ConfigInitOptions

cmd/config/init_guard_test.go

@@ -12,9 +12,7 @@ import (
 )
 
 func TestGuardAgentWorkspace_LocalAllows(t *testing.T) {
-	t.Setenv("OPENCLAW_HOME", "")
-	t.Setenv("OPENCLAW_CLI", "")
-	t.Setenv("HERMES_HOME", "")
+	clearAgentEnv(t)
 
 	if err := guardAgentWorkspace(&ConfigInitOptions{}); err != nil {
 		t.Errorf("local workspace should allow init, got: %v", err)

cmd/diagnose_scope_test.go

@@ -97,7 +97,7 @@ func diagBuild(domains []string) diagOutput {
 				if sc.Service != domain || !diagShortcutSupportsIdentity(&sc, identity) {
 					continue
 				}
-				for _, scope := range sc.ScopesForIdentity(identity) {
+				for _, scope := range sc.DeclaredScopesForIdentity(identity) {
 					k := methodKey{domain, "shortcut", sc.Command, scope}
 					if e, ok := merged[k]; ok {
 						e.Identity = appendUniq(e.Identity, identity)
@@ -169,6 +169,25 @@ func appendUniq(ss []string, s string) []string {
 	return append(ss, s)
 }
 
+func TestDiagBuild_ShortcutIncludesConditionalScopes(t *testing.T) {
+	out := diagBuild([]string{"drive"})
+	var sawMetadata, sawDownload bool
+	for _, method := range out.Methods {
+		if method.Domain != "drive" || method.Type != "shortcut" || method.Method != "+status" {
+			continue
+		}
+		if method.Scope == "drive:drive.metadata:readonly" {
+			sawMetadata = true
+		}
+		if method.Scope == "drive:file:download" {
+			sawDownload = true
+		}
+	}
+	if !sawMetadata || !sawDownload {
+		t.Fatalf("drive +status should advertise both metadata and conditional download scopes, saw metadata=%v download=%v", sawMetadata, sawDownload)
+	}
+}
+
 // ── Snapshot generation ───────────────────────────────────────────────
 //
 // Generates a JSON snapshot of all API methods and shortcuts with their

cmd/doctor/doctor.go

@@ -252,7 +252,7 @@ func checkCLIUpdate() []checkResult {
 	if update.IsNewer(latest, current) {
 		return []checkResult{warn("cli_update",
 			fmt.Sprintf("%s → %s available", current, latest),
-			"run: lark-cli update (or: npm install -g @larksuite/cli)")}
+			"run: lark-cli update")}
 	}
 	return []checkResult{pass("cli_update", latest+" (up to date)")}
 }

cmd/error_auth_hint.go

@@ -0,0 +1,175 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"fmt"
+	"strings"
+
+	internalauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/shortcuts"
+	shortcutcommon "github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+// enrichMissingScopeError preserves the original need_user_authorization
+// message and appends a scope hint when the current command declares the
+// required scopes locally.
+func enrichMissingScopeError(f *cmdutil.Factory, exitErr *output.ExitError) {
+	if exitErr == nil || exitErr.Detail == nil {
+		return
+	}
+	if !internalauth.IsNeedUserAuthorizationError(exitErr) {
+		return
+	}
+
+	scopes := resolveDeclaredScopesForCurrentCommand(f)
+	if len(scopes) == 0 {
+		return
+	}
+
+	scopeHint := fmt.Sprintf("current command requires scope(s): %s", strings.Join(scopes, ", "))
+	if exitErr.Detail.Hint == "" {
+		exitErr.Detail.Hint = scopeHint
+		return
+	}
+	exitErr.Detail.Hint += "\n" + scopeHint
+}
+
+// resolveDeclaredScopesForCurrentCommand returns the scopes declared by the
+// current command for the resolved identity, checking shortcuts first and then
+// service methods from local registry metadata.
+func resolveDeclaredScopesForCurrentCommand(f *cmdutil.Factory) []string {
+	if f == nil || f.CurrentCommand == nil {
+		return nil
+	}
+
+	identity := string(f.ResolvedIdentity)
+	if identity == "" {
+		identity = string(core.AsUser)
+	}
+	if identity != string(core.AsUser) && identity != string(core.AsBot) {
+		return nil
+	}
+
+	if scopes := resolveDeclaredShortcutScopes(f.CurrentCommand, identity); len(scopes) > 0 {
+		return scopes
+	}
+	return resolveDeclaredServiceMethodScopes(f.CurrentCommand, identity)
+}
+
+// resolveDeclaredShortcutScopes returns the scopes declared by a mounted
+// shortcut command for the given identity.
+func resolveDeclaredShortcutScopes(cmd *cobra.Command, identity string) []string {
+	if cmd == nil || cmd.Parent() == nil || !strings.HasPrefix(cmd.Name(), "+") {
+		return nil
+	}
+
+	service := cmd.Parent().Name()
+	for _, sc := range shortcuts.AllShortcuts() {
+		if sc.Service != service || sc.Command != cmd.Name() || !shortcutSupportsIdentity(sc, identity) {
+			continue
+		}
+		scopes := sc.DeclaredScopesForIdentity(identity)
+		if len(scopes) == 0 {
+			return nil
+		}
+		return append([]string(nil), scopes...)
+	}
+	return nil
+}
+
+// resolveDeclaredServiceMethodScopes returns the scopes declared by a
+// service/resource/method command from the embedded from_meta registry.
+func resolveDeclaredServiceMethodScopes(cmd *cobra.Command, identity string) []string {
+	// Service-method scope lookup only applies to commands mounted as
+	// root -> service -> resource -> method. Non-resource/method commands
+	// intentionally return no scopes here so auth-hint enrichment does not
+	// change runtime semantics for other command shapes.
+	if cmd == nil || cmd.Parent() == nil || cmd.Parent().Parent() == nil || cmd.Parent().Parent().Parent() == nil {
+		return nil
+	}
+	if strings.HasPrefix(cmd.Name(), "+") {
+		return nil
+	}
+
+	service := cmd.Parent().Parent().Name()
+	resource := cmd.Parent().Name()
+	method := cmd.Name()
+
+	spec := registry.LoadFromMeta(service)
+	if spec == nil {
+		return nil
+	}
+	resources, _ := spec["resources"].(map[string]interface{})
+	resMap, _ := resources[resource].(map[string]interface{})
+	if resMap == nil {
+		return nil
+	}
+	methods, _ := resMap["methods"].(map[string]interface{})
+	methodMap, _ := methods[method].(map[string]interface{})
+	if methodMap == nil {
+		return nil
+	}
+	return declaredScopesForMethod(methodMap, identity)
+}
+
+// declaredScopesForMethod returns all requiredScopes when present; otherwise it
+// resolves the single recommended scope from the method's scopes list.
+func declaredScopesForMethod(method map[string]interface{}, identity string) []string {
+	if requiredRaw, ok := method["requiredScopes"].([]interface{}); ok && len(requiredRaw) > 0 {
+		return interfaceStrings(requiredRaw)
+	}
+
+	rawScopes, _ := method["scopes"].([]interface{})
+	if len(rawScopes) == 0 {
+		return nil
+	}
+	recommended := registry.SelectRecommendedScope(rawScopes, identity)
+	if recommended == "" {
+		for _, raw := range rawScopes {
+			if scope, ok := raw.(string); ok && scope != "" {
+				recommended = scope
+				break
+			}
+		}
+	}
+	if recommended == "" {
+		return nil
+	}
+	return []string{recommended}
+}
+
+// interfaceStrings converts a []interface{} containing strings into a compact
+// []string, skipping empty or non-string values.
+func interfaceStrings(values []interface{}) []string {
+	scopes := make([]string, 0, len(values))
+	for _, value := range values {
+		scope, ok := value.(string)
+		if !ok || scope == "" {
+			continue
+		}
+		scopes = append(scopes, scope)
+	}
+	return scopes
+}
+
+// shortcutSupportsIdentity reports whether a shortcut supports the requested
+// identity, applying the default user-only behavior when AuthTypes is empty.
+func shortcutSupportsIdentity(sc shortcutcommon.Shortcut, identity string) bool {
+	authTypes := sc.AuthTypes
+	if len(authTypes) == 0 {
+		authTypes = []string{string(core.AsUser)}
+	}
+	for _, authType := range authTypes {
+		if authType == identity {
+			return true
+		}
+	}
+	return false
+}

cmd/root.go

@@ -20,6 +20,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/skillscheck"
 	"github.com/larksuite/cli/internal/update"
 	"github.com/spf13/cobra"
 )
@@ -47,7 +48,7 @@ EXAMPLES:
 FLAGS:
     --params <json>       URL/query parameters JSON
     --data <json>         request body JSON (POST/PATCH/PUT/DELETE)
-    --as <type>           identity type: user | bot | auto (default: auto)
+    --as <type>           identity type: user | bot
     --format <fmt>        output format: json (default) | ndjson | table | csv | pretty
     --page-all            automatically paginate through all pages
     --page-size <N>       page size (0 = use API default)
@@ -93,9 +94,9 @@ func Execute() int {
 		HideProfile(isSingleAppMode()),
 	)
 
-	// --- Update check (non-blocking) ---
+	// --- Notices (non-blocking) ---
 	if !isCompletionCommand(os.Args) {
-		setupUpdateNotice()
+		setupNotices()
 	}
 
 	if err := rootCmd.Execute(); err != nil {
@@ -104,42 +105,56 @@ func Execute() int {
 	return 0
 }
 
-// setupUpdateNotice starts an async update check and wires the output decorator.
-func setupUpdateNotice() {
-	// Sync: check cache immediately (no network, fast).
+// setupNotices wires both the binary update notice and the skills
+// staleness notice into output.PendingNotice as a composed function.
+// Each provider populates an independent key under _notice; either
+// or both may be present in any given envelope.
+func setupNotices() {
+	// Binary update — synchronous cache check + async refresh
 	if info := update.CheckCached(build.Version); info != nil {
 		update.SetPending(info)
 	}
-
-	// Async: refresh cache for this run (and future runs).
+	ver := build.Version
 	go func() {
 		defer func() {
 			if r := recover(); r != nil {
 				fmt.Fprintf(os.Stderr, "update check panic: %v\n", r)
 			}
 		}()
-		update.RefreshCache(build.Version)
-		// If cache was just populated for the first time, set pending now.
+		update.RefreshCache(ver)
 		if update.GetPending() == nil {
-			if info := update.CheckCached(build.Version); info != nil {
+			if info := update.CheckCached(ver); info != nil {
 				update.SetPending(info)
 			}
 		}
 	}()
 
-	// Wire the output decorator so JSON envelopes include "_notice".
+	// Skills check — synchronous, local-only (no network, no goroutine).
+	skillscheck.Init(build.Version)
+
+	// Composed notice provider — emits keys only when each pending is set.
 	output.PendingNotice = func() map[string]interface{} {
-		info := update.GetPending()
-		if info == nil {
-			return nil
-		}
-		return map[string]interface{}{
-			"update": map[string]interface{}{
+		notice := map[string]interface{}{}
+		if info := update.GetPending(); info != nil {
+			notice["update"] = map[string]interface{}{
 				"current": info.Current,
 				"latest":  info.Latest,
 				"message": info.Message(),
-			},
+				"command": "lark-cli update",
+			}
 		}
+		if stale := skillscheck.GetPending(); stale != nil {
+			notice["skills"] = map[string]interface{}{
+				"current": stale.Current,
+				"target":  stale.Target,
+				"message": stale.Message(),
+				"command": "lark-cli update",
+			}
+		}
+		if len(notice) == 0 {
+			return nil
+		}
+		return notice
 	}
 }
 
@@ -179,6 +194,7 @@ func handleRootError(f *cmdutil.Factory, err error) int {
 		if !exitErr.Raw {
 			// Raw errors (e.g. from `api` command) preserve the original API
 			// error detail; skip enrichment which would clear it.
+			enrichMissingScopeError(f, exitErr)
 			enrichPermissionError(f, exitErr)
 		}
 		output.WriteErrorEnvelope(errOut, exitErr, string(f.ResolvedIdentity))

cmd/root_integration_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"os"
 	"reflect"
 	"strings"
 	"testing"
@@ -14,11 +15,14 @@ import (
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
 	"github.com/larksuite/cli/cmd/service"
+	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/skillscheck"
+	"github.com/larksuite/cli/internal/update"
 	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
 )
@@ -499,3 +503,193 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 		},
 	})
 }
+
+// TestSetupNotices_ColdStart_NoNotice verifies that a missing stamp
+// produces no skills key in the composed notice. Users who installed
+// skills via `npx skills add` (no stamp) must not see the misleading
+// "not installed" notice — only `lark-cli update` users opt into the
+// drift tracker.
+func TestSetupNotices_ColdStart_NoNotice(t *testing.T) {
+	clearNoticeEnv(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+
+	origVersion := build.Version
+	build.Version = "1.0.21"
+	t.Cleanup(func() { build.Version = origVersion })
+
+	// Reset pending state to ensure a clean test.
+	skillscheck.SetPending(nil)
+	update.SetPending(nil)
+	output.PendingNotice = nil
+	t.Cleanup(func() {
+		skillscheck.SetPending(nil)
+		update.SetPending(nil)
+		output.PendingNotice = nil
+	})
+
+	setupNotices()
+
+	notice := output.GetNotice()
+	if notice == nil {
+		return // expected — no pending notices at all
+	}
+	if _, ok := notice["skills"]; ok {
+		t.Errorf("notice.skills present in cold-start state, want absent: %+v", notice)
+	}
+}
+
+// TestSetupNotices_InSync verifies that a matching stamp produces no
+// skills key in the composed notice.
+func TestSetupNotices_InSync(t *testing.T) {
+	clearNoticeEnv(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+
+	origVersion := build.Version
+	build.Version = "1.0.21"
+	t.Cleanup(func() { build.Version = origVersion })
+
+	skillscheck.SetPending(nil)
+	update.SetPending(nil)
+	output.PendingNotice = nil
+	t.Cleanup(func() {
+		skillscheck.SetPending(nil)
+		update.SetPending(nil)
+		output.PendingNotice = nil
+	})
+
+	setupNotices()
+
+	notice := output.GetNotice()
+	if notice != nil {
+		if _, ok := notice["skills"]; ok {
+			t.Errorf("notice.skills present in in-sync state: %+v", notice)
+		}
+	}
+}
+
+// TestSetupNotices_Drift verifies a mismatching stamp produces the
+// drift message with both current and target populated.
+func TestSetupNotices_Drift(t *testing.T) {
+	clearNoticeEnv(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+
+	origVersion := build.Version
+	build.Version = "1.0.21"
+	t.Cleanup(func() { build.Version = origVersion })
+
+	skillscheck.SetPending(nil)
+	update.SetPending(nil)
+	output.PendingNotice = nil
+	t.Cleanup(func() {
+		skillscheck.SetPending(nil)
+		update.SetPending(nil)
+		output.PendingNotice = nil
+	})
+
+	setupNotices()
+
+	notice := output.GetNotice()
+	if notice == nil {
+		t.Fatal("GetNotice() = nil, want non-nil for drift")
+	}
+	skills, ok := notice["skills"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("notice.skills missing, got %+v", notice)
+	}
+	if skills["current"] != "1.0.20" || skills["target"] != "1.0.21" {
+		t.Errorf("notice.skills = %+v, want {current:\"1.0.20\", target:\"1.0.21\"}", skills)
+	}
+	want := "lark-cli skills 1.0.20 out of sync with binary 1.0.21, run: lark-cli update"
+	if msg, _ := skills["message"].(string); msg != want {
+		t.Errorf("notice.skills.message = %q, want %q", msg, want)
+	}
+	if cmd, _ := skills["command"].(string); cmd != "lark-cli update" {
+		t.Errorf("notice.skills.command = %q, want %q", cmd, "lark-cli update")
+	}
+}
+
+// TestSetupNotices_BothUpdateAndSkills verifies the composed envelope
+// emits BOTH "_notice.update" and "_notice.skills" keys when each
+// pending value is set. Drives the skills key via setupNotices() (drift
+// state) and manually populates the update pending afterwards, since
+// clearNoticeEnv suppresses the update goroutine to avoid network
+// flakiness.
+func TestSetupNotices_BothUpdateAndSkills(t *testing.T) {
+	clearNoticeEnv(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+
+	origVersion := build.Version
+	build.Version = "1.0.21"
+	t.Cleanup(func() { build.Version = origVersion })
+
+	skillscheck.SetPending(nil)
+	update.SetPending(nil)
+	output.PendingNotice = nil
+	t.Cleanup(func() {
+		skillscheck.SetPending(nil)
+		update.SetPending(nil)
+		output.PendingNotice = nil
+	})
+
+	setupNotices()
+
+	// After setupNotices, skills pending is set (drift). Manually populate
+	// the update side so the composed envelope has both keys — the update
+	// goroutine is suppressed by clearNoticeEnv.
+	update.SetPending(&update.UpdateInfo{Current: "1.0.21", Latest: "1.0.22"})
+
+	notice := output.GetNotice()
+	if notice == nil {
+		t.Fatal("GetNotice() = nil, want both keys")
+	}
+	if _, ok := notice["update"].(map[string]interface{}); !ok {
+		t.Errorf("missing 'update' key: %+v", notice)
+	}
+	if _, ok := notice["skills"].(map[string]interface{}); !ok {
+		t.Errorf("missing 'skills' key: %+v", notice)
+	}
+	upd, ok := notice["update"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("notice.update missing or wrong type: %+v", notice)
+	}
+	if cmd, _ := upd["command"].(string); cmd != "lark-cli update" {
+		t.Errorf("notice.update.command = %q, want %q", cmd, "lark-cli update")
+	}
+	sk, ok := notice["skills"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("notice.skills missing or wrong type: %+v", notice)
+	}
+	if cmd, _ := sk["command"].(string); cmd != "lark-cli update" {
+		t.Errorf("notice.skills.command = %q, want %q", cmd, "lark-cli update")
+	}
+}
+
+// clearNoticeEnv unsets the env vars that affect either notice. We
+// proactively SUPPRESS the update notifier (LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1)
+// because setupNotices spawns a goroutine that hits the npm registry —
+// tests focused on the skills check should not depend on network state.
+func clearNoticeEnv(t *testing.T) {
+	t.Helper()
+	for _, key := range []string{
+		"LARKSUITE_CLI_NO_SKILLS_NOTIFIER",
+		"CI", "BUILD_NUMBER", "RUN_ID",
+	} {
+		t.Setenv(key, "")
+		os.Unsetenv(key)
+	}
+	// Suppress the update goroutine's network call deterministically.
+	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
+}

cmd/root_test.go

@@ -11,9 +11,12 @@ import (
 	"github.com/larksuite/cli/cmd/auth"
 	cmdconfig "github.com/larksuite/cli/cmd/config"
 	"github.com/larksuite/cli/cmd/schema"
+	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/registry"
+	"github.com/spf13/cobra"
 )
 
 // TestPersistentPreRunE_AuthCheckDisabledAnnotations verifies that
@@ -188,6 +191,150 @@ func TestEnrichPermissionError_SpecialCharsEscaped(t *testing.T) {
 	}
 }
 
+func TestEnrichMissingScopeError_ServiceMethodUsesLocalScopesWhenNoUAT(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	var target registry.CommandEntry
+	for _, entry := range registry.CollectCommandScopes([]string{"calendar"}, "user") {
+		if len(entry.Scopes) == 1 && entry.Scopes[0] == "calendar:calendar.event:create" {
+			target = entry
+			break
+		}
+	}
+	if target.Command == "" {
+		t.Fatal("failed to locate a calendar create command in local registry metadata")
+	}
+	parts := strings.Split(target.Command, " ")
+	if len(parts) != 2 {
+		t.Fatalf("expected resource/method command, got %q", target.Command)
+	}
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "calendar"}
+	resourceCmd := &cobra.Command{Use: parts[0]}
+	methodCmd := &cobra.Command{Use: parts[1]}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(resourceCmd)
+	resourceCmd.AddCommand(methodCmd)
+	f.CurrentCommand = methodCmd
+
+	exitErr := output.Errorf(output.ExitAPI, "api_error", "API call failed: %s", &internalauth.NeedAuthorizationError{})
+	enrichMissingScopeError(f, exitErr)
+
+	if exitErr.Code != output.ExitAPI {
+		t.Fatalf("expected exit code %d, got %d", output.ExitAPI, exitErr.Code)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "api_error" {
+		t.Fatalf("expected api_error detail, got %+v", exitErr.Detail)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "need_user_authorization") {
+		t.Fatalf("expected original need_user_authorization message, got %q", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "current command requires scope(s): calendar:calendar.event:create") {
+		t.Fatalf("expected scope guidance in hint, got %q", exitErr.Detail.Hint)
+	}
+	if strings.Contains(exitErr.Detail.Hint, "lark-cli auth login --scope") {
+		t.Fatalf("expected hint without auth login command, got %q", exitErr.Detail.Hint)
+	}
+	if exitErr.Detail.Detail != nil {
+		t.Fatalf("expected detail to remain nil, got %#v", exitErr.Detail.Detail)
+	}
+}
+
+func TestEnrichMissingScopeError_ShortcutUsesDeclaredScopesWhenNoUAT(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "docs"}
+	shortcutCmd := &cobra.Command{Use: "+create"}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(shortcutCmd)
+	f.CurrentCommand = shortcutCmd
+
+	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
+	enrichMissingScopeError(f, exitErr)
+
+	if exitErr.Code != output.ExitNetwork {
+		t.Fatalf("expected exit code %d, got %d", output.ExitNetwork, exitErr.Code)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "network" {
+		t.Fatalf("expected network detail, got %+v", exitErr.Detail)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "need_user_authorization") {
+		t.Fatalf("expected original need_user_authorization message, got %q", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "current command requires scope(s): docx:document:create") {
+		t.Fatalf("expected shortcut scope hint, got %q", exitErr.Detail.Hint)
+	}
+	if strings.Contains(exitErr.Detail.Hint, "lark-cli auth login --scope") {
+		t.Fatalf("expected hint without auth login command, got %q", exitErr.Detail.Hint)
+	}
+	if exitErr.Detail.Detail != nil {
+		t.Fatalf("expected detail to remain nil, got %#v", exitErr.Detail.Detail)
+	}
+}
+
+func TestEnrichMissingScopeError_ShortcutIncludesConditionalScopes(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "drive"}
+	shortcutCmd := &cobra.Command{Use: "+status"}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(shortcutCmd)
+	f.CurrentCommand = shortcutCmd
+
+	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
+	enrichMissingScopeError(f, exitErr)
+
+	if exitErr.Detail == nil {
+		t.Fatal("expected error detail")
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "current command requires scope(s): drive:drive.metadata:readonly, drive:file:download") {
+		t.Fatalf("expected conditional scope hint for drive +status, got %q", exitErr.Detail.Hint)
+	}
+}
+
+func TestEnrichMissingScopeError_AppendsExistingHint(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.ResolvedIdentity = core.AsUser
+
+	root := &cobra.Command{Use: "lark-cli"}
+	serviceCmd := &cobra.Command{Use: "docs"}
+	shortcutCmd := &cobra.Command{Use: "+create"}
+	root.AddCommand(serviceCmd)
+	serviceCmd.AddCommand(shortcutCmd)
+	f.CurrentCommand = shortcutCmd
+
+	exitErr := output.ErrNetwork("API call failed: %s", &internalauth.NeedAuthorizationError{})
+	exitErr.Detail.Hint = "existing hint"
+	enrichMissingScopeError(f, exitErr)
+
+	want := "existing hint\ncurrent command requires scope(s): docx:document:create"
+	if exitErr.Detail.Hint != want {
+		t.Fatalf("expected appended hint %q, got %q", want, exitErr.Detail.Hint)
+	}
+}
+
 func TestRootLong_AgentSkillsLinkTargetsReadmeSection(t *testing.T) {
 	if !strings.Contains(rootLong, "https://github.com/larksuite/cli#agent-skills") {
 		t.Fatalf("root help should link to the README Agent Skills section, got:\n%s", rootLong)

cmd/update/update.go

@@ -14,13 +14,15 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/selfupdate"
+	"github.com/larksuite/cli/internal/skillscheck"
 	"github.com/larksuite/cli/internal/update"
 )
 
 const (
-	repoURL      = "https://github.com/larksuite/cli"
-	maxNpmOutput = 2000
-	osWindows    = "windows"
+	repoURL         = "https://github.com/larksuite/cli"
+	maxNpmOutput    = 2000
+	maxStderrDetail = 500
+	osWindows       = "windows"
 )
 
 // Overridable for testing.
@@ -33,6 +35,13 @@ var (
 
 func isWindows() bool { return currentOS == osWindows }
 
+// normalizeVersion canonicalizes a version string for stamp comparison.
+// Strips a leading "v" so versions written from Makefile (git describe →
+// "v1.0.0") and npm (no prefix → "1.0.0") compare equal.
+func normalizeVersion(s string) string {
+	return strings.TrimPrefix(strings.TrimSpace(s), "v")
+}
+
 func releaseURL(version string) string {
 	return repoURL + "/releases/tag/v" + strings.TrimPrefix(version, "v")
 }
@@ -127,16 +136,15 @@ func updateRun(opts *UpdateOptions) error {
 
 	// 3. Compare versions
 	if !opts.Force && !update.IsNewer(latest, cur) {
-		if opts.JSON {
-			output.PrintJson(io.Out, map[string]interface{}{
-				"ok": true, "previous_version": cur, "current_version": cur,
-				"latest_version": latest, "action": "already_up_to_date",
-				"message": fmt.Sprintf("lark-cli %s is already up to date", cur),
-			})
-			return nil
+		// Run skills sync before returning — covers the case where the
+		// binary is already current but skills were never synced.
+		// Stamp dedup makes this a no-op if skills are already in sync.
+		// Skip side-effects under --check (pure report path per spec §3.6).
+		var skillsResult *selfupdate.NpmResult
+		if !opts.Check {
+			skillsResult = runSkillsAndStamp(updater, io, cur, opts.Force)
 		}
-		fmt.Fprintf(io.ErrOut, "%s lark-cli %s is already up to date\n", symOK(), cur)
-		return nil
+		return reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
 	}
 
 	// 4. Detect installation method
@@ -149,7 +157,7 @@ func updateRun(opts *UpdateOptions) error {
 
 	// 6. Execute update
 	if !detect.CanAutoUpdate() {
-		return doManualUpdate(opts, io, cur, latest, detect)
+		return doManualUpdate(opts, io, cur, latest, detect, updater)
 	}
 	return doNpmUpdate(opts, io, cur, latest, updater)
 }
@@ -169,13 +177,24 @@ func reportError(opts *UpdateOptions, io *cmdutil.IOStreams, exitCode int, errTy
 
 func reportCheckResult(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, canAutoUpdate bool) error {
 	if opts.JSON {
-		output.PrintJson(io.Out, map[string]interface{}{
+		out := map[string]interface{}{
 			"ok": true, "previous_version": cur, "current_version": cur,
 			"latest_version": latest, "action": "update_available",
 			"auto_update": canAutoUpdate,
 			"message":     fmt.Sprintf("lark-cli %s %s %s available", cur, symArrow(), latest),
 			"url":         releaseURL(latest), "changelog": changelogURL(),
-		})
+		}
+		// skills_status: pure report, no side effect, no stamp write.
+		// ReadStamp errors are silently swallowed — if we can't read the
+		// stamp we just omit the block rather than fail the --check.
+		if stamp, err := skillscheck.ReadStamp(); err == nil {
+			out["skills_status"] = map[string]interface{}{
+				"current": stamp,
+				"target":  cur,
+				"in_sync": stamp == cur,
+			}
+		}
+		output.PrintJson(io.Out, out)
 		return nil
 	}
 	fmt.Fprintf(io.ErrOut, "Update available: %s %s %s\n", cur, symArrow(), latest)
@@ -189,23 +208,27 @@ func reportCheckResult(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest s
 	return nil
 }
 
-func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult) error {
+func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
+	skillsResult := runSkillsAndStamp(updater, io, cur, opts.Force)
+
 	reason := detect.ManualReason()
 	if opts.JSON {
-		output.PrintJson(io.Out, map[string]interface{}{
+		out := map[string]interface{}{
 			"ok": true, "previous_version": cur, "latest_version": latest,
 			"action":  "manual_required",
 			"message": fmt.Sprintf("Automatic update unavailable: %s (path: %s)", reason, detect.ResolvedPath),
 			"url":     releaseURL(latest), "changelog": changelogURL(),
-		})
+		}
+		applySkillsResult(out, skillsResult)
+		output.PrintJson(io.Out, out)
 		return nil
 	}
 	fmt.Fprintf(io.ErrOut, "Automatic update unavailable: %s (path: %s).\n\n", reason, detect.ResolvedPath)
 	fmt.Fprintf(io.ErrOut, "To update manually, download the latest release:\n")
 	fmt.Fprintf(io.ErrOut, "  Release:   %s\n", releaseURL(latest))
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
-	fmt.Fprintf(io.ErrOut, "\nOr install via npm:\n  npm install -g %s@%s\n", selfupdate.NpmPackage, latest)
-	fmt.Fprintf(io.ErrOut, "\nAfter updating, also update skills:\n  npx -y skills add larksuite/cli -g -y\n")
+	fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
+	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
@@ -264,8 +287,10 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 		return output.ErrBare(output.ExitAPI)
 	}
 
-	// Skills update (best-effort).
-	skillsResult := updater.RunSkillsUpdate()
+	// Skills update (best-effort) — uses runSkillsAndStamp so the
+	// stamp gets persisted on success and dedup applies if a previous
+	// run already stamped this version.
+	skillsResult := runSkillsAndStamp(updater, io, latest, opts.Force)
 
 	if opts.JSON {
 		result := map[string]interface{}{
@@ -274,28 +299,17 @@ func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string,
 			"message": fmt.Sprintf("lark-cli updated from %s to %s", cur, latest),
 			"url":     releaseURL(latest), "changelog": changelogURL(),
 		}
-		if skillsResult.Err != nil {
-			result["skills_warning"] = fmt.Sprintf("skills update failed: %s", skillsResult.Err)
-			if detail := strings.TrimSpace(skillsResult.Stderr.String()); detail != "" {
-				result["skills_detail"] = selfupdate.Truncate(detail, maxNpmOutput)
-			}
-		}
+		applySkillsResult(result, skillsResult)
 		output.PrintJson(io.Out, result)
 		return nil
 	}
 
 	fmt.Fprintf(io.ErrOut, "\n%s Successfully updated lark-cli from %s to %s\n", symOK(), cur, latest)
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
-	fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
-	if skillsResult.Err != nil {
-		fmt.Fprintf(io.ErrOut, "%s Skills update failed: %s\n", symWarn(), skillsResult.Err)
-		if detail := strings.TrimSpace(skillsResult.Stderr.String()); detail != "" {
-			fmt.Fprintf(io.ErrOut, "  %s\n", selfupdate.Truncate(detail, 500))
-		}
-		fmt.Fprintf(io.ErrOut, "  Run manually: npx -y skills add larksuite/cli -g -y\n")
-	} else {
-		fmt.Fprintf(io.ErrOut, "%s Skills updated\n", symOK())
+	if skillsResult != nil {
+		fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
 	}
+	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
 
@@ -310,5 +324,98 @@ func verificationFailureHint(updater *selfupdate.Updater, latest string) string
 	if updater.CanRestorePreviousVersion() {
 		return "the previous version has been restored"
 	}
-	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually: npm install -g %s@%s, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
+	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): npm install -g %s@%s && npx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
+}
+
+// runSkillsAndStamp triggers updater.RunSkillsUpdate and persists the
+// stamp on success. Skips the npx invocation when the stamp already
+// matches stampVersion (unless force is true). The stamp write failure
+// emits a warning to io.ErrOut but does NOT fail the update command —
+// best-effort. ReadStamp errors are swallowed (fail-closed: treated as
+// out-of-sync, so npx re-runs). Returns nil iff skipped due to stamp
+// dedup; otherwise returns the underlying *NpmResult with Err semantics
+// from RunSkillsUpdate.
+func runSkillsAndStamp(updater *selfupdate.Updater, io *cmdutil.IOStreams, stampVersion string, force bool) *selfupdate.NpmResult {
+	if !force {
+		if existing, _ := skillscheck.ReadStamp(); normalizeVersion(existing) == normalizeVersion(stampVersion) {
+			return nil
+		}
+	}
+	r := updater.RunSkillsUpdate()
+	if r.Err == nil {
+		if err := skillscheck.WriteStamp(stampVersion); err != nil {
+			fmt.Fprintf(io.ErrOut, "warning: skills synced but stamp not written: %v\n", err)
+		}
+	}
+	return r
+}
+
+// reportAlreadyUpToDate emits the JSON / pretty output for the
+// already-up-to-date branch, including any skills_action / skills_warning
+// fields derived from skillsResult. When check is true, this is the pure
+// report path (spec §3.6): no side-effects, JSON envelope uses
+// skills_status (spec §4.2) instead of skills_action.
+func reportAlreadyUpToDate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, skillsResult *selfupdate.NpmResult, check bool) error {
+	if opts.JSON {
+		out := map[string]interface{}{
+			"ok": true, "previous_version": cur, "current_version": cur,
+			"latest_version": latest, "action": "already_up_to_date",
+			"message": fmt.Sprintf("lark-cli %s is already up to date", cur),
+		}
+		if check {
+			// Pure report — read stamp directly, emit skills_status block.
+			// ReadStamp errors are silently swallowed — if we can't read
+			// the stamp we just omit the block rather than fail the --check.
+			if stamp, err := skillscheck.ReadStamp(); err == nil {
+				out["skills_status"] = map[string]interface{}{
+					"current": stamp,
+					"target":  cur,
+					"in_sync": stamp == cur,
+				}
+			}
+		} else {
+			applySkillsResult(out, skillsResult)
+		}
+		output.PrintJson(io.Out, out)
+		return nil
+	}
+	fmt.Fprintf(io.ErrOut, "%s lark-cli %s is already up to date\n", symOK(), cur)
+	if !check {
+		emitSkillsTextHints(io, skillsResult)
+	}
+	return nil
+}
+
+// applySkillsResult mutates the JSON envelope to include skills_action
+// (and skills_warning when failed). nil result = "in_sync" (dedup hit).
+func applySkillsResult(env map[string]interface{}, r *selfupdate.NpmResult) {
+	switch {
+	case r == nil:
+		env["skills_action"] = "in_sync"
+	case r.Err != nil:
+		env["skills_action"] = "failed"
+		env["skills_warning"] = fmt.Sprintf("skills update failed: %s", r.Err)
+		if detail := strings.TrimSpace(r.Stderr.String()); detail != "" {
+			env["skills_detail"] = selfupdate.Truncate(detail, maxNpmOutput)
+		}
+	default:
+		env["skills_action"] = "synced"
+	}
+}
+
+// emitSkillsTextHints prints human-readable feedback about the skills
+// sync result for non-JSON output.
+func emitSkillsTextHints(io *cmdutil.IOStreams, r *selfupdate.NpmResult) {
+	switch {
+	case r == nil:
+		// dedup hit — silent (already up to date)
+	case r.Err != nil:
+		fmt.Fprintf(io.ErrOut, "%s Skills update failed: %v\n", symWarn(), r.Err)
+		if detail := strings.TrimSpace(r.Stderr.String()); detail != "" {
+			fmt.Fprintf(io.ErrOut, "  %s\n", selfupdate.Truncate(detail, maxStderrDetail))
+		}
+		fmt.Fprintf(io.ErrOut, "  Run manually: npx -y skills add larksuite/cli -g -y\n")
+	default:
+		fmt.Fprintf(io.ErrOut, "%s Skills updated\n", symOK())
+	}
 }

cmd/update/update_test.go

@@ -5,8 +5,11 @@ package cmdupdate
 
 import (
 	"bytes"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -14,6 +17,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/selfupdate"
+	"github.com/larksuite/cli/internal/skillscheck"
 )
 
 // newTestFactory creates a test factory with minimal config.
@@ -164,6 +168,11 @@ func TestUpdateManual_Human(t *testing.T) {
 }
 
 func TestUpdateNpm_JSON(t *testing.T) {
+	// Isolate config dir: this test mocks fetchLatest="2.0.0" and lets
+	// runSkillsAndStamp → WriteStamp succeed, which without isolation would
+	// clobber the real ~/.lark-cli/skills.stamp with "2.0.0".
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
 	f, stdout, _ := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{"--json"})
@@ -191,6 +200,9 @@ func TestUpdateNpm_JSON(t *testing.T) {
 }
 
 func TestUpdateNpm_Human(t *testing.T) {
+	// Same isolation as TestUpdateNpm_JSON — see comment there.
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
 	f, _, stderr := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{})
@@ -218,6 +230,9 @@ func TestUpdateNpm_Human(t *testing.T) {
 }
 
 func TestUpdateForce_JSON(t *testing.T) {
+	// Same stamp-isolation rationale as TestUpdateNpm_JSON.
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
 	f, stdout, _ := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{"--force", "--json"})
@@ -308,6 +323,9 @@ func TestUpdateInvalidVersion_JSON(t *testing.T) {
 }
 
 func TestUpdateDevVersion_JSON(t *testing.T) {
+	// Same stamp-isolation rationale as TestUpdateNpm_JSON.
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
 	f, stdout, _ := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{"--json"})
@@ -463,6 +481,12 @@ func TestUpdateNpmVerifyFail_JSON_NoRestoreHintWhenBackupUnavailable(t *testing.
 	if !strings.Contains(out, "npm install -g @larksuite/cli@2.0.0") {
 		t.Errorf("expected manual reinstall command in hint, got: %s", out)
 	}
+	if !strings.Contains(out, "skills will not be synced") {
+		t.Errorf("expected skills-not-synced warning in rollback hint, got: %s", out)
+	}
+	if !strings.Contains(out, "npx skills add larksuite/cli -y -g") {
+		t.Errorf("expected npx skills add hint for skills sync, got: %s", out)
+	}
 }
 
 func TestUpdateCheck_JSON_Npm(t *testing.T) {
@@ -625,6 +649,9 @@ func TestPermissionHint(t *testing.T) {
 
 func TestUpdateWindows_NpmSuccess_JSON(t *testing.T) {
 	// With the rename trick, Windows npm installs can now auto-update.
+	// Same stamp-isolation rationale as TestUpdateNpm_JSON.
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
 	f, stdout, _ := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{"--json"})
@@ -709,6 +736,7 @@ func TestUpdateWindows_Symbols(t *testing.T) {
 }
 
 func TestUpdateNpm_SkillsSuccess_JSON(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _ := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{"--json"})
@@ -737,6 +765,7 @@ func TestUpdateNpm_SkillsSuccess_JSON(t *testing.T) {
 }
 
 func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _ := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{"--json"})
@@ -789,6 +818,7 @@ func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
 }
 
 func TestUpdateNpm_SkillsFail_Human(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, _, stderr := newTestFactory(t)
 	cmd := NewCmdUpdate(f)
 	cmd.SetArgs([]string{})
@@ -836,6 +866,98 @@ func TestUpdateNpm_SkillsFail_Human(t *testing.T) {
 	}
 }
 
+// newTestIO returns a cmdutil.IOStreams backed by bytes.Buffers, suitable
+// for direct calls to internals like runSkillsAndStamp that write to
+// io.ErrOut.
+func newTestIO() *cmdutil.IOStreams {
+	return cmdutil.NewIOStreams(&bytes.Buffer{}, &bytes.Buffer{}, &bytes.Buffer{})
+}
+
+func TestRunSkillsAndStamp_DedupHit(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	called := false
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			called = true
+			return &selfupdate.NpmResult{}
+		},
+	}
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
+	if got != nil {
+		t.Errorf("runSkillsAndStamp() = %+v, want nil for dedup hit", got)
+	}
+	if called {
+		t.Error("SkillsUpdateOverride called, want skipped due to dedup")
+	}
+}
+
+func TestRunSkillsAndStamp_DedupForceBypass(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	called := false
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			called = true
+			return &selfupdate.NpmResult{}
+		},
+	}
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", true)
+	if got == nil {
+		t.Fatal("runSkillsAndStamp(force=true) = nil, want non-nil")
+	}
+	if !called {
+		t.Error("SkillsUpdateOverride not called with force=true")
+	}
+}
+
+func TestRunSkillsAndStamp_SuccessWritesStamp(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			return &selfupdate.NpmResult{}
+		},
+	}
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
+	if got == nil || got.Err != nil {
+		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with nil Err", got)
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.21" {
+		t.Errorf("stamp = %q, want \"1.0.21\"", stamp)
+	}
+}
+
+func TestRunSkillsAndStamp_FailureKeepsOldStamp(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			r := &selfupdate.NpmResult{}
+			r.Err = fmt.Errorf("npx failed")
+			return r
+		},
+	}
+	got := runSkillsAndStamp(updater, newTestIO(), "1.0.21", false)
+	if got == nil || got.Err == nil {
+		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with non-nil Err", got)
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.20" {
+		t.Errorf("stamp = %q, want \"1.0.20\" (failure must not overwrite)", stamp)
+	}
+}
+
 func TestTruncate(t *testing.T) {
 	long := strings.Repeat("x", 3000)
 	got := selfupdate.Truncate(long, 2000)
@@ -849,3 +971,272 @@ func TestTruncate(t *testing.T) {
 		t.Errorf("expected 'hello', got %q", got2)
 	}
 }
+
+func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.21", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	skillsCalled := false
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, _, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun() err = %v, want nil", err)
+	}
+	if !skillsCalled {
+		t.Error("RunSkillsUpdate not called in already-up-to-date branch (cold stamp), want called")
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.21" {
+		t.Errorf("stamp = %q, want \"1.0.21\"", stamp)
+	}
+}
+
+func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.22", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	skillsCalled := false
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			DetectOverride: func() selfupdate.DetectResult {
+				return selfupdate.DetectResult{
+					Method:       selfupdate.InstallManual,
+					ResolvedPath: "/usr/local/bin/lark-cli",
+				}
+			},
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, _, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun() err = %v, want nil", err)
+	}
+	if !skillsCalled {
+		t.Error("RunSkillsUpdate not called in manual branch, want called")
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.21" {
+		t.Errorf("stamp = %q, want \"1.0.21\" (manual path stamps cur)", stamp)
+	}
+}
+
+func TestUpdateRun_Npm_RunsSkillsSync_StampsLatest(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.22", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	skillsCalled := false
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			DetectOverride: func() selfupdate.DetectResult {
+				return selfupdate.DetectResult{
+					Method: selfupdate.InstallNpm, NpmAvailable: true,
+					ResolvedPath: "/usr/local/bin/lark-cli",
+				}
+			},
+			NpmInstallOverride: func(version string) *selfupdate.NpmResult {
+				return &selfupdate.NpmResult{}
+			},
+			VerifyOverride: func(expectedVersion string) error { return nil },
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, _, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun() err = %v, want nil", err)
+	}
+	if !skillsCalled {
+		t.Error("RunSkillsUpdate not called in npm branch")
+	}
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.22" {
+		t.Errorf("stamp = %q, want \"1.0.22\" (npm path stamps latest)", stamp)
+	}
+}
+
+func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.22", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	skillsCalled := false
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			DetectOverride: func() selfupdate.DetectResult {
+				return selfupdate.DetectResult{Method: selfupdate.InstallNpm, NpmAvailable: true}
+			},
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, stdout, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true, Check: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun(--check) err = %v, want nil", err)
+	}
+	if skillsCalled {
+		t.Error("RunSkillsUpdate called under --check, want skipped (pure report)")
+	}
+
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("json.Unmarshal stdout: %v\nstdout: %s", err, stdout.String())
+	}
+	status, ok := env["skills_status"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("skills_status missing or wrong type in --check JSON: %s", stdout.String())
+	}
+	if status["current"] != "1.0.20" || status["target"] != "1.0.21" || status["in_sync"] != false {
+		t.Errorf("skills_status = %+v, want {current:\"1.0.20\", target:\"1.0.21\", in_sync:false}", status)
+	}
+}
+
+func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := skillscheck.WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+
+	origFetch := fetchLatest
+	origCur := currentVersion
+	t.Cleanup(func() { fetchLatest = origFetch; currentVersion = origCur })
+	fetchLatest = func() (string, error) { return "1.0.21", nil }
+	currentVersion = func() string { return "1.0.21" }
+
+	skillsCalled := false
+	origNew := newUpdater
+	t.Cleanup(func() { newUpdater = origNew })
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{
+			SkillsUpdateOverride: func() *selfupdate.NpmResult {
+				skillsCalled = true
+				return &selfupdate.NpmResult{}
+			},
+		}
+	}
+
+	f, stdout, _ := newTestFactory(t)
+	opts := &UpdateOptions{Factory: f, JSON: true, Check: true}
+	if err := updateRun(opts); err != nil {
+		t.Fatalf("updateRun(--check, already-latest) err = %v, want nil", err)
+	}
+	if skillsCalled {
+		t.Error("RunSkillsUpdate called under --check (already-latest), want skipped (pure report)")
+	}
+
+	stamp, _ := skillscheck.ReadStamp()
+	if stamp != "1.0.20" {
+		t.Errorf("stamp mutated to %q under --check, want \"1.0.20\" (pure report must not write stamp)", stamp)
+	}
+
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("json.Unmarshal stdout: %v\n%s", err, stdout.String())
+	}
+	if env["action"] != "already_up_to_date" {
+		t.Errorf("action = %v, want \"already_up_to_date\"", env["action"])
+	}
+	if _, has := env["skills_action"]; has {
+		t.Errorf("skills_action present under --check, want absent: %+v", env)
+	}
+	status, ok := env["skills_status"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("skills_status missing under --check + already-latest: %s", stdout.String())
+	}
+	if status["current"] != "1.0.20" || status["target"] != "1.0.21" || status["in_sync"] != false {
+		t.Errorf("skills_status = %+v, want {current:\"1.0.20\", target:\"1.0.21\", in_sync:false}", status)
+	}
+}
+
+// TestRunSkillsAndStamp_StampWriteFailureWarns verifies the stderr warning
+// emission when RunSkillsUpdate succeeds but WriteStamp fails.
+func TestRunSkillsAndStamp_StampWriteFailureWarns(t *testing.T) {
+	// Force WriteStamp to fail by pointing config dir at a path that exists
+	// as a regular file (so MkdirAll fails).
+	tmp := t.TempDir()
+	badPath := filepath.Join(tmp, "blocker")
+	if err := os.WriteFile(badPath, []byte("not-a-dir"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", badPath)
+
+	f, _, stderr := newTestFactory(t)
+	updater := &selfupdate.Updater{
+		SkillsUpdateOverride: func() *selfupdate.NpmResult {
+			return &selfupdate.NpmResult{} // success
+		},
+	}
+	got := runSkillsAndStamp(updater, f.IOStreams, "1.0.21", false)
+	if got == nil || got.Err != nil {
+		t.Fatalf("runSkillsAndStamp() = %+v, want non-nil with nil Err", got)
+	}
+	if !strings.Contains(stderr.String(), "warning: skills synced but stamp not written") {
+		t.Errorf("stderr does not contain warning: %q", stderr.String())
+	}
+}
+
+// TestEmitSkillsTextHints_Success verifies the "Skills updated" success
+// message is printed to ErrOut on a successful (Err == nil) result.
+func TestEmitSkillsTextHints_Success(t *testing.T) {
+	f, _, stderr := newTestFactory(t)
+	emitSkillsTextHints(f.IOStreams, &selfupdate.NpmResult{}) // Err==nil → success
+	if !strings.Contains(stderr.String(), "Skills updated") {
+		t.Errorf("stderr does not contain 'Skills updated': %q", stderr.String())
+	}
+}

internal/auth/errors.go

@@ -4,7 +4,9 @@
 package auth
 
 import (
+	"errors"
 	"fmt"
+	"strings"
 
 	"github.com/larksuite/cli/internal/output"
 )
@@ -12,6 +14,7 @@ import (
 const (
 	LarkErrBlockByPolicy        = 21001 // access denied by access control policy
 	LarkErrBlockByPolicyTryAuth = 21000 // access denied by access control policy; challenge is required to be completed by user in order to gain access
+	needUserAuthorizationMarker = "need_user_authorization"
 )
 
 // RefreshTokenRetryable contains error codes that allow one immediate retry.
@@ -33,7 +36,26 @@ type NeedAuthorizationError struct {
 
 // Error returns the error message for NeedAuthorizationError.
 func (e *NeedAuthorizationError) Error() string {
-	return fmt.Sprintf("need_user_authorization (user: %s)", e.UserOpenId)
+	return fmt.Sprintf("%s (user: %s)", needUserAuthorizationMarker, e.UserOpenId)
+}
+
+// IsNeedUserAuthorizationError reports whether err represents a missing-UAT
+// failure, either as the original auth error or as a wrapped ExitError.
+func IsNeedUserAuthorizationError(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	var needAuthErr *NeedAuthorizationError
+	if errors.As(err, &needAuthErr) {
+		return true
+	}
+
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) && exitErr.Detail != nil {
+		return strings.Contains(exitErr.Detail.Message, needUserAuthorizationMarker)
+	}
+	return strings.Contains(err.Error(), needUserAuthorizationMarker)
 }
 
 // SecurityPolicyError is returned when a request is blocked by access control policies.

internal/auth/errors_test.go

@@ -0,0 +1,38 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"testing"
+
+	"github.com/larksuite/cli/internal/output"
+)
+
+func TestIsNeedUserAuthorizationError(t *testing.T) {
+	t.Run("nil error", func(t *testing.T) {
+		if IsNeedUserAuthorizationError(nil) {
+			t.Fatal("expected nil error not to match")
+		}
+	})
+
+	t.Run("direct auth error", func(t *testing.T) {
+		if !IsNeedUserAuthorizationError(&NeedAuthorizationError{UserOpenId: "u_1"}) {
+			t.Fatal("expected direct NeedAuthorizationError to match")
+		}
+	})
+
+	t.Run("wrapped exit error", func(t *testing.T) {
+		err := output.ErrNetwork("API call failed: %s", &NeedAuthorizationError{})
+		if !IsNeedUserAuthorizationError(err) {
+			t.Fatal("expected wrapped ExitError to match")
+		}
+	})
+
+	t.Run("other error", func(t *testing.T) {
+		err := output.ErrNetwork("API call failed: timeout")
+		if IsNeedUserAuthorizationError(err) {
+			t.Fatal("expected unrelated error not to match")
+		}
+	})
+}

internal/binding/audit.go

@@ -65,7 +65,11 @@ func AssertSecurePath(params AuditParams) (string, error) {
 }
 
 // requireAbsolutePath rejects relative paths; relative paths would depend on
-// the process cwd and defeat the point of a static audit.
+// the process cwd and defeat the point of a static audit. Shell-style
+// shortcuts like `~` are home-relative, not cwd-relative — they are an
+// orthogonal concern and the audit is intentionally Go-stdlib strict here.
+// Callers that accept user-authored config (e.g. resolveFileRef) must
+// pre-resolve any such shortcuts before passing the path in.
 func requireAbsolutePath(target, label string) error {
 	if !filepath.IsAbs(target) {
 		return fmt.Errorf("%s: path must be absolute, got %q", label, target)

internal/binding/json_pointer.go

@@ -33,8 +33,10 @@ func ReadJSONPointer(data interface{}, pointer string) (interface{}, error) {
 
 	for i, raw := range segments {
 		// RFC 6901 unescaping: ~1 → /, ~0 → ~ (order matters).
-		key := strings.ReplaceAll(raw, "~1", "/")
-		key = strings.ReplaceAll(key, "~0", "~")
+		key, err := decodeJSONPointerSegment(raw)
+		if err != nil {
+			return nil, fmt.Errorf("json pointer %q: segment %q: %w", pointer, raw, err)
+		}
 
 		m, ok := current.(map[string]interface{})
 		if !ok {
@@ -53,3 +55,26 @@ func ReadJSONPointer(data interface{}, pointer string) (interface{}, error) {
 
 	return current, nil
 }
+
+func decodeJSONPointerSegment(raw string) (string, error) {
+	var out strings.Builder
+	for i := 0; i < len(raw); i++ {
+		if raw[i] != '~' {
+			out.WriteByte(raw[i])
+			continue
+		}
+		if i+1 >= len(raw) {
+			return "", fmt.Errorf("invalid escape: ~ must be followed by 0 or 1")
+		}
+		switch raw[i+1] {
+		case '0':
+			out.WriteByte('~')
+		case '1':
+			out.WriteByte('/')
+		default:
+			return "", fmt.Errorf("invalid escape: ~%c must be ~0 or ~1", raw[i+1])
+		}
+		i++
+	}
+	return out.String(), nil
+}

internal/binding/json_pointer_test.go

@@ -98,6 +98,41 @@ func TestReadJSONPointer_RFC6901_Escaping(t *testing.T) {
 	}
 }
 
+func TestReadJSONPointer_InvalidEscape(t *testing.T) {
+	data := map[string]interface{}{
+		"a~2b": "literal",
+		"a~":   "literal",
+	}
+	tests := []struct {
+		name    string
+		pointer string
+		want    string
+	}{
+		{
+			name:    "unsupported escape code",
+			pointer: "/a~2b",
+			want:    `json pointer "/a~2b": segment "a~2b": invalid escape: ~2 must be ~0 or ~1`,
+		},
+		{
+			name:    "dangling tilde",
+			pointer: "/a~",
+			want:    `json pointer "/a~": segment "a~": invalid escape: ~ must be followed by 0 or 1`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := ReadJSONPointer(data, tt.pointer)
+			if err == nil {
+				t.Fatal("expected error for invalid escape, got nil")
+			}
+			if err.Error() != tt.want {
+				t.Errorf("error = %q, want %q", err.Error(), tt.want)
+			}
+		})
+	}
+}
+
 func TestReadJSONPointer_InvalidFormat(t *testing.T) {
 	data := map[string]interface{}{"key": "val"}
 	_, err := ReadJSONPointer(data, "no-leading-slash")

internal/binding/lark_channel.go

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// LarkChannelRoot captures ~/.lark-channel/config.json.
+// Schema mirrors lark-channel-bridge/src/config/schema.ts:AppConfig.
+// Unknown fields are ignored — forward-compatible with future bridge versions.
+type LarkChannelRoot struct {
+	Accounts LarkChannelAccounts `json:"accounts"`
+	// Secrets is an optional registry of secret providers — same shape as
+	// openclaw's `secrets` block. Lets bridge declare `exec` provider scripts
+	// (for AES-encrypted secret backends), `env` allowlists, or `file`
+	// indirection rules. Resolved by binding.ResolveSecretInput.
+	Secrets *SecretsConfig `json:"secrets,omitempty"`
+}
+
+// LarkChannelAccounts is the namespace for credential entries.
+// Currently only `app` is defined; left as a struct (not a flat field) so
+// future entries (oauth, alternate apps) can be added without re-shaping the
+// top-level on disk.
+type LarkChannelAccounts struct {
+	App LarkChannelApp `json:"app"`
+}
+
+// LarkChannelApp is the bot app credential entry.
+//
+// `Secret` accepts the full SecretInput protocol (string / "${VAR}" template /
+// SecretRef object with source env|file|exec) so users can keep secrets out
+// of config.json — either by referencing an env var the bridge inherits, a
+// chmod-0400 file outside the bridge dir, or an exec script that decrypts a
+// local AES-encrypted secret store. Aligns lark-channel with the same secret
+// protocol openclaw already uses.
+type LarkChannelApp struct {
+	ID     string      `json:"id"`
+	Secret SecretInput `json:"secret"`
+	Tenant string      `json:"tenant"` // "feishu" | "lark"
+}
+
+// ReadLarkChannelConfig reads and parses ~/.lark-channel/config.json.
+func ReadLarkChannelConfig(path string) (*LarkChannelRoot, error) {
+	data, err := vfs.ReadFile(path)
+	if err != nil {
+		return nil, err // caller formats user-facing message with path context
+	}
+
+	var root LarkChannelRoot
+	if err := json.Unmarshal(data, &root); err != nil {
+		return nil, fmt.Errorf("invalid JSON in %s: %w", path, err)
+	}
+
+	return &root, nil
+}

internal/binding/lark_channel_test.go

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestReadLarkChannelConfig_Valid(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{"accounts":{"app":{"id":"cli_abc123","secret":"plain_secret","tenant":"feishu"}}}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	root, err := ReadLarkChannelConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := root.Accounts.App.ID; got != "cli_abc123" {
+		t.Errorf("ID = %q, want %q", got, "cli_abc123")
+	}
+	if got := root.Accounts.App.Secret.Plain; got != "plain_secret" {
+		t.Errorf("Secret.Plain = %q, want %q", got, "plain_secret")
+	}
+	if root.Accounts.App.Secret.Ref != nil {
+		t.Errorf("expected Plain form, got SecretRef = %+v", root.Accounts.App.Secret.Ref)
+	}
+	if got := root.Accounts.App.Tenant; got != "feishu" {
+		t.Errorf("Tenant = %q, want %q", got, "feishu")
+	}
+}
+
+func TestReadLarkChannelConfig_LarkTenant(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{"accounts":{"app":{"id":"cli_xyz","secret":"s","tenant":"lark"}}}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	root, err := ReadLarkChannelConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := root.Accounts.App.Tenant; got != "lark" {
+		t.Errorf("Tenant = %q, want %q", got, "lark")
+	}
+}
+
+func TestReadLarkChannelConfig_MissingFile(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "does-not-exist.json")
+
+	_, err := ReadLarkChannelConfig(p)
+	if err == nil {
+		t.Fatal("expected error for missing file, got nil")
+	}
+	if !os.IsNotExist(err) {
+		t.Errorf("expected os.IsNotExist, got %v", err)
+	}
+}
+
+func TestReadLarkChannelConfig_MalformedJSON(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	if err := os.WriteFile(p, []byte("{not valid json"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	_, err := ReadLarkChannelConfig(p)
+	if err == nil {
+		t.Fatal("expected error for malformed JSON, got nil")
+	}
+}
+
+func TestReadLarkChannelConfig_PartialFields(t *testing.T) {
+	// schema isComplete check belongs at the binder layer; the reader should
+	// happily parse a partial config — emptiness is detected downstream.
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{"accounts":{"app":{}}}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	root, err := ReadLarkChannelConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if root.Accounts.App.ID != "" {
+		t.Errorf("expected empty ID, got %q", root.Accounts.App.ID)
+	}
+	if !root.Accounts.App.Secret.IsZero() {
+		t.Errorf("expected zero Secret, got %+v", root.Accounts.App.Secret)
+	}
+}
+
+func TestReadLarkChannelConfig_SecretEnvTemplate(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{"accounts":{"app":{"id":"cli_a","secret":"${LARK_APP_SECRET}","tenant":"feishu"}}}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+	root, err := ReadLarkChannelConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := root.Accounts.App.Secret.Plain; got != "${LARK_APP_SECRET}" {
+		t.Errorf("Secret.Plain = %q, want template string", got)
+	}
+}
+
+func TestReadLarkChannelConfig_SecretRefExec(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{
+		"accounts": {
+			"app": {
+				"id": "cli_a",
+				"secret": {"source": "exec", "provider": "decrypt", "id": "app-cli_a"},
+				"tenant": "feishu"
+			}
+		},
+		"secrets": {
+			"providers": {
+				"decrypt": {"source": "exec", "command": "/usr/local/bin/lark-channel-bridge", "args": ["secrets", "get"]}
+			}
+		}
+	}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+	root, err := ReadLarkChannelConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if root.Accounts.App.Secret.Ref == nil {
+		t.Fatal("expected SecretRef, got Plain")
+	}
+	if got := root.Accounts.App.Secret.Ref.Source; got != "exec" {
+		t.Errorf("Secret.Ref.Source = %q, want %q", got, "exec")
+	}
+	if got := root.Accounts.App.Secret.Ref.ID; got != "app-cli_a" {
+		t.Errorf("Secret.Ref.ID = %q, want %q", got, "app-cli_a")
+	}
+	if root.Secrets == nil || root.Secrets.Providers["decrypt"] == nil {
+		t.Errorf("expected secrets.providers[decrypt] to be parsed")
+	}
+}
+
+func TestReadLarkChannelConfig_SecretRefInvalidSource(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{"accounts":{"app":{"id":"cli_a","secret":{"source":"bogus","id":"x"},"tenant":"feishu"}}}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+	if _, err := ReadLarkChannelConfig(p); err == nil {
+		t.Fatal("expected error for invalid secret source, got nil")
+	}
+}
+
+func TestReadLarkChannelConfig_UnknownFieldsIgnored(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{
+		"accounts": {
+			"app": {"id": "cli_a", "secret": "s", "tenant": "feishu"},
+			"oauth": {"clientId": "ignored"}
+		},
+		"preferences": {"theme": "dark"}
+	}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	root, err := ReadLarkChannelConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := root.Accounts.App.ID; got != "cli_a" {
+		t.Errorf("ID = %q, want %q", got, "cli_a")
+	}
+}

internal/binding/secret_resolve_file.go

@@ -23,9 +23,19 @@ func resolveFileRef(ref *SecretRef, pc *ProviderConfig) (string, error) {
 		return "", fmt.Errorf("file provider path is empty")
 	}
 
+	// OpenClaw preserves user-authored `~/...` paths verbatim on disk for
+	// portability and resolves them at read time. lark-cli reads the file
+	// raw, so we mirror that resolution here before the audit — otherwise
+	// an unambiguous home-relative path would be rejected by
+	// requireAbsolutePath, which is meant to guard against cwd-relative
+	// paths (a different concern). expandTildePath honours OPENCLAW_HOME so
+	// a tilde inside an OPENCLAW_HOME-overridden config resolves to the
+	// same absolute path OpenClaw itself would have used.
+	targetPath := expandTildePath(pc.Path)
+
 	// Security audit on file path
 	securePath, err := AssertSecurePath(AuditParams{
-		TargetPath:            pc.Path,
+		TargetPath:            targetPath,
 		Label:                 "secrets.providers file path",
 		TrustedDirs:           pc.TrustedDirs,
 		AllowInsecurePath:     pc.AllowInsecurePath,

internal/binding/secret_resolve_file_test.go

@@ -6,6 +6,7 @@ package binding
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -230,3 +231,88 @@ func TestResolveFileRef_ExceedsMaxBytes(t *testing.T) {
 		t.Errorf("error = %q, want %q", err.Error(), want)
 	}
 }
+
+// TestResolveFileRef_TildePath_SingleValue is the end-to-end smoke test
+// for the fix: a singleValue file provider with a ~/-relative path
+// resolves correctly through resolveFileRef. Before this PR the audit
+// would reject the path as "must be absolute".
+func TestResolveFileRef_TildePath_SingleValue(t *testing.T) {
+	dir := t.TempDir()
+	setFakeOSHome(t, dir)
+	t.Setenv("OPENCLAW_HOME", "")
+
+	p := filepath.Join(dir, "secret.txt")
+	if err := os.WriteFile(p, []byte("tilde_secret\n"), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	ref := &SecretRef{Source: "file", ID: SingleValueFileRefID}
+	pc := &ProviderConfig{
+		Source:            "file",
+		Path:              "~/secret.txt",
+		Mode:              "singleValue",
+		AllowInsecurePath: true,
+	}
+
+	got, err := resolveFileRef(ref, pc)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "tilde_secret" {
+		t.Errorf("got %q, want %q", got, "tilde_secret")
+	}
+}
+
+// TestResolveFileRef_RelativePath_StillRejected guards the absolute-path
+// audit: cwd-relative input must still be rejected even though tilde was
+// loosened. Catches regressions if expandTildePath is ever widened to
+// also expand "./..." (which would weaken the audit's invariant).
+func TestResolveFileRef_RelativePath_StillRejected(t *testing.T) {
+	ref := &SecretRef{Source: "file", ID: SingleValueFileRefID}
+	pc := &ProviderConfig{
+		Source:            "file",
+		Path:              "relative/secret.txt",
+		Mode:              "singleValue",
+		AllowInsecurePath: true,
+	}
+
+	_, err := resolveFileRef(ref, pc)
+	if err == nil {
+		t.Fatal("expected error for relative path, got nil")
+	}
+	wantSub := "path must be absolute"
+	if !strings.Contains(err.Error(), wantSub) {
+		t.Errorf("error = %q, want substring %q", err.Error(), wantSub)
+	}
+}
+
+// TestResolveFileRef_TildePath_JSONMode verifies the tilde-expansion
+// path works for json mode (where ref id is a JSON pointer) as well as
+// singleValue mode — the mechanism is mode-agnostic.
+func TestResolveFileRef_TildePath_JSONMode(t *testing.T) {
+	dir := t.TempDir()
+	setFakeOSHome(t, dir)
+	t.Setenv("OPENCLAW_HOME", "")
+
+	p := filepath.Join(dir, "secrets.json")
+	content := `{"providers":{"feishu":{"key":"json_via_tilde"}}}`
+	if err := os.WriteFile(p, []byte(content), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+
+	ref := &SecretRef{Source: "file", ID: "/providers/feishu/key"}
+	pc := &ProviderConfig{
+		Source:            "file",
+		Path:              "~/secrets.json",
+		Mode:              "json",
+		AllowInsecurePath: true,
+	}
+
+	got, err := resolveFileRef(ref, pc)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "json_via_tilde" {
+		t.Errorf("got %q, want %q", got, "json_via_tilde")
+	}
+}

internal/binding/tilde.go

@@ -0,0 +1,180 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"os"
+	"os/user"
+	"path/filepath"
+	"strings"
+
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// hasTildePrefix reports whether s begins with `~` followed by end-of-string,
+// `/`, or `\` — the form OpenClaw treats as home-relative.
+func hasTildePrefix(s string) bool {
+	if s == "" || s[0] != '~' {
+		return false
+	}
+	if len(s) == 1 {
+		return true
+	}
+	return s[1] == '/' || s[1] == '\\'
+}
+
+// joinTildeSuffix expands a tilde-prefixed string against a resolved home
+// directory. Replaces only the leading `~` so the original separator
+// (forward or back slash) and suffix bytes are kept verbatim, matching
+// OpenClaw's `input.replace(/^~(?=$|[\\/])/, home)` semantics rather than
+// going through filepath.Join (which would silently drop a literal `\` on
+// POSIX). filepath.Clean is applied so `..` and duplicate separators are
+// collapsed in the same way Node's path.resolve does on each platform.
+//
+// Caller must ensure hasTildePrefix(s) is true and home is non-empty.
+func joinTildeSuffix(s, home string) string {
+	if len(s) == 1 {
+		return home
+	}
+	return filepath.Clean(home + s[1:])
+}
+
+// normalizeSentinel applies OpenClaw's normalize() helper to a single
+// string: trims whitespace and treats the JS-flavoured literals
+// "undefined" / "null" (along with empty/whitespace-only) as unset.
+func normalizeSentinel(v string) string {
+	v = strings.TrimSpace(v)
+	if v == "undefined" || v == "null" {
+		return ""
+	}
+	return v
+}
+
+// osHome returns the OS-level home directory by walking OpenClaw's
+// resolution chain: HOME → USERPROFILE → OS user database (getpwuid on
+// Unix / user32 on Windows, via os/user.Current). Each candidate is
+// passed through normalizeSentinel so sentinel literals and blank
+// strings fall through.
+//
+// Matches OpenClaw's resolveRawOsHomeDir env chain so the same tilde
+// resolves against the same home under mixed shell environments and
+// accidentally-stringified env values. Go's stdlib os.UserHomeDir on
+// Unix only re-reads HOME and gives up; Node's os.homedir() still
+// returns the account home via the user database, so the explicit
+// user.Current() step is what keeps OpenClaw-authored `~/...` working
+// in HOME-unset shells.
+//
+// Deliberate hybrid contract — neither a strict mirror of OpenClaw
+// nor a strict reject-on-missing:
+//
+//   - OpenClaw's final fallback is cwd (via resolveRequiredHomeDir →
+//     process.cwd()). We don't do that because requireAbsolutePath
+//     exists precisely to reject cwd-dependent paths; routing
+//     `~/secret` through cwd would defeat the audit invariant.
+//
+//   - We still go through user.Current() before giving up, even when
+//     HOME is a sentinel literal ("undefined" / "null") and
+//     USERPROFILE is unset. At that point OpenClaw would land on cwd,
+//     and a strict implementation would reject; user.Current() lands
+//     on the account home instead — cwd-independent and user-bound,
+//     so it satisfies the audit's safety goal while still letting
+//     ~/-authored configs resolve in a malformed-env shell.
+//
+//   - Only returns "" when the env chain AND user.Current() are all
+//     unresolvable, at which point the caller surfaces a clean
+//     "path must be absolute" error from the audit.
+func osHome() string {
+	if v := normalizeSentinel(os.Getenv("HOME")); v != "" {
+		return v
+	}
+	if v := normalizeSentinel(os.Getenv("USERPROFILE")); v != "" {
+		return v
+	}
+	if u, err := user.Current(); err == nil {
+		return normalizeSentinel(u.HomeDir)
+	}
+	return ""
+}
+
+// explicitOpenClawHome reads OPENCLAW_HOME with OpenClaw's normalize()
+// semantics applied.
+func explicitOpenClawHome() string {
+	return normalizeSentinel(os.Getenv("OPENCLAW_HOME"))
+}
+
+// absolutize returns p as an absolute path, resolving against the process
+// cwd when p is relative. Returns "" when the cwd cannot be resolved.
+// Wraps filepath.Abs semantics via vfs.Getwd because forbidigo bans
+// filepath.Abs inside internal/ packages.
+func absolutize(p string) string {
+	if p == "" {
+		return ""
+	}
+	if filepath.IsAbs(p) {
+		return filepath.Clean(p)
+	}
+	wd, err := vfs.Getwd()
+	if err != nil {
+		return ""
+	}
+	return filepath.Join(wd, p)
+}
+
+// openClawHome returns the home directory used to resolve `~`-relative paths
+// authored against OpenClaw's config. Closely mirrors OpenClaw's
+// home-resolution semantics so the same tilde resolves to the same
+// absolute path here as inside OpenClaw runtime under all normal
+// conditions.
+//
+// Resolution order:
+//  1. OPENCLAW_HOME env var, when set (sentinel-normalised).
+//  2. If OPENCLAW_HOME itself has a tilde prefix, expand it against the OS
+//     home (see osHome); the result is empty when the OS home is
+//     unresolvable.
+//  3. Otherwise fall back to the OS home.
+//
+// The returned path is absolute (relative OPENCLAW_HOME values are
+// absolutised against the process cwd, matching Node path.resolve in
+// OpenClaw's pipeline).
+//
+// Returns "" when no home can be resolved. This is a deliberate
+// divergence from OpenClaw, whose read pipeline would fall back to
+// cwd via resolveRequiredHomeDir — see osHome for the rationale.
+func openClawHome() string {
+	raw := explicitOpenClawHome()
+	switch {
+	case raw == "":
+		raw = osHome()
+	case hasTildePrefix(raw):
+		h := osHome()
+		if h == "" {
+			return ""
+		}
+		raw = joinTildeSuffix(raw, h)
+	}
+	return absolutize(raw)
+}
+
+// expandTildePath resolves a leading `~` or `~/...` prefix to OpenClaw's
+// effective home directory (see openClawHome).
+//
+// Returns the input unchanged when it lacks a tilde prefix or when
+// openClawHome cannot resolve a home directory. The latter case is a
+// deliberate divergence from OpenClaw, whose read pipeline falls back
+// to cwd — see osHome. Surfacing a "path must be absolute" error from
+// the audit is preferable to silently routing a user-authored
+// `~/secret` through cwd resolution.
+//
+// `~user` shell-style expansion is intentionally not supported (OpenClaw
+// does not support it either).
+func expandTildePath(p string) string {
+	if !hasTildePrefix(p) {
+		return p
+	}
+	home := openClawHome()
+	if home == "" {
+		return p
+	}
+	return joinTildeSuffix(p, home)
+}

internal/binding/tilde_test.go

@@ -0,0 +1,293 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package binding
+
+import (
+	"os"
+	"os/user"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+// setFakeOSHome controls osHome's env-chain inputs (HOME and USERPROFILE)
+// in one call so tests stay deterministic across platforms. osHome reads
+// HOME first, then USERPROFILE, then user.Current(); setting only one of
+// the two leaves the test sensitive to whichever the runner happens to
+// have populated. Passing dir == "" disables both env entries so tests
+// can exercise the user.Current() fallback or no-home edge cases.
+func setFakeOSHome(t *testing.T, dir string) {
+	t.Helper()
+	t.Setenv("HOME", dir)
+	t.Setenv("USERPROFILE", dir)
+}
+
+// isolateRuntimeWrites parks the process cwd in a fresh TempDir for the
+// test's duration. Tests that set HOME to a sentinel literal trigger Go
+// runtime side effects — most visibly the telemetry subsystem, which
+// calls os.UserConfigDir() (= "$HOME/Library/Application Support" on
+// darwin) and happily writes through a relative result like
+// "undefined/Library/...". Without isolation those files land in the
+// package or repo dir and get accidentally staged. Chdir'ing into a
+// TempDir routes the noise into a path testing.T auto-cleans.
+func isolateRuntimeWrites(t *testing.T) {
+	t.Helper()
+	orig, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	if err := os.Chdir(t.TempDir()); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = os.Chdir(orig)
+	})
+}
+
+// TestOpenClawHome covers the openClawHome resolution table: empty /
+// sentinel OPENCLAW_HOME falls back to the OS home, explicit absolute
+// values are used verbatim (with whitespace trimmed), and tilde-prefixed
+// values recurse through the OS home.
+func TestOpenClawHome(t *testing.T) {
+	homeDir := t.TempDir()
+	explicit := t.TempDir()
+	setFakeOSHome(t, homeDir)
+
+	tests := []struct {
+		name        string
+		openclawEnv string
+		want        string
+	}{
+		{"unset falls back to OS home", "", homeDir},
+		{"undefined literal treated as unset", "undefined", homeDir},
+		{"null literal treated as unset", "null", homeDir},
+		{"whitespace-only treated as unset", "   ", homeDir},
+		{"explicit absolute path used verbatim", explicit, explicit},
+		{"explicit absolute path is trimmed", "  " + explicit + "  ", explicit},
+		{"bare tilde resolves to OS home", "~", homeDir},
+		{"tilde-prefixed value recurses through OS home", "~/custom", filepath.Join(homeDir, "custom")},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv("OPENCLAW_HOME", tc.openclawEnv)
+			got := openClawHome()
+			if got != tc.want {
+				t.Errorf("openClawHome() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+// TestOpenClawHome_RelativeIsAbsolutized confirms a relative
+// OPENCLAW_HOME is resolved against the process cwd, mirroring Node's
+// path.resolve behaviour in OpenClaw.
+func TestOpenClawHome_RelativeIsAbsolutized(t *testing.T) {
+	t.Setenv("OPENCLAW_HOME", filepath.FromSlash("relative/dir"))
+	got := openClawHome()
+
+	if !filepath.IsAbs(got) {
+		t.Fatalf("openClawHome() = %q, want absolute path", got)
+	}
+	wantSuffix := filepath.FromSlash("relative/dir")
+	if !strings.HasSuffix(got, wantSuffix) {
+		t.Errorf("openClawHome() = %q, want suffix %q", got, wantSuffix)
+	}
+}
+
+// TestOpenClawHome_FallsBackToUserDatabase pins osHome's final fallback
+// to the OS user database when HOME and USERPROFILE are both unset,
+// matching Node's os.homedir() (which uses getpwuid). Cwd-independent
+// and user-bound, so it does not conflict with the "no cwd fallback"
+// rule documented on osHome.
+func TestOpenClawHome_FallsBackToUserDatabase(t *testing.T) {
+	u, err := user.Current()
+	if err != nil || u.HomeDir == "" {
+		t.Skip("os/user.Current() unavailable on this runner")
+	}
+	setFakeOSHome(t, "")
+	t.Setenv("OPENCLAW_HOME", "")
+	got := openClawHome()
+	if got != u.HomeDir {
+		t.Errorf("openClawHome() = %q, want %q (account home from user.Current)", got, u.HomeDir)
+	}
+}
+
+// TestOpenClawHome_TildeOpenClawHomeUsesUserDatabaseFallback pins that
+// a tilde-form OPENCLAW_HOME ("~/custom") expands against the
+// user-database fallback when HOME and USERPROFILE are both unset.
+// Without the user.Current() step in osHome this would have failed
+// (returning "") and dropped the bind back to the audit's
+// "path must be absolute" error.
+func TestOpenClawHome_TildeOpenClawHomeUsesUserDatabaseFallback(t *testing.T) {
+	u, err := user.Current()
+	if err != nil || u.HomeDir == "" {
+		t.Skip("os/user.Current() unavailable on this runner")
+	}
+	setFakeOSHome(t, "")
+	t.Setenv("OPENCLAW_HOME", "~/custom")
+	got := openClawHome()
+	want := filepath.Join(u.HomeDir, "custom")
+	if got != want {
+		t.Errorf("openClawHome() = %q, want %q", got, want)
+	}
+}
+
+// TestExpandTildePath covers the full input grid for expandTildePath:
+// bare tilde, tilde-slash, tilde + suffix, nested suffix, plain absolute
+// and relative literals, and the intentionally-unchanged forms (~user,
+// ~foo) that OpenClaw does not expand either.
+func TestExpandTildePath(t *testing.T) {
+	fakeHome := t.TempDir()
+	absFixture := filepath.Join(fakeHome, "abs.json")
+	setFakeOSHome(t, fakeHome)
+	t.Setenv("OPENCLAW_HOME", "")
+
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{"empty", "", ""},
+		{"bare tilde", "~", fakeHome},
+		{"tilde slash", "~/", fakeHome},
+		{"tilde with file", "~/secret.json", filepath.Join(fakeHome, "secret.json")},
+		{"tilde with nested path", "~/.openclaw/secret.json", filepath.Join(fakeHome, ".openclaw/secret.json")},
+		{"absolute unchanged", absFixture, absFixture},
+		{"relative unchanged", "foo/bar", "foo/bar"},
+		{"dot relative unchanged", "../foo", "../foo"},
+		{"tilde user form unchanged", "~root/foo", "~root/foo"},
+		{"tilde without separator unchanged", "~foo", "~foo"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := expandTildePath(tc.in)
+			if got != tc.want {
+				t.Errorf("expandTildePath(%q) = %q, want %q", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestExpandTildePath_RespectsOpenClawHome verifies that with
+// OPENCLAW_HOME set, tilde expansion uses that custom home rather than
+// the OS home — the integration-level invariant that closes the
+// internal inconsistency CodeX's first review flagged.
+func TestExpandTildePath_RespectsOpenClawHome(t *testing.T) {
+	homeDir := t.TempDir()
+	clawHome := t.TempDir()
+	setFakeOSHome(t, homeDir)
+	t.Setenv("OPENCLAW_HOME", clawHome)
+
+	got := expandTildePath("~/secret.json")
+	want := filepath.Join(clawHome, "secret.json")
+	if got != want {
+		t.Errorf("expandTildePath(%q) = %q, want %q (should use OPENCLAW_HOME)", "~/secret.json", got, want)
+	}
+	if got == filepath.Join(homeDir, "secret.json") {
+		t.Errorf("expandTildePath unexpectedly used OS home %q instead of OPENCLAW_HOME %q", homeDir, clawHome)
+	}
+}
+
+// TestExpandTildePath_FallsBackToUserDatabase is the end-to-end
+// equivalent of TestOpenClawHome_FallsBackToUserDatabase: with HOME and
+// USERPROFILE both unset, expandTildePath still resolves `~/foo` via
+// osHome's user.Current() step. Matches Node os.homedir() and keeps
+// OpenClaw-authored configs working in minimal-env shells.
+func TestExpandTildePath_FallsBackToUserDatabase(t *testing.T) {
+	u, err := user.Current()
+	if err != nil || u.HomeDir == "" {
+		t.Skip("os/user.Current() unavailable on this runner")
+	}
+	setFakeOSHome(t, "")
+	t.Setenv("OPENCLAW_HOME", "")
+	got := expandTildePath("~/foo")
+	want := filepath.Join(u.HomeDir, "foo")
+	if got != want {
+		t.Errorf("expandTildePath(~/foo) = %q, want %q", got, want)
+	}
+}
+
+// TestOpenClawHome_OSHomeNormalization pins OpenClaw's sentinel
+// normalisation on the env chain: the literals "undefined" / "null" /
+// blank-or-whitespace are all treated as unset, so a JS-flavoured
+// accidentally-stringified env value (e.g. `HOME=undefined` from a
+// shell wrapper) doesn't end up as a literal directory component when
+// the user authored `~/secret`. Combined with the user.Current()
+// fallback further down (see TestOpenClawHome_FallsBackToUserDatabase),
+// the contract is: a malformed HOME falls through to USERPROFILE first,
+// and only if that's also unset/sentinel do we go to the user database.
+func TestOpenClawHome_OSHomeNormalization(t *testing.T) {
+	isolateRuntimeWrites(t)
+	userProfileDir := t.TempDir()
+	homeWinsDir := t.TempDir()
+
+	tests := []struct {
+		name        string
+		home        string
+		userProfile string
+		want        string
+	}{
+		{"HOME=undefined falls through to USERPROFILE", "undefined", userProfileDir, userProfileDir},
+		{"HOME=null falls through to USERPROFILE", "null", userProfileDir, userProfileDir},
+		{"HOME=whitespace falls through to USERPROFILE", "   ", userProfileDir, userProfileDir},
+		{"HOME wins over USERPROFILE when both are valid", homeWinsDir, userProfileDir, homeWinsDir},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv("HOME", tc.home)
+			t.Setenv("USERPROFILE", tc.userProfile)
+			t.Setenv("OPENCLAW_HOME", "")
+			if got := openClawHome(); got != tc.want {
+				t.Errorf("openClawHome() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+// TestOpenClawHome_SentinelHOMEFallsToUserDatabaseNotCwd pins the
+// deliberate hybrid documented on osHome: with HOME a sentinel literal
+// and USERPROFILE unset, OpenClaw would fall back to process.cwd();
+// this implementation falls to the OS user database instead. The
+// account home is both safer (cwd-independent) and more useful (it is
+// where the user originally authored `~/...` against), so we prefer it
+// over either OpenClaw's cwd fallback or a strict reject.
+func TestOpenClawHome_SentinelHOMEFallsToUserDatabaseNotCwd(t *testing.T) {
+	isolateRuntimeWrites(t)
+	u, err := user.Current()
+	if err != nil || u.HomeDir == "" {
+		t.Skip("os/user.Current() unavailable on this runner")
+	}
+	t.Setenv("HOME", "undefined")
+	t.Setenv("USERPROFILE", "")
+	t.Setenv("OPENCLAW_HOME", "")
+	got := openClawHome()
+	if got != u.HomeDir {
+		t.Errorf("openClawHome() = %q, want %q (account home, not cwd)", got, u.HomeDir)
+	}
+}
+
+// TestExpandTildePath_BackslashPreservedOnPOSIX pins that `~\secret.json`
+// expands by replacing only the `~` byte, leaving the backslash literally
+// as part of the filename — matching OpenClaw's regex-replace semantics
+// (`/^~(?=$|[\\/])/`) rather than going through filepath.Join (which would
+// drop the backslash on POSIX). On Windows backslash is a real separator,
+// so the literal-byte invariant doesn't apply.
+func TestExpandTildePath_BackslashPreservedOnPOSIX(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("backslash is a path separator on Windows; invariant only applies on POSIX")
+	}
+	fakeHome := t.TempDir()
+	setFakeOSHome(t, fakeHome)
+	t.Setenv("OPENCLAW_HOME", "")
+
+	got := expandTildePath(`~\secret.json`)
+	want := fakeHome + `\secret.json`
+	if got != want {
+		t.Errorf("expandTildePath(%q) = %q, want %q (backslash should be preserved as filename byte)", `~\secret.json`, got, want)
+	}
+}

internal/binding/types.go

@@ -169,7 +169,7 @@ type ProviderConfig struct {
 const (
 	DefaultFileTimeoutMs      = 5000
 	DefaultFileMaxBytes       = 1024 * 1024 // 1 MiB
-	DefaultExecTimeoutMs      = 5000
+	DefaultExecTimeoutMs      = 10000
 	DefaultExecMaxOutputBytes = 1024 * 1024 // 1 MiB
 )
 

internal/cmdutil/factory.go

@@ -39,6 +39,7 @@ type Factory struct {
 	Keychain             keychain.KeychainAccess // secret storage (real keychain in prod, mock in tests)
 	IdentityAutoDetected bool                    // set by ResolveAs when identity was auto-detected
 	ResolvedIdentity     core.Identity           // identity resolved by the last ResolveAs call
+	CurrentCommand       *cobra.Command          // last matched command being executed; set during PersistentPreRun
 
 	Credential *credential.CredentialProvider
 

internal/cmdutil/identity_flag.go

@@ -14,8 +14,8 @@ import (
 // AddAPIIdentityFlag registers the standard --as flag shape used by api/service commands.
 func AddAPIIdentityFlag(ctx context.Context, cmd *cobra.Command, f *Factory, target *string) {
 	addIdentityFlag(ctx, cmd, f, target, identityFlagConfig{
-		defaultValue:     "auto",
-		usage:            "identity type: user | bot | auto (default)",
+		defaultValue:     "",
+		usage:            "identity type: user | bot",
 		completionValues: []string{"user", "bot"},
 	})
 }
@@ -26,7 +26,7 @@ func AddShortcutIdentityFlag(ctx context.Context, cmd *cobra.Command, f *Factory
 		authTypes = []string{"user"}
 	}
 	addIdentityFlag(ctx, cmd, f, nil, identityFlagConfig{
-		defaultValue:     authTypes[0],
+		defaultValue:     "",
 		usage:            "identity type: " + strings.Join(authTypes, " | "),
 		completionValues: authTypes,
 	})

internal/cmdutil/identity_flag_test.go

@@ -24,8 +24,8 @@ func TestAddAPIIdentityFlag_NonStrictMode(t *testing.T) {
 	if flag.Hidden {
 		t.Fatal("expected --as flag to be visible outside strict mode")
 	}
-	if got := flag.DefValue; got != "auto" {
-		t.Fatalf("default value = %q, want %q", got, "auto")
+	if got := flag.DefValue; got != "" {
+		t.Fatalf("default value = %q, want empty string", got)
 	}
 }
 
@@ -49,7 +49,7 @@ func TestAddAPIIdentityFlag_StrictModeHidesFlagAndLocksDefault(t *testing.T) {
 	}
 }
 
-func TestAddShortcutIdentityFlag_UsesAuthTypes(t *testing.T) {
+func TestAddShortcutIdentityFlag_NoDefault(t *testing.T) {
 	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "a", AppSecret: "s"})
 	cmd := &cobra.Command{Use: "test"}
 
@@ -62,7 +62,7 @@ func TestAddShortcutIdentityFlag_UsesAuthTypes(t *testing.T) {
 	if flag.Hidden {
 		t.Fatal("expected --as flag to be visible outside strict mode")
 	}
-	if got := flag.DefValue; got != "bot" {
-		t.Fatalf("default value = %q, want %q", got, "bot")
+	if got := flag.DefValue; got != "" {
+		t.Fatalf("default value = %q, want empty string", got)
 	}
 }

internal/core/types.go

@@ -27,6 +27,7 @@ type Endpoints struct {
 	Open     string // e.g. "https://open.feishu.cn"
 	Accounts string // e.g. "https://accounts.feishu.cn"
 	MCP      string // e.g. "https://mcp.feishu.cn"
+	AppLink  string // e.g. "https://applink.feishu.cn"
 }
 
 // ResolveEndpoints resolves endpoint URLs based on brand.
@@ -37,12 +38,14 @@ func ResolveEndpoints(brand LarkBrand) Endpoints {
 			Open:     "https://open.larksuite.com",
 			Accounts: "https://accounts.larksuite.com",
 			MCP:      "https://mcp.larksuite.com",
+			AppLink:  "https://applink.larksuite.com",
 		}
 	default:
 		return Endpoints{
 			Open:     "https://open.feishu.cn",
 			Accounts: "https://accounts.feishu.cn",
 			MCP:      "https://mcp.feishu.cn",
+			AppLink:  "https://applink.feishu.cn",
 		}
 	}
 }

internal/core/types_test.go

@@ -16,6 +16,9 @@ func TestResolveEndpoints_Feishu(t *testing.T) {
 	if ep.MCP != "https://mcp.feishu.cn" {
 		t.Errorf("MCP = %q, want feishu.cn", ep.MCP)
 	}
+	if ep.AppLink != "https://applink.feishu.cn" {
+		t.Errorf("AppLink = %q, want feishu.cn", ep.AppLink)
+	}
 }
 
 func TestResolveEndpoints_Lark(t *testing.T) {
@@ -29,6 +32,9 @@ func TestResolveEndpoints_Lark(t *testing.T) {
 	if ep.MCP != "https://mcp.larksuite.com" {
 		t.Errorf("MCP = %q, want larksuite.com", ep.MCP)
 	}
+	if ep.AppLink != "https://applink.larksuite.com" {
+		t.Errorf("AppLink = %q, want larksuite.com", ep.AppLink)
+	}
 }
 
 func TestResolveEndpoints_EmptyDefaultsToFeishu(t *testing.T) {

internal/core/workspace.go

@@ -27,6 +27,11 @@ const (
 	// WorkspaceHermes activates when any Hermes-specific env signal is
 	// present (see DetectWorkspaceFromEnv for the full list).
 	WorkspaceHermes Workspace = "hermes"
+
+	// WorkspaceLarkChannel activates when LARK_CHANNEL == "1" is set by
+	// lark-channel-bridge in subprocesses it spawns (e.g. claude). See
+	// DetectWorkspaceFromEnv for the detection rule.
+	WorkspaceLarkChannel Workspace = "lark-channel"
 )
 
 // currentWorkspace holds the workspace for the current process invocation.
@@ -90,7 +95,10 @@ func (w Workspace) IsLocal() bool {
 //     - HERMES_EXEC_ASK == "1": exported by the gateway (paired w/ QUIET)
 //     - HERMES_GATEWAY_TOKEN: injected into every gateway subprocess
 //     - HERMES_SESSION_KEY:   session identifier scoped to the current chat
-//  3. Otherwise → WorkspaceLocal
+//  3. LARK_CHANNEL == "1" → WorkspaceLarkChannel. Set by lark-channel-bridge
+//     when spawning subprocesses (e.g. claude). Single boolean marker —
+//     mirrors the OPENCLAW_CLI / HERMES_QUIET style.
+//  4. Otherwise → WorkspaceLocal
 func DetectWorkspaceFromEnv(getenv func(string) string) Workspace {
 	if getenv("OPENCLAW_CLI") == "1" ||
 		getenv("OPENCLAW_HOME") != "" ||
@@ -109,6 +117,9 @@ func DetectWorkspaceFromEnv(getenv func(string) string) Workspace {
 		getenv("HERMES_SESSION_KEY") != "" {
 		return WorkspaceHermes
 	}
+	if getenv("LARK_CHANNEL") == "1" {
+		return WorkspaceLarkChannel
+	}
 	return WorkspaceLocal
 }
 
@@ -139,6 +150,7 @@ func GetBaseConfigDir() string {
 //   - WorkspaceLocal → GetBaseConfigDir() (unchanged, backward-compatible)
 //   - WorkspaceOpenClaw → GetBaseConfigDir()/openclaw
 //   - WorkspaceHermes → GetBaseConfigDir()/hermes
+//   - WorkspaceLarkChannel → GetBaseConfigDir()/lark-channel
 func GetRuntimeDir() string {
 	base := GetBaseConfigDir()
 	ws := CurrentWorkspace()

internal/core/workspace_test.go

@@ -119,6 +119,31 @@ func TestDetectWorkspaceFromEnv(t *testing.T) {
 			env:    map[string]string{"LARKSUITE_CLI_APP_ID": "cli_local", "LARKSUITE_CLI_APP_SECRET": "local_secret"},
 			expect: WorkspaceLocal,
 		},
+		{
+			name:   "LARK_CHANNEL=1 → lark-channel",
+			env:    map[string]string{"LARK_CHANNEL": "1"},
+			expect: WorkspaceLarkChannel,
+		},
+		{
+			name:   "LARK_CHANNEL=true → local (strict ==1 check)",
+			env:    map[string]string{"LARK_CHANNEL": "true"},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "LARK_CHANNEL=0 → local",
+			env:    map[string]string{"LARK_CHANNEL": "0"},
+			expect: WorkspaceLocal,
+		},
+		{
+			name:   "OPENCLAW_CLI=1 + LARK_CHANNEL=1 → openclaw wins (priority)",
+			env:    map[string]string{"OPENCLAW_CLI": "1", "LARK_CHANNEL": "1"},
+			expect: WorkspaceOpenClaw,
+		},
+		{
+			name:   "HERMES_HOME + LARK_CHANNEL=1 → hermes wins (priority over lark-channel)",
+			env:    map[string]string{"HERMES_HOME": "/Users/me/.hermes", "LARK_CHANNEL": "1"},
+			expect: WorkspaceHermes,
+		},
 	}
 
 	for _, tt := range tests {
@@ -141,6 +166,7 @@ func TestWorkspaceDisplay(t *testing.T) {
 		{Workspace(""), "local"},
 		{WorkspaceOpenClaw, "openclaw"},
 		{WorkspaceHermes, "hermes"},
+		{WorkspaceLarkChannel, "lark-channel"},
 	}
 	for _, tt := range tests {
 		if got := tt.ws.Display(); got != tt.expect {
@@ -205,6 +231,13 @@ func TestGetRuntimeDir(t *testing.T) {
 	if got := GetRuntimeDir(); got != want {
 		t.Errorf("hermes: GetRuntimeDir() = %q, want %q", got, want)
 	}
+
+	// LarkChannel → base/lark-channel
+	SetCurrentWorkspace(WorkspaceLarkChannel)
+	want = filepath.Join(tmp, "lark-channel")
+	if got := GetRuntimeDir(); got != want {
+		t.Errorf("lark-channel: GetRuntimeDir() = %q, want %q", got, want)
+	}
 }
 
 func TestGetConfigPath(t *testing.T) {

internal/registry/remote.go

@@ -255,11 +255,18 @@ func doSyncFetch() {
 
 // --- background refresh ---
 
-var refreshOnce sync.Once
+var (
+	refreshOnce       sync.Once
+	bgRefreshInFlight sync.WaitGroup // tracks doBackgroundRefresh goroutines for test teardown (resetInit)
+)
 
 func triggerBackgroundRefresh() {
 	refreshOnce.Do(func() {
-		go doBackgroundRefresh()
+		bgRefreshInFlight.Add(1)
+		go func() {
+			defer bgRefreshInFlight.Done()
+			doBackgroundRefresh()
+		}()
 	})
 }
 

internal/registry/remote_test.go

@@ -17,8 +17,18 @@ import (
 	"github.com/larksuite/cli/internal/core"
 )
 
+// waitBackgroundRefresh blocks until any in-flight background refresh started by
+// triggerBackgroundRefresh has finished. Lives in this _test file so production
+// binaries cannot call it and accidentally block on test teardown state.
+func waitBackgroundRefresh() {
+	bgRefreshInFlight.Wait()
+}
+
 // resetInit resets the package-level state so each test starts fresh.
 func resetInit() {
+	// Must wait: a prior test's Init() may have started doBackgroundRefresh which
+	// reads globals this function mutates (see CI race: TestComputeMinimumScopeSet → Tenant).
+	waitBackgroundRefresh()
 	initOnce = sync.Once{}
 	mergedServices = make(map[string]map[string]interface{})
 	mergedProjectList = nil

internal/selfupdate/updater.go

@@ -17,6 +17,13 @@ import (
 	"github.com/larksuite/cli/internal/vfs"
 )
 
+// execLookPath is the LookPath implementation used by VerifyBinary.
+// It defaults to the standard library exec.LookPath but is swapped in tests
+// via lookPathMock to provide controlled binary resolution.
+//
+// Tests that mutate execLookPath must not call t.Parallel().
+var execLookPath = exec.LookPath
+
 // InstallMethod describes how the CLI was installed.
 type InstallMethod int
 
@@ -186,13 +193,13 @@ func (u *Updater) VerifyBinary(expectedVersion string) error {
 	if u.VerifyOverride != nil {
 		return u.VerifyOverride(expectedVersion)
 	}
-	// Prefer the current executable path (what the user actually launched).
-	// Use Executable() directly without EvalSymlinks — after npm install the
-	// symlink target may have changed, but the path itself is still valid for
-	// execution. Fall back to LookPath only if Executable() fails entirely.
-	exe, err := vfs.Executable()
+	// Prefer PATH resolution so npm global bin symlinks pick up the newly
+	// installed binary (#836). If `lark-cli` is not on PATH (e.g. the user
+	// invoked this process by absolute path), fall back to the running
+	// executable — same as the pre-#836 secondary resolution path.
+	exe, err := execLookPath("lark-cli")
 	if err != nil {
-		exe, err = exec.LookPath("lark-cli")
+		exe, err = vfs.Executable()
 		if err != nil {
 			return fmt.Errorf("cannot locate binary: %w", err)
 		}

internal/selfupdate/updater_test.go

@@ -4,6 +4,7 @@
 package selfupdate
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"runtime"
@@ -12,6 +13,7 @@ import (
 	"github.com/larksuite/cli/internal/vfs"
 )
 
+// executableTestFS mocks vfs for tests that still need vfs.Executable.
 type executableTestFS struct {
 	vfs.OsFs
 	exe string
@@ -19,6 +21,28 @@ type executableTestFS struct {
 
 func (f executableTestFS) Executable() (string, error) { return f.exe, nil }
 
+// lookPathMock patches execLookPath within VerifyBinary for controlled testing.
+// Do not use t.Parallel() in tests that install this mock — it mutates a package-level var.
+type lookPathMock struct {
+	oldLookPath func(string) (string, error)
+	result      string
+	resultErr   error
+}
+
+func (m *lookPathMock) install(bin string) {
+	m.oldLookPath = execLookPath
+	execLookPath = func(name string) (string, error) {
+		if name == bin {
+			return m.result, m.resultErr
+		}
+		return m.oldLookPath(name)
+	}
+}
+
+func (m *lookPathMock) restore() {
+	execLookPath = m.oldLookPath
+}
+
 func TestResolveExe(t *testing.T) {
 	u := New()
 	p, err := u.resolveExe()
@@ -44,46 +68,101 @@ func TestCleanupStaleFiles_NoPanic(t *testing.T) {
 	u.CleanupStaleFiles()
 }
 
-func TestVerifyBinaryChecksVersion(t *testing.T) {
+func TestVerifyBinaryLookPath(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	if runtime.GOOS == "windows" {
 		t.Skip("uses a POSIX shell script")
 	}
 
 	dir := t.TempDir()
-	exe := filepath.Join(dir, "lark-cli")
-	// Script prints version string matching real CLI format when --version is passed.
-	script := "#!/bin/sh\nif [ \"$1\" = \"--version\" ]; then echo \"lark-cli version 2.0.0\"; exit 0; fi\nexit 12\n"
-	if err := os.WriteFile(exe, []byte(script), 0755); err != nil {
+	bin := filepath.Join(dir, "lark-cli")
+	script := "#!/bin/sh\nif [ \"$1\" = \"--version\" ]; then echo \"lark-cli version 2.1.0\"; exit 0; fi\nexit 12\n"
+	if err := os.WriteFile(bin, []byte(script), 0755); err != nil {
 		t.Fatalf("write test binary: %v", err)
 	}
 
-	// Mock vfs.Executable to return our test script, matching VerifyBinary's
-	// primary lookup path. Also prepend to PATH for the LookPath fallback.
-	origFS := vfs.DefaultFS
-	vfs.DefaultFS = executableTestFS{OsFs: vfs.OsFs{}, exe: exe}
-	t.Cleanup(func() { vfs.DefaultFS = origFS })
+	mock := &lookPathMock{result: bin}
+	mock.install("lark-cli")
+	t.Cleanup(mock.restore)
 
-	origPath := os.Getenv("PATH")
-	t.Setenv("PATH", dir+string(os.PathListSeparator)+origPath)
-
-	// Matching version → success.
-	if err := New().VerifyBinary("2.0.0"); err != nil {
-		t.Fatalf("VerifyBinary(matching) error = %v, want nil", err)
+	if err := New().VerifyBinary("2.1.0"); err != nil {
+		t.Fatalf("VerifyBinary(2.1.0) error = %v, want nil", err)
 	}
 
-	// Mismatched version → error.
 	if err := New().VerifyBinary("3.0.0"); err == nil {
 		t.Fatal("VerifyBinary(mismatched) expected error, got nil")
 	}
 
-	// Substring of actual version must not match (e.g. "0.0" is in "2.0.0").
+	// Regression: version must match exactly (not substring / prefix).
 	if err := New().VerifyBinary("0.0"); err == nil {
-		t.Fatal("VerifyBinary(substring) expected error, got nil")
+		t.Fatal("VerifyBinary(substring-style mismatch) expected error, got nil")
 	}
-
-	// Version that is a prefix of actual must not match (e.g. "2.0.0" in "12.0.0").
-	// Binary reports "2.0.0", asking for "12.0.0" must fail.
-	if err := New().VerifyBinary("12.0.0"); err == nil {
-		t.Fatal("VerifyBinary(prefix-mismatch) expected error, got nil")
+	if err := New().VerifyBinary("12.1.0"); err == nil {
+		t.Fatal("VerifyBinary(prefix-style mismatch) expected error, got nil")
+	}
+}
+
+func TestVerifyBinaryLookPathNotFound(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	mock := &lookPathMock{result: "", resultErr: fmt.Errorf("not found")}
+	mock.install("lark-cli")
+	t.Cleanup(mock.restore)
+
+	oldFS := vfs.DefaultFS
+	t.Cleanup(func() { vfs.DefaultFS = oldFS })
+	// Without this, VerifyBinary would fall back to the real test binary, which
+	// is not a lark-cli --version implementation.
+	vfs.DefaultFS = executableTestFS{exe: filepath.Join(t.TempDir(), "missing-lark-cli")}
+
+	if err := New().VerifyBinary("2.0.0"); err == nil {
+		t.Fatal("VerifyBinary(not-found) expected error, got nil")
+	}
+}
+
+func TestVerifyBinaryFallbackExecutableWhenNotOnPath(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if runtime.GOOS == "windows" {
+		t.Skip("uses a POSIX shell script")
+	}
+
+	dir := t.TempDir()
+	bin := filepath.Join(dir, "lark-cli-abs")
+	script := "#!/bin/sh\nif [ \"$1\" = \"--version\" ]; then echo \"lark-cli version 2.1.0\"; exit 0; fi\nexit 12\n"
+	if err := os.WriteFile(bin, []byte(script), 0o755); err != nil {
+		t.Fatalf("write test binary: %v", err)
+	}
+
+	mock := &lookPathMock{result: "", resultErr: fmt.Errorf("not on PATH")}
+	mock.install("lark-cli")
+	t.Cleanup(mock.restore)
+
+	oldFS := vfs.DefaultFS
+	t.Cleanup(func() { vfs.DefaultFS = oldFS })
+	vfs.DefaultFS = executableTestFS{exe: bin}
+
+	if err := New().VerifyBinary("2.1.0"); err != nil {
+		t.Fatalf("VerifyBinary(fallback executable) error = %v, want nil", err)
+	}
+}
+
+func TestVerifyBinaryEmptyOutput(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if runtime.GOOS == "windows" {
+		t.Skip("uses a POSIX shell script")
+	}
+
+	dir := t.TempDir()
+	bin := filepath.Join(dir, "lark-cli")
+	script := "#!/bin/sh\necho\nexit 0\n"
+	if err := os.WriteFile(bin, []byte(script), 0755); err != nil {
+		t.Fatalf("write test binary: %v", err)
+	}
+
+	mock := &lookPathMock{result: bin}
+	mock.install("lark-cli")
+	t.Cleanup(mock.restore)
+
+	if err := New().VerifyBinary("2.0.0"); err == nil {
+		t.Fatal("VerifyBinary(empty output) expected error, got nil")
 	}
 }

internal/skillscheck/check.go

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+// Init runs the synchronous skills version check. Stores a StaleNotice
+// when the local stamp records a version that does not match
+// currentVersion. Safe to call from cmd/root.go before rootCmd.Execute();
+// zero network, zero subprocess — only a local stamp file read.
+//
+// Skip rules: see shouldSkip (CI envs, DEV builds, non-release semver,
+// LARKSUITE_CLI_NO_SKILLS_NOTIFIER opt-out).
+//
+// Failure modes (all → no notice, no nag):
+//   - shouldSkip rule met
+//   - ReadStamp returns an I/O error other than ENOENT
+//   - Stamp matches currentVersion (in-sync)
+//   - Stamp is missing (cold start) — only users who ran `lark-cli update`
+//     opt into drift tracking; npx-only installs are intentionally silent.
+func Init(currentVersion string) {
+	// Clear any stale notice from a prior call so early returns below
+	// (skip rules / read errors / cold start / in-sync) leave pending == nil
+	// instead of preserving a stale value from a previous Init invocation.
+	SetPending(nil)
+	if shouldSkip(currentVersion) {
+		return
+	}
+	stamp, err := ReadStamp()
+	if err != nil {
+		// Fail closed — don't nag for a transient FS problem.
+		return
+	}
+	if stamp == "" {
+		// Cold start: the stamp is written exclusively by `lark-cli update`
+		// (runSkillsAndStamp). Users who installed skills via
+		// `npx skills add larksuite/cli -g` have no stamp yet — they must
+		// not be nagged with "skills not installed", since the on-disk
+		// skills directory may already be fully populated.
+		return
+	}
+	if stamp == currentVersion {
+		return
+	}
+	SetPending(&StaleNotice{
+		Current: stamp, // guaranteed non-empty under the new contract
+		Target:  currentVersion,
+	})
+}

internal/skillscheck/check_test.go

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func resetPending(t *testing.T) {
+	t.Helper()
+	SetPending(nil)
+	t.Cleanup(func() { SetPending(nil) })
+}
+
+func TestInit_InSync_NoNotice(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	Init("1.0.21")
+	if got := GetPending(); got != nil {
+		t.Errorf("GetPending() = %+v, want nil (in-sync)", got)
+	}
+}
+
+func TestInit_ColdStart_NoNotice(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	Init("1.0.21")
+	if got := GetPending(); got != nil {
+		t.Errorf("GetPending() = %+v, want nil (cold start is silent)", got)
+	}
+}
+
+func TestInit_Drift_NoticeWithStampVersion(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+	Init("1.0.21")
+	got := GetPending()
+	if got == nil {
+		t.Fatal("GetPending() = nil, want non-nil for drift")
+	}
+	if got.Current != "1.0.20" || got.Target != "1.0.21" {
+		t.Errorf("notice = %+v, want {Current:\"1.0.20\", Target:\"1.0.21\"}", got)
+	}
+}
+
+func TestInit_Skipped_NoNotice(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	// Even with an empty config dir (no stamp), DEV version should skip
+	// the check entirely and never emit a notice.
+	Init("DEV")
+	if got := GetPending(); got != nil {
+		t.Errorf("GetPending() = %+v, want nil (skip rules met)", got)
+	}
+}
+
+func TestInit_ReadStampError_FailsClosed(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	resetPending(t)
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	// Make the stamp path a directory so vfs.ReadFile returns a
+	// non-ENOENT I/O error.
+	if err := os.MkdirAll(filepath.Join(dir, "skills.stamp"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	Init("1.0.21")
+	if got := GetPending(); got != nil {
+		t.Errorf("GetPending() = %+v, want nil (fail closed on I/O error)", got)
+	}
+}

internal/skillscheck/notice.go

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package skillscheck verifies that the locally installed lark-cli
+// skills are in sync with the running binary version, by comparing
+// the current binary version against a stamp file written when skills
+// are last synced (by `lark-cli update`). On mismatch it stores a
+// notice for injection into JSON envelopes via output.PendingNotice.
+package skillscheck
+
+import (
+	"fmt"
+	"sync/atomic"
+)
+
+// StaleNotice signals that the locally synced skills version does not
+// match the running binary. Current is the last successfully synced
+// version (always non-empty — Init no longer emits a notice on cold
+// start). Target is the running binary version. Mirrors
+// internal/update.UpdateInfo's pending-notice pattern.
+type StaleNotice struct {
+	Current string `json:"current"`
+	Target  string `json:"target"`
+}
+
+// Message returns a single-line, AI-agent-parseable description of the
+// drift plus the canonical fix command. Mirrors internal/update.UpdateInfo.Message
+// in style ("..., run: lark-cli update" suffix). Current is guaranteed
+// non-empty because Init only emits a StaleNotice for the drift case
+// (stamp present and != binary version).
+func (s *StaleNotice) Message() string {
+	return fmt.Sprintf(
+		"lark-cli skills %s out of sync with binary %s, run: lark-cli update",
+		s.Current, s.Target,
+	)
+}
+
+// pending stores the latest stale notice for the current process.
+var pending atomic.Pointer[StaleNotice]
+
+// SetPending stores the stale notice for consumption by output decorators.
+// Pass nil to clear.
+func SetPending(n *StaleNotice) { pending.Store(n) }
+
+// GetPending returns the pending stale notice, or nil.
+func GetPending() *StaleNotice { return pending.Load() }

internal/skillscheck/notice_test.go

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"sync"
+	"testing"
+)
+
+func TestStaleNotice_Message(t *testing.T) {
+	tests := []struct {
+		name string
+		n    StaleNotice
+		want string
+	}{
+		{
+			"drift",
+			StaleNotice{Current: "1.0.20", Target: "1.0.21"},
+			"lark-cli skills 1.0.20 out of sync with binary 1.0.21, run: lark-cli update",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.n.Message(); got != tt.want {
+				t.Errorf("Message() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSetGetPending(t *testing.T) {
+	SetPending(nil)
+	t.Cleanup(func() { SetPending(nil) })
+
+	if got := GetPending(); got != nil {
+		t.Fatalf("initial GetPending() = %+v, want nil", got)
+	}
+
+	want := &StaleNotice{Current: "1.0.20", Target: "1.0.21"}
+	SetPending(want)
+	got := GetPending()
+	if got == nil || got.Current != "1.0.20" || got.Target != "1.0.21" {
+		t.Errorf("GetPending() = %+v, want %+v", got, want)
+	}
+}
+
+func TestSetGetPending_Concurrent(t *testing.T) {
+	SetPending(nil)
+	t.Cleanup(func() { SetPending(nil) })
+
+	var wg sync.WaitGroup
+	for i := 0; i < 100; i++ {
+		wg.Add(2)
+		go func() {
+			defer wg.Done()
+			SetPending(&StaleNotice{Current: "a", Target: "b"})
+		}()
+		go func() {
+			defer wg.Done()
+			_ = GetPending()
+		}()
+	}
+	wg.Wait()
+	// Just verifying no race; -race flag enforces.
+}

internal/skillscheck/skip.go

@@ -0,0 +1,27 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"os"
+
+	"github.com/larksuite/cli/internal/update"
+)
+
+// shouldSkip returns true when the skills check should be silently
+// suppressed. Mirrors internal/update.shouldSkip semantics but uses
+// a dedicated opt-out env var so users can disable the skills nag
+// without also disabling the binary update nag.
+func shouldSkip(version string) bool {
+	if os.Getenv("LARKSUITE_CLI_NO_SKILLS_NOTIFIER") != "" {
+		return true
+	}
+	if update.IsCIEnv() {
+		return true
+	}
+	if version == "DEV" || version == "dev" || version == "" {
+		return true
+	}
+	return !update.IsRelease(version)
+}

internal/skillscheck/skip_test.go

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"os"
+	"testing"
+)
+
+// clearSkillsSkipEnv unsets the env vars shouldSkip checks so the
+// host environment cannot pollute test results.
+func clearSkillsSkipEnv(t *testing.T) {
+	t.Helper()
+	for _, key := range []string{"LARKSUITE_CLI_NO_SKILLS_NOTIFIER", "CI", "BUILD_NUMBER", "RUN_ID"} {
+		t.Setenv(key, "")
+		os.Unsetenv(key)
+	}
+}
+
+func TestShouldSkip(t *testing.T) {
+	tests := []struct {
+		name    string
+		setup   func(t *testing.T)
+		version string
+		want    bool
+	}{
+		{"release_no_skip", clearSkillsSkipEnv, "1.0.21", false},
+		{"dev_uppercase", clearSkillsSkipEnv, "DEV", true},
+		{"dev_lowercase", clearSkillsSkipEnv, "dev", true},
+		{"empty_version", clearSkillsSkipEnv, "", true},
+		{"git_describe", clearSkillsSkipEnv, "1.0.0-12-g9b933f1-dirty", true},
+		{"opt_out", func(t *testing.T) {
+			clearSkillsSkipEnv(t)
+			t.Setenv("LARKSUITE_CLI_NO_SKILLS_NOTIFIER", "1")
+		}, "1.0.21", true},
+		{"ci_env", func(t *testing.T) {
+			clearSkillsSkipEnv(t)
+			t.Setenv("CI", "true")
+		}, "1.0.21", true},
+		{"build_number_env", func(t *testing.T) {
+			clearSkillsSkipEnv(t)
+			t.Setenv("BUILD_NUMBER", "42")
+		}, "1.0.21", true},
+		{"run_id_env", func(t *testing.T) {
+			clearSkillsSkipEnv(t)
+			t.Setenv("RUN_ID", "abc")
+		}, "1.0.21", true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tt.setup(t)
+			if got := shouldSkip(tt.version); got != tt.want {
+				t.Errorf("shouldSkip(%q) = %v, want %v", tt.version, got, tt.want)
+			}
+		})
+	}
+}
+
+// Independent opt-out: LARKSUITE_CLI_NO_SKILLS_NOTIFIER must NOT be
+// affected by LARKSUITE_CLI_NO_UPDATE_NOTIFIER (different env vars).
+func TestShouldSkip_OptOutIsIndependent(t *testing.T) {
+	clearSkillsSkipEnv(t)
+	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1") // update opt-out, not us
+	if shouldSkip("1.0.21") {
+		t.Error("shouldSkip(release) = true with only LARKSUITE_CLI_NO_UPDATE_NOTIFIER set, want false")
+	}
+}

internal/skillscheck/stamp.go

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"errors"
+	"io/fs"
+	"path/filepath"
+	"strings"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+const stampFile = "skills.stamp"
+
+// stampPath returns ~/.lark-cli/skills.stamp.
+// Uses the BASE config dir (not workspace-aware) because skills install
+// globally via `npx -g`; per-workspace tracking would produce false
+// drift signals when switching workspaces.
+func stampPath() string {
+	return filepath.Join(core.GetBaseConfigDir(), stampFile)
+}
+
+// ReadStamp returns the version recorded in the stamp file. Returns
+// ("", nil) when the file does not exist (interpreted as "never synced").
+// Other I/O errors are returned as-is so callers can fail closed.
+func ReadStamp() (string, error) {
+	data, err := vfs.ReadFile(stampPath())
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			return "", nil
+		}
+		return "", err
+	}
+	return strings.TrimSpace(string(data)), nil
+}
+
+// WriteStamp records `version` as the last successfully synced skills
+// version. Atomic via tmp + rename (validate.AtomicWrite). Creates
+// the base config directory if it does not exist.
+func WriteStamp(version string) error {
+	if err := vfs.MkdirAll(core.GetBaseConfigDir(), 0o700); err != nil {
+		return err
+	}
+	return validate.AtomicWrite(stampPath(), []byte(version), 0o644)
+}

internal/skillscheck/stamp_test.go

@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillscheck
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestReadStamp_Missing(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	got, err := ReadStamp()
+	if err != nil {
+		t.Fatalf("ReadStamp() err = %v, want nil for ENOENT", err)
+	}
+	if got != "" {
+		t.Errorf("ReadStamp() = %q, want \"\" for missing file", got)
+	}
+}
+
+func TestReadStamp_Normal(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := os.WriteFile(filepath.Join(dir, "skills.stamp"), []byte("1.0.21"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := ReadStamp()
+	if err != nil || got != "1.0.21" {
+		t.Errorf("ReadStamp() = (%q, %v), want (\"1.0.21\", nil)", got, err)
+	}
+}
+
+func TestReadStamp_TrailingNewlineTolerated(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := os.WriteFile(filepath.Join(dir, "skills.stamp"), []byte("1.0.21\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := ReadStamp()
+	if got != "1.0.21" {
+		t.Errorf("ReadStamp() = %q, want \"1.0.21\" (newline trimmed)", got)
+	}
+}
+
+func TestReadStamp_EmptyFile(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := os.WriteFile(filepath.Join(dir, "skills.stamp"), []byte(""), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := ReadStamp()
+	if err != nil || got != "" {
+		t.Errorf("ReadStamp() = (%q, %v), want (\"\", nil)", got, err)
+	}
+}
+
+func TestWriteStamp_CreatesDir(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "nested")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.21"); err != nil {
+		t.Fatalf("WriteStamp() = %v, want nil", err)
+	}
+	got, _ := os.ReadFile(filepath.Join(dir, "skills.stamp"))
+	if string(got) != "1.0.21" {
+		t.Errorf("file content = %q, want \"1.0.21\"", string(got))
+	}
+}
+
+func TestWriteStamp_OverwritesExisting(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.20"); err != nil {
+		t.Fatal(err)
+	}
+	if err := WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := ReadStamp()
+	if got != "1.0.21" {
+		t.Errorf("ReadStamp() after overwrite = %q, want \"1.0.21\"", got)
+	}
+}
+
+func TestWriteStamp_NoTrailingNewline(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	if err := WriteStamp("1.0.21"); err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := os.ReadFile(filepath.Join(dir, "skills.stamp"))
+	if string(raw) != "1.0.21" {
+		t.Errorf("raw file = %q, want exactly \"1.0.21\" (no newline)", string(raw))
+	}
+}
+
+// TestWriteStamp_MkdirAllFailure verifies WriteStamp returns the mkdir error
+// when the base config dir cannot be created (parent path is a regular file).
+func TestWriteStamp_MkdirAllFailure(t *testing.T) {
+	tmp := t.TempDir()
+	blocker := filepath.Join(tmp, "blocker")
+	// Create a regular file where MkdirAll wants to create a directory.
+	if err := os.WriteFile(blocker, []byte("not-a-dir"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Point the config dir at a path UNDER the regular file — MkdirAll must fail.
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", filepath.Join(blocker, "child"))
+
+	if err := WriteStamp("1.0.21"); err == nil {
+		t.Fatal("WriteStamp() = nil, want non-nil error from MkdirAll failure")
+	}
+}

internal/update/update.go

@@ -37,9 +37,12 @@ type UpdateInfo struct {
 	Latest  string `json:"latest"`
 }
 
-// Message returns a concise update notification.
+// Message returns a concise update notification including the canonical
+// fix command. Aligned with skillscheck.StaleNotice.Message style so
+// AI agents can parse a unified "run: lark-cli update" hint across
+// both notice types.
 func (u *UpdateInfo) Message() string {
-	return fmt.Sprintf("lark-cli %s available, current %s", u.Latest, u.Current)
+	return fmt.Sprintf("lark-cli %s available, current %s, run: lark-cli update", u.Latest, u.Current)
 }
 
 // pending stores the latest update info for the current process.
@@ -111,10 +114,8 @@ func shouldSkip(version string) bool {
 		return true
 	}
 	// Suppress in CI environments.
-	for _, key := range []string{"CI", "BUILD_NUMBER", "RUN_ID"} {
-		if os.Getenv(key) != "" {
-			return true
-		}
+	if IsCIEnv() {
+		return true
 	}
 	// No version info at all — can't compare.
 	if version == "DEV" || version == "dev" || version == "" {
@@ -141,6 +142,24 @@ func isRelease(version string) bool {
 	return !gitDescribePattern.MatchString(v)
 }
 
+// IsRelease reports whether version looks like a clean published release
+// (semver "1.0.0", or npm prerelease "1.0.0-beta.1") and not a git-describe
+// dev build like "1.0.0-12-g9b933f1-dirty". Exported so internal/skillscheck
+// can apply the same release-only gating without duplicating the regex.
+func IsRelease(version string) bool { return isRelease(version) }
+
+// IsCIEnv returns true when any of the standard CI environment variables
+// is set. Exported for internal/skillscheck so its skip rules track the
+// same CI-suppression behavior as the update notifier.
+func IsCIEnv() bool {
+	for _, key := range []string{"CI", "BUILD_NUMBER", "RUN_ID"} {
+		if os.Getenv(key) != "" {
+			return true
+		}
+	}
+	return false
+}
+
 // --- state file I/O ---
 
 func statePath() string {

internal/update/update_test.go

@@ -10,7 +10,6 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
-	"strings"
 	"testing"
 	"time"
 )
@@ -143,28 +142,27 @@ func TestShouldSkip(t *testing.T) {
 
 func TestIsRelease(t *testing.T) {
 	tests := []struct {
-		version string
-		want    bool
+		name string
+		ver  string
+		want bool
 	}{
-		{"1.0.0", true},
-		{"v1.0.0", true},
-		{"0.1.0", true},
-		{"1.0.0-beta.1", true},
-		{"1.0.0-rc.1", true},
-		{"2.0.0-alpha.0", true},
-		{"v1.0.0-12-g9b933f1", false},       // git describe
-		{"v1.0.0-12-g9b933f1-dirty", false}, // git describe dirty
-		{"v2.1.0-3-gabcdef0", false},        // git describe short
-		{"9b933f1", false},                  // bare commit hash
-		{"DEV", false},                      // dev marker
-		{"", false},                         // empty
-		{"1.0", false},                      // incomplete semver
+		{"clean_semver", "1.0.0", true},
+		{"v_prefix", "v1.0.0", true},
+		{"prerelease", "1.0.0-beta.1", true},
+		{"rc", "1.0.0-rc.1", true},
+		{"alpha_prerelease", "2.0.0-alpha.0", true},
+		{"git_describe_dirty", "1.0.0-12-g9b933f1-dirty", false},
+		{"git_describe_clean", "1.0.0-12-g9b933f1", false},
+		{"bare_commit_hash", "9b933f1", false},
+		{"dev_marker", "DEV", false},
+		{"incomplete_semver", "1.0", false},
+		{"empty", "", false},
+		{"invalid", "not-a-version", false},
 	}
 	for _, tt := range tests {
-		t.Run(tt.version, func(t *testing.T) {
-			got := isRelease(tt.version)
-			if got != tt.want {
-				t.Errorf("isRelease(%q) = %v, want %v", tt.version, got, tt.want)
+		t.Run(tt.name, func(t *testing.T) {
+			if got := IsRelease(tt.ver); got != tt.want {
+				t.Errorf("IsRelease(%q) = %v, want %v", tt.ver, got, tt.want)
 			}
 		})
 	}
@@ -172,13 +170,10 @@ func TestIsRelease(t *testing.T) {
 
 func TestUpdateInfoMethods(t *testing.T) {
 	info := &UpdateInfo{Current: "1.0.0", Latest: "2.0.0"}
-
-	msg := info.Message()
-	if !strings.Contains(msg, "2.0.0") {
-		t.Errorf("Message() missing latest version: %s", msg)
-	}
-	if !strings.Contains(msg, "1.0.0") {
-		t.Errorf("Message() missing current version: %s", msg)
+	got := info.Message()
+	want := "lark-cli 2.0.0 available, current 1.0.0, run: lark-cli update"
+	if got != want {
+		t.Errorf("Message() = %q, want %q", got, want)
 	}
 }
 
@@ -264,3 +259,19 @@ func TestPendingAtomicAccess(t *testing.T) {
 	// Clean up for other tests
 	SetPending(nil)
 }
+
+func TestIsCIEnv(t *testing.T) {
+	clearSkipEnv(t)
+	if IsCIEnv() {
+		t.Fatal("IsCIEnv() = true after clearSkipEnv, want false")
+	}
+	for _, key := range []string{"CI", "BUILD_NUMBER", "RUN_ID"} {
+		t.Run(key, func(t *testing.T) {
+			clearSkipEnv(t)
+			t.Setenv(key, "1")
+			if !IsCIEnv() {
+				t.Errorf("IsCIEnv() = false with %s=1, want true", key)
+			}
+		})
+	}
+}

internal/util/strings.go

@@ -5,6 +5,9 @@ package util
 
 // TruncateStr truncates s to at most n runes, safe for multi-byte (e.g. CJK) characters.
 func TruncateStr(s string, n int) string {
+	if n <= 0 {
+		return ""
+	}
 	r := []rune(s)
 	if len(r) <= n {
 		return s
@@ -14,6 +17,9 @@ func TruncateStr(s string, n int) string {
 
 // TruncateStrWithEllipsis truncates s to at most n runes (including "..." suffix).
 func TruncateStrWithEllipsis(s string, n int) string {
+	if n <= 0 {
+		return ""
+	}
 	r := []rune(s)
 	if len(r) <= n {
 		return s

internal/util/strings_test.go

@@ -17,6 +17,7 @@ func TestTruncateStr(t *testing.T) {
 		{"truncate", "hello world", 5, "hello"},
 		{"empty", "", 5, ""},
 		{"zero limit", "hello", 0, ""},
+		{"negative limit", "hello", -1, ""},
 		{"CJK characters", "你好世界测试", 4, "你好世界"},
 	}
 	for _, tt := range tests {
@@ -41,6 +42,8 @@ func TestTruncateStrWithEllipsis(t *testing.T) {
 		{"limit less than 3", "hello", 2, "he"},
 		{"limit equals 3", "hello world", 3, "..."},
 		{"empty", "", 5, ""},
+		{"zero limit", "hello", 0, ""},
+		{"negative limit", "hello", -1, ""},
 		{"CJK with ellipsis", "你好世界测试", 5, "你好..."},
 	}
 	for _, tt := range tests {

package.json

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

scripts/check-doc-tokens.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+#
+# check-doc-tokens.sh
+#
+# Scans skill reference docs for token-like values that look realistic but
+# are not using the required placeholder format (*_EXAMPLE_TOKEN or similar).
+#
+# Real token patterns (Lark API) often look like:
+#   wikcnXXXXXXXXX  doccnXXXXXXX  shtcnXXX  fldcnXXX  ou_XXXX  cli_XXXX
+#
+# Docs MUST use clearly fake placeholders, e.g.:
+#   wikcn_EXAMPLE_TOKEN   doccn_EXAMPLE_TOKEN   <space_id>   your_token_here
+#
+# If this check fails, replace the realistic-looking value with a placeholder
+# like `wikcn_EXAMPLE_TOKEN` so gitleaks CI won't flag it as a real secret.
+
+set -euo pipefail
+
+SKILLS_DIR="${1:-skills}"
+ERRORS=0
+
+# Patterns that indicate a realistic-looking Lark token value.
+# Three forms are detected:
+#   1. JSON-style quoted strings: "field": "token_value"
+#   2. Markdown backtick spans:   `token_value`
+#   3. Bare tokens:               --flag wikcnABC123 (e.g. inside fenced code blocks)
+#
+# Token prefixes used by Lark Open Platform:
+#   wikcn  doccn  docx  shtcn  bascn  fldcn  vewcn  tbln  ou_  cli_  obcn  flec
+#
+# Excluded (clearly fake, matched by PLACEHOLDER_RE below):
+#   - Values containing EXAMPLE / _TOKEN / XXXX / your_ / _here
+#   - Angle-bracket placeholders <your_token>
+# Require at least one digit in the suffix — real API tokens are always alphanumeric
+# with digits. Pure-letter suffixes (e.g. ou_manager, ou_director) are clearly fake names.
+PREFIXES='(wikcn|doccn|docx[a-z]|shtcn|bascn|fldcn|vewcn|tbln|obcn|flec|ou_|cli_)'
+TOKEN_BODY="${PREFIXES}"'[A-Za-z0-9]*[0-9][A-Za-z0-9]{3,}'
+REALISTIC_TOKEN_RE="\"${TOKEN_BODY}\"|\`${TOKEN_BODY}\`|\\b${TOKEN_BODY}\\b"
+PLACEHOLDER_RE='(EXAMPLE|_TOKEN|XXXX|xxxx|<|>|your_|_here)'
+
+while IFS= read -r -d '' file; do
+  # grep returns exit 1 when no match — use || true to avoid set -e killing us
+  # Then filter out values that are clearly placeholders (EXAMPLE, XXXX, etc.)
+  matches=$(grep -nEo "$REALISTIC_TOKEN_RE" "$file" 2>/dev/null | grep -vE "$PLACEHOLDER_RE" || true)
+  if [[ -n "$matches" ]]; then
+    echo ""
+    echo "❌  $file"
+    echo "    Contains realistic-looking token values that may trigger gitleaks:"
+    while IFS= read -r line; do
+      echo "      $line"
+    done <<< "$matches"
+    echo "    → Replace with a placeholder, e.g.: wikcn_EXAMPLE_TOKEN, doccn_EXAMPLE_TOKEN"
+    ERRORS=$((ERRORS + 1))
+  fi
+done < <(find "$SKILLS_DIR" -path "*/references/*.md" -print0)
+
+if [[ $ERRORS -gt 0 ]]; then
+  echo ""
+  echo "❌  check-doc-tokens: $ERRORS file(s) contain realistic token values in reference docs."
+  echo "    Use _EXAMPLE_TOKEN placeholders to avoid false positives in gitleaks CI."
+  exit 1
+else
+  echo "✅  check-doc-tokens: all reference docs use safe placeholder tokens."
+fi

scripts/install-wizard.js

@@ -44,6 +44,7 @@ const messages = {
     step4Fail:      "授权失败。运行以下命令重试: lark-cli auth login",
     done:           "安装完成！\n可以和你的 AI 工具（如 Claude Code、Trae等）说：\"飞书/Lark CLI 能帮我做什么？结合我的情况推荐一下从哪里开始\"",
     cancelled:      "安装已取消",
+    nonTtyHint:     "要完成配置，请在终端中运行：\n  lark-cli config init --new\n  lark-cli auth login",
   },
   en: {
     setup:          "Setting up Feishu/Lark CLI...",
@@ -72,6 +73,7 @@ const messages = {
     step4Fail:      "Failed to authorize. Run lark-cli auth login to retry",
     done:           "You are all set!\nNow try asking your AI tool (Claude Code, Trae, etc.): \"What can Feishu/Lark CLI help me with, and where should I start?\"",
     cancelled:      "Installation cancelled",
+    nonTtyHint:     "To complete setup, run interactively:\n  lark-cli config init --new\n  lark-cli auth login",
   },
 };
 
@@ -353,17 +355,23 @@ async function stepAuthLogin(msg) {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  const lang = await stepSelectLang();
+  const isInteractive = !!process.stdin.isTTY;
+  const lang = isInteractive ? await stepSelectLang() : (parseLangArg() || "en");
   const msg = messages[lang];
 
-  p.intro(msg.setup);
-
-  await stepInstallGlobally(msg);
-  await stepInstallSkills(msg);
-  await stepConfigInit(msg, lang);
-  await stepAuthLogin(msg);
-
-  p.outro(msg.done);
+  if (isInteractive) {
+    p.intro(msg.setup);
+    await stepInstallGlobally(msg);
+    await stepInstallSkills(msg);
+    await stepConfigInit(msg, lang);
+    await stepAuthLogin(msg);
+    p.outro(msg.done);
+  } else {
+    console.log(msg.setup);
+    await stepInstallGlobally(msg);
+    await stepInstallSkills(msg);
+    console.log(msg.nonTtyHint);
+  }
 }
 
 main().catch((err) => {

scripts/install.js

@@ -146,12 +146,17 @@ function extractZipWindows(archivePath, destDir) {
         "$ErrorActionPreference='Stop';" +
         "Expand-Archive -LiteralPath $env:LARK_CLI_ARCHIVE -DestinationPath $env:LARK_CLI_DEST -Force";
       execFileSync("powershell.exe", [...psOpts, cmdlet], { stdio: psStdio, env: psEnv });
-    } catch (fallbackErr) {
-      throw new Error(
-        `Failed to extract ${archivePath}. ` +
-        `.NET ZipFile attempt: ${primaryErr.message}. ` +
-        `Expand-Archive fallback: ${fallbackErr.message}`
-      );
+    } catch (secondErr) {
+      try {
+        execFileSync("tar", ["-xf", archivePath, "-C", destDir], { stdio: psStdio });
+      } catch (fallbackErr) {
+        throw new Error(
+          `Failed to extract ${archivePath}. ` +
+          `.NET ZipFile attempt: ${primaryErr.message}. ` +
+          `Expand-Archive fallback: ${secondErr.message}. ` +
+          `tar fallback: ${fallbackErr.message}`
+        );
+      }
     }
   }
 }

shortcuts/base/base_errors.go

@@ -4,7 +4,6 @@
 package base
 
 import (
-	"fmt"
 	"strings"
 
 	"github.com/larksuite/cli/internal/output"
@@ -20,6 +19,9 @@ func handleBaseAPIResult(result interface{}, err error, action string) (map[stri
 	return dataMap, nil
 }
 
+// handleBaseAPIResultAny normalizes the Base v3 {code,msg,data} envelope used
+// by shortcut APIs. Success returns data as-is; API failures become the CLI's
+// structured ErrAPI, with server-provided message/hint promoted to the top level.
 func handleBaseAPIResultAny(result interface{}, err error, action string) (interface{}, error) {
 	if err != nil {
 		return nil, output.Errorf(output.ExitAPI, "api_error", "%s: %s", action, err)
@@ -37,17 +39,34 @@ func handleBaseAPIResultAny(result interface{}, err error, action string) (inter
 		msg, _ = resultMap["msg"].(string)
 	}
 
-	fullMsg := fmt.Sprintf("%s: [%d] %s", action, larkCode, msg)
 	detail := extractErrorDetail(resultMap)
-	apiErr := output.ErrAPI(larkCode, fullMsg, detail)
-	if apiErr.Detail != nil && apiErr.Detail.Hint == "" {
-		if hint := extractErrorHint(resultMap); hint != "" {
-			apiErr.Detail.Hint = hint
-		}
+	apiErr := output.ErrAPI(larkCode, msg, detail)
+	hint := extractErrorHint(resultMap)
+	if apiErr.Detail != nil && apiErr.Detail.Hint == "" && hint != "" {
+		apiErr.Detail.Hint = hint
+	}
+	if apiErr.Detail != nil {
+		apiErr.Detail.Detail = cleanEmptyBaseErrorDetail(detail)
 	}
 	return nil, apiErr
 }
 
+func cleanEmptyBaseErrorDetail(detail interface{}) interface{} {
+	detailMap, ok := detail.(map[string]interface{})
+	if !ok {
+		return nil
+	}
+	for key, value := range detailMap {
+		if value == nil {
+			delete(detailMap, key)
+		}
+	}
+	if len(detailMap) == 0 {
+		return nil
+	}
+	return detailMap
+}
+
 func extractErrorDetail(resultMap map[string]interface{}) interface{} {
 	if detail, ok := nonNilMapValue(resultMap, "error"); ok {
 		return detail
@@ -77,13 +96,13 @@ func nonNilMapValue(src map[string]interface{}, key string) (interface{}, bool)
 
 func extractErrorHint(resultMap map[string]interface{}) string {
 	if detail, ok := resultMap["error"].(map[string]interface{}); ok {
-		if hint, _ := detail["hint"].(string); strings.TrimSpace(hint) != "" {
+		if hint := consumeStringField(detail, "hint"); hint != "" {
 			return hint
 		}
 	}
 	data, _ := resultMap["data"].(map[string]interface{})
 	if detail, ok := data["error"].(map[string]interface{}); ok {
-		if hint, _ := detail["hint"].(string); strings.TrimSpace(hint) != "" {
+		if hint := consumeStringField(detail, "hint"); hint != "" {
 			return hint
 		}
 	}
@@ -93,9 +112,17 @@ func extractErrorHint(resultMap map[string]interface{}) string {
 func extractDataErrorMessage(resultMap map[string]interface{}) string {
 	data, _ := resultMap["data"].(map[string]interface{})
 	if detail, ok := data["error"].(map[string]interface{}); ok {
-		if message, _ := detail["message"].(string); strings.TrimSpace(message) != "" {
+		if message := consumeStringField(detail, "message"); message != "" {
 			return message
 		}
 	}
 	return ""
 }
+
+func consumeStringField(src map[string]interface{}, key string) string {
+	value, _ := src[key].(string)
+	if _, exists := src[key]; exists {
+		delete(src, key)
+	}
+	return strings.TrimSpace(value)
+}

shortcuts/base/base_errors_test.go

@@ -4,8 +4,11 @@
 package base
 
 import (
+	"errors"
 	"strings"
 	"testing"
+
+	"github.com/larksuite/cli/internal/output"
 )
 
 func TestErrorDetailHelpers(t *testing.T) {
@@ -47,14 +50,133 @@ func TestHandleBaseAPIResultErrorPaths(t *testing.T) {
 			"error": map[string]interface{}{"message": "invalid filter", "hint": "check field name"},
 		},
 	}
-	if _, err := handleBaseAPIResultAny(result, nil, "set filter"); err == nil || !strings.Contains(err.Error(), "invalid filter") || !strings.Contains(err.Error(), "190001") {
+	if _, err := handleBaseAPIResultAny(result, nil, "set filter"); err == nil || !strings.Contains(err.Error(), "invalid filter") {
 		t.Fatalf("err=%v", err)
+	} else {
+		var exitErr *output.ExitError
+		if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Code != 190001 {
+			t.Fatalf("expected structured code 190001, got %v", err)
+		}
 	}
 	if _, err := handleBaseAPIResult(result, nil, "set filter"); err == nil {
 		t.Fatalf("expected error")
 	}
 }
 
+func TestHandleBaseAPIResultCleansBaseErrorDetail(t *testing.T) {
+	result := map[string]interface{}{
+		"code": 800010407,
+		"msg":  "cell value invalid",
+		"data": map[string]interface{}{
+			"error": map[string]interface{}{
+				"docs_url":       nil,
+				"hint":           "Provide a number value.",
+				"level":          "error",
+				"logid":          "20260508160000000000000000000000",
+				"message":        "The cell value does not match the expected input shape.",
+				"path":           "Amount",
+				"retry_after_ms": nil,
+				"retryable":      false,
+				"extra_context":  "future detail field",
+				"table":          map[string]interface{}{"id": "tbl_1", "name": "Orders"},
+				"type":           "invalid_request",
+				"upstream_code":  nil,
+				"value":          "abc",
+			},
+		},
+	}
+
+	_, err := handleBaseAPIResultAny(result, nil, "API call failed")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected structured exit error, got %v", err)
+	}
+
+	errDetail := exitErr.Detail
+	if errDetail.Code != 800010407 {
+		t.Fatalf("code=%d", errDetail.Code)
+	}
+	if errDetail.Hint != "Provide a number value." {
+		t.Fatalf("hint=%q", errDetail.Hint)
+	}
+	detail, _ := errDetail.Detail.(map[string]interface{})
+	if detail == nil {
+		t.Fatalf("expected cleaned detail, got %#v", errDetail.Detail)
+	}
+	if _, exists := detail["message"]; exists {
+		t.Fatalf("detail should not repeat message: %#v", detail)
+	}
+	if _, exists := detail["hint"]; exists {
+		t.Fatalf("detail should not repeat hint: %#v", detail)
+	}
+	if _, exists := detail["docs_url"]; exists {
+		t.Fatalf("detail should omit nil docs_url: %#v", detail)
+	}
+	if detail["level"] != "error" {
+		t.Fatalf("detail should preserve non-duplicate fields: %#v", detail)
+	}
+	if detail["extra_context"] != "future detail field" {
+		t.Fatalf("detail should pass through unknown non-nil fields: %#v", detail)
+	}
+	if detail["path"] != "Amount" || detail["value"] != "abc" {
+		t.Fatalf("cleaned detail mismatch: %#v", detail)
+	}
+	if detail["logid"] != "20260508160000000000000000000000" {
+		t.Fatalf("logid=%q", detail["logid"])
+	}
+	if retryable, ok := detail["retryable"].(bool); !ok || retryable {
+		t.Fatalf("retryable=%v", detail["retryable"])
+	}
+	table, _ := detail["table"].(map[string]interface{})
+	if table["id"] != "tbl_1" || table["name"] != "Orders" {
+		t.Fatalf("table=%#v", detail["table"])
+	}
+}
+
+func TestHandleBaseAPIResultAlwaysRemovesMessageAndHintFromDetail(t *testing.T) {
+	result := map[string]interface{}{
+		"code": output.LarkErrTokenNoPermission,
+		"msg":  "permission denied",
+		"data": map[string]interface{}{
+			"error": map[string]interface{}{
+				"hint":    "Grant base:record:read to the app.",
+				"message": "Missing required scope base:record:read.",
+			},
+		},
+	}
+
+	_, err := handleBaseAPIResultAny(result, nil, "API call failed")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected structured exit error, got %v", err)
+	}
+	if exitErr.Detail.Message != "Permission denied [99991676]" {
+		t.Fatalf("message=%q", exitErr.Detail.Message)
+	}
+	if exitErr.Detail.Detail != nil {
+		t.Fatalf("detail should be empty after removing message and hint: %#v", exitErr.Detail.Detail)
+	}
+}
+
+func TestAttachBaseResponseLogIDFromHeader(t *testing.T) {
+	result := map[string]interface{}{
+		"code": 91402,
+		"msg":  "NOTEXIST",
+		"data": map[string]interface{}{},
+	}
+	attachBaseErrorLogID(result, "20260508170000000000000000000000")
+
+	_, err := handleBaseAPIResultAny(result, nil, "API call failed")
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected structured exit error, got %v", err)
+	}
+	detail, _ := exitErr.Detail.Detail.(map[string]interface{})
+	if detail["logid"] != "20260508170000000000000000000000" {
+		t.Fatalf("logid=%q", detail["logid"])
+	}
+}
+
 type assertErr struct{}
 
 func (assertErr) Error() string { return "network timeout" }

shortcuts/base/helpers.go

@@ -412,6 +412,11 @@ func baseV3Raw(runtime *common.RuntimeContext, method, path string, params map[s
 	if err != nil {
 		return nil, err
 	}
+	result, parseErr := decodeBaseV3Response(resp.RawBody)
+	if parseErr == nil && baseV3ResultCode(result) != 0 {
+		attachBaseErrorLogID(result, baseResponseLogID(resp))
+		return result, nil
+	}
 	if resp.StatusCode >= http.StatusBadRequest {
 		body := strings.TrimSpace(string(resp.RawBody))
 		if body == "" {
@@ -419,8 +424,15 @@ func baseV3Raw(runtime *common.RuntimeContext, method, path string, params map[s
 		}
 		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, body)
 	}
+	if parseErr != nil {
+		return nil, parseErr
+	}
+	return result, nil
+}
+
+func decodeBaseV3Response(body []byte) (map[string]interface{}, error) {
 	var result map[string]interface{}
-	dec := json.NewDecoder(bytes.NewReader(resp.RawBody))
+	dec := json.NewDecoder(bytes.NewReader(body))
 	dec.UseNumber()
 	if err := dec.Decode(&result); err != nil {
 		return nil, fmt.Errorf("response parse error: %w", err)
@@ -428,6 +440,46 @@ func baseV3Raw(runtime *common.RuntimeContext, method, path string, params map[s
 	return result, nil
 }
 
+func baseV3ResultCode(result map[string]interface{}) int {
+	if result == nil {
+		return 0
+	}
+	return toInt(result["code"])
+}
+
+func attachBaseErrorLogID(result map[string]interface{}, logID string) {
+	if result == nil || strings.TrimSpace(logID) == "" {
+		return
+	}
+	logID = strings.TrimSpace(logID)
+	if detail, ok := result["error"].(map[string]interface{}); ok {
+		if _, exists := detail["logid"]; !exists {
+			detail["logid"] = logID
+		}
+		return
+	}
+	data, _ := result["data"].(map[string]interface{})
+	if data == nil {
+		data = map[string]interface{}{}
+		result["data"] = data
+	}
+	detail, _ := data["error"].(map[string]interface{})
+	if detail == nil {
+		detail = map[string]interface{}{}
+		data["error"] = detail
+	}
+	if _, exists := detail["logid"]; !exists {
+		detail["logid"] = logID
+	}
+}
+
+func baseResponseLogID(resp *larkcore.ApiResp) string {
+	if resp == nil {
+		return ""
+	}
+	return strings.TrimSpace(resp.Header.Get("x-tt-logid"))
+}
+
 func baseV3Call(runtime *common.RuntimeContext, method, path string, params map[string]interface{}, data interface{}) (map[string]interface{}, error) {
 	result, err := baseV3Raw(runtime, method, path, params, data)
 	return handleBaseAPIResult(result, err, "API call failed")

shortcuts/common/types.go

@@ -33,9 +33,18 @@ type Shortcut struct {
 	Command     string
 	Description string
 	Risk        string   // "read" | "write" | "high-risk-write" (empty defaults to "read")
-	Scopes      []string // default scopes (fallback when UserScopes/BotScopes are empty)
-	UserScopes  []string // optional: user-identity scopes (overrides Scopes when non-empty)
-	BotScopes   []string // optional: bot-identity scopes (overrides Scopes when non-empty)
+	Scopes      []string // unconditional pre-flight scopes (fallback when UserScopes/BotScopes are empty)
+	UserScopes  []string // optional: user-identity unconditional scopes (overrides Scopes when non-empty)
+	BotScopes   []string // optional: bot-identity unconditional scopes (overrides Scopes when non-empty)
+
+	// ConditionalScopes are additional scopes that only some execution paths
+	// need (for example a default mode vs. a lighter --quick mode, or a
+	// destructive flag like --delete-remote). They are surfaced in metadata,
+	// auth hints, and scope-diagnosis output via DeclaredScopesForIdentity, but
+	// they are NOT enforced by the framework's unconditional pre-flight check.
+	ConditionalScopes     []string // fallback when ConditionalUserScopes/BotScopes are empty
+	ConditionalUserScopes []string // optional: user-identity conditional scopes
+	ConditionalBotScopes  []string // optional: bot-identity conditional scopes
 
 	// Declarative fields (new framework).
 	AuthTypes []string // supported identities: "user", "bot" (default: ["user"])
@@ -72,3 +81,47 @@ func (s *Shortcut) ScopesForIdentity(identity string) []string {
 	}
 	return s.Scopes
 }
+
+// ConditionalScopesForIdentity returns additional flag/path-dependent scopes
+// for the given identity. Identity-specific conditional scopes override the
+// default ConditionalScopes when present.
+func (s *Shortcut) ConditionalScopesForIdentity(identity string) []string {
+	switch identity {
+	case "user":
+		if len(s.ConditionalUserScopes) > 0 {
+			return s.ConditionalUserScopes
+		}
+	case "bot":
+		if len(s.ConditionalBotScopes) > 0 {
+			return s.ConditionalBotScopes
+		}
+	}
+	return s.ConditionalScopes
+}
+
+// DeclaredScopesForIdentity returns the full scope set agents/help/diagnostics
+// should know about for this shortcut: unconditional pre-flight scopes plus
+// any conditional scopes that some execution paths may require.
+func (s *Shortcut) DeclaredScopesForIdentity(identity string) []string {
+	base := s.ScopesForIdentity(identity)
+	extra := s.ConditionalScopesForIdentity(identity)
+	if len(base) == 0 && len(extra) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(base)+len(extra))
+	seen := make(map[string]struct{}, len(base)+len(extra))
+	for _, scope := range append(base, extra...) {
+		if scope == "" {
+			continue
+		}
+		if _, ok := seen[scope]; ok {
+			continue
+		}
+		seen[scope] = struct{}{}
+		out = append(out, scope)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}

shortcuts/common/types_test.go

@@ -71,3 +71,37 @@ func TestScopesForIdentity_NilScopes(t *testing.T) {
 		t.Errorf("expected nil, got %v", got)
 	}
 }
+
+func TestConditionalScopesForIdentity_FallbackAndOverrides(t *testing.T) {
+	s := Shortcut{
+		ConditionalScopes:     []string{"c-default"},
+		ConditionalUserScopes: []string{"c-user"},
+		ConditionalBotScopes:  []string{"c-bot"},
+	}
+	if got := s.ConditionalScopesForIdentity("user"); !reflect.DeepEqual(got, []string{"c-user"}) {
+		t.Errorf("expected user conditional scopes, got %v", got)
+	}
+	if got := s.ConditionalScopesForIdentity("bot"); !reflect.DeepEqual(got, []string{"c-bot"}) {
+		t.Errorf("expected bot conditional scopes, got %v", got)
+	}
+	if got := s.ConditionalScopesForIdentity("tenant"); !reflect.DeepEqual(got, []string{"c-default"}) {
+		t.Errorf("expected default conditional scopes for unknown identity, got %v", got)
+	}
+}
+
+func TestDeclaredScopesForIdentity_MergesAndDeduplicates(t *testing.T) {
+	s := Shortcut{
+		Scopes:            []string{"base-a", "shared"},
+		ConditionalScopes: []string{"shared", "cond-b"},
+	}
+	if got := s.DeclaredScopesForIdentity("user"); !reflect.DeepEqual(got, []string{"base-a", "shared", "cond-b"}) {
+		t.Errorf("expected merged declared scopes, got %v", got)
+	}
+}
+
+func TestDeclaredScopesForIdentity_ConditionalOnly(t *testing.T) {
+	s := Shortcut{ConditionalScopes: []string{"cond-only"}}
+	if got := s.DeclaredScopesForIdentity("user"); !reflect.DeepEqual(got, []string{"cond-only"}) {
+		t.Errorf("expected conditional-only declared scopes, got %v", got)
+	}
+}

shortcuts/doc/doc_media_insert.go

@@ -7,6 +7,11 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"image"
+	_ "image/gif"
+	_ "image/jpeg"
+	_ "image/png"
+	"io"
 	"path/filepath"
 	"strings"
 
@@ -55,6 +60,8 @@ var DocMediaInsert = common.Shortcut{
 		{Name: "selection-with-ellipsis", Desc: "plain text (or 'start...end' to disambiguate) matching the target block's content. Media is inserted at the top-level ancestor of the matched block — i.e., when the selection is inside a callout, table cell, or nested list, media lands outside that container, not inside it. Pass 'start...end' (a unique prefix and suffix separated by '...') when the plain text appears in more than one block"},
 		{Name: "before", Type: "bool", Desc: "insert before the matched block instead of after (requires --selection-with-ellipsis)"},
 		{Name: "file-view", Desc: "file block rendering: card (default) | preview | inline; only applies when --type=file. preview renders audio/video as an inline player"},
+		{Name: "width", Type: "int", Desc: "image display width in pixels (only for --type=image); if --height is omitted it is auto-computed from the source image aspect ratio"},
+		{Name: "height", Type: "int", Desc: "image display height in pixels (only for --type=image); if --width is omitted it is auto-computed from the source image aspect ratio"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		filePath := runtime.Str("file")
@@ -93,6 +100,24 @@ var DocMediaInsert = common.Shortcut{
 				return output.ErrValidation("--file-view only applies when --type=file")
 			}
 		}
+		widthChanged := runtime.Changed("width")
+		heightChanged := runtime.Changed("height")
+		if (widthChanged || heightChanged) && runtime.Str("type") != "image" {
+			return output.ErrValidation("--width/--height only apply when --type=image")
+		}
+		if widthChanged && runtime.Int("width") <= 0 {
+			return output.ErrValidation("--width must be a positive integer")
+		}
+		if heightChanged && runtime.Int("height") <= 0 {
+			return output.ErrValidation("--height must be a positive integer")
+		}
+		const maxDimension = 10000
+		if widthChanged && runtime.Int("width") > maxDimension {
+			return output.ErrValidation("--width must not exceed %d pixels", maxDimension)
+		}
+		if heightChanged && runtime.Int("height") > maxDimension {
+			return output.ErrValidation("--height must not exceed %d pixels", maxDimension)
+		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -120,7 +145,25 @@ var DocMediaInsert = common.Shortcut{
 		} else {
 			createBlockData["index"] = "<children_len>"
 		}
-		batchUpdateData := buildBatchUpdateData("<new_block_id>", mediaType, "<file_token>", runtime.Str("align"), caption)
+		// Best-effort dimension computation for dry-run.
+		dryWidth := runtime.Int("width")
+		dryHeight := runtime.Int("height")
+		widthChanged := runtime.Changed("width")
+		heightChanged := runtime.Changed("height")
+
+		if (widthChanged || heightChanged) && !(widthChanged && heightChanged) {
+			if filePath == "<clipboard image>" {
+				fmt.Fprintf(runtime.IO().ErrOut, "Note: cannot detect clipboard image dimensions in dry-run; provide both --width and --height for accurate preview\n")
+			} else if nativeW, nativeH, err := detectImageDimensionsFromPath(runtime.FileIO(), filePath); err == nil {
+				dims := computeMissingDimension(dryWidth, dryHeight, nativeW, nativeH)
+				dryWidth = dims.width
+				dryHeight = dims.height
+			} else {
+				fmt.Fprintf(runtime.IO().ErrOut, "Note: unable to detect image dimensions from %s; provide both --width and --height to avoid failure at execution time\n", filePath)
+			}
+		}
+
+		batchUpdateData := buildBatchUpdateData("<new_block_id>", mediaType, "<file_token>", runtime.Str("align"), caption, dryWidth, dryHeight)
 
 		d := common.NewDryRunAPI()
 		totalSteps := 4
@@ -188,6 +231,9 @@ var DocMediaInsert = common.Shortcut{
 		if runtime.Bool("from-clipboard") {
 			d.Set("upload_size_note", "clipboard size unknown; single-part vs multipart decision deferred to runtime")
 		}
+		if runtime.Bool("from-clipboard") && (widthChanged || heightChanged) && !(widthChanged && heightChanged) {
+			d.Set("dimension_note", "clipboard dimensions unknown; aspect-ratio calculation deferred to runtime")
+		}
 		return d
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -314,6 +360,42 @@ var DocMediaInsert = common.Shortcut{
 		// interface stays a true nil for the --file path. Passing a typed-nil
 		// *bytes.Reader here would make the downstream `if cfg.Content != nil`
 		// check incorrectly take the clipboard branch and crash on Read.
+		// Resolve display dimensions before upload to fail fast on unreadable images.
+		var finalWidth, finalHeight int
+		if mediaType == "image" {
+			userWidth := runtime.Int("width")
+			userHeight := runtime.Int("height")
+			widthChanged := runtime.Changed("width")
+			heightChanged := runtime.Changed("height")
+
+			if widthChanged && heightChanged {
+				finalWidth = userWidth
+				finalHeight = userHeight
+			} else if widthChanged || heightChanged {
+				var nativeW, nativeH int
+				var dimErr error
+				if clipboardContent != nil {
+					nativeW, nativeH, dimErr = detectImageDimensions(bytes.NewReader(clipboardContent))
+				} else {
+					f, openErr := runtime.FileIO().Open(filePath)
+					if openErr != nil {
+						return withRollbackWarning(output.ErrValidation(
+							"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName))
+					}
+					nativeW, nativeH, dimErr = detectImageDimensions(f)
+					f.Close()
+				}
+				if dimErr != nil {
+					return withRollbackWarning(output.ErrValidation(
+						"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName))
+				}
+				dims := computeMissingDimension(userWidth, userHeight, nativeW, nativeH)
+				finalWidth = dims.width
+				finalHeight = dims.height
+				fmt.Fprintf(runtime.IO().ErrOut, "Image dimensions: %dx%d (native: %dx%d)\n", finalWidth, finalHeight, nativeW, nativeH)
+			}
+		}
+
 		uploadCfg := UploadDocMediaFileConfig{
 			FilePath:   filePath,
 			FileName:   fileName,
@@ -337,16 +419,23 @@ var DocMediaInsert = common.Shortcut{
 
 		if _, err := runtime.CallAPI("PATCH",
 			fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/batch_update", validate.EncodePathSegment(documentID)),
-			nil, buildBatchUpdateData(replaceBlockID, mediaType, fileToken, alignStr, caption)); err != nil {
+			nil, buildBatchUpdateData(replaceBlockID, mediaType, fileToken, alignStr, caption, finalWidth, finalHeight)); err != nil {
 			return withRollbackWarning(err)
 		}
 
-		runtime.Out(map[string]interface{}{
+		outData := map[string]interface{}{
 			"document_id": documentID,
 			"block_id":    blockId,
 			"file_token":  fileToken,
 			"type":        mediaType,
-		}, nil)
+		}
+		if finalWidth > 0 {
+			outData["width"] = finalWidth
+		}
+		if finalHeight > 0 {
+			outData["height"] = finalHeight
+		}
+		runtime.Out(outData, nil)
 		return nil
 	},
 }
@@ -453,7 +542,51 @@ func resolveDocxDocumentID(runtime *common.RuntimeContext, input string) (string
 	}
 }
 
-func buildBatchUpdateData(blockID, mediaType, fileToken, alignStr, caption string) map[string]interface{} {
+type imageDimensions struct {
+	width  int
+	height int
+}
+
+func computeMissingDimension(userWidth, userHeight, nativeWidth, nativeHeight int) imageDimensions {
+	if nativeWidth <= 0 || nativeHeight <= 0 {
+		return imageDimensions{width: userWidth, height: userHeight}
+	}
+	if userWidth > 0 && userHeight == 0 {
+		return imageDimensions{
+			width:  userWidth,
+			height: (userWidth*nativeHeight + nativeWidth/2) / nativeWidth,
+		}
+	}
+	if userHeight > 0 && userWidth == 0 {
+		return imageDimensions{
+			width:  (userHeight*nativeWidth + nativeHeight/2) / nativeHeight,
+			height: userHeight,
+		}
+	}
+	return imageDimensions{width: userWidth, height: userHeight}
+}
+
+func detectImageDimensions(r io.Reader) (width, height int, err error) {
+	cfg, _, err := image.DecodeConfig(r)
+	if err != nil {
+		return 0, 0, err
+	}
+	return cfg.Width, cfg.Height, nil
+}
+
+func detectImageDimensionsFromPath(fio fileio.FileIO, filePath string) (int, int, error) {
+	if _, err := validate.SafeInputPath(filePath); err != nil {
+		return 0, 0, err
+	}
+	f, err := fio.Open(filePath)
+	if err != nil {
+		return 0, 0, err
+	}
+	defer f.Close()
+	return detectImageDimensions(f)
+}
+
+func buildBatchUpdateData(blockID, mediaType, fileToken, alignStr, caption string, width, height int) map[string]interface{} {
 	request := map[string]interface{}{
 		"block_id": blockID,
 	}
@@ -465,6 +598,12 @@ func buildBatchUpdateData(blockID, mediaType, fileToken, alignStr, caption strin
 		replaceImage := map[string]interface{}{
 			"token": fileToken,
 		}
+		if width > 0 {
+			replaceImage["width"] = width
+		}
+		if height > 0 {
+			replaceImage["height"] = height
+		}
 		if alignVal, ok := alignMap[alignStr]; ok {
 			replaceImage["align"] = alignVal
 		}

shortcuts/doc/doc_media_insert_test.go

@@ -6,6 +6,7 @@ package doc
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"reflect"
 	"strings"
 	"testing"
@@ -176,7 +177,7 @@ func TestBuildDeleteBlockDataUsesHalfOpenInterval(t *testing.T) {
 func TestBuildBatchUpdateDataForImage(t *testing.T) {
 	t.Parallel()
 
-	got := buildBatchUpdateData("blk_1", "image", "file_tok", "center", "caption text")
+	got := buildBatchUpdateData("blk_1", "image", "file_tok", "center", "caption text", 0, 0)
 	want := map[string]interface{}{
 		"requests": []interface{}{
 			map[string]interface{}{
@@ -199,7 +200,7 @@ func TestBuildBatchUpdateDataForImage(t *testing.T) {
 func TestBuildBatchUpdateDataForFile(t *testing.T) {
 	t.Parallel()
 
-	got := buildBatchUpdateData("blk_2", "file", "file_tok", "", "")
+	got := buildBatchUpdateData("blk_2", "file", "file_tok", "", "", 0, 0)
 	want := map[string]interface{}{
 		"requests": []interface{}{
 			map[string]interface{}{
@@ -215,6 +216,48 @@ func TestBuildBatchUpdateDataForFile(t *testing.T) {
 	}
 }
 
+func TestBuildBatchUpdateDataForImageWithWidthHeight(t *testing.T) {
+	t.Parallel()
+
+	got := buildBatchUpdateData("blk_1", "image", "file_tok", "center", "caption text", 800, 447)
+	want := map[string]interface{}{
+		"requests": []interface{}{
+			map[string]interface{}{
+				"block_id": "blk_1",
+				"replace_image": map[string]interface{}{
+					"token":   "file_tok",
+					"width":   800,
+					"height":  447,
+					"align":   2,
+					"caption": map[string]interface{}{"content": "caption text"},
+				},
+			},
+		},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("buildBatchUpdateData(image, 800, 447) = %#v, want %#v", got, want)
+	}
+}
+
+func TestBuildBatchUpdateDataForFileIgnoresWidthHeight(t *testing.T) {
+	t.Parallel()
+
+	got := buildBatchUpdateData("blk_2", "file", "file_tok", "", "", 800, 600)
+	want := map[string]interface{}{
+		"requests": []interface{}{
+			map[string]interface{}{
+				"block_id": "blk_2",
+				"replace_file": map[string]interface{}{
+					"token": "file_tok",
+				},
+			},
+		},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("buildBatchUpdateData(file, 800, 600) = %#v, want %#v", got, want)
+	}
+}
+
 func TestExtractAppendTargetUsesRootChildrenCount(t *testing.T) {
 	t.Parallel()
 
@@ -669,10 +712,202 @@ func newMediaInsertValidateRuntime(t *testing.T, doc, mediaType, fileView string
 	return common.TestNewRuntimeContext(cmd, nil)
 }
 
-// Validate is the real user-facing contract for --file-view: unknown
-// values must be rejected, and passing the flag alongside --type!=file
-// must also be rejected. buildCreateBlockData tests alone cannot catch
-// regressions here, so lock the guard logic down explicitly.
+func newMediaInsertValidateRuntimeWithSize(t *testing.T, doc, mediaType string, width, height int, setWidth, setHeight bool) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "docs +media-insert"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().Bool("from-clipboard", false, "")
+	cmd.Flags().String("doc", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("file-view", "", "")
+	cmd.Flags().Int("width", 0, "")
+	cmd.Flags().Int("height", 0, "")
+	cmd.Flags().String("selection-with-ellipsis", "", "")
+	cmd.Flags().Bool("before", false, "")
+	if err := cmd.Flags().Set("file", "dummy.bin"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("doc", doc); err != nil {
+		t.Fatalf("set --doc: %v", err)
+	}
+	if err := cmd.Flags().Set("type", mediaType); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+	if setWidth {
+		if err := cmd.Flags().Set("width", fmt.Sprintf("%d", width)); err != nil {
+			t.Fatalf("set --width: %v", err)
+		}
+	}
+	if setHeight {
+		if err := cmd.Flags().Set("height", fmt.Sprintf("%d", height)); err != nil {
+			t.Fatalf("set --height: %v", err)
+		}
+	}
+	return common.TestNewRuntimeContext(cmd, nil)
+}
+
+func TestDocMediaInsertValidateWidthHeightOnlyForImage(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		mediaType string
+		width     int
+		height    int
+		setWidth  bool
+		setHeight bool
+		wantErr   string
+	}{
+		{
+			name:      "width with file type is rejected",
+			mediaType: "file",
+			width:     800,
+			setWidth:  true,
+			wantErr:   "--width/--height only apply when --type=image",
+		},
+		{
+			name:      "height with file type is rejected",
+			mediaType: "file",
+			height:    600,
+			setHeight: true,
+			wantErr:   "--width/--height only apply when --type=image",
+		},
+		{
+			name:      "explicit zero width is rejected",
+			mediaType: "image",
+			width:     0,
+			setWidth:  true,
+			wantErr:   "--width must be a positive integer",
+		},
+		{
+			name:      "negative width is rejected",
+			mediaType: "image",
+			width:     -1,
+			setWidth:  true,
+			wantErr:   "--width must be a positive integer",
+		},
+		{
+			name:      "negative height is rejected",
+			mediaType: "image",
+			height:    -5,
+			setHeight: true,
+			wantErr:   "--height must be a positive integer",
+		},
+		{
+			name:      "valid width with image type is accepted",
+			mediaType: "image",
+			width:     800,
+			setWidth:  true,
+		},
+		{
+			name:      "valid width and height with image type is accepted",
+			mediaType: "image",
+			width:     800,
+			height:    600,
+			setWidth:  true,
+			setHeight: true,
+		},
+	}
+
+	for _, ttTemp := range tests {
+		tt := ttTemp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			rt := newMediaInsertValidateRuntimeWithSize(t, "doxcnValidateSize", tt.mediaType, tt.width, tt.height, tt.setWidth, tt.setHeight)
+			err := DocMediaInsert.Validate(context.Background(), rt)
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Fatalf("Validate() unexpected error: %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatalf("Validate() error = nil, want error containing %q", tt.wantErr)
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("Validate() error = %q, want substring %q", err.Error(), tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestDocMediaInsertValidateNoWidthHeightIsValid(t *testing.T) {
+	t.Parallel()
+
+	rt := newMediaInsertValidateRuntimeWithSize(t, "doxcnNoSize", "image", 0, 0, false, false)
+	err := DocMediaInsert.Validate(context.Background(), rt)
+	if err != nil {
+		t.Fatalf("Validate() unexpected error when neither --width nor --height passed: %v", err)
+	}
+}
+
+func TestAutoAspectRatioFromWidth(t *testing.T) {
+	t.Parallel()
+
+	// Native image: 1200x800 (3:2 ratio)
+	// User provides width=600 → expected height = 600 * 800 / 1200 = 400
+	got := computeMissingDimension(600, 0, 1200, 800)
+	wantWidth, wantHeight := 600, 400
+	if got.width != wantWidth || got.height != wantHeight {
+		t.Fatalf("computeMissingDimension(600, 0, 1200, 800) = (%d, %d), want (%d, %d)", got.width, got.height, wantWidth, wantHeight)
+	}
+}
+
+func TestAutoAspectRatioFromHeight(t *testing.T) {
+	t.Parallel()
+
+	// Native image: 1200x800 (3:2 ratio)
+	// User provides height=400 → expected width = 400 * 1200 / 800 = 600
+	got := computeMissingDimension(0, 400, 1200, 800)
+	wantWidth, wantHeight := 600, 400
+	if got.width != wantWidth || got.height != wantHeight {
+		t.Fatalf("computeMissingDimension(0, 400, 1200, 800) = (%d, %d), want (%d, %d)", got.width, got.height, wantWidth, wantHeight)
+	}
+}
+
+func TestComputeMissingDimensionBothProvided(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(800, 600, 1200, 900)
+	if got.width != 800 || got.height != 600 {
+		t.Fatalf("computeMissingDimension(800, 600, 1200, 900) = (%d, %d), want (800, 600)", got.width, got.height)
+	}
+}
+
+func TestComputeMissingDimensionNeitherProvided(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(0, 0, 1200, 900)
+	if got.width != 0 || got.height != 0 {
+		t.Fatalf("computeMissingDimension(0, 0, 1200, 900) = (%d, %d), want (0, 0)", got.width, got.height)
+	}
+}
+
+func TestComputeMissingDimensionZeroNativeWidth(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(600, 0, 0, 800)
+	if got.width != 600 || got.height != 0 {
+		t.Fatalf("computeMissingDimension(600, 0, 0, 800) = (%d, %d), want (600, 0)", got.width, got.height)
+	}
+}
+
+func TestComputeMissingDimensionZeroNativeHeight(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(0, 400, 1200, 0)
+	if got.width != 0 || got.height != 400 {
+		t.Fatalf("computeMissingDimension(0, 400, 1200, 0) = (%d, %d), want (0, 400)", got.width, got.height)
+	}
+}
+
+func TestComputeMissingDimensionRounding(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(999, 0, 1000, 333)
+	want := (999*333 + 500) / 1000
+	if got.height != want {
+		t.Fatalf("computeMissingDimension(999, 0, 1000, 333).height = %d, want %d (rounded)", got.height, want)
+	}
+}
+
 func TestDocMediaInsertValidateFileView(t *testing.T) {
 	t.Parallel()
 

shortcuts/doc/docs_create_v2.go

@@ -67,6 +67,7 @@ func buildCreateBody(runtime *common.RuntimeContext) map[string]interface{} {
 	if v := runtime.Str("parent-position"); v != "" {
 		body["parent_position"] = v
 	}
+	injectDocsScene(runtime, body)
 	return body
 }
 

shortcuts/doc/docs_fetch_v2.go

@@ -109,6 +109,7 @@ func buildFetchBody(runtime *common.RuntimeContext) map[string]interface{} {
 	if ro := buildReadOption(runtime); ro != nil {
 		body["read_option"] = ro
 	}
+	injectDocsScene(runtime, body)
 
 	return body
 }

shortcuts/doc/docs_fetch_v2_test.go

@@ -0,0 +1,95 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"context"
+	"testing"
+
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+func TestBuildFetchBodyIncludesSceneFromContext(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), docsSceneContextKey, " DoubaoCLI ")
+	runtime := newFetchBodyTestRuntime(ctx)
+
+	body := buildFetchBody(runtime)
+	if got := body["scene"]; got != "DoubaoCLI" {
+		t.Fatalf("scene = %#v, want %q", got, "DoubaoCLI")
+	}
+}
+
+func TestBuildCreateBodyIncludesSceneFromContext(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), docsSceneContextKey, "DoubaoCLI")
+	runtime := newCreateBodyTestRuntime(ctx)
+
+	body := buildCreateBody(runtime)
+	if got := body["scene"]; got != "DoubaoCLI" {
+		t.Fatalf("scene = %#v, want %q", got, "DoubaoCLI")
+	}
+}
+
+func TestBuildUpdateBodyIncludesSceneFromContext(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), docsSceneContextKey, "DoubaoCLI")
+	runtime := newUpdateBodyTestRuntime(ctx)
+
+	body := buildUpdateBody(runtime)
+	if got := body["scene"]; got != "DoubaoCLI" {
+		t.Fatalf("scene = %#v, want %q", got, "DoubaoCLI")
+	}
+}
+
+func TestBuildFetchBodyOmitsEmptyScene(t *testing.T) {
+	t.Parallel()
+
+	runtime := newFetchBodyTestRuntime(context.Background())
+
+	body := buildFetchBody(runtime)
+	if _, ok := body["scene"]; ok {
+		t.Fatalf("did not expect empty scene in fetch body: %#v", body)
+	}
+}
+
+func newFetchBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
+	cmd := &cobra.Command{Use: "+fetch"}
+	cmd.Flags().String("doc-format", "xml", "")
+	cmd.Flags().String("detail", "simple", "")
+	cmd.Flags().Int("revision-id", -1, "")
+	cmd.Flags().String("scope", "full", "")
+	cmd.Flags().String("start-block-id", "", "")
+	cmd.Flags().String("end-block-id", "", "")
+	cmd.Flags().String("keyword", "", "")
+	cmd.Flags().Int("context-before", 0, "")
+	cmd.Flags().Int("context-after", 0, "")
+	cmd.Flags().Int("max-depth", -1, "")
+	return common.TestNewRuntimeContextWithCtx(ctx, cmd, nil)
+}
+
+func newCreateBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
+	cmd := &cobra.Command{Use: "+create"}
+	cmd.Flags().String("doc-format", "xml", "")
+	cmd.Flags().String("content", "<title>hello</title>", "")
+	cmd.Flags().String("parent-token", "", "")
+	cmd.Flags().String("parent-position", "", "")
+	return common.TestNewRuntimeContextWithCtx(ctx, cmd, nil)
+}
+
+func newUpdateBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
+	cmd := &cobra.Command{Use: "+update"}
+	cmd.Flags().String("doc-format", "xml", "")
+	cmd.Flags().String("command", "append", "")
+	cmd.Flags().Int("revision-id", 0, "")
+	cmd.Flags().String("content", "<p>hello</p>", "")
+	cmd.Flags().String("pattern", "", "")
+	cmd.Flags().String("block-id", "", "")
+	cmd.Flags().String("src-block-ids", "", "")
+	return common.TestNewRuntimeContextWithCtx(ctx, cmd, nil)
+}

shortcuts/doc/docs_update_v2.go

@@ -162,5 +162,6 @@ func buildUpdateBody(runtime *common.RuntimeContext) map[string]interface{} {
 	if v := runtime.Str("src-block-ids"); v != "" {
 		body["src_block_ids"] = v
 	}
+	injectDocsScene(runtime, body)
 	return body
 }

shortcuts/doc/helpers.go

@@ -4,6 +4,7 @@
 package doc
 
 import (
+	"context"
 	"encoding/json"
 	"strings"
 
@@ -11,6 +12,10 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+// docsSceneContextKey lets in-process embedders pass a server-owned docs_ai
+// scene without exposing it as a user-controlled CLI flag.
+const docsSceneContextKey = "lark_cli_docs_scene"
+
 type documentRef struct {
 	Kind  string
 	Token string
@@ -65,6 +70,20 @@ func doDocAPI(runtime *common.RuntimeContext, method, apiPath string, body inter
 	return runtime.DoAPIJSONWithLogID(method, apiPath, nil, body)
 }
 
+func docsSceneFromContext(ctx context.Context) string {
+	if ctx == nil {
+		return ""
+	}
+	scene, _ := ctx.Value(docsSceneContextKey).(string)
+	return strings.TrimSpace(scene)
+}
+
+func injectDocsScene(runtime *common.RuntimeContext, body map[string]interface{}) {
+	if scene := docsSceneFromContext(runtime.Ctx()); scene != "" {
+		body["scene"] = scene
+	}
+}
+
 func buildDriveRouteExtra(docID string) (string, error) {
 	extra, err := json.Marshal(map[string]string{"drive_route_token": docID})
 	if err != nil {

shortcuts/doc/shortcuts.go

@@ -18,8 +18,19 @@ const docsServiceHelpDefault = `Document and content operations.`
 const docsServiceHelpV2 = `Document and content operations (v2).`
 
 var docsVersionSelectionTips = []string{
-	"Agent version rule: use --api-version v2 only when the installed lark-doc skill explicitly instructs docs +create, docs +fetch, or docs +update to use v2; otherwise use the default v1 flags.",
-	"Do not mix versions: if the skill does not mention v2, follow its legacy v1 examples and flags.",
+	"Docs v1 is deprecated and will be removed soon. Check the installed lark-doc skill first; if it is not the v2 skill, run `lark-cli update` to upgrade skills.",
+	"After confirming lark-doc is v2, follow that skill's examples and use `--api-version v2` with docs +create, docs +fetch, and docs +update.",
+}
+
+var docsV2VersionSelectionTips = []string{
+	"Check the installed lark-doc skill first; if it is not the v2 skill, run `lark-cli update` to upgrade skills.",
+}
+
+func docsTipsForVersion(apiVersion string) []string {
+	if apiVersion == "v2" {
+		return docsV2VersionSelectionTips
+	}
+	return docsVersionSelectionTips
 }
 
 // Shortcuts returns all docs shortcuts.
@@ -38,8 +49,7 @@ func Shortcuts() []common.Shortcut {
 
 // ConfigureServiceHelp adds docs-specific guidance to the parent `docs` command.
 // The shortcut-level help remains compatible with legacy v1 skills; this parent
-// help gives agents enough context to choose v2 only when their installed skill
-// explicitly asks for `--api-version v2`.
+// help switches docs guidance to match the selected API version.
 func ConfigureServiceHelp(cmd *cobra.Command) {
 	if cmd == nil {
 		return
@@ -75,7 +85,7 @@ func ConfigureServiceHelp(cmd *cobra.Command) {
 		out := cmd.OutOrStdout()
 		fmt.Fprintln(out)
 		fmt.Fprintln(out, "Tips:")
-		for _, tip := range docsVersionSelectionTips {
+		for _, tip := range docsTipsForVersion(apiVersion) {
 			fmt.Fprintf(out, "    • %s\n", tip)
 		}
 	})

shortcuts/doc/versioned_help.go

@@ -6,6 +6,7 @@ package doc
 import (
 	"fmt"
 
+	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 
@@ -29,6 +30,7 @@ func installVersionedHelp(cmd *cobra.Command, defaultVersion string, flagVersion
 				f.Hidden = fv != ver
 			}
 		})
+		cmdutil.SetTips(cmd, docsTipsForVersion(ver))
 		origHelp(cmd, args)
 	})
 }
@@ -37,6 +39,6 @@ func installVersionedHelp(cmd *cobra.Command, defaultVersion string, flagVersion
 // path is used.
 func warnDeprecatedV1(runtime *common.RuntimeContext, shortcut string) {
 	fmt.Fprintf(runtime.IO().ErrOut,
-		"[deprecated] docs %s with v1 API is deprecated and will be removed in a future release.\n",
-		shortcut)
+		"[deprecated] docs %s is using the v1 API. %s\n",
+		shortcut, docsV2VersionSelectionTips[0])
 }

shortcuts/doc/versioned_help_test.go

@@ -0,0 +1,36 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestWarnDeprecatedV1SuggestsSkillUpdate(t *testing.T) {
+	for _, shortcut := range []string{"+create", "+fetch", "+update"} {
+		t.Run(shortcut, func(t *testing.T) {
+			f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{})
+			warnDeprecatedV1(&common.RuntimeContext{Factory: f}, shortcut)
+
+			got := stderr.String()
+			for _, want := range []string{
+				"[deprecated] docs " + shortcut + " is using the v1 API.",
+				"Check the installed lark-doc skill first",
+				"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
+			} {
+				if !strings.Contains(got, want) {
+					t.Fatalf("warning missing %q:\n%s", want, got)
+				}
+			}
+			if strings.Contains(got, "will be removed in a future release") {
+				t.Fatalf("warning should not include removal-only guidance:\n%s", got)
+			}
+		})
+	}
+}

shortcuts/drive/drive_duplicate_remote_test.go

@@ -0,0 +1,994 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"os"
+	"path"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+)
+
+const (
+	duplicateRemoteFileIDFirst  = "example-file-token-first"
+	duplicateRemoteFileIDSecond = "example-file-token-second"
+	duplicateRemoteFileIDThird  = "example-file-token-third"
+	duplicateRemoteFolderID     = "example-folder-token"
+)
+
+func TestDriveStatusFailsOnDuplicateRemoteFiles(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)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+
+	err := mountAndRunDrive(t, DriveStatus, []string{
+		"+status",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	assertDuplicateRemotePathError(t, err, "dup.txt", duplicateRemoteFileIDFirst, duplicateRemoteFileIDSecond)
+	if stdout.String() != "" {
+		t.Fatalf("stdout should be empty on duplicate_remote_path, got: %s", stdout.String())
+	}
+
+	reg.Verify(t)
+}
+
+func TestDrivePullFailsOnDuplicateRemoteFilesBeforeWriting(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)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	assertDuplicateRemotePathError(t, err, "dup.txt", duplicateRemoteFileIDFirst, duplicateRemoteFileIDSecond)
+	if _, statErr := os.Stat(filepath.Join("local", "dup.txt")); !os.IsNotExist(statErr) {
+		t.Fatalf("duplicate default failure must not write local dup.txt; stat err=%v", statErr)
+	}
+	if stdout.String() != "" {
+		t.Fatalf("stdout should be empty on duplicate_remote_path, got: %s", stdout.String())
+	}
+
+	reg.Verify(t)
+}
+
+func TestDrivePullRenameDownloadsDuplicateRemoteFilesWithStableHashSuffix(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)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/files/" + duplicateRemoteFileIDFirst + "/download",
+		Status:  200,
+		Body:    []byte("FIRST"),
+		Headers: http.Header{"Content-Type": []string{"application/octet-stream"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/files/" + duplicateRemoteFileIDSecond + "/download",
+		Status:  200,
+		Body:    []byte("SECOND"),
+		Headers: http.Header{"Content-Type": []string{"application/octet-stream"}},
+	})
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--on-duplicate-remote", "rename",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
+	}
+
+	renamedRelPath := expectedRenamedRelPath("dup.txt", duplicateRemoteFileIDSecond, 12, 0)
+	mustReadFile(t, filepath.Join("local", "dup.txt"), "FIRST")
+	mustReadFile(t, filepath.Join("local", renamedRelPath), "SECOND")
+	if strings.Contains(renamedRelPath, duplicateRemoteFileIDSecond) {
+		t.Fatalf("renamed rel_path should not expose raw file token: %s", renamedRelPath)
+	}
+	payload := decodeDrivePullStdout(t, stdout.Bytes())
+	if got := payload.Data.Summary.Downloaded; got != 2 {
+		t.Fatalf("summary.downloaded = %d, want 2", got)
+	}
+	if item := findPullItem(payload.Data.Items, renamedRelPath); item.SourceID == "" || item.FileToken != "" {
+		t.Fatalf("rename item should emit source_id without file_token, got: %#v", item)
+	}
+	assertPullItemAction(t, stdout.Bytes(), renamedRelPath, "downloaded")
+
+	reg.Verify(t)
+}
+
+func TestDrivePullRenameStrengthensSuffixWhenShortHashTargetAlreadyExists(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)
+	}
+
+	shortHashRelPath := expectedRenamedRelPath("dup.txt", duplicateRemoteFileIDSecond, 12, 0)
+	registerRemoteListing(reg, "folder_root", []map[string]interface{}{
+		{"token": duplicateRemoteFileIDFirst, "name": "dup.txt", "type": "file", "size": 5, "created_time": "1", "modified_time": "1"},
+		{"token": duplicateRemoteFileIDSecond, "name": "dup.txt", "type": "file", "size": 6, "created_time": "2", "modified_time": "2"},
+		{"token": duplicateRemoteFileIDThird, "name": shortHashRelPath, "type": "file", "size": 7, "created_time": "3", "modified_time": "3"},
+	})
+	registerDownload(reg, duplicateRemoteFileIDFirst, "FIRST")
+	registerDownload(reg, duplicateRemoteFileIDSecond, "SECOND")
+	registerDownload(reg, duplicateRemoteFileIDThird, "THIRD")
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--on-duplicate-remote", "rename",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
+	}
+
+	occupied := occupiedRemotePaths([]driveRemoteEntry{
+		{RelPath: "dup.txt"},
+		{RelPath: "dup.txt"},
+		{RelPath: shortHashRelPath},
+	})
+	strongerRelPath, err := relPathWithUniqueFileTokenSuffix("dup.txt", duplicateRemoteFileIDSecond, occupied)
+	if err != nil {
+		t.Fatalf("relPathWithUniqueFileTokenSuffix: %v", err)
+	}
+	if strongerRelPath == shortHashRelPath {
+		t.Fatalf("expected stronger unique suffix when %q is already occupied", shortHashRelPath)
+	}
+	mustReadFile(t, filepath.Join("local", shortHashRelPath), "THIRD")
+	mustReadFile(t, filepath.Join("local", strongerRelPath), "SECOND")
+	payload := decodeDrivePullStdout(t, stdout.Bytes())
+	if got := payload.Data.Summary.Downloaded; got != 3 {
+		t.Fatalf("summary.downloaded = %d, want 3", got)
+	}
+	if item := findPullItem(payload.Data.Items, strongerRelPath); item.SourceID == "" || item.FileToken != "" {
+		t.Fatalf("rename item should emit source_id without file_token, got: %#v", item)
+	}
+	assertPullItemAction(t, stdout.Bytes(), strongerRelPath, "downloaded")
+
+	reg.Verify(t)
+}
+
+func TestDrivePullRenameAppendsSequenceWhenAllHashSuffixTargetsAreOccupied(t *testing.T) {
+	fileToken := duplicateRemoteFileIDSecond
+	tokenHash := stableTokenHash(fileToken)
+	occupied := map[string]struct{}{
+		"dup.txt": {},
+		relPathWithSuffix("dup.txt", "__lark_"+tokenHash[:12]): {},
+		relPathWithSuffix("dup.txt", "__lark_"+tokenHash[:24]): {},
+		relPathWithSuffix("dup.txt", "__lark_"+tokenHash):      {},
+		relPathWithSuffix("dup.txt", "__lark_"+tokenHash+"_2"): {},
+	}
+
+	got, err := relPathWithUniqueFileTokenSuffix("dup.txt", fileToken, occupied)
+	if err != nil {
+		t.Fatalf("relPathWithUniqueFileTokenSuffix: %v", err)
+	}
+	want := relPathWithSuffix("dup.txt", "__lark_"+tokenHash+"_3")
+	if got != want {
+		t.Fatalf("unique rel_path = %q, want %q", got, want)
+	}
+}
+
+func TestRelPathWithUniqueFileTokenSuffixReturnsErrorAfterMaxAttempts(t *testing.T) {
+	fileToken := duplicateRemoteFileIDSecond
+	tokenHash := stableTokenHash(fileToken)
+	occupied := map[string]struct{}{
+		"dup.txt": {},
+	}
+	for _, suffix := range []string{
+		"__lark_" + tokenHash[:12],
+		"__lark_" + tokenHash[:24],
+		"__lark_" + tokenHash,
+	} {
+		occupied[relPathWithSuffix("dup.txt", suffix)] = struct{}{}
+	}
+	for attempt := 2; attempt <= driveUniqueSuffixMaxSeq; attempt++ {
+		occupied[relPathWithSuffix("dup.txt", "__lark_"+tokenHash+"_"+strconv.Itoa(attempt))] = struct{}{}
+	}
+
+	_, err := relPathWithUniqueFileTokenSuffix("dup.txt", fileToken, occupied)
+	if err == nil {
+		t.Fatal("expected relPathWithUniqueFileTokenSuffix to fail after exhausting all suffix attempts")
+	}
+}
+
+func TestDrivePullNewestChoosesMostRecentDuplicateRemoteFile(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)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+	registerDownload(reg, duplicateRemoteFileIDSecond, "SECOND")
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--on-duplicate-remote", "newest",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
+	}
+
+	mustReadFile(t, filepath.Join("local", "dup.txt"), "SECOND")
+	assertPullItemAction(t, stdout.Bytes(), "dup.txt", "downloaded")
+	payload := decodeDrivePullStdout(t, stdout.Bytes())
+	if got := payload.Data.Summary.Downloaded; got != 1 {
+		t.Fatalf("summary.downloaded = %d, want 1", got)
+	}
+	if item := findPullItem(payload.Data.Items, "dup.txt"); item.FileToken != duplicateRemoteFileIDSecond {
+		t.Fatalf("stdout should surface the chosen newest file token, got: %#v", item)
+	}
+
+	reg.Verify(t)
+}
+
+func TestDrivePullOldestChoosesOldestDuplicateRemoteFile(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)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+	registerDownload(reg, duplicateRemoteFileIDFirst, "FIRST")
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--on-duplicate-remote", "oldest",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
+	}
+
+	mustReadFile(t, filepath.Join("local", "dup.txt"), "FIRST")
+	assertPullItemAction(t, stdout.Bytes(), "dup.txt", "downloaded")
+	payload := decodeDrivePullStdout(t, stdout.Bytes())
+	if got := payload.Data.Summary.Downloaded; got != 1 {
+		t.Fatalf("summary.downloaded = %d, want 1", got)
+	}
+	if item := findPullItem(payload.Data.Items, "dup.txt"); item.FileToken != duplicateRemoteFileIDFirst {
+		t.Fatalf("stdout should surface the chosen oldest file token, got: %#v", item)
+	}
+
+	reg.Verify(t)
+}
+
+func TestDrivePullRenameHandlesNestedDuplicateRemoteFilesEndToEnd(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)
+	}
+
+	registerRemoteListing(reg, "folder_root", []map[string]interface{}{
+		{"token": duplicateRemoteFolderID, "name": "sub", "type": "folder", "created_time": "1", "modified_time": "1"},
+	})
+	registerRemoteListing(reg, duplicateRemoteFolderID, []map[string]interface{}{
+		{"token": duplicateRemoteFileIDFirst, "name": "dup.txt", "type": "file", "size": 5, "created_time": "1", "modified_time": "1"},
+		{"token": duplicateRemoteFileIDSecond, "name": "dup.txt", "type": "file", "size": 6, "created_time": "2", "modified_time": "2"},
+	})
+	registerDownload(reg, duplicateRemoteFileIDFirst, "FIRST")
+	registerDownload(reg, duplicateRemoteFileIDSecond, "SECOND")
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--on-duplicate-remote", "rename",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
+	}
+
+	renamedRelPath := expectedRenamedRelPath("sub/dup.txt", duplicateRemoteFileIDSecond, 12, 0)
+	mustReadFile(t, filepath.Join("local", "sub", "dup.txt"), "FIRST")
+	mustReadFile(t, filepath.Join("local", filepath.FromSlash(renamedRelPath)), "SECOND")
+	assertPullItemAction(t, stdout.Bytes(), "sub/dup.txt", "downloaded")
+	assertPullItemAction(t, stdout.Bytes(), renamedRelPath, "downloaded")
+
+	reg.Verify(t)
+}
+
+func TestDrivePushFailsOnDuplicateRemoteFilesBeforeUpload(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("LOCAL"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--if-exists", "overwrite",
+		"--delete-remote",
+		"--yes",
+		"--as", "bot",
+	}, f, stdout)
+	assertDuplicateRemotePathError(t, err, "dup.txt", duplicateRemoteFileIDFirst, duplicateRemoteFileIDSecond)
+	if stdout.String() != "" {
+		t.Fatalf("stdout should be empty on duplicate_remote_path, got: %s", stdout.String())
+	}
+
+	reg.Verify(t)
+}
+
+func TestDrivePullFailsOnRemoteFileFolderConflictEvenWithRename(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)
+	}
+
+	registerRemoteListing(reg, "folder_root", []map[string]interface{}{
+		{"token": duplicateRemoteFileIDFirst, "name": "dup", "type": "file", "size": 5, "created_time": "1", "modified_time": "1"},
+		{"token": duplicateRemoteFolderID, "name": "dup", "type": "folder", "created_time": "2", "modified_time": "2"},
+	})
+	registerRemoteListing(reg, duplicateRemoteFolderID, nil)
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--on-duplicate-remote", "rename",
+		"--as", "bot",
+	}, f, stdout)
+	assertDuplicateRemotePathError(t, err, "dup", duplicateRemoteFileIDFirst, duplicateRemoteFolderID)
+	if stdout.String() != "" {
+		t.Fatalf("stdout should be empty on duplicate_remote_path, got: %s", stdout.String())
+	}
+
+	reg.Verify(t)
+}
+
+func TestDrivePushFailsOnRemoteFileFolderConflictEvenWithNewest(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"), []byte("LOCAL"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	registerRemoteListing(reg, "folder_root", []map[string]interface{}{
+		{"token": duplicateRemoteFileIDFirst, "name": "dup", "type": "file", "size": 5, "created_time": "1", "modified_time": "1"},
+		{"token": duplicateRemoteFolderID, "name": "dup", "type": "folder", "created_time": "2", "modified_time": "2"},
+	})
+	registerRemoteListing(reg, duplicateRemoteFolderID, nil)
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--on-duplicate-remote", "newest",
+		"--if-exists", "skip",
+		"--as", "bot",
+	}, f, stdout)
+	assertDuplicateRemotePathError(t, err, "dup", duplicateRemoteFileIDFirst, duplicateRemoteFolderID)
+	if stdout.String() != "" {
+		t.Fatalf("stdout should be empty on duplicate_remote_path, got: %s", stdout.String())
+	}
+
+	reg.Verify(t)
+}
+
+func TestDrivePushDeleteRemoteDeletesUnchosenDuplicateSibling(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("LOCAL"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/drive/v1/files/" + duplicateRemoteFileIDFirst,
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--if-exists", "skip",
+		"--on-duplicate-remote", "newest",
+		"--delete-remote",
+		"--yes",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
+	}
+	assertPushItemAction(t, stdout.Bytes(), "dup.txt", "deleted_remote", duplicateRemoteFileIDFirst)
+
+	reg.Verify(t)
+}
+
+func TestDrivePushOldestOverwritesChosenDuplicateAndDeletesSibling(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("LOCAL"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+	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-oldest-new-token",
+				"version":    "v11",
+			},
+		},
+	}
+	reg.Register(uploadStub)
+	deleteStub := &httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/drive/v1/files/" + duplicateRemoteFileIDSecond,
+		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", "oldest",
+		"--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 != duplicateRemoteFileIDFirst {
+		t.Fatalf("upload_all form file_token = %q, want %q", got, duplicateRemoteFileIDFirst)
+	}
+	assertPushItemAction(t, stdout.Bytes(), "dup.txt", "deleted_remote", duplicateRemoteFileIDSecond)
+	if deleteStub.CapturedHeaders == nil {
+		t.Fatal("DELETE for the newer duplicate sibling was never issued")
+	}
+
+	reg.Verify(t)
+}
+
+func TestDrivePushNewestResolvesNestedDuplicateRemoteFilesEndToEnd(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll(filepath.Join("local", "sub"), 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join("local", "sub", "dup.txt"), []byte("LOCAL"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	registerRemoteListing(reg, "folder_root", []map[string]interface{}{
+		{"token": duplicateRemoteFolderID, "name": "sub", "type": "folder", "created_time": "1", "modified_time": "1"},
+	})
+	registerRemoteListing(reg, duplicateRemoteFolderID, []map[string]interface{}{
+		{"token": duplicateRemoteFileIDFirst, "name": "dup.txt", "type": "file", "size": 5, "created_time": "1", "modified_time": "1"},
+		{"token": duplicateRemoteFileIDSecond, "name": "dup.txt", "type": "file", "size": 6, "created_time": "2", "modified_time": "2"},
+	})
+	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": "nested-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(), "sub/dup.txt", "deleted_remote", duplicateRemoteFileIDFirst)
+	if deleteStub.CapturedHeaders == nil {
+		t.Fatal("DELETE for nested duplicate sibling was never issued")
+	}
+
+	reg.Verify(t)
+}
+
+func TestChooseRemoteFileSortsByParsedTimes(t *testing.T) {
+	files := []driveRemoteEntry{
+		{FileToken: "token_b", CreatedTime: "9", ModifiedTime: "9"},
+		{FileToken: "token_a", CreatedTime: "10", ModifiedTime: "10"},
+	}
+	gotNewest, err := chooseRemoteFile(files, driveDuplicateRemoteNewest)
+	if err != nil {
+		t.Fatalf("chooseRemoteFile newest: %v", err)
+	}
+	if gotNewest.FileToken != "token_a" {
+		t.Fatalf("newest token = %q, want token_a", gotNewest.FileToken)
+	}
+	gotOldest, err := chooseRemoteFile(files, driveDuplicateRemoteOldest)
+	if err != nil {
+		t.Fatalf("chooseRemoteFile oldest: %v", err)
+	}
+	if gotOldest.FileToken != "token_b" {
+		t.Fatalf("oldest token = %q, want token_b", gotOldest.FileToken)
+	}
+}
+
+// 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"},
+		{FileToken: "token_b", CreatedTime: "10", ModifiedTime: "10"},
+	}
+	got, err := chooseRemoteFile(files, driveDuplicateRemoteNewest)
+	if err != nil {
+		t.Fatalf("chooseRemoteFile: %v", err)
+	}
+	if got.FileToken != "token_a" {
+		t.Fatalf("fallback token = %q, want token_a", got.FileToken)
+	}
+}
+
+func TestChooseRemoteFileRejectsEmptyCandidates(t *testing.T) {
+	_, err := chooseRemoteFile(nil, driveDuplicateRemoteNewest)
+	if err == nil {
+		t.Fatal("expected chooseRemoteFile to reject empty candidates")
+	}
+}
+
+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},
+		{RelPath: "dup.txt", Type: driveTypeFile, FileToken: duplicateRemoteFileIDSecond},
+	}, "mystery")
+	if err == nil {
+		t.Fatal("expected drivePullRemoteViews to reject an unknown duplicate strategy")
+	}
+}
+
+func registerDuplicateRemoteFiles(reg *httpmock.Registry) {
+	registerRemoteListing(reg, "folder_root", []map[string]interface{}{
+		{"token": duplicateRemoteFileIDFirst, "name": "dup.txt", "type": "file", "size": 5, "created_time": "1", "modified_time": "1"},
+		{"token": duplicateRemoteFileIDSecond, "name": "dup.txt", "type": "file", "size": 6, "created_time": "2", "modified_time": "2"},
+	})
+}
+
+func registerRemoteListing(reg *httpmock.Registry, folderToken string, files []map[string]interface{}) {
+	items := make([]interface{}, 0, len(files))
+	for _, file := range files {
+		items = append(items, file)
+	}
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=" + folderToken,
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"files":    items,
+				"has_more": false,
+			},
+		},
+	})
+}
+
+func registerDownload(reg *httpmock.Registry, fileToken, body string) {
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/files/" + fileToken + "/download",
+		Status:  200,
+		Body:    []byte(body),
+		Headers: http.Header{"Content-Type": []string{"application/octet-stream"}},
+	})
+}
+
+func assertDuplicateRemotePathError(t *testing.T, err error, relPath string, tokens ...string) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected duplicate_remote_path error, got nil")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitAPI {
+		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAPI)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "duplicate_remote_path" {
+		t.Fatalf("error detail = %#v, want duplicate_remote_path", exitErr.Detail)
+	}
+	detailMap, ok := exitErr.Detail.Detail.(map[string]interface{})
+	if !ok {
+		t.Fatalf("duplicate detail type = %T, want map[string]interface{}", exitErr.Detail.Detail)
+	}
+	duplicates, ok := detailMap["duplicates_remote"].([]driveDuplicateRemotePath)
+	if !ok {
+		t.Fatalf("duplicate detail duplicates_remote type = %T, want []driveDuplicateRemotePath", detailMap["duplicates_remote"])
+	}
+	if len(duplicates) == 0 {
+		t.Fatal("duplicate detail should include at least one rel_path group")
+	}
+	if _, hasLegacyFilesKey := detailMap["files"]; hasLegacyFilesKey {
+		t.Fatalf("duplicate detail should not expose legacy files key: %#v", detailMap)
+	}
+	var matched bool
+	for _, duplicate := range duplicates {
+		if duplicate.RelPath != relPath {
+			continue
+		}
+		matched = true
+		if len(duplicate.Entries) != len(tokens) {
+			t.Fatalf("duplicate entry count = %d, want %d for rel_path %q", len(duplicate.Entries), len(tokens), relPath)
+		}
+		for i, token := range tokens {
+			if duplicate.Entries[i].FileToken != token {
+				t.Fatalf("duplicate entry %d file_token = %q, want %q", i, duplicate.Entries[i].FileToken, token)
+			}
+			if duplicate.Entries[i].Type == "" {
+				t.Fatalf("duplicate entry %d missing type for rel_path %q", i, relPath)
+			}
+		}
+	}
+	if !matched {
+		t.Fatalf("duplicate detail missing rel_path group %q: %#v", relPath, duplicates)
+	}
+	raw, marshalErr := json.Marshal(exitErr.Detail.Detail)
+	if marshalErr != nil {
+		t.Fatalf("marshal detail: %v", marshalErr)
+	}
+	text := string(raw)
+	if !strings.Contains(text, relPath) {
+		t.Fatalf("duplicate detail missing rel_path %q: %s", relPath, text)
+	}
+	for _, token := range tokens {
+		if !strings.Contains(text, token) {
+			t.Fatalf("duplicate detail missing token %q: %s", token, text)
+		}
+	}
+}
+
+type drivePullStdoutPayload struct {
+	Data struct {
+		Summary struct {
+			Downloaded int `json:"downloaded"`
+			Skipped    int `json:"skipped"`
+			Failed     int `json:"failed"`
+		} `json:"summary"`
+		Items []struct {
+			RelPath   string `json:"rel_path"`
+			FileToken string `json:"file_token,omitempty"`
+			SourceID  string `json:"source_id,omitempty"`
+			Action    string `json:"action"`
+		} `json:"items"`
+	} `json:"data"`
+}
+
+func decodeDrivePullStdout(t *testing.T, raw []byte) drivePullStdoutPayload {
+	t.Helper()
+	var payload drivePullStdoutPayload
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		t.Fatalf("decode pull stdout: %v\n%s", err, string(raw))
+	}
+	return payload
+}
+
+func findPullItem(items []struct {
+	RelPath   string `json:"rel_path"`
+	FileToken string `json:"file_token,omitempty"`
+	SourceID  string `json:"source_id,omitempty"`
+	Action    string `json:"action"`
+}, relPath string) struct {
+	RelPath   string `json:"rel_path"`
+	FileToken string `json:"file_token,omitempty"`
+	SourceID  string `json:"source_id,omitempty"`
+	Action    string `json:"action"`
+} {
+	for _, item := range items {
+		if item.RelPath == relPath {
+			return item
+		}
+	}
+	return struct {
+		RelPath   string `json:"rel_path"`
+		FileToken string `json:"file_token,omitempty"`
+		SourceID  string `json:"source_id,omitempty"`
+		Action    string `json:"action"`
+	}{}
+}
+
+func expectedRenamedRelPath(relPath, fileToken string, hashLen, attempt int) string {
+	sum := sha256.Sum256([]byte(fileToken))
+	hash := hex.EncodeToString(sum[:])
+	suffix := "__lark_" + hash[:hashLen]
+	if attempt > 0 {
+		suffix = "__lark_" + hash + "_" + strconv.Itoa(attempt)
+	}
+	dir, base := path.Split(relPath)
+	ext := path.Ext(base)
+	if ext == base {
+		return dir + base + suffix
+	}
+	stem := base[:len(base)-len(ext)]
+	return dir + stem + suffix + ext
+}
+
+func assertPullItemAction(t *testing.T, raw []byte, relPath, action string) {
+	t.Helper()
+	var payload struct {
+		Data struct {
+			Items []struct {
+				RelPath string `json:"rel_path"`
+				Action  string `json:"action"`
+			} `json:"items"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		t.Fatalf("decode pull stdout: %v\n%s", err, string(raw))
+	}
+	for _, item := range payload.Data.Items {
+		if item.RelPath == relPath && item.Action == action {
+			return
+		}
+	}
+	t.Fatalf("missing pull item %q/%q in stdout: %s", relPath, action, string(raw))
+}
+
+func assertPushItemAction(t *testing.T, raw []byte, relPath, action, fileToken string) {
+	t.Helper()
+	var payload struct {
+		Data struct {
+			Items []struct {
+				RelPath   string `json:"rel_path"`
+				Action    string `json:"action"`
+				FileToken string `json:"file_token"`
+			} `json:"items"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		t.Fatalf("decode push stdout: %v\n%s", err, string(raw))
+	}
+	for _, item := range payload.Data.Items {
+		if item.RelPath == relPath && item.Action == action && item.FileToken == fileToken {
+			return
+		}
+	}
+	t.Fatalf("missing push item %q/%q/%q in stdout: %s", relPath, action, fileToken, string(raw))
+}

shortcuts/drive/drive_io_test.go

@@ -228,6 +228,206 @@ func TestDriveUploadLargeFileToWikiUsesMultipart(t *testing.T) {
 	}
 }
 
+func TestDriveUploadLargeFileOverwriteUsesMultipart(t *testing.T) {
+	uploadTestConfig := &core.CliConfig{
+		AppID: "drive-upload-large-overwrite-test", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	}
+	f, stdout, _, reg := cmdutil.TestFactory(t, uploadTestConfig)
+
+	prepareStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_prepare",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"upload_id":  "test-upload-id",
+				"block_size": float64(common.MaxDriveMediaUploadSinglePartSize),
+				"block_num":  float64(2),
+			},
+		},
+	}
+	reg.Register(prepareStub)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_part",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_part",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_finish",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"file_token": "file_multipart_overwrite_token",
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	fh, err := os.Create("large.bin")
+	if err != nil {
+		t.Fatalf("Create() error: %v", err)
+	}
+	if err := fh.Truncate(common.MaxDriveMediaUploadSinglePartSize + 1); err != nil {
+		t.Fatalf("Truncate() error: %v", err)
+	}
+	if err := fh.Close(); err != nil {
+		t.Fatalf("Close() error: %v", err)
+	}
+
+	err = mountAndRunDrive(t, DriveUpload, []string{
+		"+upload",
+		"--file", "large.bin",
+		"--file-token", "box_existing_large_upload",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("expected multipart overwrite upload to succeed, got error: %v", err)
+	}
+
+	body := decodeCapturedJSONBody(t, prepareStub)
+	if got := body["file_token"]; got != "box_existing_large_upload" {
+		t.Fatalf("file_token = %#v, want %q", got, "box_existing_large_upload")
+	}
+}
+
+func TestDriveUploadLargeFileOverwriteReturnsVersionFromUploadFinish(t *testing.T) {
+	uploadTestConfig := &core.CliConfig{
+		AppID: "drive-upload-large-overwrite-version-test", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	}
+	f, stdout, _, reg := cmdutil.TestFactory(t, uploadTestConfig)
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_prepare",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"upload_id":  "test-upload-id",
+				"block_size": float64(common.MaxDriveMediaUploadSinglePartSize),
+				"block_num":  float64(1),
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_part",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_finish",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"file_token": "file_multipart_overwrite_version_token",
+				"version":    "v44",
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	fh, err := os.Create("large.bin")
+	if err != nil {
+		t.Fatalf("Create() error: %v", err)
+	}
+	if err := fh.Truncate(common.MaxDriveMediaUploadSinglePartSize + 1); err != nil {
+		t.Fatalf("Truncate() error: %v", err)
+	}
+	if err := fh.Close(); err != nil {
+		t.Fatalf("Close() error: %v", err)
+	}
+
+	err = mountAndRunDrive(t, DriveUpload, []string{
+		"+upload",
+		"--file", "large.bin",
+		"--file-token", "box_existing_large_upload",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("expected multipart overwrite upload to succeed, got error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if got := data["version"]; got != "v44" {
+		t.Fatalf("data.version = %#v, want %q", got, "v44")
+	}
+}
+
+func TestDriveUploadLargeFileOverwriteReturnsVersionFromUploadFinishAlias(t *testing.T) {
+	uploadTestConfig := &core.CliConfig{
+		AppID: "drive-upload-large-overwrite-data-version-test", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	}
+	f, stdout, _, reg := cmdutil.TestFactory(t, uploadTestConfig)
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_prepare",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"upload_id":  "test-upload-id",
+				"block_size": float64(common.MaxDriveMediaUploadSinglePartSize),
+				"block_num":  float64(1),
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_part",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_finish",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"file_token":   "file_multipart_overwrite_alias_token",
+				"data_version": "v45",
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	fh, err := os.Create("large.bin")
+	if err != nil {
+		t.Fatalf("Create() error: %v", err)
+	}
+	if err := fh.Truncate(common.MaxDriveMediaUploadSinglePartSize + 1); err != nil {
+		t.Fatalf("Truncate() error: %v", err)
+	}
+	if err := fh.Close(); err != nil {
+		t.Fatalf("Close() error: %v", err)
+	}
+
+	err = mountAndRunDrive(t, DriveUpload, []string{
+		"+upload",
+		"--file", "large.bin",
+		"--file-token", "box_existing_large_upload",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("expected multipart overwrite upload to succeed, got error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if got := data["version"]; got != "v45" {
+		t.Fatalf("data.version = %#v, want %q", got, "v45")
+	}
+}
+
 func TestDriveUploadSmallFile(t *testing.T) {
 	uploadTestConfig := &core.CliConfig{
 		AppID: "drive-upload-small-test", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -267,6 +467,93 @@ func TestDriveUploadSmallFile(t *testing.T) {
 	}
 }
 
+func TestDriveUploadSmallFileOverwriteUsesFileToken(t *testing.T) {
+	uploadTestConfig := &core.CliConfig{
+		AppID: "drive-upload-small-overwrite-test", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	}
+	f, stdout, _, reg := cmdutil.TestFactory(t, uploadTestConfig)
+
+	stub := &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": "file_small_overwrite_token",
+				"version":    "v42",
+			},
+		},
+	}
+	reg.Register(stub)
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	if err := os.WriteFile("small.bin", make([]byte, 1024), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	err := mountAndRunDrive(t, DriveUpload, []string{
+		"+upload",
+		"--file", "small.bin",
+		"--file-token", "box_existing_small_upload",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("expected small overwrite upload to succeed, got error: %v", err)
+	}
+
+	body := decodeDriveMultipartBody(t, stub)
+	if got := body.Fields["file_token"]; got != "box_existing_small_upload" {
+		t.Fatalf("file_token = %q, want %q", got, "box_existing_small_upload")
+	}
+	data := decodeDriveEnvelope(t, stdout)
+	if got := data["version"]; got != "v42" {
+		t.Fatalf("data.version = %#v, want %q", got, "v42")
+	}
+}
+
+func TestDriveUploadReturnsVersionFromDataVersionAlias(t *testing.T) {
+	uploadTestConfig := &core.CliConfig{
+		AppID: "drive-upload-small-data-version-test", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	}
+	f, stdout, _, reg := cmdutil.TestFactory(t, uploadTestConfig)
+
+	reg.Register(&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":   "file_small_alias_token",
+				"data_version": "v43",
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+
+	if err := os.WriteFile("small.bin", make([]byte, 1024), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	err := mountAndRunDrive(t, DriveUpload, []string{
+		"+upload",
+		"--file", "small.bin",
+		"--file-token", "box_existing_alias_upload",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("expected overwrite upload to succeed, got error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if got := data["version"]; got != "v43" {
+		t.Fatalf("data.version = %#v, want %q", got, "v43")
+	}
+}
+
 func TestDriveUploadSmallFileToWiki(t *testing.T) {
 	uploadTestConfig := &core.CliConfig{
 		AppID: "drive-upload-small-wiki-test", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -767,6 +1054,7 @@ func TestDriveUploadDryRunUsesWikiTarget(t *testing.T) {
 
 	cmd := &cobra.Command{Use: "drive +upload"}
 	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("file-token", "", "")
 	cmd.Flags().String("folder-token", "", "")
 	cmd.Flags().String("wiki-token", "", "")
 	cmd.Flags().String("name", "", "")
@@ -812,6 +1100,7 @@ func TestNewDriveUploadSpecPreservesPathAndName(t *testing.T) {
 
 	cmd := &cobra.Command{Use: "drive +upload"}
 	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("file-token", "", "")
 	cmd.Flags().String("folder-token", "", "")
 	cmd.Flags().String("wiki-token", "", "")
 	cmd.Flags().String("name", "", "")
@@ -821,6 +1110,9 @@ func TestNewDriveUploadSpecPreservesPathAndName(t *testing.T) {
 	if err := cmd.Flags().Set("folder-token", " fld_upload_target "); err != nil {
 		t.Fatalf("set --folder-token: %v", err)
 	}
+	if err := cmd.Flags().Set("file-token", " box_upload_target "); err != nil {
+		t.Fatalf("set --file-token: %v", err)
+	}
 	if err := cmd.Flags().Set("wiki-token", " wikcn_upload_target "); err != nil {
 		t.Fatalf("set --wiki-token: %v", err)
 	}
@@ -839,11 +1131,108 @@ func TestNewDriveUploadSpecPreservesPathAndName(t *testing.T) {
 	if got.FolderToken != "fld_upload_target" {
 		t.Fatalf("FolderToken = %q, want trimmed token", got.FolderToken)
 	}
+	if got.FileToken != "box_upload_target" {
+		t.Fatalf("FileToken = %q, want trimmed token", got.FileToken)
+	}
 	if got.WikiToken != "wikcn_upload_target" {
 		t.Fatalf("WikiToken = %q, want trimmed token", got.WikiToken)
 	}
 }
 
+func TestDriveUploadDryRunIncludesFileToken(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +upload"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("file-token", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	cmd.Flags().String("wiki-token", "", "")
+	cmd.Flags().String("name", "", "")
+	if err := cmd.Flags().Set("file", "./report.pdf"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("file-token", "boxcn_dryrun_overwrite"); err != nil {
+		t.Fatalf("set --file-token: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContextWithCtx(context.Background(), cmd, nil)
+	dry := DriveUpload.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			Body map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if len(got.API) != 1 {
+		t.Fatalf("expected 1 API call, got %d", len(got.API))
+	}
+	if got.API[0].Body["file_token"] != "boxcn_dryrun_overwrite" {
+		t.Fatalf("file_token = %#v, want %q", got.API[0].Body["file_token"], "boxcn_dryrun_overwrite")
+	}
+}
+
+func TestDriveUploadDryRunBotOverwriteSkipsPermissionGrantHint(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +upload"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("file-token", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	cmd.Flags().String("wiki-token", "", "")
+	cmd.Flags().String("name", "", "")
+	cmd.Flags().String("as", "", "")
+	if err := cmd.Flags().Set("file", "./report.pdf"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("file-token", "boxcn_dryrun_overwrite"); err != nil {
+		t.Fatalf("set --file-token: %v", err)
+	}
+	if err := cmd.Flags().Set("as", "bot"); err != nil {
+		t.Fatalf("set --as: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContextWithCtx(context.Background(), cmd, nil)
+	dry := DriveUpload.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			Desc string                 `json:"desc"`
+			Body map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if len(got.API) != 1 {
+		t.Fatalf("expected 1 API call, got %d", len(got.API))
+	}
+	if got.API[0].Body["file_token"] != "boxcn_dryrun_overwrite" {
+		t.Fatalf("file_token = %#v, want %q", got.API[0].Body["file_token"], "boxcn_dryrun_overwrite")
+	}
+	if strings.Contains(got.API[0].Desc, "grant the current CLI user full_access") {
+		t.Fatalf("dry-run desc should skip permission-grant hint for overwrite, got %q", got.API[0].Desc)
+	}
+}
+
 func TestDriveUploadTargetLabel(t *testing.T) {
 	t.Parallel()
 
@@ -901,6 +1290,7 @@ func TestDriveUploadValidateRejectsConflictingTargets(t *testing.T) {
 
 	cmd := &cobra.Command{Use: "drive +upload"}
 	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("file-token", "", "")
 	cmd.Flags().String("folder-token", "", "")
 	cmd.Flags().String("wiki-token", "", "")
 	cmd.Flags().String("name", "", "")
@@ -923,6 +1313,7 @@ func TestDriveUploadValidateRejectsExplicitEmptyWikiToken(t *testing.T) {
 
 	cmd := &cobra.Command{Use: "drive +upload"}
 	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("file-token", "", "")
 	cmd.Flags().String("folder-token", "", "")
 	cmd.Flags().String("wiki-token", "", "")
 	cmd.Flags().String("name", "", "")
@@ -940,11 +1331,35 @@ func TestDriveUploadValidateRejectsExplicitEmptyWikiToken(t *testing.T) {
 	}
 }
 
+func TestDriveUploadValidateRejectsExplicitEmptyFileToken(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +upload"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("file-token", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	cmd.Flags().String("wiki-token", "", "")
+	cmd.Flags().String("name", "", "")
+	if err := cmd.Flags().Set("file", "report.pdf"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("file-token", "   "); err != nil {
+		t.Fatalf("set --file-token: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContextWithCtx(context.Background(), cmd, nil)
+	err := DriveUpload.Validate(context.Background(), runtime)
+	if err == nil || !strings.Contains(err.Error(), "--file-token cannot be empty") {
+		t.Fatalf("Validate() error = %v, want empty file-token error", err)
+	}
+}
+
 func TestDriveUploadValidateRejectsExplicitEmptyFolderToken(t *testing.T) {
 	t.Parallel()
 
 	cmd := &cobra.Command{Use: "drive +upload"}
 	cmd.Flags().String("file", "", "")
+	cmd.Flags().String("file-token", "", "")
 	cmd.Flags().String("folder-token", "", "")
 	cmd.Flags().String("wiki-token", "", "")
 	cmd.Flags().String("name", "", "")
@@ -983,6 +1398,12 @@ func TestDriveUploadValidateRejectsInvalidTargetTokens(t *testing.T) {
 			value:   "wikcn_bad#fragment",
 			wantErr: "--wiki-token contains invalid characters",
 		},
+		{
+			name:    "file token",
+			flag:    "file-token",
+			value:   "box_bad?query=true",
+			wantErr: "--file-token contains invalid characters",
+		},
 	}
 
 	for _, tt := range tests {
@@ -991,6 +1412,7 @@ func TestDriveUploadValidateRejectsInvalidTargetTokens(t *testing.T) {
 
 			cmd := &cobra.Command{Use: "drive +upload"}
 			cmd.Flags().String("file", "", "")
+			cmd.Flags().String("file-token", "", "")
 			cmd.Flags().String("folder-token", "", "")
 			cmd.Flags().String("wiki-token", "", "")
 			cmd.Flags().String("name", "", "")

shortcuts/drive/drive_permission_grant_test.go

@@ -75,6 +75,48 @@ func TestDriveUploadBotAutoGrantSuccess(t *testing.T) {
 	}
 }
 
+func TestDriveUploadBotOverwriteSkipsPermissionGrant(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, drivePermissionGrantTestConfig(t, "ou_current_user"))
+	registerDriveBotTokenStub(reg)
+
+	reg.Register(&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": "file_uploaded",
+				"version":    "v2",
+			},
+		},
+	})
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.WriteFile("report.pdf", []byte("pdf"), 0o644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	err := mountAndRunDrive(t, DriveUpload, []string{
+		"+upload",
+		"--file", "report.pdf",
+		"--file-token", "file_uploaded",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if _, ok := data["permission_grant"]; ok {
+		t.Fatalf("did not expect permission_grant for overwrite output: %#v", data)
+	}
+	if got := data["version"]; got != "v2" {
+		t.Fatalf("version = %#v, want %q", got, "v2")
+	}
+}
+
 func TestDriveImportBotAutoGrantSuccess(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, drivePermissionGrantTestConfig(t, "ou_current_user"))
 	registerDriveBotTokenStub(reg)

shortcuts/drive/drive_pull.go

@@ -11,6 +11,7 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+	"time"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
@@ -20,18 +21,36 @@ 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"
 )
 
 type drivePullItem struct {
 	RelPath   string `json:"rel_path"`
 	FileToken string `json:"file_token,omitempty"`
+	SourceID  string `json:"source_id,omitempty"`
 	Action    string `json:"action"`
 	Error     string `json:"error,omitempty"`
 }
 
+type drivePullTarget struct {
+	DownloadToken string
+	ItemFileToken string
+	ItemSourceID  string
+	ModifiedTime  string
+}
+
 // DrivePull performs a one-way file-level mirror from a Drive folder onto
 // a local directory: recursively lists --folder-token, downloads each
 // type=file entry under --local-dir, and optionally deletes local files
@@ -53,13 +72,16 @@ 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", Default: drivePullIfExistsOverwrite, Enum: []string{drivePullIfExistsOverwrite, drivePullIfExistsSkip}},
+		{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: "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"},
 	},
 	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.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -102,6 +124,10 @@ var DrivePull = common.Shortcut{
 		if ifExists == "" {
 			ifExists = drivePullIfExistsOverwrite
 		}
+		duplicateRemote := strings.TrimSpace(runtime.Str("on-duplicate-remote"))
+		if duplicateRemote == "" {
+			duplicateRemote = driveDuplicateRemoteFail
+		}
 		deleteLocal := runtime.Bool("delete-local")
 
 		// Resolve --local-dir to its canonical absolute path before we
@@ -132,10 +158,13 @@ var DrivePull = common.Shortcut{
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Listing Drive folder: %s\n", common.MaskToken(folderToken))
-		entries, err := listRemoteFolder(ctx, runtime, folderToken, "")
+		entries, err := listRemoteFolderEntries(ctx, runtime, folderToken, "")
 		if err != nil {
 			return err
 		}
+		if duplicates := blockingRemotePathConflicts(entries, duplicateRemote); len(duplicates) > 0 {
+			return duplicateRemotePathError(duplicates)
+		}
 		// Two views over the same listing:
 		//   - remoteFiles drives the download/skip loop (only type=file
 		//     has hashable bytes the local mirror can write back).
@@ -143,13 +172,9 @@ var DrivePull = common.Shortcut{
 		//     rel_path Drive owns regardless of type, so a local file
 		//     shadowed by a remote folder / online doc / shortcut is NOT
 		//     treated as orphaned.
-		remoteFiles := make(map[string]string, len(entries))
-		remotePaths := make(map[string]struct{}, len(entries))
-		for rel, entry := range entries {
-			remotePaths[rel] = struct{}{}
-			if entry.Type == driveTypeFile {
-				remoteFiles[rel] = entry.FileToken
-			}
+		remoteFiles, remotePaths, err := drivePullRemoteViews(entries, duplicateRemote)
+		if err != nil {
+			return output.Errorf(output.ExitInternal, "internal", "%s", err)
 		}
 
 		var downloaded, skipped, failed, deletedLocal int
@@ -164,7 +189,10 @@ var DrivePull = common.Shortcut{
 		sort.Strings(downloadablePaths)
 
 		for _, rel := range downloadablePaths {
-			token := remoteFiles[rel]
+			targetFile := remoteFiles[rel]
+			downloadToken := targetFile.DownloadToken
+			itemFileToken := targetFile.ItemFileToken
+			itemSourceID := targetFile.ItemSourceID
 			target := filepath.Join(rootRelToCwd, rel)
 
 			if info, statErr := runtime.FileIO().Stat(target); statErr == nil {
@@ -178,7 +206,8 @@ var DrivePull = common.Shortcut{
 				if info.IsDir() {
 					items = append(items, drivePullItem{
 						RelPath:   rel,
-						FileToken: token,
+						FileToken: itemFileToken,
+						SourceID:  itemSourceID,
 						Action:    "failed",
 						Error:     fmt.Sprintf("local path is a directory, remote is a regular file: %s", target),
 					})
@@ -186,20 +215,20 @@ var DrivePull = common.Shortcut{
 					downloadFailed++
 					continue
 				}
-				if ifExists == drivePullIfExistsSkip {
-					items = append(items, drivePullItem{RelPath: rel, FileToken: token, Action: "skipped"})
+				if ifExists == drivePullIfExistsSkip || drivePullShouldSkipSmart(target, targetFile, ifExists, runtime) {
+					items = append(items, drivePullItem{RelPath: rel, FileToken: itemFileToken, SourceID: itemSourceID, Action: "skipped"})
 					skipped++
 					continue
 				}
 			}
 
-			if err := drivePullDownload(ctx, runtime, token, target); err != nil {
-				items = append(items, drivePullItem{RelPath: rel, FileToken: token, Action: "failed", Error: err.Error()})
+			if err := drivePullDownload(ctx, runtime, downloadToken, target, targetFile.ModifiedTime); err != nil {
+				items = append(items, drivePullItem{RelPath: rel, FileToken: itemFileToken, SourceID: itemSourceID, Action: "failed", Error: err.Error()})
 				failed++
 				downloadFailed++
 				continue
 			}
-			items = append(items, drivePullItem{RelPath: rel, FileToken: token, Action: "downloaded"})
+			items = append(items, drivePullItem{RelPath: rel, FileToken: itemFileToken, SourceID: itemSourceID, Action: "downloaded"})
 			downloaded++
 		}
 
@@ -289,7 +318,9 @@ var DrivePull = common.Shortcut{
 	},
 }
 
-func drivePullDownload(ctx context.Context, runtime *common.RuntimeContext, fileToken, target string) error {
+// 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 {
 	resp, err := runtime.DoAPIStream(ctx, &larkcore.ApiReq{
 		HttpMethod: "GET",
 		ApiPath:    fmt.Sprintf("/open-apis/drive/v1/files/%s/download", validate.EncodePathSegment(fileToken)),
@@ -304,9 +335,114 @@ 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))
+	fileGroups := make(map[string][]driveRemoteEntry)
+	occupied := occupiedRemotePaths(entries)
+
+	for _, entry := range entries {
+		if entry.Type == driveTypeFile {
+			fileGroups[entry.RelPath] = append(fileGroups[entry.RelPath], entry)
+			continue
+		}
+		remotePaths[entry.RelPath] = struct{}{}
+	}
+
+	relPaths := make([]string, 0, len(fileGroups))
+	for rel := range fileGroups {
+		relPaths = append(relPaths, rel)
+	}
+	sort.Strings(relPaths)
+
+	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}
+			remotePaths[rel] = struct{}{}
+			continue
+		}
+		switch duplicateRemote {
+		case driveDuplicateRemoteRename:
+			candidates := append([]driveRemoteEntry(nil), files...)
+			sortRemoteFiles(candidates, driveDuplicateRemoteOldest)
+			for idx, file := range candidates {
+				targetRel := rel
+				if idx > 0 {
+					var err error
+					targetRel, err = relPathWithUniqueFileTokenSuffix(rel, file.FileToken, occupied)
+					if err != nil {
+						return nil, nil, err
+					}
+				}
+				remoteFiles[targetRel] = drivePullTarget{
+					DownloadToken: file.FileToken,
+					ItemSourceID:  stableTokenIdentifier(file.FileToken),
+					ModifiedTime:  file.ModifiedTime,
+				}
+				remotePaths[targetRel] = struct{}{}
+			}
+		case driveDuplicateRemoteNewest, driveDuplicateRemoteOldest:
+			chosen, err := chooseRemoteFile(files, duplicateRemote)
+			if err != nil {
+				return nil, nil, err
+			}
+			remoteFiles[rel] = drivePullTarget{DownloadToken: chosen.FileToken, ItemFileToken: chosen.FileToken, ModifiedTime: chosen.ModifiedTime}
+			remotePaths[rel] = struct{}{}
+		default:
+			return nil, nil, fmt.Errorf("unsupported duplicate remote strategy %q", duplicateRemote)
+		}
+	}
+	return remoteFiles, remotePaths, nil
+}
+
 // drivePullWalkLocal walks the canonical absolute root and returns the
 // absolute paths of every regular file underneath it. The caller deletes
 // some of these paths, so it is critical that they are produced by

shortcuts/drive/drive_pull_test.go

@@ -4,17 +4,23 @@
 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
@@ -151,6 +157,322 @@ 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
@@ -293,6 +615,49 @@ func TestDrivePullPaginationHandlesPageTokenField(t *testing.T) {
 	reg.Verify(t)
 }
 
+func TestDrivePullRenameSummarizesDuplicateDownloadsAndAvoidsRawTokenInRelPath(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)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+	registerDownload(reg, duplicateRemoteFileIDFirst, "FIRST")
+	registerDownload(reg, duplicateRemoteFileIDSecond, "SECOND")
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--on-duplicate-remote", "rename",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
+	}
+
+	renamedRelPath := expectedRenamedRelPath("dup.txt", duplicateRemoteFileIDSecond, 12, 0)
+	payload := decodeDrivePullStdout(t, stdout.Bytes())
+	if got := payload.Data.Summary.Downloaded; got != 2 {
+		t.Fatalf("summary.downloaded = %d, want 2", got)
+	}
+	if out := stdout.String(); strings.Contains(out, duplicateRemoteFileIDSecond) {
+		t.Fatalf("stdout should not expose the raw duplicate file token in rename mode, got: %s", out)
+	}
+	if item := findPullItem(payload.Data.Items, renamedRelPath); item.SourceID == "" || item.FileToken != "" {
+		t.Fatalf("rename item should emit source_id without file_token, got: %#v", item)
+	}
+	mustReadFile(t, filepath.Join("local", "dup.txt"), "FIRST")
+	mustReadFile(t, filepath.Join("local", renamedRelPath), "SECOND")
+	assertPullItemAction(t, stdout.Bytes(), "dup.txt", "downloaded")
+	assertPullItemAction(t, stdout.Bytes(), renamedRelPath, "downloaded")
+
+	reg.Verify(t)
+}
+
 // TestDrivePullDeleteLocalRequiresYes verifies the upfront safety guard:
 // --delete-local without --yes must be rejected before any API call.
 func TestDrivePullDeleteLocalRequiresYes(t *testing.T) {

shortcuts/drive/drive_push.go

@@ -15,6 +15,7 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+	"time"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
@@ -25,6 +26,7 @@ import (
 
 const (
 	drivePushIfExistsOverwrite = "overwrite"
+	drivePushIfExistsSmart     = "smart"
 	drivePushIfExistsSkip      = "skip"
 )
 
@@ -91,14 +93,17 @@ 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 (default: skip — safe; opt into overwrite explicitly while the backend version field is rolling out)", Default: drivePushIfExistsSkip, Enum: []string{drivePushIfExistsOverwrite, drivePushIfExistsSkip}},
+		{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: "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"},
 	},
 	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.",
-		"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.",
+		"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.",
 		"--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.",
@@ -149,7 +154,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, overwrite (when --if-exists=overwrite) or skip existing, and (when --delete-remote --yes is set) delete Drive files absent locally.").
+			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.").
 			GET("/open-apis/drive/v1/files").
 			Set("folder_token", runtime.Str("folder-token"))
 	},
@@ -164,6 +169,10 @@ var DrivePush = common.Shortcut{
 			// rolling-out upload_all `file_token`/`version` protocol field.
 			ifExists = drivePushIfExistsSkip
 		}
+		duplicateRemote := strings.TrimSpace(runtime.Str("on-duplicate-remote"))
+		if duplicateRemote == "" {
+			duplicateRemote = driveDuplicateRemoteFail
+		}
 		deleteRemote := runtime.Bool("delete-remote")
 
 		// Resolve --local-dir to its canonical absolute path before walking.
@@ -190,10 +199,13 @@ var DrivePush = common.Shortcut{
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Listing Drive folder: %s\n", common.MaskToken(folderToken))
-		entries, err := listRemoteFolder(ctx, runtime, folderToken, "")
+		entries, err := listRemoteFolderEntries(ctx, runtime, folderToken, "")
 		if err != nil {
 			return err
 		}
+		if duplicates := blockingRemotePathConflicts(entries, duplicateRemote); len(duplicates) > 0 {
+			return duplicateRemotePathError(duplicates)
+		}
 		// Two views over the same listing:
 		//   - remoteFiles drives upload / overwrite / orphan-delete
 		//     decisions (only type=file entries are upload candidates;
@@ -203,15 +215,9 @@ var DrivePush = common.Shortcut{
 		//     path skip create_folder when an intermediate folder already
 		//     exists, and keeps directory recreation idempotent across
 		//     reruns.
-		remoteFiles := make(map[string]driveRemoteEntry, len(entries))
-		remoteFolders := make(map[string]driveRemoteEntry, len(entries))
-		for rel, entry := range entries {
-			switch entry.Type {
-			case driveTypeFile:
-				remoteFiles[rel] = entry
-			case driveTypeFolder:
-				remoteFolders[rel] = entry
-			}
+		remoteFiles, remoteFolders, remoteFileGroups, err := drivePushRemoteViews(entries, duplicateRemote)
+		if err != nil {
+			return output.Errorf(output.ExitInternal, "internal", "%s", err)
 		}
 
 		var uploaded, skipped, failed, deletedRemote int
@@ -264,12 +270,19 @@ var DrivePush = common.Shortcut{
 			localFile := localFiles[rel]
 
 			if entry, ok := remoteFiles[rel]; ok {
-				if ifExists == drivePushIfExistsSkip {
+				if drivePushShouldSkipExisting(localFile, entry, ifExists) {
 					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "skipped", SizeBytes: localFile.Size})
 					skipped++
 					continue
 				}
-				token, version, upErr := drivePushUploadFile(ctx, runtime, localFile, entry.FileToken, folderToken)
+				parentToken, parentErr := drivePushEnsureParentToken(ctx, runtime, folderToken, rel, folderCache)
+				if parentErr != nil {
+					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "failed", SizeBytes: localFile.Size, Error: parentErr.Error()})
+					failed++
+					uploadFailed = true
+					continue
+				}
+				token, version, upErr := drivePushUploadFile(ctx, runtime, localFile, entry.FileToken, parentToken)
 				if upErr != nil {
 					// Token contract on overwrite failure: an in-place
 					// overwrite preserves the file's token, so the
@@ -333,24 +346,31 @@ var DrivePush = common.Shortcut{
 		}
 		if deleteRemote && !uploadFailed {
 			// Stable iteration order so failures (and tests) are deterministic.
-			remoteRelPaths := make([]string, 0, len(remoteFiles))
-			for p := range remoteFiles {
+			remoteRelPaths := make([]string, 0, len(remoteFileGroups))
+			for p := range remoteFileGroups {
 				remoteRelPaths = append(remoteRelPaths, p)
 			}
 			sort.Strings(remoteRelPaths)
 
 			for _, rel := range remoteRelPaths {
+				keepToken := ""
 				if _, ok := localFiles[rel]; ok {
-					continue
+					if chosen, ok := remoteFiles[rel]; ok {
+						keepToken = chosen.FileToken
+					}
 				}
-				entry := remoteFiles[rel]
-				if err := drivePushDeleteFile(ctx, runtime, entry.FileToken); err != nil {
-					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "delete_failed", Error: err.Error()})
-					failed++
-					continue
+				for _, entry := range remoteFileGroups[rel] {
+					if entry.FileToken == keepToken {
+						continue
+					}
+					if err := drivePushDeleteFile(ctx, runtime, entry.FileToken); err != nil {
+						items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "delete_failed", Error: err.Error()})
+						failed++
+						continue
+					}
+					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "deleted_remote"})
+					deletedRemote++
 				}
-				items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "deleted_remote"})
-				deletedRemote++
 			}
 		}
 
@@ -384,6 +404,7 @@ type drivePushLocalFile struct {
 	OpenPath string
 	FileName string
 	Size     int64
+	ModTime  time.Time
 }
 
 // drivePushWalkLocal walks the canonical absolute root produced by
@@ -440,6 +461,7 @@ func drivePushWalkLocal(root, cwdCanonical string) (map[string]drivePushLocalFil
 			OpenPath: relToCwd,
 			FileName: filepath.Base(rel),
 			Size:     info.Size(),
+			ModTime:  info.ModTime(),
 		}
 		return nil
 	})
@@ -463,6 +485,70 @@ 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))
+	fileGroups := make(map[string][]driveRemoteEntry)
+
+	for _, entry := range entries {
+		switch entry.Type {
+		case driveTypeFile:
+			fileGroups[entry.RelPath] = append(fileGroups[entry.RelPath], entry)
+		case driveTypeFolder:
+			remoteFolders[entry.RelPath] = entry
+		}
+	}
+
+	relPaths := make([]string, 0, len(fileGroups))
+	for rel := range fileGroups {
+		relPaths = append(relPaths, rel)
+	}
+	sort.Strings(relPaths)
+
+	for _, rel := range relPaths {
+		files := fileGroups[rel]
+		if len(files) == 1 {
+			remoteFiles[rel] = files[0]
+			continue
+		}
+		switch duplicateRemote {
+		case driveDuplicateRemoteNewest, driveDuplicateRemoteOldest:
+			chosen, err := chooseRemoteFile(files, duplicateRemote)
+			if err != nil {
+				return nil, nil, nil, err
+			}
+			remoteFiles[rel] = chosen
+		default:
+			return nil, nil, nil, fmt.Errorf("unsupported duplicate remote strategy %q", duplicateRemote)
+		}
+	}
+	return remoteFiles, remoteFolders, fileGroups, nil
+}
+
 // drivePushEnsureFolder ensures a folder chain (rel_dir relative to the root
 // folder identified by rootFolderToken) exists on Drive, creating any
 // missing segments via /open-apis/drive/v1/files/create_folder. Returns the
@@ -501,6 +587,10 @@ func drivePushEnsureFolder(ctx context.Context, runtime *common.RuntimeContext,
 	return token, nil
 }
 
+func drivePushEnsureParentToken(ctx context.Context, runtime *common.RuntimeContext, rootFolderToken, relPath string, folderCache map[string]string) (string, error) {
+	return drivePushEnsureFolder(ctx, runtime, rootFolderToken, drivePushParentRel(relPath), folderCache)
+}
+
 // drivePushUploadFile uploads (or overwrites) a single local file. When
 // existingToken is non-empty, the request adds the file_token form field to
 // trigger overwrite-with-version semantics on the backend; the response is

shortcuts/drive/drive_push_test.go

@@ -12,6 +12,7 @@ import (
 	"strings"
 	"sync/atomic"
 	"testing"
+	"time"
 
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -324,6 +325,203 @@ 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.
@@ -454,6 +652,124 @@ func TestDrivePushDeleteRemoteSkipsOnlineDocs(t *testing.T) {
 	}
 }
 
+func TestDrivePushNewestOverwritesChosenDuplicateAndDeletesSibling(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("LOCAL"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+	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":    "v99",
+			},
+		},
+	}
+	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)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, `"uploaded": 1`) {
+		t.Fatalf("expected uploaded=1, got: %s", out)
+	}
+	if !strings.Contains(out, `"deleted_remote": 1`) {
+		t.Fatalf("expected deleted_remote=1, got: %s", out)
+	}
+	assertPushItemAction(t, stdout.Bytes(), "dup.txt", "deleted_remote", duplicateRemoteFileIDFirst)
+	if deleteStub.CapturedHeaders == nil {
+		t.Fatal("DELETE for the unchosen duplicate sibling was never issued")
+	}
+
+	reg.Verify(t)
+}
+
+func TestDrivePushDeleteRemoteDeletesEntireDuplicateGroupWithoutLocalCounterpart(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)
+	}
+
+	registerDuplicateRemoteFiles(reg)
+	deleteFirst := &httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/drive/v1/files/" + duplicateRemoteFileIDFirst,
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	}
+	deleteSecond := &httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/drive/v1/files/" + duplicateRemoteFileIDSecond,
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	}
+	reg.Register(deleteFirst)
+	reg.Register(deleteSecond)
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--if-exists", "skip",
+		"--on-duplicate-remote", "newest",
+		"--delete-remote",
+		"--yes",
+		"--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": 0`) {
+		t.Fatalf("expected uploaded=0, got: %s", out)
+	}
+	if !strings.Contains(out, `"deleted_remote": 2`) {
+		t.Fatalf("expected deleted_remote=2, got: %s", out)
+	}
+	assertPushItemAction(t, stdout.Bytes(), "dup.txt", "deleted_remote", duplicateRemoteFileIDFirst)
+	assertPushItemAction(t, stdout.Bytes(), "dup.txt", "deleted_remote", duplicateRemoteFileIDSecond)
+	if deleteFirst.CapturedHeaders == nil || deleteSecond.CapturedHeaders == nil {
+		t.Fatal("expected both duplicate remote DELETE requests to be issued")
+	}
+
+	reg.Verify(t)
+}
+
 // TestDrivePushRejectsAbsoluteLocalDir confirms SafeLocalFlagPath surfaces
 // the proper flag name in the error message.
 func TestDrivePushRejectsAbsoluteLocalDir(t *testing.T) {
@@ -980,6 +1296,130 @@ func TestDrivePushReusesExistingRemoteFolder(t *testing.T) {
 	}
 }
 
+// TestDrivePushOverwriteNestedFileUsesParentFolderToken verifies that
+// overwriting an existing nested remote file keeps parent_node aligned with
+// the file's actual parent folder instead of the root folder token.
+func TestDrivePushOverwriteNestedFileUsesParentFolderToken(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll(filepath.Join("local", "sub"), 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join("local", "sub", "keep.txt"), []byte("local"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %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": "fld_existing_sub", "name": "sub", "type": "folder"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=fld_existing_sub",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"files": []interface{}{
+					map[string]interface{}{"token": "tok_keep_nested", "name": "keep.txt", "type": "file"},
+				},
+				"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_nested",
+				"version":    "v2",
+			},
+		},
+	}
+	reg.Register(uploadStub)
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--if-exists", "overwrite",
+		"--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 != "tok_keep_nested" {
+		t.Fatalf("upload_all file_token = %q, want tok_keep_nested", got)
+	}
+	if got := body.Fields["parent_node"]; got != "fld_existing_sub" {
+		t.Fatalf("upload_all parent_node = %q, want fld_existing_sub", got)
+	}
+}
+
+func TestDrivePushOverwriteNestedFileReportsParentEnsureFailure(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll(filepath.Join("local", "sub"), 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join("local", "sub", "keep.txt"), []byte("local"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %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_nested", "name": "sub/keep.txt", "type": "file"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/create_folder",
+		Body: map[string]interface{}{
+			"code": 9999,
+			"msg":  "create parent failed",
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--if-exists", "overwrite",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected parent ensure failure\nstdout: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"action": "failed"`) || !strings.Contains(stdout.String(), "create parent failed") {
+		t.Fatalf("expected failed item with create_folder error, got: %s", stdout.String())
+	}
+}
+
 // TestDrivePushMirrorsEmptyDirectories confirms the gap codex review
 // flagged: a local directory with no files inside must still surface on
 // Drive as a created sub-folder, not be silently dropped because the

shortcuts/drive/drive_status.go

@@ -13,6 +13,7 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+	"time"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
@@ -26,8 +27,24 @@ 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) by SHA-256 hash.
+// four buckets (new_local, new_remote, modified, unchanged) either by exact
+// SHA-256 hash (default) or by a quick modified_time comparison (--quick).
 //
 // Only Drive entries with type=file are compared; online docs (docx, sheet,
 // bitable, mindnote, slides) and shortcuts are skipped because there is no
@@ -37,19 +54,22 @@ type driveStatusEntry struct {
 // path that resolves outside cwd, which keeps the local side bounded to the
 // caller's working directory.
 var DriveStatus = common.Shortcut{
-	Service:     "drive",
-	Command:     "+status",
-	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"},
+	Service:           "drive",
+	Command:           "+status",
+	Description:       "Compare a local directory with a Drive folder by exact hash or quick modified_time",
+	Risk:              "read",
+	Scopes:            []string{"drive:drive.metadata:readonly"},
+	ConditionalScopes: []string{"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.",
-		"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.",
+		"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.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		localDir := strings.TrimSpace(runtime.Str("local-dir"))
@@ -77,17 +97,37 @@ var DriveStatus = common.Shortcut{
 		if !info.IsDir() {
 			return output.ErrValidation("--local-dir is not a directory: %s", localDir)
 		}
+		// Conditional scope pre-check: quick mode only compares local mtime with
+		// Drive modified_time, so it must not be blocked on the download grant.
+		// Exact mode hashes remote bytes, which requires drive:file:download. Do
+		// the stricter check here once we know which execution path the flags
+		// selected. EnsureScopes is a silent no-op when scope metadata is
+		// unavailable, so environments without token scope introspection still
+		// proceed and rely on the API-level missing_scope error if needed.
+		if !runtime.Bool("quick") {
+			if err := runtime.EnsureScopes([]string{"drive:file:download"}); err != nil {
+				return err
+			}
+		}
 		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("Walk --local-dir, recursively list --folder-token, and download files present on both sides to compare SHA-256.").
+			Desc(desc).
 			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,
@@ -112,45 +152,60 @@ var DriveStatus = common.Shortcut{
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Walking local: %s\n", localDir)
-		localHashes, err := walkLocalForStatus(runtime, safeRoot, cwdCanonical)
+		localFiles, err := walkLocalForStatus(safeRoot, cwdCanonical)
 		if err != nil {
 			return err
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Listing Drive folder: %s\n", common.MaskToken(folderToken))
-		entries, err := listRemoteFolder(ctx, runtime, folderToken, "")
+		entries, err := listRemoteFolderEntries(ctx, runtime, folderToken, "")
 		if err != nil {
 			return err
 		}
+		if duplicates := duplicateRemoteFilePaths(entries); len(duplicates) > 0 {
+			return duplicateRemotePathError(duplicates)
+		}
 		// +status only diffs binary content, so collapse the unified
 		// listing to type=file. Online docs / shortcuts have no
 		// 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]string, len(entries))
-		for rel, entry := range entries {
+		remoteFiles := make(map[string]driveStatusRemoteFile, len(entries))
+		for _, entry := range entries {
 			if entry.Type == driveTypeFile {
-				remoteFiles[rel] = entry.FileToken
+				remoteFiles[entry.RelPath] = driveStatusRemoteFile{FileToken: entry.FileToken, ModifiedTime: entry.ModifiedTime}
 			}
 		}
 
-		paths := mergeStatusPaths(localHashes, remoteFiles)
+		paths := mergeStatusPaths(localFiles, remoteFiles)
 
 		var newLocal, newRemote, modified, unchanged []driveStatusEntry
 		for _, relPath := range paths {
-			localHash, hasLocal := localHashes[relPath]
-			remoteToken, hasRemote := remoteFiles[relPath]
+			localFile, hasLocal := localFiles[relPath]
+			remoteFile, hasRemote := remoteFiles[relPath]
 			switch {
 			case hasLocal && !hasRemote:
 				newLocal = append(newLocal, driveStatusEntry{RelPath: relPath})
 			case !hasLocal && hasRemote:
-				newRemote = append(newRemote, driveStatusEntry{RelPath: relPath, FileToken: remoteToken})
+				newRemote = append(newRemote, driveStatusEntry{RelPath: relPath, FileToken: remoteFile.FileToken})
 			default:
-				remoteHash, err := hashRemoteForStatus(ctx, runtime, remoteToken)
+				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)
 				if err != nil {
 					return err
 				}
-				entry := driveStatusEntry{RelPath: relPath, FileToken: remoteToken}
 				if localHash == remoteHash {
 					unchanged = append(unchanged, entry)
 				} else {
@@ -160,6 +215,7 @@ var DriveStatus = common.Shortcut{
 		}
 
 		runtime.Out(map[string]interface{}{
+			"detection":  detection,
 			"new_local":  emptyIfNil(newLocal),
 			"new_remote": emptyIfNil(newRemote),
 			"modified":   emptyIfNil(modified),
@@ -177,8 +233,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(runtime *common.RuntimeContext, root, cwdCanonical string) (map[string]string, error) {
-	files := make(map[string]string)
+func walkLocalForStatus(root, cwdCanonical string) (map[string]driveStatusLocalFile, error) {
+	files := make(map[string]driveStatusLocalFile)
 	// 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
@@ -199,11 +255,11 @@ func walkLocalForStatus(runtime *common.RuntimeContext, root, cwdCanonical strin
 		if err != nil {
 			return err
 		}
-		sum, err := hashLocalForStatus(runtime, relToCwd)
+		info, err := d.Info()
 		if err != nil {
 			return err
 		}
-		files[filepath.ToSlash(rel)] = sum
+		files[filepath.ToSlash(rel)] = driveStatusLocalFile{PathToCwd: relToCwd, ModTime: info.ModTime()}
 		return nil
 	})
 	if err != nil {
@@ -212,6 +268,11 @@ func walkLocalForStatus(runtime *common.RuntimeContext, root, cwdCanonical strin
 	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 {
@@ -241,7 +302,7 @@ func hashRemoteForStatus(ctx context.Context, runtime *common.RuntimeContext, fi
 	return hex.EncodeToString(h.Sum(nil)), nil
 }
 
-func mergeStatusPaths(local, remote map[string]string) []string {
+func mergeStatusPaths(local map[string]driveStatusLocalFile, remote map[string]driveStatusRemoteFile) []string {
 	seen := make(map[string]struct{}, len(local)+len(remote))
 	for p := range local {
 		seen[p] = struct{}{}

shortcuts/drive/drive_status_test.go

@@ -4,16 +4,32 @@
 package drive
 
 import (
+	"context"
+	"errors"
 	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 )
 
+// driveStatusScopedTokenResolver returns a token with caller-controlled scopes
+// so tests can deterministically exercise the shortcut scope preflight.
+type driveStatusScopedTokenResolver struct {
+	scopes string
+}
+
+// ResolveToken satisfies credential.TokenProvider for scope-preflight tests.
+func (r *driveStatusScopedTokenResolver) ResolveToken(ctx context.Context, req credential.TokenSpec) (*credential.TokenResult, error) {
+	return &credential.TokenResult{Token: "test-token", Scopes: r.scopes}, nil
+}
+
 // TestDriveStatusCategorizesByHash exercises the four-bucket classification
 // against a real walk of the temp dir and a mocked Drive listing.
 func TestDriveStatusCategorizesByHash(t *testing.T) {
@@ -105,6 +121,9 @@ 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
@@ -134,6 +153,264 @@ 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)
+}
+
+// TestDriveStatusQuickMarksUntrustedTimestampAsModified locks in the
+// conservative fallback for malformed remote modified_time values.
+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)
+}
+
+// TestDriveStatusExactRejectsMissingDownloadScope proves that exact mode keeps
+// requiring drive:file:download even after quick mode made download optional.
+func TestDriveStatusExactRejectsMissingDownloadScope(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+	f.Credential = credential.NewCredentialProvider(nil, nil, &driveStatusScopedTokenResolver{scopes: "drive:drive.metadata:readonly"}, nil)
+
+	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)
+	}
+
+	err := mountAndRunDrive(t, DriveStatus, []string{
+		"+status",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected missing_scope error for exact mode without drive:file:download")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected structured exit error, got %T", err)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "missing_scope" {
+		t.Fatalf("expected missing_scope detail, got %#v", exitErr.Detail)
+	}
+	if !strings.Contains(err.Error(), "missing required scope(s): drive:file:download") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if exitErr.Detail == nil || !strings.Contains(exitErr.Detail.Hint, "auth login --scope") {
+		t.Fatalf("missing scope hint not found in detail: %#v", exitErr.Detail)
+	}
+	if !strings.Contains(err.Error(), "drive:file:download") {
+		t.Fatalf("error should mention drive:file:download: %v", err)
+	}
+}
+
+// TestDriveStatusQuickAcceptsMissingDownloadScope ensures quick mode is not
+// blocked on the exact-mode download scope precheck.
+func TestDriveStatusQuickAcceptsMissingDownloadScope(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	f.Credential = credential.NewCredentialProvider(nil, nil, &driveStatusScopedTokenResolver{scopes: "drive:drive.metadata:readonly"}, nil)
+
+	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("quick mode should not require drive:file:download: %v\nstdout: %s", err, stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"detection": "quick"`) {
+		t.Fatalf("output missing detection=quick\noutput: %s", stdout.String())
+	}
+
+	reg.Verify(t)
+}
+
+// TestDriveStatusShouldTreatAsUnchangedQuick exercises the tiny quick helper
+// directly so Codecov also sees coverage on the helper body itself.
+func TestDriveStatusShouldTreatAsUnchangedQuick(t *testing.T) {
+	t.Run("matching timestamp returns true", func(t *testing.T) {
+		if !driveStatusShouldTreatAsUnchangedQuick("1715594880", time.Unix(1715594880, 500)) {
+			t.Fatal("expected matching second-resolution timestamps to be unchanged")
+		}
+	})
+
+	t.Run("different timestamp returns false", func(t *testing.T) {
+		if driveStatusShouldTreatAsUnchangedQuick("1715594881", time.Unix(1715594880, 0)) {
+			t.Fatal("expected different timestamps to be treated as modified")
+		}
+	})
+
+	t.Run("invalid timestamp returns false", func(t *testing.T) {
+		if driveStatusShouldTreatAsUnchangedQuick("not-a-timestamp", time.Unix(1715594880, 0)) {
+			t.Fatal("expected invalid timestamp to be treated as modified")
+		}
+	})
+}
+
 // 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`
@@ -213,6 +490,37 @@ func TestDriveStatusPaginatesRemoteListing(t *testing.T) {
 	reg.Verify(t)
 }
 
+func TestDriveStatusFailsOnRemoteFileFolderConflict(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)
+	}
+
+	registerRemoteListing(reg, "folder_root", []map[string]interface{}{
+		{"token": duplicateRemoteFileIDFirst, "name": "dup", "type": "file", "size": 5, "created_time": "1", "modified_time": "1"},
+		{"token": duplicateRemoteFolderID, "name": "dup", "type": "folder", "created_time": "2", "modified_time": "2"},
+	})
+	registerRemoteListing(reg, duplicateRemoteFolderID, []map[string]interface{}{
+		{"token": "nested-file-token", "name": "child.txt", "type": "file", "size": 1, "created_time": "3", "modified_time": "3"},
+	})
+
+	err := mountAndRunDrive(t, DriveStatus, []string{
+		"+status",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	assertDuplicateRemotePathError(t, err, "dup", duplicateRemoteFileIDFirst, duplicateRemoteFolderID)
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout should be empty on duplicate_remote_path, got: %s", stdout.String())
+	}
+
+	reg.Verify(t)
+}
+
 func TestDriveStatusRejectsMissingLocalDir(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, driveTestConfig())
 

shortcuts/drive/drive_upload.go

@@ -27,6 +27,7 @@ const (
 
 type driveUploadSpec struct {
 	FilePath    string
+	FileToken   string
 	FolderToken string
 	WikiToken   string
 	Name        string
@@ -37,9 +38,15 @@ type driveUploadTarget struct {
 	ParentNode string
 }
 
+type driveUploadResult struct {
+	FileToken string
+	Version   string
+}
+
 func newDriveUploadSpec(runtime *common.RuntimeContext) driveUploadSpec {
 	return driveUploadSpec{
 		FilePath:    runtime.Str("file"),
+		FileToken:   strings.TrimSpace(runtime.Str("file-token")),
 		FolderToken: strings.TrimSpace(runtime.Str("folder-token")),
 		WikiToken:   strings.TrimSpace(runtime.Str("wiki-token")),
 		Name:        runtime.Str("name"),
@@ -89,6 +96,7 @@ var DriveUpload = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "file", Desc: "local file path (files > 20MB use multipart upload automatically)", Required: true},
+		{Name: "file-token", Desc: "existing file token to overwrite in place"},
 		{Name: "folder-token", Desc: "target folder token (default: root folder; mutually exclusive with --wiki-token)"},
 		{Name: "wiki-token", Desc: "target wiki node token (uploads under that wiki node; mutually exclusive with --folder-token)"},
 		{Name: "name", Desc: "uploaded file name (default: local file name)"},
@@ -96,6 +104,8 @@ var DriveUpload = common.Shortcut{
 	Tips: []string{
 		"Omit both --folder-token and --wiki-token to upload into the caller's Drive root folder.",
 		"Use --wiki-token <wiki_node_token> to upload under a wiki node; the shortcut maps this to parent_type=wiki automatically.",
+		"Pass --file-token <file_token> to overwrite an existing Drive file in place; the shortcut forwards file_token to the upload API.",
+		"In bot mode, automatic full_access (可管理权限) grant only applies to newly uploaded files; overwrite via --file-token does not modify existing file permissions.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateDriveUploadSpec(runtime, newDriveUploadSpec(runtime))
@@ -103,22 +113,28 @@ var DriveUpload = common.Shortcut{
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		spec := newDriveUploadSpec(runtime)
 		target := spec.Target()
+		isOverwrite := spec.FileToken != ""
+		body := map[string]interface{}{
+			"file_name":   spec.FileName(),
+			"parent_type": target.ParentType,
+			"parent_node": target.ParentNode,
+			"file":        "@" + spec.FilePath,
+		}
+		if spec.FileToken != "" {
+			body["file_token"] = spec.FileToken
+		}
 		d := common.NewDryRunAPI().
 			Desc("multipart/form-data upload (files > 20MB use chunked 3-step upload)").
 			POST("/open-apis/drive/v1/files/upload_all").
-			Body(map[string]interface{}{
-				"file_name":   spec.FileName(),
-				"parent_type": target.ParentType,
-				"parent_node": target.ParentNode,
-				"file":        "@" + spec.FilePath,
-			})
-		if runtime.IsBot() {
+			Body(body)
+		if runtime.IsBot() && !isOverwrite {
 			d.Desc("After file upload succeeds in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on the new file.")
 		}
 		return d
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		spec := newDriveUploadSpec(runtime)
+		isOverwrite := spec.FileToken != ""
 		fileName := spec.FileName()
 		target := spec.Target()
 
@@ -130,32 +146,37 @@ var DriveUpload = common.Shortcut{
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Uploading: %s (%s) -> %s\n", fileName, common.FormatSize(fileSize), target.Label())
 
-		var fileToken string
+		var uploadResult driveUploadResult
 		if fileSize > common.MaxDriveMediaUploadSinglePartSize {
 			fmt.Fprintf(runtime.IO().ErrOut, "File exceeds 20MB, using multipart upload\n")
-			fileToken, err = uploadFileMultipart(ctx, runtime, spec.FilePath, fileName, target, fileSize)
+			uploadResult, err = uploadFileMultipart(ctx, runtime, spec.FilePath, fileName, target, fileSize, spec.FileToken)
 		} else {
-			fileToken, err = uploadFileToDrive(ctx, runtime, spec.FilePath, fileName, target, fileSize)
+			uploadResult, err = uploadFileToDrive(ctx, runtime, spec.FilePath, fileName, target, fileSize, spec.FileToken)
 		}
 		if err != nil {
 			return err
 		}
 
 		out := map[string]interface{}{
-			"file_token": fileToken,
+			"file_token": uploadResult.FileToken,
 			"file_name":  fileName,
 			"size":       fileSize,
 		}
+		if uploadResult.Version != "" {
+			out["version"] = uploadResult.Version
+		}
 		// wiki-hosted files have no standalone /file/<token> URL — only the
 		// wiki node URL, which the upload response doesn't carry. Skip the
 		// fallback for parent_type=wiki rather than emit a link that 404s.
 		if target.ParentType == driveUploadParentTypeExplorer {
-			if u := common.BuildResourceURL(runtime.Config.Brand, "file", fileToken); u != "" {
+			if u := common.BuildResourceURL(runtime.Config.Brand, "file", uploadResult.FileToken); u != "" {
 				out["url"] = u
 			}
 		}
-		if grant := common.AutoGrantCurrentUserDrivePermission(runtime, fileToken, "file"); grant != nil {
-			out["permission_grant"] = grant
+		if !isOverwrite {
+			if grant := common.AutoGrantCurrentUserDrivePermission(runtime, uploadResult.FileToken, "file"); grant != nil {
+				out["permission_grant"] = grant
+			}
 		}
 
 		runtime.Out(out, nil)
@@ -164,6 +185,9 @@ var DriveUpload = common.Shortcut{
 }
 
 func validateDriveUploadSpec(runtime *common.RuntimeContext, spec driveUploadSpec) error {
+	if driveUploadFlagExplicitlyEmpty(runtime, "file-token") {
+		return common.FlagErrorf("--file-token cannot be empty; omit --file-token for a new upload or pass an existing file token to overwrite")
+	}
 	if driveUploadFlagExplicitlyEmpty(runtime, "folder-token") {
 		return common.FlagErrorf("--folder-token cannot be empty; omit --folder-token to upload into Drive root folder or pass a folder token")
 	}
@@ -191,6 +215,11 @@ func validateDriveUploadSpec(runtime *common.RuntimeContext, spec driveUploadSpe
 			return output.ErrValidation("%s", err)
 		}
 	}
+	if spec.FileToken != "" {
+		if err := validate.ResourceName(spec.FileToken, "--file-token"); err != nil {
+			return output.ErrValidation("%s", err)
+		}
+	}
 	return nil
 }
 
@@ -200,10 +229,10 @@ func driveUploadFlagExplicitlyEmpty(runtime *common.RuntimeContext, flagName str
 		strings.TrimSpace(runtime.Str(flagName)) == ""
 }
 
-func uploadFileToDrive(ctx context.Context, runtime *common.RuntimeContext, filePath, fileName string, target driveUploadTarget, fileSize int64) (string, error) {
+func uploadFileToDrive(ctx context.Context, runtime *common.RuntimeContext, filePath, fileName string, target driveUploadTarget, fileSize int64, existingFileToken string) (driveUploadResult, error) {
 	f, err := runtime.FileIO().Open(filePath)
 	if err != nil {
-		return "", common.WrapInputStatError(err)
+		return driveUploadResult{}, common.WrapInputStatError(err)
 	}
 	defer f.Close()
 
@@ -213,6 +242,9 @@ func uploadFileToDrive(ctx context.Context, runtime *common.RuntimeContext, file
 	fd.AddField("parent_type", target.ParentType)
 	fd.AddField("parent_node", target.ParentNode)
 	fd.AddField("size", fmt.Sprintf("%d", fileSize))
+	if existingFileToken != "" {
+		fd.AddField("file_token", existingFileToken)
+	}
 	fd.AddFile("file", f)
 
 	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
@@ -223,34 +255,37 @@ func uploadFileToDrive(ctx context.Context, runtime *common.RuntimeContext, file
 	if err != nil {
 		var exitErr *output.ExitError
 		if errors.As(err, &exitErr) {
-			return "", err
+			return driveUploadResult{}, err
 		}
-		return "", output.ErrNetwork("upload failed: %v", err)
+		return driveUploadResult{}, output.ErrNetwork("upload failed: %v", err)
 	}
 
 	var result map[string]interface{}
 	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-		return "", output.Errorf(output.ExitAPI, "api_error", "upload failed: invalid response JSON: %v", err)
+		return driveUploadResult{}, output.Errorf(output.ExitAPI, "api_error", "upload failed: invalid response JSON: %v", err)
 	}
 
 	if larkCode := int(common.GetFloat(result, "code")); larkCode != 0 {
 		msg, _ := result["msg"].(string)
-		return "", output.ErrAPI(larkCode, fmt.Sprintf("upload failed: [%d] %s", larkCode, msg), result["error"])
+		return driveUploadResult{}, output.ErrAPI(larkCode, fmt.Sprintf("upload failed: [%d] %s", larkCode, msg), result["error"])
 	}
 
 	data, _ := result["data"].(map[string]interface{})
-	fileToken, _ := data["file_token"].(string)
+	fileToken := common.GetString(data, "file_token")
 	if fileToken == "" {
-		return "", output.Errorf(output.ExitAPI, "api_error", "upload failed: no file_token returned")
+		return driveUploadResult{}, output.Errorf(output.ExitAPI, "api_error", "upload failed: no file_token returned")
 	}
-	return fileToken, nil
+	return driveUploadResult{
+		FileToken: fileToken,
+		Version:   driveUploadVersionFromData(data),
+	}, nil
 }
 
 // uploadFileMultipart uploads a large file using the three-step multipart API:
 // 1. upload_prepare — get upload_id, block_size, block_num
 // 2. upload_part   — upload each block sequentially
-// 3. upload_finish — finalize and get file_token
-func uploadFileMultipart(_ context.Context, runtime *common.RuntimeContext, filePath, fileName string, target driveUploadTarget, fileSize int64) (string, error) {
+// 3. upload_finish — finalize and get file_token/version
+func uploadFileMultipart(_ context.Context, runtime *common.RuntimeContext, filePath, fileName string, target driveUploadTarget, fileSize int64, existingFileToken string) (driveUploadResult, error) {
 	// Step 1: Prepare
 	prepareBody := map[string]interface{}{
 		"file_name":   fileName,
@@ -258,9 +293,12 @@ func uploadFileMultipart(_ context.Context, runtime *common.RuntimeContext, file
 		"parent_node": target.ParentNode,
 		"size":        fileSize,
 	}
+	if existingFileToken != "" {
+		prepareBody["file_token"] = existingFileToken
+	}
 	prepareResult, err := runtime.CallAPI("POST", "/open-apis/drive/v1/files/upload_prepare", nil, prepareBody)
 	if err != nil {
-		return "", err
+		return driveUploadResult{}, err
 	}
 
 	uploadID := common.GetString(prepareResult, "upload_id")
@@ -270,7 +308,7 @@ func uploadFileMultipart(_ context.Context, runtime *common.RuntimeContext, file
 	blockNum := int(blockNumF)
 
 	if uploadID == "" || blockSize <= 0 || blockNum <= 0 {
-		return "", output.Errorf(output.ExitAPI, "api_error",
+		return driveUploadResult{}, output.Errorf(output.ExitAPI, "api_error",
 			"upload_prepare returned invalid data: upload_id=%q, block_size=%d, block_num=%d",
 			uploadID, blockSize, blockNum)
 	}
@@ -288,7 +326,7 @@ func uploadFileMultipart(_ context.Context, runtime *common.RuntimeContext, file
 
 		partFile, err := runtime.FileIO().Open(filePath)
 		if err != nil {
-			return "", common.WrapInputStatError(err)
+			return driveUploadResult{}, common.WrapInputStatError(err)
 		}
 
 		fd := larkcore.NewFormdata()
@@ -306,18 +344,18 @@ func uploadFileMultipart(_ context.Context, runtime *common.RuntimeContext, file
 		if err != nil {
 			var exitErr *output.ExitError
 			if errors.As(err, &exitErr) {
-				return "", err
+				return driveUploadResult{}, err
 			}
-			return "", output.ErrNetwork("upload part %d/%d failed: %v", seq+1, blockNum, err)
+			return driveUploadResult{}, output.ErrNetwork("upload part %d/%d failed: %v", seq+1, blockNum, err)
 		}
 
 		var partResult map[string]interface{}
 		if err := json.Unmarshal(apiResp.RawBody, &partResult); err != nil {
-			return "", output.Errorf(output.ExitAPI, "api_error", "upload part %d/%d: invalid response JSON: %v", seq+1, blockNum, err)
+			return driveUploadResult{}, output.Errorf(output.ExitAPI, "api_error", "upload part %d/%d: invalid response JSON: %v", seq+1, blockNum, err)
 		}
 		if larkCode := int(common.GetFloat(partResult, "code")); larkCode != 0 {
 			msg, _ := partResult["msg"].(string)
-			return "", output.ErrAPI(larkCode, fmt.Sprintf("upload part %d/%d failed: [%d] %s", seq+1, blockNum, larkCode, msg), partResult["error"])
+			return driveUploadResult{}, output.ErrAPI(larkCode, fmt.Sprintf("upload part %d/%d failed: [%d] %s", seq+1, blockNum, larkCode, msg), partResult["error"])
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "  Block %d/%d uploaded (%s)\n", seq+1, blockNum, common.FormatSize(partSize))
@@ -330,13 +368,24 @@ func uploadFileMultipart(_ context.Context, runtime *common.RuntimeContext, file
 	}
 	finishResult, err := runtime.CallAPI("POST", "/open-apis/drive/v1/files/upload_finish", nil, finishBody)
 	if err != nil {
-		return "", err
+		return driveUploadResult{}, err
 	}
 
 	fileToken := common.GetString(finishResult, "file_token")
 	if fileToken == "" {
-		return "", output.Errorf(output.ExitAPI, "api_error", "upload_finish succeeded but no file_token returned")
+		return driveUploadResult{}, output.Errorf(output.ExitAPI, "api_error", "upload_finish succeeded but no file_token returned")
 	}
 
-	return fileToken, nil
+	return driveUploadResult{
+		FileToken: fileToken,
+		Version:   driveUploadVersionFromData(finishResult),
+	}, nil
+}
+
+func driveUploadVersionFromData(data map[string]interface{}) string {
+	version := common.GetString(data, "version")
+	if version == "" {
+		version = common.GetString(data, "data_version")
+	}
+	return version
 }

shortcuts/drive/list_remote.go

@@ -5,8 +5,15 @@ package drive
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
+	"path"
+	"sort"
+	"strconv"
+	"time"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -14,52 +21,63 @@ const (
 	driveListRemotePageSize = 200
 	driveTypeFile           = "file"
 	driveTypeFolder         = "folder"
+	driveUniqueSuffixMaxSeq = 1024
 )
 
-// driveRemoteEntry is one Drive entry returned by listRemoteFolder. It
+// driveRemoteEntry is one Drive entry returned by listRemoteFolderEntries. It
 // carries enough metadata for every shortcut that consumes the listing
 // to build its own per-shortcut view by filtering on Type.
 type driveRemoteEntry struct {
 	// FileToken is the Drive token for this entry. For type=folder this
 	// is the folder_token; for everything else it is the file_token.
 	FileToken string
+	Name      string
+	Size      int64
 	// Type is the Drive entry kind verbatim from the API:
 	// "file" | "folder" | "docx" | "doc" | "sheet" | "bitable" |
 	// "mindnote" | "slides" | "shortcut" | …
-	Type string
+	Type         string
+	CreatedTime  string
+	ModifiedTime string
 	// RelPath is the entry's path relative to the listing root. Encoded
 	// with "/" separators on every platform so it matches the rel_paths
 	// produced by the shortcuts' local walkers.
 	RelPath string
 }
 
-// listRemoteFolder recursively lists folderToken under relBase and
-// returns one entry per Drive item, keyed by rel_path. Subfolders are
-// descended into and the folder's own entry is also recorded — callers
-// can reason about "this rel_path is occupied by a folder" without
-// re-listing.
+type driveDuplicateRemoteEntry struct {
+	FileToken    string `json:"file_token"`
+	Name         string `json:"name"`
+	Type         string `json:"type"`
+	Size         int64  `json:"size,omitempty"`
+	CreatedTime  string `json:"created_time,omitempty"`
+	ModifiedTime string `json:"modified_time,omitempty"`
+}
+
+type driveDuplicateRemotePath struct {
+	RelPath string                      `json:"rel_path"`
+	Entries []driveDuplicateRemoteEntry `json:"entries"`
+}
+
+// listRemoteFolderEntries recursively lists folderToken under relBase and
+// returns one entry per Drive item. Subfolders are descended into and the
+// folder's own entry is also recorded, allowing callers to detect multiple
+// remote files that map to the same rel_path.
 //
-// This is the shared backbone for the three sync-disk shortcuts. None
-// of them need every field at every call site, so each one filters
-// on Type:
+// The helper deliberately stores every Drive object kind. Online docs and
+// shortcuts are skipped by sync shortcuts later, but preserving their rel_path
+// here prevents destructive mirror modes from treating a local same-named
+// regular file as an orphan when Drive already owns that path.
 //
-//   - +status (drive_status.go) keeps Type=="file" and uses FileToken
-//     to drive content-hash diffs against the local tree.
-//   - +pull (drive_pull.go) keeps Type=="file" + FileToken for the
-//     download set, and the full key set (every rel_path) as the
-//     guard for --delete-local.
-//   - +push (drive_push.go) keeps Type=="file" + FileToken for upload /
-//     overwrite / orphan-delete decisions, and Type=="folder" + FileToken
-//     for the create_folder cache.
-//
-// Pagination uses common.PaginationMeta, which accepts both
-// page_token and next_page_token — the Drive list endpoint has
-// historically returned the latter, but the helper future-proofs
-// against a backend rename.
-func listRemoteFolder(ctx context.Context, runtime *common.RuntimeContext, folderToken, relBase string) (map[string]driveRemoteEntry, error) {
-	out := make(map[string]driveRemoteEntry)
+// Pagination uses common.PaginationMeta, which accepts both page_token and
+// next_page_token.
+func listRemoteFolderEntries(ctx context.Context, runtime *common.RuntimeContext, folderToken, relBase string) ([]driveRemoteEntry, error) {
+	var out []driveRemoteEntry
 	pageToken := ""
 	for {
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
 		params := map[string]interface{}{
 			"folder_token": folderToken,
 			"page_size":    fmt.Sprint(driveListRemotePageSize),
@@ -84,15 +102,24 @@ func listRemoteFolder(ctx context.Context, runtime *common.RuntimeContext, folde
 				continue
 			}
 			rel := joinRelDrive(relBase, fName)
-			out[rel] = driveRemoteEntry{FileToken: fToken, Type: fType, RelPath: rel}
+			out = append(out, driveRemoteEntry{
+				FileToken:    fToken,
+				Name:         fName,
+				Size:         int64(common.GetFloat(f, "size")),
+				Type:         fType,
+				CreatedTime:  common.GetString(f, "created_time"),
+				ModifiedTime: common.GetString(f, "modified_time"),
+				RelPath:      rel,
+			})
 			if fType == driveTypeFolder {
-				sub, err := listRemoteFolder(ctx, runtime, fToken, rel)
+				if err := ctx.Err(); err != nil {
+					return nil, err
+				}
+				sub, err := listRemoteFolderEntries(ctx, runtime, fToken, rel)
 				if err != nil {
 					return nil, err
 				}
-				for k, v := range sub {
-					out[k] = v
-				}
+				out = append(out, sub...)
 			}
 		}
 		hasMore, nextToken := common.PaginationMeta(result)
@@ -104,6 +131,256 @@ func listRemoteFolder(ctx context.Context, runtime *common.RuntimeContext, folde
 	return out, nil
 }
 
+func duplicateRemoteFilePaths(entries []driveRemoteEntry) []driveDuplicateRemotePath {
+	groups := make(map[string][]driveRemoteEntry)
+	for _, entry := range entries {
+		groups[entry.RelPath] = append(groups[entry.RelPath], entry)
+	}
+
+	relPaths := make([]string, 0, len(groups))
+	for relPath, grouped := range groups {
+		if len(grouped) > 1 {
+			relPaths = append(relPaths, relPath)
+		}
+	}
+	sort.Strings(relPaths)
+
+	duplicates := make([]driveDuplicateRemotePath, 0, len(relPaths))
+	for _, relPath := range relPaths {
+		grouped := append([]driveRemoteEntry(nil), groups[relPath]...)
+		sort.SliceStable(grouped, func(i, j int) bool {
+			if grouped[i].Type != grouped[j].Type {
+				return grouped[i].Type < grouped[j].Type
+			}
+			if cmp, ok := compareDriveTimes(grouped[i].CreatedTime, grouped[j].CreatedTime); ok && cmp != 0 {
+				return cmp < 0
+			}
+			if cmp, ok := compareDriveTimes(grouped[i].ModifiedTime, grouped[j].ModifiedTime); ok && cmp != 0 {
+				return cmp < 0
+			}
+			return grouped[i].FileToken < grouped[j].FileToken
+		})
+		dupEntries := make([]driveDuplicateRemoteEntry, 0, len(grouped))
+		for _, entry := range grouped {
+			dupEntries = append(dupEntries, driveDuplicateRemoteEntry{
+				FileToken:    entry.FileToken,
+				Name:         entry.Name,
+				Type:         entry.Type,
+				Size:         entry.Size,
+				CreatedTime:  entry.CreatedTime,
+				ModifiedTime: entry.ModifiedTime,
+			})
+		}
+		duplicates = append(duplicates, driveDuplicateRemotePath{RelPath: relPath, Entries: dupEntries})
+	}
+	return duplicates
+}
+
+func duplicateRemotePathError(duplicates []driveDuplicateRemotePath) *output.ExitError {
+	return &output.ExitError{
+		Code: output.ExitAPI,
+		Detail: &output.ErrDetail{
+			Type:    "duplicate_remote_path",
+			Message: "multiple Drive entries map to the same rel_path",
+			Detail: map[string]interface{}{
+				"duplicates_remote": duplicates,
+			},
+		},
+	}
+}
+
+const (
+	driveDuplicateRemoteFail   = "fail"
+	driveDuplicateRemoteRename = "rename"
+	driveDuplicateRemoteNewest = "newest"
+	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]
+		switch strategy {
+		case driveDuplicateRemoteNewest:
+			if cmp, ok := compareDriveTimes(a.ModifiedTime, b.ModifiedTime); ok && cmp != 0 {
+				return cmp > 0
+			} else if !ok {
+				return a.FileToken < b.FileToken
+			}
+			if cmp, ok := compareDriveTimes(a.CreatedTime, b.CreatedTime); ok && cmp != 0 {
+				return cmp > 0
+			} else if !ok {
+				return a.FileToken < b.FileToken
+			}
+		default:
+			if cmp, ok := compareDriveTimes(a.CreatedTime, b.CreatedTime); ok && cmp != 0 {
+				return cmp < 0
+			} else if !ok {
+				return a.FileToken < b.FileToken
+			}
+			if cmp, ok := compareDriveTimes(a.ModifiedTime, b.ModifiedTime); ok && cmp != 0 {
+				return cmp < 0
+			} else if !ok {
+				return a.FileToken < b.FileToken
+			}
+		}
+		return a.FileToken < b.FileToken
+	})
+}
+
+// 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 {
+		return 0, false
+	}
+	switch {
+	case at.Before(bt):
+		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):
+		return 1, true
+	default:
+		return 0, true
+	}
+}
+
+func chooseRemoteFile(files []driveRemoteEntry, strategy string) (driveRemoteEntry, error) {
+	if len(files) == 0 {
+		return driveRemoteEntry{}, fmt.Errorf("no Drive entries available for strategy %q", strategy)
+	}
+	candidates := append([]driveRemoteEntry(nil), files...)
+	sortRemoteFiles(candidates, strategy)
+	return candidates[0], nil
+}
+
+func isFileOnlyDuplicatePath(duplicate driveDuplicateRemotePath) bool {
+	if len(duplicate.Entries) < 2 {
+		return false
+	}
+	for _, entry := range duplicate.Entries {
+		if entry.Type != driveTypeFile {
+			return false
+		}
+	}
+	return true
+}
+
+func blockingRemotePathConflicts(entries []driveRemoteEntry, duplicateRemote string) []driveDuplicateRemotePath {
+	duplicates := duplicateRemoteFilePaths(entries)
+	if duplicateRemote == driveDuplicateRemoteFail {
+		return duplicates
+	}
+	blocking := make([]driveDuplicateRemotePath, 0, len(duplicates))
+	for _, duplicate := range duplicates {
+		if !isFileOnlyDuplicatePath(duplicate) {
+			blocking = append(blocking, duplicate)
+		}
+	}
+	return blocking
+}
+
+func occupiedRemotePaths(entries []driveRemoteEntry) map[string]struct{} {
+	occupied := make(map[string]struct{}, len(entries))
+	for _, entry := range entries {
+		occupied[entry.RelPath] = struct{}{}
+	}
+	return occupied
+}
+
+func stableTokenHash(fileToken string) string {
+	sum := sha256.Sum256([]byte(fileToken))
+	return hex.EncodeToString(sum[:])
+}
+
+func stableTokenIdentifier(fileToken string) string {
+	hash := stableTokenHash(fileToken)
+	if len(hash) > 12 {
+		hash = hash[:12]
+	}
+	return "hash_" + hash
+}
+
+func relPathWithSuffix(relPath, suffix string) string {
+	dir, base := path.Split(relPath)
+	ext := path.Ext(base)
+	if ext == base {
+		return dir + base + suffix
+	}
+	stem := base[:len(base)-len(ext)]
+	return dir + stem + suffix + ext
+}
+
+func relPathWithUniqueFileTokenSuffix(relPath, fileToken string, occupied map[string]struct{}) (string, error) {
+	tokenHash := stableTokenHash(fileToken)
+	suffixes := []string{
+		"__lark_" + tokenHash[:12],
+		"__lark_" + tokenHash[:24],
+		"__lark_" + tokenHash,
+	}
+	for _, suffix := range suffixes {
+		candidate := relPathWithSuffix(relPath, suffix)
+		if _, exists := occupied[candidate]; !exists {
+			occupied[candidate] = struct{}{}
+			return candidate, nil
+		}
+	}
+	for attempt := 2; attempt <= driveUniqueSuffixMaxSeq; attempt++ {
+		candidate := relPathWithSuffix(relPath, "__lark_"+tokenHash+"_"+strconv.Itoa(attempt))
+		if _, exists := occupied[candidate]; !exists {
+			occupied[candidate] = struct{}{}
+			return candidate, nil
+		}
+	}
+	return "", fmt.Errorf("could not generate a unique rel_path for %q after %d attempts", relPath, driveUniqueSuffixMaxSeq)
+}
+
 // joinRelDrive joins a rel_path base with an entry name using "/".
 // Empty base means the entry sits at the listing root. Mirrors the
 // behavior the per-shortcut helpers used to ship and keeps rel_paths

shortcuts/im/builders_test.go

@@ -15,6 +15,7 @@ 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()
 
@@ -25,6 +26,9 @@ 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()
 
@@ -55,6 +59,9 @@ 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()
 
@@ -86,6 +93,8 @@ 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",
@@ -94,11 +103,13 @@ 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{
@@ -116,6 +127,43 @@ 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 ")
@@ -591,10 +639,12 @@ 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"} {
+		for _, name := range []string{"type", "name", "users", "owner", "chat-mode"} {
 			cmd.Flags().String(name, "", "")
 		}
 		cmd.Flags().Bool("set-bot-manager", false, "")
@@ -604,9 +654,10 @@ 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"`) {
+		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"`) {
 			t.Fatalf("ImChatCreate.DryRun() = %s", got)
 		}
 	})
@@ -623,6 +674,25 @@ func TestShortcutDryRunShapes(t *testing.T) {
 		}
 	})
 
+	t.Run("ImChatSearch dry run still works with --exclude-muted set", func(t *testing.T) {
+		runtime := newTestRuntimeContext(t, map[string]string{
+			"query": "team-alpha",
+		}, map[string]bool{
+			"exclude-muted": true,
+		})
+		got := mustMarshalDryRun(t, ImChatSearch.DryRun(context.Background(), runtime))
+		// Filter is client-side; --exclude-muted must NOT mutate request body or auto-inject search_types.
+		if !strings.Contains(got, `"/open-apis/im/v2/chats/search"`) {
+			t.Fatalf("ImChatSearch.DryRun() missing endpoint: %s", got)
+		}
+		if strings.Contains(got, `"exclude_muted"`) || strings.Contains(got, `"exclude-muted"`) {
+			t.Fatalf("--exclude-muted leaked into request: %s", got)
+		}
+		if strings.Contains(got, `"search_types"`) {
+			t.Fatalf("search_types must not be auto-injected by --exclude-muted: %s", got)
+		}
+	})
+
 	t.Run("ImMessagesSearch dry run uses messages search endpoint", func(t *testing.T) {
 		runtime := newMessagesSearchTestRuntimeContext(t, map[string]string{
 			"query":      "incident",
@@ -758,6 +828,20 @@ func TestShortcutDryRunShapes(t *testing.T) {
 			t.Fatalf("ImChatMessageList.DryRun().Format() = %s, want only_thread_root_messages=true", formatted)
 		}
 	})
+
+	t.Run("ImChatList dry run includes endpoint and params", func(t *testing.T) {
+		runtime := newTestRuntimeContext(t, map[string]string{
+			"user-id-type": "open_id",
+			"sort-type":    "ByCreateTimeAsc",
+		}, nil)
+		got := mustMarshalDryRun(t, ImChatList.DryRun(context.Background(), runtime))
+		if !strings.Contains(got, `"/open-apis/im/v1/chats"`) {
+			t.Fatalf("ImChatList.DryRun() = %s", got)
+		}
+		if !strings.Contains(got, `"sort_type":"ByCreateTimeAsc"`) {
+			t.Fatalf("ImChatList.DryRun() missing sort_type: %s", got)
+		}
+	})
 }
 
 func TestChatMessageListOnlyThreadRootMessagesDryRun(t *testing.T) {
@@ -772,3 +856,26 @@ func TestChatMessageListOnlyThreadRootMessagesDryRun(t *testing.T) {
 		t.Fatalf("ImChatMessageList.DryRun().Format() = %s, want only_thread_root_messages=true", formatted)
 	}
 }
+
+func TestDetectAllNonMemberPreSkip(t *testing.T) {
+	cases := []struct {
+		name        string
+		searchTypes string
+		want        string
+	}{
+		{"empty", "", ""},
+		{"only public_not_joined", "public_not_joined", SkipReasonAllNonMember},
+		{"public_not_joined with whitespace", "  public_not_joined  ", SkipReasonAllNonMember},
+		{"private only", "private", ""},
+		{"mixed includes public_not_joined", "public_not_joined,private", ""},
+		{"all four types", "private,public_joined,external,public_not_joined", ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got := detectAllNonMemberPreSkip(c.searchTypes)
+			if got != c.want {
+				t.Fatalf("detectAllNonMemberPreSkip(%q) = %q, want %q", c.searchTypes, got, c.want)
+			}
+		})
+	}
+}

shortcuts/im/convert_lib/content_convert.go

@@ -4,9 +4,15 @@
 package convertlib
 
 import (
+	"encoding/json"
 	"fmt"
+	"math"
+	"net/url"
+	"reflect"
+	"strconv"
 	"strings"
 
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -148,6 +154,27 @@ func FormatMessageItem(m map[string]interface{}, runtime *common.RuntimeContext,
 		msg["reply_to"] = pid
 	}
 
+	// Preserve API-provided fields (even if this formatter doesn't otherwise use them).
+	if v, ok := m["chat_id"]; ok {
+		msg["chat_id"] = v
+	}
+	if v, ok := m["message_position"]; ok {
+		msg["message_position"] = v
+	}
+	if v, ok := m["thread_message_position"]; ok {
+		msg["thread_message_position"] = v
+	}
+
+	// Prefer API-provided message_app_link when it's a non-empty string; otherwise assemble deterministically.
+	appLink, _ := m["message_app_link"].(string)
+	appLink = strings.TrimSpace(appLink)
+	if appLink == "" && runtime != nil && runtime.Config != nil {
+		appLink = assembleMessageAppLink(m, runtime.Config.Brand)
+	}
+	if appLink != "" {
+		msg["message_app_link"] = appLink
+	}
+
 	if len(mentions) > 0 {
 		simplified := make([]map[string]interface{}, 0, len(mentions))
 		for _, raw := range mentions {
@@ -166,6 +193,150 @@ func FormatMessageItem(m map[string]interface{}, runtime *common.RuntimeContext,
 	return msg
 }
 
+func assembleMessageAppLink(m map[string]interface{}, brand core.LarkBrand) string {
+	domain := resolveAppLinkDomain(brand)
+	if domain == "" {
+		return ""
+	}
+
+	chatID, _ := m["chat_id"].(string)
+	threadID, _ := m["thread_id"].(string)
+	msgPos, okMsgPos := normalizeMessagePosition(m["message_position"])
+	threadPos, okThreadPos := normalizeMessagePosition(m["thread_message_position"])
+
+	// Thread app link requires both thread_id and chat_id.
+	// Emit both underscore-less (openthreadid/openchatid) and snake_case (open_thread_id/open_chat_id)
+	// query keys so PC and mobile clients can both resolve the link.
+	if threadID != "" && chatID != "" && okThreadPos {
+		u := &url.URL{Scheme: "https", Host: domain, Path: "/client/thread/open"}
+		q := url.Values{}
+		q.Set("openthreadid", threadID)
+		q.Set("openchatid", chatID)
+		q.Set("open_thread_id", threadID)
+		q.Set("open_chat_id", chatID)
+		q.Set("thread_position", threadPos)
+		u.RawQuery = q.Encode()
+		return u.String()
+	}
+	if chatID != "" && okMsgPos {
+		u := &url.URL{Scheme: "https", Host: domain, Path: "/client/chat/open"}
+		q := url.Values{}
+		q.Set("openChatId", chatID)
+		q.Set("position", msgPos)
+		u.RawQuery = q.Encode()
+		return u.String()
+	}
+	return ""
+}
+
+func normalizeMessagePosition(v interface{}) (string, bool) {
+	if v == nil {
+		return "", false
+	}
+	switch vv := v.(type) {
+	case float32:
+		f := float64(vv)
+		if math.IsNaN(f) || math.IsInf(f, 0) {
+			return "", false
+		}
+		if math.Trunc(f) == f {
+			return strconv.FormatInt(int64(f), 10), true
+		}
+		return strconv.FormatFloat(f, 'f', -1, 64), true
+	case float64:
+		if math.IsNaN(vv) || math.IsInf(vv, 0) {
+			return "", false
+		}
+		if math.Trunc(vv) == vv {
+			return strconv.FormatInt(int64(vv), 10), true
+		}
+		return strconv.FormatFloat(vv, 'f', -1, 64), true
+	case int:
+		return strconv.Itoa(vv), true
+	case int8:
+		return strconv.FormatInt(int64(vv), 10), true
+	case int16:
+		return strconv.FormatInt(int64(vv), 10), true
+	case int32:
+		return strconv.FormatInt(int64(vv), 10), true
+	case int64:
+		return strconv.FormatInt(vv, 10), true
+	case uint:
+		return strconv.FormatUint(uint64(vv), 10), true
+	case uint8:
+		return strconv.FormatUint(uint64(vv), 10), true
+	case uint16:
+		return strconv.FormatUint(uint64(vv), 10), true
+	case uint32:
+		return strconv.FormatUint(uint64(vv), 10), true
+	case uint64:
+		return strconv.FormatUint(vv, 10), true
+	case uintptr:
+		return strconv.FormatUint(uint64(vv), 10), true
+	case json.Number:
+		s := strings.TrimSpace(vv.String())
+		if s == "" {
+			return "", false
+		}
+		f, err := strconv.ParseFloat(s, 64)
+		if err != nil || math.IsNaN(f) || math.IsInf(f, 0) {
+			return "", false
+		}
+		if math.Trunc(f) == f {
+			return strconv.FormatInt(int64(f), 10), true
+		}
+		return strconv.FormatFloat(f, 'f', -1, 64), true
+	case string:
+		s := strings.TrimSpace(vv)
+		if s == "" {
+			return "", false
+		}
+		f, err := strconv.ParseFloat(s, 64)
+		if err != nil || math.IsNaN(f) || math.IsInf(f, 0) {
+			return "", false
+		}
+		if math.Trunc(f) == f {
+			return strconv.FormatInt(int64(f), 10), true
+		}
+		return strconv.FormatFloat(f, 'f', -1, 64), true
+	default:
+		// Fallback for typed numeric values (e.g. int32/uint64 via struct -> interface{}), pointers, etc.
+		rv := reflect.ValueOf(v)
+		for rv.Kind() == reflect.Ptr {
+			if rv.IsNil() {
+				return "", false
+			}
+			rv = rv.Elem()
+		}
+		switch rv.Kind() {
+		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+			return strconv.FormatInt(rv.Int(), 10), true
+		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+			return strconv.FormatUint(rv.Uint(), 10), true
+		case reflect.Float32, reflect.Float64:
+			f := rv.Float()
+			if math.IsNaN(f) || math.IsInf(f, 0) {
+				return "", false
+			}
+			if math.Trunc(f) == f {
+				return strconv.FormatInt(int64(f), 10), true
+			}
+			return strconv.FormatFloat(f, 'f', -1, 64), true
+		default:
+			return "", false
+		}
+	}
+}
+
+func resolveAppLinkDomain(brand core.LarkBrand) string {
+	appLink := core.ResolveEndpoints(brand).AppLink
+	u, err := url.Parse(appLink)
+	if err != nil {
+		return ""
+	}
+	return u.Host
+}
+
 // extractMentionOpenId extracts open_id from mention id (string or {"open_id":...} object).
 func extractMentionOpenId(id interface{}) string {
 	if s, ok := id.(string); ok {

shortcuts/im/convert_lib/content_media_misc_test.go

@@ -4,11 +4,44 @@
 package convertlib
 
 import (
+	"encoding/json"
+	"math"
+	"net/url"
 	"testing"
 
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+func mustParseURL(t *testing.T, raw string) *url.URL {
+	t.Helper()
+	u, err := url.Parse(raw)
+	if err != nil {
+		t.Fatalf("url.Parse(%q) error: %v", raw, err)
+	}
+	return u
+}
+
+func assertURLHasQuery(t *testing.T, raw, host, path string, want map[string]string) {
+	t.Helper()
+	u := mustParseURL(t, raw)
+	if u.Scheme != "https" {
+		t.Fatalf("url scheme = %q, want https (%q)", u.Scheme, raw)
+	}
+	if u.Host != host {
+		t.Fatalf("url host = %q, want %q (%q)", u.Host, host, raw)
+	}
+	if u.Path != path {
+		t.Fatalf("url path = %q, want %q (%q)", u.Path, path, raw)
+	}
+	q := u.Query()
+	for k, v := range want {
+		if got := q.Get(k); got != v {
+			t.Fatalf("query[%q] = %q, want %q (%q)", k, got, v, raw)
+		}
+	}
+}
+
 func TestConvertBodyContent(t *testing.T) {
 	ctx := &ConvertContext{RawContent: `{"text":"hello"}`}
 
@@ -62,6 +95,300 @@ func TestFormatMessageItem(t *testing.T) {
 	}
 }
 
+func TestResolveAppLinkDomain(t *testing.T) {
+	if got := resolveAppLinkDomain(core.BrandFeishu); got != "applink.feishu.cn" {
+		t.Fatalf("resolveAppLinkDomain(feishu) = %q", got)
+	}
+	if got := resolveAppLinkDomain(core.BrandLark); got != "applink.larksuite.com" {
+		t.Fatalf("resolveAppLinkDomain(lark) = %q", got)
+	}
+	if got := resolveAppLinkDomain(core.LarkBrand("other")); got != "applink.feishu.cn" {
+		t.Fatalf("resolveAppLinkDomain(other) = %q, want feishu", got)
+	}
+}
+
+func TestFormatMessageItem_MessageAppLink_PassThrough(t *testing.T) {
+	runtime := &common.RuntimeContext{Config: &core.CliConfig{Brand: core.BrandFeishu}}
+	raw := map[string]interface{}{
+		"msg_type":         "text",
+		"message_id":       "om_123",
+		"create_time":      "1710500000",
+		"chat_id":          "oc_1",
+		"message_position": 12,
+		"message_app_link": "https://applink.feishu.cn/client/chat/open?openChatId=oc_1&position=12",
+		"body":             map[string]interface{}{"content": `{"text":"hi"}`},
+	}
+
+	got := FormatMessageItem(raw, runtime)
+	if got["message_app_link"] != raw["message_app_link"] {
+		t.Fatalf("FormatMessageItem() message_app_link = %#v, want pass-through", got["message_app_link"])
+	}
+}
+
+func TestFormatMessageItem_MessageAppLink_AssembleChat(t *testing.T) {
+	runtime := &common.RuntimeContext{Config: &core.CliConfig{Brand: core.BrandFeishu}}
+	raw := map[string]interface{}{
+		"msg_type":         "text",
+		"message_id":       "om_123",
+		"create_time":      "1710500000",
+		"chat_id":          "oc_1",
+		"message_position": float64(12),
+		"body":             map[string]interface{}{"content": `{"text":"hi"}`},
+	}
+
+	got := FormatMessageItem(raw, runtime)
+	assertURLHasQuery(t, got["message_app_link"].(string), "applink.feishu.cn", "/client/chat/open", map[string]string{
+		"openChatId": "oc_1",
+		"position":   "12",
+	})
+}
+
+func TestFormatMessageItem_MessageAppLink_AssembleThread(t *testing.T) {
+	runtime := &common.RuntimeContext{Config: &core.CliConfig{Brand: core.BrandLark}}
+	raw := map[string]interface{}{
+		"msg_type":                "text",
+		"message_id":              "om_123",
+		"create_time":             "1710500000",
+		"chat_id":                 "oc_1",
+		"thread_id":               "omt_1",
+		"thread_message_position": "9",
+		"message_position":        12,
+		"body":                    map[string]interface{}{"content": `{"text":"hi"}`},
+	}
+
+	got := FormatMessageItem(raw, runtime)
+	assertURLHasQuery(t, got["message_app_link"].(string), "applink.larksuite.com", "/client/thread/open", map[string]string{
+		"openthreadid":    "omt_1",
+		"openchatid":      "oc_1",
+		"open_thread_id":  "omt_1",
+		"open_chat_id":    "oc_1",
+		"thread_position": "9",
+	})
+}
+
+func TestFormatMessageItem_MessageAppLink_FallbackToChatWhenThreadPositionInvalid(t *testing.T) {
+	runtime := &common.RuntimeContext{Config: &core.CliConfig{Brand: core.BrandFeishu}}
+	raw := map[string]interface{}{
+		"msg_type":                "text",
+		"message_id":              "om_123",
+		"create_time":             "1710500000",
+		"chat_id":                 "oc_1",
+		"thread_id":               "omt_1",
+		"thread_message_position": "bad",
+		"message_position":        "12",
+		"body":                    map[string]interface{}{"content": `{"text":"hi"}`},
+	}
+
+	got := FormatMessageItem(raw, runtime)
+	assertURLHasQuery(t, got["message_app_link"].(string), "applink.feishu.cn", "/client/chat/open", map[string]string{
+		"openChatId": "oc_1",
+		"position":   "12",
+	})
+}
+
+func TestFormatMessageItem_MessageAppLink_BrandUnknownDefaultsToFeishu(t *testing.T) {
+	runtime := &common.RuntimeContext{Config: &core.CliConfig{Brand: core.LarkBrand("other")}}
+	raw := map[string]interface{}{
+		"msg_type":         "text",
+		"message_id":       "om_123",
+		"create_time":      "1710500000",
+		"chat_id":          "oc_1",
+		"message_position": 12,
+		"body":             map[string]interface{}{"content": `{"text":"hi"}`},
+	}
+
+	got := FormatMessageItem(raw, runtime)
+	assertURLHasQuery(t, got["message_app_link"].(string), "applink.feishu.cn", "/client/chat/open", map[string]string{
+		"openChatId": "oc_1",
+		"position":   "12",
+	})
+}
+
+func TestNormalizeMessagePosition_TypedIntsAndUints(t *testing.T) {
+	if got, ok := normalizeMessagePosition(int32(-3)); !ok || got != "-3" {
+		t.Fatalf("normalizeMessagePosition(int32(-3)) = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(uint64(9)); !ok || got != "9" {
+		t.Fatalf("normalizeMessagePosition(uint64(9)) = (%q,%v)", got, ok)
+	}
+}
+
+func TestNormalizeMessagePosition_CoversMoreNumericTypesAndInvalidInputs(t *testing.T) {
+	// ints
+	if got, ok := normalizeMessagePosition(int8(-1)); !ok || got != "-1" {
+		t.Fatalf("normalizeMessagePosition(int8(-1)) = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(int16(2)); !ok || got != "2" {
+		t.Fatalf("normalizeMessagePosition(int16(2)) = (%q,%v)", got, ok)
+	}
+
+	// uints
+	if got, ok := normalizeMessagePosition(uint(3)); !ok || got != "3" {
+		t.Fatalf("normalizeMessagePosition(uint(3)) = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(uintptr(4)); !ok || got != "4" {
+		t.Fatalf("normalizeMessagePosition(uintptr(4)) = (%q,%v)", got, ok)
+	}
+
+	// float32
+	if got, ok := normalizeMessagePosition(float32(1)); !ok || got != "1" {
+		t.Fatalf("normalizeMessagePosition(float32(1)) = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(float64(1.5)); !ok || got != "1.5" {
+		t.Fatalf("normalizeMessagePosition(float64(1.5)) = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(float64(-1.5)); !ok || got != "-1.5" {
+		t.Fatalf("normalizeMessagePosition(float64(-1.5)) = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(float32(math.NaN())); ok || got != "" {
+		t.Fatalf("normalizeMessagePosition(float32(NaN)) = (%q,%v), want ('',false)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(float32(math.Inf(1))); ok || got != "" {
+		t.Fatalf("normalizeMessagePosition(float32(+Inf)) = (%q,%v), want ('',false)", got, ok)
+	}
+
+	// json.Number invalid
+	if got, ok := normalizeMessagePosition(json.Number("1.5")); !ok || got != "1.5" {
+		t.Fatalf("normalizeMessagePosition(json.Number(1.5)) = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(json.Number("bad")); ok || got != "" {
+		t.Fatalf("normalizeMessagePosition(json.Number(bad)) = (%q,%v), want ('',false)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(json.Number("1e309")); ok || got != "" {
+		t.Fatalf("normalizeMessagePosition(json.Number(1e309)) = (%q,%v), want ('',false)", got, ok)
+	}
+
+	// string invalid
+	if got, ok := normalizeMessagePosition(" 1.5 "); !ok || got != "1.5" {
+		t.Fatalf("normalizeMessagePosition(\" 1.5 \") = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition("   "); ok || got != "" {
+		t.Fatalf("normalizeMessagePosition(blank) = (%q,%v), want ('',false)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition("not-a-number"); ok || got != "" {
+		t.Fatalf("normalizeMessagePosition(not-a-number) = (%q,%v), want ('',false)", got, ok)
+	}
+
+	// reflect fallback: pointers
+	i := int32(7)
+	if got, ok := normalizeMessagePosition(&i); !ok || got != "7" {
+		t.Fatalf("normalizeMessagePosition(*int32(7)) = (%q,%v)", got, ok)
+	}
+	u := uint64(8)
+	if got, ok := normalizeMessagePosition(&u); !ok || got != "8" {
+		t.Fatalf("normalizeMessagePosition(*uint64(8)) = (%q,%v)", got, ok)
+	}
+	f := float64(2.25)
+	if got, ok := normalizeMessagePosition(&f); !ok || got != "2.25" {
+		t.Fatalf("normalizeMessagePosition(*float64(2.25)) = (%q,%v)", got, ok)
+	}
+	fNaN := float64(math.NaN())
+	if got, ok := normalizeMessagePosition(&fNaN); ok || got != "" {
+		t.Fatalf("normalizeMessagePosition(*float64(NaN)) = (%q,%v), want ('',false)", got, ok)
+	}
+	var nilPtr *int
+	if got, ok := normalizeMessagePosition(nilPtr); ok || got != "" {
+		t.Fatalf("normalizeMessagePosition(nil ptr) = (%q,%v), want ('',false)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(struct{}{}); ok || got != "" {
+		t.Fatalf("normalizeMessagePosition(struct{}) = (%q,%v), want ('',false)", got, ok)
+	}
+}
+
+func TestAssembleMessageAppLink_EncodesQueryValues(t *testing.T) {
+	// chat link encoding
+	chat := map[string]interface{}{
+		"chat_id":          "oc_1+2/3",
+		"message_position": 12,
+	}
+	gotChat := assembleMessageAppLink(chat, core.BrandFeishu)
+	assertURLHasQuery(t, gotChat, "applink.feishu.cn", "/client/chat/open", map[string]string{
+		"openChatId": "oc_1+2/3",
+		"position":   "12",
+	})
+
+	// thread link encoding
+	thread := map[string]interface{}{
+		"chat_id":                 "oc_1+2/3",
+		"thread_id":               "omt_1+2/3",
+		"thread_message_position": -1,
+	}
+	gotThread := assembleMessageAppLink(thread, core.BrandFeishu)
+	assertURLHasQuery(t, gotThread, "applink.feishu.cn", "/client/thread/open", map[string]string{
+		"open_thread_id":  "omt_1+2/3",
+		"open_chat_id":    "oc_1+2/3",
+		"openthreadid":    "omt_1+2/3",
+		"openchatid":      "oc_1+2/3",
+		"thread_position": "-1",
+	})
+}
+
+func TestFormatMessageItem_MessageAppLink_NonStringDoesNotLeakNull(t *testing.T) {
+	runtime := &common.RuntimeContext{Config: &core.CliConfig{Brand: core.BrandFeishu}}
+	raw := map[string]interface{}{
+		"msg_type":         "text",
+		"message_id":       "om_123",
+		"create_time":      "1710500000",
+		"chat_id":          "oc_1",
+		"message_position": 12,
+		"message_app_link": nil,
+		"body":             map[string]interface{}{"content": `{"text":"hi"}`},
+	}
+
+	got := FormatMessageItem(raw, runtime)
+	// Should assemble instead of emitting JSON null.
+	assertURLHasQuery(t, got["message_app_link"].(string), "applink.feishu.cn", "/client/chat/open", map[string]string{
+		"openChatId": "oc_1",
+		"position":   "12",
+	})
+}
+
+func TestFormatMessageItem_MessageAppLink_RuntimeNilNoAssemble(t *testing.T) {
+	raw := map[string]interface{}{
+		"msg_type":         "text",
+		"message_id":       "om_123",
+		"create_time":      "1710500000",
+		"chat_id":          "oc_1",
+		"message_position": 12,
+		"body":             map[string]interface{}{"content": `{"text":"hi"}`},
+	}
+
+	got := FormatMessageItem(raw, nil)
+	if _, ok := got["message_app_link"]; ok {
+		t.Fatalf("FormatMessageItem() should not assemble without runtime, got %#v", got["message_app_link"])
+	}
+}
+
+func TestFormatMessageItem_MessageAppLink_MissingFieldsNoPanic(t *testing.T) {
+	runtime := &common.RuntimeContext{Config: &core.CliConfig{Brand: core.BrandFeishu}}
+	raw := map[string]interface{}{
+		"msg_type":    "text",
+		"message_id":  "om_123",
+		"create_time": "1710500000",
+		"body":        map[string]interface{}{"content": `{"text":"hi"}`},
+	}
+
+	got := FormatMessageItem(raw, runtime)
+	if _, ok := got["message_app_link"]; ok {
+		t.Fatalf("FormatMessageItem() message_app_link should be absent when fields are missing, got %#v", got["message_app_link"])
+	}
+}
+
+func TestNormalizeMessagePosition_AllowsZeroAndNegative(t *testing.T) {
+	if got, ok := normalizeMessagePosition("0"); !ok || got != "0" {
+		t.Fatalf("normalizeMessagePosition(\"0\") = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition("-3"); !ok || got != "-3" {
+		t.Fatalf("normalizeMessagePosition(\"-3\") = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(float64(0)); !ok || got != "0" {
+		t.Fatalf("normalizeMessagePosition(0.0) = (%q,%v)", got, ok)
+	}
+	if got, ok := normalizeMessagePosition(float64(-1)); !ok || got != "-1" {
+		t.Fatalf("normalizeMessagePosition(-1.0) = (%q,%v)", got, ok)
+	}
+}
+
 func TestExtractMentionOpenIdAndTruncateContent(t *testing.T) {
 	if got := extractMentionOpenId("ou_1"); got != "ou_1" {
 		t.Fatalf("extractMentionOpenId(string) = %q", got)

shortcuts/im/helpers.go

@@ -20,6 +20,8 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -32,6 +34,18 @@ var mentionFixRe = regexp.MustCompile(`<at\s+(id|open_id|user_id)=("?)([^"\s/>]+
 var threadIDRe = regexp.MustCompile(`^omt_`)
 var messageIDRe = regexp.MustCompile(`^om_`)
 
+func flagMessageID(rt *common.RuntimeContext) (string, error) {
+	id := strings.TrimSpace(rt.Str("message-id"))
+	if id == "" {
+		return "", output.ErrValidation("--message-id is required")
+	}
+	if strings.HasPrefix(id, "omt_") {
+		return "", output.ErrValidation(
+			"invalid message ID %q: omt_ prefix is a thread ID, not a message ID; flag operations require om_ message IDs", id)
+	}
+	return validateMessageID(id)
+}
+
 func normalizeAtMentions(content string) string {
 	return mentionFixRe.ReplaceAllString(content, `<at user_id="$3">`)
 }
@@ -1432,3 +1446,222 @@ func uploadFileFromReader(ctx context.Context, runtime *common.RuntimeContext, r
 	}
 	return fileKey, nil
 }
+
+// FlagType enumerates the kind of bookmark.
+// Aligned with server-side constants: Unknown=0, Feed=1, Message=2.
+type FlagType int
+
+const (
+	FlagTypeUnknown FlagType = 0
+	FlagTypeFeed    FlagType = 1
+	FlagTypeMessage FlagType = 2
+)
+
+// ItemType enumerates the kind of thing being bookmarked.
+// Server-side constants (only the types used by IM flags):
+//
+//	default=0, thread=4, msg_thread=11.
+//
+// Note on the two thread-shaped item types:
+//   - ItemTypeThread (4)     — thread inside a topic-style chat
+//   - ItemTypeMsgThread (11) — thread inside a regular chat
+type ItemType int
+
+const (
+	ItemTypeDefault   ItemType = 0
+	ItemTypeThread    ItemType = 4  // thread in a topic-style chat
+	ItemTypeMsgThread ItemType = 11 // thread in a regular chat
+)
+
+const (
+	flagWriteScope = "im:feed.flag:write"
+	flagReadScope  = "im:feed.flag:read"
+)
+
+var (
+	flagWriteLookupScopes = append([]string{flagWriteScope}, flagLookupScopes...)
+	flagMessageReadScopes = []string{
+		"im:message.group_msg:get_as_user",
+		"im:message.p2p_msg:get_as_user",
+	}
+	flagLookupScopes = []string{
+		"im:message.group_msg:get_as_user",
+		"im:message.p2p_msg:get_as_user",
+		"im:chat:read",
+	}
+)
+
+func checkFlagRequiredScopes(ctx context.Context, rt *common.RuntimeContext, required []string) error {
+	if len(required) == 0 {
+		return nil
+	}
+	result, err := rt.Factory.Credential.ResolveToken(ctx, credential.NewTokenSpec(rt.As(), rt.Config.AppID))
+	if err != nil {
+		return output.ErrWithHint(output.ExitAuth, "auth",
+			fmt.Sprintf("cannot verify required scope(s): %v", err),
+			flagScopeLoginHint(required))
+	}
+	if result == nil || result.Scopes == "" {
+		fmt.Fprintf(rt.IO().ErrOut,
+			"warning: cannot verify required scope(s) because token scope metadata is unavailable; API may fail if missing: %s\n",
+			strings.Join(required, " "))
+		return nil
+	}
+	if missing := auth.MissingScopes(result.Scopes, required); len(missing) > 0 {
+		return output.ErrWithHint(output.ExitAuth, "missing_scope",
+			fmt.Sprintf("missing required scope(s): %s", strings.Join(missing, ", ")),
+			flagScopeLoginHint(missing))
+	}
+	return nil
+}
+
+func flagScopeLoginHint(scopes []string) string {
+	return fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(scopes, " "))
+}
+
+// flagItem is one entry in the flags API body. The server expects numeric
+// enums serialized as strings.
+type flagItem struct {
+	ItemID   string `json:"item_id"`
+	ItemType string `json:"item_type"`
+	FlagType string `json:"flag_type"`
+}
+
+// parseItemID inspects an om_ prefix and returns a best-guess
+// (itemType, flagType) pair. Used when the user omits the explicit enums.
+//   - om_xxx  → (default, message)
+func parseItemID(id string) (ItemType, FlagType, error) {
+	id = strings.TrimSpace(id)
+	switch {
+	case strings.HasPrefix(id, "om_"):
+		return ItemTypeDefault, FlagTypeMessage, nil
+	case id == "":
+		return 0, 0, output.ErrValidation("--message-id cannot be empty")
+	default:
+		return 0, 0, output.ErrValidation(
+			"cannot infer item type from id %q: expected om_ (message) prefix; "+
+				"pass --item-type and --flag-type explicitly if you are using a different id format", id)
+	}
+}
+
+// parseItemType converts a user-facing string to the server enum.
+func parseItemType(s string) (ItemType, error) {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "", "default":
+		return ItemTypeDefault, nil
+	case "thread":
+		return ItemTypeThread, nil
+	case "msg_thread":
+		return ItemTypeMsgThread, nil
+	}
+	return 0, output.ErrValidation("invalid --item-type %q: expected one of default|thread|msg_thread", s)
+}
+
+// parseFlagType converts a user-facing string to the server enum.
+func parseFlagType(s string) (FlagType, error) {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "", "message":
+		return FlagTypeMessage, nil
+	case "feed":
+		return FlagTypeFeed, nil
+	}
+	return 0, output.ErrValidation("invalid --flag-type %q: expected one of message|feed", s)
+}
+
+// isValidCombo checks if the (ItemType, FlagType) pair is accepted by the server.
+// Note: (ItemType, FlagType) is shorthand for (item_type, flag_type) — the two
+// enum fields that determine which layer the flag operates on.
+//
+// Valid combinations are:
+//   - (default, message)  — regular chat message (message-layer flag)
+//   - (thread, feed)      — thread as feed-layer flag (topic-style chat)
+//   - (msg_thread, feed)  — message-thread as feed-layer flag (regular chat)
+func isValidCombo(it ItemType, ft FlagType) bool {
+	return (it == ItemTypeDefault && ft == FlagTypeMessage) ||
+		(it == ItemTypeThread && ft == FlagTypeFeed) ||
+		(it == ItemTypeMsgThread && ft == FlagTypeFeed)
+}
+
+// parseItemTypeFromRaw parses a stringified numeric item_type back to ItemType.
+// Used when re-parsing the serialized enum for combo-validity checks.
+// Note: Unknown values return ItemTypeDefault (0). This is safe because:
+//  1. This function only parses values we serialized ourselves via newFlagItem
+//  2. Unknown server values would fail combo validation or be rejected by the server
+func parseItemTypeFromRaw(s string) ItemType {
+	switch s {
+	case "0":
+		return ItemTypeDefault
+	case "4":
+		return ItemTypeThread
+	case "11":
+		return ItemTypeMsgThread
+	}
+	return ItemTypeDefault
+}
+
+// parseFlagTypeFromRaw parses a stringified numeric flag_type back to FlagType.
+// Used when re-parsing the serialized enum for combo-validity checks.
+func parseFlagTypeFromRaw(s string) FlagType {
+	switch s {
+	case "1":
+		return FlagTypeFeed
+	case "2":
+		return FlagTypeMessage
+	}
+	return FlagTypeUnknown
+}
+
+// newFlagItem builds a payload entry with numeric-stringified enums.
+func newFlagItem(itemID string, it ItemType, ft FlagType) flagItem {
+	return flagItem{
+		ItemID:   itemID,
+		ItemType: fmt.Sprintf("%d", int(it)),
+		FlagType: fmt.Sprintf("%d", int(ft)),
+	}
+}
+
+// getMessageChatID queries the message API to get the chat_id.
+// Used by flag-create to determine the chat type for feed-layer flags.
+func getMessageChatID(rt *common.RuntimeContext, messageID string) (string, error) {
+	data, err := rt.DoAPIJSON("GET", "/open-apis/im/v1/messages/"+validate.EncodePathSegment(messageID), nil, nil)
+	if err != nil {
+		return "", err
+	}
+
+	items, ok := data["items"].([]any)
+	if !ok || len(items) == 0 {
+		return "", output.ErrValidation("message not found or unexpected API response format")
+	}
+
+	msg, ok := items[0].(map[string]any)
+	if !ok {
+		return "", output.ErrValidation("unexpected message format in API response")
+	}
+
+	chatID, ok := msg["chat_id"].(string)
+	if !ok {
+		return "", output.ErrValidation("message response missing chat_id field")
+	}
+	return chatID, nil
+}
+
+// resolveThreadFeedItemType determines the correct feed-layer ItemType for a thread
+// by querying the chat API for chat_mode.
+//   - topic-style chat → ItemTypeThread
+//   - regular chat    → ItemTypeMsgThread
+//
+// Returns an error if the chat query fails, since guessing the wrong item_type
+// can cause silent failures in flag operations.
+func resolveThreadFeedItemType(rt *common.RuntimeContext, chatID string) (ItemType, error) {
+	data, err := rt.DoAPIJSON("GET", "/open-apis/im/v1/chats/"+validate.EncodePathSegment(chatID), nil, nil)
+	if err != nil {
+		return ItemTypeDefault, fmt.Errorf("failed to query chat_mode for chat %s: %w", chatID, err)
+	}
+
+	// DoAPIJSON returns envelope.Data, so chat_mode is at the top level
+	chatMode, _ := data["chat_mode"].(string)
+	if chatMode == "topic" {
+		return ItemTypeThread, nil
+	}
+	return ItemTypeMsgThread, nil
+}

shortcuts/im/helpers_test.go

@@ -859,6 +859,7 @@ func TestShortcuts(t *testing.T) {
 
 	want := []string{
 		"+chat-create",
+		"+chat-list",
 		"+chat-messages-list",
 		"+chat-search",
 		"+chat-update",
@@ -868,6 +869,9 @@ func TestShortcuts(t *testing.T) {
 		"+messages-search",
 		"+messages-send",
 		"+threads-messages-list",
+		"+flag-create",
+		"+flag-cancel",
+		"+flag-list",
 	}
 	if !reflect.DeepEqual(commands, want) {
 		t.Fatalf("Shortcuts() commands = %#v, want %#v", commands, want)

shortcuts/im/im_chat_create.go

@@ -16,10 +16,14 @@ 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; user/bot; creates private/public chats, invites users/bots, optionally sets bot manager",
+	Description: "Create a group chat or topic chat; user/bot; --chat-mode group|topic; private/public; invites users/bots; optionally sets bot manager",
 	Risk:        "write",
 	UserScopes:  []string{"im:chat:create_by_user"},
 	BotScopes:   []string{"im:chat:create"},
@@ -32,6 +36,7 @@ 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 {
@@ -141,9 +146,18 @@ 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

shortcuts/im/im_chat_list.go

@@ -0,0 +1,156 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package im
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// imChatListPath is the upstream HTTP path for the +chat-list shortcut.
+const imChatListPath = "/open-apis/im/v1/chats"
+
+// ImChatList is the +chat-list shortcut: wraps GET /open-apis/im/v1/chats to
+// list groups the current user/bot is a member of. Supports sort order,
+// pagination, and (user identity only) muted-chat filtering via --exclude-muted.
+var ImChatList = common.Shortcut{
+	Service:     "im",
+	Command:     "+chat-list",
+	Description: "List groups the current user/bot is a member of; user/bot; supports sorting, pagination, and --exclude-muted (user identity only)",
+	Risk:        "read",
+	Scopes:      []string{"im:chat:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "user-id-type", Default: "open_id", Desc: "ID type for owner_id in response", Enum: []string{"open_id", "union_id", "user_id"}},
+		{Name: "sort-type", Default: "ByCreateTimeAsc", Desc: "sort order", Enum: []string{"ByCreateTimeAsc", "ByActiveTimeDesc"}},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "page size (1-100)"},
+		{Name: "page-token", Desc: "pagination token for next page"},
+		{Name: "exclude-muted", Type: "bool", Desc: "(user identity only) drop chats the current user has muted (do-not-disturb); bot identity returns all chats unfiltered"},
+	},
+	// DryRun previews the GET /open-apis/im/v1/chats request without executing.
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		return common.NewDryRunAPI().
+			GET(imChatListPath).
+			Params(buildChatListParams(runtime))
+	},
+	// Validate enforces flag preconditions; only --page-size has bounds (1-100).
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if n := runtime.Int("page-size"); n < 1 || n > 100 {
+			return output.ErrValidation("--page-size must be an integer between 1 and 100")
+		}
+		return nil
+	},
+	// Execute fetches one page of chats, optionally applies --exclude-muted
+	// via MaybeApplyMuteFilter, and renders the result. outData["filter"] is
+	// populated only when --exclude-muted is set (backward compatible).
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		params := buildChatListParams(runtime)
+		resData, err := runtime.CallAPI("GET", imChatListPath, params, nil)
+		if err != nil {
+			return err
+		}
+
+		rawItems, _ := resData["items"].([]interface{})
+		hasMore, pageToken := common.PaginationMeta(resData)
+
+		var items []map[string]interface{}
+		for _, raw := range rawItems {
+			item, _ := raw.(map[string]interface{})
+			if item == nil {
+				continue
+			}
+			items = append(items, item)
+		}
+
+		mfOut, err := MaybeApplyMuteFilter(runtime, MuteFilterInput{
+			ExcludeMuted: runtime.Bool("exclude-muted"),
+			IsBot:        runtime.IsBot(),
+			Chats:        items,
+			ChatIDKey:    "chat_id",
+			HasMore:      hasMore,
+		})
+		if err != nil {
+			return err
+		}
+		items = mfOut.Chats
+
+		outData := map[string]interface{}{
+			"chats":      items,
+			"has_more":   hasMore,
+			"page_token": pageToken,
+		}
+		if mfOut.Meta.Applied != "" {
+			outData["filter"] = MuteFilterMetaToMap(mfOut.Meta)
+		}
+
+		runtime.OutFormat(outData, nil, func(w io.Writer) {
+			if len(items) == 0 {
+				fmt.Fprintln(w, "No chats found.")
+				if mfOut.Meta.Hint != "" {
+					fmt.Fprintln(w, mfOut.Meta.Hint)
+				}
+				return
+			}
+			rows := make([]map[string]interface{}, 0, len(items))
+			for _, m := range items {
+				row := map[string]interface{}{
+					"chat_id": m["chat_id"],
+					"name":    m["name"],
+				}
+				if desc, _ := m["description"].(string); desc != "" {
+					row["description"] = desc
+				}
+				if ownerID, _ := m["owner_id"].(string); ownerID != "" {
+					row["owner_id"] = ownerID
+				}
+				if external, ok := m["external"].(bool); ok {
+					row["external"] = external
+				}
+				if status, _ := m["chat_status"].(string); status != "" {
+					row["chat_status"] = status
+				}
+				rows = append(rows, row)
+			}
+			output.PrintTable(w, rows)
+			fmt.Fprintf(w, "\n%d chat(s) listed", len(rows))
+			if hasMore {
+				fmt.Fprint(w, " (more available, use --page-token to fetch next page")
+				if pageToken != "" {
+					fmt.Fprintf(w, ", page_token: %s", pageToken)
+				}
+				fmt.Fprint(w, ")")
+			}
+			fmt.Fprintln(w)
+			if mfOut.Meta.Hint != "" {
+				fmt.Fprintln(w, mfOut.Meta.Hint)
+			}
+		})
+		return nil
+	},
+}
+
+// buildChatListParams builds the query parameters for the GET /im/v1/chats
+// call from the runtime flag values. user_id_type and sort_type are always
+// present (their flag defaults are non-empty); page_token is omitted when
+// empty; page_size falls back to the API default of 20 when not provided.
+func buildChatListParams(runtime *common.RuntimeContext) map[string]interface{} {
+	params := map[string]interface{}{
+		"user_id_type": runtime.Str("user-id-type"),
+		"sort_type":    runtime.Str("sort-type"),
+	}
+	if n := runtime.Int("page-size"); n > 0 {
+		params["page_size"] = n
+	} else {
+		params["page_size"] = 20
+	}
+	if pt := runtime.Str("page-token"); pt != "" {
+		params["page_token"] = pt
+	}
+	return params
+}

shortcuts/im/im_chat_list_test.go

@@ -0,0 +1,128 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package im
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+// newChatListTestRuntimeContext mirrors newMessagesSearchTestRuntimeContext —
+// it registers page-size as Int (the existing newTestRuntimeContext registers
+// it as String, which would short-circuit our buildChatListParams logic).
+func newChatListTestRuntimeContext(t *testing.T, stringFlags map[string]string, boolFlags map[string]bool) *common.RuntimeContext {
+	t.Helper()
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().Int("page-size", 20, "")
+	for name := range stringFlags {
+		if name == "page-size" {
+			continue
+		}
+		cmd.Flags().String(name, "", "")
+	}
+	for name := range boolFlags {
+		cmd.Flags().Bool(name, false, "")
+	}
+	if err := cmd.ParseFlags(nil); err != nil {
+		t.Fatalf("ParseFlags() error = %v", err)
+	}
+	for name, val := range stringFlags {
+		if err := cmd.Flags().Set(name, val); err != nil {
+			t.Fatalf("Flags().Set(%q) error = %v", name, err)
+		}
+	}
+	for name, val := range boolFlags {
+		if err := cmd.Flags().Set(name, map[bool]string{true: "true", false: "false"}[val]); err != nil {
+			t.Fatalf("Flags().Set(%q) error = %v", name, err)
+		}
+	}
+	return &common.RuntimeContext{Cmd: cmd}
+}
+
+func TestBuildChatListParams_Defaults(t *testing.T) {
+	rt := newChatListTestRuntimeContext(t, map[string]string{
+		"user-id-type": "open_id",
+		"sort-type":    "ByCreateTimeAsc",
+	}, nil)
+	got := buildChatListParams(rt)
+	if got["user_id_type"] != "open_id" {
+		t.Fatalf("user_id_type = %v", got["user_id_type"])
+	}
+	if got["sort_type"] != "ByCreateTimeAsc" {
+		t.Fatalf("sort_type = %v", got["sort_type"])
+	}
+	if got["page_size"] != 20 {
+		t.Fatalf("page_size = %v, want 20", got["page_size"])
+	}
+	if _, present := got["page_token"]; present {
+		t.Fatalf("page_token should be omitted when empty")
+	}
+}
+
+func TestBuildChatListParams_Overrides(t *testing.T) {
+	rt := newChatListTestRuntimeContext(t, map[string]string{
+		"user-id-type": "user_id",
+		"sort-type":    "ByActiveTimeDesc",
+		"page-size":    "50",
+		"page-token":   "tok_xyz",
+	}, nil)
+	got := buildChatListParams(rt)
+	if got["user_id_type"] != "user_id" {
+		t.Fatalf("user_id_type = %v", got["user_id_type"])
+	}
+	if got["sort_type"] != "ByActiveTimeDesc" {
+		t.Fatalf("sort_type = %v", got["sort_type"])
+	}
+	if got["page_size"] != 50 {
+		t.Fatalf("page_size = %v, want 50", got["page_size"])
+	}
+	if got["page_token"] != "tok_xyz" {
+		t.Fatalf("page_token = %v", got["page_token"])
+	}
+}
+
+func TestImChatList_Validate_PageSizeBounds(t *testing.T) {
+	cases := []struct {
+		name     string
+		pageSize string
+		wantErr  bool
+	}{
+		{"zero rejected", "0", true},
+		{"negative rejected", "-1", true},
+		{"one ok", "1", false},
+		{"hundred ok", "100", false},
+		{"oneoone rejected", "101", true},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			rt := newChatListTestRuntimeContext(t, map[string]string{"page-size": c.pageSize}, nil)
+			err := ImChatList.Validate(context.Background(), rt)
+			if (err != nil) != c.wantErr {
+				t.Fatalf("Validate() err = %v, wantErr=%v", err, c.wantErr)
+			}
+		})
+	}
+}
+
+func TestImChatList_DryRun_IncludesEndpoint(t *testing.T) {
+	rt := newChatListTestRuntimeContext(t, map[string]string{
+		"user-id-type": "open_id",
+		"sort-type":    "ByActiveTimeDesc",
+		"page-size":    "30",
+	}, nil)
+	got := mustMarshalDryRun(t, ImChatList.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"/open-apis/im/v1/chats"`) {
+		t.Fatalf("DryRun missing endpoint: %s", got)
+	}
+	if !strings.Contains(got, `"sort_type":"ByActiveTimeDesc"`) {
+		t.Fatalf("DryRun missing sort_type: %s", got)
+	}
+	if !strings.Contains(got, `"page_size":30`) {
+		t.Fatalf("DryRun missing page_size: %s", got)
+	}
+}

shortcuts/im/im_chat_search.go

@@ -15,10 +15,14 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+// ImChatSearch is the +chat-search shortcut: wraps POST /open-apis/im/v2/chats/search
+// to find visible group chats by keyword and/or member open_ids. Supports
+// member/type filters, sort order, pagination, and (user identity only) the
+// --exclude-muted client-side mute filter.
 var ImChatSearch = common.Shortcut{
 	Service:     "im",
 	Command:     "+chat-search",
-	Description: "Search visible group chats by keyword and/or member open_ids (e.g. look up chat_id by group name); user/bot; supports member/type filters, sorting, and pagination",
+	Description: "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, pagination, and --exclude-muted (user identity only)",
 	Risk:        "read",
 	Scopes:      []string{"im:chat:read"},
 	AuthTypes:   []string{"user", "bot"},
@@ -32,7 +36,9 @@ var ImChatSearch = common.Shortcut{
 		{Name: "sort-by", Desc: "sort field (descending)", Enum: []string{"create_time_desc", "update_time_desc", "member_count_desc"}},
 		{Name: "page-size", Type: "int", Default: "20", Desc: "page size (1-100)"},
 		{Name: "page-token", Desc: "pagination token for next page"},
+		{Name: "exclude-muted", Type: "bool", Desc: "(user identity only) drop chats the current user has muted (do-not-disturb); bot identity returns all chats unfiltered"},
 	},
+	// DryRun previews the POST /open-apis/im/v2/chats/search request without executing.
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		body := buildSearchChatBody(runtime)
 		params := buildSearchChatParams(runtime)
@@ -41,6 +47,8 @@ var ImChatSearch = common.Shortcut{
 			Params(params).
 			Body(body)
 	},
+	// Validate enforces query/member-ids presence, --query rune cap, search-types
+	// enum, --member-ids count and format, and --page-size bounds.
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		query := runtime.Str("query")
 		memberIDs := runtime.Str("member-ids")
@@ -79,6 +87,10 @@ var ImChatSearch = common.Shortcut{
 		}
 		return nil
 	},
+	// Execute fetches one page, extracts per-item meta_data, optionally applies
+	// the --exclude-muted client-side filter (with a PreSkipReason when
+	// --search-types is exactly public_not_joined), and renders the result.
+	// outData["filter"] is populated only when --exclude-muted is set.
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		body := buildSearchChatBody(runtime)
 		params := buildSearchChatParams(runtime)
@@ -106,16 +118,39 @@ var ImChatSearch = common.Shortcut{
 			items = append(items, meta)
 		}
 
+		preSkipReason := ""
+		if runtime.Bool("exclude-muted") {
+			preSkipReason = detectAllNonMemberPreSkip(runtime.Str("search-types"))
+		}
+		mfOut, err := MaybeApplyMuteFilter(runtime, MuteFilterInput{
+			ExcludeMuted:  runtime.Bool("exclude-muted"),
+			IsBot:         runtime.IsBot(),
+			PreSkipReason: preSkipReason,
+			Chats:         items,
+			ChatIDKey:     "chat_id",
+			HasMore:       hasMore,
+		})
+		if err != nil {
+			return err
+		}
+		items = mfOut.Chats
+
 		outData := map[string]interface{}{
 			"chats":      items,
 			"total":      int(total),
 			"has_more":   hasMore,
 			"page_token": pageToken,
 		}
+		if mfOut.Meta.Applied != "" {
+			outData["filter"] = MuteFilterMetaToMap(mfOut.Meta)
+		}
 
 		runtime.OutFormat(outData, nil, func(w io.Writer) {
 			if len(items) == 0 {
 				fmt.Fprintln(w, "No matching group chats found.")
+				if mfOut.Meta.Hint != "" {
+					fmt.Fprintln(w, mfOut.Meta.Hint)
+				}
 				return
 			}
 			var rows []map[string]interface{}
@@ -154,11 +189,19 @@ var ImChatSearch = common.Shortcut{
 				moreHint += ")"
 			}
 			fmt.Fprintf(w, "\n%d chat(s) found%s\n", int(total), moreHint)
+			if mfOut.Meta.Hint != "" {
+				fmt.Fprintln(w, mfOut.Meta.Hint)
+			}
 		})
 		return nil
 	},
 }
 
+// buildSearchChatBody builds the JSON request body for POST /im/v2/chats/search
+// from the runtime flag values. The query string is normalized via
+// normalizeChatSearchQuery (hyphenated terms get quoted). The "filter" object
+// is omitted when no filter flags are set; "sorter" is omitted when --sort-by
+// is empty.
 func buildSearchChatBody(runtime *common.RuntimeContext) map[string]interface{} {
 	body := map[string]interface{}{}
 
@@ -194,6 +237,9 @@ func buildSearchChatBody(runtime *common.RuntimeContext) map[string]interface{}
 	return body
 }
 
+// buildSearchChatParams builds the query parameters for the POST
+// /im/v2/chats/search call. page_size defaults to the API default of 20 when
+// not provided; page_token is omitted when empty.
 func buildSearchChatParams(runtime *common.RuntimeContext) map[string]interface{} {
 	params := map[string]interface{}{}
 	if n := runtime.Int("page-size"); n > 0 {
@@ -207,10 +253,11 @@ func buildSearchChatParams(runtime *common.RuntimeContext) map[string]interface{
 	return params
 }
 
+// normalizeChatSearchQuery wraps hyphenated search queries in double quotes
+// because the search API treats hyphenated keywords specially and expects the
+// whole query to be quoted. Already-quoted input is unwrapped before requoting
+// so we don't emit nested quotes. Inputs without "-" pass through unchanged.
 func normalizeChatSearchQuery(query string) string {
-	// The search API treats hyphenated keywords specially and expects the whole
-	// query to be quoted. Normalize already-quoted input before requoting so we
-	// don't emit nested quotes.
 	if !strings.Contains(query, "-") {
 		return query
 	}
@@ -219,3 +266,15 @@ func normalizeChatSearchQuery(query string) string {
 	}
 	return strconv.Quote(query)
 }
+
+// detectAllNonMemberPreSkip returns SkipReasonAllNonMember when --search-types
+// is exactly "public_not_joined" — the one combination guaranteeing no member
+// chats, making the mute filter a no-op. Any other value (including empty or
+// mixed) returns "".
+func detectAllNonMemberPreSkip(searchTypesCSV string) string {
+	types := common.SplitCSV(searchTypesCSV)
+	if len(types) == 1 && types[0] == "public_not_joined" {
+		return SkipReasonAllNonMember
+	}
+	return ""
+}

shortcuts/im/im_flag_cancel.go

@@ -0,0 +1,247 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package im
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ImFlagCancel provides the +flag-cancel shortcut for removing a bookmark.
+// When no --flag-type is given, it performs double-cancel: removes both message and feed layers.
+var ImFlagCancel = common.Shortcut{
+	Service: "im",
+	Command: "+flag-cancel",
+	Description: "Cancel (remove) a bookmark. When no --flag-type is given, " +
+		"performs double-cancel: removes both message and feed layers",
+	Risk:       "write",
+	UserScopes: flagWriteLookupScopes,
+	AuthTypes:  []string{"user"},
+	HasFormat:  true,
+	Flags: []common.Flag{
+		{Name: "message-id", Desc: "message ID (om_xxx)"},
+		{Name: "item-type", Desc: "item type override: default|thread|msg_thread"},
+		{Name: "flag-type", Desc: "flag type override: message|feed; omit to double-cancel both layers"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, _, err := buildCancelItemsForPreview(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		items, _, err := buildCancelItemsForPreview(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		d := common.NewDryRunAPI().
+			POST("/open-apis/im/v1/flags/cancel").
+			Body(map[string]any{"flag_items": items})
+		if len(items) > 1 {
+			d.Desc("double-cancel: tries both message and feed layers (best-effort); feed-layer skipped if chat_type undeterminable")
+		}
+		return d
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		items, err := buildCancelItems(runtime)
+		if err != nil {
+			return err
+		}
+
+		// Make separate API calls for each item so they are independent.
+		// If one fails, the other can still succeed.
+		results := make([]map[string]any, 0, len(items))
+		var lastErr error
+		for _, item := range items {
+			itemType := itemTypeString(parseItemTypeFromRaw(item.ItemType))
+			flagType := flagTypeString(parseFlagTypeFromRaw(item.FlagType))
+			result := map[string]any{
+				"item_id":   item.ItemID,
+				"item_type": itemType,
+				"flag_type": flagType,
+			}
+			data, err := runtime.DoAPIJSON("POST", "/open-apis/im/v1/flags/cancel", nil,
+				map[string]any{"flag_items": []flagItem{item}})
+			if err != nil {
+				fmt.Fprintf(runtime.IO().ErrOut, "warning: cancel failed for %s/%s: %v\n",
+					itemType, flagType, err)
+				result["status"] = "failed"
+				result["error"] = err.Error()
+				lastErr = err
+			} else {
+				result["status"] = "ok"
+				result["response"] = data
+			}
+			results = append(results, result)
+		}
+
+		runtime.Out(map[string]any{"results": results}, nil)
+		return lastErr
+	},
+}
+
+// buildCancelItemsForPreview builds cancel items without API calls.
+// It shows double-cancel when no explicit flags are provided.
+// DryRun cannot query chat_mode, so feed-layer item_type is represented with
+// the same auto-detect placeholder used by +flag-create.
+func buildCancelItemsForPreview(rt *common.RuntimeContext) ([]any, bool, error) {
+	id, err := flagMessageID(rt)
+	if err != nil {
+		return nil, false, err
+	}
+
+	itOverride := strings.TrimSpace(rt.Str("item-type"))
+	ftOverride := strings.TrimSpace(rt.Str("flag-type"))
+
+	// Explicit override provided → single targeted delete
+	if itOverride != "" || ftOverride != "" {
+		item, err := buildSingleCancelItem(id, itOverride, ftOverride)
+		if err != nil {
+			return nil, false, err
+		}
+		return []any{item}, false, nil
+	}
+
+	// No override: show double-cancel (message + feed layers)
+	// Dry-run shows both layers; actual execution is best-effort.
+	return []any{
+		newFlagItem(id, ItemTypeDefault, FlagTypeMessage),
+		map[string]string{
+			"item_id":   id,
+			"item_type": "<auto:thread|msg_thread>",
+			"flag_type": fmt.Sprintf("%d", int(FlagTypeFeed)),
+		},
+	}, true, nil
+}
+
+// buildCancelItems picks the (item_type, flag_type) pairs to cancel.
+//
+// Logic:
+//  1. If --flag-type is explicitly provided, do a single targeted delete.
+//  2. Otherwise, perform double-cancel: remove both message layer and feed layer.
+//     - Message layer is always included (uses known message_id with ItemTypeDefault)
+//     - Feed layer is best-effort: if chat_type cannot be determined, skip with warning
+//     - Each layer is independent; failure to cancel one doesn't block the other
+func buildCancelItems(rt *common.RuntimeContext) ([]flagItem, error) {
+	id, err := flagMessageID(rt)
+	if err != nil {
+		return nil, err
+	}
+
+	itOverride := strings.TrimSpace(rt.Str("item-type"))
+	ftOverride := strings.TrimSpace(rt.Str("flag-type"))
+
+	// Explicit override provided → single targeted delete
+	if itOverride != "" || ftOverride != "" {
+		item, err := buildSingleCancelItem(id, itOverride, ftOverride)
+		if err != nil {
+			return nil, err
+		}
+		return []flagItem{item}, nil
+	}
+
+	// Double-cancel: message layer + feed layer (best effort)
+	// Message layer is always included - we have the message_id and know the combo is valid.
+	items := []flagItem{newFlagItem(id, ItemTypeDefault, FlagTypeMessage)}
+
+	// Feed layer: try to determine chat_type, but don't fail if we can't.
+	// Most messages only have one layer flagged, so this is best-effort cleanup.
+	chatID, err := getMessageChatID(rt, id)
+	if err != nil {
+		// Can't get chat_id, warn and skip feed layer
+		fmt.Fprintf(rt.IO().ErrOut, "warning: cannot determine feed-layer item_type: %v; skipping feed-layer cancel\n", err)
+		return items, nil
+	}
+
+	feedIT, err := resolveThreadFeedItemType(rt, chatID)
+	if err != nil {
+		// Can't determine chat_type, warn and skip feed layer
+		fmt.Fprintf(rt.IO().ErrOut, "warning: cannot determine feed-layer item_type: %v; skipping feed-layer cancel\n", err)
+		return items, nil
+	}
+
+	// Include feed layer
+	items = append(items, newFlagItem(id, feedIT, FlagTypeFeed))
+	return items, nil
+}
+
+// buildSingleCancelItem builds a single cancel item when user provides explicit flags.
+func buildSingleCancelItem(id, itOverride, ftOverride string) (flagItem, error) {
+	var itemType ItemType
+	var flagType FlagType
+
+	if itOverride != "" {
+		it, err := parseItemType(itOverride)
+		if err != nil {
+			return flagItem{}, err
+		}
+		itemType = it
+	}
+	if ftOverride != "" {
+		ft, err := parseFlagType(ftOverride)
+		if err != nil {
+			return flagItem{}, err
+		}
+		flagType = ft
+	}
+	if itOverride == "" || ftOverride == "" {
+		inferIT, inferFT, err := parseItemID(id)
+		if err != nil {
+			return flagItem{}, err
+		}
+		if itOverride == "" {
+			itemType = inferIT
+		}
+		if ftOverride == "" {
+			flagType = inferFT
+		}
+	}
+	if !isValidCombo(itemType, flagType) {
+		// Provide more specific hints for common mistakes
+		if itOverride != "" && ftOverride == "" {
+			if itemType == ItemTypeThread || itemType == ItemTypeMsgThread {
+				return flagItem{}, output.ErrValidation(
+					"invalid combination: --item-type=%s requires --flag-type=feed (feed-layer flags are the only valid type for threads)",
+					itOverride)
+			}
+			return flagItem{}, output.ErrValidation(
+				"invalid combination: --item-type=%s with inferred --flag-type=%s; specify --flag-type explicitly to override",
+				itOverride, flagTypeString(flagType))
+		}
+		if itOverride == "" && ftOverride != "" {
+			return flagItem{}, output.ErrValidation(
+				"invalid combination: --flag-type=%s with inferred --item-type=%s; specify --item-type explicitly to override",
+				ftOverride, itemTypeString(itemType))
+		}
+		return flagItem{}, output.ErrValidation(
+			"invalid --item-type/--flag-type combination: supported pairs are default+message, thread+feed, and msg_thread+feed")
+	}
+	return newFlagItem(id, itemType, flagType), nil
+}
+
+// itemTypeString converts ItemType to a user-facing string.
+func itemTypeString(it ItemType) string {
+	switch it {
+	case ItemTypeDefault:
+		return "default"
+	case ItemTypeThread:
+		return "thread"
+	case ItemTypeMsgThread:
+		return "msg_thread"
+	}
+	return "unknown"
+}
+
+// flagTypeString converts FlagType to a user-facing string.
+func flagTypeString(ft FlagType) string {
+	switch ft {
+	case FlagTypeFeed:
+		return "feed"
+	case FlagTypeMessage:
+		return "message"
+	}
+	return "unknown"
+}