chore: prepare v1.0.11 release metadata

Update the package version and changelog entry so the release branch matches the v1.0.11 changes already queued after v1.0.10.

This keeps the published package version and human-readable release notes aligned without pulling unrelated local workspace changes into the release PR.

Change-Id: Ia937651001e0057df4fe82bd11705c52d343f9a9
Constraint: Release PR should include only CHANGELOG.md and package.json
Rejected: Include .gitignore OMX ignore update | unrelated local-only change
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep release preparation PRs limited to versioned metadata unless a release-blocking code change is required
Tested: make unit-test; go mod tidy (no go.mod/go.sum changes); golangci-lint run --new-from-rev=origin/main
Not-tested: npm install/publish flow

.github/workflows/cli-e2e.yml

@@ -25,6 +25,8 @@ on:
 
 permissions:
   contents: read
+  actions: read
+  checks: write
 
 jobs:
   cli-e2e:
@@ -65,71 +67,17 @@ jobs:
             echo "No CLI E2E packages to test after exclusions."
             exit 1
           fi
-          go run gotest.tools/gotestsum@v1.12.3 --format testname --junitfile cli-e2e-report.xml -- -count=1 -v $packages
+          # gotestsum requires --packages when --rerun-fails is combined with go test args after --.
+          packages_arg=$(printf '%s\n' "$packages" | paste -sd' ' -)
+          go run gotest.tools/gotestsum@v1.12.3 --rerun-fails=2 --rerun-fails-max-failures=20 --packages="$packages_arg" --format testname --junitfile cli-e2e-report.xml -- -count=1 -v
 
-      - name: Summarize CLI E2E test report
+      - name: Publish CLI E2E test report
         if: ${{ !cancelled() }}
-        run: |
-          python3 - <<'PY'
-          import os
-          import xml.etree.ElementTree as ET
-
-          report_path = "cli-e2e-report.xml"
-          summary_path = os.environ["GITHUB_STEP_SUMMARY"]
-
-          root = ET.parse(report_path).getroot()
-          suites = [root] if root.tag == "testsuite" else root.findall("testsuite")
-
-          tests = failures = errors = skipped = 0
-          failed_cases = []
-          skipped_cases = []
-
-          for suite in suites:
-            tests += int(suite.attrib.get("tests", 0))
-            failures += int(suite.attrib.get("failures", 0))
-            errors += int(suite.attrib.get("errors", 0))
-            skipped += int(suite.attrib.get("skipped", 0))
-
-            for case in suite.findall("testcase"):
-              classname = case.attrib.get("classname", "")
-              name = case.attrib.get("name", "")
-              label = f"{classname}.{name}" if classname else name
-
-              failure = case.find("failure")
-              error = case.find("error")
-              skipped_node = case.find("skipped")
-
-              if failure is not None or error is not None:
-                message = ""
-                node = failure if failure is not None else error
-                if node is not None:
-                  message = node.attrib.get("message", "") or (node.text or "").strip()
-                failed_cases.append((label, message))
-              elif skipped_node is not None:
-                message = skipped_node.attrib.get("message", "") or (skipped_node.text or "").strip()
-                skipped_cases.append((label, message))
-
-          passed = tests - failures - errors - skipped
-
-          with open(summary_path, "a", encoding="utf-8") as f:
-            f.write("## CLI E2E Test Report\n\n")
-            f.write(f"- Total: {tests}\n")
-            f.write(f"- Passed: {passed}\n")
-            f.write(f"- Failed: {failures}\n")
-            f.write(f"- Errors: {errors}\n")
-            f.write(f"- Skipped: {skipped}\n\n")
-
-            if failed_cases:
-              f.write("### Failed Tests\n\n")
-              for label, message in failed_cases:
-                detail = f" - {message}" if message else ""
-                f.write(f"- `{label}`{detail}\n")
-              f.write("\n")
-
-            if skipped_cases:
-              f.write("### Skipped Tests\n\n")
-              for label, message in skipped_cases:
-                detail = f" - {message}" if message else ""
-                f.write(f"- `{label}`{detail}\n")
-              f.write("\n")
-          PY
+        uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2 # v3.0.0
+        with:
+          name: CLI E2E Tests
+          path: cli-e2e-report.xml
+          reporter: java-junit
+          use-actions-summary: true
+          list-suites: all
+          list-tests: all

.gitignore

@@ -35,3 +35,4 @@ tests/mail/reports/
 # Generated / test artifacts
 internal/registry/meta_data.json
 cmd/api/download.bin
+app.log

CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.11] - 2026-04-14
+
+### Features
+
+- **sheets**: Add dropdown shortcuts for data validation management (`+set-dropdown`, `+update-dropdown`, `+get-dropdown`, `+delete-dropdown`) (#461)
+- **task**: Add task search, tasklist search, related-task, set-ancestor, and subscribe-event shortcuts (#377)
+- Streamline interactive login by removing the extra auth confirmation step (#451)
+
+### Bug Fixes
+
+- **base**: Validate JSON object inputs for base shortcuts and reject `null` objects (#458)
+
+### Documentation
+
+- **sheets**: Document value formats for formulas and special field types (#456)
+- **readme**: Add Attendance to the features table (#460)
+
+## [v1.0.10] - 2026-04-13
+
+### Features
+
+- **im**: Support im oapi range download for large files (#283)
+- **sheets**: Add filter view and condition shortcuts (#422)
+- **wiki**: Add wiki move shortcut with async task polling (#436)
+- **drive**: Add drive `+create-shortcut` shortcut (#432)
+- **drive**: Add drive files patch metadata API (#444)
+- **task**: Support `--section-guid` flag in tasklist-task-add shortcut (#430)
+
+### Bug Fixes
+
+- **base**: Support large base attachment uploads (#441)
+- **config**: Clarify init copy for TTY, preserve original for AI (#448)
+- **im**: Reject `--user-id` under bot identity for chat-messages-list (#340)
+- **mail**: Add missing scopes for mail `+watch` shortcut (#357)
+- **mail**: Restrict `--output-dir` to current working directory (#376)
+
+### Documentation
+
+- **wiki**: Add wiki member operations to lark-wiki skill (#417)
+- **task**: Document sections API resources, permissions, and URL parsing (#430)
+- **doc**: Clarify when markdown escaping is needed (#312)
+
 ## [v1.0.9] - 2026-04-11
 
 ### Features
@@ -303,6 +345,8 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.11]: https://github.com/larksuite/cli/releases/tag/v1.0.11
+[v1.0.10]: https://github.com/larksuite/cli/releases/tag/v1.0.10
 [v1.0.9]: https://github.com/larksuite/cli/releases/tag/v1.0.9
 [v1.0.8]: https://github.com/larksuite/cli/releases/tag/v1.0.8
 [v1.0.7]: https://github.com/larksuite/cli/releases/tag/v1.0.7

README.md

@@ -6,14 +6,14 @@
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 21 AI Agent [Skills](./skills/).
+The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 22 AI Agent [Skills](./skills/).
 
 [Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Commands](#three-layer-command-system) · [Advanced](#advanced-usage) · [Security](#security--risk-warnings-read-before-use) · [Contributing](#contributing)
 
 ## Why lark-cli?
 
-- **Agent-Native Design** — 21 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
-- **Wide Coverage** — 13 business domains, 200+ curated commands, 21 AI Agent [Skills](./skills/)
+- **Agent-Native Design** — 22 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
+- **Wide Coverage** — 14 business domains, 200+ curated commands, 22 AI Agent [Skills](./skills/)
 - **AI-Friendly & Optimized** — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output to maximize Agent call success rates
 - **Open Source, Zero Barriers** — MIT license, ready to use, just `npm install`
 - **Up and Running in 3 Minutes** — One-click app creation, interactive login, from install to first API call in just 3 steps
@@ -36,6 +36,7 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 | 👤 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                                                                        |
+| 🕐 Attendance | Query personal attendance check-in records                                                                                        |
 | ✍️ Approval   | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                                      |
 
 ## Installation & Quick Start
@@ -149,6 +150,7 @@ lark-cli auth status
 | `lark-minutes`                  | Minutes metadata & AI artifacts (summary, todos, chapters)                                                     |
 | `lark-openapi-explorer`         | Explore underlying APIs from official docs                                                                     |
 | `lark-skill-maker`              | Custom skill creation framework                                                                                |
+| `lark-attendance`               | Query personal attendance check-in records                                                                     |
 | `lark-approval`                 | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                   |
 | `lark-workflow-meeting-summary` | Workflow: meeting minutes aggregation & structured report                                                      |
 | `lark-workflow-standup-report`  | Workflow: agenda & todo summary                                                                                |

README.zh.md

@@ -6,14 +6,14 @@
 
 [中文版](./README.zh.md) | [English](./README.md)
 
-飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议等核心业务域，提供 200+ 命令及 21 个 AI Agent [Skills](./skills/)。
+飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议等核心业务域，提供 200+ 命令及 22 个 AI Agent [Skills](./skills/)。
 
 [安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [命令](#三层命令调用) · [进阶用法](#进阶用法) · [安全](#安全与风险提示使用前必读) · [贡献](#贡献)
 
 ## 为什么选 lark-cli？
 
-- **为 Agent 原生设计** — 21 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
-- **覆盖面广** — 13 大业务域、200+ 精选命令、21 个 AI Agent [Skills](./skills/)
+- **为 Agent 原生设计** — 22 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
+- **覆盖面广** — 14 大业务域、200+ 精选命令、22 个 AI Agent [Skills](./skills/)
 - **AI 友好调优** — 每条命令经过 Agent 实测验证，提供更友好的参数、智能默认值和结构化输出，大幅提升 Agent 调用成功率
 - **开源零门槛** — MIT 协议，开箱即用，`npm install` 即可使用
 - **三分钟上手** — 一键创建应用、交互式登录授权，从安装到第一次 API 调用只需三步
@@ -36,6 +36,7 @@
 | 👤 通讯录   | 按姓名/邮箱/手机号搜索用户、获取用户信息                      |
 | 📧 邮箱     | 浏览、搜索、阅读邮件，发送、回复、转发邮件，管理草稿，监听新邮件           |
 | 🎥 视频会议 | 搜索会议记录、查询会议纪要与录制                           |
+| 🕐 考勤打卡 | 查询个人考勤打卡记录                                |
 | ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
 
 ## 安装与快速开始
@@ -150,6 +151,7 @@ lark-cli auth status
 | `lark-minutes`                  | 妙记元数据与 AI 产物（总结、待办、章节）                    |
 | `lark-openapi-explorer`         | 从官方文档探索底层 API                             |
 | `lark-skill-maker`              | 自定义 skill 创建框架                            |
+| `lark-attendance`               | 查询个人考勤打卡记录                                |
 | `lark-approval`                 | 审批任务查询、同意/拒绝/转交审批任务、撤回与抄送审批实例             |
 | `lark-workflow-meeting-summary` | 工作流：会议纪要汇总与结构化报告                          |
 | `lark-workflow-standup-report`  | 工作流：日程待办摘要                                |

cmd/auth/login_interactive.go

@@ -184,27 +184,6 @@ func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg) (*i
 	}
 	fmt.Fprintf(ios.ErrOut, msg.SummaryScopes, len(scopes), scopePreview)
 
-	// Phase 2: confirmation
-	var confirmed bool
-	form2 := huh.NewForm(
-		huh.NewGroup(
-			huh.NewConfirm().
-				Title(msg.ConfirmAuth).
-				Value(&confirmed),
-		),
-	).WithTheme(cmdutil.ThemeFeishu())
-
-	if err := form2.Run(); err != nil {
-		if err == huh.ErrUserAborted {
-			return nil, output.ErrBare(1)
-		}
-		return nil, err
-	}
-
-	if !confirmed {
-		return nil, output.ErrBare(1)
-	}
-
 	return &interactiveResult{
 		Domains:    selectedDomains,
 		ScopeLevel: permLevel,

cmd/config/init_interactive.go

@@ -177,17 +177,26 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	// Step 2: Build and display verification URL + QR code
 	verificationURL := larkauth.BuildVerificationURL(authResp.VerificationUriComplete, build.Version)
 
-	// Show QR code in terminal
-	qr, qrErr := qrcode.New(verificationURL, qrcode.Medium)
-	if qrErr == nil {
-		fmt.Fprint(f.IOStreams.ErrOut, qr.ToSmallString(false))
+	// Branch on TTY: human-friendly copy in interactive terminals,
+	// preserve original copy for AI / non-interactive callers.
+	if f.IOStreams.IsTerminal {
+		fmt.Fprintf(f.IOStreams.ErrOut, "%s", msg.ScanQRCode)
+		qr, qrErr := qrcode.New(verificationURL, qrcode.Medium)
+		if qrErr == nil {
+			fmt.Fprint(f.IOStreams.ErrOut, qr.ToSmallString(false))
+		}
+		fmt.Fprintf(f.IOStreams.ErrOut, "%s", msg.ScanOrOpenLink)
+		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", verificationURL)
+		fmt.Fprintf(f.IOStreams.ErrOut, "%s\n", msg.WaitingForScan)
+	} else {
+		qr, qrErr := qrcode.New(verificationURL, qrcode.Medium)
+		if qrErr == nil {
+			fmt.Fprint(f.IOStreams.ErrOut, qr.ToSmallString(false))
+		}
+		fmt.Fprintf(f.IOStreams.ErrOut, "%s", msg.OpenLinkNonTTY)
+		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", verificationURL)
+		fmt.Fprintf(f.IOStreams.ErrOut, "%s\n", msg.WaitingForScanNonTTY)
 	}
-
-	fmt.Fprintf(f.IOStreams.ErrOut, "%s", msg.ScanOrOpenLink)
-	fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", verificationURL)
-
-	// Step 3: Poll for result
-	fmt.Fprintf(f.IOStreams.ErrOut, "%s\n", msg.WaitingForScan)
 	result, err := larkauth.PollAppRegistration(ctx, httpClient, core.BrandFeishu, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 	if err != nil {
 		return nil, output.ErrAuth("%v", err)

cmd/config/init_messages.go

@@ -16,11 +16,16 @@ type initMsg struct {
 	Platform           string
 	SelectPlatform     string
 	Feishu             string
-	ScanOrOpenLink     string
-	WaitingForScan     string
-	DetectedLarkTenant string
-	AppCreated         string
-	ConfigSaved        string
+	// TTY (interactive) variants
+	ScanQRCode     string // header shown above QR code
+	ScanOrOpenLink string // post-QR alt link prompt ("or open...")
+	WaitingForScan string // active polling indicator
+	// Non-TTY (AI / non-interactive) variants — preserve original copy
+	OpenLinkNonTTY       string // primary link prompt
+	WaitingForScanNonTTY string // passive waiting indicator
+	DetectedLarkTenant   string
+	AppCreated           string
+	ConfigSaved          string
 }
 
 var initMsgZh = &initMsg{
@@ -29,12 +34,15 @@ var initMsgZh = &initMsg{
 	ConfigExistingApp:  "手动输入应用凭证",
 	Platform:           "平台",
 	SelectPlatform:     "选择平台",
-	Feishu:             "飞书",
-	ScanOrOpenLink:     "\n打开以下链接配置应用:\n\n",
-	WaitingForScan:     "等待配置应用...",
-	DetectedLarkTenant: "[lark-cli] 检测到 Lark 租户，切换端点重试...",
-	AppCreated:         "应用配置成功! App ID: %s",
-	ConfigSaved:        "应用配置成功! App ID: %s",
+	Feishu:               "飞书",
+	ScanQRCode:           "\n使用飞书 / Lark 扫码配置应用：\n\n",
+	ScanOrOpenLink:       "\n或打开以下链接完成配置：\n",
+	WaitingForScan:       "正在获取你的应用配置结果...",
+	OpenLinkNonTTY:       "\n打开以下链接配置应用:\n\n",
+	WaitingForScanNonTTY: "等待配置应用...",
+	DetectedLarkTenant:   "[lark-cli] 检测到 Lark 租户，切换端点重试...",
+	AppCreated:           "应用配置成功! App ID: %s",
+	ConfigSaved:          "应用配置成功! App ID: %s",
 }
 
 var initMsgEn = &initMsg{
@@ -43,12 +51,15 @@ var initMsgEn = &initMsg{
 	ConfigExistingApp:  "Enter app credentials yourself",
 	Platform:           "Platform",
 	SelectPlatform:     "Select platform",
-	Feishu:             "Feishu",
-	ScanOrOpenLink:     "\nOpen the link below to configure app:\n\n",
-	WaitingForScan:     "Waiting for app configuration...",
-	DetectedLarkTenant: "[lark-cli] Detected Lark tenant, switching endpoint...",
-	AppCreated:         "App configured! App ID: %s",
-	ConfigSaved:        "App configured! App ID: %s",
+	Feishu:               "Feishu",
+	ScanQRCode:           "\nScan the QR code with Feishu/Lark:\n\n",
+	ScanOrOpenLink:       "\nOr open the link below in your browser:\n",
+	WaitingForScan:       "Fetching configuration results...",
+	OpenLinkNonTTY:       "\nOpen the link below to configure app:\n\n",
+	WaitingForScanNonTTY: "Waiting for app configuration...",
+	DetectedLarkTenant:   "[lark-cli] Detected Lark tenant, switching endpoint...",
+	AppCreated:           "App configured! App ID: %s",
+	ConfigSaved:          "App configured! App ID: %s",
 }
 
 func getInitMsg(lang string) *initMsg {

cmd/config/init_messages_test.go

@@ -54,11 +54,14 @@ func assertAllFieldsNonEmpty(t *testing.T, msg *initMsg, label string) {
 		"Platform":           msg.Platform,
 		"SelectPlatform":     msg.SelectPlatform,
 		"Feishu":             msg.Feishu,
-		"ScanOrOpenLink":     msg.ScanOrOpenLink,
-		"WaitingForScan":     msg.WaitingForScan,
-		"DetectedLarkTenant": msg.DetectedLarkTenant,
-		"AppCreated":         msg.AppCreated,
-		"ConfigSaved":        msg.ConfigSaved,
+		"ScanQRCode":           msg.ScanQRCode,
+		"ScanOrOpenLink":       msg.ScanOrOpenLink,
+		"WaitingForScan":       msg.WaitingForScan,
+		"OpenLinkNonTTY":       msg.OpenLinkNonTTY,
+		"WaitingForScanNonTTY": msg.WaitingForScanNonTTY,
+		"DetectedLarkTenant":   msg.DetectedLarkTenant,
+		"AppCreated":           msg.AppCreated,
+		"ConfigSaved":          msg.ConfigSaved,
 	}
 	for name, val := range fields {
 		if val == "" {

package.json

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

shortcuts/base/base_execute_test.go

@@ -151,6 +151,87 @@ func TestBaseFieldExecuteUpdate(t *testing.T) {
 	}
 }
 
+func TestBaseObjectJSONShortcutsRejectArrayInDryRun(t *testing.T) {
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		args     []string
+	}{
+		{
+			name:     "field create",
+			shortcut: BaseFieldCreate,
+			args:     []string{"+field-create", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `[]`, "--dry-run"},
+		},
+		{
+			name:     "field update",
+			shortcut: BaseFieldUpdate,
+			args:     []string{"+field-update", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "fld_x", "--json", `[]`, "--dry-run"},
+		},
+		{
+			name:     "record search",
+			shortcut: BaseRecordSearch,
+			args:     []string{"+record-search", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `[]`, "--dry-run"},
+		},
+		{
+			name:     "record upsert",
+			shortcut: BaseRecordUpsert,
+			args:     []string{"+record-upsert", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `[]`, "--dry-run"},
+		},
+		{
+			name:     "record batch create",
+			shortcut: BaseRecordBatchCreate,
+			args:     []string{"+record-batch-create", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `[]`, "--dry-run"},
+		},
+		{
+			name:     "record batch update",
+			shortcut: BaseRecordBatchUpdate,
+			args:     []string{"+record-batch-update", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `[]`, "--dry-run"},
+		},
+		{
+			name:     "view set filter",
+			shortcut: BaseViewSetFilter,
+			args:     []string{"+view-set-filter", "--base-token", "app_x", "--table-id", "tbl_x", "--view-id", "vew_x", "--json", `[]`, "--dry-run"},
+		},
+		{
+			name:     "view set visible fields",
+			shortcut: BaseViewSetVisibleFields,
+			args:     []string{"+view-set-visible-fields", "--base-token", "app_x", "--table-id", "tbl_x", "--view-id", "vew_x", "--json", `[]`, "--dry-run"},
+		},
+		{
+			name:     "view set card",
+			shortcut: BaseViewSetCard,
+			args:     []string{"+view-set-card", "--base-token", "app_x", "--table-id", "tbl_x", "--view-id", "vew_x", "--json", `[]`, "--dry-run"},
+		},
+		{
+			name:     "view set timebar",
+			shortcut: BaseViewSetTimebar,
+			args:     []string{"+view-set-timebar", "--base-token", "app_x", "--table-id", "tbl_x", "--view-id", "vew_x", "--json", `[]`, "--dry-run"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			factory, stdout, _ := newExecuteFactory(t)
+			err := runShortcut(t, tt.shortcut, tt.args, factory, stdout)
+			if err == nil {
+				t.Fatal("expected error")
+			}
+			if !strings.Contains(err.Error(), "--json must be a JSON object") {
+				t.Fatalf("err=%v", err)
+			}
+			if !strings.Contains(err.Error(), "lark-base skill") {
+				t.Fatalf("err=%v", err)
+			}
+			if strings.Contains(err.Error(), "array") {
+				t.Fatalf("err should not mention array: %v", err)
+			}
+			if got := stdout.String(); got != "" {
+				t.Fatalf("stdout=%q, want empty", got)
+			}
+		})
+	}
+}
+
 func TestBaseTableExecuteCreate(t *testing.T) {
 	factory, stdout, reg := newExecuteFactory(t)
 	reg.Register(&httpmock.Stub{
@@ -259,7 +340,7 @@ func TestBaseViewExecutePropertyActions(t *testing.T) {
 				"data": []interface{}{map[string]interface{}{"field": "fld_status", "desc": false}},
 			},
 		})
-		if err := runShortcut(t, BaseViewSetGroup, []string{"+view-set-group", "--base-token", "app_x", "--table-id", "tbl_x", "--view-id", "vew_x", "--json", `[{"field":"fld_status","desc":false}]`}, factory, stdout); err != nil {
+		if err := runShortcut(t, BaseViewSetGroup, []string{"+view-set-group", "--base-token", "app_x", "--table-id", "tbl_x", "--view-id", "vew_x", "--json", `{"group_config":[{"field":"fld_status","desc":false}]}`}, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
 		}
 		if got := stdout.String(); !strings.Contains(got, `"group"`) || !strings.Contains(got, `"fld_status"`) {
@@ -277,7 +358,7 @@ func TestBaseViewExecutePropertyActions(t *testing.T) {
 				"data": []interface{}{map[string]interface{}{"field": "fld_amount", "desc": true}},
 			},
 		})
-		if err := runShortcut(t, BaseViewSetSort, []string{"+view-set-sort", "--base-token", "app_x", "--table-id", "tbl_x", "--view-id", "vew_x", "--json", `[{"field":"fld_amount","desc":true}]`}, factory, stdout); err != nil {
+		if err := runShortcut(t, BaseViewSetSort, []string{"+view-set-sort", "--base-token", "app_x", "--table-id", "tbl_x", "--view-id", "vew_x", "--json", `{"sort_config":[{"field":"fld_amount","desc":true}]}`}, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
 		}
 		if got := stdout.String(); !strings.Contains(got, `"sort"`) || !strings.Contains(got, `"fld_amount"`) {
@@ -865,6 +946,157 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
+	t.Run("upload attachment uses multipart for large file", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+
+		tmpFile, err := os.CreateTemp(t.TempDir(), "base-attachment-large-*.bin")
+		if err != nil {
+			t.Fatalf("CreateTemp() err=%v", err)
+		}
+		if err := tmpFile.Truncate(common.MaxDriveMediaUploadSinglePartSize + 1); err != nil {
+			t.Fatalf("Truncate() err=%v", err)
+		}
+		if err := tmpFile.Close(); err != nil {
+			t.Fatalf("Close() err=%v", err)
+		}
+		withBaseWorkingDir(t, filepath.Dir(tmpFile.Name()))
+
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields/fld_att",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{"id": "fld_att", "name": "附件", "type": "attachment"},
+			},
+		})
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/rec_x",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"record_id": "rec_x",
+					"fields":    map[string]interface{}{},
+				},
+			},
+		})
+
+		prepareStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/medias/upload_prepare",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"upload_id":  "upload_big_1",
+					"block_size": float64(8 * 1024 * 1024),
+					"block_num":  float64(3),
+				},
+			},
+		}
+		reg.Register(prepareStub)
+
+		partStubs := make([]*httpmock.Stub, 0, 3)
+		for i := 0; i < 3; i++ {
+			stub := &httpmock.Stub{
+				Method: "POST",
+				URL:    "/open-apis/drive/v1/medias/upload_part",
+				Body: map[string]interface{}{
+					"code": 0,
+					"msg":  "ok",
+				},
+			}
+			partStubs = append(partStubs, stub)
+			reg.Register(stub)
+		}
+
+		finishStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/medias/upload_finish",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{"file_token": "file_tok_big"},
+			},
+		}
+		reg.Register(finishStub)
+
+		updateStub := &httpmock.Stub{
+			Method: "PATCH",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/rec_x",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"record_id": "rec_x",
+					"fields": map[string]interface{}{
+						"附件": []interface{}{
+							map[string]interface{}{
+								"file_token":                "file_tok_big",
+								"name":                      "large-report.bin",
+								"deprecated_set_attachment": true,
+							},
+						},
+					},
+				},
+			},
+		}
+		reg.Register(updateStub)
+
+		if err := runShortcut(t, BaseRecordUploadAttachment, []string{
+			"+record-upload-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--field-id", "fld_att",
+			"--file", "./" + filepath.Base(tmpFile.Name()),
+			"--name", "large-report.bin",
+		}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+
+		if got := stdout.String(); !strings.Contains(got, `"updated": true`) || !strings.Contains(got, `"file_tok_big"`) || !strings.Contains(got, `"large-report.bin"`) {
+			t.Fatalf("stdout=%s", got)
+		}
+
+		prepareBody := string(prepareStub.CapturedBody)
+		if !strings.Contains(prepareBody, `"file_name":"large-report.bin"`) ||
+			!strings.Contains(prepareBody, `"parent_type":"bitable_file"`) ||
+			!strings.Contains(prepareBody, `"parent_node":"app_x"`) ||
+			!strings.Contains(prepareBody, `"size":20971521`) {
+			t.Fatalf("prepare body=%s", prepareBody)
+		}
+
+		firstPartBody := string(partStubs[0].CapturedBody)
+		if !strings.Contains(firstPartBody, `name="upload_id"`) ||
+			!strings.Contains(firstPartBody, "upload_big_1") ||
+			!strings.Contains(firstPartBody, `name="seq"`) ||
+			!strings.Contains(firstPartBody, "\r\n0\r\n") ||
+			!strings.Contains(firstPartBody, `name="size"`) ||
+			!strings.Contains(firstPartBody, "8388608") {
+			t.Fatalf("first part body=%s", firstPartBody)
+		}
+
+		lastPartBody := string(partStubs[2].CapturedBody)
+		if !strings.Contains(lastPartBody, `name="seq"`) ||
+			!strings.Contains(lastPartBody, "\r\n2\r\n") ||
+			!strings.Contains(lastPartBody, `name="size"`) ||
+			!strings.Contains(lastPartBody, "4194305") {
+			t.Fatalf("last part body=%s", lastPartBody)
+		}
+
+		finishBody := string(finishStub.CapturedBody)
+		if !strings.Contains(finishBody, `"upload_id":"upload_big_1"`) ||
+			!strings.Contains(finishBody, `"block_num":3`) {
+			t.Fatalf("finish body=%s", finishBody)
+		}
+
+		updateBody := string(updateStub.CapturedBody)
+		if !strings.Contains(updateBody, `"附件"`) ||
+			!strings.Contains(updateBody, `"file_token":"file_tok_big"`) ||
+			!strings.Contains(updateBody, `"name":"large-report.bin"`) ||
+			!strings.Contains(updateBody, `"deprecated_set_attachment":true`) {
+			t.Fatalf("update body=%s", updateBody)
+		}
+	})
+
 	t.Run("upload attachment rejects non-attachment field", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 
@@ -904,6 +1136,37 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			t.Fatalf("err=%v", err)
 		}
 	})
+
+	t.Run("upload attachment rejects file larger than 2GB", func(t *testing.T) {
+		factory, stdout, _ := newExecuteFactory(t)
+
+		tmpFile, err := os.CreateTemp(t.TempDir(), "base-too-large-*.bin")
+		if err != nil {
+			t.Fatalf("CreateTemp() err=%v", err)
+		}
+		if err := tmpFile.Truncate(2*1024*1024*1024 + 1); err != nil {
+			t.Fatalf("Truncate() err=%v", err)
+		}
+		if err := tmpFile.Close(); err != nil {
+			t.Fatalf("Close() err=%v", err)
+		}
+		withBaseWorkingDir(t, filepath.Dir(tmpFile.Name()))
+
+		err = runShortcut(t, BaseRecordUploadAttachment, []string{
+			"+record-upload-attachment",
+			"--base-token", "app_x",
+			"--table-id", "tbl_x",
+			"--record-id", "rec_x",
+			"--field-id", "fld_att",
+			"--file", "./" + filepath.Base(tmpFile.Name()),
+		}, factory, stdout)
+		if err == nil {
+			t.Fatal("expected validation error, got nil")
+		}
+		if !strings.Contains(err.Error(), "exceeds 2GB limit") {
+			t.Fatalf("err=%v", err)
+		}
+	})
 }
 
 func TestBaseViewExecuteReadCreateDeleteAndFilter(t *testing.T) {
@@ -1021,7 +1284,7 @@ func TestBaseViewExecuteReadCreateDeleteAndFilter(t *testing.T) {
 			factory,
 			stdout,
 		)
-		if err == nil || !strings.Contains(err.Error(), "invalid JSON object") {
+		if err == nil || !strings.Contains(err.Error(), "--json must be a JSON object") {
 			t.Fatalf("err=%v", err)
 		}
 	})

shortcuts/base/base_shortcut_helpers.go

@@ -63,7 +63,7 @@ func loadJSONInput(pc *parseCtx, raw string, flagName string) (string, error) {
 }
 
 func jsonInputTip(flagName string) string {
-	return fmt.Sprintf("tip: pass a JSON object/array directly, or use --%s @path/to/file.json", flagName)
+	return fmt.Sprintf("tip: pass a valid JSON directly, or use --%s @file.json; use the lark-base skill or this command's reference to find the expected body", flagName)
 }
 
 func formatJSONError(flagName string, target string, err error) error {

shortcuts/base/base_shortcuts_test.go

@@ -120,9 +120,9 @@ func TestWrapViewPropertyBody(t *testing.T) {
 	}
 }
 
-func TestViewSetVisibleFieldsNoValidateHook(t *testing.T) {
-	if BaseViewSetVisibleFields.Validate != nil {
-		t.Fatalf("expected no validate hook, got non-nil")
+func TestViewSetVisibleFieldsValidateHook(t *testing.T) {
+	if BaseViewSetVisibleFields.Validate == nil {
+		t.Fatal("expected validate hook")
 	}
 }
 
@@ -212,8 +212,8 @@ func TestBaseFieldUpdateHelpHidesReadGuideFlag(t *testing.T) {
 
 func TestBaseFieldValidate(t *testing.T) {
 	ctx := context.Background()
-	if err := BaseFieldCreate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "json": "{"}, nil, nil)); err != nil {
-		t.Fatalf("invalid json should bypass CLI validate, err=%v", err)
+	if err := BaseFieldCreate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "json": "{"}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--json invalid JSON object") {
+		t.Fatalf("err=%v", err)
 	}
 	if err := BaseFieldCreate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "json": `{"name":"f1","type":"formula"}`}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--i-have-read-guide is required") {
 		t.Fatalf("err=%v", err)
@@ -255,22 +255,29 @@ func TestBaseRecordValidate(t *testing.T) {
 	if BaseRecordList.Validate != nil {
 		t.Fatalf("record list validate should be nil for repeatable --field-id")
 	}
-	if BaseRecordSearch.Validate != nil {
-		t.Fatalf("record search validate should be nil for API passthrough")
+	if BaseRecordSearch.Validate == nil {
+		t.Fatalf("record search validate should reject invalid JSON before dry-run")
 	}
 	if BaseRecordGet.Validate != nil {
 		t.Fatalf("record get validate should be nil")
 	}
-	if BaseRecordUpsert.Validate != nil {
-		t.Fatalf("record upsert validate should be nil for API passthrough")
+	if BaseRecordUpsert.Validate == nil {
+		t.Fatalf("record upsert validate should reject invalid JSON before dry-run")
 	}
 }
+
 func TestBaseViewValidate(t *testing.T) {
 	ctx := context.Background()
 	if err := BaseViewCreate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "tbl_1", "json": `{"name":"Main"}`}, nil, nil)); err != nil {
 		t.Fatalf("create validate err=%v", err)
 	}
-	if err := BaseViewSetTimebar.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "tbl_1", "view-id": "Main", "json": "{"}, nil, nil)); err != nil {
-		t.Fatalf("invalid view json should bypass CLI validate, err=%v", err)
+	if err := BaseViewSetGroup.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "tbl_1", "view-id": "Main", "json": `[{"field":"fld_1"}]`}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--json must be a JSON object") {
+		t.Fatalf("err=%v", err)
+	}
+	if err := BaseViewSetSort.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "tbl_1", "view-id": "Main", "json": `[{"field":"fld_1"}]`}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--json must be a JSON object") {
+		t.Fatalf("err=%v", err)
+	}
+	if err := BaseViewSetTimebar.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "tbl_1", "view-id": "Main", "json": "{"}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--json invalid JSON object") {
+		t.Fatalf("err=%v", err)
 	}
 }

shortcuts/base/field_ops.go

@@ -81,16 +81,7 @@ func dryRunFieldSearchOptions(_ context.Context, runtime *common.RuntimeContext)
 
 func validateFieldJSON(runtime *common.RuntimeContext) (map[string]interface{}, error) {
 	pc := newParseCtx(runtime)
-	raw, _ := loadJSONInput(pc, runtime.Str("json"), "json")
-	if raw == "" {
-		return nil, nil
-	}
-	var body map[string]interface{}
-	_ = common.ParseJSON([]byte(raw), &body)
-	if body == nil {
-		return nil, nil
-	}
-	return body, nil
+	return parseJSONObject(pc, runtime.Str("json"), "json")
 }
 
 func validateFormulaLookupGuideAck(runtime *common.RuntimeContext, command string, body map[string]interface{}) error {

shortcuts/base/helpers.go

@@ -6,6 +6,7 @@ package base
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/url"
@@ -36,7 +37,14 @@ func parseJSONObject(pc *parseCtx, raw string, flagName string) (map[string]inte
 	}
 	var result map[string]interface{}
 	if err := common.ParseJSON([]byte(resolved), &result); err != nil {
-		return nil, formatJSONError(flagName, "object", err)
+		var syntaxErr *json.SyntaxError
+		if errors.As(err, &syntaxErr) {
+			return nil, formatJSONError(flagName, "object", err)
+		}
+		return nil, common.FlagErrorf("--%s must be a JSON object; %s", flagName, jsonInputTip(flagName))
+	}
+	if result == nil {
+		return nil, common.FlagErrorf("--%s must be a JSON object; %s", flagName, jsonInputTip(flagName))
 	}
 	return result, nil
 }

shortcuts/base/helpers_test.go

@@ -38,7 +38,10 @@ func TestParseHelpers(t *testing.T) {
 	if err != nil || obj["name"] != "demo" {
 		t.Fatalf("obj=%v err=%v", obj, err)
 	}
-	if _, err := parseJSONObject(testPC, `[1]`, "json"); err == nil || !strings.Contains(err.Error(), "invalid JSON object") {
+	if _, err := parseJSONObject(testPC, `[1]`, "json"); err == nil || !strings.Contains(err.Error(), "--json must be a JSON object") || !strings.Contains(err.Error(), "lark-base skill") || strings.Contains(err.Error(), "array") {
+		t.Fatalf("err=%v", err)
+	}
+	if _, err := parseJSONObject(testPC, `null`, "json"); err == nil || !strings.Contains(err.Error(), "--json must be a JSON object") {
 		t.Fatalf("err=%v", err)
 	}
 	obj, err = parseJSONObject(testPC, "@"+tmp.Name(), "json")
@@ -63,7 +66,7 @@ func TestParseHelpers(t *testing.T) {
 	if _, err := parseStringListFlexible(testPC, `[1]`, "fields"); err == nil || !strings.Contains(err.Error(), "invalid JSON string array") {
 		t.Fatalf("err=%v", err)
 	}
-	if _, err := parseJSONValue(testPC, "{", "json"); err == nil || !strings.Contains(err.Error(), "tip: pass a JSON object/array directly") {
+	if _, err := parseJSONValue(testPC, "{", "json"); err == nil || !strings.Contains(err.Error(), "tip: pass a valid JSON directly") || !strings.Contains(err.Error(), "@file.json") || !strings.Contains(err.Error(), "lark-base skill") {
 		t.Fatalf("err=%v", err)
 	}
 	if !reflect.DeepEqual(parseStringList("m,n"), []string{"m", "n"}) {
@@ -281,11 +284,11 @@ func TestJSONInputHelpers(t *testing.T) {
 		t.Fatalf("err=%v", err)
 	}
 	syntaxErr := formatJSONError("json", "object", &json.SyntaxError{Offset: 7})
-	if !strings.Contains(syntaxErr.Error(), "near byte 7") || !strings.Contains(syntaxErr.Error(), "tip: pass a JSON object/array directly") {
+	if !strings.Contains(syntaxErr.Error(), "near byte 7") || !strings.Contains(syntaxErr.Error(), "tip: pass a valid JSON directly") || !strings.Contains(syntaxErr.Error(), "@file.json") || !strings.Contains(syntaxErr.Error(), "lark-base skill") {
 		t.Fatalf("syntaxErr=%v", syntaxErr)
 	}
 	typeErr := formatJSONError("json", "object", &json.UnmarshalTypeError{Field: "filter_info"})
-	if !strings.Contains(typeErr.Error(), `field "filter_info"`) {
+	if !strings.Contains(typeErr.Error(), `field "filter_info"`) || !strings.Contains(typeErr.Error(), "tip: pass a valid JSON directly") || !strings.Contains(typeErr.Error(), "@file.json") || !strings.Contains(typeErr.Error(), "lark-base skill") {
 		t.Fatalf("typeErr=%v", typeErr)
 	}
 }

shortcuts/base/record_batch_create.go

@@ -25,6 +25,9 @@ var BaseRecordBatchCreate = common.Shortcut{
 		`Example: --json '{"fields":["Title","Status"],"rows":[["Task A","Open"],["Task B","Done"]]}'`,
 		"Agent hint: use the lark-base skill's record-batch-create guide for usage and limits.",
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateRecordJSON(runtime)
+	},
 	DryRun: dryRunRecordBatchCreate,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeRecordBatchCreate(runtime)

shortcuts/base/record_batch_update.go

@@ -25,6 +25,9 @@ var BaseRecordBatchUpdate = common.Shortcut{
 		`Example: --json '{"record_id_list":["recXXX"],"patch":{"Status":"Done"}}'`,
 		"Agent hint: use the lark-base skill's record-batch-update guide for usage and limits.",
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateRecordJSON(runtime)
+	},
 	DryRun: dryRunRecordBatchUpdate,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeRecordBatchUpdate(runtime)

shortcuts/base/record_ops.go

@@ -113,7 +113,9 @@ func dryRunRecordHistoryList(_ context.Context, runtime *common.RuntimeContext)
 }
 
 func validateRecordJSON(runtime *common.RuntimeContext) error {
-	return nil
+	pc := newParseCtx(runtime)
+	_, err := parseJSONObject(pc, runtime.Str("json"), "json")
+	return err
 }
 
 func recordListFields(runtime *common.RuntimeContext) []string {

shortcuts/base/record_search.go

@@ -25,6 +25,9 @@ var BaseRecordSearch = common.Shortcut{
 		`Example: --json '{"keyword":"Alice","search_fields":["Name"]}'`,
 		"Agent hint: use the lark-base skill's record-search guide for usage and limits.",
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateRecordJSON(runtime)
+	},
 	DryRun: dryRunRecordSearch,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeRecordSearch(runtime)

shortcuts/base/record_upload_attachment.go

@@ -5,15 +5,11 @@ package base
 
 import (
 	"context"
-	"encoding/json"
 	"errors"
 	"fmt"
-	"net/http"
 	"path/filepath"
 	"strings"
 
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/util"
@@ -21,8 +17,8 @@ import (
 )
 
 const (
-	baseAttachmentUploadMaxFileSize = 20 * 1024 * 1024
-	baseAttachmentParentType        = "bitable_file"
+	baseAttachmentUploadMaxFileSize int64 = 2 * 1024 * 1024 * 1024
+	baseAttachmentParentType              = "bitable_file"
 )
 
 var BaseRecordUploadAttachment = common.Shortcut{
@@ -37,7 +33,7 @@ var BaseRecordUploadAttachment = common.Shortcut{
 		tableRefFlag(true),
 		recordRefFlag(true),
 		fieldRefFlag(true),
-		{Name: "file", Desc: "local file path (max 20MB)", Required: true},
+		{Name: "file", Desc: "local file path (max 2GB; files > 20MB use multipart upload automatically)", Required: true},
 		{Name: "name", Desc: "attachment file name (default: local file name)"},
 	},
 	DryRun: dryRunRecordUploadAttachment,
@@ -52,7 +48,7 @@ func dryRunRecordUploadAttachment(_ context.Context, runtime *common.RuntimeCont
 	if fileName == "" {
 		fileName = filepath.Base(filePath)
 	}
-	return common.NewDryRunAPI().
+	dry := common.NewDryRunAPI().
 		Desc("4-step orchestration: validate attachment field → read existing record attachments → upload file to Base → patch merged attachment array").
 		GET("/open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id").
 		Desc("[1] Read target field and ensure it is an attachment field").
@@ -61,15 +57,42 @@ func dryRunRecordUploadAttachment(_ context.Context, runtime *common.RuntimeCont
 		Set("field_id", runtime.Str("field-id")).
 		GET("/open-apis/base/v3/bases/:base_token/tables/:table_id/records/:record_id").
 		Desc("[2] Read current record to preserve existing attachments in the target cell").
-		Set("record_id", runtime.Str("record-id")).
-		POST("/open-apis/drive/v1/medias/upload_all").
-		Desc("[3] Upload local file to the current Base as attachment media (multipart/form-data)").
-		Body(map[string]interface{}{
-			"file_name":   fileName,
-			"parent_type": baseAttachmentParentType,
-			"parent_node": runtime.Str("base-token"),
-			"file":        "@" + filePath,
-		}).
+		Set("record_id", runtime.Str("record-id"))
+	if baseAttachmentShouldUseMultipart(runtime.FileIO(), filePath) {
+		dry.POST("/open-apis/drive/v1/medias/upload_prepare").
+			Desc("[3a] Initialize multipart attachment upload to the current Base").
+			Body(map[string]interface{}{
+				"file_name":   fileName,
+				"parent_type": baseAttachmentParentType,
+				"parent_node": runtime.Str("base-token"),
+				"size":        "<file_size>",
+			}).
+			POST("/open-apis/drive/v1/medias/upload_part").
+			Desc("[3b] Upload attachment parts (repeated)").
+			Body(map[string]interface{}{
+				"upload_id": "<upload_id>",
+				"seq":       "<chunk_index>",
+				"size":      "<chunk_size>",
+				"file":      "<chunk_binary>",
+			}).
+			POST("/open-apis/drive/v1/medias/upload_finish").
+			Desc("[3c] Finalize multipart attachment upload and get file token").
+			Body(map[string]interface{}{
+				"upload_id": "<upload_id>",
+				"block_num": "<block_num>",
+			})
+	} else {
+		dry.POST("/open-apis/drive/v1/medias/upload_all").
+			Desc("[3] Upload local file to the current Base as attachment media (multipart/form-data)").
+			Body(map[string]interface{}{
+				"file_name":   fileName,
+				"parent_type": baseAttachmentParentType,
+				"parent_node": runtime.Str("base-token"),
+				"file":        "@" + filePath,
+				"size":        "<file_size>",
+			})
+	}
+	return dry.
 		PATCH("/open-apis/base/v3/bases/:base_token/tables/:table_id/records/:record_id").
 		Desc("[4] Update the target attachment cell with existing attachments plus the uploaded file token").
 		Body(map[string]interface{}{
@@ -102,7 +125,7 @@ func executeRecordUploadAttachment(runtime *common.RuntimeContext) error {
 		return output.ErrValidation("file not accessible: %s: %v", filePath, err)
 	}
 	if fileInfo.Size() > baseAttachmentUploadMaxFileSize {
-		return output.ErrValidation("file %.1fMB exceeds 20MB limit", float64(fileInfo.Size())/1024/1024)
+		return output.ErrValidation("file %s exceeds 2GB limit", common.FormatSize(fileInfo.Size()))
 	}
 
 	fileName := strings.TrimSpace(runtime.Str("name"))
@@ -124,6 +147,9 @@ func executeRecordUploadAttachment(runtime *common.RuntimeContext) error {
 	}
 
 	fmt.Fprintf(runtime.IO().ErrOut, "Uploading attachment: %s -> record %s field %s\n", fileName, runtime.Str("record-id"), fieldName(field))
+	if fileInfo.Size() > common.MaxDriveMediaUploadSinglePartSize {
+		fmt.Fprintf(runtime.IO().ErrOut, "File exceeds 20MB, using multipart upload\n")
+	}
 
 	attachment, err := uploadAttachmentToBase(runtime, filePath, fileName, runtime.Str("base-token"), fileInfo.Size())
 	if err != nil {
@@ -151,6 +177,14 @@ func executeRecordUploadAttachment(runtime *common.RuntimeContext) error {
 	return nil
 }
 
+func baseAttachmentShouldUseMultipart(fio fileio.FileIO, filePath string) bool {
+	info, err := fio.Stat(filePath)
+	if err != nil {
+		return false
+	}
+	return info.Mode().IsRegular() && info.Size() > common.MaxDriveMediaUploadSinglePartSize
+}
+
 func fetchBaseField(runtime *common.RuntimeContext, baseToken, tableIDValue, fieldRef string) (map[string]interface{}, error) {
 	return baseV3Call(runtime, "GET", baseV3Path("bases", baseToken, "tables", tableIDValue, "fields", fieldRef), nil, nil)
 }
@@ -209,47 +243,30 @@ func normalizeAttachmentForPatch(attachment map[string]interface{}) map[string]i
 }
 
 func uploadAttachmentToBase(runtime *common.RuntimeContext, filePath, fileName, baseToken string, fileSize int64) (map[string]interface{}, error) {
-	f, err := runtime.FileIO().Open(filePath)
+	parentNode := baseToken
+	var (
+		fileToken string
+		err       error
+	)
+	if fileSize <= common.MaxDriveMediaUploadSinglePartSize {
+		fileToken, err = common.UploadDriveMediaAll(runtime, common.DriveMediaUploadAllConfig{
+			FilePath:   filePath,
+			FileName:   fileName,
+			FileSize:   fileSize,
+			ParentType: baseAttachmentParentType,
+			ParentNode: &parentNode,
+		})
+	} else {
+		fileToken, err = common.UploadDriveMediaMultipart(runtime, common.DriveMediaMultipartUploadConfig{
+			FilePath:   filePath,
+			FileName:   fileName,
+			FileSize:   fileSize,
+			ParentType: baseAttachmentParentType,
+			ParentNode: parentNode,
+		})
+	}
 	if err != nil {
-		return nil, output.ErrValidation("cannot open file: %v", err)
-	}
-	defer f.Close()
-
-	fd := larkcore.NewFormdata()
-	fd.AddField("file_name", fileName)
-	fd.AddField("parent_type", baseAttachmentParentType)
-	fd.AddField("parent_node", baseToken)
-	fd.AddField("size", fmt.Sprintf("%d", fileSize))
-	fd.AddFile("file", f)
-
-	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
-		HttpMethod: http.MethodPost,
-		ApiPath:    "/open-apis/drive/v1/medias/upload_all",
-		Body:       fd,
-	}, larkcore.WithFileUpload())
-	if err != nil {
-		var exitErr *output.ExitError
-		if errors.As(err, &exitErr) {
-			return nil, err
-		}
-		return nil, output.ErrNetwork("upload failed: %v", err)
-	}
-
-	var result map[string]interface{}
-	if err := json.Unmarshal(apiResp.RawBody, &result); err != nil {
-		return nil, output.Errorf(output.ExitAPI, "api_error", "upload failed: invalid response JSON: %v", err)
-	}
-
-	code, _ := util.ToFloat64(result["code"])
-	if code != 0 {
-		msg, _ := result["msg"].(string)
-		return nil, output.ErrAPI(int(code), fmt.Sprintf("upload failed: [%d] %s", int(code), msg), result["error"])
-	}
-
-	data, _ := result["data"].(map[string]interface{})
-	fileToken, _ := data["file_token"].(string)
-	if fileToken == "" {
-		return nil, output.Errorf(output.ExitAPI, "api_error", "upload failed: no file_token returned")
+		return nil, err
 	}
 
 	attachment := map[string]interface{}{

shortcuts/base/record_upsert.go

@@ -26,6 +26,9 @@ var BaseRecordUpsert = common.Shortcut{
 		`Example: --json '{"Name":"Alice"}'`,
 		"Agent hint: use the lark-base skill's record-upsert guide for usage and limits.",
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateRecordJSON(runtime)
+	},
 	DryRun: dryRunRecordUpsert,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeRecordUpsert(runtime)

shortcuts/base/view_ops.go

@@ -138,15 +138,15 @@ func wrapViewPropertyBody(raw interface{}, key string) interface{} {
 }
 
 func validateViewCreate(runtime *common.RuntimeContext) error {
-	return nil
+	pc := newParseCtx(runtime)
+	_, err := parseObjectList(pc, runtime.Str("json"), "json")
+	return err
 }
 
 func validateViewJSONObject(runtime *common.RuntimeContext) error {
-	return nil
-}
-
-func validateViewJSONValue(runtime *common.RuntimeContext) error {
-	return nil
+	pc := newParseCtx(runtime)
+	_, err := parseJSONObject(pc, runtime.Str("json"), "json")
+	return err
 }
 
 func executeViewList(runtime *common.RuntimeContext) error {

shortcuts/base/view_set_group.go

@@ -27,7 +27,7 @@ var BaseViewSetGroup = common.Shortcut{
 		"Agent hint: use the lark-base skill's view-set-group guide for usage and limits.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateViewJSONValue(runtime)
+		return validateViewJSONObject(runtime)
 	},
 	DryRun: dryRunViewSetGroup,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/view_set_sort.go

@@ -27,7 +27,7 @@ var BaseViewSetSort = common.Shortcut{
 		"Agent hint: use the lark-base skill's view-set-sort guide for usage and limits.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateViewJSONValue(runtime)
+		return validateViewJSONObject(runtime)
 	},
 	DryRun: dryRunViewSetSort,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/view_set_visible_fields.go

@@ -26,6 +26,9 @@ var BaseViewSetVisibleFields = common.Shortcut{
 		`Example: --json '{"visible_fields":["fldXXX"]}'`,
 		"Agent hint: use the lark-base skill's view-set-visible-fields guide for usage and limits.",
 	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateViewJSONObject(runtime)
+	},
 	DryRun: dryRunViewSetVisibleFields,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeViewSetVisibleFields(runtime)

shortcuts/drive/drive_task_result.go

@@ -5,27 +5,31 @@ package drive
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"strings"
 
+	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
 // DriveTaskResult exposes a unified read path for the async task types produced
-// by Drive import, export, and folder move flows.
+// by Drive import, export, folder move/delete, and wiki move flows.
 var DriveTaskResult = common.Shortcut{
 	Service:     "drive",
 	Command:     "+task_result",
-	Description: "Poll async task result for import, export, move, or delete operations",
+	Description: "Poll async task result for import, export, drive move/delete, or wiki move operations",
 	Risk:        "read",
-	Scopes:      []string{"drive:drive.metadata:readonly"},
-	AuthTypes:   []string{"user", "bot"},
+	// This shortcut multiplexes multiple backend APIs with different scope
+	// requirements, so scenario-specific prechecks are handled in Validate.
+	Scopes:    []string{},
+	AuthTypes: []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "ticket", Desc: "async task ticket (for import/export tasks)", Required: false},
-		{Name: "task-id", Desc: "async task ID (for move/delete folder tasks)", Required: false},
-		{Name: "scenario", Desc: "task scenario: import, export, or task_check", Required: true},
+		{Name: "task-id", Desc: "async task ID (for drive task_check or wiki_move tasks)", Required: false},
+		{Name: "scenario", Desc: "task scenario: import, export, task_check, or wiki_move", Required: true},
 		{Name: "file-token", Desc: "source document token used for export task status lookup", Required: false},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -34,9 +38,10 @@ var DriveTaskResult = common.Shortcut{
 			"import":     true,
 			"export":     true,
 			"task_check": true,
+			"wiki_move":  true,
 		}
 		if !validScenarios[scenario] {
-			return output.ErrValidation("unsupported scenario: %s. Supported scenarios: import, export, task_check", scenario)
+			return output.ErrValidation("unsupported scenario: %s. Supported scenarios: import, export, task_check, wiki_move", scenario)
 		}
 
 		// Validate required params based on scenario
@@ -48,9 +53,9 @@ var DriveTaskResult = common.Shortcut{
 			if err := validate.ResourceName(runtime.Str("ticket"), "--ticket"); err != nil {
 				return output.ErrValidation("%s", err)
 			}
-		case "task_check":
+		case "task_check", "wiki_move":
 			if runtime.Str("task-id") == "" {
-				return output.ErrValidation("--task-id is required for task_check scenario")
+				return output.ErrValidation("--task-id is required for %s scenario", scenario)
 			}
 			if err := validate.ResourceName(runtime.Str("task-id"), "--task-id"); err != nil {
 				return output.ErrValidation("%s", err)
@@ -67,7 +72,7 @@ var DriveTaskResult = common.Shortcut{
 			}
 		}
 
-		return nil
+		return validateDriveTaskResultScopes(ctx, runtime, scenario)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		scenario := strings.ToLower(runtime.Str("scenario"))
@@ -92,6 +97,11 @@ var DriveTaskResult = common.Shortcut{
 			dry.GET("/open-apis/drive/v1/files/task_check").
 				Desc("[1] Query move/delete folder task status").
 				Params(driveTaskCheckParams(taskID))
+		case "wiki_move":
+			dry.GET("/open-apis/wiki/v2/tasks/:task_id").
+				Desc("[1] Query wiki move task result").
+				Set("task_id", taskID).
+				Params(map[string]interface{}{"task_type": "move"})
 		}
 
 		return dry
@@ -116,6 +126,8 @@ var DriveTaskResult = common.Shortcut{
 			result, err = queryExportTask(runtime, ticket, fileToken)
 		case "task_check":
 			result, err = queryTaskCheck(runtime, taskID)
+		case "wiki_move":
+			result, err = queryWikiMoveTask(runtime, taskID)
 		}
 
 		if err != nil {
@@ -196,3 +208,263 @@ func queryTaskCheck(runtime *common.RuntimeContext, taskID string) (map[string]i
 		"failed":   status.Failed(),
 	}, nil
 }
+
+func validateDriveTaskResultScopes(ctx context.Context, runtime *common.RuntimeContext, scenario string) error {
+	result, err := runtime.Factory.Credential.ResolveToken(ctx, credential.NewTokenSpec(runtime.As(), runtime.Config.AppID))
+	if err != nil {
+		// Propagate cancellation/timeout so callers stop instead of falling through
+		// to the API call. Other token errors are non-fatal here: the API call will
+		// surface a clearer permission error.
+		if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+			return err
+		}
+		return nil
+	}
+	if result == nil || result.Scopes == "" {
+		return nil
+	}
+
+	var required []string
+	switch scenario {
+	case "import", "export", "task_check":
+		required = []string{"drive:drive.metadata:readonly"}
+	case "wiki_move":
+		required = []string{"wiki:space:read"}
+	}
+
+	return requireDriveScopes(result.Scopes, required)
+}
+
+func requireDriveScopes(storedScopes string, required []string) error {
+	if len(required) == 0 {
+		return nil
+	}
+
+	missing := missingDriveScopes(storedScopes, required)
+	if len(missing) == 0 {
+		return nil
+	}
+
+	return output.ErrWithHint(output.ExitAuth, "missing_scope",
+		fmt.Sprintf("missing required scope(s): %s", strings.Join(missing, ", ")),
+		fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(missing, " ")))
+}
+
+func missingDriveScopes(storedScopes string, required []string) []string {
+	granted := make(map[string]bool)
+	for _, scope := range strings.Fields(storedScopes) {
+		granted[scope] = true
+	}
+
+	missing := make([]string, 0, len(required))
+	for _, scope := range required {
+		if !granted[scope] {
+			missing = append(missing, scope)
+		}
+	}
+	return missing
+}
+
+type wikiMoveTaskResultStatus struct {
+	Node      map[string]interface{}
+	Status    int
+	StatusMsg string
+}
+
+type wikiMoveTaskQueryStatus struct {
+	TaskID      string
+	MoveResults []wikiMoveTaskResultStatus
+}
+
+func (s wikiMoveTaskQueryStatus) Ready() bool {
+	if len(s.MoveResults) == 0 {
+		return false
+	}
+	for _, result := range s.MoveResults {
+		if result.Status != 0 {
+			return false
+		}
+	}
+	return true
+}
+
+func (s wikiMoveTaskQueryStatus) Failed() bool {
+	for _, result := range s.MoveResults {
+		if result.Status < 0 {
+			return true
+		}
+	}
+	return false
+}
+
+func (s wikiMoveTaskQueryStatus) FirstResult() *wikiMoveTaskResultStatus {
+	if len(s.MoveResults) == 0 {
+		return nil
+	}
+	return &s.MoveResults[0]
+}
+
+// primaryResult picks the most informative move_result for top-level status
+// surfacing: prefer a failing entry so multi-doc tasks don't mask failures
+// behind an earlier success, then a still-processing entry, and finally fall
+// back to the first entry.
+func (s wikiMoveTaskQueryStatus) primaryResult() *wikiMoveTaskResultStatus {
+	for i := range s.MoveResults {
+		if s.MoveResults[i].Status < 0 {
+			return &s.MoveResults[i]
+		}
+	}
+	for i := range s.MoveResults {
+		if s.MoveResults[i].Status > 0 {
+			return &s.MoveResults[i]
+		}
+	}
+	return s.FirstResult()
+}
+
+func (s wikiMoveTaskQueryStatus) PrimaryStatusCode() int {
+	if r := s.primaryResult(); r != nil {
+		return r.Status
+	}
+	return 1
+}
+
+func (s wikiMoveTaskQueryStatus) PrimaryStatusLabel() string {
+	if r := s.primaryResult(); r != nil {
+		if msg := strings.TrimSpace(r.StatusMsg); msg != "" {
+			return msg
+		}
+	}
+	switch {
+	case s.Ready():
+		return "success"
+	case s.Failed():
+		return "failure"
+	default:
+		return "processing"
+	}
+}
+
+func queryWikiMoveTask(runtime *common.RuntimeContext, taskID string) (map[string]interface{}, error) {
+	status, err := getWikiMoveTaskStatus(runtime, taskID)
+	if err != nil {
+		return nil, err
+	}
+
+	out := map[string]interface{}{
+		"scenario":   "wiki_move",
+		"task_id":    status.TaskID,
+		"ready":      status.Ready(),
+		"failed":     status.Failed(),
+		"status":     status.PrimaryStatusCode(),
+		"status_msg": status.PrimaryStatusLabel(),
+	}
+
+	moveResults := make([]map[string]interface{}, 0, len(status.MoveResults))
+	for _, result := range status.MoveResults {
+		item := map[string]interface{}{
+			"status":     result.Status,
+			"status_msg": result.StatusMsg,
+		}
+		if result.Node != nil {
+			item["node"] = result.Node
+		}
+		moveResults = append(moveResults, item)
+	}
+	if len(moveResults) > 0 {
+		out["move_results"] = moveResults
+	}
+
+	if first := status.FirstResult(); first != nil {
+		// Mirror the first moved node at the top level so follow-up commands can
+		// reuse a stable field set without digging into move_results[0].node.
+		if first.Node != nil {
+			out["node"] = first.Node
+			appendWikiMoveNodeFields(out, first.Node)
+			if token := common.GetString(first.Node, "node_token"); token != "" {
+				out["wiki_token"] = token
+			}
+		}
+	}
+
+	return out, nil
+}
+
+func getWikiMoveTaskStatus(runtime *common.RuntimeContext, taskID string) (wikiMoveTaskQueryStatus, error) {
+	if err := validate.ResourceName(taskID, "--task-id"); err != nil {
+		return wikiMoveTaskQueryStatus{}, output.ErrValidation("%s", err)
+	}
+
+	data, err := runtime.CallAPI(
+		"GET",
+		fmt.Sprintf("/open-apis/wiki/v2/tasks/%s", validate.EncodePathSegment(taskID)),
+		map[string]interface{}{"task_type": "move"},
+		nil,
+	)
+	if err != nil {
+		return wikiMoveTaskQueryStatus{}, err
+	}
+
+	return parseWikiMoveTaskQueryStatus(taskID, common.GetMap(data, "task"))
+}
+
+func parseWikiMoveTaskQueryStatus(taskID string, task map[string]interface{}) (wikiMoveTaskQueryStatus, error) {
+	if task == nil {
+		return wikiMoveTaskQueryStatus{}, output.Errorf(output.ExitAPI, "api_error", "wiki task response missing task")
+	}
+
+	status := wikiMoveTaskQueryStatus{
+		TaskID: common.GetString(task, "task_id"),
+	}
+	if status.TaskID == "" {
+		status.TaskID = taskID
+	}
+
+	for _, item := range common.GetSlice(task, "move_result") {
+		resultMap, ok := item.(map[string]interface{})
+		if !ok {
+			continue
+		}
+
+		status.MoveResults = append(status.MoveResults, wikiMoveTaskResultStatus{
+			Node:      parseWikiMoveTaskNode(common.GetMap(resultMap, "node")),
+			Status:    int(common.GetFloat(resultMap, "status")),
+			StatusMsg: common.GetString(resultMap, "status_msg"),
+		})
+	}
+
+	return status, nil
+}
+
+func parseWikiMoveTaskNode(node map[string]interface{}) map[string]interface{} {
+	if node == nil {
+		return nil
+	}
+
+	return map[string]interface{}{
+		"space_id":          common.GetString(node, "space_id"),
+		"node_token":        common.GetString(node, "node_token"),
+		"obj_token":         common.GetString(node, "obj_token"),
+		"obj_type":          common.GetString(node, "obj_type"),
+		"parent_node_token": common.GetString(node, "parent_node_token"),
+		"node_type":         common.GetString(node, "node_type"),
+		"origin_node_token": common.GetString(node, "origin_node_token"),
+		"title":             common.GetString(node, "title"),
+		"has_child":         common.GetBool(node, "has_child"),
+	}
+}
+
+func appendWikiMoveNodeFields(out, node map[string]interface{}) {
+	if out == nil || node == nil {
+		return
+	}
+	out["space_id"] = common.GetString(node, "space_id")
+	out["node_token"] = common.GetString(node, "node_token")
+	out["obj_token"] = common.GetString(node, "obj_token")
+	out["obj_type"] = common.GetString(node, "obj_type")
+	out["parent_node_token"] = common.GetString(node, "parent_node_token")
+	out["node_type"] = common.GetString(node, "node_type")
+	out["origin_node_token"] = common.GetString(node, "origin_node_token")
+	out["title"] = common.GetString(node, "title")
+	out["has_child"] = common.GetBool(node, "has_child")
+}

shortcuts/drive/drive_task_result_test.go

@@ -7,12 +7,15 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -54,6 +57,13 @@ func TestDriveTaskResultValidateErrorsByScenario(t *testing.T) {
 			},
 			wantErr: "--task-id is required",
 		},
+		{
+			name: "wiki move missing task id",
+			flags: map[string]string{
+				"scenario": "wiki_move",
+			},
+			wantErr: "--task-id is required",
+		},
 	}
 
 	for _, tt := range tests {
@@ -277,3 +287,259 @@ func TestDriveTaskResultTaskCheckTreatsFailAsFailed(t *testing.T) {
 		t.Fatalf("stdout missing ready=false: %s", stdout.String())
 	}
 }
+
+type mockDriveTaskResultTokenResolver struct {
+	token  string
+	scopes string
+	err    error
+}
+
+func (m *mockDriveTaskResultTokenResolver) ResolveToken(ctx context.Context, req credential.TokenSpec) (*credential.TokenResult, error) {
+	if m.err != nil {
+		return nil, m.err
+	}
+	token := m.token
+	if token == "" {
+		token = "test-token"
+	}
+	return &credential.TokenResult{Token: token, Scopes: m.scopes}, nil
+}
+
+func newDriveTaskResultRuntimeWithScopes(t *testing.T, as core.Identity, scopes string) *common.RuntimeContext {
+	t.Helper()
+
+	cfg := driveTestConfig()
+	factory, _, _, _ := cmdutil.TestFactory(t, cfg)
+	factory.Credential = credential.NewCredentialProvider(nil, nil, &mockDriveTaskResultTokenResolver{scopes: scopes}, nil)
+
+	runtime := common.TestNewRuntimeContextWithIdentity(&cobra.Command{Use: "drive +task_result"}, cfg, as)
+	runtime.Factory = factory
+	return runtime
+}
+
+func TestDriveTaskResultDryRunWikiMoveIncludesTaskTypeParam(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +task_result"}
+	cmd.Flags().String("scenario", "", "")
+	cmd.Flags().String("ticket", "", "")
+	cmd.Flags().String("task-id", "", "")
+	cmd.Flags().String("file-token", "", "")
+	if err := cmd.Flags().Set("scenario", "wiki_move"); err != nil {
+		t.Fatalf("set --scenario: %v", err)
+	}
+	if err := cmd.Flags().Set("task-id", "task_123"); err != nil {
+		t.Fatalf("set --task-id: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+	dry := DriveTaskResult.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 {
+			Params map[string]interface{} `json:"params"`
+		} `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].Params["task_type"] != "move" {
+		t.Fatalf("wiki move params = %#v, want task_type=move", got.API[0].Params)
+	}
+}
+
+func TestDriveTaskResultWikiMoveIncludesFlattenedNodeFields(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/tasks/task_123",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"task": map[string]interface{}{
+					"task_id": "task_123",
+					"move_result": []interface{}{
+						map[string]interface{}{
+							"status":     0,
+							"status_msg": "success",
+							"node": map[string]interface{}{
+								"space_id":   "space_dst",
+								"node_token": "wik_done",
+								"obj_token":  "sheet_token",
+								"obj_type":   "sheet",
+								"node_type":  "origin",
+								"title":      "Roadmap",
+							},
+						},
+					},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveTaskResult, []string{
+		"+task_result",
+		"--scenario", "wiki_move",
+		"--task-id", "task_123",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if data["scenario"] != "wiki_move" || data["task_id"] != "task_123" {
+		t.Fatalf("unexpected wiki_move envelope: %#v", data)
+	}
+	if data["ready"] != true || data["failed"] != false || data["wiki_token"] != "wik_done" {
+		t.Fatalf("unexpected readiness fields: %#v", data)
+	}
+	if data["title"] != "Roadmap" || data["obj_type"] != "sheet" || data["space_id"] != "space_dst" {
+		t.Fatalf("flattened node fields missing: %#v", data)
+	}
+	moveResults, ok := data["move_results"].([]interface{})
+	if !ok || len(moveResults) != 1 {
+		t.Fatalf("move_results = %#v, want one result", data["move_results"])
+	}
+}
+
+func TestValidateDriveTaskResultScopesWikiMoveRequiresWikiScope(t *testing.T) {
+	t.Parallel()
+
+	runtime := newDriveTaskResultRuntimeWithScopes(t, core.AsUser, "drive:drive.metadata:readonly")
+	err := validateDriveTaskResultScopes(context.Background(), runtime, "wiki_move")
+	if err == nil || !strings.Contains(err.Error(), "missing required scope(s): wiki:space:read") {
+		t.Fatalf("expected missing wiki scope error, got %v", err)
+	}
+}
+
+func TestValidateDriveTaskResultScopesWikiMoveAcceptsWikiScope(t *testing.T) {
+	t.Parallel()
+
+	runtime := newDriveTaskResultRuntimeWithScopes(t, core.AsUser, "wiki:space:read")
+	err := validateDriveTaskResultScopes(context.Background(), runtime, "wiki_move")
+	if err != nil {
+		t.Fatalf("validateDriveTaskResultScopes() error = %v", err)
+	}
+}
+
+func TestValidateDriveTaskResultScopesDriveScenariosRequireDriveScope(t *testing.T) {
+	t.Parallel()
+
+	runtime := newDriveTaskResultRuntimeWithScopes(t, core.AsUser, "wiki:space:read")
+	err := validateDriveTaskResultScopes(context.Background(), runtime, "import")
+	if err == nil || !strings.Contains(err.Error(), "missing required scope(s): drive:drive.metadata:readonly") {
+		t.Fatalf("expected missing drive scope error, got %v", err)
+	}
+}
+
+func TestParseWikiMoveTaskQueryStatusFallbackTaskIDAndNode(t *testing.T) {
+	t.Parallel()
+
+	status, err := parseWikiMoveTaskQueryStatus("task_fallback", map[string]interface{}{
+		"move_result": []interface{}{
+			map[string]interface{}{
+				"status":     0,
+				"status_msg": "success",
+				"node": map[string]interface{}{
+					"space_id":   "space_dst",
+					"node_token": "wik_done",
+					"obj_token":  "sheet_token",
+					"obj_type":   "sheet",
+					"title":      "Roadmap",
+				},
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("parseWikiMoveTaskQueryStatus() error = %v", err)
+	}
+	if status.TaskID != "task_fallback" || !status.Ready() || status.PrimaryStatusLabel() != "success" {
+		t.Fatalf("unexpected parsed status: %+v", status)
+	}
+	if first := status.FirstResult(); first == nil || first.Node == nil || first.Node["node_token"] != "wik_done" {
+		t.Fatalf("parsed node = %+v", first)
+	}
+}
+
+func TestParseWikiMoveTaskQueryStatusRejectsMissingTask(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiMoveTaskQueryStatus("task_123", nil)
+	if err == nil || !strings.Contains(err.Error(), "missing task") {
+		t.Fatalf("expected missing task error, got %v", err)
+	}
+}
+
+func TestWikiMoveTaskQueryStatusPrimarySurfacesFailureOverEarlierSuccess(t *testing.T) {
+	t.Parallel()
+
+	status := wikiMoveTaskQueryStatus{
+		MoveResults: []wikiMoveTaskResultStatus{
+			{Status: 0, StatusMsg: "success"},
+			{Status: -3, StatusMsg: "permission denied"},
+			{Status: 1, StatusMsg: "processing"},
+		},
+	}
+	if got := status.PrimaryStatusCode(); got != -3 {
+		t.Fatalf("PrimaryStatusCode = %d, want -3", got)
+	}
+	if got := status.PrimaryStatusLabel(); got != "permission denied" {
+		t.Fatalf("PrimaryStatusLabel = %q, want permission denied", got)
+	}
+	// FirstResult must keep its literal "first entry" semantics for callers
+	// that flatten node fields from the first move_result.
+	if first := status.FirstResult(); first == nil || first.StatusMsg != "success" {
+		t.Fatalf("FirstResult = %+v, want first success entry", first)
+	}
+}
+
+func TestWikiMoveTaskQueryStatusPrimaryPrefersProcessingOverFirstSuccess(t *testing.T) {
+	t.Parallel()
+
+	status := wikiMoveTaskQueryStatus{
+		MoveResults: []wikiMoveTaskResultStatus{
+			{Status: 0, StatusMsg: "success"},
+			{Status: 1, StatusMsg: "processing"},
+		},
+	}
+	if got := status.PrimaryStatusCode(); got != 1 {
+		t.Fatalf("PrimaryStatusCode = %d, want 1", got)
+	}
+	if got := status.PrimaryStatusLabel(); got != "processing" {
+		t.Fatalf("PrimaryStatusLabel = %q, want processing", got)
+	}
+}
+
+type cancelingTokenResolver struct{}
+
+func (cancelingTokenResolver) ResolveToken(ctx context.Context, req credential.TokenSpec) (*credential.TokenResult, error) {
+	return nil, context.Canceled
+}
+
+func TestValidateDriveTaskResultScopesPropagatesContextCancellation(t *testing.T) {
+	t.Parallel()
+
+	cfg := driveTestConfig()
+	factory, _, _, _ := cmdutil.TestFactory(t, cfg)
+	factory.Credential = credential.NewCredentialProvider(nil, nil, cancelingTokenResolver{}, nil)
+
+	runtime := common.TestNewRuntimeContextWithIdentity(&cobra.Command{Use: "drive +task_result"}, cfg, core.AsUser)
+	runtime.Factory = factory
+
+	err := validateDriveTaskResultScopes(context.Background(), runtime, "wiki_move")
+	if err == nil || !errors.Is(err, context.Canceled) {
+		t.Fatalf("expected context.Canceled, got %v", err)
+	}
+}

shortcuts/event/subscribe.go

@@ -74,6 +74,7 @@ var commonEventTypes = []string{
 	"approval.approval.updated",
 	"application.application.visibility.added_v6",
 	"task.task.update_tenant_v1",
+	"task.task.update_user_access_v2",
 	"task.task.comment_updated_v1",
 	"drive.notice.comment_add_v1",
 }

shortcuts/im/builders_test.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
@@ -395,6 +396,28 @@ func TestShortcutValidateBranches(t *testing.T) {
 		}
 	})
 
+	t.Run("ImChatMessageList rejects both targets", func(t *testing.T) {
+		runtime := newTestRuntimeContext(t, map[string]string{
+			"chat-id": "oc_abc",
+			"user-id": "ou_123",
+		}, nil)
+		err := ImChatMessageList.Validate(context.Background(), runtime)
+		if err == nil || !strings.Contains(err.Error(), "mutually exclusive") {
+			t.Fatalf("ImChatMessageList.Validate() error = %v, want mutually exclusive", err)
+		}
+	})
+
+	t.Run("ImChatMessageList rejects user target for bot identity", func(t *testing.T) {
+		runtime := newTestRuntimeContext(t, map[string]string{
+			"user-id": "ou_123",
+		}, nil)
+		setRuntimeField(t, runtime, "resolvedAs", core.AsBot)
+		err := ImChatMessageList.Validate(context.Background(), runtime)
+		if err == nil || !strings.Contains(err.Error(), "requires user identity") {
+			t.Fatalf("ImChatMessageList.Validate() error = %v, want requires user identity", err)
+		}
+	})
+
 	t.Run("ImMessagesMGet empty ids", func(t *testing.T) {
 		runtime := newTestRuntimeContext(t, map[string]string{
 			"message-ids": " , ",

shortcuts/im/coverage_additional_test.go

@@ -273,7 +273,7 @@ func TestResolveChatIDForMessagesList(t *testing.T) {
 	})
 
 	t.Run("user resolved through p2p lookup", func(t *testing.T) {
-		runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		runtime := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
 			switch {
 			case strings.Contains(req.URL.Path, "/open-apis/im/v1/chat_p2p/batch_query"):
 				return shortcutJSONResponse(200, map[string]interface{}{
@@ -303,6 +303,23 @@ func TestResolveChatIDForMessagesList(t *testing.T) {
 			t.Fatalf("resolveChatIDForMessagesList() = %q, want %q", got, "oc_resolved")
 		}
 	})
+
+	t.Run("user target rejected for bot identity", func(t *testing.T) {
+		runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+			return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+		}))
+		cmd := &cobra.Command{Use: "test"}
+		cmd.Flags().String("user-id", "", "")
+		if err := cmd.Flags().Set("user-id", "ou_123"); err != nil {
+			t.Fatalf("Flags().Set() error = %v", err)
+		}
+		runtime.Cmd = cmd
+
+		_, err := resolveChatIDForMessagesList(runtime, false)
+		if err == nil || !strings.Contains(err.Error(), "requires user identity") {
+			t.Fatalf("resolveChatIDForMessagesList() error = %v, want requires user identity", err)
+		}
+	})
 }
 
 func TestBuildMessagesSearchRequest(t *testing.T) {

shortcuts/im/helpers.go

@@ -377,6 +377,9 @@ func mediaFallbackOrError(originalValue, mediaType string, uploadErr error) (str
 
 // resolveP2PChatID resolves user open_id to P2P chat_id.
 func resolveP2PChatID(runtime *common.RuntimeContext, openID string) (string, error) {
+	if runtime.IsBot() {
+		return "", output.Errorf(output.ExitValidation, "validation", "--user-id requires user identity (--as user); use --chat-id when calling with bot identity")
+	}
 	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
 		HttpMethod: http.MethodPost,
 		ApiPath:    "/open-apis/im/v1/chat_p2p/batch_query",

shortcuts/im/helpers_network_test.go

@@ -6,6 +6,7 @@ package im
 import (
 	"bytes"
 	"context"
+	"crypto/md5"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -13,6 +14,7 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
+	"strconv"
 	"strings"
 	"testing"
 	"unsafe"
@@ -107,12 +109,17 @@ func newBotShortcutRuntime(t *testing.T, rt http.RoundTripper) *common.RuntimeCo
 	return runtime
 }
 
+func newUserShortcutRuntime(t *testing.T, rt http.RoundTripper) *common.RuntimeContext {
+	t.Helper()
+	runtime := newBotShortcutRuntime(t, rt)
+	setRuntimeField(t, runtime, "resolvedAs", core.AsUser)
+	return runtime
+}
+
 func TestResolveP2PChatID(t *testing.T) {
-	var gotAuth string
-	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+	runtime := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
 		switch {
 		case strings.Contains(req.URL.Path, "/open-apis/im/v1/chat_p2p/batch_query"):
-			gotAuth = req.Header.Get("Authorization")
 			return shortcutJSONResponse(200, map[string]interface{}{
 				"code": 0,
 				"data": map[string]interface{}{
@@ -133,13 +140,10 @@ func TestResolveP2PChatID(t *testing.T) {
 	if got != "oc_123" {
 		t.Fatalf("resolveP2PChatID() = %q, want %q", got, "oc_123")
 	}
-	if gotAuth != "Bearer tenant-token" {
-		t.Fatalf("Authorization header = %q, want %q", gotAuth, "Bearer tenant-token")
-	}
 }
 
 func TestResolveP2PChatIDNotFound(t *testing.T) {
-	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+	runtime := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
 		switch {
 		case strings.Contains(req.URL.Path, "/open-apis/im/v1/chat_p2p/batch_query"):
 			return shortcutJSONResponse(200, map[string]interface{}{
@@ -159,6 +163,17 @@ func TestResolveP2PChatIDNotFound(t *testing.T) {
 	}
 }
 
+func TestResolveP2PChatIDRejectsBot(t *testing.T) {
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+	}))
+
+	_, err := resolveP2PChatID(runtime, "ou_123")
+	if err == nil || !strings.Contains(err.Error(), "requires user identity") {
+		t.Fatalf("resolveP2PChatID() error = %v, want requires user identity", err)
+	}
+}
+
 func TestResolveThreadID(t *testing.T) {
 	t.Run("thread id passthrough", func(t *testing.T) {
 		got, err := resolveThreadID(newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
@@ -273,6 +288,46 @@ func TestDownloadIMResourceToPathSuccess(t *testing.T) {
 	if gotHeaders.Get(cmdutil.HeaderExecutionId) != "exec-123" {
 		t.Fatalf("%s = %q, want %q", cmdutil.HeaderExecutionId, gotHeaders.Get(cmdutil.HeaderExecutionId), "exec-123")
 	}
+	if gotHeaders.Get("Range") != fmt.Sprintf("bytes=0-%d", probeChunkSize-1) {
+		t.Fatalf("Range header = %q, want %q", gotHeaders.Get("Range"), fmt.Sprintf("bytes=0-%d", probeChunkSize-1))
+	}
+}
+
+func TestDownloadIMResourceToPathImageUsesSingleRequestWithoutRange(t *testing.T) {
+	var gotHeaders http.Header
+	payload := []byte("image download")
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		switch {
+		case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/om_img/resources/img_123"):
+			gotHeaders = req.Header.Clone()
+			return shortcutRawResponse(200, payload, http.Header{"Content-Type": []string{"image/png"}}), nil
+		default:
+			return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+		}
+	}))
+
+	cmdutil.TestChdir(t, t.TempDir())
+
+	gotPath, size, err := downloadIMResourceToPath(context.Background(), runtime, "om_img", "img_123", "image", "image")
+	if err != nil {
+		t.Fatalf("downloadIMResourceToPath() error = %v", err)
+	}
+	if size != int64(len(payload)) {
+		t.Fatalf("downloadIMResourceToPath() size = %d, want %d", size, len(payload))
+	}
+	if gotHeaders.Get("Range") != "" {
+		t.Fatalf("Range header = %q, want empty", gotHeaders.Get("Range"))
+	}
+	if !strings.HasSuffix(gotPath, "image.png") {
+		t.Fatalf("saved path = %q, want suffix %q", gotPath, "image.png")
+	}
+	data, err := os.ReadFile("image.png")
+	if err != nil {
+		t.Fatalf("ReadFile() error = %v", err)
+	}
+	if string(data) != string(payload) {
+		t.Fatalf("downloaded payload = %q, want %q", string(data), string(payload))
+	}
 }
 
 func TestDownloadIMResourceToPathHTTPErrorBody(t *testing.T) {
@@ -293,6 +348,348 @@ func TestDownloadIMResourceToPathHTTPErrorBody(t *testing.T) {
 	}
 }
 
+func TestDownloadIMResourceToPathRetriesNetworkError(t *testing.T) {
+	attempts := 0
+	payload := []byte("retry success")
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		switch {
+		case strings.Contains(req.URL.Path, "tenant_access_token"):
+			return shortcutJSONResponse(200, map[string]interface{}{
+				"code":                0,
+				"tenant_access_token": "tenant-token",
+				"expire":              7200,
+			}), nil
+		case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/om_retry/resources/file_retry"):
+			attempts++
+			if attempts < 3 {
+				return nil, fmt.Errorf("temporary network failure")
+			}
+			return shortcutRawResponse(200, payload, http.Header{"Content-Type": []string{"application/octet-stream"}}), nil
+		default:
+			return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+		}
+	}))
+
+	cmdutil.TestChdir(t, t.TempDir())
+	target := "out.bin"
+	_, size, err := downloadIMResourceToPath(context.Background(), runtime, "om_retry", "file_retry", "file", target)
+	if err != nil {
+		t.Fatalf("downloadIMResourceToPath() error = %v", err)
+	}
+	if attempts != 3 {
+		t.Fatalf("download attempts = %d, want 3", attempts)
+	}
+	if size != int64(len(payload)) {
+		t.Fatalf("downloadIMResourceToPath() size = %d, want %d", size, len(payload))
+	}
+}
+
+func TestDownloadIMResourceToPathRetrySecondAttemptSuccess(t *testing.T) {
+	attempts := 0
+	payload := []byte("second retry success")
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		switch {
+		case strings.Contains(req.URL.Path, "tenant_access_token"):
+			return shortcutJSONResponse(200, map[string]interface{}{
+				"code":                0,
+				"tenant_access_token": "tenant-token",
+				"expire":              7200,
+			}), nil
+		case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/om_retry2/resources/file_retry2"):
+			attempts++
+			if attempts < 2 {
+				return nil, fmt.Errorf("temporary network failure")
+			}
+			return shortcutRawResponse(200, payload, http.Header{"Content-Type": []string{"application/octet-stream"}}), nil
+		default:
+			return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+		}
+	}))
+
+	cmdutil.TestChdir(t, t.TempDir())
+	target := "out.bin"
+	_, size, err := downloadIMResourceToPath(context.Background(), runtime, "om_retry2", "file_retry2", "file", target)
+	if err != nil {
+		t.Fatalf("downloadIMResourceToPath() error = %v", err)
+	}
+	if attempts != 2 {
+		t.Fatalf("download attempts = %d, want 2", attempts)
+	}
+	if size != int64(len(payload)) {
+		t.Fatalf("downloadIMResourceToPath() size = %d, want %d", size, len(payload))
+	}
+}
+
+func TestDownloadIMResourceToPathRetryContextCanceled(t *testing.T) {
+	attempts := 0
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		switch {
+		case strings.Contains(req.URL.Path, "tenant_access_token"):
+			return shortcutJSONResponse(200, map[string]interface{}{
+				"code":                0,
+				"tenant_access_token": "tenant-token",
+				"expire":              7200,
+			}), nil
+		case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/om_cancel/resources/file_cancel"):
+			attempts++
+			return nil, fmt.Errorf("temporary network failure")
+		default:
+			return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+		}
+	}))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	// Cancel context immediately to trigger context error on first retry
+	cancel()
+
+	cmdutil.TestChdir(t, t.TempDir())
+	target := "out.bin"
+	_, _, err := downloadIMResourceToPath(ctx, runtime, "om_cancel", "file_cancel", "file", target)
+	if err != context.Canceled {
+		t.Fatalf("downloadIMResourceToPath() error = %v, want context.Canceled", err)
+	}
+	// First attempt is made, then retry checks ctx.Err() and returns
+	if attempts != 1 {
+		t.Fatalf("download attempts = %d, want 1", attempts)
+	}
+}
+
+func TestDownloadIMResourceToPathRangeDownload(t *testing.T) {
+	cases := []struct {
+		name       string
+		payloadLen int64
+		wantRanges []string
+	}{
+		{
+			name:       "single small chunk",
+			payloadLen: 16,
+			wantRanges: []string{"bytes=0-131071"},
+		},
+		{
+			name:       "exact probe chunk",
+			payloadLen: probeChunkSize,
+			wantRanges: []string{"bytes=0-131071"},
+		},
+		{
+			name:       "multiple chunks with tail",
+			payloadLen: probeChunkSize + normalChunkSize + 1234,
+			wantRanges: []string{
+				"bytes=0-131071",
+				fmt.Sprintf("bytes=%d-%d", probeChunkSize, probeChunkSize+normalChunkSize-1),
+				fmt.Sprintf("bytes=%d-%d", probeChunkSize+normalChunkSize, probeChunkSize+normalChunkSize+1233),
+			},
+		},
+		{
+			name:       "multiple chunks exact 8mb tail",
+			payloadLen: probeChunkSize + 2*normalChunkSize,
+			wantRanges: []string{
+				"bytes=0-131071",
+				fmt.Sprintf("bytes=%d-%d", probeChunkSize, probeChunkSize+normalChunkSize-1),
+				fmt.Sprintf("bytes=%d-%d", probeChunkSize+normalChunkSize, probeChunkSize+2*normalChunkSize-1),
+			},
+		},
+	}
+
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			payload := bytes.Repeat([]byte("range-download-"), int(tt.payloadLen/15)+1)
+			payload = payload[:tt.payloadLen]
+
+			var gotRanges []string
+			runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+				switch {
+				case strings.Contains(req.URL.Path, "tenant_access_token"):
+					return shortcutJSONResponse(200, map[string]interface{}{
+						"code":                0,
+						"tenant_access_token": "tenant-token",
+						"expire":              7200,
+					}), nil
+				case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/om_range/resources/file_range"):
+					rangeHeader := req.Header.Get("Range")
+					gotRanges = append(gotRanges, rangeHeader)
+					if req.Header.Get("Authorization") != "Bearer tenant-token" {
+						return nil, fmt.Errorf("missing authorization header")
+					}
+					start, end, err := parseRangeHeader(rangeHeader, int64(len(payload)))
+					if err != nil {
+						return nil, err
+					}
+					return shortcutRawResponse(http.StatusPartialContent, payload[start:end+1], http.Header{
+						"Content-Type":  []string{"application/octet-stream"},
+						"Content-Range": []string{fmt.Sprintf("bytes %d-%d/%d", start, end, len(payload))},
+					}), nil
+				default:
+					return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+				}
+			}))
+
+			cmdutil.TestChdir(t, t.TempDir())
+			target := filepath.Join("nested", "resource.bin")
+			_, size, err := downloadIMResourceToPath(context.Background(), runtime, "om_range", "file_range", "file", target)
+			if err != nil {
+				t.Fatalf("downloadIMResourceToPath() error = %v", err)
+			}
+			if size != int64(len(payload)) {
+				t.Fatalf("downloadIMResourceToPath() size = %d, want %d", size, len(payload))
+			}
+			if !reflect.DeepEqual(gotRanges, tt.wantRanges) {
+				t.Fatalf("Range requests = %#v, want %#v", gotRanges, tt.wantRanges)
+			}
+
+			got, err := os.ReadFile(target)
+			if err != nil {
+				t.Fatalf("ReadFile() error = %v", err)
+			}
+			if md5.Sum(got) != md5.Sum(payload) {
+				t.Fatalf("downloaded payload MD5 = %x, want %x", md5.Sum(got), md5.Sum(payload))
+			}
+		})
+	}
+}
+
+func TestDownloadIMResourceToPathInvalidContentRange(t *testing.T) {
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		switch {
+		case strings.Contains(req.URL.Path, "tenant_access_token"):
+			return shortcutJSONResponse(200, map[string]interface{}{
+				"code":                0,
+				"tenant_access_token": "tenant-token",
+				"expire":              7200,
+			}), nil
+		case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/om_bad/resources/file_bad"):
+			return shortcutRawResponse(http.StatusPartialContent, []byte("bad"), http.Header{
+				"Content-Type":  []string{"application/octet-stream"},
+				"Content-Range": []string{"bytes 0-2/not-a-number"},
+			}), nil
+		default:
+			return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+		}
+	}))
+
+	cmdutil.TestChdir(t, t.TempDir())
+	_, _, err := downloadIMResourceToPath(context.Background(), runtime, "om_bad", "file_bad", "file", "out.bin")
+	if err == nil || !strings.Contains(err.Error(), "invalid Content-Range header") {
+		t.Fatalf("downloadIMResourceToPath() error = %v", err)
+	}
+}
+
+func TestDownloadIMResourceToPathRangeChunkFailureCleansOutput(t *testing.T) {
+	payload := bytes.Repeat([]byte("range-download-"), int((probeChunkSize+1024)/15)+1)
+	payload = payload[:probeChunkSize+1024]
+
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		switch {
+		case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/om_miderr/resources/file_miderr"):
+			rangeHeader := req.Header.Get("Range")
+			if rangeHeader == fmt.Sprintf("bytes=0-%d", probeChunkSize-1) {
+				return shortcutRawResponse(http.StatusPartialContent, payload[:probeChunkSize], http.Header{
+					"Content-Type":  []string{"application/octet-stream"},
+					"Content-Range": []string{fmt.Sprintf("bytes 0-%d/%d", probeChunkSize-1, len(payload))},
+				}), nil
+			}
+			return shortcutRawResponse(http.StatusInternalServerError, []byte("chunk failed"), http.Header{"Content-Type": []string{"text/plain"}}), nil
+		default:
+			return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+		}
+	}))
+
+	cmdutil.TestChdir(t, t.TempDir())
+
+	target := "out.bin"
+	_, _, err := downloadIMResourceToPath(context.Background(), runtime, "om_miderr", "file_miderr", "file", target)
+	if err == nil || !strings.Contains(err.Error(), "HTTP 500: chunk failed") {
+		t.Fatalf("downloadIMResourceToPath() error = %v", err)
+	}
+	if _, statErr := os.Stat(target); !os.IsNotExist(statErr) {
+		t.Fatalf("output file exists after failed download, stat error = %v", statErr)
+	}
+}
+
+func TestDownloadIMResourceToPathRangeOverflowCleansOutput(t *testing.T) {
+	payload := []byte("overflow-payload")
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		switch {
+		case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/om_overflow/resources/file_overflow"):
+			return shortcutRawResponse(http.StatusPartialContent, payload, http.Header{
+				"Content-Type":  []string{"application/octet-stream"},
+				"Content-Range": []string{"bytes 0-3/4"},
+			}), nil
+		default:
+			return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+		}
+	}))
+
+	cmdutil.TestChdir(t, t.TempDir())
+
+	target := "out.bin"
+	_, _, err := downloadIMResourceToPath(context.Background(), runtime, "om_overflow", "file_overflow", "file", target)
+	if err == nil || !strings.Contains(err.Error(), "chunk overflow") {
+		t.Fatalf("downloadIMResourceToPath() error = %v", err)
+	}
+	if _, statErr := os.Stat(target); !os.IsNotExist(statErr) {
+		t.Fatalf("output file exists after overflow, stat error = %v", statErr)
+	}
+}
+
+func TestDownloadIMResourceToPathRangeShortChunkSizeMismatch(t *testing.T) {
+	payload := bytes.Repeat([]byte("range-download-"), int((probeChunkSize+1024)/15)+1)
+	payload = payload[:probeChunkSize+1024]
+
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		switch {
+		case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/om_short/resources/file_short"):
+			rangeHeader := req.Header.Get("Range")
+			start, end, err := parseRangeHeader(rangeHeader, int64(len(payload)))
+			if err != nil {
+				return nil, err
+			}
+			body := payload[start : end+1]
+			if start == probeChunkSize {
+				body = body[:len(body)-10]
+			}
+			return shortcutRawResponse(http.StatusPartialContent, body, http.Header{
+				"Content-Type":  []string{"application/octet-stream"},
+				"Content-Range": []string{fmt.Sprintf("bytes %d-%d/%d", start, end, len(payload))},
+			}), nil
+		default:
+			return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+		}
+	}))
+
+	cmdutil.TestChdir(t, t.TempDir())
+
+	_, _, err := downloadIMResourceToPath(context.Background(), runtime, "om_short", "file_short", "file", "out.bin")
+	if err == nil || !strings.Contains(err.Error(), "file size mismatch") {
+		t.Fatalf("downloadIMResourceToPath() error = %v", err)
+	}
+}
+
+func parseRangeHeader(header string, totalSize int64) (int64, int64, error) {
+	if !strings.HasPrefix(header, "bytes=") {
+		return 0, 0, fmt.Errorf("unexpected range header: %q", header)
+	}
+	parts := strings.SplitN(strings.TrimPrefix(header, "bytes="), "-", 2)
+	if len(parts) != 2 {
+		return 0, 0, fmt.Errorf("unexpected range header: %q", header)
+	}
+
+	start, err := strconv.ParseInt(parts[0], 10, 64)
+	if err != nil {
+		return 0, 0, fmt.Errorf("parse start: %w", err)
+	}
+	end, err := strconv.ParseInt(parts[1], 10, 64)
+	if err != nil {
+		return 0, 0, fmt.Errorf("parse end: %w", err)
+	}
+	if start < 0 || end < start || start >= totalSize {
+		return 0, 0, fmt.Errorf("invalid range bounds: %d-%d for size %d", start, end, totalSize)
+	}
+	if end >= totalSize {
+		end = totalSize - 1
+	}
+	return start, end, nil
+}
+
 func TestUploadImageToIMSuccess(t *testing.T) {
 	var gotBody string
 	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {

shortcuts/im/helpers_test.go

@@ -599,6 +599,44 @@ func TestDownloadIMResourceToPathHTTPClientError(t *testing.T) {
 	}
 }
 
+func TestParseTotalSize(t *testing.T) {
+	tests := []struct {
+		name         string
+		contentRange string
+		want         int64
+		wantErr      string
+	}{
+		{name: "normal", contentRange: "bytes 0-131071/104857600", want: 104857600},
+		{name: "single probe chunk", contentRange: "bytes 0-131071/131072", want: 131072},
+		{name: "single small chunk", contentRange: "bytes 0-15/16", want: 16},
+		{name: "empty", contentRange: "", wantErr: "content-range is empty"},
+		{name: "invalid prefix", contentRange: "items 0-15/16", wantErr: `unsupported content-range: "items 0-15/16"`},
+		{name: "missing total", contentRange: "bytes 0-15/", wantErr: `unsupported content-range: "bytes 0-15/"`},
+		{name: "wildcard", contentRange: "bytes */16", wantErr: `unsupported content-range: "bytes */16"`},
+		{name: "unknown total size", contentRange: "bytes 0-99/*", wantErr: `unknown total size in content-range: "bytes 0-99/*"`},
+		{name: "invalid total", contentRange: "bytes 0-15/not-a-number", wantErr: "parse total size:"},
+		{name: "zero total size", contentRange: "bytes 0-0/0", wantErr: "invalid total size: 0"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := parseTotalSize(tt.contentRange)
+			if tt.wantErr != "" {
+				if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+					t.Fatalf("parseTotalSize() error = %v, want substring %q", err, tt.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("parseTotalSize() unexpected error = %v", err)
+			}
+			if got != tt.want {
+				t.Fatalf("parseTotalSize() = %d, want %d", got, tt.want)
+			}
+		})
+	}
+}
+
 func TestShortcuts(t *testing.T) {
 	var commands []string
 	for _, shortcut := range Shortcuts() {

shortcuts/im/im_chat_messages_list.go

@@ -28,7 +28,7 @@ var ImChatMessageList = common.Shortcut{
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "chat-id", Desc: "(required, mutually exclusive with --user-id) chat ID (oc_xxx)"},
-		{Name: "user-id", Desc: "(required, mutually exclusive with --chat-id) user open_id (ou_xxx)"},
+		{Name: "user-id", Desc: "(required, mutually exclusive with --chat-id; user identity only) user open_id (ou_xxx)"},
 		{Name: "start", Desc: "start time (ISO 8601)"},
 		{Name: "end", Desc: "end time (ISO 8601)"},
 		{Name: "sort", Default: "desc", Desc: "sort order", Enum: []string{"asc", "desc"}},
@@ -57,11 +57,21 @@ var ImChatMessageList = common.Shortcut{
 		return d.GET("/open-apis/im/v1/messages").Params(dryParams)
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if err := common.ExactlyOne(runtime, "chat-id", "user-id"); err != nil {
-			if runtime.Str("chat-id") == "" && runtime.Str("user-id") == "" {
-				return common.FlagErrorf("specify at least one of --chat-id or --user-id")
+		// Under bot identity, --user-id is not supported; require --chat-id only.
+		if runtime.IsBot() {
+			if runtime.Str("user-id") != "" {
+				return common.FlagErrorf("--user-id requires user identity (--as user); use --chat-id when calling with bot identity")
+			}
+			if runtime.Str("chat-id") == "" {
+				return common.FlagErrorf("specify --chat-id (bot identity does not support --user-id)")
+			}
+		} else {
+			if err := common.ExactlyOne(runtime, "chat-id", "user-id"); err != nil {
+				if runtime.Str("chat-id") == "" && runtime.Str("user-id") == "" {
+					return common.FlagErrorf("specify at least one of --chat-id or --user-id")
+				}
+				return err
 			}
-			return err
 		}
 
 		// Validate ID formats

shortcuts/im/im_messages_resources_download.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"net/http"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 
@@ -67,6 +68,9 @@ var ImMessagesResourcesDownload = common.Shortcut{
 		if err != nil {
 			return output.ErrValidation("invalid output path: %s", err)
 		}
+		if _, err := runtime.ResolveSavePath(relPath); err != nil {
+			return output.ErrValidation("unsafe output path: %s", err)
+		}
 
 		finalPath, sizeBytes, err := downloadIMResourceToPath(ctx, runtime, messageId, fileKey, fileType, relPath)
 		if err != nil {
@@ -102,7 +106,13 @@ func normalizeDownloadOutputPath(fileKey, outputPath string) (string, error) {
 	return outputPath, nil
 }
 
-const defaultIMResourceDownloadTimeout = 120 * time.Second
+const (
+	defaultIMResourceDownloadTimeout = 120 * time.Second
+	probeChunkSize                   = int64(128 * 1024)
+	normalChunkSize                  = int64(8 * 1024 * 1024)
+	imDownloadRequestRetries         = 2
+	imDownloadRetryDelay             = 300 * time.Millisecond
+)
 
 var imMimeToExt = map[string]string{
 	"image/png":                    ".png",
@@ -135,10 +145,199 @@ var imMimeToExt = map[string]string{
 	"application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
 }
 
-func downloadIMResourceToPath(ctx context.Context, runtime *common.RuntimeContext, messageID, fileKey, fileType, safePath string) (string, int64, error) {
+type rangeChunkReader struct {
+	ctx        context.Context
+	runtime    *common.RuntimeContext
+	messageID  string
+	fileKey    string
+	fileType   string
+	totalSize  int64
+	delivered  int64
+	current    io.ReadCloser
+	nextOffset int64
+}
+
+func newRangeChunkReader(
+	ctx context.Context,
+	runtime *common.RuntimeContext,
+	messageID, fileKey, fileType string,
+	probeBody io.ReadCloser,
+	totalSize int64,
+) *rangeChunkReader {
+	return &rangeChunkReader{
+		ctx:        ctx,
+		runtime:    runtime,
+		messageID:  messageID,
+		fileKey:    fileKey,
+		fileType:   fileType,
+		totalSize:  totalSize,
+		current:    probeBody,
+		nextOffset: probeChunkSize,
+	}
+}
+
+func (r *rangeChunkReader) Read(p []byte) (int, error) {
+	for {
+		if r.current != nil {
+			n, err := r.current.Read(p)
+			r.delivered += int64(n)
+
+			if r.delivered > r.totalSize {
+				if err == io.EOF {
+					closeErr := r.current.Close()
+					r.current = nil
+					if closeErr != nil {
+						return 0, closeErr
+					}
+				}
+				return 0, output.ErrNetwork("chunk overflow: delivered %d, expected %d", r.delivered, r.totalSize)
+			}
+
+			switch err {
+			case nil:
+				return n, nil
+			case io.EOF:
+				closeErr := r.current.Close()
+				r.current = nil
+				if closeErr != nil {
+					return n, closeErr
+				}
+				if r.delivered == r.totalSize {
+					if n > 0 {
+						return n, nil
+					}
+					return 0, io.EOF
+				}
+				if n > 0 {
+					return n, nil
+				}
+			default:
+				return n, err
+			}
+		}
+
+		if r.nextOffset >= r.totalSize {
+			if r.delivered == r.totalSize {
+				return 0, io.EOF
+			}
+			return 0, output.ErrNetwork("file size mismatch: expected %d, got %d", r.totalSize, r.delivered)
+		}
+
+		end := min(r.nextOffset+normalChunkSize-1, r.totalSize-1)
+		resp, err := doIMResourceDownloadRequest(r.ctx, r.runtime, r.messageID, r.fileKey, r.fileType, map[string]string{
+			"Range": fmt.Sprintf("bytes=%d-%d", r.nextOffset, end),
+		})
+		if err != nil {
+			return 0, err
+		}
+		if resp.StatusCode >= 400 {
+			defer resp.Body.Close()
+			return 0, downloadResponseError(resp)
+		}
+		if resp.StatusCode != http.StatusPartialContent {
+			resp.Body.Close()
+			return 0, output.ErrNetwork("unexpected status code: %d", resp.StatusCode)
+		}
+
+		r.current = resp.Body
+		r.nextOffset = end + 1
+	}
+}
+
+func (r *rangeChunkReader) Close() error {
+	if r.current == nil {
+		return nil
+	}
+	err := r.current.Close()
+	r.current = nil
+	return err
+}
+
+func initialIMResourceDownloadHeaders(fileType string) map[string]string {
+	if fileType != "file" {
+		return nil
+	}
+	return map[string]string{
+		"Range": fmt.Sprintf("bytes=0-%d", probeChunkSize-1),
+	}
+}
+
+func downloadIMResourceToPath(ctx context.Context, runtime *common.RuntimeContext, messageID, fileKey, fileType, outputPath string) (string, int64, error) {
+	downloadResp, err := doIMResourceDownloadRequest(ctx, runtime, messageID, fileKey, fileType, initialIMResourceDownloadHeaders(fileType))
+	if err != nil {
+		return "", 0, err
+	}
+
+	if downloadResp.StatusCode >= 400 {
+		defer downloadResp.Body.Close()
+		return "", 0, downloadResponseError(downloadResp)
+	}
+
+	finalPath := resolveIMResourceDownloadPath(outputPath, downloadResp.Header.Get("Content-Type"))
+
+	var (
+		body      io.ReadCloser
+		sizeBytes int64
+	)
+	switch downloadResp.StatusCode {
+	case http.StatusPartialContent:
+		totalSize, err := parseTotalSize(downloadResp.Header.Get("Content-Range"))
+		if err != nil {
+			downloadResp.Body.Close()
+			return "", 0, output.ErrNetwork("invalid Content-Range header on range response: %s", err)
+		}
+		body = newRangeChunkReader(ctx, runtime, messageID, fileKey, fileType, downloadResp.Body, totalSize)
+		sizeBytes = totalSize
+
+	case http.StatusOK:
+		body = downloadResp.Body
+		sizeBytes = downloadResp.ContentLength
+
+	default:
+		downloadResp.Body.Close()
+		return "", 0, output.ErrNetwork("unexpected status code: %d", downloadResp.StatusCode)
+	}
+	defer body.Close()
+
+	result, err := runtime.FileIO().Save(finalPath, fileio.SaveOptions{
+		ContentType:   downloadResp.Header.Get("Content-Type"),
+		ContentLength: sizeBytes,
+	}, body)
+	if err != nil {
+		return "", 0, common.WrapSaveErrorByCategory(err, "api_error")
+	}
+	if sizeBytes >= 0 && result.Size() != sizeBytes {
+		return "", 0, output.ErrNetwork("file size mismatch: expected %d, got %d", sizeBytes, result.Size())
+	}
+	savedPath, resolveErr := runtime.ResolveSavePath(finalPath)
+	if resolveErr != nil || savedPath == "" {
+		savedPath = finalPath
+	}
+	return savedPath, result.Size(), nil
+}
+
+func resolveIMResourceDownloadPath(safePath, contentType string) string {
+	if filepath.Ext(safePath) != "" {
+		return safePath
+	}
+	mimeType := strings.Split(contentType, ";")[0]
+	mimeType = strings.TrimSpace(mimeType)
+	if ext, ok := imMimeToExt[mimeType]; ok {
+		return safePath + ext
+	}
+	return safePath
+}
+
+func doIMResourceDownloadRequest(ctx context.Context, runtime *common.RuntimeContext, messageID, fileKey, fileType string, headers map[string]string) (*http.Response, error) {
 	query := larkcore.QueryParams{}
 	query.Set("type", fileType)
-	downloadResp, err := runtime.DoAPIStream(ctx, &larkcore.ApiReq{
+
+	headerValues := make(http.Header, len(headers))
+	for key, value := range headers {
+		headerValues.Set(key, value)
+	}
+
+	req := &larkcore.ApiReq{
 		HttpMethod: http.MethodGet,
 		ApiPath:    "/open-apis/im/v1/messages/:message_id/resources/:file_key",
 		PathParams: larkcore.PathParams{
@@ -146,44 +345,73 @@ func downloadIMResourceToPath(ctx context.Context, runtime *common.RuntimeContex
 			"file_key":   fileKey,
 		},
 		QueryParams: query,
-	}, client.WithTimeout(defaultIMResourceDownloadTimeout))
-	if err != nil {
-		return "", 0, err
 	}
-	defer downloadResp.Body.Close()
 
-	if downloadResp.StatusCode >= 400 {
-		body, _ := io.ReadAll(io.LimitReader(downloadResp.Body, 4096))
-		if len(body) > 0 {
-			return "", 0, output.ErrNetwork("download failed: HTTP %d: %s", downloadResp.StatusCode, strings.TrimSpace(string(body)))
+	var lastErr error
+	for attempt := 0; attempt <= imDownloadRequestRetries; attempt++ {
+		resp, err := runtime.DoAPIStream(ctx, req, client.WithTimeout(defaultIMResourceDownloadTimeout), client.WithHeaders(headerValues))
+		if err == nil {
+			return resp, nil
 		}
-		return "", 0, output.ErrNetwork("download failed: HTTP %d", downloadResp.StatusCode)
-	}
-
-	// Auto-detect extension from Content-Type if missing
-	finalPath := safePath
-	if filepath.Ext(safePath) == "" {
-		contentType := downloadResp.Header.Get("Content-Type")
-		mimeType := strings.Split(contentType, ";")[0]
-		mimeType = strings.TrimSpace(mimeType)
-		if ext, ok := imMimeToExt[mimeType]; ok {
-			finalPath = safePath + ext
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
 		}
+		lastErr = err
+		if attempt == imDownloadRequestRetries {
+			break
+		}
+		sleepIMDownloadRetry(ctx, attempt)
 	}
-
-	result, err := runtime.FileIO().Save(finalPath, fileio.SaveOptions{
-		ContentType:   downloadResp.Header.Get("Content-Type"),
-		ContentLength: downloadResp.ContentLength,
-	}, downloadResp.Body)
-	if err != nil {
-		return "", 0, output.Errorf(output.ExitInternal, "api_error", "%s",
-			common.WrapSaveError(err, "unsafe output path", "cannot create parent directory", "cannot create file"))
+	if lastErr != nil {
+		return nil, lastErr
 	}
-	savedPath, resolveErr := runtime.ResolveSavePath(finalPath)
-	if resolveErr != nil {
-		// Save succeeded — file is on disk. Fall back to the relative path
-		// rather than returning an error for a successfully written file.
-		savedPath = finalPath
-	}
-	return savedPath, result.Size(), nil
+	return nil, output.ErrNetwork("download request failed")
+}
+
+func sleepIMDownloadRetry(ctx context.Context, attempt int) {
+	delay := imDownloadRetryDelay * (1 << uint(attempt))
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+	case <-timer.C:
+	}
+}
+
+func downloadResponseError(resp *http.Response) error {
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+	if len(body) > 0 {
+		return output.ErrNetwork("download failed: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+	return output.ErrNetwork("download failed: HTTP %d", resp.StatusCode)
+}
+
+func parseTotalSize(contentRange string) (int64, error) {
+	contentRange = strings.TrimSpace(contentRange)
+	if contentRange == "" {
+		return 0, fmt.Errorf("content-range is empty")
+	}
+	if !strings.HasPrefix(contentRange, "bytes ") {
+		return 0, fmt.Errorf("unsupported content-range: %q", contentRange)
+	}
+
+	parts := strings.SplitN(strings.TrimPrefix(contentRange, "bytes "), "/", 2)
+	if len(parts) != 2 || parts[1] == "" {
+		return 0, fmt.Errorf("unsupported content-range: %q", contentRange)
+	}
+	if parts[0] == "*" {
+		return 0, fmt.Errorf("unsupported content-range: %q", contentRange)
+	}
+	if parts[1] == "*" {
+		return 0, fmt.Errorf("unknown total size in content-range: %q", contentRange)
+	}
+
+	totalSize, err := strconv.ParseInt(parts[1], 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("parse total size: %w", err)
+	}
+	if totalSize <= 0 {
+		return 0, fmt.Errorf("invalid total size: %d", totalSize)
+	}
+	return totalSize, nil
 }

shortcuts/mail/mail_watch.go

@@ -95,7 +95,7 @@ var MailWatch = common.Shortcut{
 	Command:     "+watch",
 	Description: "Watch for incoming mail events via WebSocket (requires scope mail:event and bot event mail.user_mailbox.event.message_received_v1 added). Run with --print-output-schema to see per-format field reference before parsing output.",
 	Risk:        "read",
-	Scopes:      []string{"mail:event", "mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
+	Scopes:      []string{"mail:event", "mail:user_mailbox.event.mail_address:read", "mail:user_mailbox:readonly", "mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user"},
 	Flags: []common.Flag{
 		{Name: "format", Default: "data", Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},

shortcuts/sheets/sheet_dropdown.go

@@ -0,0 +1,333 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func dataValidationBasePath(token string) string {
+	return fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/dataValidation",
+		validate.EncodePathSegment(token))
+}
+
+func dataValidationSheetPath(token, sheetID string) string {
+	return fmt.Sprintf("%s/%s", dataValidationBasePath(token), validate.EncodePathSegment(sheetID))
+}
+
+func validateDropdownToken(runtime *common.RuntimeContext) (string, error) {
+	token := runtime.Str("spreadsheet-token")
+	if runtime.Str("url") != "" {
+		token = extractSpreadsheetToken(runtime.Str("url"))
+	}
+	if token == "" {
+		return "", common.FlagErrorf("specify --url or --spreadsheet-token")
+	}
+	return token, nil
+}
+
+func parseJSONStringArray(flagName, value string) ([]interface{}, error) {
+	var typed []string
+	if err := json.Unmarshal([]byte(value), &typed); err != nil {
+		return nil, common.FlagErrorf("--%s must be a JSON array of strings: %v", flagName, err)
+	}
+	if typed == nil {
+		return nil, common.FlagErrorf("--%s must be a JSON array, got null", flagName)
+	}
+	arr := make([]interface{}, len(typed))
+	for i, s := range typed {
+		arr[i] = s
+	}
+	return arr, nil
+}
+
+func validateRangesFlag(runtime *common.RuntimeContext) ([]interface{}, error) {
+	ranges, err := parseJSONStringArray("ranges", runtime.Str("ranges"))
+	if err != nil {
+		return nil, err
+	}
+	if len(ranges) == 0 {
+		return nil, common.FlagErrorf("--ranges must not be empty")
+	}
+	for i, r := range ranges {
+		s, _ := r.(string)
+		if _, _, ok := splitSheetRange(s); !ok {
+			return nil, common.FlagErrorf("--ranges[%d] %q must be a fully qualified range with sheet ID prefix (e.g. <sheetId>!A2:A100)", i, s)
+		}
+	}
+	return ranges, nil
+}
+
+func buildDropdownBody(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	condValues, err := parseJSONStringArray("condition-values", runtime.Str("condition-values"))
+	if err != nil {
+		return nil, err
+	}
+	if len(condValues) == 0 {
+		return nil, common.FlagErrorf("--condition-values must not be empty")
+	}
+
+	dv := map[string]interface{}{
+		"conditionValues": condValues,
+	}
+
+	opts := map[string]interface{}{}
+	if runtime.Cmd.Flags().Changed("multiple") {
+		opts["multipleValues"] = runtime.Bool("multiple")
+	}
+	if runtime.Cmd.Flags().Changed("highlight") {
+		opts["highlightValidData"] = runtime.Bool("highlight")
+	}
+	if runtime.Str("colors") != "" {
+		colors, err := parseJSONStringArray("colors", runtime.Str("colors"))
+		if err != nil {
+			return nil, err
+		}
+		if len(colors) != len(condValues) {
+			return nil, common.FlagErrorf("--colors length (%d) must match --condition-values length (%d)", len(colors), len(condValues))
+		}
+		opts["colors"] = colors
+	}
+	if len(opts) > 0 {
+		dv["options"] = opts
+	}
+
+	return dv, nil
+}
+
+// SheetSetDropdown sets dropdown list validation on a range.
+var SheetSetDropdown = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+set-dropdown",
+	Description: "Set dropdown list on a cell range",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only", "sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token"},
+		{Name: "range", Desc: "cell range (<sheetId>!A2:A100)", Required: true},
+		{Name: "condition-values", Desc: `dropdown options as JSON array (e.g. '["opt1","opt2"]'), max 500, each <=100 chars, no commas`, Required: true},
+		{Name: "multiple", Desc: "enable multi-select (default false)", Type: "bool"},
+		{Name: "highlight", Desc: "color-code options (default false)", Type: "bool"},
+		{Name: "colors", Desc: `RGB hex color array (e.g. '["#1FB6C1","#F006C2"]'), must match condition-values length`},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := validateDropdownToken(runtime); err != nil {
+			return err
+		}
+		if _, _, ok := splitSheetRange(runtime.Str("range")); !ok {
+			return common.FlagErrorf("--range must be a fully qualified range with sheet ID prefix (e.g. <sheetId>!A2:A100)")
+		}
+		_, err := buildDropdownBody(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateDropdownToken(runtime)
+		dv, _ := buildDropdownBody(runtime)
+		return common.NewDryRunAPI().
+			POST("/open-apis/sheets/v2/spreadsheets/:token/dataValidation").
+			Body(map[string]interface{}{
+				"range":              runtime.Str("range"),
+				"dataValidationType": "list",
+				"dataValidation":     dv,
+			}).
+			Set("token", token)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateDropdownToken(runtime)
+		dv, err := buildDropdownBody(runtime)
+		if err != nil {
+			return err
+		}
+
+		data, err := runtime.CallAPI("POST", dataValidationBasePath(token), nil,
+			map[string]interface{}{
+				"range":              runtime.Str("range"),
+				"dataValidationType": "list",
+				"dataValidation":     dv,
+			},
+		)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+// SheetUpdateDropdown updates dropdown list settings for given ranges.
+var SheetUpdateDropdown = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+update-dropdown",
+	Description: "Update dropdown list settings",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only", "sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "ranges", Desc: `ranges as JSON array (e.g. '["sheetId!A1:A100"]')`, Required: true},
+		{Name: "condition-values", Desc: `dropdown options as JSON array (e.g. '["opt1","opt2"]')`, Required: true},
+		{Name: "multiple", Desc: "enable multi-select (default false)", Type: "bool"},
+		{Name: "highlight", Desc: "color-code options (default false)", Type: "bool"},
+		{Name: "colors", Desc: `RGB hex color array, must match condition-values length`},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := validateDropdownToken(runtime); err != nil {
+			return err
+		}
+		if _, err := validateRangesFlag(runtime); err != nil {
+			return err
+		}
+		_, err := buildDropdownBody(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateDropdownToken(runtime)
+		ranges, _ := parseJSONStringArray("ranges", runtime.Str("ranges"))
+		dv, _ := buildDropdownBody(runtime)
+		return common.NewDryRunAPI().
+			PUT("/open-apis/sheets/v2/spreadsheets/:token/dataValidation/:sheet_id").
+			Body(map[string]interface{}{
+				"ranges":             ranges,
+				"dataValidationType": "list",
+				"dataValidation":     dv,
+			}).
+			Set("token", token).Set("sheet_id", runtime.Str("sheet-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateDropdownToken(runtime)
+		ranges, err := parseJSONStringArray("ranges", runtime.Str("ranges"))
+		if err != nil {
+			return err
+		}
+		dv, err := buildDropdownBody(runtime)
+		if err != nil {
+			return err
+		}
+
+		data, err := runtime.CallAPI("PUT", dataValidationSheetPath(token, runtime.Str("sheet-id")), nil,
+			map[string]interface{}{
+				"ranges":             ranges,
+				"dataValidationType": "list",
+				"dataValidation":     dv,
+			},
+		)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+// SheetGetDropdown queries dropdown list settings for a range.
+var SheetGetDropdown = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+get-dropdown",
+	Description: "Get dropdown list settings for a range",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token"},
+		{Name: "range", Desc: "cell range (<sheetId>!A2:A100)", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := validateDropdownToken(runtime); err != nil {
+			return err
+		}
+		if _, _, ok := splitSheetRange(runtime.Str("range")); !ok {
+			return common.FlagErrorf("--range must be a fully qualified range with sheet ID prefix (e.g. <sheetId>!A2:A100)")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateDropdownToken(runtime)
+		return common.NewDryRunAPI().
+			GET("/open-apis/sheets/v2/spreadsheets/:token/dataValidation?range=:range&dataValidationType=list").
+			Set("token", token).Set("range", runtime.Str("range"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateDropdownToken(runtime)
+		data, err := runtime.CallAPI("GET", dataValidationBasePath(token),
+			map[string]interface{}{
+				"range":              runtime.Str("range"),
+				"dataValidationType": "list",
+			}, nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+// SheetDeleteDropdown deletes dropdown list settings from given ranges.
+var SheetDeleteDropdown = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+delete-dropdown",
+	Description: "Delete dropdown list from cell ranges",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only", "sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token"},
+		{Name: "ranges", Desc: `ranges as JSON array (e.g. '["sheetId!A2:A100"]'), max 100 ranges`, Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := validateDropdownToken(runtime); err != nil {
+			return err
+		}
+		_, err := validateRangesFlag(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateDropdownToken(runtime)
+		ranges, _ := parseJSONStringArray("ranges", runtime.Str("ranges"))
+		dvRanges := make([]interface{}, 0, len(ranges))
+		for _, r := range ranges {
+			dvRanges = append(dvRanges, map[string]interface{}{"range": r})
+		}
+		return common.NewDryRunAPI().
+			DELETE("/open-apis/sheets/v2/spreadsheets/:token/dataValidation").
+			Body(map[string]interface{}{
+				"dataValidationRanges": dvRanges,
+			}).
+			Set("token", token)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateDropdownToken(runtime)
+		ranges, err := parseJSONStringArray("ranges", runtime.Str("ranges"))
+		if err != nil {
+			return err
+		}
+
+		dvRanges := make([]interface{}, 0, len(ranges))
+		for _, r := range ranges {
+			dvRanges = append(dvRanges, map[string]interface{}{"range": r})
+		}
+
+		data, err := runtime.CallAPI("DELETE", dataValidationBasePath(token), nil,
+			map[string]interface{}{
+				"dataValidationRanges": dvRanges,
+			},
+		)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}

shortcuts/sheets/sheet_dropdown_test.go

@@ -0,0 +1,552 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+// ── SetDropdown ─────────────────────────────────────────────────────────────
+
+func TestSetDropdownValidateMissingToken(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "",
+		"range": "s1!A2:A100", "condition-values": `["opt1","opt2"]`,
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	err := SheetSetDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--url or --spreadsheet-token") {
+		t.Fatalf("expected token error, got: %v", err)
+	}
+}
+
+func TestSetDropdownValidateInvalidConditionValues(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1",
+		"range": "s1!A2:A100", "condition-values": "not-json",
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	err := SheetSetDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--condition-values must be a JSON array") {
+		t.Fatalf("expected JSON array error, got: %v", err)
+	}
+}
+
+func TestSetDropdownValidateNonStringConditionValues(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name  string
+		input string
+	}{
+		{"mixed types", `["ok", 1, null]`},
+		{"all numbers", `[1, 2, 3]`},
+		{"null literal", `null`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			rt := newSheetsTestRuntime(t, map[string]string{
+				"url": "", "spreadsheet-token": "sht1",
+				"range": "s1!A2:A100", "condition-values": tc.input,
+				"colors": "",
+			}, map[string]bool{"multiple": false, "highlight": false})
+			err := SheetSetDropdown.Validate(context.Background(), rt)
+			if err == nil || !strings.Contains(err.Error(), "--condition-values must be") {
+				t.Fatalf("expected validation error for %q, got: %v", tc.input, err)
+			}
+		})
+	}
+}
+
+func TestSetDropdownValidateInvalidColors(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1",
+		"range": "s1!A2:A100", "condition-values": `["opt1","opt2"]`,
+		"colors": "bad-json",
+	}, map[string]bool{"multiple": false, "highlight": true})
+	err := SheetSetDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--colors must be a JSON array") {
+		t.Fatalf("expected colors JSON error, got: %v", err)
+	}
+}
+
+func TestSetDropdownValidateRangeMissingSheetID(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1",
+		"range": "A2:A100", "condition-values": `["opt1"]`,
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	err := SheetSetDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "fully qualified range") {
+		t.Fatalf("expected range validation error, got: %v", err)
+	}
+}
+
+func TestSetDropdownValidateEmptyConditionValues(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1",
+		"range": "s1!A2:A100", "condition-values": `[]`,
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	err := SheetSetDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--condition-values must not be empty") {
+		t.Fatalf("expected empty error, got: %v", err)
+	}
+}
+
+func TestSetDropdownValidateColorsMismatchLength(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1",
+		"range": "s1!A2:A100", "condition-values": `["a","b","c"]`,
+		"colors": `["#FF0000"]`,
+	}, map[string]bool{"multiple": false, "highlight": true})
+	err := SheetSetDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--colors length") {
+		t.Fatalf("expected length mismatch error, got: %v", err)
+	}
+}
+
+func TestSetDropdownValidateSuccess(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1",
+		"range": "s1!A2:A100", "condition-values": `["opt1","opt2"]`,
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	if err := SheetSetDropdown.Validate(context.Background(), rt); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestSetDropdownDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test",
+		"range": "s1!A2:A100", "condition-values": `["opt1","opt2"]`,
+		"colors": "",
+	}, map[string]bool{"multiple": true, "highlight": false})
+	got := mustMarshalSheetsDryRun(t, SheetSetDropdown.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"POST"`) {
+		t.Fatalf("DryRun should use POST: %s", got)
+	}
+	if !strings.Contains(got, `dataValidation`) {
+		t.Fatalf("DryRun missing dataValidation: %s", got)
+	}
+	if !strings.Contains(got, `"dataValidationType":"list"`) {
+		t.Fatalf("DryRun missing dataValidationType: %s", got)
+	}
+}
+
+func TestSetDropdownExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v2/spreadsheets/shtTOKEN/dataValidation",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	})
+	err := mountAndRunSheets(t, SheetSetDropdown, []string{
+		"+set-dropdown", "--spreadsheet-token", "shtTOKEN",
+		"--range", "s1!A2:A100", "--condition-values", `["opt1","opt2","opt3"]`,
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestSetDropdownExecuteWithMultipleAndColors(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	stub := &httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v2/spreadsheets/shtTOKEN/dataValidation",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	}
+	reg.Register(stub)
+	err := mountAndRunSheets(t, SheetSetDropdown, []string{
+		"+set-dropdown", "--spreadsheet-token", "shtTOKEN",
+		"--range", "s1!A2:A100", "--condition-values", `["a","b"]`,
+		"--multiple", "--highlight", "--colors", `["#1FB6C1","#F006C2"]`,
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("parse body: %v", err)
+	}
+	dv, _ := body["dataValidation"].(map[string]interface{})
+	opts, _ := dv["options"].(map[string]interface{})
+	if opts["multipleValues"] != true {
+		t.Fatalf("expected multipleValues=true, got: %v", opts["multipleValues"])
+	}
+	if opts["highlightValidData"] != true {
+		t.Fatalf("expected highlightValidData=true, got: %v", opts["highlightValidData"])
+	}
+}
+
+func TestSetDropdownExecuteAPIError(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v2/spreadsheets/shtTOKEN/dataValidation",
+		Status: 400, Body: map[string]interface{}{"code": 90001, "msg": "invalid"},
+	})
+	err := mountAndRunSheets(t, SheetSetDropdown, []string{
+		"+set-dropdown", "--spreadsheet-token", "shtTOKEN",
+		"--range", "s1!A2:A100", "--condition-values", `["opt1"]`,
+		"--as", "user",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+}
+
+func TestSetDropdownWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v2/spreadsheets/shtFromURL/dataValidation",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	})
+	err := mountAndRunSheets(t, SheetSetDropdown, []string{
+		"+set-dropdown", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--range", "s1!A2:A100", "--condition-values", `["opt1"]`,
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ── UpdateDropdown ──────────────────────────────────────────────────────────
+
+func TestUpdateDropdownValidateMissingToken(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "", "sheet-id": "s1",
+		"ranges": `["s1!A1:A100"]`, "condition-values": `["opt1"]`,
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	err := SheetUpdateDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--url or --spreadsheet-token") {
+		t.Fatalf("expected token error, got: %v", err)
+	}
+}
+
+func TestUpdateDropdownValidateInvalidRanges(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1", "sheet-id": "s1",
+		"ranges": "not-json", "condition-values": `["opt1"]`,
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	err := SheetUpdateDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--ranges must be a JSON array") {
+		t.Fatalf("expected JSON array error, got: %v", err)
+	}
+}
+
+func TestUpdateDropdownValidateRangesMissingSheetID(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1", "sheet-id": "s1",
+		"ranges": `["A1:A100"]`, "condition-values": `["opt1"]`,
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	err := SheetUpdateDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "fully qualified range") {
+		t.Fatalf("expected range validation error, got: %v", err)
+	}
+}
+
+func TestUpdateDropdownValidateEmptyRanges(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1", "sheet-id": "s1",
+		"ranges": `[]`, "condition-values": `["opt1"]`,
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	err := SheetUpdateDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--ranges must not be empty") {
+		t.Fatalf("expected empty error, got: %v", err)
+	}
+}
+
+func TestUpdateDropdownValidateInvalidColors(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1", "sheet-id": "s1",
+		"ranges": `["s1!A1:A100"]`, "condition-values": `["opt1"]`,
+		"colors": "{not-array}",
+	}, map[string]bool{"multiple": false, "highlight": true})
+	err := SheetUpdateDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--colors must be a JSON array") {
+		t.Fatalf("expected colors JSON error, got: %v", err)
+	}
+}
+
+func TestUpdateDropdownDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1",
+		"ranges": `["sheet1!A1:A100"]`, "condition-values": `["new1","new2"]`,
+		"colors": "",
+	}, map[string]bool{"multiple": false, "highlight": false})
+	got := mustMarshalSheetsDryRun(t, SheetUpdateDropdown.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"PUT"`) {
+		t.Fatalf("DryRun should use PUT: %s", got)
+	}
+	if !strings.Contains(got, `sheet1`) {
+		t.Fatalf("DryRun missing sheet_id: %s", got)
+	}
+}
+
+func TestUpdateDropdownExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "PUT", URL: "/open-apis/sheets/v2/spreadsheets/shtTOKEN/dataValidation/sheet1",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"spreadsheetToken": "shtTOKEN", "sheetId": "sheet1",
+		}},
+	})
+	err := mountAndRunSheets(t, SheetUpdateDropdown, []string{
+		"+update-dropdown", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--ranges", `["sheet1!A1:A100"]`,
+		"--condition-values", `["new1","new2"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestUpdateDropdownWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "PUT", URL: "/open-apis/sheets/v2/spreadsheets/shtFromURL/dataValidation/sheet1",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	})
+	err := mountAndRunSheets(t, SheetUpdateDropdown, []string{
+		"+update-dropdown", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--ranges", `["sheet1!A1:A100"]`,
+		"--condition-values", `["opt1"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ── GetDropdown ─────────────────────────────────────────────────────────────
+
+func TestGetDropdownValidateRangeMissingSheetID(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1", "range": "A2:A100",
+	}, nil)
+	err := SheetGetDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "fully qualified range") {
+		t.Fatalf("expected range validation error, got: %v", err)
+	}
+}
+
+func TestGetDropdownValidateMissingToken(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "", "range": "s1!A2:A100",
+	}, nil)
+	err := SheetGetDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--url or --spreadsheet-token") {
+		t.Fatalf("expected token error, got: %v", err)
+	}
+}
+
+func TestGetDropdownDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "range": "s1!A2:A100",
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetGetDropdown.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"GET"`) {
+		t.Fatalf("DryRun should use GET: %s", got)
+	}
+	if !strings.Contains(got, `dataValidation`) {
+		t.Fatalf("DryRun missing dataValidation path: %s", got)
+	}
+}
+
+func TestGetDropdownExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v2/spreadsheets/shtTOKEN/dataValidation",
+		Body: map[string]interface{}{"code": 0, "msg": "Success", "data": map[string]interface{}{
+			"dataValidations": []interface{}{
+				map[string]interface{}{
+					"dataValidationType": "list",
+					"conditionValues":    []interface{}{"opt1", "opt2"},
+					"ranges":             []interface{}{"s1!A2:A100"},
+				},
+			},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetGetDropdown, []string{
+		"+get-dropdown", "--spreadsheet-token", "shtTOKEN",
+		"--range", "s1!A2:A100", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "dataValidations") {
+		t.Fatalf("stdout missing dataValidations: %s", stdout.String())
+	}
+}
+
+func TestGetDropdownWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v2/spreadsheets/shtFromURL/dataValidation",
+		Body: map[string]interface{}{"code": 0, "msg": "Success", "data": map[string]interface{}{
+			"dataValidations": []interface{}{},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetGetDropdown, []string{
+		"+get-dropdown", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--range", "s1!A2:A100", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ── DeleteDropdown ──────────────────────────────────────────────────────────
+
+func TestDeleteDropdownValidateMissingToken(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "", "ranges": `["s1!A2:A100"]`,
+	}, nil)
+	err := SheetDeleteDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--url or --spreadsheet-token") {
+		t.Fatalf("expected token error, got: %v", err)
+	}
+}
+
+func TestDeleteDropdownValidateRangesMissingSheetID(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1", "ranges": `["B1:B50"]`,
+	}, nil)
+	err := SheetDeleteDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "fully qualified range") {
+		t.Fatalf("expected range validation error, got: %v", err)
+	}
+}
+
+func TestDeleteDropdownValidateEmptyRanges(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1", "ranges": `[]`,
+	}, nil)
+	err := SheetDeleteDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--ranges must not be empty") {
+		t.Fatalf("expected empty error, got: %v", err)
+	}
+}
+
+func TestDeleteDropdownValidateInvalidRanges(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1", "ranges": "bad",
+	}, nil)
+	err := SheetDeleteDropdown.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--ranges must be a JSON array") {
+		t.Fatalf("expected JSON array error, got: %v", err)
+	}
+}
+
+func TestDeleteDropdownDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "ranges": `["s1!A2:A100","s1!C1:C50"]`,
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetDeleteDropdown.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"DELETE"`) {
+		t.Fatalf("DryRun should use DELETE: %s", got)
+	}
+	if !strings.Contains(got, `dataValidationRanges`) {
+		t.Fatalf("DryRun missing dataValidationRanges: %s", got)
+	}
+}
+
+func TestDeleteDropdownExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: "/open-apis/sheets/v2/spreadsheets/shtTOKEN/dataValidation",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"rangeResults": []interface{}{
+				map[string]interface{}{"range": "s1!A2:A100", "success": true, "updatedCells": 99},
+			},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetDeleteDropdown, []string{
+		"+delete-dropdown", "--spreadsheet-token", "shtTOKEN",
+		"--ranges", `["s1!A2:A100"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "rangeResults") {
+		t.Fatalf("stdout missing rangeResults: %s", stdout.String())
+	}
+}
+
+func TestDeleteDropdownExecuteMultipleRanges(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	stub := &httpmock.Stub{
+		Method: "DELETE", URL: "/open-apis/sheets/v2/spreadsheets/shtTOKEN/dataValidation",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	}
+	reg.Register(stub)
+	err := mountAndRunSheets(t, SheetDeleteDropdown, []string{
+		"+delete-dropdown", "--spreadsheet-token", "shtTOKEN",
+		"--ranges", `["s1!A2:A100","s1!C1:C50"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("parse body: %v", err)
+	}
+	dvRanges, _ := body["dataValidationRanges"].([]interface{})
+	if len(dvRanges) != 2 {
+		t.Fatalf("expected 2 ranges, got: %d", len(dvRanges))
+	}
+}
+
+func TestDeleteDropdownWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: "/open-apis/sheets/v2/spreadsheets/shtFromURL/dataValidation",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	})
+	err := mountAndRunSheets(t, SheetDeleteDropdown, []string{
+		"+delete-dropdown", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--ranges", `["s1!A2:A100"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// suppress unused import for bytes in case the test helpers already import it
+var _ = (*bytes.Buffer)(nil)

shortcuts/sheets/sheet_filter_view.go

@@ -0,0 +1,239 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func filterViewBasePath(token, sheetID string) string {
+	return fmt.Sprintf("/open-apis/sheets/v3/spreadsheets/%s/sheets/%s/filter_views",
+		validate.EncodePathSegment(token), validate.EncodePathSegment(sheetID))
+}
+
+func filterViewItemPath(token, sheetID, filterViewID string) string {
+	return fmt.Sprintf("%s/%s", filterViewBasePath(token, sheetID), validate.EncodePathSegment(filterViewID))
+}
+
+func validateFilterViewToken(runtime *common.RuntimeContext) (string, error) {
+	token := runtime.Str("spreadsheet-token")
+	if runtime.Str("url") != "" {
+		token = extractSpreadsheetToken(runtime.Str("url"))
+	}
+	if token == "" {
+		return "", common.FlagErrorf("specify --url or --spreadsheet-token")
+	}
+	return token, nil
+}
+
+var SheetCreateFilterView = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+create-filter-view",
+	Description: "Create a filter view",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only", "sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "range", Desc: "filter range (e.g. sheetId!A1:H14)", Required: true},
+		{Name: "filter-view-name", Desc: "display name (max 100 chars)"},
+		{Name: "filter-view-id", Desc: "custom 10-char alphanumeric ID (auto-generated if omitted)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := validateFilterViewToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		body := map[string]interface{}{"range": runtime.Str("range")}
+		if s := runtime.Str("filter-view-name"); s != "" {
+			body["filter_view_name"] = s
+		}
+		if s := runtime.Str("filter-view-id"); s != "" {
+			body["filter_view_id"] = s
+		}
+		return common.NewDryRunAPI().
+			POST("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views").
+			Body(body).Set("token", token).Set("sheet_id", runtime.Str("sheet-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		body := map[string]interface{}{"range": runtime.Str("range")}
+		if s := runtime.Str("filter-view-name"); s != "" {
+			body["filter_view_name"] = s
+		}
+		if s := runtime.Str("filter-view-id"); s != "" {
+			body["filter_view_id"] = s
+		}
+		data, err := runtime.CallAPI("POST", filterViewBasePath(token, runtime.Str("sheet-id")), nil, body)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+var SheetUpdateFilterView = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+update-filter-view",
+	Description: "Update a filter view",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only", "sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
+		{Name: "range", Desc: "new filter range"},
+		{Name: "filter-view-name", Desc: "new display name (max 100 chars)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := validateFilterViewToken(runtime); err != nil {
+			return err
+		}
+		if !runtime.Cmd.Flags().Changed("range") &&
+			!runtime.Cmd.Flags().Changed("filter-view-name") {
+			return common.FlagErrorf("specify at least one of --range or --filter-view-name")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		body := map[string]interface{}{}
+		if s := runtime.Str("range"); s != "" {
+			body["range"] = s
+		}
+		if s := runtime.Str("filter-view-name"); s != "" {
+			body["filter_view_name"] = s
+		}
+		return common.NewDryRunAPI().
+			PATCH("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views/:filter_view_id").
+			Body(body).Set("token", token).Set("sheet_id", runtime.Str("sheet-id")).Set("filter_view_id", runtime.Str("filter-view-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		body := map[string]interface{}{}
+		if s := runtime.Str("range"); s != "" {
+			body["range"] = s
+		}
+		if s := runtime.Str("filter-view-name"); s != "" {
+			body["filter_view_name"] = s
+		}
+		data, err := runtime.CallAPI("PATCH", filterViewItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, body)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+var SheetListFilterViews = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+list-filter-views",
+	Description: "List all filter views in a sheet",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := validateFilterViewToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		return common.NewDryRunAPI().
+			GET("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views/query").
+			Set("token", token).Set("sheet_id", runtime.Str("sheet-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		data, err := runtime.CallAPI("GET", filterViewBasePath(token, runtime.Str("sheet-id"))+"/query", nil, nil)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+var SheetGetFilterView = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+get-filter-view",
+	Description: "Get a filter view by ID",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := validateFilterViewToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		return common.NewDryRunAPI().
+			GET("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views/:filter_view_id").
+			Set("token", token).Set("sheet_id", runtime.Str("sheet-id")).Set("filter_view_id", runtime.Str("filter-view-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		data, err := runtime.CallAPI("GET", filterViewItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, nil)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+var SheetDeleteFilterView = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+delete-filter-view",
+	Description: "Delete a filter view",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only", "sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := validateFilterViewToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		return common.NewDryRunAPI().
+			DELETE("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views/:filter_view_id").
+			Set("token", token).Set("sheet_id", runtime.Str("sheet-id")).Set("filter_view_id", runtime.Str("filter-view-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		data, err := runtime.CallAPI("DELETE", filterViewItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, nil)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}

shortcuts/sheets/sheet_filter_view_condition.go

@@ -0,0 +1,261 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func filterViewConditionBasePath(token, sheetID, filterViewID string) string {
+	return fmt.Sprintf("%s/conditions", filterViewItemPath(token, sheetID, filterViewID))
+}
+
+func filterViewConditionItemPath(token, sheetID, filterViewID, conditionID string) string {
+	return fmt.Sprintf("%s/%s", filterViewConditionBasePath(token, sheetID, filterViewID), validate.EncodePathSegment(conditionID))
+}
+
+var SheetCreateFilterViewCondition = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+create-filter-view-condition",
+	Description: "Create a filter condition on a filter view",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only", "sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
+		{Name: "condition-id", Desc: "column letter (e.g. E)", Required: true},
+		{Name: "filter-type", Desc: "filter type: hiddenValue, number, text, color", Required: true},
+		{Name: "compare-type", Desc: "comparison operator (e.g. less, beginsWith, between)"},
+		{Name: "expected", Desc: "filter values JSON array (e.g. [\"6\"])", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := validateFilterViewToken(runtime); err != nil {
+			return err
+		}
+		return validateExpectedFlag(runtime.Str("expected"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		body := buildConditionBody(runtime, true)
+		return common.NewDryRunAPI().
+			POST("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views/:filter_view_id/conditions").
+			Body(body).Set("token", token).Set("sheet_id", runtime.Str("sheet-id")).Set("filter_view_id", runtime.Str("filter-view-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		body := buildConditionBody(runtime, true)
+		data, err := runtime.CallAPI("POST", filterViewConditionBasePath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, body)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+var SheetUpdateFilterViewCondition = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+update-filter-view-condition",
+	Description: "Update a filter condition on a filter view",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only", "sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
+		{Name: "condition-id", Desc: "column letter (e.g. E)", Required: true},
+		{Name: "filter-type", Desc: "filter type: hiddenValue, number, text, color"},
+		{Name: "compare-type", Desc: "comparison operator"},
+		{Name: "expected", Desc: "filter values JSON array"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := validateFilterViewToken(runtime); err != nil {
+			return err
+		}
+		if !runtime.Cmd.Flags().Changed("filter-type") &&
+			!runtime.Cmd.Flags().Changed("compare-type") &&
+			!runtime.Cmd.Flags().Changed("expected") {
+			return common.FlagErrorf("specify at least one of --filter-type, --compare-type, or --expected")
+		}
+		if s := runtime.Str("expected"); s != "" {
+			return validateExpectedFlag(s)
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		body := buildConditionBody(runtime, false)
+		return common.NewDryRunAPI().
+			PUT("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views/:filter_view_id/conditions/:condition_id").
+			Body(body).Set("token", token).Set("sheet_id", runtime.Str("sheet-id")).
+			Set("filter_view_id", runtime.Str("filter-view-id")).Set("condition_id", runtime.Str("condition-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		body := buildConditionBody(runtime, false)
+		data, err := runtime.CallAPI("PUT",
+			filterViewConditionItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id"), runtime.Str("condition-id")),
+			nil, body)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+var SheetListFilterViewConditions = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+list-filter-view-conditions",
+	Description: "List all filter conditions of a filter view",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := validateFilterViewToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		return common.NewDryRunAPI().
+			GET("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views/:filter_view_id/conditions/query").
+			Set("token", token).Set("sheet_id", runtime.Str("sheet-id")).Set("filter_view_id", runtime.Str("filter-view-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		data, err := runtime.CallAPI("GET",
+			filterViewConditionBasePath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id"))+"/query",
+			nil, nil)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+var SheetGetFilterViewCondition = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+get-filter-view-condition",
+	Description: "Get a filter condition by column",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
+		{Name: "condition-id", Desc: "column letter (e.g. E)", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := validateFilterViewToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		return common.NewDryRunAPI().
+			GET("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views/:filter_view_id/conditions/:condition_id").
+			Set("token", token).Set("sheet_id", runtime.Str("sheet-id")).
+			Set("filter_view_id", runtime.Str("filter-view-id")).Set("condition_id", runtime.Str("condition-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		data, err := runtime.CallAPI("GET",
+			filterViewConditionItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id"), runtime.Str("condition-id")),
+			nil, nil)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+var SheetDeleteFilterViewCondition = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+delete-filter-view-condition",
+	Description: "Delete a filter condition from a filter view",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only", "sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "url", Desc: "spreadsheet URL (required if --spreadsheet-token is not set)"},
+		{Name: "spreadsheet-token", Desc: "spreadsheet token (required if --url is not set)"},
+		{Name: "sheet-id", Desc: "sheet ID", Required: true},
+		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
+		{Name: "condition-id", Desc: "column letter (e.g. E)", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := validateFilterViewToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := validateFilterViewToken(runtime)
+		return common.NewDryRunAPI().
+			DELETE("/open-apis/sheets/v3/spreadsheets/:token/sheets/:sheet_id/filter_views/:filter_view_id/conditions/:condition_id").
+			Set("token", token).Set("sheet_id", runtime.Str("sheet-id")).
+			Set("filter_view_id", runtime.Str("filter-view-id")).Set("condition_id", runtime.Str("condition-id"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, _ := validateFilterViewToken(runtime)
+		data, err := runtime.CallAPI("DELETE",
+			filterViewConditionItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id"), runtime.Str("condition-id")),
+			nil, nil)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+// validateExpectedFlag checks that --expected is a valid JSON array.
+func validateExpectedFlag(s string) error {
+	if s == "" {
+		return nil
+	}
+	var arr []interface{}
+	if err := json.Unmarshal([]byte(s), &arr); err != nil {
+		return fmt.Errorf("--expected must be a JSON array (e.g. [\"6\"]), got: %s", s)
+	}
+	return nil
+}
+
+// buildConditionBody constructs the request body for condition create/update.
+func buildConditionBody(runtime *common.RuntimeContext, includeConditionID bool) map[string]interface{} {
+	body := map[string]interface{}{}
+	if includeConditionID {
+		body["condition_id"] = runtime.Str("condition-id")
+	}
+	if s := runtime.Str("filter-type"); s != "" {
+		body["filter_type"] = s
+	}
+	if s := runtime.Str("compare-type"); s != "" {
+		body["compare_type"] = s
+	}
+	if s := runtime.Str("expected"); s != "" {
+		var arr []interface{}
+		// Validate already ensures this is a valid JSON array.
+		_ = json.Unmarshal([]byte(s), &arr)
+		body["expected"] = arr
+	}
+	return body
+}

shortcuts/sheets/sheet_filter_view_test.go

@@ -0,0 +1,628 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+// ── CreateFilterView ─────────────────────────────────────────────────────────
+
+func TestCreateFilterViewValidateMissingToken(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "", "sheet-id": "s1", "range": "s1!A1:H14",
+		"filter-view-name": "", "filter-view-id": "",
+	}, nil)
+	err := SheetCreateFilterView.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--url or --spreadsheet-token") {
+		t.Fatalf("expected token error, got: %v", err)
+	}
+}
+
+func TestCreateFilterViewValidateSuccess(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht1", "sheet-id": "s1", "range": "s1!A1:H14",
+		"filter-view-name": "", "filter-view-id": "",
+	}, nil)
+	if err := SheetCreateFilterView.Validate(context.Background(), rt); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestCreateFilterViewDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1", "range": "sheet1!A1:H14",
+		"filter-view-name": "my view", "filter-view-id": "",
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetCreateFilterView.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `filter_views`) {
+		t.Fatalf("DryRun URL missing filter_views: %s", got)
+	}
+	if !strings.Contains(got, `"filter_view_name":"my view"`) {
+		t.Fatalf("DryRun missing name: %s", got)
+	}
+}
+
+func TestCreateFilterViewExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"filter_view": map[string]interface{}{"filter_view_id": "pH9hbVcCXA", "range": "sheet1!A1:H14"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetCreateFilterView, []string{
+		"+create-filter-view", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--range", "sheet1!A1:H14", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "filter_view_id") {
+		t.Fatalf("stdout missing filter_view_id: %s", stdout.String())
+	}
+}
+
+func TestCreateFilterViewExecuteAPIError(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views",
+		Status: 400, Body: map[string]interface{}{"code": 90001, "msg": "invalid"},
+	})
+	err := mountAndRunSheets(t, SheetCreateFilterView, []string{
+		"+create-filter-view", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--range", "sheet1!A1:H14", "--as", "user",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+}
+
+// ── UpdateFilterView ─────────────────────────────────────────────────────────
+
+func TestUpdateFilterViewDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1",
+		"filter-view-id": "pH9hbVcCXA", "range": "sheet1!A1:J20", "filter-view-name": "",
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetUpdateFilterView.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"PATCH"`) {
+		t.Fatalf("DryRun should use PATCH: %s", got)
+	}
+	if !strings.Contains(got, `pH9hbVcCXA`) {
+		t.Fatalf("DryRun missing filter_view_id: %s", got)
+	}
+}
+
+func TestUpdateFilterViewExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "PATCH", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/fv123",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"filter_view": map[string]interface{}{"filter_view_id": "fv123", "range": "sheet1!A1:J20"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetUpdateFilterView, []string{
+		"+update-filter-view", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv123", "--range", "sheet1!A1:J20", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestUpdateFilterViewRejectsNoFields(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, sheetsTestConfig())
+	err := mountAndRunSheets(t, SheetUpdateFilterView, []string{
+		"+update-filter-view", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1",
+		"--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected validation error when no update fields provided, got nil")
+	}
+	if !strings.Contains(err.Error(), "at least one") {
+		t.Fatalf("unexpected error message: %v", err)
+	}
+}
+
+// ── ListFilterViews ──────────────────────────────────────────────────────────
+
+func TestListFilterViewsDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1",
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetListFilterViews.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `filter_views/query`) {
+		t.Fatalf("DryRun URL missing query: %s", got)
+	}
+}
+
+func TestListFilterViewsExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/query",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"items": []interface{}{map[string]interface{}{"filter_view_id": "fv1"}},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetListFilterViews, []string{
+		"+list-filter-views", "--spreadsheet-token", "shtTOKEN", "--sheet-id", "sheet1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "fv1") {
+		t.Fatalf("stdout missing fv1: %s", stdout.String())
+	}
+}
+
+// ── GetFilterView ────────────────────────────────────────────────────────────
+
+func TestGetFilterViewDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1", "filter-view-id": "fv123",
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetGetFilterView.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"GET"`) {
+		t.Fatalf("DryRun should use GET: %s", got)
+	}
+	if !strings.Contains(got, `fv123`) {
+		t.Fatalf("DryRun missing filter_view_id: %s", got)
+	}
+}
+
+func TestGetFilterViewExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/fv123",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"filter_view": map[string]interface{}{"filter_view_id": "fv123"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetGetFilterView, []string{
+		"+get-filter-view", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv123", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ── DeleteFilterView ─────────────────────────────────────────────────────────
+
+func TestDeleteFilterViewDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1", "filter-view-id": "fv123",
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetDeleteFilterView.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"DELETE"`) {
+		t.Fatalf("DryRun should use DELETE: %s", got)
+	}
+}
+
+func TestDeleteFilterViewExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/fv123",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	})
+	err := mountAndRunSheets(t, SheetDeleteFilterView, []string{
+		"+delete-filter-view", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv123", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ── CreateFilterViewCondition ────────────────────────────────────────────────
+
+func TestCreateFilterViewConditionValidateMissingToken(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "", "sheet-id": "s1", "filter-view-id": "fv1",
+		"condition-id": "E", "filter-type": "number", "compare-type": "less", "expected": `["6"]`,
+	}, nil)
+	err := SheetCreateFilterViewCondition.Validate(context.Background(), rt)
+	if err == nil || !strings.Contains(err.Error(), "--url or --spreadsheet-token") {
+		t.Fatalf("expected token error, got: %v", err)
+	}
+}
+
+func TestCreateFilterViewConditionDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1", "filter-view-id": "fv1",
+		"condition-id": "E", "filter-type": "number", "compare-type": "less", "expected": `["6"]`,
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetCreateFilterViewCondition.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `conditions`) {
+		t.Fatalf("DryRun URL missing conditions: %s", got)
+	}
+	if !strings.Contains(got, `"condition_id":"E"`) {
+		t.Fatalf("DryRun missing condition_id: %s", got)
+	}
+	if !strings.Contains(got, `"filter_type":"number"`) {
+		t.Fatalf("DryRun missing filter_type: %s", got)
+	}
+}
+
+func TestCreateFilterViewConditionExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	stub := &httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/fv1/conditions",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"condition": map[string]interface{}{"condition_id": "E", "filter_type": "number"},
+		}},
+	}
+	reg.Register(stub)
+	err := mountAndRunSheets(t, SheetCreateFilterViewCondition, []string{
+		"+create-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1",
+		"--condition-id", "E", "--filter-type", "number", "--compare-type", "less",
+		"--expected", `["6"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("parse body: %v", err)
+	}
+	if body["condition_id"] != "E" {
+		t.Fatalf("unexpected condition_id: %v", body["condition_id"])
+	}
+}
+
+// ── UpdateFilterViewCondition ────────────────────────────────────────────────
+
+func TestUpdateFilterViewConditionDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1", "filter-view-id": "fv1",
+		"condition-id": "E", "filter-type": "number", "compare-type": "between", "expected": `["2","10"]`,
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetUpdateFilterViewCondition.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"PUT"`) {
+		t.Fatalf("DryRun should use PUT: %s", got)
+	}
+	if !strings.Contains(got, `"compare_type":"between"`) {
+		t.Fatalf("DryRun missing compare_type: %s", got)
+	}
+}
+
+func TestUpdateFilterViewConditionExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "PUT", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/fv1/conditions/E",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"condition": map[string]interface{}{"condition_id": "E"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetUpdateFilterViewCondition, []string{
+		"+update-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--condition-id", "E",
+		"--filter-type", "number", "--compare-type", "between", "--expected", `["2","10"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestUpdateFilterViewConditionRejectsNoFields(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, sheetsTestConfig())
+	err := mountAndRunSheets(t, SheetUpdateFilterViewCondition, []string{
+		"+update-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--condition-id", "E",
+		"--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected validation error when no update fields provided, got nil")
+	}
+	if !strings.Contains(err.Error(), "at least one") {
+		t.Fatalf("unexpected error message: %v", err)
+	}
+}
+
+// ── ListFilterViewConditions ─────────────────────────────────────────────────
+
+func TestListFilterViewConditionsDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1", "filter-view-id": "fv1",
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetListFilterViewConditions.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `conditions/query`) {
+		t.Fatalf("DryRun URL missing conditions/query: %s", got)
+	}
+}
+
+func TestListFilterViewConditionsExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/fv1/conditions/query",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"items": []interface{}{map[string]interface{}{"condition_id": "E"}},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetListFilterViewConditions, []string{
+		"+list-filter-view-conditions", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ── GetFilterViewCondition ───────────────────────────────────────────────────
+
+func TestGetFilterViewConditionDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1",
+		"filter-view-id": "fv1", "condition-id": "E",
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetGetFilterViewCondition.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"GET"`) {
+		t.Fatalf("DryRun should use GET: %s", got)
+	}
+}
+
+func TestGetFilterViewConditionExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/fv1/conditions/E",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"condition": map[string]interface{}{"condition_id": "E", "filter_type": "number"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetGetFilterViewCondition, []string{
+		"+get-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--condition-id", "E", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ── DeleteFilterViewCondition ────────────────────────────────────────────────
+
+func TestDeleteFilterViewConditionDryRun(t *testing.T) {
+	t.Parallel()
+	rt := newSheetsTestRuntime(t, map[string]string{
+		"url": "", "spreadsheet-token": "sht_test", "sheet-id": "sheet1",
+		"filter-view-id": "fv1", "condition-id": "E",
+	}, nil)
+	got := mustMarshalSheetsDryRun(t, SheetDeleteFilterViewCondition.DryRun(context.Background(), rt))
+	if !strings.Contains(got, `"method":"DELETE"`) {
+		t.Fatalf("DryRun should use DELETE: %s", got)
+	}
+}
+
+func TestDeleteFilterViewConditionExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/fv1/conditions/E",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	})
+	err := mountAndRunSheets(t, SheetDeleteFilterViewCondition, []string{
+		"+delete-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--condition-id", "E", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ── URL flag coverage ────────────────────────────────────────────────────────
+
+func TestCreateFilterViewWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"filter_view": map[string]interface{}{"filter_view_id": "fv1"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetCreateFilterView, []string{
+		"+create-filter-view", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--range", "sheet1!A1:H14", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestListFilterViewsWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views/query",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"items": []interface{}{}}},
+	})
+	err := mountAndRunSheets(t, SheetListFilterViews, []string{
+		"+list-filter-views", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestGetFilterViewWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views/fv1",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"filter_view": map[string]interface{}{"filter_view_id": "fv1"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetGetFilterView, []string{
+		"+get-filter-view", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestUpdateFilterViewWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "PATCH", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views/fv1",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"filter_view": map[string]interface{}{"filter_view_id": "fv1"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetUpdateFilterView, []string{
+		"+update-filter-view", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--range", "sheet1!A1:J20", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDeleteFilterViewWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views/fv1",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	})
+	err := mountAndRunSheets(t, SheetDeleteFilterView, []string{
+		"+delete-filter-view", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestCreateFilterViewConditionWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views/fv1/conditions",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"condition": map[string]interface{}{"condition_id": "E"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetCreateFilterViewCondition, []string{
+		"+create-filter-view-condition", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1",
+		"--condition-id", "E", "--filter-type", "number", "--compare-type", "less",
+		"--expected", `["6"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestUpdateFilterViewConditionWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "PUT", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views/fv1/conditions/E",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"condition": map[string]interface{}{"condition_id": "E"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetUpdateFilterViewCondition, []string{
+		"+update-filter-view-condition", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--condition-id", "E",
+		"--filter-type", "number", "--expected", `["5"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestListFilterViewConditionsWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views/fv1/conditions/query",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"items": []interface{}{}}},
+	})
+	err := mountAndRunSheets(t, SheetListFilterViewConditions, []string{
+		"+list-filter-view-conditions", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestGetFilterViewConditionWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views/fv1/conditions/E",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"condition": map[string]interface{}{"condition_id": "E"},
+		}},
+	})
+	err := mountAndRunSheets(t, SheetGetFilterViewCondition, []string{
+		"+get-filter-view-condition", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--condition-id", "E", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDeleteFilterViewConditionWithURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: "/open-apis/sheets/v3/spreadsheets/shtFromURL/sheets/sheet1/filter_views/fv1/conditions/E",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{}},
+	})
+	err := mountAndRunSheets(t, SheetDeleteFilterViewCondition, []string{
+		"+delete-filter-view-condition", "--url", "https://example.feishu.cn/sheets/shtFromURL",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--condition-id", "E", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ── --expected validation rejects non-array input ────────────────────────────
+
+func TestCreateFilterViewConditionRejectsNonArrayExpected(t *testing.T) {
+	cases := []struct {
+		name     string
+		expected string
+	}{
+		{"plain string", "hello"},
+		{"JSON object", `{"key":"val"}`},
+		{"JSON number", "42"},
+		{"JSON string", `"hello"`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, stdout, _, _ := cmdutil.TestFactory(t, sheetsTestConfig())
+			err := mountAndRunSheets(t, SheetCreateFilterViewCondition, []string{
+				"+create-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+				"--sheet-id", "sheet1", "--filter-view-id", "fv1",
+				"--condition-id", "A", "--filter-type", "text", "--compare-type", "contains",
+				"--expected", tc.expected, "--as", "user",
+			}, f, stdout)
+			if err == nil {
+				t.Fatalf("expected validation error for --expected=%q, got nil", tc.expected)
+			}
+			if !strings.Contains(err.Error(), "--expected must be a JSON array") {
+				t.Fatalf("unexpected error message: %v", err)
+			}
+		})
+	}
+}

shortcuts/sheets/shortcuts.go

@@ -26,5 +26,19 @@ func Shortcuts() []common.Shortcut {
 		SheetUpdateDimension,
 		SheetMoveDimension,
 		SheetDeleteDimension,
+		SheetCreateFilterView,
+		SheetUpdateFilterView,
+		SheetListFilterViews,
+		SheetGetFilterView,
+		SheetDeleteFilterView,
+		SheetCreateFilterViewCondition,
+		SheetUpdateFilterViewCondition,
+		SheetListFilterViewConditions,
+		SheetGetFilterViewCondition,
+		SheetDeleteFilterViewCondition,
+		SheetSetDropdown,
+		SheetUpdateDropdown,
+		SheetGetDropdown,
+		SheetDeleteDropdown,
 	}
 }

shortcuts/task/shortcuts.go

@@ -223,6 +223,7 @@ func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		CreateTask,
 		UpdateTask,
+		SetAncestorTask,
 		CommentTask,
 		CompleteTask,
 		ReopenTask,
@@ -230,7 +231,11 @@ func Shortcuts() []common.Shortcut {
 		FollowersTask,
 		ReminderTask,
 		GetMyTasks,
+		GetRelatedTasks,
+		SearchTask,
+		SubscribeTaskEvent,
 		CreateTasklist,
+		SearchTasklist,
 		AddTaskToTasklist,
 		MembersTasklist,
 	}

shortcuts/task/task_get_related_tasks.go

@@ -0,0 +1,155 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	relatedTasksDefaultPageLimit = 20
+	relatedTasksMaxPageLimit     = 40
+	relatedTasksPageSize         = 100
+)
+
+var GetRelatedTasks = common.Shortcut{
+	Service:     "task",
+	Command:     "+get-related-tasks",
+	Description: "list tasks related to me",
+	Risk:        "read",
+	Scopes:      []string{"task:task:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "include-complete", Type: "bool", Desc: "default true; set false to return only incomplete tasks"},
+		{Name: "page-all", Type: "bool", Desc: "automatically paginate through all pages (max 40)"},
+		{Name: "page-limit", Type: "int", Default: "20", Desc: "max page limit (default 20, max 40)"},
+		{Name: "page-token", Desc: "page token / updated_at cursor in microseconds"},
+		{Name: "created-by-me", Type: "bool", Desc: "client-side filter to tasks created by me; pagination still follows upstream related-task pages"},
+		{Name: "followed-by-me", Type: "bool", Desc: "client-side filter to tasks followed by me; pagination still follows upstream related-task pages"},
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		params := map[string]interface{}{
+			"user_id_type": "open_id",
+			"page_size":    relatedTasksPageSize,
+		}
+		if runtime.Cmd.Flags().Changed("include-complete") && !runtime.Bool("include-complete") {
+			params["completed"] = false
+		}
+		if pageToken := runtime.Str("page-token"); pageToken != "" {
+			params["page_token"] = pageToken
+		}
+		return common.NewDryRunAPI().
+			GET("/open-apis/task/v2/task_v2/list_related_task").
+			Params(params)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		queryParams := make(larkcore.QueryParams)
+		queryParams.Set("user_id_type", "open_id")
+		queryParams.Set("page_size", fmt.Sprintf("%d", relatedTasksPageSize))
+		if runtime.Cmd.Flags().Changed("include-complete") && !runtime.Bool("include-complete") {
+			queryParams.Set("completed", "false")
+		}
+		if pageToken := runtime.Str("page-token"); pageToken != "" {
+			queryParams.Set("page_token", pageToken)
+		}
+
+		pageLimit := runtime.Int("page-limit")
+		if pageLimit <= 0 {
+			pageLimit = relatedTasksDefaultPageLimit
+		}
+		if runtime.Bool("page-all") {
+			pageLimit = relatedTasksMaxPageLimit
+		}
+		if pageLimit > relatedTasksMaxPageLimit {
+			pageLimit = relatedTasksMaxPageLimit
+		}
+
+		var allItems []interface{}
+		var lastPageToken string
+		var lastHasMore bool
+		for page := 0; page < pageLimit; page++ {
+			apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+				HttpMethod:  http.MethodGet,
+				ApiPath:     "/open-apis/task/v2/task_v2/list_related_task",
+				QueryParams: queryParams,
+			})
+			var result map[string]interface{}
+			if err == nil {
+				if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
+					return WrapTaskError(ErrCodeTaskInternalError, fmt.Sprintf("failed to parse response: %v", parseErr), "parse related tasks")
+				}
+			}
+			data, err := HandleTaskApiResult(result, err, "list related tasks")
+			if err != nil {
+				return err
+			}
+
+			items, _ := data["items"].([]interface{})
+			allItems = append(allItems, items...)
+			lastHasMore, _ = data["has_more"].(bool)
+			lastPageToken, _ = data["page_token"].(string)
+			if !lastHasMore || lastPageToken == "" {
+				break
+			}
+			queryParams.Set("page_token", lastPageToken)
+		}
+
+		userOpenID := runtime.UserOpenId()
+		filtered := make([]map[string]interface{}, 0, len(allItems))
+		for _, item := range allItems {
+			task, ok := item.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			if runtime.Bool("created-by-me") {
+				creator, _ := task["creator"].(map[string]interface{})
+				if creatorID, _ := creator["id"].(string); creatorID != userOpenID {
+					continue
+				}
+			}
+			if runtime.Bool("followed-by-me") && !taskFollowedBy(task, userOpenID) {
+				continue
+			}
+			filtered = append(filtered, outputRelatedTask(task))
+		}
+
+		outData := map[string]interface{}{
+			"items":      filtered,
+			"page_token": lastPageToken,
+			"has_more":   lastHasMore,
+		}
+		runtime.OutFormat(outData, &output.Meta{Count: len(filtered)}, func(w io.Writer) {
+			if len(filtered) == 0 {
+				fmt.Fprintln(w, "No related tasks found.")
+				return
+			}
+			io.WriteString(w, renderRelatedTasksPretty(filtered, lastHasMore, lastPageToken))
+		})
+		return nil
+	},
+}
+
+func taskFollowedBy(task map[string]interface{}, userOpenID string) bool {
+	members, _ := task["members"].([]interface{})
+	for _, member := range members {
+		memberObj, _ := member.(map[string]interface{})
+		role, _ := memberObj["role"].(string)
+		id, _ := memberObj["id"].(string)
+		if strings.EqualFold(role, "follower") && id == userOpenID {
+			return true
+		}
+	}
+	return false
+}

shortcuts/task/task_get_related_tasks_test.go

@@ -0,0 +1,207 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestTaskFollowedBy(t *testing.T) {
+	tests := []struct {
+		name       string
+		task       map[string]interface{}
+		userOpenID string
+		want       bool
+	}{
+		{
+			name: "contains follower",
+			task: map[string]interface{}{
+				"members": []interface{}{
+					map[string]interface{}{"id": "ou_1", "role": "assignee"},
+					map[string]interface{}{"id": "ou_2", "role": "follower"},
+				},
+			},
+			userOpenID: "ou_2",
+			want:       true,
+		},
+		{
+			name: "missing follower",
+			task: map[string]interface{}{
+				"members": []interface{}{
+					map[string]interface{}{"id": "ou_1", "role": "assignee"},
+				},
+			},
+			userOpenID: "ou_3",
+			want:       false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := taskFollowedBy(tt.task, tt.userOpenID)
+			if got != tt.want {
+				t.Fatalf("taskFollowedBy() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestGetRelatedTasks_DryRun(t *testing.T) {
+	tests := []struct {
+		name      string
+		setup     func(*cobra.Command)
+		wantParts []string
+	}{
+		{
+			name: "with page token and incomplete filter",
+			setup: func(cmd *cobra.Command) {
+				_ = cmd.Flags().Set("include-complete", "false")
+				_ = cmd.Flags().Set("page-token", "pt_001")
+			},
+			wantParts: []string{"GET /open-apis/task/v2/task_v2/list_related_task", "page_token=pt_001", "completed=false"},
+		},
+		{
+			name:      "default query params",
+			setup:     func(cmd *cobra.Command) {},
+			wantParts: []string{"GET /open-apis/task/v2/task_v2/list_related_task", "page_size=100", "user_id_type=open_id"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().Bool("include-complete", true, "")
+			cmd.Flags().String("page-token", "", "")
+			tt.setup(cmd)
+			runtime := common.TestNewRuntimeContextWithIdentity(cmd, taskTestConfig(t), "user")
+			out := GetRelatedTasks.DryRun(nil, runtime).Format()
+			for _, want := range tt.wantParts {
+				if !strings.Contains(out, want) {
+					t.Fatalf("dry run output missing %q: %s", want, out)
+				}
+			}
+		})
+	}
+}
+
+func TestGetRelatedTasks_Execute(t *testing.T) {
+	tests := []struct {
+		name      string
+		args      []string
+		register  func(*httpmock.Registry)
+		wantParts []string
+	}{
+		{
+			name: "json created by me",
+			args: []string{"+get-related-tasks", "--as", "bot", "--format", "json", "--created-by-me"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "GET",
+					URL:    "/open-apis/task/v2/task_v2/list_related_task",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"has_more":   false,
+							"page_token": "",
+							"items": []interface{}{
+								map[string]interface{}{
+									"guid":          "task-123",
+									"summary":       "Related Task",
+									"description":   "desc",
+									"status":        "done",
+									"source":        1,
+									"mode":          2,
+									"subtask_count": 0,
+									"tasklists":     []interface{}{},
+									"url":           "https://example.com/task-123",
+									"creator":       map[string]interface{}{"id": "ou_testuser", "type": "user"},
+								},
+							},
+						},
+					},
+				})
+			},
+			wantParts: []string{`"guid": "task-123"`, `"summary": "Related Task"`},
+		},
+		{
+			name: "pretty pagination followed by me",
+			args: []string{"+get-related-tasks", "--as", "bot", "--format", "pretty", "--followed-by-me", "--page-limit", "2"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "GET",
+					URL:    "/open-apis/task/v2/task_v2/list_related_task",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"has_more":   true,
+							"page_token": "pt_2",
+							"items": []interface{}{
+								map[string]interface{}{
+									"guid":    "task-1",
+									"summary": "Task One",
+									"url":     "https://example.com/task-1",
+									"creator": map[string]interface{}{"id": "ou_other", "type": "user"},
+									"members": []interface{}{map[string]interface{}{"id": "ou_testuser", "role": "follower"}},
+								},
+							},
+						},
+					},
+				})
+				reg.Register(&httpmock.Stub{
+					Method: "GET",
+					URL:    "page_token=pt_2",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"has_more":   false,
+							"page_token": "",
+							"items": []interface{}{
+								map[string]interface{}{
+									"guid":    "task-2",
+									"summary": "Task Two",
+									"url":     "https://example.com/task-2",
+									"creator": map[string]interface{}{"id": "ou_other", "type": "user"},
+									"members": []interface{}{map[string]interface{}{"id": "ou_testuser", "role": "follower"}},
+								},
+							},
+						},
+					},
+				})
+			},
+			wantParts: []string{"Task One", "Task Two"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, stdout, _, reg := taskShortcutTestFactory(t)
+			warmTenantToken(t, f, reg)
+			tt.register(reg)
+
+			s := GetRelatedTasks
+			s.AuthTypes = []string{"bot", "user"}
+			err := runMountedTaskShortcut(t, s, tt.args, f, stdout)
+			if err != nil {
+				t.Fatalf("runMountedTaskShortcut() error = %v", err)
+			}
+
+			out := stdout.String()
+			outNorm := strings.ReplaceAll(out, `":"`, `": "`)
+			for _, want := range tt.wantParts {
+				if !strings.Contains(out, want) && !strings.Contains(outNorm, want) {
+					t.Fatalf("output missing %q: %s", want, out)
+				}
+			}
+		})
+	}
+}

shortcuts/task/task_query_helpers.go

@@ -0,0 +1,247 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+func splitAndTrimCSV(input string) []string {
+	parts := strings.Split(input, ",")
+	out := make([]string, 0, len(parts))
+	for _, part := range parts {
+		part = strings.TrimSpace(part)
+		if part != "" {
+			out = append(out, part)
+		}
+	}
+	return out
+}
+
+func parseTimeRangeMillis(input string) (string, string, error) {
+	if strings.TrimSpace(input) == "" {
+		return "", "", nil
+	}
+
+	parts := strings.SplitN(input, ",", 2)
+	startInput := strings.TrimSpace(parts[0])
+	endInput := ""
+	if len(parts) == 2 {
+		endInput = strings.TrimSpace(parts[1])
+	}
+
+	var startMillis, endMillis string
+	var startSecInt, endSecInt int64
+	var hasStart, hasEnd bool
+	if startInput != "" {
+		startSec, err := parseTimeFlagSec(startInput, "start")
+		if err != nil {
+			return "", "", err
+		}
+		startSecInt, err = strconv.ParseInt(startSec, 10, 64)
+		if err != nil {
+			return "", "", fmt.Errorf("invalid start timestamp: %w", err)
+		}
+		hasStart = true
+		startMillis = startSec + "000"
+	}
+	if endInput != "" {
+		endSec, err := parseTimeFlagSec(endInput, "end")
+		if err != nil {
+			return "", "", err
+		}
+		endSecInt, err = strconv.ParseInt(endSec, 10, 64)
+		if err != nil {
+			return "", "", fmt.Errorf("invalid end timestamp: %w", err)
+		}
+		hasEnd = true
+		endMillis = endSec + "000"
+	}
+	if hasStart && hasEnd && startSecInt > endSecInt {
+		return "", "", fmt.Errorf("start time must be earlier than or equal to end time")
+	}
+	return startMillis, endMillis, nil
+}
+
+func parseTimeRangeRFC3339(input string) (string, string, error) {
+	if strings.TrimSpace(input) == "" {
+		return "", "", nil
+	}
+
+	parts := strings.SplitN(input, ",", 2)
+	startInput := strings.TrimSpace(parts[0])
+	endInput := ""
+	if len(parts) == 2 {
+		endInput = strings.TrimSpace(parts[1])
+	}
+
+	var startTime, endTime string
+	var startSecInt, endSecInt int64
+	var hasStart, hasEnd bool
+	if startInput != "" {
+		startSec, err := parseTimeFlagSec(startInput, "start")
+		if err != nil {
+			return "", "", err
+		}
+		startSecInt, err = strconv.ParseInt(startSec, 10, 64)
+		if err != nil {
+			return "", "", fmt.Errorf("invalid start timestamp: %w", err)
+		}
+		hasStart = true
+		startTime = time.Unix(startSecInt, 0).Local().Format(time.RFC3339)
+	}
+	if endInput != "" {
+		endSec, err := parseTimeFlagSec(endInput, "end")
+		if err != nil {
+			return "", "", err
+		}
+		endSecInt, err = strconv.ParseInt(endSec, 10, 64)
+		if err != nil {
+			return "", "", fmt.Errorf("invalid end timestamp: %w", err)
+		}
+		hasEnd = true
+		endTime = time.Unix(endSecInt, 0).Local().Format(time.RFC3339)
+	}
+	if hasStart && hasEnd && startSecInt > endSecInt {
+		return "", "", fmt.Errorf("start time must be earlier than or equal to end time")
+	}
+	return startTime, endTime, nil
+}
+
+func formatTaskDateTimeMillis(msStr string) string {
+	if msStr == "" || msStr == "0" {
+		return ""
+	}
+	ms, err := strconv.ParseInt(msStr, 10, 64)
+	if err != nil {
+		return ""
+	}
+	return time.UnixMilli(ms).Local().Format(time.DateTime)
+}
+
+func outputTaskSummary(task map[string]interface{}) map[string]interface{} {
+	urlVal, _ := task["url"].(string)
+	urlVal = truncateTaskURL(urlVal)
+
+	out := map[string]interface{}{
+		"guid":    task["guid"],
+		"summary": task["summary"],
+		"url":     urlVal,
+	}
+	if createdAt, _ := task["created_at"].(string); createdAt != "" {
+		if created := formatTaskDateTimeMillis(createdAt); created != "" {
+			out["created_at"] = created
+		}
+	}
+	if completedAt, _ := task["completed_at"].(string); completedAt != "" {
+		if completed := formatTaskDateTimeMillis(completedAt); completed != "" {
+			out["completed_at"] = completed
+		}
+	}
+	if updatedAt, _ := task["updated_at"].(string); updatedAt != "" {
+		if updated := formatTaskDateTimeMillis(updatedAt); updated != "" {
+			out["updated_at"] = updated
+		}
+	}
+	if dueObj, ok := task["due"].(map[string]interface{}); ok {
+		if tsStr, _ := dueObj["timestamp"].(string); tsStr != "" {
+			if dueAt := formatTaskDateTimeMillis(tsStr); dueAt != "" {
+				out["due_at"] = dueAt
+			}
+		}
+	}
+	return out
+}
+
+func outputRelatedTask(task map[string]interface{}) map[string]interface{} {
+	urlVal, _ := task["url"].(string)
+	urlVal = truncateTaskURL(urlVal)
+
+	out := map[string]interface{}{
+		"guid":          task["guid"],
+		"summary":       task["summary"],
+		"description":   task["description"],
+		"status":        task["status"],
+		"source":        task["source"],
+		"mode":          task["mode"],
+		"subtask_count": task["subtask_count"],
+		"tasklists":     task["tasklists"],
+		"url":           urlVal,
+	}
+	if creator, ok := task["creator"].(map[string]interface{}); ok {
+		out["creator"] = creator
+	}
+	if members, ok := task["members"].([]interface{}); ok {
+		out["members"] = members
+	}
+	if createdAt, _ := task["created_at"].(string); createdAt != "" {
+		if created := formatTaskDateTimeMillis(createdAt); created != "" {
+			out["created_at"] = created
+		}
+	}
+	if completedAt, _ := task["completed_at"].(string); completedAt != "" {
+		if completed := formatTaskDateTimeMillis(completedAt); completed != "" {
+			out["completed_at"] = completed
+		}
+	}
+	return out
+}
+
+func buildTimeRangeFilter(key, start, end string) map[string]interface{} {
+	timeRange := map[string]interface{}{}
+	if start != "" {
+		timeRange["start_time"] = start
+	}
+	if end != "" {
+		timeRange["end_time"] = end
+	}
+	if len(timeRange) == 0 {
+		return nil
+	}
+	return map[string]interface{}{key: timeRange}
+}
+
+func mergeIntoFilter(dst map[string]interface{}, src map[string]interface{}) {
+	for k, v := range src {
+		dst[k] = v
+	}
+}
+
+func requireSearchFilter(query string, filter map[string]interface{}, action string) error {
+	if strings.TrimSpace(query) != "" {
+		return nil
+	}
+	if len(filter) > 0 {
+		return nil
+	}
+	return WrapTaskError(ErrCodeTaskInvalidParams, "query is empty and no filter is provided", action)
+}
+
+func renderRelatedTasksPretty(items []map[string]interface{}, hasMore bool, pageToken string) string {
+	var b strings.Builder
+	for i, item := range items {
+		fmt.Fprintf(&b, "[%d] %v\n", i+1, item["summary"])
+		fmt.Fprintf(&b, "    GUID: %v\n", item["guid"])
+		if status, _ := item["status"].(string); status != "" {
+			fmt.Fprintf(&b, "    Status: %s\n", status)
+		}
+		if created, _ := item["created_at"].(string); created != "" {
+			fmt.Fprintf(&b, "    Created: %s\n", created)
+		}
+		if completed, _ := item["completed_at"].(string); completed != "" {
+			fmt.Fprintf(&b, "    Completed: %s\n", completed)
+		}
+		if urlVal, _ := item["url"].(string); urlVal != "" {
+			fmt.Fprintf(&b, "    URL: %s\n", urlVal)
+		}
+		b.WriteString("\n")
+	}
+	if hasMore && pageToken != "" {
+		fmt.Fprintf(&b, "Next page token: %s\n", pageToken)
+	}
+	return b.String()
+}

shortcuts/task/task_query_helpers_test.go

@@ -0,0 +1,286 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestSplitAndTrimCSV(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  []string
+	}{
+		{name: "trim blanks", input: " a, ,b , c ", want: []string{"a", "b", "c"}},
+		{name: "empty input", input: "", want: []string{}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := splitAndTrimCSV(tt.input)
+			if len(got) != len(tt.want) {
+				t.Fatalf("len(splitAndTrimCSV(%q)) = %d, want %d", tt.input, len(got), len(tt.want))
+			}
+			for i := range got {
+				if got[i] != tt.want[i] {
+					t.Fatalf("splitAndTrimCSV(%q)[%d] = %q, want %q", tt.input, i, got[i], tt.want[i])
+				}
+			}
+		})
+	}
+}
+
+func TestOutputTaskSummary(t *testing.T) {
+	tests := []struct {
+		name string
+		task map[string]interface{}
+	}{
+		{
+			name: "with timestamps and due",
+			task: map[string]interface{}{
+				"guid":       "task-123",
+				"summary":    "summary",
+				"url":        "https://example.com/task-123&suite_entity_num=t1",
+				"created_at": "1775174400000",
+				"due": map[string]interface{}{
+					"timestamp": "1775174400000",
+				},
+			},
+		},
+		{
+			name: "with completed and updated",
+			task: map[string]interface{}{
+				"guid":         "task-456",
+				"summary":      "done",
+				"url":          "https://example.com/task-456",
+				"completed_at": "1775174400000",
+				"updated_at":   "1775174400000",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := outputTaskSummary(tt.task)
+			if got["guid"] != tt.task["guid"] || got["summary"] != tt.task["summary"] {
+				t.Fatalf("unexpected summary output: %#v", got)
+			}
+			if got["url"] == "" {
+				t.Fatalf("expected url in output, got %#v", got)
+			}
+		})
+	}
+}
+
+func TestParseTimeRangeMillisAndRequireSearchFilter(t *testing.T) {
+	timeTests := []struct {
+		name      string
+		input     string
+		wantErr   bool
+		wantStart string
+		wantEnd   string
+	}{
+		{name: "empty input", input: "", wantStart: "", wantEnd: ""},
+		{name: "invalid input", input: "bad-time", wantErr: true},
+		{name: "range input", input: "-1d,+1d", wantStart: "non-empty", wantEnd: "non-empty"},
+		{name: "reversed range fails fast", input: "+1d,-1d", wantErr: true},
+	}
+	for _, tt := range timeTests {
+		t.Run("parse:"+tt.name, func(t *testing.T) {
+			start, end, err := parseTimeRangeMillis(tt.input)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatalf("parseTimeRangeMillis(%q) expected error, got nil", tt.input)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("parseTimeRangeMillis(%q) error = %v", tt.input, err)
+			}
+			if tt.wantStart == "" && start != "" {
+				t.Fatalf("start = %q, want empty", start)
+			}
+			if tt.wantEnd == "" && end != "" {
+				t.Fatalf("end = %q, want empty", end)
+			}
+			if tt.wantStart == "non-empty" && start == "" {
+				t.Fatalf("start should not be empty")
+			}
+			if tt.wantEnd == "non-empty" && end == "" {
+				t.Fatalf("end should not be empty")
+			}
+		})
+	}
+
+	filterTests := []struct {
+		name    string
+		query   string
+		filter  map[string]interface{}
+		wantErr bool
+	}{
+		{name: "missing query and filter", query: "", filter: map[string]interface{}{}, wantErr: true},
+		{name: "query only", query: "query", filter: map[string]interface{}{}, wantErr: false},
+		{name: "filter only", query: "", filter: map[string]interface{}{"creator_ids": []string{"ou_1"}}, wantErr: false},
+	}
+	for _, tt := range filterTests {
+		t.Run("filter:"+tt.name, func(t *testing.T) {
+			err := requireSearchFilter(tt.query, tt.filter, "search")
+			if tt.wantErr && err == nil {
+				t.Fatalf("expected error, got nil")
+			}
+			if !tt.wantErr && err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+		})
+	}
+}
+
+func TestOutputRelatedTaskAndTimeRangeFilter(t *testing.T) {
+	outputTests := []struct {
+		name string
+		task map[string]interface{}
+	}{
+		{
+			name: "full related task",
+			task: map[string]interface{}{
+				"guid":          "task-123",
+				"summary":       "Related Task",
+				"description":   "desc",
+				"status":        "todo",
+				"source":        1,
+				"mode":          2,
+				"subtask_count": 0,
+				"tasklists":     []interface{}{},
+				"url":           "https://example.com/task-123&suite_entity_num=t1",
+				"creator":       map[string]interface{}{"id": "ou_1"},
+				"members":       []interface{}{map[string]interface{}{"id": "ou_2", "role": "follower"}},
+				"created_at":    "1775174400000",
+				"completed_at":  "1775174400000",
+			},
+		},
+		{
+			name: "minimal related task",
+			task: map[string]interface{}{
+				"guid":    "task-456",
+				"summary": "Minimal",
+				"url":     "https://example.com/task-456",
+			},
+		},
+	}
+	for _, tt := range outputTests {
+		t.Run("output:"+tt.name, func(t *testing.T) {
+			got := outputRelatedTask(tt.task)
+			if got["guid"] != tt.task["guid"] || got["summary"] != tt.task["summary"] {
+				t.Fatalf("unexpected related task output: %#v", got)
+			}
+		})
+	}
+
+	rangeTests := []struct {
+		name    string
+		start   string
+		end     string
+		wantNil bool
+	}{
+		{name: "empty range", start: "", end: "", wantNil: true},
+		{name: "full range", start: "1", end: "2", wantNil: false},
+	}
+	for _, tt := range rangeTests {
+		t.Run("range:"+tt.name, func(t *testing.T) {
+			got := buildTimeRangeFilter("due_time", tt.start, tt.end)
+			if tt.wantNil && got != nil {
+				t.Fatalf("expected nil, got %#v", got)
+			}
+			if !tt.wantNil && got == nil {
+				t.Fatalf("expected range filter, got nil")
+			}
+		})
+	}
+}
+
+func TestRenderRelatedTasksPretty(t *testing.T) {
+	tests := []struct {
+		name      string
+		items     []map[string]interface{}
+		hasMore   bool
+		pageToken string
+		wantParts []string
+	}{
+		{
+			name: "includes next token",
+			items: []map[string]interface{}{
+				{"guid": "task-123", "summary": "Related Task", "url": "https://example.com/task-123"},
+			},
+			hasMore:   true,
+			pageToken: "pt_123",
+			wantParts: []string{"Related Task", "Next page token: pt_123"},
+		},
+		{
+			name: "without next token",
+			items: []map[string]interface{}{
+				{"guid": "task-456", "summary": "Another Task"},
+			},
+			hasMore:   false,
+			pageToken: "",
+			wantParts: []string{"Another Task"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			out := renderRelatedTasksPretty(tt.items, tt.hasMore, tt.pageToken)
+			for _, want := range tt.wantParts {
+				if !strings.Contains(out, want) {
+					t.Fatalf("output missing %q: %s", want, out)
+				}
+			}
+		})
+
+		t.Run("parseTimeRangeRFC3339", func(t *testing.T) {
+			timeTests := []struct {
+				name      string
+				input     string
+				wantErr   bool
+				wantStart string
+				wantEnd   string
+			}{
+				{name: "empty input", input: "", wantStart: "", wantEnd: ""},
+				{name: "invalid input", input: "bad-time", wantErr: true},
+				{name: "range input", input: "-1d,+1d", wantStart: "rfc3339", wantEnd: "rfc3339"},
+				{name: "reversed range fails fast", input: "+1d,-1d", wantErr: true},
+			}
+
+			for _, tt := range timeTests {
+				t.Run(tt.name, func(t *testing.T) {
+					start, end, err := parseTimeRangeRFC3339(tt.input)
+					if tt.wantErr {
+						if err == nil {
+							t.Fatal("expected error, got nil")
+						}
+						return
+					}
+					if err != nil {
+						t.Fatalf("parseTimeRangeRFC3339() error = %v", err)
+					}
+					if tt.wantStart == "rfc3339" {
+						if !strings.Contains(start, "T") || !strings.Contains(start, ":") {
+							t.Fatalf("expected RFC3339 start, got %q", start)
+						}
+					} else if start != tt.wantStart {
+						t.Fatalf("unexpected start: %q", start)
+					}
+					if tt.wantEnd == "rfc3339" {
+						if !strings.Contains(end, "T") || !strings.Contains(end, ":") {
+							t.Fatalf("expected RFC3339 end, got %q", end)
+						}
+					} else if end != tt.wantEnd {
+						t.Fatalf("unexpected end: %q", end)
+					}
+				})
+			}
+		})
+	}
+}

shortcuts/task/task_search.go

@@ -0,0 +1,222 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	taskSearchDefaultPageLimit = 20
+	taskSearchMaxPageLimit     = 40
+)
+
+var SearchTask = common.Shortcut{
+	Service:     "task",
+	Command:     "+search",
+	Description: "search tasks",
+	Risk:        "read",
+	Scopes:      []string{"task:task:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "query", Desc: "search keyword"},
+		{Name: "page-all", Type: "bool", Desc: "automatically paginate through all pages (max 40)"},
+		{Name: "page-limit", Type: "int", Default: "20", Desc: "max page limit (default 20, max 40)"},
+		{Name: "page-token", Desc: "page token"},
+		{Name: "creator", Desc: "creator open_ids, comma-separated"},
+		{Name: "assignee", Desc: "assignee open_ids, comma-separated"},
+		{Name: "completed", Type: "bool", Desc: "set true for completed or false for incomplete tasks"},
+		{Name: "due", Desc: "due time range: start,end (supports ISO/date/relative/ms)"},
+		{Name: "follower", Desc: "follower open_ids, comma-separated"},
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		body, err := buildTaskSearchBody(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			POST("/open-apis/task/v2/tasks/search").
+			Body(body).
+			Desc("Then GET /open-apis/task/v2/tasks/:guid for each search hit to render standard output")
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := buildTaskSearchBody(runtime)
+		return err
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		body, err := buildTaskSearchBody(runtime)
+		if err != nil {
+			return err
+		}
+
+		pageLimit := runtime.Int("page-limit")
+		if pageLimit <= 0 {
+			pageLimit = taskSearchDefaultPageLimit
+		}
+		if runtime.Bool("page-all") {
+			pageLimit = taskSearchMaxPageLimit
+		}
+		if pageLimit > taskSearchMaxPageLimit {
+			pageLimit = taskSearchMaxPageLimit
+		}
+
+		var rawItems []interface{}
+		var lastPageToken string
+		var lastHasMore bool
+		currentBody := body
+		for page := 0; page < pageLimit; page++ {
+			apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+				HttpMethod: http.MethodPost,
+				ApiPath:    "/open-apis/task/v2/tasks/search",
+				Body:       currentBody,
+			})
+			var result map[string]interface{}
+			if err == nil {
+				if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
+					return WrapTaskError(ErrCodeTaskInternalError, fmt.Sprintf("failed to parse response: %v", parseErr), "parse task search")
+				}
+			}
+			data, err := HandleTaskApiResult(result, err, "search tasks")
+			if err != nil {
+				return err
+			}
+			items, _ := data["items"].([]interface{})
+			rawItems = append(rawItems, items...)
+			lastHasMore, _ = data["has_more"].(bool)
+			lastPageToken, _ = data["page_token"].(string)
+			if !lastHasMore || lastPageToken == "" {
+				break
+			}
+			currentBody["page_token"] = lastPageToken
+		}
+
+		enriched := make([]map[string]interface{}, 0, len(rawItems))
+		for _, item := range rawItems {
+			itemMap, _ := item.(map[string]interface{})
+			taskID, _ := itemMap["id"].(string)
+			if taskID == "" {
+				continue
+			}
+
+			task, err := getTaskDetail(runtime, taskID)
+			if err != nil {
+				metaData, _ := itemMap["meta_data"].(map[string]interface{})
+				appLink, _ := metaData["app_link"].(string)
+				enriched = append(enriched, map[string]interface{}{
+					"guid": taskID,
+					"url":  truncateTaskURL(appLink),
+				})
+				continue
+			}
+			enriched = append(enriched, outputTaskSummary(task))
+		}
+
+		outData := map[string]interface{}{
+			"items":      enriched,
+			"page_token": lastPageToken,
+			"has_more":   lastHasMore,
+		}
+		runtime.OutFormat(outData, &output.Meta{Count: len(enriched)}, func(w io.Writer) {
+			if len(enriched) == 0 {
+				fmt.Fprintln(w, "No tasks found.")
+				return
+			}
+			for i, item := range enriched {
+				fmt.Fprintf(w, "[%d] %v\n", i+1, item["summary"])
+				fmt.Fprintf(w, "    GUID: %v\n", item["guid"])
+				if created, _ := item["created_at"].(string); created != "" {
+					fmt.Fprintf(w, "    Created: %s\n", created)
+				}
+				if dueAt, _ := item["due_at"].(string); dueAt != "" {
+					fmt.Fprintf(w, "    Due: %s\n", dueAt)
+				}
+				if urlVal, _ := item["url"].(string); urlVal != "" {
+					fmt.Fprintf(w, "    URL: %s\n", urlVal)
+				}
+				fmt.Fprintln(w)
+			}
+			if lastHasMore && lastPageToken != "" {
+				fmt.Fprintf(w, "Next page token: %s\n", lastPageToken)
+			}
+		})
+		return nil
+	},
+}
+
+func buildTaskSearchBody(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	filter := map[string]interface{}{}
+
+	if ids := splitAndTrimCSV(runtime.Str("creator")); len(ids) > 0 {
+		filter["creator_ids"] = ids
+	}
+	if ids := splitAndTrimCSV(runtime.Str("assignee")); len(ids) > 0 {
+		filter["assignee_ids"] = ids
+	}
+	if ids := splitAndTrimCSV(runtime.Str("follower")); len(ids) > 0 {
+		filter["follower_ids"] = ids
+	}
+	if runtime.Cmd.Flags().Changed("completed") {
+		filter["is_completed"] = runtime.Bool("completed")
+	}
+	if dueRange := runtime.Str("due"); dueRange != "" {
+		start, end, err := parseTimeRangeRFC3339(dueRange)
+		if err != nil {
+			return nil, WrapTaskError(ErrCodeTaskInvalidParams, fmt.Sprintf("invalid due: %v", err), "build task search")
+		}
+		if dueFilter := buildTimeRangeFilter("due_time", start, end); dueFilter != nil {
+			mergeIntoFilter(filter, dueFilter)
+		}
+	}
+	if err := requireSearchFilter(runtime.Str("query"), filter, "build task search"); err != nil {
+		return nil, err
+	}
+
+	body := map[string]interface{}{
+		"query": runtime.Str("query"),
+	}
+	if len(filter) > 0 {
+		body["filter"] = filter
+	}
+	if pageToken := runtime.Str("page-token"); pageToken != "" {
+		body["page_token"] = pageToken
+	}
+	return body, nil
+}
+
+func getTaskDetail(runtime *common.RuntimeContext, taskID string) (map[string]interface{}, error) {
+	queryParams := make(larkcore.QueryParams)
+	queryParams.Set("user_id_type", "open_id")
+
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod:  http.MethodGet,
+		ApiPath:     "/open-apis/task/v2/tasks/" + url.PathEscape(taskID),
+		QueryParams: queryParams,
+	})
+	var result map[string]interface{}
+	if err == nil {
+		if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
+			return nil, WrapTaskError(ErrCodeTaskInternalError, fmt.Sprintf("failed to parse task detail response: %v", parseErr), "parse task detail")
+		}
+	}
+	data, err := HandleTaskApiResult(result, err, "get task detail "+taskID)
+	if err != nil {
+		return nil, err
+	}
+	task, _ := data["task"].(map[string]interface{})
+	if task == nil {
+		return nil, WrapTaskError(ErrCodeTaskInternalError, "task detail response missing task object", "get task detail")
+	}
+	return task, nil
+}

shortcuts/task/task_search_test.go

@@ -0,0 +1,300 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestBuildTaskSearchBody(t *testing.T) {
+	tests := []struct {
+		name    string
+		setup   func(*cobra.Command)
+		wantErr bool
+		check   func(*testing.T, map[string]interface{})
+	}{
+		{
+			name: "query creator due and page token",
+			setup: func(cmd *cobra.Command) {
+				_ = cmd.Flags().Set("query", "release")
+				_ = cmd.Flags().Set("creator", "ou_a,ou_b")
+				_ = cmd.Flags().Set("completed", "true")
+				_ = cmd.Flags().Set("due", "-1d,+1d")
+				_ = cmd.Flags().Set("page-token", "pt_123")
+			},
+			check: func(t *testing.T, body map[string]interface{}) {
+				filter := body["filter"].(map[string]interface{})
+				dueTime := filter["due_time"].(map[string]interface{})
+				if body["query"] != "release" || body["page_token"] != "pt_123" {
+					t.Fatalf("unexpected body: %#v", body)
+				}
+				if len(filter["creator_ids"].([]string)) != 2 || filter["is_completed"] != true {
+					t.Fatalf("unexpected filter: %#v", filter)
+				}
+				startTime, _ := dueTime["start_time"].(string)
+				endTime, _ := dueTime["end_time"].(string)
+				if startTime == "" || endTime == "" || !strings.Contains(startTime, "T") || !strings.Contains(endTime, "T") {
+					t.Fatalf("unexpected due_time: %#v", dueTime)
+				}
+			},
+		},
+		{
+			name:    "requires query or filter",
+			setup:   func(cmd *cobra.Command) {},
+			wantErr: true,
+		},
+		{
+			name: "assignee follower and incomplete",
+			setup: func(cmd *cobra.Command) {
+				_ = cmd.Flags().Set("assignee", "ou_assignee")
+				_ = cmd.Flags().Set("follower", "ou_follower")
+				_ = cmd.Flags().Set("completed", "false")
+			},
+			check: func(t *testing.T, body map[string]interface{}) {
+				filter := body["filter"].(map[string]interface{})
+				if filter["assignee_ids"].([]string)[0] != "ou_assignee" || filter["follower_ids"].([]string)[0] != "ou_follower" {
+					t.Fatalf("unexpected filter: %#v", filter)
+				}
+				if filter["is_completed"] != false {
+					t.Fatalf("expected is_completed false, got %#v", filter["is_completed"])
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("query", "", "")
+			cmd.Flags().String("creator", "", "")
+			cmd.Flags().String("assignee", "", "")
+			cmd.Flags().String("follower", "", "")
+			cmd.Flags().Bool("completed", false, "")
+			cmd.Flags().String("due", "", "")
+			cmd.Flags().String("page-token", "", "")
+			tt.setup(cmd)
+
+			runtime := common.TestNewRuntimeContextWithIdentity(cmd, taskTestConfig(t), "user")
+			body, err := buildTaskSearchBody(runtime)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatal("expected error, got nil")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("buildTaskSearchBody() error = %v", err)
+			}
+			tt.check(t, body)
+		})
+	}
+}
+
+func TestSearchTask_DryRun(t *testing.T) {
+	tests := []struct {
+		name      string
+		setup     func(*cobra.Command)
+		wantParts []string
+	}{
+		{
+			name: "valid dry run",
+			setup: func(cmd *cobra.Command) {
+				_ = cmd.Flags().Set("query", "demo")
+				_ = cmd.Flags().Set("page-token", "pt_demo")
+			},
+			wantParts: []string{"POST /open-apis/task/v2/tasks/search", `"query":"demo"`},
+		},
+		{
+			name: "dry run error on invalid due",
+			setup: func(cmd *cobra.Command) {
+				_ = cmd.Flags().Set("due", "bad-time")
+			},
+			wantParts: []string{"error:"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("query", "", "")
+			cmd.Flags().String("creator", "", "")
+			cmd.Flags().String("assignee", "", "")
+			cmd.Flags().String("follower", "", "")
+			cmd.Flags().Bool("completed", false, "")
+			cmd.Flags().String("due", "", "")
+			cmd.Flags().String("page-token", "", "")
+			tt.setup(cmd)
+
+			runtime := common.TestNewRuntimeContextWithIdentity(cmd, taskTestConfig(t), "user")
+			if !strings.Contains(tt.name, "error") {
+				if err := SearchTask.Validate(nil, runtime); err != nil {
+					t.Fatalf("Validate() error = %v", err)
+				}
+			}
+			out := SearchTask.DryRun(nil, runtime).Format()
+			for _, want := range tt.wantParts {
+				if !strings.Contains(out, want) {
+					t.Fatalf("dry run output missing %q: %s", want, out)
+				}
+			}
+		})
+	}
+}
+
+func TestSearchTask_Execute(t *testing.T) {
+	tests := []struct {
+		name      string
+		args      []string
+		register  func(*httpmock.Registry)
+		wantParts []string
+	}{
+		{
+			name: "json success",
+			args: []string{"+search", "--query", "release", "--as", "bot", "--format", "json"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasks/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"has_more":   false,
+							"page_token": "",
+							"items": []interface{}{
+								map[string]interface{}{"id": "task-123", "meta_data": map[string]interface{}{"app_link": "https://example.com/task-123"}},
+							},
+						},
+					},
+				})
+				reg.Register(&httpmock.Stub{
+					Method: "GET",
+					URL:    "/open-apis/task/v2/tasks/task-123",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"task": map[string]interface{}{"guid": "task-123", "summary": "Search Result", "created_at": "1775174400000", "url": "https://example.com/task-123"},
+						},
+					},
+				})
+			},
+			wantParts: []string{`"guid": "task-123"`, `"summary": "Search Result"`},
+		},
+		{
+			name: "fallback to app link",
+			args: []string{"+search", "--query", "fallback", "--as", "bot", "--format", "json"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasks/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"has_more":   false,
+							"page_token": "",
+							"items": []interface{}{
+								map[string]interface{}{"id": "task-999", "meta_data": map[string]interface{}{"app_link": "https://example.com/task-999&suite_entity_num=t999"}},
+							},
+						},
+					},
+				})
+				reg.Register(&httpmock.Stub{
+					Method: "GET",
+					URL:    "/open-apis/task/v2/tasks/task-999",
+					Body:   map[string]interface{}{"code": 99991663, "msg": "not found"},
+				})
+			},
+			wantParts: []string{`"guid": "task-999"`, `"url": "https://example.com/task-999"`},
+		},
+		{
+			name: "empty pretty with pagination",
+			args: []string{"+search", "--query", "none", "--as", "bot", "--format", "pretty", "--page-limit", "2"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasks/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{"has_more": true, "page_token": "pt_2", "items": []interface{}{}},
+					},
+				})
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasks/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{"has_more": false, "page_token": "", "items": []interface{}{}},
+					},
+				})
+			},
+			wantParts: []string{"No tasks found."},
+		},
+		{
+			name: "pretty with next page token",
+			args: []string{"+search", "--query", "pretty", "--as", "bot", "--format", "pretty", "--page-limit", "1"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasks/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"has_more":   true,
+							"page_token": "pt_next",
+							"items": []interface{}{
+								map[string]interface{}{"id": "task-321", "meta_data": map[string]interface{}{"app_link": "https://example.com/task-321"}},
+							},
+						},
+					},
+				})
+				reg.Register(&httpmock.Stub{
+					Method: "GET",
+					URL:    "/open-apis/task/v2/tasks/task-321",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"task": map[string]interface{}{"guid": "task-321", "summary": "Pretty Search", "url": "https://example.com/task-321"},
+						},
+					},
+				})
+			},
+			wantParts: []string{"Pretty Search", "Next page token: pt_next"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, stdout, _, reg := taskShortcutTestFactory(t)
+			warmTenantToken(t, f, reg)
+			tt.register(reg)
+
+			s := SearchTask
+			s.AuthTypes = []string{"bot", "user"}
+			err := runMountedTaskShortcut(t, s, tt.args, f, stdout)
+			if err != nil {
+				t.Fatalf("runMountedTaskShortcut() error = %v", err)
+			}
+
+			out := stdout.String()
+			outNorm := strings.ReplaceAll(out, `":"`, `": "`)
+			for _, want := range tt.wantParts {
+				if !strings.Contains(out, want) && !strings.Contains(outNorm, want) {
+					t.Fatalf("output missing %q: %s", want, out)
+				}
+			}
+		})
+	}
+}

shortcuts/task/task_set_ancestor.go

@@ -0,0 +1,84 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var SetAncestorTask = common.Shortcut{
+	Service:     "task",
+	Command:     "+set-ancestor",
+	Description: "set or clear a task ancestor",
+	Risk:        "write",
+	Scopes:      []string{"task:task:write"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "task-id", Desc: "task guid to update", Required: true},
+		{Name: "ancestor-id", Desc: "ancestor task guid; omit to make it independent"},
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		taskID := url.PathEscape(runtime.Str("task-id"))
+		return common.NewDryRunAPI().
+			POST("/open-apis/task/v2/tasks/" + taskID + "/set_ancestor_task").
+			Params(map[string]interface{}{"user_id_type": "open_id"}).
+			Body(buildSetAncestorBody(runtime.Str("ancestor-id")))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		taskID := runtime.Str("task-id")
+		queryParams := make(larkcore.QueryParams)
+		queryParams.Set("user_id_type", "open_id")
+
+		apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+			HttpMethod:  http.MethodPost,
+			ApiPath:     "/open-apis/task/v2/tasks/" + url.PathEscape(taskID) + "/set_ancestor_task",
+			QueryParams: queryParams,
+			Body:        buildSetAncestorBody(runtime.Str("ancestor-id")),
+		})
+		var result map[string]interface{}
+		if err == nil {
+			if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
+				return WrapTaskError(ErrCodeTaskInternalError, fmt.Sprintf("failed to parse response: %v", parseErr), "set ancestor task")
+			}
+		}
+		if _, err = HandleTaskApiResult(result, err, "set ancestor task"); err != nil {
+			return err
+		}
+
+		outData := map[string]interface{}{
+			"ok": true,
+			"data": map[string]interface{}{
+				"guid": taskID,
+			},
+		}
+		runtime.OutFormat(outData, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "✅ Task ancestor updated successfully!\nTask ID: %s\n", taskID)
+			if ancestorID := runtime.Str("ancestor-id"); ancestorID != "" {
+				fmt.Fprintf(w, "Ancestor ID: %s\n", ancestorID)
+			} else {
+				fmt.Fprintln(w, "Ancestor cleared: task is now independent")
+			}
+		})
+		return nil
+	},
+}
+
+func buildSetAncestorBody(ancestorID string) map[string]interface{} {
+	if ancestorID == "" {
+		return map[string]interface{}{}
+	}
+	return map[string]interface{}{
+		"ancestor_guid": ancestorID,
+	}
+}

shortcuts/task/task_set_ancestor_test.go

@@ -0,0 +1,166 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestBuildSetAncestorBody(t *testing.T) {
+	tests := []struct {
+		name       string
+		ancestorID string
+		want       map[string]interface{}
+	}{
+		{name: "empty ancestor", ancestorID: "", want: map[string]interface{}{}},
+		{name: "set ancestor", ancestorID: "guid_2", want: map[string]interface{}{"ancestor_guid": "guid_2"}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := buildSetAncestorBody(tt.ancestorID)
+			if len(got) != len(tt.want) {
+				t.Fatalf("len(buildSetAncestorBody(%q)) = %d, want %d", tt.ancestorID, len(got), len(tt.want))
+			}
+			for k, want := range tt.want {
+				if got[k] != want {
+					t.Fatalf("buildSetAncestorBody(%q)[%q] = %#v, want %#v", tt.ancestorID, k, got[k], want)
+				}
+			}
+		})
+	}
+}
+
+func TestSetAncestorTask_DryRun(t *testing.T) {
+	tests := []struct {
+		name      string
+		taskID    string
+		ancestor  string
+		wantParts []string
+	}{
+		{
+			name:      "with ancestor",
+			taskID:    "task-123",
+			ancestor:  "task-456",
+			wantParts: []string{"POST /open-apis/task/v2/tasks/task-123/set_ancestor_task", `"ancestor_guid":"task-456"`},
+		},
+		{
+			name:      "clear ancestor",
+			taskID:    "task-123",
+			wantParts: []string{"POST /open-apis/task/v2/tasks/task-123/set_ancestor_task"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("task-id", "", "")
+			cmd.Flags().String("ancestor-id", "", "")
+			_ = cmd.Flags().Set("task-id", tt.taskID)
+			if tt.ancestor != "" {
+				_ = cmd.Flags().Set("ancestor-id", tt.ancestor)
+			}
+			runtime := common.TestNewRuntimeContextWithIdentity(cmd, taskTestConfig(t), "bot")
+			out := SetAncestorTask.DryRun(nil, runtime).Format()
+			for _, want := range tt.wantParts {
+				if !strings.Contains(out, want) {
+					t.Fatalf("dry run output missing %q: %s", want, out)
+				}
+			}
+		})
+	}
+}
+
+func TestSetAncestorTask_Execute(t *testing.T) {
+	tests := []struct {
+		name      string
+		args      []string
+		register  func(*httpmock.Registry)
+		wantErr   bool
+		wantParts []string
+	}{
+		{
+			name: "json output with ancestor",
+			args: []string{"+set-ancestor", "--task-id", "task-123", "--ancestor-id", "task-456", "--as", "bot", "--format", "json"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasks/task-123/set_ancestor_task",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{},
+					},
+				})
+			},
+			wantParts: []string{`"guid": "task-123"`},
+		},
+		{
+			name: "pretty output clears ancestor",
+			args: []string{"+set-ancestor", "--task-id", "task-123", "--as", "bot", "--format", "pretty"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasks/task-123/set_ancestor_task",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{},
+					},
+				})
+			},
+			wantParts: []string{"Ancestor cleared", "Task ID: task-123"},
+		},
+		{
+			name: "api-level error (code!=0) returns error",
+			args: []string{"+set-ancestor", "--task-id", "task-123", "--ancestor-id", "task-456", "--as", "bot", "--format", "pretty"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasks/task-123/set_ancestor_task",
+					Body: map[string]interface{}{
+						"code": 10003,
+						"msg":  "permission denied",
+					},
+				})
+			},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, stdout, _, reg := taskShortcutTestFactory(t)
+			warmTenantToken(t, f, reg)
+			tt.register(reg)
+
+			err := runMountedTaskShortcut(t, SetAncestorTask, tt.args, f, stdout)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatal("expected error, got nil")
+				}
+				if out := stdout.String(); out != "" {
+					t.Fatalf("expected empty stdout on error, got: %s", out)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("runMountedTaskShortcut() error = %v", err)
+			}
+			out := stdout.String()
+			outNorm := strings.ReplaceAll(out, `":"`, `": "`)
+			for _, want := range tt.wantParts {
+				if !strings.Contains(out, want) && !strings.Contains(outNorm, want) {
+					t.Fatalf("output missing %q: %s", want, out)
+				}
+			}
+		})
+	}
+}

shortcuts/task/task_subscribe_event.go

@@ -0,0 +1,58 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var SubscribeTaskEvent = common.Shortcut{
+	Service:     "task",
+	Command:     "+subscribe-event",
+	Description: "subscribe to task events",
+	Risk:        "write",
+	Scopes:      []string{"task:task:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		return common.NewDryRunAPI().
+			POST("/open-apis/task/v2/task_v2/task_subscription").
+			Params(map[string]interface{}{"user_id_type": "open_id"})
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		queryParams := make(larkcore.QueryParams)
+		queryParams.Set("user_id_type", "open_id")
+		apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+			HttpMethod:  http.MethodPost,
+			ApiPath:     "/open-apis/task/v2/task_v2/task_subscription",
+			QueryParams: queryParams,
+		})
+
+		// DoAPI may return HTTP 200 while the JSON body contains a non-zero business "code".
+		// Parse and validate the envelope to avoid false-success output.
+		var result map[string]interface{}
+		if err == nil {
+			if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
+				return WrapTaskError(ErrCodeTaskInternalError, fmt.Sprintf("failed to parse response: %v", parseErr), "subscribe task events")
+			}
+		}
+		if _, err := HandleTaskApiResult(result, err, "subscribe task events"); err != nil {
+			return err
+		}
+
+		outData := map[string]interface{}{"ok": true}
+		runtime.OutFormat(outData, nil, func(w io.Writer) {
+			fmt.Fprintln(w, "✅ Task event subscription created successfully!")
+		})
+		return nil
+	},
+}

shortcuts/task/task_subscribe_event_test.go

@@ -0,0 +1,131 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestSubscribeTaskEvent(t *testing.T) {
+	tests := []struct {
+		name      string
+		mode      string
+		args      []string
+		register  func(*httpmock.Registry)
+		wantErr   bool
+		wantParts []string
+	}{
+		{
+			name: "execute json (user identity)",
+			mode: "execute",
+			args: []string{"+subscribe-event", "--as", "user", "--format", "json"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/task_v2/task_subscription",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{},
+					},
+				})
+			},
+			wantParts: []string{`"ok": true`},
+		},
+		{
+			name: "execute json (bot identity)",
+			mode: "execute",
+			args: []string{"+subscribe-event", "--as", "bot", "--format", "json"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/task_v2/task_subscription",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{},
+					},
+				})
+			},
+			wantParts: []string{`"ok": true`},
+		},
+		{
+			name: "execute api error",
+			mode: "execute",
+			args: []string{"+subscribe-event", "--as", "bot", "--format", "json"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/task_v2/task_subscription",
+					Body: map[string]interface{}{
+						"code": 401,
+						"msg":  "Unauthorized",
+						"error": map[string]interface{}{
+							"log_id": "test-log-id",
+						},
+					},
+				})
+			},
+			wantErr:   true,
+			wantParts: []string{"Unauthorized"},
+		},
+		{
+			name:      "dry run",
+			mode:      "dryrun",
+			wantParts: []string{"POST /open-apis/task/v2/task_v2/task_subscription"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			switch tt.mode {
+			case "execute":
+				f, stdout, _, reg := taskShortcutTestFactory(t)
+				warmTenantToken(t, f, reg)
+				if tt.register != nil {
+					tt.register(reg)
+				}
+
+				err := runMountedTaskShortcut(t, SubscribeTaskEvent, tt.args, f, stdout)
+				if tt.wantErr {
+					if err == nil {
+						t.Fatal("expected error, got nil")
+					}
+					out := err.Error()
+					for _, want := range tt.wantParts {
+						if !strings.Contains(out, want) {
+							t.Fatalf("error missing %q: %s", want, out)
+						}
+					}
+					return
+				}
+				if err != nil {
+					t.Fatalf("runMountedTaskShortcut() error = %v", err)
+				}
+
+				out := stdout.String()
+				outNorm := strings.ReplaceAll(out, `":"`, `": "`)
+				for _, want := range tt.wantParts {
+					if !strings.Contains(out, want) && !strings.Contains(outNorm, want) {
+						t.Fatalf("output missing %q: %s", want, out)
+					}
+				}
+			case "dryrun":
+				runtime := common.TestNewRuntimeContextWithIdentity(&cobra.Command{Use: "test"}, taskTestConfig(t), "user")
+				out := SubscribeTaskEvent.DryRun(nil, runtime).Format()
+				for _, want := range tt.wantParts {
+					if !strings.Contains(out, want) {
+						t.Fatalf("dry run output missing %q: %s", want, out)
+					}
+				}
+			}
+		})
+	}
+}

shortcuts/task/task_tasklist_search.go

@@ -0,0 +1,209 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	tasklistSearchDefaultPageLimit = 20
+	tasklistSearchMaxPageLimit     = 40
+)
+
+var SearchTasklist = common.Shortcut{
+	Service:     "task",
+	Command:     "+tasklist-search",
+	Description: "search tasklists",
+	Risk:        "read",
+	Scopes:      []string{"task:tasklist:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "query", Desc: "search keyword"},
+		{Name: "page-all", Type: "bool", Desc: "automatically paginate through all pages (max 40)"},
+		{Name: "page-limit", Type: "int", Default: "20", Desc: "max page limit (default 20, max 40)"},
+		{Name: "page-token", Desc: "page token"},
+		{Name: "creator", Desc: "creator open_ids, comma-separated"},
+		{Name: "create-time", Desc: "create time range: start,end (supports ISO/date/relative/ms)"},
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		body, err := buildTasklistSearchBody(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			POST("/open-apis/task/v2/tasklists/search").
+			Body(body).
+			Desc("Then GET /open-apis/task/v2/tasklists/:guid for each search hit to render standard output")
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := buildTasklistSearchBody(runtime)
+		return err
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		body, err := buildTasklistSearchBody(runtime)
+		if err != nil {
+			return err
+		}
+
+		pageLimit := runtime.Int("page-limit")
+		if pageLimit <= 0 {
+			pageLimit = tasklistSearchDefaultPageLimit
+		}
+		if runtime.Bool("page-all") {
+			pageLimit = tasklistSearchMaxPageLimit
+		}
+		if pageLimit > tasklistSearchMaxPageLimit {
+			pageLimit = tasklistSearchMaxPageLimit
+		}
+
+		var rawItems []interface{}
+		var lastPageToken string
+		var lastHasMore bool
+		currentBody := body
+		for page := 0; page < pageLimit; page++ {
+			apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+				HttpMethod: http.MethodPost,
+				ApiPath:    "/open-apis/task/v2/tasklists/search",
+				Body:       currentBody,
+			})
+			var result map[string]interface{}
+			if err == nil {
+				if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
+					return WrapTaskError(ErrCodeTaskInternalError, fmt.Sprintf("failed to parse response: %v", parseErr), "parse tasklist search")
+				}
+			}
+			data, err := HandleTaskApiResult(result, err, "search tasklists")
+			if err != nil {
+				return err
+			}
+			items, _ := data["items"].([]interface{})
+			rawItems = append(rawItems, items...)
+			lastHasMore, _ = data["has_more"].(bool)
+			lastPageToken, _ = data["page_token"].(string)
+			if !lastHasMore || lastPageToken == "" {
+				break
+			}
+			currentBody["page_token"] = lastPageToken
+		}
+
+		tasklists := make([]map[string]interface{}, 0, len(rawItems))
+		for _, item := range rawItems {
+			itemMap, _ := item.(map[string]interface{})
+			tasklistID, _ := itemMap["id"].(string)
+			if tasklistID == "" {
+				continue
+			}
+
+			tasklist, err := getTasklistDetail(runtime, tasklistID)
+			if err != nil {
+				// Keep a stable identifier and avoid rendering "<nil>" in pretty output.
+				tasklists = append(tasklists, map[string]interface{}{
+					"guid": tasklistID,
+					"name": fmt.Sprintf("(unknown tasklist: %s)", tasklistID),
+				})
+				continue
+			}
+			urlVal, _ := tasklist["url"].(string)
+			urlVal = truncateTaskURL(urlVal)
+			tasklists = append(tasklists, map[string]interface{}{
+				"guid":    tasklist["guid"],
+				"name":    tasklist["name"],
+				"url":     urlVal,
+				"creator": tasklist["creator"],
+			})
+		}
+
+		outData := map[string]interface{}{
+			"items":      tasklists,
+			"page_token": lastPageToken,
+			"has_more":   lastHasMore,
+		}
+		runtime.OutFormat(outData, &output.Meta{Count: len(tasklists)}, func(w io.Writer) {
+			if len(tasklists) == 0 {
+				fmt.Fprintln(w, "No tasklists found.")
+				return
+			}
+			for i, tasklist := range tasklists {
+				fmt.Fprintf(w, "[%d] %v\n", i+1, tasklist["name"])
+				fmt.Fprintf(w, "    GUID: %v\n", tasklist["guid"])
+				if urlVal, _ := tasklist["url"].(string); urlVal != "" {
+					fmt.Fprintf(w, "    URL: %s\n", urlVal)
+				}
+				fmt.Fprintln(w)
+			}
+			if lastHasMore && lastPageToken != "" {
+				fmt.Fprintf(w, "Next page token: %s\n", lastPageToken)
+			}
+		})
+		return nil
+	},
+}
+
+func buildTasklistSearchBody(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	filter := map[string]interface{}{}
+	if ids := splitAndTrimCSV(runtime.Str("creator")); len(ids) > 0 {
+		filter["user_id"] = ids
+	}
+	if createTime := runtime.Str("create-time"); createTime != "" {
+		start, end, err := parseTimeRangeRFC3339(createTime)
+		if err != nil {
+			return nil, WrapTaskError(ErrCodeTaskInvalidParams, fmt.Sprintf("invalid create-time: %v", err), "build tasklist search")
+		}
+		if timeFilter := buildTimeRangeFilter("create_time", start, end); timeFilter != nil {
+			mergeIntoFilter(filter, timeFilter)
+		}
+	}
+	if err := requireSearchFilter(runtime.Str("query"), filter, "build tasklist search"); err != nil {
+		return nil, err
+	}
+
+	body := map[string]interface{}{
+		"query": runtime.Str("query"),
+	}
+	if len(filter) > 0 {
+		body["filter"] = filter
+	}
+	if pageToken := runtime.Str("page-token"); pageToken != "" {
+		body["page_token"] = pageToken
+	}
+	return body, nil
+}
+
+func getTasklistDetail(runtime *common.RuntimeContext, tasklistID string) (map[string]interface{}, error) {
+	queryParams := make(larkcore.QueryParams)
+	queryParams.Set("user_id_type", "open_id")
+
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod:  http.MethodGet,
+		ApiPath:     "/open-apis/task/v2/tasklists/" + url.PathEscape(tasklistID),
+		QueryParams: queryParams,
+	})
+	var result map[string]interface{}
+	if err == nil {
+		if parseErr := json.Unmarshal(apiResp.RawBody, &result); parseErr != nil {
+			return nil, WrapTaskError(ErrCodeTaskInternalError, fmt.Sprintf("failed to parse tasklist detail response: %v", parseErr), "parse tasklist detail")
+		}
+	}
+	data, err := HandleTaskApiResult(result, err, "get tasklist detail "+tasklistID)
+	if err != nil {
+		return nil, err
+	}
+	tasklist, _ := data["tasklist"].(map[string]interface{})
+	if tasklist == nil {
+		return nil, WrapTaskError(ErrCodeTaskInternalError, "tasklist detail response missing tasklist object", "get tasklist detail")
+	}
+	return tasklist, nil
+}

shortcuts/task/task_tasklist_search_test.go

@@ -0,0 +1,263 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestBuildTasklistSearchBody(t *testing.T) {
+	tests := []struct {
+		name    string
+		setup   func(*cobra.Command)
+		wantErr bool
+		check   func(*testing.T, map[string]interface{})
+	}{
+		{
+			name: "creator create-time and page token",
+			setup: func(cmd *cobra.Command) {
+				_ = cmd.Flags().Set("creator", "ou_creator")
+				_ = cmd.Flags().Set("create-time", "-7d,+0d")
+				_ = cmd.Flags().Set("page-token", "pt_tl")
+			},
+			check: func(t *testing.T, body map[string]interface{}) {
+				filter := body["filter"].(map[string]interface{})
+				createTime := filter["create_time"].(map[string]interface{})
+				if body["page_token"] != "pt_tl" {
+					t.Fatalf("unexpected body: %#v", body)
+				}
+				if filter["user_id"].([]string)[0] != "ou_creator" {
+					t.Fatalf("unexpected filter: %#v", filter)
+				}
+				startTime, _ := createTime["start_time"].(string)
+				endTime, _ := createTime["end_time"].(string)
+				if startTime == "" || endTime == "" || !strings.Contains(startTime, "T") || !strings.Contains(endTime, "T") {
+					t.Fatalf("unexpected create_time: %#v", createTime)
+				}
+			},
+		},
+		{
+			name:    "requires query or filter",
+			setup:   func(cmd *cobra.Command) {},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("query", "", "")
+			cmd.Flags().String("creator", "", "")
+			cmd.Flags().String("create-time", "", "")
+			cmd.Flags().String("page-token", "", "")
+			tt.setup(cmd)
+
+			runtime := common.TestNewRuntimeContextWithIdentity(cmd, taskTestConfig(t), "user")
+			body, err := buildTasklistSearchBody(runtime)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatal("expected error, got nil")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("buildTasklistSearchBody() error = %v", err)
+			}
+			tt.check(t, body)
+		})
+	}
+}
+
+func TestSearchTasklist_DryRun(t *testing.T) {
+	tests := []struct {
+		name      string
+		setup     func(*cobra.Command)
+		wantParts []string
+	}{
+		{
+			name: "valid dry run",
+			setup: func(cmd *cobra.Command) {
+				_ = cmd.Flags().Set("query", "Q2")
+				_ = cmd.Flags().Set("page-token", "pt_tl")
+			},
+			wantParts: []string{"POST /open-apis/task/v2/tasklists/search", `"query":"Q2"`},
+		},
+		{
+			name: "dry run error on invalid create time",
+			setup: func(cmd *cobra.Command) {
+				_ = cmd.Flags().Set("create-time", "bad-time")
+			},
+			wantParts: []string{"error:"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("query", "", "")
+			cmd.Flags().String("creator", "", "")
+			cmd.Flags().String("create-time", "", "")
+			cmd.Flags().String("page-token", "", "")
+			tt.setup(cmd)
+
+			runtime := common.TestNewRuntimeContextWithIdentity(cmd, taskTestConfig(t), "user")
+			if !strings.Contains(tt.name, "error") {
+				if err := SearchTasklist.Validate(nil, runtime); err != nil {
+					t.Fatalf("Validate() error = %v", err)
+				}
+			}
+			out := SearchTasklist.DryRun(nil, runtime).Format()
+			for _, want := range tt.wantParts {
+				if !strings.Contains(out, want) {
+					t.Fatalf("dry run output missing %q: %s", want, out)
+				}
+			}
+		})
+	}
+}
+
+func TestSearchTasklist_Execute(t *testing.T) {
+	tests := []struct {
+		name      string
+		args      []string
+		register  func(*httpmock.Registry)
+		wantParts []string
+	}{
+		{
+			name: "json success",
+			args: []string{"+tasklist-search", "--query", "Q2", "--as", "bot", "--format", "json"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasklists/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"has_more":   false,
+							"page_token": "",
+							"items":      []interface{}{map[string]interface{}{"id": "tl-123"}},
+						},
+					},
+				})
+				reg.Register(&httpmock.Stub{
+					Method: "GET",
+					URL:    "/open-apis/task/v2/tasklists/tl-123",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"tasklist": map[string]interface{}{"guid": "tl-123", "name": "Q2 Plan", "url": "https://example.com/tl-123"},
+						},
+					},
+				})
+			},
+			wantParts: []string{`"guid": "tl-123"`, `"name": "Q2 Plan"`},
+		},
+		{
+			name: "fallback on detail error",
+			args: []string{"+tasklist-search", "--query", "fallback", "--as", "bot", "--format", "json"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasklists/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"has_more":   false,
+							"page_token": "",
+							"items":      []interface{}{map[string]interface{}{"id": "tl-fallback"}},
+						},
+					},
+				})
+				reg.Register(&httpmock.Stub{
+					Method: "GET",
+					URL:    "/open-apis/task/v2/tasklists/tl-fallback",
+					Body:   map[string]interface{}{"code": 99991663, "msg": "not found"},
+				})
+			},
+			wantParts: []string{`"guid": "tl-fallback"`},
+		},
+		{
+			name: "pretty fallback avoids nil name",
+			args: []string{"+tasklist-search", "--query", "fallback-pretty", "--as", "bot", "--format", "pretty"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasklists/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{
+							"has_more":   false,
+							"page_token": "",
+							"items":      []interface{}{map[string]interface{}{"id": "tl-fallback"}},
+						},
+					},
+				})
+				reg.Register(&httpmock.Stub{
+					Method: "GET",
+					URL:    "/open-apis/task/v2/tasklists/tl-fallback",
+					Body:   map[string]interface{}{"code": 99991663, "msg": "not found"},
+				})
+			},
+			wantParts: []string{"(unknown tasklist: tl-fallback)", "GUID: tl-fallback"},
+		},
+		{
+			name: "empty pretty with pagination",
+			args: []string{"+tasklist-search", "--query", "none", "--as", "bot", "--format", "pretty", "--page-limit", "2"},
+			register: func(reg *httpmock.Registry) {
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasklists/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{"has_more": true, "page_token": "pt_2", "items": []interface{}{}},
+					},
+				})
+				reg.Register(&httpmock.Stub{
+					Method: "POST",
+					URL:    "/open-apis/task/v2/tasklists/search",
+					Body: map[string]interface{}{
+						"code": 0,
+						"msg":  "success",
+						"data": map[string]interface{}{"has_more": false, "page_token": "", "items": []interface{}{}},
+					},
+				})
+			},
+			wantParts: []string{"No tasklists found."},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, stdout, _, reg := taskShortcutTestFactory(t)
+			warmTenantToken(t, f, reg)
+			tt.register(reg)
+
+			s := SearchTasklist
+			s.AuthTypes = []string{"bot", "user"}
+			err := runMountedTaskShortcut(t, s, tt.args, f, stdout)
+			if err != nil {
+				t.Fatalf("runMountedTaskShortcut() error = %v", err)
+			}
+
+			out := stdout.String()
+			outNorm := strings.ReplaceAll(out, `":"`, `": "`)
+			for _, want := range tt.wantParts {
+				if !strings.Contains(out, want) && !strings.Contains(outNorm, want) {
+					t.Fatalf("output missing %q: %s", want, out)
+				}
+			}
+		})
+	}
+}

shortcuts/wiki/shortcuts.go

@@ -8,6 +8,7 @@ import "github.com/larksuite/cli/shortcuts/common"
 // Shortcuts returns all wiki shortcuts.
 func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
+		WikiMove,
 		WikiNodeCreate,
 	}
 }

shortcuts/wiki/wiki_move.go

@@ -0,0 +1,671 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var (
+	wikiMovePollAttempts = 30
+	wikiMovePollInterval = 2 * time.Second
+)
+
+const (
+	wikiMoveModeNode       = "node"
+	wikiMoveModeDocsToWiki = "docs_to_wiki"
+)
+
+var wikiMoveObjectTypes = []string{
+	"doc",
+	"sheet",
+	"bitable",
+	"mindnote",
+	"docx",
+	"file",
+	"slides",
+}
+
+// WikiMove moves an existing wiki node inside Wiki or migrates a Drive
+// document into Wiki with bounded polling for async task completion.
+var WikiMove = common.Shortcut{
+	Service:     "wiki",
+	Command:     "+move",
+	Description: "Move a wiki node, or move a Drive document into Wiki",
+	Risk:        "write",
+	Scopes:      []string{"wiki:node:move", "wiki:node:read", "wiki:space:read"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "node-token", Desc: "wiki node token to move inside Wiki"},
+		{Name: "source-space-id", Desc: "source wiki space ID for --node-token; if omitted, it is resolved from the node token"},
+		{Name: "target-space-id", Desc: "target wiki space ID; required for docs-to-wiki, optional for node move when --target-parent-token is set"},
+		{Name: "target-parent-token", Desc: "target parent wiki node token; if omitted for docs-to-wiki, the document is moved to the target space root"},
+		{Name: "obj-type", Desc: "Drive document type for docs-to-wiki mode", Enum: wikiMoveObjectTypes},
+		{Name: "obj-token", Desc: "Drive document token for docs-to-wiki mode"},
+		{Name: "apply", Type: "bool", Desc: "submit a move request when the caller lacks permission to move the document immediately"},
+	},
+	Tips: []string{
+		"Use --node-token to move an existing wiki node inside or across wiki spaces.",
+		"Use --obj-type and --obj-token to move a Drive document into Wiki.",
+		"If docs-to-wiki returns a long-running task, this command polls for a bounded window and then prints a follow-up drive +task_result command.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec := readWikiMoveSpec(runtime)
+		// `my_library` is a per-user personal-library alias; it has no meaning
+		// for a tenant_access_token (--as bot), so reject early with a clear
+		// hint instead of letting the API return a confusing error.
+		if runtime.As().IsBot() && spec.TargetSpaceID == wikiMyLibrarySpaceID {
+			return output.ErrValidation("--target-space-id my_library is a per-user personal library alias and cannot be used with --as bot; resolve it to a real space_id first via `lark-cli wiki spaces get --params '{\"space_id\":\"my_library\"}' --as user`")
+		}
+		return validateWikiMoveSpec(spec)
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		return buildWikiMoveDryRun(readWikiMoveSpec(runtime))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec := readWikiMoveSpec(runtime)
+		fmt.Fprintf(runtime.IO().ErrOut, "Running wiki move (%s)...\n", spec.Mode())
+
+		out, err := runWikiMove(ctx, wikiMoveAPI{runtime: runtime}, runtime, spec)
+		if err != nil {
+			return err
+		}
+
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+type wikiMoveSpec struct {
+	NodeToken         string
+	SourceSpaceID     string
+	TargetSpaceID     string
+	TargetParentToken string
+	ObjType           string
+	ObjToken          string
+	Apply             bool
+}
+
+func (spec wikiMoveSpec) Mode() string {
+	if spec.NodeToken != "" {
+		return wikiMoveModeNode
+	}
+	return wikiMoveModeDocsToWiki
+}
+
+func (spec wikiMoveSpec) NodeMoveBody() map[string]interface{} {
+	body := map[string]interface{}{}
+	if spec.TargetParentToken != "" {
+		body["target_parent_token"] = spec.TargetParentToken
+	}
+	if spec.TargetSpaceID != "" {
+		body["target_space_id"] = spec.TargetSpaceID
+	}
+	return body
+}
+
+func (spec wikiMoveSpec) DocsToWikiBody() map[string]interface{} {
+	body := map[string]interface{}{
+		"obj_type":  spec.ObjType,
+		"obj_token": spec.ObjToken,
+	}
+	if spec.TargetParentToken != "" {
+		body["parent_wiki_token"] = spec.TargetParentToken
+	}
+	if spec.Apply {
+		body["apply"] = true
+	}
+	return body
+}
+
+type wikiMoveTaskResult struct {
+	Node      *wikiNodeRecord
+	Status    int
+	StatusMsg string
+}
+
+type wikiMoveTaskStatus struct {
+	TaskID      string
+	MoveResults []wikiMoveTaskResult
+}
+
+func (s wikiMoveTaskStatus) Ready() bool {
+	if len(s.MoveResults) == 0 {
+		return false
+	}
+	for _, result := range s.MoveResults {
+		if result.Status != 0 {
+			return false
+		}
+	}
+	return true
+}
+
+func (s wikiMoveTaskStatus) Failed() bool {
+	for _, result := range s.MoveResults {
+		if result.Status < 0 {
+			return true
+		}
+	}
+	return false
+}
+
+func (s wikiMoveTaskStatus) Pending() bool {
+	return !s.Ready() && !s.Failed()
+}
+
+func (s wikiMoveTaskStatus) FirstResult() *wikiMoveTaskResult {
+	if len(s.MoveResults) == 0 {
+		return nil
+	}
+	return &s.MoveResults[0]
+}
+
+// primaryResult picks the most informative move_result for top-level status
+// surfacing: prefer a failing entry so multi-doc tasks don't mask failures
+// behind an earlier success, then a still-processing entry, and finally fall
+// back to the first entry.
+func (s wikiMoveTaskStatus) primaryResult() *wikiMoveTaskResult {
+	for i := range s.MoveResults {
+		if s.MoveResults[i].Status < 0 {
+			return &s.MoveResults[i]
+		}
+	}
+	for i := range s.MoveResults {
+		if s.MoveResults[i].Status > 0 {
+			return &s.MoveResults[i]
+		}
+	}
+	return s.FirstResult()
+}
+
+func (s wikiMoveTaskStatus) PrimaryStatusCode() int {
+	if r := s.primaryResult(); r != nil {
+		return r.Status
+	}
+	return 1
+}
+
+func (s wikiMoveTaskStatus) PrimaryStatusLabel() string {
+	if r := s.primaryResult(); r != nil {
+		if msg := strings.TrimSpace(r.StatusMsg); msg != "" {
+			return msg
+		}
+	}
+	switch {
+	case s.Ready():
+		return "success"
+	case s.Failed():
+		return "failure"
+	default:
+		return "processing"
+	}
+}
+
+type wikiMoveDocsResponse struct {
+	WikiToken string
+	TaskID    string
+	Applied   bool
+}
+
+type wikiMoveClient interface {
+	GetNode(ctx context.Context, token string) (*wikiNodeRecord, error)
+	MoveNode(ctx context.Context, sourceSpaceID string, spec wikiMoveSpec) (*wikiNodeRecord, error)
+	MoveDocsToWiki(ctx context.Context, targetSpaceID string, spec wikiMoveSpec) (*wikiMoveDocsResponse, error)
+	GetMoveTask(ctx context.Context, taskID string) (wikiMoveTaskStatus, error)
+}
+
+type wikiMoveAPI struct {
+	runtime *common.RuntimeContext
+}
+
+func (api wikiMoveAPI) GetNode(ctx context.Context, token string) (*wikiNodeRecord, error) {
+	data, err := api.runtime.CallAPI(
+		"GET",
+		"/open-apis/wiki/v2/spaces/get_node",
+		map[string]interface{}{"token": token},
+		nil,
+	)
+	if err != nil {
+		return nil, err
+	}
+	return parseWikiNodeRecord(common.GetMap(data, "node"))
+}
+
+func (api wikiMoveAPI) MoveNode(ctx context.Context, sourceSpaceID string, spec wikiMoveSpec) (*wikiNodeRecord, error) {
+	data, err := api.runtime.CallAPI(
+		"POST",
+		fmt.Sprintf(
+			"/open-apis/wiki/v2/spaces/%s/nodes/%s/move",
+			validate.EncodePathSegment(sourceSpaceID),
+			validate.EncodePathSegment(spec.NodeToken),
+		),
+		nil,
+		spec.NodeMoveBody(),
+	)
+	if err != nil {
+		return nil, err
+	}
+	return parseWikiNodeRecord(common.GetMap(data, "node"))
+}
+
+func (api wikiMoveAPI) MoveDocsToWiki(ctx context.Context, targetSpaceID string, spec wikiMoveSpec) (*wikiMoveDocsResponse, error) {
+	data, err := api.runtime.CallAPI(
+		"POST",
+		fmt.Sprintf(
+			"/open-apis/wiki/v2/spaces/%s/nodes/move_docs_to_wiki",
+			validate.EncodePathSegment(targetSpaceID),
+		),
+		nil,
+		spec.DocsToWikiBody(),
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return &wikiMoveDocsResponse{
+		WikiToken: common.GetString(data, "wiki_token"),
+		TaskID:    common.GetString(data, "task_id"),
+		Applied:   common.GetBool(data, "applied"),
+	}, nil
+}
+
+func (api wikiMoveAPI) GetMoveTask(ctx context.Context, taskID string) (wikiMoveTaskStatus, error) {
+	data, err := api.runtime.CallAPI(
+		"GET",
+		fmt.Sprintf("/open-apis/wiki/v2/tasks/%s", validate.EncodePathSegment(taskID)),
+		map[string]interface{}{"task_type": "move"},
+		nil,
+	)
+	if err != nil {
+		return wikiMoveTaskStatus{}, err
+	}
+	return parseWikiMoveTaskStatus(taskID, common.GetMap(data, "task"))
+}
+
+func readWikiMoveSpec(runtime *common.RuntimeContext) wikiMoveSpec {
+	return wikiMoveSpec{
+		NodeToken:         strings.TrimSpace(runtime.Str("node-token")),
+		SourceSpaceID:     strings.TrimSpace(runtime.Str("source-space-id")),
+		TargetSpaceID:     strings.TrimSpace(runtime.Str("target-space-id")),
+		TargetParentToken: strings.TrimSpace(runtime.Str("target-parent-token")),
+		ObjType:           strings.ToLower(strings.TrimSpace(runtime.Str("obj-type"))),
+		ObjToken:          strings.TrimSpace(runtime.Str("obj-token")),
+		Apply:             runtime.Bool("apply"),
+	}
+}
+
+func validateWikiMoveSpec(spec wikiMoveSpec) error {
+	if err := validateOptionalResourceName(spec.NodeToken, "--node-token"); err != nil {
+		return err
+	}
+	if err := validateOptionalResourceName(spec.SourceSpaceID, "--source-space-id"); err != nil {
+		return err
+	}
+	if err := validateOptionalResourceName(spec.TargetSpaceID, "--target-space-id"); err != nil {
+		return err
+	}
+	if err := validateOptionalResourceName(spec.TargetParentToken, "--target-parent-token"); err != nil {
+		return err
+	}
+	if err := validateOptionalResourceName(spec.ObjToken, "--obj-token"); err != nil {
+		return err
+	}
+
+	if spec.NodeToken != "" {
+		if spec.ObjType != "" || spec.ObjToken != "" || spec.Apply {
+			return output.ErrValidation("--node-token cannot be combined with --obj-type, --obj-token, or --apply")
+		}
+		if spec.TargetParentToken == "" && spec.TargetSpaceID == "" {
+			return output.ErrValidation("--target-parent-token and --target-space-id cannot both be empty for wiki node move")
+		}
+		return nil
+	}
+
+	if spec.SourceSpaceID != "" {
+		return output.ErrValidation("--source-space-id can only be used with --node-token")
+	}
+	if spec.ObjType == "" && spec.ObjToken == "" && !spec.Apply {
+		return output.ErrValidation("provide --node-token for wiki node move, or provide --obj-type and --obj-token for docs-to-wiki move")
+	}
+	if spec.ObjType == "" {
+		return output.ErrValidation("--obj-type is required for docs-to-wiki move")
+	}
+	if spec.ObjToken == "" {
+		return output.ErrValidation("--obj-token is required for docs-to-wiki move")
+	}
+	if spec.TargetSpaceID == "" {
+		return output.ErrValidation("--target-space-id is required for docs-to-wiki move")
+	}
+
+	return nil
+}
+
+func buildWikiMoveDryRun(spec wikiMoveSpec) *common.DryRunAPI {
+	dry := common.NewDryRunAPI()
+	switch spec.Mode() {
+	case wikiMoveModeNode:
+		step := 1
+		switch {
+		case spec.SourceSpaceID == "" && spec.TargetParentToken != "":
+			dry.Desc("3-step orchestration: resolve source node -> resolve target parent -> move wiki node")
+		case spec.SourceSpaceID == "":
+			dry.Desc("2-step orchestration: resolve source node -> move wiki node")
+		case spec.TargetParentToken != "":
+			dry.Desc("2-step orchestration: resolve target parent -> move wiki node")
+		default:
+			dry.Desc("1-step request: move wiki node")
+		}
+
+		if spec.SourceSpaceID == "" {
+			dry.GET("/open-apis/wiki/v2/spaces/get_node").
+				Desc(fmt.Sprintf("[%d] Resolve source space from node token", step)).
+				Params(map[string]interface{}{"token": spec.NodeToken})
+			step++
+		}
+		if spec.TargetParentToken != "" {
+			dry.GET("/open-apis/wiki/v2/spaces/get_node").
+				Desc(fmt.Sprintf("[%d] Resolve target parent node", step)).
+				Params(map[string]interface{}{"token": spec.TargetParentToken})
+			step++
+		}
+
+		dry.POST(fmt.Sprintf(
+			"/open-apis/wiki/v2/spaces/%s/nodes/%s/move",
+			dryRunWikiMoveSourceSpaceID(spec),
+			validate.EncodePathSegment(spec.NodeToken),
+		)).
+			Desc(fmt.Sprintf("[%d] Move wiki node", step)).
+			Body(spec.NodeMoveBody())
+	case wikiMoveModeDocsToWiki:
+		dry.Desc("2-step orchestration: move Drive document into Wiki -> poll wiki task result when task_id is returned")
+		dry.POST(fmt.Sprintf(
+			"/open-apis/wiki/v2/spaces/%s/nodes/move_docs_to_wiki",
+			dryRunWikiMoveTargetSpaceID(spec),
+		)).
+			Desc("[1] Move Drive document into Wiki").
+			Body(spec.DocsToWikiBody())
+		dry.GET("/open-apis/wiki/v2/tasks/:task_id").
+			Desc("[2] Poll wiki move task result when async").
+			Set("task_id", "<task_id>").
+			Params(map[string]interface{}{"task_type": "move"})
+	default:
+		dry.Set("error", "unknown wiki move mode")
+	}
+	return dry
+}
+
+func dryRunWikiMoveSourceSpaceID(spec wikiMoveSpec) string {
+	if spec.SourceSpaceID != "" {
+		return validate.EncodePathSegment(spec.SourceSpaceID)
+	}
+	return "<resolved_source_space_id>"
+}
+
+func dryRunWikiMoveTargetSpaceID(spec wikiMoveSpec) string {
+	if spec.TargetSpaceID != "" {
+		return validate.EncodePathSegment(spec.TargetSpaceID)
+	}
+	return "<target_space_id>"
+}
+
+func runWikiMove(ctx context.Context, client wikiMoveClient, runtime *common.RuntimeContext, spec wikiMoveSpec) (map[string]interface{}, error) {
+	switch spec.Mode() {
+	case wikiMoveModeNode:
+		return runWikiNodeMove(ctx, client, spec)
+	case wikiMoveModeDocsToWiki:
+		return runWikiDocsToWikiMove(ctx, client, runtime, spec)
+	default:
+		return nil, output.ErrValidation("unknown wiki move mode")
+	}
+}
+
+func runWikiNodeMove(ctx context.Context, client wikiMoveClient, spec wikiMoveSpec) (map[string]interface{}, error) {
+	sourceSpaceID, targetSpaceID, err := resolveWikiNodeMoveSpaces(ctx, client, spec)
+	if err != nil {
+		return nil, err
+	}
+
+	node, err := client.MoveNode(ctx, sourceSpaceID, spec)
+	if err != nil {
+		return nil, err
+	}
+
+	out := map[string]interface{}{
+		"mode":            wikiMoveModeNode,
+		"source_space_id": sourceSpaceID,
+		"target_space_id": targetSpaceID,
+	}
+	appendWikiNodeOutput(out, node)
+	return out, nil
+}
+
+func resolveWikiNodeMoveSpaces(ctx context.Context, client wikiMoveClient, spec wikiMoveSpec) (string, string, error) {
+	// Node move requests may start from just a node token and/or a target parent.
+	// Resolve both ends up front so we can fail on space mismatches before sending
+	// the mutation request.
+	sourceSpaceID := spec.SourceSpaceID
+	if sourceSpaceID == "" {
+		sourceNode, err := client.GetNode(ctx, spec.NodeToken)
+		if err != nil {
+			return "", "", err
+		}
+		sourceSpaceID, err = requireWikiNodeSpaceID(sourceNode)
+		if err != nil {
+			return "", "", err
+		}
+	}
+
+	targetSpaceID := spec.TargetSpaceID
+	if spec.TargetParentToken != "" {
+		targetParent, err := client.GetNode(ctx, spec.TargetParentToken)
+		if err != nil {
+			return "", "", err
+		}
+		parentSpaceID, err := requireWikiNodeSpaceID(targetParent)
+		if err != nil {
+			return "", "", err
+		}
+		if targetSpaceID == "" {
+			targetSpaceID = parentSpaceID
+		} else if targetSpaceID != parentSpaceID {
+			return "", "", output.ErrValidation(
+				"--target-space-id %q does not match target parent node space %q",
+				spec.TargetSpaceID,
+				parentSpaceID,
+			)
+		}
+	}
+
+	if targetSpaceID == "" {
+		targetSpaceID = sourceSpaceID
+	}
+
+	return sourceSpaceID, targetSpaceID, nil
+}
+
+func runWikiDocsToWikiMove(ctx context.Context, client wikiMoveClient, runtime *common.RuntimeContext, spec wikiMoveSpec) (map[string]interface{}, error) {
+	response, err := client.MoveDocsToWiki(ctx, spec.TargetSpaceID, spec)
+	if err != nil {
+		return nil, err
+	}
+
+	out := map[string]interface{}{
+		"mode":                wikiMoveModeDocsToWiki,
+		"obj_type":            spec.ObjType,
+		"obj_token":           spec.ObjToken,
+		"target_space_id":     spec.TargetSpaceID,
+		"target_parent_token": spec.TargetParentToken,
+	}
+
+	// move_docs_to_wiki has three success-shaped responses: immediate completion,
+	// approval-request submission, or an async task that must be polled.
+	switch {
+	case response.WikiToken != "":
+		out["ready"] = true
+		out["failed"] = false
+		out["wiki_token"] = response.WikiToken
+		out["node_token"] = response.WikiToken
+		return out, nil
+	case response.Applied:
+		out["ready"] = false
+		out["failed"] = false
+		out["applied"] = true
+		out["status_msg"] = "move request submitted for approval"
+		return out, nil
+	case response.TaskID != "":
+		fmt.Fprintf(runtime.IO().ErrOut, "Docs-to-wiki move is async, polling task %s...\n", response.TaskID)
+		status, ready, err := pollWikiMoveTask(ctx, client, runtime, response.TaskID)
+		if err != nil {
+			return nil, err
+		}
+
+		out["task_id"] = response.TaskID
+		out["ready"] = ready
+		out["failed"] = status.Failed()
+		out["status"] = status.PrimaryStatusCode()
+		out["status_msg"] = status.PrimaryStatusLabel()
+		if first := status.FirstResult(); first != nil {
+			appendWikiNodeOutput(out, first.Node)
+			if first.Node != nil && first.Node.NodeToken != "" {
+				out["wiki_token"] = first.Node.NodeToken
+			}
+		}
+		if !ready {
+			nextCommand := wikiMoveTaskResultCommand(response.TaskID, runtime.As())
+			fmt.Fprintf(runtime.IO().ErrOut, "Wiki move task is still in progress. Continue with: %s\n", nextCommand)
+			out["timed_out"] = true
+			out["next_command"] = nextCommand
+		}
+		return out, nil
+	default:
+		return nil, output.Errorf(output.ExitAPI, "api_error", "move_docs_to_wiki returned neither wiki_token, task_id, nor applied result")
+	}
+}
+
+func wikiMoveTaskResultCommand(taskID string, identity core.Identity) string {
+	asFlag := string(identity)
+	if asFlag == "" {
+		asFlag = "user"
+	}
+	return fmt.Sprintf("lark-cli drive +task_result --scenario wiki_move --task-id %s --as %s", taskID, asFlag)
+}
+
+func pollWikiMoveTask(ctx context.Context, client wikiMoveClient, runtime *common.RuntimeContext, taskID string) (wikiMoveTaskStatus, bool, error) {
+	lastStatus := wikiMoveTaskStatus{TaskID: taskID}
+	var lastErr error
+	hadSuccessfulPoll := false
+
+	// The move request itself already succeeded. Treat poll failures as transient
+	// until every attempt fails, then return a resume hint instead of discarding
+	// the task identifier.
+	for attempt := 1; attempt <= wikiMovePollAttempts; attempt++ {
+		if attempt > 1 {
+			select {
+			case <-ctx.Done():
+				return lastStatus, false, ctx.Err()
+			case <-time.After(wikiMovePollInterval):
+			}
+		}
+
+		status, err := client.GetMoveTask(ctx, taskID)
+		if err != nil {
+			lastErr = err
+			fmt.Fprintf(runtime.IO().ErrOut, "Wiki move status attempt %d/%d failed: %v\n", attempt, wikiMovePollAttempts, err)
+			continue
+		}
+		lastStatus = status
+		hadSuccessfulPoll = true
+
+		if status.Ready() {
+			fmt.Fprintf(runtime.IO().ErrOut, "Wiki move task completed successfully.\n")
+			return status, true, nil
+		}
+		if status.Failed() {
+			return status, false, output.Errorf(output.ExitAPI, "api_error", "wiki move task failed: %s", status.PrimaryStatusLabel())
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Wiki move status %d/%d: %s\n", attempt, wikiMovePollAttempts, status.PrimaryStatusLabel())
+	}
+
+	if !hadSuccessfulPoll && lastErr != nil {
+		nextCommand := wikiMoveTaskResultCommand(taskID, runtime.As())
+		hint := fmt.Sprintf(
+			"the wiki move task was created but every status poll failed (task_id=%s)\nretry status lookup with: %s",
+			taskID,
+			nextCommand,
+		)
+		var exitErr *output.ExitError
+		if errors.As(lastErr, &exitErr) && exitErr.Detail != nil {
+			if strings.TrimSpace(exitErr.Detail.Hint) != "" {
+				hint = exitErr.Detail.Hint + "\n" + hint
+			}
+			return lastStatus, false, output.ErrWithHint(exitErr.Code, exitErr.Detail.Type, exitErr.Detail.Message, hint)
+		}
+		return lastStatus, false, output.ErrWithHint(output.ExitAPI, "api_error", lastErr.Error(), hint)
+	}
+
+	return lastStatus, false, nil
+}
+
+func parseWikiMoveTaskStatus(taskID string, task map[string]interface{}) (wikiMoveTaskStatus, error) {
+	if task == nil {
+		return wikiMoveTaskStatus{}, output.Errorf(output.ExitAPI, "api_error", "wiki task response missing task")
+	}
+
+	status := wikiMoveTaskStatus{
+		TaskID: common.GetString(task, "task_id"),
+	}
+	if status.TaskID == "" {
+		status.TaskID = taskID
+	}
+
+	for _, item := range common.GetSlice(task, "move_result") {
+		resultMap, ok := item.(map[string]interface{})
+		if !ok {
+			continue
+		}
+
+		var node *wikiNodeRecord
+		if nodeMap := common.GetMap(resultMap, "node"); nodeMap != nil {
+			parsedNode, err := parseWikiNodeRecord(nodeMap)
+			if err != nil {
+				return wikiMoveTaskStatus{}, err
+			}
+			node = parsedNode
+		}
+
+		status.MoveResults = append(status.MoveResults, wikiMoveTaskResult{
+			Node:      node,
+			Status:    int(common.GetFloat(resultMap, "status")),
+			StatusMsg: common.GetString(resultMap, "status_msg"),
+		})
+	}
+
+	return status, nil
+}
+
+func appendWikiNodeOutput(out map[string]interface{}, node *wikiNodeRecord) {
+	if out == nil || node == nil {
+		return
+	}
+	out["space_id"] = node.SpaceID
+	out["node_token"] = node.NodeToken
+	out["obj_token"] = node.ObjToken
+	out["obj_type"] = node.ObjType
+	out["parent_node_token"] = node.ParentNodeToken
+	out["node_type"] = node.NodeType
+	out["origin_node_token"] = node.OriginNodeToken
+	out["title"] = node.Title
+	out["has_child"] = node.HasChild
+}

shortcuts/wiki/wiki_move_test.go

@@ -0,0 +1,905 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type fakeWikiMoveNodeCall struct {
+	SourceSpaceID string
+	Spec          wikiMoveSpec
+}
+
+type fakeWikiDocsToWikiMoveCall struct {
+	TargetSpaceID string
+	Spec          wikiMoveSpec
+}
+
+type fakeWikiMoveClient struct {
+	nodes map[string]*wikiNodeRecord
+
+	getNodeErr  error
+	moveNode    *wikiNodeRecord
+	moveNodeErr error
+	docsResp    *wikiMoveDocsResponse
+	docsErr     error
+
+	taskStatuses []wikiMoveTaskStatus
+	taskErrs     []error
+
+	getNodeCalls     []string
+	moveNodeCalls    []fakeWikiMoveNodeCall
+	docsToWikiCalls  []fakeWikiDocsToWikiMoveCall
+	moveTaskCallArgs []string
+}
+
+func (fake *fakeWikiMoveClient) GetNode(ctx context.Context, token string) (*wikiNodeRecord, error) {
+	fake.getNodeCalls = append(fake.getNodeCalls, token)
+	if fake.getNodeErr != nil {
+		return nil, fake.getNodeErr
+	}
+	if node, ok := fake.nodes[token]; ok {
+		return node, nil
+	}
+	return &wikiNodeRecord{}, nil
+}
+
+func (fake *fakeWikiMoveClient) MoveNode(ctx context.Context, sourceSpaceID string, spec wikiMoveSpec) (*wikiNodeRecord, error) {
+	fake.moveNodeCalls = append(fake.moveNodeCalls, fakeWikiMoveNodeCall{SourceSpaceID: sourceSpaceID, Spec: spec})
+	if fake.moveNodeErr != nil {
+		return nil, fake.moveNodeErr
+	}
+	if fake.moveNode != nil {
+		return fake.moveNode, nil
+	}
+	return &wikiNodeRecord{SpaceID: sourceSpaceID, NodeToken: spec.NodeToken}, nil
+}
+
+func (fake *fakeWikiMoveClient) MoveDocsToWiki(ctx context.Context, targetSpaceID string, spec wikiMoveSpec) (*wikiMoveDocsResponse, error) {
+	fake.docsToWikiCalls = append(fake.docsToWikiCalls, fakeWikiDocsToWikiMoveCall{TargetSpaceID: targetSpaceID, Spec: spec})
+	if fake.docsErr != nil {
+		return nil, fake.docsErr
+	}
+	if fake.docsResp != nil {
+		return fake.docsResp, nil
+	}
+	return &wikiMoveDocsResponse{}, nil
+}
+
+func (fake *fakeWikiMoveClient) GetMoveTask(ctx context.Context, taskID string) (wikiMoveTaskStatus, error) {
+	idx := len(fake.moveTaskCallArgs)
+	fake.moveTaskCallArgs = append(fake.moveTaskCallArgs, taskID)
+	if idx < len(fake.taskErrs) && fake.taskErrs[idx] != nil {
+		return wikiMoveTaskStatus{TaskID: taskID}, fake.taskErrs[idx]
+	}
+	if idx < len(fake.taskStatuses) {
+		status := fake.taskStatuses[idx]
+		if status.TaskID == "" {
+			status.TaskID = taskID
+		}
+		return status, nil
+	}
+	return wikiMoveTaskStatus{TaskID: taskID}, nil
+}
+
+type mockWikiMoveTokenResolver struct {
+	token  string
+	scopes string
+	err    error
+}
+
+type wikiMoveAccountResolver struct {
+	cfg *core.CliConfig
+}
+
+func (r *wikiMoveAccountResolver) ResolveAccount(ctx context.Context) (*credential.Account, error) {
+	return credential.AccountFromCliConfig(r.cfg), nil
+}
+
+func (m *mockWikiMoveTokenResolver) ResolveToken(ctx context.Context, req credential.TokenSpec) (*credential.TokenResult, error) {
+	if m.err != nil {
+		return nil, m.err
+	}
+	token := m.token
+	if token == "" {
+		token = "test-token"
+	}
+	return &credential.TokenResult{Token: token, Scopes: m.scopes}, nil
+}
+
+var wikiMovePollMu sync.Mutex
+
+func withSingleWikiMovePoll(t *testing.T) {
+	t.Helper()
+	wikiMovePollMu.Lock()
+
+	prevAttempts, prevInterval := wikiMovePollAttempts, wikiMovePollInterval
+	wikiMovePollAttempts, wikiMovePollInterval = 1, 0
+	t.Cleanup(func() {
+		wikiMovePollAttempts, wikiMovePollInterval = prevAttempts, prevInterval
+		wikiMovePollMu.Unlock()
+	})
+}
+
+func newWikiMoveRuntimeWithScopes(t *testing.T, as core.Identity, scopes string) (*common.RuntimeContext, *bytes.Buffer) {
+	t.Helper()
+
+	cfg := wikiTestConfig()
+	factory, _, stderr, _ := cmdutil.TestFactory(t, cfg)
+	factory.Credential = credential.NewCredentialProvider(nil, nil, &mockWikiMoveTokenResolver{scopes: scopes}, nil)
+
+	runtime := common.TestNewRuntimeContextWithIdentity(&cobra.Command{Use: "wiki +move"}, cfg, as)
+	runtime.Factory = factory
+	return runtime, stderr
+}
+
+func decodeWikiEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
+	t.Helper()
+
+	var env struct {
+		OK   bool                   `json:"ok"`
+		Data map[string]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("unmarshal wiki envelope: %v\nstdout=%s", err, stdout.String())
+	}
+	if !env.OK {
+		t.Fatalf("expected ok=true envelope, got stdout=%s", stdout.String())
+	}
+	return env.Data
+}
+
+func decodeWikiCapturedJSONBody(t *testing.T, stub *httpmock.Stub) map[string]interface{} {
+	t.Helper()
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("unmarshal captured body: %v\nraw=%s", err, string(stub.CapturedBody))
+	}
+	return body
+}
+
+func TestValidateWikiMoveSpecRejectsInvalidCombinations(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		spec    wikiMoveSpec
+		wantErr string
+	}{
+		{
+			name:    "node move rejects docs flags",
+			spec:    wikiMoveSpec{NodeToken: "wik_node", ObjType: "sheet", TargetSpaceID: "space_dst"},
+			wantErr: "cannot be combined",
+		},
+		{
+			name:    "node move requires target",
+			spec:    wikiMoveSpec{NodeToken: "wik_node"},
+			wantErr: "cannot both be empty",
+		},
+		{
+			name:    "source space requires node token",
+			spec:    wikiMoveSpec{SourceSpaceID: "space_src", ObjType: "sheet", ObjToken: "sheet_token", TargetSpaceID: "space_dst"},
+			wantErr: "can only be used with --node-token",
+		},
+		{
+			name:    "docs to wiki requires obj type",
+			spec:    wikiMoveSpec{ObjToken: "sheet_token", TargetSpaceID: "space_dst"},
+			wantErr: "--obj-type is required",
+		},
+		{
+			name:    "docs to wiki requires obj token",
+			spec:    wikiMoveSpec{ObjType: "sheet", TargetSpaceID: "space_dst"},
+			wantErr: "--obj-token is required",
+		},
+		{
+			name:    "docs to wiki requires target space",
+			spec:    wikiMoveSpec{ObjType: "sheet", ObjToken: "sheet_token"},
+			wantErr: "--target-space-id is required",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := validateWikiMoveSpec(tt.spec)
+			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("expected error containing %q, got %v", tt.wantErr, err)
+			}
+		})
+	}
+}
+
+func TestValidateWikiMoveSpecAcceptsValidModes(t *testing.T) {
+	t.Parallel()
+
+	for _, spec := range []wikiMoveSpec{
+		{NodeToken: "wik_node", TargetSpaceID: "space_dst"},
+		{ObjType: "sheet", ObjToken: "sheet_token", TargetSpaceID: "space_dst", TargetParentToken: "wik_parent", Apply: true},
+	} {
+		if err := validateWikiMoveSpec(spec); err != nil {
+			t.Fatalf("validateWikiMoveSpec(%+v) error = %v", spec, err)
+		}
+	}
+}
+
+func TestWikiMoveDeclaredScopes(t *testing.T) {
+	t.Parallel()
+
+	want := []string{"wiki:node:move", "wiki:node:read", "wiki:space:read"}
+	if !reflect.DeepEqual(WikiMove.Scopes, want) {
+		t.Fatalf("WikiMove.Scopes = %v, want %v", WikiMove.Scopes, want)
+	}
+}
+
+func TestWikiMoveShortcutMissingDeclaredScope(t *testing.T) {
+	cfg := wikiTestConfig()
+	factory, stdout, _, _ := cmdutil.TestFactory(t, cfg)
+	factory.Credential = credential.NewCredentialProvider(nil, &wikiMoveAccountResolver{cfg: cfg}, &mockWikiMoveTokenResolver{scopes: "wiki:node:read"}, nil)
+
+	err := mountAndRunWiki(t, WikiMove, []string{
+		"+move",
+		"--node-token", "wik_node",
+		"--target-space-id", "space_dst",
+		"--as", "user",
+	}, factory, stdout)
+	if err == nil {
+		t.Fatal("expected missing scope error, got nil")
+	}
+	if !strings.Contains(err.Error(), "missing required scope(s): wiki:node:move") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestWikiMoveTaskStatusPendingAndFallbackLabels(t *testing.T) {
+	t.Parallel()
+
+	pending := wikiMoveTaskStatus{}
+	if !pending.Pending() || pending.PrimaryStatusLabel() != "processing" {
+		t.Fatalf("pending status = %+v", pending)
+	}
+
+	ready := wikiMoveTaskStatus{MoveResults: []wikiMoveTaskResult{{Status: 0}}}
+	if !ready.Ready() || ready.PrimaryStatusLabel() != "success" {
+		t.Fatalf("ready status = %+v", ready)
+	}
+
+	failed := wikiMoveTaskStatus{MoveResults: []wikiMoveTaskResult{{Status: -1}}}
+	if !failed.Failed() || failed.PrimaryStatusLabel() != "failure" {
+		t.Fatalf("failed status = %+v", failed)
+	}
+}
+
+func TestWikiMoveTaskStatusPrimarySurfacesFailureOverEarlierSuccess(t *testing.T) {
+	t.Parallel()
+
+	status := wikiMoveTaskStatus{
+		MoveResults: []wikiMoveTaskResult{
+			{Status: 0, StatusMsg: "success"},
+			{Status: -3, StatusMsg: "permission denied"},
+			{Status: 1, StatusMsg: "processing"},
+		},
+	}
+	if got := status.PrimaryStatusCode(); got != -3 {
+		t.Fatalf("PrimaryStatusCode = %d, want -3", got)
+	}
+	if got := status.PrimaryStatusLabel(); got != "permission denied" {
+		t.Fatalf("PrimaryStatusLabel = %q, want permission denied", got)
+	}
+	// FirstResult must keep its literal "first entry" semantics for callers
+	// that flatten node fields from the first move_result.
+	if first := status.FirstResult(); first == nil || first.StatusMsg != "success" {
+		t.Fatalf("FirstResult = %+v, want first success entry", first)
+	}
+}
+
+func TestWikiMoveTaskStatusPrimaryPrefersProcessingOverFirstSuccess(t *testing.T) {
+	t.Parallel()
+
+	status := wikiMoveTaskStatus{
+		MoveResults: []wikiMoveTaskResult{
+			{Status: 0, StatusMsg: "success"},
+			{Status: 1, StatusMsg: "processing"},
+		},
+	}
+	if got := status.PrimaryStatusCode(); got != 1 {
+		t.Fatalf("PrimaryStatusCode = %d, want 1", got)
+	}
+	if got := status.PrimaryStatusLabel(); got != "processing" {
+		t.Fatalf("PrimaryStatusLabel = %q, want processing", got)
+	}
+}
+
+func TestWikiMoveValidateRejectsBotMyLibrary(t *testing.T) {
+	cfg := wikiTestConfig()
+	factory, stdout, _, _ := cmdutil.TestFactory(t, cfg)
+
+	err := mountAndRunWiki(t, WikiMove, []string{
+		"+move",
+		"--obj-type", "docx",
+		"--obj-token", "doccnXXX",
+		"--target-space-id", "my_library",
+		"--as", "bot",
+	}, factory, stdout)
+	if err == nil {
+		t.Fatal("expected validation error for bot + my_library, got nil")
+	}
+	if !strings.Contains(err.Error(), "my_library") || !strings.Contains(err.Error(), "--as bot") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestWikiMoveValidateAllowsUserMyLibrary(t *testing.T) {
+	t.Parallel()
+
+	// Bot guard must not affect user identity. We only assert the my_library
+	// validation path doesn't trip; an empty obj-token still fails downstream
+	// for unrelated reasons, so we check the error does not mention my_library.
+	if err := validateWikiMoveSpec(wikiMoveSpec{
+		ObjType:       "docx",
+		ObjToken:      "doccnXXX",
+		TargetSpaceID: "my_library",
+	}); err != nil {
+		t.Fatalf("validateWikiMoveSpec(user my_library) = %v, want nil", err)
+	}
+}
+
+func TestWikiMoveDryRunNodeMoveIncludesResolutionSteps(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "wiki +move"}
+	cmd.Flags().String("node-token", "", "")
+	cmd.Flags().String("source-space-id", "", "")
+	cmd.Flags().String("target-space-id", "", "")
+	cmd.Flags().String("target-parent-token", "", "")
+	cmd.Flags().String("obj-type", "", "")
+	cmd.Flags().String("obj-token", "", "")
+	cmd.Flags().Bool("apply", false, "")
+	if err := cmd.Flags().Set("node-token", "wik_node"); err != nil {
+		t.Fatalf("set --node-token: %v", err)
+	}
+	if err := cmd.Flags().Set("target-parent-token", "wik_parent"); err != nil {
+		t.Fatalf("set --target-parent-token: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+	dry := WikiMove.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)
+	}
+	if !bytes.Contains(data, []byte(`"description":"3-step orchestration:`)) {
+		t.Fatalf("dry run missing 3-step description: %s", string(data))
+	}
+	if !bytes.Contains(data, []byte(`"target_parent_token":"wik_parent"`)) {
+		t.Fatalf("dry run missing target_parent_token body: %s", string(data))
+	}
+	if !bytes.Contains(data, []byte(`/open-apis/wiki/v2/spaces/\u003cresolved_source_space_id\u003e/nodes/wik_node/move`)) {
+		t.Fatalf("dry run missing resolved source placeholder: %s", string(data))
+	}
+}
+
+func TestWikiMoveDryRunDocsToWikiIncludesTaskPoll(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "wiki +move"}
+	cmd.Flags().String("node-token", "", "")
+	cmd.Flags().String("source-space-id", "", "")
+	cmd.Flags().String("target-space-id", "", "")
+	cmd.Flags().String("target-parent-token", "", "")
+	cmd.Flags().String("obj-type", "", "")
+	cmd.Flags().String("obj-token", "", "")
+	cmd.Flags().Bool("apply", false, "")
+	if err := cmd.Flags().Set("obj-type", "sheet"); err != nil {
+		t.Fatalf("set --obj-type: %v", err)
+	}
+	if err := cmd.Flags().Set("obj-token", "sheet_token"); err != nil {
+		t.Fatalf("set --obj-token: %v", err)
+	}
+	if err := cmd.Flags().Set("target-space-id", "space_dst"); err != nil {
+		t.Fatalf("set --target-space-id: %v", err)
+	}
+	if err := cmd.Flags().Set("apply", "true"); err != nil {
+		t.Fatalf("set --apply: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+	dry := WikiMove.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)
+	}
+	if !bytes.Contains(data, []byte(`"obj_type":"sheet"`)) || !bytes.Contains(data, []byte(`"apply":true`)) {
+		t.Fatalf("dry run missing docs-to-wiki body: %s", string(data))
+	}
+	if !bytes.Contains(data, []byte(`"task_type":"move"`)) {
+		t.Fatalf("dry run missing task polling params: %s", string(data))
+	}
+}
+
+func TestResolveWikiNodeMoveSpacesUsesSourceAndTargetLookups(t *testing.T) {
+	t.Parallel()
+
+	client := &fakeWikiMoveClient{
+		nodes: map[string]*wikiNodeRecord{
+			"wik_node":   {SpaceID: "space_src"},
+			"wik_parent": {SpaceID: "space_dst"},
+		},
+	}
+
+	sourceSpaceID, targetSpaceID, err := resolveWikiNodeMoveSpaces(context.Background(), client, wikiMoveSpec{
+		NodeToken:         "wik_node",
+		TargetParentToken: "wik_parent",
+	})
+	if err != nil {
+		t.Fatalf("resolveWikiNodeMoveSpaces() error = %v", err)
+	}
+	if sourceSpaceID != "space_src" || targetSpaceID != "space_dst" {
+		t.Fatalf("resolved spaces = (%q, %q), want (%q, %q)", sourceSpaceID, targetSpaceID, "space_src", "space_dst")
+	}
+	if strings.Join(client.getNodeCalls, ",") != "wik_node,wik_parent" {
+		t.Fatalf("getNodeCalls = %v, want source and target-parent lookups", client.getNodeCalls)
+	}
+}
+
+func TestResolveWikiNodeMoveSpacesRejectsTargetSpaceMismatch(t *testing.T) {
+	t.Parallel()
+
+	client := &fakeWikiMoveClient{
+		nodes: map[string]*wikiNodeRecord{
+			"wik_parent": {SpaceID: "space_parent"},
+		},
+	}
+
+	_, _, err := resolveWikiNodeMoveSpaces(context.Background(), client, wikiMoveSpec{
+		NodeToken:         "wik_node",
+		SourceSpaceID:     "space_src",
+		TargetSpaceID:     "space_other",
+		TargetParentToken: "wik_parent",
+	})
+	if err == nil || !strings.Contains(err.Error(), "does not match") {
+		t.Fatalf("expected mismatch error, got %v", err)
+	}
+}
+
+func TestRunWikiNodeMoveReturnsResolvedMetadata(t *testing.T) {
+	t.Parallel()
+
+	client := &fakeWikiMoveClient{
+		nodes: map[string]*wikiNodeRecord{
+			"wik_node":   {SpaceID: "space_src"},
+			"wik_parent": {SpaceID: "space_dst"},
+		},
+		moveNode: &wikiNodeRecord{
+			SpaceID:         "space_dst",
+			NodeToken:       "wik_moved",
+			ObjToken:        "sheet_token",
+			ObjType:         "sheet",
+			ParentNodeToken: "wik_parent",
+			NodeType:        wikiNodeTypeOrigin,
+			Title:           "Roadmap",
+		},
+	}
+
+	out, err := runWikiNodeMove(context.Background(), client, wikiMoveSpec{
+		NodeToken:         "wik_node",
+		TargetParentToken: "wik_parent",
+	})
+	if err != nil {
+		t.Fatalf("runWikiNodeMove() error = %v", err)
+	}
+	if len(client.moveNodeCalls) != 1 {
+		t.Fatalf("MoveNode called %d times, want 1", len(client.moveNodeCalls))
+	}
+	if client.moveNodeCalls[0].SourceSpaceID != "space_src" {
+		t.Fatalf("source space = %q, want %q", client.moveNodeCalls[0].SourceSpaceID, "space_src")
+	}
+	if out["mode"] != wikiMoveModeNode || out["source_space_id"] != "space_src" || out["target_space_id"] != "space_dst" {
+		t.Fatalf("unexpected node move output: %#v", out)
+	}
+	if out["node_token"] != "wik_moved" || out["title"] != "Roadmap" {
+		t.Fatalf("node fields not propagated: %#v", out)
+	}
+}
+
+func TestRunWikiMoveDispatchesByMode(t *testing.T) {
+	t.Parallel()
+
+	runtime, _ := newWikiMoveRuntimeWithScopes(t, core.AsUser, "")
+	client := &fakeWikiMoveClient{
+		docsResp: &wikiMoveDocsResponse{WikiToken: "wik_ready"},
+		moveNode: &wikiNodeRecord{SpaceID: "space_dst", NodeToken: "wik_node"},
+	}
+
+	nodeOut, err := runWikiMove(context.Background(), client, runtime, wikiMoveSpec{
+		NodeToken:     "wik_node",
+		SourceSpaceID: "space_src",
+		TargetSpaceID: "space_dst",
+	})
+	if err != nil {
+		t.Fatalf("runWikiMove(node) error = %v", err)
+	}
+	if nodeOut["mode"] != wikiMoveModeNode {
+		t.Fatalf("node mode output = %#v", nodeOut)
+	}
+
+	docsOut, err := runWikiMove(context.Background(), client, runtime, wikiMoveSpec{
+		ObjType:       "sheet",
+		ObjToken:      "sheet_token",
+		TargetSpaceID: "space_dst",
+	})
+	if err != nil {
+		t.Fatalf("runWikiMove(docs_to_wiki) error = %v", err)
+	}
+	if docsOut["mode"] != wikiMoveModeDocsToWiki {
+		t.Fatalf("docs-to-wiki output = %#v", docsOut)
+	}
+}
+
+func TestRunWikiDocsToWikiMoveSyncReady(t *testing.T) {
+	t.Parallel()
+
+	runtime, _ := newWikiMoveRuntimeWithScopes(t, core.AsUser, "")
+	client := &fakeWikiMoveClient{
+		docsResp: &wikiMoveDocsResponse{WikiToken: "wik_ready"},
+	}
+
+	out, err := runWikiDocsToWikiMove(context.Background(), client, runtime, wikiMoveSpec{
+		ObjType:       "sheet",
+		ObjToken:      "sheet_token",
+		TargetSpaceID: "space_dst",
+	})
+	if err != nil {
+		t.Fatalf("runWikiDocsToWikiMove() error = %v", err)
+	}
+	if out["ready"] != true || out["failed"] != false {
+		t.Fatalf("expected ready sync result, got %#v", out)
+	}
+	if out["wiki_token"] != "wik_ready" || out["node_token"] != "wik_ready" {
+		t.Fatalf("wiki token fields = %#v", out)
+	}
+	if len(client.docsToWikiCalls) != 1 || client.docsToWikiCalls[0].TargetSpaceID != "space_dst" {
+		t.Fatalf("unexpected docs-to-wiki calls: %#v", client.docsToWikiCalls)
+	}
+}
+
+func TestRunWikiDocsToWikiMoveApplied(t *testing.T) {
+	t.Parallel()
+
+	runtime, _ := newWikiMoveRuntimeWithScopes(t, core.AsUser, "")
+	client := &fakeWikiMoveClient{
+		docsResp: &wikiMoveDocsResponse{Applied: true},
+	}
+
+	out, err := runWikiDocsToWikiMove(context.Background(), client, runtime, wikiMoveSpec{
+		ObjType:       "sheet",
+		ObjToken:      "sheet_token",
+		TargetSpaceID: "space_dst",
+	})
+	if err != nil {
+		t.Fatalf("runWikiDocsToWikiMove() error = %v", err)
+	}
+	if out["applied"] != true || out["ready"] != false || out["failed"] != false {
+		t.Fatalf("expected applied response, got %#v", out)
+	}
+	if out["status_msg"] != "move request submitted for approval" {
+		t.Fatalf("status_msg = %#v", out["status_msg"])
+	}
+}
+
+func TestRunWikiDocsToWikiMoveAsyncReady(t *testing.T) {
+	withSingleWikiMovePoll(t)
+
+	runtime, stderr := newWikiMoveRuntimeWithScopes(t, core.AsUser, "")
+	client := &fakeWikiMoveClient{
+		docsResp: &wikiMoveDocsResponse{TaskID: "task_123"},
+		taskStatuses: []wikiMoveTaskStatus{{
+			MoveResults: []wikiMoveTaskResult{{
+				Status:    0,
+				StatusMsg: "success",
+				Node: &wikiNodeRecord{
+					SpaceID:   "space_dst",
+					NodeToken: "wik_done",
+					ObjToken:  "sheet_token",
+					ObjType:   "sheet",
+					NodeType:  wikiNodeTypeOrigin,
+					Title:     "Roadmap",
+				},
+			}},
+		}},
+	}
+
+	out, err := runWikiDocsToWikiMove(context.Background(), client, runtime, wikiMoveSpec{
+		ObjType:       "sheet",
+		ObjToken:      "sheet_token",
+		TargetSpaceID: "space_dst",
+	})
+	if err != nil {
+		t.Fatalf("runWikiDocsToWikiMove() error = %v", err)
+	}
+	if out["task_id"] != "task_123" || out["ready"] != true || out["failed"] != false {
+		t.Fatalf("unexpected async-ready output: %#v", out)
+	}
+	if out["wiki_token"] != "wik_done" || out["title"] != "Roadmap" || out["status_msg"] != "success" {
+		t.Fatalf("async-ready output missing flattened fields: %#v", out)
+	}
+	if !strings.Contains(stderr.String(), "Docs-to-wiki move is async") || !strings.Contains(stderr.String(), "completed successfully") {
+		t.Fatalf("stderr = %q, want async progress logs", stderr.String())
+	}
+}
+
+func TestRunWikiDocsToWikiMoveAsyncTimeoutReturnsNextCommand(t *testing.T) {
+	withSingleWikiMovePoll(t)
+
+	runtime, stderr := newWikiMoveRuntimeWithScopes(t, core.AsUser, "")
+	client := &fakeWikiMoveClient{
+		docsResp: &wikiMoveDocsResponse{TaskID: "task_123"},
+		taskStatuses: []wikiMoveTaskStatus{{
+			MoveResults: []wikiMoveTaskResult{{Status: 1, StatusMsg: "processing"}},
+		}},
+	}
+
+	out, err := runWikiDocsToWikiMove(context.Background(), client, runtime, wikiMoveSpec{
+		ObjType:       "sheet",
+		ObjToken:      "sheet_token",
+		TargetSpaceID: "space_dst",
+	})
+	if err != nil {
+		t.Fatalf("runWikiDocsToWikiMove() error = %v", err)
+	}
+	if out["ready"] != false || out["timed_out"] != true || out["next_command"] != wikiMoveTaskResultCommand("task_123", core.AsUser) {
+		t.Fatalf("expected timeout response, got %#v", out)
+	}
+	if out["status_msg"] != "processing" {
+		t.Fatalf("status_msg = %#v, want processing", out["status_msg"])
+	}
+	if !strings.Contains(stderr.String(), "Continue with") {
+		t.Fatalf("stderr = %q, want continuation hint", stderr.String())
+	}
+}
+
+func TestRunWikiDocsToWikiMoveAsyncFailureReturnsStructuredError(t *testing.T) {
+	withSingleWikiMovePoll(t)
+
+	runtime, _ := newWikiMoveRuntimeWithScopes(t, core.AsUser, "")
+	client := &fakeWikiMoveClient{
+		docsResp: &wikiMoveDocsResponse{TaskID: "task_123"},
+		taskStatuses: []wikiMoveTaskStatus{{
+			MoveResults: []wikiMoveTaskResult{{Status: -1, StatusMsg: "approval rejected"}},
+		}},
+	}
+
+	_, err := runWikiDocsToWikiMove(context.Background(), client, runtime, wikiMoveSpec{
+		ObjType:       "sheet",
+		ObjToken:      "sheet_token",
+		TargetSpaceID: "space_dst",
+	})
+	if err == nil || !strings.Contains(err.Error(), "wiki move task failed: approval rejected") {
+		t.Fatalf("expected async failure error, got %v", err)
+	}
+}
+
+func TestWikiMoveExecuteNodeShortcut(t *testing.T) {
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{"space_id": "space_src"},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{"space_id": "space_dst"},
+			},
+		},
+	})
+	moveStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/wiki/v2/spaces/space_src/nodes/wik_node/move",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"space_id":          "space_dst",
+					"node_token":        "wik_moved",
+					"obj_token":         "sheet_token",
+					"obj_type":          "sheet",
+					"parent_node_token": "wik_parent",
+					"node_type":         "origin",
+					"title":             "Roadmap",
+				},
+			},
+		},
+	}
+	reg.Register(moveStub)
+
+	err := mountAndRunWiki(t, WikiMove, []string{
+		"+move",
+		"--node-token", "wik_node",
+		"--target-parent-token", "wik_parent",
+		"--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	if data["mode"] != wikiMoveModeNode || data["source_space_id"] != "space_src" || data["target_space_id"] != "space_dst" {
+		t.Fatalf("unexpected node shortcut output: %#v", data)
+	}
+	body := decodeWikiCapturedJSONBody(t, moveStub)
+	if body["target_parent_token"] != "wik_parent" {
+		t.Fatalf("move body = %#v, want target_parent_token", body)
+	}
+}
+
+func TestWikiMoveExecuteDocsToWikiShortcutAsyncSuccess(t *testing.T) {
+	withSingleWikiMovePoll(t)
+
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+	docsStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/wiki/v2/spaces/space_dst/nodes/move_docs_to_wiki",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"task_id": "task_123",
+			},
+		},
+	}
+	reg.Register(docsStub)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/tasks/task_123",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"task": map[string]interface{}{
+					"task_id": "task_123",
+					"move_result": []interface{}{
+						map[string]interface{}{
+							"status":     0,
+							"status_msg": "success",
+							"node": map[string]interface{}{
+								"space_id":   "space_dst",
+								"node_token": "wik_done",
+								"obj_token":  "sheet_token",
+								"obj_type":   "sheet",
+								"node_type":  "origin",
+								"title":      "Roadmap",
+							},
+						},
+					},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunWiki(t, WikiMove, []string{
+		"+move",
+		"--obj-type", "sheet",
+		"--obj-token", "sheet_token",
+		"--target-space-id", "space_dst",
+		"--apply",
+		"--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	if data["mode"] != wikiMoveModeDocsToWiki || data["ready"] != true || data["wiki_token"] != "wik_done" {
+		t.Fatalf("unexpected docs-to-wiki shortcut output: %#v", data)
+	}
+	body := decodeWikiCapturedJSONBody(t, docsStub)
+	if body["obj_type"] != "sheet" || body["obj_token"] != "sheet_token" || body["apply"] != true {
+		t.Fatalf("docs-to-wiki body = %#v", body)
+	}
+}
+
+func TestPollWikiMoveTaskWrapsRepeatedPollFailuresWithHint(t *testing.T) {
+	withSingleWikiMovePoll(t)
+
+	runtime, stderr := newWikiMoveRuntimeWithScopes(t, core.AsUser, "")
+	client := &fakeWikiMoveClient{
+		taskErrs: []error{output.ErrWithHint(output.ExitAPI, "api_error", "poll failed", "retry original")},
+	}
+
+	status, ready, err := pollWikiMoveTask(context.Background(), client, runtime, "task_123")
+	if err == nil {
+		t.Fatal("expected pollWikiMoveTask() error, got nil")
+	}
+	if ready {
+		t.Fatal("expected ready=false when every poll fails")
+	}
+	if status.TaskID != "task_123" {
+		t.Fatalf("status.TaskID = %q, want %q", status.TaskID, "task_123")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected structured exit error, got %T %v", err, err)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "retry original") || !strings.Contains(exitErr.Detail.Hint, wikiMoveTaskResultCommand("task_123", core.AsUser)) {
+		t.Fatalf("hint = %q, want original hint and resume command", exitErr.Detail.Hint)
+	}
+	if !strings.Contains(stderr.String(), "Wiki move status attempt 1/1 failed") {
+		t.Fatalf("stderr = %q, want poll failure log", stderr.String())
+	}
+}
+
+func TestParseWikiMoveTaskStatusFallbackTaskIDAndNode(t *testing.T) {
+	t.Parallel()
+
+	status, err := parseWikiMoveTaskStatus("task_fallback", map[string]interface{}{
+		"move_result": []interface{}{
+			map[string]interface{}{
+				"status":     0,
+				"status_msg": "success",
+				"node": map[string]interface{}{
+					"space_id":   "space_dst",
+					"node_token": "wik_done",
+					"obj_token":  "sheet_token",
+					"obj_type":   "sheet",
+					"node_type":  wikiNodeTypeOrigin,
+					"title":      "Roadmap",
+				},
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("parseWikiMoveTaskStatus() error = %v", err)
+	}
+	if status.TaskID != "task_fallback" {
+		t.Fatalf("TaskID = %q, want %q", status.TaskID, "task_fallback")
+	}
+	if !status.Ready() || status.PrimaryStatusLabel() != "success" {
+		t.Fatalf("unexpected parsed status: %+v", status)
+	}
+	if first := status.FirstResult(); first == nil || first.Node == nil || first.Node.NodeToken != "wik_done" {
+		t.Fatalf("parsed node = %+v", first)
+	}
+}
+
+func TestParseWikiMoveTaskStatusRejectsMissingTask(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseWikiMoveTaskStatus("task_123", nil)
+	if err == nil || !strings.Contains(err.Error(), "missing task") {
+		t.Fatalf("expected missing task error, got %v", err)
+	}
+}

shortcuts/wiki/wiki_node_create_test.go

@@ -94,15 +94,18 @@ func mountAndRunWiki(t *testing.T, shortcut common.Shortcut, args []string, fact
 	return parent.Execute()
 }
 
-func TestWikiShortcutsIncludesNodeCreate(t *testing.T) {
+func TestWikiShortcutsIncludeMoveAndNodeCreate(t *testing.T) {
 	t.Parallel()
 
 	shortcuts := Shortcuts()
-	if len(shortcuts) != 1 {
-		t.Fatalf("len(Shortcuts()) = %d, want 1", len(shortcuts))
+	if len(shortcuts) != 2 {
+		t.Fatalf("len(Shortcuts()) = %d, want 2", len(shortcuts))
 	}
-	if shortcuts[0].Command != "+node-create" {
-		t.Fatalf("shortcut command = %q, want %q", shortcuts[0].Command, "+node-create")
+	if shortcuts[0].Command != "+move" {
+		t.Fatalf("shortcuts[0].Command = %q, want %q", shortcuts[0].Command, "+move")
+	}
+	if shortcuts[1].Command != "+node-create" {
+		t.Fatalf("shortcuts[1].Command = %q, want %q", shortcuts[1].Command, "+node-create")
 	}
 }
 

skill-template/domains/drive.md

@@ -8,6 +8,9 @@
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 
+## 修改标题
+- 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型
+
 ## 核心概念
 
 ### 文档类型与 Token

skill-template/domains/sheets.md

@@ -126,4 +126,40 @@ lark-cli sheets spreadsheet.sheet.filters update \
 
 **常见错误：**
 - `Wrong Filter Value`：筛选已存在，需要先 delete 再 create
-- `Excess Limit`：update 时重复添加同一列条件
+- `Excess Limit`：update 时重复添加同一列条件
+
+### 单元格数据类型
+
+接受二维数组的 shortcut（`+write`/`+append` 的 `--values`、`+create` 的 `--data`）中，每个单元格值支持以下类型。**公式、带文本链接、@人、@文档、下拉列表必须使用对象格式**，直接传字符串会被当作纯文本存储。
+
+| 类型 | 写入格式 | 示例 |
+|------|---------|------|
+| 字符串 | `"文本"` | `"hello"` |
+| 数字 | `数字` | `123`、`3.14` |
+| 日期 | `数字`（自 1899-12-30 起的天数，需先设单元格日期格式） | `42101` |
+| 链接（纯 URL） | `"URL 字符串"` | `"https://example.com"` |
+| 链接（带文本） | `{"type":"url","text":"显示文本","link":"URL"}` | `{"type":"url","text":"飞书","link":"https://www.feishu.cn"}` |
+| 邮箱 | `"邮箱字符串"` | `"user@example.com"` |
+| **公式** | `{"type":"formula","text":"=公式"}` | `{"type":"formula","text":"=SUM(A1:A10)"}` |
+| @人 | `{"type":"mention","text":"标识","textType":"email\|openId\|unionId","notify":false}` | `{"type":"mention","text":"user@example.com","textType":"email","notify":false}`（notify 可选，默认 false；仅在用户明确要求通知时设为 true） |
+| @文档 | `{"type":"mention","textType":"fileToken","text":"token","objType":"类型"}` | `{"type":"mention","textType":"fileToken","text":"shtXXX","objType":"sheet"}` |
+| 下拉列表 | `{"type":"multipleValue","values":[值1,值2]}` | `{"type":"multipleValue","values":["选项A","选项B"]}` |
+
+**写入公式示例**：
+
+```bash
+# ✅ 正确：使用对象格式
+lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \
+  --values '[[{"type":"formula","text":"=SUM(C2:C5)"}]]'
+
+# ❌ 错误：直接传字符串，会被存为纯文本
+lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \
+  --values '[["=SUM(C2:C5)"]]'
+```
+
+> **公式语法参考**：涉及 ARRAYFORMULA、原生数组函数、MAP/LAMBDA、日期差、Excel 公式改写等飞书特有规则时，先阅读 [`references/lark-sheets-formula.md`](references/lark-sheets-formula.md)。
+
+**限制**：
+- 公式支持 IMPORTRANGE 跨表引用（最多 5 层嵌套、每个工作表最多 100 个引用）
+- @人仅支持同租户用户，单次最多 50 人
+- 下拉列表需**先通过 `+set-dropdown` 配置下拉选项**，否则 `multipleValue` 写入会变成纯文本。值中的字符串不能包含逗号

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

@@ -31,7 +31,7 @@ lark-cli base +record-upload-attachment \
 | `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
 | `--record-id <id>` | 是 | 记录 ID |
 | `--field-id <id_or_name>` | 是 | 附件字段 ID 或字段名 |
-| `--file <path>` | 是 | 本地文件路径，最大 20MB |
+| `--file <path>` | 是 | 本地文件路径，最大 2GB |
 | `--name <name>` | 否 | 写入附件字段时显示的文件名，默认使用本地文件名 |
 
 
@@ -43,6 +43,7 @@ lark-cli base +record-upload-attachment \
 ## 坑点
 
 - ⚠️ 目标字段必须是 `attachment` 字段。
+- ⚠️ 记录里的附件 `file_token` 属于 Drive media token；下载时不要走 `lark-cli drive +download`，应使用 `lark-cli docs +media-download --token <file_token> --output <path>`。
 
 ## 参考
 

skills/lark-drive/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-drive
 version: 1.0.0
-description: "飞书云空间：管理云空间中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件；也负责把本地 Word/Markdown/Excel/CSV 导入为飞书在线云文档（docx、sheet、bitable）。当用户需要上传或下载文件、整理云空间目录、查看文件详情、管理评论、管理文档权限、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base 时使用。"
+description: "飞书云空间：管理云空间中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word/Markdown/Excel/CSV 导入为飞书在线云文档（docx、sheet、bitable）。当用户需要上传或下载文件、整理云空间目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base 时使用。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -21,6 +21,9 @@ metadata:
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 
+## 修改标题
+- 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型
+
 ## 核心概念
 
 ### 文档类型与 Token
@@ -156,7 +159,7 @@ Drive Folder (云空间文件夹)
 - 使用 `drive file.comments batch_query` 是**已知评论 ID 后**的批量查询，需要传入具体的评论 ID 列表。
 - 使用 `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论，或获取"最新/最后 N 条评论"等场景。
 
-#### Reaction 场景
+#### Reaction / 表情场景
 - 遇到评论 / 回复上的 reaction（表情、各表情数量、谁点了什么、添加/删除表情）相关问题时，**先阅读 [lark-drive-reactions.md](../../skills/lark-drive/references/lark-drive-reactions.md) 了解如何使用**。
 
 ### 典型错误与解决方案
@@ -217,6 +220,7 @@ lark-cli drive <resource> <method> [flags] # 调用 API
   - `copy` — 复制文件
   - `create_folder` — 新建文件夹
   - `list` — 获取文件夹下的清单
+  - `patch` — 修改文件标题
 
 ### file.comments
 
@@ -267,6 +271,7 @@ lark-cli drive <resource> <method> [flags] # 调用 API
 | `files.copy` | `docs:document:copy` |
 | `files.create_folder` | `space:folder:create` |
 | `files.list` | `space:document:retrieve` |
+| `files.patch` | `docx:document:write_only` |
 | `file.comments.batch_query` | `docs:document.comment:read` |
 | `file.comments.create_v2` | `docs:document.comment:create` |
 | `file.comments.list` | `docs:document.comment:read` |

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

@@ -5,6 +5,33 @@
 
 将文件或文件夹移动到用户云空间的其他位置。
 
+## 与 `wiki +move` 的区别
+
+- `drive +move` 只处理 **Drive 文件夹树内部** 的位置调整，目标位置用 `--folder-token` 表示
+- `wiki +move` 处理的是 **Wiki 知识空间 / 页面层级**：要么移动已有 Wiki 节点，要么把 Drive 文档迁入 Wiki
+- 如果用户说“移动到某个文件夹”“移动到我的空间根目录”，应使用 `drive +move`
+- 如果用户说“移动到某个知识库 / 页面下”“迁入 Wiki / 知识空间”，应使用 `wiki +move`
+- 如果用户说“移动到我的文档库 / 我的知识库 / 个人知识库 / my_library”，不要使用 `drive +move`；先按 Wiki 目标处理
+- `我的文档库` 不是 Drive root folder，也不是 `--folder-token` 省略后的默认目的地
+- `drive +move` 不支持 wiki 文档；如果目标是 Wiki，不要尝试用 `drive +move` 代替
+
+## 不要误用到 `我的文档库`
+
+下面几种说法都**不应该**触发 `drive +move`：
+
+- `移动到我的文档库`
+- `放到我的知识库`
+- `迁入个人知识库`
+- `move to My Document Library`
+
+这些目标都应该先走 Wiki 解析流程：
+
+```bash
+lark-cli wiki spaces get --params '{"space_id":"my_library"}'
+```
+
+拿到真实 `space_id` 后，再改用 `wiki +move`。不要因为 `drive +move` 可以省略 `--folder-token` 就把它当作“我的文档库”的近似目标。
+
 ## 命令
 
 ```bash
@@ -60,6 +87,7 @@ lark-cli drive +move \
 - **轮询超时不是失败**：文件夹移动内置最多轮询 30 次、每次间隔 2 秒；如果轮询结束任务仍未完成，会返回 `task_id`、`status`、`ready=false`、`timed_out=true` 和 `next_command`
 - **继续查询**：当看到 `next_command` 时，改用 `lark-cli drive +task_result --scenario task_check --task-id <TASK_ID>` 继续查询
 - **目标文件夹**：如果不指定 `--folder-token`，文件将被移动到用户的根文件夹（"我的空间"）
+- **不要混淆产品概念**：这里的“根文件夹 / 我的空间”仅属于 Drive 文件夹树，不等于 Wiki 的“我的文档库”
 - **权限要求**：需要被移动文件的可管理权限、被移动文件所在位置的编辑权限、目标位置的编辑权限
 
 ## 推荐续跑方式

skills/lark-drive/references/lark-drive-task-result.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-查询异步任务结果。该 shortcut 聚合了导入、导出、移动/删除文件夹等多种异步任务的结果查询，统一接口方便调用。
+查询异步任务结果。该 shortcut 聚合了导入、导出、移动/删除文件夹、Wiki 节点 / 文档迁入 Wiki 等多种异步任务的结果查询，统一接口方便调用。
 
 > [!IMPORTANT]
 > 对于 `import` 场景，如果使用 `--as bot` 且这次查询**已经拿到最终在线文档目标**（`ready=true` 且返回了最终 `token` / `url`），CLI 会**再次尝试为当前 CLI 用户自动授予该资源的 `full_access`（可管理权限）**。
@@ -35,15 +35,20 @@ lark-cli drive +task_result \
 lark-cli drive +task_result \
   --scenario task_check \
   --task-id <TASK_ID>
+
+# 查询 Wiki 移动任务结果（wiki +move 异步超时后的续跑）
+lark-cli drive +task_result \
+  --scenario wiki_move \
+  --task-id <TASK_ID>
 ```
 
 ## 参数
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--scenario` | 是 | 任务场景，可选值：`import` (导入任务)、`export` (导出任务)、`task_check` (移动/删除文件夹任务) |
+| `--scenario` | 是 | 任务场景，可选值：`import` (导入任务)、`export` (导出任务)、`task_check` (移动/删除文件夹任务)、`wiki_move` (Wiki 移动任务) |
 | `--ticket` | 条件必填 | 异步任务 ticket，**import/export 场景必填** |
-| `--task-id` | 条件必填 | 异步任务 ID，**task_check 场景必填** |
+| `--task-id` | 条件必填 | 异步任务 ID，**task_check / wiki_move 场景必填** |
 | `--file-token` | 条件必填 | 导出任务对应的源文档 token，**export 场景必填** |
 
 ## 场景说明
@@ -53,6 +58,7 @@ lark-cli drive +task_result \
 | `import` | 文档导入任务（如将本地文件导入为云文档） | `--ticket` |
 | `export` | 文档导出任务（如云文档导出为 PDF/Word） | `--ticket`、`--file-token` |
 | `task_check` | 文件夹移动/删除任务 | `--task-id` |
+| `wiki_move` | Wiki 移动任务（`wiki +move` 的 docs-to-wiki 异步流程，超时后续跑用） | `--task-id` |
 
 ## 返回结果
 
@@ -135,6 +141,55 @@ lark-cli drive +task_result \
 - `ready`: 是否已经完成
 - `failed`: 是否已经失败
 
+### Wiki_move 场景返回
+
+```json
+{
+  "scenario": "wiki_move",
+  "task_id": "<TASK_ID>",
+  "ready": true,
+  "failed": false,
+  "status": 0,
+  "status_msg": "success",
+  "wiki_token": "wikcnXXX",
+  "node_token": "wikcnXXX",
+  "space_id": "<TARGET_SPACE_ID>",
+  "obj_token": "<OBJ_TOKEN>",
+  "obj_type": "docx",
+  "parent_node_token": "",
+  "node_type": "origin",
+  "origin_node_token": "",
+  "title": "项目计划",
+  "has_child": false,
+  "node": {
+    "space_id": "<TARGET_SPACE_ID>",
+    "node_token": "wikcnXXX",
+    "obj_token": "<OBJ_TOKEN>",
+    "obj_type": "docx",
+    "parent_node_token": "",
+    "node_type": "origin",
+    "origin_node_token": "",
+    "title": "项目计划",
+    "has_child": false
+  },
+  "move_results": [
+    {
+      "status": 0,
+      "status_msg": "success",
+      "node": { "...": "同上" }
+    }
+  ]
+}
+```
+
+**字段说明：**
+- `ready`: 所有 `move_results[].status` 都为 `0` 时为 `true`
+- `failed`: 任一 `move_results[].status` 小于 `0` 时为 `true`
+- `status` / `status_msg`: 第一个 move_result 的状态码 / 标签（无结果时回退为 `1` / `processing`）
+- `wiki_token` / `node_token`: 移入 Wiki 后的目标节点 token（首个结果有 `node.node_token` 时镜像到顶层，便于下游脚本使用）
+- `space_id`、`obj_token`、`obj_type`、`title` 等：从首个 `move_results[0].node` 平铺到顶层，方便直接引用
+- `move_results`: 保留完整列表（适用于一次任务移动多个文档的场景）
+
 ## 使用场景
 
 ### 配合 +import 使用
@@ -162,6 +217,20 @@ lark-cli drive +move --file-token <FOLDER_TOKEN> --type folder --folder-token <T
 lark-cli drive +task_result --scenario task_check --task-id <TASK_ID>
 ```
 
+### 配合 wiki +move 使用
+
+```bash
+# 1. 把 Drive 文档迁入 Wiki（异步任务可能返回 task_id）
+lark-cli wiki +move --obj-type docx --obj-token <DOC_TOKEN> --target-space-id <TARGET_SPACE_ID>
+# 若内置轮询窗口内完成：直接返回 ready=true 和 wiki_token
+# 若轮询窗口结束仍未完成：返回 ready=false、task_id、timed_out=true 和 next_command
+
+# 2. 续跑查询 Wiki 移动结果（next_command 即下面这条）
+lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID> --as user
+```
+
+> **身份保持一致**：续跑命令的 `--as` 必须与原 `wiki +move` 调用一致；`wiki +move` 的 `next_command` 已自动带上正确的 `--as`。
+
 ### 配合 +export 使用
 
 ```bash
@@ -184,6 +253,7 @@ lark-cli drive +export-download --file-token <EXPORTED_FILE_TOKEN>
 | import | `drive:drive.metadata:readonly` |
 | export | `drive:drive.metadata:readonly` |
 | task_check | `drive:drive.metadata:readonly` |
+| wiki_move | `wiki:space:read` |
 
 > [!NOTE]
 > `import` 场景在 `--as bot` 且任务最终就绪时，还可能额外尝试一次协作者授权；如果 `permission_grant.status = failed`，请根据失败信息检查应用是否具备相应的文档协作者授权能力。

skills/lark-event/references/lark-event-subscribe.md

@@ -17,7 +17,7 @@ Subscribe to Lark events via WebSocket long connection, outputting NDJSON to std
 ## Commands
 
 ```bash
-# Subscribe to all registered events (catch-all mode, 24 common event types)
+# Subscribe to all registered events (catch-all mode, 25 common event types)
 lark-cli event +subscribe
 
 # Subscribe to specific event types only
@@ -153,6 +153,7 @@ The following 24 event types are registered in catch-all mode (when `--event-typ
 | Event Type | Description | Required Scope |
 |-----------|-------------|---------------|
 | `task.task.update_tenant_v1` | Task updated (tenant) | `task:task:readonly` |
+| `task.task.update_user_access_v2` | Task updated (user access) | `task:task:readonly` |
 | `task.task.comment_updated_v1` | Task comment updated | `task:task:readonly` |
 
 ### Drive

skills/lark-im/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-im
 version: 1.0.0
-description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员时使用。"
+description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员时使用。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -62,7 +62,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 | [`+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 |
-| [`+messages-resources-download`](references/lark-im-messages-resources-download.md) | Download images/files from a message; user/bot; downloads image/file resources by message-id and file-key to a safe relative output path |
+| [`+messages-resources-download`](references/lark-im-messages-resources-download.md) | Download images/files from a message; user/bot; supports automatic chunked download for large files (8MB chunks), auto-detects file extension from Content-Type |
 | [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user identity; user-only; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch_query |
 | [`+messages-send`](references/lark-im-messages-send.md) | Send a message to a chat or direct message; user/bot; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key |
 | [`+threads-messages-list`](references/lark-im-threads-messages-list.md) | List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination |

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

@@ -36,7 +36,7 @@ lark-cli im +chat-messages-list --chat-id oc_xxx --format json
 | Parameter | Required | Description |
 |------|------|------|
 | `--chat-id <id>` | One of two | Specify the conversation by its chat_id directly (e.g., group chat `oc_xxx`) |
-| `--user-id <id>` | One of two | Specify a DM conversation by the other user's open_id (`ou_xxx`); p2p chat_id is resolved automatically |
+| `--user-id <id>` | One of two | Specify a DM conversation by the other user's open_id (`ou_xxx`); p2p chat_id is resolved automatically. Requires user identity (`--as user`); not supported with bot identity |
 | `--start <time>` | No | Start time (ISO 8601 or date only) |
 | `--end <time>` | No | End time (ISO 8601 or date only) |
 | `--sort <order>` | No | Sort order: `asc` / `desc` (default `desc`) |
@@ -116,6 +116,7 @@ lark-cli api GET /open-apis/im/v1/messages \
 |---------|---------|---------|
 | `specify --chat-id <chat_id> or --user-id <open_id>` | Neither `--chat-id` nor `--user-id` was provided | You must provide exactly one |
 | `--chat-id and --user-id cannot be specified together` | Both parameters were provided | Use only one |
+| `--user-id requires user identity (--as user); use --chat-id when calling with bot identity` | `--user-id` was used with bot identity | The p2p resolution endpoint requires user identity. Either pass `--as user` or look up the p2p `chat_id` separately and pass it via `--chat-id` |
 | `P2P chat not found for this user` | `--user-id` was used but no p2p chat exists for the current identity and that user | Confirm the target direct-message relationship exists for the current identity |
 | `--start: invalid time format` | Invalid time format | Use ISO 8601 or date-only format such as `2026-03-10` |
 | Permission denied | Message read permissions are missing | Ensure the app has `im:message:readonly` and `im:chat:read` enabled |
@@ -130,7 +131,7 @@ lark-cli api GET /open-apis/im/v1/messages \
    ```
    **Do not use `im chats search` or `im chats 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.
+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.
 5. **For full content:** table output truncates content. Use `--format json` when you need the complete message body.
 6. **For sender info:** the command already resolves sender names, so you do not need a separate lookup.

skills/lark-im/references/lark-im-messages-resources-download.md

@@ -2,7 +2,7 @@
 
 > **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
 
-Download image or file resources from a message. Resources are identified by the combination of `message_id` + `file_key`, both of which come directly from message content returned by `im +chat-messages-list`.
+Download image or file resources from a message. Supports **automatic chunked download for large files** using HTTP Range requests. Resources are identified by the combination of `message_id` + `file_key`, both of which come directly from message content returned by `im +chat-messages-list`.
 
 > **Note:** read-only message commands render resource keys in message content, but they do not download binaries automatically. Use this command whenever you need to fetch the actual image/file bytes or save them to a specific path.
 
@@ -34,10 +34,26 @@ lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_x
 | `--message-id <id>` | Yes | Message ID (`om_xxx` format) |
 | `--file-key <key>` | Yes | Resource key (`img_xxx` or `file_xxx`) |
 | `--type <type>` | Yes | Resource type: `image` or `file` |
-| `--output <path>` | No | Output path (relative paths only; `..` traversal is not allowed; defaults to `file_key` as the file name) |
+| `--output <path>` | No | Output path (relative paths only; `..` traversal is not allowed; defaults to `file_key` as the file name). File extension is automatically added based on Content-Type if not provided |
 | `--as <identity>` | No | Identity type: `user` (default) or `bot` |
 | `--dry-run` | No | Print the request only, do not execute it |
 
+## Large File Download (Auto Chunking)
+
+When downloading large files, the command automatically uses **HTTP Range requests** for reliable chunked downloading:
+
+| Behavior | Details |
+|----------|---------|
+| Probe chunk | First 128 KB to detect file size and Content-Type |
+| Chunk size | 8 MB per subsequent request |
+| Workers | Single-threaded sequential download (ensures reliability) |
+| Retries | Up to 2 retries for transient request failures, with exponential backoff |
+
+**Benefits:**
+- Reduces the impact of transient request failures during large downloads
+- Automatically detects and appends correct file extension from Content-Type
+- Validates file size integrity after download completion
+
 ## `file_key` Sources
 
 Different resource markers in message content correspond to different `file_key` and `type` values:
@@ -69,7 +85,8 @@ lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_x
 | Download failed | `file_key` does not match the `message_id` | Make sure the `file_key` came from that message's content |
 | Hit error code 234002 or 14005 | No permission, **not** missing API scope | no access to this chat or file was deleted — do not retry, return the error to the user |
 | Permission denied | `im:message:readonly` is not authorized | Run `auth login --scope "im:message:readonly"` |
-| File too large | Over the 100 MB limit | This is a Feishu API limitation and cannot be bypassed with this endpoint |
+| File size mismatch | Chunked download integrity check failed | Network instability during download; retry the command |
+| Content-Range error | Server returned invalid range header | Transient API issue; retry the command |
 
 ## References
 

skills/lark-sheets/SKILL.md

@@ -141,6 +141,42 @@ lark-cli sheets spreadsheet.sheet.filters update \
 - `Wrong Filter Value`：筛选已存在，需要先 delete 再 create
 - `Excess Limit`：update 时重复添加同一列条件
 
+### 单元格数据类型
+
+接受二维数组的 shortcut（`+write`/`+append` 的 `--values`、`+create` 的 `--data`）中，每个单元格值支持以下类型。**公式、带文本链接、@人、@文档、下拉列表必须使用对象格式**，直接传字符串会被当作纯文本存储。
+
+| 类型 | 写入格式 | 示例 |
+|------|---------|------|
+| 字符串 | `"文本"` | `"hello"` |
+| 数字 | `数字` | `123`、`3.14` |
+| 日期 | `数字`（自 1899-12-30 起的天数，需先设单元格日期格式） | `42101` |
+| 链接（纯 URL） | `"URL 字符串"` | `"https://example.com"` |
+| 链接（带文本） | `{"type":"url","text":"显示文本","link":"URL"}` | `{"type":"url","text":"飞书","link":"https://www.feishu.cn"}` |
+| 邮箱 | `"邮箱字符串"` | `"user@example.com"` |
+| **公式** | `{"type":"formula","text":"=公式"}` | `{"type":"formula","text":"=SUM(A1:A10)"}` |
+| @人 | `{"type":"mention","text":"标识","textType":"email\|openId\|unionId","notify":false}` | `{"type":"mention","text":"user@example.com","textType":"email","notify":false}`（notify 可选，默认 false；仅在用户明确要求通知时设为 true） |
+| @文档 | `{"type":"mention","textType":"fileToken","text":"token","objType":"类型"}` | `{"type":"mention","textType":"fileToken","text":"shtXXX","objType":"sheet"}` |
+| 下拉列表 | `{"type":"multipleValue","values":[值1,值2]}` | `{"type":"multipleValue","values":["选项A","选项B"]}` |
+
+**写入公式示例**：
+
+```bash
+# ✅ 正确：使用对象格式
+lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \
+  --values '[[{"type":"formula","text":"=SUM(C2:C5)"}]]'
+
+# ❌ 错误：直接传字符串，会被存为纯文本
+lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \
+  --values '[["=SUM(C2:C5)"]]'
+```
+
+> **公式语法参考**：涉及 ARRAYFORMULA、原生数组函数、MAP/LAMBDA、日期差、Excel 公式改写等飞书特有规则时，先阅读 [`references/lark-sheets-formula.md`](references/lark-sheets-formula.md)。
+
+**限制**：
+- 公式支持 IMPORTRANGE 跨表引用（最多 5 层嵌套、每个工作表最多 100 个引用）
+- @人仅支持同租户用户，单次最多 50 人
+- 下拉列表需**先配置下拉选项**，否则 `multipleValue` 写入会变成纯文本。配置方法见 [`references/lark-sheets-set-dropdown.md`](references/lark-sheets-set-dropdown.md)。值中的字符串不能包含逗号
+
 ## Shortcuts（推荐优先使用）
 
 Shortcut 是对常用操作的高级封装（`lark-cli sheets +<verb> [flags]`）。有 Shortcut 的操作优先使用。
@@ -165,6 +201,25 @@ Shortcut 是对常用操作的高级封装（`lark-cli sheets +<verb> [flags]`
 | [`+update-dimension`](references/lark-sheets-update-dimension.md) | Update row or column properties (visibility, size) |
 | [`+move-dimension`](references/lark-sheets-move-dimension.md) | Move rows or columns to a new position |
 | [`+delete-dimension`](references/lark-sheets-delete-dimension.md) | Delete rows or columns |
+| [`+create-filter-view`](references/lark-sheets-create-filter-view.md) | Create a filter view |
+| [`+update-filter-view`](references/lark-sheets-update-filter-view.md) | Update a filter view |
+| [`+list-filter-views`](references/lark-sheets-list-filter-views.md) | List all filter views in a sheet |
+| [`+get-filter-view`](references/lark-sheets-get-filter-view.md) | Get a filter view by ID |
+| [`+delete-filter-view`](references/lark-sheets-delete-filter-view.md) | Delete a filter view |
+| [`+create-filter-view-condition`](references/lark-sheets-create-filter-view-condition.md) | Create a filter condition on a filter view |
+| [`+update-filter-view-condition`](references/lark-sheets-update-filter-view-condition.md) | Update a filter condition |
+| [`+list-filter-view-conditions`](references/lark-sheets-list-filter-view-conditions.md) | List all filter conditions of a filter view |
+| [`+get-filter-view-condition`](references/lark-sheets-get-filter-view-condition.md) | Get a filter condition by column |
+| [`+delete-filter-view-condition`](references/lark-sheets-delete-filter-view-condition.md) | Delete a filter condition |
+
+### 下拉列表
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+set-dropdown`](references/lark-sheets-set-dropdown.md) | 设置下拉列表（`multipleValue` 写入的前置步骤） |
+| [`+update-dropdown`](references/lark-sheets-update-dropdown.md) | 更新下拉列表选项 |
+| [`+get-dropdown`](references/lark-sheets-get-dropdown.md) | 查询下拉列表配置 |
+| [`+delete-dropdown`](references/lark-sheets-delete-dropdown.md) | 删除下拉列表 |
 
 ## API Resources
 

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

@@ -0,0 +1,42 @@
+
+# sheets +create-filter-view-condition（创建筛选条件）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +create-filter-view-condition`。
+
+为筛选视图的指定列创建筛选条件。
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。
+
+## 命令
+
+```bash
+# 数值筛选：E 列 < 6
+lark-cli sheets +create-filter-view-condition --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>" \
+  --condition-id "E" --filter-type "number" --compare-type "less" --expected '["6"]'
+
+# 文本筛选：G 列以 a 开头
+lark-cli sheets +create-filter-view-condition --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>" \
+  --condition-id "G" --filter-type "text" --compare-type "beginsWith" --expected '["a"]'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--filter-view-id` | 是 | 筛选视图 ID |
+| `--condition-id` | 是 | 列字母（如 `E`） |
+| `--filter-type` | 是 | 筛选类型：`hiddenValue`、`number`、`text`、`color` |
+| `--compare-type` | 否 | 比较运算符（如 `less`、`beginsWith`、`between`） |
+| `--expected` | 是 | 筛选值 JSON 数组（如 `["6"]` 或 `["2","10"]`） |
+
+## 输出
+
+JSON，包含 `condition`（condition_id, filter_type, compare_type, expected）。

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

@@ -0,0 +1,42 @@
+
+# sheets +create-filter-view（创建筛选视图）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +create-filter-view`。
+
+在工作表中创建筛选视图，每个工作表最多 150 个筛选视图。
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。可以先用 `--dry-run` 预览。
+
+## 命令
+
+```bash
+lark-cli sheets +create-filter-view --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --range "<sheetId>!A1:H14"
+
+# 指定名称
+lark-cli sheets +create-filter-view --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --range "<sheetId>!A1:H14" --filter-view-name "我的筛选"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL（与 `--spreadsheet-token` 二选一） |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--range` | 是 | 筛选范围（如 `sheetId!A1:H14`） |
+| `--filter-view-name` | 否 | 显示名称（最多 100 字符） |
+| `--filter-view-id` | 否 | 自定义 10 位字母数字 ID（不传则自动生成） |
+
+## 输出
+
+JSON，包含 `filter_view`（filter_view_id, filter_view_name, range）。
+
+## 参考
+
+- [lark-sheets-list-filter-views](lark-sheets-list-filter-views.md) — 查询所有筛选视图
+- [lark-sheets-create-filter-view-condition](lark-sheets-create-filter-view-condition.md) — 添加筛选条件

skills/lark-sheets/references/lark-sheets-delete-dropdown.md

@@ -0,0 +1,46 @@
+
+# sheets +delete-dropdown（删除下拉列表）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +delete-dropdown`。
+
+删除指定范围的下拉列表配置。支持一次删除多个范围。
+
+> [!CAUTION]
+> 这是**删除操作** —— 执行前必须确认用户意图。可以先用 `--dry-run` 预览。
+
+## 命令
+
+```bash
+# 删除单个范围
+lark-cli sheets +delete-dropdown --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
+  --ranges '["<sheetId>!A2:A100"]'
+
+# 删除多个范围
+lark-cli sheets +delete-dropdown --spreadsheet-token "shtxxxxxxxx" \
+  --ranges '["<sheetId>!A2:A100", "<sheetId>!C1:C50"]'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL（与 `--spreadsheet-token` 二选一） |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--ranges` | 是 | 范围 JSON 数组（如 `'["sheetId!A2:A100"]'`），单个范围最多 5000 格，单次最多 100 个范围 |
+| `--dry-run` | 否 | 仅打印参数，不执行请求 |
+
+## 输出
+
+JSON，包含：
+
+- `rangeResults[].range` — 对应的范围
+- `rangeResults[].success` — 是否成功
+- `rangeResults[].updatedCells` — 影响的单元格数量
+
+## 参考
+
+- [lark-sheets-set-dropdown](lark-sheets-set-dropdown.md) — 设置下拉列表
+- [lark-sheets-update-dropdown](lark-sheets-update-dropdown.md) — 更新下拉列表
+- [lark-sheets-get-dropdown](lark-sheets-get-dropdown.md) — 查询下拉列表

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

@@ -0,0 +1,26 @@
+
+# sheets +delete-filter-view-condition（删除筛选条件）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +delete-filter-view-condition`。
+
+> [!CAUTION]
+> 这是**破坏性写入操作** —— 删除后不可恢复。
+
+## 命令
+
+```bash
+lark-cli sheets +delete-filter-view-condition --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>" --condition-id "E"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--filter-view-id` | 是 | 筛选视图 ID |
+| `--condition-id` | 是 | 列字母（如 `E`） |

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

@@ -0,0 +1,25 @@
+
+# sheets +delete-filter-view（删除筛选视图）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +delete-filter-view`。
+
+> [!CAUTION]
+> 这是**破坏性写入操作** —— 删除后不可恢复。执行前必须确认用户意图。
+
+## 命令
+
+```bash
+lark-cli sheets +delete-filter-view --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--filter-view-id` | 是 | 筛选视图 ID |

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

@@ -0,0 +1,89 @@
+
+# 飞书表格公式规则
+
+> 生成或改写飞书电子表格公式时的参考规则。飞书不像 Excel 365 默认 spill，普通公式对区域默认"投影"（只取当前行/列对应的单值），必须显式使用 `ARRAYFORMULA` 或原生数组函数才能逐项展开。
+
+## 写入方式
+
+公式必须使用对象格式写入（参见 SKILL.md「单元格数据类型」）：
+
+```bash
+--values '[[{"type":"formula","text":"=SUM(A1:A10)"}]]'
+```
+
+## ARRAYFORMULA 判断流程
+
+1. 结果是**标量**（单值）→ 不需要
+2. 结果是**数组**，且公式中**有**原生数组函数 → 不需要（数组语义自动传播）
+3. 结果是**数组**，且公式中**无**原生数组函数，对区域做标量计算 → 加 `ARRAYFORMULA`
+
+```text
+# 有原生数组函数，无需包裹
+=FILTER(A2:A10,B2:B10="x")+1          ✓
+=XLOOKUP(E2:E10,A2:A10,B2:B10)*100    ✓
+=MAP(A2:A10,LAMBDA(x,x*2))-1          ✓
+
+# 无原生数组函数，必须包裹
+=ARRAYFORMULA(A2:A100*B2:B100)         ✓
+=ARRAYFORMULA(IF(A2:A100>0,B2:B100,""))✓
+```
+
+## 原生数组函数清单（无需 ARRAYFORMULA）
+
+`ARRAYFORMULA` `ARRAY_CONSTRAIN` `BYCOL` `BYROW` `CELL` `CHOOSECOLS` `CHOOSEROWS` `DROP` `EXPAND` `FILTER` `FLATTEN` `FREQUENCY` `GROWTH` `HSTACK` `IMPORTDATA` `IMPORTFEED` `IMPORTHTML` `IMPORTRANGE` `IMPORTXML` `LINEST` `LOGEST` `LOOKUP` `MAKEARRAY` `MAP` `MINVERSE` `MMULT` `MUNIT` `QUERY` `RANDARRAY` `REDUCE` `REGEXEXTRACT` `SCAN` `SEQUENCE` `SORT` `SORTBY` `SORTN` `SPLIT` `SUMPRODUCT` `SWITCH` `TAKE` `TEXTSPLIT` `TOCOL` `TOROW` `TRANSPOSE` `TREND` `UNIQUE` `VSTACK` `WRAPCOLS` `WRAPROWS` `XLOOKUP`
+
+## 高风险函数：INDEX / OFFSET / ROW / COLUMN / MATCH
+
+行号/列号/偏移量本身是数组时，必须显式包裹：
+
+```text
+=ARRAYFORMULA(INDEX(...))
+=ARRAYFORMULA(ROW(...))
+```
+
+例外：结果直接交给聚合函数消费时不需要：`=SUM(INDEX(A1:B2,0,1))` ✓
+
+## 隐式逐项求值 → MAP/LAMBDA
+
+Excel 中 `SUBTOTAL`、`INDIRECT`、`OFFSET` 等在 `SUMPRODUCT` 内会隐式逐行求值，飞书不会。用 MAP 显式遍历：
+
+```text
+# Excel
+=SUMPRODUCT(SUBTOTAL(103,INDIRECT("E"&ROW($E$16:$E$387))))
+
+# 飞书
+=SUMPRODUCT(MAP(ARRAYFORMULA(ROW($E$16:$E$387)),LAMBDA(r,SUBTOTAL(103,INDIRECT("E"&r)))))
+```
+
+同类场景：`SUMIF/COUNTIF/SUMIFS` 的范围参数来自 `INDIRECT/OFFSET` 时也需要 MAP。
+
+## 多维结果降维
+
+飞书公式结果只能是二维，不能返回"区域的列表"。合并多个区域时：
+
+| 需求 | 写法 |
+|------|------|
+| 上下堆叠 | `=VSTACK(a, b, c)` |
+| 左右拼接 | `=HSTACK(a, b, c)` |
+| 压成单列 | `=TOCOL(...)` |
+| 压成单行 | `=TOROW(...)` |
+| 归约为标量 | `=REDUCE(init, arr, LAMBDA(acc, x, ...))` |
+
+## 日期差
+
+| 需求 | 正确写法 | 错误写法 |
+|------|---------|---------|
+| 天数差 | `=DAYS(B2,A2)` 或 `=DATEDIF(A2,B2,"D")` 或 `=B2-A2` | `=DAY(B2-A2)` |
+| 月份差 | `=DATEDIF(A2,B2,"M")` | `=MONTH(B2-A2)` |
+| 年份差 | `=DATEDIF(A2,B2,"Y")` | `=YEAR(B2-A2)` |
+| 工作日差 | `=NETWORKDAYS(A2,B2)` | — |
+
+## 飞书不支持的 Excel 语法
+
+| Excel 语法 | 飞书替代 |
+|-----------|---------|
+| `=@A1:A10`（隐式交叉） | `=A1:A10`（飞书默认投影，去掉 `@`） |
+| `=A1#`（spill range） | 改成明确范围，或用 `TAKE`/`DROP`/`ARRAY_CONSTRAIN` |
+| `=SUM(Table1[Amount])`（结构化引用） | `=SUM(A2:A100)`（改为 A1 区域） |
+| `{=A1:A10*B1:B10}`（CSE 花括号） | `=ARRAYFORMULA(A1:A10*B1:B10)` |
+| `STOCKHISTORY` / `WEBSERVICE` / `CUBE*` | 飞书无等价函数 |

skills/lark-sheets/references/lark-sheets-get-dropdown.md

@@ -0,0 +1,43 @@
+
+# sheets +get-dropdown（查询下拉列表）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +get-dropdown`。
+
+查询指定范围内已配置的下拉列表设置，包括选项值、是否多选、颜色映射等。
+
+## 命令
+
+```bash
+lark-cli sheets +get-dropdown --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
+  --range "<sheetId>!A2:A100"
+
+lark-cli sheets +get-dropdown --spreadsheet-token "shtxxxxxxxx" \
+  --range "<sheetId>!A2:A100"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL（与 `--spreadsheet-token` 二选一） |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--range` | 是 | 范围（如 `<sheetId>!A2:A100`） |
+| `--dry-run` | 否 | 仅打印参数，不执行请求 |
+
+## 输出
+
+JSON，包含：
+
+- `dataValidations[].conditionValues` — 下拉选项列表
+- `dataValidations[].ranges` — 应用范围
+- `dataValidations[].options.multipleValues` — 是否多选
+- `dataValidations[].options.highlightValidData` — 是否着色
+- `dataValidations[].options.colorValueMap` — 选项颜色映射
+
+## 参考
+
+- [lark-sheets-set-dropdown](lark-sheets-set-dropdown.md) — 设置下拉列表
+- [lark-sheets-update-dropdown](lark-sheets-update-dropdown.md) — 更新下拉列表
+- [lark-sheets-delete-dropdown](lark-sheets-delete-dropdown.md) — 删除下拉列表

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

@@ -0,0 +1,27 @@
+
+# sheets +get-filter-view-condition（获取筛选条件）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +get-filter-view-condition`。
+
+## 命令
+
+```bash
+lark-cli sheets +get-filter-view-condition --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>" --condition-id "E"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--filter-view-id` | 是 | 筛选视图 ID |
+| `--condition-id` | 是 | 列字母（如 `E`） |
+
+## 输出
+
+JSON，包含 `condition`（condition_id, filter_type, compare_type, expected）。

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

@@ -0,0 +1,26 @@
+
+# sheets +get-filter-view（获取筛选视图）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +get-filter-view`。
+
+## 命令
+
+```bash
+lark-cli sheets +get-filter-view --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--filter-view-id` | 是 | 筛选视图 ID |
+
+## 输出
+
+JSON，包含 `filter_view`（filter_view_id, filter_view_name, range）。

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

@@ -0,0 +1,28 @@
+
+# sheets +list-filter-view-conditions（查询筛选条件）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +list-filter-view-conditions`。
+
+查询筛选视图的所有筛选条件。
+
+## 命令
+
+```bash
+lark-cli sheets +list-filter-view-conditions --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--filter-view-id` | 是 | 筛选视图 ID |
+
+## 输出
+
+JSON，包含 `items[]`（condition_id, filter_type, compare_type, expected）。

skills/lark-sheets/references/lark-sheets-list-filter-views.md

@@ -0,0 +1,26 @@
+
+# sheets +list-filter-views（查询筛选视图）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +list-filter-views`。
+
+查询工作表中的所有筛选视图，返回视图 ID、名称和范围。
+
+## 命令
+
+```bash
+lark-cli sheets +list-filter-views --spreadsheet-token "shtxxxxxxxx" --sheet-id "<sheetId>"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+
+## 输出
+
+JSON，包含 `items[]`（filter_view_id, filter_view_name, range）。

skills/lark-sheets/references/lark-sheets-set-dropdown.md

@@ -0,0 +1,62 @@
+
+# sheets +set-dropdown（设置下拉列表）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +set-dropdown`。
+
+为指定范围的单元格配置下拉列表选项。**这是使用 `multipleValue` 格式写入数据的前置步骤**——未配置下拉选项的单元格，`multipleValue` 写入会变成纯文本。
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。可以先用 `--dry-run` 预览。
+
+## 命令
+
+```bash
+# 基础：设置单选下拉
+lark-cli sheets +set-dropdown --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
+  --range "<sheetId>!A2:A100" --condition-values '["选项1", "选项2", "选项3"]'
+
+# 多选 + 颜色高亮
+lark-cli sheets +set-dropdown --spreadsheet-token "shtxxxxxxxx" \
+  --range "<sheetId>!A2:A100" --condition-values '["选项1", "选项2", "选项3"]' \
+  --multiple --highlight --colors '["#1FB6C1", "#F006C2", "#FB16C3"]'
+
+# 仅预览参数（不发请求）
+lark-cli sheets +set-dropdown --url "https://..." --range "..." --condition-values '...' --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL（与 `--spreadsheet-token` 二选一） |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--range` | 是 | 范围（如 `<sheetId>!A2:A100`），单次最多 5000 行 x 100 列 |
+| `--condition-values` | 是 | 下拉选项，JSON 数组（如 `'["选项1","选项2"]'`），最多 500 个，每个 ≤100 字符，不能包含逗号 |
+| `--multiple` | 否 | 是否多选，默认 false |
+| `--highlight` | 否 | 是否着色，默认 false |
+| `--colors` | 否 | RGB 十六进制颜色 JSON 数组，需与 `--condition-values` 一一对应（`--highlight` 时必填） |
+| `--dry-run` | 否 | 仅打印参数，不执行请求 |
+
+## 输出
+
+JSON，包含 `code`（0=成功）和 `msg`。
+
+## 典型流程
+
+```bash
+# 1. 先配置下拉选项
+lark-cli sheets +set-dropdown --url "<url>" \
+  --range "<sheetId>!J2:J100" --condition-values '["选项1","选项2"]' --multiple
+
+# 2. 再用 multipleValue 写入
+lark-cli sheets +write --url "<url>" --sheet-id "<sheetId>" --range "J2" \
+  --values '[[{"type":"multipleValue","values":["选项1","选项2"]}]]'
+```
+
+## 参考
+
+- [lark-sheets-update-dropdown](lark-sheets-update-dropdown.md) — 更新下拉列表
+- [lark-sheets-get-dropdown](lark-sheets-get-dropdown.md) — 查询下拉列表
+- [lark-sheets-delete-dropdown](lark-sheets-delete-dropdown.md) — 删除下拉列表

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

@@ -0,0 +1,51 @@
+
+# sheets +update-dropdown（更新下拉列表）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +update-dropdown`。
+
+更新已有下拉列表的选项、颜色等配置。可同时更新多个范围。
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。可以先用 `--dry-run` 预览。
+
+## 命令
+
+```bash
+lark-cli sheets +update-dropdown --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
+  --sheet-id "<sheetId>" \
+  --ranges '["<sheetId>!A1:A100", "<sheetId>!C1:C100"]' \
+  --condition-values '["新选项1", "新选项2", "新选项3"]'
+
+# 更新为多选 + 着色
+lark-cli sheets +update-dropdown --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" \
+  --ranges '["<sheetId>!A1:A100"]' \
+  --condition-values '["选项A", "选项B"]' \
+  --multiple --highlight --colors '["#1FB6C1", "#F006C2"]'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL（与 `--spreadsheet-token` 二选一） |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--ranges` | 是 | 范围 JSON 数组（如 `'["sheetId!A1:A100"]'`） |
+| `--condition-values` | 是 | 新的下拉选项，JSON 数组 |
+| `--multiple` | 否 | 是否多选，默认 false |
+| `--highlight` | 否 | 是否着色，默认 false |
+| `--colors` | 否 | RGB 颜色 JSON 数组，需与 `--condition-values` 一一对应 |
+| `--dry-run` | 否 | 仅打印参数，不执行请求 |
+
+## 输出
+
+JSON，包含 `spreadsheetToken`、`sheetId`、`dataValidation`（选项值和颜色映射）。
+
+## 参考
+
+- [lark-sheets-set-dropdown](lark-sheets-set-dropdown.md) — 设置下拉列表
+- [lark-sheets-get-dropdown](lark-sheets-get-dropdown.md) — 查询下拉列表
+- [lark-sheets-delete-dropdown](lark-sheets-delete-dropdown.md) — 删除下拉列表

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

@@ -0,0 +1,27 @@
+
+# sheets +update-filter-view-condition（更新筛选条件）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +update-filter-view-condition`。
+
+## 命令
+
+```bash
+lark-cli sheets +update-filter-view-condition --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>" --condition-id "E" \
+  --filter-type "number" --compare-type "between" --expected '["2","10"]'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--filter-view-id` | 是 | 筛选视图 ID |
+| `--condition-id` | 是 | 列字母（如 `E`） |
+| `--filter-type` | 否 | 筛选类型 |
+| `--compare-type` | 否 | 比较运算符 |
+| `--expected` | 否 | 筛选值 JSON 数组 |

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

@@ -0,0 +1,24 @@
+
+# sheets +update-filter-view（更新筛选视图）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli sheets +update-filter-view`。
+
+## 命令
+
+```bash
+lark-cli sheets +update-filter-view --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>" --range "<sheetId>!A1:J20"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 否 | 电子表格 URL |
+| `--spreadsheet-token` | 否 | 表格 token |
+| `--sheet-id` | 是 | 工作表 ID |
+| `--filter-view-id` | 是 | 筛选视图 ID |
+| `--range` | 否 | 新的筛选范围 |
+| `--filter-view-name` | 否 | 新的显示名称 |

skills/lark-task/SKILL.md

@@ -12,7 +12,9 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
-> **搜索技巧**：如果用户的查询只指定了任务名称（例如“完成任务龙虾一号”），请直接使用 `+get-my-tasks --query "龙虾一号"` 命令搜索（不要带 `--complete` 参数，这样可以同时搜索未完成和已完成的任务）。
+> **任务搜索技巧**：先区分用户是否**特地指定使用搜索 skill**，以及是否真的提供了**查询关键字**（例如任务名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了任务查询关键字，则目标是**任务**时优先使用 `+search`。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“今年以来”“已完成”“由我创建”“我关注的”），并且使用 `+search` 与 `+get-related-tasks` / `+get-my-tasks` 都能达到目的时，应优先使用列表型能力，而不是搜索型能力。其中，“与我相关 / 我关注的 / 由我创建”等优先考虑 `+get-related-tasks`；“我负责的 / 分配给我”的列表优先考虑 `+get-my-tasks`。不要把时间范围词（例如“今年以来”）本身误当成 `query` 去走搜索。
+> **任务清单搜索技巧**：任务清单也遵循同样的判断逻辑。先区分用户是否**特地指定使用搜索 skill**，以及是否真的提供了**清单查询关键字**（例如清单名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了清单查询关键字，则优先使用 `+tasklist-search`。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“由我创建的任务清单”“今年以来创建的清单”），并且使用搜索或原生列取清单都能达到目的时，应优先使用原生 `tasklists.list` 接口列取清单（先 `schema task.tasklists.list`，再 `lark-cli task tasklists list --as user ...`），再按 `creator`、`created_at` 等字段做本地筛选和分页控制。
+> **意图区分补充**：像“搜索飞书中今年以来我关注的任务”这类表达，虽然字面带有“搜索”，但如果没有真正的查询关键字，且本质是在限定“与我相关 + 时间范围”，则应优先走 `+get-related-tasks`；像“搜索飞书中由我创建的任务清单”这类表达，如果没有清单关键字，且本质是在限定“清单范围 + 创建者”，则应优先走原生 `tasklists.list` 后筛选，而不是直接走搜索型 shortcut。
 > **用户身份识别**：在用户身份（user identity）场景下，如果用户提到了“我”（例如“分配给我”、“由我创建”），请默认获取当前登录用户的 `open_id` 作为对应的参数值。
 > **术语理解**：如果用户提到 “todo”（待办），应当思考其是否是指“task”（任务），并优先尝试使用本 Skill 提供的命令来处理。
 > **友好输出**：在输出任务（或清单）的执行结果给用户时，建议同时提取并输出命令返回结果中的 `url` 字段（任务链接），以便用户可以直接点击跳转查看详情。
@@ -24,7 +26,8 @@ metadata:
 
 > **查询注意**：
 > 1. 在输出任务详情时，如果需要渲染负责人、创建人等人员字段，除了展示 `id` (例如 open_id) 外，还必须通过其他方式（例如调用通讯录技能）尝试获取并展示这个人的真实名字，以便用户更容易识别。
-> 2. 在输出任务详情时，如果需要渲染创建时间、截止时间等字段，需要使用本地时区来渲染（格式为2006-01-02 15:04:05）。
+> 2. 在输出清单详情时，如果需要渲染 owner、member、角色成员等人员字段，也必须像任务成员展示一样，除了展示 `id` 外，尽量解析并展示对应人员的真实名字。
+> 3. 在输出任务或清单详情时，如果需要渲染创建时间、截止时间等字段，需要使用本地时区来渲染（格式为2006-01-02 15:04:05）。
 
 > **Task GUID 定义**：
 > Task OpenAPI 中用于更新/操作任务的 `guid` 是任务的全局唯一标识（GUID），不是客户端展示的任务编号（例如 `t104121` / `suite_entity_num`）。
@@ -41,7 +44,12 @@ metadata:
 - [`+followers`](./references/lark-task-followers.md) — Manage task followers
 - [`+reminder`](./references/lark-task-reminder.md) — Manage task reminders
 - [`+get-my-tasks`](./references/lark-task-get-my-tasks.md) — List tasks assigned to me
+- [`+get-related-tasks`](./references/lark-task-get-related-tasks.md) — List tasks related to me
+- [`+search`](./references/lark-task-search.md) — Search tasks
+- [`+subscribe-event`](./references/lark-task-subscribe-event.md) — Subscribe to task events
+- [`+set-ancestor`](./references/lark-task-set-ancestor.md) — Set or clear a task ancestor
 - [`+tasklist-create`](./references/lark-task-tasklist-create.md) — Create a tasklist and batch add tasks
+- [`+tasklist-search`](./references/lark-task-tasklist-search.md) — Search tasklists
 - [`+tasklist-task-add`](./references/lark-task-tasklist-task-add.md) — Add existing tasks to a tasklist
 - [`+tasklist-members`](./references/lark-task-tasklist-members.md) — Manage tasklist members
 

skills/lark-task/references/lark-task-create.md

@@ -38,7 +38,7 @@ lark-cli task +create --summary "Test Task" --dry-run
 ## Workflow
 
 1. Confirm with the user: task summary, due date, assignee, and tasklist if necessary.
-   - **Crucial Rule for Assignee**: If the user explicitly or implicitly says "create a task for me" (给我创建一个任务), or "help me create a task" (帮我新建/创建一个任务), you MUST assign the task to the current logged-in user. You can get the current user's `open_id` by executing `lark-cli auth status --json` or `lark-cli contact +get-user` first, extracting the `userOpenId` or `open_id`, and then passing it to the `--assignee` parameter.
+   - **Crucial Rule for Assignee**: If the user explicitly or implicitly says "create a task for me" (给我创建一个任务), or "help me create a task" (帮我新建/创建一个任务), you MUST assign the task to the current logged-in user. You can get the current user's `open_id` by executing `lark-cli auth status` (it already outputs JSON by default, so do not add `--json`) or `lark-cli contact +get-user` first, extracting the `userOpenId` or `open_id`, and then passing it to the `--assignee` parameter.
 2. Execute `lark-cli task +create --summary "..." ...`
 3. Report the result: task ID and summary.
 

skills/lark-task/references/lark-task-get-related-tasks.md

@@ -0,0 +1,53 @@
+# task +get-related-tasks
+
+> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+>
+> **⚠️ Note:** This API must be called with a user identity. **Do NOT use an app identity, otherwise the call will fail.**
+>
+> **Pagination / Time Cursor Rule:**
+> In `+get-related-tasks`, `page_token` is the task `updated_at` cursor in microseconds.
+>
+> **Execution Priority:**
+> 1. If the request contains a start/end time boundary (for example, "今年以来", "最近一个月", "从 3 月 1 日开始"), first convert the **start time** boundary to a microsecond `page_token` and query from that token.
+> 2. Continue pagination using returned `page_token` until `has_more=false`, but never exceed 40 total page fetches.
+> 3. Do NOT default to `--page-all` for time-bounded queries.
+>
+> Only use `--page-all` from the beginning when:
+> 1. the user explicitly asks for a full scan of all related tasks, or
+> 2. no time boundary can be inferred from the request.
+
+List tasks related to the current user.
+
+## Recommended Commands
+
+```bash
+# List all related tasks
+lark-cli task +get-related-tasks
+
+# List incomplete related tasks starting from a page token
+lark-cli task +get-related-tasks --include-complete=false --page-token "1752730590582902"
+
+# Show only tasks created by me
+lark-cli task +get-related-tasks --created-by-me
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--include-complete=<bool>` | No | Default behavior includes completed tasks. Set to `false` to keep only incomplete tasks. |
+| `--page-all` | No | Automatically paginate through all pages (max 40). |
+| `--page-limit <int>` | No | Max page limit (default 20). |
+| `--page-token <string>` | No | Start from the specified page token. This token is the task's last update time cursor in microseconds. |
+| `--created-by-me` | No | Keep only tasks whose creator is the current user. This is a client-side filter applied after fetching related-task pages. |
+| `--followed-by-me` | No | Keep only tasks followed by the current user. This is a client-side filter applied after fetching related-task pages. |
+
+> **Page Token Note:** In `+get-related-tasks`, the `page_token` is a microsecond-level cursor representing the task's last update time. For example, `1752730590582902` should be treated as an updated-at cursor, not a task ID.
+>
+> **Pagination Note for Client-side Filters:** When `--created-by-me` or `--followed-by-me` is used, filtering happens locally after each upstream related-task page is fetched. The returned `has_more` and `page_token` still describe the upstream cursor, so later pages may contain more matching tasks, or may contain none.
+
+## Workflow
+
+1. Determine whether the user needs all related tasks or a filtered subset.
+2. Execute `lark-cli task +get-related-tasks ...`
+3. Report the matching tasks and, if present, the next `page_token`.

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

@@ -0,0 +1,41 @@
+# task +search
+
+> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+>
+> **⚠️ Note:** This API must be called with a user identity. **Do NOT use an app identity, otherwise the call will fail.**
+
+Search tasks by keyword and optional filters.
+
+## Recommended Commands
+
+```bash
+# Search by keyword
+lark-cli task +search --query "test"
+
+# Search incomplete tasks assigned to specific users
+lark-cli task +search --assignee "ou_xxx,ou_yyy" --completed=false
+
+# Search by due time range
+lark-cli task +search --query "release" --due "-1d,+7d"
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--query <string>` | No | Search keyword. If omitted, at least one filter must be provided. |
+| `--creator <ids>` | No | Creator open_ids, comma-separated. |
+| `--assignee <ids>` | No | Assignee open_ids, comma-separated. |
+| `--follower <ids>` | No | Follower open_ids, comma-separated. |
+| `--completed=<bool>` | No | Filter by completion state. |
+| `--due <range>` | No | Due time range in `start,end` form. Each side supports ISO/date/relative/ms input. |
+| `--page-token <string>` | No | Page token for pagination. |
+| `--page-all` | No | Automatically paginate through all pages (max 40). |
+| `--page-limit <int>` | No | Max page limit (default 20). |
+
+## Workflow
+
+1. Build the keyword and filters from the user's request.
+2. Execute `lark-cli task +search ...`
+3. Report the matched tasks and include the next `page_token` if more results exist.
+

skills/lark-task/references/lark-task-set-ancestor.md

@@ -0,0 +1,32 @@
+# task +set-ancestor
+
+> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+
+Set a parent task for a task, or clear the parent to make it independent.
+
+## Recommended Commands
+
+```bash
+# Set a parent task
+lark-cli task +set-ancestor --task-id "guid_1" --ancestor-id "guid_2"
+
+# Clear the parent task
+lark-cli task +set-ancestor --task-id "guid_1"
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--task-id <guid>` | Yes | The task GUID to update. |
+| `--ancestor-id <guid>` | No | The parent task GUID. Omit it to clear the ancestor. |
+
+## Workflow
+
+1. Confirm the child task and, if applicable, the ancestor task.
+2. Execute `lark-cli task +set-ancestor ...`
+3. Report the updated task GUID and whether the ancestor was set or cleared.
+
+> [!CAUTION]
+> This is a **Write Operation** -- You must confirm the user's intent before executing.
+

skills/lark-task/references/lark-task-subscribe-event.md

@@ -0,0 +1,86 @@
+# task +subscribe-event
+
+> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+>
+> **⚠️ Note:** This API supports both `user` and `bot` identities. Use `user` to subscribe the current user's accessible tasks; use `bot` to subscribe tasks the **application is responsible for**.
+
+Subscribe task update events with the current identity.
+
+This shortcut is different from `event +subscribe`:
+- `task +subscribe-event` registers task-event access for the **current identity**
+- with `--as user`, it subscribes the **current user** to task events for tasks they created, are responsible for, or follow
+- with `--as bot`, it subscribes using the **application identity** for tasks the application is responsible for
+
+The task event type is:
+
+```text
+task.task.update_user_access_v2
+```
+
+Within this event, task changes are represented by commit types (string values). Deduped list:
+
+```text
+task_assignees_update
+task_completed_update
+task_create
+task_deleted
+task_desc_update
+task_followers_update
+task_reminders_update
+task_start_due_update
+task_summary_update
+```
+
+Event payload shape (example):
+
+```json
+{
+  "event_id": "evt_xxx",
+  "event_types": ["task_summary_update"],
+  "task_guid": "task_guid_xxx",
+  "timestamp": "1775793266152",
+  "type": "task.task.update_user_access_v2"
+}
+```
+
+- `type`: event type, should be `task.task.update_user_access_v2`
+- `event_id`: unique event id (useful for dedup)
+- `event_types`: list of commit types (see the deduped list above)
+- `task_guid`: the task GUID that changed
+- `timestamp`: event timestamp (ms)
+
+In practice, this means:
+- with `--as user`, the subscribed user can receive updates for tasks visible to them through authorship, assignment, or following
+- with `--as bot`, the subscription covers tasks the application is responsible for
+
+To actually receive the subscribed events, use the standard event WebSocket receiver:
+
+```bash
+lark-cli event +subscribe --event-types task.task.update_user_access_v2 --compact --quiet
+```
+
+The full flow is:
+1. Register the subscription with `lark-cli task +subscribe-event [--as user|bot]`
+2. Receive those events with `lark-cli event +subscribe --event-types task.task.update_user_access_v2 ...`
+
+## Recommended Commands
+
+```bash
+lark-cli task +subscribe-event
+```
+# Subscribe with app identity
+lark-cli task +subscribe-event --as bot
+
+
+## Parameters
+
+This shortcut has no additional parameters.
+
+## Workflow
+
+1. Confirm whether the user wants to subscribe with `user` identity or `bot` identity.
+2. Execute `lark-cli task +subscribe-event`
+3. Report whether the subscription succeeded, and clarify which identity the subscription applies to.
+
+> [!CAUTION]
+> This is a **Write Operation** -- You must confirm the user's intent before executing.

skills/lark-task/references/lark-task-tasklist-search.md

@@ -0,0 +1,38 @@
+# task +tasklist-search
+
+> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+>
+> **⚠️ Note:** This shortcut uses tasklist search followed by tasklist detail queries to render the final output.
+
+Search tasklists by keyword and optional filters.
+
+## Recommended Commands
+
+```bash
+# Search by keyword
+lark-cli task +tasklist-search --query "测试"
+
+# Search tasklists created by specific users
+lark-cli task +tasklist-search --creator "ou_xxx,ou_yyy"
+
+# Search by creation time range
+lark-cli task +tasklist-search --query "Q2" --create-time "-30d,+0d"
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--query <string>` | No | Search keyword. If omitted, at least one filter must be provided. |
+| `--creator <ids>` | No | Creator open_ids, comma-separated. |
+| `--create-time <range>` | No | Creation time range in `start,end` form. Each side supports ISO/date/relative/ms input. |
+| `--page-token <string>` | No | Page token for pagination. |
+| `--page-all` | No | Automatically paginate through all pages (max 40). |
+| `--page-limit <int>` | No | Max page limit (default 20). |
+
+## Workflow
+
+1. Build the search keyword and filters from the user's request.
+2. Execute `lark-cli task +tasklist-search ...`
+3. Report the matched tasklists and the next `page_token` if more results exist.
+

skills/lark-wiki/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-wiki
 version: 1.0.0
-description: "飞书知识库：管理知识空间和文档节点。创建和查询知识空间、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、移动或复制节点时使用。"
+description: "飞书知识库：管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -12,14 +12,44 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
+> **成员管理硬限制：**
+> - 如果目标是“部门”，先判断身份，再决定是否继续。
+> - `--as bot` 对应 `tenant_access_token`。官方限制：这种身份下不能使用部门 ID (`opendepartmentid`) 添加知识空间成员。
+> - 遇到“部门 + --as bot”时，禁止先调用 `lark-cli wiki members create` 试错；直接说明该路径不可行。
+> - 如果用户明确要求“以 bot 身份运行”，且目标是部门，必须停下说明 bot 路径无法完成，不要静默切到 `--as user`。
+
+## 快速决策
+
+- 用户给的是知识库 URL（`.../wiki/<token>`），且后续要查成员/加成员/删成员：先调用 `lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'` 获取 `space_id`，后续成员接口统一使用 `space_id`。
+- 用户说“给知识库添加成员/管理员”：先把目标解析成“用户 / 群 / 部门”三类之一，再决定 `member_type`，不要先调 `wiki members create` 再根据报错反推类型。
+- 用户说“部门 + bot”：这是已知不支持路径。不要继续尝试 `wiki members create --as bot`；直接提示必须改成 `--as user`，或明确告知当前要求无法完成。
+- 用户说“用户 / 群 + 添加成员”：先解析对应 ID，再执行 `wiki members create`。
+
+## 成员添加流程
+
+- 调用 `lark-cli wiki members create` 前，先把自然语言里的“人 / 群 / 部门”解析成正确的 `member_id`，不要猜格式。
+- 用户场景默认优先 `member_type=openid`：用 `lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --format json` 获取 `open_id`。
+- 群组场景使用 `member_type=openchat`：用 `lark-cli im +chat-search --query "<群名关键词>" --format json` 获取 `chat_id`。
+- `userid` / `unionid` 只在下游明确要求时才使用；先拿到 `open_id`，再调用 `lark-cli api GET /open-apis/contact/v3/users/<open_id> --params '{"user_id_type":"open_id"}' --format json` 读取 `user_id` / `union_id`。
+- 部门场景使用 `member_type=opendepartmentid`：当前 CLI 没有 shortcut，需调用 `lark-cli api POST /open-apis/contact/v3/departments/search --as user --params '{"department_id_type":"open_department_id"}' --data '{"query":"<部门名>"}'` 获取 `open_department_id`。
+- 只有在目标类型和身份都已确认可行后，才调用 `lark-cli wiki members create`。对于部门场景，这意味着必须是 `--as user`。
+
 ## Shortcuts（推荐优先使用）
 
 Shortcut 是对常用操作的高级封装（`lark-cli wiki +<verb> [flags]`）。有 Shortcut 的操作优先使用。
 
 | Shortcut | 说明 |
 |----------|------|
+| [`+move`](references/lark-wiki-move.md) | Move a wiki node, or move a Drive document into Wiki |
 | [`+node-create`](references/lark-wiki-node-create.md) | Create a wiki node with automatic space resolution |
 
+## 目标语义约束
+
+- `我的文档库` / `My Document Library` / `我的知识库` / `个人知识库` / `my_library` 都应视为 **Wiki personal library**，不是 Drive 根目录
+- 处理这类目标时，先解析 `my_library` 对应的真实 `space_id`，再执行 `wiki +move`、`wiki +node-create` 或其他 Wiki 写操作
+- 不要因为缺少显式 `space_id` 就退化成 `drive +move`
+- 如果用户明确说的是 Drive 文件夹、云空间根目录、`我的空间`，才进入 Drive 域处理
+
 ## API Resources
 
 ```bash
@@ -35,6 +65,12 @@ lark-cli wiki <resource> <method> [flags] # 调用 API
 - `get_node` — 获取知识空间节点信息
 - `list` — 获取知识空间列表
 
+### members
+
+- `create` — 添加知识空间成员
+- `delete` — 删除知识空间成员
+- `list` — 获取知识空间成员列表
+
 ### nodes
 
 - `copy` — 创建知识空间节点副本
@@ -48,6 +84,9 @@ lark-cli wiki <resource> <method> [flags] # 调用 API
 | `spaces.get` | `wiki:space:read` |
 | `spaces.get_node` | `wiki:node:read` |
 | `spaces.list` | `wiki:space:retrieve` |
+| `members.create` | `wiki:member:create` |
+| `members.delete` | `wiki:member:update` |
+| `members.list` | `wiki:member:retrieve` |
 | `nodes.copy` | `wiki:node:copy` |
 | `nodes.create` | `wiki:node:create` |
 | `nodes.list` | `wiki:node:retrieve` |

skills/lark-wiki/references/lark-wiki-move.md

@@ -0,0 +1,183 @@
+# wiki +move
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+在飞书知识库中移动已有 Wiki 节点，或将 Drive 文档迁入 Wiki。这个 shortcut 统一封装了两类流程：
+
+- `node` 模式：移动已有 Wiki 节点，可同空间移动，也可跨空间移动
+- `docs_to_wiki` 模式：把 Drive 文档迁入目标知识空间；必要时可提交移动申请，并在异步任务场景下自动有限轮询
+
+当 `docs_to_wiki` 返回 `task_id` 时，shortcut 会先轮询一小段时间；如果轮询窗口内仍未完成，会返回 `next_command`，让调用方继续执行 `lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID>`。
+
+## 与 `drive +move` 的区别
+
+- `wiki +move` 的目标是 **知识空间或 Wiki 父节点**，使用 `--target-space-id` / `--target-parent-token`
+- `drive +move` 的目标是 **Drive 文件夹**，使用 `--folder-token`
+- 如果源对象已经是 Wiki 节点，必须使用 `wiki +move`，而不是 `drive +move`
+- 如果源对象还是 Drive 文档，但用户要“迁入知识库”“挂到某个 Wiki 页面下”，也应使用 `wiki +move`
+- 如果用户只是想整理云空间文件夹，把文件/文件夹挪到另一个 Drive 文件夹，应使用 `drive +move`
+
+## 口语目标识别
+
+- 当用户说“移动到某个知识库”“挂到某个页面下”“迁入 Wiki”时，按 **Wiki 目标** 处理，优先使用 `wiki +move`
+- 当用户说“移动到某个文件夹”“移动到云空间根目录”时，按 **Drive 文件夹目标** 处理，优先使用 `drive +move`
+- 当用户说“移动到我的文档库”“移动到我的知识库”“放到个人知识库”时，应先按 **Wiki 个人知识库目标** 理解，而不是直接退化成 `drive +move`
+- 遇到“我的文档库”这类表述时，可以把它理解成：先用 `my_library` 去查询用户个人知识库，再拿到真实 `space_id`
+- 推荐做法是先执行 `lark-cli wiki spaces get --params '{"space_id":"my_library"}'`，取回真实知识库 `space_id`，再把这个 `space_id` 用到 `wiki +move`
+- 当前 `wiki +move` 文档的主示例仍以显式 `--target-space-id` / `--target-parent-token` 为主；如果调用方只有自然语言目标，不要因为目标暂时不明确就改走 `drive +move`
+
+## 命令
+
+```bash
+# 将已有 wiki 节点移动到另一个父节点下
+lark-cli wiki +move \
+  --node-token <NODE_TOKEN> \
+  --target-parent-token <TARGET_PARENT_TOKEN>
+
+# 将已有 wiki 节点移动到另一个知识空间根目录
+lark-cli wiki +move \
+  --node-token <NODE_TOKEN> \
+  --target-space-id <TARGET_SPACE_ID>
+
+# 将 Drive 文档迁入某个知识空间根目录
+lark-cli wiki +move \
+  --obj-type docx \
+  --obj-token <DOC_TOKEN> \
+  --target-space-id <TARGET_SPACE_ID>
+
+# 将 Drive 文档迁入某个父节点下；如果当前没有直接移动权限，则提交申请
+lark-cli wiki +move \
+  --obj-type sheet \
+  --obj-token <SHEET_TOKEN> \
+  --target-space-id <TARGET_SPACE_ID> \
+  --target-parent-token <TARGET_PARENT_TOKEN> \
+  --apply
+
+# 预览底层调用链
+lark-cli wiki +move \
+  --obj-type docx \
+  --obj-token <DOC_TOKEN> \
+  --target-space-id <TARGET_SPACE_ID> \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--node-token` | 条件必填 | 要移动的 Wiki 节点 token。传入后命令进入 `node` 模式 |
+| `--source-space-id` | 否 | 源知识空间 ID，仅 `node` 模式可用；不传时会根据 `--node-token` 自动解析 |
+| `--target-space-id` | 条件必填 | 目标知识空间 ID。`docs_to_wiki` 模式必填；`node` 模式下如果不传，则必须传 `--target-parent-token` |
+| `--target-parent-token` | 否 | 目标父节点 token。`docs_to_wiki` 不传时表示迁入目标知识空间根目录 |
+| `--obj-type` | 条件必填 | Drive 文档类型，仅 `docs_to_wiki` 模式可用。可选值：`doc`、`sheet`、`bitable`、`mindnote`、`docx`、`file`、`slides` |
+| `--obj-token` | 条件必填 | Drive 文档 token，仅 `docs_to_wiki` 模式可用 |
+| `--apply` | 否 | 仅 `docs_to_wiki` 模式可用；当当前调用方不能直接移动文档时，提交一个 move request |
+
+## 模式选择与校验规则
+
+- **`node` 模式**：只要传了 `--node-token`，就会按“移动已有 Wiki 节点”执行
+- **`docs_to_wiki` 模式**：未传 `--node-token` 时，按“把 Drive 文档迁入 Wiki”执行
+- `node` 模式下，`--node-token` 不能与 `--obj-type`、`--obj-token`、`--apply` 同时使用
+- `node` 模式下，`--target-parent-token` 和 `--target-space-id` 不能同时为空
+- `docs_to_wiki` 模式下，必须同时提供 `--obj-type`、`--obj-token`、`--target-space-id`
+- `docs_to_wiki` 模式下，`--source-space-id` 非法，只能用于 `node` 模式
+
+## 空间解析与一致性校验
+
+### `node` 模式
+
+- **源空间解析**：如果未传 `--source-space-id`，shortcut 会先调用 `GET /open-apis/wiki/v2/spaces/get_node` 查询 `--node-token`，再读取其 `space_id`
+- **目标父节点解析**：如果传了 `--target-parent-token`，shortcut 会先解析该父节点所属的 `space_id`
+- **一致性校验**：如果同时传了 `--target-space-id` 和 `--target-parent-token`，shortcut 会校验两者是否属于同一个知识空间；不一致时直接返回验证错误
+- **移动到空间根目录**：如果只传 `--target-space-id`，则表示移动到该知识空间根目录
+
+### `docs_to_wiki` 模式
+
+- `--target-space-id` 始终必填
+- `--target-parent-token` 可选；不传时表示移动到目标知识空间根目录
+- 请求体会自动映射成 `obj_type`、`obj_token`、`parent_wiki_token`、`apply`
+
+## 行为说明
+
+- **`node` 模式是同步操作**：请求成功后直接返回移动后的节点信息
+- **`docs_to_wiki` 可能是同步，也可能是异步**：
+  - 如果接口直接返回 `wiki_token`，shortcut 会立刻返回 `ready=true`
+  - 如果接口返回 `applied=true`，shortcut 会返回 `ready=false`、`failed=false`、`applied=true` 和 `status_msg="move request submitted for approval"`
+  - 如果接口返回 `task_id`，shortcut 会先进入有限轮询
+- **有限轮询窗口**：固定最多轮询 `30` 次，每次间隔 `2` 秒
+- **轮询超时不是失败**：如果轮询窗口结束任务仍在处理中，会返回 `task_id`、`status`、`status_msg`、`ready=false`、`timed_out=true` 和 `next_command`
+- **继续查询**：看到 `next_command` 后，改用 `lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID>` 继续查
+- **任务失败直接报错**：如果轮询期间任务进入失败态，shortcut 会直接返回错误，不会再输出 `ready=false` 结果
+- **轮询请求全部失败时也直接报错**：如果任务已创建，但后续每一次状态查询都失败，shortcut 会返回带 hint 的错误，并给出继续查询命令
+
+## 返回结果
+
+### `node` 模式典型返回
+
+```json
+{
+  "mode": "node",
+  "source_space_id": "space_src",
+  "target_space_id": "space_dst",
+  "space_id": "space_dst",
+  "node_token": "wikcnode_xxx",
+  "obj_token": "doccn_xxx",
+  "obj_type": "docx",
+  "parent_node_token": "wikcparent_xxx",
+  "node_type": "origin",
+  "origin_node_token": "",
+  "title": "项目计划",
+  "has_child": false
+}
+```
+
+### `docs_to_wiki` 异步超时返回
+
+```json
+{
+  "mode": "docs_to_wiki",
+  "obj_type": "docx",
+  "obj_token": "doccn_xxx",
+  "target_space_id": "space_xxx",
+  "target_parent_token": "wikcparent_xxx",
+  "task_id": "7500000000000000001",
+  "ready": false,
+  "failed": false,
+  "status": 1,
+  "status_msg": "processing",
+  "timed_out": true,
+  "next_command": "lark-cli drive +task_result --scenario wiki_move --task-id 7500000000000000001"
+}
+```
+
+**输出字段说明：**
+
+- `mode`：当前执行模式，值为 `node` 或 `docs_to_wiki`
+- `ready`：任务是否已经完成并可直接继续使用结果
+- `failed`：任务是否已失败
+- `task_id`：异步任务 ID，仅异步场景返回
+- `status` / `status_msg`：异步任务的主状态码和可读状态
+- `wiki_token`：docs-to-wiki 成功后返回的 Wiki 节点 token；同时也会镜像到 `node_token`
+- `space_id`、`node_token`、`obj_token`、`obj_type`、`parent_node_token`、`title` 等：成功拿到节点信息时返回，方便下游继续调用
+
+## dry-run 编排
+
+- `node` 模式下，dry-run 会根据是否需要解析源节点 / 目标父节点，展示 1 到 3 步的调用链
+- `docs_to_wiki` 模式下，dry-run 会展示两步：
+  1. `POST /open-apis/wiki/v2/spaces/{target_space_id}/nodes/move_docs_to_wiki`
+  2. `GET /open-apis/wiki/v2/tasks/{task_id}?task_type=move`
+
+## 权限说明
+
+CLI 会在执行前做本地 scope 预检查；当前 shortcut 声明的权限为 `wiki:node:move`、`wiki:node:read`、`wiki:space:read`（分别覆盖 move 写操作、节点解析读操作、以及异步任务轮询读操作）。如果本地 token 已记录 scopes 且缺失任一权限，命令会直接提示重新执行 `lark-cli auth login --scope ...`。
+
+当异步任务超时后，后续 `lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID>` 只需要 `wiki:space:read` 权限。
+
+> [!CAUTION]
+> `wiki +move` 是**写入操作**。执行前必须确认用户意图，以及目标节点 / 目标知识空间是否明确。
+
+## 参考
+
+- [lark-wiki](../SKILL.md) -- 知识库全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [drive +task_result](../../lark-drive/references/lark-drive-task-result.md) -- docs-to-wiki 异步任务的续跑查询命令

tests/cli_e2e/cli-e2e-testcase-writer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cli-e2e-testcase-writer
-description: Write scenario-based end-to-end Go testcases for the compiled `lark-cli` binary under `tests/cli_e2e`. Use when adding or updating a CLI testcase that should autonomously explore help and schema output, build a self-contained lifecycle with `clie2e.RunCmd`, organize steps with `t.Run`, clean up with `t.Cleanup`, and assert JSON output with `testify/assert` and `gjson`.
+description: Use when adding or updating Go CLI E2E coverage for one `tests/cli_e2e/{domain}` domain of the compiled `lark-cli`, especially when the work requires live `--help` or `schema` exploration, scenario-based `clie2e.RunCmd` workflows, and per-domain `coverage.md` maintenance.
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -8,211 +8,115 @@ metadata:
 
 # CLI E2E Testcase Writer
 
-Write testcase code, not framework code. `tests/cli_e2e/core.go` already provides the harness, and `tests/cli_e2e/demo/task_lifecycle_test.go` is the reference example only. Unless the user explicitly asks for framework work, add or update testcase files only.
+Work on one domain per run. Produce exactly two artifacts for that domain:
+- workflow testcase files under `tests/cli_e2e/{domain}/`
+- `tests/cli_e2e/{domain}/coverage.md`
 
-## What a good testcase looks like
+Focus on domain testcase files. Do not change shared E2E support code such as `tests/cli_e2e/core.go` unless the user explicitly asks. Treat `tests/cli_e2e/demo/` as reference only.
 
-A good cli e2e testcase here is:
-- scenario-based, not a loose smoke test
-- self-contained and data-consistent
-  create the resource you later read, update, search, or delete
-- broad enough to prove the workflow
-  usually create plus one or more follow-up reads or mutations plus teardown
-- scoped to one feature or one workflow
-  do not turn one testcase into the entire domain
-- written with normal Go testing primitives
+## Core standard
 
-This is different from traditional API test suites where usage docs live elsewhere. Here, the command contract is discoverable from `lark-cli --help`, domain help, subcommand help, and schema output, and the agent is expected to explore and verify it autonomously.
+- Make the testcase scenario-based and self-contained.
+- Prove one workflow end to end: create plus follow-up read, or mutate plus teardown.
+- Prefer one file per workflow or one closely related feature.
+- For mutable flows, prove persisted state with read-after-write assertions, not just exit code.
+- Leave prerequisite-heavy paths uncovered when they cannot be proven, and explain why in `coverage.md`.
 
-## File organization
+## Workflow
 
-Put real domain testcases under:
-
-```text
-tests/cli_e2e/{domain}/
-```
-
-Examples:
-- `tests/cli_e2e/task/task_status_workflow_test.go`
-- `tests/cli_e2e/task/task_comment_workflow_test.go`
-
-Treat `tests/cli_e2e/demo/` as reference material, not as the place to accumulate real coverage.
-
-## How to split cases
-
-Split by feature or workflow, not by API surface inventory.
-
-Good splits:
-- one file for task status flow: `create -> complete -> get -> reopen -> get`
-- one file for task comment flow
-- one file for task reminder flow
-- one file for tasklist association flow
-
-Bad split:
-- one giant `task_test.go` that creates a task, updates it, comments it, reminds it, assigns it, adds followers, attaches tasklists, and queries everything in one lifecycle
-
-Prefer:
-- one top-level test per workflow
-- one file per workflow or per closely related feature
-- small shared helpers in the same domain test package when setup/cleanup logic truly repeats
-
-## Explore before writing
-
-Do not guess command names, flags, or payload fields from memory. Discover them:
+### 1. Explore the live CLI before writing code
 
 ```bash
 lark-cli --help
 lark-cli <domain> --help
 lark-cli <domain> +<shortcut> -h
-lark-cli <domain> <resource> <method> -h
-lark-cli schema <domain>.<resource>.<method>
+lark-cli <domain> <group> --help
+lark-cli <domain> <group> <method> -h
+lark-cli schema <domain>.<group>.<method>
 ```
 
-Use this exploration loop repeatedly while writing the testcase:
-1. find the right domain and command path
-2. decide whether the scenario should use a shortcut or a resource method
-3. inspect the exact `--params` and `--data` shape
-4. run the draft testcase
-5. inspect failures, then go back to help or schema and refine
+### 2. Count leaf commands for the denominator
 
-Also inspect environmental constraints before finalizing coverage:
-- whether the current test environment supports `bot`, `user`, or both
-- whether the scenario needs external identities, preexisting groups, documents, chats, or other remote fixtures
-- whether the command path is actually executable in CI-like conditions
+- A leaf command is one that executes an action — it has no further subcommands.
+- If `lark-cli <domain> <group> --help` lists no subcommands, `<group>` itself is the leaf.
+- Count `task +create` as one leaf and `task tasks get` as one leaf.
+- Do not count parameter combinations.
+- Reuse coverage already present under `tests/cli_e2e/{domain}/`. Do not count `tests/cli_e2e/demo/`.
 
-## Use the harness directly
+### 3. Choose the proof surface before editing
 
-Call `clie2e.RunCmd` with `clie2e.Request`.
+Identify the provable risks for the touched workflow: invalid input, missing prerequisite, identity or permission, state transition, output shape, cleanup safety. If only the happy path is testable, document the blocked risk areas in `coverage.md`.
 
-```go
-result, err := clie2e.RunCmd(ctx, clie2e.Request{
-	Args: []string{"task", "tasks", "get"},
-	Params: map[string]any{
-		"task_guid": taskGUID,
-	},
-})
-require.NoError(t, err)
-result.AssertExitCode(t, 0)
-result.AssertStdoutStatus(t, 0)
+### 4. Add or update the workflow testcase
+
+- Use `clie2e.RunCmd(ctx, clie2e.Request{...})`.
+- Put command path and plain flags in `Args`; put JSON in `Params` (URL/path parameters) and `Data` (request body).
+- Prefer one top-level test per workflow with `t.Run` substeps.
+- Register teardown on `parentT.Cleanup` so it survives subtest failures.
+- When touching an existing command, verify the JSON response shape is stable: assert status type, field paths, and identifiers consumed by later steps before changing assertions.
+
+### 5. Run and iterate
+
+Run `go test ./tests/cli_e2e/{domain} -count=1` while iterating and before finishing. If command shape or behavior is unclear, re-check help or schema (step 1) before changing assertions.
+
+### 6. Refresh the domain outputs
+
+- Update the workflow testcase files.
+- Update `coverage.md`: recompute the denominator from live help output, mark each command as `shortcut` or `api`, and keep one command table for the whole domain.
+
+## Testcase rules
+
+- Override `BinaryPath`, `DefaultAs`, or `Format` on `clie2e.Request` only when the testcase truly needs it.
+- Use `require.NoError`, `result.AssertExitCode`, `result.AssertStdoutStatus`, `assert`, and `gjson`.
+- Shortcut responses (`{ok: bool}`) assert `true`; API responses (`{code: int}`) assert `0`.
+- Use `t.Helper()` only for setup or assertion helpers that are called from multiple tests.
+- Use table-driven tests only when the scenario shape repeats across inputs.
+- For expected failures, assert stderr content and exit code when the environment makes them deterministic.
+- If identity or external fixtures cannot be proven, leave the command uncovered and document the prerequisite rather than faking confidence.
+
+## coverage.md
+
+Keep `coverage.md` brief and mechanical. Include:
+- a domain-specific H1 title
+- a metrics section with denominator, covered count, and coverage rate
+- a summary section restating each `Test...` workflow, key `t.Run(...)` proof points, and main blockers
+- one command table for all commands
+
+Recommended structure:
+
+```markdown
+# <Domain> CLI E2E Coverage
+
+## Metrics
+- Denominator: N leaf commands
+- Covered: N
+- Coverage: N%
+
+## Summary
+- TestXxx: ... key `t.Run(...)` proof points ...
+- Blocked area: ...
+
+## Command Table
+| Status | Cmd | Type | Testcase | Key parameter shapes | Notes / uncovered reason |
+| --- | --- | --- | --- | --- | --- |
+| ✓ | task +create | shortcut | task_status_workflow_test.go::TestTask_StatusWorkflow | basic create; create with due | |
+| ✕ | task +assign | shortcut |  | none | requires real user open_id |
 ```
 
-Use `Request` like this:
-- `Args`: command path and plain flags
-- `Params`: JSON for `--params`
-- `Data`: JSON for `--data`
-- `BinaryPath`, `DefaultAs`, `Format`: only when the testcase must override defaults
+- Mark each command `shortcut` or `api`.
+- Write testcase entries in `go test -run` friendly form.
+- Commands only exercised in `parentT.Cleanup` teardown are not counted as covered.
+- Do not split covered and uncovered commands into separate sections.
 
-## Default testcase shape
+## Guardrails
 
-Use one top-level test per workflow. Break the workflow into substeps with `t.Run`.
-
-```go
-func TestDomain_Scenario(t *testing.T) {
-	parentT := t
-	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
-	t.Cleanup(cancel)
-
-	suffix := time.Now().UTC().Format("20060102-150405")
-	var resourceID string
-
-	t.Run("create", func(t *testing.T) {
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{...})
-		require.NoError(t, err)
-		result.AssertExitCode(t, 0)
-		result.AssertStdoutStatus(t, true)
-		resourceID = gjson.Get(result.Stdout, "data.guid").String()
-		require.NotEmpty(t, resourceID)
-
-		parentT.Cleanup(func() {
-			// best-effort delete
-		})
-	})
-
-	t.Run("get", func(t *testing.T) {
-		require.NotEmpty(t, resourceID)
-	})
-}
-```
-
-Use this shape because:
-- `t.Run` makes reports readable
-- `parentT.Cleanup` keeps created resources alive for later substeps
-- one testcase owns one full resource lifecycle
-
-## Data self-consistency
-
-Prefer workflows whose data can be created and cleaned up entirely within the testcase.
-
-Good:
-- create a task, then get/update/comment/delete that same task
-- create a tasklist, then add a task created by the testcase
-
-Be explicit when the data is not self-consistent:
-- if a testcase needs a real user open_id, preexisting chat, existing document, or tenant-specific fixture, do not invent one
-- call out the missing prerequisite to the user
-- if you still want to leave a reference testcase in code, write it with `t.Skip()` and a short reason
-
-Example:
-
-```go
-func TestTask_AssignWorkflow_UserOnly(t *testing.T) {
-	t.Skip("requires a real user open_id and user-capable test environment")
-}
-```
-
-Do not silently hardcode made-up IDs, fake URLs, or guessed remote resources just to make the testcase look complete.
-
-## Environment constraints
-
-Assume the current local/CI-like environment may support only `bot` identity by default.
-
-Implications:
-- do not assume `--as user` works
-- commands or workflows that require user identity may be unsupported in the current environment
-- confirm this by checking help, running the command, or using known repo guidance before writing the final testcase set
-
-When `--as user` is unavailable:
-- still implement bot-compatible workflows normally
-- for user-only workflows, either stop and tell the user what prerequisite is missing, or leave a skipped testcase with `t.Skip()`
-
-Typical risky areas:
-- `+get-my-tasks`
-- commands that require current-user profile or self identity lookup
-- workflows that need a real user open_id for assign/follower/member mutations
-
-## Go testing rules
-
-- Use `t.Run` for lifecycle steps such as `create`, `update`, `get`, `list`, `delete`.
-- Use `t.Cleanup` for teardown and shared cleanup.
-- Use `t.Helper()` in local helpers when the same setup or assertion logic really repeats.
-- Use table-driven tests only when the same scenario shape repeats across multiple inputs. Do not force table-driven style onto a single live workflow.
-- Use `require.NoError` for command execution and prerequisites.
-- Use `assert` for returned field values after the command has succeeded.
-- Use `gjson.Get(result.Stdout, "...")` for JSON field extraction.
-
-## Output conventions
-
-- shortcut-style commands often return `{"ok": true, ...}` and should use `result.AssertStdoutStatus(t, true)`
-- service-style commands often return `{"code": 0, "data": ...}` and should use `result.AssertStdoutStatus(t, 0)`
-
-Then assert the business fields with `gjson`.
-
-## Common mistakes
-
-- Do not modify `tests/cli_e2e/core.go` just because one testcase wants a convenience wrapper.
-- Do not write a testcase that depends on preexisting remote data.
-- Do not put agent, model, or vendor brand names into task summaries, comments, tasklist names, fixture IDs, or other visible remote test data; use neutral prefixes such as `lark-cli-e2e-` or `<domain>-e2e-`.
-- Do not attach cleanup to the create subtest if later subtests still need the resource.
+- Run as bot identity only; do not assume `--as user` works.
 - Do not place new real coverage under `tests/cli_e2e/demo/`.
-- Do not dump all domain behaviors into one file or one testcase.
-- Do not hardcode obvious defaults unless the command really needs explicit flags.
-- Do not guess `Params` or `Data` fields when schema output can tell you the exact shape.
-- Do not fabricate prerequisite data when the scenario needs real external fixtures.
-- Do not force a user-only workflow to run in a bot-only environment; use `t.Skip()` with a concrete reason.
-- Do not stop after the first draft. Run, inspect, explore again, and improve the testcase.
-
-## Validation
-
-- Run `go test ./tests/cli_e2e/... -count=1`.
-- Rerun the touched package directly when the testcase is live and slow.
-- If behavior is unclear, go back to help and schema before changing the testcase.
+- Do not depend on preexisting remote data.
+- Do not fabricate open_ids, chats, docs, or other remote fixtures.
+- Prefer deterministic negative cases over tenant-dependent assertions.
+- Do not guess `Params` or `Data` fields when help or schema can tell you the exact shape.
+- Do not hardcode obvious defaults unless the command truly requires explicit flags.
+- Do not put agent, model, or vendor brand names in visible remote test data; use neutral prefixes such as `lark-cli-e2e-` or `<domain>-e2e-`.
+- A command is covered only when the testcase asserts returned fields or persisted state, not just exit code.
+- Cleanup-only execution is not primary coverage, except `delete` in the same workflow that created the resource.

tests/cli_e2e/demo/coverage.md

@@ -0,0 +1,42 @@
+# Demo Coverage Template
+
+> This file is a demo template only.
+> It shows the expected `coverage.md` shape for real domains under `tests/cli_e2e/{domain}`.
+> The numbers, command list, and coverage status below are illustrative, not authoritative.
+> `tests/cli_e2e/demo/` is reference material and is not part of formal CLI E2E coverage accounting.
+> `lark-cli demo --help` does not exist, so this file cannot be recomputed from live domain help output.
+
+## Metrics
+
+- Denominator: 8 leaf commands
+- Covered: 3
+- Coverage: 37.5%
+
+## Summary
+
+- Purpose: show humans and AI agents how to maintain a per-domain coverage file even when the directory is documentation-only and not backed by a real `lark-cli demo` command tree.
+- TestDemo_TaskLifecycle: demonstrates one minimal task lifecycle workflow for documentation purposes.
+- TestDemo_TaskLifecycle/create: runs `task +create` with `summary` and `description`, captures the returned `taskGUID`, and registers parent cleanup for later teardown.
+- TestDemo_TaskLifecycle/update: runs `task +update --task-id <guid>` and mutates both `summary` and `description` on the created task.
+- TestDemo_TaskLifecycle/get: runs `task tasks get` for the same task and asserts the persisted `guid`, updated `summary`, and updated `description`.
+- Cleanup note: `task tasks delete` is executed in `parentT.Cleanup`, but this template intentionally keeps cleanup-only execution marked uncovered so workflow assertions remain distinct from teardown mechanics.
+- Demo-only gap note: `task +complete`, `task +reopen`, `task +assign`, and `task +get-my-tasks` are intentionally left as uncovered examples for a minimal template.
+
+## Command Table
+
+| Status | Cmd | Type | Testcase | Key parameter shapes | Notes / uncovered reason |
+| --- | --- | --- | --- | --- | --- |
+| ✓ | task +create | shortcut | task_lifecycle_test.go::TestDemo_TaskLifecycle/create | basic create; summary; description | demo example |
+| ✓ | task +update | shortcut | task_lifecycle_test.go::TestDemo_TaskLifecycle/update | --task-id; update summary; update description | demo example |
+| ✓ | task tasks get | api | task_lifecycle_test.go::TestDemo_TaskLifecycle/get | task_guid in --params | demo example |
+| ✕ | task tasks delete | api |  | none | cleanup exists in parentT.Cleanup, but demo coverage intentionally treats cleanup-only execution as uncovered |
+| ✕ | task +complete | shortcut |  | none | not shown in this minimal lifecycle example |
+| ✕ | task +reopen | shortcut |  | none | not shown in this minimal lifecycle example |
+| ✕ | task +assign | shortcut |  | none | example of a user-identity-sensitive command; requires real user fixtures |
+| ✕ | task +get-my-tasks | shortcut |  | none | example of a current-user-dependent command; often unavailable in bot-only environments |
+
+## Notes
+
+- In a real domain, recompute the denominator from live `lark-cli --help` exploration instead of copying this file.
+- Replace demo rows with real command inventory for that domain.
+- Keep skipped commands unchecked; reuse the `t.Skip(...)` reason as the uncovered reason.

tests/cli_e2e/task/coverage.md

@@ -0,0 +1,50 @@
+# Task CLI E2E Coverage
+
+## Metrics
+- Denominator: 29 leaf commands
+- Covered: 10
+- Coverage: 34.5%
+
+## Summary
+- TestTask_StatusWorkflow: creates a task via `task +create`, then proves `task +complete`, `task tasks get`, and `task +reopen` through `complete`, `get completed task`, `reopen`, and `get reopened task`; asserts `status` flips between `done` and `todo` and `completed_at` is set then cleared.
+- TestTask_ReminderWorkflow: creates a task with a due time via `task +create`, then proves `task +reminder` and `task tasks get` through `set reminder`, `get task with reminder`, `remove reminder`, and `get task without reminder`; asserts `relative_fire_minute=30`, reminder id presence, and reminder removal.
+- TestTask_CommentWorkflow: creates a task via `task +create`, runs `comment`, and asserts the returned comment id is non-empty; this is the direct proof for `task +comment`.
+- TestTask_TasklistWorkflow: runs `create tasklist with task`, then `get tasklist`, `list tasklist tasks`, and `get task`; proves `task +tasklist-create`, `task tasklists get`, `task tasklists tasks`, and `task tasks get` with seeded task payload and task-to-tasklist linkage.
+- TestTask_TasklistAddTaskWorkflow: creates a standalone tasklist and task, runs `add task to tasklist`, then `list tasklist tasks` and `get task with tasklist link`; proves `task +tasklist-task-add`, `task tasklists tasks`, and `task tasks get`, including no failed tasks in the add response.
+- Cleanup path note: workflow-created tasks and tasklists are deleted through direct `task tasks delete` / `task tasklists delete` cleanup paths in `helpers_test.go::createTask`, `helpers_test.go::createTasklist`, and `tasklist_workflow_test.go::TestTask_TasklistWorkflow`, but those cleanup-only executions are not counted as command coverage because no testcase asserts delete behavior as the primary proof surface.
+- Blocked area: assignee, follower, and tasklist member mutations still require stable real-user `open_id` fixtures; the current suite is bot-safe only.
+- Blocked area: `task +get-my-tasks` still depends on `--as user` identity plus deterministic user-scoped data.
+- Gap pattern: direct `tasks create/delete/list/patch`, `tasklists create/delete/list/patch`, `members *`, and `subtasks *` APIs still lack deterministic direct-call workflows, so shortcut coverage does not count for those leaf commands.
+
+## Command Table
+| Status | Cmd | Type | Testcase | Key parameter shapes | Notes / uncovered reason |
+| --- | --- | --- | --- | --- | --- |
+| ✕ | task +assign | shortcut |  | none | requires real assignee open_id fixtures; shortcut defaults to `--as user` |
+| ✓ | task +comment | shortcut | task_comment_workflow_test.go::TestTask_CommentWorkflow/comment | `--task-id`; `--content` | |
+| ✓ | task +complete | shortcut | task_status_workflow_test.go::TestTask_StatusWorkflow/complete | `--task-id` | |
+| ✓ | task +create | shortcut | task_status_workflow_test.go::TestTask_StatusWorkflow; task_comment_workflow_test.go::TestTask_CommentWorkflow; task_reminder_workflow_test.go::TestTask_ReminderWorkflow; tasklist_add_task_workflow_test.go::TestTask_TasklistAddTaskWorkflow | `summary` + `description`; `due.timestamp` + `due.is_all_day` | |
+| ✕ | task +followers | shortcut |  | none | requires real follower open_id fixtures; shortcut defaults to `--as user` |
+| ✕ | task +get-my-tasks | shortcut |  | none | depends on `--as user` identity and deterministic user-scoped task data |
+| ✓ | task +reminder | shortcut | task_reminder_workflow_test.go::TestTask_ReminderWorkflow/set reminder; task_reminder_workflow_test.go::TestTask_ReminderWorkflow/remove reminder | `--task-id --set 30m`; `--task-id --remove` | |
+| ✓ | task +reopen | shortcut | task_status_workflow_test.go::TestTask_StatusWorkflow/reopen | `--task-id` | |
+| ✓ | task +tasklist-create | shortcut | tasklist_workflow_test.go::TestTask_TasklistWorkflow/create tasklist with task; tasklist_add_task_workflow_test.go::TestTask_TasklistAddTaskWorkflow | `--name` only; `--name` plus task array in `--data` | |
+| ✕ | task +tasklist-members | shortcut |  | none | requires real member open_id fixtures to add, remove, or set tasklist members |
+| ✓ | task +tasklist-task-add | shortcut | tasklist_add_task_workflow_test.go::TestTask_TasklistAddTaskWorkflow/add task to tasklist | `--tasklist-id`; `--task-id` | |
+| ✕ | task +update | shortcut |  | none | no dedicated workflow yet for summary, description, or due-field mutation assertions |
+| ✕ | task members add | api |  | none | requires stable member fixtures and explicit direct API-body assertions |
+| ✕ | task members remove | api |  | none | requires stable member fixtures and explicit direct API-body assertions |
+| ✕ | task subtasks create | api |  | none | needs a parent-task workflow plus direct subtask payload assertions |
+| ✕ | task subtasks list | api |  | none | needs deterministic subtask fixtures created in the same workflow |
+| ✕ | task tasklists add_members | api |  | none | requires real member open_id fixtures and direct API coverage |
+| ✕ | task tasklists create | api |  | none | only covered indirectly through `task +tasklist-create`; no direct API invocation yet |
+| ✕ | task tasklists delete | api |  | none | only exercised in parent cleanup; no testcase asserts delete behavior or post-delete state as the primary proof |
+| ✓ | task tasklists get | api | tasklist_workflow_test.go::TestTask_TasklistWorkflow/get tasklist | `tasklist_guid` in `--params` | |
+| ✕ | task tasklists list | api |  | none | needs isolated list or filter assertions against ambient tasklist data |
+| ✕ | task tasklists patch | api |  | none | no dedicated direct tasklist-update workflow yet |
+| ✕ | task tasklists remove_members | api |  | none | requires real member open_id fixtures and direct API coverage |
+| ✓ | task tasklists tasks | api | tasklist_workflow_test.go::TestTask_TasklistWorkflow/list tasklist tasks; tasklist_add_task_workflow_test.go::TestTask_TasklistAddTaskWorkflow/list tasklist tasks | `tasklist_guid`; `page_size` | |
+| ✕ | task tasks create | api |  | none | only covered indirectly through `task +create`; no direct API invocation yet |
+| ✕ | task tasks delete | api |  | none | only exercised in parent cleanup; no testcase asserts delete behavior or post-delete state as the primary proof |
+| ✓ | task tasks get | api | task_status_workflow_test.go::TestTask_StatusWorkflow/get completed task; task_status_workflow_test.go::TestTask_StatusWorkflow/get reopened task; task_reminder_workflow_test.go::TestTask_ReminderWorkflow/get task with reminder; task_reminder_workflow_test.go::TestTask_ReminderWorkflow/get task without reminder; tasklist_workflow_test.go::TestTask_TasklistWorkflow/get task; tasklist_add_task_workflow_test.go::TestTask_TasklistAddTaskWorkflow/get task with tasklist link | `task_guid` in `--params`; assert status, reminders, summary, description, and tasklist link | |
+| ✕ | task tasks list | api |  | none | needs isolated list or filter assertions against ambient task data |
+| ✕ | task tasks patch | api |  | none | no dedicated direct task-update workflow yet |