chore: cut v1.0.13 with reviewed release notes (#519)

Change-Id: If9a08002588cc9ae96280bdd8bbc4a05ba0f92a1

.codecov.yml

@@ -6,3 +6,6 @@ coverage:
     patch:
       default:
         target: 60%
+
+github_checks:
+  annotations: true

.github/workflows/arch-audit.yml

@@ -0,0 +1,116 @@
+name: Architecture Audit
+
+on:
+  schedule:
+    - cron: '0 9 * * 1' # Monday 09:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+      - name: Fetch meta data
+        run: python3 scripts/fetch_meta.py
+
+      - name: Dead code detection
+        run: |
+          echo "## Dead Code" >> report.md
+          go run golang.org/x/tools/cmd/deadcode@v0.31.0 -test ./... 2>&1 | tee deadcode.txt
+          count=$(wc -l < deadcode.txt | tr -d ' ')
+          echo "Found **$count** unreachable functions" >> report.md
+          echo '```' >> report.md
+          cat deadcode.txt >> report.md
+          echo '```' >> report.md
+
+      - name: Package complexity
+        run: |
+          echo "## Package Complexity" >> report.md
+          echo "" >> report.md
+          echo "Packages exceeding 2 000 lines or 20 files:" >> report.md
+          echo "" >> report.md
+          echo "| Package | Files | Lines | Deps |" >> report.md
+          echo "|---------|-------|-------|------|" >> report.md
+          found=0
+          for pkg in $(go list ./cmd/... ./internal/... ./shortcuts/...); do
+            dir=$(go list -f '{{.Dir}}' "$pkg")
+            files=$(find "$dir" -maxdepth 1 -name '*.go' ! -name '*_test.go' | wc -l | tr -d ' ')
+            lines=$(find "$dir" -maxdepth 1 -name '*.go' ! -name '*_test.go' -exec cat {} + 2>/dev/null | wc -l | tr -d ' ')
+            deps=$(go list -f '{{len .Imports}}' "$pkg")
+            if [ "$lines" -gt 2000 ] || [ "$files" -gt 20 ]; then
+              echo "| **$pkg** | **$files** | **$lines** | **$deps** |" >> report.md
+              found=1
+            fi
+          done
+          if [ "$found" = "0" ]; then
+            echo "| _(none)_ | | | |" >> report.md
+          fi
+
+      - name: Dependency freshness
+        run: |
+          echo "## Outdated Dependencies" >> report.md
+          echo '```' >> report.md
+          go list -m -u all 2>/dev/null | grep '\[' >> report.md || echo "All dependencies up to date" >> report.md
+          echo '```' >> report.md
+
+      - name: Circular dependency check
+        run: |
+          echo "## Circular Dependencies" >> report.md
+          go list -f '{{.ImportPath}} {{join .Imports " "}}' ./... | \
+            go run golang.org/x/tools/cmd/digraph@v0.31.0 scc 2>&1 | tee cycles.txt
+          if [ -s cycles.txt ]; then
+            echo '```' >> report.md
+            cat cycles.txt >> report.md
+            echo '```' >> report.md
+          else
+            echo "No circular dependencies detected." >> report.md
+          fi
+
+      - name: E2E coverage gaps
+        run: |
+          echo "## E2E Coverage Gaps" >> report.md
+          echo "" >> report.md
+          echo "Shortcut domains without E2E tests:" >> report.md
+          echo "" >> report.md
+          found=0
+          for domain in $(ls -d shortcuts/*/); do
+            name=$(basename "$domain")
+            if [ "$name" = "common" ]; then continue; fi
+            if [ ! -d "tests/cli_e2e/$name" ]; then
+              echo "- **$name** (no tests/cli_e2e/$name/)" >> report.md
+              found=1
+            fi
+          done
+          if [ "$found" = "0" ]; then
+            echo "All shortcut domains have E2E test directories." >> report.md
+          fi
+
+      - name: Coverage
+        run: |
+          echo "## Coverage" >> report.md
+          packages=$(go list ./... | grep -v 'tests/cli_e2e')
+          go test -coverprofile=coverage.txt -covermode=atomic $packages 2>/dev/null || true
+          total=$(go tool cover -func=coverage.txt 2>/dev/null | grep total | awk '{print $3}')
+          echo "Current total coverage: **${total:-n/a}**" >> report.md
+
+      - name: Publish report
+        run: |
+          echo "# Architecture Audit Report — $(date +%Y-%m-%d)" > $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          cat report.md >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload report artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: arch-audit-${{ github.run_number }}
+          path: report.md
+          retention-days: 90

.github/workflows/ci.yml

@@ -0,0 +1,333 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  # ── Layer 1: Fast Gate ─────────────────────────────────────────────
+  fast-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+      - name: Fetch meta data
+        run: python3 scripts/fetch_meta.py
+      - name: Build
+        run: go build ./...
+      - name: Vet
+        run: go vet ./...
+      - name: Check formatting
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "$unformatted"
+            echo "::error::Unformatted Go files detected — run 'gofmt -w .' and commit"
+            exit 1
+          fi
+      - name: Check go.mod tidiness
+        run: |
+          go mod tidy
+          if ! git diff --quiet go.mod go.sum; then
+            echo "::error::go.mod or go.sum is not tidy. Run 'go mod tidy' and commit the changes."
+            git diff go.mod go.sum
+            exit 1
+          fi
+
+  # ── Layer 2: Quality Gate ──────────────────────────────────────────
+  unit-test:
+    needs: fast-gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+      - name: Fetch meta data
+        run: python3 scripts/fetch_meta.py
+      - name: Run tests
+        run: go test -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/...
+
+  lint:
+    needs: fast-gate
+    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: Fetch meta data
+        run: python3 scripts/fetch_meta.py
+      - name: Run golangci-lint
+        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main
+
+  coverage:
+    needs: fast-gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+      - name: Fetch meta data
+        run: python3 scripts/fetch_meta.py
+      - name: Run tests with coverage
+        run: |
+          packages=$(go list ./... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '^github.com/larksuite/cli/tests/cli_e2e/')
+          go test -race -coverprofile=coverage.txt -covermode=atomic $packages
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@3f20e214133d0983f9a10f3d63b0faf9241a3daa # v6
+        with:
+          files: coverage.txt
+          token: ${{ secrets.CODECOV_TOKEN }}
+      - name: Check coverage threshold
+        run: |
+          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}' | tr -d '%')
+          threshold=40
+          echo "Coverage: ${total}% (threshold: ${threshold}%)"
+          if (( $(echo "$total < $threshold" | bc -l) )); then
+            echo "::error::Coverage ${total}% is below threshold ${threshold}%"
+            exit 1
+          fi
+      - name: Coverage summary
+        if: ${{ !cancelled() }}
+        run: |
+          if [ ! -f coverage.txt ]; then
+            echo "No coverage data available" >> $GITHUB_STEP_SUMMARY
+            exit 0
+          fi
+          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}')
+          echo "## Coverage Report" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "<details><summary>Details</summary>" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          go tool cover -func=coverage.txt >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "</details>" >> $GITHUB_STEP_SUMMARY
+
+  deadcode:
+    needs: fast-gate
+    if: ${{ github.event_name == 'pull_request' }}
+    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: Fetch meta data
+        run: python3 scripts/fetch_meta.py
+      - name: Dead code check (incremental)
+        run: |
+          # Analyze current HEAD (strip line:col for stable diff across line shifts)
+          # Filter "go: downloading ..." lines to avoid false diffs from module cache state
+          go run golang.org/x/tools/cmd/deadcode@v0.31.0 ./... 2>&1 | \
+            grep -v '^go: ' | \
+            sed 's/:[0-9][0-9]*:[0-9][0-9]*:/:/' | sort > /tmp/dc-head.txt
+
+          # Analyze base branch via worktree
+          git worktree add -q /tmp/dc-base "origin/${{ github.base_ref }}"
+          (cd /tmp/dc-base && python3 scripts/fetch_meta.py && \
+           go run golang.org/x/tools/cmd/deadcode@v0.31.0 ./... 2>&1 | \
+            grep -v '^go: ' | \
+            sed 's/:[0-9][0-9]*:[0-9][0-9]*:/:/' | sort > /tmp/dc-base.txt) || {
+            echo "::warning::Failed to analyze base branch — skipping incremental dead code check"
+            git worktree remove -f /tmp/dc-base 2>/dev/null || true
+            exit 0
+          }
+          git worktree remove -f /tmp/dc-base
+
+          # Only new dead code blocks the PR
+          comm -23 /tmp/dc-head.txt /tmp/dc-base.txt > /tmp/dc-new.txt
+          if [ -s /tmp/dc-new.txt ]; then
+            echo "::group::New dead code"
+            cat /tmp/dc-new.txt
+            echo "::endgroup::"
+            echo "::error::New dead code detected — remove unreachable functions before merging"
+            exit 1
+          fi
+          echo "No new dead code introduced"
+
+  # ── Layer 3: E2E Gate ──────────────────────────────────────────────
+  e2e-dry-run:
+    needs: [unit-test, lint]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+      - name: Build lark-cli
+        run: make build
+      - name: Run dry-run E2E tests
+        env:
+          LARK_CLI_BIN: ${{ github.workspace }}/lark-cli
+          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-live:
+    needs: [unit-test, lint]
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
+    runs-on: ubuntu-latest
+    env:
+      TEST_BOT1_APP_ID: ${{ secrets.TEST_BOT1_APP_ID }}
+      TEST_BOT1_APP_SECRET: ${{ secrets.TEST_BOT1_APP_SECRET }}
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+      - name: Build lark-cli
+        run: make build
+      - name: Configure bot credentials
+        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"
+            exit 1
+          fi
+          printf '%s\n' "$TEST_BOT1_APP_SECRET" | ./lark-cli config init --app-id "$TEST_BOT1_APP_ID" --app-secret-stdin
+      - name: Run CLI E2E tests
+        env:
+          LARK_CLI_BIN: ${{ github.workspace }}/lark-cli
+        run: |
+          packages=$(go list ./tests/cli_e2e/... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '/demo$')
+          if [ -z "$packages" ]; then
+            echo "No CLI E2E packages to test after exclusions."
+            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
+      - name: Publish CLI E2E test report
+        if: ${{ !cancelled() }}
+        uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2 # v3.0.0
+        with:
+          name: CLI E2E Tests
+          path: cli-e2e-report.xml
+          reporter: java-junit
+          use-actions-summary: true
+          list-suites: all
+          list-tests: all
+
+  # ── Layer 4: Security & Compliance (parallel with L2-L3) ──────────
+  security:
+    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: Fetch meta data
+        run: python3 scripts/fetch_meta.py
+      - name: Gitleaks
+        if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
+        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_KEY }}
+      - name: govulncheck
+        continue-on-error: true
+        run: go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...
+      - name: Check dependency licenses
+        run: go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown
+
+  license-header:
+    if: ${{ github.event_name == 'pull_request' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - name: Check license headers
+        uses: apache/skywalking-eyes/header@8c96ee223558797cdd9eba82c0919258e1cf2dad
+        with:
+          config: .licenserc.yaml
+
+  # ── Results Gate (single required check for branch protection) ─────
+  results:
+    if: ${{ always() }}
+    needs: [fast-gate, unit-test, lint, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate results
+        run: |
+          echo "## CI Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Layer | Job | Status |" >> $GITHUB_STEP_SUMMARY
+          echo "|-------|-----|--------|" >> $GITHUB_STEP_SUMMARY
+          echo "| L1 | fast-gate | ${{ needs.fast-gate.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L2 | unit-test | ${{ needs.unit-test.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L2 | lint | ${{ needs.lint.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L2 | coverage | ${{ needs.coverage.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L2 | deadcode | ${{ needs.deadcode.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L3 | e2e-dry-run | ${{ needs.e2e-dry-run.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L3 | e2e-live | ${{ needs.e2e-live.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L4 | security | ${{ needs.security.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L4 | license-header | ${{ needs.license-header.result }} |" >> $GITHUB_STEP_SUMMARY
+
+          # Any failure or cancellation in any job blocks the merge.
+          # Legitimately skipped jobs (deadcode on push, e2e-live on fork,
+          # license-header on push) are OK.
+          FAILED=0
+          for result in \
+            "${{ needs.fast-gate.result }}" \
+            "${{ needs.unit-test.result }}" \
+            "${{ needs.lint.result }}" \
+            "${{ needs.coverage.result }}" \
+            "${{ needs.deadcode.result }}" \
+            "${{ needs.e2e-dry-run.result }}" \
+            "${{ needs.e2e-live.result }}" \
+            "${{ needs.security.result }}" \
+            "${{ needs.license-header.result }}"; do
+            if [ "$result" = "failure" ] || [ "$result" = "cancelled" ]; then
+              FAILED=1
+            fi
+          done
+
+          if [ "$FAILED" = "1" ]; then
+            echo ""
+            echo "::error::One or more CI jobs failed — see table above"
+            exit 1
+          fi

.github/workflows/cli-e2e.yml

@@ -1,83 +0,0 @@
-name: CLI E2E Tests
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - Makefile
-      - scripts/fetch_meta.py
-      - tests/cli_e2e/**
-      - .github/workflows/cli-e2e.yml
-  pull_request:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - Makefile
-      - scripts/fetch_meta.py
-      - tests/cli_e2e/**
-      - .github/workflows/cli-e2e.yml
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  actions: read
-  checks: write
-
-jobs:
-  cli-e2e:
-    # Forked pull_request runs do not receive repository/org secrets except GITHUB_TOKEN.
-    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
-    runs-on: ubuntu-latest
-    env:
-      TEST_BOT1_APP_ID: ${{ secrets.TEST_BOT1_APP_ID }}
-      TEST_BOT1_APP_SECRET: ${{ secrets.TEST_BOT1_APP_SECRET }}
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
-        with:
-          python-version: '3.x'
-
-      - name: Build lark-cli
-        run: make build
-
-      - name: Configure bot credentials
-        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"
-            exit 1
-          fi
-          printf '%s\n' "$TEST_BOT1_APP_SECRET" | ./lark-cli config init --app-id "$TEST_BOT1_APP_ID" --app-secret-stdin
-
-      - name: Run CLI E2E tests
-        env:
-          LARK_CLI_BIN: ${{ github.workspace }}/lark-cli
-        run: |
-          packages=$(go list ./tests/cli_e2e/... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '/demo$')
-          if [ -z "$packages" ]; then
-            echo "No CLI E2E packages to test after exclusions."
-            exit 1
-          fi
-          # gotestsum requires --packages when --rerun-fails is combined with go test args after --.
-          packages_arg=$(printf '%s\n' "$packages" | paste -sd' ' -)
-          go run gotest.tools/gotestsum@v1.12.3 --rerun-fails=2 --rerun-fails-max-failures=20 --packages="$packages_arg" --format testname --junitfile cli-e2e-report.xml -- -count=1 -v
-
-      - name: Publish CLI E2E test report
-        if: ${{ !cancelled() }}
-        uses: dorny/test-reporter@a43b3a5f7366b97d083190328d2c652e1a8b6aa2 # v3.0.0
-        with:
-          name: CLI E2E Tests
-          path: cli-e2e-report.xml
-          reporter: java-junit
-          use-actions-summary: true
-          list-suites: all
-          list-tests: all

.github/workflows/coverage.yml

@@ -1,58 +0,0 @@
-name: Coverage
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - "**.go"
-      - "!tests/cli_e2e/**"
-      - go.mod
-      - go.sum
-      - .github/workflows/coverage.yml
-  pull_request:
-    branches: [main]
-    paths:
-      - "**.go"
-      - "!tests/cli_e2e/**"
-      - go.mod
-      - go.sum
-      - .github/workflows/coverage.yml
-
-permissions:
-  contents: read
-
-jobs:
-  coverage:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
-        with:
-          go-version-file: go.mod
-
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
-        with:
-          python-version: '3.x'
-
-      - name: Fetch meta data
-        run: python3 scripts/fetch_meta.py
-
-      - name: Run tests with coverage
-        run: |
-          packages=$(go list ./... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '^github.com/larksuite/cli/tests/cli_e2e/')
-          go test -race -coverprofile=coverage.txt -covermode=atomic $packages
-
-      - name: Generate coverage report
-        run: |
-          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}')
-          echo "## Coverage Report" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "<details><summary>Details</summary>" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo '```' >> $GITHUB_STEP_SUMMARY
-          go tool cover -func=coverage.txt >> $GITHUB_STEP_SUMMARY
-          echo '```' >> $GITHUB_STEP_SUMMARY
-          echo "</details>" >> $GITHUB_STEP_SUMMARY

.github/workflows/gitleaks.yml

@@ -1,28 +0,0 @@
-name: Gitleaks
-
-on:
-  pull_request:
-    branches: [main]
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  gitleaks:
-    # Forked pull_request runs do not receive repository/org secrets except GITHUB_TOKEN.
-    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          fetch-depth: 0
-
-      - uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
-        env:
-          # GITHUB_TOKEN is provided automatically by GitHub Actions.
-          # GITLEAKS_KEY must be configured as a repository secret.
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_KEY }}

.github/workflows/license-header.yml

@@ -1,26 +0,0 @@
-name: License Header
-
-on:
-  pull_request:
-    branches: [main]
-    paths:
-      - "**/*.go"
-      - "**/*.js"
-      - "**/*.py"
-      - .licenserc.yaml
-      - .github/workflows/license-header.yml
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  header-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-
-      - name: Check license headers
-        uses: apache/skywalking-eyes/header@8c96ee223558797cdd9eba82c0919258e1cf2dad
-        with:
-          config: .licenserc.yaml

.github/workflows/lint.yml

@@ -1,60 +0,0 @@
-name: Lint
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - .golangci.yml
-      - .github/workflows/lint.yml
-  pull_request:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - .golangci.yml
-      - .github/workflows/lint.yml
-
-permissions:
-  contents: read
-
-jobs:
-  golangci-lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
-        with:
-          go-version-file: go.mod
-
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
-        with:
-          python-version: '3.x'
-
-      - name: Fetch meta_data.json
-        run: python3 scripts/fetch_meta.py
-
-      - name: Ensure go.mod and go.sum are tidy
-        run: |
-          go mod tidy
-          if ! git diff --quiet go.mod go.sum; then
-            echo "::error::go.mod or go.sum is not tidy. Run 'go mod tidy' and commit the changes."
-            git diff go.mod go.sum
-            exit 1
-          fi
-
-      - name: Run golangci-lint
-        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main
-
-      - name: Run govulncheck
-        continue-on-error: true # informational until Go version is upgraded
-        run: go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...
-
-      - name: Check dependency licenses
-        run: go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown

.github/workflows/tests.yml

@@ -1,43 +0,0 @@
-name: Tests
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - .github/workflows/tests.yml
-  pull_request:
-    branches: [main]
-    paths:
-      - "**.go"
-      - go.mod
-      - go.sum
-      - .github/workflows/tests.yml
-
-permissions:
-  contents: read
-
-jobs:
-  unit-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-
-      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
-        with:
-          go-version-file: go.mod
-
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
-        with:
-          python-version: '3.x'
-
-      - name: Fetch meta data
-        run: python3 scripts/fetch_meta.py
-
-      - name: Run tests
-        run: go test -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/...
-
-      - name: Build
-        run: go build -v ./...

.golangci.yml

@@ -70,6 +70,14 @@ linters:
               desc: >-
                 shortcuts must not import internal/vfs/localfileio directly.
                 Use runtime.FileIO() for file operations or runtime.ValidatePath() for path validation.
+        shortcuts-no-raw-http:
+          files:
+            - "**/shortcuts/**"
+          deny:
+            - pkg: "net/http"
+              desc: >-
+                use RuntimeContext.DoAPI/CallAPI/DoAPIJSON instead of raw net/http.
+                The client layer handles auth, headers, and error normalization.
     forbidigo:
       forbid:
         # ── os: already wrapped in internal/vfs ──
@@ -100,6 +108,16 @@ linters:
           msg: >-
             Do not use os.Exit in shortcuts/. Return an error instead and let
             the caller (cmd layer) decide how to terminate.
+        # ── output: shortcuts must use ctx.Out() ──
+        - pattern: fmt\.Print(f|ln)?\b
+          msg: >-
+            use ctx.Out() or ctx.OutFormat() for structured JSON output.
+            fmt.Print* bypasses the output envelope and breaks --jq/--format.
+        # ── logging: shortcuts must return errors, not log.Fatal ──
+        - pattern: log\.(Print|Fatal|Panic)(f|ln)?\b
+          msg: >-
+            use structured error return, not log.Fatal/Panic.
+            Shortcuts must return errors to the framework for proper exit code handling.
         # ── filepath: functions that access the filesystem ──
         - pattern: filepath\.(EvalSymlinks|Walk|WalkDir|Glob|Abs)\b
           msg: >-

AGENTS.md

@@ -18,9 +18,11 @@ make test           # Full: vet + unit + integration
 ## Pre-PR Checks (match CI gates)
 
 1. `make unit-test`
-2. `go mod tidy` — must not change `go.mod`/`go.sum`
-3. `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main`
-4. If dependencies changed: `go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown`
+2. `go vet ./...`
+3. `gofmt -l .` — must produce no output
+4. `go mod tidy` — must not change `go.mod`/`go.sum`
+5. `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main`
+6. If dependencies changed: `go run github.com/google/go-licenses/v2@v2.0.1 check ./... --disallowed_types=forbidden,restricted,reciprocal,unknown`
 
 ## Commit & PR
 
@@ -76,3 +78,26 @@ CLI arguments are untrusted (they come from AI agents). Call `validate.SafeInput
 - Every behavior change needs a test alongside the change.
 - `cmdutil.TestFactory(t, config)` for test factories.
 - `t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())` to isolate config state.
+
+### E2E Testing
+
+**Dry-run E2E (required for every shortcut change)**
+- Validates request structure without calling real APIs
+- Place in `tests/cli_e2e/dryrun/` or the corresponding domain directory
+- Set env vars `LARKSUITE_CLI_APP_ID`/`APP_SECRET`/`BRAND`, use `--dry-run`, assert method/URL/params
+- No secrets needed — runs on fork PRs
+- Explore correct params with `lark-cli <domain> --help` and `lark-cli schema` first
+
+**Live E2E (required for new flows or behavior changes)**
+- Validates real API round-trips
+- Place in `tests/cli_e2e/<domain>/`
+- Must be self-contained: create -> use -> cleanup
+- Needs bot credentials (CI secrets, skipped on fork PRs)
+- Reference: `tests/cli_e2e/task/task_status_workflow_test.go`
+
+| Change | Dry-run E2E | Live E2E |
+|--------|:-----------:|:--------:|
+| New shortcut | Required | Required |
+| Modify shortcut flags/params | Required | If behavior changes |
+| Shortcut bug fix | Required | If regression risk |
+| Internal refactor (no shortcut impact) | Not needed | Not needed |

CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.13] - 2026-04-16
+
+### Features
+
+- **im**: Support user access token for file, image, audio, and video upload, aligning upload and send identity with `--as` flag (#474)
+- **drive**: Add `drive +create-folder` shortcut with root-folder fallback and bot-mode auto-grant (#470)
+- **wiki**: Add bot-mode auto-grant support to `wiki +node-create` (#470)
+- **doc**: Default `skip_task_detail` in `docs +fetch` to reduce unnecessary task detail expansion (#471)
+
+### Bug Fixes
+
+- **im**: Preserve original URL filename for uploaded file messages instead of generic `media.ext` names (#514)
+- **whiteboard**: Use atomic overwrite API parameter for `whiteboard +update`, replacing read-then-delete approach (#483)
+
+### Documentation
+
+- **base**: Unify record batch write limit to 200 and enforce serial writes for continuous operations (#499)
+- **base**: Remove redundant reference documentation and command grouping chapters from SKILL.md (#500)
+
+### CI
+
+- Consolidate workflows into layered CI pyramid with single `results` gate (#510)
+
+## [v1.0.12] - 2026-04-15
+
+### Features
+
+- Add guided npm install flow that installs or upgrades the CLI, installs AI skills, and walks through app config and auth login (#464)
+- **mail**: Add email signature support with `+signature`, `--signature-id` compose flags, and draft signature edit operations (#485)
+- **mail**: Return recall hints for sent emails when recall is available (#481)
+- **slides**: Add `+media-upload` and support `@path` image placeholders in `+create --slides` (#450)
+
+### Documentation
+
+- **mail**: Add recipient search guidance to the mail skill workflow (#437)
+- **calendar/vc**: Route past meeting queries to `lark-vc` and clarify historical date matching in skills (#482, #480)
+
+## [v1.0.11] - 2026-04-14
+
+### Features
+
+- **sheets**: Add dropdown shortcuts for data validation management (`+set-dropdown`, `+update-dropdown`, `+get-dropdown`, `+delete-dropdown`) (#461)
+- **task**: Add task search, tasklist search, related-task, set-ancestor, and subscribe-event shortcuts (#377)
+- Streamline interactive login by removing the extra auth confirmation step (#451)
+
+### Bug Fixes
+
+- **base**: Validate JSON object inputs for base shortcuts and reject `null` objects (#458)
+
+### Documentation
+
+- **sheets**: Document value formats for formulas and special field types (#456)
+- **readme**: Add Attendance to the features table (#460)
+
 ## [v1.0.10] - 2026-04-13
 
 ### Features
@@ -328,6 +382,9 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.13]: https://github.com/larksuite/cli/releases/tag/v1.0.13
+[v1.0.12]: https://github.com/larksuite/cli/releases/tag/v1.0.12
+[v1.0.11]: https://github.com/larksuite/cli/releases/tag/v1.0.11
 [v1.0.10]: https://github.com/larksuite/cli/releases/tag/v1.0.10
 [v1.0.9]: https://github.com/larksuite/cli/releases/tag/v1.0.9
 [v1.0.8]: https://github.com/larksuite/cli/releases/tag/v1.0.8

cmd/config/init_messages.go

@@ -10,12 +10,12 @@ import (
 )
 
 type initMsg struct {
-	SelectAction       string
-	CreateNewApp       string
-	ConfigExistingApp  string
-	Platform           string
-	SelectPlatform     string
-	Feishu             string
+	SelectAction      string
+	CreateNewApp      string
+	ConfigExistingApp string
+	Platform          string
+	SelectPlatform    string
+	Feishu            string
 	// TTY (interactive) variants
 	ScanQRCode     string // header shown above QR code
 	ScanOrOpenLink string // post-QR alt link prompt ("or open...")
@@ -29,11 +29,11 @@ type initMsg struct {
 }
 
 var initMsgZh = &initMsg{
-	SelectAction:       "选择操作",
-	CreateNewApp:       "一键配置应用 (推荐) ",
-	ConfigExistingApp:  "手动输入应用凭证",
-	Platform:           "平台",
-	SelectPlatform:     "选择平台",
+	SelectAction:         "选择操作",
+	CreateNewApp:         "一键配置应用 (推荐) ",
+	ConfigExistingApp:    "手动输入应用凭证",
+	Platform:             "平台",
+	SelectPlatform:       "选择平台",
 	Feishu:               "飞书",
 	ScanQRCode:           "\n使用飞书 / Lark 扫码配置应用：\n\n",
 	ScanOrOpenLink:       "\n或打开以下链接完成配置：\n",
@@ -46,11 +46,11 @@ var initMsgZh = &initMsg{
 }
 
 var initMsgEn = &initMsg{
-	SelectAction:       "Select action",
-	CreateNewApp:       "Set up your app with one click (Recommended)",
-	ConfigExistingApp:  "Enter app credentials yourself",
-	Platform:           "Platform",
-	SelectPlatform:     "Select platform",
+	SelectAction:         "Select action",
+	CreateNewApp:         "Set up your app with one click (Recommended)",
+	ConfigExistingApp:    "Enter app credentials yourself",
+	Platform:             "Platform",
+	SelectPlatform:       "Select platform",
 	Feishu:               "Feishu",
 	ScanQRCode:           "\nScan the QR code with Feishu/Lark:\n\n",
 	ScanOrOpenLink:       "\nOr open the link below in your browser:\n",

cmd/config/init_messages_test.go

@@ -48,12 +48,12 @@ func TestInitMsgEn_AllFieldsNonEmpty(t *testing.T) {
 func assertAllFieldsNonEmpty(t *testing.T, msg *initMsg, label string) {
 	t.Helper()
 	fields := map[string]string{
-		"SelectAction":       msg.SelectAction,
-		"CreateNewApp":       msg.CreateNewApp,
-		"ConfigExistingApp":  msg.ConfigExistingApp,
-		"Platform":           msg.Platform,
-		"SelectPlatform":     msg.SelectPlatform,
-		"Feishu":             msg.Feishu,
+		"SelectAction":         msg.SelectAction,
+		"CreateNewApp":         msg.CreateNewApp,
+		"ConfigExistingApp":    msg.ConfigExistingApp,
+		"Platform":             msg.Platform,
+		"SelectPlatform":       msg.SelectPlatform,
+		"Feishu":               msg.Feishu,
 		"ScanQRCode":           msg.ScanQRCode,
 		"ScanOrOpenLink":       msg.ScanOrOpenLink,
 		"WaitingForScan":       msg.WaitingForScan,

cmd/service/service.go

@@ -101,16 +101,16 @@ type ServiceMethodOptions struct {
 	SchemaPath string
 
 	// Flags
-	Params    string
-	Data      string
-	As        core.Identity
-	Output    string
-	PageAll   bool
-	PageLimit int
-	PageDelay int
-	Format    string
-	JqExpr    string
-	DryRun    bool
+	Params     string
+	Data       string
+	As         core.Identity
+	Output     string
+	PageAll    bool
+	PageLimit  int
+	PageDelay  int
+	Format     string
+	JqExpr     string
+	DryRun     bool
 	File       string   // --file flag value
 	FileFields []string // auto-detected file field names from metadata
 }

internal/selfupdate/updater.go

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

internal/util/strings_test.go

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package util
+
+import "testing"
+
+func TestTruncateStr(t *testing.T) {
+	tests := []struct {
+		name string
+		s    string
+		n    int
+		want string
+	}{
+		{"short string", "hello", 10, "hello"},
+		{"exact length", "hello", 5, "hello"},
+		{"truncate", "hello world", 5, "hello"},
+		{"empty", "", 5, ""},
+		{"zero limit", "hello", 0, ""},
+		{"CJK characters", "你好世界测试", 4, "你好世界"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := TruncateStr(tt.s, tt.n); got != tt.want {
+				t.Errorf("TruncateStr(%q, %d) = %q, want %q", tt.s, tt.n, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestTruncateStrWithEllipsis(t *testing.T) {
+	tests := []struct {
+		name string
+		s    string
+		n    int
+		want string
+	}{
+		{"short string", "hello", 10, "hello"},
+		{"exact length", "hello", 5, "hello"},
+		{"truncate with ellipsis", "hello world", 8, "hello..."},
+		{"limit less than 3", "hello", 2, "he"},
+		{"limit equals 3", "hello world", 3, "..."},
+		{"empty", "", 5, ""},
+		{"CJK with ellipsis", "你好世界测试", 5, "你好..."},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := TruncateStrWithEllipsis(tt.s, tt.n); got != tt.want {
+				t.Errorf("TruncateStrWithEllipsis(%q, %d) = %q, want %q", tt.s, tt.n, got, tt.want)
+			}
+		})
+	}
+}

package-lock.json

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

package.json

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

scripts/install-wizard.js

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

scripts/install.js

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

scripts/run.js

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

shortcuts/common/runner.go

@@ -263,8 +263,8 @@ func (ctx *RuntimeContext) DoAPI(req *larkcore.ApiReq, opts ...larkcore.RequestO
 }
 
 // DoAPIAsBot executes a raw Lark SDK request using bot identity (tenant access token),
-// regardless of the current --as flag. Use this for bot-only APIs (e.g. image/file upload)
-// that must be called with TAT even when the surrounding shortcut runs as user.
+// regardless of the current --as flag. Use this for APIs that must always be called
+// with TAT even when the surrounding shortcut runs as user.
 func (ctx *RuntimeContext) DoAPIAsBot(req *larkcore.ApiReq, opts ...larkcore.RequestOptionFunc) (*larkcore.ApiResp, error) {
 	ac, err := ctx.getAPIClient()
 	if err != nil {

shortcuts/doc/docs_fetch.go

@@ -28,6 +28,8 @@ var DocsFetch = common.Shortcut{
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		args := map[string]interface{}{
 			"doc_id": runtime.Str("doc"),
+			// Default to skipping embedded task detail expansion for faster +fetch output.
+			"skip_task_detail": true,
 		}
 		if v := runtime.Str("offset"); v != "" {
 			n, _ := strconv.Atoi(v)
@@ -46,6 +48,8 @@ var DocsFetch = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		args := map[string]interface{}{
 			"doc_id": runtime.Str("doc"),
+			// Default to skipping embedded task detail expansion for faster +fetch output.
+			"skip_task_detail": true,
 		}
 		if v := runtime.Str("offset"); v != "" {
 			n, _ := strconv.Atoi(v)

shortcuts/drive/drive_create_folder.go

@@ -0,0 +1,120 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type driveCreateFolderSpec struct {
+	Name        string
+	FolderToken string
+}
+
+func newDriveCreateFolderSpec(runtime *common.RuntimeContext) driveCreateFolderSpec {
+	return driveCreateFolderSpec{
+		Name:        strings.TrimSpace(runtime.Str("name")),
+		FolderToken: strings.TrimSpace(runtime.Str("folder-token")),
+	}
+}
+
+func (s driveCreateFolderSpec) RequestBody() map[string]interface{} {
+	return map[string]interface{}{
+		"name":         s.Name,
+		"folder_token": s.FolderToken,
+	}
+}
+
+// DriveCreateFolder creates a new Drive folder under the specified parent
+// folder, or under the caller's root folder when --folder-token is omitted.
+var DriveCreateFolder = common.Shortcut{
+	Service:     "drive",
+	Command:     "+create-folder",
+	Description: "Create a folder in Drive",
+	Risk:        "write",
+	Scopes:      []string{"space:folder:create"},
+	AuthTypes:   []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "name", Desc: "folder name", Required: true},
+		{Name: "folder-token", Desc: "parent folder token (default: root folder)"},
+	},
+	Tips: []string{
+		"Omit --folder-token to create the folder in the caller's root folder.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateDriveCreateFolderSpec(newDriveCreateFolderSpec(runtime))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec := newDriveCreateFolderSpec(runtime)
+		dry := common.NewDryRunAPI().
+			Desc("Create a folder in Drive").
+			POST("/open-apis/drive/v1/files/create_folder").
+			Desc("[1] Create folder").
+			Body(spec.RequestBody())
+		if runtime.IsBot() {
+			dry.Desc("After folder creation succeeds in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on the new folder.")
+		}
+		return dry
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec := newDriveCreateFolderSpec(runtime)
+
+		target := "root folder"
+		if spec.FolderToken != "" {
+			target = "folder " + common.MaskToken(spec.FolderToken)
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "Creating folder %q in %s...\n", spec.Name, target)
+
+		data, err := runtime.CallAPI(
+			"POST",
+			"/open-apis/drive/v1/files/create_folder",
+			nil,
+			spec.RequestBody(),
+		)
+		if err != nil {
+			return err
+		}
+
+		folderToken := common.GetString(data, "token")
+		if folderToken == "" {
+			return output.Errorf(output.ExitAPI, "api_error", "drive create_folder succeeded but returned no folder token (data.token)")
+		}
+		out := map[string]interface{}{
+			"created":             true,
+			"name":                spec.Name,
+			"folder_token":        folderToken,
+			"parent_folder_token": spec.FolderToken,
+		}
+		if url := common.GetString(data, "url"); url != "" {
+			out["url"] = url
+		}
+		if grant := common.AutoGrantCurrentUserDrivePermission(runtime, folderToken, "folder"); grant != nil {
+			out["permission_grant"] = grant
+		}
+
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+func validateDriveCreateFolderSpec(spec driveCreateFolderSpec) error {
+	if spec.Name == "" {
+		return output.ErrValidation("--name must not be empty")
+	}
+	if nameBytes := len([]byte(spec.Name)); nameBytes > 256 {
+		return output.ErrValidation("--name exceeds the maximum of 256 bytes (got %d)", nameBytes)
+	}
+	if spec.FolderToken != "" {
+		if err := validate.ResourceName(spec.FolderToken, "--folder-token"); err != nil {
+			return output.ErrValidation("%s", err)
+		}
+	}
+	return nil
+}

shortcuts/drive/drive_create_folder_test.go

@@ -0,0 +1,266 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestValidateDriveCreateFolderSpecRejectsInvalidInputs(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		spec    driveCreateFolderSpec
+		wantErr string
+	}{
+		{
+			name:    "empty name",
+			spec:    driveCreateFolderSpec{},
+			wantErr: "--name must not be empty",
+		},
+		{
+			name: "name too long",
+			spec: driveCreateFolderSpec{
+				Name: strings.Repeat("a", 257),
+			},
+			wantErr: "maximum of 256 bytes",
+		},
+		{
+			name: "invalid folder token",
+			spec: driveCreateFolderSpec{
+				Name:        "Reports",
+				FolderToken: "../bad",
+			},
+			wantErr: "--folder-token",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := validateDriveCreateFolderSpec(tt.spec)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestDriveCreateFolderDryRunIncludesCreateRequest(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{Use: "drive +create-folder"}
+	cmd.Flags().String("name", "", "")
+	cmd.Flags().String("folder-token", "", "")
+	if err := cmd.Flags().Set("name", " Weekly Reports "); err != nil {
+		t.Fatalf("set --name: %v", err)
+	}
+	if err := cmd.Flags().Set("folder-token", " fld_parent "); err != nil {
+		t.Fatalf("set --folder-token: %v", err)
+	}
+
+	runtime := common.TestNewRuntimeContextWithIdentity(cmd, nil, core.AsBot)
+	dry := DriveCreateFolder.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+
+	data, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("marshal dry run: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("unmarshal dry run json: %v", err)
+	}
+	if len(got.API) != 1 {
+		t.Fatalf("expected 1 API call, got %d", len(got.API))
+	}
+	if got.API[0].Method != "POST" || got.API[0].URL != "/open-apis/drive/v1/files/create_folder" {
+		t.Fatalf("unexpected dry-run API call: %#v", got.API[0])
+	}
+	if got.API[0].Body["name"] != "Weekly Reports" {
+		t.Fatalf("name = %#v, want %q", got.API[0].Body["name"], "Weekly Reports")
+	}
+	if got.API[0].Body["folder_token"] != "fld_parent" {
+		t.Fatalf("folder_token = %#v, want %q", got.API[0].Body["folder_token"], "fld_parent")
+	}
+}
+
+func TestDriveCreateFolderBotAutoGrantSuccess(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, drivePermissionGrantTestConfig(t, "ou_current_user"))
+
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/create_folder",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"token": "fld_created",
+				"url":   "https://example.feishu.cn/drive/folder/fld_created",
+			},
+		},
+	}
+	reg.Register(createStub)
+
+	permStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/permissions/fld_created/members",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+		},
+	}
+	reg.Register(permStub)
+
+	err := mountAndRunDrive(t, DriveCreateFolder, []string{
+		"+create-folder",
+		"--name", " Weekly Reports ",
+		"--folder-token", " fld_parent ",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeCapturedJSONBody(t, createStub)
+	if body["name"] != "Weekly Reports" {
+		t.Fatalf("name = %#v, want %q", body["name"], "Weekly Reports")
+	}
+	if body["folder_token"] != "fld_parent" {
+		t.Fatalf("folder_token = %#v, want %q", body["folder_token"], "fld_parent")
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if data["folder_token"] != "fld_created" {
+		t.Fatalf("folder_token = %#v, want %q", data["folder_token"], "fld_created")
+	}
+	if data["parent_folder_token"] != "fld_parent" {
+		t.Fatalf("parent_folder_token = %#v, want %q", data["parent_folder_token"], "fld_parent")
+	}
+	if data["name"] != "Weekly Reports" {
+		t.Fatalf("name = %#v, want %q", data["name"], "Weekly Reports")
+	}
+	if data["url"] != "https://example.feishu.cn/drive/folder/fld_created" {
+		t.Fatalf("url = %#v, want folder url", data["url"])
+	}
+
+	grant, _ := data["permission_grant"].(map[string]interface{})
+	if grant["status"] != common.PermissionGrantGranted {
+		t.Fatalf("permission_grant.status = %#v, want %q", grant["status"], common.PermissionGrantGranted)
+	}
+	if grant["user_open_id"] != "ou_current_user" {
+		t.Fatalf("permission_grant.user_open_id = %#v, want %q", grant["user_open_id"], "ou_current_user")
+	}
+	if grant["message"] != "Granted the current CLI user full_access (可管理权限) on the new folder." {
+		t.Fatalf("permission_grant.message = %#v", grant["message"])
+	}
+
+	permBody := decodeCapturedJSONBody(t, permStub)
+	if permBody["member_type"] != "openid" || permBody["member_id"] != "ou_current_user" || permBody["perm"] != "full_access" || permBody["type"] != "user" {
+		t.Fatalf("unexpected permission request body: %#v", permBody)
+	}
+}
+
+func TestDriveCreateFolderUsesRootWhenParentIsOmitted(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, drivePermissionGrantTestConfig(t, "ou_current_user"))
+
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/create_folder",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"token": "fld_root_child",
+			},
+		},
+	}
+	reg.Register(createStub)
+
+	err := mountAndRunDrive(t, DriveCreateFolder, []string{
+		"+create-folder",
+		"--name", "Inbox",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeCapturedJSONBody(t, createStub)
+	if body["folder_token"] != "" {
+		t.Fatalf("folder_token = %#v, want empty string for root create", body["folder_token"])
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if data["folder_token"] != "fld_root_child" {
+		t.Fatalf("folder_token = %#v, want %q", data["folder_token"], "fld_root_child")
+	}
+	if data["parent_folder_token"] != "" {
+		t.Fatalf("parent_folder_token = %#v, want empty string", data["parent_folder_token"])
+	}
+	if _, ok := data["permission_grant"]; ok {
+		t.Fatalf("did not expect permission_grant in user mode output: %#v", data)
+	}
+}
+
+func TestDriveCreateFolderRejectsCreateResponseWithoutToken(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, drivePermissionGrantTestConfig(t, "ou_current_user"))
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/create_folder",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"url": "https://example.feishu.cn/drive/folder/unknown",
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveCreateFolder, []string{
+		"+create-folder",
+		"--name", "Broken Folder",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "returned no folder token") {
+		t.Fatalf("err = %v, want missing folder token error", err)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout should be empty on error, got %s", stdout.String())
+	}
+}

shortcuts/drive/shortcuts.go

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

shortcuts/drive/shortcuts_test.go

@@ -12,6 +12,7 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 	got := Shortcuts()
 	want := []string{
 		"+upload",
+		"+create-folder",
 		"+create-shortcut",
 		"+download",
 		"+add-comment",

shortcuts/im/coverage_additional_test.go

@@ -602,3 +602,51 @@ func TestMediaBufferReader(t *testing.T) {
 		}
 	}
 }
+
+func TestMediaBufferFileName(t *testing.T) {
+	tests := []struct {
+		label string
+		buf   mediaBuffer
+		want  string
+	}{
+		{"original URL filename", mediaBuffer{name: "report.pdf", ext: ".pdf"}, "report.pdf"},
+		{"name with spaces", mediaBuffer{name: "Q1 report.pdf", ext: ".pdf"}, "Q1 report.pdf"},
+		{"download fallback", mediaBuffer{name: "download", ext: ""}, "download"},
+		{"ext not leaked into name", mediaBuffer{name: "x", ext: ".mp4"}, "x"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.label, func(t *testing.T) {
+			if got := tt.buf.FileName(); got != tt.want {
+				t.Fatalf("FileName() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+// TestNewMediaBufferFromBytesURLFilename locks in the URL -> mediaBuffer.name
+// wiring so a future refactor cannot regress back to the "media.<ext>" synthetic
+// filename that was shipped in 91067ec.
+func TestNewMediaBufferFromBytesURLFilename(t *testing.T) {
+	tests := []struct {
+		label string
+		url   string
+		want  string
+	}{
+		{"path filename", "http://example.com/report.pdf", "report.pdf"},
+		{"filename survives query string", "http://example.com/videos/clip.mp4?token=abc", "clip.mp4"},
+		{"percent-encoded spaces decoded", "http://example.com/Q1%20report.pdf", "Q1 report.pdf"},
+		{"no path falls back to download", "http://example.com/", "download"},
+		{"non-http scheme falls back to download", "ftp://example.com/x.pdf", "download"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.label, func(t *testing.T) {
+			mb := newMediaBufferFromBytes([]byte("payload"), ".pdf", tt.url)
+			if got := mb.FileName(); got != tt.want {
+				t.Fatalf("FileName() for %q = %q, want %q", tt.url, got, tt.want)
+			}
+			if got := mb.FileName(); strings.HasPrefix(got, "media") && tt.want != "media" {
+				t.Fatalf("regression: FileName() returned synthetic %q for %q", got, tt.url)
+			}
+		})
+	}
+}

shortcuts/im/helpers.go

@@ -584,6 +584,7 @@ func parseMediaDuration(runtime *common.RuntimeContext, filePath, fileType strin
 type mediaBuffer struct {
 	data []byte
 	ext  string // file extension including leading dot, e.g. ".mp4"
+	name string // original file name extracted from the source URL
 }
 
 // newMediaBuffer downloads URL content into memory via downloadURLToReader.
@@ -598,7 +599,14 @@ func newMediaBuffer(ctx context.Context, runtime *common.RuntimeContext, rawURL
 	if err != nil {
 		return nil, fmt.Errorf("download failed: %w", err)
 	}
-	return &mediaBuffer{data: data, ext: ext}, nil
+	return newMediaBufferFromBytes(data, ext, rawURL), nil
+}
+
+// newMediaBufferFromBytes builds a mediaBuffer from already-downloaded bytes.
+// Split out from newMediaBuffer so the URL-to-filename wiring is testable
+// without going through the hardened download transport.
+func newMediaBufferFromBytes(data []byte, ext, rawURL string) *mediaBuffer {
+	return &mediaBuffer{data: data, ext: ext, name: fileNameFromURL(rawURL)}
 }
 
 // Reader returns a new io.Reader over the buffered data. Each call returns a
@@ -608,9 +616,9 @@ func (b *mediaBuffer) Reader() io.Reader {
 	return bytes.NewReader(b.data)
 }
 
-// FileName returns a synthetic file name based on the URL extension.
+// FileName returns the original file name extracted from the source URL.
 func (b *mediaBuffer) FileName() string {
-	return "media" + b.ext
+	return b.name
 }
 
 // FileType returns the IM file type detected from the extension.
@@ -1131,7 +1139,7 @@ func uploadImageToIM(ctx context.Context, runtime *common.RuntimeContext, filePa
 	fd.AddField("image_type", imageType)
 	fd.AddFile("image", f)
 
-	apiResp, err := runtime.DoAPIAsBot(&larkcore.ApiReq{
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
 		HttpMethod: http.MethodPost,
 		ApiPath:    "/open-apis/im/v1/images",
 		Body:       fd,
@@ -1172,7 +1180,7 @@ func uploadFileToIM(ctx context.Context, runtime *common.RuntimeContext, filePat
 	}
 	fd.AddFile("file", f)
 
-	apiResp, err := runtime.DoAPIAsBot(&larkcore.ApiReq{
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
 		HttpMethod: http.MethodPost,
 		ApiPath:    "/open-apis/im/v1/files",
 		Body:       fd,
@@ -1200,7 +1208,7 @@ func uploadImageFromReader(ctx context.Context, runtime *common.RuntimeContext,
 	fd.AddField("image_type", imageType)
 	fd.AddFile("image", r)
 
-	apiResp, err := runtime.DoAPIAsBot(&larkcore.ApiReq{
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
 		HttpMethod: http.MethodPost,
 		ApiPath:    "/open-apis/im/v1/images",
 		Body:       fd,
@@ -1232,7 +1240,7 @@ func uploadFileFromReader(ctx context.Context, runtime *common.RuntimeContext, r
 	}
 	fd.AddFile("file", r)
 
-	apiResp, err := runtime.DoAPIAsBot(&larkcore.ApiReq{
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
 		HttpMethod: http.MethodPost,
 		ApiPath:    "/open-apis/im/v1/files",
 		Body:       fd,

shortcuts/im/helpers_network_test.go

@@ -892,3 +892,38 @@ func TestResolveLocalMediaFile(t *testing.T) {
 		t.Fatalf("resolveLocalMedia(file) = %q, want %q", got, "file_via_resolve")
 	}
 }
+
+// TestUploadFileToIMPreservesLocalFileName locks in that local uploads keep
+// the basename of the caller-supplied path as the multipart file_name, so the
+// URL-side fix for mediaBuffer cannot silently regress the local branch later.
+func TestUploadFileToIMPreservesLocalFileName(t *testing.T) {
+	var gotBody string
+	runtime := newBotShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		if strings.Contains(req.URL.Path, "/open-apis/im/v1/files") {
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				return nil, err
+			}
+			gotBody = string(body)
+			return shortcutJSONResponse(200, map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{"file_key": "file_uploaded"},
+			}), nil
+		}
+		return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+	}))
+
+	cmdutil.TestChdir(t, t.TempDir())
+
+	localName := "Q1-meeting-notes.pdf"
+	if err := os.WriteFile(localName, []byte("pdfdata"), 0600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	if _, err := uploadFileToIM(context.Background(), runtime, "./"+localName, "pdf", ""); err != nil {
+		t.Fatalf("uploadFileToIM() error = %v", err)
+	}
+	if !strings.Contains(gotBody, `name="file_name"`) || !strings.Contains(gotBody, localName) {
+		t.Fatalf("upload body missing local filename %q; got: %q", localName, gotBody)
+	}
+}

shortcuts/mail/draft/model.go

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

shortcuts/mail/draft/patch.go

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

shortcuts/mail/draft/patch_signature_test.go

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

shortcuts/mail/draft/projection.go

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

shortcuts/mail/draft/projection_test.go

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

shortcuts/mail/helpers.go

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

shortcuts/mail/mail_draft_create.go

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

shortcuts/mail/mail_draft_create_test.go

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

shortcuts/mail/mail_draft_edit.go

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

shortcuts/mail/mail_forward.go

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

shortcuts/mail/mail_reply.go

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

shortcuts/mail/mail_reply_all.go

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

shortcuts/mail/mail_send.go

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

shortcuts/mail/mail_signature.go

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

shortcuts/mail/shortcuts.go

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

shortcuts/mail/signature/interpolate.go

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

shortcuts/mail/signature/interpolate_test.go

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

shortcuts/mail/signature/model.go

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

shortcuts/mail/signature/provider.go

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

shortcuts/mail/signature_compose.go

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

shortcuts/slides/helpers.go

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

shortcuts/slides/helpers_test.go

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

shortcuts/slides/shortcuts.go

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

shortcuts/slides/slides_create.go

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

shortcuts/slides/slides_create_test.go

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

shortcuts/slides/slides_media_upload.go

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

shortcuts/slides/slides_media_upload_test.go

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

shortcuts/whiteboard/shortcuts.go

@@ -23,6 +23,8 @@ type WbCliOutput struct {
 }
 
 type WbCliOutputData struct {
-	To     string      `json:"to"`
-	Result interface{} `json:"result"`
+	To     string `json:"to"`
+	Result struct {
+		Nodes []interface{} `json:"nodes"`
+	} `json:"result"`
 }

shortcuts/whiteboard/whiteboard_update.go

@@ -11,7 +11,6 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
-	"time"
 
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -31,9 +30,8 @@ var formatCodeMap = map[string]int{
 	FormatMermaid:  2,
 }
 
-var wbUpdateScopes = []string{"board:whiteboard:node:read", "board:whiteboard:node:create", "board:whiteboard:node:delete"}
+var wbUpdateScopes = []string{"board:whiteboard:node:create"}
 var wbUpdateAuthTypes = []string{"user", "bot"}
-var skipDeleteNodesBatchSleep = false // for accelerate UT testing only
 var wbUpdateFlags = []common.Flag{
 	{Name: "idempotent-token", Desc: "idempotent token to ensure the update is idempotent. Default is empty. min length is 10.", Required: false},
 	{Name: "whiteboard-token", Desc: "whiteboard token of the whiteboard to update. You will need edit permission to update the whiteboard.", Required: true},
@@ -82,19 +80,6 @@ func wbUpdateDryRun(ctx context.Context, runtime *common.RuntimeContext) *common
 	token := runtime.Str("whiteboard-token")
 	overwrite := runtime.Bool("overwrite")
 	descStr := "will call whiteboard open api to update content."
-	var delNum int
-	var err error
-	if overwrite {
-		// 还是会读取一下 whiteboard nodes，确认是否有节点要删除
-		delNum, _, err = clearWhiteboardContent(ctx, runtime, token, []string{}, true)
-		if err != nil {
-			return common.NewDryRunAPI().Desc("read whiteboard nodes failed: " + err.Error())
-		}
-		if delNum > 0 {
-			descStr += fmt.Sprintf(" %d existing nodes deleted before update.", delNum)
-		}
-	}
-
 	desc := common.NewDryRunAPI().Desc(descStr)
 
 	switch format {
@@ -103,7 +88,11 @@ func wbUpdateDryRun(ctx context.Context, runtime *common.RuntimeContext) *common
 		if err != nil {
 			return common.NewDryRunAPI().Desc("parse input failed: " + err.Error())
 		}
-		desc.POST(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", common.MaskToken(url.PathEscape(token)))).Body(nodes).Desc("create all nodes of the whiteboard.")
+		reqBody := rawNodesCreateReq{
+			Nodes:     nodes,
+			Overwrite: overwrite,
+		}
+		desc.POST(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", common.MaskToken(url.PathEscape(token)))).Body(reqBody).Desc("create all nodes of the whiteboard.")
 	case FormatPlantUML, FormatMermaid:
 		syntaxType := formatCodeMap[format]
 		reqBody := plantumlCreateReq{
@@ -111,16 +100,11 @@ func wbUpdateDryRun(ctx context.Context, runtime *common.RuntimeContext) *common
 			SyntaxType:   syntaxType,
 			ParseMode:    1,
 			DiagramType:  0,
+			Overwrite:    overwrite,
 		}
 		desc.POST(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes/plantuml", common.MaskToken(url.PathEscape(token)))).Body(reqBody).Desc(fmt.Sprintf("create %s node on the whiteboard.", format))
 	}
 
-	if overwrite && delNum > 0 {
-		// 在 DryRun 中只记录意图，不实际拉取和计算节点
-		desc.GET(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", common.MaskToken(url.PathEscape(token)))).Desc("get all nodes of the whiteboard to delete, then filter out newly created ones.")
-		desc.DELETE(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes/batch_delete", common.MaskToken(url.PathEscape(token)))).Body("{\"ids\":[\"...\"]}").
-			Desc(fmt.Sprintf("delete all old nodes of the whiteboard 100 nodes at a time. This API may be called multiple times and is not reversible. %d whiteboard nodes will be deleted while update.", delNum))
-	}
 	return desc
 }
 
@@ -185,31 +169,17 @@ type createResponse struct {
 	} `json:"data"`
 }
 
-type deleteResponse struct {
-	Code int    `json:"code"`
-	Msg  string `json:"msg"`
-}
-
-type simpleNodeResp struct {
-	Code int    `json:"code"`
-	Msg  string `json:"msg"`
-	Data struct {
-		Nodes []struct {
-			Id       string   `json:"id"`
-			Children []string `json:"children"`
-		} `json:"nodes"`
-	} `json:"data"`
-}
-
-type deleteNodeReqBody struct {
-	Ids []string `json:"ids"`
-}
-
 type plantumlCreateReq struct {
 	PlantUmlCode string `json:"plant_uml_code"`
 	SyntaxType   int    `json:"syntax_type"`
 	DiagramType  int    `json:"diagram_type,omitempty"`
 	ParseMode    int    `json:"parse_mode,omitempty"`
+	Overwrite    bool   `json:"overwrite,omitempty"`
+}
+
+type rawNodesCreateReq struct {
+	Nodes     []interface{} `json:"nodes"`
+	Overwrite bool          `json:"overwrite,omitempty"`
 }
 
 type plantumlCreateResp struct {
@@ -220,7 +190,7 @@ type plantumlCreateResp struct {
 	} `json:"data"`
 }
 
-func parseWBcliNodes(rawjson []byte) (wbNodes interface{}, err error, isRaw bool) {
+func parseWBcliNodes(rawjson []byte) (wbNodes []interface{}, err error, isRaw bool) {
 	var wbOutput WbCliOutput
 	if err := json.Unmarshal(rawjson, &wbOutput); err != nil {
 		return nil, output.Errorf(output.ExitValidation, "parsing", fmt.Sprintf("unmarshal input json failed: %v", err)), false
@@ -229,121 +199,17 @@ func parseWBcliNodes(rawjson []byte) (wbNodes interface{}, err error, isRaw bool
 		return nil, output.Errorf(output.ExitValidation, "whiteboard-cli", "whiteboard-cli failed. please check previous log."), false
 	}
 	if wbOutput.RawNodes != nil {
-		wbNodes = struct {
-			Nodes []interface{} `json:"nodes"`
-		}{
-			Nodes: wbOutput.RawNodes,
-		}
+		wbNodes = wbOutput.RawNodes
 		isRaw = true
 	} else {
-		wbNodes = wbOutput.Data.Result
+		if wbOutput.Data.Result.Nodes == nil {
+			return nil, output.Errorf(output.ExitValidation, "whiteboard-cli", "whiteboard-cli failed. please check previous log."), false
+		}
+		wbNodes = wbOutput.Data.Result.Nodes
 	}
 	return wbNodes, nil, isRaw
 }
 
-func clearWhiteboardContent(ctx context.Context, runtime *common.RuntimeContext, wbToken string, newNodeIDs []string, dryRun bool) (int, []string, error) {
-	resp, err := runtime.DoAPI(&larkcore.ApiReq{
-		HttpMethod: http.MethodGet,
-		ApiPath:    fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", url.PathEscape(wbToken)),
-	})
-	if err != nil {
-		return 0, nil, output.ErrNetwork(fmt.Sprintf("get whiteboard nodes failed: %v", err))
-	}
-	if resp.StatusCode != http.StatusOK {
-		return 0, nil, output.ErrAPI(resp.StatusCode, string(resp.RawBody), nil)
-	}
-	var nodes simpleNodeResp
-	err = json.Unmarshal(resp.RawBody, &nodes)
-	if err != nil {
-		return 0, nil, output.Errorf(output.ExitInternal, "parsing", fmt.Sprintf("parse whiteboard nodes failed: %v", err))
-	}
-	if nodes.Code != 0 {
-		return 0, nil, output.ErrAPI(nodes.Code, "get whiteboard nodes failed", fmt.Sprintf("get whiteboard nodes failed: %s", nodes.Msg))
-	}
-
-	// 收集所有新节点及其 children 的 ID，递归处理
-	protectedIDs := make(map[string]bool)
-	for _, id := range newNodeIDs {
-		protectedIDs[id] = true
-	}
-	// 构建 node map 以便快速查找
-	nodeMap := make(map[string][]string)
-	if nodes.Data.Nodes != nil {
-		for _, node := range nodes.Data.Nodes {
-			nodeMap[node.Id] = node.Children
-		}
-	}
-	// 递归收集所有 children
-	visited := make(map[string]bool)
-	var collectChildren func(id string)
-	collectChildren = func(id string) {
-		if visited[id] {
-			return
-		}
-		visited[id] = true
-		if children, ok := nodeMap[id]; ok {
-			for _, child := range children {
-				protectedIDs[child] = true
-				collectChildren(child)
-			}
-		}
-	}
-	for _, id := range newNodeIDs {
-		collectChildren(id)
-	}
-
-	// 确定要删除的节点
-	nodeIds := make([]string, 0, len(nodes.Data.Nodes))
-	if nodes.Data.Nodes != nil {
-		for _, node := range nodes.Data.Nodes {
-			nodeIds = append(nodeIds, node.Id)
-		}
-	}
-	delIds := make([]string, 0, len(nodeIds))
-	for _, nodeId := range nodeIds {
-		if !protectedIDs[nodeId] {
-			delIds = append(delIds, nodeId)
-		}
-	}
-	if dryRun {
-		return len(delIds), delIds, nil
-	}
-	// 实际删除节点，按每批最多100个进行切分
-	for i := 0; i < len(delIds); i += 100 {
-		if !skipDeleteNodesBatchSleep {
-			time.Sleep(time.Millisecond * 1000) // 画板内删除大量节点时，内部会有大量写操作，需要稍等一下，避免被限流
-		}
-		end := i + 100
-		if end > len(delIds) {
-			end = len(delIds)
-		}
-		batchIds := delIds[i:end]
-		delReq := deleteNodeReqBody{
-			Ids: batchIds,
-		}
-		resp, err = runtime.DoAPI(&larkcore.ApiReq{
-			HttpMethod: http.MethodDelete,
-			ApiPath:    fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes/batch_delete", url.PathEscape(wbToken)),
-			Body:       delReq,
-		})
-		if err != nil {
-			return 0, nil, output.ErrNetwork(fmt.Sprintf("delete whiteboard nodes failed: %v", err))
-		}
-		if resp.StatusCode != http.StatusOK {
-			return 0, nil, output.ErrAPI(resp.StatusCode, string(resp.RawBody), nil)
-		}
-		var delResp deleteResponse
-		err = json.Unmarshal(resp.RawBody, &delResp)
-		if err != nil {
-			return 0, nil, output.Errorf(output.ExitInternal, "parsing", fmt.Sprintf("parse whiteboard delete response failed: %v", err))
-		}
-		if delResp.Code != 0 {
-			return 0, nil, output.ErrAPI(delResp.Code, "delete whiteboard nodes failed", fmt.Sprintf("delete whiteboard nodes failed: %s", delResp.Msg))
-		}
-	}
-	return len(delIds), delIds, nil
-}
-
 // updateWhiteboardByCode 使用 plantuml/mermaid 代码更新画板
 func updateWhiteboardByCode(ctx context.Context, runtime *common.RuntimeContext, wbToken string, input []byte, format string, overwrite bool, idempotentToken string) error {
 	syntaxType := formatCodeMap[format]
@@ -352,6 +218,7 @@ func updateWhiteboardByCode(ctx context.Context, runtime *common.RuntimeContext,
 		SyntaxType:   syntaxType,
 		ParseMode:    1,
 		DiagramType:  0, // 0 表示自动识别
+		Overwrite:    overwrite,
 	}
 
 	req := &larkcore.ApiReq{
@@ -383,20 +250,7 @@ func updateWhiteboardByCode(ctx context.Context, runtime *common.RuntimeContext,
 
 	outData := make(map[string]string)
 	outData["created_node_id"] = createResp.Data.NodeID
-	newNodeIDs := []string{createResp.Data.NodeID}
-
-	if overwrite {
-		numNodes, _, err := clearWhiteboardContent(ctx, runtime, wbToken, newNodeIDs, false)
-		if err != nil {
-			return err
-		}
-		outData["deleted_nodes_num"] = fmt.Sprintf("%d", numNodes)
-	}
-
 	runtime.OutFormat(outData, nil, func(w io.Writer) {
-		if outData["deleted_nodes_num"] != "" {
-			fmt.Fprintf(w, "%s existing nodes deleted.\n", outData["deleted_nodes_num"])
-		}
 		if outData["created_node_id"] != "" {
 			fmt.Fprintf(w, "New node created.\n")
 		}
@@ -413,11 +267,15 @@ func updateWhiteboardByRawNodes(ctx context.Context, runtime *common.RuntimeCont
 		return err
 	}
 	outData := make(map[string]string)
+	reqBody := rawNodesCreateReq{
+		Nodes:     nodes,
+		Overwrite: overwrite,
+	}
 
 	req := &larkcore.ApiReq{
 		HttpMethod:  http.MethodPost,
 		ApiPath:     fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", url.PathEscape(wbToken)),
-		Body:        nodes,
+		Body:        reqBody,
 		QueryParams: map[string][]string{},
 	}
 	if idempotentToken != "" {
@@ -452,19 +310,7 @@ func updateWhiteboardByRawNodes(ctx context.Context, runtime *common.RuntimeCont
 	}
 
 	outData["created_node_ids"] = strings.Join(createResp.Data.NodeIDs, ",")
-
-	if overwrite {
-		numNodes, _, err := clearWhiteboardContent(ctx, runtime, wbToken, createResp.Data.NodeIDs, false)
-		if err != nil {
-			return err
-		}
-		outData["deleted_nodes_num"] = fmt.Sprintf("%d", numNodes)
-	}
-
 	runtime.OutFormat(outData, nil, func(w io.Writer) {
-		if outData["deleted_nodes_num"] != "" {
-			fmt.Fprintf(w, "%s existing nodes deleted.\n", outData["deleted_nodes_num"])
-		}
 		if outData["created_node_ids"] != "" {
 			fmt.Fprintf(w, "%d new nodes created.\n", len(createResp.Data.NodeIDs))
 		}

shortcuts/whiteboard/whiteboard_update_test.go

@@ -478,36 +478,9 @@ invalid
 }
 
 func TestWhiteboardUpdateExecute_WithOverwrite(t *testing.T) {
-	// Skip sleep for testing
-	origSkip := skipDeleteNodesBatchSleep
-	skipDeleteNodesBatchSleep = true
-	defer func() { skipDeleteNodesBatchSleep = origSkip }()
-
 	factory, stdout, reg := newUpdateExecuteFactory(t)
 
-	// Mock 1: Get existing nodes (for clearWhiteboardContent)
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/board/v1/whiteboards/test-token-overwrite/nodes",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "",
-			"data": map[string]interface{}{
-				"nodes": []map[string]interface{}{
-					{
-						"id":       "old-node-1",
-						"children": []string{},
-					},
-					{
-						"id":       "old-node-2",
-						"children": []string{},
-					},
-				},
-			},
-		},
-	})
-
-	// Mock 2: Create nodes API response
+	// Mock: Create nodes API response with overwrite in request body
 	reg.Register(&httpmock.Stub{
 		Method: "POST",
 		URL:    "/open-apis/board/v1/whiteboards/test-token-overwrite/nodes/plantuml",
@@ -520,16 +493,6 @@ func TestWhiteboardUpdateExecute_WithOverwrite(t *testing.T) {
 		},
 	})
 
-	// Mock 3: Delete nodes batch
-	reg.Register(&httpmock.Stub{
-		Method: "DELETE",
-		URL:    "/open-apis/board/v1/whiteboards/test-token-overwrite/nodes/batch_delete",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "success",
-		},
-	})
-
 	source := `graph TD
 A-->B`
 	args := []string{"+update", "--whiteboard-token", "test-token-overwrite", "--input_format", "mermaid", "--overwrite", "--source", source}
@@ -539,36 +502,9 @@ A-->B`
 }
 
 func TestWhiteboardUpdateExecute_RawWithOverwrite(t *testing.T) {
-	// Skip sleep for testing
-	origSkip := skipDeleteNodesBatchSleep
-	skipDeleteNodesBatchSleep = true
-	defer func() { skipDeleteNodesBatchSleep = origSkip }()
-
 	factory, stdout, reg := newUpdateExecuteFactory(t)
 
-	// Mock 1: Get existing nodes (for clearWhiteboardContent)
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/board/v1/whiteboards/test-token-raw-overwrite/nodes",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "",
-			"data": map[string]interface{}{
-				"nodes": []map[string]interface{}{
-					{
-						"id":       "old-node-1",
-						"children": []string{"old-child-1"},
-					},
-					{
-						"id":       "old-child-1",
-						"children": []string{},
-					},
-				},
-			},
-		},
-	})
-
-	// Mock 2: Create nodes API response
+	// Mock: Create nodes API response with overwrite in request body
 	reg.Register(&httpmock.Stub{
 		Method: "POST",
 		URL:    "/open-apis/board/v1/whiteboards/test-token-raw-overwrite/nodes",
@@ -581,16 +517,6 @@ func TestWhiteboardUpdateExecute_RawWithOverwrite(t *testing.T) {
 		},
 	})
 
-	// Mock 3: Delete nodes batch
-	reg.Register(&httpmock.Stub{
-		Method: "DELETE",
-		URL:    "/open-apis/board/v1/whiteboards/test-token-raw-overwrite/nodes/batch_delete",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "success",
-		},
-	})
-
 	source := `{"code":0,"data":{"to":"openapi","result":{"nodes":[]}}}`
 	args := []string{"+update", "--whiteboard-token", "test-token-raw-overwrite", "--input_format", "raw", "--overwrite", "--source", source}
 	if err := runUpdateShortcut(t, WhiteboardUpdate, args, factory, stdout); err != nil {

shortcuts/wiki/wiki_node_create.go

@@ -58,7 +58,11 @@ var WikiNodeCreate = common.Shortcut{
 		return validateWikiNodeCreateSpec(readWikiNodeCreateSpec(runtime), runtime.As())
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return buildWikiNodeCreateDryRun(readWikiNodeCreateSpec(runtime))
+		dry := buildWikiNodeCreateDryRun(readWikiNodeCreateSpec(runtime))
+		if runtime.IsBot() {
+			dry.Desc("After wiki node creation succeeds in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on the new wiki node.")
+		}
+		return dry
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		spec := readWikiNodeCreateSpec(runtime)
@@ -70,7 +74,7 @@ var WikiNodeCreate = common.Shortcut{
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Created wiki node in space %s via %s.\n", execution.ResolvedSpace.SpaceID, execution.ResolvedSpace.ResolvedBy)
-		runtime.Out(wikiNodeCreateOutput(execution), nil)
+		runtime.Out(augmentWikiNodeCreateOutput(runtime, execution), nil)
 		return nil
 	},
 }
@@ -293,6 +297,9 @@ func runWikiNodeCreate(ctx context.Context, client wikiNodeCreateClient, identit
 	if err != nil {
 		return nil, err
 	}
+	if node == nil {
+		return nil, output.Errorf(output.ExitAPI, "api_error", "wiki node create returned no node")
+	}
 
 	return &wikiNodeCreateExecution{
 		Node:          node,
@@ -462,3 +469,15 @@ func wikiNodeCreateOutput(execution *wikiNodeCreateExecution) map[string]interfa
 		"has_child":         node.HasChild,
 	}
 }
+
+func augmentWikiNodeCreateOutput(runtime *common.RuntimeContext, execution *wikiNodeCreateExecution) map[string]interface{} {
+	if execution == nil || execution.Node == nil {
+		return map[string]interface{}{}
+	}
+
+	out := wikiNodeCreateOutput(execution)
+	if grant := common.AutoGrantCurrentUserDrivePermission(runtime, execution.Node.NodeToken, "wiki"); grant != nil {
+		out["permission_grant"] = grant
+	}
+	return out
+}

shortcuts/wiki/wiki_node_create_test.go

@@ -29,6 +29,7 @@ type fakeWikiNodeCreateClient struct {
 	spaces        map[string]*wikiSpaceRecord
 	nodes         map[string]*wikiNodeRecord
 	createNode    *wikiNodeRecord
+	returnNilNode bool
 	createErr     error
 	getSpaceErr   error
 	getNodeErr    error
@@ -65,6 +66,9 @@ func (fake *fakeWikiNodeCreateClient) CreateNode(ctx context.Context, spaceID st
 	if fake.createErr != nil {
 		return nil, fake.createErr
 	}
+	if fake.returnNilNode {
+		return nil, nil
+	}
 	if fake.createNode != nil {
 		return fake.createNode, nil
 	}
@@ -81,6 +85,15 @@ func wikiTestConfig() *core.CliConfig {
 	}
 }
 
+func wikiPermissionTestConfig(userOpenID string) *core.CliConfig {
+	return &core.CliConfig{
+		AppID:      fmt.Sprintf("wiki-permission-test-app-%d", wikiTestConfigSeq.Add(1)),
+		AppSecret:  "test-secret",
+		Brand:      core.BrandFeishu,
+		UserOpenId: userOpenID,
+	}
+}
+
 func mountAndRunWiki(t *testing.T, shortcut common.Shortcut, args []string, factory *cmdutil.Factory, stdout *bytes.Buffer) error {
 	t.Helper()
 	parent := &cobra.Command{Use: "wiki"}
@@ -268,6 +281,26 @@ func TestRunWikiNodeCreateCreatesNodeInResolvedSpace(t *testing.T) {
 	}
 }
 
+func TestRunWikiNodeCreateRejectsNilCreatedNode(t *testing.T) {
+	t.Parallel()
+
+	client := &fakeWikiNodeCreateClient{
+		spaces: map[string]*wikiSpaceRecord{
+			wikiMyLibrarySpaceID: {SpaceID: "space_my_library", SpaceType: "my_library"},
+		},
+		returnNilNode: true,
+	}
+
+	_, err := runWikiNodeCreate(context.Background(), client, core.AsUser, wikiNodeCreateSpec{
+		NodeType: wikiNodeTypeOrigin,
+		ObjType:  "docx",
+		Title:    "Roadmap",
+	})
+	if err == nil || !strings.Contains(err.Error(), "wiki node create returned no node") {
+		t.Fatalf("expected missing node error, got %v", err)
+	}
+}
+
 func TestWikiNodeCreateDryRunShowsMyLibraryLookup(t *testing.T) {
 	t.Parallel()
 
@@ -484,3 +517,126 @@ func TestWikiNodeCreateMountedExecuteWithExplicitSpaceID(t *testing.T) {
 		t.Fatalf("stderr = %q, want completed creation message", got)
 	}
 }
+
+func TestWikiNodeCreateBotAutoGrantSuccess(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiPermissionTestConfig("ou_current_user"))
+
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"space_id":   "space_123",
+					"node_token": "wik_created",
+					"obj_token":  "docx_created",
+					"obj_type":   "docx",
+					"node_type":  "origin",
+					"title":      "Wiki Node",
+					"has_child":  false,
+				},
+			},
+			"msg": "success",
+		},
+	}
+	reg.Register(createStub)
+
+	permStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/permissions/wik_created/members",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+		},
+	}
+	reg.Register(permStub)
+
+	err := mountAndRunWiki(t, WikiNodeCreate, []string{
+		"+node-create",
+		"--space-id", "space_123",
+		"--title", "Wiki Node",
+		"--as", "bot",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	grant, _ := data["permission_grant"].(map[string]interface{})
+	if grant["status"] != common.PermissionGrantGranted {
+		t.Fatalf("permission_grant.status = %#v, want %q", grant["status"], common.PermissionGrantGranted)
+	}
+	if grant["user_open_id"] != "ou_current_user" {
+		t.Fatalf("permission_grant.user_open_id = %#v, want %q", grant["user_open_id"], "ou_current_user")
+	}
+	if grant["message"] != "Granted the current CLI user full_access (可管理权限) on the new wiki node." {
+		t.Fatalf("permission_grant.message = %#v", grant["message"])
+	}
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(permStub.CapturedBody, &body); err != nil {
+		t.Fatalf("unmarshal permission body: %v", err)
+	}
+	if body["member_type"] != "openid" || body["member_id"] != "ou_current_user" || body["perm"] != "full_access" || body["type"] != "user" {
+		t.Fatalf("unexpected permission request body: %#v", body)
+	}
+	if body["perm_type"] != "container" {
+		t.Fatalf("perm_type = %#v, want %q", body["perm_type"], "container")
+	}
+}
+
+func TestWikiNodeCreateUserSkipsPermissionGrantAugmentation(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiPermissionTestConfig("ou_current_user"))
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/wiki/v2/spaces/space_123/nodes",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"space_id":   "space_123",
+					"node_token": "wik_created",
+					"obj_token":  "docx_created",
+					"obj_type":   "docx",
+					"node_type":  "origin",
+					"title":      "Wiki Node",
+					"has_child":  false,
+				},
+			},
+			"msg": "success",
+		},
+	})
+
+	err := mountAndRunWiki(t, WikiNodeCreate, []string{
+		"+node-create",
+		"--space-id", "space_123",
+		"--title", "Wiki Node",
+		"--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("mountAndRunWiki() error = %v", err)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	if _, ok := data["permission_grant"]; ok {
+		t.Fatalf("did not expect permission_grant in user mode output: %#v", data)
+	}
+}
+
+func TestAugmentWikiNodeCreateOutputReturnsEmptyMapForNilInput(t *testing.T) {
+	t.Parallel()
+
+	if got := augmentWikiNodeCreateOutput(nil, nil); len(got) != 0 {
+		t.Fatalf("augmentWikiNodeCreateOutput(nil, nil) = %#v, want empty map", got)
+	}
+
+	if got := augmentWikiNodeCreateOutput(nil, &wikiNodeCreateExecution{}); len(got) != 0 {
+		t.Fatalf("augmentWikiNodeCreateOutput(nil, empty execution) = %#v, want empty map", got)
+	}
+}

skill-template/domains/drive.md

@@ -6,6 +6,7 @@
 - 用户要把本地 `.xlsx` / `.csv` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
+- 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 
 ## 修改标题

skill-template/domains/mail.md

@@ -60,6 +60,48 @@ lark-cli mail user_mailbox.messages -h
 
 `-h` 输出即可用 flag 的权威来源。reference 文档中的参数表可辅助理解语义，但实际 flag 名称以 `-h` 为准。
 
+### 收件人搜索：查找邮箱地址
+
+当需要查找收件人邮箱地址时，使用联系人搜索接口。支持多种搜索方式，如：
+- **按人名搜索**：如"给张三发邮件" → query="张三"
+- **按邮箱关键词搜索**：如"发到 larkmail 的邮箱" → query="@larkmail"
+- **按群名搜索**：如"发给项目群" → query="项目群"
+
+```bash
+lark-cli mail multi_entity search --as user --data '{"query":"<关键词>"}'
+```
+
+搜索结果包含多种实体类型：
+
+| `type` 值 | `tag` 示例 | 说明 |
+|-----------|-----------|------|
+| `user` / `chatter` | `chatter` | 个人用户 |
+| `enterprise_mail_group` | `mail_group` | 企业邮件组 |
+| `chat` / `group` | `chat_group_tenant` / `chat_group_normal` | 群聊（有群邮件地址） |
+| `external_contact` | `external_contact` | 外部联系人 |
+
+**处理规则：**
+1. 从结果中筛选有 `email` 字段的条目
+2. 无论匹配数量多少，都必须列出候选项供用户确认后再使用（搜索是模糊匹配，单条结果不代表精确命中）。展示尽可能多的字段帮助用户区分：
+   ```text
+   找到以下匹配"张三"的结果：
+   1. 张三 <zhangsan@example.com>
+      类型：user | 部门：研发团队
+   ---
+   找到多个匹配"组"的结果，请选择：
+   1. 团队邮件组 <team@example.com>
+      类型：enterprise_mail_group | 标签：mail_group
+   2. 项目群 <project@example.com>
+      类型：chat | 成员数：50 | 标签：chat_group_normal
+   3. 张群 <zhangqun@example.com>
+      类型：user | 部门：研发团队 | 备注名：张群同学
+   ```
+   可用字段：`name`（名称）、`email`（邮箱）、`department`（部门）、`tag`（标签）、`display_name`（备注名）、`type`（实体类型）、`member_count`（成员数，群类型时展示）。字段为空时省略。
+3. 若无匹配，告知用户未找到，建议换关键词或直接提供邮箱地址
+4. 用户确认后，将 `email` 传入 compose shortcut 的 `--to` / `--cc` / `--bcc` 参数
+
+**注意：** 用户直接提供完整邮箱地址时不需要搜索，直接使用即可。
+
 ### 命令选择：先判断邮件类型，再决定草稿还是发送
 
 | 邮件类型 | 存草稿（不发送） | 直接发送 |
@@ -117,6 +159,30 @@ lark-cli mail user_mailbox.messages send_status --params '{"user_mailbox_id":"me
 
 返回每个收件人的投递状态（`status`）：1=正在投递, 2=投递失败重试, 3=退信, 4=投递成功, 5=待审批, 6=审批拒绝。向用户简要报告结果，如有异常状态（退信/审批拒绝）需重点提示。
 
+### 撤回邮件
+
+发送成功后，若响应中包含 `recall_available: true`，说明该邮件支持撤回（24 小时内已投递的邮件）。
+
+**撤回操作：**
+```bash
+lark-cli mail user_mailbox.sent_messages recall --as user \
+  --params '{"user_mailbox_id":"me","message_id":"<message_id>"}'
+```
+
+- 返回 `recall_status: available` 表示撤回请求已受理（异步执行）
+- 返回 `recall_status: unavailable` 表示不可撤回，`recall_restriction_reason` 说明原因
+
+**查询撤回进度：**
+```bash
+lark-cli mail user_mailbox.sent_messages get_recall_detail --as user \
+  --params '{"user_mailbox_id":"me","message_id":"<message_id>"}'
+```
+
+- `recall_status: in_progress` — 撤回进行中，可稍后再查
+- `recall_status: done` — 撤回完成，查看 `recall_result`（`all_success` / `all_fail` / `some_fail`）和每个收件人的详情
+
+**注意：** 撤回是异步操作，`recall` 返回成功仅表示请求已受理，实际结果需通过 `get_recall_detail` 查询。若响应中无 `recall_available` 字段，说明该邮件或应用不支持撤回，不要主动提及撤回。
+
 ### 正文格式：优先使用 HTML
 
 撰写邮件正文时，**默认使用 HTML 格式**（body 内容会被自动检测）。仅当用户明确要求纯文本时，才使用 `--plain-text` 标志强制纯文本模式。

skills/lark-base/SKILL.md

@@ -103,7 +103,7 @@ metadata:
 | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
 |------|------------------|----------------|----------|
 | `+record-search / +record-list / +record-get` | 按关键词检索记录、读取记录明细 / 分页导出，或获取单条记录详情 | [`lark-base-record-search.md`](references/lark-base-record-search.md)、[`lark-base-record-list.md`](references/lark-base-record-list.md)、[`lark-base-record-get.md`](references/lark-base-record-get.md) | 默认优先 `+record-list`；仅当用户提供明确搜索关键词时使用 `+record-search`；取数不用来做聚合分析；`--limit` 最大 `200`；仅在用户明确需要时继续翻页；`+record-list` 只能串行执行 |
-| `+record-upsert / +record-batch-create / +record-batch-update` | 创建、更新或批量写入记录 | [`lark-base-record-upsert.md`](references/lark-base-record-upsert.md)、[`lark-base-record-batch-create.md`](references/lark-base-record-batch-create.md)、[`lark-base-record-batch-update.md`](references/lark-base-record-batch-update.md)、[`lark-base-shortcut-record-value.md`](references/lark-base-shortcut-record-value.md) | 写前先 `+field-list`；只写存储字段；批量单次建议不超过 `500` 条；附件不要走这里 |
+| `+record-upsert / +record-batch-create / +record-batch-update` | 创建、更新或批量写入记录 | [`lark-base-record-upsert.md`](references/lark-base-record-upsert.md)、[`lark-base-record-batch-create.md`](references/lark-base-record-batch-create.md)、[`lark-base-record-batch-update.md`](references/lark-base-record-batch-update.md)、[`lark-base-shortcut-record-value.md`](references/lark-base-shortcut-record-value.md) | 写前先 `+field-list`；只写存储字段；`+record-batch-update` 为同值更新（同一 patch 应用到多条记录）；批量单次不超过 `200` 条；附件不要走这里 |
 | `+record-upload-attachment` | 给已有记录上传附件 | [`lark-base-record-upload-attachment.md`](references/lark-base-record-upload-attachment.md) | 附件上传专用链路，不要用 `+record-upsert` / `+record-batch-*` 伪造附件值 |
 | `lark-cli docs +media-download` | 下载 Base 附件文件到本地 | [`../lark-doc/references/lark-doc-media-download.md`](../lark-doc/references/lark-doc-media-download.md) | Base 附件的 `file_token` 从 `+record-get` 返回的附件字段数组里取；**不要用 `lark-cli drive +download`**（对 Base 附件返回 403） |
 | `+record-delete / +record-history-list` | 删除记录，或查询某条记录的变更历史 | [`lark-base-record-delete.md`](references/lark-base-record-delete.md)、[`lark-base-record-history-list.md`](references/lark-base-record-history-list.md) | 删除时用户已明确目标可直接执行并带 `--yes`；历史查询按 `table-id + record-id`，不支持整表扫描；`+record-history-list` 只能串行执行 |
@@ -287,8 +287,8 @@ metadata:
 
 - `+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list / +dashboard-list / +dashboard-block-list / +workflow-list` 禁止并发调用，只能串行执行。
 - `+record-list` 分页时，`--limit` 最大 `200`；先拉首批并检查 `has_more`，只有用户明确需要更多数据时再继续翻页。
-- 批量写入时，单批建议不超过 `500` 条。
-- 连续写入同一表时，建议串行写入，批次间延迟 `0.5–1` 秒。
+- 批量写入时，单批不超过 `200` 条。
+- 连续写入同一表时，必须串行写入，批次间延迟 `0.5–1` 秒。
 
 ### 4.4 确认与回复规则
 
@@ -311,51 +311,5 @@ metadata:
 | `not found` 且用户给的是 wiki 链接 | 常见于把 wiki token 当成 base token | 优先回退检查 wiki 解析，而不是改走 `bitable/v1` |
 | formula / lookup 创建失败 | 指南未读或结构不合法 | 先读 `formula-field-guide.md` / `lookup-field-guide.md`，再按 guide 重建请求 |
 | 系统字段 / 公式字段写入失败 | 只读字段被当成可写字段 | 改为写存储字段，计算结果交给 formula / lookup / 系统字段自动产出 |
-| `1254104` | 批量超 500 条 | 分批调用 |
+| `1254104` | 批量超 200 条 | 分批调用 |
 | `1254291` | 并发写冲突 | 串行写入 + 批次间延迟 |
-
-## 6. 参考文档
-
-- [lark-base-shortcut-field-properties.md](references/lark-base-shortcut-field-properties.md) — `+field-create/+field-update` 调用前必看，各类型 field JSON 规范
-- [role-config.md](references/role-config.md) — 角色权限配置详解
-- [lark-base-shortcut-record-value.md](references/lark-base-shortcut-record-value.md) — record 写入（`+record-upsert / +record-batch-create / +record-batch-update`）调用前必看，各类型 record JSON 规范
-- [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) — `+record-batch-create` 用法与 `--json` 结构
-- [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) — `+record-batch-update` 用法与 `--json` 结构
-- [formula-field-guide.md](references/formula-field-guide.md) — formula 字段写法、函数约束、CurrentValue 规则、跨表计算模式
-- [lookup-field-guide.md](references/lookup-field-guide.md) — lookup 字段配置规则、where/aggregate 约束、与 formula 的取舍
-- [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md) — 视图筛选配置
-- [lark-base-record-list.md](references/lark-base-record-list.md) — 记录列表读取与分页
-- [lark-base-record-search.md](references/lark-base-record-search.md) — 关键词搜索记录
-- [lark-base-advperm-enable.md](references/lark-base-advperm-enable.md) — `+advperm-enable` 启用高级权限
-- [lark-base-advperm-disable.md](references/lark-base-advperm-disable.md) — `+advperm-disable` 停用高级权限
-- [lark-base-role-list.md](references/lark-base-role-list.md) — `+role-list` 列出角色
-- [lark-base-role-get.md](references/lark-base-role-get.md) — `+role-get` 获取角色详情
-- [lark-base-role-create.md](references/lark-base-role-create.md) — `+role-create` 创建角色
-- [lark-base-role-update.md](references/lark-base-role-update.md) — `+role-update` 更新角色
-- [lark-base-role-delete.md](references/lark-base-role-delete.md) — `+role-delete` 删除角色
-- [lark-base-dashboard.md](references/lark-base-dashboard.md) — dashboard 模块工作流指引
-- [dashboard-block-data-config.md](references/dashboard-block-data-config.md) — Block `data_config` 结构、图表类型、filter 规则
-- [lark-base-workflow.md](references/lark-base-workflow.md) — workflow 命令索引
-- [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md) — `+workflow-create/+workflow-update` JSON body 结构详解
-- [lark-base-data-query.md](references/lark-base-data-query.md) — `+data-query` 聚合分析，含 DSL 结构、支持字段类型、聚合函数
-- [examples.md](references/examples.md) — 完整操作示例
-
-## 7. 命令分组
-
-> **执行前必做：** 从下表定位到命令后，务必先阅读对应命令的 reference 文档，再调用命令。
-
-| 命令分组 | 说明 |
-|----------|------|
-| [`table commands`](references/lark-base-table.md) | `+table-list / +table-get / +table-create / +table-update / +table-delete` |
-| [`field commands`](references/lark-base-field.md) | `+field-list / +field-get / +field-create / +field-update / +field-delete / +field-search-options` |
-| [`record commands`](references/lark-base-record.md) | `+record-search / +record-list / +record-get / +record-upsert / +record-batch-create / +record-batch-update / +record-upload-attachment / +record-delete` |
-| [`view commands`](references/lark-base-view.md) | `+view-list / +view-get / +view-create / +view-delete / +view-get-* / +view-set-* / +view-rename` |
-| [`data-query commands`](references/lark-base-data-query.md) | `+data-query` |
-| [`history commands`](references/lark-base-history.md) | `+record-history-list` |
-| [`base / workspace commands`](references/lark-base-workspace.md) | `+base-create / +base-get / +base-copy` |
-| [`advperm commands`](references/lark-base-advperm-enable.md) | `+advperm-enable / +advperm-disable` |
-| [`role commands`](references/lark-base-role-list.md) | `+role-list / +role-get / +role-create / +role-update / +role-delete` |
-| [`form commands`](references/lark-base-form-create.md) | `+form-list / +form-get / +form-create / +form-update / +form-delete` |
-| [`form questions commands`](references/lark-base-form-questions-create.md) | `+form-questions-list / +form-questions-create / +form-questions-update / +form-questions-delete` |
-| [`workflow commands`](references/lark-base-workflow.md) | `+workflow-list / +workflow-get / +workflow-create / +workflow-update / +workflow-enable / +workflow-disable` |
-| [`dashboard / dashboard-block commands`](references/lark-base-dashboard.md) | `+dashboard-list / +dashboard-get / +dashboard-create / +dashboard-update / +dashboard-delete / +dashboard-arrange / +dashboard-block-list / +dashboard-block-get / +dashboard-block-create / +dashboard-block-update / +dashboard-block-delete` |

skills/lark-calendar/SKILL.md

@@ -14,6 +14,9 @@ metadata:
 **CRITICAL — 所有的 Shortcuts 在执行之前，务必先使用 Read 工具读取其对应的说明文档，禁止直接盲目调用命令。**
 **CRITICAL — 凡涉及【预约日程/会议】或【查询/搜索会议室】，第一步 MUST 强制使用 Read 工具读取 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。禁止跳过此步直接调用 API 或 Shortcut！**
 **CRITICAL — 术语约束：用户日常表达中常说的“帮我约个日历”、“查一下今天的日历”等，其实际意图通常是针对 日程（Event） 的创建或查询，而非操作 日历（Calendar） 容器本身。请自动将口语化的“日历”意图映射为“日程”操作（如 `+create`, `+agenda`）。**
+**CRITICAL — 会议与日程的意图路由：**
+- **查询过去时间的会议**：如果用户明确查询过去时间的会议（如“昨天的会议”、“上周的会议”），**优先使用 [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md) 搜索会议记录**。因为会议数据不仅包含从日程发起的视频会议，还包含即时会议，仅查询日程数据会导致结果不全。
+- **查询日历/日程或未来时间的会议**：如果用户明确表达的是“日历”、“日程”，或者涉及**未来时间**的安排，则属于本技能（lark-calendar）的业务域，请继续使用本技能处理。
 
 
 **时间与日期推断规范：**

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

@@ -86,6 +86,21 @@ lark-cli docs +fetch --doc Z1FjxxxxxxxxxxxxxxxxxxxtnAc --format pretty
 | `bitable` | `lark-base` | 多维表格 |
 | 其他 | 告知用户暂不支持 | — |
 
+## 重要：任务卡片（task 标签）
+
+`docs +fetch` 默认不会查询/展开文档中内嵌的任务详情（例如任务标题、状态、负责人等）。
+它会在返回的 Markdown 中保留任务引用，并返回任务 ID（GUID），例如：
+
+```html
+<task task-id="30597dc9-262e-4597-97f4-f8efcd1aeb95"></task>
+```
+
+如果用户需要查看该任务的详情，需要用返回的 `task-id` 再调用任务 CLI 查询：
+
+```bash
+lark-cli task tasks get --as user --params '{"task_guid":"30597dc9-262e-4597-97f4-f8efcd1aeb95"}'
+```
+
 ## 工具组合
 
 | 需求 | 工具 |

skills/lark-drive/SKILL.md

@@ -19,6 +19,7 @@ metadata:
 - 用户要把本地 `.xlsx` / `.csv` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
+- 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 
 ## 修改标题
@@ -196,6 +197,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | Shortcut | 说明 |
 |----------|------|
 | [`+upload`](references/lark-drive-upload.md) | Upload a local file to Drive |
+| [`+create-folder`](references/lark-drive-create-folder.md) | Create a Drive folder, optionally under a parent folder, with bot auto-grant support |
 | [`+download`](references/lark-drive-download.md) | Download a file from Drive to local |
 | [`+create-shortcut`](references/lark-drive-create-shortcut.md) | Create a shortcut to an existing Drive file in another folder |
 | [`+add-comment`](references/lark-drive-add-comment.md) | Add a full-document comment, or a local comment to selected docx text (also supports wiki URL resolving to doc/docx) |

skills/lark-drive/references/lark-drive-create-folder.md

@@ -0,0 +1,73 @@
+# drive +create-folder（创建云空间文件夹）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+在飞书云空间中创建一个新文件夹。该 shortcut 对原生 `drive files create_folder` 做了一层更适合日常使用的封装：`--folder-token` 可省略，此时会在调用者根目录创建；如果使用 `--as bot`，创建成功后 CLI 会尝试把新文件夹的可管理权限自动授予当前 CLI 用户。
+
+## 命令
+
+```bash
+# 在根目录创建文件夹
+lark-cli drive +create-folder \
+  --name "周报归档"
+
+# 在指定父文件夹下创建子文件夹
+lark-cli drive +create-folder \
+  --folder-token <PARENT_FOLDER_TOKEN> \
+  --name "2026-W16"
+
+# 预览底层调用
+lark-cli drive +create-folder \
+  --folder-token <PARENT_FOLDER_TOKEN> \
+  --name "分析资料" \
+  --dry-run
+```
+
+## 返回值
+
+成功后会返回一个 JSON 对象，常见字段包括：
+
+- `folder_token`：新建文件夹 token，可直接用于后续 `drive +move`、`drive +upload` 等命令
+- `url`：新建文件夹链接（如果接口返回）
+- `name`：文件夹名称
+- `parent_folder_token`：父文件夹 token；为空字符串表示创建在根目录
+- `permission_grant`（可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
+
+> [!IMPORTANT]
+> 如果文件夹是**以应用身份（bot）创建**的，如 `lark-cli drive +create-folder --as bot`，在创建成功后 CLI 会**尝试为当前 CLI 用户自动授予该文件夹的 `full_access`（可管理权限）**。
+>
+> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
+> - `status = granted`：当前 CLI 用户已获得该文件夹的可管理权限
+> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
+> - `status = failed`：文件夹已创建成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文件夹
+>
+> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”。
+>
+> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--name` | 是 | 文件夹名称，不能为空，最长 256 字节 |
+| `--folder-token` | 否 | 父文件夹 token；省略时表示在调用者根目录创建 |
+
+## 行为说明
+
+- **根目录创建**：不传 `--folder-token` 时，shortcut 会向 API 显式传空字符串 `folder_token=""`，让后端按“根目录”语义创建
+- **bot 自动授权**：只有在 `--as bot` 时，结果才会额外带上 `permission_grant`
+- **原生 API 仍可用**：如果用户明确要求按底层 API 字段调用，仍可继续使用 `lark-cli drive files create_folder`
+
+## 推荐场景
+
+- 用户说“在云空间新建一个文件夹 / 目录”时，优先使用 `drive +create-folder`
+- 用户给了父文件夹链接或 token，需要在其下继续分层建目录时，传 `--folder-token`
+- 如果后续还要上传文件、移动文件、建子目录，优先复用返回值里的 `folder_token`
+
+> [!CAUTION]
+> `drive +create-folder` 是**写入操作**，执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -211,7 +211,7 @@ The reply appears in the target message's thread and does not show up in the mai
 - When using `--content`, you are responsible for making the JSON structure match the effective `msg_type`
 - `--reply-in-thread` adds `reply_in_thread=true` to the API request
 - `--reply-in-thread` is mainly meaningful in chats that support thread replies
-- `--image`/`--file`/`--video`/`--audio`/`--video-cover` support local file paths; the shortcut uploads first and then sends the reply; file/image upload is bot-only, so when using `--as user`, the upload step is automatically performed with bot identity, and only the final send uses user identity
+- `--image`/`--file`/`--video`/`--audio`/`--video-cover` support local file paths; the shortcut uploads first and then sends the reply; both the upload and send steps use the same identity (UAT when `--as user`, TAT when `--as bot`)
 - If the provided media value starts with `img_` or `file_`, it is treated as an existing key and used directly
 - `--markdown` always sends `msg_type=post`
 - If you explicitly set `--msg-type` and it conflicts with the chosen content flag, validation fails

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

@@ -211,7 +211,7 @@ lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Test\n\nhello' --dry
 - `--chat-id` and `--user-id` are mutually exclusive; you must provide exactly one
 - `--content` must be valid JSON
 - When using `--content`, you are responsible for making the JSON structure match the effective `msg_type`
-- `--image`/`--file`/`--video`/`--audio` support local file paths; the shortcut uploads first and then sends the message; file/image upload is bot-only, so when using `--as user`, the upload step is automatically performed with bot identity, and only the final send uses user identity
+- `--image`/`--file`/`--video`/`--audio` support local file paths; the shortcut uploads first and then sends the message; both the upload and send steps use the same identity (UAT when `--as user`, TAT when `--as bot`)
 - If the provided media value starts with `img_` or `file_`, it is treated as an existing key and used directly
 - `--markdown` always sends `msg_type=post`, even if you do not explicitly set `--msg-type post`
 - If you explicitly set `--msg-type` and it conflicts with the chosen content flag, validation fails

skills/lark-mail/SKILL.md

@@ -74,6 +74,48 @@ lark-cli mail user_mailbox.messages -h
 
 `-h` 输出即可用 flag 的权威来源。reference 文档中的参数表可辅助理解语义，但实际 flag 名称以 `-h` 为准。
 
+### 收件人搜索：查找邮箱地址
+
+当需要查找收件人邮箱地址时，使用联系人搜索接口。支持多种搜索方式，如：
+- **按人名搜索**：如"给张三发邮件" → query="张三"
+- **按邮箱关键词搜索**：如"发到 larkmail 的邮箱" → query="@larkmail"
+- **按群名搜索**：如"发给项目群" → query="项目群"
+
+```bash
+lark-cli mail multi_entity search --as user --data '{"query":"<关键词>"}'
+```
+
+搜索结果包含多种实体类型：
+
+| `type` 值 | `tag` 示例 | 说明 |
+|-----------|-----------|------|
+| `user` / `chatter` | `chatter` | 个人用户 |
+| `enterprise_mail_group` | `mail_group` | 企业邮件组 |
+| `chat` / `group` | `chat_group_tenant` / `chat_group_normal` | 群聊（有群邮件地址） |
+| `external_contact` | `external_contact` | 外部联系人 |
+
+**处理规则：**
+1. 从结果中筛选有 `email` 字段的条目
+2. 无论匹配数量多少，都必须列出候选项供用户确认后再使用（搜索是模糊匹配，单条结果不代表精确命中）。展示尽可能多的字段帮助用户区分：
+   ```text
+   找到以下匹配"张三"的结果：
+   1. 张三 <zhangsan@example.com>
+      类型：user | 部门：研发团队
+   ---
+   找到多个匹配"组"的结果，请选择：
+   1. 团队邮件组 <team@example.com>
+      类型：enterprise_mail_group | 标签：mail_group
+   2. 项目群 <project@example.com>
+      类型：chat | 成员数：50 | 标签：chat_group_normal
+   3. 张群 <zhangqun@example.com>
+      类型：user | 部门：研发团队 | 备注名：张群同学
+   ```
+   可用字段：`name`（名称）、`email`（邮箱）、`department`（部门）、`tag`（标签）、`display_name`（备注名）、`type`（实体类型）、`member_count`（成员数，群类型时展示）。字段为空时省略。
+3. 若无匹配，告知用户未找到，建议换关键词或直接提供邮箱地址
+4. 用户确认后，将 `email` 传入 compose shortcut 的 `--to` / `--cc` / `--bcc` 参数
+
+**注意：** 用户直接提供完整邮箱地址时不需要搜索，直接使用即可。
+
 ### 命令选择：先判断邮件类型，再决定草稿还是发送
 
 | 邮件类型 | 存草稿（不发送） | 直接发送 |
@@ -131,6 +173,30 @@ lark-cli mail user_mailbox.messages send_status --params '{"user_mailbox_id":"me
 
 返回每个收件人的投递状态（`status`）：1=正在投递, 2=投递失败重试, 3=退信, 4=投递成功, 5=待审批, 6=审批拒绝。向用户简要报告结果，如有异常状态（退信/审批拒绝）需重点提示。
 
+### 撤回邮件
+
+发送成功后，若响应中包含 `recall_available: true`，说明该邮件支持撤回（24 小时内已投递的邮件）。
+
+**撤回操作：**
+```bash
+lark-cli mail user_mailbox.sent_messages recall --as user \
+  --params '{"user_mailbox_id":"me","message_id":"<message_id>"}'
+```
+
+- 返回 `recall_status: available` 表示撤回请求已受理（异步执行）
+- 返回 `recall_status: unavailable` 表示不可撤回，`recall_restriction_reason` 说明原因
+
+**查询撤回进度：**
+```bash
+lark-cli mail user_mailbox.sent_messages get_recall_detail --as user \
+  --params '{"user_mailbox_id":"me","message_id":"<message_id>"}'
+```
+
+- `recall_status: in_progress` — 撤回进行中，可稍后再查
+- `recall_status: done` — 撤回完成，查看 `recall_result`（`all_success` / `all_fail` / `some_fail`）和每个收件人的详情
+
+**注意：** 撤回是异步操作，`recall` 返回成功仅表示请求已受理，实际结果需通过 `get_recall_detail` 查询。若响应中无 `recall_available` 字段，说明该邮件或应用不支持撤回，不要主动提及撤回。
+
 ### 正文格式：优先使用 HTML
 
 撰写邮件正文时，**默认使用 HTML 格式**（body 内容会被自动检测）。仅当用户明确要求纯文本时，才使用 `--plain-text` 标志强制纯文本模式。
@@ -250,6 +316,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli mail +<verb> [flags]`）
 | [`+draft-create`](references/lark-mail-draft-create.md) | Create a brand-new mail draft from scratch (NOT for reply or forward). For reply drafts use +reply; for forward drafts use +forward. Only use +draft-create when composing a new email with no parent message. |
 | [`+draft-edit`](references/lark-mail-draft-edit.md) | Use when updating an existing mail draft without sending it. Prefer this shortcut over calling raw drafts.get or drafts.update directly, because it performs draft-safe MIME read/patch/write editing while preserving unchanged structure, attachments, and headers where possible. |
 | [`+forward`](references/lark-mail-forward.md) | Forward a message and save as draft (default). Use --confirm-send to send immediately after user confirmation. Original message block included automatically. |
+| [`+signature`](references/lark-mail-signature.md) | List or view email signatures with default usage info. |
 
 ## API Resources
 
@@ -329,6 +396,7 @@ lark-cli mail <resource> <method> [flags] # 调用 API
 
 ### user_mailbox.settings
 
+  - `get_signatures` — 获取用户邮箱签名列表
   - `send_as` — 获取账号的所有可发信地址，包括主地址、别名地址、邮件组。可以使用用户地址访问该接口，也可以使用用户有权限的公共邮箱地址访问该接口。
 
 ### user_mailbox.threads
@@ -340,6 +408,11 @@ lark-cli mail <resource> <method> [flags] # 调用 API
   - `modify` — 本接口提供修改邮件会话的能力，支持移动邮件会话的文件夹、给邮件会话添加和移除标签、标记邮件会话读和未读、移动邮件会话至垃圾邮件等能力。不支持移动邮件会话到已删除文件夹，如需，请使用删除邮件会话接口。至少填写add_label_ids、remove_label_ids、add_folder中的一个参数。
   - `trash` — 移动指定的邮件会话到已删除文件夹
 
+### user_mailbox.sent_messages
+
+  - `recall` — 撤回指定邮件。前置条件：邮件须已投递，且发送时间在 24 小时以内；搬家中的域名不支持撤回。返回说明：若用户或邮件不满足撤回条件，接口仍返回 200，响应体中 recall_status 为 unavailable，recall_restriction_reason 标明具体原因。返回成功仅表示撤回请求已受理，实际撤回结果请调用「查询邮件撤回进度」接口获取。
+  - `get_recall_detail` — 查询指定邮件的撤回结果详情，包括整体撤回进度、成功/失败/处理中的收件人数量，以及每个收件人的撤回状态和失败原因。
+
 ## 权限表
 
 | 方法 | 所需 scope |
@@ -384,6 +457,7 @@ lark-cli mail <resource> <method> [flags] # 调用 API
 | `user_mailbox.rules.list` | `mail:user_mailbox.rule:read` |
 | `user_mailbox.rules.reorder` | `mail:user_mailbox.rule:write` |
 | `user_mailbox.rules.update` | `mail:user_mailbox.rule:write` |
+| `user_mailbox.settings.get_signatures` | `mail:user_mailbox:readonly` |
 | `user_mailbox.settings.send_as` | `mail:user_mailbox:readonly` |
 | `user_mailbox.threads.batch_modify` | `mail:user_mailbox.message:modify` |
 | `user_mailbox.threads.batch_trash` | `mail:user_mailbox.message:modify` |
@@ -391,4 +465,6 @@ lark-cli mail <resource> <method> [flags] # 调用 API
 | `user_mailbox.threads.list` | `mail:user_mailbox.message:readonly` |
 | `user_mailbox.threads.modify` | `mail:user_mailbox.message:modify` |
 | `user_mailbox.threads.trash` | `mail:user_mailbox.message:modify` |
+| `user_mailbox.sent_messages.recall` | `mail:user_mailbox.message:modify` |
+| `user_mailbox.sent_messages.get_recall_detail` | `mail:user_mailbox.message:readonly` |
 

skills/lark-mail/references/lark-mail-draft-create.md

@@ -51,6 +51,7 @@ lark-cli mail +draft-create --to alice@example.com --subject '测试' --body 'te
 | `--plain-text` | 否 | 强制纯文本模式，忽略 HTML 自动检测。不可与 `--inline` 同时使用 |
 | `--attach <paths>` | 否 | 普通附件文件路径，多个用逗号分隔。相对路径 |
 | `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到正文末尾。运行 `mail +signature` 查看可用签名。不可与 `--plain-text` 同时使用 |
 | `--format <mode>` | 否 | 输出格式：`json`（默认）/ `pretty` / `table` / `ndjson` / `csv` |
 | `--dry-run` | 否 | 仅打印请求，不执行 |
 

skills/lark-mail/references/lark-mail-draft-edit.md

@@ -219,6 +219,22 @@ lark-cli mail +draft-edit --draft-id <draft_id> --inspect
 { "op": "remove_inline", "target": { "cid": "logo" } }
 ```
 
+`insert_signature`
+
+```json
+{ "op": "insert_signature", "signature_id": "<签名ID>" }
+```
+
+插入签名到正文末尾（引用块之前）。如已有签名则先移除再插入。运行 `mail +signature` 获取可用签名 ID。签名中的模板变量会自动替换，内联图片自动下载嵌入。
+
+`remove_signature`
+
+```json
+{ "op": "remove_signature" }
+```
+
+移除草稿中的现有签名（含签名前的空行间距）。如签名包含内联图片且正文不再引用这些图片，对应的 MIME part 也会一并移除。
+
 注意事项：
 
 - `ops` 按顺序执行
@@ -228,6 +244,7 @@ lark-cli mail +draft-edit --draft-id <draft_id> --inspect
 - **`set_body` 是完整替换** — 它替换整个正文内容（包括引用区）
 - **`set_reply_body` 仅替换引用区前面的用户撰写部分** — 引用区自动重新拼接；value 只传用户撰写内容，不要包含引用区；如果用户要修改引用区内容，用 `set_body` 全量覆盖
 - 通过 `--inspect` 返回的 `has_quoted_content` 字段可判断草稿是否包含引用区
+- 通过 `--inspect` 返回的 `has_signature` / `signature_id` 字段可判断草稿是否包含签名
 
 ## 返回值
 

skills/lark-mail/references/lark-mail-forward.md

@@ -66,6 +66,7 @@ lark-cli mail +forward --message-id <邮件ID> --to alice@example.com --dry-run
 | `--plain-text` | 否 | 强制纯文本模式，忽略所有 HTML 自动检测。不可与 `--inline` 同时使用 |
 | `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔，追加在原邮件附件之后。相对路径 |
 | `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到转发正文与引用块之间。运行 `mail +signature` 查看可用签名。不可与 `--plain-text` 同时使用 |
 | `--confirm-send` | 否 | 确认发送转发（默认只保存草稿）。仅在用户明确确认后使用 |
 | `--dry-run` | 否 | 仅打印请求，不执行 |
 

skills/lark-mail/references/lark-mail-reply-all.md

@@ -70,6 +70,7 @@ lark-cli mail +reply-all --message-id <邮件ID> --body '测试' --dry-run
 | `--plain-text` | 否 | 强制纯文本模式，忽略所有 HTML 自动检测。不可与 `--inline` 同时使用 |
 | `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔。相对路径 |
 | `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到回复正文与引用块之间。运行 `mail +signature` 查看可用签名。不可与 `--plain-text` 同时使用 |
 | `--confirm-send` | 否 | 确认发送回复（默认只保存草稿）。仅在用户明确确认后使用 |
 | `--dry-run` | 否 | 仅打印请求，不执行 |
 

skills/lark-mail/references/lark-mail-reply.md

@@ -73,6 +73,7 @@ lark-cli mail +reply --message-id <邮件ID> --body '<p>测试</p>' --dry-run
 | `--plain-text` | 否 | 强制纯文本模式，忽略所有 HTML 自动检测。不可与 `--inline` 同时使用 |
 | `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔。相对路径 |
 | `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到回复正文与引用块之间。运行 `mail +signature` 查看可用签名。不可与 `--plain-text` 同时使用 |
 | `--confirm-send` | 否 | 确认发送回复（默认只保存草稿）。仅在用户明确确认后使用 |
 | `--dry-run` | 否 | 仅打印请求，不执行 |
 

skills/lark-mail/references/lark-mail-send.md

@@ -70,6 +70,7 @@ lark-cli mail +send --to alice@example.com --subject '测试' --body '<p>test</p
 | `--plain-text` | 否 | 强制纯文本模式，忽略 HTML 自动检测。不可与 `--inline` 同时使用 |
 | `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔。相对路径 |
 | `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到正文末尾。运行 `mail +signature` 查看可用签名。不可与 `--plain-text` 同时使用 |
 | `--confirm-send` | 否 | 确认发送邮件（默认只保存草稿）。仅在用户明确确认收件人和内容后使用 |
 | `--dry-run` | 否 | 仅打印请求，不执行 |
 

skills/lark-mail/references/lark-mail-signature.md

@@ -0,0 +1,98 @@
+# mail +signature
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查看邮箱签名列表或详情。返回签名的类型、默认使用情况、内容预览等信息。TENANT（企业）签名的模板变量会被自动替换为实际值。
+
+本 skill 对应 shortcut：`lark-cli mail +signature`。
+
+## 命令
+
+```bash
+# 列出所有签名
+lark-cli mail +signature
+
+# 查看某个签名的详情（渲染后的内容预览、模板变量值、图片信息）
+lark-cli mail +signature --detail <signature_id>
+
+# 指定邮箱
+lark-cli mail +signature --from shared@example.com
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--from <email>` | 否 | 邮箱地址（默认 `me`） |
+| `--detail <id>` | 否 | 签名 ID，查看详情。省略则列出所有签名 |
+
+## 返回值
+
+**列表模式：**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signatures": [
+      {
+        "id": "<签名ID>",
+        "name": "个人签名",
+        "type": "USER",
+        "content_preview": "这是我的签名内容 [image] 超链接哈哈"
+      },
+      {
+        "id": "<签名ID>",
+        "name": "企业签名",
+        "type": "TENANT",
+        "is_send_default": true,
+        "is_reply_default": true,
+        "content_preview": "企业签名 姓名：陈煌 部门：研发团队"
+      }
+    ]
+  }
+}
+```
+
+**详情模式（`--detail`）：**
+
+```json
+{
+  "ok": true,
+  "data": {
+    "id": "<签名ID>",
+    "name": "企业签名",
+    "type": "TENANT",
+    "is_send_default": true,
+    "is_reply_default": true,
+    "images": [
+      {"cid": "76CEB29E-...", "file_key": "121011...", "image_name": "image.png"}
+    ],
+    "template_vars": {"B-NAME": "陈煌", "B-DEPARTMENT": "研发团队"},
+    "content_preview": "企业签名 姓名：陈煌 部门：研发团队"
+  }
+}
+```
+
+## 字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `type` | `USER`（用户签名，可编辑）或 `TENANT`（企业签名，管理员模板控制） |
+| `is_send_default` | 是否为新邮件的默认签名 |
+| `is_reply_default` | 是否为回复/转发的默认签名 |
+| `images` | 签名内联图片元数据（仅详情模式） |
+| `template_vars` | TENANT 签名的模板变量已替换值（仅详情模式） |
+| `content_preview` | 签名内容的纯文本预览（`<img>` 显示为 `[image]`，最长 200 字符） |
+
+## 与 compose shortcut 配合
+
+获取签名 ID 后，可在发送/回复/转发时附加签名：
+
+```bash
+# 查看签名列表获取 ID
+lark-cli mail +signature
+
+# 在发送邮件时附加签名
+lark-cli mail +send --to alice@example.com --subject '你好' --body '<p>内容</p>' --signature-id <签名ID>
+```

skills/lark-slides/SKILL.md

@@ -83,6 +83,14 @@ Step 2: 生成大纲 → 用户确认 → 创建
   - 生成结构化大纲（每页标题 + 要点 + 布局描述），交给用户确认
   - 10 页以内：用 slides +create --slides '[...]' 一步创建 PPT 并添加所有页面
   - 超过 10 页：先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
+  - 含本地图片：
+    · 新建带图 PPT —— 在 slide XML 里写 <img src="@./pic.png" .../>，
+      +create 会自动上传并替换为 file_token（详见 lark-slides-create.md）
+    · 给已有 PPT 加带图新页 —— 先 `slides +media-upload --file ./pic.png --presentation $PID`
+      拿到 file_token，再用它写进 slide XML 调 xml_presentation.slide.create
+    · 给已有页加图 —— XML API 无元素级编辑，需要整页替换；必守规则和流程见下方「给已有 PPT 的已有页加图」章节
+    · 路径必须是 CWD 内的相对路径（如 ./pic.png 或 ./assets/x.png）；
+      绝对路径会被 CLI 拒绝，先 cd 到素材所在目录再执行
   - 每页 slide 需要完整的 XML：背景、文本、图形、配色
   - 复杂元素（table、chart）需参考 XSD 原文
 
@@ -99,6 +107,7 @@ Step 3: 审查 & 交付
 新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
 
 ```bash
+# 追加到末尾
 lark-cli slides xml_presentation.slide create \
   --as user \
   --params '{"xml_presentation_id":"YOUR_ID"}' \
@@ -108,8 +117,29 @@ lark-cli slides xml_presentation.slide create \
     在这里放置 shape、line、table、chart 等元素
   </data>
 </slide>' '{slide:{content:$content}}')"
+
+# 插到指定页之前：before_slide_id 必须在 --data body 里，与 slide 同级
+# ⚠️ 不要把 before_slide_id 写进 --params —— CLI 会当未知 query 参数静默下发，服务端忽略，新页跑到末尾
+lark-cli slides xml_presentation.slide create \
+  --as user \
+  --params '{"xml_presentation_id":"YOUR_ID"}' \
+  --data "$(jq -n --arg content '<slide ...>...</slide>' --arg before 'TARGET_SLIDE_ID' \
+    '{slide:{content:$content}, before_slide_id:$before}')"
 ```
 
+### 给已有 PPT 的已有页加图（整页替换）
+
+XML API 没有元素级编辑接口（见核心规则 7）。想给某一页加图，只能**整页替换**：读原 slide → 加 `<img>` → 原位 create 新页 → 删除旧页。
+
+**必守 4 条**：
+
+1. **先 create 后 delete** —— 顺序反了且 create 失败会丢页
+2. **原 slide 的所有元素必须原样搬到新 XML**（标题、正文、形状、原有 img）—— 只写新 `<img>` 会把原页其他内容全删掉
+3. **`before_slide_id=<旧 slide_id>` 必传，且必须放在 `--data` body 里**（与 `slide` 同级），**不能放在 `--params`** —— `--params` 只接 path/query 参数，body 字段塞进去会被 CLI 当未知 query 参数静默下发，服务端忽略，结果是新页追加到末尾、打乱页序。正确形状：`--data '{"slide":{"content":"..."},"before_slide_id":"<旧 slide_id>"}'`
+4. **新 `<img>` 坐标避开现有元素** —— 读原 `<data>` 里元素的 `topLeftX/Y/width/height` 挑空白区；空间不够就先缩小/挪动现有元素再放图
+
+完整 bash 模板和 `+media-upload` 参数见 [+media-upload 文档](references/lark-slides-media-upload.md)。
+
 ### 风格快速判断表
 
 > **注意**：渐变色必须使用 `rgba()` 格式并带百分比停靠点，如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端回退为白色。
@@ -229,7 +259,8 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 
 | Shortcut | 说明 |
 |----------|------|
-| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面），bot 模式自动授权 |
+| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传），bot 模式自动授权 |
+| [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
 
 ## API Resources
 
@@ -257,12 +288,15 @@ lark-cli slides <resource> <method> [flags]  # 调用 API
 4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
 5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
 6. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
+7. **没有元素级编辑能力**：飞书 slides XML API 只有 slide 级 `create` / `delete`，**没有更新单个 shape/img 坐标或尺寸的接口**。不要向用户承诺"微调坐标/尺寸"、"挪一下这个图"。要改只能整页重建（`xml_presentations.get` 读回 → 改 XML → `slide.delete` 旧页 + `slide.create` 新页），且 `slide_id` 会变、默认追加到末尾（要回原位需 `before_slide_id`）。整页重建前必须先告知用户代价并确认
+8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
 
 ## 权限表
 
 | 方法 | 所需 scope |
 |------|-----------|
-| `slides +create` | `slides:presentation:create`, `slides:presentation:write_only` |
+| `slides +create` | `slides:presentation:create`, `slides:presentation:write_only`（含 `@` 占位符时还需 `docs:document.media:upload`） |
+| `slides +media-upload` | `docs:document.media:upload`（wiki URL 解析还需 `wiki:node:read`） |
 | `xml_presentations.get` | `slides:presentation:read` |
 | `xml_presentation.slide.create` | `slides:presentation:update` 或 `slides:presentation:write_only` |
 | `xml_presentation.slide.delete` | `slides:presentation:update` 或 `slides:presentation:write_only` |
@@ -278,6 +312,9 @@ lark-cli slides <resource> <method> [flags]  # 调用 API
 | 404 | 幻灯片不存在 | 检查 `slide_id` 是否正确 |
 | 403 | 权限不足 | 检查是否拥有对应的 scope |
 | 400 | 无法删除唯一幻灯片 | 演示文稿至少保留一页幻灯片 |
+| 1061002 | params error（媒体上传时） | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
+| 1061004 | forbidden：当前身份对演示文稿无编辑权限 | 确认 user/bot 对目标 PPT 有编辑权限；bot 常见于 PPT 非该 bot 创建，需先授权或用 `+create --as bot` 新建 |
+| validation: unsafe file path | `--file` 给了绝对路径或上层路径 | `--file` 必须是 CWD 内相对路径；先 `cd` 到素材目录再执行 |
 
 ## 创建前自查
 
@@ -301,17 +338,22 @@ lark-cli slides <resource> <method> [flags]  # 调用 API
 | 文字和背景色太接近 | 深色背景用浅色文字，浅色背景用深色文字 |
 | 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
 | 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1`/`dim2` 数据数量是否匹配 |
+| 图片被裁掉一部分 | `<img>` 的 `width`/`height` 是裁剪后尺寸，比例和原图不一致时会自动裁剪；要整图显示就让 `width:height` 对齐原图比例 |
+| 给已有页加图后，原页文字/形状消失了 | 替换整页时必须把原 slide 的 `<data>` 所有元素原样搬过来，不能只写新 `<img>` |
 | 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)`；用 `rgb()` 或省略停靠点会被回退为白色 |
 | 渐变方向不对 | 调整 `linear-gradient` 的角度（`90deg` 水平、`180deg` 垂直、`135deg` 对角线） |
 | 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
 | API 返回 400 | 检查 XML 语法：标签闭合、属性引号、特殊字符转义 |
 | API 返回 3350001 | `xml_presentation_id` 不是通过 `xml_presentations.create` 创建的，或 token 不正确 |
+| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符**只在 `+create --slides` 中替换**；直接调 `xml_presentation.slide.create` 必须先用 `+media-upload` 拿 `file_token` 写进 src |
+| 上传图片报 1061002 params error | `parent_type` 必须是 `slide_file`（slides 唯一接受值）；不要手拼，用 `slides +media-upload` |
 
 ## 参考文档
 
 | 文档 | 说明 |
 |------|------|
-| [lark-slides-create.md](references/lark-slides-create.md) | **+create Shortcut：创建 PPT（支持 `--slides` 一步添加页面）** |
+| [lark-slides-create.md](references/lark-slides-create.md) | **+create Shortcut：创建 PPT（支持 `--slides` 一步添加页面，含 `@` 占位符自动上传图片）** |
+| [lark-slides-media-upload.md](references/lark-slides-media-upload.md) | **+media-upload Shortcut：上传本地图片，返回 `file_token`** |
 | [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md) | **XML Schema 精简速查（必读）** |
 | [slide-templates.md](references/slide-templates.md) | 可复制的 Slide XML 模板 |
 | [xml-format-guide.md](references/xml-format-guide.md) | XML 详细结构与示例 |

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

@@ -34,6 +34,7 @@ lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
 - **`revision_id`**（integer）：演示文稿版本号
 - **`slide_ids`**（string[]，可选）：仅传 `--slides` 时返回，成功添加的页面 ID 列表
 - **`slides_added`**（integer，可选）：仅传 `--slides` 时返回，成功添加的页面数量
+- **`images_uploaded`**（integer，可选）：仅 `--slides` 中含 `@<本地路径>` 占位符时返回，已上传的去重后图片数量
 - **`permission_grant`**（object，可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
 
 > [!IMPORTANT]
@@ -68,6 +69,43 @@ lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
 
 JSON string 数组，每个元素是一页 slide 的完整 XML。CLI 内部负责包装成 API 所需的 `{"slide": {"content": "..."}}` 格式并逐页调用。
 
+### 本地图片：`@<path>` 占位符
+
+`<img>` 元素的 `src` 属性如果以 `@` 开头，CLI 会把它当作本地文件路径，自动上传到当前演示文稿，并把占位符替换为返回的 `file_token`。
+
+```bash
+lark-cli slides +create --as user --title "图测试" --slides '[
+  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><img src=\"@./assets/chart.png\" topLeftX=\"100\" topLeftY=\"100\" width=\"320\" height=\"180\"/></data></slide>"
+]'
+```
+
+行为：
+
+- 路径相对于**当前工作目录**（CWD）解析；**必须是 CWD 内的相对路径**（如 `./pic.png`、`./assets/x.png`）
+- 同一份图被多次引用时**只上传一次**（按路径去重）
+- `src` 不以 `@` 开头的会原样保留，但**只允许写 `slides +media-upload` 拿到的 `file_token`**；**禁止写 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 通常显示破图。要用网图必须先下载到 CWD 内、再走上传流程
+- 单张图片最大 20 MB（slides upload API 不支持分片上传）
+- 校验阶段就会检查所有占位符文件存在及大小；缺文件或超限直接报错，不会创建空白 PPT 占位
+- 创空白 PPT → 上传所有图 → 替换 token → 逐页创建 slide，按这个顺序执行
+
+> [!IMPORTANT]
+> **路径必须在 CWD 内**：`@/abs/path/x.png` 或 `@../up/x.png` 这种会被 CLI 拒绝（报 `unsafe file path`）。如果素材在别的目录，先 `cd` 过去再执行。
+
+### 给已有 PPT 加带图新页
+
+`+create --slides` 只在新建 PPT 时使用 `@` 占位符。给已有 PPT 加带图新页要分两步（CLI 没封装这个组合）：
+
+```bash
+# 1) 上传图片
+TOKEN=$(lark-cli slides +media-upload --as user \
+  --file ./pic.png --presentation $PRES_ID | jq -r .data.file_token)
+
+# 2) 用返回的 file_token 创建带图新页
+lark-cli slides xml_presentation.slide create --as user \
+  --params "{\"xml_presentation_id\":\"$PRES_ID\"}" \
+  --data "{\"slide\":{\"content\":\"<slide xmlns=\\\"http://www.larkoffice.com/sml/2.0\\\"><data><img src=\\\"$TOKEN\\\" topLeftX=\\\"100\\\" topLeftY=\\\"100\\\" width=\\\"200\\\" height=\\\"200\\\"/></data></slide>\"}}"
+```
+
 ## 创建后续步骤
 
 如果没有使用 `--slides`，`slides +create` 返回的 `xml_presentation_id` 用于后续操作：

skills/lark-slides/references/lark-slides-media-upload.md

@@ -0,0 +1,143 @@
+
+# slides +media-upload（上传本地图片到飞书幻灯片）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+把本地图片上传到指定演示文稿的 drive 媒体库，返回 `file_token`。**返回的 token 作为 `<img src="...">` 的值塞进 slide XML 即可显示图片。**
+
+## 命令
+
+```bash
+# 直接传 xml_presentation_id
+lark-cli slides +media-upload --as user \
+  --file ./pic.png \
+  --presentation slidesXXXXXXXXXXXXXXXXXXXXXX
+
+# 传 slides URL 也行
+lark-cli slides +media-upload --as user \
+  --file ./chart.png \
+  --presentation "https://xxx.feishu.cn/slides/slidesXXXXXXXXXXXXXXXXXXXXXX"
+
+# 传 wiki URL（CLI 自动 wiki.spaces.get_node 解析为真实 token，校验 obj_type=slides）
+lark-cli slides +media-upload --as user \
+  --file ./pic.png \
+  --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX"
+
+# 预览（不实际上传）
+lark-cli slides +media-upload --file ./pic.png --presentation $PRES_ID --dry-run
+```
+
+## 返回值
+
+```json
+{
+  "file_token": "boxcnXXXXXXXXXXXXXXXXXXXXXX",
+  "file_name": "pic.png",
+  "size": 12345,
+  "presentation_id": "slidesXXXXXXXXXXXXXXXXXXXXXX"
+}
+```
+
+- **`file_token`**：把它写进 `<img src="...">`
+- **`file_name` / `size`**：上传文件元信息
+- **`presentation_id`**：解析后的真实 `xml_presentation_id`（wiki URL 解析后会变化）
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file` | 是 | 本地图片路径，**必须是 CWD 内的相对路径**（如 `./pic.png`）。**最大 20 MB**（slides upload API 不支持分片上传） |
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
+
+> [!IMPORTANT]
+> **路径必须在 CWD 内**：`--file /abs/path/x.png` 或 `--file ../up/x.png` 会被 CLI 拒绝（报 `unsafe file path`）。如果素材在别的目录，先 `cd` 过去再执行。
+
+## 使用流程
+
+### 给已有 PPT 加带图新页
+
+```bash
+# 1) 上传图片
+TOKEN=$(lark-cli slides +media-upload --as user \
+  --file ./pic.png \
+  --presentation $PRES_ID | jq -r .data.file_token)
+
+# 2) 用 file_token 创建带图新页
+lark-cli slides xml_presentation.slide create --as user \
+  --params "{\"xml_presentation_id\":\"$PRES_ID\"}" \
+  --data "{\"slide\":{\"content\":\"<slide xmlns=\\\"http://www.larkoffice.com/sml/2.0\\\"><data><img src=\\\"$TOKEN\\\" topLeftX=\\\"100\\\" topLeftY=\\\"100\\\" width=\\\"320\\\" height=\\\"180\\\"/></data></slide>\"}}"
+```
+
+### 新建带图 PPT（推荐用 `+create --slides` 的 `@` 占位符，一步到位）
+
+```bash
+# 不需要单独 +media-upload，写 src="@<本地路径>" 即可
+lark-cli slides +create --as user --title "图测试" --slides '[
+  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><img src=\"@./pic.png\" topLeftX=\"100\" topLeftY=\"100\" width=\"320\" height=\"180\"/></data></slide>"
+]'
+```
+
+详见 [+create 文档](lark-slides-create.md#本地图片path-占位符)。
+
+### 给已有 PPT 的已有页加图（整页替换）
+
+> ⚠️ slides XML API 没有元素级编辑接口（见 SKILL.md 核心规则 7）—— 没法"往现有 slide 上贴一张图"，只能**把整页替换**：读原 slide → 加 `<img>` → 原位插入新页 → 删除旧页。
+
+```bash
+PRES_ID=xxx
+TARGET_SLIDE_ID=yyy       # 要加图的那一页
+
+# 1) 上传图片拿 file_token
+TOKEN=$(lark-cli slides +media-upload --as user \
+  --file ./pic.png --presentation $PRES_ID | jq -r '.data.file_token')
+
+# 2) 读整份 PPT，摘出目标 slide 的完整 XML（保留所有 shape/line/img 原样）
+lark-cli slides xml_presentations get --as user \
+  --params "{\"xml_presentation_id\":\"$PRES_ID\"}" \
+  | jq -r '.data.xml_presentation.content'
+
+# 3) 在 agent 侧拼新 slide XML：原有所有元素原样保留 + 新增一个 <img>
+#    关键：先看原 <data> 里现有元素的 topLeftX/Y/width/height，把 <img> 放到空白区
+
+# 4) 原位 create（before_slide_id = 旧 slide_id）
+lark-cli slides xml_presentation.slide create --as user \
+  --params "{\"xml_presentation_id\":\"$PRES_ID\"}" \
+  --data "$(jq -n --arg content "$NEW_XML" --arg before "$TARGET_SLIDE_ID" \
+    '{slide:{content:$content}, before_slide_id:$before}')"
+
+# 5) create 成功后删旧页
+lark-cli slides xml_presentation.slide delete --as user \
+  --params "{\"xml_presentation_id\":\"$PRES_ID\",\"slide_id\":\"$TARGET_SLIDE_ID\"}"
+```
+
+**必须遵守**：
+
+1. **先 create 后 delete** —— 顺序反了且 create 失败会丢页
+2. **原 slide 的所有元素必须原样搬过来** —— 只写新 `<img>` 会把原页标题/正文/形状全删掉
+3. **`before_slide_id=<旧 slide_id>` 必传** —— 不传新页追加到末尾，打乱页序
+4. **`<img>` 坐标避开现有元素** —— 先读现有元素 bbox 挑空白区；空间不够就缩小/挪动现有元素后再放图
+5. **`<img>` 的 `width:height` 仍需对齐原图比例** —— 比例不一致会被裁剪，参见 [xml-schema-quick-ref.md](xml-schema-quick-ref.md) `<img>` 说明
+6. **`slide_id` 会变** —— 新页有新 ID，外部有深链依赖的要告知用户
+
+## 工作原理
+
+`+media-upload` 内部调用 `POST /open-apis/drive/v1/medias/upload_all`（单次上传，最大 20 MB），固定使用：
+
+- `parent_type=slide_file`（slides 后端唯一接受的取值，已实测验证）
+- `parent_node=<xml_presentation_id>`
+
+**不要尝试用 `slides_image`、`slide_image` 等 parent_type**——后端会返回 1061001 / 1061002 错误。这是 slides 的特殊约定。
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 1061002 | params error / 不支持的 parent_type | 不要用原生 API 自己拼 parent_type；用 `+media-upload` 即可 |
+| 1061004 | forbidden：当前身份对该演示文稿无编辑权限 | 确认当前身份（user 或 bot）对目标 PPT 有编辑权限。bot 模式常见原因：PPT 不是该 bot 创建的——可用 `+create --as bot` 新建，或以 user 身份给 bot 授权 `lark-cli drive permission.members create --as user ...` |
+| 1061044 | parent node not exist | `--presentation` 给的 token 不对，或不是 slides 类型 |
+| 403 | 权限不足 | 检查 `docs:document.media:upload` scope；wiki URL 还需要 `wiki:node:read` |
+
+## 相关命令
+
+- [+create](lark-slides-create.md) — 新建 PPT（支持 `@` 占位符自动上传图片）
+- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 创建 slide 页面（拿到 file_token 后塞进 XML）

skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md

@@ -161,6 +161,11 @@ lark-cli slides xml_presentation.slide create --as user \
 | `<data>` | 图形元素容器（shape、img、table、chart 等） |
 | `<note>` | 演讲者备注 |
 
+> [!IMPORTANT]
+> **本地图片必须先上传**：`xml_presentation.slide.create` 不识别 `@./local.png` 占位符（那是 `+create --slides` 的语法糖）。直接调本接口添加带图新页时，必须先用 [`slides +media-upload`](lark-slides-media-upload.md) 拿到 `file_token`，再写进 `<img src="<file_token>">`。
+>
+> 如果是从零开始建带图 PPT，**强烈建议改用 [`slides +create --slides '[...]'`](lark-slides-create.md#本地图片path-占位符)** 一步搞定（自动上传 + 替换 token）。
+
 ## 常见错误
 
 | 错误码 | 含义 | 解决方案 |

skills/lark-slides/references/slide-templates.md

@@ -79,6 +79,106 @@ lark-cli slides xml_presentation.slide create --as user \
 </slide>
 ```
 
+## 带图版式
+
+> **关键提醒**：`<img>` 的 `width:height` = 原图比例时才不会被裁剪。每个模板都标注了图框比例和建议原图比例，**选模板前先对照你的素材比例**，不要硬塞（如把横图放进竖框，会被左右裁掉大半）。把 `@./your-image.jpg` 替换为实际路径（仅 `+create --slides` 支持 `@` 占位符；其他场景需先用 `slides +media-upload` 拿 `file_token`）。
+
+### 封面右图（左字右图）
+
+图框 400×225（**16:9**），建议原图：横幅 16:9（桌面壁纸、产品 banner、landscape 照片）
+
+```xml
+<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <style><fill><fillColor color="linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)"/></fill></style>
+  <data>
+    <shape type="text" topLeftX="60" topLeftY="180" width="450" height="80">
+      <content><p><strong><span color="rgb(255,255,255)" fontSize="44">主标题</span></strong></p></content>
+    </shape>
+    <shape type="text" topLeftX="60" topLeftY="270" width="450" height="40">
+      <content><p><span color="rgb(186,230,253)" fontSize="20">副标题</span></p></content>
+    </shape>
+    <line startX="60" startY="350" endX="180" endY="350">
+      <border color="rgb(59,130,246)" width="3"/>
+    </line>
+    <shape type="text" topLeftX="60" topLeftY="370" width="450" height="30">
+      <content><p><span color="rgb(203,213,225)" fontSize="13">底部信息</span></p></content>
+    </shape>
+    <!-- 图框 400×225 = 16:9；原图建议 16:9 横幅 -->
+    <img src="@./your-landscape.jpg" topLeftX="540" topLeftY="157" width="400" height="225"/>
+  </data>
+</slide>
+```
+
+### 三卡片带图（上图下文）
+
+每个图框 240×180（**4:3**），建议原图：4:3 或接近正方形的图（产品照、截图、icon 类）
+
+```xml
+<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <style><fill><fillColor color="rgb(248,250,252)"/></fill></style>
+  <data>
+    <shape type="text" topLeftX="60" topLeftY="40" width="600" height="45">
+      <content><p><strong><span color="rgb(15,23,42)" fontSize="28">核心亮点</span></strong></p></content>
+    </shape>
+    <line startX="60" startY="95" endX="140" endY="95">
+      <border color="rgb(59,130,246)" width="3"/>
+    </line>
+
+    <!-- 卡片 1 -->
+    <shape type="rect" topLeftX="60" topLeftY="130" width="270" height="360">
+      <fill><fillColor color="rgb(255,255,255)"/></fill>
+      <border color="rgba(0,0,0,0.08)" width="1"/>
+    </shape>
+    <!-- 图框 240×180 = 4:3；原图建议 4:3 -->
+    <img src="@./your-image-1.jpg" topLeftX="75" topLeftY="150" width="240" height="180"/>
+    <shape type="text" topLeftX="75" topLeftY="345" width="240" height="30">
+      <content><p><strong><span color="rgb(15,23,42)" fontSize="18">特性一</span></strong></p></content>
+    </shape>
+    <shape type="text" topLeftX="75" topLeftY="380" width="240" height="90">
+      <content><p><span color="rgb(71,85,105)" fontSize="14">简短描述文案，控制在两行以内。</span></p></content>
+    </shape>
+
+    <!-- 卡片 2：复制卡片 1，shape/img 的 topLeftX 改为 345 / 360 -->
+    <!-- 卡片 3：复制卡片 1，shape/img 的 topLeftX 改为 630 / 645 -->
+  </data>
+</slide>
+```
+
+### 左右分栏（图在左，文在右）
+
+图框 360×540（**2:3 竖幅**），建议原图：2:3 或 3:4 竖幅（人像照、产品竖拍、海报）
+
+> 如果你只有横幅图，不要硬塞进这个竖框 —— 改用"顶部横幅图 + 下方文字"的版式（把这里的图框改成 960×240 横条放在顶部）。
+
+```xml
+<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <style><fill><fillColor color="rgb(255,255,255)"/></fill></style>
+  <data>
+    <!-- 图框 360×540 = 2:3；原图建议 2:3 或 3:4 竖幅 -->
+    <img src="@./your-portrait.jpg" topLeftX="0" topLeftY="0" width="360" height="540"/>
+
+    <shape type="text" topLeftX="410" topLeftY="80" width="490" height="50">
+      <content><p><strong><span color="rgb(15,23,42)" fontSize="30">场景标题</span></strong></p></content>
+    </shape>
+    <line startX="410" startY="140" endX="490" endY="140">
+      <border color="rgb(59,130,246)" width="3"/>
+    </line>
+    <shape type="text" topLeftX="410" topLeftY="160" width="490" height="50">
+      <content><p><span color="rgb(71,85,105)" fontSize="16">一句话描述这个场景的价值。</span></p></content>
+    </shape>
+    <shape type="text" topLeftX="410" topLeftY="230" width="490" height="250">
+      <content textType="body" lineSpacing="multiple:1.8">
+        <ul>
+          <li><p><span color="rgb(51,65,85)" fontSize="15">要点一</span></p></li>
+          <li><p><span color="rgb(51,65,85)" fontSize="15">要点二</span></p></li>
+          <li><p><span color="rgb(51,65,85)" fontSize="15">要点三</span></p></li>
+        </ul>
+      </content>
+    </shape>
+  </data>
+</slide>
+```
+
 ## 深色结尾页
 
 ```xml

skills/lark-slides/references/xml-format-guide.md

@@ -219,6 +219,20 @@
 
 `img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
 
+`src` 只接受两种值：
+
+| `src` 形式 | 说明 |
+|---|---|
+| `file_token`（如 `boxcnXXXXXXXXXXXXXXXXXXXXXX`） | 通过 `slides +media-upload` 上传后返回的 token |
+| `@<本地路径>`（如 `@./assets/chart.png`） | **仅在 `slides +create --slides` 中可用**：CLI 会自动上传该文件并替换为 file_token |
+
+> **禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，`src="https://..."` 在 PPT 里通常显示破图。要用网图必须先 `curl`/下载到 CWD 内，再走上传流程拿 `file_token`。
+
+本地图片的两种姿势：
+
+- **新建带图 PPT**：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
+- **给已有 PPT 加带图新页**：先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token，再用 token 写进 `xml_presentation.slide create` 的 XML
+
 ### `<icon>`
 
 ```xml

skills/lark-slides/references/xml-schema-quick-ref.md

@@ -132,6 +132,10 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 <img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
 ```
 
+`src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（仅 `+create --slides` 自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
+
+> **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
+
 ### icon
 
 ```xml

skills/lark-vc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-vc
 version: 1.0.0
-description: "飞书视频会议：查询会议记录、获取会议纪要产物（总结、待办、章节、逐字稿）。1. 查询已经结束的会议数量或详情时使用本技能(如昨天 | 上周 | 今天已经开过的会议等场景)，查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议记录。3. 获取或整理会议纪要时使用本技能。"
+description: "飞书视频会议：查询会议记录、获取会议纪要产物（总结、待办、章节、逐字稿）。1. 查询已经结束的会议数量或详情时使用本技能(如历史日期｜ 昨天 | 上周 | 今天已经开过的会议等场景)，查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议记录。3. 获取或整理会议纪要时使用本技能。"
 metadata:
   requires:
     bins: ["lark-cli"]

skills/lark-wiki/SKILL.md

@@ -21,6 +21,7 @@ metadata:
 ## 快速决策
 
 - 用户给的是知识库 URL（`.../wiki/<token>`），且后续要查成员/加成员/删成员：先调用 `lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'` 获取 `space_id`，后续成员接口统一使用 `space_id`。
+- 用户要在知识库中创建新节点，优先使用 `lark-cli wiki +node-create`。
 - 用户说“给知识库添加成员/管理员”：先把目标解析成“用户 / 群 / 部门”三类之一，再决定 `member_type`，不要先调 `wiki members create` 再根据报错反推类型。
 - 用户说“部门 + bot”：这是已知不支持路径。不要继续尝试 `wiki members create --as bot`；直接提示必须改成 `--as user`，或明确告知当前要求无法完成。
 - 用户说“用户 / 群 + 添加成员”：先解析对应 ID，再执行 `wiki members create`。

skills/lark-wiki/references/lark-wiki-node-create.md

@@ -45,6 +45,31 @@ lark-cli wiki +node-create \
   --dry-run
 ```
 
+## 返回值
+
+成功后会返回一个 JSON 对象，常见字段包括：
+
+- `resolved_space_id`：最终用于创建的真实知识空间 ID
+- `resolved_by`：空间解析来源，可能是 `explicit_space_id`、`parent_node_token`、`my_library`
+- `node_token`：新建知识库节点 token
+- `obj_token`：节点关联对象 token
+- `obj_type`：节点关联对象类型
+- `node_type`：节点类型
+- `title`：节点标题
+- `permission_grant`（可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
+
+> [!IMPORTANT]
+> 如果节点是**以应用身份（bot）创建**的，如 `lark-cli wiki +node-create --as bot`，在创建成功后 CLI 会**尝试为当前 CLI 用户自动授予该知识库节点的 `full_access`（可管理权限）**。
+>
+> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
+> - `status = granted`：当前 CLI 用户已获得该知识库节点的可管理权限
+> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
+> - `status = failed`：节点已创建成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该节点
+>
+> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”
+>
+> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
 ## 参数
 
 | 参数 | 必填 | 说明 |
@@ -84,6 +109,7 @@ lark-cli wiki +node-create \
   - 仅传 `--title`：会展示 `my_library` 解析 + 创建节点 两步调用
   - 仅传 `--parent-node-token`：会展示“查询父节点 -> 创建节点”两步调用
   - 同时需要 `my_library` 和父节点时：会展示三步调用链
+- **bot 自动授权**：若使用 `--as bot`，结果还会额外带上 `permission_grant`，用于说明是否已自动为当前 CLI 用户授予新建节点的可管理权限
 - **输出结果**：成功后会返回 `resolved_space_id`、`resolved_by`、`node_token`、`obj_token`、`obj_type`、`node_type`、`title` 等字段，便于后续继续操作
 
 ## 推荐场景