chore: cut v1.0.12 with reviewed release notes (#493)

This release prep captures the version bump and changelog entry for v1.0.12 without pulling unrelated workspace edits into the release branch.

Change-Id: Ib343337c4851b7cc15a52dd0068795a92092b781
Constraint: Keep the release PR scoped to package version and changelog only
Rejected: Include .gitignore and local workspace files | unrelated to this release PR
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep release notes aligned with shipped changes only; exclude reverted work from summaries
Tested: make unit-test
Tested: go mod tidy
Tested: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main
Not-tested: Manual tag/release publishing 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,62 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.12] - 2026-04-15
+
+### Features
+
+- Add guided npm install flow that installs or upgrades the CLI, installs AI skills, and walks through app config and auth login (#464)
+- **mail**: Add email signature support with `+signature`, `--signature-id` compose flags, and draft signature edit operations (#485)
+- **mail**: Return recall hints for sent emails when recall is available (#481)
+- **slides**: Add `+media-upload` and support `@path` image placeholders in `+create --slides` (#450)
+
+### Documentation
+
+- **mail**: Add recipient search guidance to the mail skill workflow (#437)
+- **calendar/vc**: Route past meeting queries to `lark-vc` and clarify historical date matching in skills (#482, #480)
+
+## [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 +359,9 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.12]: https://github.com/larksuite/cli/releases/tag/v1.0.12
+[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 == "" {

internal/output/lark_errors.go

@@ -33,6 +33,11 @@ const (
 	LarkErrRefreshRevoked     = 20064 // refresh_token revoked
 	LarkErrRefreshAlreadyUsed = 20073 // refresh_token already consumed (single-use rotation)
 	LarkErrRefreshServerError = 20050 // refresh endpoint server-side error, retryable
+
+	// Drive shortcut / cross-space constraints.
+	LarkErrDriveResourceContention = 1061045 // resource contention occurred, please retry
+	LarkErrDriveCrossTenantUnit    = 1064510 // cross tenant and unit not support
+	LarkErrDriveCrossBrand         = 1064511 // cross brand not support
 )
 
 // ClassifyLarkError maps a Lark API error code + message to (exitCode, errType, hint).
@@ -60,6 +65,14 @@ func ClassifyLarkError(code int, msg string) (int, string, string) {
 	// rate limit
 	case LarkErrRateLimit:
 		return ExitAPI, "rate_limit", "please try again later"
+
+	// drive-specific constraints that benefit from actionable hints
+	case LarkErrDriveResourceContention:
+		return ExitAPI, "conflict", "please retry later and avoid concurrent duplicate requests"
+	case LarkErrDriveCrossTenantUnit:
+		return ExitAPI, "cross_tenant_unit", "operate on source and target within the same tenant and region/unit"
+	case LarkErrDriveCrossBrand:
+		return ExitAPI, "cross_brand", "operate on source and target within the same brand environment"
 	}
 
 	return ExitAPI, "api_error", ""

internal/output/lark_errors_test.go

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package output
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestClassifyLarkError_DriveCreateShortcutConstraints verifies known Drive shortcut errors map to actionable hints.
+func TestClassifyLarkError_DriveCreateShortcutConstraints(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name         string
+		code         int
+		wantExitCode int
+		wantType     string
+		wantHint     string
+	}{
+		{
+			name:         "resource contention",
+			code:         LarkErrDriveResourceContention,
+			wantExitCode: ExitAPI,
+			wantType:     "conflict",
+			wantHint:     "avoid concurrent duplicate requests",
+		},
+		{
+			name:         "cross tenant unit",
+			code:         LarkErrDriveCrossTenantUnit,
+			wantExitCode: ExitAPI,
+			wantType:     "cross_tenant_unit",
+			wantHint:     "same tenant and region/unit",
+		},
+		{
+			name:         "cross brand",
+			code:         LarkErrDriveCrossBrand,
+			wantExitCode: ExitAPI,
+			wantType:     "cross_brand",
+			wantHint:     "same brand environment",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			gotExitCode, gotType, gotHint := ClassifyLarkError(tt.code, "raw msg")
+			if gotExitCode != tt.wantExitCode {
+				t.Fatalf("exitCode=%d, want %d", gotExitCode, tt.wantExitCode)
+			}
+			if gotType != tt.wantType {
+				t.Fatalf("type=%q, want %q", gotType, tt.wantType)
+			}
+			if gotHint == "" {
+				t.Fatal("expected non-empty hint")
+			}
+			if !strings.Contains(gotHint, tt.wantHint) {
+				t.Fatalf("hint=%q, want substring %q", gotHint, tt.wantHint)
+			}
+		})
+	}
+}

internal/selfupdate/updater.go

@@ -146,11 +146,20 @@ func (u *Updater) RunNpmInstall(version string) *NpmResult {
 	return r
 }
 
-// RunSkillsUpdate executes npx -y skills add larksuite/cli -g -y.
+// RunSkillsUpdate installs skills, trying the .well-known source first and
+// falling back to the GitHub repo on failure or timeout.
 func (u *Updater) RunSkillsUpdate() *NpmResult {
 	if u.SkillsUpdateOverride != nil {
 		return u.SkillsUpdateOverride()
 	}
+	r := u.runSkillsAdd("https://open.feishu.cn")
+	if r.Err != nil {
+		r = u.runSkillsAdd("larksuite/cli")
+	}
+	return r
+}
+
+func (u *Updater) runSkillsAdd(source string) *NpmResult {
 	r := &NpmResult{}
 	npxPath, err := exec.LookPath("npx")
 	if err != nil {
@@ -159,7 +168,7 @@ func (u *Updater) RunSkillsUpdate() *NpmResult {
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), skillsUpdateTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, npxPath, "-y", "skills", "add", "larksuite/cli", "-g", "-y")
+	cmd := exec.CommandContext(ctx, npxPath, "-y", "skills", "add", source, "-g", "-y")
 	cmd.Stdout = &r.Stdout
 	cmd.Stderr = &r.Stderr
 	r.Err = cmd.Run()

package-lock.json

@@ -0,0 +1,84 @@
+{
+  "name": "@larksuite/cli",
+  "version": "1.0.11",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@larksuite/cli",
+      "version": "1.0.11",
+      "cpu": [
+        "x64",
+        "arm64"
+      ],
+      "hasInstallScript": true,
+      "license": "MIT",
+      "os": [
+        "darwin",
+        "linux",
+        "win32"
+      ],
+      "dependencies": {
+        "@clack/prompts": "^1.2.0"
+      },
+      "bin": {
+        "lark-cli": "scripts/run.js"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@clack/core": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@clack/core/-/core-1.2.0.tgz",
+      "integrity": "sha512-qfxof/3T3t9DPU/Rj3OmcFyZInceqj/NVtO9rwIuJqCUgh32gwPjpFQQp/ben07qKlhpwq7GzfWpST4qdJ5Drg==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-wrap-ansi": "^0.1.3",
+        "sisteransi": "^1.0.5"
+      }
+    },
+    "node_modules/@clack/prompts": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@clack/prompts/-/prompts-1.2.0.tgz",
+      "integrity": "sha512-4jmztR9fMqPMjz6H/UZXj0zEmE43ha1euENwkckKKel4XpSfokExPo5AiVStdHSAlHekz4d0CA/r45Ok1E4D3w==",
+      "license": "MIT",
+      "dependencies": {
+        "@clack/core": "1.2.0",
+        "fast-string-width": "^1.1.0",
+        "fast-wrap-ansi": "^0.1.3",
+        "sisteransi": "^1.0.5"
+      }
+    },
+    "node_modules/fast-string-truncated-width": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/fast-string-truncated-width/-/fast-string-truncated-width-1.2.1.tgz",
+      "integrity": "sha512-Q9acT/+Uu3GwGj+5w/zsGuQjh9O1TyywhIwAxHudtWrgF09nHOPrvTLhQevPbttcxjr/SNN7mJmfOw/B1bXgow==",
+      "license": "MIT"
+    },
+    "node_modules/fast-string-width": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/fast-string-width/-/fast-string-width-1.1.0.tgz",
+      "integrity": "sha512-O3fwIVIH5gKB38QNbdg+3760ZmGz0SZMgvwJbA1b2TGXceKE6A2cOlfogh1iw8lr049zPyd7YADHy+B7U4W9bQ==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-string-truncated-width": "^1.2.0"
+      }
+    },
+    "node_modules/fast-wrap-ansi": {
+      "version": "0.1.6",
+      "resolved": "https://registry.npmjs.org/fast-wrap-ansi/-/fast-wrap-ansi-0.1.6.tgz",
+      "integrity": "sha512-HlUwET7a5gqjURj70D5jl7aC3Zmy4weA1SHUfM0JFI0Ptq987NH2TwbBFLoERhfwk+E+eaq4EK3jXoT+R3yp3w==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-string-width": "^1.1.0"
+      }
+    },
+    "node_modules/sisteransi": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
+      "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==",
+      "license": "MIT"
+    }
+  }
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"
@@ -27,7 +27,11 @@
   "license": "MIT",
   "files": [
     "scripts/install.js",
+    "scripts/install-wizard.js",
     "scripts/run.js",
     "CHANGELOG.md"
-  ]
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.2.0"
+  }
 }

scripts/install-wizard.js

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync, execFile } = require("child_process");
+const p = require("@clack/prompts");
+
+const PKG = "@larksuite/cli";
+const SKILLS_REPO = "https://open.feishu.cn";
+const SKILLS_REPO_FALLBACK = "larksuite/cli";
+const isWindows = process.platform === "win32";
+
+// ---------------------------------------------------------------------------
+// i18n
+// ---------------------------------------------------------------------------
+
+const messages = {
+  zh: {
+    setup:          "正在设置 Feishu/Lark CLI...",
+    step1:          "正在安装 %s...",
+    step1Upgrade:   "正在升级 %s (v%s → v%s)...",
+    step1Skip:      "已安装 (v%s)，跳过",
+    step1Done:      "已全局安装",
+    step1Upgraded:  "已升级到 v%s",
+    step1Fail:      "全局安装失败。运行以下命令重试: npm install -g %s",
+    step2:          "安装 AI Skills",
+    step2Skip:      "已安装，跳过",
+    step2Spinner:   "正在安装 Skills...",
+    step2Done:      "Skills 已安装",
+    step2Fail:      "Skills 安装失败。运行以下命令重试: npx skills add %s -y -g",
+    step3:          "正在配置应用...",
+    step3NotFound:  "未找到 lark-cli，终止",
+    step3Found:     "发现已配置应用 (App ID: %s)，继续使用？",
+    step3Skip:      "跳过应用配置",
+    step3Done:      "应用已配置",
+    step3Fail:      "应用配置失败。运行以下命令重试: lark-cli config init --new",
+    step4:          "授权",
+    step4NotFound:  "未找到 lark-cli，跳过授权",
+    step4Confirm:   "允许 AI 访问你的飞书数据（消息、文档、日历等）？",
+    step4Skip:      "跳过授权。后续运行 lark-cli auth login 完成授权",
+    step4Done:      "授权完成",
+    step4Fail:      "授权失败。运行以下命令重试: lark-cli auth login",
+    done:           "安装完成！\n现在可以对你的 AI 工具（Claude Code、Trae 等）说：\"Feishu/Lark CLI 能帮我做什么？结合我的情况推荐一下从哪里开始\"",
+    cancelled:      "安装已取消",
+  },
+  en: {
+    setup:          "Setting up Feishu/Lark CLI...",
+    step1:          "Installing %s globally...",
+    step1Upgrade:   "Upgrading %s (v%s → v%s)...",
+    step1Skip:      "Already installed (v%s). Skipped",
+    step1Done:      "Installed globally",
+    step1Upgraded:  "Upgraded to v%s",
+    step1Fail:      "Failed to install globally. Run manually: npm install -g %s",
+    step2:          "Install AI skills",
+    step2Skip:      "Already installed. Skipped",
+    step2Spinner:   "Installing skills...",
+    step2Done:      "Skills installed",
+    step2Fail:      "Failed to install skills. Run manually: npx skills add %s -y -g",
+    step3:          "Configuring app...",
+    step3NotFound:  "lark-cli not found. Aborting",
+    step3Found:     "Found existing app (App ID: %s). Use this app?",
+    step3Skip:      "Skipped app configuration",
+    step3Done:      "App configured",
+    step3Fail:      "Failed to configure app. Run manually: lark-cli config init --new",
+    step4:          "Authorization",
+    step4NotFound:  "lark-cli not found. Skipping authorization",
+    step4Confirm:   "Allow AI to access your Feishu/Lark data (messages, docs, calendar, etc.)?",
+    step4Skip:      "Skipped. Run lark-cli auth login to authorize later",
+    step4Done:      "Authorization complete",
+    step4Fail:      "Failed to authorize. Run lark-cli auth login to retry",
+    done:           "You are all set!\nNow try asking your AI tool (Claude Code, Trae, etc.): \"What can Feishu/Lark CLI help me with, and where should I start?\"",
+    cancelled:      "Installation cancelled",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function handleCancel(value, msg) {
+  if (p.isCancel(value)) {
+    p.cancel(msg.cancelled);
+    process.exit(0);
+  }
+  return value;
+}
+
+function execCmd(cmd, args, opts) {
+  if (isWindows) {
+    return execFileSync("cmd.exe", ["/c", cmd, ...args], opts);
+  }
+  return execFileSync(cmd, args, opts);
+}
+
+function run(cmd, args, opts = {}) {
+  execCmd(cmd, args, { stdio: "inherit", ...opts });
+}
+
+function runSilent(cmd, args, opts = {}) {
+  return execCmd(cmd, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    ...opts,
+  });
+}
+
+function runSilentAsync(cmd, args, opts = {}) {
+  const actualCmd = isWindows ? "cmd.exe" : cmd;
+  const actualArgs = isWindows ? ["/c", cmd, ...args] : args;
+  return new Promise((resolve, reject) => {
+    execFile(actualCmd, actualArgs, {
+      stdio: ["ignore", "pipe", "pipe"],
+      ...opts,
+    }, (err, stdout) => {
+      if (err) reject(err);
+      else resolve(stdout);
+    });
+  });
+}
+
+function fmt(template, ...values) {
+  let i = 0;
+  return template.replace(/%s/g, () => values[i++] ?? "");
+}
+
+/** Resolve the path of globally installed lark-cli (skip npx temp copies). */
+function whichLarkCli() {
+  try {
+    const prefix = execFileSync("npm", ["prefix", "-g"], {
+      stdio: ["ignore", "pipe", "pipe"],
+    }).toString().trim();
+    const bin = isWindows
+      ? path.join(prefix, "lark-cli.cmd")
+      : path.join(prefix, "bin", "lark-cli");
+    if (fs.existsSync(bin)) return bin;
+  } catch (_) {
+    // fall through
+  }
+  // Fallback to which/where if npm prefix lookup fails.
+  try {
+    const cmd = isWindows ? "where" : "which";
+    return execFileSync(cmd, ["lark-cli"], { stdio: ["ignore", "pipe", "pipe"] })
+      .toString()
+      .split("\n")[0]
+      .trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Get the latest version of @larksuite/cli from the registry. Returns version or null. */
+function getLatestVersion() {
+  try {
+    const out = runSilent("npm", ["view", PKG, "version"], { timeout: 15000 });
+    const ver = out.toString().trim();
+    return /^\d+\.\d+\.\d+/.test(ver) ? ver : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Compare two semver strings. Returns true if a < b. */
+function semverLessThan(a, b) {
+  const pa = a.replace(/-.*$/, "").split(".").map(Number);
+  const pb = b.replace(/-.*$/, "").split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return true;
+    if ((pa[i] || 0) > (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+/** Check whether @larksuite/cli is truly installed in npm global prefix. Returns version or null. */
+function getGloballyInstalledVersion() {
+  try {
+    const out = runSilent("npm", ["list", "-g", PKG], { timeout: 15000 });
+    const match = out.toString().match(/@(\d+\.\d+\.\d+[^\s]*)/);
+    return match ? match[1] : "unknown";
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Check whether lark-cli config already exists. Returns app ID or null. */
+function getExistingAppId(binPath) {
+  try {
+    const out = runSilent(binPath, ["config", "show"], { timeout: 10000 });
+    const json = JSON.parse(out.toString());
+    return json.appId || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Parse --lang from process.argv, returns "zh", "en", or null. */
+function parseLangArg() {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--lang" && args[i + 1]) {
+      const val = args[i + 1].toLowerCase();
+      if (val === "zh" || val === "en") return val;
+    }
+    if (args[i].startsWith("--lang=")) {
+      const val = args[i].split("=")[1].toLowerCase();
+      if (val === "zh" || val === "en") return val;
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Steps
+// ---------------------------------------------------------------------------
+
+async function stepSelectLang() {
+  const fromArg = parseLangArg();
+  if (fromArg) return fromArg;
+
+  const lang = await p.select({
+    message: "请选择语言 / Select language",
+    options: [
+      { value: "zh", label: "中文" },
+      { value: "en", label: "English" },
+    ],
+  });
+  return handleCancel(lang, messages.zh);
+}
+
+async function stepInstallGlobally(msg) {
+  const installedVer = getGloballyInstalledVersion();
+  const latestVer = getLatestVersion();
+  const needsUpgrade = installedVer && latestVer && semverLessThan(installedVer, latestVer);
+
+  if (installedVer && !needsUpgrade) {
+    p.log.info(fmt(msg.step1Skip, installedVer));
+    return false;
+  }
+
+  const s = p.spinner();
+  if (needsUpgrade) {
+    s.start(fmt(msg.step1Upgrade, PKG, installedVer, latestVer));
+  } else {
+    s.start(fmt(msg.step1, PKG));
+  }
+  try {
+    await runSilentAsync("npm", ["install", "-g", PKG], { timeout: 120000 });
+    s.stop(needsUpgrade ? fmt(msg.step1Upgraded, latestVer) : msg.step1Done);
+    return needsUpgrade;
+  } catch (_) {
+    s.stop(fmt(msg.step1Fail, PKG));
+    process.exit(1);
+  }
+}
+
+async function skillsAlreadyInstalled() {
+  try {
+    const out = await runSilentAsync("npx", ["-y", "skills", "ls", "-g"], {
+      timeout: 120000,
+    });
+    return /^lark-/m.test(out.toString());
+  } catch (_) {
+    return false;
+  }
+}
+
+async function stepInstallSkills(msg) {
+  const s = p.spinner();
+  s.start(msg.step2Spinner);
+  try {
+    if (await skillsAlreadyInstalled()) {
+      s.stop(msg.step2Skip);
+      return;
+    }
+    try {
+      await runSilentAsync("npx", ["-y", "skills", "add", SKILLS_REPO, "-y", "-g"], {
+        timeout: 120000,
+      });
+    } catch (_) {
+      await runSilentAsync("npx", ["-y", "skills", "add", SKILLS_REPO_FALLBACK, "-y", "-g"], {
+        timeout: 120000,
+      });
+    }
+    s.stop(msg.step2Done);
+  } catch (_) {
+    s.stop(fmt(msg.step2Fail, SKILLS_REPO_FALLBACK));
+    process.exit(1);
+  }
+}
+
+async function stepConfigInit(msg, lang) {
+  const s = p.spinner();
+  s.start(msg.step3);
+
+  const larkCli = whichLarkCli();
+  if (!larkCli) {
+    s.stop(msg.step3NotFound);
+    process.exit(1);
+  }
+
+  const appId = getExistingAppId(larkCli);
+  s.stop(msg.step3);
+
+  if (appId) {
+    const reuse = await p.confirm({
+      message: fmt(msg.step3Found, appId),
+    });
+    if (handleCancel(reuse, msg) && reuse) {
+      p.log.info(msg.step3Skip);
+      return;
+    }
+  }
+
+  try {
+    run(larkCli, ["config", "init", "--new", "--lang", lang]);
+    p.log.success(msg.step3Done);
+  } catch (_) {
+    p.log.error(msg.step3Fail);
+    process.exit(1);
+  }
+}
+
+async function stepAuthLogin(msg) {
+  const larkCli = whichLarkCli();
+  if (!larkCli) {
+    p.log.warn(msg.step4NotFound);
+    return;
+  }
+
+  const yes = await p.confirm({
+    message: msg.step4Confirm,
+  });
+  if (p.isCancel(yes)) {
+    p.cancel(msg.cancelled);
+    process.exit(0);
+  }
+  if (!yes) {
+    p.log.info(msg.step4Skip);
+    return;
+  }
+
+  p.log.step(msg.step4);
+  try {
+    run(larkCli, ["auth", "login"]);
+    p.log.success(msg.step4Done);
+  } catch (_) {
+    p.log.warn(msg.step4Fail);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const lang = await stepSelectLang();
+  const msg = messages[lang];
+
+  p.intro(msg.setup);
+
+  await stepInstallGlobally(msg);
+  await stepInstallSkills(msg);
+  await stepConfigInit(msg, lang);
+  await stepAuthLogin(msg);
+
+  p.outro(msg.done);
+}
+
+main().catch((err) => {
+  p.cancel("Unexpected error: " + (err.message || err));
+  process.exit(1);
+});

scripts/install.js

@@ -3,10 +3,10 @@
 
 const fs = require("fs");
 const path = require("path");
-const { execSync } = require("child_process");
+const { execFileSync } = require("child_process");
 const os = require("os");
 
-const VERSION = require("../package.json").version;
+const VERSION = require("../package.json").version.replace(/-.*$/, "");
 const REPO = "larksuite/cli";
 const NAME = "lark-cli";
 
@@ -43,13 +43,16 @@ const dest = path.join(binDir, NAME + (isWindows ? ".exe" : ""));
 fs.mkdirSync(binDir, { recursive: true });
 
 function download(url, destPath) {
+  const args = [
+    "--fail", "--location", "--silent", "--show-error",
+    "--connect-timeout", "10", "--max-time", "120",
+    "--output", destPath,
+  ];
   // --ssl-revoke-best-effort: on Windows (Schannel), avoid CRYPT_E_REVOCATION_OFFLINE
   // errors when the certificate revocation list server is unreachable
-  const sslFlag = isWindows ? "--ssl-revoke-best-effort " : "";
-  execSync(
-    `curl ${sslFlag}--fail --location --silent --show-error --connect-timeout 10 --max-time 120 --output "${destPath}" "${url}"`,
-    { stdio: ["ignore", "ignore", "pipe"] }
-  );
+  if (isWindows) args.unshift("--ssl-revoke-best-effort");
+  args.push(url);
+  execFileSync("curl", args, { stdio: ["ignore", "ignore", "pipe"] });
 }
 
 function install() {
@@ -64,12 +67,12 @@ function install() {
     }
 
     if (isWindows) {
-      execSync(
-        `powershell -Command "Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}'"`,
-        { stdio: "ignore" }
-      );
+      execFileSync("powershell", [
+        "-Command",
+        `Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}'`,
+      ], { stdio: "ignore" });
     } else {
-      execSync(`tar -xzf "${archivePath}" -C "${tmpDir}"`, {
+      execFileSync("tar", ["-xzf", archivePath, "-C", tmpDir], {
         stdio: "ignore",
       });
     }
@@ -85,6 +88,16 @@ function install() {
   }
 }
 
+// When triggered as a postinstall hook under npx, skip the binary download.
+// The "install" wizard doesn't need it, and run.js calls install.js directly
+// (with LARK_CLI_RUN=1) for other commands that do need the binary.
+const isNpxPostinstall =
+  process.env.npm_command === "exec" && !process.env.LARK_CLI_RUN;
+
+if (isNpxPostinstall) {
+  process.exit(0);
+}
+
 try {
   install();
 } catch (err) {

scripts/run.js

@@ -41,21 +41,32 @@ if (process.platform === "win32" && fs.existsSync(oldBin)) {
   }
 }
 
-if (!fs.existsSync(bin)) {
-  console.error(
-    `Error: lark-cli binary not found at ${bin}\n\n` +
-    `This usually means the postinstall script was skipped.\n` +
-    `Common causes:\n` +
-    `  - npm is configured with ignore-scripts=true\n` +
-    `  - The postinstall download failed\n\n` +
-    `To fix, run the install script manually:\n` +
-    `  node "${path.join(__dirname, "install.js")}"\n`
-  );
-  process.exit(1);
-}
+// Intercept "install" subcommand — run the setup wizard directly,
+// bypassing the native binary (which may not exist yet under npx).
+const args = process.argv.slice(2);
+if (args[0] === "install") {
+  require("./install-wizard.js");
+} else {
+  // Auto-download binary if missing (e.g. npx skipped postinstall).
+  if (!fs.existsSync(bin)) {
+    try {
+      execFileSync(process.execPath, [path.join(__dirname, "install.js")], {
+        stdio: "inherit",
+        env: { ...process.env, LARK_CLI_RUN: "true" },
+      });
+    } catch (_) {
+      console.error(
+        `\nFailed to auto-install lark-cli binary.\n` +
+        `To fix, run the install script manually:\n` +
+        `  node "${path.join(__dirname, "install.js")}"\n`
+      );
+      process.exit(1);
+    }
+  }
 
-try {
-  execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
-} catch (e) {
-  process.exit(e.status || 1);
+  try {
+    execFileSync(bin, args, { stdio: "inherit" });
+  } catch (e) {
+    process.exit(e.status || 1);
+  }
 }

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_create_shortcut.go

@@ -0,0 +1,136 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var driveCreateShortcutAllowedTypes = map[string]bool{
+	"file":     true,
+	"docx":     true,
+	"bitable":  true,
+	"doc":      true,
+	"sheet":    true,
+	"mindnote": true,
+	"slides":   true,
+}
+
+type driveCreateShortcutSpec struct {
+	FileToken   string
+	FileType    string
+	FolderToken string
+}
+
+func newDriveCreateShortcutSpec(runtime *common.RuntimeContext) driveCreateShortcutSpec {
+	return driveCreateShortcutSpec{
+		FileToken:   strings.TrimSpace(runtime.Str("file-token")),
+		FileType:    strings.ToLower(strings.TrimSpace(runtime.Str("type"))),
+		FolderToken: strings.TrimSpace(runtime.Str("folder-token")),
+	}
+}
+
+// RequestBody builds the create_shortcut API payload from the shortcut spec.
+func (s driveCreateShortcutSpec) RequestBody() map[string]interface{} {
+	return map[string]interface{}{
+		"parent_token": s.FolderToken,
+		"refer_entity": map[string]interface{}{
+			"refer_token": s.FileToken,
+			"refer_type":  s.FileType,
+		},
+	}
+}
+
+// DriveCreateShortcut creates a Drive shortcut for an existing file in another folder.
+var DriveCreateShortcut = common.Shortcut{
+	Service:     "drive",
+	Command:     "+create-shortcut",
+	Description: "Create a Drive shortcut in another folder",
+	Risk:        "write",
+	Scopes:      []string{"space:document:shortcut"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "file-token", Desc: "source file token to reference", Required: true},
+		{Name: "type", Desc: "source file type (file, docx, bitable, doc, sheet, mindnote, slides)", Required: true},
+		{Name: "folder-token", Desc: "target folder token for the new shortcut", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateDriveCreateShortcutSpec(newDriveCreateShortcutSpec(runtime))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec := newDriveCreateShortcutSpec(runtime)
+
+		return common.NewDryRunAPI().
+			Desc("Create a Drive shortcut").
+			POST("/open-apis/drive/v1/files/create_shortcut").
+			Desc("[1] Create shortcut").
+			Body(spec.RequestBody())
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec := newDriveCreateShortcutSpec(runtime)
+
+		fmt.Fprintf(
+			runtime.IO().ErrOut,
+			"Creating shortcut for %s %s in folder %s...\n",
+			spec.FileType,
+			common.MaskToken(spec.FileToken),
+			common.MaskToken(spec.FolderToken),
+		)
+
+		data, err := runtime.CallAPI(
+			"POST",
+			"/open-apis/drive/v1/files/create_shortcut",
+			nil,
+			spec.RequestBody(),
+		)
+		if err != nil {
+			return err
+		}
+
+		out := map[string]interface{}{
+			"created":           true,
+			"source_file_token": spec.FileToken,
+			"source_type":       spec.FileType,
+			"folder_token":      spec.FolderToken,
+		}
+		if shortcutToken := common.GetString(data, "succ_shortcut_node", "token"); shortcutToken != "" {
+			out["shortcut_token"] = shortcutToken
+		}
+		if url := common.GetString(data, "succ_shortcut_node", "url"); url != "" {
+			out["url"] = url
+		}
+		if title := common.GetString(data, "succ_shortcut_node", "name"); title != "" {
+			out["title"] = title
+		}
+
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+// validateDriveCreateShortcutSpec validates shortcut creation inputs before API execution.
+func validateDriveCreateShortcutSpec(spec driveCreateShortcutSpec) error {
+	if err := validate.ResourceName(spec.FileToken, "--file-token"); err != nil {
+		return output.ErrValidation("%s", err)
+	}
+	if err := validate.ResourceName(spec.FolderToken, "--folder-token"); err != nil {
+		return output.ErrValidation("%s", err)
+	}
+	if spec.FileType == "wiki" {
+		return output.ErrValidation("unsupported file type: wiki. This shortcut only supports Drive file tokens; wiki documents must be resolved to their underlying file token first")
+	}
+	if spec.FileType == "folder" {
+		return output.ErrValidation("unsupported file type: folder. The create_shortcut API only supports Drive files, not folders")
+	}
+	if !driveCreateShortcutAllowedTypes[spec.FileType] {
+		return output.ErrValidation("unsupported file type: %s. Supported types: file, docx, bitable, doc, sheet, mindnote, slides", spec.FileType)
+	}
+	return nil
+}

shortcuts/drive/drive_create_shortcut_test.go

@@ -0,0 +1,336 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// TestValidateDriveCreateShortcutSpecRejectsUnsupportedTypes verifies unsupported source types are rejected early.
+func TestValidateDriveCreateShortcutSpecRejectsUnsupportedTypes(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		spec    driveCreateShortcutSpec
+		wantErr string
+	}{
+		{
+			name: "wiki",
+			spec: driveCreateShortcutSpec{
+				FileToken:   "wiki_token_test",
+				FileType:    "wiki",
+				FolderToken: "target_folder_token_test",
+			},
+			wantErr: "underlying file token first",
+		},
+		{
+			name: "folder",
+			spec: driveCreateShortcutSpec{
+				FileToken:   "folder_token_test",
+				FileType:    "folder",
+				FolderToken: "target_folder_token_test",
+			},
+			wantErr: "not folders",
+		},
+		{
+			name: "shortcut",
+			spec: driveCreateShortcutSpec{
+				FileToken:   "shortcut_token_test",
+				FileType:    "shortcut",
+				FolderToken: "target_folder_token_test",
+			},
+			wantErr: "Supported types",
+		},
+		{
+			name: "missing folder token",
+			spec: driveCreateShortcutSpec{
+				FileToken: "file_token_test",
+				FileType:  "docx",
+			},
+			wantErr: "--folder-token must not be empty",
+		},
+		{
+			name: "unknown",
+			spec: driveCreateShortcutSpec{
+				FileToken:   "file_token_test",
+				FileType:    "unknown",
+				FolderToken: "target_folder_token_test",
+			},
+			wantErr: "Supported types",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := validateDriveCreateShortcutSpec(tt.spec)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantErr)
+			}
+		})
+	}
+}
+
+// TestDriveCreateShortcutDryRunIncludesSingleCreateRequest verifies dry-run only previews the create request.
+func TestDriveCreateShortcutDryRunIncludesSingleCreateRequest(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +create-shortcut"}
+	cmd.Flags().String("file-token", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	if err := cmd.Flags().Set("file-token", " doc_token_test "); err != nil {
+		t.Fatalf("set --file-token: %v", err)
+	}
+	if err := cmd.Flags().Set("type", " DOCX "); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+	if err := cmd.Flags().Set("folder-token", " folder_target_token_test "); err != nil {
+		t.Fatalf("set --folder-token: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+	dry := DriveCreateShortcut.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 {
+			Method string                 `json:"method"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if len(got.API) != 1 {
+		t.Fatalf("expected 1 API call, got %d", len(got.API))
+	}
+	if got.API[0].Method != "POST" {
+		t.Fatalf("first method = %q, want POST", got.API[0].Method)
+	}
+	if got.API[0].Body["parent_token"] != "folder_target_token_test" {
+		t.Fatalf("parent_token = %#v, want folder_target_token_test", got.API[0].Body["parent_token"])
+	}
+	referEntity, _ := got.API[0].Body["refer_entity"].(map[string]interface{})
+	if referEntity["refer_token"] != "doc_token_test" || referEntity["refer_type"] != "docx" {
+		t.Fatalf("unexpected refer_entity: %#v", referEntity)
+	}
+}
+
+// TestDriveCreateShortcutUsesProvidedFolderToken verifies execution uses the explicit target folder token.
+func TestDriveCreateShortcutUsesProvidedFolderToken(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/create_shortcut",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"succ_shortcut_node": map[string]interface{}{
+					"token":        "shortcut_token_test",
+					"name":         "shortcut_name_test",
+					"type":         "docx",
+					"parent_token": "folder_target_token_test",
+					"url":          "https://example.feishu.cn/docx/shortcut_token_test",
+					"shortcut_info": map[string]interface{}{
+						"target_type":  "docx",
+						"target_token": "doc_token_test",
+					},
+				},
+			},
+		},
+	}
+	reg.Register(createStub)
+
+	err := mountAndRunDrive(t, DriveCreateShortcut, []string{
+		"+create-shortcut",
+		"--file-token", " doc_token_test ",
+		"--type", " DOCX ",
+		"--folder-token", " folder_target_token_test ",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeCapturedJSONBody(t, createStub)
+	if body["parent_token"] != "folder_target_token_test" {
+		t.Fatalf("parent_token = %#v, want folder_target_token_test", body["parent_token"])
+	}
+	referEntity, _ := body["refer_entity"].(map[string]interface{})
+	if referEntity["refer_token"] != "doc_token_test" || referEntity["refer_type"] != "docx" {
+		t.Fatalf("unexpected refer_entity: %#v", referEntity)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if data["shortcut_token"] != "shortcut_token_test" {
+		t.Fatalf("shortcut_token = %#v, want shortcut_token_test", data["shortcut_token"])
+	}
+	if data["folder_token"] != "folder_target_token_test" {
+		t.Fatalf("folder_token = %#v, want folder_target_token_test", data["folder_token"])
+	}
+	if data["source_file_token"] != "doc_token_test" {
+		t.Fatalf("source_file_token = %#v, want doc_token_test", data["source_file_token"])
+	}
+	if data["title"] != "shortcut_name_test" {
+		t.Fatalf("title = %#v, want shortcut_name_test", data["title"])
+	}
+	if data["url"] != "https://example.feishu.cn/docx/shortcut_token_test" {
+		t.Fatalf("url = %#v, want https://example.feishu.cn/docx/shortcut_token_test", data["url"])
+	}
+	if data["created"] != true {
+		t.Fatalf("created = %#v, want true", data["created"])
+	}
+}
+
+// TestDriveCreateShortcutValidateRequiresFolderToken verifies folder-token is mandatory.
+func TestDriveCreateShortcutValidateRequiresFolderToken(t *testing.T) {
+	err := validateDriveCreateShortcutSpec(driveCreateShortcutSpec{
+		FileToken: "doc_token_test",
+		FileType:  "docx",
+	})
+	if err == nil {
+		t.Fatal("expected validation error, got nil")
+	}
+	if !strings.Contains(err.Error(), "--folder-token must not be empty") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// TestDriveCreateShortcutValidateRejectsWhitespaceOnlyFolderToken verifies runtime normalization rejects blank folder tokens.
+func TestDriveCreateShortcutValidateRejectsWhitespaceOnlyFolderToken(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +create-shortcut"}
+	cmd.Flags().String("file-token", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	if err := cmd.Flags().Set("file-token", "doc_token_test"); err != nil {
+		t.Fatalf("set --file-token: %v", err)
+	}
+	if err := cmd.Flags().Set("type", " DOCX "); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+	if err := cmd.Flags().Set("folder-token", "   "); err != nil {
+		t.Fatalf("set --folder-token: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContext(cmd, nil)
+	err := DriveCreateShortcut.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected validation error, got nil")
+	}
+	if !strings.Contains(err.Error(), "--folder-token must not be empty") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// TestDriveCreateShortcutClassifiesKnownAPIConstraints verifies known API constraints surface as structured errors.
+func TestDriveCreateShortcutClassifiesKnownAPIConstraints(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		code        int
+		msg         string
+		wantType    string
+		wantHint    string
+		wantMsgPart string
+	}{
+		{
+			name:        "resource contention",
+			code:        output.LarkErrDriveResourceContention,
+			msg:         "resource contention occurred, please retry",
+			wantType:    "conflict",
+			wantHint:    "avoid concurrent duplicate requests",
+			wantMsgPart: "resource contention occurred",
+		},
+		{
+			name:        "cross tenant and unit",
+			code:        output.LarkErrDriveCrossTenantUnit,
+			msg:         "cross tenant and unit not support",
+			wantType:    "cross_tenant_unit",
+			wantHint:    "same tenant and region/unit",
+			wantMsgPart: "cross tenant and unit not support",
+		},
+		{
+			name:        "cross brand",
+			code:        output.LarkErrDriveCrossBrand,
+			msg:         "cross brand not support",
+			wantType:    "cross_brand",
+			wantHint:    "same brand environment",
+			wantMsgPart: "cross brand not support",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+			reg.Register(&httpmock.Stub{
+				Method: "POST",
+				URL:    "/open-apis/drive/v1/files/create_shortcut",
+				Body: map[string]interface{}{
+					"code": float64(tt.code),
+					"msg":  tt.msg,
+				},
+			})
+
+			err := mountAndRunDrive(t, DriveCreateShortcut, []string{
+				"+create-shortcut",
+				"--file-token", "doc_token_test",
+				"--type", "docx",
+				"--folder-token", "folder_token_test",
+				"--as", "bot",
+			}, f, nil)
+			if err == nil {
+				t.Fatal("expected API error, got nil")
+			}
+
+			var exitErr *output.ExitError
+			if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+				t.Fatalf("expected structured exit error, got %v", err)
+			}
+			if exitErr.Code != output.ExitAPI {
+				t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitAPI)
+			}
+			if exitErr.Detail.Type != tt.wantType {
+				t.Fatalf("type = %q, want %q", exitErr.Detail.Type, tt.wantType)
+			}
+			if exitErr.Detail.Code != tt.code {
+				t.Fatalf("detail code = %d, want %d", exitErr.Detail.Code, tt.code)
+			}
+			if !strings.Contains(exitErr.Detail.Message, tt.wantMsgPart) {
+				t.Fatalf("message = %q, want substring %q", exitErr.Detail.Message, tt.wantMsgPart)
+			}
+			if !strings.Contains(exitErr.Detail.Hint, tt.wantHint) {
+				t.Fatalf("hint = %q, want substring %q", exitErr.Detail.Hint, tt.wantHint)
+			}
+		})
+	}
+}

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/drive/shortcuts.go

@@ -9,6 +9,7 @@ import "github.com/larksuite/cli/shortcuts/common"
 func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		DriveUpload,
+		DriveCreateShortcut,
 		DriveDownload,
 		DriveAddComment,
 		DriveExport,

shortcuts/drive/shortcuts_test.go

@@ -5,12 +5,14 @@ package drive
 
 import "testing"
 
+// TestShortcutsIncludesExpectedCommands verifies the drive shortcut registry contains the expected commands.
 func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 	t.Parallel()
 
 	got := Shortcuts()
 	want := []string{
 		"+upload",
+		"+create-shortcut",
 		"+download",
 		"+add-comment",
 		"+export",

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/draft/model.go

@@ -144,6 +144,8 @@ type DraftProjection struct {
 	BodyText           string        `json:"body_text,omitempty"`
 	BodyHTMLSummary    string        `json:"body_html_summary,omitempty"`
 	HasQuotedContent   bool          `json:"has_quoted_content,omitempty"`
+	HasSignature       bool          `json:"has_signature,omitempty"`
+	SignatureID        string        `json:"signature_id,omitempty"`
 	AttachmentsSummary []PartSummary `json:"attachments_summary,omitempty"`
 	InlineSummary      []PartSummary `json:"inline_summary,omitempty"`
 	Warnings           []string      `json:"warnings,omitempty"`
@@ -182,6 +184,22 @@ type PatchOp struct {
 	FileName    string           `json:"filename,omitempty"`
 	ContentType string           `json:"content_type,omitempty"`
 	Target      AttachmentTarget `json:"target,omitempty"`
+	SignatureID string           `json:"signature_id,omitempty"`
+
+	// RenderedSignatureHTML is set by the shortcut layer (not from JSON) after
+	// fetching and interpolating the signature. The patch layer uses this
+	// pre-rendered content for insert_signature ops.
+	RenderedSignatureHTML string           `json:"-"`
+	SignatureImages       []SignatureImage `json:"-"`
+}
+
+// SignatureImage holds pre-downloaded image data for signature inline images.
+// Populated by the shortcut layer, consumed by the patch layer.
+type SignatureImage struct {
+	CID         string
+	ContentType string
+	FileName    string
+	Data        []byte
 }
 
 func (p Patch) Validate() error {
@@ -274,6 +292,12 @@ func (op PatchOp) Validate() error {
 		if !op.Target.hasKey() {
 			return fmt.Errorf("remove_inline requires target with at least one of part_id or cid")
 		}
+	case "insert_signature":
+		if strings.TrimSpace(op.SignatureID) == "" {
+			return fmt.Errorf("insert_signature requires signature_id")
+		}
+	case "remove_signature":
+		// No required fields.
 	default:
 		return fmt.Errorf("unsupported op %q", op.Op)
 	}

shortcuts/mail/draft/patch.go

@@ -33,10 +33,12 @@ var protectedHeaders = map[string]bool{
 // bodyChangingOps lists patch operations that modify the HTML body content,
 // which is the trigger for running local image path resolution.
 var bodyChangingOps = map[string]bool{
-	"set_body":       true,
-	"set_reply_body": true,
-	"replace_body":   true,
-	"append_body":    true,
+	"set_body":         true,
+	"set_reply_body":   true,
+	"replace_body":     true,
+	"append_body":      true,
+	"insert_signature": true,
+	"remove_signature": true,
 }
 
 func Apply(dctx *DraftCtx, snapshot *DraftSnapshot, patch Patch) error {
@@ -121,6 +123,10 @@ func applyOp(dctx *DraftCtx, snapshot *DraftSnapshot, op PatchOp, options PatchO
 			return fmt.Errorf("remove_inline: %w", err)
 		}
 		return removeInline(snapshot, partID)
+	case "insert_signature":
+		return insertSignatureOp(snapshot, op)
+	case "remove_signature":
+		return removeSignatureOp(snapshot)
 	default:
 		return fmt.Errorf("unsupported patch op %q", op.Op)
 	}
@@ -284,7 +290,7 @@ func setReplyBody(snapshot *DraftSnapshot, value string, options PatchOptions) e
 	if htmlPart == nil {
 		return setBody(snapshot, value, options)
 	}
-	_, quotePart := splitAtQuote(string(htmlPart.Body))
+	_, quotePart := SplitAtQuote(string(htmlPart.Body))
 	if quotePart == "" {
 		// No quote block found — fall back to regular set_body.
 		return setBody(snapshot, value, options)
@@ -1135,3 +1141,166 @@ func postProcessInlineImages(dctx *DraftCtx, snapshot *DraftSnapshot, resolveLoc
 	removeOrphanedInlineParts(snapshot.Body, refSet)
 	return nil
 }
+
+// ── Signature patch operations ──
+
+// insertSignatureOp inserts a pre-rendered signature into the HTML body.
+// The RenderedSignatureHTML and SignatureImages fields must be populated
+// by the shortcut layer before calling Apply.
+func insertSignatureOp(snapshot *DraftSnapshot, op PatchOp) error {
+	htmlPart := findPart(snapshot.Body, snapshot.PrimaryHTMLPartID)
+	if htmlPart == nil {
+		return fmt.Errorf("insert_signature: no HTML body part found; use set_body first")
+	}
+	html := string(htmlPart.Body)
+
+	// Collect CIDs from old signature before removing it, so we can
+	// clean up orphaned MIME inline parts and avoid duplicates.
+	oldSigCIDs := collectSignatureCIDsFromHTML(html)
+
+	// Remove existing signature (if any), including preceding spacing.
+	html = RemoveSignatureHTML(html)
+
+	// Remove orphaned MIME inline parts from old signature.
+	for _, cid := range oldSigCIDs {
+		if !containsCIDIgnoreCase(html, cid) {
+			removeMIMEPartByCID(snapshot.Body, cid)
+		}
+	}
+
+	// Split at quote and insert signature between body and quote.
+	body, quote := SplitAtQuote(html)
+	sigBlock := SignatureSpacing() + BuildSignatureHTML(op.SignatureID, op.RenderedSignatureHTML)
+	html = body + sigBlock + quote
+
+	htmlPart.Body = []byte(html)
+	htmlPart.Dirty = true
+
+	// Add signature inline images to the MIME tree.
+	for _, img := range op.SignatureImages {
+		addInlinePartToSnapshot(snapshot, img.Data, img.ContentType, img.FileName, img.CID)
+	}
+
+	syncTextPartFromHTML(snapshot, html)
+	return nil
+}
+
+// removeSignatureOp removes the signature block from the HTML body.
+func removeSignatureOp(snapshot *DraftSnapshot) error {
+	htmlPart := findPart(snapshot.Body, snapshot.PrimaryHTMLPartID)
+	if htmlPart == nil {
+		return fmt.Errorf("remove_signature: no HTML body part found")
+	}
+	html := string(htmlPart.Body)
+
+	if !signatureWrapperRe.MatchString(html) {
+		return fmt.Errorf("no signature found in draft body")
+	}
+
+	// Collect CIDs referenced by the signature before removing it.
+	sigCIDs := collectSignatureCIDsFromHTML(html)
+
+	// Remove signature and preceding spacing.
+	html = RemoveSignatureHTML(html)
+
+	// Remove orphaned inline parts (only if the CID is no longer referenced in remaining HTML).
+	for _, cid := range sigCIDs {
+		if !containsCIDIgnoreCase(html, cid) {
+			removeMIMEPartByCID(snapshot.Body, cid)
+		}
+	}
+
+	htmlPart.Body = []byte(html)
+	htmlPart.Dirty = true
+
+	syncTextPartFromHTML(snapshot, html)
+	return nil
+}
+
+// syncTextPartFromHTML regenerates the text/plain part from the current HTML,
+// mirroring the coupled-body logic in tryApplyCoupledBodySetBody.
+func syncTextPartFromHTML(snapshot *DraftSnapshot, html string) {
+	if snapshot.PrimaryTextPartID == "" {
+		return
+	}
+	textPart := findPart(snapshot.Body, snapshot.PrimaryTextPartID)
+	if textPart == nil {
+		return
+	}
+	textPart.Body = []byte(plainTextFromHTML(html))
+	textPart.Dirty = true
+}
+
+// Note: SignatureSpacing, BuildSignatureHTML, FindMatchingCloseDiv, and
+// RemoveSignatureHTML are exported from projection.go to avoid duplication
+// with the mail package's signature_html.go.
+
+// collectSignatureCIDsFromHTML extracts CID references from the signature block in HTML.
+func collectSignatureCIDsFromHTML(html string) []string {
+	loc := signatureWrapperRe.FindStringIndex(html)
+	if loc == nil {
+		return nil
+	}
+	sigEnd := FindMatchingCloseDiv(html, loc[0])
+	sigHTML := html[loc[0]:sigEnd]
+
+	matches := cidRefRegexp.FindAllStringSubmatch(sigHTML, -1)
+	cids := make([]string, 0, len(matches))
+	for _, m := range matches {
+		if len(m) >= 2 {
+			cids = append(cids, m[1])
+		}
+	}
+	return cids
+}
+
+// removeMIMEPartByCID removes the first MIME part with the given Content-ID.
+func removeMIMEPartByCID(root *Part, cid string) {
+	if root == nil {
+		return
+	}
+	normalizedCID := strings.Trim(cid, "<>")
+	for i, child := range root.Children {
+		if child == nil {
+			continue
+		}
+		childCID := strings.Trim(child.ContentID, "<>")
+		if strings.EqualFold(childCID, normalizedCID) {
+			root.Children = append(root.Children[:i], root.Children[i+1:]...)
+			return
+		}
+		removeMIMEPartByCID(child, cid)
+	}
+}
+
+// addInlinePartToSnapshot adds an inline image part to the MIME tree.
+func addInlinePartToSnapshot(snapshot *DraftSnapshot, data []byte, contentType, filename, cid string) {
+	part := &Part{
+		MediaType:          contentType,
+		ContentDisposition: "inline",
+		ContentID:          strings.Trim(cid, "<>"),
+		Body:               data,
+		Dirty:              true,
+	}
+	if filename != "" {
+		part.MediaParams = map[string]string{"name": filename}
+	}
+	// Find or create the multipart/related container.
+	if snapshot.Body == nil {
+		return
+	}
+	if snapshot.Body.IsMultipart() {
+		snapshot.Body.Children = append(snapshot.Body.Children, part)
+	}
+	// Non-multipart body: inline part is not added. This is expected when
+	// the draft has a simple text/html body without multipart/related wrapper.
+	// The signature HTML still references the CID, but the image won't render.
+	// In practice, compose shortcuts wrap the body in multipart/related when
+	// inline images are present, so this path rarely triggers.
+}
+
+// containsCIDIgnoreCase checks if html contains a "cid:<value>" reference,
+// case-insensitively. Aligned with other CID comparisons in this package.
+func containsCIDIgnoreCase(html, cid string) bool {
+	return strings.Contains(strings.ToLower(html), "cid:"+strings.ToLower(cid))
+}

shortcuts/mail/draft/patch_signature_test.go

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package draft
+
+import (
+	"strings"
+	"testing"
+)
+
+// ---------------------------------------------------------------------------
+// insert_signature — basic insertion into HTML body
+// ---------------------------------------------------------------------------
+
+func TestInsertSignature_BasicHTML(t *testing.T) {
+	snapshot := mustParseFixtureDraft(t, `Subject: Sig test
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+MIME-Version: 1.0
+Content-Type: text/html; charset=UTF-8
+
+<p>Hello</p>`)
+
+	err := Apply(&DraftCtx{FIO: testFIO}, snapshot, Patch{
+		Ops: []PatchOp{{
+			Op:                    "insert_signature",
+			SignatureID:           "sig-123",
+			RenderedSignatureHTML: "<div>-- My Signature</div>",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("Apply insert_signature: %v", err)
+	}
+
+	html := string(findPart(snapshot.Body, snapshot.PrimaryHTMLPartID).Body)
+	if !strings.Contains(html, "My Signature") {
+		t.Error("signature not found in HTML body")
+	}
+	if !strings.Contains(html, `class="lark-mail-signature"`) {
+		t.Error("signature wrapper class not found")
+	}
+	if !strings.Contains(html, `id="sig-123"`) {
+		t.Error("signature ID not found")
+	}
+	// Body text should come before signature
+	bodyIdx := strings.Index(html, "Hello")
+	sigIdx := strings.Index(html, "My Signature")
+	if bodyIdx > sigIdx {
+		t.Error("signature should appear after body text")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// insert_signature — with quoted content (reply/forward)
+// ---------------------------------------------------------------------------
+
+func TestInsertSignature_BeforeQuote(t *testing.T) {
+	snapshot := mustParseFixtureDraft(t, `Subject: Reply with sig
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+MIME-Version: 1.0
+Content-Type: text/html; charset=UTF-8
+
+<p>My reply</p><div id="lark-mail-quote-cli123" class="history-quote-wrapper"><div>quoted content</div></div>`)
+
+	err := Apply(&DraftCtx{FIO: testFIO}, snapshot, Patch{
+		Ops: []PatchOp{{
+			Op:                    "insert_signature",
+			SignatureID:           "sig-456",
+			RenderedSignatureHTML: "<div>-- Reply Sig</div>",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("Apply insert_signature: %v", err)
+	}
+
+	html := string(findPart(snapshot.Body, snapshot.PrimaryHTMLPartID).Body)
+	sigIdx := strings.Index(html, "Reply Sig")
+	quoteIdx := strings.Index(html, "quoted content")
+	if sigIdx < 0 || quoteIdx < 0 {
+		t.Fatalf("missing signature or quote in: %s", html)
+	}
+	if sigIdx > quoteIdx {
+		t.Error("signature should appear before quote block")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// insert_signature — replaces existing signature
+// ---------------------------------------------------------------------------
+
+func TestInsertSignature_ReplacesExisting(t *testing.T) {
+	snapshot := mustParseFixtureDraft(t, `Subject: Replace sig
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+MIME-Version: 1.0
+Content-Type: text/html; charset=UTF-8
+
+<p>Hello</p><div id="old-sig" class="lark-mail-signature" style="padding-top:6px;padding-bottom:6px"><div>-- Old Sig</div></div>`)
+
+	err := Apply(&DraftCtx{FIO: testFIO}, snapshot, Patch{
+		Ops: []PatchOp{{
+			Op:                    "insert_signature",
+			SignatureID:           "new-sig",
+			RenderedSignatureHTML: "<div>-- New Sig</div>",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("Apply insert_signature: %v", err)
+	}
+
+	html := string(findPart(snapshot.Body, snapshot.PrimaryHTMLPartID).Body)
+	if strings.Contains(html, "Old Sig") {
+		t.Error("old signature should have been removed")
+	}
+	if !strings.Contains(html, "New Sig") {
+		t.Error("new signature not found")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// insert_signature — no HTML body
+// ---------------------------------------------------------------------------
+
+func TestInsertSignature_NoHTMLBody(t *testing.T) {
+	snapshot := mustParseFixtureDraft(t, `Subject: Plain text
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+
+Just plain text`)
+
+	err := Apply(&DraftCtx{FIO: testFIO}, snapshot, Patch{
+		Ops: []PatchOp{{
+			Op:                    "insert_signature",
+			SignatureID:           "sig-x",
+			RenderedSignatureHTML: "<div>sig</div>",
+		}},
+	})
+	if err == nil {
+		t.Fatal("expected error for insert_signature on plain text draft")
+	}
+	if !strings.Contains(err.Error(), "no HTML body") {
+		t.Fatalf("expected 'no HTML body' error, got: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// remove_signature — removes existing signature
+// ---------------------------------------------------------------------------
+
+func TestRemoveSignature_Basic(t *testing.T) {
+	snapshot := mustParseFixtureDraft(t, `Subject: Remove sig
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+MIME-Version: 1.0
+Content-Type: text/html; charset=UTF-8
+
+<p>Hello</p><div id="sig-rm" class="lark-mail-signature" style="padding-top:6px;padding-bottom:6px"><div>-- My Sig</div></div>`)
+
+	err := Apply(&DraftCtx{FIO: testFIO}, snapshot, Patch{
+		Ops: []PatchOp{{Op: "remove_signature"}},
+	})
+	if err != nil {
+		t.Fatalf("Apply remove_signature: %v", err)
+	}
+
+	html := string(findPart(snapshot.Body, snapshot.PrimaryHTMLPartID).Body)
+	if strings.Contains(html, "My Sig") {
+		t.Error("signature should have been removed")
+	}
+	if strings.Contains(html, "lark-mail-signature") {
+		t.Error("signature wrapper should have been removed")
+	}
+	if !strings.Contains(html, "Hello") {
+		t.Error("body text should be preserved")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// remove_signature — no signature present
+// ---------------------------------------------------------------------------
+
+func TestRemoveSignature_NoSignature(t *testing.T) {
+	snapshot := mustParseFixtureDraft(t, `Subject: No sig
+From: Alice <alice@example.com>
+To: Bob <bob@example.com>
+MIME-Version: 1.0
+Content-Type: text/html; charset=UTF-8
+
+<p>No signature here</p>`)
+
+	err := Apply(&DraftCtx{FIO: testFIO}, snapshot, Patch{
+		Ops: []PatchOp{{Op: "remove_signature"}},
+	})
+	if err == nil {
+		t.Fatal("expected error when removing non-existent signature")
+	}
+	if !strings.Contains(err.Error(), "no signature found") {
+		t.Fatalf("expected 'no signature found' error, got: %v", err)
+	}
+}

shortcuts/mail/draft/projection.go

@@ -4,6 +4,7 @@
 package draft
 
 import (
+	"html"
 	"regexp"
 	"strings"
 )
@@ -27,6 +28,18 @@ var quoteWrapperRe = regexp.MustCompile(`<div\s[^>]*class="[^"]*` + QuoteWrapper
 
 var cidRefRegexp = regexp.MustCompile(`(?i)cid:([^"' >]+)`)
 
+// SignatureWrapperClass is the CSS class for the mail signature container.
+const SignatureWrapperClass = "lark-mail-signature"
+
+var signatureWrapperRe = regexp.MustCompile(
+	`<div\s[^>]*class="[^"]*` + SignatureWrapperClass + `[^"]*"`)
+
+// signatureIDRe extracts the id from a signature wrapper div, regardless of
+// whether id appears before or after the class attribute.
+var signatureIDRe = regexp.MustCompile(
+	`<div\s[^>]*class="[^"]*` + SignatureWrapperClass + `[^"]*"[^>]*id="([^"]*)"` +
+		`|<div\s[^>]*id="([^"]*)"[^>]*class="[^"]*` + SignatureWrapperClass)
+
 func Project(snapshot *DraftSnapshot) DraftProjection {
 	proj := DraftProjection{
 		Subject:    snapshot.Subject,
@@ -45,6 +58,17 @@ func Project(snapshot *DraftSnapshot) DraftProjection {
 		html := string(part.Body)
 		proj.BodyHTMLSummary = summarizeHTML(html)
 		proj.HasQuotedContent = hasQuotedContent(html)
+		proj.HasSignature = signatureWrapperRe.MatchString(html)
+		if proj.HasSignature {
+			if m := signatureIDRe.FindStringSubmatch(html); m != nil {
+				// alternation regex: id is in m[1] (class-first) or m[2] (id-first)
+				if m[1] != "" {
+					proj.SignatureID = m[1]
+				} else if len(m) >= 3 {
+					proj.SignatureID = m[2]
+				}
+			}
+		}
 	}
 
 	parts := flattenParts(snapshot.Body)
@@ -128,10 +152,10 @@ func hasQuotedContent(html string) bool {
 	return quoteWrapperRe.MatchString(html)
 }
 
-// splitAtQuote splits an HTML body into the user-authored content and
+// SplitAtQuote splits an HTML body into the user-authored content and
 // the trailing reply/forward quote block. If no quote block is found,
 // quote is empty and body is the original html unchanged.
-func splitAtQuote(html string) (body, quote string) {
+func SplitAtQuote(html string) (body, quote string) {
 	loc := quoteWrapperRe.FindStringIndex(html)
 	if loc == nil {
 		return html, ""
@@ -139,6 +163,70 @@ func splitAtQuote(html string) (body, quote string) {
 	return html[:loc[0]], html[loc[0]:]
 }
 
+// ── Exported signature HTML utilities ──
+// Used by both draft/patch.go (internal) and mail/signature_html.go (cross-package).
+
+// signatureSpacingRe matches 1-2 empty-line divs before the signature.
+var signatureSpacingRe = regexp.MustCompile(
+	`(?:<div[^>]*><div[^>]*><br></div></div>\s*){1,2}$`)
+
+// SignatureSpacingRe returns the compiled regex for signature spacing detection.
+func SignatureSpacingRe() *regexp.Regexp { return signatureSpacingRe }
+
+// SignatureSpacing returns the 2 empty-line divs placed before the signature,
+// matching the structure generated by the Lark mail editor.
+func SignatureSpacing() string {
+	line := `<div style="margin-top:4px;margin-bottom:4px;line-height:1.6"><div dir="auto"><br></div></div>`
+	return line + line
+}
+
+// BuildSignatureHTML wraps signature content in the standard signature container div.
+// sigID is HTML-escaped to prevent attribute injection.
+func BuildSignatureHTML(sigID, content string) string {
+	return `<div id="` + html.EscapeString(sigID) + `" class="` + SignatureWrapperClass + `" style="padding-top:6px;padding-bottom:6px">` + content + `</div>`
+}
+
+// FindMatchingCloseDiv finds the position after the closing </div> that matches
+// the <div at startPos, tracking nesting depth.
+func FindMatchingCloseDiv(html string, startPos int) int {
+	depth := 0
+	i := startPos
+	for i < len(html) {
+		if strings.HasPrefix(html[i:], "<div") {
+			depth++
+			i += 4
+		} else if strings.HasPrefix(html[i:], "</div>") {
+			depth--
+			i += 6
+			if depth == 0 {
+				return i
+			}
+		} else {
+			i++
+		}
+	}
+	return len(html)
+}
+
+// RemoveSignatureHTML removes the signature block and its preceding spacing from HTML.
+// Returns the HTML unchanged if no signature is found.
+func RemoveSignatureHTML(html string) string {
+	loc := signatureWrapperRe.FindStringIndex(html)
+	if loc == nil {
+		return html
+	}
+	sigStart := loc[0]
+	sigEnd := FindMatchingCloseDiv(html, sigStart)
+
+	// Extend backward to include preceding spacing.
+	beforeSig := html[:sigStart]
+	if spacingLoc := signatureSpacingRe.FindStringIndex(beforeSig); spacingLoc != nil {
+		sigStart = spacingLoc[0]
+	}
+
+	return html[:sigStart] + html[sigEnd:]
+}
+
 func summarizeHTML(html string) string {
 	trimmed := strings.TrimSpace(html)
 	runes := []rune(trimmed)

shortcuts/mail/draft/projection_test.go

@@ -100,7 +100,7 @@ Content-Type: text/html; charset=UTF-8
 
 func TestSplitAtQuoteReply(t *testing.T) {
 	html := `<div>My reply</div><div class="history-quote-wrapper"><div>quoted</div></div>`
-	body, quote := splitAtQuote(html)
+	body, quote := SplitAtQuote(html)
 	if body != `<div>My reply</div>` {
 		t.Fatalf("body = %q", body)
 	}
@@ -111,7 +111,7 @@ func TestSplitAtQuoteReply(t *testing.T) {
 
 func TestSplitAtQuoteForward(t *testing.T) {
 	html := `<div>note</div><div id="lark-mail-quote-cli123456" class="history-quote-wrapper"><div>quoted</div></div>`
-	body, quote := splitAtQuote(html)
+	body, quote := SplitAtQuote(html)
 	if body != `<div>note</div>` {
 		t.Fatalf("body = %q", body)
 	}
@@ -122,7 +122,7 @@ func TestSplitAtQuoteForward(t *testing.T) {
 
 func TestSplitAtQuoteNoQuote(t *testing.T) {
 	html := `<div>no quote here</div>`
-	body, quote := splitAtQuote(html)
+	body, quote := SplitAtQuote(html)
 	if body != html {
 		t.Fatalf("body = %q, want original html", body)
 	}
@@ -169,7 +169,7 @@ Content-Type: text/html; charset=UTF-8
 
 func TestSplitAtQuoteFalsePositivePlainText(t *testing.T) {
 	html := `<p>The CSS class history-quote-wrapper is used for quotes.</p>`
-	body, quote := splitAtQuote(html)
+	body, quote := SplitAtQuote(html)
 	if body != html {
 		t.Fatalf("body should be unchanged, got %q", body)
 	}

shortcuts/mail/helpers.go

@@ -1933,6 +1933,23 @@ func validateConfirmSendScope(runtime *common.RuntimeContext) error {
 	return nil
 }
 
+// buildSendResult builds the output map for a successful send, including
+// recall tip if the backend indicates the message is recallable.
+func buildSendResult(resData map[string]interface{}, mailboxID string) map[string]interface{} {
+	result := map[string]interface{}{
+		"message_id": resData["message_id"],
+		"thread_id":  resData["thread_id"],
+	}
+	if recallStatus, ok := resData["recall_status"].(string); ok && recallStatus == "available" {
+		messageID, _ := resData["message_id"].(string)
+		result["recall_available"] = true
+		result["recall_tip"] = fmt.Sprintf(
+			`This message can be recalled within 24 hours. To recall: lark-cli mail user_mailbox.sent_messages recall --params '{"user_mailbox_id":"%s","message_id":"%s"}'`,
+			mailboxID, messageID)
+	}
+	return result
+}
+
 // validateFolderReadScope checks that the user's token includes the
 // mail:user_mailbox.folder:read scope. Called on-demand by listMailboxFolders
 // before hitting the folders API. System folders are resolved locally and

shortcuts/mail/mail_draft_create.go

@@ -46,6 +46,7 @@ var MailDraftCreate = common.Shortcut{
 		{Name: "plain-text", Type: "bool", Desc: "Force plain-text mode, ignoring HTML auto-detection. Cannot be used with --inline."},
 		{Name: "attach", Desc: "Optional. Regular attachment file paths (relative path only). Separate multiple paths with commas. Each path must point to a readable local file."},
 		{Name: "inline", Desc: "Optional. Inline images as a JSON array. Each entry: {\"cid\":\"<unique-id>\",\"file_path\":\"<relative-path>\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via <img src=\"cid:...\"> in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
+		signatureFlag,
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		input, err := parseDraftCreateInput(runtime)
@@ -72,6 +73,9 @@ var MailDraftCreate = common.Shortcut{
 		if strings.TrimSpace(runtime.Str("body")) == "" {
 			return output.ErrValidation("--body is required; pass the full email body")
 		}
+		if err := validateSignatureWithPlainText(runtime.Bool("plain-text"), runtime.Str("signature-id")); err != nil {
+			return err
+		}
 		if err := validateComposeInlineAndAttachments(runtime.FileIO(), runtime.Str("attach"), runtime.Str("inline"), runtime.Bool("plain-text"), runtime.Str("body")); err != nil {
 			return err
 		}
@@ -82,11 +86,15 @@ var MailDraftCreate = common.Shortcut{
 		if err != nil {
 			return err
 		}
-		rawEML, err := buildRawEMLForDraftCreate(runtime, input)
+		mailboxID := resolveComposeMailboxID(runtime)
+		sigResult, err := resolveSignature(ctx, runtime, mailboxID, runtime.Str("signature-id"), runtime.Str("from"))
+		if err != nil {
+			return err
+		}
+		rawEML, err := buildRawEMLForDraftCreate(runtime, input, sigResult)
 		if err != nil {
 			return err
 		}
-		mailboxID := resolveComposeMailboxID(runtime)
 		draftID, err := draftpkg.CreateWithRaw(runtime, mailboxID, rawEML)
 		if err != nil {
 			return fmt.Errorf("create draft failed: %w", err)
@@ -121,7 +129,7 @@ func parseDraftCreateInput(runtime *common.RuntimeContext) (draftCreateInput, er
 	return input, nil
 }
 
-func buildRawEMLForDraftCreate(runtime *common.RuntimeContext, input draftCreateInput) (string, error) {
+func buildRawEMLForDraftCreate(runtime *common.RuntimeContext, input draftCreateInput, sigResult *signatureResult) (string, error) {
 	senderEmail := resolveComposeSenderEmail(runtime)
 	if senderEmail == "" {
 		return "", fmt.Errorf("unable to determine sender email; please specify --from explicitly")
@@ -153,12 +161,18 @@ func buildRawEMLForDraftCreate(runtime *common.RuntimeContext, input draftCreate
 	var autoResolvedPaths []string
 	if input.PlainText {
 		bld = bld.TextBody([]byte(input.Body))
-	} else if bodyIsHTML(input.Body) {
-		resolved, refs, resolveErr := draftpkg.ResolveLocalImagePaths(input.Body)
+	} else if bodyIsHTML(input.Body) || sigResult != nil {
+		htmlBody := input.Body
+		if !bodyIsHTML(input.Body) {
+			htmlBody = buildBodyDiv(input.Body, false)
+		}
+		resolved, refs, resolveErr := draftpkg.ResolveLocalImagePaths(htmlBody)
 		if resolveErr != nil {
 			return "", resolveErr
 		}
+		resolved = injectSignatureIntoBody(resolved, sigResult)
 		bld = bld.HTMLBody([]byte(resolved))
+		bld = addSignatureImagesToBuilder(bld, sigResult)
 		var allCIDs []string
 		for _, ref := range refs {
 			bld = bld.AddFileInline(ref.FilePath, ref.CID)
@@ -169,6 +183,7 @@ func buildRawEMLForDraftCreate(runtime *common.RuntimeContext, input draftCreate
 			bld = bld.AddFileInline(spec.FilePath, spec.CID)
 			allCIDs = append(allCIDs, spec.CID)
 		}
+		allCIDs = append(allCIDs, signatureCIDs(sigResult)...)
 		if err := validateInlineCIDs(resolved, allCIDs, nil); err != nil {
 			return "", err
 		}

shortcuts/mail/mail_draft_create_test.go

@@ -33,7 +33,7 @@ func TestBuildRawEMLForDraftCreate_ResolvesLocalImages(t *testing.T) {
 		Body:    `<p>Hello</p><p><img src="./test_image.png" /></p>`,
 	}
 
-	rawEML, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input)
+	rawEML, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input, nil)
 	if err != nil {
 		t.Fatalf("buildRawEMLForDraftCreate() error = %v", err)
 	}
@@ -58,7 +58,7 @@ func TestBuildRawEMLForDraftCreate_NoLocalImages(t *testing.T) {
 		Body:    `<p>Hello <b>world</b></p>`,
 	}
 
-	rawEML, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input)
+	rawEML, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input, nil)
 	if err != nil {
 		t.Fatalf("buildRawEMLForDraftCreate() error = %v", err)
 	}
@@ -93,7 +93,7 @@ func TestBuildRawEMLForDraftCreate_AutoResolveCountedInSizeLimit(t *testing.T) {
 		Attach:  "./big.txt",
 	}
 
-	_, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input)
+	_, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input, nil)
 	if err == nil {
 		t.Fatal("expected size limit error when auto-resolved image + attachment exceed 25MB")
 	}
@@ -113,7 +113,7 @@ func TestBuildRawEMLForDraftCreate_OrphanedInlineSpecError(t *testing.T) {
 		Inline:  `[{"cid":"orphan","file_path":"./unused.png"}]`,
 	}
 
-	_, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input)
+	_, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input, nil)
 	if err == nil {
 		t.Fatal("expected error for orphaned --inline CID not referenced in body")
 	}
@@ -133,7 +133,7 @@ func TestBuildRawEMLForDraftCreate_MissingCIDRefError(t *testing.T) {
 		Inline:  `[{"cid":"present","file_path":"./present.png"}]`,
 	}
 
-	_, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input)
+	_, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input, nil)
 	if err == nil {
 		t.Fatal("expected error for missing CID reference")
 	}
@@ -153,7 +153,7 @@ func TestBuildRawEMLForDraftCreate_PlainTextSkipsResolve(t *testing.T) {
 		PlainText: true,
 	}
 
-	rawEML, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input)
+	rawEML, err := buildRawEMLForDraftCreate(newRuntimeWithFrom("sender@example.com"), input, nil)
 	if err != nil {
 		t.Fatalf("buildRawEMLForDraftCreate() error = %v", err)
 	}

shortcuts/mail/mail_draft_edit.go

@@ -92,6 +92,24 @@ var MailDraftEdit = common.Shortcut{
 		if err != nil {
 			return output.ErrValidation("parse draft raw EML failed: %v", err)
 		}
+		// Pre-process insert_signature ops: resolve signature using the draft's
+		// From address so alias/shared-mailbox senders get correct template vars.
+		var draftFromEmail string
+		if len(snapshot.From) > 0 {
+			draftFromEmail = snapshot.From[0].Address
+		}
+		for i := range patch.Ops {
+			if patch.Ops[i].Op == "insert_signature" {
+				sigResult, sigErr := resolveSignature(ctx, runtime, mailboxID, patch.Ops[i].SignatureID, draftFromEmail)
+				if sigErr != nil {
+					return sigErr
+				}
+				if sigResult != nil {
+					patch.Ops[i].RenderedSignatureHTML = sigResult.RenderedContent
+					patch.Ops[i].SignatureImages = sigResult.Images
+				}
+			}
+		}
 		dctx := &draftpkg.DraftCtx{FIO: runtime.FileIO()}
 		if err := draftpkg.Apply(dctx, snapshot, patch); err != nil {
 			return output.ErrValidation("apply draft patch failed: %v", err)
@@ -313,6 +331,8 @@ func buildDraftEditPatchTemplate() map[string]interface{} {
 			{"op": "add_inline", "shape": map[string]interface{}{"path": "string(relative path)", "cid": "string", "filename": "string(optional)", "content_type": "string(optional)"}, "note": "advanced: prefer <img src=\"./path\"> in set_body/set_reply_body instead"},
 			{"op": "replace_inline", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}, "path": "string(relative path)", "cid": "string(optional)", "filename": "string(optional)", "content_type": "string(optional)"}},
 			{"op": "remove_inline", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}}},
+			{"op": "insert_signature", "shape": map[string]interface{}{"signature_id": "string (run mail +signature to list IDs)"}},
+			{"op": "remove_signature", "shape": map[string]interface{}{}, "note": "removes existing signature from the HTML body"},
 		},
 		"supported_ops_by_group": []map[string]interface{}{
 			{
@@ -348,6 +368,13 @@ func buildDraftEditPatchTemplate() map[string]interface{} {
 					{"op": "remove_inline", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}}},
 				},
 			},
+			{
+				"group": "signature",
+				"ops": []map[string]interface{}{
+					{"op": "insert_signature", "shape": map[string]interface{}{"signature_id": "string (run mail +signature to list IDs)"}},
+					{"op": "remove_signature", "shape": map[string]interface{}{}, "note": "removes existing signature and its preceding spacing from the HTML body"},
+				},
+			},
 		},
 		"recommended_usage": []string{
 			"Use direct flags (--set-subject, --set-to, --set-cc, --set-bcc) for simple metadata edits",

shortcuts/mail/mail_forward.go

@@ -34,7 +34,7 @@ var MailForward = common.Shortcut{
 		{Name: "attach", Desc: "Attachment file path(s), comma-separated, appended after original attachments (relative path only)"},
 		{Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"<unique-id>\",\"file_path\":\"<relative-path>\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via <img src=\"cid:...\"> in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
 		{Name: "confirm-send", Type: "bool", Desc: "Send the forward immediately instead of saving as draft. Only use after the user has explicitly confirmed recipients and content."},
-	},
+		signatureFlag},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		messageId := runtime.Str("message-id")
 		to := runtime.Str("to")
@@ -64,6 +64,9 @@ var MailForward = common.Shortcut{
 				return err
 			}
 		}
+		if err := validateSignatureWithPlainText(runtime.Bool("plain-text"), runtime.Str("signature-id")); err != nil {
+			return err
+		}
 		return validateComposeInlineAndAttachments(runtime.FileIO(), runtime.Str("attach"), runtime.Str("inline"), runtime.Bool("plain-text"), "")
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -77,7 +80,12 @@ var MailForward = common.Shortcut{
 		inlineFlag := runtime.Str("inline")
 		confirmSend := runtime.Bool("confirm-send")
 
+		signatureID := runtime.Str("signature-id")
 		mailboxID := resolveComposeMailboxID(runtime)
+		sigResult, sigErr := resolveSignature(ctx, runtime, mailboxID, signatureID, runtime.Str("from"))
+		if sigErr != nil {
+			return sigErr
+		}
 		sourceMsg, err := fetchComposeSourceMessage(runtime, mailboxID, messageId)
 		if err != nil {
 			return fmt.Errorf("failed to fetch original message: %w", err)
@@ -114,7 +122,7 @@ var MailForward = common.Shortcut{
 		if messageId != "" {
 			bld = bld.LMSReplyToMessageID(messageId)
 		}
-		useHTML := !plainText && (bodyIsHTML(body) || bodyIsHTML(orig.bodyRaw))
+		useHTML := !plainText && (bodyIsHTML(body) || bodyIsHTML(orig.bodyRaw) || sigResult != nil)
 		if strings.TrimSpace(inlineFlag) != "" && !useHTML {
 			return fmt.Errorf("--inline requires HTML mode, but neither the new body nor the original message contains HTML")
 		}
@@ -138,8 +146,13 @@ var MailForward = common.Shortcut{
 			if resolveErr != nil {
 				return resolveErr
 			}
-			fullHTML := resolved + forwardQuote
+			bodyWithSig := resolved
+			if sigResult != nil {
+				bodyWithSig += draftpkg.SignatureSpacing() + draftpkg.BuildSignatureHTML(sigResult.ID, sigResult.RenderedContent)
+			}
+			fullHTML := bodyWithSig + forwardQuote
 			bld = bld.HTMLBody([]byte(fullHTML))
+			bld = addSignatureImagesToBuilder(bld, sigResult)
 			var userCIDs []string
 			for _, ref := range refs {
 				bld = bld.AddFileInline(ref.FilePath, ref.CID)
@@ -150,7 +163,7 @@ var MailForward = common.Shortcut{
 				bld = bld.AddFileInline(spec.FilePath, spec.CID)
 				userCIDs = append(userCIDs, spec.CID)
 			}
-			if err := validateInlineCIDs(resolved, userCIDs, srcCIDs); err != nil {
+			if err := validateInlineCIDs(bodyWithSig, append(userCIDs, signatureCIDs(sigResult)...), srcCIDs); err != nil {
 				return err
 			}
 		} else {
@@ -222,10 +235,7 @@ var MailForward = common.Shortcut{
 		if err != nil {
 			return fmt.Errorf("failed to send forward (draft %s created but not sent): %w", draftID, err)
 		}
-		runtime.Out(map[string]interface{}{
-			"message_id": resData["message_id"],
-			"thread_id":  resData["thread_id"],
-		}, nil)
+		runtime.Out(buildSendResult(resData, mailboxID), nil)
 		hintMarkAsRead(runtime, mailboxID, messageId)
 		return nil
 	},

shortcuts/mail/mail_reply.go

@@ -32,7 +32,7 @@ var MailReply = common.Shortcut{
 		{Name: "attach", Desc: "Attachment file path(s), comma-separated (relative path only)"},
 		{Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"<unique-id>\",\"file_path\":\"<relative-path>\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via <img src=\"cid:...\"> in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
 		{Name: "confirm-send", Type: "bool", Desc: "Send the reply immediately instead of saving as draft. Only use after the user has explicitly confirmed recipients and content."},
-	},
+		signatureFlag},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		messageId := runtime.Str("message-id")
 		confirmSend := runtime.Bool("confirm-send")
@@ -56,6 +56,9 @@ var MailReply = common.Shortcut{
 		if err := validateConfirmSendScope(runtime); err != nil {
 			return err
 		}
+		if err := validateSignatureWithPlainText(runtime.Bool("plain-text"), runtime.Str("signature-id")); err != nil {
+			return err
+		}
 		return validateComposeInlineAndAttachments(runtime.FileIO(), runtime.Str("attach"), runtime.Str("inline"), runtime.Bool("plain-text"), "")
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -74,7 +77,12 @@ var MailReply = common.Shortcut{
 			return err
 		}
 
+		signatureID := runtime.Str("signature-id")
 		mailboxID := resolveComposeMailboxID(runtime)
+		sigResult, sigErr := resolveSignature(ctx, runtime, mailboxID, signatureID, runtime.Str("from"))
+		if sigErr != nil {
+			return sigErr
+		}
 		sourceMsg, err := fetchComposeSourceMessage(runtime, mailboxID, messageId)
 		if err != nil {
 			return fmt.Errorf("failed to fetch original message: %w", err)
@@ -92,7 +100,7 @@ var MailReply = common.Shortcut{
 		}
 		replyTo = mergeAddrLists(replyTo, toFlag)
 
-		useHTML := !plainText && (bodyIsHTML(body) || bodyIsHTML(orig.bodyRaw))
+		useHTML := !plainText && (bodyIsHTML(body) || bodyIsHTML(orig.bodyRaw) || sigResult != nil)
 		if strings.TrimSpace(inlineFlag) != "" && !useHTML {
 			return fmt.Errorf("--inline requires HTML mode, but neither the new body nor the original message contains HTML")
 		}
@@ -139,8 +147,13 @@ var MailReply = common.Shortcut{
 			if resolveErr != nil {
 				return resolveErr
 			}
-			fullHTML := resolved + quoted
+			bodyWithSig := resolved
+			if sigResult != nil {
+				bodyWithSig += draftpkg.SignatureSpacing() + draftpkg.BuildSignatureHTML(sigResult.ID, sigResult.RenderedContent)
+			}
+			fullHTML := bodyWithSig + quoted
 			bld = bld.HTMLBody([]byte(fullHTML))
+			bld = addSignatureImagesToBuilder(bld, sigResult)
 			var userCIDs []string
 			for _, ref := range refs {
 				bld = bld.AddFileInline(ref.FilePath, ref.CID)
@@ -151,7 +164,7 @@ var MailReply = common.Shortcut{
 				bld = bld.AddFileInline(spec.FilePath, spec.CID)
 				userCIDs = append(userCIDs, spec.CID)
 			}
-			if err := validateInlineCIDs(resolved, userCIDs, srcCIDs); err != nil {
+			if err := validateInlineCIDs(bodyWithSig, append(userCIDs, signatureCIDs(sigResult)...), srcCIDs); err != nil {
 				return err
 			}
 		} else {
@@ -185,10 +198,7 @@ var MailReply = common.Shortcut{
 		if err != nil {
 			return fmt.Errorf("failed to send reply (draft %s created but not sent): %w", draftID, err)
 		}
-		runtime.Out(map[string]interface{}{
-			"message_id": resData["message_id"],
-			"thread_id":  resData["thread_id"],
-		}, nil)
+		runtime.Out(buildSendResult(resData, mailboxID), nil)
 		hintMarkAsRead(runtime, mailboxID, messageId)
 		return nil
 	},

shortcuts/mail/mail_reply_all.go

@@ -33,7 +33,7 @@ var MailReplyAll = common.Shortcut{
 		{Name: "attach", Desc: "Attachment file path(s), comma-separated (relative path only)"},
 		{Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"<unique-id>\",\"file_path\":\"<relative-path>\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via <img src=\"cid:...\"> in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
 		{Name: "confirm-send", Type: "bool", Desc: "Send the reply immediately instead of saving as draft. Only use after the user has explicitly confirmed recipients and content."},
-	},
+		signatureFlag},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		messageId := runtime.Str("message-id")
 		confirmSend := runtime.Bool("confirm-send")
@@ -57,6 +57,9 @@ var MailReplyAll = common.Shortcut{
 		if err := validateConfirmSendScope(runtime); err != nil {
 			return err
 		}
+		if err := validateSignatureWithPlainText(runtime.Bool("plain-text"), runtime.Str("signature-id")); err != nil {
+			return err
+		}
 		return validateComposeInlineAndAttachments(runtime.FileIO(), runtime.Str("attach"), runtime.Str("inline"), runtime.Bool("plain-text"), "")
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -76,7 +79,12 @@ var MailReplyAll = common.Shortcut{
 			return err
 		}
 
+		signatureID := runtime.Str("signature-id")
 		mailboxID := resolveComposeMailboxID(runtime)
+		sigResult, sigErr := resolveSignature(ctx, runtime, mailboxID, signatureID, runtime.Str("from"))
+		if sigErr != nil {
+			return sigErr
+		}
 		sourceMsg, err := fetchComposeSourceMessage(runtime, mailboxID, messageId)
 		if err != nil {
 			return fmt.Errorf("failed to fetch original message: %w", err)
@@ -110,7 +118,7 @@ var MailReplyAll = common.Shortcut{
 			return err
 		}
 
-		useHTML := !plainText && (bodyIsHTML(body) || bodyIsHTML(orig.bodyRaw))
+		useHTML := !plainText && (bodyIsHTML(body) || bodyIsHTML(orig.bodyRaw) || sigResult != nil)
 		if strings.TrimSpace(inlineFlag) != "" && !useHTML {
 			return fmt.Errorf("--inline requires HTML mode, but neither the new body nor the original message contains HTML")
 		}
@@ -153,8 +161,13 @@ var MailReplyAll = common.Shortcut{
 			if resolveErr != nil {
 				return resolveErr
 			}
-			fullHTML := resolved + quoted
+			bodyWithSig := resolved
+			if sigResult != nil {
+				bodyWithSig += draftpkg.SignatureSpacing() + draftpkg.BuildSignatureHTML(sigResult.ID, sigResult.RenderedContent)
+			}
+			fullHTML := bodyWithSig + quoted
 			bld = bld.HTMLBody([]byte(fullHTML))
+			bld = addSignatureImagesToBuilder(bld, sigResult)
 			var userCIDs []string
 			for _, ref := range refs {
 				bld = bld.AddFileInline(ref.FilePath, ref.CID)
@@ -165,7 +178,7 @@ var MailReplyAll = common.Shortcut{
 				bld = bld.AddFileInline(spec.FilePath, spec.CID)
 				userCIDs = append(userCIDs, spec.CID)
 			}
-			if err := validateInlineCIDs(resolved, userCIDs, srcCIDs); err != nil {
+			if err := validateInlineCIDs(bodyWithSig, append(userCIDs, signatureCIDs(sigResult)...), srcCIDs); err != nil {
 				return err
 			}
 		} else {
@@ -199,10 +212,7 @@ var MailReplyAll = common.Shortcut{
 		if err != nil {
 			return fmt.Errorf("failed to send reply-all (draft %s created but not sent): %w", draftID, err)
 		}
-		runtime.Out(map[string]interface{}{
-			"message_id": resData["message_id"],
-			"thread_id":  resData["thread_id"],
-		}, nil)
+		runtime.Out(buildSendResult(resData, mailboxID), nil)
 		hintMarkAsRead(runtime, mailboxID, messageId)
 		return nil
 	},

shortcuts/mail/mail_send.go

@@ -32,7 +32,7 @@ var MailSend = common.Shortcut{
 		{Name: "attach", Desc: "Attachment file path(s), comma-separated (relative path only)"},
 		{Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"<unique-id>\",\"file_path\":\"<relative-path>\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via <img src=\"cid:...\"> in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
 		{Name: "confirm-send", Type: "bool", Desc: "Send the email immediately instead of saving as draft. Only use after the user has explicitly confirmed recipients and content."},
-	},
+		signatureFlag},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		to := runtime.Str("to")
 		subject := runtime.Str("subject")
@@ -62,6 +62,9 @@ var MailSend = common.Shortcut{
 		if err := validateComposeHasAtLeastOneRecipient(runtime.Str("to"), runtime.Str("cc"), runtime.Str("bcc")); err != nil {
 			return err
 		}
+		if err := validateSignatureWithPlainText(runtime.Bool("plain-text"), runtime.Str("signature-id")); err != nil {
+			return err
+		}
 		return validateComposeInlineAndAttachments(runtime.FileIO(), runtime.Str("attach"), runtime.Str("inline"), runtime.Bool("plain-text"), runtime.Str("body"))
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -76,6 +79,13 @@ var MailSend = common.Shortcut{
 		confirmSend := runtime.Bool("confirm-send")
 
 		senderEmail := resolveComposeSenderEmail(runtime)
+		signatureID := runtime.Str("signature-id")
+
+		mailboxID := resolveComposeMailboxID(runtime)
+		sigResult, err := resolveSignature(ctx, runtime, mailboxID, signatureID, senderEmail)
+		if err != nil {
+			return err
+		}
 
 		bld := emlbuilder.New().WithFileIO(runtime.FileIO()).
 			Subject(subject).
@@ -96,12 +106,19 @@ var MailSend = common.Shortcut{
 		var autoResolvedPaths []string
 		if plainText {
 			bld = bld.TextBody([]byte(body))
-		} else if bodyIsHTML(body) {
-			resolved, refs, resolveErr := draftpkg.ResolveLocalImagePaths(body)
+		} else if bodyIsHTML(body) || sigResult != nil {
+			// If signature is requested on plain-text body, auto-upgrade to HTML.
+			htmlBody := body
+			if !bodyIsHTML(body) {
+				htmlBody = buildBodyDiv(body, false)
+			}
+			resolved, refs, resolveErr := draftpkg.ResolveLocalImagePaths(htmlBody)
 			if resolveErr != nil {
 				return resolveErr
 			}
+			resolved = injectSignatureIntoBody(resolved, sigResult)
 			bld = bld.HTMLBody([]byte(resolved))
+			bld = addSignatureImagesToBuilder(bld, sigResult)
 			var allCIDs []string
 			for _, ref := range refs {
 				bld = bld.AddFileInline(ref.FilePath, ref.CID)
@@ -112,6 +129,7 @@ var MailSend = common.Shortcut{
 				bld = bld.AddFileInline(spec.FilePath, spec.CID)
 				allCIDs = append(allCIDs, spec.CID)
 			}
+			allCIDs = append(allCIDs, signatureCIDs(sigResult)...)
 			if err := validateInlineCIDs(resolved, allCIDs, nil); err != nil {
 				return err
 			}
@@ -132,7 +150,6 @@ var MailSend = common.Shortcut{
 			return fmt.Errorf("failed to build EML: %w", err)
 		}
 
-		mailboxID := resolveComposeMailboxID(runtime)
 		draftID, err := draftpkg.CreateWithRaw(runtime, mailboxID, rawEML)
 		if err != nil {
 			return fmt.Errorf("failed to create draft: %w", err)
@@ -149,10 +166,7 @@ var MailSend = common.Shortcut{
 		if err != nil {
 			return fmt.Errorf("failed to send email (draft %s created but not sent): %w", draftID, err)
 		}
-		runtime.Out(map[string]interface{}{
-			"message_id": resData["message_id"],
-			"thread_id":  resData["thread_id"],
-		}, nil)
+		runtime.Out(buildSendResult(resData, mailboxID), nil)
 		return nil
 	},
 }

shortcuts/mail/mail_signature.go

@@ -0,0 +1,216 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"context"
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/larksuite/cli/shortcuts/mail/signature"
+)
+
+var MailSignature = common.Shortcut{
+	Service:     "mail",
+	Command:     "+signature",
+	Description: "List or view email signatures with default usage info.",
+	Risk:        "read",
+	Scopes:      []string{"mail:user_mailbox:readonly"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "from", Default: "me", Desc: "Mailbox address (default: me)"},
+		{Name: "detail", Desc: "Signature ID to view rendered details. Omit to list all signatures."},
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		mailboxID := runtime.Str("from")
+		if mailboxID == "" {
+			mailboxID = "me"
+		}
+		return common.NewDryRunAPI().
+			Desc("List or view email signatures").
+			GET(mailboxPath(mailboxID, "signatures"))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		mailboxID := runtime.Str("from")
+		if mailboxID == "" {
+			mailboxID = "me"
+		}
+		detailID := runtime.Str("detail")
+
+		resp, err := signature.ListAll(runtime, mailboxID)
+		if err != nil {
+			return err
+		}
+
+		if detailID != "" {
+			return executeSignatureDetail(runtime, resp, detailID, mailboxID)
+		}
+		return executeSignatureList(runtime, resp)
+	},
+}
+
+func executeSignatureList(runtime *common.RuntimeContext, resp *signature.GetSignaturesResponse) error {
+	// Build default signature ID maps from usages.
+	sendDefaults := map[string]bool{}
+	replyDefaults := map[string]bool{}
+	for _, usage := range resp.Usages {
+		if usage.SendMailSignatureID != "" && usage.SendMailSignatureID != "0" {
+			sendDefaults[usage.SendMailSignatureID] = true
+		}
+		if usage.ReplySignatureID != "" && usage.ReplySignatureID != "0" {
+			replyDefaults[usage.ReplySignatureID] = true
+		}
+	}
+
+	lang := resolveLang(runtime)
+	items := make([]map[string]interface{}, 0, len(resp.Signatures))
+	for _, sig := range resp.Signatures {
+		item := map[string]interface{}{
+			"id":   sig.ID,
+			"name": sig.Name,
+			"type": string(sig.SignatureType),
+		}
+		if len(sig.Images) > 0 {
+			item["images"] = len(sig.Images)
+		}
+
+		// Short content preview (rendered for TENANT).
+		rendered := signature.InterpolateTemplate(&sig, lang, "", "")
+		item["content_preview"] = contentPreview(rendered, 200, lang)
+
+		if sendDefaults[sig.ID] {
+			item["is_send_default"] = true
+		}
+		if replyDefaults[sig.ID] {
+			item["is_reply_default"] = true
+		}
+
+		items = append(items, item)
+	}
+
+	runtime.OutFormat(
+		map[string]interface{}{"signatures": items},
+		&output.Meta{Count: len(items)},
+		nil,
+	)
+	return nil
+}
+
+func executeSignatureDetail(runtime *common.RuntimeContext, resp *signature.GetSignaturesResponse, sigID, mailboxID string) error {
+	var sig *signature.Signature
+	for i := range resp.Signatures {
+		if resp.Signatures[i].ID == sigID {
+			sig = &resp.Signatures[i]
+			break
+		}
+	}
+	if sig == nil {
+		return output.ErrValidation("signature not found: %s", sigID)
+	}
+
+	lang := resolveLang(runtime)
+
+	detail := map[string]interface{}{
+		"id":   sig.ID,
+		"name": sig.Name,
+		"type": string(sig.SignatureType),
+	}
+
+	// Usage info.
+	for _, usage := range resp.Usages {
+		if usage.SendMailSignatureID == sig.ID {
+			detail["is_send_default"] = true
+		}
+		if usage.ReplySignatureID == sig.ID {
+			detail["is_reply_default"] = true
+		}
+	}
+
+	// Images metadata — output the full structure from API.
+	if len(sig.Images) > 0 {
+		detail["images"] = sig.Images
+	}
+
+	// Template variables (TENANT signatures): show resolved values.
+	if sig.HasTemplateVars() {
+		vars := make(map[string]string, len(sig.UserFields))
+		for key, field := range sig.UserFields {
+			vars[key] = field.Resolve(lang)
+		}
+		detail["template_vars"] = vars
+	}
+
+	// Rendered content preview.
+	rendered := signature.InterpolateTemplate(sig, lang, "", "")
+	detail["content_preview"] = contentPreview(rendered, 200, lang)
+
+	runtime.Out(detail, nil)
+	return nil
+}
+
+// resolveLang maps CLI config lang ("zh"/"en") to i18n key ("zh_cn"/"en_us").
+func resolveLang(runtime *common.RuntimeContext) string {
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		return "zh_cn"
+	}
+	cfg, err := runtime.Factory.Config()
+	if err != nil {
+		return "zh_cn"
+	}
+	app := multi.FindApp(cfg.ProfileName)
+	if app == nil {
+		return "zh_cn"
+	}
+	switch app.Lang {
+	case "en":
+		return "en_us"
+	case "ja":
+		return "ja_jp"
+	default:
+		return "zh_cn"
+	}
+}
+
+// contentPreview converts HTML to a compact plain-text preview.
+// <img> tags become a localized image placeholder, all other tags become
+// spaces, then consecutive whitespace is collapsed. Result is truncated
+// to maxLen runes.
+func contentPreview(html string, maxLen int, lang string) string {
+	placeholder := "[image]"
+	if strings.HasPrefix(lang, "zh") {
+		placeholder = "[图片]"
+	}
+	imgRe := regexp.MustCompile(`<img[^>]*>`)
+	s := imgRe.ReplaceAllString(html, placeholder)
+
+	// Strip remaining tags, replacing each with a space.
+	var result strings.Builder
+	inTag := false
+	for _, r := range s {
+		switch {
+		case r == '<':
+			inTag = true
+			result.WriteByte(' ')
+		case r == '>':
+			inTag = false
+		case !inTag:
+			result.WriteRune(r)
+		}
+	}
+
+	// Collapse whitespace and trim.
+	text := strings.Join(strings.Fields(result.String()), " ")
+	text = strings.TrimSpace(text)
+
+	runes := []rune(text)
+	if len(runes) <= maxLen {
+		return text
+	}
+	return string(runes[:maxLen]) + "..."
+}

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"},
@@ -192,36 +192,23 @@ var MailWatch = common.Shortcut{
 		msgFormat := runtime.Str("msg-format")
 		outputDir := runtime.Str("output-dir")
 		if outputDir != "" {
-			if outputDir == "~" || strings.HasPrefix(outputDir, "~/") {
-				home, err := vfs.UserHomeDir()
-				if err != nil {
-					return fmt.Errorf("cannot expand ~: %w", err)
-				}
-				if outputDir == "~" {
-					outputDir = home
-				} else {
-					outputDir = filepath.Join(home, outputDir[2:])
-				}
-			} else if filepath.IsAbs(outputDir) {
-				outputDir = filepath.Clean(outputDir)
-			} else {
-				safePath, err := validate.SafeOutputPath(outputDir)
-				if err != nil {
-					return err
-				}
-				outputDir = safePath
+			// Reject all tilde-prefixed paths — SafeOutputPath treats "~/x" as a
+			// literal relative path (creating a directory named "~"), which is
+			// confusing. This also covers ~user/path forms.
+			if strings.HasPrefix(outputDir, "~") {
+				return output.ErrValidation("--output-dir does not support ~ expansion; use a relative path like ./output instead")
 			}
-			// Resolve symlinks on the output directory so all writes use the real
-			// filesystem path. This prevents a symlink from redirecting writes to
-			// an unintended location (TOCTOU mitigation).
+			// Enforce CWD containment: reject absolute paths, path traversal,
+			// and symlink escapes. SafeOutputPath returns a resolved absolute path
+			// under CWD, preventing writes to arbitrary system directories.
+			safePath, err := validate.SafeOutputPath(outputDir)
+			if err != nil {
+				return err
+			}
+			outputDir = safePath
 			if err := vfs.MkdirAll(outputDir, 0700); err != nil {
 				return fmt.Errorf("cannot create output directory %q: %w", outputDir, err)
 			}
-			resolved, err := filepath.EvalSymlinks(outputDir)
-			if err != nil {
-				return fmt.Errorf("cannot resolve output directory: %w", err)
-			}
-			outputDir = resolved
 		}
 		labelIDsInput := runtime.Str("label-ids")
 		folderIDsInput := runtime.Str("folder-ids")

shortcuts/mail/shortcuts.go

@@ -19,5 +19,6 @@ func Shortcuts() []common.Shortcut {
 		MailDraftCreate,
 		MailDraftEdit,
 		MailForward,
+		MailSignature,
 	}
 }

shortcuts/mail/signature/interpolate.go

@@ -0,0 +1,157 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package signature
+
+import (
+	"encoding/json"
+	"regexp"
+	"strings"
+)
+
+// variableMetaProps represents the JSON structure in data-variable-meta-props attributes.
+type variableMetaProps struct {
+	ID          string `json:"id"`
+	Type        string `json:"type"`        // "text" or "image"
+	DisplayName string `json:"displayName"` // human-readable label
+	Width       string `json:"width"`       // image width (for type=image)
+	Style       string `json:"style"`       // CSS style
+	Circle      bool   `json:"circle"`      // circular image
+}
+
+// variableSpanRe matches <span data-variable-meta-props='...'> and captures the JSON and inner content.
+// Group 1: JSON attribute value (double-quoted), Group 2: (single-quoted), Group 3: inner content.
+//
+// Limitation: uses regex instead of DOM parsing (Go has no built-in DOMParser like JS).
+// If a variable <span> contains nested <span> tags, [\s\S]*? will match to the
+// innermost </span>, potentially truncating content. In practice, Lark's signature
+// templates do not nest <span> inside variable spans (verified against mail-editor
+// source and test data). If this becomes an issue, consider using golang.org/x/net/html.
+var variableSpanRe = regexp.MustCompile(
+	`<span\s+data-variable-meta-props=(?:"([^"]*?)"|'([^']*?)')>([\s\S]*?)</span>`)
+
+// InterpolateTemplate replaces template variables in a TENANT signature's content HTML.
+// For USER signatures (no template variables), it returns sig.Content unchanged.
+//
+// Parameters:
+//   - sig: the signature object
+//   - lang: language code for i18n ("zh_cn", "en_us", "ja_jp")
+//   - senderName: sender display name (overrides B-NAME)
+//   - senderEmail: sender email address (overrides B-ENTERPRISE-EMAIL)
+func InterpolateTemplate(sig *Signature, lang, senderName, senderEmail string) string {
+	if !sig.HasTemplateVars() {
+		return sig.Content
+	}
+
+	// Build value map from user_fields with i18n resolution.
+	valueMap := make(map[string]string, len(sig.UserFields)+2)
+	for key, field := range sig.UserFields {
+		valueMap[key] = field.Resolve(lang)
+	}
+
+	// Fixed injections override API values.
+	if senderName != "" {
+		valueMap["B-NAME"] = senderName
+	}
+	if senderEmail != "" {
+		valueMap["B-ENTERPRISE-EMAIL"] = senderEmail
+	}
+
+	// Replace each <span data-variable-meta-props='...'> with interpolated content.
+	result := variableSpanRe.ReplaceAllStringFunc(sig.Content, func(match string) string {
+		submatches := variableSpanRe.FindStringSubmatch(match)
+		if submatches == nil {
+			return match
+		}
+
+		// JSON is in group 1 (double-quoted) or group 2 (single-quoted).
+		attrJSON := submatches[1]
+		if attrJSON == "" {
+			attrJSON = submatches[2]
+		}
+
+		// Unescape HTML entities in the JSON attribute value.
+		attrJSON = unescapeHTMLEntities(attrJSON)
+
+		var meta variableMetaProps
+		if err := json.Unmarshal([]byte(attrJSON), &meta); err != nil {
+			return match // preserve original on parse failure
+		}
+
+		val, ok := valueMap[meta.ID]
+		if !ok {
+			val = "" // variable not in map, replace with empty
+		}
+
+		switch meta.Type {
+		case "text":
+			return interpolateText(val, meta.Style)
+		case "image":
+			return interpolateImage(val, meta)
+		default:
+			return val
+		}
+	})
+
+	return result
+}
+
+// interpolateText returns the replacement for a text variable.
+func interpolateText(val, style string) string {
+	if val == "" {
+		return ""
+	}
+	// If value looks like a URL, wrap in <a>.
+	if isURL(val) {
+		escaped := escapeHTML(val)
+		return `<a href="` + escaped + `" target="_blank" rel="noopener noreferrer">` + escaped + `</a>`
+	}
+	if style != "" {
+		return `<span style="` + escapeHTML(style) + `">` + escapeHTML(val) + `</span>`
+	}
+	return escapeHTML(val)
+}
+
+// interpolateImage returns the replacement for an image variable.
+func interpolateImage(val string, meta variableMetaProps) string {
+	if val == "" {
+		return ""
+	}
+	var attrs []string
+	attrs = append(attrs, `src="`+escapeHTML(val)+`"`)
+	if meta.Width != "" {
+		attrs = append(attrs, `width="`+escapeHTML(meta.Width)+`"`)
+	}
+	var styles []string
+	if meta.Style != "" {
+		styles = append(styles, meta.Style)
+	}
+	if meta.Circle {
+		styles = append(styles, "border-radius: 100%")
+	}
+	if len(styles) > 0 {
+		attrs = append(attrs, `style="`+escapeHTML(strings.Join(styles, ";"))+`"`)
+	}
+	return `<img ` + strings.Join(attrs, " ") + `>`
+}
+
+func isURL(s string) bool {
+	s = strings.TrimSpace(s)
+	return strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://")
+}
+
+func escapeHTML(s string) string {
+	s = strings.ReplaceAll(s, "&", "&amp;")
+	s = strings.ReplaceAll(s, "<", "&lt;")
+	s = strings.ReplaceAll(s, ">", "&gt;")
+	s = strings.ReplaceAll(s, `"`, "&quot;")
+	return s
+}
+
+func unescapeHTMLEntities(s string) string {
+	s = strings.ReplaceAll(s, "&quot;", `"`)
+	s = strings.ReplaceAll(s, "&amp;", "&")
+	s = strings.ReplaceAll(s, "&lt;", "<")
+	s = strings.ReplaceAll(s, "&gt;", ">")
+	return s
+}

shortcuts/mail/signature/interpolate_test.go

@@ -0,0 +1,137 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package signature
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestInterpolateTemplate_UserSignatureUnchanged(t *testing.T) {
+	sig := &Signature{
+		Content:       "<b>My signature</b>",
+		SignatureType: SignatureTypeUser,
+	}
+	got := InterpolateTemplate(sig, "zh_cn", "Alice", "alice@example.com")
+	if got != sig.Content {
+		t.Errorf("USER signature should be unchanged, got %q", got)
+	}
+}
+
+func TestInterpolateTemplate_TenantTextVariables(t *testing.T) {
+	sig := &Signature{
+		Content:          `姓名：<span data-variable-meta-props='{"id":"B-NAME","type":"text"}'>{text}</span>, 部门：<span data-variable-meta-props='{"id":"B-DEPARTMENT","type":"text"}'>{text}</span>`,
+		SignatureType:    SignatureTypeTenant,
+		TemplateJSONKeys: []string{"B-NAME", "B-DEPARTMENT"},
+		UserFields: map[string]UserFieldValue{
+			"B-NAME":       {DefaultVal: "张三", I18nVals: map[string]string{"zh_cn": "", "en_us": "Zhang San"}},
+			"B-DEPARTMENT": {DefaultVal: "默认部门", I18nVals: map[string]string{"zh_cn": "研发部", "en_us": "R&D"}},
+		},
+	}
+
+	// zh_cn: B-DEPARTMENT should resolve to "研发部" (from i18n), B-NAME overridden by senderName
+	got := InterpolateTemplate(sig, "zh_cn", "李四", "lisi@example.com")
+	if !strings.Contains(got, "李四") {
+		t.Errorf("expected senderName override for B-NAME, got %q", got)
+	}
+	if !strings.Contains(got, "研发部") {
+		t.Errorf("expected zh_cn i18n value for B-DEPARTMENT, got %q", got)
+	}
+	if strings.Contains(got, "{text}") {
+		t.Errorf("should not contain raw placeholder {text}, got %q", got)
+	}
+	if strings.Contains(got, "data-variable-meta-props") {
+		t.Errorf("should not contain data-variable-meta-props attribute, got %q", got)
+	}
+}
+
+func TestInterpolateTemplate_I18nFallback(t *testing.T) {
+	sig := &Signature{
+		Content:          `<span data-variable-meta-props='{"id":"B-DEPARTMENT","type":"text"}'>{text}</span>`,
+		SignatureType:    SignatureTypeTenant,
+		TemplateJSONKeys: []string{"B-DEPARTMENT"},
+		UserFields: map[string]UserFieldValue{
+			"B-DEPARTMENT": {DefaultVal: "默认部门", I18nVals: map[string]string{"zh_cn": "", "en_us": ""}},
+		},
+	}
+
+	got := InterpolateTemplate(sig, "zh_cn", "", "")
+	if !strings.Contains(got, "默认部门") {
+		t.Errorf("expected fallback to DefaultVal, got %q", got)
+	}
+}
+
+func TestInterpolateTemplate_HTMLEntityEscaping(t *testing.T) {
+	// Simulate the HTML-entity-escaped attribute format from real API responses.
+	sig := &Signature{
+		Content:          `<span data-variable-meta-props="{&quot;id&quot;:&quot;B-NAME&quot;,&quot;type&quot;:&quot;text&quot;}">{text}</span>`,
+		SignatureType:    SignatureTypeTenant,
+		TemplateJSONKeys: []string{"B-NAME"},
+		UserFields: map[string]UserFieldValue{
+			"B-NAME": {DefaultVal: "default"},
+		},
+	}
+
+	got := InterpolateTemplate(sig, "zh_cn", "陈煌", "")
+	if !strings.Contains(got, "陈煌") {
+		t.Errorf("expected interpolated name, got %q", got)
+	}
+}
+
+func TestInterpolateTemplate_URLAsText(t *testing.T) {
+	sig := &Signature{
+		Content:          `<span data-variable-meta-props='{"id":"B-URL","type":"text"}'>{text}</span>`,
+		SignatureType:    SignatureTypeTenant,
+		TemplateJSONKeys: []string{"B-URL"},
+		UserFields: map[string]UserFieldValue{
+			"B-URL": {DefaultVal: "https://example.com"},
+		},
+	}
+
+	got := InterpolateTemplate(sig, "zh_cn", "", "")
+	if !strings.Contains(got, "<a href=") {
+		t.Errorf("expected URL to be wrapped in <a> tag, got %q", got)
+	}
+	if !strings.Contains(got, "https://example.com") {
+		t.Errorf("expected URL in output, got %q", got)
+	}
+}
+
+func TestInterpolateTemplate_ImageVariable(t *testing.T) {
+	sig := &Signature{
+		Content:          `<span data-variable-meta-props='{"id":"B-LOGO","type":"image","width":"40"}'><img src="cid:old"/></span>`,
+		SignatureType:    SignatureTypeTenant,
+		TemplateJSONKeys: []string{"B-LOGO"},
+		UserFields: map[string]UserFieldValue{
+			"B-LOGO": {DefaultVal: "cid:new-logo-cid"},
+		},
+	}
+
+	got := InterpolateTemplate(sig, "zh_cn", "", "")
+	if !strings.Contains(got, `src="cid:new-logo-cid"`) {
+		t.Errorf("expected new image src, got %q", got)
+	}
+	if !strings.Contains(got, `width="40"`) {
+		t.Errorf("expected width attribute, got %q", got)
+	}
+}
+
+func TestUserFieldValue_Resolve(t *testing.T) {
+	v := UserFieldValue{
+		DefaultVal: "default",
+		I18nVals:   map[string]string{"zh_cn": "中文", "en_us": "", "ja_jp": "日本語"},
+	}
+	if got := v.Resolve("zh_cn"); got != "中文" {
+		t.Errorf("zh_cn = %q, want 中文", got)
+	}
+	if got := v.Resolve("en_us"); got != "default" {
+		t.Errorf("en_us (empty) should fallback to default, got %q", got)
+	}
+	if got := v.Resolve("ja_jp"); got != "日本語" {
+		t.Errorf("ja_jp = %q, want 日本語", got)
+	}
+	if got := v.Resolve("fr_fr"); got != "default" {
+		t.Errorf("unknown lang should fallback, got %q", got)
+	}
+}

shortcuts/mail/signature/model.go

@@ -0,0 +1,82 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package signature
+
+// SignatureType represents the type of a mail signature.
+type SignatureType string
+
+const (
+	SignatureTypeUser   SignatureType = "USER"
+	SignatureTypeTenant SignatureType = "TENANT"
+)
+
+// SignatureDevice represents the device platform a signature is designed for.
+type SignatureDevice string
+
+const (
+	DevicePC     SignatureDevice = "PC"
+	DeviceMobile SignatureDevice = "MOBILE"
+)
+
+// SignatureImage holds metadata for an inline image embedded in a signature.
+type SignatureImage struct {
+	ImageName   string `json:"image_name,omitempty"`
+	FileKey     string `json:"file_key,omitempty"`
+	CID         string `json:"cid,omitempty"`
+	FileSize    string `json:"file_size,omitempty"`
+	Header      string `json:"header,omitempty"`
+	ImageWidth  int32  `json:"image_width,omitempty"`
+	ImageHeight int32  `json:"image_height,omitempty"`
+	DownloadURL string `json:"download_url,omitempty"`
+}
+
+// UserFieldValue holds a template variable value with multi-language support.
+type UserFieldValue struct {
+	DefaultVal string            `json:"default_val"`
+	I18nVals   map[string]string `json:"i18n_vals"` // keys: "zh_cn", "en_us", "ja_jp"
+}
+
+// Resolve returns the localized value for the given language code.
+// Falls back to DefaultVal when the language key is missing or empty.
+func (v UserFieldValue) Resolve(lang string) string {
+	if val, ok := v.I18nVals[lang]; ok && val != "" {
+		return val
+	}
+	return v.DefaultVal
+}
+
+// Signature represents a single mail signature returned by the API.
+type Signature struct {
+	ID               string                    `json:"id"`
+	Name             string                    `json:"name"`
+	SignatureType    SignatureType             `json:"signature_type"`
+	SignatureDevice  SignatureDevice           `json:"signature_device"`
+	Content          string                    `json:"content"`
+	Images           []SignatureImage          `json:"images,omitempty"`
+	TemplateJSONKeys []string                  `json:"template_json_keys,omitempty"`
+	UserFields       map[string]UserFieldValue `json:"user_fields,omitempty"`
+}
+
+// IsTenant returns true if this is a tenant/corporate signature with template variables.
+func (s *Signature) IsTenant() bool {
+	return s.SignatureType == SignatureTypeTenant
+}
+
+// HasTemplateVars returns true if the signature contains template variables that need interpolation.
+func (s *Signature) HasTemplateVars() bool {
+	return len(s.TemplateJSONKeys) > 0
+}
+
+// SignatureUsage indicates which signature is used by default for a given email address.
+type SignatureUsage struct {
+	EmailAddress        string `json:"email_address"`
+	SendMailSignatureID string `json:"send_mail_signature_id"`
+	ReplySignatureID    string `json:"reply_signature_id"`
+}
+
+// GetSignaturesResponse is the parsed response from the get_signatures API.
+type GetSignaturesResponse struct {
+	Signatures []Signature      `json:"signatures"`
+	Usages     []SignatureUsage `json:"usages"`
+}

shortcuts/mail/signature/provider.go

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package signature
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// processCache holds per-mailbox cached responses.
+// CLI runs one command per process, so a package-level map is sufficient —
+// it is naturally scoped to a single Execute lifecycle.
+var processCache = map[string]*GetSignaturesResponse{}
+
+func signaturesPath(mailboxID string) string {
+	return "/open-apis/mail/v1/user_mailboxes/" + url.PathEscape(mailboxID) + "/settings/signatures"
+}
+
+// ListAll fetches all signatures and usage info for a mailbox.
+// Results are cached per mailboxID within the current Execute lifecycle.
+func ListAll(runtime *common.RuntimeContext, mailboxID string) (*GetSignaturesResponse, error) {
+	if cached, ok := processCache[mailboxID]; ok {
+		return cached, nil
+	}
+
+	data, err := runtime.CallAPI("GET", signaturesPath(mailboxID), nil, nil)
+	if err != nil {
+		return nil, fmt.Errorf("get signatures: %w", err)
+	}
+
+	raw, err := json.Marshal(data)
+	if err != nil {
+		return nil, fmt.Errorf("get signatures: marshal response: %w", err)
+	}
+
+	var resp GetSignaturesResponse
+	if err := json.Unmarshal(raw, &resp); err != nil {
+		return nil, fmt.Errorf("get signatures: unmarshal response: %w", err)
+	}
+
+	processCache[mailboxID] = &resp
+	return &resp, nil
+}
+
+// List returns all signatures for a mailbox.
+func List(runtime *common.RuntimeContext, mailboxID string) ([]Signature, error) {
+	resp, err := ListAll(runtime, mailboxID)
+	if err != nil {
+		return nil, err
+	}
+	return resp.Signatures, nil
+}
+
+// Get returns a single signature by ID. Returns an error if not found.
+func Get(runtime *common.RuntimeContext, mailboxID, signatureID string) (*Signature, error) {
+	resp, err := ListAll(runtime, mailboxID)
+	if err != nil {
+		return nil, err
+	}
+	for i := range resp.Signatures {
+		if resp.Signatures[i].ID == signatureID {
+			return &resp.Signatures[i], nil
+		}
+	}
+	return nil, fmt.Errorf("signature not found: %s", signatureID)
+}

shortcuts/mail/signature_compose.go

@@ -0,0 +1,245 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/shortcuts/common"
+	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
+	"github.com/larksuite/cli/shortcuts/mail/emlbuilder"
+	"github.com/larksuite/cli/shortcuts/mail/signature"
+)
+
+// signatureFlag is the common flag definition for --signature-id, shared by all compose shortcuts.
+var signatureFlag = common.Flag{
+	Name: "signature-id",
+	Desc: "Optional. Signature ID to append after body content. Run `mail +signature` to list available signatures.",
+}
+
+// signatureResult holds the pre-processed signature data ready for HTML injection.
+type signatureResult struct {
+	ID              string
+	RenderedContent string
+	Images          []draftpkg.SignatureImage
+}
+
+// resolveSignature fetches, interpolates, and downloads images for a signature.
+// Returns nil if signatureID is empty.
+// resolveSignature fetches, interpolates, and downloads images for a signature.
+// fromEmail is the --from address (may be an alias); used to match the correct
+// sender identity for template interpolation. Pass "" to use the primary address.
+func resolveSignature(ctx context.Context, runtime *common.RuntimeContext, mailboxID, signatureID, fromEmail string) (*signatureResult, error) {
+	if signatureID == "" {
+		return nil, nil
+	}
+
+	sig, err := signature.Get(runtime, mailboxID, signatureID)
+	if err != nil {
+		return nil, err
+	}
+
+	// Resolve sender info for template interpolation.
+	lang := resolveLang(runtime)
+	senderName, senderEmail := resolveSenderInfo(runtime, mailboxID, fromEmail)
+	rendered := signature.InterpolateTemplate(sig, lang, senderName, senderEmail)
+
+	// Download signature inline images. The file_key field contains a
+	// direct download URL provided by the mail backend.
+	var images []draftpkg.SignatureImage
+	for _, img := range sig.Images {
+		if img.DownloadURL == "" || img.CID == "" {
+			continue
+		}
+		data, ct, err := downloadSignatureImage(runtime, img.DownloadURL, img.ImageName)
+		if err != nil {
+			return nil, fmt.Errorf("failed to download signature image %s: %w", img.ImageName, err)
+		}
+		images = append(images, draftpkg.SignatureImage{
+			CID:         img.CID,
+			ContentType: ct,
+			FileName:    img.ImageName,
+			Data:        data,
+		})
+	}
+
+	return &signatureResult{
+		ID:              sig.ID,
+		RenderedContent: rendered,
+		Images:          images,
+	}, nil
+}
+
+// injectSignatureIntoBody inserts signature HTML into the body, before the quote block.
+// It removes any existing signature first, then places the new signature between
+// the user-authored content and the quote block (if any).
+// Returns the new full HTML body.
+func injectSignatureIntoBody(bodyHTML string, sig *signatureResult) string {
+	if sig == nil {
+		return bodyHTML
+	}
+	cleaned := draftpkg.RemoveSignatureHTML(bodyHTML)
+	userContent, quote := draftpkg.SplitAtQuote(cleaned)
+	sigBlock := draftpkg.SignatureSpacing() + draftpkg.BuildSignatureHTML(sig.ID, sig.RenderedContent)
+	return userContent + sigBlock + quote
+}
+
+// addSignatureImagesToBuilder adds signature inline images to the EML builder.
+func addSignatureImagesToBuilder(bld emlbuilder.Builder, sig *signatureResult) emlbuilder.Builder {
+	if sig == nil {
+		return bld
+	}
+	for _, img := range sig.Images {
+		cid := normalizeInlineCID(img.CID)
+		if cid == "" {
+			continue
+		}
+		bld = bld.AddInline(img.Data, img.ContentType, img.FileName, cid)
+	}
+	return bld
+}
+
+// resolveSenderInfo fetches senderName and senderEmail via the send_as API.
+// resolveSenderInfo fetches send_as addresses and returns the name/email
+// for signature interpolation. If fromEmail is non-empty, it matches
+// that address in the sendable list (for alias/send_as scenarios);
+// otherwise falls back to the first (primary) address.
+func resolveSenderInfo(runtime *common.RuntimeContext, mailboxID, fromEmail string) (name, email string) {
+	data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "settings", "send_as"), nil, nil)
+	if err != nil {
+		return "", ""
+	}
+	addrs, ok := data["sendable_addresses"].([]interface{})
+	if !ok || len(addrs) == 0 {
+		return "", ""
+	}
+	// If fromEmail is specified, find the matching address.
+	if fromEmail != "" {
+		for _, a := range addrs {
+			m, ok := a.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			e, _ := m["email_address"].(string)
+			if strings.EqualFold(e, fromEmail) {
+				n, _ := m["name"].(string)
+				return n, e
+			}
+		}
+	}
+	// Fall back to the first sendable address (primary).
+	first, ok := addrs[0].(map[string]interface{})
+	if !ok {
+		return "", ""
+	}
+	n, _ := first["name"].(string)
+	e, _ := first["email_address"].(string)
+	return n, e
+}
+
+// downloadSignatureImage downloads a signature image by its direct URL.
+// Security: enforces https, does not send Bearer token (URL is pre-signed),
+// uses context timeout, and limits response size. Aligned with
+// downloadAttachmentContent in helpers.go.
+func downloadSignatureImage(runtime *common.RuntimeContext, downloadURL, filename string) ([]byte, string, error) {
+	u, err := url.Parse(downloadURL)
+	if err != nil {
+		return nil, "", fmt.Errorf("signature image download: invalid URL: %w", err)
+	}
+	if u.Scheme != "https" {
+		return nil, "", fmt.Errorf("signature image download: URL must use https (got %q)", u.Scheme)
+	}
+	if u.Host == "" {
+		return nil, "", fmt.Errorf("signature image download: URL has no host")
+	}
+
+	httpClient, err := runtime.Factory.HttpClient()
+	if err != nil {
+		return nil, "", fmt.Errorf("signature image download: %w", err)
+	}
+	ctx, cancel := context.WithTimeout(runtime.Ctx(), 30*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
+	if err != nil {
+		return nil, "", fmt.Errorf("signature image download: %w", err)
+	}
+	// Do NOT send Authorization: the download URL is pre-signed.
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, "", fmt.Errorf("signature image download: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode >= 400 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+		return nil, "", fmt.Errorf("signature image download: HTTP %d: %s", resp.StatusCode, string(body))
+	}
+
+	const maxSize = 10 * 1024 * 1024
+	data, err := io.ReadAll(io.LimitReader(resp.Body, maxSize+1))
+	if err != nil {
+		return nil, "", fmt.Errorf("signature image download: read body: %w", err)
+	}
+	if len(data) > maxSize {
+		return nil, "", fmt.Errorf("signature image download: file exceeds 10MB limit")
+	}
+
+	ct := resp.Header.Get("Content-Type")
+	if ct == "" || ct == "application/octet-stream" {
+		ct = contentTypeFromFilename(filename)
+	}
+
+	return data, ct, nil
+}
+
+func contentTypeFromFilename(name string) string {
+	ext := strings.ToLower(filepath.Ext(name))
+	switch ext {
+	case ".png":
+		return "image/png"
+	case ".jpg", ".jpeg":
+		return "image/jpeg"
+	case ".gif":
+		return "image/gif"
+	case ".webp":
+		return "image/webp"
+	case ".svg":
+		return "image/svg+xml"
+	case ".bmp":
+		return "image/bmp"
+	default:
+		return "application/octet-stream"
+	}
+}
+
+// signatureCIDs returns the CID list from a signatureResult, for inline CID validation.
+func signatureCIDs(sig *signatureResult) []string {
+	if sig == nil {
+		return nil
+	}
+	cids := make([]string, 0, len(sig.Images))
+	for _, img := range sig.Images {
+		cid := normalizeInlineCID(img.CID)
+		if cid != "" {
+			cids = append(cids, cid)
+		}
+	}
+	return cids
+}
+
+// validateSignatureWithPlainText returns an error if both --plain-text and --signature-id are set.
+func validateSignatureWithPlainText(plainText bool, signatureID string) error {
+	if plainText && signatureID != "" {
+		return fmt.Errorf("--plain-text and --signature-id are mutually exclusive: signatures require HTML mode")
+	}
+	return nil
+}

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/slides/helpers.go

@@ -0,0 +1,177 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"fmt"
+	"net/url"
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// presentationRef holds a parsed --presentation input.
+//
+// Slides shortcuts accept three input shapes:
+//   - a raw xml_presentation_id token
+//   - a slides URL like https://<host>/slides/<token>
+//   - a wiki URL like https://<host>/wiki/<token> (must resolve to obj_type=slides)
+type presentationRef struct {
+	Kind  string // "slides" | "wiki"
+	Token string
+}
+
+// parsePresentationRef extracts a presentation token from a token, slides URL, or wiki URL.
+// Wiki tokens are returned unresolved; callers must run resolveWikiToSlidesToken to
+// obtain the real xml_presentation_id and verify obj_type=slides.
+func parsePresentationRef(input string) (presentationRef, error) {
+	raw := strings.TrimSpace(input)
+	if raw == "" {
+		return presentationRef{}, output.ErrValidation("--presentation cannot be empty")
+	}
+	// URL inputs: parse properly and only honor /slides/ or /wiki/ when they
+	// appear as a prefix of the URL path. Substring matching previously let
+	// e.g. `https://x/docx/foo?next=/slides/abc` resolve to token "abc".
+	if strings.Contains(raw, "://") {
+		u, err := url.Parse(raw)
+		if err != nil || u.Path == "" {
+			return presentationRef{}, output.ErrValidation("unsupported --presentation input %q: use an xml_presentation_id, a /slides/ URL, or a /wiki/ URL", raw)
+		}
+		if token, ok := tokenAfterPathPrefix(u.Path, "/slides/"); ok {
+			return presentationRef{Kind: "slides", Token: token}, nil
+		}
+		if token, ok := tokenAfterPathPrefix(u.Path, "/wiki/"); ok {
+			return presentationRef{Kind: "wiki", Token: token}, nil
+		}
+		return presentationRef{}, output.ErrValidation("unsupported --presentation input %q: use an xml_presentation_id, a /slides/ URL, or a /wiki/ URL", raw)
+	}
+	// Non-URL input must be a bare token — anything with path/query/fragment
+	// chars is rejected so partial-path inputs like `tmp/wiki/wikcn123` don't
+	// get silently accepted.
+	if strings.ContainsAny(raw, "/?#") {
+		return presentationRef{}, output.ErrValidation("unsupported --presentation input %q: use an xml_presentation_id, a /slides/ URL, or a /wiki/ URL", raw)
+	}
+	return presentationRef{Kind: "slides", Token: raw}, nil
+}
+
+// tokenAfterPathPrefix extracts the first path segment after prefix from path.
+// Returns ("", false) if path doesn't start with prefix or the segment is empty.
+func tokenAfterPathPrefix(path, prefix string) (string, bool) {
+	if !strings.HasPrefix(path, prefix) {
+		return "", false
+	}
+	rest := path[len(prefix):]
+	if i := strings.IndexByte(rest, '/'); i >= 0 {
+		rest = rest[:i]
+	}
+	rest = strings.TrimSpace(rest)
+	if rest == "" {
+		return "", false
+	}
+	return rest, true
+}
+
+// resolvePresentationID resolves a parsed ref into an xml_presentation_id.
+// Slides refs pass through; wiki refs are looked up via wiki.spaces.get_node and
+// must resolve to obj_type=slides.
+func resolvePresentationID(runtime *common.RuntimeContext, ref presentationRef) (string, error) {
+	switch ref.Kind {
+	case "slides":
+		return ref.Token, nil
+	case "wiki":
+		data, err := runtime.CallAPI(
+			"GET",
+			"/open-apis/wiki/v2/spaces/get_node",
+			map[string]interface{}{"token": ref.Token},
+			nil,
+		)
+		if err != nil {
+			return "", err
+		}
+		node := common.GetMap(data, "node")
+		objType := common.GetString(node, "obj_type")
+		objToken := common.GetString(node, "obj_token")
+		if objType == "" || objToken == "" {
+			return "", output.Errorf(output.ExitAPI, "api_error", "wiki get_node returned incomplete node data")
+		}
+		if objType != "slides" {
+			return "", output.ErrValidation("wiki resolved to %q, but slides shortcuts require a slides presentation", objType)
+		}
+		return objToken, nil
+	default:
+		return "", output.ErrValidation("unsupported presentation ref kind %q", ref.Kind)
+	}
+}
+
+// imgSrcPlaceholderRegex matches `src="@<path>"` or `src='@<path>'` inside <img> tags.
+// The "@" prefix is the magic marker for "this is a local file path; upload it and
+// replace with file_token".
+//
+// Match groups:
+//
+//	1: opening quote character (so we can replace symmetrically)
+//	2: the path string (everything inside the quotes after the leading @)
+//
+// We deliberately scope to <img ... src="@..."> rather than any src= so other
+// schema elements (like icon/iconType) aren't accidentally rewritten.
+// `\s*=\s*` tolerates `src = "..."` style attributes (XML allows whitespace
+// around `=`); without it we'd silently leave such placeholders unrewritten.
+var imgSrcPlaceholderRegex = regexp.MustCompile(`(?s)<img\b[^>]*?\bsrc\s*=\s*(["'])@([^"']+)(["'])`)
+
+// extractImagePlaceholderPaths returns the de-duplicated list of local paths
+// referenced via <img src="@path"> in the given slide XML strings.
+//
+// Order is preserved (first occurrence wins) so dry-run / progress messages are
+// stable across runs.
+func extractImagePlaceholderPaths(slideXMLs []string) []string {
+	var paths []string
+	seen := map[string]bool{}
+	for _, xml := range slideXMLs {
+		matches := imgSrcPlaceholderRegex.FindAllStringSubmatch(xml, -1)
+		for _, m := range matches {
+			if m[1] != m[3] {
+				// Mismatched opening/closing quotes — Go's RE2 has no backreferences,
+				// so we filter it here. Treat as malformed XML and skip.
+				continue
+			}
+			path := strings.TrimSpace(m[2])
+			if path == "" || seen[path] {
+				continue
+			}
+			seen[path] = true
+			paths = append(paths, path)
+		}
+	}
+	return paths
+}
+
+// replaceImagePlaceholders rewrites <img src="@path"> occurrences in the input
+// XML by looking up each path in tokens. Paths missing from the map are left
+// untouched (callers should ensure the map is complete).
+func replaceImagePlaceholders(slideXML string, tokens map[string]string) string {
+	return imgSrcPlaceholderRegex.ReplaceAllStringFunc(slideXML, func(match string) string {
+		sub := imgSrcPlaceholderRegex.FindStringSubmatch(match)
+		if len(sub) < 4 {
+			return match
+		}
+		quote, path, closeQuote := sub[1], sub[2], sub[3]
+		if quote != closeQuote {
+			// Mismatched quotes — see extractImagePlaceholderPaths.
+			return match
+		}
+		token, ok := tokens[strings.TrimSpace(path)]
+		if !ok {
+			return match
+		}
+		// Replace only the `"@<path>"` segment (quotes inclusive) so any
+		// surrounding attrs and whitespace around `=` stay intact. Looking up
+		// by the literal `@<path>"` (with closing quote) avoids accidentally
+		// matching the same path elsewhere in the tag.
+		oldQuoted := fmt.Sprintf("%s@%s%s", quote, path, closeQuote)
+		newQuoted := fmt.Sprintf("%s%s%s", quote, token, closeQuote)
+		return strings.Replace(match, oldQuoted, newQuoted, 1)
+	})
+}

shortcuts/slides/helpers_test.go

@@ -0,0 +1,191 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestParsePresentationRef(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		input     string
+		wantKind  string
+		wantToken string
+		wantErr   string
+	}{
+		{name: "raw token", input: "slidesXXXXXXXXXXXXXXXXXXXXXX", wantKind: "slides", wantToken: "slidesXXXXXXXXXXXXXXXXXXXXXX"},
+		{name: "slides URL", input: "https://x.feishu.cn/slides/abc123", wantKind: "slides", wantToken: "abc123"},
+		{name: "slides URL with query", input: "https://x.feishu.cn/slides/abc123?from=share", wantKind: "slides", wantToken: "abc123"},
+		{name: "slides URL with anchor", input: "https://x.feishu.cn/slides/abc123#p1", wantKind: "slides", wantToken: "abc123"},
+		{name: "wiki URL", input: "https://x.feishu.cn/wiki/wikcn123", wantKind: "wiki", wantToken: "wikcn123"},
+		{name: "trims whitespace", input: "  abc123  ", wantKind: "slides", wantToken: "abc123"},
+		{name: "empty", input: "", wantErr: "cannot be empty"},
+		{name: "blank", input: "   ", wantErr: "cannot be empty"},
+		{name: "unsupported url", input: "https://x.feishu.cn/docx/foo", wantErr: "unsupported"},
+		{name: "unsupported path", input: "foo/bar", wantErr: "unsupported"},
+		// Regression: /slides/ inside a query string must NOT be treated as a slides marker.
+		{name: "slides marker inside query", input: "https://x.feishu.cn/docx/foo?next=/slides/abc", wantErr: "unsupported"},
+		// Regression: /wiki/ as a path segment but not a prefix must not match.
+		{name: "wiki marker mid-path", input: "https://x.feishu.cn/docx/wiki/wikcn123", wantErr: "unsupported"},
+		// Regression: bare relative path containing wiki/ is not a wiki ref.
+		{name: "non-url wiki segment", input: "tmp/wiki/wikcn123", wantErr: "unsupported"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got, err := parsePresentationRef(tt.input)
+			if tt.wantErr != "" {
+				if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+					t.Fatalf("err = %v, want substring %q", err, tt.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if got.Kind != tt.wantKind || got.Token != tt.wantToken {
+				t.Fatalf("got = %+v, want kind=%s token=%s", got, tt.wantKind, tt.wantToken)
+			}
+		})
+	}
+}
+
+func TestExtractImagePlaceholderPaths(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		in   []string
+		want []string
+	}{
+		{
+			name: "no placeholders",
+			in:   []string{`<slide><data><img src="https://x.com/a.png"/></data></slide>`},
+			want: nil,
+		},
+		{
+			name: "single placeholder",
+			in:   []string{`<slide><data><img src="@./pic.png" topLeftX="10"/></data></slide>`},
+			want: []string{"./pic.png"},
+		},
+		{
+			name: "single quotes",
+			in:   []string{`<img src='@./a.png'/>`},
+			want: []string{"./a.png"},
+		},
+		{
+			name: "dedup across slides",
+			in: []string{
+				`<slide><data><img src="@./shared.png"/></data></slide>`,
+				`<slide><data><img src="@./shared.png" topLeftX="100"/><img src="@./other.png"/></data></slide>`,
+			},
+			want: []string{"./shared.png", "./other.png"},
+		},
+		{
+			name: "ignores non-img src",
+			in:   []string{`<icon src="@./fake.png"/><img src="@./real.png"/>`},
+			want: []string{"./real.png"},
+		},
+		{
+			name: "preserves order of first occurrence",
+			in:   []string{`<img src="@b.png"/><img src="@a.png"/><img src="@b.png"/>`},
+			want: []string{"b.png", "a.png"},
+		},
+		{
+			// Regression: Go RE2 has no backreferences, so the regex captures
+			// opening and closing quotes independently. Mismatched pairs must
+			// be filtered out post-match instead of producing bogus paths.
+			name: "rejects mismatched quotes",
+			in:   []string{`<img src="@./oops.png'/>`},
+			want: nil,
+		},
+		{
+			// Regression: XML allows whitespace around `=`; placeholders in
+			// `src = "@..."` form must still be detected.
+			name: "tolerates whitespace around equals",
+			in:   []string{`<img src = "@./spaced.png" />`},
+			want: []string{"./spaced.png"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := extractImagePlaceholderPaths(tt.in)
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Fatalf("got %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestReplaceImagePlaceholders(t *testing.T) {
+	t.Parallel()
+
+	tokens := map[string]string{
+		"./pic.png": "tok_abc",
+		"./b.png":   "tok_b",
+	}
+
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "single replacement preserves siblings",
+			in:   `<img src="@./pic.png" topLeftX="10" width="100"/>`,
+			want: `<img src="tok_abc" topLeftX="10" width="100"/>`,
+		},
+		{
+			name: "multiple replacements",
+			in:   `<img src="@./pic.png"/><img src="@./b.png"/>`,
+			want: `<img src="tok_abc"/><img src="tok_b"/>`,
+		},
+		{
+			name: "single quotes",
+			in:   `<img src='@./pic.png'/>`,
+			want: `<img src='tok_abc'/>`,
+		},
+		{
+			name: "leaves unknown placeholder untouched",
+			in:   `<img src="@./missing.png"/>`,
+			want: `<img src="@./missing.png"/>`,
+		},
+		{
+			name: "leaves http url alone",
+			in:   `<img src="https://x.com/a.png"/>`,
+			want: `<img src="https://x.com/a.png"/>`,
+		},
+		{
+			name: "leaves bare token alone",
+			in:   `<img src="existing_token"/>`,
+			want: `<img src="existing_token"/>`,
+		},
+		{
+			// Regression: placeholders with whitespace around `=` must be
+			// rewritten too (XML permits the form). Surrounding whitespace
+			// is preserved so the rewritten attribute reads naturally.
+			name: "tolerates whitespace around equals",
+			in:   `<img src = "@./pic.png" topLeftX="10"/>`,
+			want: `<img src = "tok_abc" topLeftX="10"/>`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := replaceImagePlaceholders(tt.in, tokens)
+			if got != tt.want {
+				t.Fatalf("got %q\nwant %q", got, tt.want)
+			}
+		})
+	}
+}

shortcuts/slides/shortcuts.go

@@ -9,5 +9,6 @@ import "github.com/larksuite/cli/shortcuts/common"
 func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		SlidesCreate,
+		SlidesMediaUpload,
 	}
 }

shortcuts/slides/slides_create.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"path/filepath"
 	"strings"
 
 	"github.com/larksuite/cli/internal/output"
@@ -27,10 +28,15 @@ var SlidesCreate = common.Shortcut{
 	Description: "Create a Lark Slides presentation",
 	Risk:        "write",
 	AuthTypes:   []string{"user", "bot"},
-	Scopes:      []string{"slides:presentation:create", "slides:presentation:write_only"},
+	// docs:document.media:upload is required by the @-placeholder upload path.
+	// Declared up-front (matching the convention used by other multi-API shortcuts
+	// like wiki_move) so the pre-flight check fails fast and lark-cli's
+	// auth login --scope hint guides the user, instead of leaving an orphaned
+	// empty presentation when the in-flight upload 403s.
+	Scopes: []string{"slides:presentation:create", "slides:presentation:write_only", "docs:document.media:upload"},
 	Flags: []common.Flag{
 		{Name: "title", Desc: "presentation title"},
-		{Name: "slides", Desc: "slide content JSON array (each element is a <slide> XML string, max 10; for more pages, create first then add via xml_presentation.slide.create)"},
+		{Name: "slides", Desc: "slide content JSON array (each element is a <slide> XML string, max 10; for more pages, create first then add via xml_presentation.slide.create). <img src=\"@./local.png\"> placeholders are auto-uploaded and replaced with file_token."},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if slidesStr := runtime.Str("slides"); slidesStr != "" {
@@ -41,6 +47,21 @@ var SlidesCreate = common.Shortcut{
 			if len(slides) > maxSlidesPerCreate {
 				return common.FlagErrorf("--slides array exceeds maximum of %d slides; create the presentation first, then add slides via xml_presentation.slide.create", maxSlidesPerCreate)
 			}
+			// Validate placeholder paths up front so we don't create a presentation
+			// only to fail mid-way on a missing local file.
+			for _, path := range extractImagePlaceholderPaths(slides) {
+				stat, err := runtime.FileIO().Stat(path)
+				if err != nil {
+					return common.WrapInputStatError(err, fmt.Sprintf("--slides @%s: file not found", path))
+				}
+				if !stat.Mode().IsRegular() {
+					return common.FlagErrorf("--slides @%s: must be a regular file", path)
+				}
+				if stat.Size() > common.MaxDriveMediaUploadSinglePartSize {
+					return common.FlagErrorf("--slides @%s: file size %s exceeds 20 MB limit for slides image upload",
+						path, common.FormatSize(stat.Size()))
+				}
+			}
 		}
 		return nil
 	},
@@ -61,16 +82,32 @@ var SlidesCreate = common.Shortcut{
 			var slides []string
 			_ = json.Unmarshal([]byte(slidesStr), &slides)
 			n := len(slides)
-			total := n + 1
+			placeholders := extractImagePlaceholderPaths(slides)
+			total := n + 1 + len(placeholders)
 
-			dry.Desc(fmt.Sprintf("Create presentation + add %d slide(s)", n)).
+			descSuffix := ""
+			if len(placeholders) > 0 {
+				descSuffix = fmt.Sprintf(" + upload %d image(s)", len(placeholders))
+			}
+			dry.Desc(fmt.Sprintf("Create presentation%s + add %d slide(s)", descSuffix, n)).
 				POST("/open-apis/slides_ai/v1/xml_presentations").
 				Desc(fmt.Sprintf("[1/%d] Create presentation", total)).
 				Body(createBody)
 
+			// Upload steps come right after creation so they can use the new
+			// presentation_id as parent_node.
+			for i, path := range placeholders {
+				appendSlidesUploadDryRun(dry, path, "<xml_presentation_id>", i+2)
+			}
+
+			slideStepStart := 2 + len(placeholders)
+			slideDescSuffix := ""
+			if len(placeholders) > 0 {
+				slideDescSuffix = " (img placeholders auto-replaced)"
+			}
 			for i, slideXML := range slides {
 				dry.POST("/open-apis/slides_ai/v1/xml_presentations/<xml_presentation_id>/slide").
-					Desc(fmt.Sprintf("[%d/%d] Add slide %d", i+2, total, i+1)).
+					Desc(fmt.Sprintf("[%d/%d] Add slide %d%s", slideStepStart+i, total, i+1, slideDescSuffix)).
 					Body(map[string]interface{}{
 						"slide": map[string]interface{}{"content": slideXML},
 					})
@@ -121,6 +158,23 @@ var SlidesCreate = common.Shortcut{
 			_ = json.Unmarshal([]byte(slidesStr), &slides) // already validated
 
 			if len(slides) > 0 {
+				// Step 1.5: Upload any @path placeholders, then rewrite slide XML
+				// with the resulting file_tokens. Uploads run after creation so
+				// they can use the new presentation_id as parent_node.
+				placeholders := extractImagePlaceholderPaths(slides)
+				if len(placeholders) > 0 {
+					tokens, uploaded, err := uploadSlidesPlaceholders(runtime, presentationID, placeholders)
+					if err != nil {
+						return output.Errorf(output.ExitAPI, "api_error",
+							"image upload failed: %v (presentation %s was created; %d image(s) uploaded before failure)",
+							err, presentationID, uploaded)
+					}
+					for i := range slides {
+						slides[i] = replaceImagePlaceholders(slides[i], tokens)
+					}
+					result["images_uploaded"] = uploaded
+				}
+
 				slideURL := fmt.Sprintf(
 					"/open-apis/slides_ai/v1/xml_presentations/%s/slide",
 					validate.EncodePathSegment(presentationID),
@@ -205,6 +259,33 @@ func buildPresentationXML(title string) string {
 	)
 }
 
+// uploadSlidesPlaceholders uploads each unique placeholder path against the
+// presentation and returns the path→file_token map. The second return value is
+// the number of files successfully uploaded before any error, so callers can
+// surface progress in the failure message.
+func uploadSlidesPlaceholders(runtime *common.RuntimeContext, presentationID string, paths []string) (map[string]string, int, error) {
+	tokens := make(map[string]string, len(paths))
+	for i, path := range paths {
+		stat, err := runtime.FileIO().Stat(path)
+		if err != nil {
+			return tokens, i, common.WrapInputStatError(err, fmt.Sprintf("@%s: file not found", path))
+		}
+		if !stat.Mode().IsRegular() {
+			return tokens, i, output.ErrValidation("@%s: must be a regular file", path)
+		}
+		fileName := filepath.Base(path)
+		fmt.Fprintf(runtime.IO().ErrOut, "Uploading image %d/%d: %s (%s)\n",
+			i+1, len(paths), fileName, common.FormatSize(stat.Size()))
+
+		token, err := uploadSlidesMedia(runtime, path, fileName, stat.Size(), presentationID)
+		if err != nil {
+			return tokens, i, fmt.Errorf("@%s: %w", path, err)
+		}
+		tokens[path] = token
+	}
+	return tokens, len(paths), nil
+}
+
 // xmlEscape escapes special XML characters in text content.
 func xmlEscape(s string) string {
 	s = strings.ReplaceAll(s, "&", "&amp;")

shortcuts/slides/slides_create_test.go

@@ -6,6 +6,7 @@ package slides
 import (
 	"bytes"
 	"encoding/json"
+	"os"
 	"strings"
 	"testing"
 
@@ -651,3 +652,175 @@ func decodeSlidesCreateEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]i
 	}
 	return data
 }
+
+// TestSlidesCreateWithImagePlaceholders verifies @path placeholders are uploaded
+// once each (with dedup) and replaced with file_tokens before slide.create runs.
+//
+// Not parallel: uses os.Chdir to pin local file paths to a temp dir.
+func TestSlidesCreateWithImagePlaceholders(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+	if err := os.WriteFile("a.png", []byte("aa"), 0o644); err != nil {
+		t.Fatalf("write a.png: %v", err)
+	}
+	if err := os.WriteFile("b.png", []byte("bb"), 0o644); err != nil {
+		t.Fatalf("write b.png: %v", err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"xml_presentation_id": "pres_img",
+				"revision_id":         1,
+			},
+		},
+	})
+
+	// Two distinct images → two upload calls. a.png is referenced twice but
+	// must be uploaded only once.
+	uploadStubA := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"file_token": "tok_a"}},
+	}
+	uploadStubB := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"file_token": "tok_b"}},
+	}
+	reg.Register(uploadStubA)
+	reg.Register(uploadStubB)
+
+	// Slide stubs: capture the rewritten slide content to assert tokens were
+	// actually substituted into the XML.
+	slideStub1 := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_img/slide",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"slide_id": "s1", "revision_id": 2}},
+	}
+	slideStub2 := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_img/slide",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"slide_id": "s2", "revision_id": 3}},
+	}
+	reg.Register(slideStub1)
+	reg.Register(slideStub2)
+	registerBatchQueryStub(reg, "pres_img", "https://x.feishu.cn/slides/pres_img")
+
+	slidesJSON := `[
+	  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><img src=\"@a.png\" topLeftX=\"10\"/><img src=\"@b.png\" topLeftX=\"20\"/></data></slide>",
+	  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><img src=\"@a.png\" topLeftX=\"30\"/></data></slide>"
+	]`
+	err := runSlidesCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--title", "Img test",
+		"--slides", slidesJSON,
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeSlidesCreateEnvelope(t, stdout)
+	if data["images_uploaded"] != float64(2) {
+		t.Fatalf("images_uploaded = %v, want 2 (a.png deduped)", data["images_uploaded"])
+	}
+	if data["slides_added"] != float64(2) {
+		t.Fatalf("slides_added = %v, want 2", data["slides_added"])
+	}
+
+	// Assert each slide.create body uses tokens (not @path placeholders), and
+	// that both upload tokens reach at least one slide so a buggy mapping
+	// where `@b.png` got rewritten to `tok_a` would still fail.
+	hasTokB := false
+	for _, stub := range []*httpmock.Stub{slideStub1, slideStub2} {
+		var body map[string]interface{}
+		if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+			t.Fatalf("decode slide body: %v", err)
+		}
+		slide, _ := body["slide"].(map[string]interface{})
+		content, _ := slide["content"].(string)
+		if strings.Contains(content, "@a.png") || strings.Contains(content, "@b.png") {
+			t.Fatalf("slide content still contains placeholder: %s", content)
+		}
+		if !strings.Contains(content, "tok_a") {
+			t.Fatalf("slide content missing tok_a: %s", content)
+		}
+		if strings.Contains(content, "tok_b") {
+			hasTokB = true
+		}
+	}
+	if !hasTokB {
+		t.Fatal("expected at least one slide body to contain tok_b")
+	}
+}
+
+// TestSlidesCreatePlaceholderFileMissing verifies validation rejects a missing local file
+// up front, before the presentation is created.
+func TestSlidesCreatePlaceholderFileMissing(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	// No HTTP mocks registered — Validate must reject before any API call.
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	slidesJSON := `["<slide><data><img src=\"@./missing.png\"/></data></slide>"]`
+	err := runSlidesCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--title", "missing img",
+		"--slides", slidesJSON,
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected validation error for missing placeholder file")
+	}
+	if !strings.Contains(err.Error(), "missing.png") {
+		t.Fatalf("err = %v, want mention of missing.png", err)
+	}
+}
+
+// TestSlidesCreateWithPlaceholdersDryRun verifies dry-run lists upload steps
+// with placeholder files counted into the total.
+func TestSlidesCreateWithPlaceholdersDryRun(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+	if err := os.WriteFile("p1.png", []byte("x"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	if err := os.WriteFile("p2.png", []byte("x"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	slidesJSON := `["<slide><data><img src=\"@p1.png\"/><img src=\"@p2.png\"/></data></slide>"]`
+	err := runSlidesCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--title", "dry imgs",
+		"--slides", slidesJSON,
+		"--dry-run",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	// Bookend step markers: [1/4] = create presentation, [4/4] = add slide 1.
+	// Upload steps in between use the helper's own [N] labels (no /total).
+	for _, marker := range []string{"[1/4]", "[4/4]"} {
+		if !strings.Contains(out, marker) {
+			t.Fatalf("dry-run missing %s, got: %s", marker, out)
+		}
+	}
+	if strings.Count(out, "upload_all") != 2 {
+		t.Fatalf("dry-run should contain 2 upload_all calls, got: %s", out)
+	}
+	if !strings.Contains(out, slidesMediaParentType) {
+		t.Fatalf("dry-run missing parent_type %q, got: %s", slidesMediaParentType, out)
+	}
+	if !strings.Contains(out, "Create presentation + upload 2 image(s)") {
+		t.Fatalf("dry-run header should describe upload count, got: %s", out)
+	}
+}

shortcuts/slides/slides_media_upload.go

@@ -0,0 +1,151 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// slidesMediaParentType is the only parent_type the slides backend accepts for
+// media uploaded against an xml_presentation. Verified empirically:
+// `slide_image` returns 1061001 unknown error, `slides_image` / `slides_file`
+// return 1061002 params error, but `slide_file` returns a valid file_token
+// that can be used as <img src="..."> in slide XML.
+//
+// NOTE: `slide_file` is only accepted by the single-part upload_all endpoint.
+// The multipart upload_prepare endpoint rejects it (99992402 field validation
+// failed), so slides image uploads are capped at 20 MB.
+const slidesMediaParentType = "slide_file"
+
+// SlidesMediaUpload uploads a local image to drive media against a slides
+// presentation and returns the file_token. The token can be used as the value
+// of <img src="..."> in slide XML.
+//
+// This is the atomic building block for getting a local image into a slides
+// deck. Higher-level shortcuts (e.g. +create with @path placeholders) reuse
+// the same upload helpers.
+var SlidesMediaUpload = common.Shortcut{
+	Service:     "slides",
+	Command:     "+media-upload",
+	Description: "Upload a local image to a slides presentation and return the file_token (use as <img src=...>)",
+	Risk:        "write",
+	// wiki:node:read is required by the wiki-URL resolution path. Declared
+	// up-front (matching the convention used by other multi-API shortcuts) so
+	// users without it get the standard auth login --scope hint at pre-flight.
+	Scopes:    []string{"docs:document.media:upload", "wiki:node:read"},
+	AuthTypes: []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "file", Desc: "local image path (max 20 MB)", Required: true},
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parsePresentationRef(runtime.Str("presentation")); err != nil {
+			return err
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		filePath := runtime.Str("file")
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+
+		dry := common.NewDryRunAPI()
+		parentNode := ref.Token
+		stepBase := 1
+		if ref.Kind == "wiki" {
+			parentNode = "<resolved_slides_token>"
+			stepBase = 2
+			dry.Desc("2-step orchestration: resolve wiki → upload media").
+				GET("/open-apis/wiki/v2/spaces/get_node").
+				Desc("[1] Resolve wiki node to slides presentation").
+				Params(map[string]interface{}{"token": ref.Token})
+		} else {
+			dry.Desc("Upload local file to slides presentation")
+		}
+		appendSlidesUploadDryRun(dry, filePath, parentNode, stepBase)
+		return dry.Set("presentation_id", ref.Token)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		filePath := runtime.Str("file")
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		presentationID, err := resolvePresentationID(runtime, ref)
+		if err != nil {
+			return err
+		}
+
+		stat, err := runtime.FileIO().Stat(filePath)
+		if err != nil {
+			return common.WrapInputStatError(err, "file not found")
+		}
+		if !stat.Mode().IsRegular() {
+			return output.ErrValidation("file must be a regular file: %s", filePath)
+		}
+
+		if stat.Size() > common.MaxDriveMediaUploadSinglePartSize {
+			return output.ErrValidation("file %s is %s, exceeds 20 MB limit for slides image upload",
+				filepath.Base(filePath), common.FormatSize(stat.Size()))
+		}
+
+		fileName := filepath.Base(filePath)
+		fmt.Fprintf(runtime.IO().ErrOut, "Uploading: %s (%s) -> presentation %s\n",
+			fileName, common.FormatSize(stat.Size()), common.MaskToken(presentationID))
+
+		fileToken, err := uploadSlidesMedia(runtime, filePath, fileName, stat.Size(), presentationID)
+		if err != nil {
+			return err
+		}
+
+		runtime.Out(map[string]interface{}{
+			"file_token":      fileToken,
+			"file_name":       fileName,
+			"size":            stat.Size(),
+			"presentation_id": presentationID,
+		}, nil)
+		return nil
+	},
+}
+
+// uploadSlidesMedia is the shared upload helper used by both +media-upload and
+// the +create placeholder pipeline. Always uses parent_type=slide_file with the
+// presentation_id as parent_node — verified to be the only working combo.
+//
+// Callers must ensure fileSize ≤ MaxDriveMediaUploadSinglePartSize (20 MB)
+// because the multipart upload API does not accept parent_type=slide_file.
+func uploadSlidesMedia(runtime *common.RuntimeContext, filePath, fileName string, fileSize int64, presentationID string) (string, error) {
+	if fileSize > common.MaxDriveMediaUploadSinglePartSize {
+		return "", output.ErrValidation("file %s is %s, exceeds 20 MB limit for slides image upload",
+			fileName, common.FormatSize(fileSize))
+	}
+	parent := presentationID
+	return common.UploadDriveMediaAll(runtime, common.DriveMediaUploadAllConfig{
+		FilePath:   filePath,
+		FileName:   fileName,
+		FileSize:   fileSize,
+		ParentType: slidesMediaParentType,
+		ParentNode: &parent,
+	})
+}
+
+// appendSlidesUploadDryRun renders the upload_all step for a single file.
+func appendSlidesUploadDryRun(d *common.DryRunAPI, filePath, parentNode string, step int) {
+	d.POST("/open-apis/drive/v1/medias/upload_all").
+		Desc(fmt.Sprintf("[%d] Upload local file (max 20 MB)", step)).
+		Body(map[string]interface{}{
+			"file_name":   filepath.Base(filePath),
+			"parent_type": slidesMediaParentType,
+			"parent_node": parentNode,
+			"size":        "<file_size>",
+			"file":        "@" + filePath,
+		})
+}

shortcuts/slides/slides_media_upload_test.go

@@ -0,0 +1,359 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"bytes"
+	"encoding/json"
+	"mime"
+	"mime/multipart"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// TestSlidesMediaUploadBasic verifies the happy path: token + presentation_id
+// with a real (small) local file.
+func TestSlidesMediaUploadBasic(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	if err := os.WriteFile("img.png", []byte("png-bytes"), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	uploadStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"file_token": "file_tok_xyz"},
+		},
+	}
+	reg.Register(uploadStub)
+
+	err := runSlidesShortcut(t, f, stdout, SlidesMediaUpload, []string{
+		"+media-upload",
+		"--file", "img.png",
+		"--presentation", "pres_abc",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["file_token"] != "file_tok_xyz" {
+		t.Fatalf("file_token = %v, want file_tok_xyz", data["file_token"])
+	}
+	if data["presentation_id"] != "pres_abc" {
+		t.Fatalf("presentation_id = %v, want pres_abc", data["presentation_id"])
+	}
+	if data["file_name"] != "img.png" {
+		t.Fatalf("file_name = %v, want img.png", data["file_name"])
+	}
+	if data["size"] != float64(len("png-bytes")) {
+		t.Fatalf("size = %v, want %d", data["size"], len("png-bytes"))
+	}
+
+	body := decodeMultipartBody(t, uploadStub)
+	if got := body.Fields["parent_type"]; got != slidesMediaParentType {
+		t.Fatalf("parent_type = %q, want %q", got, slidesMediaParentType)
+	}
+	if got := body.Fields["parent_node"]; got != "pres_abc" {
+		t.Fatalf("parent_node = %q, want pres_abc", got)
+	}
+	if got := body.Fields["file_name"]; got != "img.png" {
+		t.Fatalf("file_name = %q, want img.png", got)
+	}
+}
+
+// TestSlidesMediaUploadFromSlidesURL verifies that a slides URL is accepted
+// and the path-segment token is used as parent_node.
+func TestSlidesMediaUploadFromSlidesURL(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+	if err := os.WriteFile("p.png", []byte("x"), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"file_token": "tok"}},
+	}
+	reg.Register(stub)
+
+	err := runSlidesShortcut(t, f, stdout, SlidesMediaUpload, []string{
+		"+media-upload",
+		"--file", "p.png",
+		"--presentation", "https://x.feishu.cn/slides/url_token_123?from=share",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeMultipartBody(t, stub)
+	if got := body.Fields["parent_node"]; got != "url_token_123" {
+		t.Fatalf("parent_node = %q, want url_token_123", got)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["presentation_id"] != "url_token_123" {
+		t.Fatalf("presentation_id = %v, want url_token_123", data["presentation_id"])
+	}
+}
+
+// TestSlidesMediaUploadFromWikiURL verifies wiki URL → get_node lookup is performed
+// and the resolved obj_token is used as parent_node.
+func TestSlidesMediaUploadFromWikiURL(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+	if err := os.WriteFile("w.png", []byte("x"), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	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{}{
+					"obj_type":  "slides",
+					"obj_token": "real_pres_id",
+				},
+			},
+		},
+	})
+	uploadStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"file_token": "tok"}},
+	}
+	reg.Register(uploadStub)
+
+	err := runSlidesShortcut(t, f, stdout, SlidesMediaUpload, []string{
+		"+media-upload",
+		"--file", "w.png",
+		"--presentation", "https://x.feishu.cn/wiki/wikcn_xyz",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeMultipartBody(t, uploadStub)
+	if got := body.Fields["parent_node"]; got != "real_pres_id" {
+		t.Fatalf("parent_node = %q, want real_pres_id", got)
+	}
+}
+
+// TestSlidesMediaUploadWikiWrongType verifies wiki resolution rejects non-slides docs.
+func TestSlidesMediaUploadWikiWrongType(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+	if err := os.WriteFile("w.png", []byte("x"), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	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{}{
+					"obj_type":  "docx",
+					"obj_token": "docx_tok",
+				},
+			},
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesMediaUpload, []string{
+		"+media-upload",
+		"--file", "w.png",
+		"--presentation", "https://x.feishu.cn/wiki/wikcn",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error for non-slides wiki node")
+	}
+	if !strings.Contains(err.Error(), "docx") {
+		t.Fatalf("err = %v, want mention of resolved obj_type", err)
+	}
+}
+
+// TestSlidesMediaUploadFileNotFound verifies a missing local file fails fast.
+func TestSlidesMediaUploadFileNotFound(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	err := runSlidesShortcut(t, f, stdout, SlidesMediaUpload, []string{
+		"+media-upload",
+		"--file", "missing.png",
+		"--presentation", "pres_abc",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error for missing file")
+	}
+	if !strings.Contains(err.Error(), "file not found") && !strings.Contains(err.Error(), "no such file") {
+		t.Fatalf("err = %v, want file-not-found error", err)
+	}
+}
+
+// TestSlidesMediaUploadInvalidPresentation verifies validation rejects a bad ref.
+func TestSlidesMediaUploadInvalidPresentation(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	err := runSlidesShortcut(t, f, stdout, SlidesMediaUpload, []string{
+		"+media-upload",
+		"--file", "any.png",
+		"--presentation", "https://x.feishu.cn/docx/foo",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected validation error for unsupported presentation URL")
+	}
+	if !strings.Contains(err.Error(), "unsupported") {
+		t.Fatalf("err = %v, want 'unsupported' mention", err)
+	}
+}
+
+// TestSlidesMediaUploadDryRun verifies dry-run prints the upload step.
+func TestSlidesMediaUploadDryRun(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+	if err := os.WriteFile("dry.png", []byte("x"), 0o644); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	err := runSlidesShortcut(t, f, stdout, SlidesMediaUpload, []string{
+		"+media-upload",
+		"--file", "dry.png",
+		"--presentation", "pres_abc",
+		"--dry-run",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "/open-apis/drive/v1/medias/upload_all") {
+		t.Fatalf("dry-run should mention upload_all, got: %s", out)
+	}
+	if !strings.Contains(out, slidesMediaParentType) {
+		t.Fatalf("dry-run should mention parent_type %q, got: %s", slidesMediaParentType, out)
+	}
+}
+
+// runSlidesShortcut mounts and executes a slides shortcut with the given args.
+func runSlidesShortcut(t *testing.T, f *cmdutil.Factory, stdout *bytes.Buffer, sc common.Shortcut, args []string) error {
+	t.Helper()
+	parent := &cobra.Command{Use: "slides"}
+	sc.Mount(parent, f)
+	parent.SetArgs(args)
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	if stdout != nil {
+		stdout.Reset()
+	}
+	return parent.Execute()
+}
+
+// decodeShortcutData parses the JSON envelope and returns the data map.
+func decodeShortcutData(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
+	t.Helper()
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode output: %v\nraw=%s", err, stdout.String())
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	if data == nil {
+		t.Fatalf("missing data: %#v", envelope)
+	}
+	return data
+}
+
+// withSlidesTestWorkingDir chdirs to dir for this test (restored on cleanup).
+// Not compatible with t.Parallel — chdir is process-wide.
+func withSlidesTestWorkingDir(t *testing.T, dir string) {
+	t.Helper()
+	cwd, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	if err := os.Chdir(dir); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = os.Chdir(cwd)
+	})
+}
+
+type capturedMultipart struct {
+	Fields map[string]string
+	Files  map[string][]byte
+}
+
+func decodeMultipartBody(t *testing.T, stub *httpmock.Stub) capturedMultipart {
+	t.Helper()
+	contentType := stub.CapturedHeaders.Get("Content-Type")
+	mediaType, params, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		t.Fatalf("parse content-type %q: %v", contentType, err)
+	}
+	if mediaType != "multipart/form-data" {
+		t.Fatalf("content type = %q, want multipart/form-data", mediaType)
+	}
+	reader := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
+	body := capturedMultipart{Fields: map[string]string{}, Files: map[string][]byte{}}
+	for {
+		part, err := reader.NextPart()
+		if err != nil {
+			break
+		}
+		data := readAll(t, part)
+		if part.FileName() != "" {
+			body.Files[part.FormName()] = data
+			continue
+		}
+		body.Fields[part.FormName()] = string(data)
+	}
+	return body
+}
+
+func readAll(t *testing.T, r interface {
+	Read(p []byte) (n int, err error)
+}) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	tmp := make([]byte, 4096)
+	for {
+		n, err := r.Read(tmp)
+		if n > 0 {
+			buf.Write(tmp[:n])
+		}
+		if err != nil {
+			break
+		}
+	}
+	return buf.Bytes()
+}

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/task/tasklist_add_task.go

@@ -30,6 +30,7 @@ var AddTaskToTasklist = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "tasklist-id", Desc: "tasklist id", Required: true},
 		{Name: "task-id", Desc: "task id (comma-separated for multiple)", Required: true},
+		{Name: "section-guid", Desc: "section guid"},
 	},
 
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -40,6 +41,10 @@ var AddTaskToTasklist = common.Shortcut{
 			"tasklist_guid": extractTasklistGuid(runtime.Str("tasklist-id")),
 		}
 
+		if sectionGuid := strings.TrimSpace(runtime.Str("section-guid")); sectionGuid != "" {
+			body["section_guid"] = sectionGuid
+		}
+
 		return common.NewDryRunAPI().
 			POST("/open-apis/task/v2/tasks/" + taskId + "/add_tasklist").
 			Params(map[string]interface{}{"user_id_type": "open_id"}).
@@ -57,6 +62,10 @@ var AddTaskToTasklist = common.Shortcut{
 			"tasklist_guid": tasklistGuid,
 		}
 
+		if sectionGuid := strings.TrimSpace(runtime.Str("section-guid")); sectionGuid != "" {
+			body["section_guid"] = sectionGuid
+		}
+
 		var successful []map[string]interface{}
 		var failed []map[string]interface{}
 

shortcuts/task/tasklist_add_task_test.go

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestAddTaskToTasklist_Success(t *testing.T) {
+	f, stdout, _, reg := taskShortcutTestFactory(t)
+	warmTenantToken(t, f, reg)
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/task/v2/tasks/task-1/add_tasklist",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"task": map[string]interface{}{
+					"guid": "task-1",
+				},
+			},
+		},
+	})
+
+	s := AddTaskToTasklist
+	s.AuthTypes = []string{"bot", "user"}
+
+	args := []string{"+tasklist-task-add", "--tasklist-id", "tl-123", "--task-id", "task-1", "--section-guid", "sec-456", "--as", "bot", "--format", "json"}
+	err := runMountedTaskShortcut(t, s, args, f, stdout)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, `"tasklist_guid":"tl-123"`) && !strings.Contains(out, `"tasklist_guid": "tl-123"`) {
+		t.Errorf("expected tasklist_guid in output, got: %s", 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")
 	}
 }