docs: add v2 api version to docs fetch examples (#891)

Change-Id: I130e6e02c0b7594a05bdda6c9bf552fb15572791

CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
@@ -659,6 +703,9 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[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

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/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

@@ -75,7 +75,7 @@ func resolveDeclaredShortcutScopes(cmd *cobra.Command, identity string) []string
 		if sc.Service != service || sc.Command != cmd.Name() || !shortcutSupportsIdentity(sc, identity) {
 			continue
 		}
-		scopes := sc.ScopesForIdentity(identity)
+		scopes := sc.DeclaredScopesForIdentity(identity)
 		if len(scopes) == 0 {
 			return nil
 		}

cmd/root.go

@@ -140,6 +140,7 @@ func setupNotices() {
 				"current": info.Current,
 				"latest":  info.Latest,
 				"message": info.Message(),
+				"command": "lark-cli update",
 			}
 		}
 		if stale := skillscheck.GetPending(); stale != nil {
@@ -147,6 +148,7 @@ func setupNotices() {
 				"current": stale.Current,
 				"target":  stale.Target,
 				"message": stale.Message(),
+				"command": "lark-cli update",
 			}
 		}
 		if len(notice) == 0 {

cmd/root_integration_test.go

@@ -504,10 +504,12 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 	})
 }
 
-// TestSetupNotices_ColdStart verifies that when no skills stamp exists,
-// the composed PendingNotice provider includes a "skills" key with an
-// empty Current and the cold-start message.
-func TestSetupNotices_ColdStart(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)
@@ -530,17 +532,10 @@ func TestSetupNotices_ColdStart(t *testing.T) {
 
 	notice := output.GetNotice()
 	if notice == nil {
-		t.Fatal("GetNotice() = nil, want non-nil for cold start")
+		return // expected — no pending notices at all
 	}
-	skills, ok := notice["skills"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("notice.skills missing, got %+v", notice)
-	}
-	if skills["current"] != "" || skills["target"] != "1.0.21" {
-		t.Errorf("notice.skills = %+v, want {current:\"\", target:\"1.0.21\"}", skills)
-	}
-	if msg, _ := skills["message"].(string); msg != "lark-cli skills not installed, run: lark-cli update" {
-		t.Errorf("notice.skills.message = %q, want cold-start message", msg)
+	if _, ok := notice["skills"]; ok {
+		t.Errorf("notice.skills present in cold-start state, want absent: %+v", notice)
 	}
 }
 
@@ -617,6 +612,9 @@ func TestSetupNotices_Drift(t *testing.T) {
 	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
@@ -663,6 +661,20 @@ func TestSetupNotices_BothUpdateAndSkills(t *testing.T) {
 	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

cmd/root_test.go

@@ -284,6 +284,32 @@ func TestEnrichMissingScopeError_ShortcutUsesDeclaredScopesWhenNoUAT(t *testing.
 	}
 }
 
+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())
 

cmd/update/update.go

@@ -227,7 +227,7 @@ func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest stri
 	fmt.Fprintf(io.ErrOut, "To update manually, download the latest release:\n")
 	fmt.Fprintf(io.ErrOut, "  Release:   %s\n", releaseURL(latest))
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
-	fmt.Fprintf(io.ErrOut, "\nOr install via npm:\n  npm install -g %s@%s\n", selfupdate.NpmPackage, latest)
+	fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }
@@ -324,7 +324,7 @@ 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

cmd/update/update_test.go

@@ -168,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"})
@@ -195,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{})
@@ -222,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"})
@@ -312,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"})
@@ -467,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) {
@@ -629,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"})

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/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/skillscheck/check.go

@@ -4,9 +4,9 @@
 package skillscheck
 
 // Init runs the synchronous skills version check. Stores a StaleNotice
-// when the local stamp does not match currentVersion. Safe to call
-// from cmd/root.go before rootCmd.Execute(); zero network, zero
-// subprocess — only a local stamp file read.
+// 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).
@@ -15,10 +15,12 @@ package skillscheck
 //   - 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 / in-sync) leave pending == nil instead
-	// of preserving a stale value from a previous Init invocation.
+	// (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
@@ -28,11 +30,19 @@ func Init(currentVersion string) {
 		// 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, // "" when never synced
+		Current: stamp, // guaranteed non-empty under the new contract
 		Target:  currentVersion,
 	})
 }

internal/skillscheck/check_test.go

@@ -29,17 +29,13 @@ func TestInit_InSync_NoNotice(t *testing.T) {
 	}
 }
 
-func TestInit_ColdStart_NoticeWithEmptyCurrent(t *testing.T) {
+func TestInit_ColdStart_NoNotice(t *testing.T) {
 	clearSkillsSkipEnv(t)
 	resetPending(t)
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	Init("1.0.21")
-	got := GetPending()
-	if got == nil {
-		t.Fatal("GetPending() = nil, want non-nil for cold start")
-	}
-	if got.Current != "" || got.Target != "1.0.21" {
-		t.Errorf("notice = %+v, want {Current:\"\", Target:\"1.0.21\"}", got)
+	if got := GetPending(); got != nil {
+		t.Errorf("GetPending() = %+v, want nil (cold start is silent)", got)
 	}
 }
 

internal/skillscheck/notice.go

@@ -15,20 +15,20 @@ import (
 
 // StaleNotice signals that the locally synced skills version does not
 // match the running binary. Current is the last successfully synced
-// version (or "" when never synced); Target is the running binary
-// version. Mirrors internal/update.UpdateInfo's pending-notice pattern.
+// 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
-// gap plus the canonical fix command. Mirrors internal/update.UpdateInfo.Message
-// in style ("..., run: lark-cli update" suffix).
+// 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 {
-	if s.Current == "" {
-		return "lark-cli skills not installed, run: lark-cli update"
-	}
 	return fmt.Sprintf(
 		"lark-cli skills %s out of sync with binary %s, run: lark-cli update",
 		s.Current, s.Target,

internal/skillscheck/notice_test.go

@@ -14,11 +14,6 @@ func TestStaleNotice_Message(t *testing.T) {
 		n    StaleNotice
 		want string
 	}{
-		{
-			"cold_start",
-			StaleNotice{Current: "", Target: "1.0.21"},
-			"lark-cli skills not installed, run: lark-cli update",
-		},
 		{
 			"drift",
 			StaleNotice{Current: "1.0.20", Target: "1.0.21"},

package.json

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

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) => {

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/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

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

shortcuts/drive/drive_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,8 +21,18 @@ 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"
 )
 
@@ -37,6 +48,7 @@ type drivePullTarget struct {
 	DownloadToken string
 	ItemFileToken string
 	ItemSourceID  string
+	ModifiedTime  string
 }
 
 // DrivePull performs a one-way file-level mirror from a Drive folder onto
@@ -60,7 +72,7 @@ var DrivePull = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "local-dir", Desc: "local root directory (relative to cwd)", Required: true},
 		{Name: "folder-token", Desc: "source Drive folder token", Required: true},
-		{Name: "if-exists", Desc: "policy when a local file already exists", 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"},
@@ -68,6 +80,7 @@ var DrivePull = common.Shortcut{
 	Tips: []string{
 		"Only entries with type=file are downloaded; online docs (docx, sheet, bitable, mindnote, slides) and shortcuts are skipped.",
 		"Subfolders recurse and are reproduced as local directories under --local-dir; missing parents are created automatically.",
+		"For repeat syncs, --if-exists=smart is the recommended best-effort incremental mode: it compares local mtime with Drive modified_time and skips downloads when the local copy is already up to date.",
 		"Duplicate remote rel_path conflicts fail by default. Use --on-duplicate-remote=rename to download duplicate files with stable hashed suffixes.",
 		"--delete-local requires --yes; without --yes the command is rejected upfront so a stray flag never deletes anything.",
 	},
@@ -202,14 +215,14 @@ var DrivePull = common.Shortcut{
 					downloadFailed++
 					continue
 				}
-				if ifExists == drivePullIfExistsSkip {
+				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, downloadToken, target); err != nil {
+			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++
@@ -305,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)),
@@ -320,9 +335,53 @@ 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))
@@ -346,7 +405,7 @@ func drivePullRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (m
 	for _, rel := range relPaths {
 		files := fileGroups[rel]
 		if len(files) == 1 {
-			remoteFiles[rel] = drivePullTarget{DownloadToken: files[0].FileToken, ItemFileToken: files[0].FileToken}
+			remoteFiles[rel] = drivePullTarget{DownloadToken: files[0].FileToken, ItemFileToken: files[0].FileToken, ModifiedTime: files[0].ModifiedTime}
 			remotePaths[rel] = struct{}{}
 			continue
 		}
@@ -366,6 +425,7 @@ func drivePullRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (m
 				remoteFiles[targetRel] = drivePullTarget{
 					DownloadToken: file.FileToken,
 					ItemSourceID:  stableTokenIdentifier(file.FileToken),
+					ModifiedTime:  file.ModifiedTime,
 				}
 				remotePaths[targetRel] = struct{}{}
 			}
@@ -374,7 +434,7 @@ func drivePullRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (m
 			if err != nil {
 				return nil, nil, err
 			}
-			remoteFiles[rel] = drivePullTarget{DownloadToken: chosen.FileToken, ItemFileToken: chosen.FileToken}
+			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)

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

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,7 +93,7 @@ var DrivePush = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "local-dir", Desc: "local root directory (relative to cwd)", Required: true},
 		{Name: "folder-token", Desc: "target Drive folder token", Required: true},
-		{Name: "if-exists", Desc: "policy when a Drive file already exists at the same rel_path (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"},
@@ -99,8 +101,9 @@ var DrivePush = common.Shortcut{
 	Tips: []string{
 		"This is a file-level mirror: only type=file entries are uploaded, overwritten or deleted. Online docs (docx, sheet, bitable, mindnote, slides), shortcuts, and remote-only directories are never touched.",
 		"Local directory structure (including empty directories) is mirrored to Drive via create_folder; existing remote folders are reused.",
+		"For repeat syncs, --if-exists=smart is a best-effort incremental mode: it compares local mtime with Drive modified_time and skips uploads when the remote copy is already up to date; otherwise it falls through to the same overwrite path as --if-exists=overwrite.",
 		"Duplicate remote rel_path conflicts fail by default before upload, overwrite, or delete. Use --on-duplicate-remote=newest|oldest only when the conflict is duplicate files and you explicitly want to target one.",
-		"Default --if-exists=skip is the safe choice while the upload_all overwrite-version field is rolling out. Pass --if-exists=overwrite to replace remote bytes; on tenants without the field it surfaces a structured api_error and the run exits non-zero.",
+		"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.",
@@ -151,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"))
 	},
@@ -267,7 +270,7 @@ 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
@@ -394,6 +397,7 @@ type drivePushLocalFile struct {
 	OpenPath string
 	FileName string
 	Size     int64
+	ModTime  time.Time
 }
 
 // drivePushWalkLocal walks the canonical absolute root produced by
@@ -450,6 +454,7 @@ func drivePushWalkLocal(root, cwdCanonical string) (map[string]drivePushLocalFil
 			OpenPath: relToCwd,
 			FileName: filepath.Base(rel),
 			Size:     info.Size(),
+			ModTime:  info.ModTime(),
 		}
 		return nil
 	})
@@ -473,6 +478,30 @@ func drivePushWalkLocal(root, cwdCanonical string) (map[string]drivePushLocalFil
 	return files, dirs, nil
 }
 
+func drivePushShouldSkipExisting(localFile drivePushLocalFile, remoteFile driveRemoteEntry, ifExists string) bool {
+	switch ifExists {
+	case drivePushIfExistsSkip:
+		return true
+	case drivePushIfExistsSmart:
+		return drivePushShouldSkipSmart(localFile, remoteFile)
+	default:
+		return false
+	}
+}
+
+func drivePushShouldSkipSmart(localFile drivePushLocalFile, remoteFile driveRemoteEntry) bool {
+	cmp, ok := compareDriveRemoteModifiedToLocal(remoteFile.ModifiedTime, localFile.ModTime)
+	if !ok {
+		// Smart mode is an optimization. If the timestamp is missing or
+		// malformed, fall back to the safe transfer path instead of silently
+		// skipping an update we could not compare.
+		return false
+	}
+	// Remote is already at least as new as the local file, so another
+	// upload would be redundant.
+	return cmp >= 0
+}
+
 func drivePushRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (map[string]driveRemoteEntry, map[string]driveRemoteEntry, map[string][]driveRemoteEntry, error) {
 	remoteFiles := make(map[string]driveRemoteEntry, len(entries))
 	remoteFolders := make(map[string]driveRemoteEntry, len(entries))

shortcuts/drive/drive_push_test.go

@@ -12,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.

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,7 +152,7 @@ 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
 		}
@@ -130,30 +170,42 @@ var DriveStatus = common.Shortcut{
 		// hashable bytes and are intentionally absent from the diff
 		// view (a docx living next to a same-named local file is a
 		// known no-op).
-		remoteFiles := make(map[string]string, len(entries))
+		remoteFiles := make(map[string]driveStatusRemoteFile, len(entries))
 		for _, entry := range entries {
 			if entry.Type == driveTypeFile {
-				remoteFiles[entry.RelPath] = 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 {
@@ -163,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),
@@ -180,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
@@ -202,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 {
@@ -215,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 {
@@ -244,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`

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

@@ -11,6 +11,7 @@ import (
 	"path"
 	"sort"
 	"strconv"
+	"time"
 
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -195,6 +196,9 @@ const (
 	driveDuplicateRemoteOldest = "oldest"
 )
 
+// sortRemoteFiles orders duplicate Drive files according to the conflict
+// strategy, using parsed Drive timestamps so mixed second/millisecond/
+// microsecond epochs compare by actual time rather than raw integer width.
 func sortRemoteFiles(files []driveRemoteEntry, strategy string) {
 	sort.SliceStable(files, func(i, j int) bool {
 		a, b := files[i], files[j]
@@ -226,16 +230,61 @@ func sortRemoteFiles(files []driveRemoteEntry, strategy string) {
 	})
 }
 
+// compareDriveTimes compares two Drive epoch strings after normalizing their
+// unit (seconds, milliseconds, or microseconds) into time.Time values.
 func compareDriveTimes(a, b string) (int, bool) {
-	av, aErr := strconv.ParseInt(a, 10, 64)
-	bv, bErr := strconv.ParseInt(b, 10, 64)
-	if aErr != nil || bErr != nil {
+	at, _, aOK := parseDriveEpoch(a)
+	bt, _, bOK := parseDriveEpoch(b)
+	if !aOK || !bOK {
 		return 0, false
 	}
 	switch {
-	case av < bv:
+	case at.Before(bt):
 		return -1, true
-	case av > bv:
+	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

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/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",

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/mute_filter.go

@@ -0,0 +1,320 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package-level helper: client-side filter that drops muted chats from
+// search/list results by calling /open-apis/im/v1/chat_user_setting/batch_get_mute_status.
+//
+// The native chat search/list APIs do not return mute status; we fetch it as
+// a separate batch lookup, then drop is_muted=true items. Non-member /
+// invalid-format chat_ids come back via invalid_id_list and are silently
+// retained (we don't know their mute state). Bot identity is unsupported by
+// the upstream API (UAT-only), so we skip the filter and emit a machine-readable
+// skipped indicator instead of erroring.
+
+package im
+
+import (
+	"fmt"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// MuteFilterMeta describes the outcome of a single page's mute filter run.
+// UnknownCount is internal — used to compose the hint, not exposed in JSON.
+type MuteFilterMeta struct {
+	Applied       string
+	Skipped       bool
+	SkipReason    string
+	FetchedCount  int
+	ReturnedCount int
+	FilteredCount int
+	UnknownCount  int
+	Hint          string
+}
+
+// MaxMuteStatusBatchSize is the upstream cap for chat_ids per
+// batch_get_mute_status call (after dedupe).
+const MaxMuteStatusBatchSize = 100
+
+// BatchGetMuteStatusPath is the upstream HTTP path.
+const BatchGetMuteStatusPath = "/open-apis/im/v1/chat_user_setting/batch_get_mute_status"
+
+// SkipReason constants — written to filter.skip_reason when Skipped=true.
+const (
+	SkipReasonBotIdentity  = "bot_identity_no_mute_data"
+	SkipReasonAllNonMember = "all_non_member_search_types"
+)
+
+// BuildMuteFilterHint composes the user/AI-facing English hint for a finished
+// filter run. hasMore is the underlying API's has_more (so we can suggest paging).
+// Returns "" when the filter ran but had no effect (FilteredCount==0 and not skipped).
+func BuildMuteFilterHint(meta MuteFilterMeta, hasMore bool) string {
+	if meta.Skipped {
+		switch meta.SkipReason {
+		case SkipReasonBotIdentity:
+			return "--exclude-muted has no effect under bot identity (mute is a per-user setting, bots have no mute data); returned all results unfiltered. Use --as user to filter."
+		case SkipReasonAllNonMember:
+			if hasMore {
+				return "All results on this page are non-member public groups; mute filter does not apply. Use --page-token to fetch more."
+			}
+			return "All results on this page are non-member public groups; mute filter does not apply. No more pages."
+		}
+		return ""
+	}
+	if meta.FilteredCount == 0 {
+		return ""
+	}
+
+	tail := "no more pages."
+	if hasMore {
+		tail = "use --page-token to fetch more."
+	}
+
+	if meta.UnknownCount > 0 {
+		return fmt.Sprintf("Filtered out %d muted chat(s) on this page (%d remaining, including %d non-member public group(s)); %s",
+			meta.FilteredCount, meta.ReturnedCount, meta.UnknownCount, tail)
+	}
+	return fmt.Sprintf("Filtered out %d muted chat(s) on this page (%d remaining); %s",
+		meta.FilteredCount, meta.ReturnedCount, tail)
+}
+
+// BuildBatchGetMuteStatusBody constructs the request body for
+// POST /open-apis/im/v1/chat_user_setting/batch_get_mute_status.
+func BuildBatchGetMuteStatusBody(chatIDs []string) map[string]interface{} {
+	return map[string]interface{}{"chat_ids": chatIDs}
+}
+
+// ParseBatchGetMuteStatusResponse maps the API response to:
+//   - muted:   chat_id -> is_muted, only for ids returned in items
+//   - unknown: chat_ids that came back in invalid_id_list (any msg) OR
+//     were in input but missing from both lists.
+//
+// unknown preserves input order for stable hint output.
+func ParseBatchGetMuteStatusResponse(input []string, resp map[string]interface{}) (map[string]bool, []string) {
+	muted := make(map[string]bool, len(input))
+	if rawItems, ok := resp["items"].([]interface{}); ok {
+		for _, raw := range rawItems {
+			item, _ := raw.(map[string]interface{})
+			if item == nil {
+				continue
+			}
+			cid, _ := item["chat_id"].(string)
+			if cid == "" {
+				continue
+			}
+			isMuted, _ := item["is_muted"].(bool)
+			muted[cid] = isMuted
+		}
+	}
+
+	unknownSet := make(map[string]struct{})
+	if rawInvalid, ok := resp["invalid_id_list"].([]interface{}); ok {
+		for _, raw := range rawInvalid {
+			item, _ := raw.(map[string]interface{})
+			if item == nil {
+				continue
+			}
+			id, _ := item["id"].(string)
+			if id != "" {
+				unknownSet[id] = struct{}{}
+			}
+		}
+	}
+	for _, id := range input {
+		if _, hasMute := muted[id]; hasMute {
+			continue
+		}
+		unknownSet[id] = struct{}{}
+	}
+
+	unknown := make([]string, 0, len(unknownSet))
+	for _, id := range input {
+		if _, ok := unknownSet[id]; ok {
+			unknown = append(unknown, id)
+			delete(unknownSet, id) // dedupe while preserving input order
+		}
+	}
+	return muted, unknown
+}
+
+// ApplyMuteFilter drops chats whose mute map entry is true. Chats whose id
+// is in the unknown set, or which have no chatIDKey value, are retained
+// (we have no basis to filter them) and counted as UnknownCount.
+//
+// Pure function; no API calls. The caller is responsible for fetching the
+// mute map via FetchMuteStatus.
+//
+// Invariant: meta.FetchedCount == meta.ReturnedCount + meta.FilteredCount.
+func ApplyMuteFilter(
+	chats []map[string]interface{},
+	chatIDKey string,
+	muted map[string]bool,
+	unknown []string,
+) ([]map[string]interface{}, MuteFilterMeta) {
+	unknownSet := make(map[string]struct{}, len(unknown))
+	for _, id := range unknown {
+		unknownSet[id] = struct{}{}
+	}
+
+	out := make([]map[string]interface{}, 0, len(chats))
+	meta := MuteFilterMeta{Applied: "exclude_muted", FetchedCount: len(chats)}
+
+	for _, row := range chats {
+		cid, _ := row[chatIDKey].(string)
+		if cid == "" {
+			out = append(out, row)
+			meta.UnknownCount++
+			continue
+		}
+		if _, isUnknown := unknownSet[cid]; isUnknown {
+			out = append(out, row)
+			meta.UnknownCount++
+			continue
+		}
+		if isMuted, ok := muted[cid]; ok {
+			if isMuted {
+				meta.FilteredCount++
+				continue
+			}
+			out = append(out, row)
+			continue
+		}
+		// Defensive: id not in muted, not in unknown — treat as unknown, retain.
+		out = append(out, row)
+		meta.UnknownCount++
+	}
+	meta.ReturnedCount = len(out)
+	return out, meta
+}
+
+// ExtractChatIDs collects unique chat_ids (in input order) from a page of rows.
+// Rows missing the key or with an empty value are skipped.
+func ExtractChatIDs(chats []map[string]interface{}, chatIDKey string) []string {
+	if len(chats) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(chats))
+	out := make([]string, 0, len(chats))
+	for _, row := range chats {
+		cid, _ := row[chatIDKey].(string)
+		if cid == "" {
+			continue
+		}
+		if _, dup := seen[cid]; dup {
+			continue
+		}
+		seen[cid] = struct{}{}
+		out = append(out, cid)
+	}
+	return out
+}
+
+// MuteFilterMetaToMap renders the meta as the "filter" sub-object the
+// command writes into outData. The schema is fixed-shape: exactly 5 fields,
+// regardless of skip state.
+//
+// Skip context (bot identity / all-non-member search-types) is encoded
+// entirely in the Hint string — consumers read the natural-language hint
+// to understand why the filter did or did not apply. UnknownCount and the
+// Skipped / SkipReason struct fields are internal-only (used to compose
+// Hint) and are not exposed in JSON.
+func MuteFilterMetaToMap(meta MuteFilterMeta) map[string]interface{} {
+	return map[string]interface{}{
+		"applied":        meta.Applied,
+		"fetched_count":  meta.FetchedCount,
+		"returned_count": meta.ReturnedCount,
+		"filtered_count": meta.FilteredCount,
+		"hint":           meta.Hint,
+	}
+}
+
+// FetchMuteStatus calls batch_get_mute_status for the given chat_ids and
+// parses the result. Caller MUST ensure len(chatIDs) <= MaxMuteStatusBatchSize
+// (the shortcuts already cap --page-size at 100, so a single page is safe).
+//
+// Empty input is a no-op (avoids triggering the upstream "chat_ids is empty"
+// InvalidParam).
+func FetchMuteStatus(runtime *common.RuntimeContext, chatIDs []string) (map[string]bool, []string, error) {
+	if len(chatIDs) == 0 {
+		return map[string]bool{}, nil, nil
+	}
+	if len(chatIDs) > MaxMuteStatusBatchSize {
+		return nil, nil, output.ErrValidation(
+			"batch_get_mute_status accepts at most %d chat_ids per call (got %d)",
+			MaxMuteStatusBatchSize, len(chatIDs))
+	}
+	body := BuildBatchGetMuteStatusBody(chatIDs)
+	resp, err := runtime.CallAPI("POST", BatchGetMuteStatusPath, nil, body)
+	if err != nil {
+		return nil, nil, fmt.Errorf("fetch mute status: %w", err)
+	}
+	muted, unknown := ParseBatchGetMuteStatusResponse(chatIDs, resp)
+	return muted, unknown, nil
+}
+
+// MuteFilterInput captures everything the orchestrator needs from the calling shortcut.
+type MuteFilterInput struct {
+	ExcludeMuted  bool                     // value of --exclude-muted
+	IsBot         bool                     // current identity
+	PreSkipReason string                   // optional caller-supplied skip reason (e.g. SkipReasonAllNonMember); leave empty under bot — IsBot is handled separately
+	Chats         []map[string]interface{} // page of result rows
+	ChatIDKey     string                   // key in row holding the chat_id ("chat_id" for both v1 list and v2 search meta_data)
+	HasMore       bool                     // for hint composition
+}
+
+// MuteFilterOutput is what the shortcut writes back into outData.
+type MuteFilterOutput struct {
+	Chats []map[string]interface{} // filtered (or unchanged when not applied)
+	Meta  MuteFilterMeta           // zero-valued when ExcludeMuted=false; callers detect via Meta.Applied != ""
+}
+
+// MaybeApplyMuteFilter is the single entry point shortcuts call.
+//
+// Behavior:
+//   - ExcludeMuted=false: returns chats unchanged, Meta is zero-valued (Applied=="")
+//   - ExcludeMuted=true && IsBot:  skip the API call, mark Skipped with SkipReasonBotIdentity
+//   - ExcludeMuted=true && PreSkipReason!="" (not bot): skip the API call, mark Skipped with that reason
+//   - ExcludeMuted=true && len(chats)==0: skip the API call (avoids upstream
+//     InvalidParam on empty chat_ids); meta has zero counts, Skipped=false
+//   - ExcludeMuted=true && otherwise: fetch + apply; populate counts and Hint
+//
+// Callers detect whether the filter ran via out.Meta.Applied != "".
+// Callers compose the JSON map via MuteFilterMetaToMap(out.Meta) at the use site.
+func MaybeApplyMuteFilter(runtime *common.RuntimeContext, in MuteFilterInput) (MuteFilterOutput, error) {
+	if !in.ExcludeMuted {
+		return MuteFilterOutput{Chats: in.Chats}, nil
+	}
+
+	meta := MuteFilterMeta{
+		Applied:       "exclude_muted",
+		FetchedCount:  len(in.Chats),
+		ReturnedCount: len(in.Chats),
+	}
+
+	switch {
+	case in.IsBot:
+		meta.Skipped = true
+		meta.SkipReason = SkipReasonBotIdentity
+	case in.PreSkipReason != "":
+		meta.Skipped = true
+		meta.SkipReason = in.PreSkipReason
+	case len(in.Chats) == 0:
+		// counts already zero; Skipped stays false
+	default:
+		ids := ExtractChatIDs(in.Chats, in.ChatIDKey)
+		muted, unknown, err := FetchMuteStatus(runtime, ids)
+		if err != nil {
+			return MuteFilterOutput{}, err
+		}
+		var filtered []map[string]interface{}
+		filtered, meta = ApplyMuteFilter(in.Chats, in.ChatIDKey, muted, unknown)
+		in.Chats = filtered
+	}
+
+	meta.Hint = BuildMuteFilterHint(meta, in.HasMore)
+	return MuteFilterOutput{
+		Chats: in.Chats,
+		Meta:  meta,
+	}, nil
+}

shortcuts/im/mute_filter_test.go

@@ -0,0 +1,445 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package im
+
+import (
+	"fmt"
+	"reflect"
+	"testing"
+
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+func TestBuildMuteFilterHint(t *testing.T) {
+	cases := []struct {
+		name    string
+		meta    MuteFilterMeta
+		hasMore bool
+		want    string
+	}{
+		{
+			name:    "1 skipped bot identity",
+			meta:    MuteFilterMeta{Applied: "exclude_muted", Skipped: true, SkipReason: SkipReasonBotIdentity},
+			hasMore: false,
+			want:    "--exclude-muted has no effect under bot identity (mute is a per-user setting, bots have no mute data); returned all results unfiltered. Use --as user to filter.",
+		},
+		{
+			name:    "2 skipped all non-member, has_more",
+			meta:    MuteFilterMeta{Applied: "exclude_muted", Skipped: true, SkipReason: SkipReasonAllNonMember},
+			hasMore: true,
+			want:    "All results on this page are non-member public groups; mute filter does not apply. Use --page-token to fetch more.",
+		},
+		{
+			name:    "3 skipped all non-member, no more",
+			meta:    MuteFilterMeta{Applied: "exclude_muted", Skipped: true, SkipReason: SkipReasonAllNonMember},
+			hasMore: false,
+			want:    "All results on this page are non-member public groups; mute filter does not apply. No more pages.",
+		},
+		{
+			name:    "4 filtered>0 unknown=0 has_more",
+			meta:    MuteFilterMeta{Applied: "exclude_muted", FetchedCount: 20, ReturnedCount: 17, FilteredCount: 3},
+			hasMore: true,
+			want:    "Filtered out 3 muted chat(s) on this page (17 remaining); use --page-token to fetch more.",
+		},
+		{
+			name:    "5 filtered>0 unknown=0 no more",
+			meta:    MuteFilterMeta{Applied: "exclude_muted", FetchedCount: 20, ReturnedCount: 17, FilteredCount: 3},
+			hasMore: false,
+			want:    "Filtered out 3 muted chat(s) on this page (17 remaining); no more pages.",
+		},
+		{
+			name:    "6 filtered>0 unknown>0 has_more",
+			meta:    MuteFilterMeta{Applied: "exclude_muted", FetchedCount: 20, ReturnedCount: 19, FilteredCount: 1, UnknownCount: 2},
+			hasMore: true,
+			want:    "Filtered out 1 muted chat(s) on this page (19 remaining, including 2 non-member public group(s)); use --page-token to fetch more.",
+		},
+		{
+			name:    "7 filtered>0 unknown>0 no more",
+			meta:    MuteFilterMeta{Applied: "exclude_muted", FetchedCount: 20, ReturnedCount: 19, FilteredCount: 1, UnknownCount: 2},
+			hasMore: false,
+			want:    "Filtered out 1 muted chat(s) on this page (19 remaining, including 2 non-member public group(s)); no more pages.",
+		},
+		{
+			name:    "8 filtered=0 returns empty regardless of unknown/hasMore",
+			meta:    MuteFilterMeta{Applied: "exclude_muted", FetchedCount: 5, ReturnedCount: 5, UnknownCount: 2},
+			hasMore: true,
+			want:    "",
+		},
+		{
+			name:    "9 skipped with unrecognized reason returns empty",
+			meta:    MuteFilterMeta{Applied: "exclude_muted", Skipped: true, SkipReason: "unknown_reason"},
+			hasMore: false,
+			want:    "",
+		},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got := BuildMuteFilterHint(c.meta, c.hasMore)
+			if got != c.want {
+				t.Fatalf("BuildMuteFilterHint() = %q, want %q", got, c.want)
+			}
+		})
+	}
+}
+
+func TestBuildBatchGetMuteStatusBody(t *testing.T) {
+	got := BuildBatchGetMuteStatusBody([]string{"oc_a", "oc_b"})
+	want := map[string]interface{}{"chat_ids": []string{"oc_a", "oc_b"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("BuildBatchGetMuteStatusBody() = %v, want %v", got, want)
+	}
+}
+
+func TestParseBatchGetMuteStatusResponse(t *testing.T) {
+	t.Run("happy path with mixed muted/non-muted/invalid", func(t *testing.T) {
+		input := []string{"oc_a", "oc_b", "oc_c", "bad"}
+		resp := map[string]interface{}{
+			"items": []interface{}{
+				map[string]interface{}{"chat_id": "oc_a", "is_muted": true},
+				map[string]interface{}{"chat_id": "oc_b", "is_muted": false},
+			},
+			"invalid_id_list": []interface{}{
+				map[string]interface{}{"id": "oc_c", "msg": "not_a_member"},
+				map[string]interface{}{"id": "bad", "msg": "invalid_format"},
+			},
+		}
+		muted, unknown := ParseBatchGetMuteStatusResponse(input, resp)
+		wantMuted := map[string]bool{"oc_a": true, "oc_b": false}
+		wantUnknown := []string{"oc_c", "bad"}
+		if !reflect.DeepEqual(muted, wantMuted) {
+			t.Fatalf("muted = %v, want %v", muted, wantMuted)
+		}
+		if !reflect.DeepEqual(unknown, wantUnknown) {
+			t.Fatalf("unknown = %v, want %v", unknown, wantUnknown)
+		}
+	})
+
+	t.Run("missing chat_ids fall through to unknown", func(t *testing.T) {
+		input := []string{"oc_a", "oc_b"}
+		resp := map[string]interface{}{
+			"items": []interface{}{
+				map[string]interface{}{"chat_id": "oc_a", "is_muted": true},
+			},
+		}
+		muted, unknown := ParseBatchGetMuteStatusResponse(input, resp)
+		if !reflect.DeepEqual(muted, map[string]bool{"oc_a": true}) {
+			t.Fatalf("muted = %v", muted)
+		}
+		if !reflect.DeepEqual(unknown, []string{"oc_b"}) {
+			t.Fatalf("unknown = %v", unknown)
+		}
+	})
+
+	t.Run("empty response yields all unknown", func(t *testing.T) {
+		input := []string{"oc_a"}
+		muted, unknown := ParseBatchGetMuteStatusResponse(input, map[string]interface{}{})
+		if len(muted) != 0 {
+			t.Fatalf("muted = %v, want empty", muted)
+		}
+		if !reflect.DeepEqual(unknown, []string{"oc_a"}) {
+			t.Fatalf("unknown = %v", unknown)
+		}
+	})
+
+	t.Run("skips nil entries and empty chat_id in items/invalid_id_list", func(t *testing.T) {
+		input := []string{"oc_a", "oc_b"}
+		resp := map[string]interface{}{
+			"items": []interface{}{
+				nil,
+				map[string]interface{}{"chat_id": "", "is_muted": false},
+				map[string]interface{}{"chat_id": "oc_a", "is_muted": true},
+			},
+			"invalid_id_list": []interface{}{
+				nil,
+				map[string]interface{}{"id": "oc_b", "msg": "not_a_member"},
+			},
+		}
+		muted, unknown := ParseBatchGetMuteStatusResponse(input, resp)
+		if !reflect.DeepEqual(muted, map[string]bool{"oc_a": true}) {
+			t.Fatalf("muted = %v", muted)
+		}
+		if !reflect.DeepEqual(unknown, []string{"oc_b"}) {
+			t.Fatalf("unknown = %v", unknown)
+		}
+	})
+}
+
+func TestApplyMuteFilter(t *testing.T) {
+	chats := []map[string]interface{}{
+		{"chat_id": "oc_a", "name": "alpha"},
+		{"chat_id": "oc_b", "name": "beta"},
+		{"chat_id": "oc_c", "name": "gamma"},
+		{"chat_id": "oc_d", "name": "delta"},
+	}
+
+	t.Run("drops only is_muted=true", func(t *testing.T) {
+		muted := map[string]bool{"oc_a": true, "oc_b": false, "oc_c": true, "oc_d": false}
+		got, meta := ApplyMuteFilter(chats, "chat_id", muted, nil)
+		if len(got) != 2 {
+			t.Fatalf("len(got) = %d, want 2", len(got))
+		}
+		if got[0]["chat_id"] != "oc_b" || got[1]["chat_id"] != "oc_d" {
+			t.Fatalf("got = %v, want [oc_b, oc_d]", got)
+		}
+		want := MuteFilterMeta{
+			Applied: "exclude_muted", FetchedCount: 4, ReturnedCount: 2, FilteredCount: 2, UnknownCount: 0,
+		}
+		if meta != want {
+			t.Fatalf("meta = %+v, want %+v", meta, want)
+		}
+	})
+
+	t.Run("retains unknown chats and counts them", func(t *testing.T) {
+		muted := map[string]bool{"oc_a": true, "oc_b": false}
+		unknown := []string{"oc_c", "oc_d"}
+		got, meta := ApplyMuteFilter(chats, "chat_id", muted, unknown)
+		if len(got) != 3 {
+			t.Fatalf("len(got) = %d, want 3 (oc_b + oc_c + oc_d)", len(got))
+		}
+		if meta.FilteredCount != 1 || meta.UnknownCount != 2 || meta.ReturnedCount != 3 {
+			t.Fatalf("meta = %+v, want filtered=1 unknown=2 returned=3", meta)
+		}
+	})
+
+	t.Run("preserves original order", func(t *testing.T) {
+		muted := map[string]bool{"oc_b": true}
+		got, _ := ApplyMuteFilter(chats, "chat_id", muted, []string{"oc_c", "oc_d"})
+		gotIDs := []string{}
+		for _, r := range got {
+			gotIDs = append(gotIDs, r["chat_id"].(string))
+		}
+		want := []string{"oc_a", "oc_c", "oc_d"}
+		if !reflect.DeepEqual(gotIDs, want) {
+			t.Fatalf("ordering = %v, want %v", gotIDs, want)
+		}
+	})
+
+	t.Run("missing chatIDKey treated as unknown but kept", func(t *testing.T) {
+		bad := []map[string]interface{}{{"name": "no_id"}}
+		got, meta := ApplyMuteFilter(bad, "chat_id", map[string]bool{}, nil)
+		if len(got) != 1 {
+			t.Fatalf("missing-id row should be retained, got len = %d", len(got))
+		}
+		if meta.UnknownCount != 1 || meta.FilteredCount != 0 || meta.ReturnedCount != 1 {
+			t.Fatalf("meta = %+v, want unknown=1 filtered=0 returned=1", meta)
+		}
+	})
+
+	t.Run("invariant fetched == returned + filtered", func(t *testing.T) {
+		muted := map[string]bool{"oc_a": true, "oc_b": false}
+		_, meta := ApplyMuteFilter(chats, "chat_id", muted, []string{"oc_c", "oc_d"})
+		if meta.FetchedCount != meta.ReturnedCount+meta.FilteredCount {
+			t.Fatalf("invariant broken: fetched=%d, returned=%d, filtered=%d",
+				meta.FetchedCount, meta.ReturnedCount, meta.FilteredCount)
+		}
+	})
+}
+
+func TestExtractChatIDs(t *testing.T) {
+	t.Run("dedupes and preserves order", func(t *testing.T) {
+		chats := []map[string]interface{}{
+			{"chat_id": "oc_a"},
+			{"chat_id": "oc_b"},
+			{"chat_id": "oc_a"},
+			{"chat_id": ""},
+			{"name": "no_id"},
+			{"chat_id": "oc_c"},
+		}
+		got := ExtractChatIDs(chats, "chat_id")
+		want := []string{"oc_a", "oc_b", "oc_c"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("ExtractChatIDs() = %v, want %v", got, want)
+		}
+	})
+
+	t.Run("empty input yields empty slice", func(t *testing.T) {
+		got := ExtractChatIDs(nil, "chat_id")
+		if len(got) != 0 {
+			t.Fatalf("ExtractChatIDs(nil) = %v, want empty", got)
+		}
+	})
+}
+
+func TestMuteFilterMetaToMap(t *testing.T) {
+	wantKeys := []string{"applied", "fetched_count", "returned_count", "filtered_count", "hint"}
+
+	t.Run("active filter exposes exactly 5 fields", func(t *testing.T) {
+		meta := MuteFilterMeta{
+			Applied:      "exclude_muted",
+			FetchedCount: 20, ReturnedCount: 19, FilteredCount: 1, UnknownCount: 2,
+			Hint: "test hint",
+		}
+		got := MuteFilterMetaToMap(meta)
+		if got["applied"] != "exclude_muted" ||
+			got["fetched_count"] != 20 || got["returned_count"] != 19 ||
+			got["filtered_count"] != 1 || got["hint"] != "test hint" {
+			t.Fatalf("MuteFilterMetaToMap() = %v", got)
+		}
+		assertExactKeys(t, got, wantKeys)
+	})
+
+	t.Run("skipped path: hint carries the skip explanation, no extra fields", func(t *testing.T) {
+		meta := MuteFilterMeta{
+			Applied: "exclude_muted", Skipped: true, SkipReason: SkipReasonBotIdentity,
+			FetchedCount: 5, ReturnedCount: 5, Hint: "skipped hint",
+		}
+		got := MuteFilterMetaToMap(meta)
+		if got["hint"] != "skipped hint" {
+			t.Fatalf("hint = %v, want \"skipped hint\"", got["hint"])
+		}
+		assertExactKeys(t, got, wantKeys)
+	})
+}
+
+// assertExactKeys fails the test if got has any keys outside want, or is missing any.
+func assertExactKeys(t *testing.T, got map[string]interface{}, want []string) {
+	t.Helper()
+	wantSet := make(map[string]struct{}, len(want))
+	for _, k := range want {
+		wantSet[k] = struct{}{}
+		if _, ok := got[k]; !ok {
+			t.Errorf("missing required key %q", k)
+		}
+	}
+	for k := range got {
+		if _, ok := wantSet[k]; !ok {
+			t.Errorf("unexpected key %q in MuteFilterMetaToMap output (got %v)", k, got)
+		}
+	}
+}
+
+// runtimeForOrchestrator builds a minimal RuntimeContext for testing the
+// branches of MaybeApplyMuteFilter that do NOT call the underlying API.
+func runtimeForOrchestrator(t *testing.T) *common.RuntimeContext {
+	t.Helper()
+	cmd := &cobra.Command{Use: "test"}
+	if err := cmd.ParseFlags(nil); err != nil {
+		t.Fatalf("ParseFlags: %v", err)
+	}
+	return &common.RuntimeContext{Cmd: cmd}
+}
+
+func TestMaybeApplyMuteFilter_NotEnabled(t *testing.T) {
+	rt := runtimeForOrchestrator(t)
+	chats := []map[string]interface{}{{"chat_id": "oc_a"}}
+	out, err := MaybeApplyMuteFilter(rt, MuteFilterInput{
+		ExcludeMuted: false,
+		Chats:        chats,
+		ChatIDKey:    "chat_id",
+	})
+	if err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	if len(out.Chats) != 1 || out.Meta.Applied != "" {
+		t.Fatalf("expected pass-through, got chats=%v meta.applied=%q", out.Chats, out.Meta.Applied)
+	}
+}
+
+func TestMaybeApplyMuteFilter_BotIdentity(t *testing.T) {
+	rt := runtimeForOrchestrator(t)
+	chats := []map[string]interface{}{
+		{"chat_id": "oc_a"},
+		{"chat_id": "oc_b"},
+	}
+	out, err := MaybeApplyMuteFilter(rt, MuteFilterInput{
+		ExcludeMuted: true,
+		IsBot:        true,
+		Chats:        chats,
+		ChatIDKey:    "chat_id",
+		HasMore:      false,
+	})
+	if err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	if len(out.Chats) != 2 {
+		t.Fatalf("bot skip should retain all chats, got %d", len(out.Chats))
+	}
+	if !out.Meta.Skipped {
+		t.Fatalf("skipped should be true, got meta=%+v", out.Meta)
+	}
+	if out.Meta.SkipReason != SkipReasonBotIdentity {
+		t.Fatalf("skip_reason = %v", out.Meta.SkipReason)
+	}
+	wantHint := "--exclude-muted has no effect under bot identity (mute is a per-user setting, bots have no mute data); returned all results unfiltered. Use --as user to filter."
+	if out.Meta.Hint != wantHint {
+		t.Fatalf("hint = %q", out.Meta.Hint)
+	}
+}
+
+func TestMaybeApplyMuteFilter_PreSkipAllNonMember(t *testing.T) {
+	rt := runtimeForOrchestrator(t)
+	chats := []map[string]interface{}{
+		{"chat_id": "oc_a"},
+		{"chat_id": "oc_b"},
+	}
+	out, err := MaybeApplyMuteFilter(rt, MuteFilterInput{
+		ExcludeMuted:  true,
+		IsBot:         false,
+		PreSkipReason: SkipReasonAllNonMember,
+		Chats:         chats,
+		ChatIDKey:     "chat_id",
+		HasMore:       true,
+	})
+	if err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	if len(out.Chats) != 2 {
+		t.Fatalf("pre-skip should retain all chats, got %d", len(out.Chats))
+	}
+	if !out.Meta.Skipped || out.Meta.SkipReason != SkipReasonAllNonMember {
+		t.Fatalf("meta = %+v", out.Meta)
+	}
+	wantHint := "All results on this page are non-member public groups; mute filter does not apply. Use --page-token to fetch more."
+	if out.Meta.Hint != wantHint {
+		t.Fatalf("hint = %q", out.Meta.Hint)
+	}
+}
+
+func TestMaybeApplyMuteFilter_EmptyPage(t *testing.T) {
+	rt := runtimeForOrchestrator(t)
+	out, err := MaybeApplyMuteFilter(rt, MuteFilterInput{
+		ExcludeMuted: true,
+		Chats:        nil,
+		ChatIDKey:    "chat_id",
+	})
+	if err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	if len(out.Chats) != 0 {
+		t.Fatalf("expected empty out, got %v", out.Chats)
+	}
+	if out.Meta.Applied != "exclude_muted" {
+		t.Fatalf("meta.applied = %q, want exclude_muted", out.Meta.Applied)
+	}
+	if out.Meta.FetchedCount != 0 || out.Meta.ReturnedCount != 0 || out.Meta.FilteredCount != 0 {
+		t.Fatalf("counts should all be zero, got meta=%+v", out.Meta)
+	}
+	if out.Meta.Skipped {
+		t.Fatalf("empty page is not 'skipped', got meta.skipped=%v", out.Meta.Skipped)
+	}
+}
+
+func TestFetchMuteStatus_OverLimit(t *testing.T) {
+	rt := runtimeForOrchestrator(t)
+	ids := make([]string, MaxMuteStatusBatchSize+1)
+	for i := range ids {
+		ids[i] = fmt.Sprintf("oc_%d", i)
+	}
+	_, _, err := FetchMuteStatus(rt, ids)
+	if err == nil {
+		t.Fatalf("expected error on over-limit batch")
+	}
+}
+
+func TestFetchMuteStatus_Empty(t *testing.T) {
+	rt := runtimeForOrchestrator(t)
+	muted, unknown, err := FetchMuteStatus(rt, nil)
+	if err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	if len(muted) != 0 || len(unknown) != 0 {
+		t.Fatalf("expected empty results, got muted=%v unknown=%v", muted, unknown)
+	}
+}

shortcuts/im/shortcuts.go

@@ -9,6 +9,7 @@ import "github.com/larksuite/cli/shortcuts/common"
 func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		ImChatCreate,
+		ImChatList,
 		ImChatMessageList,
 		ImChatSearch,
 		ImChatUpdate,

shortcuts/mail/flag_suggest.go

@@ -0,0 +1,288 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"github.com/larksuite/cli/internal/output"
+)
+
+// flagName is a package-private snapshot of a pflag.Flag's identity.
+type flagName struct {
+	long, short string
+	hidden      bool
+}
+
+// Candidate is a single suggested flag returned to the user when an
+// unknown flag is detected. It is serialised into the ErrorEnvelope's
+// error.detail.candidates[] array.
+type Candidate struct {
+	// Flag is the long-form spelling of the suggested flag, e.g. "--to".
+	Flag string `json:"flag"`
+	// Shorthand is the single-character shorthand (without the leading
+	// dash) when the suggested flag has one; empty otherwise.
+	Shorthand string `json:"shorthand,omitempty"`
+	// Distance is the Levenshtein edit distance to the unknown token.
+	// Zero indicates a bidirectional prefix hit (Reason == "prefix").
+	Distance int `json:"distance"`
+	// Reason explains how the candidate was matched: "prefix" for
+	// bidirectional prefix hits, "edit_distance" for fuzzy matches.
+	Reason string `json:"reason"`
+}
+
+// maxCandidates caps the number of suggestions returned per error so
+// the JSON envelope stays compact and the user-visible hint remains
+// scannable.
+const maxCandidates = 5
+
+// InstallOnMail attaches the unknown-flag fuzzy-match hook on the mail
+// service cobra parent command. It is invoked exactly once from
+// shortcuts/register.go inside the `service == "mail"` branch.
+//
+// Cobra's FlagErrorFunc walks up the parent chain looking for the nearest
+// non-nil hook, so every mail subcommand inherits this behaviour without
+// any per-shortcut wiring.
+func InstallOnMail(svc *cobra.Command) {
+	if svc == nil {
+		return
+	}
+	svc.SetFlagErrorFunc(flagSuggestErrorFunc)
+}
+
+// flagSuggestErrorFunc converts pflag's unknown-flag errors into a
+// structured *output.ExitError carrying candidate suggestions. Any other
+// error is passed through unchanged so cobra's existing handling kicks in.
+func flagSuggestErrorFunc(c *cobra.Command, err error) error {
+	if err == nil {
+		return nil
+	}
+	token, isShorthand, ok := parseUnknownToken(err.Error())
+	if !ok {
+		// Non unknown-flag errors (e.g. "required flag(s) ... not set")
+		// pass through to cmd/root.go::handleRootError's fallback path.
+		return err
+	}
+	names := collectFlags(c)
+	var matches []Candidate
+	if isShorthand {
+		matches = suggestShorthand(token, names)
+	} else {
+		matches = suggest(token, names)
+	}
+	// Normalise to a non-nil slice so the JSON envelope always emits
+	// `candidates: []` instead of `null`, keeping the wire shape stable
+	// for downstream parsers regardless of command-state.
+	if matches == nil {
+		matches = []Candidate{}
+	}
+	hint := buildHint(c, matches)
+	detail := map[string]any{
+		"unknown":      rawUnknownToken(token, isShorthand),
+		"command_path": c.CommandPath(),
+		"candidates":   matches,
+	}
+	// Code is ExitAPI (=1), matching cobra's default unknown-flag exit
+	// code. The structured type discrimination lives in error.type.
+	return &output.ExitError{
+		Code: output.ExitAPI,
+		Detail: &output.ErrDetail{
+			Type:    "unknown_flag",
+			Message: err.Error(),
+			Hint:    hint,
+			Detail:  detail,
+		},
+	}
+}
+
+// parseUnknownToken extracts the offending flag name from a pflag error
+// string. Recognised forms:
+//
+//   - "unknown flag: --tos"
+//   - "unknown flag: --bogus=val"
+//   - "unknown shorthand flag: 'X' in -Xyz"
+//
+// Anything else returns (_, _, false) so the caller can pass the error
+// through unchanged.
+func parseUnknownToken(errMsg string) (token string, isShorthand bool, ok bool) {
+	const longPrefix = "unknown flag: --"
+	const shortPrefix = "unknown shorthand flag: '"
+	switch {
+	case strings.HasPrefix(errMsg, longPrefix):
+		rest := errMsg[len(longPrefix):]
+		if eq := strings.IndexAny(rest, "= \t"); eq >= 0 {
+			rest = rest[:eq]
+		}
+		return rest, false, rest != ""
+	case strings.HasPrefix(errMsg, shortPrefix):
+		rest := errMsg[len(shortPrefix):]
+		end := strings.IndexByte(rest, '\'')
+		if end <= 0 {
+			return "", false, false
+		}
+		return rest[:end], true, true
+	}
+	return "", false, false
+}
+
+// rawUnknownToken re-attaches the leading dash(es) to a bare token so the
+// JSON envelope echoes the user-visible spelling.
+func rawUnknownToken(token string, isShorthand bool) string {
+	if isShorthand {
+		return "-" + token
+	}
+	return "--" + token
+}
+
+// collectFlags snapshots the merged local + persistent + inherited flag
+// set of cmd. The hidden bit is preserved on each entry; the suggest
+// helpers apply the actual filter so the slice stays reusable.
+func collectFlags(cmd *cobra.Command) []flagName {
+	if cmd == nil {
+		return nil
+	}
+	var out []flagName
+	cmd.Flags().VisitAll(func(f *pflag.Flag) {
+		out = append(out, flagName{long: f.Name, short: f.Shorthand, hidden: f.Hidden})
+	})
+	return out
+}
+
+// suggest produces top-N long-flag candidates for an unknown token, using
+// bidirectional prefix matching first and Levenshtein distance for the
+// remainder. Hidden flags and empty long names are skipped. Results are
+// stably sorted by (Distance asc, Flag asc) and capped at maxCandidates.
+func suggest(unknown string, names []flagName) []Candidate {
+	if unknown == "" || len(names) == 0 {
+		return nil
+	}
+	threshold := levThreshold(unknown)
+	out := make([]Candidate, 0, len(names))
+	seen := make(map[string]struct{}, len(names))
+
+	// Priority 1: bidirectional prefix match.
+	for _, n := range names {
+		if n.hidden || n.long == "" {
+			continue
+		}
+		if strings.HasPrefix(n.long, unknown) || strings.HasPrefix(unknown, n.long) {
+			out = append(out, Candidate{Flag: "--" + n.long, Shorthand: n.short, Distance: 0, Reason: "prefix"})
+			seen[n.long] = struct{}{}
+		}
+	}
+	// Priority 2: Levenshtein distance, skipping already-matched names.
+	for _, n := range names {
+		if n.hidden || n.long == "" {
+			continue
+		}
+		if _, ok := seen[n.long]; ok {
+			continue
+		}
+		if d := levenshtein(unknown, n.long); d <= threshold {
+			out = append(out, Candidate{Flag: "--" + n.long, Shorthand: n.short, Distance: d, Reason: "edit_distance"})
+		}
+	}
+	sort.SliceStable(out, func(i, j int) bool {
+		if out[i].Distance != out[j].Distance {
+			return out[i].Distance < out[j].Distance
+		}
+		return out[i].Flag < out[j].Flag
+	})
+	if len(out) > maxCandidates {
+		out = out[:maxCandidates]
+	}
+	return out
+}
+
+// suggestShorthand produces candidates for an unknown single-character
+// shorthand. It first looks for exact f.Shorthand matches; if there are
+// none, it falls back to long names that begin with the same character.
+// Levenshtein is deliberately not used here since single-char edit
+// distance would match almost every flag.
+func suggestShorthand(c string, names []flagName) []Candidate {
+	if c == "" || len(names) == 0 {
+		return nil
+	}
+	out := make([]Candidate, 0)
+	for _, n := range names {
+		if n.hidden {
+			continue
+		}
+		if n.short == c {
+			out = append(out, Candidate{Flag: "--" + n.long, Shorthand: n.short, Distance: 0, Reason: "prefix"})
+		}
+	}
+	if len(out) == 0 {
+		for _, n := range names {
+			if n.hidden || n.long == "" {
+				continue
+			}
+			if strings.HasPrefix(n.long, c) {
+				out = append(out, Candidate{Flag: "--" + n.long, Shorthand: n.short, Distance: 0, Reason: "prefix"})
+			}
+		}
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].Flag < out[j].Flag })
+	if len(out) > maxCandidates {
+		out = out[:maxCandidates]
+	}
+	return out
+}
+
+// buildHint returns a one-line hint suitable for the ErrorEnvelope.
+// When at least one candidate exists, the top hit is named; otherwise
+// the user is directed to --help.
+func buildHint(c *cobra.Command, matches []Candidate) string {
+	if len(matches) == 0 {
+		return fmt.Sprintf("Run `%s --help` to view available flags", c.CommandPath())
+	}
+	return fmt.Sprintf("Did you mean: %s ?", matches[0].Flag)
+}
+
+// levThreshold returns the maximum acceptable Levenshtein distance for a
+// token of the given length, clamped to [1, 4].
+func levThreshold(s string) int {
+	t := len(s)/3 + 1
+	if t < 1 {
+		return 1
+	}
+	if t > 4 {
+		return 4
+	}
+	return t
+}
+
+// levenshtein computes the standard Levenshtein edit distance between
+// two ASCII strings using a 2-row dynamic-programming table.
+func levenshtein(a, b string) int {
+	la, lb := len(a), len(b)
+	if la == 0 {
+		return lb
+	}
+	if lb == 0 {
+		return la
+	}
+	prev := make([]int, lb+1)
+	curr := make([]int, lb+1)
+	for j := 0; j <= lb; j++ {
+		prev[j] = j
+	}
+	for i := 1; i <= la; i++ {
+		curr[0] = i
+		for j := 1; j <= lb; j++ {
+			cost := 1
+			if a[i-1] == b[j-1] {
+				cost = 0
+			}
+			curr[j] = min(curr[j-1]+1, prev[j]+1, prev[j-1]+cost)
+		}
+		prev, curr = curr, prev
+	}
+	return prev[lb]
+}

shortcuts/mail/flag_suggest_test.go

@@ -0,0 +1,352 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/larksuite/cli/internal/output"
+)
+
+// --- suggest (long-flag) ---
+
+func TestSuggest_Prefix(t *testing.T) {
+	names := []flagName{
+		{long: "to", short: "t"},
+		{long: "cc"},
+		{long: "subject", short: "s"},
+	}
+	got := suggest("tos", names)
+	require.NotEmpty(t, got)
+	// "tos" has --to as a prefix → bidirectional prefix hit, Distance=0.
+	assert.Equal(t, "--to", got[0].Flag)
+	assert.Equal(t, 0, got[0].Distance)
+	assert.Equal(t, "prefix", got[0].Reason)
+}
+
+func TestSuggest_Levenshtein(t *testing.T) {
+	names := []flagName{
+		{long: "subject"},
+		{long: "body"},
+		{long: "to"},
+	}
+	// Distance 1 from "subject".
+	got := suggest("subjec", names)
+	require.NotEmpty(t, got)
+	// "subjec" is prefix of "subject" → bidirectional prefix.
+	assert.Equal(t, "--subject", got[0].Flag)
+	assert.Equal(t, "prefix", got[0].Reason)
+
+	// True edit-distance: "subjeect" is not a prefix either way of "subject".
+	got = suggest("subjeect", names)
+	require.NotEmpty(t, got)
+	assert.Equal(t, "--subject", got[0].Flag)
+	assert.Equal(t, "edit_distance", got[0].Reason)
+	assert.GreaterOrEqual(t, got[0].Distance, 1)
+}
+
+func TestSuggest_HiddenSkipped(t *testing.T) {
+	names := []flagName{
+		{long: "internal-debug", hidden: true},
+		{long: "interactive"},
+	}
+	got := suggest("internal", names)
+	for _, c := range got {
+		assert.NotEqual(t, "--internal-debug", c.Flag, "hidden flag must not appear in suggestions")
+	}
+}
+
+func TestSuggest_TopNAndStableSort(t *testing.T) {
+	// 6 names all within threshold and at the same distance (1) from the
+	// unknown token so that the lexicographic tiebreak and maxCandidates
+	// cap are both exercised. (Earlier the names were 3-distance from
+	// "zzz" which is above the threshold of 2 — suggest returned empty
+	// and the assertions trivially passed.)
+	names := []flagName{
+		{long: "aaab"},
+		{long: "aaac"},
+		{long: "aaad"},
+		{long: "aaae"},
+		{long: "aaaf"},
+		{long: "aaag"},
+	}
+	got := suggest("aaaa", names)
+	require.Len(t, got, maxCandidates, "must cap at maxCandidates")
+	// All distances equal → lex ordering by Flag asc, top 5 alphabetically.
+	wantFlags := []string{"--aaab", "--aaac", "--aaad", "--aaae", "--aaaf"}
+	gotFlags := []string{got[0].Flag, got[1].Flag, got[2].Flag, got[3].Flag, got[4].Flag}
+	assert.Equal(t, wantFlags, gotFlags, "tiebreak must order by Flag asc")
+}
+
+// --- suggestShorthand ---
+
+func TestSuggestShorthand_Exact(t *testing.T) {
+	names := []flagName{
+		{long: "to", short: "t"},
+		{long: "cc", short: "c"},
+		{long: "subject", short: "s"},
+	}
+	got := suggestShorthand("t", names)
+	require.NotEmpty(t, got)
+	assert.Equal(t, "--to", got[0].Flag)
+	assert.Equal(t, "t", got[0].Shorthand)
+	assert.Equal(t, "prefix", got[0].Reason)
+}
+
+func TestSuggestShorthand_PrefixFallback(t *testing.T) {
+	// No short matches "x"; fall back to long names starting with "x".
+	names := []flagName{
+		{long: "xargs"},
+		{long: "xterm"},
+		{long: "yargs"},
+	}
+	got := suggestShorthand("x", names)
+	require.NotEmpty(t, got)
+	flags := make([]string, 0, len(got))
+	for _, c := range got {
+		flags = append(flags, c.Flag)
+	}
+	assert.Contains(t, flags, "--xargs")
+	assert.Contains(t, flags, "--xterm")
+	assert.NotContains(t, flags, "--yargs")
+}
+
+// --- parseUnknownToken ---
+
+func TestParseUnknownToken_Long(t *testing.T) {
+	tok, isShort, ok := parseUnknownToken("unknown flag: --tos")
+	assert.True(t, ok)
+	assert.False(t, isShort)
+	assert.Equal(t, "tos", tok)
+
+	tok, isShort, ok = parseUnknownToken("unknown flag: --bogus=val")
+	assert.True(t, ok)
+	assert.False(t, isShort)
+	assert.Equal(t, "bogus", tok, "must strip =value tail")
+
+	tok, _, ok = parseUnknownToken("unknown flag: --bogus value")
+	assert.True(t, ok)
+	assert.Equal(t, "bogus", tok, "must strip whitespace tail")
+}
+
+func TestParseUnknownToken_Shorthand(t *testing.T) {
+	tok, isShort, ok := parseUnknownToken("unknown shorthand flag: 'X' in -X")
+	assert.True(t, ok)
+	assert.True(t, isShort)
+	assert.Equal(t, "X", tok)
+
+	tok, isShort, ok = parseUnknownToken("unknown shorthand flag: 'q' in -qrs")
+	assert.True(t, ok)
+	assert.True(t, isShort)
+	assert.Equal(t, "q", tok)
+}
+
+func TestParseUnknownToken_NotMatch(t *testing.T) {
+	cases := []string{
+		`required flag(s) "to" not set`,
+		"some unrelated error",
+		"",
+		"unknown command \"foo\" for \"mail\"",
+	}
+	for _, in := range cases {
+		tok, isShort, ok := parseUnknownToken(in)
+		assert.False(t, ok, "input %q must not match", in)
+		assert.False(t, isShort)
+		assert.Equal(t, "", tok)
+	}
+}
+
+// --- flagSuggestErrorFunc ---
+
+// newFakeMailCmd builds a cobra command tree resembling the mail parent
+// with a handful of flags exercised by the hook tests.
+func newFakeMailCmd() *cobra.Command {
+	c := &cobra.Command{Use: "mail"}
+	c.Flags().String("to", "", "recipients")
+	c.Flags().String("cc", "", "cc recipients")
+	c.Flags().String("subject", "", "subject")
+	c.Flags().StringP("body", "b", "", "body")
+	return c
+}
+
+func TestFlagSuggestErrorFunc_LongUnknown_ReturnsExitError(t *testing.T) {
+	cmd := newFakeMailCmd()
+	got := flagSuggestErrorFunc(cmd, errors.New("unknown flag: --tos"))
+
+	var exitErr *output.ExitError
+	require.True(t, errors.As(got, &exitErr), "expected *output.ExitError, got %T", got)
+	require.NotNil(t, exitErr.Detail)
+	assert.Equal(t, "unknown_flag", exitErr.Detail.Type)
+	assert.Equal(t, "unknown flag: --tos", exitErr.Detail.Message)
+	assert.Contains(t, exitErr.Detail.Hint, "--to")
+
+	detail, ok := exitErr.Detail.Detail.(map[string]any)
+	require.True(t, ok, "Detail.Detail should be map[string]any")
+	assert.Equal(t, "--tos", detail["unknown"])
+	assert.Equal(t, cmd.CommandPath(), detail["command_path"])
+
+	cands, ok := detail["candidates"].([]Candidate)
+	require.True(t, ok, "candidates should be []Candidate")
+	require.NotEmpty(t, cands)
+
+	var foundTo bool
+	for _, c := range cands {
+		if c.Flag == "--to" {
+			foundTo = true
+			assert.Equal(t, "prefix", c.Reason)
+			break
+		}
+	}
+	assert.True(t, foundTo, "expected --to in candidates")
+}
+
+func TestFlagSuggestErrorFunc_NotUnknownFlag_PassesThrough(t *testing.T) {
+	cmd := newFakeMailCmd()
+	in := errors.New(`required flag(s) "to" not set`)
+	got := flagSuggestErrorFunc(cmd, in)
+	// Identity passthrough: same error pointer.
+	assert.Same(t, in, got, "non-unknown-flag errors must be returned unchanged")
+}
+
+func TestFlagSuggestErrorFunc_ExitCodeIsOne(t *testing.T) {
+	cmd := newFakeMailCmd()
+	got := flagSuggestErrorFunc(cmd, errors.New("unknown flag: --tos"))
+	var exitErr *output.ExitError
+	require.True(t, errors.As(got, &exitErr))
+	// Hard contract — both compile-time and runtime guards:
+	assert.Equal(t, output.ExitAPI, exitErr.Code, "unknown_flag must use ExitAPI, not ExitValidation")
+	assert.Equal(t, 1, output.ExitAPI, "ExitAPI constant must remain 1")
+}
+
+// --- edge-case coverage ---
+
+func TestInstallOnMail_NilIsNoop(t *testing.T) {
+	// Must not panic; the nil-guard is the contract.
+	InstallOnMail(nil)
+}
+
+func TestInstallOnMail_InstallsHook(t *testing.T) {
+	c := newFakeMailCmd()
+	InstallOnMail(c)
+	require.NotNil(t, c.FlagErrorFunc())
+	got := c.FlagErrorFunc()(c, errors.New("unknown flag: --tos"))
+	var exitErr *output.ExitError
+	require.True(t, errors.As(got, &exitErr), "installed hook must produce *output.ExitError")
+	assert.Equal(t, "unknown_flag", exitErr.Detail.Type)
+}
+
+func TestFlagSuggestErrorFunc_NilError(t *testing.T) {
+	cmd := newFakeMailCmd()
+	assert.NoError(t, flagSuggestErrorFunc(cmd, nil))
+}
+
+func TestFlagSuggestErrorFunc_LongUnknown_StripsValueTail(t *testing.T) {
+	cmd := newFakeMailCmd()
+	got := flagSuggestErrorFunc(cmd, errors.New("unknown flag: --tos=alice@example.com"))
+	var exitErr *output.ExitError
+	require.True(t, errors.As(got, &exitErr))
+	detail := exitErr.Detail.Detail.(map[string]any)
+	assert.Equal(t, "--tos", detail["unknown"], "value tail must be stripped before echoing")
+}
+
+func TestFlagSuggestErrorFunc_ShorthandUnknown(t *testing.T) {
+	cmd := newFakeMailCmd()
+	got := flagSuggestErrorFunc(cmd, errors.New("unknown shorthand flag: 'b' in -bXY"))
+	var exitErr *output.ExitError
+	require.True(t, errors.As(got, &exitErr))
+	detail := exitErr.Detail.Detail.(map[string]any)
+	assert.Equal(t, "-b", detail["unknown"])
+	cands, ok := detail["candidates"].([]Candidate)
+	require.True(t, ok)
+	// newFakeMailCmd has --body/-b; exact shorthand hit expected.
+	require.NotEmpty(t, cands)
+	assert.Equal(t, "--body", cands[0].Flag)
+	assert.Equal(t, "b", cands[0].Shorthand)
+}
+
+func TestFlagSuggestErrorFunc_CandidatesAlwaysArray(t *testing.T) {
+	// A cobra command with no flags forces collectFlags → empty names →
+	// suggest → nil. The envelope must still expose candidates as a
+	// non-nil []Candidate so the JSON wire shape is "candidates: []"
+	// rather than "candidates: null".
+	bare := &cobra.Command{Use: "mail"}
+	got := flagSuggestErrorFunc(bare, errors.New("unknown flag: --bogus"))
+	var exitErr *output.ExitError
+	require.True(t, errors.As(got, &exitErr))
+	detail := exitErr.Detail.Detail.(map[string]any)
+	cands, ok := detail["candidates"].([]Candidate)
+	require.True(t, ok, "candidates must be []Candidate even when empty")
+	assert.NotNil(t, cands, "candidates must be non-nil empty slice, not nil")
+	assert.Empty(t, cands)
+}
+
+func TestFlagSuggestErrorFunc_NoCandidatesUsesHelpHint(t *testing.T) {
+	cmd := newFakeMailCmd()
+	// Token with no plausible neighbor in {to, cc, subject, body}.
+	got := flagSuggestErrorFunc(cmd, errors.New("unknown flag: --zzzzzzz"))
+	var exitErr *output.ExitError
+	require.True(t, errors.As(got, &exitErr))
+	assert.Contains(t, exitErr.Detail.Hint, "--help")
+}
+
+func TestParseUnknownToken_EmptyAndMalformed(t *testing.T) {
+	// Long form with empty token after the prefix.
+	_, _, ok := parseUnknownToken("unknown flag: --")
+	assert.False(t, ok, "empty long token must not match")
+
+	// Shorthand with no closing quote.
+	_, _, ok = parseUnknownToken("unknown shorthand flag: 'q")
+	assert.False(t, ok, "shorthand without closing quote must not match")
+
+	// Shorthand with empty char between quotes.
+	_, _, ok = parseUnknownToken("unknown shorthand flag: '' in -")
+	assert.False(t, ok, "empty shorthand token must not match")
+}
+
+func TestSuggest_EmptyInputs(t *testing.T) {
+	assert.Nil(t, suggest("", []flagName{{long: "to"}}))
+	assert.Nil(t, suggest("foo", nil))
+}
+
+func TestSuggestShorthand_EmptyInputs(t *testing.T) {
+	assert.Nil(t, suggestShorthand("", []flagName{{long: "to", short: "t"}}))
+	assert.Nil(t, suggestShorthand("x", nil))
+}
+
+func TestSuggestShorthand_HiddenSkipped(t *testing.T) {
+	names := []flagName{
+		{long: "secret", short: "s", hidden: true},
+		{long: "subject", short: "s"},
+	}
+	got := suggestShorthand("s", names)
+	for _, c := range got {
+		assert.NotEqual(t, "--secret", c.Flag, "hidden shorthand must not be suggested")
+	}
+}
+
+func TestCollectFlags_NilSafe(t *testing.T) {
+	assert.Nil(t, collectFlags(nil))
+}
+
+func TestLevThreshold_Clamp(t *testing.T) {
+	// len 0 → 0/3+1 = 1
+	assert.Equal(t, 1, levThreshold(""))
+	// len 3 → 2
+	assert.Equal(t, 2, levThreshold("abc"))
+	// Long token caps at 4.
+	assert.Equal(t, 4, levThreshold("aaaaaaaaaaaaaaaaaaaa"))
+}
+
+func TestLevenshtein_EmptyAndIdentical(t *testing.T) {
+	assert.Equal(t, 0, levenshtein("", ""))
+	assert.Equal(t, 3, levenshtein("", "abc"))
+	assert.Equal(t, 3, levenshtein("abc", ""))
+	assert.Equal(t, 0, levenshtein("abc", "abc"))
+	assert.Equal(t, 1, levenshtein("abc", "abd"))
+}

shortcuts/register.go

@@ -99,5 +99,8 @@ func RegisterShortcutsWithContext(ctx context.Context, program *cobra.Command, f
 		for _, shortcut := range shortcuts {
 			shortcut.MountWithContext(ctx, svc, f)
 		}
+		if service == "mail" {
+			mail.InstallOnMail(svc)
+		}
 	}
 }

shortcuts/register_test.go

@@ -6,6 +6,7 @@ package shortcuts
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -14,6 +15,7 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
@@ -109,7 +111,7 @@ func TestRegisterShortcutsMountsDocsMediaPreview(t *testing.T) {
 	}
 }
 
-func TestRegisterShortcutsDocsHelpAddsVersionSelectorAndLegacyTips(t *testing.T) {
+func TestRegisterShortcutsDocsHelpAddsVersionSelectorAndUpgradeTips(t *testing.T) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))
 
@@ -135,11 +137,11 @@ func TestRegisterShortcutsDocsHelpAddsVersionSelectorAndLegacyTips(t *testing.T)
 	}
 	for _, want := range []string{
 		"Tips:",
-		"Agent version rule",
-		"use --api-version v2 only when the installed lark-doc skill explicitly instructs",
-		"otherwise use the default v1 flags",
-		"if the skill does not mention v2",
-		"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",
+		"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
 	} {
 		if !strings.Contains(defaultHelp.String(), want) {
 			t.Fatalf("docs default help missing %q:\n%s", want, defaultHelp.String())
@@ -168,15 +170,22 @@ func TestRegisterShortcutsDocsV2HelpUsesV2Description(t *testing.T) {
 	for _, want := range []string{
 		"Document and content operations (v2).",
 		"Tips:",
-		"Agent version rule",
-		"otherwise use the default v1 flags",
-		"if the skill does not mention v2",
-		"legacy v1 examples and flags",
+		"Check the installed lark-doc skill first",
+		"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
 	} {
 		if !strings.Contains(out.String(), want) {
 			t.Fatalf("docs v2 help missing %q:\n%s", want, out.String())
 		}
 	}
+	for _, unwanted := range []string{
+		"Docs v1 is deprecated and will be removed soon",
+		"After confirming lark-doc is v2",
+		"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
+	} {
+		if strings.Contains(out.String(), unwanted) {
+			t.Fatalf("docs v2 help should not include %q:\n%s", unwanted, out.String())
+		}
+	}
 }
 
 func TestRegisterShortcutsDocsVersionedShortcutHelpAddsVersionTips(t *testing.T) {
@@ -253,24 +262,47 @@ func TestRegisterShortcutsDocsVersionedShortcutHelpAddsVersionTips(t *testing.T)
 				t.Fatalf("docs %s help failed: %v", tt.shortcut, err)
 			}
 
+			wantTips := []string{
+				"Tips:",
+				"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",
+				"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
+			}
+			unwantedTips := []string{
+				"[NOTE]",
+				"Use --api-version v2 for the latest API",
+				"otherwise use the default v1 flags",
+				"legacy v1 examples and flags",
+			}
+			if tt.apiVersion == "v2" {
+				wantTips = []string{
+					"Tips:",
+					"Check the installed lark-doc skill first",
+					"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
+				}
+				unwantedTips = append(unwantedTips,
+					"Docs v1 is deprecated and will be removed soon",
+					"After confirming lark-doc is v2",
+					"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
+				)
+			}
+
 			for _, want := range []string{
 				tt.shortcutHelp,
 				tt.versionedFlag,
-				"Tips:",
-				"Agent version rule",
-				"use --api-version v2 only when the installed lark-doc skill explicitly instructs",
-				"otherwise use the default v1 flags",
-				"if the skill does not mention v2",
-				"legacy v1 examples and flags",
 			} {
 				if !strings.Contains(out.String(), want) {
 					t.Fatalf("docs %s %s help missing %q:\n%s", tt.shortcut, tt.apiVersion, want, out.String())
 				}
 			}
-			for _, unwanted := range []string{
-				"[NOTE]",
-				"Use --api-version v2 for the latest API",
-			} {
+			for _, want := range wantTips {
+				if !strings.Contains(out.String(), want) {
+					t.Fatalf("docs %s %s help missing %q:\n%s", tt.shortcut, tt.apiVersion, want, out.String())
+				}
+			}
+			for _, unwanted := range unwantedTips {
 				if strings.Contains(out.String(), unwanted) {
 					t.Fatalf("docs %s %s help should not include %q:\n%s", tt.shortcut, tt.apiVersion, unwanted, out.String())
 				}
@@ -305,6 +337,65 @@ func TestRegisterShortcutsReusesExistingServiceCommand(t *testing.T) {
 	}
 }
 
+// TestRegisterShortcutsInstallsMailFlagSuggestHook is the end-to-end
+// wiring guard for the mail unknown-flag fuzzy-match feature: it ensures
+// the `if service == "mail" { mail.InstallOnMail(svc) }` branch in
+// RegisterShortcutsWithContext is actually exercised, so a future refactor
+// that drops the branch (or breaks the import) will fail this test rather
+// than silently regressing the structured-error contract.
+func TestRegisterShortcutsInstallsMailFlagSuggestHook(t *testing.T) {
+	program := &cobra.Command{Use: "root"}
+	RegisterShortcuts(program, newRegisterTestFactory(t))
+
+	mailCmd, _, err := program.Find([]string{"mail"})
+	if err != nil {
+		t.Fatalf("find mail command: %v", err)
+	}
+	if mailCmd == nil || mailCmd.Name() != "mail" {
+		t.Fatalf("mail command not mounted: %#v", mailCmd)
+	}
+
+	// The FlagErrorFunc lookup walks up to the nearest non-nil hook, so
+	// invoking it on the mail parent (or any of its children) must yield
+	// a structured *output.ExitError with type "unknown_flag".
+	got := mailCmd.FlagErrorFunc()(mailCmd, errors.New("unknown flag: --bogus"))
+	var exitErr *output.ExitError
+	if !errors.As(got, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T (%v)", got, got)
+	}
+	if exitErr.Detail == nil || exitErr.Detail.Type != "unknown_flag" {
+		t.Fatalf("expected Detail.Type=unknown_flag, got %#v", exitErr.Detail)
+	}
+	if exitErr.Code != output.ExitAPI {
+		t.Fatalf("expected Code=ExitAPI(%d), got %d", output.ExitAPI, exitErr.Code)
+	}
+}
+
+// TestRegisterShortcutsLeavesNonMailFlagErrorUntouched confirms the
+// install is scoped: a non-mail service must keep the default cobra
+// pass-through behaviour, otherwise an accidental fall-through in
+// register.go would silently change every domain's error envelope.
+func TestRegisterShortcutsLeavesNonMailFlagErrorUntouched(t *testing.T) {
+	program := &cobra.Command{Use: "root"}
+	RegisterShortcuts(program, newRegisterTestFactory(t))
+
+	baseCmd, _, err := program.Find([]string{"base"})
+	if err != nil {
+		t.Fatalf("find base command: %v", err)
+	}
+	in := errors.New("unknown flag: --bogus")
+	got := baseCmd.FlagErrorFunc()(baseCmd, in)
+	// Default cobra hook is identity — anything else means the mail hook
+	// leaked across domains.
+	var exitErr *output.ExitError
+	if errors.As(got, &exitErr) {
+		t.Fatalf("base service unexpectedly produced *output.ExitError: %#v", exitErr)
+	}
+	if got != in {
+		t.Fatalf("base service should pass through original error pointer, got %T (%v)", got, got)
+	}
+}
+
 func TestGenerateShortcutsJSON(t *testing.T) {
 	output := os.Getenv("SHORTCUTS_OUTPUT")
 	if output == "" {
@@ -324,7 +415,7 @@ func TestGenerateShortcutsJSON(t *testing.T) {
 		grouped[s.Service] = append(grouped[s.Service], entry{
 			Verb:        verb,
 			Description: s.Description,
-			Scopes:      s.ScopesForIdentity("user"),
+			Scopes:      s.DeclaredScopesForIdentity("user"),
 		})
 	}
 

shortcuts/vc/shortcuts.go

@@ -11,5 +11,8 @@ func Shortcuts() []common.Shortcut {
 		VCSearch,
 		VCNotes,
 		VCRecording,
+		VCMeetingJoin,
+		VCMeetingLeave,
+		VCMeetingEvents,
 	}
 }

shortcuts/vc/vc_meeting_events.go

@@ -0,0 +1,984 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+	"unicode"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	vcMeetingEventsAPIPath     = "/open-apis/vc/v1/bots/events"
+	defaultVCMeetingEventsSize = 20
+	minVCMeetingEventsPageSize = 20
+	maxVCMeetingEventsPageSize = 100
+	maxVCMeetingEventsPages    = 200
+)
+
+var meetingDisplayLocation = time.FixedZone("UTC+8", 8*60*60)
+
+// toUnixSeconds converts a supported CLI time input into a Unix seconds string.
+func toUnixSeconds(input string, hint ...string) (string, error) {
+	ts, err := common.ParseTime(input, hint...)
+	if err != nil {
+		return "", err
+	}
+	if _, err := strconv.ParseInt(ts, 10, 64); err != nil {
+		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err)
+	}
+	return ts, nil
+}
+
+// VCMeetingEvents lists bot meeting events for a meeting.
+var VCMeetingEvents = common.Shortcut{
+	Service:     "vc",
+	Command:     "+meeting-events",
+	Description: "List bot meeting events by meeting ID",
+	Risk:        "read",
+	Scopes:      []string{"vc:meeting.meetingevent:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "meeting-id", Required: true, Desc: "meeting ID to query"},
+		{Name: "start", Desc: "time lower bound (ISO 8601, YYYY-MM-DD, or Unix seconds)"},
+		{Name: "end", Desc: "time upper bound (ISO 8601, YYYY-MM-DD, or Unix seconds)"},
+		{Name: "page-token", Desc: "page token for the next page"},
+		{Name: "page-size", Default: "20", Desc: "page size, 20-100 (default 20)"},
+		{Name: "page-all", Type: "bool", Desc: "automatically paginate through all available pages"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := validateMeetingEventsMeetingID(runtime.Str("meeting-id")); err != nil {
+			return err
+		}
+		if _, err := meetingEventsPageSize(runtime); err != nil {
+			return err
+		}
+		if _, _, err := parseMeetingEventsTimeRange(runtime); err != nil {
+			return err
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		startTime, endTime, err := parseMeetingEventsTimeRange(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		params, err := buildMeetingEventsParams(runtime, startTime, endTime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		dryRun := common.NewDryRunAPI()
+		if runtime.Bool("page-all") {
+			dryRun = dryRun.Desc("Auto-paginates through all available pages")
+		}
+		dryRun = dryRun.GET(vcMeetingEventsAPIPath)
+		if flat := flattenQueryParams(params); len(flat) > 0 {
+			dryRun.Params(flat)
+		}
+		return dryRun
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		startTime, endTime, err := parseMeetingEventsTimeRange(runtime)
+		if err != nil {
+			return err
+		}
+		data, events, hasMore, pageToken, err := fetchMeetingEvents(ctx, runtime, startTime, endTime)
+		if err != nil {
+			return err
+		}
+		events = compactMeetingEvents(events)
+		outData := map[string]interface{}{
+			"events":     events,
+			"has_more":   data["has_more"],
+			"page_token": data["page_token"],
+		}
+
+		timeline := buildMeetingEventTimeline(events)
+		runtime.OutFormat(outData, &output.Meta{Count: len(events)}, func(w io.Writer) {
+			if len(timeline.entries) == 0 {
+				fmt.Fprintln(w, "No meeting events.")
+				return
+			}
+			io.WriteString(w, renderMeetingEventsPretty(timeline))
+		})
+		if runtime.Format == "pretty" && pageToken != "" {
+			fmt.Fprintf(runtime.IO().Out, "\npage_token: %s\n", pageToken)
+			if hasMore {
+				fmt.Fprintln(runtime.IO().Out, "more available")
+			}
+		}
+		return nil
+	},
+}
+
+func meetingEventsPageSize(runtime *common.RuntimeContext) (int, error) {
+	if runtime.Bool("page-all") {
+		return maxVCMeetingEventsPageSize, nil
+	}
+	pageSizeStr := strings.TrimSpace(runtime.Str("page-size"))
+	if pageSizeStr == "" {
+		return defaultVCMeetingEventsSize, nil
+	}
+	pageSize, err := strconv.Atoi(pageSizeStr)
+	if err != nil {
+		return 0, common.FlagErrorf("invalid --page-size %q: must be an integer", pageSizeStr)
+	}
+	if pageSize < minVCMeetingEventsPageSize {
+		return minVCMeetingEventsPageSize, nil
+	}
+	if pageSize > maxVCMeetingEventsPageSize {
+		return maxVCMeetingEventsPageSize, nil
+	}
+	return pageSize, nil
+}
+
+func meetingEventsPaginationConfig(runtime *common.RuntimeContext) (bool, int) {
+	if !runtime.Bool("page-all") {
+		return false, 0
+	}
+	return true, maxVCMeetingEventsPages
+}
+
+func validateMeetingEventsMeetingID(meetingID string) error {
+	meetingID = strings.TrimSpace(meetingID)
+	if meetingID == "" {
+		return common.FlagErrorf("--meeting-id is required")
+	}
+	value, err := strconv.ParseInt(meetingID, 10, 64)
+	if err != nil || value <= 0 {
+		return common.FlagErrorf("--meeting-id must be a positive integer, got %q", meetingID)
+	}
+	return nil
+}
+
+// parseMeetingEventsTimeRange validates --start/--end and returns Unix seconds strings.
+func parseMeetingEventsTimeRange(runtime *common.RuntimeContext) (string, string, error) {
+	start := strings.TrimSpace(runtime.Str("start"))
+	end := strings.TrimSpace(runtime.Str("end"))
+	if start == "" && end == "" {
+		return "", "", nil
+	}
+
+	var startTime, endTime string
+	if start != "" {
+		parsed, err := toUnixSeconds(start)
+		if err != nil {
+			return "", "", output.ErrValidation("--start: %v", err)
+		}
+		startTime = parsed
+	}
+	if end != "" {
+		parsed, err := toUnixSeconds(end, "end")
+		if err != nil {
+			return "", "", output.ErrValidation("--end: %v", err)
+		}
+		endTime = parsed
+	}
+	if startTime != "" && endTime != "" {
+		startValue, _ := strconv.ParseInt(startTime, 10, 64)
+		endValue, _ := strconv.ParseInt(endTime, 10, 64)
+		if startValue > endValue {
+			return "", "", output.ErrValidation("--start (%s) is after --end (%s)", start, end)
+		}
+	}
+	return startTime, endTime, nil
+}
+
+func buildMeetingEventsParams(runtime *common.RuntimeContext, startTime, endTime string) (larkcore.QueryParams, error) {
+	pageSize, err := meetingEventsPageSize(runtime)
+	if err != nil {
+		return nil, err
+	}
+
+	params := make(larkcore.QueryParams)
+	params.Set("meeting_id", strings.TrimSpace(runtime.Str("meeting-id")))
+	params.Set("page_size", strconv.Itoa(pageSize))
+	if pageToken := strings.TrimSpace(runtime.Str("page-token")); pageToken != "" {
+		params.Set("page_token", pageToken)
+	}
+	if startTime != "" {
+		params.Set("start_time", startTime)
+	}
+	if endTime != "" {
+		params.Set("end_time", endTime)
+	}
+	return params, nil
+}
+
+func fetchMeetingEvents(ctx context.Context, runtime *common.RuntimeContext, startTime, endTime string) (map[string]interface{}, []interface{}, bool, string, error) {
+	params, err := buildMeetingEventsParams(runtime, startTime, endTime)
+	if err != nil {
+		return nil, nil, false, "", err
+	}
+	autoPaginate, pageLimit := meetingEventsPaginationConfig(runtime)
+	if !autoPaginate {
+		data, err := runtime.DoAPIJSON(http.MethodGet, vcMeetingEventsAPIPath, params, nil)
+		if err != nil {
+			return nil, nil, false, "", err
+		}
+		if data == nil {
+			data = map[string]interface{}{}
+		}
+		events := common.GetSlice(data, "events")
+		hasMore, _ := data["has_more"].(bool)
+		pageToken, _ := data["page_token"].(string)
+		return data, events, hasMore, pageToken, nil
+	}
+
+	var (
+		allEvents     []interface{}
+		lastData      map[string]interface{}
+		lastPageToken string
+		lastHasMore   bool
+	)
+	for page := 0; page < pageLimit; page++ {
+		data, err := runtime.DoAPIJSON(http.MethodGet, vcMeetingEventsAPIPath, params, nil)
+		if err != nil {
+			return nil, nil, false, "", err
+		}
+		if data == nil {
+			data = map[string]interface{}{}
+		}
+		lastData = data
+		events := common.GetSlice(data, "events")
+		allEvents = append(allEvents, events...)
+		lastHasMore, _ = data["has_more"].(bool)
+		lastPageToken, _ = data["page_token"].(string)
+		if !lastHasMore || lastPageToken == "" {
+			break
+		}
+		params.Set("page_token", lastPageToken)
+	}
+	if lastData == nil {
+		lastData = map[string]interface{}{}
+	}
+	lastData["events"] = allEvents
+	lastData["has_more"] = lastHasMore
+	lastData["page_token"] = lastPageToken
+	return lastData, allEvents, lastHasMore, lastPageToken, nil
+}
+
+func flattenQueryParams(params larkcore.QueryParams) map[string]interface{} {
+	if len(params) == 0 {
+		return nil
+	}
+	flat := make(map[string]interface{}, len(params))
+	for key, values := range params {
+		switch len(values) {
+		case 0:
+			continue
+		case 1:
+			flat[key] = values[0]
+		default:
+			copied := make([]string, len(values))
+			copy(copied, values)
+			flat[key] = copied
+		}
+	}
+	return flat
+}
+
+func compactMeetingEvents(events []interface{}) []interface{} {
+	compacted := make([]interface{}, 0, len(events))
+	for _, raw := range events {
+		event, _ := raw.(map[string]interface{})
+		if event == nil {
+			continue
+		}
+		if payload := common.GetMap(event, "payload"); payload != nil {
+			event["payload"] = compactMeetingPayload(payload)
+		}
+		compacted = append(compacted, event)
+	}
+	return compacted
+}
+
+func compactMeetingPayload(payload map[string]interface{}) map[string]interface{} {
+	if payload == nil {
+		return nil
+	}
+	compacted := make(map[string]interface{}, len(payload))
+	for key, value := range payload {
+		if items, ok := value.([]interface{}); ok && len(items) == 0 {
+			continue
+		}
+		compacted[key] = value
+	}
+	return compacted
+}
+
+type meetingTimeline struct {
+	topic     string
+	startTime time.Time
+	hasStart  bool
+	endTime   time.Time
+	hasEnd    bool
+	entries   []meetingTimelineEntry
+}
+
+type meetingTimelineEntry struct {
+	when        time.Time
+	hasWhen     bool
+	sequence    int
+	group       int
+	subject     string
+	description string
+	details     []string
+}
+
+func buildMeetingEventTimeline(events []interface{}) meetingTimeline {
+	timeline := meetingTimeline{}
+	var sequence int
+	var group int
+	for _, raw := range events {
+		event, _ := raw.(map[string]interface{})
+		if event == nil {
+			continue
+		}
+		payload := common.GetMap(event, "payload")
+		if payload == nil {
+			continue
+		}
+		if timeline.topic == "" || !timeline.hasStart || !timeline.hasEnd {
+			populateMeetingHeader(&timeline, common.GetMap(payload, "meeting"))
+		}
+		for _, entry := range buildTimelineEntriesForEvent(event, &sequence, group) {
+			timeline.entries = append(timeline.entries, entry)
+		}
+		group++
+	}
+	sort.SliceStable(timeline.entries, func(i, j int) bool {
+		left := timeline.entries[i]
+		right := timeline.entries[j]
+		switch {
+		case left.hasWhen && right.hasWhen:
+			if left.when.Equal(right.when) {
+				return left.sequence < right.sequence
+			}
+			return left.when.Before(right.when)
+		case left.hasWhen:
+			return true
+		case right.hasWhen:
+			return false
+		default:
+			return left.sequence < right.sequence
+		}
+	})
+	return timeline
+}
+
+func populateMeetingHeader(timeline *meetingTimeline, meeting map[string]interface{}) {
+	if timeline == nil || meeting == nil {
+		return
+	}
+	if timeline.topic == "" {
+		timeline.topic = common.GetString(meeting, "topic")
+	}
+	if !timeline.hasStart {
+		if parsed, ok := parseFlexibleTime(common.GetString(meeting, "start_time")); ok {
+			timeline.startTime = parsed
+			timeline.hasStart = true
+		}
+	}
+	if !timeline.hasEnd {
+		if parsed, ok := parseFlexibleTime(common.GetString(meeting, "end_time")); ok {
+			timeline.endTime = parsed
+			timeline.hasEnd = true
+		}
+	}
+}
+
+func buildTimelineEntriesForEvent(event map[string]interface{}, sequence *int, group int) []meetingTimelineEntry {
+	payload := common.GetMap(event, "payload")
+	if payload == nil {
+		return nil
+	}
+	eventType := meetingEventType(event)
+	eventTime, eventTimeOK := parseFlexibleTime(common.GetString(event, "event_time"))
+	switch eventType {
+	case "participant_joined":
+		return participantJoinedEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "participant_left":
+		return participantLeftEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "transcript_received":
+		return transcriptEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "chat_received":
+		return chatEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "magic_share_started":
+		return magicShareStartedEntries(payload, eventTime, eventTimeOK, sequence, group)
+	case "magic_share_ended":
+		return magicShareEndedEntries(payload, eventTime, eventTimeOK, sequence, group)
+	default:
+		return []meetingTimelineEntry{newTimelineEntry(eventTime, eventTimeOK, sequence, group, meetingEventUserDisplayName(nil), meetingEventSummary(event), nil)}
+	}
+}
+
+func participantJoinedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "participant_joined_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "加入了会议", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "join_time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "participant"))
+		if subject == "" {
+			subject = "未知参会人"
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, "加入了会议", nil))
+	}
+	return entries
+}
+
+func participantLeftEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "participant_left_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "离开了会议", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "leave_time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "participant"))
+		if subject == "" {
+			subject = "未知参会人"
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, leaveAction(item), nil))
+	}
+	return entries
+}
+
+func transcriptEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "transcript_received_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "产生了转写", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "start_time_ms"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "speaker"))
+		if subject == "" {
+			subject = "未知发言人"
+		}
+		text := strings.TrimSpace(common.GetString(item, "text"))
+		description := "产生了转写"
+		if text != "" {
+			description = text
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, description, nil))
+	}
+	return entries
+}
+
+func chatEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "chat_received_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "发送了消息", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "send_time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "operator"))
+		if subject == "" {
+			subject = "未知发送者"
+		}
+		typeLabel := chatMessageTypeLabel(item)
+		description := strings.TrimSpace(common.GetString(item, "content"))
+		if description == "" {
+			description = fmt.Sprintf("[%s] 发送了消息", typeLabel)
+		} else {
+			description = fmt.Sprintf("[%s] %s", typeLabel, description)
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, description, nil))
+	}
+	return entries
+}
+
+func magicShareStartedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "magic_share_started_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "开始共享内容", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "operator"))
+		if subject == "" {
+			subject = "未知用户"
+		}
+		title := strings.TrimSpace(common.GetString(common.GetMap(item, "share_doc"), "title"))
+		url := strings.TrimSpace(common.GetString(common.GetMap(item, "share_doc"), "url"))
+		description := "开始共享内容"
+		if title != "" {
+			description = fmt.Sprintf("开始共享「%s」", title)
+		}
+		var details []string
+		if url != "" {
+			details = append(details, "URL: "+url)
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, description, details))
+	}
+	return entries
+}
+
+func magicShareEndedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
+	items := common.GetSlice(payload, "magic_share_ended_items")
+	if len(items) == 0 {
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "结束共享", nil)}
+	}
+	entries := make([]meetingTimelineEntry, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		when, ok := parseFlexibleTime(common.GetString(item, "time"))
+		if !ok {
+			when, ok = fallbackTime, fallbackOK
+		}
+		subject := meetingEventUserWithID(common.GetMap(item, "operator"))
+		if subject == "" {
+			subject = "未知用户"
+		}
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, "结束共享", nil))
+	}
+	return entries
+}
+
+func newTimelineEntry(when time.Time, hasWhen bool, sequence *int, group int, subject, description string, details []string) meetingTimelineEntry {
+	entry := meetingTimelineEntry{
+		when:        when,
+		hasWhen:     hasWhen,
+		sequence:    *sequence,
+		group:       group,
+		subject:     subject,
+		description: description,
+		details:     details,
+	}
+	*sequence = *sequence + 1
+	return entry
+}
+
+func parseFlexibleTime(raw string) (time.Time, bool) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return time.Time{}, false
+	}
+	if ts, err := strconv.ParseInt(raw, 10, 64); err == nil {
+		switch {
+		case ts > 1_000_000_000_000:
+			return time.UnixMilli(ts), true
+		case ts > 0:
+			return time.Unix(ts, 0), true
+		}
+	}
+	if parsed, err := time.Parse(time.RFC3339, raw); err == nil {
+		return parsed, true
+	}
+	return time.Time{}, false
+}
+
+func renderMeetingEventsPretty(timeline meetingTimeline) string {
+	var b strings.Builder
+	if timeline.topic != "" {
+		fmt.Fprintf(&b, "会议主题：%s\n", escapePrettyText(timeline.topic))
+	}
+	if timeline.hasStart || timeline.hasEnd {
+		fmt.Fprintf(&b, "会议时间：%s\n", escapePrettyText(formatMeetingWindow(timeline.startTime, timeline.hasStart, timeline.endTime, timeline.hasEnd)))
+	}
+	if b.Len() > 0 {
+		b.WriteString("\n")
+	}
+	for _, entry := range timeline.entries {
+		fmt.Fprintf(&b, "[%s] ", formatTimelineOffset(entry.when, entry.hasWhen, timeline.startTime, timeline.hasStart))
+		if entry.subject != "" {
+			if entry.description == "" {
+				fmt.Fprintln(&b, escapePrettyText(entry.subject))
+				for _, detail := range entry.details {
+					fmt.Fprintf(&b, "           %s\n", escapePrettyText(detail))
+				}
+				continue
+			}
+			if needsColon(entry.description) {
+				fmt.Fprintf(&b, "%s: %s\n", escapePrettyText(entry.subject), escapePrettyText(entry.description))
+			} else {
+				fmt.Fprintf(&b, "%s %s\n", escapePrettyText(entry.subject), escapePrettyText(entry.description))
+			}
+			for _, detail := range entry.details {
+				fmt.Fprintf(&b, "           %s\n", escapePrettyText(detail))
+			}
+			continue
+		}
+		fmt.Fprintln(&b, escapePrettyText(entry.description))
+		for _, detail := range entry.details {
+			fmt.Fprintf(&b, "           %s\n", escapePrettyText(detail))
+		}
+	}
+	if b.Len() == 0 {
+		return ""
+	}
+	return b.String()
+}
+
+func escapePrettyText(s string) string {
+	if s == "" {
+		return ""
+	}
+	var b strings.Builder
+	for _, r := range s {
+		switch r {
+		case '\n':
+			b.WriteString(`\n`)
+		case '\r':
+			b.WriteString(`\r`)
+		case '\t':
+			b.WriteString(`\t`)
+		default:
+			if unicode.IsControl(r) {
+				fmt.Fprintf(&b, "\\u%04X", r)
+				continue
+			}
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}
+
+func formatMeetingWindow(start time.Time, hasStart bool, end time.Time, hasEnd bool) string {
+	switch {
+	case hasStart && hasEnd:
+		if !end.After(start) {
+			return fmt.Sprintf("%s（进行中）", start.In(meetingDisplayLocation).Format("2006-01-02 15:04:05"))
+		}
+		return fmt.Sprintf("%s - %s", start.In(meetingDisplayLocation).Format("2006-01-02 15:04:05"), end.In(meetingDisplayLocation).Format("2006-01-02 15:04:05"))
+	case hasStart:
+		return start.In(meetingDisplayLocation).Format("2006-01-02 15:04:05")
+	case hasEnd:
+		return end.In(meetingDisplayLocation).Format("2006-01-02 15:04:05")
+	default:
+		return ""
+	}
+}
+
+func formatTimelineOffset(when time.Time, hasWhen bool, meetingStart time.Time, hasMeetingStart bool) string {
+	if hasWhen && hasMeetingStart {
+		diff := when.Sub(meetingStart)
+		if diff < 0 {
+			diff = 0
+		}
+		totalSeconds := int(diff.Seconds())
+		hours := totalSeconds / 3600
+		minutes := (totalSeconds % 3600) / 60
+		seconds := totalSeconds % 60
+		return fmt.Sprintf("%02d:%02d:%02d", hours, minutes, seconds)
+	}
+	if hasWhen {
+		return when.In(meetingDisplayLocation).Format("15:04:05")
+	}
+	return "??:??:??"
+}
+
+func needsColon(description string) bool {
+	switch description {
+	case "发送了消息", "产生了转写":
+		return false
+	default:
+		return !strings.HasPrefix(description, "加入了") &&
+			!strings.HasPrefix(description, "离开了") &&
+			!strings.HasPrefix(description, "被移出") &&
+			!strings.HasPrefix(description, "会议结束") &&
+			!strings.HasPrefix(description, "开始共享") &&
+			!strings.HasPrefix(description, "结束共享")
+	}
+}
+
+func leaveAction(item map[string]interface{}) string {
+	switch int(common.GetFloat(item, "leave_reason")) {
+	case 2:
+		return "因会议结束离开了会议"
+	case 3:
+		return "被移出了会议"
+	default:
+		return "离开了会议"
+	}
+}
+
+func meetingEventUserWithID(user map[string]interface{}) string {
+	if user == nil {
+		return ""
+	}
+	userID := common.GetString(user, "id")
+	userName := common.GetString(user, "user_name")
+	switch {
+	case userName != "" && userID != "":
+		return fmt.Sprintf("%s(%s)", userName, userID)
+	case userName != "":
+		return userName
+	case userID != "":
+		return userID
+	default:
+		return ""
+	}
+}
+
+func meetingEventType(event map[string]interface{}) string {
+	if eventType := common.GetString(event, "event_type"); eventType != "" {
+		return eventType
+	}
+	return common.GetString(common.GetMap(event, "payload"), "activity_event_type")
+}
+
+func meetingEventSummary(event map[string]interface{}) string {
+	payload := common.GetMap(event, "payload")
+	eventType := meetingEventType(event)
+	switch eventType {
+	case "participant_joined":
+		return participantJoinedSummary(payload)
+	case "participant_left":
+		return participantLeftSummary(payload)
+	case "transcript_received":
+		return transcriptReceivedSummary(payload)
+	case "chat_received":
+		return chatReceivedSummary(payload)
+	case "magic_share_started":
+		return magicShareStartedSummary(payload)
+	case "magic_share_ended":
+		return magicShareEndedSummary(payload)
+	default:
+		return fallbackMeetingEventSummary(payload, eventType)
+	}
+}
+
+func participantJoinedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "participant_joined_items")
+	switch len(items) {
+	case 0:
+		return "participant joined"
+	case 1:
+		user := common.GetMap(firstSliceMap(payload, "participant_joined_items"), "participant")
+		if label := meetingEventUserLabel(user); label != "" {
+			return fmt.Sprintf("participant %s joined", label)
+		}
+		return "participant joined"
+	default:
+		return fmt.Sprintf("%d participants joined", len(items))
+	}
+}
+
+func participantLeftSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "participant_left_items")
+	switch len(items) {
+	case 0:
+		return "participant left"
+	case 1:
+		user := common.GetMap(firstSliceMap(payload, "participant_left_items"), "participant")
+		if label := meetingEventUserLabel(user); label != "" {
+			return fmt.Sprintf("participant %s left", label)
+		}
+		return "participant left"
+	default:
+		return fmt.Sprintf("%d participants left", len(items))
+	}
+}
+
+func transcriptReceivedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "transcript_received_items")
+	if len(items) > 1 {
+		return fmt.Sprintf("%d transcript items", len(items))
+	}
+	item := firstSliceMap(payload, "transcript_received_items")
+	text := common.GetString(item, "text")
+	speaker := meetingEventUserLabel(common.GetMap(item, "speaker"))
+	switch {
+	case speaker != "" && text != "":
+		return fmt.Sprintf("speaker %s: %s", speaker, text)
+	case speaker != "":
+		return fmt.Sprintf("speaker %s transcript received", speaker)
+	case text != "":
+		return fmt.Sprintf("transcript: %s", text)
+	default:
+		return "transcript received"
+	}
+}
+
+func chatReceivedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "chat_received_items")
+	switch len(items) {
+	case 0:
+		return "chat received"
+	case 1:
+		item := firstSliceMap(payload, "chat_received_items")
+		content := common.GetString(item, "content")
+		operator := meetingEventUserDisplayName(common.GetMap(item, "operator"))
+		switch {
+		case operator != "" && content != "":
+			return fmt.Sprintf("%s: %s", operator, content)
+		case operator != "":
+			return fmt.Sprintf("message by %s", operator)
+		case content != "":
+			return fmt.Sprintf("message: %s", content)
+		default:
+			return "chat received"
+		}
+	default:
+		count, operator := summarizeChatOperators(items)
+		switch {
+		case count == 1 && operator != "":
+			return fmt.Sprintf("%d messages by %s", len(items), operator)
+		case count > 1:
+			return fmt.Sprintf("%d messages by %d users", len(items), count)
+		default:
+			return fmt.Sprintf("%d messages", len(items))
+		}
+	}
+}
+
+func magicShareStartedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "magic_share_started_items")
+	if len(items) > 1 {
+		return fmt.Sprintf("%d share start events", len(items))
+	}
+	item := firstSliceMap(payload, "magic_share_started_items")
+	shareID := common.GetString(item, "share_id")
+	title := common.GetString(common.GetMap(item, "share_doc"), "title")
+	switch {
+	case shareID != "" && title != "":
+		return fmt.Sprintf("share %s started: %s", shareID, title)
+	case shareID != "":
+		return fmt.Sprintf("share %s started", shareID)
+	case title != "":
+		return fmt.Sprintf("share started: %s", title)
+	default:
+		return "share started"
+	}
+}
+
+func magicShareEndedSummary(payload map[string]interface{}) string {
+	items := common.GetSlice(payload, "magic_share_ended_items")
+	if len(items) > 1 {
+		return fmt.Sprintf("%d share end events", len(items))
+	}
+	item := firstSliceMap(payload, "magic_share_ended_items")
+	if shareID := common.GetString(item, "share_id"); shareID != "" {
+		return fmt.Sprintf("share %s ended", shareID)
+	}
+	return "share ended"
+}
+
+func fallbackMeetingEventSummary(payload map[string]interface{}, eventType string) string {
+	meeting := common.GetMap(payload, "meeting")
+	if topic := common.GetString(meeting, "topic"); topic != "" {
+		if eventType != "" {
+			return fmt.Sprintf("%s: %s", eventType, topic)
+		}
+		return topic
+	}
+	if eventType != "" {
+		return eventType
+	}
+	return "meeting event"
+}
+
+func firstSliceMap(payload map[string]interface{}, key string) map[string]interface{} {
+	items := common.GetSlice(payload, key)
+	if len(items) == 0 {
+		return nil
+	}
+	first, _ := items[0].(map[string]interface{})
+	return first
+}
+
+func meetingEventUserLabel(user map[string]interface{}) string {
+	if user == nil {
+		return ""
+	}
+	userID := common.GetString(user, "id")
+	userName := common.GetString(user, "user_name")
+	switch {
+	case userID != "" && userName != "":
+		return fmt.Sprintf("%s (%s)", userID, userName)
+	case userID != "":
+		return userID
+	case userName != "":
+		return userName
+	default:
+		return ""
+	}
+}
+
+func meetingEventUserDisplayName(user map[string]interface{}) string {
+	if user == nil {
+		return ""
+	}
+	if userName := common.GetString(user, "user_name"); userName != "" {
+		return userName
+	}
+	return common.GetString(user, "id")
+}
+
+func chatMessageTypeLabel(item map[string]interface{}) string {
+	code := int(common.GetFloat(item, "message_type"))
+	switch code {
+	case 1:
+		return "text"
+	case 2:
+		return "system"
+	case 3:
+		return "reaction"
+	case 4:
+		return "encrypted"
+	default:
+		return "unknown"
+	}
+}
+
+func summarizeChatOperators(items []interface{}) (int, string) {
+	seen := make(map[string]struct{}, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		if item == nil {
+			continue
+		}
+		operator := meetingEventUserDisplayName(common.GetMap(item, "operator"))
+		if operator == "" {
+			continue
+		}
+		seen[operator] = struct{}{}
+	}
+	if len(seen) != 1 {
+		return len(seen), ""
+	}
+	for operator := range seen {
+		return 1, operator
+	}
+	return 0, ""
+}

shortcuts/vc/vc_meeting_events_test.go

@@ -0,0 +1,931 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+)
+
+func newMeetingEventsRuntime() *common.RuntimeContext {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-id", "", "")
+	cmd.Flags().String("start", "", "")
+	cmd.Flags().String("end", "", "")
+	cmd.Flags().String("page-token", "", "")
+	cmd.Flags().String("page-size", "", "")
+	cmd.Flags().Bool("page-all", false, "")
+	return common.TestNewRuntimeContext(cmd, defaultConfig())
+}
+
+func mustSetMeetingEventsFlag(t *testing.T, runtime *common.RuntimeContext, name, value string) {
+	t.Helper()
+	if err := runtime.Cmd.Flags().Set(name, value); err != nil {
+		t.Fatalf("Flags().Set(%q, %q) error = %v", name, value, err)
+	}
+}
+
+func meetingEventsStub(events []interface{}, hasMore bool, pageToken string) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    vcMeetingEventsAPIPath,
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"total":      len(events),
+				"has_more":   hasMore,
+				"page_token": pageToken,
+				"events":     events,
+			},
+		},
+	}
+}
+
+func participantJoinedEvent() map[string]interface{} {
+	return map[string]interface{}{
+		"event_id":   "event-1",
+		"event_type": "participant_joined",
+		"event_time": "2026-04-17T08:00:00Z",
+		"payload": map[string]interface{}{
+			"activity_event_type": "participant_joined",
+			"meeting": map[string]interface{}{
+				"id":         "7628568141510692381",
+				"topic":      "项目例会",
+				"meeting_no": "724939760",
+				"start_time": "1776407700",
+				"end_time":   "1776411300",
+			},
+			"participant_joined_items": []interface{}{
+				map[string]interface{}{
+					"participant": map[string]interface{}{
+						"id":        "bot_001",
+						"user_name": "Demo Bot",
+					},
+					"join_time": "2026-04-17T08:00:00Z",
+				},
+			},
+		},
+	}
+}
+
+func participantJoinedEventOngoing() map[string]interface{} {
+	event := participantJoinedEvent()
+	payload := common.GetMap(event, "payload")
+	meeting := common.GetMap(payload, "meeting")
+	meeting["start_time"] = "1776410100"
+	meeting["end_time"] = "1776410100"
+	return event
+}
+
+func chatReceivedEvent() map[string]interface{} {
+	return map[string]interface{}{
+		"event_id":   "event-2",
+		"event_type": "chat_received",
+		"event_time": "2026-04-17T08:05:00Z",
+		"payload": map[string]interface{}{
+			"activity_event_type": "chat_received",
+			"meeting": map[string]interface{}{
+				"id":         "7628568141510692381",
+				"topic":      "项目例会",
+				"meeting_no": "724939760",
+				"start_time": "1776407700",
+				"end_time":   "1776411300",
+			},
+			"participant_joined_items":  []interface{}{},
+			"participant_left_items":    []interface{}{},
+			"transcript_received_items": []interface{}{},
+			"magic_share_started_items": []interface{}{},
+			"magic_share_ended_items":   []interface{}{},
+			"chat_received_items": []interface{}{
+				map[string]interface{}{
+					"content":      "hello",
+					"message_type": 3,
+					"operator": map[string]interface{}{
+						"id":        "u1",
+						"user_name": "Alice",
+					},
+				},
+			},
+		},
+	}
+}
+
+func multiChatReceivedEvent() map[string]interface{} {
+	return map[string]interface{}{
+		"event_id":   "event-3",
+		"event_type": "chat_received",
+		"event_time": "2026-04-17T08:06:00Z",
+		"payload": map[string]interface{}{
+			"activity_event_type": "chat_received",
+			"meeting": map[string]interface{}{
+				"id":         "7628568141510692381",
+				"topic":      "项目例会",
+				"meeting_no": "724939760",
+				"start_time": "1776407700",
+				"end_time":   "1776411300",
+			},
+			"chat_received_items": []interface{}{
+				map[string]interface{}{
+					"content":      "第一条\n第二行",
+					"message_type": 3,
+					"send_time":    "1776408061000",
+					"operator": map[string]interface{}{
+						"id":        "u1",
+						"user_name": "Alice",
+					},
+				},
+				map[string]interface{}{
+					"content":      "第二条",
+					"message_type": 3,
+					"send_time":    "1776408062000",
+					"operator": map[string]interface{}{
+						"id":        "u1",
+						"user_name": "Alice",
+					},
+				},
+			},
+		},
+	}
+}
+
+func magicShareStartedEvent() map[string]interface{} {
+	return map[string]interface{}{
+		"event_id":   "event-4",
+		"event_type": "magic_share_started",
+		"event_time": "2026-04-17T08:07:00Z",
+		"payload": map[string]interface{}{
+			"activity_event_type": "magic_share_started",
+			"meeting": map[string]interface{}{
+				"id":         "7628568141510692381",
+				"topic":      "项目例会",
+				"meeting_no": "724939760",
+				"start_time": "1776407700",
+				"end_time":   "1776411300",
+			},
+			"magic_share_started_items": []interface{}{
+				map[string]interface{}{
+					"time": "1776408123000",
+					"operator": map[string]interface{}{
+						"id":        "u2",
+						"user_name": "Bob",
+					},
+					"share_doc": map[string]interface{}{
+						"title": "共享文档",
+						"url":   "https://example.com/doc",
+					},
+				},
+			},
+		},
+	}
+}
+
+func TestChatReceivedSummary_MultipleItems(t *testing.T) {
+	payload := map[string]interface{}{
+		"chat_received_items": []interface{}{
+			map[string]interface{}{"content": "hello"},
+			map[string]interface{}{"content": "world"},
+		},
+	}
+
+	got := chatReceivedSummary(payload)
+	if got != "2 messages" {
+		t.Fatalf("chatReceivedSummary() = %q, want %q", got, "2 messages")
+	}
+}
+
+func TestChatReceivedSummary_MultipleItemsSameOperator(t *testing.T) {
+	payload := map[string]interface{}{
+		"chat_received_items": []interface{}{
+			map[string]interface{}{"content": "hello", "operator": map[string]interface{}{"id": "u1", "user_name": "Alice"}},
+			map[string]interface{}{"content": "world", "operator": map[string]interface{}{"id": "u1", "user_name": "Alice"}},
+		},
+	}
+
+	got := chatReceivedSummary(payload)
+	if got != "2 messages by Alice" {
+		t.Fatalf("chatReceivedSummary() = %q, want %q", got, "2 messages by Alice")
+	}
+}
+
+func TestChatReceivedSummary_MultipleItemsMultipleOperators(t *testing.T) {
+	payload := map[string]interface{}{
+		"chat_received_items": []interface{}{
+			map[string]interface{}{"content": "hello", "operator": map[string]interface{}{"id": "u1", "user_name": "Alice"}},
+			map[string]interface{}{"content": "world", "operator": map[string]interface{}{"id": "u2", "user_name": "Bob"}},
+			map[string]interface{}{"content": "again", "operator": map[string]interface{}{"id": "u3", "user_name": "Carol"}},
+		},
+	}
+
+	got := chatReceivedSummary(payload)
+	if got != "3 messages by 3 users" {
+		t.Fatalf("chatReceivedSummary() = %q, want %q", got, "3 messages by 3 users")
+	}
+}
+
+func TestParticipantJoinedSummary_MultipleItems(t *testing.T) {
+	payload := map[string]interface{}{
+		"participant_joined_items": []interface{}{
+			map[string]interface{}{"participant": map[string]interface{}{"id": "u1", "user_name": "User 1"}},
+			map[string]interface{}{"participant": map[string]interface{}{"id": "u2", "user_name": "User 2"}},
+		},
+	}
+
+	got := participantJoinedSummary(payload)
+	if got != "2 participants joined" {
+		t.Fatalf("participantJoinedSummary() = %q, want %q", got, "2 participants joined")
+	}
+}
+
+func TestMeetingEvents_Validation_InvalidMeetingID(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "not-a-number")
+
+	err := VCMeetingEvents.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected validation error for invalid meeting ID")
+	}
+	if !strings.Contains(err.Error(), "positive integer") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestMeetingEvents_Validation_InvalidTimeRange(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
+	mustSetMeetingEventsFlag(t, runtime, "start", "200")
+	mustSetMeetingEventsFlag(t, runtime, "end", "100")
+
+	err := VCMeetingEvents.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected validation error for invalid time range")
+	}
+	if !strings.Contains(err.Error(), "after --end") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestMeetingEvents_Validation_PageSizeBelowMinDoesNotError(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
+	mustSetMeetingEventsFlag(t, runtime, "page-size", "10")
+
+	err := VCMeetingEvents.Validate(context.Background(), runtime)
+	if err != nil {
+		t.Fatalf("expected no validation error for page-size clamp, got: %v", err)
+	}
+}
+
+func TestMeetingEvents_Validation_PageAllIgnoresInvalidPageSize(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
+	mustSetMeetingEventsFlag(t, runtime, "page-all", "true")
+	mustSetMeetingEventsFlag(t, runtime, "page-size", "10")
+
+	err := VCMeetingEvents.Validate(context.Background(), runtime)
+	if err != nil {
+		t.Fatalf("expected no validation error when page-all ignores page-size, got: %v", err)
+	}
+}
+
+func TestMeetingEvents_Validation_InvalidPageSizeReturnsFlagError(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
+	mustSetMeetingEventsFlag(t, runtime, "page-size", "foo")
+
+	err := VCMeetingEvents.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected validation error for non-integer page-size")
+	}
+	if !strings.Contains(err.Error(), "invalid --page-size") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestBuildMeetingEventsParams(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
+	mustSetMeetingEventsFlag(t, runtime, "page-size", "40")
+	mustSetMeetingEventsFlag(t, runtime, "page-token", "1710000000000000000")
+
+	params, err := buildMeetingEventsParams(runtime, "1710000000", "1710003600")
+	if err != nil {
+		t.Fatalf("buildMeetingEventsParams() error = %v", err)
+	}
+	if got := params["meeting_id"][0]; got != "7628568141510692381" {
+		t.Fatalf("meeting_id = %q, want %q", got, "7628568141510692381")
+	}
+	if got := params["page_size"][0]; got != "40" {
+		t.Fatalf("page_size = %q, want %q", got, "40")
+	}
+	if got := params["page_token"][0]; got != "1710000000000000000" {
+		t.Fatalf("page_token = %q, want %q", got, "1710000000000000000")
+	}
+	if got := params["start_time"][0]; got != "1710000000" {
+		t.Fatalf("start_time = %q, want %q", got, "1710000000")
+	}
+	if got := params["end_time"][0]; got != "1710003600" {
+		t.Fatalf("end_time = %q, want %q", got, "1710003600")
+	}
+}
+
+func TestBuildMeetingEventsParams_PageSizeBelowMinClampsToMin(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
+	mustSetMeetingEventsFlag(t, runtime, "page-size", "10")
+
+	params, err := buildMeetingEventsParams(runtime, "", "")
+	if err != nil {
+		t.Fatalf("buildMeetingEventsParams() error = %v", err)
+	}
+	if got := params["page_size"][0]; got != "20" {
+		t.Fatalf("page_size = %q, want %q when below min", got, "20")
+	}
+}
+
+func TestBuildMeetingEventsParams_PageSizeAboveMaxClampsToMax(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
+	mustSetMeetingEventsFlag(t, runtime, "page-size", "999")
+
+	params, err := buildMeetingEventsParams(runtime, "", "")
+	if err != nil {
+		t.Fatalf("buildMeetingEventsParams() error = %v", err)
+	}
+	if got := params["page_size"][0]; got != "100" {
+		t.Fatalf("page_size = %q, want %q when above max", got, "100")
+	}
+}
+
+func TestBuildMeetingEventsParams_PageAllUsesMaxPageSize(t *testing.T) {
+	runtime := newMeetingEventsRuntime()
+	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
+	mustSetMeetingEventsFlag(t, runtime, "page-all", "true")
+	mustSetMeetingEventsFlag(t, runtime, "page-size", "50")
+
+	params, err := buildMeetingEventsParams(runtime, "", "")
+	if err != nil {
+		t.Fatalf("buildMeetingEventsParams() error = %v", err)
+	}
+	if got := params["page_size"][0]; got != "100" {
+		t.Fatalf("page_size = %q, want %q when page-all is set", got, "100")
+	}
+}
+
+func TestMeetingEvents_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--page-token", "1710000000000000000",
+		"--page-size", "40",
+		"--start", "1710000000",
+		"--end", "1710003600",
+		"--dry-run",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	for _, want := range []string{
+		vcMeetingEventsAPIPath,
+		`"meeting_id": "7628568141510692381"`,
+		`"page_token": "1710000000000000000"`,
+		`"page_size": "40"`,
+		`"start_time": "1710000000"`,
+		`"end_time": "1710003600"`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("dry-run output missing %q: %s", want, out)
+		}
+	}
+}
+
+func TestMeetingEvents_DryRun_PageAllUsesMaxLimit(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--page-all",
+		"--dry-run",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if !strings.Contains(stdout.String(), "Auto-paginates through all available pages") {
+		t.Fatalf("dry-run output missing auto-pagination description: %s", stdout.String())
+	}
+}
+
+func TestMeetingEvents_ExecuteJSON_PageAll(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, true, "pt_2"))
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, false, ""))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "json",
+		"--page-all",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := strings.ReplaceAll(stdout.String(), " ", "")
+	out = strings.ReplaceAll(out, "\n", "")
+	if count := strings.Count(out, `"event_type":"participant_joined"`); count != 2 {
+		t.Fatalf("expected 2 aggregated events, got %d: %s", count, stdout.String())
+	}
+	if !strings.Contains(out, `"has_more":false`) {
+		t.Fatalf("expected final has_more=false: %s", stdout.String())
+	}
+}
+
+func TestMeetingEvents_ExecuteJSON(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, true, "1710000000000000000"))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "json",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := strings.ReplaceAll(stdout.String(), " ", "")
+	out = strings.ReplaceAll(out, "\n", "")
+	for _, want := range []string{
+		`"event_type":"participant_joined"`,
+		`"has_more":true`,
+		`"page_token":"1710000000000000000"`,
+		`"events":[`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("json output missing %q: %s", want, stdout.String())
+		}
+	}
+}
+
+func TestMeetingEvents_ExecuteJSON_PrunesEmptySlices(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{chatReceivedEvent()}, false, ""))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "json",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := stdout.String()
+	for _, unwanted := range []string{
+		`"participant_joined_items": []`,
+		`"participant_left_items": []`,
+		`"transcript_received_items": []`,
+		`"magic_share_started_items": []`,
+		`"magic_share_ended_items": []`,
+	} {
+		if strings.Contains(out, unwanted) {
+			t.Fatalf("json output should not contain %q: %s", unwanted, out)
+		}
+	}
+	if !strings.Contains(out, `"message_type": 3`) {
+		t.Fatalf("json output should keep numeric fields: %s", out)
+	}
+}
+
+func TestMeetingEvents_ExecutePretty(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEventOngoing(), multiChatReceivedEvent(), magicShareStartedEvent()}, true, "1710000000000000000"))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "pretty",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := stdout.String()
+	for _, want := range []string{
+		"会议主题：项目例会",
+		"会议时间：2026-04-17 15:15:00（进行中）",
+		"Demo Bot(bot_001) 加入了会议",
+		"Alice(u1): [reaction] 第一条\\n第二行",
+		"Alice(u1): [reaction] 第二条",
+		"Bob(u2) 开始共享「共享文档」",
+		"URL: https://example.com/doc",
+		"page_token: 1710000000000000000",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("pretty output missing %q: %s", want, out)
+		}
+	}
+	if strings.Contains(out, "第二条\n\n[") {
+		t.Fatalf("pretty output should not insert blank lines between event entries: %s", out)
+	}
+	if !strings.Contains(out, "第二条\n[") {
+		t.Fatalf("pretty output should keep event entries contiguous: %s", out)
+	}
+}
+
+func TestMeetingEvents_ExecutePretty_PrintsPageTokenWithoutHasMore(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub([]interface{}{participantJoinedEventOngoing()}, false, "pt_last"))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "pretty",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	out := stdout.String()
+	if !strings.Contains(out, "page_token: pt_last") {
+		t.Fatalf("pretty output should print page_token even when has_more is false: %s", out)
+	}
+	if strings.Contains(out, "more available") {
+		t.Fatalf("pretty output should not print more-available hint when has_more is false: %s", out)
+	}
+}
+
+func TestMeetingEvents_ExecuteEmpty(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingEventsStub(nil, false, ""))
+
+	err := mountAndRun(t, VCMeetingEvents, []string{
+		"+meeting-events",
+		"--meeting-id", "7628568141510692381",
+		"--format", "pretty",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	reg.Verify(t)
+
+	if !strings.Contains(stdout.String(), "No meeting events.") {
+		t.Fatalf("unexpected output: %s", stdout.String())
+	}
+}
+
+func TestParseFlexibleTime(t *testing.T) {
+	t.Run("unix seconds", func(t *testing.T) {
+		got, ok := parseFlexibleTime("1776410100")
+		if !ok {
+			t.Fatal("parseFlexibleTime() ok = false, want true")
+		}
+		if want := time.Unix(1776410100, 0); !got.Equal(want) {
+			t.Fatalf("parseFlexibleTime() = %v, want %v", got, want)
+		}
+	})
+
+	t.Run("unix millis", func(t *testing.T) {
+		got, ok := parseFlexibleTime("1776408061000")
+		if !ok {
+			t.Fatal("parseFlexibleTime() ok = false, want true")
+		}
+		if want := time.UnixMilli(1776408061000); !got.Equal(want) {
+			t.Fatalf("parseFlexibleTime() = %v, want %v", got, want)
+		}
+	})
+
+	t.Run("rfc3339", func(t *testing.T) {
+		got, ok := parseFlexibleTime("2026-04-17T08:00:00Z")
+		if !ok {
+			t.Fatal("parseFlexibleTime() ok = false, want true")
+		}
+		if want, _ := time.Parse(time.RFC3339, "2026-04-17T08:00:00Z"); !got.Equal(want) {
+			t.Fatalf("parseFlexibleTime() = %v, want %v", got, want)
+		}
+	})
+
+	t.Run("invalid", func(t *testing.T) {
+		if _, ok := parseFlexibleTime("not-a-time"); ok {
+			t.Fatal("parseFlexibleTime() ok = true, want false")
+		}
+	})
+}
+
+func TestFormatMeetingWindow(t *testing.T) {
+	start := time.Unix(1776410100, 0)
+	end := time.Unix(1776413700, 0)
+
+	tests := []struct {
+		name     string
+		start    time.Time
+		hasStart bool
+		end      time.Time
+		hasEnd   bool
+		want     string
+	}{
+		{
+			name:     "ongoing",
+			start:    start,
+			hasStart: true,
+			end:      start,
+			hasEnd:   true,
+			want:     "2026-04-17 15:15:00（进行中）",
+		},
+		{
+			name:     "finished range",
+			start:    start,
+			hasStart: true,
+			end:      end,
+			hasEnd:   true,
+			want:     "2026-04-17 15:15:00 - 2026-04-17 16:15:00",
+		},
+		{
+			name:     "only start",
+			start:    start,
+			hasStart: true,
+			want:     "2026-04-17 15:15:00",
+		},
+		{
+			name:   "only end",
+			end:    end,
+			hasEnd: true,
+			want:   "2026-04-17 16:15:00",
+		},
+		{
+			name: "empty",
+			want: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := formatMeetingWindow(tt.start, tt.hasStart, tt.end, tt.hasEnd); got != tt.want {
+				t.Fatalf("formatMeetingWindow() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFormatTimelineOffset(t *testing.T) {
+	start := time.Unix(1776410100, 0)
+	later := start.Add(90 * time.Second)
+	earlier := start.Add(-5 * time.Minute)
+
+	tests := []struct {
+		name            string
+		when            time.Time
+		hasWhen         bool
+		meetingStart    time.Time
+		hasMeetingStart bool
+		want            string
+	}{
+		{
+			name:            "with meeting start",
+			when:            later,
+			hasWhen:         true,
+			meetingStart:    start,
+			hasMeetingStart: true,
+			want:            "00:01:30",
+		},
+		{
+			name:            "negative diff clamps to zero",
+			when:            earlier,
+			hasWhen:         true,
+			meetingStart:    start,
+			hasMeetingStart: true,
+			want:            "00:00:00",
+		},
+		{
+			name:    "without meeting start uses wall clock",
+			when:    later,
+			hasWhen: true,
+			want:    "15:16:30",
+		},
+		{
+			name: "missing when",
+			want: "??:??:??",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := formatTimelineOffset(tt.when, tt.hasWhen, tt.meetingStart, tt.hasMeetingStart); got != tt.want {
+				t.Fatalf("formatTimelineOffset() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFlattenQueryParams(t *testing.T) {
+	params := larkcore.QueryParams{
+		"one":   []string{"1"},
+		"many":  []string{"2", "3"},
+		"empty": []string{},
+	}
+
+	got := flattenQueryParams(params)
+	want := map[string]interface{}{
+		"one":  "1",
+		"many": []string{"2", "3"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("flattenQueryParams() = %#v, want %#v", got, want)
+	}
+}
+
+func TestCompactMeetingPayload_DropsOnlyEmptySlices(t *testing.T) {
+	got := compactMeetingPayload(map[string]interface{}{
+		"empty_items": []interface{}{},
+		"items":       []interface{}{"x"},
+		"zero":        0,
+		"text":        "ok",
+	})
+
+	if _, ok := got["empty_items"]; ok {
+		t.Fatalf("compactMeetingPayload() should drop empty_items: %#v", got)
+	}
+	if !reflect.DeepEqual(got["items"], []interface{}{"x"}) {
+		t.Fatalf("compactMeetingPayload() items = %#v, want %#v", got["items"], []interface{}{"x"})
+	}
+	if got["zero"] != 0 || got["text"] != "ok" {
+		t.Fatalf("compactMeetingPayload() preserved fields mismatch: %#v", got)
+	}
+}
+
+func TestCompactMeetingEvents_IgnoresNonMapsAndCompactsPayload(t *testing.T) {
+	got := compactMeetingEvents([]interface{}{
+		"skip-me",
+		map[string]interface{}{
+			"event_type": "chat_received",
+			"payload": map[string]interface{}{
+				"chat_received_items": []interface{}{"x"},
+				"empty_items":         []interface{}{},
+			},
+		},
+	})
+
+	if len(got) != 1 {
+		t.Fatalf("len(compactMeetingEvents()) = %d, want 1", len(got))
+	}
+	event, _ := got[0].(map[string]interface{})
+	payload := common.GetMap(event, "payload")
+	if _, ok := payload["empty_items"]; ok {
+		t.Fatalf("compactMeetingEvents() should prune empty payload slices: %#v", payload)
+	}
+}
+
+func TestVCShortcuts_RegistersMeetingAgentCommands(t *testing.T) {
+	got := Shortcuts()
+	var commands []string
+	for _, shortcut := range got {
+		commands = append(commands, shortcut.Command)
+	}
+	want := []string{"+search", "+notes", "+recording", "+meeting-join", "+meeting-leave", "+meeting-events"}
+	if !reflect.DeepEqual(commands, want) {
+		t.Fatalf("shortcut commands = %#v, want %#v", commands, want)
+	}
+}
+
+func TestLeaveAction(t *testing.T) {
+	tests := []struct {
+		name string
+		item map[string]interface{}
+		want string
+	}{
+		{name: "meeting ended", item: map[string]interface{}{"leave_reason": 2}, want: "因会议结束离开了会议"},
+		{name: "kicked", item: map[string]interface{}{"leave_reason": 3}, want: "被移出了会议"},
+		{name: "default", item: map[string]interface{}{"leave_reason": 1}, want: "离开了会议"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := leaveAction(tt.item); got != tt.want {
+				t.Fatalf("leaveAction() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestMeetingEventUserWithID(t *testing.T) {
+	tests := []struct {
+		name string
+		user map[string]interface{}
+		want string
+	}{
+		{name: "nil", want: ""},
+		{name: "name and id", user: map[string]interface{}{"user_name": "Alice", "id": "u1"}, want: "Alice(u1)"},
+		{name: "name only", user: map[string]interface{}{"user_name": "Alice"}, want: "Alice"},
+		{name: "id only", user: map[string]interface{}{"id": "u1"}, want: "u1"},
+		{name: "empty", user: map[string]interface{}{}, want: ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := meetingEventUserWithID(tt.user); got != tt.want {
+				t.Fatalf("meetingEventUserWithID() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestMeetingEventSummary(t *testing.T) {
+	tests := []struct {
+		name  string
+		event map[string]interface{}
+		want  string
+	}{
+		{
+			name: "participant joined count",
+			event: map[string]interface{}{
+				"event_type": "participant_joined",
+				"payload": map[string]interface{}{
+					"participant_joined_items": []interface{}{
+						map[string]interface{}{},
+						map[string]interface{}{},
+					},
+				},
+			},
+			want: "2 participants joined",
+		},
+		{
+			name: "participant left with label",
+			event: map[string]interface{}{
+				"event_type": "participant_left",
+				"payload": map[string]interface{}{
+					"participant_left_items": []interface{}{
+						map[string]interface{}{"participant": map[string]interface{}{"user_name": "Bob", "id": "u2"}},
+					},
+				},
+			},
+			want: "participant u2 (Bob) left",
+		},
+		{
+			name: "fallback unknown event",
+			event: map[string]interface{}{
+				"event_type": "mystery_event",
+				"payload":    map[string]interface{}{},
+			},
+			want: "mystery_event",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := meetingEventSummary(tt.event); got != tt.want {
+				t.Fatalf("meetingEventSummary() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestEscapePrettyText(t *testing.T) {
+	got := escapePrettyText("line1\nline2\t\r" + string(rune(0x07)))
+	want := `line1\nline2\t\r\u0007`
+	if got != want {
+		t.Fatalf("escapePrettyText() = %q, want %q", got, want)
+	}
+}
+
+func TestNeedsColon(t *testing.T) {
+	tests := []struct {
+		description string
+		want        bool
+	}{
+		{description: "发送了消息", want: false},
+		{description: "加入了会议", want: false},
+		{description: "离开了会议", want: false},
+		{description: "开始共享「文档」", want: false},
+		{description: "[text] hello", want: true},
+	}
+	for _, tt := range tests {
+		if got := needsColon(tt.description); got != tt.want {
+			t.Fatalf("needsColon(%q) = %v, want %v", tt.description, got, tt.want)
+		}
+	}
+}

shortcuts/vc/vc_meeting_join.go

@@ -0,0 +1,94 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var meetingNumberRe = regexp.MustCompile(`^\d{9}$`)
+
+// validMeetingNumber checks whether s is a valid 9-digit meeting number.
+func validMeetingNumber(s string) bool {
+	return meetingNumberRe.MatchString(s)
+}
+
+// VCMeetingJoin joins a meeting by meeting number via /vc/v1/bots/join.
+var VCMeetingJoin = common.Shortcut{
+	Service:     "vc",
+	Command:     "+meeting-join",
+	Description: "Join a meeting by meeting number (bot join)",
+	Risk:        "write",
+	Scopes:      []string{"vc:meeting.bot.join:write"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "meeting-number", Required: true, Desc: "meeting number to join"},
+		{Name: "password", Desc: "meeting password (if required)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		mn := strings.TrimSpace(runtime.Str("meeting-number"))
+		if !validMeetingNumber(mn) {
+			return common.FlagErrorf("--meeting-number must be exactly 9 digits, got %q", mn)
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		body := buildMeetingJoinBody(runtime)
+		return common.NewDryRunAPI().
+			POST("/open-apis/vc/v1/bots/join").
+			Body(body)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		body := buildMeetingJoinBody(runtime)
+		data, err := runtime.DoAPIJSON("POST", "/open-apis/vc/v1/bots/join", nil, body)
+		if err != nil {
+			return err
+		}
+		if data == nil {
+			data = map[string]interface{}{}
+		}
+		runtime.OutFormat(data, nil, func(w io.Writer) {
+			meeting, _ := data["meeting"].(map[string]interface{})
+			if meeting == nil {
+				fmt.Fprintln(w, "Joined meeting (no meeting info returned).")
+				return
+			}
+			fmt.Fprintf(w, "Joined meeting successfully.\n")
+			if id := common.GetString(meeting, "id"); id != "" {
+				fmt.Fprintf(w, "  Meeting ID:  %s\n", id)
+			}
+			if no := common.GetString(meeting, "meeting_no"); no != "" {
+				fmt.Fprintf(w, "  Meeting No:  %s\n", no)
+			}
+			if topic := common.GetString(meeting, "topic"); topic != "" {
+				fmt.Fprintf(w, "  Topic:       %s\n", topic)
+			}
+			if startTime := common.GetString(meeting, "start_time"); startTime != "" {
+				fmt.Fprintf(w, "  Start Time:  %s\n", startTime)
+			}
+		})
+		return nil
+	},
+}
+
+func buildMeetingJoinBody(runtime *common.RuntimeContext) map[string]interface{} {
+	meetingNo := strings.TrimSpace(runtime.Str("meeting-number"))
+	body := map[string]interface{}{
+		"join_type": 1,
+		"join_identify": map[string]interface{}{
+			"meeting_no": meetingNo,
+		},
+	}
+	if pw := strings.TrimSpace(runtime.Str("password")); pw != "" {
+		body["password"] = pw
+	}
+	return body
+}

shortcuts/vc/vc_meeting_leave.go

@@ -0,0 +1,57 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// VCMeetingLeave leaves a meeting via /vc/v1/bots/leave.
+var VCMeetingLeave = common.Shortcut{
+	Service:     "vc",
+	Command:     "+meeting-leave",
+	Description: "Leave a meeting by meeting ID",
+	Risk:        "write",
+	Scopes:      []string{"vc:meeting.bot.join:write"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "meeting-id", Required: true, Desc: "meeting ID to leave"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if strings.TrimSpace(runtime.Str("meeting-id")) == "" {
+			return common.FlagErrorf("--meeting-id is required")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		return common.NewDryRunAPI().
+			POST("/open-apis/vc/v1/bots/leave").
+			Body(map[string]interface{}{
+				"meeting_id": strings.TrimSpace(runtime.Str("meeting-id")),
+			})
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		meetingID := strings.TrimSpace(runtime.Str("meeting-id"))
+		body := map[string]interface{}{
+			"meeting_id": meetingID,
+		}
+		data, err := runtime.DoAPIJSON("POST", "/open-apis/vc/v1/bots/leave", nil, body)
+		if err != nil {
+			return err
+		}
+		if data == nil {
+			data = map[string]interface{}{}
+		}
+		runtime.OutFormat(data, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Left meeting %s successfully.\n", meetingID)
+		})
+		return nil
+	},
+}

shortcuts/vc/vc_meeting_test.go

@@ -0,0 +1,536 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ---------------------------------------------------------------------------
+// Unit tests: pure functions
+// ---------------------------------------------------------------------------
+
+func TestValidMeetingNumber(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want bool
+	}{
+		{"9 digits", "123456789", true},
+		{"9 digits leading zero", "012345678", true},
+		{"empty", "", false},
+		{"8 digits", "12345678", false},
+		{"10 digits", "1234567890", false},
+		{"with space", "12345 678", false},
+		{"letters mixed", "12345678a", false},
+		{"pure letters", "abcdefghi", false},
+		{"with dash", "123-456-789", false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := validMeetingNumber(tt.in); got != tt.want {
+				t.Errorf("validMeetingNumber(%q) = %v, want %v", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestBuildMeetingJoinBody_WithoutPassword(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-number", "", "")
+	cmd.Flags().String("password", "", "")
+	_ = cmd.Flags().Set("meeting-number", "123456789")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	body := buildMeetingJoinBody(runtime)
+
+	if body["join_type"] != 1 {
+		t.Errorf("join_type = %v, want 1", body["join_type"])
+	}
+	ji, ok := body["join_identify"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("join_identify missing or wrong type: %v", body["join_identify"])
+	}
+	if ji["meeting_no"] != "123456789" {
+		t.Errorf("meeting_no = %v, want 123456789", ji["meeting_no"])
+	}
+	if _, exists := body["password"]; exists {
+		t.Errorf("password should be omitted when empty, got %v", body["password"])
+	}
+}
+
+func TestBuildMeetingJoinBody_WithPassword(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-number", "", "")
+	cmd.Flags().String("password", "", "")
+	_ = cmd.Flags().Set("meeting-number", "123456789")
+	_ = cmd.Flags().Set("password", "secret")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	body := buildMeetingJoinBody(runtime)
+
+	if body["password"] != "secret" {
+		t.Errorf("password = %v, want secret", body["password"])
+	}
+}
+
+func TestBuildMeetingJoinBody_TrimsWhitespace(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-number", "", "")
+	cmd.Flags().String("password", "", "")
+	_ = cmd.Flags().Set("meeting-number", "  123456789  ")
+	_ = cmd.Flags().Set("password", "  pw  ")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	body := buildMeetingJoinBody(runtime)
+
+	ji, _ := body["join_identify"].(map[string]interface{})
+	if ji["meeting_no"] != "123456789" {
+		t.Errorf("meeting_no should be trimmed, got %q", ji["meeting_no"])
+	}
+	if body["password"] != "pw" {
+		t.Errorf("password should be trimmed, got %q", body["password"])
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Validate tests: VCMeetingJoin
+// ---------------------------------------------------------------------------
+
+func TestMeetingJoin_Validate_MissingNumber(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	// cobra MarkFlagRequired should reject missing --meeting-number
+	err := mountAndRun(t, VCMeetingJoin, []string{"+meeting-join", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected error when --meeting-number is missing")
+	}
+	if !strings.Contains(err.Error(), "meeting-number") {
+		t.Errorf("error should mention meeting-number, got: %v", err)
+	}
+}
+
+func TestMeetingJoin_Validate_InvalidFormat(t *testing.T) {
+	tests := []struct {
+		name string
+		num  string
+	}{
+		{"too short", "12345678"},
+		{"too long", "1234567890"},
+		{"with letters", "12345abcd"},
+		{"empty after trim", "   "},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("meeting-number", "", "")
+			cmd.Flags().String("password", "", "")
+			_ = cmd.Flags().Set("meeting-number", tt.num)
+
+			runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+			err := VCMeetingJoin.Validate(context.Background(), runtime)
+			if err == nil {
+				t.Fatalf("expected validation error for %q", tt.num)
+			}
+			if !strings.Contains(err.Error(), "9 digits") {
+				t.Errorf("error should mention '9 digits', got: %v", err)
+			}
+		})
+	}
+}
+
+func TestMeetingJoin_Validate_Valid(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-number", "", "")
+	cmd.Flags().String("password", "", "")
+	_ = cmd.Flags().Set("meeting-number", "123456789")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	if err := VCMeetingJoin.Validate(context.Background(), runtime); err != nil {
+		t.Errorf("unexpected validation error: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// DryRun tests: VCMeetingJoin
+// ---------------------------------------------------------------------------
+
+func TestMeetingJoin_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789", "--password", "pw123",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "/open-apis/vc/v1/bots/join") {
+		t.Errorf("dry-run should include API path, got: %s", out)
+	}
+	if !strings.Contains(out, "123456789") {
+		t.Errorf("dry-run should include meeting number, got: %s", out)
+	}
+	if !strings.Contains(out, "pw123") {
+		t.Errorf("dry-run should include password, got: %s", out)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execute tests: VCMeetingJoin
+// ---------------------------------------------------------------------------
+
+func TestMeetingJoin_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"meeting": map[string]interface{}{
+					"id":         "69999999",
+					"meeting_no": "123456789",
+					"topic":      "Weekly Sync",
+					"start_time": "1700000000",
+				},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// verify captured request body
+	if len(stub.CapturedBody) == 0 {
+		t.Fatal("expected request body to be captured")
+	}
+	var req map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &req); err != nil {
+		t.Fatalf("failed to parse request body: %v", err)
+	}
+	if req["join_type"].(float64) != 1 {
+		t.Errorf("join_type = %v, want 1", req["join_type"])
+	}
+	ji, _ := req["join_identify"].(map[string]interface{})
+	if ji["meeting_no"] != "123456789" {
+		t.Errorf("meeting_no = %v, want 123456789", ji["meeting_no"])
+	}
+	if _, exists := ji["password"]; exists {
+		t.Errorf("password should be omitted when not provided, got %v", ji["password"])
+	}
+
+	// verify response envelope carries meeting info under data.meeting
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse stdout: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meeting, _ := data["meeting"].(map[string]any)
+	if meeting["id"] != "69999999" {
+		t.Errorf("meeting.id = %v, want 69999999 (envelope: %s)", meeting["id"], stdout.String())
+	}
+}
+
+func TestMeetingJoin_Execute_WithPassword_CapturesBody(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "987654321", "--password", "s3cret",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var req map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &req); err != nil {
+		t.Fatalf("failed to parse request body: %v", err)
+	}
+	ji, _ := req["join_identify"].(map[string]interface{})
+	if req["password"] != "s3cret" {
+		t.Errorf("password = %v, want s3cret", req["password"])
+	}
+	if ji["meeting_no"] != "987654321" {
+		t.Errorf("meeting_no = %v, want 987654321", ji["meeting_no"])
+	}
+}
+
+func TestMeetingJoin_Execute_PrettyOutput(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"meeting": map[string]interface{}{
+					"id":         "69999999",
+					"meeting_no": "123456789",
+					"topic":      "Weekly Sync",
+					"start_time": "1700000000",
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789",
+		"--format", "pretty", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"Joined meeting successfully", "69999999", "123456789", "Weekly Sync", "1700000000"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("pretty output missing %q, got: %s", want, out)
+		}
+	}
+}
+
+func TestMeetingJoin_Execute_PrettyOutput_NoMeetingInfo(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789",
+		"--format", "pretty", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "no meeting info returned") {
+		t.Errorf("pretty output should fall back to 'no meeting info' notice, got: %s", stdout.String())
+	}
+}
+
+func TestMeetingLeave_Execute_PrettyOutput(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/leave",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "69999999",
+		"--format", "pretty", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "Left meeting 69999999 successfully") {
+		t.Errorf("pretty output should confirm leave, got: %s", out)
+	}
+}
+
+func TestMeetingJoin_Execute_APIError(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/join",
+		Body:   map[string]interface{}{"code": 190001, "msg": "invalid meeting number"},
+	})
+
+	err := mountAndRun(t, VCMeetingJoin, []string{
+		"+meeting-join", "--meeting-number", "123456789",
+		"--as", "user",
+	}, f, &bytes.Buffer{})
+	if err == nil {
+		t.Fatal("expected error for API failure")
+	}
+	if !strings.Contains(err.Error(), "invalid meeting number") {
+		t.Errorf("error should surface API message, got: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Validate tests: VCMeetingLeave
+// ---------------------------------------------------------------------------
+
+func TestMeetingLeave_Validate_MissingID(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingLeave, []string{"+meeting-leave", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected error when --meeting-id is missing")
+	}
+	if !strings.Contains(err.Error(), "meeting-id") {
+		t.Errorf("error should mention meeting-id, got: %v", err)
+	}
+}
+
+func TestMeetingLeave_Validate_WhitespaceOnly(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-id", "", "")
+	_ = cmd.Flags().Set("meeting-id", "   ")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	err := VCMeetingLeave.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected error for whitespace-only meeting-id")
+	}
+	if !strings.Contains(err.Error(), "meeting-id") {
+		t.Errorf("error should mention meeting-id, got: %v", err)
+	}
+}
+
+func TestMeetingLeave_Validate_Valid(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("meeting-id", "", "")
+	_ = cmd.Flags().Set("meeting-id", "69999999")
+
+	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
+	if err := VCMeetingLeave.Validate(context.Background(), runtime); err != nil {
+		t.Errorf("unexpected validation error: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// DryRun tests: VCMeetingLeave
+// ---------------------------------------------------------------------------
+
+func TestMeetingLeave_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "69999999",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "/open-apis/vc/v1/bots/leave") {
+		t.Errorf("dry-run should include API path, got: %s", out)
+	}
+	if !strings.Contains(out, "69999999") {
+		t.Errorf("dry-run should include meeting-id, got: %s", out)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execute tests: VCMeetingLeave
+// ---------------------------------------------------------------------------
+
+func TestMeetingLeave_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/leave",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "69999999",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// verify captured request body
+	var req map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &req); err != nil {
+		t.Fatalf("failed to parse request body: %v", err)
+	}
+	if req["meeting_id"] != "69999999" {
+		t.Errorf("meeting_id = %v, want 69999999", req["meeting_id"])
+	}
+}
+
+func TestMeetingLeave_Execute_TrimsMeetingID(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/leave",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "  69999999  ",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var req map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &req); err != nil {
+		t.Fatalf("failed to parse request body: %v", err)
+	}
+	if req["meeting_id"] != "69999999" {
+		t.Errorf("meeting_id should be trimmed, got %q", req["meeting_id"])
+	}
+}
+
+func TestMeetingLeave_Execute_APIError(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/vc/v1/bots/leave",
+		Body:   map[string]interface{}{"code": 121005, "msg": "no permission"},
+	})
+
+	err := mountAndRun(t, VCMeetingLeave, []string{
+		"+meeting-leave", "--meeting-id", "69999999", "--as", "user",
+	}, f, &bytes.Buffer{})
+	if err == nil {
+		t.Fatal("expected error for API failure")
+	}
+	if !strings.Contains(err.Error(), "no permission") {
+		t.Errorf("error should surface API message, got: %v", err)
+	}
+}

skill-template/domains/doc.md

@@ -86,8 +86,8 @@ Drive Folder (云空间文件夹)
 
 ## 重要说明：画板编辑
 > **⚠️ lark-doc skill 不能直接编辑已有画板内容，但 `docs +update` 可以新建空白画板**
-### 场景 1：已通过 docs +fetch 获取到文档内容和画板 token
-如果用户已经通过 `docs +fetch` 拉取了文档内容，并且文档中已有画板（返回的 markdown 中包含 `<whiteboard token="xxx"/>` 标签），请引导用户：
+### 场景 1：已通过 docs +fetch --api-version v2 获取到文档内容和画板 token
+如果用户已经通过 `docs +fetch --api-version v2` 拉取了文档内容，并且文档中已有画板（返回的 markdown 中包含 `<whiteboard token="xxx"/>` 标签），请引导用户：
 1. 记录画板的 token
 2. 查看 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) 了解如何编辑画板内容
 ### 场景 2：刚创建画板，需要编辑
@@ -115,4 +115,4 @@ Drive Folder (云空间文件夹)
 - 用户说“给文档加评论”“查看评论”“回复评论”“给评论加表情 / reaction”“删除评论表情 / reaction”，**不要留在 `lark-doc`**，直接切到 `lark-drive` 处理。
 
 ## 补充说明 
-`docs +search` 除了搜索文档 / Wiki，也承担“先定位云空间对象，再切回对应业务 skill 操作”的资源发现入口角色；当用户口头说“表格 / 报表”时，也优先从这里开始。
+`docs +search` 除了搜索文档 / Wiki，也承担“先定位云空间对象，再切回对应业务 skill 操作”的资源发现入口角色；当用户口头说“表格 / 报表”时，也优先从这里开始。

skill-template/domains/drive.md

@@ -101,7 +101,7 @@ Drive Folder (云空间文件夹)
 
 | 操作 | 需要的 Token | 说明 |
 |------|-------------|------|
-| 读取文档内容 | `file_token` / 通过 `docs +fetch` 自动处理 | `docs +fetch` 支持直接传入 URL |
+| 读取文档内容 | `file_token` / 通过 `docs +fetch --api-version v2` 自动处理 | `docs +fetch --api-version v2` 支持直接传入 URL |
 | 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL |
 | 添加全文评论 | `file_token` | 不传 `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL，以及最终解析为 `doc`/`docx` 的 wiki URL |
 | 下载文件 | `file_token` | 从文件 URL 中直接提取 |

skills/lark-approval/SKILL.md

@@ -35,6 +35,8 @@ lark-cli approval <resource> <method> [flags] # 调用 API
   - `reject` — 拒绝审批任务
   - `transfer` — 转交审批任务
   - `query` — 查询用户的任务列表
+  - `add_sign` — 审批任务加签
+  - `rollback` — 退回审批任务
 
 ## 权限表
 
@@ -49,4 +51,6 @@ lark-cli approval <resource> <method> [flags] # 调用 API
 | `tasks.reject` | `approval:task:write` |
 | `tasks.transfer` | `approval:task:write` |
 | `tasks.query` | `approval:task:read` |
+| `tasks.add_sign` | `approval:task:write` |
+| `tasks.rollback` | `approval:task:write` |
 

skills/lark-base/SKILL.md

@@ -12,6 +12,7 @@ metadata:
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。
 > **执行前必做：** 执行任何 `base` 命令前，必须先阅读对应命令的 reference 文档，再调用命令。
+> **查询类任务必做：** 涉及筛选、排序、Top/Bottom N、聚合、多表关联、查询后写入或判断全局结论时，必须先阅读 [`references/lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md)，再选择 `record / view / data-query` 路径。
 > **命名约定：** Base 业务命令仅使用 `lark-cli base +...` 形式；如需先解析 Wiki 链接，可先调用 `lark-cli wiki ...`。
 > **分流规则：** 如果用户要“把本地文件导入成 Base / 多维表格 / bitable”，第一步不是 `base`，而是 `lark-cli drive +import --type bitable`；导入完成后再回到 `lark-cli base +...` 做表内操作。
 
@@ -104,7 +105,7 @@ metadata:
 
 | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
 |------|------------------|----------------|----------|
-| `+record-search / +record-list / +record-get` | 按关键词检索记录、读取记录明细 / 分页导出，或按 ID 获取一条或多条记录 | [`lark-base-record-read-sop.md`](references/lark-base-record-read-sop.md) | 记录读取统一先读 read SOP guide：已知 `record_id` 用 `+record-get`；明确关键词用 `+record-search`；普通明细用 `+record-list`；明确筛选 / 排序 / Top N 用临时视图投影后 `+record-list --view-id`；统计聚合才分流到 `+data-query`；`+record-get` 支持重复 `--record-id` 或 `--json` 读取多条记录 |
+| `+record-search / +record-list / +record-get` | 按关键词检索记录、读取记录明细 / 分页导出，或按 ID 获取一条或多条记录 | [`lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md) | 记录读取统一先读 data analysis SOP：已知 `record_id` 用 `+record-get`；明确关键词用 `+record-search`；普通明细用 `+record-list`；明确筛选 / 排序 / Top N 用临时视图投影后 `+record-list --view-id`；统计聚合才分流到 `+data-query`；`+record-get` 支持重复 `--record-id` 或 `--json` 读取多条记录 |
 | `+record-upsert / +record-batch-create / +record-batch-update` | 创建、更新或批量写入记录 | [`lark-base-record-upsert.md`](references/lark-base-record-upsert.md)、[`lark-base-record-batch-create.md`](references/lark-base-record-batch-create.md)、[`lark-base-record-batch-update.md`](references/lark-base-record-batch-update.md)、[`lark-base-cell-value.md`](references/lark-base-cell-value.md) | 写前先 `+field-list`；只写存储字段；`+record-batch-update` 为同值更新（同一 patch 应用到多条记录）；批量单次不超过 `200` 条；附件不要走这里 |
 | `+record-upload-attachment` | 给已有记录上传附件 | [`lark-base-record-upload-attachment.md`](references/lark-base-record-upload-attachment.md) | 附件上传专用链路，不要用 `+record-upsert` / `+record-batch-*` 伪造附件值 |
 | `lark-cli docs +media-download` | 下载 Base 附件文件到本地 | [`../lark-doc/references/lark-doc-media-download.md`](../lark-doc/references/lark-doc-media-download.md) | Base 附件的 `file_token` 从 `+record-get` 返回的附件字段数组里取；**不要用 `lark-cli drive +download`**（对 Base 附件返回 403） |
@@ -120,7 +121,7 @@ metadata:
 |------|------------------|----------------|----------|
 | `+view-list / +view-get` | 列出视图，或获取视图详情 | [`lark-base-view-list.md`](references/lark-base-view-list.md)、[`lark-base-view-get.md`](references/lark-base-view-get.md) | `+view-list` 只能串行执行；`+view-get` 适合查看已有视图配置 |
 | `+view-create / +view-delete / +view-rename` | 创建、删除或重命名视图 | [`lark-base-view-create.md`](references/lark-base-view-create.md)、[`lark-base-view-delete.md`](references/lark-base-view-delete.md)、[`lark-base-view-rename.md`](references/lark-base-view-rename.md) | 创建前先确认表和视图类型；删除前先确认目标；用户已明确新名字时可直接重命名 |
-| `+view-get-filter / +view-set-filter` | 读取或配置筛选条件 | [`lark-base-view-get-filter.md`](references/lark-base-view-get-filter.md)、[`lark-base-view-set-filter.md`](references/lark-base-view-set-filter.md)、[`lark-base-record-read-sop.md`](references/lark-base-record-read-sop.md) | 常与 `+record-list` 组合，用于按视图筛选读取 |
+| `+view-get-filter / +view-set-filter` | 读取或配置筛选条件 | [`lark-base-view-get-filter.md`](references/lark-base-view-get-filter.md)、[`lark-base-view-set-filter.md`](references/lark-base-view-set-filter.md)、[`lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md) | 常与 `+record-list` 组合，用于按视图筛选读取 |
 | `+view-get-sort / +view-set-sort` | 读取或配置排序 | [`lark-base-view-get-sort.md`](references/lark-base-view-get-sort.md)、[`lark-base-view-set-sort.md`](references/lark-base-view-set-sort.md) | 字段名必须来自真实结构 |
 | `+view-get-group / +view-set-group` | 读取或配置分组 | [`lark-base-view-get-group.md`](references/lark-base-view-get-group.md)、[`lark-base-view-set-group.md`](references/lark-base-view-set-group.md) | 字段名必须来自真实结构 |
 | `+view-get-visible-fields / +view-set-visible-fields` | 读取或配置视图可见字段 | [`lark-base-view-get-visible-fields.md`](references/lark-base-view-get-visible-fields.md)、[`lark-base-view-set-visible-fields.md`](references/lark-base-view-set-visible-fields.md) | 用于控制视图中的字段顺序与可见性；字段名必须来自真实结构 |
@@ -228,14 +229,24 @@ metadata:
 | 基于视图做筛选读取 | `+view-set-filter` + `+record-list` | 不要跳过视图筛选直接猜条件 |
 | 本地 Excel / CSV / `.base` 导入为 Base | `lark-cli drive +import --type bitable` | 不要误走 `+base-create`、`+table-create` 或 `+record-upsert` |
 
-### 3.3 表名、字段名与表达式引用
+### 3.3 查询执行契约
+
+涉及查询、统计或判断结论时，先阅读 [`references/lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md)，并遵守以下高优先级规则：
+
+1. `+record-list` 默认页、固定 `--limit` 和本地 `jq` 只能证明已读取范围内的事实，不能直接支撑全局最值、全量计数、Top/Bottom N、异常识别或分组结论。
+2. 能由 Base 表达的筛选、排序、投影、聚合、分组和限制，应在 Base 云端查询服务中执行；不要先拉明细到本地上下文再手工筛选排序。
+3. `has_more=true` 或等价分页信号表示当前结果不是全量；除非用户只要样例/前 N 条，不能基于该页回答全局问题。
+4. 多表查询必须先确认关系字段和连接键；link 单元格里的 `record_id` 是关系键，不是用户可读答案。
+5. 最终答案必须能追溯到真实表、真实字段、查询范围、筛选/排序/聚合条件和必要的连接键。
+
+### 3.4 表名、字段名与表达式引用
 
 1. 表名、字段名必须精确匹配真实返回，来源应是 `+table-list / +table-get / +field-list`。
 2. 不要凭自然语言猜名称，不要自行改写用户口述中的表名、字段名。
 3. `formula / lookup / data-query / workflow` 中出现的名称同样必须精确匹配；表达式引用、where 条件、DSL 字段名、workflow 配置都遵守同一规则。
 4. 跨表场景必须额外读取目标表结构，不能只看当前表。
 
-### 3.4 Token 与链接
+### 3.5 Token 与链接
 
 这是高优先级章节。只要用户输入里出现链接、token，或报错涉及 `baseToken` / `wiki_token` / `obj_token`，都应优先回到这里检查。
 
@@ -254,7 +265,7 @@ metadata:
 | `slides` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 |
 | `mindnote` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 |
 
-### 3.5 身份选择与权限降级策略
+### 3.6 身份选择与权限降级策略
 
 多维表格通常属于用户的个人或团队资源。**默认应优先使用 `--as user`（用户身份）执行所有 Base 操作**，始终显式指定身份。
 
@@ -282,10 +293,11 @@ lark-cli auth login --domain base
 
 1. 先判断任务属于哪个模块，选对命令族。
 2. 如果用户给了链接，先解析 token，不要把 wiki token、完整 URL 或其他对象 ID 误当成 `base_token`。
-3. 先拿结构，再写命令，避免猜表名、字段名、表达式引用。
-4. 定位到命令后，先读对应 reference，再执行命令。
-5. 执行命令，并按返回结果判断下一步。
-6. 回复时返回关键结果和后续可继续操作的信息，方便 agent 链式执行下一步。
+3. 如果是查询类任务，先判断问题范围，阅读 data analysis SOP，再决定使用 `record / view / data-query`。
+4. 先拿结构，再写命令，避免猜表名、字段名、表达式引用。
+5. 定位到命令后，先读对应 reference，再执行命令。
+6. 执行命令，并按返回结果判断下一步。
+7. 回复时返回关键结果和后续可继续操作的信息，方便 agent 链式执行下一步。
 
 ### 4.2 不可违反规则
 
@@ -297,11 +309,12 @@ lark-cli auth login --domain base
 6. 只写可写字段；系统字段、附件字段、`formula`、`lookup` 默认不作为普通记录写入目标。
 7. 聚合分析与取数分流；统计走 `+data-query`，关键词检索走 `+record-search`，明细走 `+record-list / +record-get`。
 8. 筛选查询按视图能力执行；先用 `+view-set-filter` 配置筛选，再结合 `+record-list` 读取。
-9. Base 场景不要改走裸 API，不要切去 `lark-cli api /open-apis/bitable/v1/...`。
-10. 统一使用 `--base-token`。
-11. workflow 场景先读 schema，不要凭自然语言猜 `type`。
-12. dashboard 场景先读 guide；提到图表、看板、block 就先进入 dashboard 模块。
-13. formula / lookup 场景先读 guide；没读 guide 前不要直接创建或更新。
+9. 全局查询不得基于默认分页、小 `--limit` 或未证明全量的本地 `jq` 结果下结论。
+10. Base 场景不要改走裸 API，不要切去 `lark-cli api /open-apis/bitable/v1/...`。
+11. 统一使用 `--base-token`。
+12. workflow 场景先读 schema，不要凭自然语言猜 `type`。
+13. dashboard 场景先读 guide；提到图表、看板、block 就先进入 dashboard 模块。
+14. formula / lookup 场景先读 guide；没读 guide 前不要直接创建或更新。
 
 ### 4.3 并发、分页与批量限制
 

skills/lark-base/references/lark-base-data-analysis-sop.md

@@ -0,0 +1,88 @@
+# Base data analysis SOP
+
+Base 数据查询与分析任务的执行契约。覆盖记录读取、筛选、排序、Top/Bottom N、聚合统计、分组聚合、多表关联、临时分析和查询后写入前的目标定位。
+
+具体命令参数不要在本文猜；需要时跳到对应 reference：
+
+- `+data-query`: [lark-base-data-query.md](lark-base-data-query.md)
+- 视图筛选/排序/投影: [lark-base-view-set-filter.md](lark-base-view-set-filter.md), [lark-base-view-set-sort.md](lark-base-view-set-sort.md), [lark-base-view-set-visible-fields.md](lark-base-view-set-visible-fields.md)
+- 记录读取: [lark-base-record.md](lark-base-record.md)
+
+## 0. Hard Rules
+
+- 全局问题不能用默认 `+record-list --limit N` 片面地回答。
+- `jq` / shell / 本地代码是在个人电脑或当前运行环境中处理已返回数据，只适合小范围结果；超过 200 行默认不推荐本地统计、排序或求极值，应改用 Base 云端查询服务的 filter/sort/aggregate。
+- “最高、最低、最新、最早、Top、Bottom、总数、全部、异常、最大、最小、最多、最少、优先级最高”等全局语义，必须在 Base 云端查询服务中完成筛选、排序或聚合。
+- `+record-search` 用于关键词检索字段的展示文本；可搜多类字段，但匹配的是文本表示（如人员命中 name），不要用它替代金额、状态、日期、空值等结构化条件。
+- 不要依赖已有视图，除非用户明确指定该视图，或你已读取并验证其 filter/sort/projection 符合当前问题。
+- 交付输出必须使用用户可读的真实字段值；内部 ID、`record_id`、关联记录 ID、open_id、编码字段只可作为连接键或定位键，不能替代最终输出，除非用户明确要求输出这些键值。
+- 每次读取必须做最小投影，并包含后续解释、回查或写入需要的业务 key。
+
+## 1. Intent -> Tool Path
+
+| 用户意图 | 首选路径 | 关键规则 |
+| --- | --- | --- |
+| 看几条、预览、示例 | `+record-list --limit N` | 保持局部语义；不要推广为全局结论 |
+| 已知 `record_id` | `+record-get` | 直接读取；不要 search/list 反查 |
+| 明确关键词 | `+record-search` | 按字段展示文本命中；使用 `search_fields` 限定匹配范围、`select_fields` 投影降低返回内容 token 量；不要把文本检索当作结构化关联解析 |
+| 按条件找明细记录 | 先创建临时视图设置筛选和可见字段，再用 `+record-list --view-id` 读取 | 条件字段来自 `+field-list`；不要先读全表再本地过滤 |
+| 排序 / TopN 原始记录 | 临时视图 filter/sort/projection -> `+record-list --view-id --limit N` | 最高/最新降序，最低/最早升序 |
+| 聚合 / 分组 / 分组排序 | `+data-query` | 使用 filters/dimensions/measures/sort/limit |
+| 聚合后输出实体字段 | `+data-query` 得到业务 key -> record 路径回查明细 | `+data-query` 不返回原始记录或 link 明细；聚合结果中的 key 需要再解析成用户要求字段 |
+| 多表 / 多跳关联 | 以候选数最小的事实表为驱动表，沿业务 key 或 link `record_id` 逐跳回查 | 读出 link 单元格里的关联 `record_id` 后，到被关联表批量 `+record-get` 展示字段，并在回答用结果中合并展示 |
+| 查询后写入 / 视图化 | 先用本 SOP 得到可复核的目标记录 id 集合 | 再进入记录写入或视图配置；高价值可复用查询优先沉淀为持久视图 |
+
+## 2. Execution Patterns
+
+### 2.1 结构化明细与 TopN
+
+使用视图路径：
+
+1. `+field-list` 确认筛选字段、排序字段、展示字段、业务 key。
+2. `+view-create` 创建 grid 视图。
+3. 设置 filter/sort/visible fields。
+4. `+record-list --view-id <view_id> --limit <N>` 读取结果。
+
+不要从未筛选、未排序的全表输出中手动挑选。一次性查询可用临时视图；如果这个筛选/排序结果对用户后续查看有价值，应保留为持久视图，不要删除，并告知用户视图名称和用途。视图参数细节见 view-set references。
+
+### 2.2 聚合分析与 TopN
+
+使用 `+data-query`：
+
+- 让 Base 云端查询服务完成 filters、dimensions、measures、sort、pagination.limit。
+- `pagination.limit` 是 Base 云端查询服务中的聚合结果限制，不是本地分页扫描。
+- 需要输出明细或用户可读字段时，先拿业务 key，再用 record 路径精确回查。
+- 字段类型、日期 value、DSL shape 以 [lark-base-data-query.md](lark-base-data-query.md) 为准。
+
+### 2.3 关系查询与回查
+
+- link 单元格通常是关联表 `record_id` 数组，不是用户可读内容，只是连接键。
+- 先用 `+field-list` 确认 link 字段的 `link_table`、业务唯一键和展示字段。
+- 从驱动表拿到候选记录后，用关联 `record_id` 到关联表 `+record-get` 批量读取记录内容。
+- 多跳关系逐跳建立 `record_id/key -> 用户可读字段` 映射；最终用户可读的信息。
+
+禁止：
+
+- 把 link `record_id` 当最终输出。
+- 用 `+record-search` 搜 link `record_id`。
+- 基于 ID、自增编号、link 值做语义猜测；禁止依赖字段先验、样本记忆补全交付输出。
+
+## 3. Range & Pagination Contract
+
+- `+record-list` 默认页、固定 `--limit`、本地 `jq`、shell 管道、手工浏览输出，都只覆盖已读取范围；超过 200 行不要把本地处理当作推荐路径。
+- `has_more=true`、存在下一页 offset/page token、或返回行数等于 page size，都表示可能还有未读取数据。
+- 对全局问题，只有 Base 云端查询服务已经通过 filter/sort/aggregate 收敛目标范围，或 `data-query` 已在云端完成聚合、排序和限制时，才可以用有限返回形成结论。
+- 必须全量导出时，按 CLI 分页语义串行翻页；不要并发调用 `+record-list`。
+
+## 4. Final Answer Check
+
+形成交付输出前必须能确认：
+
+- 问题范围是局部样例、单点定位、全局明细、聚合分析、多表关联，还是查询后写入。
+- 筛选、排序、聚合是否发生在 Base 云端查询服务中，而不是本地 `jq` / shell 中。
+- 如果使用 `jq` / shell，本地输入是否是 200 行以内的小范围结果；超过 200 行是否已改用 Base 云端查询服务查询。
+- 如果使用 `+record-list`，是否处理了 `has_more`，且投影包含业务 key 和解释字段。
+- 如果涉及关系查询，是否按 `record_id` 或业务 key 精确回查，交付输出是否来自关联表真实字段。
+- 交付输出能追溯到表、字段、筛选条件、排序/聚合条件和连接键。
+
+任一项无法确认时，继续查询或明确说明只能得到局部结论。

skills/lark-base/references/lark-base-data-query.md

@@ -5,6 +5,8 @@
 
 对多维表格数据进行聚合查询（分组、过滤、排序、聚合计算），基于以下语法的 JSON DSL：
 
+查询类任务还必须先遵守 [`lark-base-data-analysis-sop.md`](lark-base-data-analysis-sop.md)。`+data-query` 适合让筛选、分组、聚合、排序和 TopN 在 Base 云端查询服务中执行；不要用默认分页的 `+record-list` 或本地 `jq` 替代聚合查询。
+
 ## 限制
 
 - **权限要求**（按文档类型分流）：
@@ -51,6 +53,23 @@ lark-cli base +data-query \
     "measures": [{"field_name": "金额", "aggregation": "sum", "alias": "total"}],
     "shaper": {"format": "flat"}
   }'
+
+# 聚合后如需读取明细，先让 data-query 返回可回查的业务 key
+lark-cli base +data-query \
+  --base-token MAGObxxxxx \
+  --dsl '{
+    "datasource": {"type": "table", "table": {"tableId": "tblxxxxxxxx"}},
+    "dimensions": [{"field_name": "业务编号", "alias": "biz_key"}],
+    "measures": [{"field_name": "指标值", "aggregation": "max", "alias": "max_value"}],
+    "filters": {
+      "type": 1,
+      "conjunction": "and",
+      "conditions": [{"field_name": "状态", "operator": "is", "value": ["有效"]}]
+    },
+    "sort": [{"field_name": "max_value", "order": "desc"}],
+    "pagination": {"limit": 10},
+    "shaper": {"format": "flat"}
+  }'
 ```
 
 ## 参数
@@ -397,6 +416,19 @@ value 使用预定义关键字机制，第一个元素为字符串常量名称
    - 每个 value 是 CellValue 对象，实际值在 `value` 字段中，如 `{"value": "北京"}` 或 `{"value": 12345.00}`
    - 失败时结果在 `data.error` 中，包含具体错误码和信息
 
+## 与记录读取组合
+
+`+data-query` 不返回原始记录或 link 字段明细。需要输出聚合结果对应的原始记录字段、展示值或关联表字段时，按以下方式组合：
+
+1. 用 `+data-query` 在 Base 云端查询服务中完成全局筛选、分组、聚合、排序和 TopN，得到业务 key、分组值或候选范围。
+2. 如果已经拿到候选记录的 `record_id`，用 `+record-get` 读取明细字段。
+3. 如果拿到的是结构化业务 key（例如编号、状态、日期、金额等），优先创建临时视图做精确过滤后再 `+record-list --view-id` 读取；不要用 `+record-search` 代替结构化条件。
+4. 只有候选条件本身是文本展示值关键词时，才使用 `+record-search`，并用 `search_fields` 限定范围、`select_fields` 做投影。
+5. 若候选记录包含 link 字段，提取关联 `record_id` 后到关联表用 `+record-get` 批量读取展示字段。
+6. 最终回答业务字段，不要把内部 `record_id` 当作用户可读答案。
+
+不要把 `data-query pagination.limit` 理解为分页扫描；它只限制 Base 云端查询服务返回的聚合结果行数，不支持 offset。需要全量明细导出时回到 data analysis SOP 的 record 分页规则。
+
 ## 坑点
 
 - ⚠️ **必须先查表结构**：DSL 的 `field_name` 必须与表中字段名称精确匹配（区分大小写），不能凭猜测构造。先用 `lark-cli base +field-list --base-token <base_token> --table-id <table_id>` 获取真实字段名
@@ -408,10 +440,12 @@ value 使用预定义关键字机制，第一个元素为字符串常量名称
 - ⚠️ **数据表标识 `tableId` vs `tableName`**：datasource 中可以用 `tableId`（如 `tblXXX`）或 `tableName`（数据表的用户自定义显示名称），二选一，不要混用
 - ⚠️ **`pagination.limit` 最大 5000**：超过会报错，且不支持 offset，只支持 limit
 - ⚠️ **所有 alias 必须全局唯一**：dimensions 和 measures 之间的 alias 也不能重名
+- ⚠️ **不要用本地分页结果替代 data-query**：凡是全局计数、分组、聚合、排序 TopN，优先让 `+data-query` 在 Base 云端查询服务中执行；默认页 `+record-list` 后本地统计只能得到已读取范围内的结果
 
 ## 参考
 
 - [lark-base](../SKILL.md) — 多维表格全部命令
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
+- [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md) — 查询范围、选路、下推、分页、record 明细回查和关系查询 SOP
 - [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范
 - [lark-base-shortcut-field-properties.md](lark-base-shortcut-field-properties.md) — shortcut 字段类型与 JSON 结构

skills/lark-base/references/lark-base-record-read-sop.md

@@ -1,86 +0,0 @@
-# base record read SOP
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和全局参数。
-
-记录读取由 6 个功能组合完成：选路、字段投影、视图预处理、分页与范围、返回结构解释、link 关联读取。
-
-## 1. 读取选路
-
-| 场景 | 使用方式 | 规则 |
-|------|------|------|
-| 已知 `record_id` | `+record-get` | 只读单条记录，不要用 search/list 反查。 |
-| 明确关键词检索 | `+record-search` | 只用于文本关键词检索；金额、状态、日期等结构化条件不要用 search。 |
-| 普通明细读取 / 导出 / 查看前 N 条 | `+record-list` | 优先加 `--view-id` 时只读该视图可见记录与可见字段；或者加 `--field-id` 手动裁剪字段；不传 `--view-id` 时会读取全表。 |
-| 明确筛选 / 排序 / Top N / Bottom N 且需要原始记录或 `record_id` | 创建带 filter + sort 的临时视图 + `+record-list --view-id` | 让视图完成 filter/sort projection，LLM 不擅长手工筛选排序，建议用视图完成。 |
-| 统计 / 聚合结果且不需要 `record_id` | 转到 [`lark-base-data-query.md`](lark-base-data-query.md) | `data-query` 是特殊分析 DSL，不是记录读取工具。 |
-
-## 2. 字段投影
-
-- `FieldListFirst`: 不清楚字段结构时先 `+field-list`，确认筛选字段、排序字段、展示字段、关联字段、业务唯一键字段。
-- `UseRealField`: 字段名和字段 ID 必须来自 `+field-list` 返回，不要凭自然语言猜字段名。
-- `MinimalProjection`: 每次读取只返回本次任务需要的字段；`+record-list` 用重复 `--field-id`，视图读取用 `+view-set-visible-fields`。
-- `FieldScopePriority`: 返回字段优先级为显式投影字段（`+record-list --field-id` / `record-search select_fields`） > 视图可见字段 > 全表字段；需要稳定列范围时必须显式投影。
-- `LongFieldAvoidance`: 默认不要读取 `trace`、`raw`、长文本、附件等高噪声字段，除非任务明确需要。
-- `BusinessKey`: 后续要定位、更新或解释记录时，投影中必须包含可识别业务字段，例如订单号、日报ID、姓名、编号。
-
-## 3. 视图预处理
-
-适用于结构化筛选、排序、最高/最低、倒数、Top/Bottom N、按条件找记录等场景。
-
-1. `+field-list` 获取字段 ID、字段名和字段类型。
-2. `+view-create` 创建临时 `grid` 视图，名称带任务语义，例如 `tmp_query_销售额升序`。
-3. `+view-set-filter` 设置筛选条件；空值是否参与必须按用户语义判断。
-4. `+view-set-sort` 设置排序条件；最高/最新用降序，最低/最早/倒数用升序。
-5. `+view-set-visible-fields` 设置投影字段，只保留业务键、排序字段、筛选解释字段、需要展示或二跳的字段。
-6. `+record-list --view-id <view_id> --limit <N>` 读取结果；不要再从未排序全表输出中手动挑选。
-
-## 4. 分页与范围
-
-- `ViewScope`: URL 带 `view_id` 时先判断用户是否要求“该视图下”；全表问题不要误用 URL 视图范围，应该根据需求创建合适的临时视图完成查询任务。
-- `ViewIdScope`: `+record-list --view-id` 是作用域参数；仅用于用户指定的视图，或本次任务主动创建的临时筛选 / 排序 / 投影视图。
-- `NeedAllPages`: 用户要求全部、导出、统计、最高/最低且未用视图/limit 限定时，必须检查 `has_more` 并串行翻页。
-- `LimitWhenScoped`: 用户只要示例、前 N 条、Top/Bottom N，使用 `--limit` 控制结果规模。
-- `NoConcurrentList`: `+record-list` 禁止并发调用；分页和多表读取必须串行。
-- `DataQueryScope`: `data-query` 的筛选 DSL 与视图筛选不是同一套语法；不要混用。
-
-## 5. 返回结构解释
-
-- `ColumnMapping`: `fields` / `field_id_list` 定义 `data` 每列含义；解释记录前先建立列到字段名的映射。
-- `RowMapping`: `record_id_list[i]` 与 `data[i]` 是同一行；需要后续定位、更新或关联时，按下标整理成 `record_id + 字段名:值` 的小表。
-- `BusinessMatch`: 后续引用目标记录时按业务字段匹配，不靠肉眼数行号。
-- `FieldType`: 按字段类型解释值；数字、货币、日期、人员、formula、lookup、attachment、link 不要当普通文本处理。
-- `EmptyValue`: 空值参与筛选或排序前必须明确语义；不要默认把空值当 `0`、空字符串或有效状态。
-- `AnswerCheck`: 最终回答前复核答案记录来自读取结果、筛选排序已应用、字段含义和 record_id 映射无误。
-
-## 6. link 关联字段读取
-
-link 字段是关联单元格；读取结果通常是关联表的 `record_id` 数组，不是用户可读名称。
-
-| 步骤 | 做法 |
-|------|------|
-| 识别 link 字段 | 用 `+field-list` 查看字段类型为 `link`，并读取 `link_table` 确认关联目标表。 |
-| 读取当前表 | 在当前表 `+record-list` / `+record-get` 中保留 link 字段和业务键字段。 |
-| 解析单元格值 | link 单元格通常形如 `[{"id":"rec..."}]`；提取其中每个 `id` 作为关联表 `record_id`。 |
-| 读取关联表 | 到 `link_table` 使用 `+record-get --record-id <rec...>` 或裁剪后的 `+record-list` 读取显示字段。 |
-| 建立映射 | 形成 `关联record_id -> 显示字段值` 映射，再回填当前表结果。 |
-| 多值处理 | 多个关联值保持原顺序；可去重批量读取，但回答时按原单元格顺序输出。 |
-
-禁止事项：
-
-- 不要把 link 单元格里的 `record_id` 当作最终答案。
-- 不要用 `+record-search` 搜索 link `record_id` 来查关联记录。
-- 不要凭关联 `record_id` 猜名称、负责人、门店等显示值。
-- 不要只看当前表字段名推断关联表结构；跨表读取前必须拿关联表字段结构。
-
-## 7. 命令 help
-
-- `HelpFirst`: 参数、示例、JSON shape 和取值约束以 `lark-cli base +record-get --help`、`+record-search --help`、`+record-list --help` 为准。
-- `RecordSearchJson`: 构造 `+record-search --json` 前先看 `+record-search --help`，确认 `keyword/search_fields/select_fields/view_id/offset/limit` 的结构和约束。
-- `RecordListProjection`: 构造 `+record-list` 前先看 `+record-list --help`，确认 `--field-id`、`--view-id`、`--offset`、`--limit` 的语义。
-
-## 参考
-
-- [lark-base-view-set-filter.md](lark-base-view-set-filter.md)
-- [lark-base-view-set-sort.md](lark-base-view-set-sort.md)
-- [lark-base-view-set-visible-fields.md](lark-base-view-set-visible-fields.md)
-- [lark-base-data-query.md](lark-base-data-query.md)

skills/lark-base/references/lark-base-record.md

@@ -8,7 +8,7 @@ record 相关命令索引。
 
 | 文档 | 命令 | 说明 |
 |------|------|------|
-| [lark-base-record-read-sop.md](lark-base-record-read-sop.md) | `+record-get` / `+record-search` / `+record-list` | 记录读取统一选路、筛选排序投影 SOP |
+| [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md) | `+record-get` / `+record-search` / `+record-list` / `+data-query` / 视图筛选排序 | 数据查询与分析统一选路、筛选排序投影、聚合后回查明细 SOP |
 | [lark-base-record-upsert.md](lark-base-record-upsert.md) | `+record-upsert` | 创建或更新记录 |
 | [lark-base-record-batch-create.md](lark-base-record-batch-create.md) | `+record-batch-create` | 按 `fields/rows` 批量创建记录 |
 | [lark-base-record-batch-update.md](lark-base-record-batch-update.md) | `+record-batch-update` | 批量更新记录 |
@@ -19,7 +19,7 @@ record 相关命令索引。
 
 ## 说明
 
-- 读取记录前优先阅读 [lark-base-record-read-sop.md](lark-base-record-read-sop.md)，它合并了 `+record-get` / `+record-search` / `+record-list` 的选路和 SOP。
+- 读取记录前优先阅读 [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md)，它合并了 `record / view / data-query` 的选路、分页、投影、聚合后回查明细和 link 关联读取。
 - 聚合页只保留目录职责；写入、删除、历史等命令的详细说明请进入对应单命令文档。
 - 所有 `+xxx-list` 调用都必须串行执行；若要批量跑多个 list 请求，只能串行执行。
 - `+record-list` 支持重复传参 `--field-id` 做字段筛选。

skills/lark-doc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-doc
 version: 2.0.0
-description: "飞书云文档（v2）：创建和编辑飞书文档。使用本 skill 时，docs +create、docs +fetch、docs +update 必须携带 --api-version v2；默认使用 DocxXML 格式（也支持 Markdown）。创建文档、获取文档内容（支持 simple/with-ids/full 三种导出详细度，以及 full/outline/range/keyword/section 五种局部读取模式，可按目录、block id 区间、关键词或标题自动成节只拉部分内容以节省上下文）、更新文档（八种指令：str_replace/block_insert_after/block_copy_insert_after/block_replace/block_delete/block_move_after/overwrite/append）、上传和下载文档中的图片和文件、搜索云空间文档。当用户需要创建或编辑飞书文档、读取文档内容、在文档中插入图片、搜索云空间文档时使用；如果用户是想按名称或关键词先定位电子表格、报表等云空间对象，也优先使用本 skill 的 docs +search 做资源发现。"
+description: "飞书云文档 / Docx / 知识库 Wiki 文档（v2）：创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token，或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、画板、引用或同步块时，也先用本 skill 读取和提取 token，再切到对应 skill 下钻。使用本 skill 时，docs +create、docs +fetch、docs +update 必须携带 --api-version v2；默认使用 DocxXML，也支持 Markdown。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -10,7 +10,7 @@ metadata:
 
 # docs (v2)
 
-> **⚠️ API 版本：本 skill 使用 v2 API。所有 `docs +create`、`docs +fetch`、`docs +update` 命令必须携带 `--api-version v2`。**
+> **⚠️ API 版本：本 skill 使用 v2 API。所有 `docs +create --api-version v2`、`docs +fetch --api-version v2`、`docs +update --api-version v2` 命令必须携带 `--api-version v2`。**
 
 ```bash
 # 常用示例
@@ -23,7 +23,7 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
 
 **CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
 1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
-2. **读取文档（`docs +fetch`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
+2. **读取文档（`docs +fetch --api-version v2`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
 3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
 
 **未读完以上文件就执行相应操作会导致参数选择错误、格式错误或样式不达标。**
@@ -49,7 +49,7 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
 | `<bitable token="..." table-id="...">` | `token` -> app_token, `table-id` | [`lark-base`](../lark-base/SKILL.md) |
 | `<cite type="doc" file-type="sheets" token="..." sheet-id="...">` | 同 `<sheet>` | [`lark-sheets`](../lark-sheets/SKILL.md) |
 | `<cite type="doc" file-type="bitable" token="..." table-id="...">` | 同 `<bitable>` | [`lark-base`](../lark-base/SKILL.md) |
-| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch` 读取 src-token 文档，定位 block |
+| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch --api-version v2` 读取 src-token 文档，定位 block |
 
 **补充：** 云空间资源发现统一走 [`drive +search`](../lark-drive/references/lark-drive-search.md)；当用户口头说"表格/报表/最近我编辑过的 xxx"时，也优先从 `drive +search` 开始。老的 `docs +search` 只在沿用 `--filter` JSON 的存量脚本里保留，后续会下线。
 

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

@@ -130,7 +130,7 @@ lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
 
 ## 嵌入电子表格 / 多维表格
 
-返回中可能含 `<sheet>`、`<bitable>`、`<cite file-type="sheets|bitable">`。内部数据无法通过 `docs +fetch` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。
+返回中可能含 `<sheet>`、`<bitable>`、`<cite file-type="sheets|bitable">`。内部数据无法通过 `docs +fetch --api-version v2` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。
 
 ## 参考
 

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

@@ -1,6 +1,6 @@
 # Markdown 格式参考
 
-`docs +fetch / +create / +update` 使用 `--doc-format markdown` 时适用。
+`docs +fetch --api-version v2` / `docs +create --api-version v2` / `docs +update --api-version v2` 使用 `--doc-format markdown` 时适用。
 
 ## 转义规则
 
@@ -34,14 +34,14 @@
 - `$...$` 数学公式内部，符号为 LaTeX 语法，不受 Markdown 转义影响
 
 **导出已转义，不要反转义：**
-`docs +fetch --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\[`、`\|`、`\\` 等）。这些 `\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\`。**
+`docs +fetch --api-version v2 --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\[`、`\|`、`\\` 等）。这些 `\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\`。**
 
 **写入时必须转义：**
 使用 `docs +create` 或 `docs +update` 的 `--doc-format markdown` 写入内容时，字面文本中的特殊字符同样必须转义。`--pattern` 参数中也必须使用转义形式才能正确匹配。
 
 **导出 → 更新 工作流示例：**
 
-1. `docs +fetch` 导出得到 `C:\\Users\\test\[1\]`
+1. `docs +fetch --api-version v2` 导出得到 `C:\\Users\\test\[1\]`
 2. 用 `str_replace --pattern 'C:\\Users\\test\[1\]'` 匹配（直接使用导出的转义形式）
 3. `--content` 中的替换内容也要保持转义：`C:\\Users\\prod\[2\]`
 

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

@@ -15,7 +15,7 @@
 > - **局部精修**（`str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after`）：优先使用 XML（默认）。XML 能稳定表达 block 结构和样式，精准编辑更可控；不要因为 Markdown 写起来更简单就自行切换。
 > - **整段写入**（`append` / `overwrite`）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件或明确要求 Markdown 时直接用 Markdown；否则默认 XML。
 >
-> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。
+> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --api-version v2 --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。
 
 ## 参数
 
@@ -221,7 +221,7 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
 
 ## 画板处理
 
-> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch` 取到 `<whiteboard token="...">`，再切到 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 用 `whiteboard +update` 写入。
+> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch --api-version v2` 取到 `<whiteboard token="...">`，再切到 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 用 `whiteboard +update` 写入。
 
 画板的语法选型与插入示例见 [`lark-doc-style.md`](style/lark-doc-style.md) 的「画板语法与插入」章节。
 

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

@@ -16,7 +16,7 @@
 | 场景 | 入口 |
 |------|------|
 | 文档中需要插入新画板 | 继续步骤 2 |
-| 已有画板需要更新内容 | 先 `docs +fetch` 获取 `board_token`，跳至步骤 3 |
+| 已有画板需要更新内容 | 先 `docs +fetch --api-version v2` 获取 `board_token`，跳至步骤 3 |
 | 只查看 / 下载已有画板 | 切换至 `lark-whiteboard`，不走本流程 |
 
 ### 步骤 2：在文档中创建空白画板

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

@@ -33,7 +33,7 @@
 
 ### 第三波 — 整合审查 + 画板意图识别（串行）
 
-5. `docs +fetch --detail with-ids` 获取文档，审查整体效果
+5. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
 6. 评估样式达标（富 block 密度、元素多样性、连续 `<p>` 数量）
 7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。记录需要插图的章节及推荐的画板类型
 

skills/lark-drive/SKILL.md

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

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

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

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

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

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

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

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

@@ -23,12 +23,16 @@ lark-cli drive +upload --file ./report.pdf
 # 自定义上传后的文件名
 lark-cli drive +upload --file ./report.pdf --name "季度总结.pdf"
 
+# 覆盖已存在文件（原地覆盖，保留 file_token）
+lark-cli drive +upload --file ./report.pdf --file-token boxcn_existing_file
+
 # 原生命令（高级/分片上传）：预上传 + 完成上传
 lark-cli drive files upload_prepare --data '{
   "file_name": "report.pdf",
   "parent_type": "explorer",
   "parent_node": "fldbc_xxx",
-  "size": 1048576
+  "size": 1048576,
+  "file_token": "boxcn_existing_file"
 }'
 lark-cli drive files upload_finish --data '{
   "upload_id": "<UPLOAD_ID>",
@@ -40,7 +44,9 @@ lark-cli schema drive.files.upload_prepare
 ```
 
 > [!IMPORTANT]
-> 如果文件是**以应用身份（bot）上传**的，如 `lark-cli drive +upload --as bot` 在上传成功后，CLI 会**尝试为当前 CLI 用户自动授予该文件的 `full_access`（可管理权限）**。
+> 如果文件是**以应用身份（bot）新建上传**的，如 `lark-cli drive +upload --as bot` 在上传成功后，CLI 会**尝试为当前 CLI 用户自动授予该文件的 `full_access`（可管理权限）**。
+>
+> 如果这次调用传了 `--file-token`，表示是在**覆盖已有文件**，CLI **不会**额外修改该文件权限。
 >
 > 以应用身份上传时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
 > - `status = granted`：当前 CLI 用户已获得该文件的可管理权限
@@ -51,12 +57,18 @@ lark-cli schema drive.files.upload_prepare
 >
 > **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
 
+> [!TIP]
+> 当底层上传接口返回版本号时，shortcut 会在结果里额外透出 `version`。
+
 ## 目标位置选择（关键）
 
 - 上传到 Drive 文件夹：传 `--folder-token <folder_token>`，shortcut 会发送 `parent_type=explorer`
 - 上传到 wiki 节点：传 `--wiki-token <wiki_token>`，shortcut 会发送 `parent_type=wiki`
 - 上传到 Drive 根目录：`--folder-token` 和 `--wiki-token` 都不传
+- 覆盖已有文件：额外传 `--file-token <existing_file_token>`；shortcut 会把它原样透传到底层 `upload_all` / `upload_prepare`，让后端按覆盖语义写入
+- bot 模式下，`--file-token` 覆盖只改文件内容；不会额外给当前 CLI 用户补 `full_access`
 - 不要传空目标值：`--folder-token ""` / `--wiki-token ""` 会被视为参数错误；如需上传到 Drive 根目录，应直接省略这两个参数
+- 不要传空 `--file-token`：如需新建上传，直接省略该参数；显式传空字符串会报错
 - `--folder-token` 和 `--wiki-token` 互斥，不要同时传
 - `--wiki-token` 传的是 **wiki node token**，不是 `space_id`
 
@@ -65,6 +77,7 @@ Shortcut 参数：
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--file` | 是 | 本地文件路径 |
+| `--file-token` | 否 | 已存在文件的 token；传入后按“覆盖已有文件”语义上传 |
 | `--folder-token` | 否 | 目标文件夹 token；与 `--wiki-token` 互斥；省略时默认为 Drive 根目录；显式传空字符串会报错 |
 | `--wiki-token` | 否 | 目标 wiki 节点 token；与 `--folder-token` 互斥；会映射为 `parent_type=wiki`、`parent_node=<wiki_token>`；显式传空字符串会报错 |
 | `--name` | 否 | 上传后的文件名；默认使用本地文件名 |
@@ -77,6 +90,7 @@ Shortcut 参数：
 | `parent_type` | 是 | 父节点类型；上传到文件夹 / 根目录时用 `"explorer"`，上传到 wiki 节点时用 `"wiki"` |
 | `parent_node` | 是 | 父节点 token；`explorer` 时传文件夹 token（根目录可为空字符串），`wiki` 时传 wiki node token |
 | `size` | 是 | 文件大小（字节） |
+| `file_token` | 否 | 已存在文件 token；传入后覆盖该文件内容 |
 
 > [!CAUTION]
 > 这是**写入操作** —— 执行前必须确认用户意图。

skills/lark-im/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-im
 version: 1.0.0
-description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、管理标记数据时使用。"
+description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据时使用。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -68,9 +68,10 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 
 | Shortcut | 说明 |
 |----------|------|
-| [`+chat-create`](references/lark-im-chat-create.md) | Create a group chat; user/bot; creates private/public chats, invites users/bots, optionally sets bot manager |
+| [`+chat-create`](references/lark-im-chat-create.md) | Create a group chat or topic chat; user/bot; --chat-mode group|topic; private/public; invites users/bots; optionally sets bot manager |
+| [`+chat-list`](references/lark-im-chat-list.md) | List groups the current user/bot is a member of; user/bot; supports sorting, pagination, and --exclude-muted (user identity only) |
 | [`+chat-messages-list`](references/lark-im-chat-messages-list.md) | List messages in a chat or P2P conversation; user/bot; accepts --chat-id or --user-id, resolves P2P chat_id, supports time range/sort/pagination |
-| [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by `--query` keyword and/or `--member-ids`; user/bot; e.g. look up chat_id by group name; supports type filters, sorting, and pagination |
+| [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by --query keyword and/or --member-ids; user/bot; e.g. look up chat_id by group name; supports type filters, sorting, pagination, and --exclude-muted (user identity only) |
 | [`+chat-update`](references/lark-im-chat-update.md) | Update group chat name or description; user/bot; updates a chat's name or description |
 | [`+messages-mget`](references/lark-im-messages-mget.md) | Batch get messages by IDs; user/bot; fetches up to 50 om_ message IDs, formats sender names, expands thread replies |
 | [`+messages-reply`](references/lark-im-messages-reply.md) | Reply to a message (supports thread replies); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key |
@@ -96,7 +97,6 @@ lark-cli im <resource> <method> [flags] # 调用 API
   - `create` — 创建群。Identity: `bot` only (`tenant_access_token`).
   - `get` — 获取群信息。Identity: supports `user` and `bot`; the caller must be in the target chat to get full details, and must belong to the same tenant for internal chats.
   - `link` — 获取群分享链接。Identity: supports `user` and `bot`; the caller must be in the target chat, must be an owner or admin when chat sharing is restricted to owners/admins, and must belong to the same tenant for internal chats.
-  - `list` — 获取用户或机器人所在的群列表。Identity: supports `user` and `bot`.
   - `update` — 更新群信息。Identity: supports `user` and `bot`.
 
 ### chat.members
@@ -141,7 +141,6 @@ lark-cli im <resource> <method> [flags] # 调用 API
 | `chats.create` | `im:chat:create` |
 | `chats.get` | `im:chat:read` |
 | `chats.link` | `im:chat:read` |
-| `chats.list` | `im:chat:read` |
 | `chats.update` | `im:chat:update` |
 | `chat.members.bots` | `im:chat.members:read` |
 | `chat.members.create` | `im:chat.members:write_only` |

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

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

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

@@ -0,0 +1,113 @@
+# im +chat-list
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+List groups the current user (or bot, with `--as bot`) is a member of. Useful for enumerating "my chats" without a search keyword, or for bulk operations against the caller's chats. Supports pagination, sort order, and (user identity only) muted-chat filtering.
+
+This skill maps to the shortcut: `lark-cli im +chat-list` (internally calls `GET /open-apis/im/v1/chats`).
+
+## Commands
+
+```bash
+# List the user's chats (default sort: ByCreateTimeAsc)
+lark-cli im +chat-list
+
+# Sort by recent activity (most recently active first)
+lark-cli im +chat-list --sort-type ByActiveTimeDesc
+
+# Limit page size
+lark-cli im +chat-list --page-size 50
+
+# Pagination
+lark-cli im +chat-list --page-token "xxx"
+
+# Drop muted chats (user identity only)
+lark-cli im +chat-list --exclude-muted
+
+# JSON output
+lark-cli im +chat-list --format json
+
+# Preview the request without executing it
+lark-cli im +chat-list --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--user-id-type <type>` | No | `open_id` (default), `union_id`, `user_id` | ID type used for `owner_id` in the response |
+| `--sort-type <type>` | No | `ByCreateTimeAsc` (default), `ByActiveTimeDesc` | Result ordering |
+| `--page-size <n>` | No | 1-100, default 20 | Number of results per page |
+| `--page-token <token>` | No | - | Pagination token from the previous response |
+| `--exclude-muted` | No | User identity only | Drop chats the current user has muted (do-not-disturb). Under `--as bot`, the flag is silently inactive; see "Filtering muted chats" below |
+| `--format json` | No | - | Output as JSON |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+> **Note:** Supports both `--as user` (default) and `--as bot`. When using bot identity, the app must have bot capability enabled.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | Chat ID (`oc_xxx` format) |
+| `name` | Chat name |
+| `description` | Chat description |
+| `owner_id` | Owner ID (type controlled by `--user-id-type`) |
+| `external` | Whether the chat is external |
+| `chat_status` | Chat status (`normal` / `dissolved` / `dissolved_save`) |
+
+## Filtering muted chats
+
+`--exclude-muted` (user identity only) drops chats the current user has set to do-not-disturb. After the list call, the CLI batches the page's chat_ids through `POST /open-apis/im/v1/chat_user_setting/batch_get_mute_status` and filters client-side. Under `--as bot`, the mute API is UAT-only and the filter is silently skipped.
+
+When the flag is set, the JSON envelope gains a `filter` sub-object (absent otherwise, so existing consumers are unaffected); `fetched_count == returned_count + filtered_count` always holds:
+
+```json
+{
+  "chats": [...],
+  "filter": {
+    "applied": "exclude_muted",
+    "fetched_count": 20,
+    "returned_count": 17,
+    "filtered_count": 3,
+    "hint": "Filtered out 3 muted chat(s) on this page (17 remaining); use --page-token to fetch more."
+  }
+}
+```
+
+## Usage Scenarios
+
+### Scenario 1: List my recent chats
+
+```bash
+lark-cli im +chat-list --sort-type ByActiveTimeDesc --page-size 10
+```
+
+### Scenario 2: List my non-muted chats sorted by activity
+
+```bash
+lark-cli im +chat-list --sort-type ByActiveTimeDesc --exclude-muted
+```
+
+### Scenario 3: Iterate all my chats programmatically
+
+```bash
+TOKEN=""
+while :; do
+  RESP=$(lark-cli im +chat-list --page-size 100 --page-token "$TOKEN" --format json)
+  echo "$RESP" | jq -r '.data.chats[].chat_id'
+  HAS_MORE=$(echo "$RESP" | jq -r '.data.has_more')
+  [ "$HAS_MORE" = "true" ] || break
+  TOKEN=$(echo "$RESP" | jq -r '.data.page_token')
+done
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `--page-size must be an integer between 1 and 100` | page-size is out of range or not an integer | Use an integer between 1 and 100 |
+| Permission denied (99991672) | The bot app does not have `im:chat:read` TAT permission enabled | Enable the permission for the app in the Open Platform console |
+| Permission denied (99991679) with `--as user` | UAT is not authorized for `im:chat:read` | Run `lark-cli auth login --scope "im:chat:read"` |
+| `Bot ability is not activated` (232025) | The app does not have bot capability enabled | Enable bot capability in the Open Platform console |
+| `--exclude-muted` returns all chats unfiltered and `hint` says "no effect under bot identity" | Running under `--as bot` (mute API is UAT-only) | Switch to `--as user` for mute filtering |

skills/lark-im/references/lark-im-chat-messages-list.md

@@ -129,7 +129,7 @@ lark-cli api GET /open-apis/im/v1/messages \
    lark-cli im +chat-search --query "<chat name keyword>" --format json
    lark-cli im +chat-messages-list --chat-id <chat_id>
    ```
-   **Do not use `im chats search` or `im chats list` — always use the `+chat-search` shortcut.**
+   **Do not use `im chats search` or `+chat-list` — always use the `+chat-search` shortcut.**
 2. **Prefer `--chat-id` when available:** if the chat_id is already known, use it directly to avoid extra API calls.
 3. **For direct messages:** use `--user-id` to resolve the p2p chat automatically instead of looking it up manually. This requires user identity (`--as user`); with bot identity, resolve the p2p `chat_id` yourself and pass it via `--chat-id`.
 4. **For time ranges:** both ISO 8601 and date-only inputs are supported. Date-only is usually simpler.

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

@@ -49,6 +49,7 @@ lark-cli im +chat-search --query "project" --dry-run
 | `--sort-by <field>` | No | `create_time_desc`, `update_time_desc`, `member_count_desc` | Sort field in descending order |
 | `--page-size <n>` | No | 1-100, default 20 | Number of results per page |
 | `--page-token <token>` | No | - | Pagination token from the previous response |
+| `--exclude-muted` | No | User identity only | Drop chats the current user has muted (do-not-disturb). Under `--as bot`, the flag is silently inactive (mute is a per-user setting); see "Filtering muted chats" below |
 | `--format json` | No | - | Output as JSON |
 | `--dry-run` | No | - | Preview the request without executing it |
 
@@ -65,6 +66,27 @@ lark-cli im +chat-search --query "project" --dry-run
 | `external` | Whether the chat is external |
 | `chat_status` | Chat status (`normal` / `dissolved` / `dissolved_save`) |
 
+## Filtering muted chats
+
+`--exclude-muted` (user identity only) drops chats the current user has set to do-not-disturb. After the search call, the CLI batches the page's chat_ids through `POST /open-apis/im/v1/chat_user_setting/batch_get_mute_status` and filters client-side. Under `--as bot`, the mute API is UAT-only and the filter is silently skipped.
+
+When the flag is set, the JSON envelope gains a `filter` sub-object (absent otherwise, so existing consumers are unaffected); `fetched_count == returned_count + filtered_count` always holds:
+
+```json
+{
+  "chats": [...],
+  "filter": {
+    "applied": "exclude_muted",
+    "fetched_count": 20,
+    "returned_count": 19,
+    "filtered_count": 1,
+    "hint": "Filtered out 1 muted chat(s) on this page (19 remaining, including 2 non-member public group(s)); use --page-token to fetch more."
+  }
+}
+```
+
+Note: only confirmed-muted chats count toward `filtered_count`; non-member public groups are retained and surfaced in `hint`. For strict member-only results, combine with `--search-types "private,public_joined,external"`.
+
 ## Usage Scenarios
 
 ### Scenario 1: Search chats that contain a keyword
@@ -106,7 +128,7 @@ When the user asks to search chats, follow these rules:
 2. **Search scope is limited:** only chats visible to the current user or bot can be found (joined chats plus public chats). This is not a global search over all chats.
 3. **Control result volume:** the result set may be large. Use `--page-size` deliberately.
 4. **Suggest follow-up actions:** after finding a chat, common next steps include listing recent messages (`im +chat-messages-list`) or sending a message (`im +messages-send`).
-5. **NEVER fall back to chats list:** If `+chat-search` returns empty results, do NOT attempt to use `im chats list` or `GET /open-apis/im/v1/chats` as a fallback. The list API is not a search API — it returns all chats without keyword filtering and will not help locate the target chat. Instead, ask the user to refine the keyword or check whether the chat is visible to the current identity.
+5. **NEVER fall back to chats list:** If `+chat-search` returns empty results, do NOT attempt to use `+chat-list` or `GET /open-apis/im/v1/chats` as a fallback. The list API is not a search API — it returns all chats without keyword filtering and will not help locate the target chat. Instead, ask the user to refine the keyword or check whether the chat is visible to the current identity.
 
 ## References
 

skills/lark-im/references/lark-im-messages-search.md

@@ -168,7 +168,7 @@ lark-cli im +chat-search --query "<chat name keyword>" --format json
 lark-cli im +messages-search --query "keyword" --chat-id <chat_id>
 ```
 
-**Do not use `im chats search` or `im chats list` — always use the `+chat-search` shortcut.**
+**Do not use `im chats search` or `+chat-list` — always use the `+chat-search` shortcut.**
 
 ## Work Summary / Report Generation
 

skills/lark-shared/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-shared
 version: 1.0.0
-description: "飞书/Lark CLI 共享基础：应用配置初始化、认证登录（auth login）、身份切换（--as user/bot）、权限与 scope 管理、Permission denied 错误处理、安全规则。当用户需要第一次配置(`lark-cli config init`)、使用登录授权(`lark-cli auth login`)、遇到权限不足、切换 user/bot 身份、配置 scope、或首次使用 lark-cli 时触发。"
+description: "Use when first setting up lark-cli, running auth login, switching user/bot identity (--as), handling permission denied or scope errors, needing to update lark-cli, or seeing _notice in JSON output."
 ---
 
 # lark-cli 共享规则
@@ -12,7 +12,9 @@ description: "飞书/Lark CLI 共享基础：应用配置初始化、认证登
 
 首次使用需运行 `lark-cli config init` 完成应用配置。
 
-当你帮用户初始化配置时，使用background方式使用下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户：
+当你帮用户初始化配置时，使用background方式使用下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户。
+
+**URL 转发规则**：当命令输出 `verification_url`、`verification_uri_complete`、`console_url` 等 URL 字段时，必须将 URL exactly as returned by the CLI 转发给用户，并把它视为不可修改的 opaque string；不要做 URL encode/decode，不要补 `%20`、空格或标点，不要重新拼接 query，不要改写成 Markdown link text，建议用只包含原始 URL 的代码块单独输出。
 
 ```bash
 # 发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）
@@ -51,7 +53,7 @@ lark-cli config init --new
 
 #### Bot 身份（`--as bot`）
 
-将错误中的 `console_url` 提供给用户，引导去后台开通 scope。**禁止**对 bot 执行 `auth login`。
+将错误中的 `console_url` 原样提供给用户，引导去后台开通 scope。**禁止**对 bot 执行 `auth login`。
 
 #### User 身份（`--as user`）
 
@@ -64,7 +66,7 @@ lark-cli auth login --scope "<missing_scope>"   # 按具体 scope 授权（推
 
 #### Agent 代理发起认证（推荐）
 
-当你作为 AI agent 需要帮用户完成认证时，使用background方式 执行以下命令发起授权流程, 并将授权链接发给用户：
+当你作为 AI agent 需要帮用户完成认证时，使用background方式 执行以下命令发起授权流程, 并将授权链接原样发给用户：
 
 ```bash
 # 发起授权（阻塞直到用户授权完成或过期）
@@ -80,11 +82,13 @@ lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_
 **当你在输出中看到 `_notice.update` 时，完成用户当前请求后，主动提议帮用户更新**：
 
 1. 告知用户当前版本和最新版本号
-2. 提议执行更新（CLI 和 Skills 需要同时更新）：
+2. 提议执行更新（同时更新 CLI 和 Skills）：
    ```bash
-   npm update -g @larksuite/cli && npx skills add larksuite/cli -g -y
+   lark-cli update
    ```
-3. 更新完成后提醒用户：**退出并重新打开 AI Agent**以加载最新 Skills
+3. 更新完成后提醒用户：**退出并重新打开 AI Agent** 以加载最新 Skills
+
+**重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
 
 **规则**：不要静默忽略更新提示。即使当前任务与更新无关，也应在完成用户请求后补充告知。
 

skills/lark-vc-agent/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: lark-vc-agent
+version: 1.0.0
+description: "飞书视频会议：让机器人代当前用户加入/离开正在进行的会议，并读取会议期间的实时事件（参会人加入与离开、发言、聊天、屏幕共享等）。1. 用户提供 9 位会议号、要求代为入会或离会时使用 +meeting-join / +meeting-leave——会真实产生入会/离会记录。2. 会议进行中用户想知道“谁加入了”“谁离开了”“谁在发言”“有人共享屏幕吗”等会中动态时，机器人入会后用 +meeting-events 读取事件时间线。3. 典型场景：参会机器人、会中助手、代为旁听、代为参会。前提：机器人只能读到它自己参会过且仍在进行中的会议的事件；查询已结束会议的参会名单、纪要或逐字稿请使用 lark-vc 技能。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli vc --help"
+---
+
+# vc-agent (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取以下两份 skill 文档：**
+
+- [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、身份切换、权限处理
+- [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md) — 视频会议的核心概念（Meeting / Note / Minutes 等），本 skill 直接复用，不再重复定义
+
+## 内测提示
+
+- 当前功能正在内测中，仅少数用户可用。忽略 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 中的权限申请流程，以下方的指引为准。
+- 如果 `lark-cli` 提示 `missing required scope(s)` / `permission_violations`，不要申请对应权限，而是提示用户加入早鸟群：`https://go.larkoffice.com/join-chat/2f4nb0e1-fe00-4f67-bed7-25beaf533fbd`。
+- 如果 `lark-cli` 返回 `error.code=20017` / `ErrNotInGray`，提示用户加入早鸟群：`https://go.larkoffice.com/join-chat/2f4nb0e1-fe00-4f67-bed7-25beaf533fbd`。
+
+## 定位
+
+本 skill 与 [`lark-vc`](../lark-vc/SKILL.md) 并列：
+
+- **`lark-vc`** **负责"会后查询"**：搜索历史会议、参会人快照、纪要/逐字稿/录制
+- **`lark-vc-agent`** **负责"会中动作"**：机器人入会 / 读取进行中会议的实时事件 / 机器人离会
+
+按此分工路由，避免两个 skill 语义混淆。
+
+| 用户意图示例                                                     | 应路由到                                                                                                                                                  |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "帮我入会 123456789"、"代我参会"、"让机器人进会旁听"                         | **本 skill** `+meeting-join`                                                                                                                           |
+| "会议现在还开着，谁刚加入了"、"会议里谁在发言"、"有人共享屏幕吗"（**进行中会议**，且**机器人已入会**） | **本 skill** `+meeting-events`                                                                                                                         |
+| "退出会议"、"让机器人离开"                                            | **本 skill** `+meeting-leave`                                                                                                                          |
+| "昨天那场会有谁参加过"、"搜昨天的会"、"查纪要/逐字稿/录制"                          | [`lark-vc`](../lark-vc/SKILL.md)                                                                                                                      |
+| "帮我参会，结束后把纪要发到群" 等跨阶段场景                                    | 按序编排：本 skill（入会 → 读事件 → 离会）→ [`lark-vc`](../lark-vc/SKILL.md) / [`lark-minutes`](../lark-minutes/SKILL.md)（拉纪要）→ [`lark-im`](../lark-im/SKILL.md)（发群） |
+
+## 核心场景
+
+### 1. 加入正在进行的会议（写操作）
+
+1. 只有用户明确表达"让 Agent **真实入会**"（参会机器人、会中助手、代为旁听、代参会）时才用 `+meeting-join`。只是查数据不要入会。
+2. `+meeting-join --meeting-number` 只接受 **9 位纯数字**会议号，不是会议链接整串、也不是 `meeting_id`。
+3. 返回体中的 `meeting.id` **必须立刻记录**——后续 `+meeting-events` / `+meeting-leave` 都靠它，**不能用 9 位会议号替代**。
+4. 入会对所有参会人可见，执行前核实 9 位会议号来源，避免误入错会。
+5. 仅支持 `user` 身份，需提前 `lark-cli auth login`。
+6. 若入会失败，优先查看 `+meeting-join` reference 的错误排查段落，重点确认会议号、密码、会议状态、等候室 / 审批以及会议是否禁止当前身份加入。
+
+### 2. 感知会中事件（读操作）
+
+1. 用户要看"会议里正在发生什么"（参会人加入/离开、聊天、转写、屏幕共享）时，用 `+meeting-events`。
+2. 输入是 **`meeting_id`**（长数字 ID），不是 9 位会议号。
+3. Bot 必须**真实参会过**（先 `+meeting-join`），否则事件流通常不可见。具体的状态边界、结束后宽限窗口与错误码（如 `10005 / 20001 / 20002`）请查看 `+meeting-events` reference。
+4. **不能做会后复盘**，**不能替代参会人快照查询**。如果会议已结束：
+   - 想拿纪要文档或逐字稿文档 token：用 `lark-cli vc +notes --meeting-ids <meeting.id>`
+   - 想拿 AI 产物（summary / todos / chapters）或导出逐字稿文件：先用 `lark-cli vc +recording --meeting-ids <meeting.id>` 拿 `minute_token`，再用 `lark-cli vc +notes --minute-tokens <minute_token>`
+   - 想看参会人快照：用 `vc meeting get --with-participants`（见 [`lark-vc`](../lark-vc/SKILL.md)）
+5. **默认必须使用** **`--page-all`**，除非用户明确要求“只查一页”，或确实需要控制返回体大小。
+6. 输出格式默认优先 `--format pretty`（时间线更易读）；只有在需要完整保留原始消息流与结构化字段时，才使用 `--format json`。
+7. **必须识别分页信号**：只要响应里出现 `has_more=true`、pretty 里的 `more available`，或返回了非空 `page_token`，就不能把当前结果当作完整事件流；默认应继续分页，或明确告诉用户当前只是部分结果。
+8. 保留响应里的 `page_token`，下次增量拉取直接续，不要从头再拉。
+9. **只要你是基于** **`+meeting-events`** **来回答一场正在进行中的会议内容，就不能直接复用旧结果。** 无论用户是在问“现在/刚刚/最新”的状态，还是让你“总结一下这个会议讲什么”，都必须先重新拉一次当前事件流，确认拿到的是最新信息，再基于最新结果回答。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。
+
+### 3. 离开会议（写操作）
+
+1. 任务完成、或用户要求结束时，用 `+meeting-leave --meeting-id <从 +meeting-join 拿到的 meeting.id>`。
+2. `--meeting-id` **必须**是 `+meeting-join` 返回的长数字 `meeting.id`，**不接受 9 位会议号**。
+3. 离会**立即生效**，机器人从会议的参会人列表中消失，对其他参会人可见；若需要重新入会，再跑一次 `+meeting-join` 即可（非真正"不可逆"）。
+4. 仅支持 `user` 身份。
+
+### 4. Agent 参会最小闭环示范
+
+```bash
+# 1. 入会，捕获 meeting.id
+JOIN=$(lark-cli vc +meeting-join --meeting-number 123456789 --format json)
+MID=$(echo "$JOIN" | jq -r '.data.meeting.id')
+
+# 2. 会中轮询事件
+#    默认用 --page-all 拉全当前可见事件；下次增量优先复用 page_token
+#    典型间隔 10-30 秒
+lark-cli vc +meeting-events --meeting-id "$MID" --page-all --format pretty
+
+# 3. 任务完成或用户要求结束时离会
+lark-cli vc +meeting-leave --meeting-id "$MID"
+
+# 4. 会后可选：取纪要 / 逐字稿（跨到 lark-vc）
+lark-cli vc +notes --meeting-ids "$MID"
+```
+
+## Shortcuts
+
+Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
+
+| Shortcut                                                        | 类型 | 说明                                                                         |
+| --------------------------------------------------------------- | -- | -------------------------------------------------------------------------- |
+| [`+meeting-join`](references/lark-vc-agent-meeting-join.md)     | 写  | Join an in-progress meeting by 9-digit meeting number                      |
+| [`+meeting-events`](references/lark-vc-agent-meeting-events.md) | 读  | List bot meeting events (participant joined/left, transcript, chat, share) |
+| [`+meeting-leave`](references/lark-vc-agent-meeting-leave.md)   | 写  | Leave a meeting by meeting\_id                                             |
+
+- 使用 `+meeting-join` 前**必须**阅读 [references/lark-vc-agent-meeting-join.md](references/lark-vc-agent-meeting-join.md)，了解入参格式与写操作可见性风险。
+- 使用 `+meeting-events` 前**必须**阅读 [references/lark-vc-agent-meeting-events.md](references/lark-vc-agent-meeting-events.md)，了解 `meeting_id` 来源、分页、错误码（10005 / 20001 / 20002）与 "bot 仍在会中" 硬约束。
+- 使用 `+meeting-leave` 前**必须**阅读 [references/lark-vc-agent-meeting-leave.md](references/lark-vc-agent-meeting-leave.md)，了解 `meeting_id` 的来源与写操作可见性。
+
+## 权限表
+
+| Shortcut          | 所需 scope                       |
+| ----------------- | ------------------------------ |
+| `+meeting-join`   | `vc:meeting.bot.join:write`    |
+| `+meeting-events` | `vc:meeting.meetingevent:read` |
+| `+meeting-leave`  | `vc:meeting.bot.join:write`    |
+
+## 延伸
+
+- 查已结束会议、参会人快照、搜索历史会议 → [`lark-vc`](../lark-vc/SKILL.md)
+- 会议纪要、逐字稿 → [`lark-vc`](../lark-vc/SKILL.md) 的 `+notes`
+- 妙记产物（AI 总结 / 转写 / 章节）→ [`lark-minutes`](../lark-minutes/SKILL.md)
+- 会后把产物发到群 / 私聊 → [`lark-im`](../lark-im/SKILL.md)
+- 认证、身份切换、scope 管理 → [`lark-shared`](../lark-shared/SKILL.md)

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

@@ -0,0 +1,247 @@
+
+# vc +meeting-events
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询当前 bot 在一场正在进行的视频会议中收到的会中事件列表。该命令是**读操作**。对进行中会议，要求 bot 当前仍在会中；对已结束会议，存在一个**结束后 5 分钟内的宽限窗口**，只要 bot 曾经在这场会里出现过，仍可继续拉取事件。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-events`（调用 `GET /open-apis/vc/v1/bots/events`）。
+
+## 命令
+
+```bash
+# 默认用法：全量拉取当前可见事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-all --format pretty
+
+# 指定时间范围，并拉全该时间窗内当前可见事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --page-all --format pretty
+
+# 基于上一次保存的 page_token 继续查新增事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-token <last_page_token> --page-all --format pretty
+
+# 调试或控制返回体大小时，显式只查一页
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-size 20 --format json
+
+# 预览 API 调用（不实际请求）
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-id <id>` | 是 | 会议 ID（长数字 ID，不是 9 位会议号） |
+| `--start <time>` | 否 | 起始时间，支持 ISO 8601 / `YYYY-MM-DD` / Unix 秒 |
+| `--end <time>` | 否 | 结束时间，支持 ISO 8601 / `YYYY-MM-DD` / Unix 秒 |
+| `--page-token <token>` | 否 | 从指定分页游标继续拉取下一页 |
+| `--page-size <n>` | 否 | 单页模式每页大小。CLI 会自动夹紧到 `20-100`；传 `--page-all` 时固定使用 `100` |
+| `--page-all` | 否 | 自动分页，直到没有更多页面为止（内部有安全上限） |
+| `--format <fmt>` | 否 | 输出格式：json (CLI 默认) / pretty（本 skill 推荐默认） / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 输入必须是 meeting_id，不是 9 位会议号
+
+`--meeting-id` 必须是会议的长数字 ID。它通常来自：
+- `+meeting-join` 返回体中的 `meeting.id`
+- `+search` 结果中的 `id`
+
+**不要**把 9 位会议号（`--meeting-number`）传给这个命令。
+
+### 2. 仅支持 user 身份
+
+该命令仅支持 `user` 身份。
+
+### 3. bot 必须在会中，或在会议结束后的 5 分钟宽限窗口内曾经在会中
+
+这是查询“bot 在会中观察到的事件”的接口。若 bot 已离会、未入会、或会议已经无法再判断 bot 身份，后端通常会报：
+- `bot is not in meeting, no permission`
+
+因此，最稳妥的调用顺序通常是：
+
+```bash
+# 先入会
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 记录返回的 meeting.id
+
+# 再查询事件
+lark-cli vc +meeting-events --meeting-id <meeting.id>
+```
+
+更精确地说，后端当前的判断规则是：
+
+- **会议进行中**：要求 bot **当前仍在会中**
+- **会议已结束后的 5 分钟内**：只要 bot **曾经在这场会中出现过**，仍可拉取事件
+- **会议结束超过 5 分钟**：按会议结束处理，通常不再返回事件流
+- **bot 从未真实入会过**：即使会议仍在进行或刚结束，也会返回 `10005 bot is not in meeting`
+
+### 4. 自动分页规则
+
+- **先分清两层默认值**：
+  - shortcut 本身：不传 `--page-all` 时，只查 1 页。
+  - 本 skill 的默认策略：除非用户明确要求只看一页，或你确实需要控制返回体大小，否则默认**必须主动带 `--page-all`**，把当前可见事件尽量一次拉全。
+- 传 `--page-all`：开启自动分页，直到没有更多页面为止。
+- `--page-all` 时，CLI 固定使用最大 `page_size=100`。
+
+执行准则：
+
+- **默认命令模板**：`lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty`
+- 如果你发现自己执行成了不带 `--page-all` 的单页查询，而响应里又出现 `has_more=true` / `more available` / 非空 `page_token`，应立刻意识到这只是部分结果。
+- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --meeting-id <meeting.id> --page-token <returned_page_token> --page-all --format pretty`
+- 只有在用户明确要求“就看第一页”“先不要翻页”时，才不要默认带 `--page-all`
+- 只要你是基于 `+meeting-events` 来回答一场**正在进行中的会议内容**，就不能直接复用上一次查询结果。无论用户是在问“现在是谁在说话”“刚刚发生了什么”“最新事件有哪些”，还是让你“总结一下这个会议讲什么”，都必须先重新执行一次 `+meeting-events`，确认拿到的是最新事件流，再回答用户。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。
+
+### 5. pretty / json 输出差异
+
+- `--format pretty`：输出会议主题、会议时间和逐条时间线，适合快速理解“发生了什么”，也是本 skill 的默认推荐格式。
+- `--format json`：保留完整原始 `events[]` 结构——参会人 open_id、聊天原文、share_doc、分页字段都在原始响应里，适合提取字段、联动其他命令或做进一步程序处理。
+
+**选型原则**：只要目标是告诉用户“发生了什么”，默认就用 `--page-all --format pretty`；只有在需要完整原始消息流和结构化字段时，才改用 `json`。
+
+> **注意**：pretty 输出中的正文文本会做单行转义，真实换行会显示为 `\n`，避免打乱时间线布局。
+
+### 6. 内容理解模式：共享文档不能只看标题
+
+当用户意图是：
+
+- “总结这个会议”
+- “这个会议讲了什么”
+- “有哪些结论 / 待办 / 关键讨论”
+- “共享文档里在讲什么”
+
+不要只基于事件时间线直接回答。此时 `+meeting-events` 只是**线索发现器**，不是最终信息源。
+
+执行准则：
+
+- 这类问题默认先用 `lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format json` 拉取最新事件流。
+- 如果事件中出现共享文档线索，例如：
+  - `magic_share_started`
+  - `share_doc.title`
+  - `share_doc.url`
+- 必须继续读取共享文档内容，再生成总结，不能只根据“开始共享了某文档”这条事件和文档标题来概括会议内容。
+- 若存在多个共享文档，优先读取**最近一次共享**的文档。
+- 若文档读取失败，必须明确说明“以下总结仅基于会中事件流，未成功读取共享文档内容”。
+
+### 7. 关于 `page_token` 的返回与续拉
+
+- 不管这次是只查 1 页，还是通过 `--page-all` 已经把当前可见事件都拿完，都应把最后拿到的 `page_token` 一并保留下来并返回给用户。
+- 只要响应里出现 `has_more=true`、pretty 里出现 `more available`，或返回了非空 `page_token`，就必须先判断当前结果是否完整；默认情况下，这意味着你还需要继续分页。
+- 如果没有使用 `--page-all`，但出现了上述分页信号，默认应继续用返回的 `page_token` 拉下一页，而不是直接结束。只有在用户明确不要继续翻页时，才可以停止并明确说明当前结果不完整。
+- 下次继续“查新增事件”时，应优先复用上一次保存的 `page_token`，而不是从头全量再拉一次。
+- 只有在用户明确要求“从头回放全部事件”时，才忽略历史 `page_token`，重新从第一页开始。
+- 但如果用户要你回答的是**当前这场会正在讲什么**，而不是“上一次之后新增了什么”，也要先做一次新的事件查询，再决定是否需要基于旧 `page_token` 继续补拉。
+
+## 返回结构
+
+常见顶层字段：
+
+| 字段 | 说明 |
+|------|------|
+| `events` | 事件列表 |
+| `has_more` | 是否还有下一页 |
+| `page_token` | 下一页游标 |
+
+事件 `event_type` 常见类型：
+
+| event_type | 含义 |
+|-----------|------|
+| `participant_joined` | 有参会人加入会议 |
+| `participant_left` | 有参会人离开会议 |
+| `chat_received` | 收到会中聊天消息 |
+| `transcript_received` | 收到转写文本 |
+| `magic_share_started` | 开始共享内容 / 文档 |
+| `magic_share_ended` | 结束共享 |
+
+## pretty 输出示例
+
+```text
+会议主题：张三的视频会议
+会议时间：2026-04-17 15:28:52（进行中）
+
+[00:00:33] 明日之虾BOE(ou_xxx) 加入了会议
+[00:00:41] 张三(ou_xxx): [text] 6666
+[00:00:44] 张三(ou_xxx) 开始共享《智能纪要：飞书20251022-140223 2026年3月9日》
+           URL: https://...
+[00:01:32] 张三(ou_xxx): [reaction] JIAYI
+```
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+search` 结果中的 `id` |
+| `start` / `end` | 用户给出的时间范围；如未给出则默认取全量可见事件 |
+| `page-token` | 上一页或上一次查询结果中保存的 `page_token`；建议持久化保存，便于下次继续拉取新增事件 |
+
+## Agent 组合场景
+
+### 场景 1：入会后查看会中发生了什么
+
+```bash
+# 第 1 步：加入会议，记录返回的 meeting.id
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：查询事件流
+lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty
+```
+
+### 场景 2：过滤某段时间内的事件
+
+```bash
+lark-cli vc +meeting-events \
+  --meeting-id <meeting.id> \
+  --start 2026-04-17T15:00:00+08:00 \
+  --end 2026-04-17T16:00:00+08:00 \
+  --page-all \
+  --format pretty
+```
+
+### 场景 3：基于上一次的 `page_token` 继续查新增事件
+
+```bash
+# 上一次查询结束后，保留最后返回的 page_token
+# 这次直接从该游标继续拉新增事件
+lark-cli vc +meeting-events \
+  --meeting-id <meeting.id> \
+  --page-token <last_page_token> \
+  --page-all \
+  --format pretty
+```
+
+适用规则：
+
+- 当用户说“继续看新事件”“看上次之后新增了什么”时，优先使用上一次保存的 `page_token`。
+- 如果这次返回里仍有 `has_more=true`、pretty 里出现 `more available`，或又返回了新的 `page_token`，说明新增事件还没拉完，应继续分页，而不是把当前页误当成完整增量结果。
+- 只有在用户明确要求“从头回放全部事件”时，才忽略已有 `page_token`，重新从第一页开始。
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-id is required` | 未传入 `--meeting-id` | 传入长数字 `meeting.id` |
+| `10005 bot is not in meeting` | bot 从未真实入会该会议；或会议已结束但 bot 从未在会中出现过 | 先 `+meeting-join --meeting-number <9位号>` 真实入会再查；如果会议已经结束且当时 bot 没进过会，本接口也拉不到数据。**如果只是想看参会人快照，改用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants`**（不依赖 bot 身份参会） |
+| `20001 meeting_status_MEETING_END` | 会议已结束且已超出后端允许的 5 分钟宽限窗口 | 本接口不再适合继续拉取事件。若要拿纪要文档或逐字稿 token，用 `lark-cli vc +notes --meeting-ids <meeting.id>`；若要拿 AI 产物（summary / todos / chapters）或导出逐字稿文件，先用 `lark-cli vc +recording --meeting-ids <meeting.id>` 拿 `minute_token`，再用 `lark-cli vc +notes --minute-tokens <minute_token>`；参会人请用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants` |
+| `20002 meeting not exist` | `meeting_id` 错误，或会议实例当前已不可获取（常见于把 9 位会议号当 meeting_id 传） | 确认传入的是长数字 `meeting_id`，不是 9 位会议号 |
+| `HTTP 404` / `HTTP 500` | 服务端当前无法找到或处理该会议实例 | 换一个正在进行且 bot 可见的 meeting_id，或排查后端问题 |
+
+## 提示
+
+- 这是**会中事件流**查询，不适合拿来搜历史会议记录；搜历史会议请用 `+search`。
+- 如果会议已经结束，不要卡在 `+meeting-events`：  
+  - 想拿纪要文档或逐字稿 token：用 `lark-cli vc +notes --meeting-ids <meeting.id>`
+  - 想拿 AI 产物（summary / todos / chapters）或导出逐字稿文件：先用 `lark-cli vc +recording --meeting-ids <meeting.id>` 拿 `minute_token`，再用 `lark-cli vc +notes --minute-tokens <minute_token>`
+- 事件列表是否完整，取决于 bot 何时入会、何时离会，以及后端当前可见的会中事件范围。对于已结束会议，通常只在**结束后 5 分钟内**、且 bot **曾经在会中**时还能继续拉到事件。
+- 查询"谁参加过某会议"请用 `vc meeting get --params '{"meeting_id":"<id>","with_participants":true}'`——这是参会人**快照** API，不依赖 bot 是否参会，对已结束会议也可查；**不要** 用 `+meeting-events` 做参会人查询。
+
+## 参考
+
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 先真实入会
+- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 完成任务后离会
+- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
+- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,133 @@
+
+# vc +meeting-join
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+通过 9 位会议号加入一场正在进行的视频会议（bot join）。这是一次**写操作**，会实际让当前身份加入会议。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-join`（调用 `POST /open-apis/vc/v1/bots/join`）。
+
+## 命令
+
+```bash
+# 仅指定会议号（无密码）
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 指定会议号 + 密码
+lark-cli vc +meeting-join --meeting-number 123456789 --password 8888
+
+# 输出格式
+lark-cli vc +meeting-join --meeting-number 123456789 --format json
+
+# 预览 API 调用（不实际加入会议）
+lark-cli vc +meeting-join --meeting-number 123456789 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-number <no>` | 是 | 会议号，必须为 **9 位纯数字** |
+| `--password <pw>` | 否 | 会议密码，仅在该会议设置了入会密码时传入 |
+| `--format <fmt>` | 否 | 输出格式：json (默认) / pretty / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 仅支持 user 身份
+
+该命令仅支持 `user` 身份。
+
+### 2. 会议号格式严格校验
+
+`--meeting-number` 必须是 9 位纯数字，否则本地校验直接报错：
+`--meeting-number must be exactly 9 digits`。
+
+常见错误来源：
+- 把会议链接整条粘进来（应仅取尾部的 9 位数字）
+- 把 `meeting_id`（长数字 ID）当成会议号传入（两者不是同一个东西）
+
+### 3. 会议必须已开始且允许入会
+
+- 会议必须处于**进行中**状态，bot 无法加入尚未开始或已结束的会议。
+- 若会议设置了**等候室 / 入会审批**，bot 可能需要主持人放行后才真正入会。
+- 若返回 `HTTP 403: no permission`（错误码 `121003`），不要只理解成“账号没权限”。这类报错更常见的原因是：会议参数或会控配置当前不满足入会条件，例如会议号填错、密码未传或错误、会议尚未开始、等候室 / 入会审批未放行、会议禁止外部/特定身份加入等。应先确认这些配置项，再重试。
+
+### 4. 机器人入会后对其他参会人可见
+
+这是一次真实入会操作，机器人会立即出现在参会人列表中，其他参会人可见，并产生会议日志。误入错会的社交成本高于技术成本——执行前优先确认 9 位会议号的来源（用户输入 / 会议链接末尾），不要臆造。参数格式有疑问时可用 `--dry-run` 预览请求体。
+
+## 输出结果
+
+接口返回会议基本信息，字段视具体响应而定，常见字段：
+
+| 字段 | 说明 |
+|------|------|
+| `meeting.id` | 会议 ID（可后续传给 `+meeting-leave --meeting-id`） |
+| `meeting.meeting_no` | 会议号（与入参一致） |
+| `meeting.topic` | 会议主题 |
+| `meeting.start_time` | 会议开始时间 |
+
+> **重要**：拿到 `meeting.id` 后务必保留，退出会议（`+meeting-leave`）需要使用它，而不是会议号。
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-number` | 会议号由主持人分享；也可从会议链接尾部解析 9 位数字 |
+| `password` | 若会议设置了入会密码，由主持人提供 |
+
+## Agent 组合场景
+
+### 场景 1：加入会议 → 离开会议（最小闭环）
+
+```bash
+# 第 1 步：加入会议，记录返回的 meeting.id
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：完成任务后，使用上一步返回的 meeting.id 离开会议
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+```
+
+### 场景 2：加入会议 → 会后拉取纪要 / 录制
+
+```bash
+# 第 1 步：加入并参会
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：离会
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+
+# 第 3 步：会议结束后，查询录制（拿到 minute_token）
+lark-cli vc +recording --meeting-ids <meeting.id>
+
+# 第 4 步：查询会议纪要（总结 / 待办 / 章节 / 逐字稿）
+lark-cli vc +notes --meeting-ids <meeting.id>
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-number must be exactly 9 digits` | 会议号不是 9 位纯数字 | 检查是否误传了会议链接或 meeting_id |
+| 会议密码错误 | `--password` 错误或未提供 | 向主持人确认会议密码 |
+| 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中 |
+| `HTTP 403: no permission` / `121003` | 入会前置条件不满足，通常不是单纯 scope 问题 | 依次确认：1）会议允许智能体加入；2）会议号正确；3）如有密码，已正确传入 `--password`；4）会议已开始；5）等候室 / 入会审批已放行；6）会议未禁止当前身份加入（如限制外部、限制 bot、仅特定成员可入会）；确认后重试 |
+| 入会被拒绝 | 等候室 / 入会审批 / 限制外部入会 | 联系主持人放行或调整会议设置 |
+
+## 提示
+
+- 仅在 Agent 需要**真实加入**会议（例如参会机器人、会中助手）时使用；只拉取会议数据不需要入会。
+- 入会会让机器人立即出现在参会列表；若要回退，直接 `+meeting-leave` 即可。参数格式不确定时可选 `--dry-run` 预览，但不是必经步骤。
+- 执行成功后，立即记录返回的 `meeting.id`，用于后续 `+meeting-leave` / `+meeting-events`。
+
+## 参考
+
+- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 对应的离会命令
+- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
+- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议记录
+- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,111 @@
+
+# vc +meeting-leave
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+通过 `meeting_id` 离开当前身份所在的视频会议（bot leave）。这是一次**写操作**，会实际把当前身份从会议中移出。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-leave`（调用 `POST /open-apis/vc/v1/bots/leave`）。
+
+## 命令
+
+```bash
+# 通过 meeting_id 离会
+lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28
+
+# 输出格式
+lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --format json
+
+# 预览 API 调用（不实际离会）
+lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-id <id>` | 是 | 会议 ID（**不是 9 位会议号**） |
+| `--format <fmt>` | 否 | 输出格式：json (默认) / pretty / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 入参是 meeting_id，不是会议号
+
+`--meeting-id` 必须是会议的长数字 ID，通常由 `+meeting-join` 返回体中的 `meeting.id` 提供，也可从 `+search` 结果中的 `id` 字段获取。**传 9 位会议号会失败**。
+
+### 2. 仅支持 user 身份
+
+该命令仅支持 `user` 身份。只能让当前身份自己离会，无法强制移出其他参会人。
+
+### 3. 当前身份必须在会议中
+
+必须先通过 `+meeting-join` 或其他方式在该会议中，否则接口会报错。
+
+### 4. 离会立即生效，对其他参会人可见
+
+机器人会立刻从参会列表消失；若会议启用了录制/纪要，bot 的参会时段到此截止。确认任务完成再调用；如需要重新入会，再跑 `+meeting-join` 即可（非真正"不可逆"）。
+
+## 输出结果
+
+接口成功返回时，默认输出：`Left meeting <meeting-id> successfully.`。
+`--format json` 返回 API 原始响应体。
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+search` 结果中的 `id` 字段 |
+
+## Agent 组合场景
+
+### 场景 1：加入 → 完成任务 → 离开（最小闭环）
+
+```bash
+# 第 1 步：加入会议，记录 meeting.id
+lark-cli vc +meeting-join --meeting-number 123456789
+
+# 第 2 步：在会中完成任务（如监听发言、记录信息等）
+# ...
+
+# 第 3 步：使用上一步记录的 meeting.id 离会
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+```
+
+### 场景 2：会后补拉产物
+
+```bash
+# 第 1 步：离会后会议仍在进行或已结束
+lark-cli vc +meeting-leave --meeting-id <meeting.id>
+
+# 第 2 步：会议结束后查询录制
+lark-cli vc +recording --meeting-ids <meeting.id>
+
+# 第 3 步：查询会议纪要
+lark-cli vc +notes --meeting-ids <meeting.id>
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--meeting-id is required` | 未传入 `--meeting-id` | 传入从 `+meeting-join` 得到的 `meeting.id` |
+| `meeting not found` / `invalid meeting_id` | 误传了 9 位会议号 | 必须使用 `meeting.id`，不是会议号 |
+| `not in meeting` | 当前身份并不在该会议中 | 确认先 `+meeting-join` 成功 |
+
+## 提示
+
+- 离会会让机器人从参会列表消失，对其他参会人可见；若需要重新入会直接再 `+meeting-join`，不是真正的"不可逆"。参数格式不确定时可选 `--dry-run` 预览。
+- 与 `+meeting-join` 成对使用：能 join 的身份才能 leave。
+- `meeting_id` 必须来自 `+meeting-join` 的返回值，不要用 9 位会议号。
+
+## 参考
+
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 对应的入会命令
+- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
+- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
+- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 获取会议纪要
+- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
+- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-vc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-vc
 version: 1.0.0
-description: "飞书视频会议：查询会议记录、获取会议纪要产物（总结、待办、章节、逐字稿）。1. 查询已经结束的会议数量或详情时使用本技能(如历史日期｜ 昨天 | 上周 | 今天已经开过的会议等场景)，查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议记录。3. 获取或整理会议纪要时使用本技能。"
+description: "飞书视频会议：搜索历史会议、查询会议纪要产物（总结、待办、章节、逐字稿）、查询会议参会人快照。1. 查询已经结束的会议数量或详情时使用本技能（如历史日期｜昨天｜上周｜今天已经开过的会议等场景），查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议。3. 获取或整理会议纪要、逐字稿、录制产物时使用本技能。4. 查询“谁参加过某会议”“参会人列表”等参会人快照信息用 vc meeting get --with-participants（任意时点可查，含已结束会议）。注意：**Agent 真实入会/离会、感知正在进行中会议的实时事件**请使用 lark-vc-agent 技能，本技能不覆盖写操作和会中事件流。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -14,8 +14,7 @@ metadata:
 
 ## 核心概念
 
-- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting\_id 标识。
-- **会议记录（Meeting Record）**：视频会议结束后生成的记录，支持通过关键词、时间段、参会人、组织者、会议室等筛选条件搜索会议室。
+- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting\_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索（见 `+search`）。
 - **会议纪要（Note）**：视频会议结束后生成的结构化文档，包含纪要文档（包含总结、待办、章节）和逐字稿文档。
 - **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，支持视频/音频的转写和会议纪要，通过 minute\_token 标识。
 - **纪要文档（MainDoc）**：AI 智能纪要的主文档，包含 AI 生成的总结和待办，对应 `note_doc_token`。
@@ -61,12 +60,29 @@ lark-cli schema drive.metas.batch_query
 # 批量获取文档基本信息: 一次最多查询 10 个文档
 lark-cli drive metas batch_query --data '{"request_docs": [{"doc_type": "docx", "doc_token": "<doc_token>"}], "with_url": true}'
 ```
-3. 需要获取文档内容时，使用 `lark-cli docs +fetch`。
+3. 需要获取文档内容时，使用 `lark-cli docs +fetch --api-version v2`。
 ```bash
 # 获取文档内容
 lark-cli docs +fetch --api-version v2 --doc <doc_token> --doc-format markdown
 ```
 
+### 4. 查询参会人快照（读操作）
+
+用户问"谁参加过这场会议""这个会议有哪些参会人""某某参会了吗"等**参会人快照**类问题时，使用 **`vc meeting get --with-participants`**：这是参会人服务端快照 API，不依赖 bot 身份参会，**已结束会议也可查**：
+
+```bash
+lark-cli vc meeting get --params '{"meeting_id":"<meeting_id>","with_participants":true}'
+```
+
+选型判断表：
+
+| 用户意图 | 推荐命令 | 所在 skill |
+|---------|---------|--------|
+| 参会人快照（谁参加过、何时入/离会，任意时点）| `vc meeting get --with-participants` | 本 skill |
+| 已结束会议的发言内容 | `vc +notes` 取 `verbatim_doc_token` 再 `docs +fetch --api-version v2` | 本 skill |
+| **进行中会议**的实时事件流（转写、聊天、共享、会中加入/离开）| `vc +meeting-events` | [`lark-vc-agent`](../lark-vc-agent/SKILL.md) |
+| **Agent 真实入会 / 离会** | `vc +meeting-join` / `vc +meeting-leave` | [`lark-vc-agent`](../lark-vc-agent/SKILL.md) |
+
 ## 资源关系
 
 ```
@@ -109,6 +125,8 @@ Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
 - 使用 `+notes` 命令时，必须阅读 [references/lark-vc-notes.md](references/lark-vc-notes.md)，了解查询参数、产物类型和返回值结构。
 - 使用 `+recording` 命令时，必须阅读 [references/lark-vc-recording.md](references/lark-vc-recording.md)，了解查询参数和返回值结构。
 
+> **Agent 参会相关命令已独立**：`+meeting-join` / `+meeting-leave` / `+meeting-events` 请使用 [`lark-vc-agent`](../lark-vc-agent/SKILL.md) 技能。
+
 ## API Resources
 
 ```bash
@@ -146,3 +164,5 @@ lark-cli vc meeting get --params '{"meeting_id": "<meeting_id>", "with_participa
 | `+recording --calendar-event-ids` | `vc:record:readonly`、`calendar:calendar:read`、`calendar:calendar.event:read` |
 | `+search` | `vc:meeting.search:read` |
 | `meeting.get` | `vc:meeting.meetingevent:read` |
+
+> Agent 参会相关 scope（`vc:meeting.bot.join:write` / `vc:meeting.meetingevent:read`）见 [`lark-vc-agent`](../lark-vc-agent/SKILL.md)。

skills/lark-vc/references/lark-vc-recording.md

@@ -109,7 +109,7 @@ lark-cli vc +notes --minute-tokens <minute_token>
 
 ```bash
 # 第 1 步：搜索历史会议，拿到 meeting_ids
-lark-cli vc +search --query "周会" --start yesterday
+lark-cli vc +search --query "周会" --start 2026-03-10
 
 # 第 2 步：使用上一步返回的 meeting_ids 查询录制，拿到 minute_tokens
 lark-cli vc +recording --meeting-ids <ids>

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

@@ -88,7 +88,17 @@ lark-cli vc +search --query "周会" --format json
 
 当返回 `has_more=true` 时，使用响应中的 `page_token` 配合 `--page-token` 获取下一页结果。
 
-### 5. 日期型 `--end` 包含当天整天
+### 5. 机器人可同时加入多个会议
+
+机器人支持同时加入多个正在进行中的会议；加入新会议前，不需要先退出已经在会中的其他会议。
+
+这意味着：
+
+- 不要假设 bot 一次只能在一个会议中
+- 如果用户要求 bot 再加入另一场会，可以直接继续执行对应的入会命令
+- 只有在用户明确要求结束某一场会中的 bot 参会时，才调用对应的离会命令
+
+### 6. 日期型 `--end` 包含当天整天
 
 当 `--end` 传入的是仅日期格式（如 `2026-03-10`）时，CLI 会将它解释为当天 `23:59:59`，而不是当天 `00:00:00`。
 

skills/lark-whiteboard/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 > [!IMPORTANT]
 > - 运行 `lark-cli --version`，确认可用，无需询问用户。
-> - 运行 `npx -y @larksuite/whiteboard-cli@^0.2.10 -v`，确认可用，无需询问用户。
+> - 运行 `npx -y @larksuite/whiteboard-cli@^0.2.11 -v`，确认可用，无需询问用户。
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
@@ -54,7 +54,7 @@ metadata:
 | 用户给了什么 | 怎么获取 |
 |---|---|
 | 直接给了 whiteboard token（`wbcnXXX`）| 直接使用 |
-| 文档 URL 或 doc_id，文档中已有画板 | `lark-cli docs +fetch --doc <URL> --as user`，从返回的 `<whiteboard token="xxx"/>` 提取 |
+| 文档 URL 或 doc_id，文档中已有画板 | `lark-cli docs +fetch --api-version v2 --doc <URL> --as user`，从返回的 `<whiteboard token="xxx"/>` 提取 |
 | 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --api-version v2 --doc <doc_id> --command append --content '<whiteboard type="blank"></whiteboard>' --as user`，从响应 `data.new_blocks[0].block_token` 取得（`block_type == "whiteboard"` 的那条；参数详见 lark-doc SKILL.md）|
 
 **Step 2：渲染 & 写入**
@@ -124,7 +124,7 @@ diagram.png           ← 渲染结果
 
 ```bash
 # 第一步：dry-run 探测
-npx -y @larksuite/whiteboard-cli@^0.2.10 -i <产物文件> --to openapi --format json \
+npx -y @larksuite/whiteboard-cli@^0.2.11 -i <产物文件> --to openapi --format json \
   | lark-cli whiteboard +update \
     --whiteboard-token <Token> \
     --source - --input_format raw \
@@ -132,7 +132,7 @@ npx -y @larksuite/whiteboard-cli@^0.2.10 -i <产物文件> --to openapi --format
     --overwrite --dry-run --as user
 
 # 第二步：确认后执行
-npx -y @larksuite/whiteboard-cli@^0.2.10 -i <产物文件> --to openapi --format json \
+npx -y @larksuite/whiteboard-cli@^0.2.11 -i <产物文件> --to openapi --format json \
   | lark-cli whiteboard +update \
     --whiteboard-token <Token> \
     --source - --input_format raw \

skills/lark-whiteboard/references/image.md

@@ -4,20 +4,24 @@
 
 ## 概述
 
-画板 DSL 支持 `type: 'image'` 节点，但图片不能直接使用 URL，必须先上传到飞书获取 **media token**，然后在 DSL 中引用。
+画板 DSL 支持 `type: 'image'` 节点，但图片不能直接使用 URL 或其他域的 token，**必须先上传到目标画板获取 `whiteboard` 域 media token**，然后在 DSL 中引用。
 
-**关键约束**：
-- 图片 token 必须通过 `docs +media-upload --parent-type whiteboard` 上传获取
-- 图片必须上传到**目标画板**（`--parent-node` 设为目标画板 token），跨画板的 token 不可用
-- `drive +upload` 获取的 Drive file token **不能**用于画板图片节点
+**核心规则**：不管图片从哪来（本地文件、URL、文档中的 `docx_image` token、其他域的 Drive token），都必须通过 `docs +media-upload --parent-type whiteboard --parent-node <目标画板token>` 上传，拿到画板专属的 media token 后才能在 DSL 中使用。直接使用非 `whiteboard` 域的 token 会导致画板 API 报 500（错误码 2891001）或图片在文档中消失。
 
 ## Step 0：图片准备流程
 
-### 1. 下载图片
+### 1. 获取图片到本地
 
-用 `curl` 下载图片到本地。**必须使用能根据关键词返回相关图片的图片源**。
+根据图片来源选择对应方式：
 
-**推荐图片源**：
+| 图片来源 | 获取方式 |
+|---------|---------|
+| 本地文件 | 直接使用 |
+| 网络 URL | `curl -L -o photo.jpg "<URL>"` |
+| 文档中的图片 token | `lark-cli docs +media-download --token <token> --output ./photo.png` |
+| 其他域的 Drive token | `lark-cli docs +media-download --token <token> --output ./photo.png` |
+
+**图片源选择（需要搜索图片时）**：
 
 | 图片源类型 | 说明 |
 |-------|------|
@@ -29,11 +33,6 @@
 - **关键词搜索**：支持按关键词搜索并返回相关图片，确保图片内容与主题匹配
 - **内容丰富**：图库图片种类多、数量大，能覆盖常见主题（宠物、美食、景点、产品等）
 
-```bash
-curl -L -o photo1.jpg "<图片URL>"
-curl -L -o photo2.jpg "<图片URL>"
-```
-
 **严禁使用随机占位图服务**：某些图库仅提供随机占位图，URL 中的关键词参数不会影响返回的图片内容，下载的图片与主题完全无关。
 
 ### 2. 校验图片
@@ -74,7 +73,8 @@ lark-cli docs +media-upload --file ./photo3.jpg --parent-type whiteboard --paren
 
 | 错误现象 | 原因 | 解决 |
 |---------|------|------|
-| 画板 API 返回 500（2891001） | 使用了 Drive file token 而非 media token | 改用 `docs +media-upload --parent-type whiteboard` |
+| 画板 API 返回 500（2891001） | 使用了非 `whiteboard` 域 token（如 `docx_image`、Drive file token） | 下载图片后用 `docs +media-upload --parent-type whiteboard` 重新上传 |
 | 画板 API 返回 500 | 图片上传到了其他画板 | 重新上传到目标画板 |
+| 画板在文档中图片消失 | 图片 token 的资源域与画板不匹配 | 确保图片通过 `--parent-type whiteboard --parent-node <画板token>` 上传 |
 | 图片裂开/无法显示 | token 无效或已过期 | 重新上传获取新 token |
 | 图片内容与主题无关 | 使用了随机占位图服务 | 改用免费版权图库服务 |

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

@@ -74,7 +74,7 @@ whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKIL
 
 ```bash
 # 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
-npx -y @larksuite/whiteboard-cli@^0.2.10 -i <产物文件> --to openapi --format json \
+npx -y @larksuite/whiteboard-cli@^0.2.11 -i <产物文件> --to openapi --format json \
   | lark-cli whiteboard +update \
     --whiteboard-token <画板Token> \
     --source - --input_format raw \
@@ -88,7 +88,7 @@ whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKIL
 
 ```bash
 # 生成 OpenAPI 格式到文件
-npx -y @larksuite/whiteboard-cli@^0.2.10 -i <DSL 文件> --to openapi --format json -o ./temp.json
+npx -y @larksuite/whiteboard-cli@^0.2.11 -i <DSL 文件> --to openapi --format json -o ./temp.json
 
 # 从文件读取并更新
 lark-cli whiteboard +update \

skills/lark-whiteboard/references/layout.md

@@ -336,7 +336,7 @@ DSL 的语法是严格白名单，不能写原生 CSS 属性（不支持 `alignS
 先出骨架图导出坐标，再基于坐标补充连线和注解：
 
 ```bash
-npx -y @larksuite/whiteboard-cli@^0.2.10 -i skeleton.json -o step1.png -l coords.json
+npx -y @larksuite/whiteboard-cli@^0.2.11 -i skeleton.json -o step1.png -l coords.json
 ```
 
 `coords.json` 包含每个带 id 节点的精确坐标（absX, absY, width, height）。

skills/lark-whiteboard/references/schema.md

@@ -272,14 +272,14 @@ SVG 通过 `image/svg+xml` Blob 加载到画布，**不在 HTML DOM 中**，因
   x?: number; y?: number;
   width?: WBSizeValue;          // 默认 48
   height?: WBSizeValue;         // 默认 48，保持正方形
-  name: string;                 // 图标名称，从 npx -y @larksuite/whiteboard-cli@^0.2.10 --icons 输出中选取
+  name: string;                 // 图标名称，从 npx -y @larksuite/whiteboard-cli@^0.2.11 --icons 输出中选取
   color?: string;               // 可选颜色覆盖，hex 格式如 '#FF6600'
 }
 ```
 
 **获取可用图标**：规划好内容和布局后，运行以下命令查看所有可用图标名，从中选取：
 ```bash
-npx -y @larksuite/whiteboard-cli@^0.2.10 --icons
+npx -y @larksuite/whiteboard-cli@^0.2.11 --icons
 ```
 
 用法：

skills/lark-whiteboard/routes/dsl.md

@@ -13,7 +13,7 @@ Step 1: 路由 & 读取知识
 Step 2: 生成完整 DSL（含颜色）
   - 按 content.md 规划信息量和分组
   - 按 layout.md 选择布局模式和间距
-  - 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.10 --icons` 查看可用图标
+  - 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.11 --icons` 查看可用图标
   - 按 style.md 上色（用户没指定时用默认经典色板）
   - 按 schema.md 语法输出完整 JSON
   - 连线参考 connectors.md，排版参考 typography.md
@@ -25,12 +25,12 @@ Step 2: 生成完整 DSL（含颜色）
 
 Step 3: 渲染 & 审查 → 交付
   - 渲染前自查（见下方检查清单）
-  - 渲染 PNG（仅用于预览验证，不是最终产物）：npx -y @larksuite/whiteboard-cli@^0.2.10 -i diagram.json -o diagram.png
+  - 渲染 PNG（仅用于预览验证，不是最终产物）：npx -y @larksuite/whiteboard-cli@^0.2.11 -i diagram.json -o diagram.png
   - 检查：信息完整？布局合理？配色协调？文字无截断？连线无交叉？
   - 有问题 → 按症状表修复 → 重新渲染（最多 2 轮）
   - 2 轮后仍有严重问题 → 考虑走 Mermaid 路径兜底
   - 写入画板：用 whiteboard-cli 将 diagram.json 转换为 OpenAPI 格式并 pipe 给 +update：
-      npx -y @larksuite/whiteboard-cli@^0.2.10 -i diagram.json --to openapi --format json \
+      npx -y @larksuite/whiteboard-cli@^0.2.11 -i diagram.json --to openapi --format json \
         | lark-cli whiteboard +update --whiteboard-token <board_token> \
             --source - --input_format raw --idempotent-token <时间戳+标识> --as user
       → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)

skills/lark-whiteboard/routes/mermaid.md

@@ -16,10 +16,10 @@ Step 3: 渲染验证 & 写入画板 & 交付
   1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/
   2. 保存为 diagram.mmd
   3. 渲染（仅用于预览验证，PNG 不是最终产物）：
-       npx -y @larksuite/whiteboard-cli@^0.2.10 -i diagram.mmd -o diagram.png
+       npx -y @larksuite/whiteboard-cli@^0.2.11 -i diagram.mmd -o diagram.png
   4. 审查 PNG，有问题修改后重新渲染（最多 2 轮）
   5. 写入画板：用 whiteboard-cli 将 diagram.mmd 转换为 OpenAPI 格式并 pipe 给 +update：
-       npx -y @larksuite/whiteboard-cli@^0.2.10 -i diagram.mmd --to openapi --format json \
+       npx -y @larksuite/whiteboard-cli@^0.2.11 -i diagram.mmd --to openapi --format json \
          | lark-cli whiteboard +update --whiteboard-token <board_token> \
              --source - --input_format raw --idempotent-token <时间戳+标识> --as user
        → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)