feat(mail): add message modify and trash shortcuts (#1567 )

e2e: harden CLI E2E retry, cleanup, and domain selection (#1709 )
2026-07-08 02:00:19 +08:00 · 2026-07-07 21:44:40 +08:00 · 2026-07-07 19:41:11 +08:00
33 changed files with 2191 additions and 148 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -263,13 +263,19 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          fetch-depth: 0
      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
        with:
          go-version-file: go.mod
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: '3.x'
+      - name: Resolve CLI E2E domains
+        id: e2e_domains
+        run: node scripts/e2e_domains.js
      - name: Build lark-cli
+        if: ${{ steps.e2e_domains.outputs.mode != 'skip' }}
        run: make build
      - name: Run dry-run E2E tests
        env:
@@ -277,7 +283,28 @@ jobs:
          LARKSUITE_CLI_APP_ID: dry-run
          LARKSUITE_CLI_APP_SECRET: dry-run
          LARKSUITE_CLI_BRAND: feishu
-        run: go test -v -count=1 -timeout=5m ./tests/cli_e2e/... -run 'DryRun|Regression'
+          E2E_MODE: ${{ steps.e2e_domains.outputs.mode }}
+          E2E_REASON: ${{ steps.e2e_domains.outputs.reason }}
+          E2E_DRY_ROOT_PACKAGE: ${{ steps.e2e_domains.outputs.dry_root_package }}
+          E2E_DRY_PACKAGES: ${{ steps.e2e_domains.outputs.dry_packages }}
+        run: |
+          if [ "$E2E_MODE" = "skip" ]; then
+            echo "No dry-run CLI E2E needed: $E2E_REASON"
+            exit 0
+          fi
+          if [ -z "$E2E_DRY_ROOT_PACKAGE" ] && [ -z "$E2E_DRY_PACKAGES" ]; then
+            echo "::error::No dry-run CLI E2E packages resolved for mode $E2E_MODE"
+            exit 1
+          fi
+          echo "Dry-run CLI E2E domains: $E2E_MODE ($E2E_REASON)"
+          if [ -n "$E2E_DRY_ROOT_PACKAGE" ]; then
+            echo "Dry-run CLI E2E root package: $E2E_DRY_ROOT_PACKAGE"
+            go test -v -count=1 -timeout=5m "$E2E_DRY_ROOT_PACKAGE"
+          fi
+          if [ -n "$E2E_DRY_PACKAGES" ]; then
+            echo "Dry-run CLI E2E packages: $E2E_DRY_PACKAGES"
+            go test -v -count=1 -timeout=5m $E2E_DRY_PACKAGES -run 'DryRun|Regression'
+          fi

  e2e-live:
    needs: [unit-test, lint, script-test, deterministic-gate]
@@ -292,15 +319,22 @@ jobs:
      TEST_USER_ACCESS_TOKEN: ${{ secrets.TEST_USER_ACCESS_TOKEN }}
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          fetch-depth: 0
      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
        with:
          go-version-file: go.mod
      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: '3.x'
+      - name: Resolve CLI E2E domains
+        id: e2e_domains
+        run: node scripts/e2e_domains.js
      - name: Build lark-cli
+        if: ${{ steps.e2e_domains.outputs.mode != 'skip' }}
        run: make build
      - name: Configure bot credentials
+        if: ${{ steps.e2e_domains.outputs.mode != 'skip' }}
        run: |
          if [ -z "$TEST_BOT1_APP_ID" ] || [ -z "$TEST_BOT1_APP_SECRET" ]; then
            echo "::error::Missing required secrets: TEST_BOT1_APP_ID / TEST_BOT1_APP_SECRET"
@@ -310,16 +344,24 @@ jobs:
      - name: Run CLI E2E tests
        env:
          LARK_CLI_BIN: ${{ github.workspace }}/lark-cli
+          E2E_MODE: ${{ steps.e2e_domains.outputs.mode }}
+          E2E_REASON: ${{ steps.e2e_domains.outputs.reason }}
+          E2E_LIVE_PACKAGES: ${{ steps.e2e_domains.outputs.live_packages }}
        run: |
-          packages=$(go list ./tests/cli_e2e/... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '/demo$')
+          if [ "$E2E_MODE" = "skip" ]; then
+            echo "No live CLI E2E needed: $E2E_REASON"
+            exit 0
+          fi
+          packages="$E2E_LIVE_PACKAGES"
          if [ -z "$packages" ]; then
-            echo "No CLI E2E packages to test after exclusions."
+            echo "::error::No live CLI E2E packages resolved for mode $E2E_MODE"
            exit 1
          fi
-          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
+          echo "Live CLI E2E domains: $E2E_MODE ($E2E_REASON)"
+          echo "Live CLI E2E packages: $packages"
+          go run gotest.tools/gotestsum@v1.12.3 --rerun-fails=2 --rerun-fails-max-failures=20 --packages="$packages" --format testname --junitfile cli-e2e-report.xml -- -count=1 -v
      - name: Publish CLI E2E test report
-        if: ${{ !cancelled() }}
+        if: ${{ !cancelled() && steps.e2e_domains.outputs.mode != 'skip' }}
        uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2 # v3.0.0
        with:
          name: CLI E2E Tests
--- a/2
+++ b/2
@@ -51,7 +51,7 @@ script-test:
 	bash scripts/resolve-changed-from.test.sh
 	bash scripts/ci-workflow.test.sh
 	bash scripts/semantic-review-workflow.test.sh
-	$(NODE) --test scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js
+	$(NODE) --test scripts/e2e_domains.test.js scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js

 # ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta
--- a/cmd/root_integration_test.go
+++ b/cmd/root_integration_test.go
@@ -14,11 +14,13 @@ import (
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
 	"github.com/larksuite/cli/cmd/service"
+	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/meta"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/skillscheck"
 	"github.com/larksuite/cli/internal/update"
@@ -103,6 +105,11 @@ func parseTypedEnvelope(t *testing.T, stderr *bytes.Buffer) typedErrorEnvelope {
 }

 func buildStrictModeIntegrationRootCmd(t *testing.T, f *cmdutil.Factory) *cobra.Command {
+	t.Helper()
+	return buildStrictModeIntegrationRootCmdWithCatalog(t, f, nil)
+}
+
+func buildStrictModeIntegrationRootCmdWithCatalog(t *testing.T, f *cmdutil.Factory, catalog *apicatalog.Catalog) *cobra.Command {
 	t.Helper()
 	rootCmd := &cobra.Command{Use: "lark-cli"}
 	rootCmd.SilenceErrors = true
@@ -113,7 +120,11 @@ func buildStrictModeIntegrationRootCmd(t *testing.T, f *cmdutil.Factory) *cobra.
 	}
 	rootCmd.AddCommand(auth.NewCmdAuth(f))
 	rootCmd.AddCommand(api.NewCmdApi(f, nil))
-	service.RegisterServiceCommands(rootCmd, f)
+	if catalog != nil {
+		service.RegisterServiceCommandsFromCatalog(context.Background(), rootCmd, f, *catalog)
+	} else {
+		service.RegisterServiceCommands(rootCmd, f)
+	}
 	shortcuts.RegisterShortcuts(rootCmd, f)
 	if mode := f.ResolveStrictMode(context.Background()); mode.IsActive() {
 		pruneForStrictMode(rootCmd, mode)
@@ -121,6 +132,29 @@ func buildStrictModeIntegrationRootCmd(t *testing.T, f *cmdutil.Factory) *cobra.
 	return rootCmd
 }

+func strictModeFixtureCatalog() apicatalog.Catalog {
+	return apicatalog.New(apicatalog.SourceEmbedded, []meta.Service{
+		{
+			Name:        "fixture",
+			ServicePath: "/open-apis/fixture/v1",
+			Resources: map[string]meta.Resource{
+				"things": {
+					Methods: map[string]meta.Method{
+						"create": {
+							Path:         "things",
+							HTTPMethod:   "POST",
+							AccessTokens: []meta.Token{meta.TokenTenant},
+							RequestBody: map[string]meta.Field{
+								"name": {Type: "string"},
+							},
+						},
+					},
+				},
+			},
+		},
+	})
+}
+
 func newStrictModeDefaultFactory(t *testing.T, profile string, mode core.StrictMode) (*cmdutil.Factory, *bytes.Buffer, *bytes.Buffer) {
 	t.Helper()
 	t.Setenv(envvars.CliAppID, "")
@@ -355,10 +389,11 @@ func TestIntegration_StrictModeBot_ProfileOverride_ServiceExplicitUserReturnsEnv

 func TestIntegration_StrictModeUser_ProfileOverride_ServiceBotOnlyMethodReturnsEnvelope(t *testing.T) {
 	f, stdout, stderr := newStrictModeDefaultFactory(t, "target", core.StrictModeUser)
-	rootCmd := buildStrictModeIntegrationRootCmd(t, f)
+	catalog := strictModeFixtureCatalog()
+	rootCmd := buildStrictModeIntegrationRootCmdWithCatalog(t, f, &catalog)

 	code := executeRootIntegration(t, f, rootCmd, []string{
-		"im", "images", "create", "--data", `{"image_type":"message","image":"x"}`, "--dry-run",
+		"fixture", "things", "create", "--data", `{"name":"probe"}`, "--dry-run",
 	})

 	if code != output.ExitValidation {
--- a/scripts/ci-workflow.test.sh
+++ b/scripts/ci-workflow.test.sh
@@ -215,6 +215,73 @@ if ! grep -Fq "if: \${{ $fork_safe_guard }}" <<<"$section"; then
  exit 1
 fi

+if ! grep -Fq "name: Resolve CLI E2E domains" <<<"$dry_run_section" ||
+   ! grep -Fq "id: e2e_domains" <<<"$dry_run_section" ||
+   ! grep -Fq "run: node scripts/e2e_domains.js" <<<"$dry_run_section"; then
+  echo "e2e-dry-run should resolve changed-file CLI E2E domains before running tests"
+  exit 1
+fi
+
+if ! grep -Fq "steps.e2e_domains.outputs.dry_packages" <<<"$dry_run_section"; then
+  echo "e2e-dry-run should use resolved dry_packages instead of always running the full suite"
+  exit 1
+fi
+
+if ! grep -Fq "E2E_REASON: \${{ steps.e2e_domains.outputs.reason }}" <<<"$dry_run_section" ||
+   ! grep -Fq 'echo "Dry-run CLI E2E domains: $E2E_MODE ($E2E_REASON)"' <<<"$dry_run_section"; then
+  echo "e2e-dry-run should pass dynamic domain output through env before shell use"
+  exit 1
+fi
+
+if ! grep -Fq "E2E_DRY_ROOT_PACKAGE: \${{ steps.e2e_domains.outputs.dry_root_package }}" <<<"$dry_run_section" ||
+   ! grep -Fq 'go test -v -count=1 -timeout=5m "$E2E_DRY_ROOT_PACKAGE"' <<<"$dry_run_section"; then
+  echo "e2e-dry-run should run the root CLI E2E harness package without the DryRun/Regression filter"
+  exit 1
+fi
+
+if ! grep -Fq "No dry-run CLI E2E needed" <<<"$dry_run_section"; then
+  echo "e2e-dry-run should explicitly skip when domain mode is skip"
+  exit 1
+fi
+
+if ! grep -Fq "name: Resolve CLI E2E domains" <<<"$section" ||
+   ! grep -Fq "id: e2e_domains" <<<"$section" ||
+   ! grep -Fq "run: node scripts/e2e_domains.js" <<<"$section"; then
+  echo "e2e-live should resolve changed-file CLI E2E domains before credentials and tests"
+  exit 1
+fi
+
+if ! grep -Fq "steps.e2e_domains.outputs.live_packages" <<<"$section"; then
+  echo "e2e-live should use resolved live_packages instead of always running the full suite"
+  exit 1
+fi
+
+if ! grep -Fq "E2E_REASON: \${{ steps.e2e_domains.outputs.reason }}" <<<"$section" ||
+   ! grep -Fq 'echo "Live CLI E2E domains: $E2E_MODE ($E2E_REASON)"' <<<"$section"; then
+  echo "e2e-live should pass dynamic domain output through env before shell use"
+  exit 1
+fi
+
+if ! awk '
+  /^      - name: Build lark-cli/ { in_step = 1 }
+  in_step && /if: \$\{\{ steps\.e2e_domains\.outputs\.mode != '\''skip'\'' \}\}/ { found = 1 }
+  in_step && /^      - name:/ && !/Build lark-cli/ { in_step = 0 }
+  END { exit found ? 0 : 1 }
+' <<<"$dry_run_section"; then
+  echo "e2e-dry-run should skip building lark-cli when domain mode is skip"
+  exit 1
+fi
+
+if ! awk '
+  /^      - name: Build lark-cli/ { in_step = 1 }
+  in_step && /if: \$\{\{ steps\.e2e_domains\.outputs\.mode != '\''skip'\'' \}\}/ { found = 1 }
+  in_step && /^      - name:/ && !/Build lark-cli/ { in_step = 0 }
+  END { exit found ? 0 : 1 }
+' <<<"$section"; then
+  echo "e2e-live should skip building lark-cli when domain mode is skip"
+  exit 1
+fi
+
 if ! grep -Fq "permissions:" <<<"$section" ||
   ! grep -Fq "contents: read" <<<"$section" ||
   ! grep -Fq "checks: write" <<<"$section"; then
@@ -237,13 +304,23 @@ if ! grep -Fq "::error::Missing required secrets: TEST_BOT1_APP_ID / TEST_BOT1_A
  exit 1
 fi

+if ! awk '
+  /^      - name: Configure bot credentials/ { in_step = 1 }
+  in_step && /if: \$\{\{ steps\.e2e_domains\.outputs\.mode != '\''skip'\'' \}\}/ { found = 1 }
+  in_step && /^      - name:/ && !/Configure bot credentials/ { in_step = 0 }
+  END { exit found ? 0 : 1 }
+' <<<"$section"; then
+  echo "e2e-live should only configure bot credentials when domain mode is not skip"
+  exit 1
+fi
+
 if grep -Fq "steps.live_e2e_credentials.outputs.configured" <<<"$section"; then
  echo "e2e-live build, configure, test, and report steps should not be gated by a skip-state output"
  exit 1
 fi

-if ! grep -Fq "if: \${{ !cancelled() }}" <<<"$section"; then
-  echo "e2e-live report step should run after attempted live tests unless the workflow is cancelled"
+if ! grep -Fq "if: \${{ !cancelled() && steps.e2e_domains.outputs.mode != 'skip' }}" <<<"$section"; then
+  echo "e2e-live report step should run after attempted live tests unless the workflow is cancelled or domain mode is skip"
  exit 1
 fi

--- a/scripts/domain-map.js
+++ b/scripts/domain-map.js
@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const DOMAIN_MAP_PATH = path.join(__dirname, "domain-map.json");
+const domainMap = JSON.parse(fs.readFileSync(DOMAIN_MAP_PATH, "utf8"));
+
+function normalizeRepoPath(input) {
+  return String(input || "").trim().replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
+}
+
+const pathMappingsBySpecificity = (domainMap.pathMappings || [])
+  .map((entry) => ({ ...entry, prefix: normalizeRepoPath(entry.prefix) }))
+  .sort((a, b) => b.prefix.length - a.prefix.length);
+
+function findPathMapping(filePath) {
+  const normalized = normalizeRepoPath(filePath);
+  return pathMappingsBySpecificity.find((entry) => normalized.startsWith(entry.prefix));
+}
+
+function labelDomainsForPath(filePath) {
+  const mapping = findPathMapping(filePath);
+  return mapping ? [...(mapping.labelDomains || [])] : [];
+}
+
+function e2eDomainsForPath(filePath) {
+  const mapping = findPathMapping(filePath);
+  return mapping ? [...(mapping.e2eDomains || [])] : [];
+}
+
+function matchesFullFallback(filePath) {
+  const normalized = normalizeRepoPath(filePath);
+  return (domainMap.fullFallbackPrefixes || []).some((prefix) => normalized.startsWith(prefix));
+}
+
+function isSkippablePath(filePath) {
+  const normalized = normalizeRepoPath(filePath);
+  const basename = path.posix.basename(normalized);
+  return (domainMap.skipPrefixes || []).some((prefix) => normalized.startsWith(prefix))
+    || (domainMap.skipSuffixes || []).some((suffix) => normalized.endsWith(suffix))
+    || (domainMap.skipFilenames || []).includes(basename);
+}
+
+module.exports = {
+  domainMap,
+  e2eDomainsForPath,
+  findPathMapping,
+  isSkippablePath,
+  labelDomainsForPath,
+  matchesFullFallback,
+  normalizeRepoPath,
+};
--- a/scripts/domain-map.json
+++ b/scripts/domain-map.json
@@ -0,0 +1,71 @@
+{
+  "pathMappings": [
+    { "prefix": "shortcuts/im/", "labelDomains": ["im"], "e2eDomains": ["im"] },
+    { "prefix": "shortcuts/vc/", "labelDomains": ["vc"], "e2eDomains": ["vc"] },
+    { "prefix": "shortcuts/calendar/", "labelDomains": ["calendar"], "e2eDomains": ["calendar"] },
+    { "prefix": "shortcuts/doc/", "labelDomains": ["ccm"], "e2eDomains": ["docs"] },
+    { "prefix": "shortcuts/sheets/", "labelDomains": ["ccm"], "e2eDomains": ["sheets"] },
+    { "prefix": "shortcuts/drive/", "labelDomains": ["ccm"], "e2eDomains": ["drive"] },
+    { "prefix": "shortcuts/wiki/", "labelDomains": ["ccm"], "e2eDomains": ["wiki"] },
+    { "prefix": "shortcuts/base/", "labelDomains": ["base"], "e2eDomains": ["base"] },
+    { "prefix": "shortcuts/mail/", "labelDomains": ["mail"], "e2eDomains": ["mail"] },
+    { "prefix": "shortcuts/task/", "labelDomains": ["task"], "e2eDomains": ["task"] },
+    { "prefix": "shortcuts/contact/", "labelDomains": ["contact"], "e2eDomains": ["contact"] },
+    { "prefix": "shortcuts/apps/", "labelDomains": [], "e2eDomains": ["apps"] },
+    { "prefix": "shortcuts/markdown/", "labelDomains": [], "e2eDomains": ["markdown"] },
+    { "prefix": "shortcuts/minutes/", "labelDomains": [], "e2eDomains": ["minutes"] },
+    { "prefix": "shortcuts/okr/", "labelDomains": [], "e2eDomains": ["okr"] },
+    { "prefix": "shortcuts/slides/", "labelDomains": [], "e2eDomains": ["slides"] },
+    { "prefix": "shortcuts/note/", "labelDomains": [], "e2eDomains": ["note"] },
+    { "prefix": "shortcuts/event/", "labelDomains": [], "e2eDomains": ["event"] },
+
+    { "prefix": "skills/lark-im/", "labelDomains": ["im"], "e2eDomains": ["im"] },
+    { "prefix": "skills/lark-vc/", "labelDomains": ["vc"], "e2eDomains": ["vc"] },
+    { "prefix": "skills/lark-doc/", "labelDomains": ["ccm"], "e2eDomains": ["docs"] },
+    { "prefix": "skills/lark-wiki/", "labelDomains": ["ccm"], "e2eDomains": ["wiki"] },
+    { "prefix": "skills/lark-drive/", "labelDomains": ["ccm"], "e2eDomains": ["drive"] },
+    { "prefix": "skills/lark-sheets/", "labelDomains": ["ccm"], "e2eDomains": ["sheets"] },
+    { "prefix": "skills/lark-base/", "labelDomains": ["base"], "e2eDomains": ["base"] },
+    { "prefix": "skills/lark-mail/", "labelDomains": ["mail"], "e2eDomains": ["mail"] },
+    { "prefix": "skills/lark-calendar/", "labelDomains": ["calendar"], "e2eDomains": ["calendar"] },
+    { "prefix": "skills/lark-task/", "labelDomains": ["task"], "e2eDomains": ["task"] },
+    { "prefix": "skills/lark-contact/", "labelDomains": ["contact"], "e2eDomains": ["contact"] },
+    { "prefix": "skills/lark-apps/", "labelDomains": [], "e2eDomains": ["apps"] },
+    { "prefix": "skills/lark-markdown/", "labelDomains": [], "e2eDomains": ["markdown"] },
+    { "prefix": "skills/lark-minutes/", "labelDomains": [], "e2eDomains": ["minutes"] },
+    { "prefix": "skills/lark-okr/", "labelDomains": [], "e2eDomains": ["okr"] },
+    { "prefix": "skills/lark-slides/", "labelDomains": [], "e2eDomains": ["slides"] },
+    { "prefix": "skills/lark-note/", "labelDomains": [], "e2eDomains": ["note"] },
+    { "prefix": "skills/lark-event/", "labelDomains": [], "e2eDomains": ["event"] }
+  ],
+  "fullFallbackPrefixes": [
+    "shortcuts/common/",
+    "cmd/",
+    "internal/",
+    "pkg/",
+    "extension/",
+    "registry/",
+    "go.mod",
+    "go.sum",
+    "Makefile",
+    ".github/workflows/",
+    "scripts/"
+  ],
+  "skipPrefixes": [
+    "docs/",
+    ".changeset/"
+  ],
+  "skipSuffixes": [
+    ".md",
+    ".mdx",
+    ".txt",
+    ".rst"
+  ],
+  "skipFilenames": [
+    "readme.md",
+    "readme.zh.md",
+    "changelog.md",
+    "license",
+    "cla.md"
+  ]
+}
--- a/scripts/e2e_domains.js
+++ b/scripts/e2e_domains.js
@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { execFileSync } = require("node:child_process");
+const {
+  e2eDomainsForPath,
+  findPathMapping,
+  isSkippablePath,
+  matchesFullFallback,
+  normalizeRepoPath,
+} = require("./domain-map");
+
+const ROOT = process.env.E2E_DOMAINS_ROOT || path.join(__dirname, "..");
+process.chdir(ROOT);
+
+function execLines(command, args) {
+  return execFileSync(command, args, { encoding: "utf8" })
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function modulePath() {
+  return execLines("go", ["list", "-m"])[0];
+}
+
+function rootPackage(moduleName) {
+  return `${moduleName}/tests/cli_e2e`;
+}
+
+function allLivePackages(moduleName) {
+  return execLines("go", ["list", "./tests/cli_e2e/..."])
+    .filter((pkg) => pkg !== rootPackage(moduleName))
+    .filter((pkg) => !pkg.endsWith("/demo"));
+}
+
+function allDryPackages(moduleName) {
+  return allLivePackages(moduleName);
+}
+
+const domainExistsCache = new Map();
+
+function domainExists(domain) {
+  if (domainExistsCache.has(domain)) {
+    return domainExistsCache.get(domain);
+  }
+  let exists = false;
+  try {
+    execFileSync("go", ["list", `./tests/cli_e2e/${domain}`], { stdio: "ignore" });
+    exists = true;
+  } catch {
+    exists = false;
+  }
+  domainExistsCache.set(domain, exists);
+  return exists;
+}
+
+function readChangedFiles() {
+  const changedFilesPath = process.env.E2E_DOMAIN_CHANGED_FILES;
+  if (changedFilesPath) {
+    return fs.readFileSync(changedFilesPath, "utf8")
+      .split(/\r?\n/)
+      .map(normalizeRepoPath)
+      .filter(Boolean);
+  }
+
+  if (process.env.GITHUB_EVENT_NAME !== "pull_request") {
+    return null;
+  }
+
+  const baseRef = process.env.GITHUB_BASE_REF || "main";
+  try {
+    execFileSync("git", ["rev-parse", "--verify", `origin/${baseRef}`], { stdio: "ignore" });
+    return execLines("git", ["diff", "--name-only", `origin/${baseRef}...HEAD`]).map(normalizeRepoPath);
+  } catch {
+    return null;
+  }
+}
+
+function addDomain(domains, domain) {
+  if (domain && domainExists(domain)) {
+    domains.add(domain);
+    return true;
+  }
+  return false;
+}
+
+function classifyPath(filePath, domains) {
+  const normalized = normalizeRepoPath(filePath);
+  if (!normalized) return { matched: false };
+
+  const e2eMatch = normalized.match(/^tests\/cli_e2e\/([^/]+)\//);
+  if (e2eMatch) {
+    const domain = e2eMatch[1];
+    if (domain === "demo") return { matched: false };
+    if (domainExists(domain)) {
+      addDomain(domains, domain);
+      return { matched: true };
+    }
+    if (isSkippablePath(normalized)) return { matched: false };
+    return { fullReason: `unknown CLI E2E domain path: ${normalized}` };
+  }
+
+  if (normalized.startsWith("tests/cli_e2e/")) {
+    return { fullReason: `shared CLI E2E harness changed: ${normalized}` };
+  }
+
+  if (matchesFullFallback(normalized)) {
+    return { fullReason: `shared/runtime path changed: ${normalized}` };
+  }
+
+  const mappedDomains = e2eDomainsForPath(normalized);
+  if (mappedDomains.length > 0) {
+    const missingDomains = [];
+    for (const domain of mappedDomains) {
+      if (!addDomain(domains, domain)) missingDomains.push(domain);
+    }
+    if (missingDomains.length > 0) {
+      return { fullReason: `mapped CLI E2E domain has no package: ${missingDomains.join(",")} (${normalized})` };
+    }
+    return { matched: true };
+  }
+
+  if (findPathMapping(normalized)) {
+    return { fullReason: `mapped path has no CLI E2E package: ${normalized}` };
+  }
+
+  if (normalized.match(/^shortcuts\/[^/]+\//) || normalized.match(/^skills\/lark-[^/]+\//)) {
+    return { fullReason: `unmapped CLI E2E domain path: ${normalized}` };
+  }
+
+  if (isSkippablePath(normalized)) return { matched: false };
+
+  return { fullReason: `unclassified path changed: ${normalized}` };
+}
+
+function resolveDomains(changedFiles) {
+  const moduleName = modulePath();
+  const rootDryPackage = rootPackage(moduleName);
+  if (changedFiles === null) {
+    return {
+      mode: "full",
+      reason: "non-pull_request run or unavailable diff",
+      domains: ["all"],
+      dryRootPackage: rootDryPackage,
+      dryPackages: allDryPackages(moduleName),
+      livePackages: allLivePackages(moduleName),
+    };
+  }
+
+  const domains = new Set();
+  let matchedRelevant = false;
+  let fullReason = "";
+
+  for (const file of changedFiles) {
+    const result = classifyPath(file, domains);
+    if (result.matched) matchedRelevant = true;
+    if (result.fullReason && !fullReason) fullReason = result.fullReason;
+  }
+
+  if (fullReason) {
+    return {
+      mode: "full",
+      reason: fullReason,
+      domains: ["all"],
+      dryRootPackage: rootDryPackage,
+      dryPackages: allDryPackages(moduleName),
+      livePackages: allLivePackages(moduleName),
+    };
+  }
+
+  if (matchedRelevant && domains.size > 0) {
+    const sortedDomains = [...domains].sort();
+    const packages = sortedDomains.map((domain) => `${moduleName}/tests/cli_e2e/${domain}`);
+    return {
+      mode: "subset",
+      reason: "business domain changes",
+      domains: sortedDomains,
+      dryRootPackage: rootDryPackage,
+      dryPackages: packages,
+      livePackages: packages,
+    };
+  }
+
+  return {
+    mode: "skip",
+    reason: "docs-only or no live CLI E2E impact",
+    domains: [],
+    dryRootPackage: "",
+    dryPackages: [],
+    livePackages: [],
+  };
+}
+
+function emit(resolved) {
+  const values = {
+    mode: resolved.mode,
+    reason: resolved.reason,
+    domains: resolved.domains.join(","),
+    dry_root_package: resolved.dryRootPackage,
+    dry_packages: resolved.dryPackages.join(" "),
+    live_packages: resolved.livePackages.join(" "),
+  };
+
+  const lines = Object.entries(values).map(([key, value]) => `${key}=${value}`);
+  console.log(lines.join("\n"));
+
+  if (process.env.GITHUB_OUTPUT) {
+    fs.appendFileSync(process.env.GITHUB_OUTPUT, `${lines.join("\n")}\n`);
+  }
+}
+
+if (require.main === module) {
+  emit(resolveDomains(readChangedFiles()));
+}
+
+module.exports = {
+  classifyPath,
+  readChangedFiles,
+  resolveDomains,
+};
--- a/scripts/e2e_domains.test.js
+++ b/scripts/e2e_domains.test.js
@@ -0,0 +1,94 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { execFileSync } = require("node:child_process");
+const test = require("node:test");
+
+const scriptPath = path.join(__dirname, "e2e_domains.js");
+
+function parseOutput(raw) {
+  const result = {};
+  for (const line of raw.trim().split(/\r?\n/)) {
+    const idx = line.indexOf("=");
+    if (idx === -1) continue;
+    result[line.slice(0, idx)] = line.slice(idx + 1);
+  }
+  return result;
+}
+
+function runDomains(files) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "e2e-domains-"));
+  const file = path.join(dir, "changed.txt");
+  fs.writeFileSync(file, `${files.join("\n")}\n`);
+  try {
+    return parseOutput(execFileSync(process.execPath, [scriptPath], {
+      cwd: path.join(__dirname, ".."),
+      encoding: "utf8",
+      env: { ...process.env, E2E_DOMAIN_CHANGED_FILES: file },
+    }));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("maps shortcut changes to one business domain package", () => {
+  const output = runDomains(["shortcuts/im/messages/send.go"]);
+  assert.equal(output.mode, "subset");
+  assert.equal(output.domains, "im");
+  assert.match(output.dry_root_package, /github\.com\/larksuite\/cli\/tests\/cli_e2e$/);
+  assert.match(output.live_packages, /github\.com\/larksuite\/cli\/tests\/cli_e2e\/im/);
+  assert.doesNotMatch(output.live_packages, /github\.com\/larksuite\/cli\/tests\/cli_e2e\/drive/);
+});
+
+test("maps doc shortcuts to docs package", () => {
+  const output = runDomains(["shortcuts/doc/update.go"]);
+  assert.equal(output.mode, "subset");
+  assert.equal(output.domains, "docs");
+  assert.match(output.live_packages, /github\.com\/larksuite\/cli\/tests\/cli_e2e\/docs/);
+});
+
+test("maps direct e2e domain package changes", () => {
+  const output = runDomains(["tests/cli_e2e/drive/helpers.go"]);
+  assert.equal(output.mode, "subset");
+  assert.equal(output.domains, "drive");
+  assert.match(output.live_packages, /github\.com\/larksuite\/cli\/tests\/cli_e2e\/drive/);
+});
+
+test("falls back to full for shared e2e harness changes", () => {
+  const output = runDomains(["tests/cli_e2e/core.go"]);
+  assert.equal(output.mode, "full");
+  assert.equal(output.domains, "all");
+  assert.match(output.reason, /shared CLI E2E harness changed/);
+});
+
+test("falls back to full for runtime changes", () => {
+  const output = runDomains(["cmd/root.go"]);
+  assert.equal(output.mode, "full");
+  assert.equal(output.domains, "all");
+  assert.match(output.reason, /shared\/runtime path changed/);
+});
+
+test("skips docs-only changes", () => {
+  const output = runDomains(["docs/usage.md", "README.md"]);
+  assert.equal(output.mode, "skip");
+  assert.equal(output.domains, "");
+  assert.equal(output.dry_root_package, "");
+  assert.equal(output.live_packages, "");
+});
+
+test("uses shared map for skill domain changes", () => {
+  const output = runDomains(["skills/lark-sheets/SKILL.md"]);
+  assert.equal(output.mode, "subset");
+  assert.equal(output.domains, "sheets");
+  assert.match(output.live_packages, /github\.com\/larksuite\/cli\/tests\/cli_e2e\/sheets/);
+});
+
+test("falls back to full when a mapped path has no e2e package", () => {
+  const output = runDomains(["shortcuts/whiteboard/export.go"]);
+  assert.equal(output.mode, "full");
+  assert.match(output.reason, /unmapped CLI E2E domain path/);
+});
--- a/scripts/pr-labels/index.js
+++ b/scripts/pr-labels/index.js
@@ -4,6 +4,7 @@

 const fs = require("node:fs/promises");
 const path = require("node:path");
+const { labelDomainsForPath } = require("../domain-map");

 // ============================================================================
 // Constants & Configuration
@@ -35,33 +36,6 @@ const CORE_PREFIXES = ["internal/auth/", "internal/engine/", "internal/config/",
 const HEAD_BUSINESS_DOMAINS = new Set(["im", "contact", "ccm", "base", "docx"]);
 const LOW_RISK_TYPES = new Set(["docs", "ci", "test", "chore"]);

-// CODEOWNERS-based path to domain label mapping
-// Maps shortcuts and skills paths to business domain labels
-const PATH_TO_DOMAIN_MAP = {
-  // shortcuts
-  "shortcuts/im/": "im",
-  "shortcuts/vc/": "vc",
-  "shortcuts/calendar/": "calendar",
-  "shortcuts/doc/": "ccm",
-  "shortcuts/sheets/": "ccm",
-  "shortcuts/drive/": "ccm",
-  "shortcuts/wiki/": "ccm",
-  "shortcuts/base/": "base",
-  "shortcuts/mail/": "mail",
-  "shortcuts/task/": "task",
-  "shortcuts/contact/": "contact",
-  // skills
-  "skills/lark-im/": "im",
-  "skills/lark-vc/": "vc",
-  "skills/lark-doc/": "ccm",
-  "skills/lark-wiki/": "ccm",
-  "skills/lark-base/": "base",
-  "skills/lark-mail/": "mail",
-  "skills/lark-calendar/": "calendar",
-  "skills/lark-task/": "task",
-  "skills/lark-contact/": "contact",
-};
-
 const SENSITIVE_PATTERN = /(^|\/)(auth|permission|permissions|security)(\/|_|\.|$)/;

 const CLASS_STANDARDS = {
@@ -285,13 +259,7 @@ function skillDomainForPath(filePath) {

 // Get business domain label based on CODEOWNERS path mapping
 function getBusinessDomain(filePath) {
-  const normalized = normalizePath(filePath);
-  for (const [prefix, domain] of Object.entries(PATH_TO_DOMAIN_MAP)) {
-    if (normalized.startsWith(prefix)) {
-      return domain;
-    }
-  }
-  return "";
+  return labelDomainsForPath(filePath)[0] || "";
 }

 async function detectNewShortcutDomain(files) {
--- a/scripts/resolve-changed-from.test.sh
+++ b/scripts/resolve-changed-from.test.sh
@@ -8,7 +8,17 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 script="$repo_root/scripts/resolve-changed-from.sh"

 tmp="${TMPDIR:-/tmp}/resolve-changed-from-test-$$"
-trap 'rm -rf "$tmp"' EXIT
+
+cleanup_tmp() {
+  local attempt
+  for attempt in 1 2 3; do
+    rm -rf "$tmp" && return 0
+    sleep 1
+  done
+  rm -rf "$tmp"
+}
+
+trap cleanup_tmp EXIT
 mkdir -p "$tmp"

 git_init() {
--- a/shortcuts/mail/helpers.go
+++ b/shortcuts/mail/helpers.go
@@ -51,9 +51,8 @@ func hintSendDraft(runtime *common.RuntimeContext, mailboxID, draftID string) {
 // original message as read after a reply/reply-all/forward operation.
 func hintMarkAsRead(runtime *common.RuntimeContext, mailboxID, originalMessageID string) {
 	fmt.Fprintf(runtime.IO().ErrOut,
-		"tip: mark original as read? lark-cli mail user_mailbox.messages batch_modify_message"+
-			` --params '{"user_mailbox_id":"%s"}' --data '{"message_ids":["%s"],"remove_label_ids":["UNREAD"]}'`+"\n",
-		sanitizeForTerminal(mailboxID), sanitizeForTerminal(originalMessageID))
+		"tip: mark original as read? lark-cli mail +message-modify --mailbox '%s' --message-ids '%s' --remove-label-ids UNREAD\n",
+		shellQuoteForHint(mailboxID), shellQuoteForHint(originalMessageID))
 }

 // hintReadReceiptRequest prints a stderr tip when a message that the caller
--- a/shortcuts/mail/helpers_test.go
+++ b/shortcuts/mail/helpers_test.go
@@ -465,14 +465,19 @@ func TestPrintWatchOutputSchema(t *testing.T) {
 // TestHintMarkAsRead verifies hint mark as read.
 func TestHintMarkAsRead(t *testing.T) {
 	rt, _, stderr := newOutputRuntime(t)
-	// Inject ANSI escape + message ID to verify sanitization
-	hintMarkAsRead(rt, "me", "msg-\x1b[31m123")
+	hintMarkAsRead(rt, "mail box;$(whoami)", "msg-\x1b[31m123 'quoted'\nnext")
 	out := stderr.String()
 	if strings.Contains(out, "\x1b[") {
 		t.Errorf("hintMarkAsRead should sanitize ANSI escapes, got: %q", out)
 	}
-	if !strings.Contains(out, "msg-123") {
-		t.Errorf("hintMarkAsRead should contain sanitized message ID, got: %q", out)
+	if strings.Contains(out, "\nnext") {
+		t.Errorf("hintMarkAsRead should strip embedded newlines, got: %q", out)
+	}
+	if !strings.Contains(out, "--mailbox 'mail box;$(whoami)'") {
+		t.Errorf("hintMarkAsRead should quote mailbox for shell copy/paste, got: %q", out)
+	}
+	if !strings.Contains(out, "--message-ids 'msg-123 '\\''quoted'\\''next'") {
+		t.Errorf("hintMarkAsRead should quote message ID for shell copy/paste, got: %q", out)
 	}
 }

--- a/shortcuts/mail/mail_message_manage_test.go
+++ b/shortcuts/mail/mail_message_manage_test.go
@@ -0,0 +1,482 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func messageManageID(suffix string) string {
+	return "msg_abcdefghijklmnop_" + suffix
+}
+
+func stubMessageManagePost(reg *httpmock.Registry, endpoint string, body map[string]interface{}) *httpmock.Stub {
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/user_mailboxes/me/messages/" + endpoint,
+		Body:   body,
+	}
+	reg.Register(stub)
+	return stub
+}
+
+func decodeMessageManageSummary(t *testing.T, data map[string]interface{}) ([]interface{}, []interface{}) {
+	t.Helper()
+	success, ok := data["success_message_ids"].([]interface{})
+	if !ok {
+		t.Fatalf("success_message_ids = %#v, want array", data["success_message_ids"])
+	}
+	failed, ok := data["failed_message_ids"].([]interface{})
+	if !ok {
+		t.Fatalf("failed_message_ids = %#v, want array", data["failed_message_ids"])
+	}
+	return success, failed
+}
+
+func requireMessageManageValidationParam(t *testing.T, err error, param string) *errs.ValidationError {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("expected validation error for %s, got nil", param)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError for %s, got %T", param, err)
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed Problem for %s, got %T", param, err)
+	}
+	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("problem = %s/%s, want validation/invalid_argument", problem.Category, problem.Subtype)
+	}
+	if validationErr.Param != param {
+		t.Fatalf("param = %q, want %q", validationErr.Param, param)
+	}
+	return validationErr
+}
+
+func requireMessageManageFailedPrecondition(t *testing.T, err error) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected failed precondition error, got nil")
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed Problem, got %T", err)
+	}
+	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("problem = %s/%s, want validation/failed_precondition", problem.Category, problem.Subtype)
+	}
+}
+
+func TestMessageManage_NormalizeMessageIDs(t *testing.T) {
+	id1 := messageManageID("1")
+	id2 := messageManageID("2")
+	got, err := normalizeMessageManageIDs([]string{id1, id2, id1})
+	if err != nil {
+		t.Fatalf("normalizeMessageManageIDs returned error: %v", err)
+	}
+	if len(got) != 2 || got[0] != id1 || got[1] != id2 {
+		t.Fatalf("ids = %v, want [%s %s]", got, id1, id2)
+	}
+	got, err = normalizeMessageManageIDs([]string{id1 + "," + id2, id1})
+	if err != nil {
+		t.Fatalf("normalizeMessageManageIDs CSV/repeated returned error: %v", err)
+	}
+	if len(got) != 2 || got[0] != id1 || got[1] != id2 {
+		t.Fatalf("CSV/repeated ids = %v, want [%s %s]", got, id1, id2)
+	}
+
+	cases := [][]string{
+		{""},
+		{" id_with_leading_space_12345"},
+		{"msg_abcdefghijklmnop_1,msg_abcdefghijklmnop_2 "},
+		{"1234567890123456"},
+		{"short"},
+		{"msg_abcdefghijklmnop!"},
+		{"msg_abcdefghijklmnop\t"},
+		{"msg_abcdefghijklmnop_1\nmsg_abcdefghijklmnop_2"},
+		{"msg_abcdefghijklmnop_1", "msg_abcdefghijklmnop_2 "},
+	}
+	for _, tc := range cases {
+		_, err := normalizeMessageManageIDs(tc)
+		requireMessageManageValidationParam(t, err, "--message-ids")
+	}
+}
+
+func TestMessageModify_Metadata(t *testing.T) {
+	if MailMessageModify.Command != "+message-modify" {
+		t.Fatalf("Command = %q", MailMessageModify.Command)
+	}
+	if MailMessageModify.Risk != "write" {
+		t.Errorf("Risk = %q, want write", MailMessageModify.Risk)
+	}
+	if len(MailMessageModify.AuthTypes) != 1 || MailMessageModify.AuthTypes[0] != "user" {
+		t.Errorf("AuthTypes = %v, want [user]", MailMessageModify.AuthTypes)
+	}
+	requiredScopes := map[string]bool{
+		"mail:user_mailbox.message:modify": true,
+	}
+	for _, scope := range MailMessageModify.Scopes {
+		delete(requiredScopes, scope)
+	}
+	if len(requiredScopes) != 0 {
+		t.Errorf("Scopes missing %v", requiredScopes)
+	}
+	if len(MailMessageModify.ConditionalScopes) != 1 || MailMessageModify.ConditionalScopes[0] != "mail:user_mailbox.folder:read" {
+		t.Errorf("ConditionalScopes = %v, want [mail:user_mailbox.folder:read]", MailMessageModify.ConditionalScopes)
+	}
+	flags := map[string]common.Flag{}
+	for _, fl := range MailMessageModify.Flags {
+		flags[fl.Name] = fl
+	}
+	for _, name := range []string{"mailbox", "message-ids", "add-label-ids", "remove-label-ids", "add-folder"} {
+		if _, ok := flags[name]; !ok {
+			t.Fatalf("missing --%s flag", name)
+		}
+	}
+	if flags["message-ids"].Type != "string_array" || !flags["message-ids"].Required {
+		t.Errorf("--message-ids = %#v, want required string_array", flags["message-ids"])
+	}
+}
+
+func TestMessageTrash_Metadata(t *testing.T) {
+	if MailMessageTrash.Command != "+message-trash" {
+		t.Fatalf("Command = %q", MailMessageTrash.Command)
+	}
+	if MailMessageTrash.Risk != "high-risk-write" {
+		t.Errorf("Risk = %q, want high-risk-write", MailMessageTrash.Risk)
+	}
+	if len(MailMessageTrash.AuthTypes) != 1 || MailMessageTrash.AuthTypes[0] != "user" {
+		t.Errorf("AuthTypes = %v, want [user]", MailMessageTrash.AuthTypes)
+	}
+	if len(MailMessageTrash.Scopes) != 1 || MailMessageTrash.Scopes[0] != "mail:user_mailbox.message:modify" {
+		t.Errorf("Scopes = %v, want [mail:user_mailbox.message:modify]", MailMessageTrash.Scopes)
+	}
+}
+
+func TestMessageModify_LabelOnlyDoesNotRequireFolderReadScope(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	token := auth.GetStoredToken("test-app", "ou_testuser")
+	if token == nil {
+		t.Fatal("expected test token")
+	}
+	token.Scope = strings.ReplaceAll(token.Scope, " mail:user_mailbox.folder:read", "")
+	if err := auth.SetStoredToken(token); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	id := messageManageID("1")
+	post := stubMessageManagePost(reg, "batch_modify", map[string]interface{}{"code": 0, "data": map[string]interface{}{}})
+
+	err := runMountedMailShortcut(t, MailMessageModify, []string{
+		"+message-modify",
+		"--message-ids", id,
+		"--remove-label-ids", "UNREAD",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(post.CapturedBody, &body); err != nil {
+		t.Fatalf("unmarshal captured body: %v", err)
+	}
+	removeLabels := body["remove_label_ids"].([]interface{})
+	if len(removeLabels) != 1 || removeLabels[0] != "UNREAD" {
+		t.Fatalf("remove_label_ids = %#v, want [UNREAD]", removeLabels)
+	}
+}
+
+func TestMessageModify_ReadReceiptRequestLabelIsSystemLabel(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	id := messageManageID("1")
+	post := stubMessageManagePost(reg, "batch_modify", map[string]interface{}{"code": 0, "data": map[string]interface{}{}})
+
+	err := runMountedMailShortcut(t, MailMessageModify, []string{
+		"+message-modify",
+		"--message-ids", id,
+		"--remove-label-ids", "read_receipt_request",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(post.CapturedBody, &body); err != nil {
+		t.Fatalf("unmarshal captured body: %v", err)
+	}
+	removeLabels := body["remove_label_ids"].([]interface{})
+	if len(removeLabels) != 1 || removeLabels[0] != "READ_RECEIPT_REQUEST" {
+		t.Fatalf("remove_label_ids = %#v, want [READ_RECEIPT_REQUEST]", removeLabels)
+	}
+}
+
+func TestMessageModify_LabelFolderNormalizationAndValidationAPIs(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	id := messageManageID("1")
+	reg.Register(&httpmock.Stub{Method: "GET", URL: "/user_mailboxes/me/labels/customA", Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"label_id": "customA"}}})
+	reg.Register(&httpmock.Stub{Method: "GET", URL: "/user_mailboxes/me/folders/folderA", Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"folder_id": "folderA"}}})
+	post := stubMessageManagePost(reg, "batch_modify", map[string]interface{}{"code": 0, "data": map[string]interface{}{}})
+
+	err := runMountedMailShortcut(t, MailMessageModify, []string{
+		"+message-modify",
+		"--message-ids", id,
+		"--add-label-ids", "unread,customA",
+		"--remove-label-ids", "FLAGGED",
+		"--add-folder", "folderA",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(post.CapturedBody, &body); err != nil {
+		t.Fatalf("unmarshal captured body: %v", err)
+	}
+	if got := body["add_folder"]; got != "folderA" {
+		t.Errorf("add_folder = %v, want folderA", got)
+	}
+	addLabels := body["add_label_ids"].([]interface{})
+	if addLabels[0] != "UNREAD" || addLabels[1] != "customA" {
+		t.Errorf("add_label_ids = %#v, want [UNREAD customA]", addLabels)
+	}
+	removeLabels := body["remove_label_ids"].([]interface{})
+	if removeLabels[0] != "FLAGGED" {
+		t.Errorf("remove_label_ids = %#v, want [FLAGGED]", removeLabels)
+	}
+	success, failed := decodeMessageManageSummary(t, decodeShortcutEnvelopeData(t, stdout))
+	if len(success) != 1 || success[0] != id || len(failed) != 0 {
+		t.Errorf("summary success=%v failed=%v", success, failed)
+	}
+}
+
+func TestMessageModify_RejectsLabelIntersectionAndTrashFolder(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	id := messageManageID("1")
+	err := runMountedMailShortcut(t, MailMessageModify, []string{
+		"+message-modify",
+		"--message-ids", id,
+		"--add-label-ids", "unread",
+		"--remove-label-ids", "UNREAD",
+	}, f, stdout)
+	requireMessageManageValidationParam(t, err, "--add-label-ids")
+	if !strings.Contains(err.Error(), "label cannot be both added and removed") {
+		t.Fatalf("error = %v, want label intersection validation", err)
+	}
+
+	err = runMountedMailShortcut(t, MailMessageModify, []string{
+		"+message-modify",
+		"--message-ids", id,
+		"--add-folder", "trash",
+	}, f, stdout)
+	requireMessageManageValidationParam(t, err, "--add-folder")
+	if !strings.Contains(err.Error(), "use +message-trash") {
+		t.Fatalf("error = %v, want TRASH validation", err)
+	}
+}
+
+func TestMessageModify_EmptyOperationDoesNotCallPost(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	id1 := messageManageID("1")
+	id2 := messageManageID("2")
+	err := runMountedMailShortcut(t, MailMessageModify, []string{
+		"+message-modify",
+		"--message-ids", id1 + "," + id2 + "," + id1,
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	success, failed := decodeMessageManageSummary(t, decodeShortcutEnvelopeData(t, stdout))
+	if len(success) != 2 || success[0] != id1 || success[1] != id2 || len(failed) != 0 {
+		t.Fatalf("summary success=%v failed=%v", success, failed)
+	}
+}
+
+func TestMessageModify_BatchesAndAggregatesPartialFailure(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	ids := make([]string, 41)
+	for i := range ids {
+		ids[i] = messageManageID(fmt.Sprintf("%02d", i))
+	}
+	first := stubMessageManagePost(reg, "batch_modify", map[string]interface{}{"code": 0, "data": map[string]interface{}{}})
+	second := stubMessageManagePost(reg, "batch_modify", map[string]interface{}{"code": 1230001, "msg": "bad request"})
+	third := stubMessageManagePost(reg, "batch_modify", map[string]interface{}{"code": 0, "data": map[string]interface{}{}})
+
+	err := runMountedMailShortcut(t, MailMessageModify, []string{
+		"+message-modify",
+		"--message-ids", strings.Join(ids, ","),
+		"--add-folder", "archive",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	for idx, stub := range []*httpmock.Stub{first, second, third} {
+		var body map[string]interface{}
+		if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+			t.Fatalf("batch %d body unmarshal: %v", idx+1, err)
+		}
+		messageIDs := body["message_ids"].([]interface{})
+		want := []int{20, 20, 1}[idx]
+		if len(messageIDs) != want {
+			t.Fatalf("batch %d size = %d, want %d", idx+1, len(messageIDs), want)
+		}
+		if body["add_folder"] != "ARCHIVED" {
+			t.Fatalf("batch %d add_folder = %v, want ARCHIVED", idx+1, body["add_folder"])
+		}
+	}
+	success, failed := decodeMessageManageSummary(t, decodeShortcutEnvelopeData(t, stdout))
+	if len(success) != 21 || len(failed) != 20 {
+		t.Fatalf("success=%d failed=%d, want 21/20", len(success), len(failed))
+	}
+}
+
+func TestMessageModify_AllBatchesFailReturnsError(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	id := messageManageID("1")
+	stubMessageManagePost(reg, "batch_modify", map[string]interface{}{"code": 1230001, "msg": "bad request"})
+
+	err := runMountedMailShortcut(t, MailMessageModify, []string{
+		"+message-modify",
+		"--message-ids", id,
+		"--add-folder", "archive",
+	}, f, stdout)
+	requireMessageManageFailedPrecondition(t, err)
+}
+
+func TestMessageModify_DryRunShowsPlanWithoutValidationGET(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	id1 := messageManageID("1")
+	id2 := messageManageID("2")
+	err := runMountedMailShortcut(t, MailMessageModify, []string{
+		"+message-modify",
+		"--message-ids", id1 + "," + id2,
+		"--add-label-ids", "customA",
+		"--add-folder", "folderA",
+		"--dry-run",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("dry-run failed: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{
+		`/user_mailboxes/me/messages/batch_modify`,
+		`validation_api_plan`,
+		`/user_mailboxes/me/labels/customA`,
+		`/user_mailboxes/me/folders/folderA`,
+		`will_validate`,
+		`batch_size`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("dry-run output missing %q; got %s", want, out)
+		}
+	}
+}
+
+func TestMessageTrash_RequiresYesAndBatches(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	id1 := messageManageID("1")
+	id2 := messageManageID("2")
+	err := runMountedMailShortcut(t, MailMessageTrash, []string{
+		"+message-trash",
+		"--message-ids", id1 + "," + id2,
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected confirmation error, got nil")
+	}
+	if code := output.ExitCodeOf(err); code != output.ExitConfirmationRequired {
+		t.Fatalf("exit code = %d, want %d", code, output.ExitConfirmationRequired)
+	}
+
+	post := stubMessageManagePost(reg, "batch_trash", map[string]interface{}{"code": 0, "data": map[string]interface{}{}})
+	err = runMountedMailShortcut(t, MailMessageTrash, []string{
+		"+message-trash",
+		"--message-ids", id1 + "," + id2,
+		"--yes",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected err with --yes: %v", err)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(post.CapturedBody, &body); err != nil {
+		t.Fatalf("unmarshal captured body: %v", err)
+	}
+	if got := len(body["message_ids"].([]interface{})); got != 2 {
+		t.Fatalf("message_ids len = %d, want 2", got)
+	}
+	success, failed := decodeMessageManageSummary(t, decodeShortcutEnvelopeData(t, stdout))
+	if len(success) != 2 || len(failed) != 0 {
+		t.Fatalf("summary success=%v failed=%v", success, failed)
+	}
+}
+
+func TestMessageTrash_AllBatchesFailReturnsError(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	id := messageManageID("1")
+	stubMessageManagePost(reg, "batch_trash", map[string]interface{}{"code": 1230001, "msg": "bad request"})
+
+	err := runMountedMailShortcut(t, MailMessageTrash, []string{
+		"+message-trash",
+		"--message-ids", id,
+		"--yes",
+	}, f, stdout)
+	requireMessageManageFailedPrecondition(t, err)
+}
+
+func TestMessageManage_RejectsWhitespaceBeforeAPI(t *testing.T) {
+	id1 := messageManageID("1")
+	id2 := messageManageID("2")
+	cases := []struct {
+		name     string
+		shortcut common.Shortcut
+		args     []string
+	}{
+		{
+			name:     "trash newline in repeated flag",
+			shortcut: MailMessageTrash,
+			args:     []string{"+message-trash", "--message-ids", id1 + "\n" + id2, "--yes"},
+		},
+		{
+			name:     "trash tab in csv flag",
+			shortcut: MailMessageTrash,
+			args:     []string{"+message-trash", "--message-ids", id1 + ",\t" + id2, "--yes"},
+		},
+		{
+			name:     "modify space in repeated flag",
+			shortcut: MailMessageModify,
+			args:     []string{"+message-modify", "--message-ids", id1, "--message-ids", id2 + " ", "--add-folder", "archive"},
+		},
+		{
+			name:     "modify space in csv flag",
+			shortcut: MailMessageModify,
+			args:     []string{"+message-modify", "--message-ids", id1 + ", " + id2, "--add-folder", "archive"},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, stdout, _, _ := mailShortcutTestFactory(t)
+			err := runMountedMailShortcut(t, tc.shortcut, tc.args, f, stdout)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			if code := output.ExitCodeOf(err); code != output.ExitValidation {
+				t.Fatalf("exit code = %d, want %d; err=%v", code, output.ExitValidation, err)
+			}
+			if !strings.Contains(err.Error(), "must not contain whitespace or control characters") {
+				t.Fatalf("error = %v, want whitespace/control validation", err)
+			}
+		})
+	}
+}
--- a/shortcuts/mail/mail_message_modify.go
+++ b/shortcuts/mail/mail_message_modify.go
@@ -0,0 +1,141 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type messageModifyInput struct {
+	MessageIDs         []string
+	AddLabelIDs        []string
+	RemoveLabelIDs     []string
+	AddFolder          string
+	CustomLabelIDs     []string
+	CustomFolderID     string
+	ValidationAPIPlans []validationAPIPlan
+}
+
+// MailMessageModify is the `+message-modify` shortcut: apply labels, unread
+// state labels, or a folder move to existing messages in batches of 20.
+var MailMessageModify = common.Shortcut{
+	Service:     "mail",
+	Command:     "+message-modify",
+	Description: "Modify existing mail messages by adding/removing label IDs or moving them to a folder. Batches message IDs in groups of 20 and keeps output compact.",
+	Risk:        "write",
+	Scopes:      []string{"mail:user_mailbox.message:modify"},
+	ConditionalScopes: []string{
+		"mail:user_mailbox.folder:read",
+	},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "mailbox", Desc: "Mailbox email address that owns the messages (default: me)."},
+		{Name: "message-ids", Type: "string_array", Required: true, Desc: "Message IDs to modify; comma-separated or repeat the flag."},
+		{Name: "add-label-ids", Type: "string_slice", Desc: "Label IDs to add. System labels unread/important/other/flagged are normalized to upper case."},
+		{Name: "remove-label-ids", Type: "string_slice", Desc: "Label IDs to remove. System labels unread/important/other/flagged are normalized to upper case."},
+		{Name: "add-folder", Desc: "Folder ID to move messages to. System folders inbox/sent/spam/archive/archived are normalized; TRASH is rejected, use +message-trash."},
+	},
+	Validate: validateMessageModify,
+	DryRun:   dryRunMessageModify,
+	Execute:  executeMessageModify,
+}
+
+func validateMessageModify(ctx context.Context, rt *common.RuntimeContext) error {
+	_, err := buildMessageModifyInput(rt)
+	return err
+}
+
+func dryRunMessageModify(ctx context.Context, rt *common.RuntimeContext) *common.DryRunAPI {
+	mailboxID := resolveMailboxID(rt)
+	input, _ := buildMessageModifyInput(rt)
+	api := common.NewDryRunAPI().
+		Desc("Modify messages sequentially in batches of 20; dry-run does not call label/folder validation APIs").
+		Set("batch_size", mailMessageManageBatchSize).
+		Set("batches", chunkMessageManageIDs(input.MessageIDs)).
+		Set("validation_api_plan", input.ValidationAPIPlans)
+	for _, batch := range chunkMessageManageIDs(input.MessageIDs) {
+		api = api.POST(mailboxPath(mailboxID, "messages", "batch_modify")).
+			Body(messageManageBody(batch, input.AddLabelIDs, input.RemoveLabelIDs, input.AddFolder))
+	}
+	return api
+}
+
+func executeMessageModify(ctx context.Context, rt *common.RuntimeContext) error {
+	mailboxID := resolveMailboxID(rt)
+	input, err := buildMessageModifyInput(rt)
+	if err != nil {
+		return err
+	}
+	if err := validateCustomMessageManageLabels(rt, mailboxID, input.CustomLabelIDs); err != nil {
+		return err
+	}
+	if err := validateCustomMessageManageFolder(rt, mailboxID, input.CustomFolderID); err != nil {
+		return err
+	}
+
+	if len(input.AddLabelIDs) == 0 && len(input.RemoveLabelIDs) == 0 && input.AddFolder == "" {
+		emitMessageManageSummary(rt, messageManageSummary{
+			SuccessMessageIDs: input.MessageIDs,
+			FailedMessageIDs:  []messageManageFailure{},
+		}, true)
+		return nil
+	}
+
+	summary := messageManageSummary{FailedMessageIDs: []messageManageFailure{}}
+	for _, batch := range chunkMessageManageIDs(input.MessageIDs) {
+		_, err := rt.CallAPITyped("POST", mailboxPath(mailboxID, "messages", "batch_modify"), nil,
+			messageManageBody(batch, input.AddLabelIDs, input.RemoveLabelIDs, input.AddFolder))
+		if err != nil {
+			for _, id := range batch {
+				summary.FailedMessageIDs = append(summary.FailedMessageIDs, messageManageFailure{MessageID: id, Reason: err.Error()})
+			}
+			continue
+		}
+		summary.SuccessMessageIDs = append(summary.SuccessMessageIDs, batch...)
+	}
+	emitMessageManageSummary(rt, summary, false)
+	if len(summary.SuccessMessageIDs) == 0 && len(summary.FailedMessageIDs) > 0 {
+		return mailFailedPreconditionError("all message modify batches failed")
+	}
+	return nil
+}
+
+func buildMessageModifyInput(rt *common.RuntimeContext) (messageModifyInput, error) {
+	messageIDs, err := normalizeMessageManageIDs(rt.StrArray("message-ids"))
+	if err != nil {
+		return messageModifyInput{}, err
+	}
+	addLabels, customAddLabels, err := normalizeMessageManageLabels(rt.StrSlice("add-label-ids"), "--add-label-ids")
+	if err != nil {
+		return messageModifyInput{}, err
+	}
+	removeLabels, customRemoveLabels, err := normalizeMessageManageLabels(rt.StrSlice("remove-label-ids"), "--remove-label-ids")
+	if err != nil {
+		return messageModifyInput{}, err
+	}
+	if err := validateLabelIntersection(addLabels, removeLabels); err != nil {
+		return messageModifyInput{}, err
+	}
+	folder, customFolder, err := normalizeMessageManageFolder(rt.Str("add-folder"))
+	if err != nil {
+		return messageModifyInput{}, err
+	}
+	customLabels := append(customAddLabels, customRemoveLabels...)
+	customFolderID := ""
+	if customFolder {
+		customFolderID = folder
+	}
+	return messageModifyInput{
+		MessageIDs:         messageIDs,
+		AddLabelIDs:        addLabels,
+		RemoveLabelIDs:     removeLabels,
+		AddFolder:          folder,
+		CustomLabelIDs:     customLabels,
+		CustomFolderID:     customFolderID,
+		ValidationAPIPlans: messageManageValidationPlan(resolveMailboxID(rt), customLabels, customFolderID),
+	}, nil
+}
--- a/shortcuts/mail/mail_message_trash.go
+++ b/shortcuts/mail/mail_message_trash.go
@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// MailMessageTrash is the `+message-trash` shortcut: soft-delete existing
+// messages in batches of 20 via batch_trash. Risk is high-risk-write, so the
+// runner requires --yes before Execute.
+var MailMessageTrash = common.Shortcut{
+	Service:     "mail",
+	Command:     "+message-trash",
+	Description: "Soft-delete existing mail messages. Batches message IDs in groups of 20 and calls batch_trash sequentially. Requires --yes.",
+	Risk:        "high-risk-write",
+	Scopes:      []string{"mail:user_mailbox.message:modify"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "mailbox", Desc: "Mailbox email address that owns the messages (default: me)."},
+		{Name: "message-ids", Type: "string_array", Required: true, Desc: "Message IDs to soft-delete; comma-separated or repeat the flag."},
+	},
+	Validate: validateMessageTrash,
+	DryRun:   dryRunMessageTrash,
+	Execute:  executeMessageTrash,
+}
+
+func validateMessageTrash(ctx context.Context, rt *common.RuntimeContext) error {
+	_, err := normalizeMessageManageIDs(rt.StrArray("message-ids"))
+	return err
+}
+
+func dryRunMessageTrash(ctx context.Context, rt *common.RuntimeContext) *common.DryRunAPI {
+	mailboxID := resolveMailboxID(rt)
+	messageIDs, _ := normalizeMessageManageIDs(rt.StrArray("message-ids"))
+	api := common.NewDryRunAPI().
+		Desc("Soft-delete messages sequentially in batches of 20").
+		Set("batch_size", mailMessageManageBatchSize).
+		Set("batches", chunkMessageManageIDs(messageIDs))
+	for _, batch := range chunkMessageManageIDs(messageIDs) {
+		api = api.POST(mailboxPath(mailboxID, "messages", "batch_trash")).
+			Body(map[string]interface{}{"message_ids": batch})
+	}
+	return api
+}
+
+func executeMessageTrash(ctx context.Context, rt *common.RuntimeContext) error {
+	mailboxID := resolveMailboxID(rt)
+	messageIDs, err := normalizeMessageManageIDs(rt.StrArray("message-ids"))
+	if err != nil {
+		return err
+	}
+
+	summary := messageManageSummary{FailedMessageIDs: []messageManageFailure{}}
+	for _, batch := range chunkMessageManageIDs(messageIDs) {
+		_, err := rt.CallAPITyped("POST", mailboxPath(mailboxID, "messages", "batch_trash"), nil,
+			map[string]interface{}{"message_ids": batch})
+		if err != nil {
+			for _, id := range batch {
+				summary.FailedMessageIDs = append(summary.FailedMessageIDs, messageManageFailure{MessageID: id, Reason: err.Error()})
+			}
+			continue
+		}
+		summary.SuccessMessageIDs = append(summary.SuccessMessageIDs, batch...)
+	}
+	emitMessageManageSummary(rt, summary, false)
+	if len(summary.SuccessMessageIDs) == 0 && len(summary.FailedMessageIDs) > 0 {
+		return mailFailedPreconditionError("all message trash batches failed")
+	}
+	return nil
+}
--- a/shortcuts/mail/mail_shortcut_test.go
+++ b/shortcuts/mail/mail_shortcut_test.go
@@ -44,7 +44,7 @@ func mailShortcutTestFactory(t *testing.T) (*cmdutil.Factory, *bytes.Buffer, *by
 		RefreshToken:     "test-refresh-token",
 		ExpiresAt:        time.Now().Add(1 * time.Hour).UnixMilli(),
 		RefreshExpiresAt: time.Now().Add(24 * time.Hour).UnixMilli(),
-		Scope:            "mail:user_mailbox.messages:write mail:user_mailbox.messages:read mail:user_mailbox.message:modify mail:user_mailbox.message:readonly mail:user_mailbox.message.address:read mail:user_mailbox.message.subject:read mail:user_mailbox.message.body:read mail:user_mailbox:readonly",
+		Scope:            "mail:user_mailbox.messages:write mail:user_mailbox.messages:read mail:user_mailbox.message:modify mail:user_mailbox.message:readonly mail:user_mailbox.message.address:read mail:user_mailbox.message.subject:read mail:user_mailbox.message.body:read mail:user_mailbox:readonly mail:user_mailbox.folder:read",
 		GrantedAt:        time.Now().Add(-1 * time.Hour).UnixMilli(),
 	}
 	if err := auth.SetStoredToken(token); err != nil {
--- a/shortcuts/mail/message_manage_helpers.go
+++ b/shortcuts/mail/message_manage_helpers.go
@@ -0,0 +1,283 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"fmt"
+	"io"
+	"strings"
+	"unicode"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const mailMessageManageBatchSize = 20
+
+var messageManageSystemLabels = map[string]string{
+	"UNREAD":               "UNREAD",
+	"IMPORTANT":            "IMPORTANT",
+	"OTHER":                "OTHER",
+	"FLAGGED":              "FLAGGED",
+	"READ_RECEIPT_REQUEST": "READ_RECEIPT_REQUEST",
+}
+
+var messageManageSystemFolders = map[string]string{
+	"INBOX":    "INBOX",
+	"SENT":     "SENT",
+	"SPAM":     "SPAM",
+	"ARCHIVE":  "ARCHIVED",
+	"ARCHIVED": "ARCHIVED",
+}
+
+type messageManageSummary struct {
+	SuccessMessageIDs []string               `json:"success_message_ids"`
+	FailedMessageIDs  []messageManageFailure `json:"failed_message_ids"`
+}
+
+type messageManageFailure struct {
+	MessageID string `json:"message_id"`
+	Reason    string `json:"reason"`
+}
+
+type validationAPIPlan struct {
+	Method       string `json:"method"`
+	Path         string `json:"path"`
+	WillValidate bool   `json:"will_validate"`
+}
+
+func normalizeMessageManageIDs(raw []string) ([]string, error) {
+	if len(raw) == 0 {
+		return nil, mailValidationParamError("--message-ids", "--message-ids is required")
+	}
+	parts, err := splitMessageManageIDTokens(raw)
+	if err != nil {
+		return nil, err
+	}
+	ids := make([]string, 0, len(parts))
+	seen := make(map[string]struct{}, len(parts))
+	for i, part := range parts {
+		if part == "" {
+			return nil, mailValidationParamError("--message-ids", "--message-ids entry %d is empty; remove extra commas or provide valid message IDs", i+1)
+		}
+		id := strings.TrimSpace(part)
+		if id == "" {
+			return nil, mailValidationParamError("--message-ids", "--message-ids entry %d is empty; remove extra commas or provide valid message IDs", i+1)
+		}
+		if id != part {
+			return nil, mailValidationParamError("--message-ids", "--message-ids entry %d (%q): must not contain leading or trailing whitespace", i+1, part)
+		}
+		if err := validateMessageManageID(id, i); err != nil {
+			return nil, err
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	if len(ids) == 0 {
+		return nil, mailValidationParamError("--message-ids", "--message-ids is required")
+	}
+	return ids, nil
+}
+
+func splitMessageManageIDTokens(raw []string) ([]string, error) {
+	parts := make([]string, 0, len(raw))
+	for i, token := range raw {
+		for _, r := range token {
+			if unicode.IsSpace(r) || unicode.IsControl(r) {
+				return nil, mailValidationParamError("--message-ids", "--message-ids entry %d (%q): must not contain whitespace or control characters", i+1, token)
+			}
+		}
+		parts = append(parts, strings.Split(token, ",")...)
+	}
+	return parts, nil
+}
+
+func validateMessageManageID(id string, index int) error {
+	if len(id) < 16 {
+		return mailValidationParamError("--message-ids", "--message-ids entry %d (%q): length must be at least 16 characters", index+1, id)
+	}
+	if strings.Trim(id, "0123456789") == "" {
+		return mailValidationParamError("--message-ids", "--message-ids entry %d (%q): numeric primary IDs are not supported; pass the Open API message_id from mail output", index+1, id)
+	}
+	for _, r := range id {
+		if unicode.IsSpace(r) || unicode.IsControl(r) {
+			return mailValidationParamError("--message-ids", "--message-ids entry %d (%q): must not contain whitespace or control characters", index+1, id)
+		}
+		if (r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') {
+			continue
+		}
+		switch r {
+		case '+', '/', '=', '_', '-':
+			continue
+		default:
+			return mailValidationParamError("--message-ids", "--message-ids entry %d (%q): contains characters outside the Open API message_id character set", index+1, id)
+		}
+	}
+	return nil
+}
+
+func normalizeMessageManageLabels(raw []string, flagName string) ([]string, []string, error) {
+	labels := make([]string, 0, len(raw))
+	custom := make([]string, 0, len(raw))
+	seen := make(map[string]struct{}, len(raw))
+	for i, part := range raw {
+		id := strings.TrimSpace(part)
+		if id == "" {
+			return nil, nil, mailValidationParamError(flagName, "%s entry %d is empty; remove extra commas or provide valid label IDs", flagName, i+1)
+		}
+		if id != part {
+			return nil, nil, mailValidationParamError(flagName, "%s entry %d (%q): must not contain leading or trailing whitespace", flagName, i+1, part)
+		}
+		normalized := id
+		if system, ok := messageManageSystemLabels[strings.ToUpper(id)]; ok {
+			normalized = system
+		} else {
+			custom = append(custom, id)
+		}
+		if _, ok := seen[normalized]; ok {
+			continue
+		}
+		seen[normalized] = struct{}{}
+		labels = append(labels, normalized)
+	}
+	if len(labels) > 20 {
+		return nil, nil, mailValidationParamError(flagName, "%s accepts at most 20 label IDs (got %d)", flagName, len(labels))
+	}
+	return labels, custom, nil
+}
+
+func validateLabelIntersection(add, remove []string) error {
+	removeSet := make(map[string]struct{}, len(remove))
+	for _, id := range remove {
+		removeSet[id] = struct{}{}
+	}
+	for _, id := range add {
+		if _, ok := removeSet[id]; ok {
+			return mailValidationParamError("--add-label-ids", "label cannot be both added and removed: %s", id)
+		}
+	}
+	return nil
+}
+
+func normalizeMessageManageFolder(raw string) (string, bool, error) {
+	if raw == "" {
+		return "", false, nil
+	}
+	folder := strings.TrimSpace(raw)
+	if folder == "" {
+		return "", false, mailValidationParamError("--add-folder", "--add-folder must not be empty")
+	}
+	if folder != raw {
+		return "", false, mailValidationParamError("--add-folder", "--add-folder %q must not contain leading or trailing whitespace", raw)
+	}
+	if strings.EqualFold(folder, "TRASH") {
+		return "", false, mailValidationParamError("--add-folder", "TRASH is not supported by +message-modify; use +message-trash")
+	}
+	if system, ok := messageManageSystemFolders[strings.ToUpper(folder)]; ok {
+		return system, false, nil
+	}
+	return folder, true, nil
+}
+
+func chunkMessageManageIDs(ids []string) [][]string {
+	if len(ids) == 0 {
+		return nil
+	}
+	chunks := make([][]string, 0, (len(ids)+mailMessageManageBatchSize-1)/mailMessageManageBatchSize)
+	for start := 0; start < len(ids); start += mailMessageManageBatchSize {
+		end := start + mailMessageManageBatchSize
+		if end > len(ids) {
+			end = len(ids)
+		}
+		chunks = append(chunks, ids[start:end])
+	}
+	return chunks
+}
+
+func validateCustomMessageManageLabels(rt *common.RuntimeContext, mailboxID string, ids []string) error {
+	if len(ids) == 0 {
+		return nil
+	}
+	if err := validateLabelReadScope(rt); err != nil {
+		return err
+	}
+	seen := map[string]struct{}{}
+	for _, id := range ids {
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		if _, err := rt.CallAPITyped("GET", mailboxPath(mailboxID, "labels", id), nil, nil); err != nil {
+			return mailDecorateProblemMessage(err, "label not found: %s", id)
+		}
+	}
+	return nil
+}
+
+func validateCustomMessageManageFolder(rt *common.RuntimeContext, mailboxID, id string) error {
+	if id == "" {
+		return nil
+	}
+	if err := validateFolderReadScope(rt); err != nil {
+		return err
+	}
+	if _, err := rt.CallAPITyped("GET", mailboxPath(mailboxID, "folders", id), nil, nil); err != nil {
+		return mailDecorateProblemMessage(err, "folder not found: %s", id)
+	}
+	return nil
+}
+
+func messageManageBody(ids, addLabels, removeLabels []string, addFolder string) map[string]interface{} {
+	body := map[string]interface{}{"message_ids": ids}
+	if len(addLabels) > 0 {
+		body["add_label_ids"] = addLabels
+	}
+	if len(removeLabels) > 0 {
+		body["remove_label_ids"] = removeLabels
+	}
+	if addFolder != "" {
+		body["add_folder"] = addFolder
+	}
+	return body
+}
+
+func messageManageValidationPlan(mailboxID string, customLabels []string, customFolder string) []validationAPIPlan {
+	plans := make([]validationAPIPlan, 0, len(customLabels)+1)
+	seenLabels := map[string]struct{}{}
+	for _, id := range customLabels {
+		if _, ok := seenLabels[id]; ok {
+			continue
+		}
+		seenLabels[id] = struct{}{}
+		plans = append(plans, validationAPIPlan{
+			Method:       "GET",
+			Path:         mailboxPath(mailboxID, "labels", id),
+			WillValidate: true,
+		})
+	}
+	if customFolder != "" {
+		plans = append(plans, validationAPIPlan{
+			Method:       "GET",
+			Path:         mailboxPath(mailboxID, "folders", customFolder),
+			WillValidate: true,
+		})
+	}
+	return plans
+}
+
+func emitMessageManageSummary(rt *common.RuntimeContext, summary messageManageSummary, noAPICalls bool) {
+	rt.OutFormat(summary, &output.Meta{Count: len(summary.SuccessMessageIDs)}, func(w io.Writer) {
+		fmt.Fprintf(w, "success_message_ids: %d\n", len(summary.SuccessMessageIDs))
+		fmt.Fprintf(w, "failed_message_ids: %d\n", len(summary.FailedMessageIDs))
+		if noAPICalls {
+			fmt.Fprintln(w, "No changes requested; no API calls were made.")
+		}
+		for _, item := range summary.FailedMessageIDs {
+			fmt.Fprintf(w, "- %s: %s\n", item.MessageID, item.Reason)
+		}
+	})
+}
--- a/shortcuts/mail/shortcuts.go
+++ b/shortcuts/mail/shortcuts.go
@@ -10,6 +10,8 @@ func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		MailMessage,
 		MailMessages,
+		MailMessageModify,
+		MailMessageTrash,
 		MailThread,
 		MailTriage,
 		MailWatch,
--- a/skill-template/domains/mail.md
+++ b/skill-template/domains/mail.md
@@ -65,7 +65,7 @@

 1. `+triage --from spam@x.com` → 列出 N 条结果
 2. 展示："将删除 N 封邮件（发件人 spam@x.com，主题：…），确认？"
-3. 用户确认后 → `*.batch_trash`
+3. 用户确认后 → `+message-trash --message-ids ... --yes`

 ## 身份选择：优先使用 user 身份

@@ -82,12 +82,13 @@
 1. **确认身份** — 首次操作邮箱前先调用 `lark-cli mail user_mailboxes profile --params '{"user_mailbox_id":"me"}'` 获取当前用户的真实邮箱地址（`primary_email_address`），不要通过系统用户名猜测。后续判断"发件人是否为用户本人"时以此地址为准。
 2. **浏览** — `+triage` 查看收件箱摘要，获取 `message_id` / `thread_id`
 3. **阅读** — `+message` 读单封邮件，`+thread` 读整个会话
-4. **回复** — `+reply` / `+reply-all`（默认存草稿，加 `--confirm-send` 则立即发送）
-5. **转发** — `+forward`（默认存草稿，加 `--confirm-send` 则立即发送）
-6. **新邮件** — `+send` 存草稿（默认），加 `--confirm-send` 发送
-7. **确认投递** — 立即发送后用 `send_status` 查询投递状态，定时发送后在预定时间后再查询；取消定时发送用 `cancel_scheduled_send`
-8. **编辑草稿** — `+draft-edit` 修改已有草稿。正文编辑通过 `--patch-file`：回复/转发草稿用 `set_reply_body` op 保留引用区，普通草稿用 `set_body` op
-9. **已读回执** —
+4. **整理** — 标签、已读/未读状态和移动文件夹优先用 `+message-modify`；软删除优先用 `+message-trash`
+5. **回复** — `+reply` / `+reply-all`（默认存草稿，加 `--confirm-send` 则立即发送）
+6. **转发** — `+forward`（默认存草稿，加 `--confirm-send` 则立即发送）
+7. **新邮件** — `+send` 存草稿（默认），加 `--confirm-send` 发送
+8. **确认投递** — 立即发送后用 `send_status` 查询投递状态，定时发送后在预定时间后再查询；取消定时发送用 `cancel_scheduled_send`
+9. **编辑草稿** — `+draft-edit` 修改已有草稿。正文编辑通过 `--patch-file`：回复/转发草稿用 `set_reply_body` op 保留引用区，普通草稿用 `set_body` op
+10. **已读回执** —
   - **请求回执（写信侧）**：`--request-receipt` 仅在**用户显式要求**时添加，**不要从 subject / body 内容推断意图**。
   - **响应回执（拉信侧）**：拉信看到 `label_ids` 含 `READ_RECEIPT_REQUEST`（或 `-607`）时，**必须先问用户**是否回执（不要自动回执，涉及隐私）。用户同意 → `+send-receipt` 响应；用户不同意但想消掉提示 → `+decline-receipt` 只清本地标签、不发邮件。

@@ -417,7 +418,7 @@ lark-cli mail +message --message-id <id>

 ## 原生 API 调用规则

-没有 Shortcut 覆盖的操作才使用原生 API。调用步骤以本节为准（API Resources 章节的 resource/method 列表可辅助查阅）。
+没有 Shortcut 覆盖的操作才使用原生 API。标签、已读状态、移动文件夹优先使用 `+message-modify`；软删除优先使用 `+message-trash`。调用步骤以本节为准（API Resources 章节的 resource/method 列表可辅助查阅）。

 ### Step 1 — 用 `-h` 确定要调用的 API（必须，不可跳过）

--- a/skills/lark-mail/SKILL.md
+++ b/skills/lark-mail/SKILL.md
@@ -79,7 +79,7 @@ metadata:

 1. `+triage --from spam@x.com` → 列出 N 条结果
 2. 展示："将删除 N 封邮件（发件人 spam@x.com，主题：…），确认？"
-3. 用户确认后 → `*.batch_trash`
+3. 用户确认后 → `+message-trash --message-ids ... --yes`

 ## 身份选择：优先使用 user 身份

@@ -96,13 +96,14 @@ metadata:
 1. **确认身份** — 首次操作邮箱前先调用 `lark-cli mail user_mailboxes profile --params '{"user_mailbox_id":"me"}'` 获取当前用户的真实邮箱地址（`primary_email_address`），不要通过系统用户名猜测。后续判断"发件人是否为用户本人"时以此地址为准。
 2. **浏览** — `+triage` 查看收件箱摘要，获取 `message_id` / `thread_id`
 3. **阅读** — `+message` 只读单封邮件；已有多个 `message_id` 时用 `+messages` 批量读取，不要循环调用 `+message`；`+thread` 读整个会话
-4. **回复** — `+reply` / `+reply-all`（默认存草稿，加 `--confirm-send` 则立即发送）
-5. **转发** — `+forward`（默认存草稿，加 `--confirm-send` 则立即发送）
-6. **新邮件** — `+send` 存草稿（默认），加 `--confirm-send` 发送
-7. **HTML body 预检（可选）** — 复杂 HTML body 提交前可先跑 `+lint-html` 看 lint 会改 / 删什么；写信路径（`+send` / `+draft-create` / `+reply` / `+reply-all` / `+forward` / `+draft-edit` body op）已内置 autofix，普通正文不必先跑。详见 [references/lark-mail-html.md](references/lark-mail-html.md) 中的「写入路径内置 HTML lint」章节
-8. **确认投递** — 立即发送后用 `send_status` 查询投递状态，定时发送后在预定时间后再查询；取消定时发送用 `cancel_scheduled_send`
-9. **编辑草稿** — `+draft-edit` 修改已有草稿。正文编辑通过 `--patch-file`：回复/转发草稿用 `set_reply_body` op 保留引用区，普通草稿用 `set_body` op
-10. **已读回执** —
+4. **整理** — 标签、已读/未读状态和移动文件夹优先用 `+message-modify`；软删除优先用 `+message-trash`
+5. **回复** — `+reply` / `+reply-all`（默认存草稿，加 `--confirm-send` 则立即发送）
+6. **转发** — `+forward`（默认存草稿，加 `--confirm-send` 则立即发送）
+7. **新邮件** — `+send` 存草稿（默认），加 `--confirm-send` 发送
+8. **HTML body 预检（可选）** — 复杂 HTML body 提交前可先跑 `+lint-html` 看 lint 会改 / 删什么；写信路径（`+send` / `+draft-create` / `+reply` / `+reply-all` / `+forward` / `+draft-edit` body op）已内置 autofix，普通正文不必先跑。详见 [references/lark-mail-html.md](references/lark-mail-html.md) 中的「写入路径内置 HTML lint」章节
+9. **确认投递** — 立即发送后用 `send_status` 查询投递状态，定时发送后在预定时间后再查询；取消定时发送用 `cancel_scheduled_send`
+10. **编辑草稿** — `+draft-edit` 修改已有草稿。正文编辑通过 `--patch-file`：回复/转发草稿用 `set_reply_body` op 保留引用区，普通草稿用 `set_body` op
+11. **已读回执** —
   - **请求回执（写信侧）**：`--request-receipt` 仅在**用户显式要求**时添加，**不要从 subject / body 内容推断意图**。
   - **响应回执（拉信侧）**：拉信看到 `label_ids` 含 `READ_RECEIPT_REQUEST`（或 `-607`）时，**必须先问用户**是否回执（不要自动回执，涉及隐私）。用户同意 → `+send-receipt` 响应；用户不同意但想消掉提示 → `+decline-receipt` 只清本地标签、不发邮件。

@@ -119,6 +120,8 @@ metadata:
 - 查看发送邮件后的投递状态：发送成功后查看邮件投递状态；也覆盖发送拦截。ref: [lark-mail-send-status](references/lark-mail-send-status.md)
 - 使用邮件模板：区分个人模板和静态 HTML 模板，发信类 shortcut 用 `--template-id` 套用模板。ref: [lark-mail-template](references/lark-mail-template.md)
 - 撤回已发送邮件：撤回邮件并查询异步撤回状态。ref: [lark-mail-recall](references/lark-mail-recall.md)
+- 修改邮件标签/已读状态/文件夹：优先使用 `+message-modify`。ref: [`+message-modify`](references/lark-mail-message-modify.md)
+- 软删除邮件：优先使用 `+message-trash`。ref: [`+message-trash`](references/lark-mail-message-trash.md)
 - 收信规则：创建、验证、删除自动处理收到邮件的规则。ref: [lark-mail-rules](references/lark-mail-rules.md)
 - 分享邮件到 IM：分享邮件或会话到群聊、个人会话。ref: [lark-mail-share-to-chat](references/lark-mail-share-to-chat.md)
 - 发送日程邀请邮件：在邮件中嵌入 `text/calendar` 日程邀请。ref: [lark-mail-calendar-invite](references/lark-mail-calendar-invite.md)
@@ -192,7 +195,7 @@ lark-cli mail +messages --message-ids <id1>,<id2>,<id3> --html=false

 ## 原生 API 调用规则

-没有 Shortcut 覆盖的操作才使用原生 API。调用步骤以本节为准；资源和 method 用 `lark-cli mail -h` / `lark-cli mail <resource> -h` 发现，不在入口保留完整资源表。
+没有 Shortcut 覆盖的操作才使用原生 API。标签、已读状态、移动文件夹优先使用 `+message-modify`；软删除优先使用 `+message-trash`。调用步骤以本节为准；资源和 method 用 `lark-cli mail -h` / `lark-cli mail <resource> -h` 发现，不在入口保留完整资源表。

 ### Step 1 — 用 `-h` 确定要调用的 API（必须，不可跳过）

--- a/skills/lark-mail/references/lark-mail-forward.md
+++ b/skills/lark-mail/references/lark-mail-forward.md
@@ -215,7 +215,7 @@ lark-cli mail user_mailbox.drafts cancel_scheduled_send --params '{"user_mailbox
 **2. 标记已读**（可选）— 询问用户是否需要将原邮件标记为已读。如果用户同意：

 ```bash
-lark-cli mail user_mailbox.messages batch_modify --params '{"user_mailbox_id":"me"}' --data '{"message_ids":["<原邮件ID>"],"remove_label_ids":["UNREAD"]}'
+lark-cli mail +message-modify --message-ids <原邮件ID> --remove-label-ids UNREAD
 ```

 ## 编辑转发草稿
--- a/skills/lark-mail/references/lark-mail-message-modify.md
+++ b/skills/lark-mail/references/lark-mail-message-modify.md
@@ -0,0 +1,48 @@
+# mail +message-modify
+
+`mail +message-modify` is the preferred shortcut for changing labels, read-state labels, or folder placement on existing messages.
+
+Use it instead of raw `user_mailbox.messages batch_modify` when the operation targets concrete `message_id` values from `+triage`, `+message`, or `+messages`.
+
+## Common Commands
+
+```bash
+lark-cli mail +message-modify --message-ids <id1>,<id2> --add-label-ids unread
+lark-cli mail +message-modify --message-ids <id> --remove-label-ids FLAGGED
+lark-cli mail +message-modify --message-ids <id> --add-folder archive
+lark-cli mail +message-modify --mailbox shared@example.com --message-ids <id> --add-folder folder_xxx
+lark-cli mail +message-modify --message-ids <id> --add-label-ids custom_label_id --dry-run
+```
+
+## Flags
+
+| Flag | Required | Notes |
+| --- | --- | --- |
+| `--mailbox` | No | Mailbox that owns the messages. Defaults to `me`. |
+| `--message-ids` | Yes | `string_array`; supports comma-separated values and repeated flags. |
+| `--add-label-ids` | No | Adds labels. System labels `unread`, `important`, `other`, `flagged` normalize to upper case. |
+| `--remove-label-ids` | No | Removes labels. Cannot overlap with `--add-label-ids`. |
+| `--add-folder` | No | Moves to one folder. `inbox`, `sent`, `spam`, `archive`, `archived` normalize to system folder IDs. |
+
+`TRASH` is intentionally rejected by this shortcut. Use `mail +message-trash --message-ids <id> --yes` for soft deletion.
+
+## Behavior
+
+- Message IDs are locally validated, de-duplicated in first-seen order, and sent in batches of 20.
+- Custom label IDs are checked with `labels.get`; custom folder IDs are checked with `folders.get`.
+- If no label or folder operation is requested, the command succeeds locally, emits all message IDs as `success_message_ids`, and makes no POST request.
+- Single batch POST failures mark every message in that batch with the same failure reason; later batches still run.
+- JSON output is intentionally compact:
+
+```json
+{
+  "success_message_ids": ["id1"],
+  "failed_message_ids": [
+    {"message_id": "id2", "reason": "api error"}
+  ]
+}
+```
+
+## When Raw API Is Still Appropriate
+
+Use raw `mail user_mailbox.messages batch_modify` only when you need a request shape that the shortcut intentionally does not expose, or when reproducing backend/API behavior exactly for diagnostics.
--- a/skills/lark-mail/references/lark-mail-message-trash.md
+++ b/skills/lark-mail/references/lark-mail-message-trash.md
@@ -0,0 +1,41 @@
+# mail +message-trash
+
+`mail +message-trash` is the preferred shortcut for soft-deleting existing messages.
+
+Use it after obtaining real `message_id` values from `+triage`, `+message`, or `+messages`, and after the user has confirmed the deletion preview.
+
+## Common Commands
+
+```bash
+lark-cli mail +message-trash --message-ids <id1>,<id2> --yes
+lark-cli mail +message-trash --mailbox shared@example.com --message-ids <id> --yes
+lark-cli mail +message-trash --message-ids <id1> --message-ids <id2> --dry-run
+```
+
+## Flags
+
+| Flag | Required | Notes |
+| --- | --- | --- |
+| `--mailbox` | No | Mailbox that owns the messages. Defaults to `me`. |
+| `--message-ids` | Yes | `string_array`; supports comma-separated values and repeated flags. |
+| `--yes` | Yes for execution | Required by the high-risk write confirmation framework. |
+
+## Behavior
+
+- Message IDs are locally validated, de-duplicated in first-seen order, and sent in batches of 20.
+- The shortcut calls `POST /open-apis/mail/v1/user_mailboxes/<mailbox>/messages/batch_trash` sequentially.
+- Single batch POST failures mark every message in that batch with the same failure reason; later batches still run.
+- JSON output is intentionally compact:
+
+```json
+{
+  "success_message_ids": ["id1"],
+  "failed_message_ids": [
+    {"message_id": "id2", "reason": "api error"}
+  ]
+}
+```
+
+## When Raw API Is Still Appropriate
+
+Use raw `mail user_mailbox.messages batch_trash` only when reproducing backend/API behavior exactly for diagnostics. For normal soft deletion, prefer this shortcut because it handles validation, batching, compact output, and `--yes` confirmation consistently.
--- a/skills/lark-mail/references/lark-mail-reply-all.md
+++ b/skills/lark-mail/references/lark-mail-reply-all.md
@@ -203,7 +203,7 @@ lark-cli mail user_mailbox.drafts cancel_scheduled_send --params '{"user_mailbox
 **2. 标记已读**（可选）— 询问用户是否需要将原邮件标记为已读。如果用户同意：

 ```bash
-lark-cli mail user_mailbox.messages batch_modify --params '{"user_mailbox_id":"me"}' --data '{"message_ids":["<原邮件ID>"],"remove_label_ids":["UNREAD"]}'
+lark-cli mail +message-modify --message-ids <原邮件ID> --remove-label-ids UNREAD
 ```

 ## 相关命令
--- a/skills/lark-mail/references/lark-mail-reply.md
+++ b/skills/lark-mail/references/lark-mail-reply.md
@@ -218,7 +218,7 @@ lark-cli mail user_mailbox.drafts cancel_scheduled_send --params '{"user_mailbox
 **2. 标记已读**（可选）— 询问用户是否需要将原邮件标记为已读。如果用户同意：

 ```bash
-lark-cli mail user_mailbox.messages batch_modify --params '{"user_mailbox_id":"me"}' --data '{"message_ids":["<原邮件ID>"],"remove_label_ids":["UNREAD"]}'
+lark-cli mail +message-modify --message-ids <原邮件ID> --remove-label-ids UNREAD
 ```

 ## 编辑回复草稿
--- a/tests/cli_e2e/core.go
+++ b/tests/cli_e2e/core.go
@@ -24,7 +24,17 @@ import (
 const EnvBinaryPath = "LARK_CLI_BIN"
 const projectRootMarkerDir = "tests"
 const cliBinaryName = "lark-cli"
-const CleanupTimeout = 30 * time.Second
+
+const (
+	// CleanupTimeout is the outer teardown budget. Keep it above any
+	// per-resource wait so cleanup command retries still have room to run.
+	CleanupTimeout = 60 * time.Second
+
+	defaultRetryAttempts        = 4
+	defaultRetryInitialDelay    = time.Second
+	defaultRetryMaxDelay        = 6 * time.Second
+	defaultRetryBackoffMultiple = 2
+)

 func SkipWithoutUserToken(t *testing.T) {
 	t.Helper()
@@ -102,6 +112,34 @@ type Result struct {
 	RunErr     error
 }

+type cleanupWarningError struct {
+	err error
+}
+
+func (e *cleanupWarningError) Error() string {
+	return e.err.Error()
+}
+
+func (e *cleanupWarningError) Unwrap() error {
+	return e.err
+}
+
+// CleanupWarning marks a cleanup verification issue as non-fatal after the
+// destructive cleanup command itself has already succeeded.
+func CleanupWarning(err error) error {
+	if err == nil {
+		return nil
+	}
+	return &cleanupWarningError{err: err}
+}
+
+// IsCleanupWarning reports whether err should be logged without failing the
+// parent test.
+func IsCleanupWarning(err error) bool {
+	var warning *cleanupWarningError
+	return errors.As(err, &warning)
+}
+
 // RetryOptions configures retry behavior for flaky external API calls.
 type RetryOptions struct {
 	Attempts        int
@@ -111,8 +149,25 @@ type RetryOptions struct {
 	ShouldRetry     func(*Result) bool
 }

+// WaitOptions configures a bounded poll loop for eventually consistent cleanup
+// or verification checks.
+type WaitOptions struct {
+	Timeout      time.Duration
+	Interval     time.Duration
+	TimeoutError func() error
+}
+
 // RunCmd executes lark-cli and captures stdout/stderr/exit code.
+// Service errors that return {"error":{"retryable":true}} are retried with
+// bounded exponential backoff so individual tests do not need to remember
+// RunCmdWithRetry for normal transient server contention.
 func RunCmd(ctx context.Context, req Request) (*Result, error) {
+	return RunCmdWithRetry(ctx, req, RetryOptions{
+		ShouldRetry: ResultHasRetryableError,
+	})
+}
+
+func runCmdOnce(ctx context.Context, req Request) (*Result, error) {
 	binaryPath, err := ResolveBinaryPath(req)
 	if err != nil {
 		return nil, err
@@ -186,16 +241,16 @@ func buildCommandEnv(req Request) []string {
 // RunCmdWithRetry reruns a command when the result matches the configured retry condition.
 func RunCmdWithRetry(ctx context.Context, req Request, opts RetryOptions) (*Result, error) {
 	if opts.Attempts <= 0 {
-		opts.Attempts = 4
+		opts.Attempts = defaultRetryAttempts
 	}
 	if opts.InitialDelay <= 0 {
-		opts.InitialDelay = 1 * time.Second
+		opts.InitialDelay = defaultRetryInitialDelay
 	}
 	if opts.MaxDelay <= 0 {
-		opts.MaxDelay = 6 * time.Second
+		opts.MaxDelay = defaultRetryMaxDelay
 	}
 	if opts.BackoffMultiple <= 1 {
-		opts.BackoffMultiple = 2
+		opts.BackoffMultiple = defaultRetryBackoffMultiple
 	}
 	if opts.ShouldRetry == nil {
 		opts.ShouldRetry = func(result *Result) bool {
@@ -206,7 +261,7 @@ func RunCmdWithRetry(ctx context.Context, req Request, opts RetryOptions) (*Resu
 	delay := opts.InitialDelay
 	var lastResult *Result
 	for attempt := 1; attempt <= opts.Attempts; attempt++ {
-		result, err := RunCmd(ctx, req)
+		result, err := runCmdOnce(ctx, req)
 		if err != nil {
 			return nil, err
 		}
@@ -234,6 +289,63 @@ func RunCmdWithRetry(ctx context.Context, req Request, opts RetryOptions) (*Resu
 	return lastResult, nil
 }

+// ResultHasRetryableError reports whether lark-cli returned a structured
+// service error with error.retryable=true in either output stream.
+func ResultHasRetryableError(result *Result) bool {
+	if result == nil {
+		return false
+	}
+	return rawHasRetryableError(result.Stdout) || rawHasRetryableError(result.Stderr)
+}
+
+func rawHasRetryableError(raw string) bool {
+	payload := extractJSONPayload(raw)
+	if payload == "" {
+		return false
+	}
+	return gjson.Get(payload, "error.retryable").Bool()
+}
+
+// WaitForCondition polls condition until it returns true, an error, the context
+// is canceled, or the configured timeout expires.
+func WaitForCondition(ctx context.Context, opts WaitOptions, condition func() (bool, error)) error {
+	if condition == nil {
+		return errors.New("wait condition is nil")
+	}
+	if opts.Timeout <= 0 {
+		opts.Timeout = CleanupTimeout
+	}
+	if opts.Interval <= 0 {
+		opts.Interval = time.Second
+	}
+
+	deadline := time.NewTimer(opts.Timeout)
+	defer deadline.Stop()
+	ticker := time.NewTicker(opts.Interval)
+	defer ticker.Stop()
+
+	for {
+		done, err := condition()
+		if err != nil {
+			return err
+		}
+		if done {
+			return nil
+		}
+
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-deadline.C:
+			if opts.TimeoutError != nil {
+				return opts.TimeoutError()
+			}
+			return fmt.Errorf("condition still false after %s", opts.Timeout)
+		case <-ticker.C:
+		}
+	}
+}
+
 // GenerateSuffix returns a high-entropy UTC timestamp suffix suitable for remote test resource names.
 func GenerateSuffix() string {
 	now := time.Now().UTC()
@@ -251,6 +363,10 @@ func ReportCleanupFailure(parentT *testing.T, prefix string, result *Result, err
 	parentT.Helper()

 	if err != nil {
+		if IsCleanupWarning(err) {
+			parentT.Logf("%s: %v", prefix, err)
+			return
+		}
 		parentT.Errorf("%s: %v", prefix, err)
 		return
 	}
@@ -271,26 +387,11 @@ func isCleanupSuppressedResult(result *Result) bool {
 		return false
 	}

-	raw := strings.TrimSpace(result.Stdout)
-	if raw == "" {
-		raw = strings.TrimSpace(result.Stderr)
+	payload := extractJSONPayload(result.Stdout)
+	if payload == "" {
+		payload = extractJSONPayload(result.Stderr)
 	}
-	if raw == "" {
-		return false
-	}
-
-	start := strings.LastIndex(raw, "\n{")
-	if start >= 0 {
-		start++
-	} else {
-		start = strings.Index(raw, "{")
-	}
-	if start < 0 {
-		return false
-	}
-
-	payload := raw[start:]
-	if !gjson.Valid(payload) {
+	if payload == "" {
 		return false
 	}

@@ -306,6 +407,32 @@ func isCleanupSuppressedResult(result *Result) bool {
 	return errType == "api_error" && (errCode == 800004135 || strings.Contains(errMessage, " limited"))
 }

+func extractJSONPayload(raw string) string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return ""
+	}
+	if gjson.Valid(raw) {
+		return raw
+	}
+
+	start := strings.LastIndex(raw, "\n{")
+	if start >= 0 {
+		start++
+	} else {
+		start = strings.Index(raw, "{")
+	}
+	if start < 0 {
+		return ""
+	}
+
+	payload := raw[start:]
+	if !gjson.Valid(payload) {
+		return ""
+	}
+	return payload
+}
+
 // ResolveBinaryPath finds the CLI binary path using request, env, then PATH.
 func ResolveBinaryPath(req Request) (string, error) {
 	if req.BinaryPath != "" {
--- a/tests/cli_e2e/core_test.go
+++ b/tests/cli_e2e/core_test.go
@@ -5,10 +5,12 @@ package clie2e

 import (
 	"context"
+	"errors"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"

 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -223,6 +225,88 @@ func TestRunCmd(t *testing.T) {
 		assert.NotContains(t, env, "LARKSUITE_CLI_APP_ID=cli_app_test")
 		assert.NotContains(t, env, "LARKSUITE_CLI_USER_ACCESS_TOKEN=uat_test")
 	})
+
+	t.Run("retries structured retryable service errors by default", func(t *testing.T) {
+		fake := newFakeCLI(t)
+		statePath := filepath.Join(t.TempDir(), "retry-count")
+		result, err := RunCmd(context.Background(), Request{
+			BinaryPath: fake.BinaryPath,
+			Args:       []string{"fail-once-retryable", statePath},
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		result.AssertStdoutStatus(t, true)
+
+		countBytes, err := os.ReadFile(statePath)
+		require.NoError(t, err)
+		assert.Equal(t, "2\n", string(countBytes))
+	})
+
+	t.Run("does not retry non-retryable service errors by default", func(t *testing.T) {
+		fake := newFakeCLI(t)
+		statePath := filepath.Join(t.TempDir(), "retry-count")
+		result, err := RunCmd(context.Background(), Request{
+			BinaryPath: fake.BinaryPath,
+			Args:       []string{"always-non-retryable", statePath},
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 1)
+
+		countBytes, err := os.ReadFile(statePath)
+		require.NoError(t, err)
+		assert.Equal(t, "1\n", string(countBytes))
+	})
+}
+
+func TestRunCmdWithRetry(t *testing.T) {
+	t.Run("does not include RunCmd default retry as a nested retry", func(t *testing.T) {
+		fake := newFakeCLI(t)
+		statePath := filepath.Join(t.TempDir(), "retry-count")
+		result, err := RunCmdWithRetry(context.Background(), Request{
+			BinaryPath: fake.BinaryPath,
+			Args:       []string{"fail-once-retryable", statePath},
+		}, RetryOptions{
+			Attempts:     1,
+			InitialDelay: time.Millisecond,
+			MaxDelay:     time.Millisecond,
+			ShouldRetry:  ResultHasRetryableError,
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 1)
+
+		countBytes, err := os.ReadFile(statePath)
+		require.NoError(t, err)
+		assert.Equal(t, "1\n", string(countBytes))
+	})
+}
+
+func TestWaitForCondition(t *testing.T) {
+	t.Run("polls until condition succeeds", func(t *testing.T) {
+		attempts := 0
+		err := WaitForCondition(context.Background(), WaitOptions{
+			Timeout:  50 * time.Millisecond,
+			Interval: time.Millisecond,
+		}, func() (bool, error) {
+			attempts++
+			return attempts == 2, nil
+		})
+
+		require.NoError(t, err)
+		assert.Equal(t, 2, attempts)
+	})
+
+	t.Run("returns custom timeout error", func(t *testing.T) {
+		wantErr := errors.New("still visible")
+		err := WaitForCondition(context.Background(), WaitOptions{
+			Timeout:      time.Millisecond,
+			Interval:     time.Millisecond,
+			TimeoutError: func() error { return wantErr },
+		}, func() (bool, error) {
+			return false, nil
+		})
+
+		assert.ErrorIs(t, err, wantErr)
+	})
 }

 type fakeCLI struct {
@@ -260,6 +344,35 @@ if [ "$1" = "emit-stdin" ]; then
  exit 0
 fi

+if [ "$1" = "fail-once-retryable" ]; then
+  state="$2"
+  count=0
+  if [ -f "$state" ]; then
+    count="$(cat "$state")"
+  fi
+  count=$((count + 1))
+  echo "$count" > "$state"
+  if [ "$count" -eq 1 ]; then
+    echo "Deleting folder fake..." >&2
+    echo '{"ok":false,"error":{"type":"api","code":1061045,"message":"resource contention occurred, please retry.","retryable":true}}' >&2
+    exit 1
+  fi
+  echo '{"ok":true}'
+  exit 0
+fi
+
+if [ "$1" = "always-non-retryable" ]; then
+  state="$2"
+  count=0
+  if [ -f "$state" ]; then
+    count="$(cat "$state")"
+  fi
+  count=$((count + 1))
+  echo "$count" > "$state"
+  echo '{"ok":false,"error":{"type":"api","code":123,"message":"validation failed","retryable":false}}' >&2
+  exit 1
+fi
+
 exit_code=0
 while [ "$#" -gt 0 ]; do
  case "$1" in
--- a/tests/cli_e2e/docs/coverage.md
+++ b/tests/cli_e2e/docs/coverage.md
@@ -21,7 +21,7 @@
 | Status | Cmd | Type | Testcase | Key parameter shapes | Notes / uncovered reason |
 | --- | --- | --- | --- | --- | --- |
 | ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/create; docs_update_dryrun_test.go::TestDocs_CreateTitleDryRunPrependsContent | `--parent-token`; `--doc-format markdown`; `--content`; `--title` | helper asserts returned doc id from `data.document.document_id`; dry-run asserts title is prepended into request body content |
-| ✓ | docs +fetch | shortcut | docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflow/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/fetch | `--doc <docToken>`; `--doc-format markdown`; default `extra_param.enable_user_cite_reference_map=true` | |
+| ✓ | docs +fetch | shortcut | docs_fetch_dryrun_test.go::TestDocsFetchDryRunIgnoresAPIVersionCompatFlag; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflow/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/fetch | `--doc <docToken>`; `--doc-format markdown`; default `extra_param.enable_user_cite_reference_map=true`; `--api-version v1` compatibility flag still dry-runs the v2 fetch endpoint | |
 | ✓ | docs +history-list | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history list; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--page-size`; `--page-token` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
 | ✓ | docs +history-revert | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--history-version-id`; `--wait-timeout-ms` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
 | ✓ | docs +history-revert-status | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert status; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--task-id` | live workflow polls only when revert returns `running` |
--- a/tests/cli_e2e/docs/docs_fetch_dryrun_test.go
+++ b/tests/cli_e2e/docs/docs_fetch_dryrun_test.go
@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT

-package doc
+package docs

 import (
 	"context"
@@ -23,7 +23,7 @@ func TestDocsFetchDryRunIgnoresAPIVersionCompatFlag(t *testing.T) {
 		Args: []string{
 			"docs", "+fetch",
 			"--doc", "doxcnDryRunCompat",
-			"--api-version", "legacy",
+			"--api-version", "v1",
 			"--dry-run",
 		},
 		DefaultAs: "bot",
--- a/tests/cli_e2e/drive/helpers.go
+++ b/tests/cli_e2e/drive/helpers.go
@@ -14,6 +14,18 @@ import (
 	"github.com/tidwall/gjson"
 )

+const (
+	driveDeleteVisibilityTimeout = 30 * time.Second
+	driveDeleteVisibilityPoll    = 3 * time.Second
+)
+
+var driveDeleteVisibilityWait = clie2e.WaitOptions{
+	// This wait only covers the post-delete visibility lag after Drive accepts
+	// deletion. The delete command itself is bounded by clie2e.CleanupContext.
+	Timeout:  driveDeleteVisibilityTimeout,
+	Interval: driveDeleteVisibilityPoll,
+}
+
 // CreateDriveFolder creates a Drive folder, optionally under a parent folder, and
 // deletes it during parent cleanup.
 func CreateDriveFolder(t *testing.T, parentT *testing.T, ctx context.Context, name string, defaultAs string, parentFolderToken string) string {
@@ -60,14 +72,18 @@ func CreateDriveFolder(t *testing.T, parentT *testing.T, ctx context.Context, na
 // returned a suppressed not_found or partial API error but the resource still
 // exists.
 func DeleteDriveResourceAndVerify(ctx context.Context, token, docType, defaultAs string) (*clie2e.Result, error) {
+	return deleteDriveResourceAndVerify(ctx, token, docType, defaultAs, driveDeleteVisibilityWait)
+}
+
+func deleteDriveResourceAndVerify(ctx context.Context, token, docType, defaultAs string, visibilityWait clie2e.WaitOptions) (*clie2e.Result, error) {
 	if defaultAs == "" {
 		defaultAs = "bot"
 	}

-	deleteResult, deleteErr := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
+	deleteResult, deleteErr := clie2e.RunCmd(ctx, clie2e.Request{
 		Args:      []string{"drive", "+delete", "--file-token", token, "--type", docType, "--yes"},
 		DefaultAs: defaultAs,
-	}, clie2e.RetryOptions{})
+	})
 	if deleteErr != nil || deleteResult == nil {
 		return deleteResult, deleteErr
 	}
@@ -82,35 +98,21 @@ func DeleteDriveResourceAndVerify(ctx context.Context, token, docType, defaultAs
 		}
 		return deleteResult, fmt.Errorf("drive resource %s/%s still exists after delete failed: exit=%d stdout=%s stderr=%s", docType, token, deleteResult.ExitCode, deleteResult.Stdout, deleteResult.Stderr)
 	}
-	if err := WaitDriveResourceDeleted(ctx, token, docType, defaultAs); err != nil {
-		return deleteResult, err
+	if err := waitDriveResourceDeleted(ctx, token, docType, defaultAs, visibilityWait); err != nil {
+		return deleteResult, clie2e.CleanupWarning(
+			fmt.Errorf("drive resource %s/%s still visible after accepted delete: %w", docType, token, err),
+		)
 	}
 	return deleteResult, nil
 }

-func WaitDriveResourceDeleted(ctx context.Context, token, docType, defaultAs string) error {
-	deadline := time.NewTimer(20 * time.Second)
-	defer deadline.Stop()
-	ticker := time.NewTicker(time.Second)
-	defer ticker.Stop()
-
-	for {
-		deleted, err := IsDriveResourceDeleted(ctx, token, docType, defaultAs)
-		if err != nil {
-			return err
-		}
-		if deleted {
-			return nil
-		}
-
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case <-deadline.C:
-			return fmt.Errorf("drive resource %s/%s still exists after delete", docType, token)
-		case <-ticker.C:
-		}
+func waitDriveResourceDeleted(ctx context.Context, token, docType, defaultAs string, opts clie2e.WaitOptions) error {
+	opts.TimeoutError = func() error {
+		return fmt.Errorf("drive resource %s/%s still exists %s after delete", docType, token, opts.Timeout)
 	}
+	return clie2e.WaitForCondition(ctx, opts, func() (bool, error) {
+		return IsDriveResourceDeleted(ctx, token, docType, defaultAs)
+	})
 }

 func IsDriveResourceDeleted(ctx context.Context, token, docType, defaultAs string) (bool, error) {
--- a/tests/cli_e2e/drive/helpers_test.go
+++ b/tests/cli_e2e/drive/helpers_test.go
@@ -5,8 +5,13 @@ package drive

 import (
 	"context"
+	"os"
+	"path/filepath"
 	"testing"
+	"time"

+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )

@@ -16,3 +21,59 @@ func createDriveFolder(t *testing.T, parentT *testing.T, ctx context.Context, na
 	require.NotEmpty(t, folderToken)
 	return folderToken
 }
+
+func TestDeleteDriveResourceAndVerify(t *testing.T) {
+	t.Run("successful delete with stale meta returns cleanup warning", func(t *testing.T) {
+		fake := mustWriteDriveCleanupFakeCLI(t)
+		t.Setenv(clie2e.EnvBinaryPath, fake)
+
+		result, err := deleteDriveResourceAndVerify(context.Background(), "fld_stale", "folder", "bot", clie2e.WaitOptions{
+			Timeout:  10 * time.Millisecond,
+			Interval: time.Millisecond,
+		})
+		require.NotNil(t, result)
+		assert.Equal(t, 0, result.ExitCode)
+		require.Error(t, err)
+		assert.True(t, clie2e.IsCleanupWarning(err), "err: %v", err)
+	})
+
+	t.Run("failed delete with existing meta remains fatal", func(t *testing.T) {
+		fake := mustWriteDriveCleanupFakeCLI(t)
+		t.Setenv(clie2e.EnvBinaryPath, fake)
+		t.Setenv("FAKE_DRIVE_DELETE_EXIT", "1")
+
+		result, err := DeleteDriveResourceAndVerify(context.Background(), "fld_existing", "folder", "bot")
+		require.NotNil(t, result)
+		assert.Equal(t, 1, result.ExitCode)
+		require.Error(t, err)
+		assert.False(t, clie2e.IsCleanupWarning(err), "err: %v", err)
+		assert.Contains(t, err.Error(), "still exists after delete failed")
+	})
+}
+
+func mustWriteDriveCleanupFakeCLI(t *testing.T) string {
+	t.Helper()
+
+	script := `#!/bin/sh
+if [ "$1" = "drive" ] && [ "$2" = "+delete" ]; then
+  if [ "${FAKE_DRIVE_DELETE_EXIT:-0}" != "0" ]; then
+    echo '{"ok":false,"error":{"type":"api","message":"delete failed"}}' >&2
+    exit "$FAKE_DRIVE_DELETE_EXIT"
+  fi
+  echo '{"ok":true}'
+  exit 0
+fi
+
+if [ "$1" = "api" ] && [ "$2" = "post" ] && [ "$3" = "/open-apis/drive/v1/metas/batch_query" ]; then
+  echo '{"ok":true,"data":{"metas":[{"url":"https://example.com/still-visible"}]}}'
+  exit 0
+fi
+
+echo "unexpected fake CLI args: $*" >&2
+exit 2
+`
+
+	binaryPath := filepath.Join(t.TempDir(), "fake-lark-cli")
+	require.NoError(t, os.WriteFile(binaryPath, []byte(script), 0o755))
+	return binaryPath
+}
--- a/tests/cli_e2e/mail/coverage.md
+++ b/tests/cli_e2e/mail/coverage.md
@@ -1,9 +1,9 @@
 # Mail CLI E2E Coverage

 ## Metrics
- Denominator: 63 leaf commands
- Covered: 14
- Coverage: 22.2%
+- Denominator: 65 leaf commands
+- Covered: 16
+- Coverage: 24.6%

 ## Summary
 - TestMail_DraftLifecycleWorkflowAsUser: proves a self-contained user draft workflow across `mail user_mailboxes profile`, `mail +draft-create`, `mail user_mailbox.drafts list`, `mail user_mailbox.drafts get`, `mail +draft-edit`, and `mail user_mailbox.drafts delete`; key `t.Run(...)` proof points are `get mailbox profile as user`, `create draft with shortcut as user`, `list draft as user`, `get created draft as user`, `inspect created draft as user`, `update draft subject with shortcut as user`, `inspect updated draft as user`, `delete draft as user`, and `verify draft removed from list as user`.
@@ -20,6 +20,8 @@
 | ✓ | mail +draft-send | shortcut | mail_draft_send_workflow_test.go::TestMail_DraftSendWorkflowAsUser/send draft with shortcut as user; mail_draft_send_dryrun_test.go::TestMail_DraftSendDryRun | `--draft-id`; `--mailbox me`; `--yes`; dry-run repeated/comma-separated `--draft-id` | sends a self-addressed draft through the batch shortcut and locks dry-run request shape |
 | ✓ | mail +forward | shortcut | mail_send_workflow_test.go::TestMail_SendWorkflowAsUser/forward received message with shortcut as user; mail_send_workflow_test.go::TestMail_SendWorkflowAsUser/inspect forward draft as user | `--message-id`; `--to`; `--body`; `--plain-text` | uses self-generated inbox message as source and inspects forwarded draft projection |
 | ✓ | mail +message | shortcut | mail_send_workflow_test.go::TestMail_SendWorkflowAsUser/get sent message as user; mail_send_workflow_test.go::TestMail_SendWorkflowAsUser/get received message as user | `--mailbox me`; `--message-id` | verifies both SENT and INBOX copies after self-send |
+| ✓ | mail +message-modify | shortcut | shortcuts/mail/mail_message_manage_test.go::TestMessageModify_DryRunShowsPlanWithoutValidationGET; shortcuts/mail/mail_message_manage_test.go::TestMessageModify_BatchesAndAggregatesPartialFailure | `--message-ids`; `--add-label-ids`; `--remove-label-ids`; `--add-folder`; `--dry-run` | unit/dry-run coverage locks validation, batching, request shape, and partial failure aggregation; live E2E needs controlled disposable messages/labels/folders |
+| ✓ | mail +message-trash | shortcut | shortcuts/mail/mail_message_manage_test.go::TestMessageTrash_RequiresYesAndBatches | `--message-ids`; `--yes`; `--dry-run` | unit coverage locks high-risk confirmation and batch_trash request shape; live E2E needs controlled disposable messages |
 | ✓ | mail +messages | shortcut | mail_send_workflow_test.go::TestMail_SendWorkflowAsUser/get both self sent messages as user | `--mailbox me`; `--message-ids` | batch reads both sent and received message copies |
 | ✓ | mail +reply | shortcut | mail_send_workflow_test.go::TestMail_SendWorkflowAsUser/reply to received message with shortcut as user; mail_send_workflow_test.go::TestMail_SendWorkflowAsUser/inspect reply draft as user | `--message-id`; `--body`; `--plain-text` | creates reply draft from self-generated inbox message and inspects quoted content |
 | ✕ | mail +reply-all | shortcut |  | none | self-send traffic leaves no stable non-self recipient set for deterministic reply-all assertions |
--- a/tests/cli_e2e/wiki/helpers_test.go
+++ b/tests/cli_e2e/wiki/helpers_test.go
@@ -5,6 +5,7 @@ package wiki

 import (
 	"context"
+	"errors"
 	"fmt"
 	"strings"
 	"testing"
@@ -203,6 +204,11 @@ type wikiNodeInfo struct {
 	ObjType   string
 }

+const (
+	wikiDeleteVisibilityTimeout = 30 * time.Second
+	wikiDeleteVisibilityPoll    = 3 * time.Second
+)
+
 // deleteWikiNodeAndVerify removes a wiki node, then polls get_node until the
 // original node token is gone. Wiki cleanup cannot use drive +delete because
 // wiki origin nodes need the backing obj_token and parent nodes must delete
@@ -333,28 +339,34 @@ func listWikiNodeChildren(ctx context.Context, spaceID, parentNodeToken string)
 }

 func waitWikiNodeDeleted(ctx context.Context, nodeToken string) error {
-	deadline := time.NewTimer(20 * time.Second)
-	defer deadline.Stop()
-	ticker := time.NewTicker(time.Second)
-	defer ticker.Stop()
+	var lastTransientErr error

-	for {
+	opts := clie2e.WaitOptions{
+		Timeout:  wikiDeleteVisibilityTimeout,
+		Interval: wikiDeleteVisibilityPoll,
+		TimeoutError: func() error {
+			if lastTransientErr != nil {
+				return fmt.Errorf("wiki node %s delete verification kept hitting transient errors: %w", nodeToken, lastTransientErr)
+			}
+			return fmt.Errorf("wiki node %s still exists after delete", nodeToken)
+		},
+	}
+
+	return clie2e.WaitForCondition(ctx, opts, func() (bool, error) {
 		deleted, err := isWikiNodeDeleted(ctx, nodeToken)
 		if err != nil {
-			return err
+			if isWikiVerifyTransientError(err) {
+				lastTransientErr = err
+				return false, nil
+			} else {
+				return false, err
+			}
 		}
 		if deleted {
-			return nil
+			return true, nil
 		}
-
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case <-deadline.C:
-			return fmt.Errorf("wiki node %s still exists after delete", nodeToken)
-		case <-ticker.C:
-		}
-	}
+		return false, nil
+	})
 }

 func isWikiNodeDeleted(ctx context.Context, nodeToken string) (bool, error) {
@@ -375,9 +387,31 @@ func isWikiNodeDeleted(ctx context.Context, nodeToken string) (bool, error) {
 	if isWikiNodeDeletedResult(result) {
 		return true, nil
 	}
+	if isWikiVerifyTransientResult(result) {
+		return false, wikiVerifyTransientError{
+			err: fmt.Errorf("verify wiki node %s after delete hit transient response: exit=%d stdout=%s stderr=%s", nodeToken, result.ExitCode, result.Stdout, result.Stderr),
+		}
+	}
 	return false, fmt.Errorf("verify wiki node %s after delete: exit=%d stdout=%s stderr=%s", nodeToken, result.ExitCode, result.Stdout, result.Stderr)
 }

+type wikiVerifyTransientError struct {
+	err error
+}
+
+func (e wikiVerifyTransientError) Error() string {
+	return e.err.Error()
+}
+
+func (e wikiVerifyTransientError) Unwrap() error {
+	return e.err
+}
+
+func isWikiVerifyTransientError(err error) bool {
+	var transient wikiVerifyTransientError
+	return err != nil && errors.As(err, &transient)
+}
+
 func wikiAPISuccess(stdout string) bool {
 	if ok := gjson.Get(stdout, "ok"); ok.Exists() {
 		return ok.Bool()
@@ -404,6 +438,55 @@ func isWikiNodeDeletedResult(result *clie2e.Result) bool {
 		strings.Contains(combined, "not found")
 }

+func isWikiVerifyTransientResult(result *clie2e.Result) bool {
+	if result == nil {
+		return false
+	}
+	payload := result.Stdout
+	if strings.TrimSpace(payload) == "" {
+		payload = result.Stderr
+	}
+	if gjson.Get(payload, "error.type").String() != "internal" ||
+		gjson.Get(payload, "error.subtype").String() != "invalid_response" {
+		return false
+	}
+	message := strings.ToLower(gjson.Get(payload, "error.message").String())
+	return strings.Contains(message, "http 429") ||
+		strings.Contains(message, "http 500") ||
+		strings.Contains(message, "http 502") ||
+		strings.Contains(message, "http 503") ||
+		strings.Contains(message, "http 504")
+}
+
+func TestWikiVerifyTransientResult(t *testing.T) {
+	t.Run("matches invalid response from transient http status", func(t *testing.T) {
+		result := &clie2e.Result{
+			ExitCode: 5,
+			Stderr:   `{"ok":false,"error":{"type":"internal","subtype":"invalid_response","message":"SDK returned an invalid JSON response: failed to parse TAT response (HTTP 429): invalid character 'r' looking for beginning of value"}}`,
+		}
+
+		require.True(t, isWikiVerifyTransientResult(result))
+	})
+
+	t.Run("does not match unrelated invalid response", func(t *testing.T) {
+		result := &clie2e.Result{
+			ExitCode: 5,
+			Stderr:   `{"ok":false,"error":{"type":"internal","subtype":"invalid_response","message":"SDK returned an invalid JSON response: malformed body"}}`,
+		}
+
+		require.False(t, isWikiVerifyTransientResult(result))
+	})
+
+	t.Run("does not match api errors", func(t *testing.T) {
+		result := &clie2e.Result{
+			ExitCode: 1,
+			Stderr:   `{"ok":false,"error":{"type":"api","subtype":"conflict","message":"resource contention occurred, please retry","retryable":true}}`,
+		}
+
+		require.False(t, isWikiVerifyTransientResult(result))
+	})
+}
+
 func findWikiNodeByToken(t *testing.T, ctx context.Context, spaceID string, nodeToken string, parentNodeTokens ...string) gjson.Result {
 	t.Helper()
Author	SHA1	Message	Date
bubbmon233	f495cbb166	feat(mail): add message modify and trash shortcuts (#1567 )	2026-07-07 21:44:40 +08:00
Yuxuan Zhao	6f95c5eb22	e2e: harden CLI E2E retry, cleanup, and domain selection (#1709 )	2026-07-07 19:41:11 +08:00