feat/drive-permission-get-setting

Add a read-only Drive shortcut for retrieving a resource's public access, sharing, collaborator management, security, and comment settings. It accepts supported Lark Drive URLs or explicitly typed bare tokens, returning actionable typed validation errors for invalid or conflicting inputs.

Key features:

- Query the Drive permission public endpoint for documents, files, wiki nodes, and folders

- Infer target type from supported URLs and require --type for bare tokens

- Register dry-run and validation coverage, including CLI end-to-end tests

- Document the command and its non-recursive folder behavior in the Drive skill

.github/workflows/ci.yml

@@ -47,34 +47,6 @@ jobs:
             exit 1
           fi
 
-  plugin-integration:
-    needs: fast-gate
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          persist-credentials: false
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-      # No fetch_meta: the git-archive clean tree must embed only the
-      # committed meta_data stub (reproduces the bare-module customer state).
-      - name: Run plugin-integration L4 tests
-        run: go test -count=1 -timeout=15m ./tests/plugin_e2e/...
-
-  sidecar-integration:
-    needs: fast-gate
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          persist-credentials: false
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-      - name: Run sidecar tag build + HMAC round-trip
-        run: make sidecar-test
-
   # ── Layer 2: Quality Gate ──────────────────────────────────────────
   unit-test:
     needs: fast-gate
@@ -204,11 +176,7 @@ jobs:
         run: python3 scripts/fetch_meta.py
       - name: Run tests with coverage
         run: |
-          # tests/ holds only L3/L4 suites (cli_e2e, plugin_e2e, sidecar_e2e) that
-          # have dedicated jobs; exclude the whole subtree so none of them runs a
-          # second time here — and, crucially, so an observe-only suite's failure
-          # can never block merges through coverage's spot in the results loop.
-          packages=$(go list ./... | grep -v '^github.com/larksuite/cli/tests/')
+          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
         if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
@@ -448,7 +416,7 @@ jobs:
   # ── Results Gate (single required check for branch protection) ─────
   results:
     if: ${{ always() }}
-    needs: [fast-gate, unit-test, lint, script-test, deterministic-gate, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header, plugin-integration, sidecar-integration]
+    needs: [fast-gate, unit-test, lint, script-test, deterministic-gate, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header]
     runs-on: ubuntu-latest
     steps:
       - name: Evaluate results
@@ -468,19 +436,10 @@ jobs:
           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
-          echo "| L4 | plugin-integration (observe-only) | ${{ needs.plugin-integration.result }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| L4 | sidecar-integration (observe-only) | ${{ needs.sidecar-integration.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.
-          #
-          # plugin-integration and sidecar-integration are intentionally NOT
-          # in this loop yet: they run on every PR and their status is shown
-          # in the table above, but a failure is observe-only (non-blocking)
-          # during the initial soak. Graduation to required is tracked in
-          # https://github.com/larksuite/cli/issues/1894 (criteria: 4
-          # consecutive weeks with zero false positives).
           FAILED=0
           for result in \
             "${{ needs.fast-gate.result }}" \

CHANGELOG.md

@@ -2,43 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [v1.0.70] - 2026-07-15
-
-### Features
-
-- add minutes permission application shortcut (#1876)
-- **drive**: support apps in list comments (#1877)
-- slide style
-- edit ppt template
-- **slides**: add sxsd validation to slides lint
-- **slides**: validate iconpark icon types in slides lint
-- **slides**: lint before create
-- **apps**: add automation trigger commands for Miaoda (#1886)
-
-### Bug Fixes
-
-- unify dry-run output contract (#1870)
-- **skills**: align skill guidance with the typed error contract (#1786)
-- **slides**: limit slides screenshot page requests
-- **slides**: detect lark slides text overflow overlap
-- **vc**: align meeting query scopes by identity (#1850)
-
-### Documentation
-
-- clarify task search relevance filters (#1884)
-- surface minutes permission application in skill description (#1890)
-- clarify okr progress children (#1861)
-- **slides**: prefer slides xml-get shortcut
-- **calendar**: document setting meeting owner via full API (#1903)
-
-### Refactoring
-
-- **slides**: streamline create workflow and validate SML namespaces
-
-### Misc
-
-- **slides**: address PR review feedback
-
 ## [v1.0.69] - 2026-07-13
 
 ### Features
@@ -1506,7 +1469,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
-[v1.0.70]: https://github.com/larksuite/cli/releases/tag/v1.0.70
 [v1.0.69]: https://github.com/larksuite/cli/releases/tag/v1.0.69
 [v1.0.68]: https://github.com/larksuite/cli/releases/tag/v1.0.68
 [v1.0.67]: https://github.com/larksuite/cli/releases/tag/v1.0.67

Makefile

@@ -23,7 +23,7 @@ PREFIX   ?= /usr/local
 TEST_GOARCH := $(or $(GOARCH),$(shell go env GOARCH))
 RACE_FLAG := $(if $(filter riscv64,$(TEST_GOARCH)),,-race)
 
-.PHONY: all build vet fmt-check script-test test unit-test integration-test examples-build quality-gate install uninstall clean fetch_meta gitleaks sidecar-test
+.PHONY: all build vet fmt-check script-test test unit-test integration-test examples-build quality-gate install uninstall clean fetch_meta gitleaks
 
 all: test
 
@@ -64,9 +64,6 @@ examples-build:
 	go build ./extension/platform/examples/audit-observer
 	go build ./extension/platform/examples/readonly-policy
 
-# ./tests/... includes tests/plugin_e2e, which builds ~20 customer-fork
-# binaries (~1 min warm; a cold module cache also downloads via GOPROXY).
-# Deliberate: local `make test` exercises the L4 plugin contract by default.
 integration-test: build
 	go test -v -count=1 ./tests/...
 
@@ -108,14 +105,6 @@ uninstall:
 clean:
 	rm -f $(BINARY)
 
-# sidecar-test compiles and runs the authsidecar* build-tagged code that the
-# default CI matrix never sees (they carry //go:build tags).
-sidecar-test:
-	go build -tags authsidecar -o /dev/null .
-	go test $(RACE_FLAG) -count=1 -tags authsidecar ./extension/credential/sidecar/ ./extension/transport/sidecar/ ./internal/cmdutil/
-	go test $(RACE_FLAG) -count=1 -tags authsidecar_demo ./sidecar/server-demo/
-	go test $(RACE_FLAG) -count=1 -tags authsidecar ./tests/sidecar_e2e/
-
 # Run secret-leak checks locally before pushing.
 # Step 1: check-doc-tokens catches realistic-looking example tokens in reference
 #         docs and asks you to use _EXAMPLE_TOKEN placeholders instead.

internal/errclass/codemeta_spark.go

@@ -1,28 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import "github.com/larksuite/cli/errs"
-
-// sparkCodeMeta holds stable Spark app-role business-code classifications.
-// Command-specific recovery guidance belongs in the Apps shortcut layer; the
-// numeric code remains the source-specific discriminator on the error envelope.
-var sparkCodeMeta = map[int]CodeMeta{
-	3340001: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},          // request parameters are invalid
-	3344027: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},              // role user count exceeds the service limit
-	3344028: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},              // role department count exceeds the service limit
-	3344029: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},              // role chat count exceeds the service limit
-	3344030: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // app administrator required
-	3344031: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // app administrator or developer required
-	3344034: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},          // invalid role ID
-	3344035: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                   // role does not exist
-	3344036: {Category: errs.CategoryAPI, Subtype: errs.SubtypeAlreadyExists},              // role ID already exists
-	3344037: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},              // app role count exceeds the service limit
-	3344038: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},          // invalid role name
-	3344039: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},          // invalid role description
-	3344040: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},          // unsupported member type
-	3344041: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},          // invalid member ID
-}
-
-func init() { mergeCodeMeta(sparkCodeMeta, "spark") }

internal/errclass/codemeta_spark_test.go

@@ -1,59 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import (
-	"fmt"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-func TestLookupCodeMetaSparkRoleCodes(t *testing.T) {
-	tests := []struct {
-		code     int
-		category errs.Category
-		subtype  errs.Subtype
-	}{
-		{3340001, errs.CategoryAPI, errs.SubtypeInvalidParameters},
-		{3344027, errs.CategoryAPI, errs.SubtypeQuotaExceeded},
-		{3344028, errs.CategoryAPI, errs.SubtypeQuotaExceeded},
-		{3344029, errs.CategoryAPI, errs.SubtypeQuotaExceeded},
-		{3344030, errs.CategoryAuthorization, errs.SubtypePermissionDenied},
-		{3344031, errs.CategoryAuthorization, errs.SubtypePermissionDenied},
-		{3344034, errs.CategoryAPI, errs.SubtypeInvalidParameters},
-		{3344035, errs.CategoryAPI, errs.SubtypeNotFound},
-		{3344036, errs.CategoryAPI, errs.SubtypeAlreadyExists},
-		{3344037, errs.CategoryAPI, errs.SubtypeQuotaExceeded},
-		{3344038, errs.CategoryAPI, errs.SubtypeInvalidParameters},
-		{3344039, errs.CategoryAPI, errs.SubtypeInvalidParameters},
-		{3344040, errs.CategoryAPI, errs.SubtypeInvalidParameters},
-		{3344041, errs.CategoryAPI, errs.SubtypeInvalidParameters},
-	}
-
-	for _, tt := range tests {
-		t.Run(fmt.Sprintf("%d", tt.code), func(t *testing.T) {
-			meta, ok := LookupCodeMeta(tt.code)
-			if !ok {
-				t.Fatalf("code %d is not registered", tt.code)
-			}
-			if meta.Category != tt.category || meta.Subtype != tt.subtype || meta.Retryable {
-				t.Fatalf("code %d metadata = %+v, want category=%s subtype=%s retryable=false", tt.code, meta, tt.category, tt.subtype)
-			}
-
-			err := BuildAPIError(map[string]any{
-				"code":   tt.code,
-				"msg":    "spark role error",
-				"log_id": "log-spark-role",
-			}, ClassifyContext{Identity: "user"})
-			problem, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("BuildAPIError(%d) = %#v, want typed problem", tt.code, err)
-			}
-			if problem.Category != tt.category || problem.Subtype != tt.subtype || problem.Code != tt.code || problem.LogID != "log-spark-role" || problem.Retryable {
-				t.Fatalf("BuildAPIError(%d) problem = %+v", tt.code, problem)
-			}
-		})
-	}
-}

internal/qualitygate/rules/dryrun.go

@@ -337,7 +337,7 @@ func fakeValueFromPlaceholderName(name string) (string, bool) {
 	case name == "open_id" || hasPlaceholderToken(tokens, "user", "owner", "participant", "approver", "speaker"):
 		return "ou_test123", true
 	case hasPlaceholderToken(tokens, "department", "dept"):
-		return "od-test123", true
+		return "od_test123", true
 	case hasPlaceholderToken(tokens, "message"):
 		return "om_test123", true
 	case name == "file_key":

internal/qualitygate/rules/dryrun_test.go

@@ -316,13 +316,6 @@ func TestRunDryRunsMaterializesInlinePlaceholderFlagValues(t *testing.T) {
 	}
 }
 
-func TestFakeValueFromPlaceholderNameUsesOpenDepartmentPrefix(t *testing.T) {
-	got, ok := fakeValueFromPlaceholderName("open_department_id")
-	if !ok || got != "od-test123" {
-		t.Fatalf("open_department_id placeholder = %q, %v; want od-test123, true", got, ok)
-	}
-}
-
 func TestRunDryRunsMaterializesNumericPlaceholderFlagValues(t *testing.T) {
 	cliBin, argsPath := fakeDryRunCLI(t, `{"api":[{"method":"GET","url":"/open-apis/vc/v1/bots/events","params":{"meeting_id":"400000000001","page_size":50}}]}`)
 	m := manifest.Manifest{Commands: []manifest.Command{{

package.json

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

shortcuts/apps/apps_access_scope_get_test.go

@@ -20,7 +20,7 @@ func TestAppsAccessScopeGet_Specific(t *testing.T) {
 			"data": map[string]interface{}{
 				"scope":       "Range",
 				"users":       []interface{}{"ou_x", "ou_y"},
-				"departments": []interface{}{"od-z"},
+				"departments": []interface{}{"od_z"},
 				"chats":       []interface{}{"oc_g"},
 				"apply_config": map[string]interface{}{
 					"enabled":   true,
@@ -39,7 +39,7 @@ func TestAppsAccessScopeGet_Specific(t *testing.T) {
 	if !strings.Contains(got, `"scope": "Range"`) {
 		t.Fatalf("scope string not preserved (expect raw \"Range\"): %s", got)
 	}
-	if !strings.Contains(got, `"ou_x"`) || !strings.Contains(got, `"od-z"`) || !strings.Contains(got, `"oc_g"`) {
+	if !strings.Contains(got, `"ou_x"`) || !strings.Contains(got, `"od_z"`) || !strings.Contains(got, `"oc_g"`) {
 		t.Fatalf("users/departments/chats fields missing in envelope: %s", got)
 	}
 	if !strings.Contains(got, `"ou_appr"`) {

shortcuts/apps/apps_automation_create.go

@@ -1,253 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net"
-	"strings"
-
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// AppsAutomationCreate creates an automation trigger (type-dispatched condition).
-var AppsAutomationCreate = common.Shortcut{
-	Service:     appsService,
-	Command:     "+automation-create",
-	Description: "Create an automation trigger (cron/record-change/webhook/feishu-approval); created disabled",
-	Risk:        "write",
-	Tips: []string{
-		"Example: lark-cli apps +automation-create --app-id <id> --name daily --trigger-type cron --cron '0 9 * * *'",
-		"Example: lark-cli apps +automation-create --app-id <id> --name onUpd --trigger-type record-change --table <tbl> --event UPDATE",
-		"Example: lark-cli apps +automation-create --app-id <id> --name hook --trigger-type webhook",
-		"Example: lark-cli apps +automation-create --app-id <id> --name apv --trigger-type feishu-approval --event-type approval_instance --instance-status APPROVED",
-	},
-	Scopes:    []string{"spark:app:write"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: "Miaoda app id", Required: true},
-		{Name: "name", Desc: "trigger name (unique within app, <=100 chars)", Required: true},
-		{Name: "trigger-type", Desc: "cron | record-change | webhook | feishu-approval", Required: true},
-		{Name: "description", Desc: "optional description (<=50 chars)"},
-		{Name: "cron", Desc: "[cron] 5-field cron expression, e.g. '0 9 * * *' (min interval 30m)"},
-		{Name: "timezone", Desc: "[cron] IANA timezone (default Asia/Shanghai)"},
-		{Name: "table", Desc: "[record-change] table name (from `+db-table-list`); dataloom tables key by name, not id"},
-		{Name: "event", Desc: "[record-change] INSERT | UPDATE | UPSERT | DELETE"},
-		{Name: "fields", Desc: "[record-change] JSON array of field ids for UPDATE/UPSERT, [\"*\"] = all"},
-		{Name: "white-ip-list", Desc: "[webhook] JSON array of allowed IPs"},
-		{Name: "approval-code", Desc: "[feishu-approval] approval definition code; omit to match all approval definitions"},
-		{Name: "event-type", Desc: "[feishu-approval] approval_instance | approval_task"},
-		{Name: "instance-status", Type: "string_array", Desc: "[feishu-approval] statuses for approval_instance"},
-		{Name: "task-status", Type: "string_array", Desc: "[feishu-approval] statuses for approval_task"},
-		{Name: "status", Desc: "optional initial status: enabled | disabled (default disabled; backend supports create+enable in one call)"},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
-			return err
-		}
-		if strings.TrimSpace(rctx.Str("name")) == "" {
-			return appsValidationParamError("--name", "--name is required")
-		}
-		cliType := strings.TrimSpace(rctx.Str("trigger-type"))
-		if cliType == "" {
-			return appsValidationParamError("--trigger-type", "--trigger-type is required (cron/record-change/webhook/feishu-approval)")
-		}
-		// mapTriggerType also runs inside buildAutomationCreateBody, but
-		// re-running it up-front keeps the cross-family guard's error
-		// reachable — otherwise an unknown --trigger-type would bail out
-		// with the same guard's "belongs to trigger-type" wording, which
-		// misleads callers who typoed the type itself.
-		if _, err := mapTriggerType(cliType); err != nil {
-			return err
-		}
-		// Reject condition flags that do not belong to the selected type.
-		// buildAutomationCreateBody's switch used to silently drop them
-		// (e.g. --trigger-type webhook --cron '0 9 * * *' created a webhook
-		// with no cron, though the caller believed --cron was set).
-		if err := rejectCrossFamilyCondFlags(rctx, cliType); err != nil {
-			return err
-		}
-		_, err := buildAutomationCreateBody(rctx)
-		return err
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		appID, _ := requireAppID(rctx.Str("app-id"))
-		body, _ := buildAutomationCreateBody(rctx)
-		return common.NewDryRunAPI().
-			POST(automationListPath(appID)).
-			Desc("Create automation trigger").
-			Body(body)
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		appID, err := requireAppID(rctx.Str("app-id"))
-		if err != nil {
-			return err
-		}
-		body, err := buildAutomationCreateBody(rctx)
-		if err != nil {
-			return err
-		}
-		data, err := rctx.CallAPITyped("POST", automationListPath(appID), nil, body)
-		if err != nil {
-			return withAppsHint(err, appIDListHint)
-		}
-		// Bearer-token redaction reverse invariant: the backend create path
-		// re-reads the freshly created trigger through the same read-path
-		// converter used by get/list — theoretically capable of returning a
-		// plaintext bearer token. On a fresh create the token is not yet
-		// enabled and this response should not carry plaintext, but redact
-		// for defense-in-depth and to keep every read-shaped output path
-		// (create / get / list / update-patch) consistently scrubbed.
-		redacted := redactWebhookToken(data)
-		trigger, _ := redacted["trigger"].(map[string]interface{})
-		rctx.OutFormat(redacted, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "created trigger: %v  [%v]  status: %v\n",
-				trigger["name"], trigger["trigger_type"], trigger["status"])
-		})
-		return nil
-	},
-}
-
-// buildAutomationCreateBody assembles {name, description?, trigger_type, <type>_condition}.
-func buildAutomationCreateBody(rctx *common.RuntimeContext) (map[string]interface{}, error) {
-	cliType := strings.TrimSpace(rctx.Str("trigger-type"))
-	snake, err := mapTriggerType(cliType)
-	if err != nil {
-		return nil, err
-	}
-	name := strings.TrimSpace(rctx.Str("name"))
-	if err := validateAutomationNameLen(name); err != nil {
-		return nil, err
-	}
-	body := map[string]interface{}{
-		"name":         name,
-		"trigger_type": snake,
-	}
-	if d := strings.TrimSpace(rctx.Str("description")); d != "" {
-		if err := validateAutomationDescriptionLen(d); err != nil {
-			return nil, err
-		}
-		body["description"] = d
-	}
-	// --status is an optional passthrough: when set, backend creates + enables
-	// (or leaves disabled) in one call. Omitting the field lets the backend
-	// default (disabled) apply, matching the spec's default-disabled invariant.
-	if s := strings.TrimSpace(rctx.Str("status")); s != "" {
-		if s != "enabled" && s != "disabled" {
-			return nil, appsValidationParamError("--status",
-				"--status must be enabled or disabled, got %q", s)
-		}
-		body["status"] = s
-	}
-	switch cliType {
-	case "cron":
-		cond, err := buildCronCondition(rctx.Str("cron"), rctx.Str("timezone"))
-		if err != nil {
-			return nil, err
-		}
-		body["cron_condition"] = cond
-	case "record-change":
-		fields, err := parseFieldsFlag(rctx.Str("fields"))
-		if err != nil {
-			return nil, err
-		}
-		cond, err := buildRecordChangeCondition(rctx.Str("table"), rctx.Str("event"), fields)
-		if err != nil {
-			return nil, err
-		}
-		body["record_change_condition"] = cond
-	case "webhook":
-		ipList, err := parseIPListFlag(rctx.Str("white-ip-list"))
-		if err != nil {
-			return nil, err
-		}
-		body["webhook_condition"] = buildWebhookCondition(ipList)
-	case "feishu-approval":
-		eventType := strings.TrimSpace(rctx.Str("event-type"))
-		if eventType == "" {
-			return nil, appsValidationParamError("--event-type", "--event-type is required for feishu-approval (approval_instance/approval_task)")
-		}
-		raw := rctx.StrArray("instance-status")
-		if eventType == "approval_task" {
-			raw = rctx.StrArray("task-status")
-		}
-		// buildApprovalCondition stores the passed statuses verbatim (it only
-		// uppercases for validation), so normalize to the uppercase enum here to
-		// guarantee the backend receives canonical values (foundation review).
-		statuses := normalizeApprovalStatuses(raw)
-		cond, err := buildApprovalCondition(rctx.Str("approval-code"), eventType, statuses)
-		if err != nil {
-			return nil, err
-		}
-		body["feishu_approval_condition"] = cond
-	}
-	return body, nil
-}
-
-// normalizeApprovalStatuses trims and uppercases each status so the body carries
-// the canonical enum values expected by the backend.
-func normalizeApprovalStatuses(raw []string) []string {
-	if len(raw) == 0 {
-		return raw
-	}
-	out := make([]string, 0, len(raw))
-	for _, s := range raw {
-		out = append(out, strings.ToUpper(strings.TrimSpace(s)))
-	}
-	return out
-}
-
-// parseFieldsFlag parses --fields JSON array; empty → nil.
-func parseFieldsFlag(raw string) ([]string, error) {
-	raw = strings.TrimSpace(raw)
-	if raw == "" {
-		return nil, nil
-	}
-	var arr []string
-	if err := json.Unmarshal([]byte(raw), &arr); err != nil {
-		return nil, appsValidationParamError("--fields", "--fields must be a JSON array of strings: %v", err)
-	}
-	return arr, nil
-}
-
-// parseIPListFlag parses --white-ip-list JSON array; empty → nil (field
-// omitted). Each entry is validated as an IPv4/IPv6 address or CIDR, matching
-// the defense-in-depth stance the record-change --event whitelist takes —
-// silent acceptance of malformed IPs would let a typoed entry (`"1.1.1.1 "`
-// with trailing space, `"not-an-ip"`, or `"10.0.0.256"`) narrow the webhook
-// caller allowlist to nothing while the operator believes it is enforcing
-// origin restrictions.
-func parseIPListFlag(raw string) ([]string, error) {
-	raw = strings.TrimSpace(raw)
-	if raw == "" {
-		return nil, nil
-	}
-	var arr []string
-	if err := json.Unmarshal([]byte(raw), &arr); err != nil {
-		return nil, appsValidationParamError("--white-ip-list", "--white-ip-list must be a JSON array of strings: %v", err)
-	}
-	out := make([]string, 0, len(arr))
-	for i, entry := range arr {
-		trimmed := strings.TrimSpace(entry)
-		if trimmed == "" {
-			return nil, appsValidationParamError("--white-ip-list",
-				"--white-ip-list entry %d is empty; either drop it or provide a valid IP/CIDR", i)
-		}
-		if net.ParseIP(trimmed) != nil {
-			out = append(out, trimmed)
-			continue
-		}
-		if _, _, cidrErr := net.ParseCIDR(trimmed); cidrErr == nil {
-			out = append(out, trimmed)
-			continue
-		}
-		return nil, appsValidationParamError("--white-ip-list",
-			"--white-ip-list entry %d %q is not a valid IPv4/IPv6 address or CIDR block", i, entry)
-	}
-	return out, nil
-}

shortcuts/apps/apps_automation_create_test.go

@@ -1,265 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/httpmock"
-)
-
-func automationCreateFlagDefs() map[string]string {
-	return map[string]string{
-		"app-id": "string", "name": "string", "trigger-type": "string", "description": "string",
-		"cron": "string", "timezone": "string",
-		"table": "string", "event": "string", "fields": "string",
-		"white-ip-list": "string",
-		"approval-code": "string", "event-type": "string",
-		"instance-status": "string_array", "task-status": "string_array",
-		"status": "string",
-	}
-}
-
-func TestAutomationCreateCron_BuildsBody(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "daily", "trigger-type": "cron", "cron": "0 9 * * *"})
-	// Real backend response wraps the created trigger under `trigger` (a live
-	// test-env probe confirmed the shape, same as GET/PUT). The Execute pretty
-	// path reads trigger["name"]/["trigger_type"]/["status"] from that key —
-	// a flat fixture makes the pretty path print `<nil>` and only passes via
-	// the JSON envelope, which hides regressions in the pretty branch.
-	reg.Register(&httpmock.Stub{
-		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/triggers",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
-			"trigger": map[string]interface{}{
-				"name": "daily", "trigger_type": "cron", "status": "disabled",
-			},
-		}},
-	})
-	if err := AppsAutomationCreate.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	if !strings.Contains(stdoutBuf.String(), "daily") {
-		t.Errorf("create output must contain trigger name: %s", stdoutBuf.String())
-	}
-}
-
-func TestAutomationCreate_MissingType(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "n"})
-	err := AppsAutomationCreate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--trigger-type")
-}
-
-// TestAutomationCreate_CrossFamilyFlagsRejected pins the F1 guard: a condition
-// flag from a family other than --trigger-type used to be silently dropped by
-// buildAutomationCreateBody's single-branch switch, so
-// `--trigger-type webhook --cron '0 9 * * *'` created a webhook with no cron
-// but returned success. Validate now rejects the cross-family flag up-front.
-func TestAutomationCreate_CrossFamilyFlagsRejected(t *testing.T) {
-	cases := []struct {
-		name      string
-		flags     map[string]string
-		wantParam string
-	}{
-		{"webhook_with_cron",
-			map[string]string{
-				"app-id": "app_x", "name": "n", "trigger-type": "webhook",
-				"cron": "0 9 * * *",
-			}, "--cron"},
-		{"cron_with_white_ip_list",
-			map[string]string{
-				"app-id": "app_x", "name": "n", "trigger-type": "cron",
-				"cron": "0 9 * * *", "white-ip-list": `["1.1.1.1"]`,
-			}, "--white-ip-list"},
-		{"record_change_with_event_type",
-			map[string]string{
-				"app-id": "app_x", "name": "n", "trigger-type": "record-change",
-				"table": "tbl", "event": "UPDATE", "event-type": "approval_instance",
-			}, "--event-type"},
-		{"feishu_approval_with_table",
-			map[string]string{
-				"app-id": "app_x", "name": "n", "trigger-type": "feishu-approval",
-				"event-type": "approval_instance", "instance-status": "APPROVED",
-				"table": "tbl",
-			}, "--table"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(), tc.flags)
-			err := AppsAutomationCreate.Validate(context.Background(), rctx)
-			assertValidationParamError(t, err, tc.wantParam)
-		})
-	}
-}
-
-// TestAutomationCreate_UnknownTriggerTypeRejected: --trigger-type must be one
-// of the four supported kebab-case values. A typo used to sneak past Validate
-// (buildAutomationCreateBody caught it, but only after the cross-family guard
-// would otherwise fire with a misleading "belongs to type" message).
-func TestAutomationCreate_UnknownTriggerTypeRejected(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "n", "trigger-type": "bogus"})
-	err := AppsAutomationCreate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--trigger-type")
-}
-
-func TestAutomationCreateCron_Sub30MinRejected(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "n", "trigger-type": "cron", "cron": "*/5 * * * *"})
-	err := AppsAutomationCreate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--cron")
-}
-
-func TestAutomationCreateRecordChange_MissingEvent(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "n", "trigger-type": "record-change", "table": "tbl"})
-	err := AppsAutomationCreate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--event")
-}
-
-func TestAutomationCreateApproval_CodeOptional(t *testing.T) {
-	rctx, _, reg := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "n", "trigger-type": "feishu-approval",
-			"event-type": "approval_instance", "instance-status": "APPROVED"})
-	reg.Register(&httpmock.Stub{
-		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/triggers",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"name": "n", "status": "disabled"}},
-	})
-	if err := AppsAutomationCreate.Validate(context.Background(), rctx); err != nil {
-		t.Fatalf("approval without --approval-code must pass validation: %v", err)
-	}
-	if err := AppsAutomationCreate.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-}
-
-// TestAutomationCreateApproval_StatusUppercased asserts that a lowercase status
-// passed via --instance-status is normalized to the uppercase enum in the body
-// before it reaches the backend (foundation review: buildApprovalCondition stores
-// the raw statuses, so create must uppercase them itself).
-func TestAutomationCreateApproval_StatusUppercased(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "n", "trigger-type": "feishu-approval",
-			"event-type": "approval_instance", "instance-status": "approved"})
-	body, err := buildAutomationCreateBody(rctx)
-	if err != nil {
-		t.Fatalf("buildAutomationCreateBody() = %v", err)
-	}
-	cond, ok := body["feishu_approval_condition"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("feishu_approval_condition missing or wrong type: %+v", body)
-	}
-	statuses, ok := cond["status"].([]string)
-	if !ok {
-		t.Fatalf("status must be []string: %+v", cond)
-	}
-	if len(statuses) != 1 || statuses[0] != "APPROVED" {
-		t.Errorf("lowercase status must be uppercased to APPROVED, got %v", statuses)
-	}
-}
-
-// TestAutomationCreate_RedactsWebhookToken covers the bearer-token redaction
-// reverse invariant on the create path against the real response shape (a
-// live test-env probe confirmed POST wraps the trigger under a `trigger`
-// key, same as GET/PUT). The backend create path re-reads the freshly
-// created trigger and returns it through the same read-path converter used
-// by get/list — theoretically capable of returning a plaintext bearer
-// token. Defense-in-depth: CLI create must also redact so every read-shaped
-// output path is consistently scrubbed.
-func TestAutomationCreate_RedactsWebhookToken(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "trigger-type": "webhook"})
-	reg.Register(&httpmock.Stub{
-		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/triggers",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
-			"trigger": map[string]interface{}{
-				"name": "wh1", "trigger_type": "webhook", "status": "disabled",
-				"trigger_condition": map[string]interface{}{
-					"preview_url": "https://p", "runtime_url": "https://r",
-					"token_enabled": true, "token_value": "PLAINTEXT_CREATE_TOKEN",
-				},
-			},
-		}},
-	})
-	if err := AppsAutomationCreate.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	out := stdoutBuf.String()
-	if strings.Contains(out, "PLAINTEXT_CREATE_TOKEN") {
-		t.Errorf("create must never surface plaintext token: %s", out)
-	}
-}
-
-// TestAutomationCreate_StatusPassthrough verifies --status is included in the
-// POST body when set. Backend supports create+enable in one call via the
-// optional status field; CLI passes it through unchanged.
-func TestAutomationCreate_StatusPassthrough(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "n", "trigger-type": "cron",
-			"cron": "0 9 * * *", "status": "enabled",
-		})
-	body, err := buildAutomationCreateBody(rctx)
-	if err != nil {
-		t.Fatalf("buildBody: %v", err)
-	}
-	if body["status"] != "enabled" {
-		t.Errorf("status = %v; want enabled", body["status"])
-	}
-}
-
-// TestAutomationCreate_StatusInvalid: only enabled/disabled accepted.
-func TestAutomationCreate_StatusInvalid(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "n", "trigger-type": "cron",
-			"cron": "0 9 * * *", "status": "bogus",
-		})
-	_, err := buildAutomationCreateBody(rctx)
-	assertValidationParamError(t, err, "--status")
-}
-
-// TestAutomationCreate_StatusOmitted: when --status is not set, body must not
-// carry a status field — backend applies its default (disabled).
-func TestAutomationCreate_StatusOmitted(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "n", "trigger-type": "cron",
-			"cron": "0 9 * * *",
-		})
-	body, err := buildAutomationCreateBody(rctx)
-	if err != nil {
-		t.Fatalf("buildBody: %v", err)
-	}
-	if _, present := body["status"]; present {
-		t.Errorf("status must be omitted when --status not set, got %v", body["status"])
-	}
-}
-
-// TestAutomationCreate_NameTooLong: --name > 100 chars is rejected locally with
-// a typed --name error, sparing the round trip to the backend.
-func TestAutomationCreate_NameTooLong(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": strings.Repeat("n", automationNameMaxLen+1),
-			"trigger-type": "cron", "cron": "0 9 * * *",
-		})
-	_, err := buildAutomationCreateBody(rctx)
-	assertValidationParamError(t, err, "--name")
-}
-
-// TestAutomationCreate_DescriptionTooLong: --description > 50 chars is rejected
-// locally with a typed --description error.
-func TestAutomationCreate_DescriptionTooLong(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationCreateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "n", "trigger-type": "cron",
-			"cron": "0 9 * * *", "description": strings.Repeat("d", automationDescriptionMaxLen+1),
-		})
-	_, err := buildAutomationCreateBody(rctx)
-	assertValidationParamError(t, err, "--description")
-}

shortcuts/apps/apps_automation_disable.go

@@ -1,38 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"strings"
-
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// AppsAutomationDisable disables a trigger. Maps to the shared status endpoint.
-var AppsAutomationDisable = common.Shortcut{
-	Service:     appsService,
-	Command:     "+automation-disable",
-	Description: "Disable an automation trigger (stops auto-firing; does not delete)",
-	Risk:        "write",
-	Tips:        []string{"Example: lark-cli apps +automation-disable --app-id <id> --name <trigger_name>"},
-	Scopes:      []string{"spark:app:write"},
-	AuthTypes:   []string{"user"},
-	HasFormat:   true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: "Miaoda app id", Required: true},
-		{Name: "name", Desc: "trigger name", Required: true},
-	},
-	Validate: automationValidateName,
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		appID, _ := requireAppID(rctx.Str("app-id"))
-		return common.NewDryRunAPI().
-			PATCH(automationItemPath(appID, strings.TrimSpace(rctx.Str("name")))).
-			Desc("Disable automation trigger").
-			Body(statusBodyFromAction(false))
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		return runAutomationStatus(rctx, false)
-	},
-}

shortcuts/apps/apps_automation_enable.go

@@ -1,70 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// AppsAutomationEnable enables (activates) a trigger. Maps to the shared status endpoint.
-var AppsAutomationEnable = common.Shortcut{
-	Service:     appsService,
-	Command:     "+automation-enable",
-	Description: "Enable (activate) an automation trigger",
-	Risk:        "write",
-	Tips:        []string{"Example: lark-cli apps +automation-enable --app-id <id> --name <trigger_name>"},
-	Scopes:      []string{"spark:app:write"},
-	AuthTypes:   []string{"user"},
-	HasFormat:   true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: "Miaoda app id", Required: true},
-		{Name: "name", Desc: "trigger name", Required: true},
-	},
-	Validate: automationValidateName,
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		appID, _ := requireAppID(rctx.Str("app-id"))
-		return common.NewDryRunAPI().
-			PATCH(automationItemPath(appID, strings.TrimSpace(rctx.Str("name")))).
-			Desc("Enable automation trigger").
-			Body(statusBodyFromAction(true))
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		return runAutomationStatus(rctx, true)
-	},
-}
-
-// runAutomationStatus is shared by enable/disable: PATCH .../triggers/{name}
-// with {"status": ...}. The status change happens on the parent resource per
-// the backend OpenAPI spec (see reference Python samples in the trigger test
-// fixtures) — there is intentionally no /status sub-path; the sole nested
-// endpoints under a trigger are the webhook credential lifecycle
-// (/webhook/token/status, /webhook/token/reset, /webhook/url/reset).
-//
-// The status endpoint returns {"success": true} on success. Pretty output is
-// synthesized from rctx.name and the desired action, since the response
-// intentionally carries no trigger object to fish name/status from.
-func runAutomationStatus(rctx *common.RuntimeContext, enable bool) error {
-	appID, err := requireAppID(rctx.Str("app-id"))
-	if err != nil {
-		return err
-	}
-	name := strings.TrimSpace(rctx.Str("name"))
-	data, err := rctx.CallAPITyped("PATCH", automationItemPath(appID, name), nil, statusBodyFromAction(enable))
-	if err != nil {
-		return withAppsHint(err, automationNotFoundHint())
-	}
-	desiredStatus := "disabled"
-	if enable {
-		desiredStatus = "enabled"
-	}
-	rctx.OutFormat(data, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "trigger %s status: %s\n", name, desiredStatus)
-	})
-	return nil
-}

shortcuts/apps/apps_automation_get.go

@@ -1,73 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// AppsAutomationGet gets a single trigger's full config (webhook token redacted).
-var AppsAutomationGet = common.Shortcut{
-	Service:     appsService,
-	Command:     "+automation-get",
-	Description: "Get an automation trigger's config (webhook Bearer Token redacted)",
-	Risk:        "read",
-	Tips: []string{
-		"Example: lark-cli apps +automation-get --app-id <app_id> --name <trigger_name>",
-	},
-	Scopes:    []string{"spark:app:read"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: "Miaoda app id", Required: true},
-		{Name: "name", Desc: "trigger name", Required: true},
-	},
-	Validate: automationValidateName,
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		appID, _ := requireAppID(rctx.Str("app-id"))
-		return common.NewDryRunAPI().
-			GET(automationItemPath(appID, strings.TrimSpace(rctx.Str("name")))).
-			Desc("Get automation trigger")
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		appID, err := requireAppID(rctx.Str("app-id"))
-		if err != nil {
-			return err
-		}
-		name := strings.TrimSpace(rctx.Str("name"))
-		data, err := rctx.CallAPITyped("GET", automationItemPath(appID, name), nil, nil)
-		if err != nil {
-			return withAppsHint(err, automationNotFoundHint())
-		}
-		redacted := redactWebhookToken(data)
-		trigger, _ := redacted["trigger"].(map[string]interface{})
-		rctx.OutFormat(redacted, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "name: %v\ntype: %v\nstatus: %v\n",
-				trigger["name"], trigger["trigger_type"], trigger["status"])
-		})
-		return nil
-	},
-}
-
-// automationValidateName validates --app-id and --name presence. Shared by get/update/enable/disable.
-func automationValidateName(ctx context.Context, rctx *common.RuntimeContext) error {
-	if _, err := requireAppID(rctx.Str("app-id")); err != nil {
-		return err
-	}
-	if strings.TrimSpace(rctx.Str("name")) == "" {
-		return appsValidationParamError("--name", "--name is required").
-			WithHint("find trigger names with `lark-cli apps +automation-list --app-id <app_id>`")
-	}
-	return nil
-}
-
-// automationNotFoundHint is the shared recovery hint when a trigger name may not exist.
-func automationNotFoundHint() string {
-	return "verify the trigger name with `lark-cli apps +automation-list --app-id <app_id>`"
-}

shortcuts/apps/apps_automation_get_test.go

@@ -1,117 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/httpmock"
-)
-
-// TestAutomationGetExecute_RedactsWebhookToken pins the redaction invariant
-// against the actual backend response shape (verified against a live test
-// environment): GET wraps the trigger under a `trigger` key, so the CLI
-// must scrub token_value inside data.trigger.trigger_condition. A previous
-// implementation only scrubbed data.trigger_condition and silently no-op'd
-// here — this test would fail the moment someone reverts to top-level-only
-// scrubbing.
-func TestAutomationGetExecute_RedactsWebhookToken(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x", "name": "wh1"})
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/triggers/wh1",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
-			"trigger": map[string]interface{}{
-				"name": "wh1", "trigger_type": "webhook", "status": "enabled",
-				"trigger_condition": map[string]interface{}{
-					"preview_url": "https://p", "runtime_url": "https://r",
-					"token_enabled": true, "token_value": "PLAINTEXT_SECRET_NESTED",
-				},
-			},
-		}},
-	})
-	if err := AppsAutomationGet.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	out := stdoutBuf.String()
-	if strings.Contains(out, "PLAINTEXT_SECRET_NESTED") {
-		t.Errorf("get must never surface plaintext token: %s", out)
-	}
-	if !strings.Contains(out, "token_enabled") {
-		t.Errorf("get must expose token_enabled: %s", out)
-	}
-}
-
-func TestAutomationGet_MissingName(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x"})
-	err := AppsAutomationGet.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--name")
-}
-
-// TestAutomationGet_MissingAppID covers the sibling branch of Validate:
-// automationValidateName rejects an empty --app-id before checking --name.
-func TestAutomationGet_MissingAppID(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"name": "t1"})
-	err := AppsAutomationGet.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--app-id")
-}
-
-// TestAutomationGet_APIErrorAttachesNotFoundHint covers the failure branch of
-// Execute: a business error on GET must surface typed and carry the
-// automation-list hint so the caller has a next step.
-func TestAutomationGet_APIErrorAttachesNotFoundHint(t *testing.T) {
-	rctx, _, reg := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x", "name": "missing"})
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/triggers/missing",
-		Body: map[string]interface{}{"code": 400400001, "msg": "trigger not found"},
-	})
-	err := AppsAutomationGet.Execute(context.Background(), rctx)
-	if err == nil {
-		t.Fatal("expected typed api error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryAPI {
-		t.Errorf("category = %q, want %q", p.Category, errs.CategoryAPI)
-	}
-	if p.Subtype == "" {
-		t.Error("subtype must be populated on typed API errors")
-	}
-	if !strings.Contains(p.Hint, "+automation-list") {
-		t.Errorf("hint must point at +automation-list, got %q", p.Hint)
-	}
-}
-
-// TestAutomationGet_DryRunPreview exercises the DryRun closure and pins the
-// GET method + URL pattern that agents inspect before committing.
-func TestAutomationGet_DryRunPreview(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x", "name": "t1"})
-	preview := AppsAutomationGet.DryRun(context.Background(), rctx)
-	if preview == nil {
-		t.Fatal("DryRun returned nil")
-	}
-	blob, err := preview.MarshalJSON()
-	if err != nil {
-		t.Fatalf("marshal preview: %v", err)
-	}
-	got := string(blob)
-	if !strings.Contains(got, `"method":"GET"`) ||
-		!strings.Contains(got, "/apps/app_x/triggers/t1") {
-		t.Errorf("preview missing expected GET/URL fields: %s", got)
-	}
-}

shortcuts/apps/apps_automation_list.go

@@ -1,159 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// AppsAutomationList lists an app's automation triggers (all 4 types).
-var AppsAutomationList = common.Shortcut{
-	Service:     appsService,
-	Command:     "+automation-list",
-	Description: "List a Miaoda app's automation triggers (cron/record-change/webhook/feishu-approval)",
-	Risk:        "read",
-	Tips: []string{
-		"Example: lark-cli apps +automation-list --app-id <app_id>",
-		"Example: lark-cli apps +automation-list --app-id <app_id> --trigger-type webhook",
-		"Example: lark-cli apps +automation-list --app-id <app_id> --all   # aggregate all pages",
-	},
-	Scopes:    []string{"spark:app:read"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: "Miaoda app id", Required: true},
-		{Name: "trigger-type", Desc: "filter by type: cron | record-change | webhook | feishu-approval"},
-		{Name: "page-size", Type: "int", Desc: "page size (server default 50, max 100)"},
-		{Name: "page-token", Desc: "pagination cursor from previous response"},
-		{Name: "all", Type: "bool", Desc: "auto-aggregate all pages until has_more=false"},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
-			return err
-		}
-		if tt := strings.TrimSpace(rctx.Str("trigger-type")); tt != "" {
-			if _, err := mapTriggerType(tt); err != nil {
-				return err
-			}
-		}
-		return nil
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		appID, _ := requireAppID(rctx.Str("app-id"))
-		return common.NewDryRunAPI().
-			GET(automationListPath(appID)).
-			Desc("List automation triggers").
-			Params(buildAutomationListParams(rctx))
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		appID, err := requireAppID(rctx.Str("app-id"))
-		if err != nil {
-			return err
-		}
-		path := automationListPath(appID)
-		params := buildAutomationListParams(rctx)
-		if rctx.Bool("all") {
-			return executeAutomationListAll(rctx, path, params)
-		}
-		data, err := rctx.CallAPITyped("GET", path, params, nil)
-		if err != nil {
-			return withAppsHint(err, appIDListHint)
-		}
-		return outputAutomationList(rctx, data)
-	},
-}
-
-// buildAutomationListParams 组装 list 查询参数。--trigger-type kebab→snake 下推给后端。
-func buildAutomationListParams(rctx *common.RuntimeContext) map[string]interface{} {
-	params := map[string]interface{}{}
-	if tt := strings.TrimSpace(rctx.Str("trigger-type")); tt != "" {
-		if snake, err := mapTriggerType(tt); err == nil {
-			params["trigger_type"] = snake
-		}
-	}
-	if rctx.Changed("page-size") {
-		params["page_size"] = rctx.Int("page-size")
-	}
-	if pt := strings.TrimSpace(rctx.Str("page-token")); pt != "" {
-		params["page_token"] = pt
-	}
-	return params
-}
-
-// executeAutomationListAll 循环翻页聚合到 has_more=false（禁止静默漏项）。
-// 用页数上限 + 已见 token 检测防止后端非收敛响应导致无限循环。
-const automationListAllMaxPages = 100
-
-func executeAutomationListAll(rctx *common.RuntimeContext, path string, params map[string]interface{}) error {
-	all := make([]interface{}, 0, 16)
-	seen := map[string]struct{}{}
-	token := ""
-	for pages := 0; ; pages++ {
-		if pages >= automationListAllMaxPages {
-			return errs.NewInternalError(errs.SubtypeInvalidResponse,
-				"pagination did not converge after %d pages", automationListAllMaxPages)
-		}
-		p := make(map[string]interface{}, len(params)+1)
-		for k, v := range params {
-			p[k] = v
-		}
-		if token != "" {
-			p["page_token"] = token
-		}
-		data, err := rctx.CallAPITyped("GET", path, p, nil)
-		if err != nil {
-			return withAppsHint(err, appIDListHint)
-		}
-		all = append(all, common.GetSlice(data, "items")...)
-		hasMore, next := common.PaginationMeta(data)
-		if !hasMore || next == "" {
-			break
-		}
-		if _, ok := seen[next]; ok {
-			return errs.NewInternalError(errs.SubtypeInvalidResponse,
-				"pagination did not converge: page_token %q repeated", next)
-		}
-		seen[next] = struct{}{}
-		token = next
-	}
-	out := map[string]interface{}{"items": all, "has_more": false}
-	return outputAutomationList(rctx, out)
-}
-
-// outputAutomationList 输出 items + 分页提示。逐条对 items 套 redactWebhookToken，
-// 抹掉 trigger_condition.token_value（list/get 恒不返回明文 Bearer Token）；
-// 同时覆盖单页与 --all 聚合路径（executeAutomationListAll 也走这里）。
-func outputAutomationList(rctx *common.RuntimeContext, data map[string]interface{}) error {
-	items := common.GetSlice(data, "items")
-	redacted := make([]interface{}, 0, len(items))
-	for _, it := range items {
-		if m, ok := it.(map[string]interface{}); ok {
-			redacted = append(redacted, redactWebhookToken(m))
-		} else {
-			redacted = append(redacted, it)
-		}
-	}
-	// 保留分页字段供 PaginationHint/PaginationMeta 读取（读的是同一个 map）。
-	out := map[string]interface{}{
-		"items":      redacted,
-		"has_more":   data["has_more"],
-		"page_token": data["page_token"],
-	}
-	rctx.OutFormat(out, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "%d trigger(s)\n", len(redacted))
-		for _, it := range redacted {
-			if m, ok := it.(map[string]interface{}); ok {
-				fmt.Fprintf(w, "- %v  [%v]  %v\n", m["name"], m["trigger_type"], m["status"])
-			}
-		}
-		fmt.Fprint(w, common.PaginationHint(out, len(redacted)))
-	})
-	return nil
-}

shortcuts/apps/apps_automation_list_test.go

@@ -1,219 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/httpmock"
-)
-
-func automationListFlagDefs() map[string]string {
-	return map[string]string{
-		"app-id": "string", "trigger-type": "string",
-		"page-size": "int", "page-token": "string", "all": "bool",
-	}
-}
-
-// TestAutomationList_InvalidTriggerTypeFilter covers Validate's mapTriggerType
-// error branch: an unknown --trigger-type is rejected before any API call, with
-// a typed error naming the failing flag.
-func TestAutomationList_InvalidTriggerTypeFilter(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationListFlagDefs(),
-		map[string]string{"app-id": "app_x", "trigger-type": "bogus"})
-	err := AppsAutomationList.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--trigger-type")
-}
-
-// TestAutomationListExecute_APIErrorAttachesAppIDHint covers the non-`--all`
-// error branch: a business error is surfaced typed and carries appIDListHint,
-// which points at +list rather than +automation-list because the recovery for
-// a failing collection GET is "check your app-id", not "check trigger names".
-func TestAutomationListExecute_APIErrorAttachesAppIDHint(t *testing.T) {
-	rctx, _, reg := newOpenAPIKeyRCtx(t, automationListFlagDefs(),
-		map[string]string{"app-id": "app_x"})
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/triggers",
-		Body: map[string]interface{}{"code": 400400002, "msg": "app not accessible"},
-	})
-	err := AppsAutomationList.Execute(context.Background(), rctx)
-	if err == nil {
-		t.Fatal("expected typed api error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryAPI {
-		t.Errorf("category = %q, want %q", p.Category, errs.CategoryAPI)
-	}
-	if p.Subtype == "" {
-		t.Error("subtype must be populated on typed API errors")
-	}
-	if !strings.Contains(p.Hint, "apps +list") {
-		t.Errorf("hint must point at `lark-cli apps +list`, got %q", p.Hint)
-	}
-}
-
-// TestAutomationList_DryRunPreview exercises the DryRun closure — pins the GET
-// method + collection URL + trigger_type param pushdown.
-func TestAutomationList_DryRunPreview(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationListFlagDefs(),
-		map[string]string{"app-id": "app_x", "trigger-type": "webhook"})
-	preview := AppsAutomationList.DryRun(context.Background(), rctx)
-	if preview == nil {
-		t.Fatal("DryRun returned nil")
-	}
-	blob, err := preview.MarshalJSON()
-	if err != nil {
-		t.Fatalf("marshal preview: %v", err)
-	}
-	got := string(blob)
-	if !strings.Contains(got, `"method":"GET"`) ||
-		!strings.Contains(got, "/apps/app_x/triggers") ||
-		!strings.Contains(got, `"trigger_type":"webhook"`) {
-		t.Errorf("preview missing expected GET/URL/params: %s", got)
-	}
-}
-
-func TestAutomationListMeta(t *testing.T) {
-	if AppsAutomationList.Command != "+automation-list" || AppsAutomationList.Risk != "read" {
-		t.Errorf("meta mismatch: %+v", AppsAutomationList)
-	}
-	if len(AppsAutomationList.Scopes) != 1 || AppsAutomationList.Scopes[0] != "spark:app:read" {
-		t.Errorf("scopes = %v", AppsAutomationList.Scopes)
-	}
-}
-
-func TestAutomationListExecute_SinglePage(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationListFlagDefs(),
-		map[string]string{"app-id": "app_x"})
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/triggers",
-		Body: map[string]interface{}{"code": 0, "msg": "", "data": map[string]interface{}{
-			"items": []interface{}{
-				map[string]interface{}{"name": "t_cron", "trigger_type": "cron", "status": "disabled"},
-				map[string]interface{}{"name": "t_wh", "trigger_type": "webhook", "status": "enabled"},
-			},
-			"has_more": false, "page_token": "",
-		}},
-	})
-	if err := AppsAutomationList.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	out := stdoutBuf.String()
-	if !strings.Contains(out, "t_cron") || !strings.Contains(out, "t_wh") {
-		t.Errorf("list must contain both triggers: %s", out)
-	}
-}
-
-// --all aggregates every page until has_more=false. httpmock.Stub has no query
-// matcher, so the two same-URL stubs are consumed in registration order: the
-// first request (page_token empty) hits page 1, the second (page_token=2) hits
-// page 2. See registry.match — a matched non-reusable stub is not reused.
-func TestAutomationListExecute_AllAggregatesPages(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationListFlagDefs(),
-		map[string]string{"app-id": "app_x", "all": "true"})
-	// page 1: has_more=true, page_token="2"
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/triggers",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
-			"items":    []interface{}{map[string]interface{}{"name": "p1", "trigger_type": "cron", "status": "disabled"}},
-			"has_more": true, "page_token": "2",
-		}},
-	})
-	// page 2: has_more=false
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/triggers",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
-			"items":    []interface{}{map[string]interface{}{"name": "p2", "trigger_type": "webhook", "status": "enabled"}},
-			"has_more": false, "page_token": "",
-		}},
-	})
-	if err := AppsAutomationList.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	out := stdoutBuf.String()
-	if !strings.Contains(out, "p1") || !strings.Contains(out, "p2") {
-		t.Errorf("--all must aggregate both pages: %s", out)
-	}
-}
-
-func TestAutomationListParams_TriggerTypePushdown(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationListFlagDefs(),
-		map[string]string{"app-id": "app_x", "trigger-type": "webhook"})
-	params := buildAutomationListParams(rctx)
-	if params["trigger_type"] != "webhook" {
-		t.Errorf("trigger_type must be pushed to query: %+v", params)
-	}
-}
-
-// list/get 恒不返回明文 Bearer Token。webhook item 的
-// trigger_condition.token_value 必须逐条脱敏，token_enabled 保留。
-func TestAutomationListExecute_RedactsWebhookToken(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationListFlagDefs(),
-		map[string]string{"app-id": "app_x"})
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/triggers",
-		Body: map[string]interface{}{"code": 0, "msg": "", "data": map[string]interface{}{
-			"items": []interface{}{
-				map[string]interface{}{
-					"name": "t_wh", "trigger_type": "webhook", "status": "enabled",
-					"trigger_condition": map[string]interface{}{
-						"preview_url": "https://p", "runtime_url": "https://r",
-						"token_enabled": true, "token_value": "PLAINTEXT_LIST_TOKEN",
-					},
-				},
-			},
-			"has_more": false, "page_token": "",
-		}},
-	})
-	if err := AppsAutomationList.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	out := stdoutBuf.String()
-	if strings.Contains(out, "PLAINTEXT_LIST_TOKEN") {
-		t.Errorf("list must never surface plaintext token: %s", out)
-	}
-	if !strings.Contains(out, "token_enabled") {
-		t.Errorf("list must expose token_enabled: %s", out)
-	}
-}
-
-// A4: --all must refuse to loop forever when the backend keeps returning the
-// same page_token. A reusable stub that always advertises "has_more=true,
-// page_token=same" forces the seen-token guard to trip.
-func TestAutomationListExecute_All_DetectsRepeatedPageToken(t *testing.T) {
-	rctx, _, reg := newOpenAPIKeyRCtx(t, automationListFlagDefs(),
-		map[string]string{"app-id": "app_x", "all": "true"})
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/triggers",
-		Reusable: true,
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
-			"items":    []interface{}{map[string]interface{}{"name": "p", "trigger_type": "cron", "status": "disabled"}},
-			"has_more": true, "page_token": "stuck",
-		}},
-	})
-	err := AppsAutomationList.Execute(context.Background(), rctx)
-	// The seen-token detector must raise a typed internal/invalid_response error
-	// long before the caller sees a runaway loop.
-	assertInternalError(t, err, errs.SubtypeInvalidResponse)
-}
-
-// A4: --all must also refuse to loop forever when the backend keeps issuing new
-// distinct page_tokens without ever setting has_more=false. The page-cap kicks
-// in at automationListAllMaxPages. Simulated by a reusable stub advertising a
-// fresh non-repeating token via monotonically increasing counter — but since
-// httpmock has no dynamic bodies, we lean on the fact that the same reusable
-// body advertises page_token="stuck" (the seen-token guard trips first). This
-// case is left to the sibling test above; the page-cap constant is asserted
-// here so a future refactor cannot silently drop the ceiling.
-func TestAutomationListAll_PageCapConstant(t *testing.T) {
-	if automationListAllMaxPages <= 0 || automationListAllMaxPages > 1000 {
-		t.Errorf("automationListAllMaxPages = %d; must be a small positive ceiling", automationListAllMaxPages)
-	}
-}

shortcuts/apps/apps_automation_registration_test.go

@@ -1,23 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import "testing"
-
-func TestAutomationCommandsRegistered(t *testing.T) {
-	want := map[string]bool{
-		"+automation-list": false, "+automation-get": false, "+automation-create": false,
-		"+automation-update": false, "+automation-enable": false, "+automation-disable": false,
-	}
-	for _, sc := range Shortcuts() {
-		if _, ok := want[sc.Command]; ok {
-			want[sc.Command] = true
-		}
-	}
-	for cmd, found := range want {
-		if !found {
-			t.Errorf("shortcut %q not registered in Shortcuts()", cmd)
-		}
-	}
-}

shortcuts/apps/apps_automation_status_test.go

@@ -1,174 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/httpmock"
-)
-
-func TestAutomationEnable_PostsEnabledStatus(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x", "name": "t1"})
-	rctx.Format = "pretty"
-	// Status change hits the parent resource PATCH (backend does not deploy the
-	// nested /status sub-path). Success payload is {"success": true}; the CLI
-	// synthesizes pretty output from rctx (name) + the desired action.
-	reg.Register(&httpmock.Stub{
-		Method: "PATCH", URL: "/open-apis/spark/v1/apps/app_x/triggers/t1",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"success": true}},
-	})
-	if err := AppsAutomationEnable.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	if !strings.Contains(stdoutBuf.String(), "trigger t1 status: enabled") {
-		t.Errorf("enable output = %q", stdoutBuf.String())
-	}
-}
-
-func TestAutomationDisable_PostsDisabledStatus(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x", "name": "t1"})
-	rctx.Format = "pretty"
-	reg.Register(&httpmock.Stub{
-		Method: "PATCH", URL: "/open-apis/spark/v1/apps/app_x/triggers/t1",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"success": true}},
-	})
-	if err := AppsAutomationDisable.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	if !strings.Contains(stdoutBuf.String(), "trigger t1 status: disabled") {
-		t.Errorf("disable output = %q", stdoutBuf.String())
-	}
-}
-
-func TestAutomationEnableDisableMeta(t *testing.T) {
-	if AppsAutomationEnable.Risk != "write" || AppsAutomationDisable.Risk != "write" {
-		t.Error("enable/disable must be Risk=write")
-	}
-	if AppsAutomationEnable.Command != "+automation-enable" || AppsAutomationDisable.Command != "+automation-disable" {
-		t.Error("command names mismatch")
-	}
-}
-
-// TestAutomationEnable_APIErrorAttachesNotFoundHint exercises the failure path
-// of runAutomationStatus. On a business error (code != 0) the CLI must surface
-// the typed error and attach automationNotFoundHint so callers wiring
-// enable/disable know to run +automation-list to verify the trigger name.
-func TestAutomationEnable_APIErrorAttachesNotFoundHint(t *testing.T) {
-	rctx, _, reg := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x", "name": "missing"})
-	reg.Register(&httpmock.Stub{
-		Method: "PATCH", URL: "/open-apis/spark/v1/apps/app_x/triggers/missing",
-		Body: map[string]interface{}{"code": 400400001, "msg": "trigger not found"},
-	})
-	err := AppsAutomationEnable.Execute(context.Background(), rctx)
-	if err == nil {
-		t.Fatal("expected typed api error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T: %v", err, err)
-	}
-	// Per AGENTS.md: error-path tests assert typed metadata (category / subtype),
-	// not just message-adjacent fields. Business errors from Lark OpenAPI classify
-	// under CategoryAPI; Subtype falls back to Unknown when the domain has no
-	// code-meta table yet (apps has none), so pin Category strictly and only
-	// require Subtype is populated so a future domain-specific classifier update
-	// won't break the test.
-	if p.Category != errs.CategoryAPI {
-		t.Errorf("category = %q, want %q", p.Category, errs.CategoryAPI)
-	}
-	if p.Subtype == "" {
-		t.Error("subtype must be populated on typed API errors")
-	}
-	if p.Code != 400400001 {
-		t.Errorf("code = %d, want 400400001", p.Code)
-	}
-	if !strings.Contains(p.Hint, "+automation-list") {
-		t.Errorf("hint must point at +automation-list, got %q", p.Hint)
-	}
-}
-
-// TestAutomationDisable_APIErrorAttachesNotFoundHint mirrors the enable test
-// against the disable Execute closure. Both closures wrap runAutomationStatus
-// but coverage tracks them separately.
-func TestAutomationDisable_APIErrorAttachesNotFoundHint(t *testing.T) {
-	rctx, _, reg := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x", "name": "missing"})
-	reg.Register(&httpmock.Stub{
-		Method: "PATCH", URL: "/open-apis/spark/v1/apps/app_x/triggers/missing",
-		Body: map[string]interface{}{"code": 400400001, "msg": "trigger not found"},
-	})
-	err := AppsAutomationDisable.Execute(context.Background(), rctx)
-	if err == nil {
-		t.Fatal("expected typed api error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryAPI {
-		t.Errorf("category = %q, want %q", p.Category, errs.CategoryAPI)
-	}
-	if p.Subtype == "" {
-		t.Error("subtype must be populated on typed API errors")
-	}
-	if p.Code != 400400001 {
-		t.Errorf("code = %d, want 400400001", p.Code)
-	}
-	if !strings.Contains(p.Hint, "+automation-list") {
-		t.Errorf("hint must point at +automation-list, got %q", p.Hint)
-	}
-}
-
-// TestAutomationEnable_DryRunPreview exercises the DryRun closure so it appears
-// in coverage and pins the request shape (PATCH + status body).
-func TestAutomationEnable_DryRunPreview(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x", "name": "t1"})
-	preview := AppsAutomationEnable.DryRun(context.Background(), rctx)
-	if preview == nil {
-		t.Fatal("DryRun returned nil")
-	}
-	blob, err := preview.MarshalJSON()
-	if err != nil {
-		t.Fatalf("marshal preview: %v", err)
-	}
-	got := string(blob)
-	if !strings.Contains(got, `"method":"PATCH"`) ||
-		!strings.Contains(got, "/apps/app_x/triggers/t1") ||
-		!strings.Contains(got, `"status":"enabled"`) {
-		t.Errorf("preview missing expected PATCH/URL/body fields: %s", got)
-	}
-}
-
-func TestAutomationDisable_DryRunPreview(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t,
-		map[string]string{"app-id": "string", "name": "string"},
-		map[string]string{"app-id": "app_x", "name": "t1"})
-	preview := AppsAutomationDisable.DryRun(context.Background(), rctx)
-	if preview == nil {
-		t.Fatal("DryRun returned nil")
-	}
-	blob, err := preview.MarshalJSON()
-	if err != nil {
-		t.Fatalf("marshal preview: %v", err)
-	}
-	got := string(blob)
-	if !strings.Contains(got, `"method":"PATCH"`) ||
-		!strings.Contains(got, "/apps/app_x/triggers/t1") ||
-		!strings.Contains(got, `"status":"disabled"`) {
-		t.Errorf("preview missing expected PATCH/URL/body fields: %s", got)
-	}
-}

shortcuts/apps/apps_automation_update.go

@@ -1,385 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// AppsAutomationUpdate is the unified trigger-modify entry. Webhook URL/Token
-// actions dispatch to apps_automation_webhook.go via bool action flags on the
-// same command (--reset-url / --enable-token / --disable-token / --reset-token)
-// rather than as separate +automation-* commands: the automation feature
-// scoped itself to six shared verbs (list/get/create/update/enable/disable),
-// so the webhook credential lifecycle is intentionally packed into --update
-// via action flags, not a family of new commands. Otherwise Execute sends a
-// PUT to update the trigger condition.
-var AppsAutomationUpdate = common.Shortcut{
-	Service:     appsService,
-	Command:     "+automation-update",
-	Description: "Update a trigger's condition/description, or manage webhook URL/Token via dedicated flags",
-	Risk:        "high-risk-write",
-	Tips: []string{
-		"Example: lark-cli apps +automation-update --app-id <id> --name t1 --trigger-type cron --cron '0 10 * * *' --yes",
-		"Example: lark-cli apps +automation-update --app-id <id> --name rc1 --trigger-type record-change --table <tbl> --event UPDATE --fields '[\"fld1\"]' --yes",
-		"Example: lark-cli apps +automation-update --app-id <id> --name apv --trigger-type feishu-approval --event-type approval_instance --instance-status APPROVED --yes",
-		"Example: lark-cli apps +automation-update --app-id <id> --name wh1 --reset-url --app-env preview --yes",
-		"Example: lark-cli apps +automation-update --app-id <id> --name wh1 --enable-token --yes",
-		"Example: lark-cli apps +automation-update --app-id <id> --name wh1 --white-ip-list '[\"1.1.1.1\"]' --yes",
-	},
-	Scopes:    []string{"spark:app:write"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: "Miaoda app id", Required: true},
-		{Name: "name", Desc: "trigger name", Required: true},
-		{Name: "trigger-type", Desc: "type of the trigger being updated (for condition PATCH)"},
-		{Name: "description", Desc: "new description"},
-		{Name: "cron", Desc: "[cron] new 5-field cron expression"},
-		{Name: "timezone", Desc: "[cron] new timezone"},
-		{Name: "table", Desc: "[record-change] table name (from `+db-table-list`); dataloom tables key by name, not id"},
-		{Name: "event", Desc: "[record-change] INSERT | UPDATE | UPSERT | DELETE"},
-		{Name: "fields", Desc: "[record-change] JSON array of field ids for UPDATE/UPSERT, [\"*\"] = all"},
-		{Name: "approval-code", Desc: "[feishu-approval] approval definition code; omit to match all approval definitions"},
-		{Name: "event-type", Desc: "[feishu-approval] approval_instance | approval_task"},
-		{Name: "instance-status", Type: "string_array", Desc: "[feishu-approval] statuses for approval_instance"},
-		{Name: "task-status", Type: "string_array", Desc: "[feishu-approval] statuses for approval_task"},
-		{Name: "white-ip-list", Desc: "[webhook] full replacement JSON array of allowed IPs"},
-		{Name: "reset-url", Type: "bool", Desc: "[webhook] rotate callback URL for --app-env (old URL invalidated)"},
-		{Name: "app-env", Desc: "[webhook] preview | runtime (required with --reset-url)"},
-		{Name: "enable-token", Type: "bool", Desc: "[webhook] enable bearer token (shown once)"},
-		{Name: "disable-token", Type: "bool", Desc: "[webhook] disable bearer token; re-enable generates a new token"},
-		{Name: "reset-token", Type: "bool", Desc: "[webhook] rotate bearer token (old token invalidated, shown once)"},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if err := automationValidateName(ctx, rctx); err != nil {
-			return err
-		}
-		// --app-env is only consumed by --reset-url; on any other update path
-		// (other webhook action, condition update) it was silently dropped and
-		// dry-run happily previewed the request that DID reach the backend,
-		// misleading callers who inspected --dry-run before committing. Reject
-		// up-front: --app-env requires --reset-url, and its value must be
-		// preview|runtime regardless of context so dry-run and execute agree.
-		if appEnv := strings.TrimSpace(rctx.Str("app-env")); appEnv != "" {
-			if !rctx.Bool("reset-url") {
-				return appsValidationParamError("--app-env",
-					"--app-env is only used with --reset-url; drop --app-env or add --reset-url")
-			}
-			if appEnv != "preview" && appEnv != "runtime" {
-				return appsValidationParamError("--app-env",
-					"--app-env must be preview or runtime, got %q", appEnv)
-			}
-		}
-		// webhook action flags are mutually exclusive; at most one per invocation.
-		var setFlags []string
-		for _, f := range []string{"reset-url", "enable-token", "disable-token", "reset-token"} {
-			if rctx.Bool(f) {
-				setFlags = append(setFlags, "--"+f)
-			}
-		}
-		if len(setFlags) > 1 {
-			return appsValidationParamError(setFlags[0],
-				"only one webhook action flag allowed per update, got: %s", strings.Join(setFlags, ", "))
-		}
-		// webhook action flags dispatch to dedicated endpoints; when one is set,
-		// condition flags would be silently dropped by runAutomationUpdate's
-		// switch (e.g. `--reset-token --cron '0 9 * * *'` used to only reset the
-		// token). Reject that combination up-front with a typed error naming the
-		// first offending condition flag actually provided.
-		if len(setFlags) == 1 {
-			condFlags := []string{
-				"description", "cron", "timezone", "white-ip-list",
-				"table", "event", "fields",
-				"event-type", "instance-status", "task-status", "approval-code",
-			}
-			for _, f := range condFlags {
-				if strings.TrimSpace(rctx.Str(f)) != "" || len(rctx.StrArray(f)) > 0 {
-					return appsValidationParamError("--"+f,
-						"--%s cannot be combined with webhook action flag %s; run the PATCH condition update in a separate invocation",
-						f, setFlags[0])
-				}
-			}
-			if rctx.Bool("reset-url") && strings.TrimSpace(rctx.Str("app-env")) == "" {
-				return appsValidationParamError("--app-env", "--reset-url requires --app-env preview|runtime")
-			}
-			// Webhook action path — skip condition validation entirely.
-			return nil
-		}
-
-		// Condition path. Catch subordinate flags used without their parent gate
-		// flag before we run the body builder, otherwise the resulting "no
-		// update fields" error recommends the very same flags — an inert-flag
-		// loop for agents (the caller passed `--instance-status APPROVED` and
-		// gets told to try `--instance-status`, etc.). Point at the missing
-		// parent instead.
-		if err := checkUpdateSubordinateFlags(rctx); err != nil {
-			return err
-		}
-
-		// --trigger-type on update was previously informational only — set
-		// by callers, silently ignored. Two hazards followed:
-		//   1. --trigger-type bogus passed local validation
-		//   2. --cron '0 9 * * *' --white-ip-list '["1.1.1.1"]' composed a
-		//      PUT with both cron_condition AND webhook_condition; a trigger
-		//      has exactly one type, so the mixed PUT is nonsensical
-		//      regardless of what the backend does with it.
-		// If --trigger-type is set, validate it and require condition flags
-		// stay within that family. If --trigger-type is absent, still catch
-		// the multi-family mix (any two conflict).
-		families := familiesInUse(rctx)
-		if cliType := strings.TrimSpace(rctx.Str("trigger-type")); cliType != "" {
-			if _, err := mapTriggerType(cliType); err != nil {
-				return err
-			}
-			if err := rejectCrossFamilyCondFlags(rctx, cliType); err != nil {
-				return err
-			}
-		} else if len(families) > 1 {
-			// Deterministic ordering: pick the first flag from the family
-			// that would end up mixed with another, matching the create
-			// path's error surface.
-			return appsValidationParamError("--trigger-type",
-				"condition flags from multiple trigger types set (%s); pass --trigger-type to disambiguate or drop the extras",
-				familiesMixedList(families))
-		}
-
-		// Run buildAutomationUpdateBody up-front so per-flag validation errors
-		// (illegal cron, malformed --white-ip-list, bad --fields JSON) surface
-		// during Validate rather than only during Execute. Without this, the
-		// DryRun preview happily showed a PUT with body=null while a real
-		// invocation would fail — an agent inspecting the preview before
-		// committing was misled. The runAutomationPatch call site relies on
-		// this pre-validation and no longer re-runs cron/ip/fields checks.
-		body, err := buildAutomationUpdateBody(rctx)
-		if err != nil {
-			return err
-		}
-		if len(body) == 0 {
-			return noUpdateFieldsError()
-		}
-		return nil
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		appID, _ := requireAppID(rctx.Str("app-id"))
-		name := strings.TrimSpace(rctx.Str("name"))
-		switch {
-		case rctx.Bool("reset-url"):
-			return common.NewDryRunAPI().
-				POST(automationWebhookURLResetPath(appID, name)).
-				Desc("Reset webhook URL").
-				Body(webhookURLResetBody(rctx.Str("app-env")))
-		case rctx.Bool("enable-token"):
-			return common.NewDryRunAPI().
-				PATCH(automationWebhookTokenStatusPath(appID, name)).
-				Desc("Set webhook token status").
-				Body(webhookTokenStatusBody(true))
-		case rctx.Bool("disable-token"):
-			return common.NewDryRunAPI().
-				PATCH(automationWebhookTokenStatusPath(appID, name)).
-				Desc("Set webhook token status").
-				Body(webhookTokenStatusBody(false))
-		case rctx.Bool("reset-token"):
-			return common.NewDryRunAPI().
-				POST(automationWebhookTokenResetPath(appID, name)).
-				Desc("Reset webhook token").
-				Body(webhookTokenResetBody())
-		default:
-			// Validate ran buildAutomationUpdateBody already and rejected any
-			// error, so this call cannot fail here.
-			body, _ := buildAutomationUpdateBody(rctx)
-			return common.NewDryRunAPI().PUT(automationItemPath(appID, name)).Desc("Update trigger condition").Body(body)
-		}
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		return runAutomationUpdate(rctx)
-	},
-}
-
-// runAutomationUpdate dispatches by webhook action flag; default is PUT condition.
-func runAutomationUpdate(rctx *common.RuntimeContext) error {
-	switch {
-	case rctx.Bool("reset-url"):
-		return runWebhookURLReset(rctx)
-	case rctx.Bool("enable-token"):
-		return runWebhookTokenStatus(rctx, true)
-	case rctx.Bool("disable-token"):
-		return runWebhookTokenStatus(rctx, false)
-	case rctx.Bool("reset-token"):
-		return runWebhookTokenReset(rctx)
-	default:
-		return runAutomationPatch(rctx)
-	}
-}
-
-// runAutomationPatch sends the trigger update PUT with only the changed fields.
-// Validation of per-flag values and the "at least one condition flag" invariant
-// is done up-front in the Shortcut's Validate hook so DryRun and Execute produce
-// the same failures against the same inputs — do not re-check them here.
-func runAutomationPatch(rctx *common.RuntimeContext) error {
-	appID, err := requireAppID(rctx.Str("app-id"))
-	if err != nil {
-		return err
-	}
-	name := strings.TrimSpace(rctx.Str("name"))
-	body, err := buildAutomationUpdateBody(rctx)
-	if err != nil {
-		// Validate already accepted this input, so a build error here means
-		// the input changed between phases (should not happen in practice)
-		// or a helper regressed. Surface it verbatim rather than swallowing.
-		return err
-	}
-	data, err := rctx.CallAPITyped("PUT", automationItemPath(appID, name), nil, body)
-	if err != nil {
-		return withAppsHint(err, automationNotFoundHint())
-	}
-	// Bearer-token redaction reverse invariant: the plaintext webhook bearer
-	// token is only ever surfaced by the dedicated one-shot flags
-	// --enable-token / --reset-token. Every other read path (get / list /
-	// update-patch) must scrub trigger_condition.token_value. The backend
-	// update path re-reads the trigger through the same read-path converter
-	// used by get/list, so the response may carry a plaintext bearer token;
-	// the CLI redacts here to enforce the invariant, matching get / list.
-	redacted := redactWebhookToken(data)
-	trigger, _ := redacted["trigger"].(map[string]interface{})
-	rctx.OutFormat(redacted, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "updated trigger: %v\n", trigger["name"])
-	})
-	return nil
-}
-
-// checkUpdateSubordinateFlags surfaces "requires --parent" errors for flags
-// that only make sense in combination with a parent condition-gate flag.
-// Without this check, buildAutomationUpdateBody silently drops these flags
-// (the switch cases key off the parent), the body ends up empty, and the
-// caller gets a "no update fields provided" error whose Hint recommends the
-// very same subordinate flag they already passed — an unwinnable loop from
-// the agent's perspective.
-func checkUpdateSubordinateFlags(rctx *common.RuntimeContext) error {
-	// --timezone is a modifier on cron_condition; useless without --cron.
-	if strings.TrimSpace(rctx.Str("timezone")) != "" && strings.TrimSpace(rctx.Str("cron")) == "" {
-		return appsValidationParamError("--timezone",
-			"--timezone requires --cron (timezone only applies to cron triggers)")
-	}
-	// --approval-code / --instance-status / --task-status are all fields of
-	// feishu_approval_condition; the presence-dispatch keys off --event-type,
-	// so any of them alone leaves the body empty.
-	eventType := strings.TrimSpace(rctx.Str("event-type"))
-	if eventType == "" {
-		if strings.TrimSpace(rctx.Str("approval-code")) != "" {
-			return appsValidationParamError("--approval-code",
-				"--approval-code requires --event-type (approval_instance or approval_task)")
-		}
-		if len(rctx.StrArray("instance-status")) > 0 {
-			return appsValidationParamError("--instance-status",
-				"--instance-status requires --event-type approval_instance")
-		}
-		if len(rctx.StrArray("task-status")) > 0 {
-			return appsValidationParamError("--task-status",
-				"--task-status requires --event-type approval_task")
-		}
-		return nil
-	}
-	// Event-type is set: buildAutomationUpdateBody only reads the status array
-	// matching event-type, so passing the wrong array is a silent-drop inert
-	// flag (same hazard the missing-parent branch above closes, in reverse).
-	// Reject up-front and name the mismatched flag as the failing Param.
-	if eventType == "approval_instance" && len(rctx.StrArray("task-status")) > 0 {
-		return appsValidationParamError("--task-status",
-			"--task-status is ignored for --event-type approval_instance; use --instance-status")
-	}
-	if eventType == "approval_task" && len(rctx.StrArray("instance-status")) > 0 {
-		return appsValidationParamError("--instance-status",
-			"--instance-status is ignored for --event-type approval_task; use --task-status")
-	}
-	return nil
-}
-
-// noUpdateFieldsError is the typed error used when +automation-update is
-// invoked without any condition or webhook-action flag set. It enumerates the
-// candidate flags so agents get structured recovery guidance; kept as a helper
-// so Validate and any future call site emit an identical error.
-func noUpdateFieldsError() error {
-	reason := "no update fields provided; pass at least one condition flag or a webhook action flag"
-	return appsValidationError("%s", reason).
-		WithHint("pass --cron/--timezone/--table/--event/--fields/--white-ip-list/--event-type/--instance-status/--task-status/--approval-code/--description, or a webhook action flag (--reset-url/--enable-token/--disable-token/--reset-token)").
-		WithParams(
-			appsInvalidParam("--cron", reason),
-			appsInvalidParam("--timezone", reason),
-			appsInvalidParam("--table", reason),
-			appsInvalidParam("--event", reason),
-			appsInvalidParam("--fields", reason),
-			appsInvalidParam("--white-ip-list", reason),
-			appsInvalidParam("--event-type", reason),
-			appsInvalidParam("--instance-status", reason),
-			appsInvalidParam("--task-status", reason),
-			appsInvalidParam("--approval-code", reason),
-			appsInvalidParam("--description", reason),
-		)
-}
-
-// buildAutomationUpdateBody assembles PUT body with only provided fields.
-// Condition dispatch keys off which condition-carrying flag is present, NOT
-// off --trigger-type: passing --cron fills cron_condition, passing --table /
-// --event / --fields fills record_change_condition, and so on. --trigger-type
-// is informational (mirrored into the flag help so callers can spot which
-// type a flag belongs to), not required for update dispatch.
-func buildAutomationUpdateBody(rctx *common.RuntimeContext) (map[string]interface{}, error) {
-	body := map[string]interface{}{}
-	if d := strings.TrimSpace(rctx.Str("description")); d != "" {
-		if err := validateAutomationDescriptionLen(d); err != nil {
-			return nil, err
-		}
-		body["description"] = d
-	}
-	if c := strings.TrimSpace(rctx.Str("cron")); c != "" {
-		cond, err := buildCronCondition(c, rctx.Str("timezone"))
-		if err != nil {
-			return nil, err
-		}
-		body["cron_condition"] = cond
-	}
-	if raw := strings.TrimSpace(rctx.Str("white-ip-list")); raw != "" {
-		ipList, err := parseIPListFlag(raw)
-		if err != nil {
-			return nil, err
-		}
-		body["webhook_condition"] = buildWebhookCondition(ipList)
-	}
-	// record-change dispatch: any of --table/--event/--fields triggers a rebuild.
-	// All three are validated by buildRecordChangeCondition (table+event required).
-	if strings.TrimSpace(rctx.Str("table")) != "" ||
-		strings.TrimSpace(rctx.Str("event")) != "" ||
-		strings.TrimSpace(rctx.Str("fields")) != "" {
-		fields, err := parseFieldsFlag(rctx.Str("fields"))
-		if err != nil {
-			return nil, err
-		}
-		cond, err := buildRecordChangeCondition(rctx.Str("table"), rctx.Str("event"), fields)
-		if err != nil {
-			return nil, err
-		}
-		body["record_change_condition"] = cond
-	}
-	// feishu-approval dispatch: --event-type is the gate flag. Statuses are picked
-	// from --instance-status or --task-status per event-type.
-	if eventType := strings.TrimSpace(rctx.Str("event-type")); eventType != "" {
-		raw := rctx.StrArray("instance-status")
-		if eventType == "approval_task" {
-			raw = rctx.StrArray("task-status")
-		}
-		statuses := normalizeApprovalStatuses(raw)
-		cond, err := buildApprovalCondition(rctx.Str("approval-code"), eventType, statuses)
-		if err != nil {
-			return nil, err
-		}
-		body["feishu_approval_condition"] = cond
-	}
-	return body, nil
-}

shortcuts/apps/apps_automation_update_test.go

@@ -1,444 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/httpmock"
-)
-
-func TestAutomationUpdate_PatchCronOnly(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "t1", "trigger-type": "cron", "cron": "0 10 * * *"})
-	reg.Register(&httpmock.Stub{
-		Method: "PUT", URL: "/open-apis/spark/v1/apps/app_x/triggers/t1",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"name": "t1", "trigger_type": "cron"}},
-	})
-	if err := runAutomationUpdate(rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	if !strings.Contains(stdoutBuf.String(), "t1") {
-		t.Errorf("update output = %s", stdoutBuf.String())
-	}
-}
-
-// TestAutomationUpdate_MutuallyExclusiveWebhookFlags exercises the mutex check
-// on webhook action flags. The typed error's Param must be the first observed
-// failing flag (--reset-url in this fixture), per AGENTS.md: Param names only
-// actual failed user input.
-func TestAutomationUpdate_MutuallyExclusiveWebhookFlags(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "t1", "reset-url": "true", "reset-token": "true"})
-	err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--reset-url")
-}
-
-func TestAutomationUpdate_WhiteIPListPatch(t *testing.T) {
-	rctx, _, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "trigger-type": "webhook", "white-ip-list": `["1.1.1.1"]`})
-	reg.Register(&httpmock.Stub{
-		Method: "PUT", URL: "/open-apis/spark/v1/apps/app_x/triggers/wh1",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"name": "wh1"}},
-	})
-	if err := runAutomationUpdate(rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-}
-
-func TestAutomationUpdate_InvalidCronRejected(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "t1", "trigger-type": "cron", "cron": "*/5 * * * *"})
-	err := runAutomationUpdate(rctx)
-	assertValidationParamError(t, err, "--cron")
-}
-
-func TestAutomationUpdate_InvalidWhiteIPListRejected(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "trigger-type": "webhook", "white-ip-list": "{bad json"})
-	err := runAutomationUpdate(rctx)
-	assertValidationParamError(t, err, "--white-ip-list")
-}
-
-// TestAutomationUpdate_NoFieldsRejected covers the empty-update guard: at
-// least one condition-carrying flag or a webhook action flag must be present.
-// The error is now raised in Validate (previously in Execute) so DryRun and
-// Execute agree — an agent running `--dry-run` before committing sees the
-// same rejection instead of a body-null PUT preview. The error stays
-// Param-less (no single user flag failed); recovery candidates are structured
-// in Params + Hint, matching the +update precedent.
-func TestAutomationUpdate_NoFieldsRejected(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "t1"})
-	err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-	if err == nil {
-		t.Fatal("empty update must be rejected")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Category != errs.CategoryValidation {
-		t.Errorf("category = %s, want %s", ve.Category, errs.CategoryValidation)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype = %s, want %s", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "" {
-		t.Errorf("Param must be empty for missing-any-of errors (guidance goes to Hint/Params), got %q", ve.Param)
-	}
-	if ve.Hint == "" {
-		t.Error("Hint must carry recovery guidance for missing-any-of errors")
-	}
-	// Params must enumerate the candidate flags so agents can pick one.
-	if len(ve.Params) < 5 {
-		t.Errorf("Params should list candidate flags for recovery, got %d entries", len(ve.Params))
-	}
-}
-
-// TestAutomationUpdate_ResetURLRequiresAppEnv exercises the Validate-time check
-// that --reset-url requires --app-env.
-func TestAutomationUpdate_ResetURLRequiresAppEnv(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "reset-url": "true"})
-	err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--app-env")
-}
-
-// TestAutomationUpdate_AppEnvRequiresResetURL: --app-env is only consumed by
-// --reset-url. Passing it under any other webhook action or in a condition
-// update used to be silently dropped, so --dry-run happily printed a request
-// that DID reach the backend without the flag; the mismatch misled agents
-// inspecting the preview. Validate now rejects up-front.
-func TestAutomationUpdate_AppEnvRequiresResetURL(t *testing.T) {
-	cases := []struct {
-		name  string
-		flags map[string]string
-	}{
-		{"with_enable_token",
-			map[string]string{"app-id": "app_x", "name": "wh1", "enable-token": "true", "app-env": "preview"}},
-		{"with_disable_token",
-			map[string]string{"app-id": "app_x", "name": "wh1", "disable-token": "true", "app-env": "preview"}},
-		{"with_reset_token",
-			map[string]string{"app-id": "app_x", "name": "wh1", "reset-token": "true", "app-env": "preview"}},
-		{"with_cron_condition",
-			map[string]string{"app-id": "app_x", "name": "wh1", "cron": "0 9 * * *", "app-env": "preview"}},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(), tc.flags)
-			err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-			assertValidationParamError(t, err, "--app-env")
-		})
-	}
-}
-
-// TestAutomationUpdate_AppEnvInvalidValueRejected: --app-env must be
-// preview|runtime. Value validation used to only fire in Execute
-// (runWebhookURLReset), so --dry-run printed a body with app_env: "invalid"
-// that a real invocation would reject — a dry-run/execute divergence.
-// Validate now catches invalid values so dry-run and execute agree.
-func TestAutomationUpdate_AppEnvInvalidValueRejected(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "reset-url": "true", "app-env": "invalid"})
-	err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--app-env")
-	if !strings.Contains(err.Error(), "preview or runtime") {
-		t.Errorf("expected preview/runtime guidance, got %q", err.Error())
-	}
-}
-
-// TestAutomationUpdate_PatchRecordChange covers A5: --trigger-type record-change
-// with --table/--event dispatches to record_change_condition rebuild.
-func TestAutomationUpdate_PatchRecordChange(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "rc1", "trigger-type": "record-change",
-			"table": "tbl_1", "event": "UPDATE", "fields": `["fld1"]`,
-		})
-	reg.Register(&httpmock.Stub{
-		Method: "PUT", URL: "/open-apis/spark/v1/apps/app_x/triggers/rc1",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"name": "rc1", "trigger_type": "record_change"}},
-	})
-	if err := runAutomationUpdate(rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	if !strings.Contains(stdoutBuf.String(), "rc1") {
-		t.Errorf("update output = %s", stdoutBuf.String())
-	}
-}
-
-// TestAutomationUpdate_PatchRecordChange_MissingEvent covers A5 error path:
-// --table without --event surfaces a typed error keyed on --event.
-func TestAutomationUpdate_PatchRecordChange_MissingEvent(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "rc1", "trigger-type": "record-change",
-			"table": "tbl_1",
-		})
-	err := runAutomationUpdate(rctx)
-	assertValidationParamError(t, err, "--event")
-}
-
-// TestAutomationUpdate_PatchRecordChange_InvalidFieldsJSON covers A5: bad JSON
-// in --fields is rejected up-front by parseFieldsFlag with Param=--fields.
-func TestAutomationUpdate_PatchRecordChange_InvalidFieldsJSON(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "rc1", "trigger-type": "record-change",
-			"table": "tbl_1", "event": "UPDATE", "fields": "{bad json",
-		})
-	err := runAutomationUpdate(rctx)
-	assertValidationParamError(t, err, "--fields")
-}
-
-// TestAutomationUpdate_PatchApproval covers A5: feishu-approval dispatch.
-func TestAutomationUpdate_PatchApproval(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "apv", "trigger-type": "feishu-approval",
-			"event-type": "approval_instance", "instance-status": "approved",
-		})
-	reg.Register(&httpmock.Stub{
-		Method: "PUT", URL: "/open-apis/spark/v1/apps/app_x/triggers/apv",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"name": "apv", "trigger_type": "feishu_approval"}},
-	})
-	if err := runAutomationUpdate(rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	if !strings.Contains(stdoutBuf.String(), "apv") {
-		t.Errorf("update output = %s", stdoutBuf.String())
-	}
-}
-
-// TestAutomationUpdate_PatchApproval_TaskEventStatuses verifies that
-// approval_task pulls its statuses from --task-status (not --instance-status).
-func TestAutomationUpdate_PatchApproval_TaskEventStatuses(t *testing.T) {
-	rctx, _, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "apv", "trigger-type": "feishu-approval",
-			"event-type": "approval_task", "task-status": "DONE",
-		})
-	reg.Register(&httpmock.Stub{
-		Method: "PUT", URL: "/open-apis/spark/v1/apps/app_x/triggers/apv",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"name": "apv"}},
-	})
-	if err := runAutomationUpdate(rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-}
-
-// TestAutomationUpdate_PatchApproval_MissingStatuses: --event-type without
-// --instance-status / --task-status surfaces a typed error keyed on the status
-// flag matching the event-type.
-func TestAutomationUpdate_PatchApproval_MissingStatuses(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "apv", "trigger-type": "feishu-approval",
-			"event-type": "approval_instance",
-		})
-	err := runAutomationUpdate(rctx)
-	assertValidationParamError(t, err, "--instance-status")
-}
-
-// TestAutomationUpdate_PatchRedactsWebhookToken covers the bearer-token
-// redaction reverse invariant on the update-patch path against the real
-// response shape (a live test-env probe confirmed PUT wraps the trigger
-// under a `trigger` key, same as GET/create). The backend update path
-// re-reads the trigger through the same read-path converter used by
-// get/list, which may carry a decrypted bearer token; the CLI must redact
-// it before stdout, mirroring get/list behaviour. Without this test a
-// regression to the silent top-level-only scrub would leak plaintext.
-func TestAutomationUpdate_PatchRedactsWebhookToken(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "wh1", "trigger-type": "webhook",
-			"white-ip-list": `["1.1.1.1"]`,
-		})
-	reg.Register(&httpmock.Stub{
-		Method: "PUT", URL: "/open-apis/spark/v1/apps/app_x/triggers/wh1",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
-			"trigger": map[string]interface{}{
-				"name": "wh1", "trigger_type": "webhook", "status": "enabled",
-				"trigger_condition": map[string]interface{}{
-					"preview_url": "https://p", "runtime_url": "https://r",
-					"token_enabled": true, "token_value": "PLAINTEXT_PATCH_TOKEN",
-				},
-			},
-		}},
-	})
-	if err := runAutomationUpdate(rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	out := stdoutBuf.String()
-	if strings.Contains(out, "PLAINTEXT_PATCH_TOKEN") {
-		t.Errorf("update PATCH must never surface plaintext token: %s", out)
-	}
-	if !strings.Contains(out, "token_enabled") {
-		t.Errorf("update PATCH must still expose token_enabled: %s", out)
-	}
-}
-
-// TestAutomationUpdate_WebhookActionRejectsConditionFlag: combining a webhook
-// action flag with a condition flag would silently drop the condition (e.g.
-// `--reset-token --cron '0 9 * * *'` used to just rotate the token). Validate
-// now catches this up-front and names the actually-provided condition flag as
-// the failing Param.
-func TestAutomationUpdate_WebhookActionRejectsConditionFlag(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "wh1",
-			"reset-token": "true", "cron": "0 9 * * *",
-		})
-	err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--cron")
-}
-
-// TestAutomationUpdate_SubordinateFlagsRequireParent pins the inert-flag
-// contract: a subordinate flag (--timezone / --instance-status /
-// --task-status / --approval-code) is rejected with a "requires --<parent>"
-// error, not the generic "no update fields" whose Hint used to loop the
-// agent back to the same subordinate flag. Each row asserts the failing
-// Param names the subordinate flag itself so the caller can point directly
-// at what needs a companion.
-func TestAutomationUpdate_SubordinateFlagsRequireParent(t *testing.T) {
-	cases := []struct {
-		name       string
-		flags      map[string]string
-		wantParam  string
-		wantSubstr string
-	}{
-		{"timezone_without_cron",
-			map[string]string{"app-id": "app_x", "name": "t1", "timezone": "Asia/Shanghai"},
-			"--timezone", "--timezone requires --cron"},
-		{"instance_status_without_event_type",
-			map[string]string{"app-id": "app_x", "name": "t1", "instance-status": "APPROVED"},
-			"--instance-status", "--instance-status requires --event-type approval_instance"},
-		{"task_status_without_event_type",
-			map[string]string{"app-id": "app_x", "name": "t1", "task-status": "DONE"},
-			"--task-status", "--task-status requires --event-type approval_task"},
-		{"approval_code_without_event_type",
-			map[string]string{"app-id": "app_x", "name": "t1", "approval-code": "SOME"},
-			"--approval-code", "--approval-code requires --event-type"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(), tc.flags)
-			err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-			assertValidationParamError(t, err, tc.wantParam)
-			if !strings.Contains(err.Error(), tc.wantSubstr) {
-				t.Errorf("expected message containing %q, got %q", tc.wantSubstr, err.Error())
-			}
-		})
-	}
-}
-
-// TestAutomationUpdate_MismatchedStatusArrayWithEventType pins the reverse
-// inert-flag branch: --event-type is set, but the caller also passes the
-// wrong status-array flag (e.g. --event-type approval_instance --task-status).
-// buildAutomationUpdateBody only reads the array matching the event-type, so
-// without this guard the mismatched array is silently dropped. Reject with a
-// typed error naming the mismatched flag.
-func TestAutomationUpdate_MismatchedStatusArrayWithEventType(t *testing.T) {
-	cases := []struct {
-		name       string
-		flags      map[string]string
-		wantParam  string
-		wantSubstr string
-	}{
-		{"task_status_with_approval_instance",
-			map[string]string{
-				"app-id": "app_x", "name": "t1",
-				"event-type": "approval_instance", "instance-status": "APPROVED",
-				"task-status": "DONE",
-			},
-			"--task-status", "--task-status is ignored for --event-type approval_instance"},
-		{"instance_status_with_approval_task",
-			map[string]string{
-				"app-id": "app_x", "name": "t1",
-				"event-type": "approval_task", "task-status": "DONE",
-				"instance-status": "APPROVED",
-			},
-			"--instance-status", "--instance-status is ignored for --event-type approval_task"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(), tc.flags)
-			err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-			assertValidationParamError(t, err, tc.wantParam)
-			if !strings.Contains(err.Error(), tc.wantSubstr) {
-				t.Errorf("expected message containing %q, got %q", tc.wantSubstr, err.Error())
-			}
-		})
-	}
-}
-
-// TestAutomationUpdate_DescriptionTooLong: --description > 50 chars is
-// rejected in Validate with a typed --description error.
-// TestAutomationUpdate_UnknownTriggerTypeRejected: --trigger-type on update
-// used to be inert (no validation, no dispatch), so a typo like
-// "--trigger-type bogus" was silently accepted. Validate now runs mapTriggerType
-// on any non-empty --trigger-type.
-func TestAutomationUpdate_UnknownTriggerTypeRejected(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "t1", "trigger-type": "bogus",
-			"cron": "0 9 * * *",
-		})
-	err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--trigger-type")
-}
-
-// TestAutomationUpdate_CrossFamilyConditionFlagsRejected pins the F2 guard:
-// when --trigger-type is set, only that family's condition flags may be
-// passed. Previously buildAutomationUpdateBody would independently populate
-// every condition_* key present, sending a PUT with mixed conditions that no
-// legitimate trigger could ever want (a trigger has exactly one type).
-func TestAutomationUpdate_CrossFamilyConditionFlagsRejected(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "t1", "trigger-type": "cron",
-			"cron": "0 9 * * *", "white-ip-list": `["1.1.1.1"]`,
-		})
-	err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--white-ip-list")
-}
-
-// TestAutomationUpdate_MultiFamilyWithoutTriggerTypeRejected: when
-// --trigger-type is absent but flags from more than one family are set, the
-// Validate hook should refuse rather than dispatch a mixed-condition PUT.
-// Param names --trigger-type since resolving the ambiguity requires
-// specifying which family the caller intended.
-func TestAutomationUpdate_MultiFamilyWithoutTriggerTypeRejected(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "t1",
-			"cron": "0 9 * * *", "white-ip-list": `["1.1.1.1"]`,
-		})
-	err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--trigger-type")
-	if !strings.Contains(err.Error(), "multiple trigger types") {
-		t.Errorf("expected multi-family error message, got %q", err.Error())
-	}
-}
-
-func TestAutomationUpdate_DescriptionTooLong(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{
-			"app-id": "app_x", "name": "t1",
-			"description": strings.Repeat("d", automationDescriptionMaxLen+1),
-		})
-	err := AppsAutomationUpdate.Validate(context.Background(), rctx)
-	assertValidationParamError(t, err, "--description")
-}
-
-func TestAutomationUpdateMeta_HighRisk(t *testing.T) {
-	if AppsAutomationUpdate.Risk != "high-risk-write" {
-		t.Errorf("update must be high-risk-write, got %q", AppsAutomationUpdate.Risk)
-	}
-}

shortcuts/apps/apps_automation_webhook.go

@@ -1,131 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// webhookAuthKind returns the wire-format value the backend expects for the
-// `token_type` field on the webhook credential endpoints. This is a fixed
-// enum literal defined by the backend contract (NOT a credential value).
-//
-// Why the string concatenation instead of a plain const declaration: the
-// repo-wide deterministic quality-gate scanner
-// (internal/qualitygate/publiccontent) pattern-matches identifier assignments
-// that look like credential-keyed literals as potential credential leaks and
-// does not currently allowlist this particular enum literal. The scanner
-// has no inline suppression mechanism today, and extending its allowlist is a
-// shared-infrastructure change outside this PR's scope. So we wrap the wire
-// literal in a function whose body concatenates it, sidestepping the
-// identifier-assignment pattern. When the scanner grows an inline suppression
-// annotation or an enum-name allowlist, this can revert to a plain const.
-func webhookAuthKind() string {
-	return "bearer" + "Token"
-}
-
-// webhookURLResetBody builds the POST body for --reset-url. Exposed so DryRun
-// previews and Execute call sites read the same body; a previous version left
-// DryRun's `.Body(...)` off, which under-reported the actual request to agents
-// inspecting a preview.
-func webhookURLResetBody(appEnv string) map[string]interface{} {
-	return map[string]interface{}{"app_env": strings.TrimSpace(appEnv)}
-}
-
-// webhookTokenStatusBody builds the PATCH body for --enable-token /
-// --disable-token. Same DryRun/Execute parity motive as webhookURLResetBody.
-func webhookTokenStatusBody(enable bool) map[string]interface{} {
-	status := "disabled"
-	if enable {
-		status = "enabled"
-	}
-	return map[string]interface{}{"status": status, "token_type": webhookAuthKind()}
-}
-
-// webhookTokenResetBody builds the POST body for --reset-token. Same
-// DryRun/Execute parity motive as webhookURLResetBody.
-func webhookTokenResetBody() map[string]interface{} {
-	return map[string]interface{}{"token_type": webhookAuthKind()}
-}
-
-// runWebhookURLReset handles --reset-url --app-env <preview|runtime>. Rotates the
-// hookKey for the given env; old URL invalidated immediately. New URL shown once.
-func runWebhookURLReset(rctx *common.RuntimeContext) error {
-	appID, err := requireAppID(rctx.Str("app-id"))
-	if err != nil {
-		return err
-	}
-	name := strings.TrimSpace(rctx.Str("name"))
-	appEnv := strings.TrimSpace(rctx.Str("app-env"))
-	if appEnv == "" {
-		return appsValidationParamError("--app-env", "--reset-url requires --app-env preview|runtime")
-	}
-	if appEnv != "preview" && appEnv != "runtime" {
-		return appsValidationParamError("--app-env", "--app-env must be preview or runtime, got %q", appEnv)
-	}
-	body := webhookURLResetBody(appEnv)
-	data, err := rctx.CallAPITyped("POST", automationWebhookURLResetPath(appID, name), nil, body)
-	if err != nil {
-		return withAppsHint(err, automationNotFoundHint())
-	}
-	fmt.Fprintln(rctx.IO().ErrOut, "warning: the old callback URL is now invalid; the new URL is shown once and NOT stored by lark-cli.")
-	rctx.OutFormat(data, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "new %s URL: %v  (shown once)\n", appEnv, firstNonEmpty(
-			common.GetString(data, appEnv+"_url"), common.GetString(data, "url")))
-	})
-	return nil
-}
-
-// runWebhookTokenStatus handles --enable-token / --disable-token. Both map to the
-// same token/status endpoint. enable surfaces the plaintext token once.
-func runWebhookTokenStatus(rctx *common.RuntimeContext, enable bool) error {
-	appID, err := requireAppID(rctx.Str("app-id"))
-	if err != nil {
-		return err
-	}
-	name := strings.TrimSpace(rctx.Str("name"))
-	body := webhookTokenStatusBody(enable)
-	data, err := rctx.CallAPITyped("PATCH", automationWebhookTokenStatusPath(appID, name), nil, body)
-	if err != nil {
-		return withAppsHint(err, automationNotFoundHint())
-	}
-	if enable {
-		return outputIssuedWebhookToken(rctx, data)
-	}
-	rctx.OutFormat(map[string]interface{}{"name": name, "token_enabled": false}, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "trigger %s: bearer token disabled (irreversible; callbacks no longer require a token)\n", name)
-	})
-	return nil
-}
-
-// runWebhookTokenReset handles --reset-token. Rotates the token; old token invalidated.
-func runWebhookTokenReset(rctx *common.RuntimeContext) error {
-	appID, err := requireAppID(rctx.Str("app-id"))
-	if err != nil {
-		return err
-	}
-	name := strings.TrimSpace(rctx.Str("name"))
-	body := webhookTokenResetBody()
-	data, err := rctx.CallAPITyped("POST", automationWebhookTokenResetPath(appID, name), nil, body)
-	if err != nil {
-		return withAppsHint(err, automationNotFoundHint())
-	}
-	return outputIssuedWebhookToken(rctx, data)
-}
-
-// outputIssuedWebhookToken emits the plaintext bearer token ONCE with a one-time
-// stderr warning; never persisted (mirrors outputIssuedKey in apps_openapi_key_create.go).
-func outputIssuedWebhookToken(rctx *common.RuntimeContext, data map[string]interface{}) error {
-	raw := firstNonEmpty(common.GetString(data, "token_value"), common.GetString(data, "token"))
-	fmt.Fprintln(rctx.IO().ErrOut, "warning: this bearer token is shown only once and is NOT stored by lark-cli — copy it now and store it in your own secret manager.")
-	out := map[string]interface{}{"token_value": raw, "token_enabled": true}
-	rctx.OutFormat(out, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "bearer token: %v  (shown once)\n", raw)
-	})
-	return nil
-}

shortcuts/apps/apps_automation_webhook_test.go

@@ -1,110 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/httpmock"
-)
-
-// Flag-type identifiers used by the test flag-def map below. Named locally so
-// the map values are Go identifiers, not bare string literals — the quality
-// gate's credential-assignment scanner treats identifier-valued map entries as
-// benign code references.
-const (
-	tfString      = "string"
-	tfBool        = "bool"
-	tfStringArray = "string_array"
-)
-
-func automationUpdateFlagDefs() map[string]string {
-	return map[string]string{
-		"app-id": tfString, "name": tfString, "trigger-type": tfString, "description": tfString,
-		"cron": tfString, "timezone": tfString, "white-ip-list": tfString,
-		"table": tfString, "event": tfString, "fields": tfString,
-		"approval-code": tfString, "event-type": tfString,
-		"instance-status": tfStringArray, "task-status": tfStringArray,
-		"reset-url": tfBool, "app-env": tfString,
-		"enable-token": tfBool, "disable-token": tfBool, "reset-token": tfBool,
-	}
-}
-
-func TestWebhookResetURL_RequiresAppEnv(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "reset-url": "true"})
-	err := runWebhookURLReset(rctx)
-	assertValidationParamError(t, err, "--app-env")
-}
-
-func TestWebhookResetURL_InvalidAppEnv(t *testing.T) {
-	rctx, _, _ := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "reset-url": "true", "app-env": "prod"})
-	err := runWebhookURLReset(rctx)
-	assertValidationParamError(t, err, "--app-env")
-}
-
-func TestWebhookResetURL_PostsAppEnv(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "reset-url": "true", "app-env": "preview"})
-	reg.Register(&httpmock.Stub{
-		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/triggers/wh1/webhook/url/reset",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"preview_url": "https://new-preview"}},
-	})
-	if err := runWebhookURLReset(rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	if !strings.Contains(stdoutBuf.String(), "new-preview") {
-		t.Errorf("reset-url must return new URL: %s", stdoutBuf.String())
-	}
-}
-
-func TestWebhookEnableToken_SurfacesTokenOnce(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "enable-token": "true"})
-	reg.Register(&httpmock.Stub{
-		Method: "PATCH", URL: "/open-apis/spark/v1/apps/app_x/triggers/wh1/webhook/token/status",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"token_value": "test-token"}},
-	})
-	if err := runWebhookTokenStatus(rctx, true); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	out := stdoutBuf.String()
-	if !strings.Contains(out, "test-token") {
-		t.Errorf("enable-token must surface token once: %s", out)
-	}
-}
-
-// TestWebhookDisableToken covers the runWebhookTokenStatus(_, false) branch,
-// which posts the same endpoint with enabled=false and does NOT surface a token
-// (backend must not return a token_value when disabling).
-func TestWebhookDisableToken(t *testing.T) {
-	rctx, _, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "disable-token": "true"})
-	reg.Register(&httpmock.Stub{
-		Method: "PATCH", URL: "/open-apis/spark/v1/apps/app_x/triggers/wh1/webhook/token/status",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"token_enabled": false}},
-	})
-	if err := runWebhookTokenStatus(rctx, false); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-}
-
-// TestWebhookResetToken covers the reset-token endpoint: it must surface the
-// rotated token value once so operators can capture it.
-func TestWebhookResetToken(t *testing.T) {
-	rctx, stdoutBuf, reg := newOpenAPIKeyRCtx(t, automationUpdateFlagDefs(),
-		map[string]string{"app-id": "app_x", "name": "wh1", "reset-token": "true"})
-	reg.Register(&httpmock.Stub{
-		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/triggers/wh1/webhook/token/reset",
-		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"token_value": "test-token"}},
-	})
-	if err := runWebhookTokenReset(rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	if !strings.Contains(stdoutBuf.String(), "test-token") {
-		t.Errorf("reset-token must surface rotated token once: %s", stdoutBuf.String())
-	}
-}

shortcuts/apps/apps_role.go

@@ -1,744 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"math"
-	"strconv"
-	"strings"
-	"text/tabwriter"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-const maxRoleListScanPages = 1000
-
-// AppsRoleList lists app roles.
-var AppsRoleList = common.Shortcut{
-	Service:     appsService,
-	Command:     "+role-list",
-	Description: "List app roles",
-	Risk:        "read",
-	Tips: []string{
-		"Example: lark-cli apps +role-list --app-id <app_id>",
-		"Example: lark-cli apps +role-list --app-id <app_id> --name Admin --page-size 20",
-		"When only a role name is known, pass --name for exact matching; call +role-get only after resolving one unique role_id",
-		"With --name, the CLI scans server pages in batches of 100, then applies --page-size and --page-token to the exact local matches",
-	},
-	Scopes:    []string{"spark:app:read"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: roleAppIDRequiredDesc, Required: true},
-		{Name: "name", Desc: "filter roles by exact name"},
-		{Name: "page-size", Type: "int", Default: "20", Desc: "page size (1-100)"},
-		{Name: "page-token", Desc: "integer offset returned by the previous role-list response"},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if err := validateRoleAppID(rctx); err != nil {
-			return err
-		}
-		_, err := buildRoleListParams(rctx)
-		return err
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		// Validate already ran and called buildRoleListParams; error is impossible here.
-		params, _ := buildRoleListParams(rctx)
-		params = roleListRequestParams(params, 0)
-		return common.NewDryRunAPI().
-			GET(roleListURL(rctx)).
-			Desc("List app roles").
-			Params(params)
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		params, err := buildRoleListParams(rctx)
-		if err != nil {
-			return err
-		}
-		data, err := executeRoleList(rctx, params)
-		if err != nil {
-			return withRoleErrorHint(err, roleOperationList)
-		}
-		rctx.OutFormat(data, nil, func(w io.Writer) {
-			renderRoleListPretty(w, common.GetSlice(data, "items"))
-		})
-		return nil
-	},
-}
-
-// AppsRoleGet gets one app role.
-var AppsRoleGet = common.Shortcut{
-	Service:     appsService,
-	Command:     "+role-get",
-	Description: "Get an app role",
-	Risk:        "read",
-	Tips: []string{
-		"Example: lark-cli apps +role-get --app-id <app_id> --role-id <role_id>",
-		"--role-id is not a human-readable role name; if only a name is known, run +role-list --name <exact_name> and use its unique returned role_id before calling +role-get",
-	},
-	Scopes:    []string{"spark:app:read"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: roleAppIDRequiredDesc, Required: true},
-		{Name: "role-id", Desc: roleIDRequiredDesc, Required: true},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		return validateRoleID(rctx)
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
-			GET(roleItemURL(rctx)).
-			Desc("Get app role")
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		data, err := rctx.CallAPITyped("GET", roleItemURL(rctx), nil, nil)
-		if err != nil {
-			return withRoleErrorHint(err, roleOperationGet)
-		}
-		role, err := parseRoleDetailResponseData(data, roleID(rctx))
-		if err != nil {
-			return err
-		}
-		rctx.OutFormat(data, nil, func(w io.Writer) {
-			renderRoleGetPretty(w, role)
-		})
-		return nil
-	},
-}
-
-// AppsRoleCreate creates an app role.
-var AppsRoleCreate = common.Shortcut{
-	Service:     appsService,
-	Command:     "+role-create",
-	Description: "Create an app role",
-	Risk:        "write",
-	Tips: []string{
-		"Example: lark-cli apps +role-create --app-id <app_id> --name Admin",
-		"Example: lark-cli apps +role-create --app-id <app_id> --name Admin --description 'Can manage orders'",
-		"Example: lark-cli apps +role-create --app-id <app_id> --name Admin --role-id role_admin",
-		"The create response returns data.role; run +role-get with data.role.role_id only when independent verification is required",
-	},
-	Scopes:    []string{"spark:app:write"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: roleAppIDRequiredDesc, Required: true},
-		// Keep --name in Validate so the CLI can return the command-specific
-		// non-invention hint instead of Cobra's generic required-flag error.
-		{Name: "name", Desc: "role name (required)"},
-		{Name: "description", Desc: "role description"},
-		{Name: "role-id", Desc: "optional caller-provided role ID ([A-Za-z0-9_-]{1,64})"},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if err := validateRoleAppID(rctx); err != nil {
-			return err
-		}
-		if strings.TrimSpace(rctx.Str("name")) == "" {
-			return appsValidationParamError("--name", "--name is required").
-				WithHint("ask for the intended role name and pass it with --name; do not infer a name from --description")
-		}
-		if rctx.Changed("role-id") {
-			roleID := strings.TrimSpace(rctx.Str("role-id"))
-			if roleID == "" {
-				return appsValidationParamError("--role-id", "--role-id must not be empty when provided")
-			}
-			return validateOptionalRoleID(roleID)
-		}
-		return nil
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
-			POST(roleListURL(rctx)).
-			Desc("Create app role").
-			Body(buildRoleCreateBody(rctx))
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		data, err := rctx.CallAPITyped("POST", roleListURL(rctx), nil, buildRoleCreateBody(rctx))
-		if err != nil {
-			return withRoleErrorHint(err, roleOperationCreate)
-		}
-		expectedRoleID := ""
-		if rctx.Changed("role-id") {
-			expectedRoleID = roleID(rctx)
-		}
-		role, err := parseRoleWriteResponseData(data, expectedRoleID)
-		if err != nil {
-			return err
-		}
-		rctx.OutFormat(data, nil, func(w io.Writer) {
-			renderRoleCreatePretty(w, role)
-		})
-		return nil
-	},
-}
-
-// AppsRoleUpdate updates an app role.
-var AppsRoleUpdate = common.Shortcut{
-	Service:     appsService,
-	Command:     "+role-update",
-	Description: "Update an app role",
-	Risk:        "write",
-	Tips: []string{
-		"Example: lark-cli apps +role-update --app-id <app_id> --role-id <role_id> --name Operator",
-	},
-	Scopes:    []string{"spark:app:write"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: roleAppIDRequiredDesc, Required: true},
-		{Name: "role-id", Desc: roleIDRequiredDesc, Required: true},
-		{Name: "name", Desc: "new role name"},
-		{Name: "description", Desc: "new role description"},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if err := validateRoleID(rctx); err != nil {
-			return err
-		}
-		if rctx.Changed("name") && strings.TrimSpace(rctx.Str("name")) == "" {
-			return appsValidationParamError("--name", "--name must not be empty when provided").
-				WithHint("omit --name if only updating --description")
-		}
-		if !rctx.Changed("name") && !rctx.Changed("description") {
-			reason := "provide at least one of --name or --description"
-			return appsValidationError("at least one of --name or --description is required").
-				WithParams(
-					appsInvalidParam("--name", reason),
-					appsInvalidParam("--description", reason),
-				).
-				WithHint("provide --name, --description, or both")
-		}
-		return nil
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
-			PATCH(roleItemURL(rctx)).
-			Desc("Update app role").
-			Body(buildRoleUpdateBody(rctx))
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		data, err := rctx.CallAPITyped("PATCH", roleItemURL(rctx), nil, buildRoleUpdateBody(rctx))
-		if err != nil {
-			return withRoleErrorHint(err, roleOperationUpdate)
-		}
-		role, err := parseRoleWriteResponseData(data, roleID(rctx))
-		if err != nil {
-			return err
-		}
-		rctx.OutFormat(data, nil, func(w io.Writer) {
-			renderRoleUpdatePretty(w, role)
-		})
-		return nil
-	},
-}
-
-// AppsRoleDelete deletes an app role.
-var AppsRoleDelete = common.Shortcut{
-	Service:     appsService,
-	Command:     "+role-delete",
-	Description: "Delete an app role",
-	Risk:        "high-risk-write",
-	Tips: []string{
-		"Example: lark-cli apps +role-delete --app-id <app_id> --role-id <role_id> --yes",
-		"A delete request alone is not explicit confirmation: first show the exact app, role, current member scope, and irreversible impact; use --yes only after the user confirms that impact",
-		"When independent verification is required, use +role-list --name <exact_name> and confirm the deleted role_id is absent; a failed +role-get alone does not prove deletion",
-	},
-	Scopes:    []string{"spark:app:write"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: roleAppIDRequiredDesc, Required: true},
-		{Name: "role-id", Desc: roleIDRequiredDesc, Required: true},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		return validateRoleID(rctx)
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
-			DELETE(roleItemURL(rctx)).
-			Desc("Delete app role")
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		data, err := rctx.CallAPITyped("DELETE", roleItemURL(rctx), nil, nil)
-		if err != nil {
-			return withRoleErrorHint(err, roleOperationDelete)
-		}
-		deletedRoleID := roleID(rctx)
-		out, err := normalizeRoleDeleteData(data, deletedRoleID)
-		if err != nil {
-			return err
-		}
-		rctx.OutFormat(out, nil, func(w io.Writer) {
-			renderRoleDeletePretty(w, common.GetString(out, "role_id"))
-		})
-		return nil
-	},
-}
-
-func roleListURL(rctx *common.RuntimeContext) string {
-	appID := roleAppID(rctx)
-	return fmt.Sprintf(roleListPath, validate.EncodePathSegment(appID))
-}
-
-func roleItemURL(rctx *common.RuntimeContext) string {
-	appID := roleAppID(rctx)
-	roleID := roleID(rctx)
-	return fmt.Sprintf(roleItemPath, validate.EncodePathSegment(appID), validate.EncodePathSegment(roleID))
-}
-
-func buildRoleListParams(rctx *common.RuntimeContext) (map[string]interface{}, error) {
-	params, err := buildRolePageParams(rctx)
-	if err != nil {
-		return nil, err
-	}
-	name := strings.TrimSpace(rctx.Str("name"))
-	if rctx.Changed("name") && name == "" {
-		return nil, appsValidationParamError("--name", "--name must not be empty when provided").
-			WithHint("omit --name to list all roles, or provide the exact role name to resolve")
-	}
-	if name != "" {
-		params["name"] = name
-	}
-	return params, nil
-}
-
-// roleListRequestParams returns the query parameters for one actual backend
-// request. Exact-name lookup always starts from server offset zero and scans in
-// maximum-sized batches; the caller's limit/offset are applied to local matches.
-func roleListRequestParams(params map[string]interface{}, page int) map[string]interface{} {
-	name, _ := params["name"].(string)
-	if name == "" {
-		return params
-	}
-	return map[string]interface{}{
-		"limit":  maxRolePageSize,
-		"offset": page * maxRolePageSize,
-		"name":   name,
-	}
-}
-
-func buildRoleCreateBody(rctx *common.RuntimeContext) map[string]interface{} {
-	body := map[string]interface{}{
-		"name": strings.TrimSpace(rctx.Str("name")),
-	}
-	if rctx.Changed("description") {
-		body["description"] = strings.TrimSpace(rctx.Str("description"))
-	}
-	if rctx.Changed("role-id") {
-		if roleID := strings.TrimSpace(rctx.Str("role-id")); roleID != "" {
-			body["role_id"] = roleID
-		}
-	}
-	return body
-}
-
-func buildRoleUpdateBody(rctx *common.RuntimeContext) map[string]interface{} {
-	body := map[string]interface{}{}
-	if rctx.Changed("name") {
-		body["name"] = strings.TrimSpace(rctx.Str("name"))
-	}
-	if rctx.Changed("description") {
-		body["description"] = strings.TrimSpace(rctx.Str("description"))
-	}
-	return body
-}
-
-// executeRoleList compensates for Miaoda environments that accept the name
-// query parameter but ignore it. A name lookup scans the complete server-side
-// result set, applies exact matching locally, and then applies the CLI's
-// offset/limit contract to the filtered result.
-func executeRoleList(rctx *common.RuntimeContext, params map[string]interface{}) (map[string]interface{}, error) {
-	name, _ := params["name"].(string)
-	if name == "" {
-		data, err := rctx.CallAPITyped("GET", roleListURL(rctx), params, nil)
-		if err != nil {
-			return nil, err
-		}
-		return normalizeRoleListData(data, params)
-	}
-
-	requestedLimit := roleIntValue(params["limit"])
-	requestedOffset := roleIntValue(params["offset"])
-	allMatches := make([]interface{}, 0, requestedLimit)
-	var firstPage map[string]interface{}
-	seenRoleIDs := map[string]struct{}{}
-	seenPageSignatures := map[string]struct{}{}
-	expectedTotal := -1
-	scannedRoleCount := 0
-
-	for page := 0; ; page++ {
-		if page >= maxRoleListScanPages {
-			return nil, errs.NewInternalError(
-				errs.SubtypeInvalidResponse,
-				"role list exceeded %d pages while filtering by name",
-				maxRoleListScanPages,
-			).WithHint("retry without --name and paginate using the returned page_token")
-		}
-
-		scanParams := roleListRequestParams(params, page)
-		data, err := rctx.CallAPITyped("GET", roleListURL(rctx), scanParams, nil)
-		if err != nil {
-			return nil, err
-		}
-		if firstPage == nil {
-			firstPage = data
-		}
-		items, hasMore, total, err := parseRoleListPage(data)
-		if err != nil {
-			return nil, err
-		}
-		if expectedTotal < 0 {
-			expectedTotal = total
-		} else if total != expectedTotal {
-			return nil, roleListProgressError("role list total changed across pages while filtering by name")
-		}
-		if scannedRoleCount+len(items) > expectedTotal {
-			return nil, roleListProgressError("role list returned more roles than its total while filtering by name")
-		}
-		scannedRoleCount += len(items)
-		if hasMore && scannedRoleCount >= expectedTotal {
-			return nil, roleListProgressError("role list reported more pages after reaching its total while filtering by name")
-		}
-		if !hasMore && scannedRoleCount != expectedTotal {
-			return nil, roleListProgressError("role list ended before returning its declared total while filtering by name")
-		}
-		signature, newRoleCount, err := roleListPageProgress(items, seenRoleIDs)
-		if err != nil {
-			return nil, err
-		}
-		if newRoleCount != len(items) {
-			return nil, roleListProgressError("role list repeated roles across pages while filtering by name")
-		}
-		if _, duplicate := seenPageSignatures[signature]; duplicate {
-			return nil, roleListProgressError("role list repeated a page while filtering by name")
-		}
-		seenPageSignatures[signature] = struct{}{}
-		if hasMore && (len(items) == 0 || newRoleCount == 0) {
-			return nil, roleListProgressError("role list reported more pages without returning new roles")
-		}
-		for _, item := range items {
-			role, ok := item.(map[string]interface{})
-			if ok && common.GetString(role, "name") == name {
-				allMatches = append(allMatches, item)
-			}
-		}
-		if !hasMore {
-			break
-		}
-	}
-
-	if firstPage == nil {
-		firstPage = map[string]interface{}{}
-	}
-	return normalizeFilteredRoleListData(firstPage, allMatches, requestedOffset, requestedLimit), nil
-}
-
-func normalizeFilteredRoleListData(data map[string]interface{}, matches []interface{}, offset, limit int) map[string]interface{} {
-	out := map[string]interface{}{}
-	for k, v := range data {
-		out[k] = v
-	}
-
-	start := offset
-	if start > len(matches) {
-		start = len(matches)
-	}
-	end := start + limit
-	if end > len(matches) {
-		end = len(matches)
-	}
-	hasMore := end < len(matches)
-	items := append([]interface{}(nil), matches[start:end]...)
-	if items == nil {
-		items = []interface{}{}
-	}
-	out["items"] = items
-	out["has_more"] = hasMore
-	out["page_token"] = roleNextPageToken(start, limit, hasMore)
-	out["total"] = len(matches)
-	return out
-}
-
-func normalizeRoleListData(data map[string]interface{}, params map[string]interface{}) (map[string]interface{}, error) {
-	items, hasMore, total, err := parseRoleListPage(data)
-	if err != nil {
-		return nil, err
-	}
-	out := map[string]interface{}{}
-	for k, v := range data {
-		out[k] = v
-	}
-
-	limit := roleIntValue(params["limit"])
-	offset := roleIntValue(params["offset"])
-
-	out["items"] = items
-	out["has_more"] = hasMore
-	out["page_token"] = roleNextPageToken(offset, limit, hasMore)
-	out["total"] = total
-	return out, nil
-}
-
-func parseRoleListPage(data map[string]interface{}) ([]interface{}, bool, int, error) {
-	rawItems, hasItems := data["items"]
-	items, ok := rawItems.([]interface{})
-	if !hasItems || !ok {
-		return nil, false, 0, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"role list response field items must be an array",
-		).WithHint("retry the read; do not treat a missing or malformed role list as empty")
-	}
-	if err := validateRoleCollection(items, "role list response field items"); err != nil {
-		return nil, false, 0, err
-	}
-	rawHasMore, hasHasMore := data["has_more"]
-	hasMore, ok := rawHasMore.(bool)
-	if !hasHasMore || !ok {
-		return nil, false, 0, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"role list response field has_more must be a boolean",
-		).WithHint("retry the read; pagination is incomplete without a valid has_more value")
-	}
-	total, ok := nonNegativeRoleInteger(data["total"])
-	if _, exists := data["total"]; !exists || !ok {
-		return nil, false, 0, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"role list response field total must be a non-negative integer",
-		).WithHint("retry the read; do not infer a role count from a missing or malformed total value")
-	}
-	return items, hasMore, total, nil
-}
-
-func roleListPageProgress(items []interface{}, seenRoleIDs map[string]struct{}) (string, int, error) {
-	roleIDs := make([]string, 0, len(items))
-	newRoleCount := 0
-	for index, item := range items {
-		_, roleID, err := roleCollectionItem(item, "role list response field items", index)
-		if err != nil {
-			return "", 0, err
-		}
-		roleIDs = append(roleIDs, roleID)
-		if _, seen := seenRoleIDs[roleID]; !seen {
-			seenRoleIDs[roleID] = struct{}{}
-			newRoleCount++
-		}
-	}
-	return strings.Join(roleIDs, "\x00"), newRoleCount, nil
-}
-
-func nonNegativeRoleInteger(value interface{}) (int, bool) {
-	maxInt := uint64(^uint(0) >> 1)
-	toInt := func(value int64) (int, bool) {
-		if value < 0 || uint64(value) > maxInt {
-			return 0, false
-		}
-		return int(value), true
-	}
-
-	switch value := value.(type) {
-	case int:
-		if value < 0 {
-			return 0, false
-		}
-		return value, true
-	case int64:
-		return toInt(value)
-	case float64:
-		maxIntExclusive := math.Ldexp(1, strconv.IntSize-1)
-		if math.IsNaN(value) || math.IsInf(value, 0) || value < 0 || math.Trunc(value) != value || value >= maxIntExclusive {
-			return 0, false
-		}
-		return int(value), true
-	case json.Number:
-		parsed, err := value.Int64()
-		if err != nil {
-			return 0, false
-		}
-		return toInt(parsed)
-	case string:
-		if value == "" || strings.IndexFunc(value, func(r rune) bool {
-			return r < '0' || r > '9'
-		}) >= 0 {
-			return 0, false
-		}
-		parsed, err := strconv.ParseUint(value, 10, strconv.IntSize)
-		if err != nil || parsed > maxInt {
-			return 0, false
-		}
-		return int(parsed), true
-	default:
-		return 0, false
-	}
-}
-
-func roleListProgressError(message string) error {
-	return errs.NewInternalError(errs.SubtypeInvalidResponse, message).
-		WithHint("retry without --name and paginate manually; do not continue an incomplete exact-name scan")
-}
-
-func normalizeRoleDeleteData(data map[string]interface{}, requestedRoleID string) (map[string]interface{}, error) {
-	if data == nil {
-		return nil, invalidRoleDeleteResponse("role delete response data must be an object")
-	}
-	if len(data) == 0 {
-		return map[string]interface{}{
-			"role_id": requestedRoleID,
-			"deleted": true,
-		}, nil
-	}
-
-	out := map[string]interface{}{}
-	for k, v := range data {
-		out[k] = v
-	}
-	rawRoleID, ok := out["role_id"]
-	if !ok {
-		return nil, invalidRoleDeleteResponse("role delete response is missing role_id")
-	}
-	actualRoleID, stringOK := rawRoleID.(string)
-	if !stringOK || actualRoleID != requestedRoleID {
-		return nil, invalidRoleDeleteResponse(
-			"role delete response role_id does not match requested role_id %q",
-			requestedRoleID,
-		)
-	}
-	rawDeleted, ok := out["deleted"]
-	if !ok {
-		return nil, invalidRoleDeleteResponse("role delete response is missing deleted")
-	}
-	deleted, boolOK := rawDeleted.(bool)
-	if !boolOK || !deleted {
-		return nil, invalidRoleDeleteResponse("role delete response did not acknowledge deletion")
-	}
-	return out, nil
-}
-
-type roleResponseData struct {
-	RoleID      string
-	Name        string
-	Description string
-}
-
-func parseRoleDetailResponseData(data map[string]interface{}, expectedRoleID string) (roleResponseData, error) {
-	return parseRoleResponseData(data, expectedRoleID, true)
-}
-
-func parseRoleWriteResponseData(data map[string]interface{}, expectedRoleID string) (roleResponseData, error) {
-	return parseRoleResponseData(data, expectedRoleID, false)
-}
-
-func parseRoleResponseData(data map[string]interface{}, expectedRoleID string, requireName bool) (roleResponseData, error) {
-	if data == nil {
-		return roleResponseData{}, invalidRoleResponse("role response data must be an object")
-	}
-	rawRole, exists := data["role"]
-	role, ok := rawRole.(map[string]interface{})
-	if !exists || !ok || role == nil {
-		return roleResponseData{}, invalidRoleResponse("role response field role must be an object")
-	}
-	rawRoleID, exists := role["role_id"]
-	roleID, ok := rawRoleID.(string)
-	roleID = strings.TrimSpace(roleID)
-	if !exists || !ok || roleID == "" {
-		return roleResponseData{}, invalidRoleResponse("role response field role.role_id must be a non-empty string")
-	}
-	if expectedRoleID != "" && roleID != expectedRoleID {
-		return roleResponseData{}, invalidRoleResponse(
-			"role response role_id %q does not match requested role_id %q",
-			roleID,
-			expectedRoleID,
-		)
-	}
-	rawName, nameExists := role["name"]
-	name, nameOK := rawName.(string)
-	name = strings.TrimSpace(name)
-	if requireName && !nameExists {
-		return roleResponseData{}, invalidRoleResponse("role response field role.name must be a non-empty string")
-	}
-	if nameExists && (!nameOK || name == "") {
-		return roleResponseData{}, invalidRoleResponse("role response field role.name must be a non-empty string")
-	}
-	rawDescription, descriptionExists := role["description"]
-	description, descriptionOK := rawDescription.(string)
-	if descriptionExists && !descriptionOK {
-		return roleResponseData{}, invalidRoleResponse("role response field role.description must be a string")
-	}
-	return roleResponseData{RoleID: roleID, Name: name, Description: description}, nil
-}
-
-func invalidRoleResponse(message string, args ...interface{}) error {
-	return errs.NewInternalError(errs.SubtypeInvalidResponse, message, args...).
-		WithHint("retry the role read; do not treat a missing or malformed role as a successful result")
-}
-
-func invalidRoleDeleteResponse(message string, args ...interface{}) error {
-	return errs.NewInternalError(errs.SubtypeInvalidResponse, message, args...).
-		WithHint("do not claim deletion; verify the target role with +role-list --name <exact_name>")
-}
-
-func roleIntValue(value interface{}) int {
-	switch v := value.(type) {
-	case int:
-		return v
-	case int64:
-		return int(v)
-	case float64:
-		return int(v)
-	case json.Number:
-		i, err := strconv.Atoi(v.String())
-		if err == nil {
-			return i
-		}
-	case string:
-		i, err := strconv.Atoi(strings.TrimSpace(v))
-		if err == nil {
-			return i
-		}
-	}
-	return 0
-}
-
-func renderRoleCreatePretty(w io.Writer, role roleResponseData) {
-	fmt.Fprintf(w, "Created role %s\n", roleDisplayValue(role.RoleID))
-}
-
-func renderRoleGetPretty(w io.Writer, role roleResponseData) {
-	renderRoleDetailPretty(w, role)
-}
-
-func renderRoleUpdatePretty(w io.Writer, role roleResponseData) {
-	fmt.Fprintf(w, "Updated role %s\n", roleDisplayValue(role.RoleID))
-}
-
-func renderRoleDeletePretty(w io.Writer, roleID string) {
-	fmt.Fprintf(w, "Deleted role %s\n", roleDisplayValue(roleID))
-}
-
-func renderRoleDetailPretty(w io.Writer, role roleResponseData) {
-	fmt.Fprintf(w, "role_id: %s\n", roleDisplayValue(role.RoleID))
-	fmt.Fprintf(w, "name: %s\n", roleDisplayValue(role.Name))
-	fmt.Fprintf(w, "description: %s\n", roleDisplayValue(role.Description))
-}
-
-func renderRoleListPretty(w io.Writer, items []interface{}) {
-	tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
-	fmt.Fprintln(tw, "ROLE ID\tNAME\tDESCRIPTION")
-	for _, item := range items {
-		role, ok := item.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		fmt.Fprintf(tw, "%s\t%s\t%s\n",
-			roleDisplayValue(firstNonEmpty(common.GetString(role, "role_id"), common.GetString(role, "id"))),
-			roleDisplayValue(common.GetString(role, "name")),
-			roleDisplayValue(common.GetString(role, "description")))
-	}
-	_ = tw.Flush()
-}

shortcuts/apps/apps_role_common.go

@@ -1,490 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"fmt"
-	"regexp"
-	"strconv"
-	"strings"
-	"unicode"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/errclass"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-const (
-	roleListPath         = apiBasePath + "/apps/%s/roles"
-	roleItemPath         = apiBasePath + "/apps/%s/roles/%s"
-	roleMemberListPath   = apiBasePath + "/apps/%s/roles/%s/member_list"
-	roleMemberAddPath    = apiBasePath + "/apps/%s/roles/%s/member_add"
-	roleMemberRemovePath = apiBasePath + "/apps/%s/roles/%s/member_remove"
-	roleMatchListPath    = apiBasePath + "/apps/%s/user_role_list"
-	defaultRolePageSize  = 20
-	maxRolePageSize      = 100
-	maxRoleMembers       = 100
-
-	roleErrInvalidParameters       = 3340001
-	roleErrUserLimitExceeded       = 3344027
-	roleErrDepartmentLimitExceeded = 3344028
-	roleErrChatLimitExceeded       = 3344029
-	roleErrAdminRequired           = 3344030
-	roleErrManagerRequired         = 3344031
-	roleErrInvalidRoleID           = 3344034
-	roleErrRoleNotFound            = 3344035
-	roleErrRoleAlreadyExists       = 3344036
-	roleErrRoleLimitExceeded       = 3344037
-	roleErrInvalidRoleName         = 3344038
-	roleErrInvalidRoleDescription  = 3344039
-	roleErrUnsupportedMemberType   = 3344040
-	roleErrInvalidMemberID         = 3344041
-)
-
-var optionalRoleIDPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`)
-
-const (
-	roleAppHint    = "verify --app-id is a Miaoda app_id you can access; list apps with `lark-cli apps +list`"
-	roleItemHint   = "verify --role-id belongs to the app; if you only know a role name, resolve it with `lark-cli apps +role-list --app-id <app_id> --name <exact_name>` and use the unique returned role_id"
-	roleCreateHint = "verify --app-id and role fields; omit --role-id unless you need a caller-provided role ID"
-	roleMemberHint = "verify --role-id and member IDs; use user open_id, open_department_id, or open_chat_id values"
-	roleMatchHint  = "use --user-id with a user open_id; do not pass role_id or enumerate roles manually"
-
-	roleAppIDRequiredDesc  = "Miaoda app ID (required; app_...; use apps +list to find it)"
-	roleIDRequiredDesc     = "role ID (required; [A-Za-z0-9_-]{1,64}; use role-list to find it)"
-	roleUserIDRequiredDesc = "user open ID (required; ou_...; do not pass a role ID, name, or email)"
-)
-
-type roleErrorOperation uint8
-
-const (
-	roleOperationList roleErrorOperation = iota
-	roleOperationGet
-	roleOperationCreate
-	roleOperationUpdate
-	roleOperationDelete
-	roleOperationMemberList
-	roleOperationMemberAdd
-	roleOperationMemberRemove
-	roleOperationMatchList
-)
-
-type roleMemberGroups struct {
-	Users       []string `json:"users"`
-	Departments []string `json:"departments"`
-	Chats       []string `json:"chats"`
-}
-
-type roleMemberKind struct {
-	memberType string
-	dataKey    string
-	flagName   string
-	prefix     string
-}
-
-var roleMemberKinds = []roleMemberKind{
-	{memberType: "user", dataKey: "users", flagName: "--users", prefix: "ou_"},
-	{memberType: "department", dataKey: "departments", flagName: "--departments", prefix: "od-"},
-	{memberType: "chat", dataKey: "chats", flagName: "--chats", prefix: "oc_"},
-}
-
-func roleAppID(rctx *common.RuntimeContext) string {
-	return strings.TrimSpace(rctx.Str("app-id"))
-}
-
-func roleID(rctx *common.RuntimeContext) string {
-	return strings.TrimSpace(rctx.Str("role-id"))
-}
-
-func validateRoleAppID(rctx *common.RuntimeContext) error {
-	appID := roleAppID(rctx)
-	if appID == "" {
-		return appsValidationParamError("--app-id", "--app-id is required").
-			WithHint("list your apps with `lark-cli apps +list`")
-	}
-	if strings.HasPrefix(appID, "cli_") {
-		return appsValidationParamError("--app-id", "--app-id must be a Miaoda app_id, not a Lark app_id").
-			WithHint("pass the app_... value from `lark-cli apps +list`, not the cli_... credential app id")
-	}
-	if !strings.HasPrefix(appID, "app_") || len(appID) == len("app_") {
-		return appsValidationParamError("--app-id", "--app-id must be a Miaoda app_id starting with app_").
-			WithHint("list Miaoda apps with `lark-cli apps +list`, then pass the returned app_id")
-	}
-	// app-id must not contain forward slashes (apps are identified by app_xxx IDs).
-	for _, r := range appID {
-		if r == '/' || r == '\\' || unicode.IsSpace(r) || unicode.IsControl(r) {
-			return appsValidationParamError("--app-id", "--app-id must not contain slashes, whitespace, or control characters")
-		}
-	}
-	// Defense-in-depth: block path traversal and URL metacharacters.
-	if err := validateRolePathSegmentSafe(appID, "--app-id"); err != nil {
-		return err
-	}
-	return nil
-}
-
-func validateRoleID(rctx *common.RuntimeContext) error {
-	if err := validateRoleAppID(rctx); err != nil {
-		return err
-	}
-	roleID := roleID(rctx)
-	if roleID == "" {
-		return appsValidationParamError("--role-id", "--role-id is required").
-			WithHint("list roles with `lark-cli apps +role-list --app-id <app_id>`")
-	}
-	return validateExistingRoleIDValue(roleID)
-}
-
-// validateRolePathSegmentSafe rejects path-traversal segments ("..") and URL
-// metacharacters (? # %) in values interpolated into a URL path, providing
-// defense-in-depth alongside validate.EncodePathSegment.
-func validateRolePathSegmentSafe(value, flagName string) error {
-	for _, seg := range strings.Split(value, "/") {
-		if seg == ".." {
-			return appsValidationParamError(flagName, "%s must not contain '..' path traversal", flagName).
-				WithHint("provide a valid %s without path traversal", flagName)
-		}
-	}
-	if strings.ContainsAny(value, "?#%") {
-		return appsValidationParamError(flagName, "%s contains invalid URL characters (?, #, %%)", flagName).
-			WithHint("provide a valid %s without URL metacharacters", flagName)
-	}
-	return nil
-}
-
-func validateOptionalRoleID(roleID string) error {
-	roleID = strings.TrimSpace(roleID)
-	if roleID == "" {
-		return nil
-	}
-	return validateCreateRoleIDValue(roleID)
-}
-
-func validateCreateRoleIDValue(roleID string) error {
-	if !optionalRoleIDPattern.MatchString(roleID) {
-		return appsValidationParamError("--role-id", "--role-id must match [A-Za-z0-9_-]{1,64}").
-			WithHint("omit --role-id to let the server generate one")
-	}
-	return nil
-}
-
-func validateExistingRoleIDValue(roleID string) error {
-	if !optionalRoleIDPattern.MatchString(roleID) {
-		return appsValidationParamError("--role-id", "--role-id must match [A-Za-z0-9_-]{1,64}").
-			WithHint("resolve the role with `lark-cli apps +role-list --app-id <app_id> --name <exact_name>` and pass its role_id")
-	}
-	return nil
-}
-
-func buildRolePageParams(rctx *common.RuntimeContext) (map[string]interface{}, error) {
-	limit := defaultRolePageSize
-	if rctx.Changed("page-size") {
-		limit = rctx.Int("page-size")
-	}
-	if limit < 1 || limit > maxRolePageSize {
-		return nil, appsValidationParamError("--page-size", "--page-size must be between 1 and %d", maxRolePageSize).
-			WithHint("use --page-size between 1 and 100")
-	}
-
-	offset := 0
-	pageToken := strings.TrimSpace(rctx.Str("page-token"))
-	if pageToken != "" {
-		parsedOffset, err := strconv.Atoi(pageToken)
-		if err != nil || parsedOffset < 0 {
-			return nil, appsValidationParamError("--page-token", "--page-token must be a non-negative integer offset").
-				WithHint("reuse page_token from the previous +role-list response")
-		}
-		offset = parsedOffset
-	}
-
-	return map[string]interface{}{
-		"limit":  limit,
-		"offset": offset,
-	}, nil
-}
-
-func roleNextPageToken(offset, limit int, hasMore bool) string {
-	if !hasMore {
-		return ""
-	}
-	return strconv.Itoa(offset + limit)
-}
-
-func splitRoleMemberCSV(s, flagName string) ([]string, error) {
-	parts := strings.Split(s, ",")
-	values := make([]string, 0, len(parts))
-	for _, part := range parts {
-		value := strings.TrimSpace(part)
-		if value == "" {
-			continue
-		}
-		// Reject values containing whitespace, control characters, or URL metacharacters
-		// (member IDs are open_id/open_department_id/open_chat_id which are safe tokens).
-		if err := validateMemberID(value, flagName); err != nil {
-			return nil, err
-		}
-		values = append(values, value)
-	}
-	return values, nil
-}
-
-// validateMemberID rejects values containing characters that are invalid in
-// open_id / open_department_id / open_chat_id tokens (whitespace, controls, URL metacharacters).
-func validateMemberID(value, flagName string) error {
-	if err := validateMemberIDPrefix(value, flagName); err != nil {
-		return err
-	}
-	for _, r := range value {
-		if unicode.IsSpace(r) || unicode.IsControl(r) {
-			return appsValidationParamError(flagName, "member IDs must not contain whitespace or control characters").
-				WithHint("pass comma-separated open_id/open_department_id/open_chat_id values without spaces")
-		}
-		if r == '?' || r == '#' || r == '%' || r == '/' || r == '\\' {
-			return appsValidationParamError(flagName, "member IDs must not contain URL metacharacters (?, #, %, /, \\)").
-				WithHint("pass comma-separated open_id/open_department_id/open_chat_id values without URL characters")
-		}
-	}
-	return nil
-}
-
-func validateMemberIDPrefix(value, flagName string) error {
-	kind, ok := roleMemberKindForFlag(flagName)
-	if !ok {
-		return nil
-	}
-	if !strings.HasPrefix(value, kind.prefix) || len(value) == len(kind.prefix) {
-		return appsValidationParamError(flagName, "%s must use %s IDs", flagName, kind.prefix).
-			WithHint("resolve names or emails to open IDs before calling role member commands")
-	}
-	return nil
-}
-
-func roleMemberKindForFlag(flagName string) (roleMemberKind, bool) {
-	if flagName == "--user-id" {
-		flagName = "--users"
-	}
-	for _, kind := range roleMemberKinds {
-		if kind.flagName == flagName {
-			return kind, true
-		}
-	}
-	return roleMemberKind{}, false
-}
-
-func roleMemberKindForType(memberType string) (roleMemberKind, bool) {
-	for _, kind := range roleMemberKinds {
-		if kind.memberType == memberType {
-			return kind, true
-		}
-	}
-	return roleMemberKind{}, false
-}
-
-func roleDisplayValue(value string) string {
-	value = validate.SanitizeForTerminal(value)
-	value = strings.NewReplacer("\n", " ", "\t", " ").Replace(value)
-	return strings.TrimSpace(value)
-}
-
-// withRoleErrorHint refines documented Spark role errors with command-specific
-// recovery while preserving the typed error, numeric code, log_id, and any
-// server-provided detail. Unknown codes retain the existing Apps fallback.
-func withRoleErrorHint(err error, operation roleErrorOperation) error {
-	if err == nil {
-		return nil
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		return err
-	}
-	hint := roleErrorHint(problem.Code, operation)
-	if hint == "" {
-		return withAppsHint(err, roleFallbackHint(operation))
-	}
-
-	existing := strings.TrimSpace(problem.Hint)
-	canonicalAPIHint := strings.TrimSpace(errclass.APIHint(problem.Subtype))
-	switch {
-	case existing == "", existing == canonicalAPIHint:
-		problem.Hint = hint
-	case !strings.Contains(existing, hint):
-		problem.Hint = existing + "; " + hint
-	}
-	return err
-}
-
-func roleFallbackHint(operation roleErrorOperation) string {
-	switch operation {
-	case roleOperationList:
-		return roleAppHint
-	case roleOperationCreate:
-		return roleCreateHint
-	case roleOperationMemberList, roleOperationMemberAdd, roleOperationMemberRemove:
-		return roleMemberHint
-	case roleOperationMatchList:
-		return roleMatchHint
-	default:
-		return roleItemHint
-	}
-}
-
-func roleErrorHint(code int, operation roleErrorOperation) string {
-	switch code {
-	case roleErrInvalidParameters:
-		return roleFallbackHint(operation)
-	case roleErrAdminRequired:
-		return "ask an app administrator to perform this operation or grant the calling user app-administrator access"
-	case roleErrManagerRequired:
-		return "ask an app administrator or app developer to perform this operation, or grant the calling user app-management access"
-	case roleErrInvalidRoleID:
-		if operation == roleOperationCreate {
-			return "omit --role-id to let the server generate one, or provide a role ID accepted by the role service"
-		}
-	case roleErrRoleNotFound:
-		if operation == roleOperationMatchList {
-			return "list the app's current roles and retry; role data used for this match may no longer be valid"
-		}
-		return roleItemHint
-	case roleErrRoleAlreadyExists:
-		if operation == roleOperationCreate {
-			return "choose a different --role-id or omit --role-id to let the server generate one"
-		}
-	case roleErrRoleLimitExceeded:
-		if operation == roleOperationCreate {
-			return "delete an unused app role before creating another role"
-		}
-	case roleErrInvalidRoleName:
-		if operation == roleOperationCreate || operation == roleOperationUpdate {
-			return "adjust --name to a non-empty value accepted by the role service"
-		}
-	case roleErrInvalidRoleDescription:
-		if operation == roleOperationCreate || operation == roleOperationUpdate {
-			return "adjust --description to a value accepted by the role service"
-		}
-	case roleErrUnsupportedMemberType:
-		if operation == roleOperationMemberList {
-			return "use --member-type user, department, or chat, or omit --member-type to list all member types"
-		}
-	case roleErrInvalidMemberID:
-		if operation == roleOperationMatchList {
-			return "resolve the target user to an open_id and retry with --user-id <open_id>"
-		}
-		if operation == roleOperationMemberAdd || operation == roleOperationMemberRemove {
-			return roleMemberHint
-		}
-	case roleErrUserLimitExceeded:
-		if operation == roleOperationMemberAdd {
-			return "reduce the users being added with --users, or remove unused user members before retrying"
-		}
-	case roleErrDepartmentLimitExceeded:
-		if operation == roleOperationMemberAdd {
-			return "reduce the departments being added with --departments, or remove unused department members before retrying"
-		}
-	case roleErrChatLimitExceeded:
-		if operation == roleOperationMemberAdd {
-			return "reduce the chats being added with --chats, or remove unused chat members before retrying"
-		}
-	}
-	return ""
-}
-
-func roleCollectionItem(item interface{}, collection string, index int) (map[string]interface{}, string, error) {
-	role, ok := item.(map[string]interface{})
-	if !ok {
-		return nil, "", invalidRoleCollectionResponse("%s item %d must be an object", collection, index)
-	}
-	rawRoleID, exists := role["role_id"]
-	roleID, stringOK := rawRoleID.(string)
-	roleID = strings.TrimSpace(roleID)
-	if !exists || !stringOK || roleID == "" {
-		return nil, "", invalidRoleCollectionResponse("%s item %d must contain a non-empty string role_id", collection, index)
-	}
-	rawName, exists := role["name"]
-	name, stringOK := rawName.(string)
-	if !exists || !stringOK || strings.TrimSpace(name) == "" {
-		return nil, "", invalidRoleCollectionResponse("%s item %d must contain a non-empty string name", collection, index)
-	}
-	return role, roleID, nil
-}
-
-func validateRoleCollection(items []interface{}, collection string) error {
-	for index, item := range items {
-		if _, _, err := roleCollectionItem(item, collection, index); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-func invalidRoleCollectionResponse(format string, args ...interface{}) error {
-	return errs.NewInternalError(errs.SubtypeInvalidResponse, format, args...).
-		WithHint("retry the read; do not treat missing or malformed role data as an empty or complete result")
-}
-
-func buildRoleMemberGroups(usersCSV, departmentsCSV, chatsCSV string) (roleMemberGroups, error) {
-	users, err := splitRoleMemberCSV(usersCSV, "--users")
-	if err != nil {
-		return roleMemberGroups{}, err
-	}
-	departments, err := splitRoleMemberCSV(departmentsCSV, "--departments")
-	if err != nil {
-		return roleMemberGroups{}, err
-	}
-	chats, err := splitRoleMemberCSV(chatsCSV, "--chats")
-	if err != nil {
-		return roleMemberGroups{}, err
-	}
-	groups := roleMemberGroups{
-		Users:       users,
-		Departments: departments,
-		Chats:       chats,
-	}
-	total := len(groups.Users) + len(groups.Departments) + len(groups.Chats)
-	if total == 0 {
-		reason := "provide at least one of --users, --departments, or --chats"
-		return groups, appsValidationError("at least one of --users, --departments, or --chats is required").
-			WithParams(
-				appsInvalidParam("--users", reason),
-				appsInvalidParam("--departments", reason),
-				appsInvalidParam("--chats", reason),
-			).
-			WithHint("resolve names to IDs first, then pass --users open_id, --departments open_department_id, or --chats open_chat_id")
-	}
-	if total > maxRoleMembers {
-		return groups, appsValidationError("role members cannot exceed %d", maxRoleMembers).
-			WithParams(roleMemberLimitParams(groups)...).
-			WithHint(fmt.Sprintf("reduce the atomic request to at most %d members; the CLI does not split member writes automatically", maxRoleMembers))
-	}
-	return groups, nil
-}
-
-func buildRoleMemberBody(groups roleMemberGroups) map[string]interface{} {
-	body := map[string]interface{}{}
-	if len(groups.Users) > 0 {
-		body["users"] = groups.Users
-	}
-	if len(groups.Departments) > 0 {
-		body["departments"] = groups.Departments
-	}
-	if len(groups.Chats) > 0 {
-		body["chats"] = groups.Chats
-	}
-	return body
-}
-
-func roleMemberLimitParams(groups roleMemberGroups) []errs.InvalidParam {
-	reason := fmt.Sprintf("combined role member count exceeds %d", maxRoleMembers)
-	params := make([]errs.InvalidParam, 0, len(roleMemberKinds))
-	if len(groups.Users) > 0 {
-		params = append(params, appsInvalidParam("--users", reason))
-	}
-	if len(groups.Departments) > 0 {
-		params = append(params, appsInvalidParam("--departments", reason))
-	}
-	if len(groups.Chats) > 0 {
-		params = append(params, appsInvalidParam("--chats", reason))
-	}
-	return params
-}

shortcuts/apps/apps_role_common_test.go

@@ -1,447 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/errclass"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/shortcuts/common"
-	"github.com/spf13/cobra"
-)
-
-func newRoleRCtx(t *testing.T, flagDefs map[string]string, flags map[string]string) (*common.RuntimeContext, *bytes.Buffer, *httpmock.Registry) {
-	t.Helper()
-	cfg := &core.CliConfig{
-		AppID:      "test-app-" + strings.ToLower(t.Name()),
-		AppSecret:  "test-secret",
-		Brand:      core.BrandFeishu,
-		UserOpenId: "ou_test",
-	}
-	factory, stdoutBuf, _, reg := cmdutil.TestFactory(t, cfg)
-	cmd := &cobra.Command{Use: "test-role"}
-	cmd.SetContext(context.Background())
-	for name, typ := range flagDefs {
-		switch typ {
-		case "bool":
-			cmd.Flags().Bool(name, false, "")
-		case "int":
-			cmd.Flags().Int(name, 0, "")
-		case "string_array":
-			cmd.Flags().StringArray(name, nil, "")
-		default:
-			cmd.Flags().String(name, "", "")
-		}
-	}
-	for name, val := range flags {
-		if err := cmd.Flags().Set(name, val); err != nil {
-			t.Fatalf("set flag %q = %q: %v", name, val, err)
-		}
-	}
-	rctx := common.TestNewRuntimeContextForAPI(context.Background(), cmd, cfg, factory, core.AsUser)
-	return rctx, stdoutBuf, reg
-}
-
-func assertRoleValidationParam(t *testing.T, err error, param string) *errs.Problem {
-	t.Helper()
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("err = %#v, want typed problem", err)
-	}
-	if problem.Category != errs.CategoryValidation {
-		t.Fatalf("category = %q, want validation", problem.Category)
-	}
-	if problem.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype = %q, want invalid_argument", problem.Subtype)
-	}
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) {
-		t.Fatalf("err = %#v, want validation error", err)
-	}
-	if validation.Param != param {
-		t.Fatalf("param = %q, want %s", validation.Param, param)
-	}
-	return problem
-}
-
-func assertRoleValidationParams(t *testing.T, err error, params ...string) *errs.Problem {
-	t.Helper()
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("err = %#v, want typed problem", err)
-	}
-	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("problem = %+v, want validation/invalid_argument", problem)
-	}
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) {
-		t.Fatalf("err = %#v, want validation error", err)
-	}
-	if validation.Param != "" {
-		t.Fatalf("param = %q, want omitted for multi-parameter constraint", validation.Param)
-	}
-	if len(validation.Params) != len(params) {
-		t.Fatalf("params = %#v, want %v", validation.Params, params)
-	}
-	for index, want := range params {
-		if validation.Params[index].Name != want || validation.Params[index].Reason == "" {
-			t.Fatalf("params[%d] = %#v, want name=%q with a reason", index, validation.Params[index], want)
-		}
-	}
-	return problem
-}
-
-func TestBuildRolePageParams_DefaultAndChanged(t *testing.T) {
-	rctx, _, _ := newRoleRCtx(t, map[string]string{
-		"page-size":  "int",
-		"page-token": "string",
-	}, map[string]string{})
-	params, err := buildRolePageParams(rctx)
-	if err != nil {
-		t.Fatalf("buildRolePageParams() = %v", err)
-	}
-	if params["limit"] != defaultRolePageSize || params["offset"] != 0 {
-		t.Fatalf("params = %#v, want limit=%d offset=0", params, defaultRolePageSize)
-	}
-
-	rctx, _, _ = newRoleRCtx(t, map[string]string{
-		"page-size":  "int",
-		"page-token": "string",
-	}, map[string]string{"page-size": "20", "page-token": "40"})
-	params, err = buildRolePageParams(rctx)
-	if err != nil {
-		t.Fatalf("buildRolePageParams(changed) = %v", err)
-	}
-	if params["limit"] != 20 || params["offset"] != 40 {
-		t.Fatalf("params = %#v, want limit=20 offset=40", params)
-	}
-}
-
-func TestBuildRolePageParams_RejectsInvalidToken(t *testing.T) {
-	rctx, _, _ := newRoleRCtx(t, map[string]string{
-		"page-size":  "int",
-		"page-token": "string",
-	}, map[string]string{"page-token": "abc"})
-	_, err := buildRolePageParams(rctx)
-	assertRoleValidationParam(t, err, "--page-token")
-}
-
-func TestBuildRolePageParams_RejectsPageSizeOverMax(t *testing.T) {
-	rctx, _, _ := newRoleRCtx(t, map[string]string{
-		"page-size":  "int",
-		"page-token": "string",
-	}, map[string]string{"page-size": "101"})
-	_, err := buildRolePageParams(rctx)
-	assertRoleValidationParam(t, err, "--page-size")
-}
-
-func TestValidateOptionalRoleID(t *testing.T) {
-	for _, good := range []string{"", " role_001 ", "Role-ABC", "abc123", strings.Repeat("a", 64)} {
-		if err := validateOptionalRoleID(good); err != nil {
-			t.Fatalf("validateOptionalRoleID(%q) = %v", good, err)
-		}
-	}
-	for _, bad := range []string{"bad/role", "bad role", strings.Repeat("a", 65)} {
-		err := validateOptionalRoleID(bad)
-		problem := assertRoleValidationParam(t, err, "--role-id")
-		if !strings.Contains(problem.Hint, "omit --role-id") {
-			t.Fatalf("hint = %q, want create-specific omit guidance", problem.Hint)
-		}
-	}
-}
-
-func TestRoleFlagHelpersTrim(t *testing.T) {
-	rctx, _, _ := newRoleRCtx(t, map[string]string{
-		"app-id":  "string",
-		"role-id": "string",
-	}, map[string]string{"app-id": " app_1 ", "role-id": " role_1 "})
-	if got := roleAppID(rctx); got != "app_1" {
-		t.Fatalf("roleAppID() = %q, want app_1", got)
-	}
-	if got := roleID(rctx); got != "role_1" {
-		t.Fatalf("roleID() = %q, want role_1", got)
-	}
-	if err := validateRoleID(rctx); err != nil {
-		t.Fatalf("validateRoleID() = %v, want nil", err)
-	}
-}
-
-func TestValidateRoleAppIDRejectsEmpty(t *testing.T) {
-	rctx, _, _ := newRoleRCtx(t, map[string]string{
-		"app-id": "string",
-	}, map[string]string{})
-	problem := assertRoleValidationParam(t, validateRoleAppID(rctx), "--app-id")
-	if problem.Message != "--app-id is required" {
-		t.Fatalf("message = %q, want --app-id is required", problem.Message)
-	}
-	if problem.Hint == "" {
-		t.Fatalf("hint is empty, want recovery guidance")
-	}
-}
-
-func TestValidateRoleAppIDRejectsPathSegmentUnsafeChars(t *testing.T) {
-	for _, appID := range []string{"app/bad", `app\bad`, "app bad", "app\u00a0bad", "app\nbad", "app\u0000bad"} {
-		rctx, _, _ := newRoleRCtx(t, map[string]string{
-			"app-id": "string",
-		}, map[string]string{"app-id": appID})
-		assertRoleValidationParam(t, validateRoleAppID(rctx), "--app-id")
-	}
-}
-
-func TestValidateRoleAppIDRejectsLarkCredentialAppID(t *testing.T) {
-	rctx, _, _ := newRoleRCtx(t, map[string]string{
-		"app-id": "string",
-	}, map[string]string{"app-id": "cli_app"})
-	assertRoleValidationParam(t, validateRoleAppID(rctx), "--app-id")
-}
-
-func TestValidateRoleAppIDRequiresMiaodaPrefix(t *testing.T) {
-	for _, appID := range []string{"app", "app_", "miaoda_123", "plain"} {
-		rctx, _, _ := newRoleRCtx(t, map[string]string{
-			"app-id": "string",
-		}, map[string]string{"app-id": appID})
-		problem := assertRoleValidationParam(t, validateRoleAppID(rctx), "--app-id")
-		if !strings.Contains(problem.Message, "starting with app_") {
-			t.Fatalf("appID=%q message=%q, want app_ guidance", appID, problem.Message)
-		}
-	}
-}
-
-func TestValidateRoleIDRejectsInvalidRequiredRoleID(t *testing.T) {
-	rctx, _, _ := newRoleRCtx(t, map[string]string{
-		"app-id":  "string",
-		"role-id": "string",
-	}, map[string]string{"app-id": "app_x", "role-id": "bad/role"})
-	problem := assertRoleValidationParam(t, validateRoleID(rctx), "--role-id")
-	if strings.Contains(problem.Hint, "omit --role-id") || !strings.Contains(problem.Hint, "+role-list") {
-		t.Fatalf("hint = %q, want existing-role resolution guidance", problem.Hint)
-	}
-}
-
-func TestValidateRoleIDRejectsMissingRequiredRoleID(t *testing.T) {
-	rctx, _, _ := newRoleRCtx(t, map[string]string{
-		"app-id":  "string",
-		"role-id": "string",
-	}, map[string]string{"app-id": "app_x"})
-	problem := assertRoleValidationParam(t, validateRoleID(rctx), "--role-id")
-	if problem.Message != "--role-id is required" {
-		t.Fatalf("message = %q, want --role-id is required", problem.Message)
-	}
-}
-
-func TestBuildRoleMemberGroupsAndBody(t *testing.T) {
-	groups, err := buildRoleMemberGroups(" ou_a,ou_b ", " od-a ", " oc_a ")
-	if err != nil {
-		t.Fatalf("buildRoleMemberGroups() = %v", err)
-	}
-	if len(groups.Users) != 2 || len(groups.Departments) != 1 || len(groups.Chats) != 1 {
-		t.Fatalf("groups = %#v", groups)
-	}
-	body := buildRoleMemberBody(groups)
-	assertJSONEquivalent(t, body, map[string]interface{}{
-		"users":       []interface{}{"ou_a", "ou_b"},
-		"departments": []interface{}{"od-a"},
-		"chats":       []interface{}{"oc_a"},
-	})
-}
-
-func TestBuildRoleMemberGroupsRejectsEmpty(t *testing.T) {
-	_, err := buildRoleMemberGroups(" , ", "", "")
-	assertRoleValidationParams(t, err, "--users", "--departments", "--chats")
-}
-
-func TestBuildRoleMemberGroupsRejectsInvalidMemberIDWithSourceParam(t *testing.T) {
-	tests := []struct {
-		name        string
-		users       string
-		departments string
-		chats       string
-		wantParam   string
-	}{
-		{name: "users slash", users: "ou/bad", wantParam: "--users"},
-		{name: "users email", users: "alice@example.com", wantParam: "--users"},
-		{name: "users wrong prefix", users: "user_123", wantParam: "--users"},
-		{name: "users prefix only", users: "ou_", wantParam: "--users"},
-		{name: "departments wrong prefix", departments: "ou_user", wantParam: "--departments"},
-		{name: "departments prefix only", departments: "od-", wantParam: "--departments"},
-		{name: "legacy departments prefix", departments: "od_department", wantParam: "--departments"},
-		{name: "chats wrong prefix", chats: "od-department", wantParam: "--chats"},
-		{name: "chats prefix only", chats: "oc_", wantParam: "--chats"},
-		{
-			name:        "departments",
-			departments: "od-bad value",
-			wantParam:   "--departments",
-		},
-		{
-			name:      "chats",
-			chats:     "oc?bad",
-			wantParam: "--chats",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			_, err := buildRoleMemberGroups(tt.users, tt.departments, tt.chats)
-			assertRoleValidationParam(t, err, tt.wantParam)
-		})
-	}
-}
-
-func TestBuildRoleMemberGroupsRejectsMoreThanMax(t *testing.T) {
-	users := make([]string, maxRoleMembers+1)
-	for i := range users {
-		users[i] = "ou_test"
-	}
-	_, err := buildRoleMemberGroups(strings.Join(users, ","), "", "")
-	assertRoleValidationParams(t, err, "--users")
-}
-
-func TestBuildRoleMemberGroupsRejectsMoreThanMaxOnlyChats(t *testing.T) {
-	chats := make([]string, maxRoleMembers+1)
-	for i := range chats {
-		chats[i] = "oc_test"
-	}
-	_, err := buildRoleMemberGroups("", "", strings.Join(chats, ","))
-	problem := assertRoleValidationParams(t, err, "--chats")
-	if !strings.Contains(problem.Message, "role members cannot exceed 100") {
-		t.Fatalf("message = %q, want role members limit", problem.Message)
-	}
-	if !strings.Contains(problem.Hint, "does not split") || !strings.Contains(problem.Hint, "atomic request") {
-		t.Fatalf("hint = %q, want no automatic batching guidance", problem.Hint)
-	}
-}
-
-func TestBuildRoleMemberGroupsOverflowNamesEveryContributingFlag(t *testing.T) {
-	users := strings.TrimSuffix(strings.Repeat("ou_user,", 60), ",")
-	chats := strings.TrimSuffix(strings.Repeat("oc_chat,", 41), ",")
-	_, err := buildRoleMemberGroups(users, "", chats)
-	assertRoleValidationParams(t, err, "--users", "--chats")
-}
-
-func TestRoleMemberKindsAreCompleteAndStable(t *testing.T) {
-	want := []roleMemberKind{
-		{memberType: "user", dataKey: "users", flagName: "--users", prefix: "ou_"},
-		{memberType: "department", dataKey: "departments", flagName: "--departments", prefix: "od-"},
-		{memberType: "chat", dataKey: "chats", flagName: "--chats", prefix: "oc_"},
-	}
-	if len(roleMemberKinds) != len(want) {
-		t.Fatalf("roleMemberKinds = %#v, want %#v", roleMemberKinds, want)
-	}
-	for index := range want {
-		if roleMemberKinds[index] != want[index] {
-			t.Fatalf("roleMemberKinds[%d] = %#v, want %#v", index, roleMemberKinds[index], want[index])
-		}
-	}
-}
-
-func TestRoleDisplayValueSanitizesAndFlattens(t *testing.T) {
-	got := roleDisplayValue("  Admin\n\x1b[31mred\x1b[0m\tvalue  ")
-	if got != "Admin red value" {
-		t.Fatalf("roleDisplayValue() = %q, want flattened safe text", got)
-	}
-}
-
-func TestRoleNextPageToken(t *testing.T) {
-	if got := roleNextPageToken(40, 20, true); got != "60" {
-		t.Fatalf("roleNextPageToken(hasMore) = %q, want 60", got)
-	}
-	if got := roleNextPageToken(40, 20, false); got != "" {
-		t.Fatalf("roleNextPageToken(!hasMore) = %q, want empty", got)
-	}
-}
-
-func TestWithRoleErrorHintUsesDocumentedRecoveryAndPreservesEnvelope(t *testing.T) {
-	tests := []struct {
-		name      string
-		code      int
-		operation roleErrorOperation
-		wantHint  string
-		forbid    string
-	}{
-		{name: "invalid parameters", code: roleErrInvalidParameters, operation: roleOperationList, wantHint: roleAppHint},
-		{name: "administrator required", code: roleErrAdminRequired, operation: roleOperationList, wantHint: "app administrator"},
-		{name: "administrator or developer required", code: roleErrManagerRequired, operation: roleOperationGet, wantHint: "administrator or app developer"},
-		{name: "invalid create role id", code: roleErrInvalidRoleID, operation: roleOperationCreate, wantHint: "omit --role-id"},
-		{name: "role missing", code: roleErrRoleNotFound, operation: roleOperationGet, wantHint: "+role-list"},
-		{name: "stale match role", code: roleErrRoleNotFound, operation: roleOperationMatchList, wantHint: "may no longer be valid", forbid: "--role-id"},
-		{name: "duplicate role id", code: roleErrRoleAlreadyExists, operation: roleOperationCreate, wantHint: "different --role-id"},
-		{name: "role limit", code: roleErrRoleLimitExceeded, operation: roleOperationCreate, wantHint: "delete an unused app role"},
-		{name: "invalid role name", code: roleErrInvalidRoleName, operation: roleOperationUpdate, wantHint: "adjust --name"},
-		{name: "invalid role description", code: roleErrInvalidRoleDescription, operation: roleOperationUpdate, wantHint: "adjust --description"},
-		{name: "unsupported member type", code: roleErrUnsupportedMemberType, operation: roleOperationMemberList, wantHint: "user, department, or chat"},
-		{name: "invalid member id", code: roleErrInvalidMemberID, operation: roleOperationMemberAdd, wantHint: "member IDs"},
-		{name: "invalid match target", code: roleErrInvalidMemberID, operation: roleOperationMatchList, wantHint: "--user-id", forbid: "--role-id"},
-		{name: "user quota", code: roleErrUserLimitExceeded, operation: roleOperationMemberAdd, wantHint: "reduce the users"},
-		{name: "department quota", code: roleErrDepartmentLimitExceeded, operation: roleOperationMemberAdd, wantHint: "reduce the departments"},
-		{name: "chat quota", code: roleErrChatLimitExceeded, operation: roleOperationMemberAdd, wantHint: "reduce the chats"},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			err := errclass.BuildAPIError(map[string]any{
-				"code":   tt.code,
-				"msg":    "role request failed",
-				"log_id": "log-role-hint",
-			}, errclass.ClassifyContext{Identity: "user"})
-			err = withRoleErrorHint(err, tt.operation)
-			problem, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("err = %#v, want typed problem", err)
-			}
-			if problem.Code != tt.code || problem.LogID != "log-role-hint" || problem.Retryable {
-				t.Fatalf("problem envelope changed: %+v", problem)
-			}
-			if !strings.Contains(problem.Hint, tt.wantHint) {
-				t.Fatalf("hint = %q, want substring %q", problem.Hint, tt.wantHint)
-			}
-			if tt.forbid != "" && strings.Contains(problem.Hint, tt.forbid) {
-				t.Fatalf("hint = %q, must not contain %q", problem.Hint, tt.forbid)
-			}
-		})
-	}
-}
-
-func TestWithRoleErrorHintPreservesServerDetail(t *testing.T) {
-	err := errclass.BuildAPIError(map[string]any{
-		"code": roleErrInvalidRoleName,
-		"msg":  "invalid role name",
-		"error": map[string]any{
-			"details": []any{map[string]any{"value": "name exceeds the service limit"}},
-		},
-	}, errclass.ClassifyContext{Identity: "user"})
-	err = withRoleErrorHint(err, roleOperationCreate)
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("err = %#v, want typed problem", err)
-	}
-	for _, want := range []string{"name exceeds the service limit", "adjust --name"} {
-		if !strings.Contains(problem.Hint, want) {
-			t.Fatalf("hint = %q, want %q", problem.Hint, want)
-		}
-	}
-}
-
-func TestWithRoleErrorHintPreservesAuthorizationDetail(t *testing.T) {
-	var err error = errs.NewPermissionError(errs.SubtypePermissionDenied, "administrator access required").
-		WithCode(roleErrAdminRequired).
-		WithHint("server detail: only owners may change this app")
-	err = withRoleErrorHint(err, roleOperationUpdate)
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("err = %#v, want typed problem", err)
-	}
-	for _, want := range []string{"server detail: only owners", "ask an app administrator"} {
-		if !strings.Contains(problem.Hint, want) {
-			t.Fatalf("hint = %q, want %q", problem.Hint, want)
-		}
-	}
-}

shortcuts/apps/apps_role_member.go

@@ -1,611 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"strings"
-	"text/tabwriter"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// AppsRoleMemberList lists members of an app role.
-var AppsRoleMemberList = common.Shortcut{
-	Service:     appsService,
-	Command:     "+role-member-list",
-	Description: "List app role members",
-	Risk:        "read",
-	Tips: []string{
-		"Example: lark-cli apps +role-member-list --app-id <app_id> --role-id <role_id>",
-		"Example: lark-cli apps +role-member-list --app-id <app_id> --role-id <role_id> --member-type user",
-		"When only one member type is requested, pass --member-type user|department|chat instead of filtering the full response",
-		"--member-type returns only the selected member field; omitted fields are unknown, so omit the flag for pre/post-write baselines",
-		"--format table renders the CLI-native member_type/member_id table; this command has no --limit or --page-size flag",
-	},
-	Scopes:    []string{"spark:app:read"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: roleAppIDRequiredDesc, Required: true},
-		{Name: "role-id", Desc: roleIDRequiredDesc, Required: true},
-		{Name: "member-type", Desc: "filter member type", Enum: []string{"user", "department", "chat"}},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if err := validateRoleID(rctx); err != nil {
-			return err
-		}
-		_, err := buildRoleMemberListParams(rctx)
-		return err
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		// Validate already ran and called buildRoleMemberListParams; error is impossible here.
-		params, _ := buildRoleMemberListParams(rctx)
-		return common.NewDryRunAPI().
-			GET(roleMemberListURL(rctx)).
-			Desc("List app role members").
-			Params(params)
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		params, err := buildRoleMemberListParams(rctx)
-		if err != nil {
-			return err
-		}
-		data, err := rctx.CallAPITyped("GET", roleMemberListURL(rctx), params, nil)
-		memberType, _ := params["member_type"].(string)
-		if shouldRetryRoleMemberListWithoutFilter(err, memberType) {
-			fmt.Fprintln(rctx.IO().ErrOut, "warning: the server rejected chat member filtering; retried without the filter and returned only the chats field. Omit --member-type for a complete member baseline.")
-			data, err = rctx.CallAPITyped("GET", roleMemberListURL(rctx), nil, nil)
-		}
-		if err != nil {
-			return withRoleErrorHint(err, roleOperationMemberList)
-		}
-		data, err = normalizeRoleMemberListData(data, memberType)
-		if err != nil {
-			return err
-		}
-		if memberType != "" {
-			fmt.Fprintf(
-				rctx.IO().ErrOut,
-				"warning: --member-type=%s returns only the selected member field; omitted member fields are unknown. Omit --member-type for a complete member baseline.\n",
-				memberType,
-			)
-		}
-		out := roleMemberListOutputData(rctx, data)
-		rctx.OutFormat(out, nil, func(w io.Writer) {
-			renderRoleMemberListPretty(w, data)
-		})
-		return nil
-	},
-}
-
-// AppsRoleMemberAdd adds members to an app role.
-var AppsRoleMemberAdd = common.Shortcut{
-	Service:     appsService,
-	Command:     "+role-member-add",
-	Description: "Add app role members",
-	Risk:        "write",
-	Tips: []string{
-		"Example: lark-cli apps +role-member-add --app-id <app_id> --role-id <role_id> --users ou_x",
-		"Example: lark-cli apps +role-member-add --app-id <app_id> --role-id <role_id> --users ou_x,ou_y --departments od-x --chats oc_x",
-		"Resolve every name first, then add all resolved users (ou_), departments (od-), and chats (oc_) in one call using the three type-specific flags; if any resolution fails, stop without a partial write",
-	},
-	Scopes:    []string{"spark:app:write"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: roleAppIDRequiredDesc, Required: true},
-		{Name: "role-id", Desc: roleIDRequiredDesc, Required: true},
-		{Name: "users", Desc: "comma-separated user open IDs; do not pass names or emails"},
-		{Name: "departments", Desc: "comma-separated open_department_id values"},
-		{Name: "chats", Desc: "comma-separated open_chat_id values"},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if err := validateRoleID(rctx); err != nil {
-			return err
-		}
-		_, err := buildRoleMemberGroups(rctx.Str("users"), rctx.Str("departments"), rctx.Str("chats"))
-		return err
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		// Validate already ran and called buildRoleMemberAddBody; error is impossible here.
-		body, _, _ := buildRoleMemberAddBody(rctx)
-		return common.NewDryRunAPI().
-			POST(roleMemberAddURL(rctx)).
-			Desc("Add app role members").
-			Body(body)
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		body, _, err := buildRoleMemberAddBody(rctx)
-		if err != nil {
-			return err
-		}
-		data, err := rctx.CallAPITyped("POST", roleMemberAddURL(rctx), nil, body)
-		if err != nil {
-			return withRoleErrorHint(err, roleOperationMemberAdd)
-		}
-		data, err = normalizeRoleMemberMutationData(data)
-		if err != nil {
-			return err
-		}
-		rctx.OutFormat(data, nil, func(w io.Writer) {
-			renderRoleMemberMutationPretty(w, data)
-		})
-		return nil
-	},
-}
-
-// AppsRoleMemberRemove removes members from an app role.
-var AppsRoleMemberRemove = common.Shortcut{
-	Service:     appsService,
-	Command:     "+role-member-remove",
-	Description: "Remove app role members",
-	Risk:        "high-risk-write",
-	Tips: []string{
-		"Example: lark-cli apps +role-member-remove --app-id <app_id> --role-id <role_id> --users ou_x --yes",
-		"Example: lark-cli apps +role-member-remove --app-id <app_id> --role-id <role_id> --all --yes",
-		"When the user names a member, resolve and verify that exact name before writing; if lookup fails, stop and never infer that the role's only current member is the target",
-		"--all clears members but does not delete the role; after a confirmed --all operation, use an unfiltered +role-member-list to verify users, departments, and chats are empty",
-	},
-	Scopes:    []string{"spark:app:write"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: roleAppIDRequiredDesc, Required: true},
-		{Name: "role-id", Desc: roleIDRequiredDesc, Required: true},
-		{Name: "users", Desc: "comma-separated user open IDs; do not pass names or emails"},
-		{Name: "departments", Desc: "comma-separated open_department_id values"},
-		{Name: "chats", Desc: "comma-separated open_chat_id values"},
-		{Name: "all", Type: "bool", Desc: "remove all members from the role"},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if err := validateRoleID(rctx); err != nil {
-			return err
-		}
-		_, _, err := buildRoleMemberRemoveBody(rctx)
-		return err
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		// Validate already ran and called buildRoleMemberRemoveBody; error is impossible here.
-		body, _, _ := buildRoleMemberRemoveBody(rctx)
-		return common.NewDryRunAPI().
-			POST(roleMemberRemoveURL(rctx)).
-			Desc("Remove app role members").
-			Body(body)
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		body, _, err := buildRoleMemberRemoveBody(rctx)
-		if err != nil {
-			return err
-		}
-		data, err := rctx.CallAPITyped("POST", roleMemberRemoveURL(rctx), nil, body)
-		if err != nil {
-			return withRoleErrorHint(err, roleOperationMemberRemove)
-		}
-		data, err = normalizeRoleMemberMutationData(data)
-		if err != nil {
-			return err
-		}
-		rctx.OutFormat(data, nil, func(w io.Writer) {
-			renderRoleMemberMutationPretty(w, data)
-		})
-		return nil
-	},
-}
-
-// AppsRoleMatchList lists roles matching a user in an app.
-var AppsRoleMatchList = common.Shortcut{
-	Service:     appsService,
-	Command:     "+role-match-list",
-	Description: "List app roles matching a user",
-	Risk:        "read",
-	Tips: []string{
-		"Example: lark-cli apps +role-match-list --app-id <app_id> --user-id <user_open_id>",
-	},
-	Scopes:    []string{"spark:app:read"},
-	AuthTypes: []string{"user"},
-	HasFormat: true,
-	Flags: []common.Flag{
-		{Name: "app-id", Desc: roleAppIDRequiredDesc, Required: true},
-		{Name: "user-id", Desc: roleUserIDRequiredDesc, Required: true},
-	},
-	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		if err := validateRoleAppID(rctx); err != nil {
-			return err
-		}
-		_, err := roleMatchTargetUserID(rctx)
-		return err
-	},
-	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
-		// Validate already ran and called buildRoleMatchListBody; error is impossible here.
-		body, _ := buildRoleMatchListBody(rctx)
-		return common.NewDryRunAPI().
-			POST(roleMatchListURL(rctx)).
-			Desc("List app role matches").
-			Body(body)
-	},
-	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		body, err := buildRoleMatchListBody(rctx)
-		if err != nil {
-			return err
-		}
-		data, err := rctx.CallAPITyped("POST", roleMatchListURL(rctx), nil, body)
-		if err != nil {
-			return withRoleErrorHint(err, roleOperationMatchList)
-		}
-		out, err := normalizeRoleMatchListData(data)
-		if err != nil {
-			return err
-		}
-		rctx.OutFormat(out, nil, func(w io.Writer) {
-			renderRoleMatchListPretty(w, common.GetSlice(out, "roles"))
-		})
-		return nil
-	},
-}
-
-func roleMemberListURL(rctx *common.RuntimeContext) string {
-	return fmt.Sprintf(roleMemberListPath,
-		validate.EncodePathSegment(roleAppID(rctx)),
-		validate.EncodePathSegment(roleID(rctx)),
-	)
-}
-
-func roleMemberAddURL(rctx *common.RuntimeContext) string {
-	return fmt.Sprintf(roleMemberAddPath,
-		validate.EncodePathSegment(roleAppID(rctx)),
-		validate.EncodePathSegment(roleID(rctx)),
-	)
-}
-
-func roleMemberRemoveURL(rctx *common.RuntimeContext) string {
-	return fmt.Sprintf(roleMemberRemovePath,
-		validate.EncodePathSegment(roleAppID(rctx)),
-		validate.EncodePathSegment(roleID(rctx)),
-	)
-}
-
-func roleMatchListURL(rctx *common.RuntimeContext) string {
-	return fmt.Sprintf(roleMatchListPath, validate.EncodePathSegment(roleAppID(rctx)))
-}
-
-func buildRoleMemberListParams(rctx *common.RuntimeContext) (map[string]interface{}, error) {
-	params := map[string]interface{}{}
-	if memberType := strings.TrimSpace(rctx.Str("member-type")); memberType != "" {
-		if _, ok := roleMemberKindForType(memberType); !ok {
-			return nil, appsValidationParamError("--member-type", "--member-type must be one of user, department, or chat").
-				WithHint("omit --member-type to list all member types")
-		}
-		params["member_type"] = memberType
-	}
-	return params, nil
-}
-
-func shouldRetryRoleMemberListWithoutFilter(err error, memberType string) bool {
-	if err == nil || memberType != "chat" {
-		return false
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		return false
-	}
-	if problem.Code == roleErrUnsupportedMemberType || problem.Code == 400004040 {
-		return true
-	}
-	return problem.Code == 2 && strings.Contains(strings.ToLower(problem.Message), "member_type")
-}
-
-func normalizeRoleMemberListData(data map[string]interface{}, memberType string) (map[string]interface{}, error) {
-	if data == nil {
-		return nil, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"role member response data must be an object",
-		).WithHint("retry the complete member read; do not treat missing, null, or non-object data as an empty role")
-	}
-	out := map[string]interface{}{}
-	for k, v := range data {
-		out[k] = v
-	}
-	// The role service uses an exact empty data object when the requested member
-	// view is empty. For a filtered request, that proves only the selected group
-	// is empty; non-selected groups must remain omitted rather than being
-	// synthesized as empty.
-	if len(data) == 0 {
-		if memberType != "" {
-			kind, _ := roleMemberKindForType(memberType)
-			out[kind.dataKey] = []string{}
-			return out, nil
-		}
-		for _, kind := range roleMemberKinds {
-			out[kind.dataKey] = []string{}
-		}
-		return out, nil
-	}
-	if memberType != "" {
-		selectedKind, _ := roleMemberKindForType(memberType)
-		values, err := parseRoleMemberIDs(data, selectedKind)
-		if err != nil {
-			return nil, err
-		}
-		for _, kind := range roleMemberKinds {
-			if kind.memberType != memberType {
-				delete(out, kind.dataKey)
-			}
-		}
-		out[selectedKind.dataKey] = values
-		return out, nil
-	}
-	for _, kind := range roleMemberKinds {
-		values, err := parseRoleMemberIDs(data, kind)
-		if err != nil {
-			return nil, err
-		}
-		out[kind.dataKey] = values
-	}
-	return out, nil
-}
-
-func parseRoleMemberIDs(data map[string]interface{}, kind roleMemberKind) ([]string, error) {
-	raw, exists := data[kind.dataKey]
-	if !exists {
-		return nil, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"role member response is missing %s",
-			kind.dataKey,
-		).WithHint("retry the member operation; do not treat a missing member group as empty")
-	}
-	items, ok := raw.([]interface{})
-	if !ok {
-		if stringItems, stringOK := raw.([]string); stringOK {
-			items = make([]interface{}, len(stringItems))
-			for index, value := range stringItems {
-				items[index] = value
-			}
-		} else {
-			return nil, errs.NewInternalError(
-				errs.SubtypeInvalidResponse,
-				"role member response field %s must be an array of strings",
-				kind.dataKey,
-			).WithHint("retry the member operation; do not use malformed member data as a permission baseline")
-		}
-	}
-	values := make([]string, 0, len(items))
-	for index, item := range items {
-		value, ok := item.(string)
-		value = strings.TrimSpace(value)
-		if !ok || value == "" || !strings.HasPrefix(value, kind.prefix) || len(value) == len(kind.prefix) {
-			return nil, errs.NewInternalError(
-				errs.SubtypeInvalidResponse,
-				"role member response field %s contains an invalid ID at index %d",
-				kind.dataKey,
-				index,
-			).WithHint("retry the member operation; expected open IDs with the documented member-type prefix")
-		}
-		values = append(values, value)
-	}
-	return values, nil
-}
-
-func normalizeRoleMemberMutationData(data map[string]interface{}) (map[string]interface{}, error) {
-	if data == nil {
-		return nil, nil
-	}
-	out := map[string]interface{}{}
-	for key, value := range data {
-		out[key] = value
-	}
-	for _, kind := range roleMemberKinds {
-		if _, exists := data[kind.dataKey]; !exists {
-			continue
-		}
-		values, err := parseRoleMemberIDs(data, kind)
-		if err != nil {
-			return nil, err
-		}
-		out[kind.dataKey] = values
-	}
-	return out, nil
-}
-
-func buildRoleMemberAddBody(rctx *common.RuntimeContext) (map[string]interface{}, roleMemberGroups, error) {
-	groups, err := buildRoleMemberGroups(rctx.Str("users"), rctx.Str("departments"), rctx.Str("chats"))
-	if err != nil {
-		return nil, groups, err
-	}
-	return buildRoleMemberBody(groups), groups, nil
-}
-
-func buildRoleMemberRemoveBody(rctx *common.RuntimeContext) (map[string]interface{}, roleMemberGroups, error) {
-	if rctx.Bool("all") {
-		if hasExplicitRoleMemberFlags(rctx) {
-			return nil, roleMemberGroups{}, appsValidationError("--all cannot be used with --users, --departments, or --chats").
-				WithParams(roleMemberRemoveConflictParams(rctx)...).
-				WithHint("use --all by itself to clear every member, or pass explicit member IDs without --all")
-		}
-		return map[string]interface{}{"all": true}, roleMemberGroups{}, nil
-	}
-	if !hasExplicitRoleMemberFlags(rctx) {
-		reason := "provide member IDs or use --all"
-		return nil, roleMemberGroups{}, appsValidationError("specify members to remove with --users/--departments/--chats, or use --all to clear every member").
-			WithParams(
-				appsInvalidParam("--users", reason),
-				appsInvalidParam("--departments", reason),
-				appsInvalidParam("--chats", reason),
-				appsInvalidParam("--all", reason),
-			).
-			WithHint("pass specific member IDs (e.g. --users ou_x), or use --all to remove all members")
-	}
-	groups, err := buildRoleMemberGroups(rctx.Str("users"), rctx.Str("departments"), rctx.Str("chats"))
-	if err != nil {
-		return nil, groups, err
-	}
-	return buildRoleMemberBody(groups), groups, nil
-}
-
-func roleMemberRemoveConflictParams(rctx *common.RuntimeContext) []errs.InvalidParam {
-	reason := "cannot be combined with --all"
-	params := []errs.InvalidParam{appsInvalidParam("--all", "cannot be combined with explicit member flags")}
-	for _, kind := range roleMemberKinds {
-		if strings.TrimSpace(rctx.Str(strings.TrimPrefix(kind.flagName, "--"))) != "" {
-			params = append(params, appsInvalidParam(kind.flagName, reason))
-		}
-	}
-	return params
-}
-
-func hasExplicitRoleMemberFlags(rctx *common.RuntimeContext) bool {
-	return strings.TrimSpace(rctx.Str("users")) != "" ||
-		strings.TrimSpace(rctx.Str("departments")) != "" ||
-		strings.TrimSpace(rctx.Str("chats")) != ""
-}
-
-func buildRoleMatchListBody(rctx *common.RuntimeContext) (map[string]interface{}, error) {
-	targetUserID, err := roleMatchTargetUserID(rctx)
-	if err != nil {
-		return nil, err
-	}
-	return map[string]interface{}{"target_user_id": targetUserID}, nil
-}
-
-func roleMatchTargetUserID(rctx *common.RuntimeContext) (string, error) {
-	raw := strings.TrimSpace(rctx.Str("user-id"))
-	if raw == "" {
-		return "", appsValidationParamError("--user-id", "--user-id is required").
-			WithHint("resolve the user to open_id first, then pass --user-id <open_id>")
-	}
-	if err := validateMemberID(raw, "--user-id"); err != nil {
-		return "", err
-	}
-	return raw, nil
-}
-
-func roleMemberListOutputData(rctx *common.RuntimeContext, data map[string]interface{}) interface{} {
-	switch rctx.Format {
-	case "table", "csv", "ndjson":
-		return roleMemberRows(data)
-	default:
-		return data
-	}
-}
-
-func roleMemberRows(data map[string]interface{}) []interface{} {
-	rows := []interface{}{}
-	addRows := func(memberType string, values []string) {
-		for _, value := range values {
-			rows = append(rows, map[string]interface{}{
-				"member_type": memberType,
-				"member_id":   value,
-			})
-		}
-	}
-	for _, kind := range roleMemberKinds {
-		addRows(kind.memberType, roleIDValues(data[kind.dataKey]))
-	}
-	return rows
-}
-
-func normalizeRoleMatchListData(data map[string]interface{}) (map[string]interface{}, error) {
-	rawRoles, exists := data["roles"]
-	roles, ok := rawRoles.([]interface{})
-	if !exists || !ok {
-		return nil, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"role match response field roles must be an array",
-		).WithHint("retry the user-role lookup; do not treat a missing or malformed roles field as no matches")
-	}
-	if err := validateRoleCollection(roles, "role match response field roles"); err != nil {
-		return nil, err
-	}
-	out := map[string]interface{}{}
-	for k, v := range data {
-		out[k] = v
-	}
-	out["roles"] = roles
-	return out, nil
-}
-
-func renderRoleMemberListPretty(w io.Writer, data map[string]interface{}) {
-	renderRoleMemberGroupsPretty(w, data)
-}
-
-func renderRoleMemberGroupsPretty(w io.Writer, data map[string]interface{}) {
-	for _, kind := range roleMemberKinds {
-		value, exists := data[kind.dataKey]
-		if !exists {
-			continue
-		}
-		renderRoleMemberSection(w, kind.dataKey, roleIDValues(value))
-	}
-}
-
-func renderRoleMemberMutationPretty(w io.Writer, data map[string]interface{}) {
-	renderedGroup := false
-	for _, kind := range roleMemberKinds {
-		value, exists := data[kind.dataKey]
-		if !exists {
-			continue
-		}
-		renderRoleMemberSection(w, kind.dataKey, roleIDValues(value))
-		renderedGroup = true
-	}
-	if !renderedGroup {
-		fmt.Fprintln(w, "Role member update accepted; use +role-member-list to verify current members.")
-	}
-}
-
-func renderRoleMemberSection(w io.Writer, label string, values []string) {
-	if len(values) == 0 {
-		fmt.Fprintf(w, "%s: []\n", label)
-		return
-	}
-	fmt.Fprintf(w, "%s:\n", label)
-	for _, value := range values {
-		fmt.Fprintf(w, "  - %s\n", roleDisplayValue(value))
-	}
-}
-
-func roleIDValues(value interface{}) []string {
-	switch items := value.(type) {
-	case []string:
-		out := make([]string, 0, len(items))
-		for _, item := range items {
-			if item = strings.TrimSpace(item); item != "" {
-				out = append(out, item)
-			}
-		}
-		return out
-	case []interface{}:
-		out := make([]string, 0, len(items))
-		for _, item := range items {
-			v, ok := item.(string)
-			if ok && strings.TrimSpace(v) != "" {
-				out = append(out, strings.TrimSpace(v))
-			}
-		}
-		return out
-	default:
-		return nil
-	}
-}
-
-func renderRoleMatchListPretty(w io.Writer, items []interface{}) {
-	tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
-	fmt.Fprintln(tw, "ROLE ID\tNAME\tDESCRIPTION")
-	for _, item := range items {
-		role, ok := item.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		fmt.Fprintf(tw, "%s\t%s\t%s\n",
-			roleDisplayValue(firstNonEmpty(common.GetString(role, "role_id"), common.GetString(role, "id"))),
-			roleDisplayValue(common.GetString(role, "name")),
-			roleDisplayValue(common.GetString(role, "description")),
-		)
-	}
-	_ = tw.Flush()
-}

shortcuts/apps/automation_common.go

@@ -1,453 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"fmt"
-	"sort"
-	"strconv"
-	"strings"
-	"unicode/utf8"
-
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// automationBasePath 是触发器公网 OpenAPI 前缀。后端把触发器公网端点统一
-// 到 apps 域 (spark/v1) 下，8 个端点全部位于
-// /open-apis/spark/v1/apps/:app_id/triggers* 下。这里直接复用同包的
-// apiBasePath 而不是自定义前缀，避免误用早期的备选前缀。
-const automationBasePath = apiBasePath
-
-func automationListPath(appID string) string {
-	return fmt.Sprintf(automationBasePath+"/apps/%s/triggers", validate.EncodePathSegment(appID))
-}
-
-func automationItemPath(appID, name string) string {
-	return fmt.Sprintf(automationBasePath+"/apps/%s/triggers/%s",
-		validate.EncodePathSegment(appID), validate.EncodePathSegment(name))
-}
-
-func automationWebhookTokenStatusPath(appID, name string) string {
-	return automationItemPath(appID, name) + "/webhook/token/status"
-}
-
-func automationWebhookTokenResetPath(appID, name string) string {
-	return automationItemPath(appID, name) + "/webhook/token/reset"
-}
-
-func automationWebhookURLResetPath(appID, name string) string {
-	return automationItemPath(appID, name) + "/webhook/url/reset"
-}
-
-// mapTriggerType 把 CLI 面向 Agent 的 kebab-case 类型转成 OpenAPI 的 snake_case。
-func mapTriggerType(cliType string) (string, error) {
-	switch cliType {
-	case "cron":
-		return "cron", nil
-	case "record-change":
-		return "record_change", nil
-	case "webhook":
-		return "webhook", nil
-	case "feishu-approval":
-		return "feishu_approval", nil
-	default:
-		return "", appsValidationParamError("--trigger-type",
-			"unknown --trigger-type %q; want one of cron, record-change, webhook, feishu-approval", cliType)
-	}
-}
-
-// validateCronExpr 校验五段式 cron 表达式，并兜底最小间隔 30 分钟。
-// 这是给 Agent 的即时提示；后端 OpenAPI 层也会校验（ErrInvalidCronTab /
-// ErrCronIntervalTooSmall），CLI 本地拦截只为更快反馈。
-//
-// Minute field accepted forms:
-//   - "N" (single value 0-59)
-//   - "N,M,..." (comma list of single values; min pairwise gap incl. wrap >= 30)
-//   - "*/N" (step from 0; N must be >= 30)
-//
-// Anything else (ranges like "N-M", stepped ranges like "N-M/S",
-// range shorthands like "0/10", question marks) is rejected up-front with a
-// typed --cron error. A previous version accepted "1-59/10" through the
-// fallthrough because none of the three matchers claimed it, and the caller
-// only found out the interval was 10 minutes when the backend rejected it
-// (or worse, silently accepted a schedule the operator did not intend).
-func validateCronExpr(expr string) error {
-	fields := strings.Fields(strings.TrimSpace(expr))
-	if len(fields) != 5 {
-		return appsValidationParamError("--cron",
-			"cron must have 5 fields (minute hour day month weekday), got %d in %q", len(fields), expr)
-	}
-	minute := fields[0]
-	if minute == "*" {
-		return appsValidationParamError("--cron",
-			"cron minute field '*' means every minute; minimum interval is 30 minutes")
-	}
-	if strings.HasPrefix(minute, "*/") {
-		n, err := strconv.Atoi(strings.TrimPrefix(minute, "*/"))
-		if err != nil || n < 1 || n > 59 {
-			return appsValidationParamError("--cron",
-				"cron minute step %q must be an integer 1..59", minute)
-		}
-		// */N in cron expands to [0, N, 2N, ...] within 0..59, then wraps to 0
-		// of the next hour. When N does not divide 60 the wraparound gap is
-		// 60 - last_multiple, which is <N. For the 30-minute floor to hold on
-		// every gap (in-hour AND wrap), *only* N=30 works: */30 fires at :00
-		// and :30, gaps [30, 30]. */45 fires at :00 and :45, gaps [45, 15] —
-		// the 15-min wraparound gap violates the floor. All 31..59 fail the
-		// same way (small wraparound remainder); 1..29 fail the in-hour gap.
-		if n != 30 {
-			return appsValidationParamError("--cron",
-				"cron step */%d produces a gap below the 30-minute minimum "+
-					"(only */30 keeps every gap >=30 including the wraparound); "+
-					"use */30, or an explicit list like '0,30'", n)
-		}
-		return nil
-	}
-	if strings.Contains(minute, ",") {
-		parts := strings.Split(minute, ",")
-		vals := make([]int, 0, len(parts))
-		for _, p := range parts {
-			p = strings.TrimSpace(p)
-			n, err := strconv.Atoi(p)
-			if err != nil || n < 0 || n > 59 {
-				return appsValidationParamError("--cron",
-					"cron minute list entry %q must be an integer 0..59", p)
-			}
-			vals = append(vals, n)
-		}
-		if len(vals) >= 2 {
-			sort.Ints(vals)
-			minGap := 60
-			for i := 1; i < len(vals); i++ {
-				if gap := vals[i] - vals[i-1]; gap < minGap {
-					minGap = gap
-				}
-			}
-			if wrapGap := vals[0] + 60 - vals[len(vals)-1]; wrapGap < minGap {
-				minGap = wrapGap
-			}
-			if minGap < 30 {
-				return appsValidationParamError("--cron",
-					"cron minute list %q has %d-min interval; minimum interval is 30 minutes", minute, minGap)
-			}
-		}
-		return nil
-	}
-	// Bare single value fallthrough. Reject range/step-range/anything else so
-	// forms like "1-59/10" (10-min interval) and "0/10" (10-min interval)
-	// cannot bypass the 30-minute floor. The backend enforces its own cron
-	// rules, but the CLI stays strict about which forms it accepts so callers
-	// get an early, unambiguous error.
-	if n, err := strconv.Atoi(minute); err == nil && n >= 0 && n <= 59 {
-		return nil
-	}
-	return appsValidationParamError("--cron",
-		"unsupported cron minute syntax %q; use N (0..59), N,M,... (min gap >=30), or */N (N>=30)", minute)
-}
-
-const defaultCronTimezone = "Asia/Shanghai"
-
-// Local length limits mirrored from the flag help ("--name <=100 chars",
-// "--description <=50 chars"). Enforcing here catches a violation before the
-// API round-trip and returns a typed --name / --description error, whereas
-// hitting the backend surfaces an opaque business error the agent has to
-// diagnose. Constants (not magic numbers) so the flag help and the check
-// share one source of truth if the backend ever renegotiates the limits.
-const (
-	automationNameMaxLen        = 100
-	automationDescriptionMaxLen = 50
-)
-
-// validateAutomationNameLen guards against a --name that would be rejected by
-// the backend on length. Empty is intentionally permitted here — the required
-// check lives in the create Validate hook (which fires first) and in Update
-// the flag is not required at all. Counts runes, not bytes: the flag help
-// documents "<=100 chars", and Chinese/emoji names would be silently rejected
-// well below the char limit if we counted UTF-8 bytes.
-func validateAutomationNameLen(name string) error {
-	if n := utf8.RuneCountInString(name); n > automationNameMaxLen {
-		return appsValidationParamError("--name",
-			"--name must be at most %d chars, got %d", automationNameMaxLen, n)
-	}
-	return nil
-}
-
-// validateAutomationDescriptionLen guards --description length; empty passes.
-// Counts runes for the same reason as validateAutomationNameLen.
-func validateAutomationDescriptionLen(desc string) error {
-	if n := utf8.RuneCountInString(desc); n > automationDescriptionMaxLen {
-		return appsValidationParamError("--description",
-			"--description must be at most %d chars, got %d", automationDescriptionMaxLen, n)
-	}
-	return nil
-}
-
-// conditionFlagFamily maps each condition-carrying flag to the trigger-type
-// family it belongs to. Used by create/update to reject cross-type flag
-// combinations up-front (e.g. --trigger-type webhook --cron '0 9 * * *'
-// silently dropped --cron before this guard).
-//
-// --timezone is a modifier on --cron, so it lives in the cron family.
-// --description is trigger-type-agnostic and NOT in this map — it can pair
-// with any type on create and can appear alone on update.
-var conditionFlagFamily = map[string]string{
-	"cron":            "cron",
-	"timezone":        "cron",
-	"table":           "record-change",
-	"event":           "record-change",
-	"fields":          "record-change",
-	"white-ip-list":   "webhook",
-	"event-type":      "feishu-approval",
-	"instance-status": "feishu-approval",
-	"task-status":     "feishu-approval",
-	"approval-code":   "feishu-approval",
-}
-
-// flagIsSet reports whether a condition-carrying flag has a caller-provided
-// value. string and string-array types both need to be probed; a nil / empty
-// value counts as unset.
-func flagIsSet(rctx *common.RuntimeContext, name string) bool {
-	if v := strings.TrimSpace(rctx.Str(name)); v != "" {
-		return true
-	}
-	if arr := rctx.StrArray(name); len(arr) > 0 {
-		return true
-	}
-	return false
-}
-
-// familiesInUse returns the set of trigger-type families whose condition flags
-// the caller has set on this invocation. A trigger has exactly one type, so
-// legitimate condition writes involve at most one family; anything else is a
-// user mistake that must not slip through to the backend.
-func familiesInUse(rctx *common.RuntimeContext) map[string]string {
-	out := map[string]string{}
-	for flag, family := range conditionFlagFamily {
-		if flagIsSet(rctx, flag) {
-			out[family] = flag
-		}
-	}
-	return out
-}
-
-// familiesMixedList renders a comma-separated, sorted list of families
-// currently in use for inclusion in the multi-family rejection error. Stable
-// order keeps the error message deterministic across Go's random map
-// iteration.
-func familiesMixedList(families map[string]string) string {
-	names := make([]string, 0, len(families))
-	for name := range families {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-	return strings.Join(names, ", ")
-}
-
-// rejectCrossFamilyCondFlags rejects any condition flag that does not belong
-// to `wantFamily`. Returns a typed --<flag> error naming the first offending
-// flag encountered. Deterministic ordering (iterated over a stable slice)
-// keeps the error message reproducible for tests.
-func rejectCrossFamilyCondFlags(rctx *common.RuntimeContext, wantFamily string) error {
-	// Stable iteration order for a deterministic Param on error.
-	order := []string{
-		"cron", "timezone",
-		"table", "event", "fields",
-		"white-ip-list",
-		"event-type", "instance-status", "task-status", "approval-code",
-	}
-	for _, flag := range order {
-		if conditionFlagFamily[flag] != wantFamily && flagIsSet(rctx, flag) {
-			return appsValidationParamError("--"+flag,
-				"--%s belongs to trigger-type %q, not %q; drop it or change --trigger-type",
-				flag, conditionFlagFamily[flag], wantFamily)
-		}
-	}
-	return nil
-}
-
-// approvalStatusSets 是 feishu-approval 两种 event-type 各自的合法状态集合。
-// 后端 OpenAPI 不逐值校验 status，CLI 本地分桶校验是唯一保障。
-var approvalStatusSets = map[string]map[string]struct{}{
-	"approval_instance": setOf("PENDING", "APPROVED", "REJECTED", "CANCELED", "DELETED", "REVERTED", "OVERTIME_CLOSE", "OVERTIME_RECOVER"),
-	"approval_task":     setOf("REVERTED", "PENDING", "APPROVED", "REJECTED", "TRANSFERRED", "ROLLBACK", "DONE", "OVERTIME_CLOSE", "OVERTIME_RECOVER"),
-}
-
-func setOf(items ...string) map[string]struct{} {
-	m := make(map[string]struct{}, len(items))
-	for _, it := range items {
-		m[it] = struct{}{}
-	}
-	return m
-}
-
-// buildCronCondition 产出 OpenAPI 层 cron_condition body。缺省时区补 Asia/Shanghai。
-func buildCronCondition(expr, tz string) (map[string]interface{}, error) {
-	if err := validateCronExpr(expr); err != nil {
-		return nil, err
-	}
-	if strings.TrimSpace(tz) == "" {
-		tz = defaultCronTimezone
-	}
-	return map[string]interface{}{"cron": strings.TrimSpace(expr), "timezone": tz}, nil
-}
-
-// recordChangeEventSet 是 record-change 触发器合法 event 枚举。
-// 4 个值来自需求定义。CLI 本地做白名单校验，
-// 避免后端 event 字段校验缺失导致的"接受任意字符串→触发器永不触发"问题。
-var recordChangeEventSet = setOf("INSERT", "UPDATE", "UPSERT", "DELETE")
-
-// buildRecordChangeCondition 产出 record_change_condition body；event 大写化。
-func buildRecordChangeCondition(table, event string, fields []string) (map[string]interface{}, error) {
-	if strings.TrimSpace(table) == "" {
-		return nil, appsValidationParamError("--table", "--table is required for record-change triggers")
-	}
-	ev := strings.ToUpper(strings.TrimSpace(event))
-	if ev == "" {
-		return nil, appsValidationParamError("--event", "--event is required for record-change triggers (INSERT/UPDATE/UPSERT/DELETE)")
-	}
-	if _, valid := recordChangeEventSet[ev]; !valid {
-		return nil, appsValidationParamError("--event",
-			"--event %q is not a valid record-change event; want one of INSERT, UPDATE, UPSERT, DELETE", event)
-	}
-	cond := map[string]interface{}{"event": ev, "table": strings.TrimSpace(table)}
-	if len(fields) > 0 {
-		cond["fields"] = fields
-	}
-	return cond, nil
-}
-
-// buildWebhookCondition 产出 webhook_condition body。white_ip_list 在后端契约
-// 里是 required，因此当 CLI 侧未传 --white-ip-list 时也发一个空数组，避免后端
-// 拒收；显式空数组 `[]` 与"不限来源 IP"语义一致（呼应无鉴权公网回调告警）。
-func buildWebhookCondition(ipList []string) map[string]interface{} {
-	if ipList == nil {
-		ipList = []string{}
-	}
-	return map[string]interface{}{"white_ip_list": ipList}
-}
-
-// validateApprovalStatuses 按 event-type 分桶校验状态枚举合法性。
-func validateApprovalStatuses(eventType string, statuses []string) error {
-	set, ok := approvalStatusSets[eventType]
-	if !ok {
-		return appsValidationParamError("--event-type",
-			"unknown --event-type %q; want approval_task or approval_instance", eventType)
-	}
-	if len(statuses) == 0 {
-		flag := statusFlagFor(eventType)
-		return appsValidationParamError("--"+flag,
-			"--%s is required for event-type %q (at least one status)", flag, eventType)
-	}
-	for _, s := range statuses {
-		if _, valid := set[strings.ToUpper(strings.TrimSpace(s))]; !valid {
-			// 列出该 event-type 的合法状态集合，便于 Agent 修正。
-			return appsValidationParamError("--"+statusFlagFor(eventType),
-				"status %q is not valid for event-type %q; valid values: %s",
-				s, eventType, sortedStatusList(set))
-		}
-	}
-	return nil
-}
-
-// sortedStatusList 返回状态集合的稳定排序、逗号分隔字符串，用于错误提示。
-func sortedStatusList(set map[string]struct{}) string {
-	out := make([]string, 0, len(set))
-	for s := range set {
-		out = append(out, s)
-	}
-	sort.Strings(out)
-	return strings.Join(out, ", ")
-}
-
-func statusFlagFor(eventType string) string {
-	if eventType == "approval_task" {
-		return "task-status"
-	}
-	return "instance-status"
-}
-
-// buildApprovalCondition 产出 feishu_approval_condition body。approval_code 可选：
-// 空则省略（匹配所有审批定义），不发空串。
-func buildApprovalCondition(code, eventType string, statuses []string) (map[string]interface{}, error) {
-	if err := validateApprovalStatuses(eventType, statuses); err != nil {
-		return nil, err
-	}
-	cond := map[string]interface{}{"event_type": eventType, "status": statuses}
-	if strings.TrimSpace(code) != "" {
-		cond["approval_code"] = strings.TrimSpace(code)
-	}
-	return cond, nil
-}
-
-// statusBodyFromAction 把 enable/disable 命令映射到同一 status 端点的 body。
-func statusBodyFromAction(enable bool) map[string]interface{} {
-	if enable {
-		return map[string]interface{}{"status": "enabled"}
-	}
-	return map[string]interface{}{"status": "disabled"}
-}
-
-// redactWebhookToken returns a shallow copy of a trigger view with any
-// trigger_condition.token_value scrubbed to nil, working for both response
-// shapes this package sees against the real backend (BOE probe, 2026-07):
-//
-//   - nested (get/create/update):
-//     { "trigger": { "trigger_condition": { "token_value": ... } } }
-//   - flat (list items):
-//     { "trigger_condition": { "token_value": ... } }
-//
-// The distinction matters because the get/create/update response envelopes
-// wrap the trigger under a `trigger` key while list items are already flat.
-// A version of this helper that only inspected the top-level key silently
-// no-op'd on the nested shape — a real risk to the "get/list never returns
-// plaintext token" invariant if the backend ever starts populating
-// token_value in these read paths (the field is `optional string` in the
-// IDL, so it's legal). We scrub both shapes here so the invariant does not
-// depend on backend behavior.
-//
-// The input is not mutated; callers get a fresh outer map with a rebuilt
-// trigger view. Non-webhook triggers and payloads without token_value pass
-// through unchanged.
-func redactWebhookToken(info map[string]interface{}) map[string]interface{} {
-	out := make(map[string]interface{}, len(info))
-	for k, v := range info {
-		out[k] = v
-	}
-	// Nested shape: rebuild info["trigger"] with a scrubbed trigger_condition.
-	if wrapped, ok := info["trigger"].(map[string]interface{}); ok {
-		out["trigger"] = scrubTriggerCondition(wrapped)
-		return out
-	}
-	// Flat shape (e.g. list items projected without a `trigger` wrapper):
-	// scrub trigger_condition on the same map.
-	if _, hasFlat := info["trigger_condition"].(map[string]interface{}); hasFlat {
-		return scrubTriggerCondition(out)
-	}
-	return out
-}
-
-// scrubTriggerCondition returns a shallow copy of a trigger-shaped map with
-// its trigger_condition.token_value replaced by nil. Called by
-// redactWebhookToken for each shape it recognizes.
-func scrubTriggerCondition(trigger map[string]interface{}) map[string]interface{} {
-	out := make(map[string]interface{}, len(trigger))
-	for k, v := range trigger {
-		out[k] = v
-	}
-	tc, ok := out["trigger_condition"].(map[string]interface{})
-	if !ok {
-		return out
-	}
-	redactedTC := make(map[string]interface{}, len(tc))
-	for k, v := range tc {
-		if k == "token_value" {
-			redactedTC[k] = nil
-			continue
-		}
-		redactedTC[k] = v
-	}
-	out["trigger_condition"] = redactedTC
-	return out
-}

shortcuts/apps/automation_common_test.go

@@ -1,381 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestAutomationPaths(t *testing.T) {
-	if got := automationListPath("app_x"); got != "/open-apis/spark/v1/apps/app_x/triggers" {
-		t.Errorf("listPath = %q", got)
-	}
-	if got := automationItemPath("app_x", "t1"); got != "/open-apis/spark/v1/apps/app_x/triggers/t1" {
-		t.Errorf("itemPath = %q", got)
-	}
-	if got := automationWebhookTokenStatusPath("app_x", "t1"); got != "/open-apis/spark/v1/apps/app_x/triggers/t1/webhook/token/status" {
-		t.Errorf("tokenStatusPath = %q", got)
-	}
-	if got := automationWebhookTokenResetPath("app_x", "t1"); got != "/open-apis/spark/v1/apps/app_x/triggers/t1/webhook/token/reset" {
-		t.Errorf("tokenResetPath = %q", got)
-	}
-	if got := automationWebhookURLResetPath("app_x", "t1"); got != "/open-apis/spark/v1/apps/app_x/triggers/t1/webhook/url/reset" {
-		t.Errorf("urlResetPath = %q", got)
-	}
-}
-
-// TestValidateAutomationNameLen_CountsRunes pins the char-not-byte contract:
-// the flag help documents "<=100 chars", and Chinese/emoji names would be
-// silently rejected below the char limit if we counted UTF-8 bytes.
-// A 100-rune Chinese string is 300 bytes but is 100 chars — must pass.
-func TestValidateAutomationNameLen_CountsRunes(t *testing.T) {
-	// 100 Chinese characters (each 3 UTF-8 bytes = 300 bytes total). This must
-	// pass because the limit is characters, not bytes; a byte-based check would
-	// have rejected it at len()=300 > 100.
-	name := strings.Repeat("触", automationNameMaxLen)
-	if err := validateAutomationNameLen(name); err != nil {
-		t.Errorf("100-rune Chinese name must pass rune-count limit, got: %v", err)
-	}
-	// 101 Chinese characters must fail: exceeds the char limit by one.
-	over := strings.Repeat("触", automationNameMaxLen+1)
-	if err := validateAutomationNameLen(over); err == nil {
-		t.Error("101-rune Chinese name must fail rune-count limit")
-	}
-}
-
-func TestMapTriggerType(t *testing.T) {
-	cases := map[string]string{
-		"cron": "cron", "record-change": "record_change",
-		"webhook": "webhook", "feishu-approval": "feishu_approval",
-	}
-	for in, want := range cases {
-		got, err := mapTriggerType(in)
-		if err != nil || got != want {
-			t.Errorf("mapTriggerType(%q) = %q, %v; want %q", in, got, err, want)
-		}
-	}
-	err := func() error { _, e := mapTriggerType("bogus"); return e }()
-	assertValidationParamError(t, err, "--trigger-type")
-}
-
-func TestValidateCronExpr(t *testing.T) {
-	if err := validateCronExpr("0 9 * * *"); err != nil {
-		t.Errorf("valid daily cron rejected: %v", err)
-	}
-	assertValidationParamError(t, validateCronExpr("0 9 * *"), "--cron")
-	assertValidationParamError(t, validateCronExpr("*/5 * * * *"), "--cron")
-	if err := validateCronExpr("*/30 * * * *"); err != nil {
-		t.Errorf("30-minute interval must pass: %v", err)
-	}
-}
-
-// TestValidateCronExpr_RejectsRangeStepBypass pins two related tightenings:
-//
-//   - Range-step syntax like "1-59/10" or shorthand "0/10" is a 10-minute
-//     interval, but the old *,*/N,list-only matcher fell through and
-//     accepted these. The new whitelist rejects any minute form outside
-//     {"N", "N,M,...", "*/N"}.
-//   - */N with N != 30 fails on wraparound: */45 fires at :00 and :45,
-//     leaving a 15-min gap before the next hour's :00. In standard cron,
-//     */N expands to [0, N, 2N, ...] then wraps to 0, so any N that does
-//     not divide 60 produces a small wraparound gap. Only N=30 keeps
-//     every gap (in-hour AND wrap) >= 30.
-func TestValidateCronExpr_RejectsRangeStepBypass(t *testing.T) {
-	rejected := []string{
-		"1-59/10 * * * *",
-		"0/10 * * * *",
-		"*/29 * * * *",  // step of 29 is below the 30-min floor
-		"*/31 * * * *",  // above 30: wraparound gap 60-31=29 < 30
-		"*/45 * * * *",  // reviewer example: fires [:00,:45], wraparound gap 15
-		"*/59 * * * *",  // fires [:00,:59], wraparound gap 1
-		"?  * * * *",    // range/? shorthand not supported
-		"5-25 * * * *",  // plain range not supported (backend may accept it, but CLI stays strict)
-		"5,10 * * * *",  // 5-min gap in comma list
-		"foo * * * *",   // garbage
-		"1,foo * * * *", // partially invalid list
-		"60 * * * *",    // out of range
-		"1,60 * * * *",  // list out of range
-	}
-	for _, expr := range rejected {
-		if err := validateCronExpr(expr); err == nil {
-			t.Errorf("expected %q to be rejected, got nil", expr)
-		}
-	}
-	accepted := []string{
-		"0 9 * * *",
-		"30 9 * * *",
-		"0,30 * * * *",
-		"*/30 * * * *",
-	}
-	for _, expr := range accepted {
-		if err := validateCronExpr(expr); err != nil {
-			t.Errorf("expected %q to pass, got: %v", expr, err)
-		}
-	}
-}
-
-func TestBuildCronCondition(t *testing.T) {
-	c, err := buildCronCondition("0 9 * * *", "")
-	if err != nil {
-		t.Fatalf("buildCronCondition err: %v", err)
-	}
-	if c["cron"] != "0 9 * * *" || c["timezone"] != "Asia/Shanghai" {
-		t.Errorf("cron condition = %+v; want default tz Asia/Shanghai", c)
-	}
-	_, err = buildCronCondition("*/5 * * * *", "")
-	assertValidationParamError(t, err, "--cron")
-}
-
-func TestBuildRecordChangeCondition(t *testing.T) {
-	c, err := buildRecordChangeCondition("tbl_1", "update", []string{"status"})
-	if err != nil {
-		t.Fatalf("err: %v", err)
-	}
-	if c["event"] != "UPDATE" || c["table"] != "tbl_1" {
-		t.Errorf("record_change = %+v; event must be uppercased", c)
-	}
-	_, err = buildRecordChangeCondition("", "UPDATE", nil)
-	assertValidationParamError(t, err, "--table")
-	_, err = buildRecordChangeCondition("tbl_1", "", nil)
-	assertValidationParamError(t, err, "--event")
-	// event 枚举白名单：PRD 定义 4 值枚举，CLI 本地拦截非法值。这道防线
-	// 存在是因为后端 record_change_condition.event 字段接受任意字符串
-	// (2026-07-08 BOE 实测)，创建后触发器永远不触发，用户不易察觉。
-	_, err = buildRecordChangeCondition("tbl_1", "INVALID_XXX", nil)
-	assertValidationParamError(t, err, "--event")
-	_, err = buildRecordChangeCondition("tbl_1", "insert_typo", nil)
-	assertValidationParamError(t, err, "--event")
-	// 大小写不敏感：小写合法值 uppercase 后仍应通过。
-	for _, ev := range []string{"insert", "UPDATE", "upsert", "delete"} {
-		if _, err := buildRecordChangeCondition("tbl_1", ev, nil); err != nil {
-			t.Errorf("event %q must be accepted (case-insensitive): %v", ev, err)
-		}
-	}
-}
-
-func TestValidateApprovalStatuses(t *testing.T) {
-	if err := validateApprovalStatuses("approval_instance", []string{"APPROVED"}); err != nil {
-		t.Errorf("valid instance status rejected: %v", err)
-	}
-	if err := validateApprovalStatuses("approval_task", []string{"TRANSFERRED"}); err != nil {
-		t.Errorf("valid task status rejected: %v", err)
-	}
-	// TRANSFERRED is task-only; must be rejected for approval_instance, keyed on
-	// --instance-status per statusFlagFor.
-	err := validateApprovalStatuses("approval_instance", []string{"TRANSFERRED"})
-	assertValidationParamError(t, err, "--instance-status")
-	// Unknown event-type must surface Param=--event-type.
-	err = validateApprovalStatuses("bogus", []string{"APPROVED"})
-	assertValidationParamError(t, err, "--event-type")
-
-	// A2: empty statuses slice must fail with param=--<flag> for the event-type.
-	err = validateApprovalStatuses("approval_instance", nil)
-	assertValidationParamError(t, err, "--instance-status")
-	err = validateApprovalStatuses("approval_task", []string{})
-	assertValidationParamError(t, err, "--task-status")
-
-	// The rejection message must enumerate the valid status set so an agent
-	// can correct itself. Message content is one of the few non-metadata
-	// assertions we keep, because the recovery workflow depends on it.
-	err = validateApprovalStatuses("approval_instance", []string{"TRANSFERRED"})
-	if err == nil {
-		t.Fatal("TRANSFERRED must be rejected for approval_instance")
-	}
-	msg := err.Error()
-	if !strings.Contains(msg, "valid values:") {
-		t.Errorf("error must list valid values, got: %s", msg)
-	}
-	if !strings.Contains(msg, "APPROVED") || !strings.Contains(msg, "PENDING") {
-		t.Errorf("error must enumerate the instance status set, got: %s", msg)
-	}
-	if strings.Contains(msg, "TRANSFERRED") && !strings.Contains(msg, "not valid") {
-		t.Errorf("instance valid-list must not include task-only TRANSFERRED, got: %s", msg)
-	}
-}
-
-func TestBuildApprovalCondition_CodeOptional(t *testing.T) {
-	// approval_code omitted → matches all definitions, no error
-	c, err := buildApprovalCondition("", "approval_instance", []string{"APPROVED"})
-	if err != nil {
-		t.Fatalf("empty approval_code must be allowed: %v", err)
-	}
-	if _, present := c["approval_code"]; present {
-		t.Error("empty approval_code must be omitted from body, not sent as empty string")
-	}
-	if c["event_type"] != "approval_instance" {
-		t.Errorf("event_type = %v", c["event_type"])
-	}
-	c2, _ := buildApprovalCondition("APV123", "approval_task", []string{"DONE"})
-	if c2["approval_code"] != "APV123" {
-		t.Errorf("approval_code = %v; want APV123", c2["approval_code"])
-	}
-}
-
-func TestStatusBodyFromAction(t *testing.T) {
-	if b := statusBodyFromAction(true); b["status"] != "enabled" {
-		t.Errorf("enable body = %+v", b)
-	}
-	if b := statusBodyFromAction(false); b["status"] != "disabled" {
-		t.Errorf("disable body = %+v", b)
-	}
-}
-
-// TestRedactWebhookToken exercises the flat shape (list items pass the
-// projected trigger view without a `trigger` wrapper) — token_value must be
-// scrubbed at the top-level trigger_condition.
-func TestRedactWebhookToken(t *testing.T) {
-	in := map[string]interface{}{
-		"name": "wh1", "trigger_type": "webhook",
-		"trigger_condition": map[string]interface{}{
-			"preview_url": "https://p", "runtime_url": "https://r",
-			"token_enabled": true, "token_value": "SECRET_PLAINTEXT",
-		},
-	}
-	out := redactWebhookToken(in)
-	tc, _ := out["trigger_condition"].(map[string]interface{})
-	if tc["token_value"] != nil {
-		t.Errorf("token_value must be nil after redaction, got %v", tc["token_value"])
-	}
-	if tc["token_enabled"] != true {
-		t.Errorf("token_enabled must be preserved")
-	}
-	if tc["preview_url"] != "https://p" {
-		t.Errorf("preview_url must be preserved")
-	}
-	// input must not be mutated
-	origTC, _ := in["trigger_condition"].(map[string]interface{})
-	if origTC["token_value"] != "SECRET_PLAINTEXT" {
-		t.Error("redactWebhookToken must not mutate the input")
-	}
-}
-
-// TestRedactWebhookToken_NestedShape pins the nested shape used by
-// get/create/update: the raw response envelope's `data` is passed in as
-// {trigger: {..., trigger_condition: {token_value}}}. A previous
-// implementation only inspected the top-level trigger_condition and this
-// path silently no-op'd — this test blocks that regression.
-//
-// The bearer-token map key is built at runtime via `"token"+"_value"` on
-// purpose: it plants the literal key/value pair in the map without
-// triggering the deterministic-gate credential-assignment regex on the
-// source of this file. Same sidestep as webhookAuthKind()'s split literal.
-func TestRedactWebhookToken_NestedShape(t *testing.T) {
-	credField := "token" + "_value"
-	tc := map[string]interface{}{
-		"preview_url": "https://p", "runtime_url": "https://r",
-		"token_enabled": true,
-	}
-	tc[credField] = "NESTED_PLAINTEXT"
-	in := map[string]interface{}{
-		"trigger": map[string]interface{}{
-			"name": "wh1", "trigger_type": "webhook", "status": "enabled",
-			"trigger_condition": tc,
-		},
-	}
-	out := redactWebhookToken(in)
-	trigger, _ := out["trigger"].(map[string]interface{})
-	if trigger == nil {
-		t.Fatal("nested shape must preserve the trigger wrapper")
-	}
-	tcOut, _ := trigger["trigger_condition"].(map[string]interface{})
-	if tcOut[credField] != nil {
-		t.Errorf("nested token_value must be nil after redaction, got %v", tcOut[credField])
-	}
-	if tcOut["token_enabled"] != true {
-		t.Errorf("nested token_enabled must be preserved, got %v", tcOut["token_enabled"])
-	}
-	if trigger["name"] != "wh1" {
-		t.Errorf("nested trigger.name must be preserved, got %v", trigger["name"])
-	}
-	// input must not be mutated
-	origTrigger, _ := in["trigger"].(map[string]interface{})
-	origTC, _ := origTrigger["trigger_condition"].(map[string]interface{})
-	if origTC[credField] != "NESTED_PLAINTEXT" {
-		t.Error("redactWebhookToken must not mutate the input on nested shape")
-	}
-}
-
-// TestRedactWebhookToken_RegressionGuardOnGetPath is the guard the reviewer
-// asked for: stub a nested response that plants a plaintext token where the
-// backend legally could put it (IDL: `optional string TokenValue`), and
-// assert the helper scrubs it. If someone reverts redactWebhookToken to
-// top-level only, this test will fail. Same runtime-key split as above to
-// keep the credential-assignment scanner quiet on the source.
-func TestRedactWebhookToken_RegressionGuardOnGetPath(t *testing.T) {
-	credField := "token" + "_value"
-	tc := map[string]interface{}{}
-	tc[credField] = "GUARD_SENTINEL"
-	nested := redactWebhookToken(map[string]interface{}{
-		"trigger": map[string]interface{}{
-			"trigger_condition": tc,
-		},
-	})
-	nestedTrigger, _ := nested["trigger"].(map[string]interface{})
-	nestedTC, _ := nestedTrigger["trigger_condition"].(map[string]interface{})
-	if nestedTC[credField] != nil {
-		t.Errorf("regression guard: helper failed to scrub nested token_value, got %v", nestedTC[credField])
-	}
-}
-
-// TestBuildWebhookCondition_AlwaysEmitsWhiteIPList: backend IDL marks
-// WhiteIPList required; CLI must send an empty array when the user omits
-// --white-ip-list rather than an empty condition object.
-func TestBuildWebhookCondition_AlwaysEmitsWhiteIPList(t *testing.T) {
-	cond := buildWebhookCondition(nil)
-	arr, ok := cond["white_ip_list"].([]string)
-	if !ok {
-		t.Fatalf("white_ip_list must be []string, got %T: %+v", cond["white_ip_list"], cond)
-	}
-	if len(arr) != 0 {
-		t.Errorf("nil input must produce empty array, got %v", arr)
-	}
-	cond2 := buildWebhookCondition([]string{"1.1.1.1"})
-	arr2, _ := cond2["white_ip_list"].([]string)
-	if len(arr2) != 1 || arr2[0] != "1.1.1.1" {
-		t.Errorf("explicit list not passed through: %v", arr2)
-	}
-}
-
-// TestParseIPListFlag_Validates rejects entries that are not valid IPv4/IPv6
-// addresses or CIDR blocks. The record-change --event whitelist already
-// treats "silent accept of a typoed value → the trigger never matches" as a
-// concrete user harm (see automation_common.go); an equally malformed IP
-// silently ships to the backend and narrows the allowlist to something the
-// operator did not intend. Same defense-in-depth stance here.
-func TestParseIPListFlag_Validates(t *testing.T) {
-	cases := []struct {
-		name    string
-		raw     string
-		wantErr bool
-	}{
-		{"empty", ``, false},
-		{"ipv4", `["1.1.1.1"]`, false},
-		{"ipv6", `["2001:db8::1"]`, false},
-		{"cidr_ipv4", `["10.0.0.0/8"]`, false},
-		{"cidr_ipv6", `["2001:db8::/32"]`, false},
-		{"mixed", `["1.1.1.1","10.0.0.0/24","2001:db8::1"]`, false},
-		{"trims_space", `[" 1.1.1.1 "]`, false},
-		{"malformed_json", `not-json`, true},
-		{"not_an_ip", `["not-an-ip"]`, true},
-		{"trailing_space_becomes_valid_after_trim", `["8.8.8.8 "]`, false},
-		{"octet_out_of_range", `["10.0.0.256"]`, true},
-		{"empty_entry", `["1.1.1.1",""]`, true},
-		{"garbage_cidr", `["10.0.0.0/64"]`, true}, // /64 invalid for IPv4
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			_, err := parseIPListFlag(tc.raw)
-			if tc.wantErr && err == nil {
-				t.Errorf("parseIPListFlag(%q): expected error, got nil", tc.raw)
-			}
-			if !tc.wantErr && err != nil {
-				t.Errorf("parseIPListFlag(%q): unexpected error: %v", tc.raw, err)
-			}
-			if err != nil {
-				assertValidationParamError(t, err, "--white-ip-list")
-			}
-		})
-	}
-}

shortcuts/apps/automation_helpers_test.go

@@ -1,57 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package apps
-
-import (
-	"errors"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// assertValidationParamError asserts that err is a typed *errs.ValidationError
-// (category=validation, subtype=invalid_argument) whose Param equals wantParam.
-// Message substrings are intentionally NOT asserted — per AGENTS.md, error-path
-// tests must key on typed metadata (Category/Subtype/Param) plus optional cause
-// preservation, not on user-facing message text.
-func assertValidationParamError(t *testing.T, err error, wantParam string) *errs.ValidationError {
-	t.Helper()
-	if err == nil {
-		t.Fatalf("expected typed validation error with param=%q, got nil", wantParam)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Category != errs.CategoryValidation {
-		t.Errorf("category = %s, want %s", ve.Category, errs.CategoryValidation)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype = %s, want %s", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != wantParam {
-		t.Errorf("param = %q, want %q", ve.Param, wantParam)
-	}
-	return ve
-}
-
-// assertInternalError asserts err is a typed *errs.InternalError with the given
-// subtype. Used to key error-path tests on typed metadata rather than message.
-func assertInternalError(t *testing.T, err error, wantSubtype errs.Subtype) *errs.InternalError {
-	t.Helper()
-	if err == nil {
-		t.Fatalf("expected typed internal error subtype=%s, got nil", wantSubtype)
-	}
-	var ie *errs.InternalError
-	if !errors.As(err, &ie) {
-		t.Fatalf("expected *errs.InternalError, got %T: %v", err, err)
-	}
-	if ie.Category != errs.CategoryInternal {
-		t.Errorf("category = %s, want %s", ie.Category, errs.CategoryInternal)
-	}
-	if ie.Subtype != wantSubtype {
-		t.Errorf("subtype = %s, want %s", ie.Subtype, wantSubtype)
-	}
-	return ie
-}

shortcuts/apps/shortcuts.go

@@ -17,15 +17,6 @@ func Shortcuts() []common.Shortcut {
 		AppsList,
 		AppsAccessScopeSet,
 		AppsAccessScopeGet,
-		AppsRoleList,
-		AppsRoleGet,
-		AppsRoleCreate,
-		AppsRoleUpdate,
-		AppsRoleDelete,
-		AppsRoleMemberList,
-		AppsRoleMemberAdd,
-		AppsRoleMemberRemove,
-		AppsRoleMatchList,
 		AppsHTMLPublish,
 		AppsInit,
 		AppsReleaseCreate,
@@ -85,13 +76,6 @@ func Shortcuts() []common.Shortcut {
 		AppsOpenAPIKeyDisable,
 		AppsOpenAPIKeyDelete,
 		AppsOpenAPIKeyReset,
-		// automation triggers (cron / record-change / webhook / feishu-approval)
-		AppsAutomationList,
-		AppsAutomationGet,
-		AppsAutomationCreate,
-		AppsAutomationUpdate,
-		AppsAutomationEnable,
-		AppsAutomationDisable,
 	}
 }
 

shortcuts/apps/shortcuts_test.go

@@ -20,13 +20,11 @@ import (
 //   - 3 git-credential
 //   - 5 session（create/list/get/stop/chat）+ 1 session-messages-list
 //   - 8 openapi-key（list/get/create/update/enable/disable/delete/reset）
-//   - 3 plugin（install/uninstall/list）
-//   - 6 automation（list/get/create/update/enable/disable）
-//   - 9 role（role CRUD + role-member list/add/remove + role-match-list）= 79。
-func TestAppsShortcuts_Returns79(t *testing.T) {
+//   - 3 plugin（install/uninstall/list）= 63。
+func TestAppsShortcuts_Returns64(t *testing.T) {
 	got := Shortcuts()
-	if len(got) != 79 {
-		t.Fatalf("Shortcuts() returned %d entries, want 79", len(got))
+	if len(got) != 64 {
+		t.Fatalf("Shortcuts() returned %d entries, want 64", len(got))
 	}
 }
 
@@ -90,34 +88,6 @@ func TestAppsShortcuts_IncludesSessionCommands(t *testing.T) {
 	}
 }
 
-// 确认 role 管理命令都已挂载，避免实现存在但 shortcut 漏注册。
-func TestAppsShortcuts_IncludesRoleCommands(t *testing.T) {
-	want := map[string]bool{
-		"+role-list":          false,
-		"+role-get":           false,
-		"+role-create":        false,
-		"+role-update":        false,
-		"+role-delete":        false,
-		"+role-member-list":   false,
-		"+role-member-add":    false,
-		"+role-member-remove": false,
-		"+role-match-list":    false,
-	}
-	for _, sc := range Shortcuts() {
-		if _, ok := want[sc.Command]; ok {
-			want[sc.Command] = true
-			if sc.Hidden {
-				t.Errorf("%s must be visible", sc.Command)
-			}
-		}
-	}
-	for cmd, found := range want {
-		if !found {
-			t.Errorf("Shortcuts() missing %s", cmd)
-		}
-	}
-}
-
 // TestAppsGitCredentialHelper_IsNotAShortcut 确认 git credential helper 不作为 shortcut 暴露。
 func TestAppsGitCredentialHelper_IsNotAShortcut(t *testing.T) {
 	for _, shortcut := range Shortcuts() {

shortcuts/base/base_dashboard_execute_test.go

@@ -4,11 +4,9 @@
 package base
 
 import (
-	"errors"
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/httpmock"
 )
 
@@ -678,145 +676,6 @@ func TestBaseDashboardBlockCreate_InvalidRollup(t *testing.T) {
 	}
 }
 
-// TestBaseDashboardBlockCreate_IllegalSortOrderType guards against a P1 where a
-// non-string sort.order (123 / null / false) was silently coerced to "asc" and
-// created a block with a tampered sort. A present-but-illegal order must now
-// surface a typed validation error, never a silent default.
-func TestBaseDashboardBlockCreate_IllegalSortOrderType(t *testing.T) {
-	for _, tc := range []struct {
-		name  string
-		order string // raw JSON literal for the order value
-	}{
-		{"number", "123"},
-		{"null", "null"},
-		{"bool", "false"},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			factory, stdout, _ := newExecuteFactory(t)
-			dc := `{"table_name":"T","series":[{"field_name":"金额","rollup":"SUM"}],` +
-				`"group_by":[{"field_name":"状态","mode":"integrated","sort":{"type":"group","order":` + tc.order + `}}]}`
-			args := []string{"+dashboard-block-create", "--base-token", "app_x", "--dashboard-id", "dsh_1",
-				"--name", "Bad", "--type", "column", "--data-config", dc}
-			err := runShortcut(t, BaseDashboardBlockCreate, args, factory, stdout)
-			if err == nil {
-				t.Fatalf("expected validation error for order=%s, got nil (stdout=%s)", tc.order, stdout.String())
-			}
-			var ve *errs.ValidationError
-			if !errors.As(err, &ve) {
-				t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
-			}
-			if ve.Category != errs.CategoryValidation || ve.Subtype != errs.SubtypeInvalidArgument {
-				t.Fatalf("category=%q subtype=%q, want validation/invalid_argument", ve.Category, ve.Subtype)
-			}
-			if ve.Param != "--data-config" {
-				t.Fatalf("param=%q, want --data-config", ve.Param)
-			}
-			if !strings.Contains(ve.Error(), "sort.order") {
-				t.Fatalf("error should name sort.order, got: %v", ve)
-			}
-		})
-	}
-}
-
-// TestBaseDashboardBlockCreate_MissingSortOrder pins the full create-path behavior
-// when sort.order is absent: group/view are normalized to order:"asc" and succeed
-// (matching the documented auto-fill), while value has no safe default and must
-// surface a typed validation error. These run end-to-end (Validate → normalize →
-// validate), so reverting the normalize/validate change flips a case and fails.
-func TestBaseDashboardBlockCreate_MissingSortOrder(t *testing.T) {
-	dc := func(sortType string) string {
-		return `{"table_name":"T","series":[{"field_name":"金额","rollup":"SUM"}],` +
-			`"group_by":[{"field_name":"状态","mode":"integrated","sort":{"type":"` + sortType + `"}}]}`
-	}
-
-	// group / view: absent order is auto-filled with "asc" and the request goes through.
-	for _, sortType := range []string{"group", "view"} {
-		t.Run(sortType+" defaults to asc", func(t *testing.T) {
-			factory, stdout, _ := newExecuteFactory(t)
-			args := []string{"+dashboard-block-create", "--base-token", "app_x", "--dashboard-id", "dsh_1",
-				"--name", "OK", "--type", "column", "--data-config", dc(sortType),
-				"--dry-run", "--format", "pretty"}
-			if err := runShortcut(t, BaseDashboardBlockCreate, args, factory, stdout); err != nil {
-				t.Fatalf("err=%v", err)
-			}
-			if got := stdout.String(); !strings.Contains(got, `"order":"asc"`) {
-				t.Fatalf("expected normalized order:asc for type=%s, stdout=%s", sortType, got)
-			}
-		})
-	}
-
-	// value: no meaningful default direction, so a missing order is a typed error.
-	t.Run("value requires explicit order", func(t *testing.T) {
-		factory, stdout, _ := newExecuteFactory(t)
-		args := []string{"+dashboard-block-create", "--base-token", "app_x", "--dashboard-id", "dsh_1",
-			"--name", "Bad", "--type", "column", "--data-config", dc("value")}
-		err := runShortcut(t, BaseDashboardBlockCreate, args, factory, stdout)
-		if err == nil {
-			t.Fatalf("expected validation error for value sort missing order, got nil (stdout=%s)", stdout.String())
-		}
-		p, ok := errs.ProblemOf(err)
-		if !ok || p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument {
-			t.Fatalf("expected validation/invalid_argument problem, got %T %v", err, err)
-		}
-		var ve *errs.ValidationError
-		if !errors.As(err, &ve) || ve.Param != "--data-config" {
-			t.Fatalf("expected param --data-config, got %T %v", err, err)
-		}
-		if !strings.Contains(ve.Error(), "sort.order 缺失") {
-			t.Fatalf("error should report missing order, got: %v", ve)
-		}
-	})
-}
-
-// TestNormalizeDataConfigSortOrder pins the normalization contract for sort.order:
-// only a truly absent key gets the "asc" default; a present illegal value is left
-// untouched so validation can reject it; a valid string is lower-cased.
-func TestNormalizeDataConfigSortOrder(t *testing.T) {
-	sortOf := func(cfg map[string]interface{}) map[string]interface{} {
-		gb := cfg["group_by"].([]interface{})
-		return gb[0].(map[string]interface{})["sort"].(map[string]interface{})
-	}
-	newCfg := func(sort map[string]interface{}) map[string]interface{} {
-		return map[string]interface{}{
-			"table_name": "T",
-			"series":     []interface{}{map[string]interface{}{"field_name": "v", "rollup": "sum"}},
-			"group_by":   []interface{}{map[string]interface{}{"field_name": "g", "sort": sort}},
-		}
-	}
-
-	t.Run("absent order defaults to asc for group", func(t *testing.T) {
-		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "group"}))
-		if got := sortOf(out)["order"]; got != "asc" {
-			t.Fatalf("order=%v, want asc", got)
-		}
-	})
-	t.Run("absent order not defaulted for value", func(t *testing.T) {
-		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "value"}))
-		if _, has := sortOf(out)["order"]; has {
-			t.Fatalf("value sort must not get a defaulted order: %v", sortOf(out))
-		}
-	})
-	t.Run("valid string lower-cased", func(t *testing.T) {
-		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "group", "order": "DESC"}))
-		if got := sortOf(out)["order"]; got != "desc" {
-			t.Fatalf("order=%v, want desc", got)
-		}
-	})
-	t.Run("illegal number not coerced", func(t *testing.T) {
-		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "group", "order": float64(123)}))
-		if got := sortOf(out)["order"]; got != float64(123) {
-			t.Fatalf("order=%v (type %T), want untouched 123", got, got)
-		}
-	})
-	t.Run("illegal nil not coerced", func(t *testing.T) {
-		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "view", "order": nil}))
-		got, has := sortOf(out)["order"]
-		if !has || got != nil {
-			t.Fatalf("order=%v has=%v, want present nil (untouched)", got, has)
-		}
-	})
-}
-
 // ── Text Block Tests ────────────────────────────────────────────────
 
 // TestBaseDashboardBlockExecuteCreate_TextType tests creating text blocks with markdown content.

shortcuts/base/base_dryrun_ops_test.go

@@ -117,14 +117,6 @@ func TestDryRunRecordOps(t *testing.T) {
 	)
 	assertDryRunContains(t, dryRunRecordList(ctx, listRT), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/records", "offset=0", "limit=200", "view_id=viw_1", "field_id=Name", "field_id=Age")
 
-	listFieldNamesAliasRT := newBaseTestRuntimeWithSlices(
-		map[string]string{"base-token": "app_x", "table-id": "tbl_1"},
-		map[string][]string{"field-names": {"Name", "Age"}},
-		nil,
-		map[string]int{"limit": 20},
-	)
-	assertDryRunContains(t, dryRunRecordList(ctx, listFieldNamesAliasRT), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/records", "limit=20", "field_id=Name", "field_id=Age")
-
 	filteredListRT := newBaseTestRuntimeWithArrays(
 		map[string]string{
 			"base-token":  "app_x",

shortcuts/base/base_execute_test.go

@@ -1296,29 +1296,6 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
-	t.Run("list field names alias", func(t *testing.T) {
-		factory, stdout, reg := newExecuteFactory(t)
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "field_id=Name&field_id=Age&limit=1&offset=0",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{
-					"fields":         []interface{}{"Name", "Age"},
-					"record_id_list": []interface{}{"rec_alias"},
-					"data":           []interface{}{[]interface{}{"Alice", 18}},
-					"total":          1,
-				},
-			},
-		})
-		if err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--limit", "1", "--field-names", "Name,Age", "--format", "json"}, factory, stdout); err != nil {
-			t.Fatalf("err=%v", err)
-		}
-		if got := stdout.String(); !strings.Contains(got, `"rec_alias"`) || !strings.Contains(got, `"Alice"`) {
-			t.Fatalf("stdout=%s", got)
-		}
-	})
-
 	t.Run("list json format", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
@@ -1343,30 +1320,6 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
-	t.Run("list json alias", func(t *testing.T) {
-		factory, stdout, reg := newExecuteFactory(t)
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "limit=1&offset=0",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{
-					"fields":         []interface{}{"Name"},
-					"field_id_list":  []interface{}{"fld_name"},
-					"record_id_list": []interface{}{"rec_alias"},
-					"data":           []interface{}{[]interface{}{"Carol"}},
-					"total":          1,
-				},
-			},
-		})
-		if err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--limit", "1", "--json"}, factory, stdout); err != nil {
-			t.Fatalf("err=%v", err)
-		}
-		if got := stdout.String(); !strings.Contains(got, `"record_id_list"`) || !strings.Contains(got, `"Carol"`) || !strings.Contains(got, `"rec_alias"`) {
-			t.Fatalf("stdout=%s", got)
-		}
-	})
-
 	t.Run("list markdown format", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
@@ -1623,14 +1576,6 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
-	t.Run("list field ids and field names alias are mutually exclusive", func(t *testing.T) {
-		factory, stdout, _ := newExecuteFactory(t)
-		err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "Name", "--field-names", "Age"}, factory, stdout)
-		if err == nil || !strings.Contains(err.Error(), "--field-id and --field-names are mutually exclusive") {
-			t.Fatalf("err=%v", err)
-		}
-	})
-
 	t.Run("list legacy fields flag rejected in dry-run", func(t *testing.T) {
 		factory, stdout, _ := newExecuteFactory(t)
 		err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--fields", "Name", "--dry-run"}, factory, stdout)

shortcuts/base/base_shortcuts_test.go

@@ -28,14 +28,6 @@ func newBaseTestRuntime(stringFlags map[string]string, boolFlags map[string]bool
 }
 
 func newBaseTestRuntimeWithArrays(stringFlags map[string]string, stringArrayFlags map[string][]string, boolFlags map[string]bool, intFlags map[string]int) *common.RuntimeContext {
-	return newBaseTestRuntimeWithArraysAndSlices(stringFlags, stringArrayFlags, nil, boolFlags, intFlags)
-}
-
-func newBaseTestRuntimeWithSlices(stringFlags map[string]string, stringSliceFlags map[string][]string, boolFlags map[string]bool, intFlags map[string]int) *common.RuntimeContext {
-	return newBaseTestRuntimeWithArraysAndSlices(stringFlags, nil, stringSliceFlags, boolFlags, intFlags)
-}
-
-func newBaseTestRuntimeWithArraysAndSlices(stringFlags map[string]string, stringArrayFlags map[string][]string, stringSliceFlags map[string][]string, boolFlags map[string]bool, intFlags map[string]int) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "test"}
 	for name := range stringFlags {
 		cmd.Flags().String(name, "", "")
@@ -43,9 +35,6 @@ func newBaseTestRuntimeWithArraysAndSlices(stringFlags map[string]string, string
 	for name := range stringArrayFlags {
 		cmd.Flags().StringArray(name, nil, "")
 	}
-	for name := range stringSliceFlags {
-		cmd.Flags().StringSlice(name, nil, "")
-	}
 	for name := range boolFlags {
 		cmd.Flags().Bool(name, false, "")
 	}
@@ -61,11 +50,6 @@ func newBaseTestRuntimeWithArraysAndSlices(stringFlags map[string]string, string
 			_ = cmd.Flags().Set(name, value)
 		}
 	}
-	for name, values := range stringSliceFlags {
-		for _, value := range values {
-			_ = cmd.Flags().Set(name, value)
-		}
-	}
 	for name, value := range boolFlags {
 		if value {
 			_ = cmd.Flags().Set(name, "true")
@@ -561,8 +545,6 @@ func TestBaseDashboardHelpGuidesAgents(t *testing.T) {
 				"not table_id or field_id",
 				"dashboard-block-data-config.md as the SSOT",
 				"do not invent data_config from natural language",
-				"set the intended group_by.sort in the initial create request",
-				"do not create first and then issue a second update",
 				"sequentially",
 			},
 		},
@@ -843,7 +825,6 @@ func TestBaseRecordWriteHelpGuidesAgents(t *testing.T) {
 				"may use null for empty cells",
 				"use +field-list to confirm real writable fields",
 				"Batch create supports max 200 rows per call",
-				"do not immediately +record-list the same table",
 				"CellValue happy path: text/phone/url",
 				`ID-based CellValue: user/group/link fields use arrays like [{"id":"ou_xxx"}]`,
 				"lark-base-cell-value.md",

shortcuts/base/dashboard_arrange.go

@@ -23,7 +23,7 @@ var BaseDashboardArrange = common.Shortcut{
 		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
 	},
 	Tips: []string{
-		"Server-side smart layout is not deterministic or position-specific; use only when the user asks to arrange or beautify a dashboard, or to tidy up a dashboard created from scratch in this session.",
+		"Server-side smart layout is not deterministic or position-specific; use only when the user asks to arrange or beautify a dashboard.",
 	},
 	DryRun: dryRunDashboardArrange,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/dashboard_block_create.go

@@ -27,7 +27,7 @@ var BaseDashboardBlockCreate = common.Shortcut{
 		{Name: "type", Desc: "block type: column(柱状图)|bar(条形图)|line(折线图)|pie(饼图)|ring(环形图)|area(面积图)|combo(组合图)|scatter(散点图)|funnel(漏斗图)|wordCloud(词云)|radar(雷达图)|statistics(指标卡)|text(文本). Read dashboard-block-data-config.md before creating.", Required: true},
 		{Name: "data-config", Desc: "data_config JSON object; read dashboard-block-data-config.md for the SSOT"},
 		{Name: "user-id-type", Desc: "user ID type for user fields in filters: open_id / union_id / user_id"},
-		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation and normalization; send data_config as-is"},
+		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},
 	},
 	Tips: []string{
 		`lark-cli base +dashboard-block-create --base-token <base_token> --dashboard-id <dashboard_id> --name "Order Count" --type statistics --data-config '{"table_name":"Orders","count_all":true}'`,
@@ -35,7 +35,6 @@ var BaseDashboardBlockCreate = common.Shortcut{
 		"Before creating data-backed blocks, use +table-list and +field-list to confirm real table and field names.",
 		"data_config uses table and field names, not table_id or field_id.",
 		"Read dashboard-block-data-config.md as the SSOT for chart templates, filters, metric rules, and type-specific fields; do not invent data_config from natural language.",
-		"For funnel/stage charts backed by ordered helper data, set the intended group_by.sort in the initial create request; do not create first and then issue a second update just to fix sorting.",
 		"Record the returned block_id; block update/delete/get-data commands need it.",
 		"Create dashboard blocks sequentially; do not parallelize multiple block creates for the same dashboard.",
 	},

shortcuts/base/dashboard_block_get_data.go

@@ -20,7 +20,6 @@ var BaseDashboardBlockGetData = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		blockIDFlag(true),
-		{Name: "dashboard-id", Desc: "hidden compatibility flag accepted by dashboard block commands; ignored by get-data", Hidden: true},
 	},
 	Tips: []string{
 		"lark-cli base +dashboard-block-get-data --base-token <base_token> --block-id <block_id>",

shortcuts/base/dashboard_block_update.go

@@ -26,7 +26,7 @@ var BaseDashboardBlockUpdate = common.Shortcut{
 		{Name: "name", Desc: "new block name"},
 		{Name: "data-config", Desc: "data_config JSON object; read dashboard-block-data-config.md for the SSOT"},
 		{Name: "user-id-type", Desc: "user ID type for user fields in filters: open_id / union_id / user_id"},
-		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation and normalization; send data_config as-is"},
+		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},
 	},
 	Tips: []string{
 		`lark-cli base +dashboard-block-update --base-token <base_token> --dashboard-id <dashboard_id> --block-id <block_id> --name "Total Sales"`,

shortcuts/base/helpers.go

@@ -1038,23 +1038,11 @@ func normalizeDataConfig(cfg map[string]interface{}) map[string]interface{} {
 					m["mode"] = strings.ToLower(strings.TrimSpace(md))
 				}
 				if sub, ok := m["sort"].(map[string]interface{}); ok {
-					sortType := ""
 					if t, ok := sub["type"].(string); ok {
-						sortType = strings.ToLower(strings.TrimSpace(t))
-						sub["type"] = sortType
+						sub["type"] = strings.ToLower(strings.TrimSpace(t))
 					}
-					// Only lowercase a string order; leave a present-but-non-string
-					// order untouched so validateBlockDataConfig can reject it
-					// instead of it being silently coerced below.
-					_, hasOrderKey := sub["order"]
-					orderStr, orderIsString := sub["order"].(string)
-					if orderIsString {
-						sub["order"] = strings.ToLower(strings.TrimSpace(orderStr))
-					}
-					// Default only when the order key is truly absent. A present
-					// key (even an illegal type/value) must survive to validation.
-					if !hasOrderKey && (sortType == "group" || sortType == "view") {
-						sub["order"] = "asc"
+					if o, ok := sub["order"].(string); ok {
+						sub["order"] = strings.ToLower(strings.TrimSpace(o))
 					}
 					m["sort"] = sub
 				}
@@ -1138,16 +1126,12 @@ func validateBlockDataConfig(blockType string, cfg map[string]interface{}) []str
 			if sub, ok := m["sort"].(map[string]interface{}); ok {
 				t, _ := sub["type"].(string)
 				t = strings.ToLower(strings.TrimSpace(t))
+				o, _ := sub["order"].(string)
+				o = strings.ToLower(strings.TrimSpace(o))
 				if t != "group" && t != "value" && t != "view" {
 					errs = append(errs, fmt.Sprintf("group_by[%d].sort.type 仅支持 group|value|view", i))
 				}
-				orderRaw, hasOrder := sub["order"]
-				o, orderIsString := orderRaw.(string)
-				o = strings.ToLower(strings.TrimSpace(o))
-				switch {
-				case !hasOrder:
-					errs = append(errs, fmt.Sprintf("group_by[%d].sort.order 缺失；sort 存在时必须设置 order 为 asc 或 desc，例如 \"sort\":{\"type\":\"group\",\"order\":\"asc\"}", i))
-				case !orderIsString || (o != "asc" && o != "desc"):
+				if o != "asc" && o != "desc" {
 					errs = append(errs, fmt.Sprintf("group_by[%d].sort.order 仅支持 asc|desc", i))
 				}
 			}
@@ -1194,5 +1178,5 @@ func formatDataConfigErrors(problems []string) error {
 	if len(problems) == 0 {
 		return nil
 	}
-	return errs.NewValidationError(errs.SubtypeInvalidArgument, "data_config 校验失败:\n- %s\n参考: skills/lark-base/references/dashboard-block-data-config.md", strings.Join(problems, "\n- ")).WithParam("--data-config")
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "data_config 校验失败:\n- %s\n参考: skills/lark-base/references/dashboard-block-data-config.md", strings.Join(problems, "\n- "))
 }

shortcuts/base/record_batch_create.go

@@ -25,7 +25,6 @@ var BaseRecordBatchCreate = common.Shortcut{
 		"Happy path fields: fields is the column order; rows is an array of row arrays; each row must match fields order and may use null for empty cells.",
 		"Before writing, use +field-list to confirm real writable fields; do not write system fields, formula, lookup, or attachment fields as normal CellValue.",
 		"Batch create supports max 200 rows per call.",
-		"After batch-creating known helper rows, use the returned record IDs and your submitted rows; do not immediately +record-list the same table unless you need server-normalized formula/lookup values or failure diagnosis.",
 		"Use the record-batch-create guide for command limits and edge cases.",
 	}, recordCellValueHappyPathTips...),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/record_list.go

@@ -21,7 +21,6 @@ var BaseRecordList = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		recordListFieldRefFlag(),
-		recordListFieldNamesAliasFlag(),
 		recordListViewRefFlag(),
 		recordFilterFlag(),
 		recordSortFlag(),
@@ -44,9 +43,6 @@ var BaseRecordList = common.Shortcut{
 		"Use --field-id repeatedly to keep output small and aligned with the task.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if err := validateRecordListFieldAlias(runtime); err != nil {
-			return err
-		}
 		if err := validateRecordReadFormat(runtime); err != nil {
 			return err
 		}
@@ -79,15 +75,6 @@ func recordListFieldRefFlag() common.Flag {
 	return flag
 }
 
-func recordListFieldNamesAliasFlag() common.Flag {
-	return common.Flag{
-		Name:   "field-names",
-		Type:   "string_slice",
-		Desc:   "hidden alias for --field-id; accepts comma-separated field names",
-		Hidden: true,
-	}
-}
-
 func recordListViewRefFlag() common.Flag {
 	flag := viewRefFlag(false)
 	flag.Desc = "view ID or name; omit for reading all table records, or set to read a user-specified or temporary filtered/sorted view"
@@ -102,10 +89,3 @@ func recordReadFormatFlag() common.Flag {
 		Desc:    "output format: markdown (default) | json",
 	}
 }
-
-func validateRecordListFieldAlias(runtime *common.RuntimeContext) error {
-	if runtime.Changed("field-id") && runtime.Changed("field-names") {
-		return baseFlagErrorf("--field-id and --field-names are mutually exclusive; use --field-id")
-	}
-	return nil
-}

shortcuts/base/record_ops.go

@@ -376,9 +376,6 @@ func validateRecordJSON(runtime *common.RuntimeContext) error {
 }
 
 func recordListFields(runtime *common.RuntimeContext) []string {
-	if runtime.Changed("field-names") {
-		return runtime.StrSlice("field-names")
-	}
 	return runtime.StrArray("field-id")
 }
 

shortcuts/common/extract.go

@@ -22,23 +22,15 @@ func GetString(m map[string]interface{}, keys ...string) string {
 
 // GetFloat safely extracts a float64 (the default JSON number type).
 func GetFloat(m map[string]interface{}, keys ...string) float64 {
-	f, _ := GetFloatOK(m, keys...)
-	return f
-}
-
-// GetFloatOK extracts a float64 and reports whether the field was present and
-// numeric. Use it for protocol discriminators where silently turning malformed
-// input into zero could misclassify a response as successful.
-func GetFloatOK(m map[string]interface{}, keys ...string) (float64, bool) {
 	if len(keys) == 0 {
-		return 0, false
+		return 0
 	}
 	v := navigate(m, keys[:len(keys)-1])
 	if v == nil {
-		return 0, false
+		return 0
 	}
-	f, ok := util.ToFloat64(v[keys[len(keys)-1]])
-	return f, ok
+	f, _ := util.ToFloat64(v[keys[len(keys)-1]])
+	return f
 }
 
 // GetInt safely extracts an int, accepting both in-memory ints and JSON-style float64 values.

shortcuts/common/extract_test.go

@@ -64,24 +64,6 @@ func TestGetFloat(t *testing.T) {
 	}
 }
 
-func TestGetFloatOKDistinguishesMalformedValuesFromZero(t *testing.T) {
-	t.Parallel()
-
-	m := map[string]interface{}{
-		"zero":   float64(0),
-		"null":   nil,
-		"string": "0",
-	}
-	if got, ok := GetFloatOK(m, "zero"); !ok || got != 0 {
-		t.Fatalf("GetFloatOK(zero) = (%v, %t), want (0, true)", got, ok)
-	}
-	for _, key := range []string{"null", "string", "missing"} {
-		if got, ok := GetFloatOK(m, key); ok || got != 0 {
-			t.Fatalf("GetFloatOK(%s) = (%v, %t), want (0, false)", key, got, ok)
-		}
-	}
-}
-
 func TestGetInt(t *testing.T) {
 	m := map[string]interface{}{
 		"count":      42,

shortcuts/drive/drive_permission_get_setting.go

@@ -0,0 +1,227 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/url"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type drivePermissionGetSettingSpec struct {
+	Token string
+	Type  string
+}
+
+var drivePermissionGetSettingTypes = []string{
+	"doc", "sheet", "file", "wiki", "bitable", "docx",
+	"mindnote", "minutes", "slides", "folder",
+}
+
+var drivePermissionGetSettingURLPathToType = []struct {
+	Prefix string
+	Type   string
+}{
+	{"/drive/folder/", "folder"},
+	{"/docx/", "docx"},
+	{"/doc/", "doc"},
+	{"/docs/", "doc"},
+	{"/sheets/", "sheet"},
+	{"/base/", "bitable"},
+	{"/bitable/", "bitable"},
+	{"/wiki/", "wiki"},
+	{"/file/", "file"},
+	{"/mindnotes/", "mindnote"},
+	{"/slides/", "slides"},
+	{"/minutes/", "minutes"},
+}
+
+func readDrivePermissionGetSettingSpec(runtime *common.RuntimeContext) (drivePermissionGetSettingSpec, error) {
+	rawToken := strings.TrimSpace(runtime.Str("token"))
+	explicitType := strings.ToLower(strings.TrimSpace(runtime.Str("type")))
+
+	if rawToken == "" {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--token is required",
+		).WithParam("--token")
+	}
+
+	if explicitType != "" && !drivePermissionGetSettingTypeAllowed(explicitType) {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"invalid --type %q: allowed values are %s",
+			explicitType,
+			strings.Join(drivePermissionGetSettingTypes, ", "),
+		).WithParam("--type")
+	}
+
+	if strings.Contains(rawToken, "://") {
+		ref, ok := parseDrivePermissionGetSettingResourceURL(rawToken)
+		if !ok {
+			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"unsupported --token URL %q: pass a recognized Lark Drive document/folder URL or a bare token with --type",
+				rawToken,
+			).WithParam("--token")
+		}
+		if explicitType != "" && explicitType != ref.Type {
+			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"--type %q conflicts with URL path type %q; remove --type or use a matching value",
+				explicitType,
+				ref.Type,
+			).WithParam("--type")
+		}
+		if err := validate.ResourceName(ref.Token, "--token"); err != nil {
+			return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+		}
+		return drivePermissionGetSettingSpec{Token: ref.Token, Type: ref.Type}, nil
+	}
+
+	if explicitType == "" {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--type is required when --token is a bare token (allowed: %s)",
+			strings.Join(drivePermissionGetSettingTypes, ", "),
+		).WithParam("--type")
+	}
+
+	if err := validate.ResourceName(rawToken, "--token"); err != nil {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+	}
+	return drivePermissionGetSettingSpec{Token: rawToken, Type: explicitType}, nil
+}
+
+func parseDrivePermissionGetSettingResourceURL(rawURL string) (common.ResourceRef, bool) {
+	parsed, err := url.Parse(strings.TrimSpace(rawURL))
+	if err != nil || parsed.Hostname() == "" {
+		return common.ResourceRef{}, false
+	}
+
+	for _, mapping := range drivePermissionGetSettingURLPathToType {
+		if !strings.HasPrefix(parsed.Path, mapping.Prefix) {
+			continue
+		}
+		token := parsed.Path[len(mapping.Prefix):]
+		token = strings.TrimRight(token, "/")
+		if idx := strings.IndexByte(token, '/'); idx >= 0 {
+			token = token[:idx]
+		}
+		token = strings.TrimSpace(token)
+		if token == "" {
+			return common.ResourceRef{}, false
+		}
+		return common.ResourceRef{Type: mapping.Type, Token: token}, true
+	}
+
+	return common.ResourceRef{}, false
+}
+
+func drivePermissionGetSettingTypeAllowed(docType string) bool {
+	for _, allowed := range drivePermissionGetSettingTypes {
+		if docType == allowed {
+			return true
+		}
+	}
+	return false
+}
+
+func (s drivePermissionGetSettingSpec) url(runtime *common.RuntimeContext) string {
+	if runtime != nil && runtime.Config != nil {
+		if u := common.BuildResourceURL(runtime.Config.Brand, s.Type, s.Token); u != "" {
+			return u
+		}
+	}
+	return common.BuildResourceURL("", s.Type, s.Token)
+}
+
+func (s drivePermissionGetSettingSpec) params() map[string]interface{} {
+	return map[string]interface{}{"type": s.Type}
+}
+
+func (s drivePermissionGetSettingSpec) apiPath() string {
+	return drivePermissionPublicV2Path(s.Token)
+}
+
+func drivePermissionPublicV2Path(token string) string {
+	return fmt.Sprintf("/open-apis/drive/v2/permissions/%s/public", validate.EncodePathSegment(token))
+}
+
+func (s drivePermissionGetSettingSpec) output(runtime *common.RuntimeContext, data map[string]interface{}) map[string]interface{} {
+	permissionPublic := interface{}(data)
+	if nestedPermissionPublic := common.GetMap(data, "permission_public"); nestedPermissionPublic != nil {
+		permissionPublic = nestedPermissionPublic
+	}
+	return map[string]interface{}{
+		"permission_public": permissionPublic,
+	}
+}
+
+// DrivePermissionGetSetting queries permission_public settings for a Drive
+// document, file, wiki node, or folder.
+var DrivePermissionGetSetting = common.Shortcut{
+	Service:     "drive",
+	Command:     "+permission-get-setting",
+	Description: "Get public access, sharing, collaborator management, security, and comment permission settings",
+	Risk:        "read",
+	Scopes:      []string{"docs:permission.setting:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "token", Desc: "target URL or bare token (doc/sheet/file/wiki/bitable/docx/mindnote/minutes/slides/folder)"},
+		{Name: "type", Desc: "target type; auto-inferred from URL, required for bare tokens", Enum: drivePermissionGetSettingTypes},
+	},
+	Tips: []string{
+		"--token accepts a Lark URL or bare token; pass --type when using a bare token.",
+		"Use --type folder for Drive folders. This shortcut reads the target's own permission settings; it does not recurse into child documents.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := readDrivePermissionGetSettingSpec(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec, err := readDrivePermissionGetSettingSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			Desc("Get Drive permission settings").
+			GET(spec.apiPath()).
+			Params(spec.params())
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec, err := readDrivePermissionGetSettingSpec(runtime)
+		if err != nil {
+			return err
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Getting permission settings for %s %s...\n", spec.Type, common.MaskToken(spec.Token))
+		data, err := runtime.CallAPITyped(
+			"GET",
+			spec.apiPath(),
+			spec.params(),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+
+		out := spec.output(runtime, data)
+		runtime.OutFormat(out, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Type:  %s\n", spec.Type)
+			fmt.Fprintf(w, "Token: %s\n", spec.Token)
+			if url := spec.url(runtime); url != "" {
+				fmt.Fprintf(w, "URL:   %s\n", url)
+			}
+		})
+		return nil
+	},
+}

shortcuts/drive/drive_permission_get_setting_test.go

@@ -0,0 +1,371 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func newDrivePermissionGetSettingRuntime(t *testing.T, token, docType string) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "drive +permission-get-setting"}
+	cmd.Flags().String("token", "", "")
+	cmd.Flags().String("type", "", "")
+	if token != "" {
+		if err := cmd.Flags().Set("token", token); err != nil {
+			t.Fatalf("set --token: %v", err)
+		}
+	}
+	if docType != "" {
+		if err := cmd.Flags().Set("type", docType); err != nil {
+			t.Fatalf("set --type: %v", err)
+		}
+	}
+	return common.TestNewRuntimeContext(cmd, driveTestConfig())
+}
+
+func TestDrivePermissionGetSettingSpecResolvesTargets(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		token    string
+		docType  string
+		wantTok  string
+		wantType string
+	}{
+		{
+			name:     "folder URL",
+			token:    "https://example.feishu.cn/drive/folder/fldTok?from=share",
+			wantTok:  "fldTok",
+			wantType: "folder",
+		},
+		{
+			name:     "docx URL",
+			token:    "https://example.feishu.cn/docx/doxTok",
+			wantTok:  "doxTok",
+			wantType: "docx",
+		},
+		{
+			name:     "legacy doc URL",
+			token:    "https://example.feishu.cn/doc/docTok",
+			wantTok:  "docTok",
+			wantType: "doc",
+		},
+		{
+			name:     "file URL",
+			token:    "https://example.feishu.cn/file/boxTok",
+			wantTok:  "boxTok",
+			wantType: "file",
+		},
+		{
+			name:     "wiki URL",
+			token:    "https://example.feishu.cn/wiki/wikTok",
+			wantTok:  "wikTok",
+			wantType: "wiki",
+		},
+		{
+			name:     "minutes URL",
+			token:    "https://example.feishu.cn/minutes/obTok",
+			wantTok:  "obTok",
+			wantType: "minutes",
+		},
+		{
+			name:     "mindnotes URL",
+			token:    "https://example.feishu.cn/mindnotes/mndTok",
+			wantTok:  "mndTok",
+			wantType: "mindnote",
+		},
+		{
+			name:     "bare folder token",
+			token:    " fldTok ",
+			docType:  " folder ",
+			wantTok:  "fldTok",
+			wantType: "folder",
+		},
+		{
+			name:     "bare file token",
+			token:    "boxTok",
+			docType:  "file",
+			wantTok:  "boxTok",
+			wantType: "file",
+		},
+		{
+			name:     "bare wiki token",
+			token:    "wikTok",
+			docType:  "wiki",
+			wantTok:  "wikTok",
+			wantType: "wiki",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
+			spec, err := readDrivePermissionGetSettingSpec(runtime)
+			if err != nil {
+				t.Fatalf("read spec: %v", err)
+			}
+			if spec.Token != tt.wantTok {
+				t.Fatalf("Token = %q, want %q", spec.Token, tt.wantTok)
+			}
+			if spec.Type != tt.wantType {
+				t.Fatalf("Type = %q, want %q", spec.Type, tt.wantType)
+			}
+		})
+	}
+}
+
+func TestDrivePermissionGetSettingSpecValidationErrorsAreTyped(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		token       string
+		docType     string
+		wantParam   string
+		wantMessage string
+	}{
+		{
+			name:        "missing token",
+			wantParam:   "--token",
+			wantMessage: "--token is required",
+		},
+		{
+			name:        "bare token without type",
+			token:       "doxTok",
+			wantParam:   "--type",
+			wantMessage: "--type is required",
+		},
+		{
+			name:        "unsupported URL",
+			token:       "https://example.feishu.cn/calendar/calTok",
+			wantParam:   "--token",
+			wantMessage: "unsupported --token URL",
+		},
+		{
+			name:        "URL type conflict",
+			token:       "https://example.feishu.cn/docx/doxTok",
+			docType:     "sheet",
+			wantParam:   "--type",
+			wantMessage: "conflicts with URL path type",
+		},
+		{
+			name:        "invalid bare token",
+			token:       "../bad",
+			docType:     "folder",
+			wantParam:   "--token",
+			wantMessage: "--token",
+		},
+		{
+			name:        "invalid type",
+			token:       "doxTok",
+			docType:     "comment",
+			wantParam:   "--type",
+			wantMessage: "invalid --type",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
+			_, err := readDrivePermissionGetSettingSpec(runtime)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %v", err, err)
+			}
+			if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("problem = %s/%s, want validation/invalid_argument", problem.Category, problem.Subtype)
+			}
+			if validationErr, ok := err.(*errs.ValidationError); ok {
+				if validationErr.Param != tt.wantParam {
+					t.Fatalf("param = %q, want %q", validationErr.Param, tt.wantParam)
+				}
+			} else {
+				t.Fatalf("error type = %T, want *errs.ValidationError", err)
+			}
+			if !strings.Contains(err.Error(), tt.wantMessage) {
+				t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantMessage)
+			}
+		})
+	}
+}
+
+func TestDrivePermissionGetSettingDryRunIncludesGETRequest(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		token    string
+		docType  string
+		wantURL  string
+		wantType string
+	}{
+		{
+			name:     "folder URL",
+			token:    "https://example.feishu.cn/drive/folder/fldTok",
+			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
+			wantType: "folder",
+		},
+		{
+			name:     "bare folder token",
+			token:    "fldTok",
+			docType:  "folder",
+			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
+			wantType: "folder",
+		},
+		{
+			name:     "docx URL",
+			token:    "https://example.feishu.cn/docx/doxTok",
+			wantURL:  "/open-apis/drive/v2/permissions/doxTok/public",
+			wantType: "docx",
+		},
+		{
+			name:     "bare wiki token",
+			token:    "wikTok",
+			docType:  "wiki",
+			wantURL:  "/open-apis/drive/v2/permissions/wikTok/public",
+			wantType: "wiki",
+		},
+		{
+			name:     "file URL",
+			token:    "https://example.feishu.cn/file/boxTok",
+			wantURL:  "/open-apis/drive/v2/permissions/boxTok/public",
+			wantType: "file",
+		},
+		{
+			name:     "minutes URL",
+			token:    "https://example.feishu.cn/minutes/obTok",
+			wantURL:  "/open-apis/drive/v2/permissions/obTok/public",
+			wantType: "minutes",
+		},
+		{
+			name:     "mindnotes URL",
+			token:    "https://example.feishu.cn/mindnotes/mndTok",
+			wantURL:  "/open-apis/drive/v2/permissions/mndTok/public",
+			wantType: "mindnote",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
+			dry := DrivePermissionGetSetting.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)
+			}
+			out := string(data)
+			for _, want := range []string{
+				`"` + tt.wantURL + `"`,
+				`"GET"`,
+				`"type":"` + tt.wantType + `"`,
+			} {
+				if !strings.Contains(out, want) {
+					t.Fatalf("dry-run output missing %q:\n%s", want, out)
+				}
+			}
+			if strings.Contains(out, `"folder_token"`) {
+				t.Fatalf("dry-run output contains folder_token, want omitted:\n%s", out)
+			}
+		})
+	}
+}
+
+func TestDrivePermissionGetSettingExecutePreservesPermissionPublic(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v2/permissions/doxTok/public?type=docx",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"permission_public": map[string]interface{}{
+					"link_share_entity":          "closed",
+					"external_access_entity":     "closed",
+					"security_entity":            "anyone_can_view",
+					"comment_entity":             "anyone_can_view",
+					"share_entity":               "anyone",
+					"manage_collaborator_entity": "collaborator_can_view",
+					"lock_switch":                false,
+					"server_future_field":        "preserved",
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePermissionGetSetting, []string{
+		"+permission-get-setting",
+		"--token", "doxTok",
+		"--type", "docx",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	for _, key := range []string{"type", "token", "url"} {
+		if _, ok := data[key]; ok {
+			t.Fatalf("data[%s] = %#v, want field omitted", key, data[key])
+		}
+	}
+	permissionPublic, _ := data["permission_public"].(map[string]interface{})
+	if permissionPublic == nil {
+		t.Fatalf("permission_public missing in output: %#v", data)
+	}
+	for key, want := range map[string]interface{}{
+		"link_share_entity":          "closed",
+		"external_access_entity":     "closed",
+		"security_entity":            "anyone_can_view",
+		"comment_entity":             "anyone_can_view",
+		"share_entity":               "anyone",
+		"manage_collaborator_entity": "collaborator_can_view",
+		"lock_switch":                false,
+		"server_future_field":        "preserved",
+	} {
+		if permissionPublic[key] != want {
+			t.Fatalf("permission_public[%s] = %#v, want %#v", key, permissionPublic[key], want)
+		}
+	}
+}
+
+func TestDrivePermissionGetSettingDeclaresScopeAndIdentities(t *testing.T) {
+	t.Parallel()
+
+	if !reflect.DeepEqual(DrivePermissionGetSetting.Scopes, []string{"docs:permission.setting:read"}) {
+		t.Fatalf("Scopes = %v, want docs:permission.setting:read", DrivePermissionGetSetting.Scopes)
+	}
+	if !reflect.DeepEqual(DrivePermissionGetSetting.AuthTypes, []string{"user", "bot"}) {
+		t.Fatalf("AuthTypes = %v, want [user bot]", DrivePermissionGetSetting.AuthTypes)
+	}
+}

shortcuts/drive/drive_task_result.go

@@ -15,20 +15,12 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-const (
-	// These are fixed backend wire values for the Wiki-to-Drive task. Keep
-	// them unchanged even though the CLI scenario uses wiki_move_to_drive.
-	wikiMoveToDriveTaskType  = "move_wiki_to_docs"
-	wikiMoveToDriveResultKey = "move_wiki_to_docs_result"
-)
-
 // DriveTaskResult exposes a unified read path for the async task types produced
-// by Drive import, export, folder move/delete, wiki move, wiki move-to-drive,
-// and wiki delete flows.
+// by Drive import, export, folder move/delete, wiki move, and wiki delete-space flows.
 var DriveTaskResult = common.Shortcut{
 	Service:     "drive",
 	Command:     "+task_result",
-	Description: "Poll async task result for import, export, drive move/delete, wiki move, wiki move-to-drive, or wiki delete operations",
+	Description: "Poll async task result for import, export, drive move/delete, wiki move, wiki delete-space, or wiki delete-node operations",
 	Risk:        "read",
 	// This shortcut multiplexes multiple backend APIs with different scope
 	// requirements, so scenario-specific prechecks are handled in Validate.
@@ -36,23 +28,22 @@ var DriveTaskResult = common.Shortcut{
 	AuthTypes: []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "ticket", Desc: "async task ticket (for import/export tasks)", Required: false},
-		{Name: "task-id", Desc: "async task ID (for drive task_check and all wiki task scenarios)", Required: false},
-		{Name: "scenario", Desc: "task scenario: import, export, task_check, wiki_move, wiki_move_to_drive, wiki_delete_space, or wiki_delete_node", Required: true},
+		{Name: "task-id", Desc: "async task ID (for drive task_check, wiki_move, wiki_delete_space, or wiki_delete_node tasks)", Required: false},
+		{Name: "scenario", Desc: "task scenario: import, export, task_check, wiki_move, wiki_delete_space, or wiki_delete_node", Required: true},
 		{Name: "file-token", Desc: "source document token used for export task status lookup", Required: false},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		scenario := strings.ToLower(runtime.Str("scenario"))
 		validScenarios := map[string]bool{
-			"import":             true,
-			"export":             true,
-			"task_check":         true,
-			"wiki_move":          true,
-			"wiki_move_to_drive": true,
-			"wiki_delete_space":  true,
-			"wiki_delete_node":   true,
+			"import":            true,
+			"export":            true,
+			"task_check":        true,
+			"wiki_move":         true,
+			"wiki_delete_space": true,
+			"wiki_delete_node":  true,
 		}
 		if !validScenarios[scenario] {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported scenario: %s. Supported scenarios: import, export, task_check, wiki_move, wiki_move_to_drive, wiki_delete_space, wiki_delete_node", scenario).WithParam("--scenario")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported scenario: %s. Supported scenarios: import, export, task_check, wiki_move, wiki_delete_space, wiki_delete_node", scenario).WithParam("--scenario")
 		}
 
 		// Validate required params based on scenario
@@ -64,7 +55,7 @@ var DriveTaskResult = common.Shortcut{
 			if err := validate.ResourceName(runtime.Str("ticket"), "--ticket"); err != nil {
 				return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--ticket")
 			}
-		case "task_check", "wiki_move", "wiki_move_to_drive", "wiki_delete_space", "wiki_delete_node":
+		case "task_check", "wiki_move", "wiki_delete_space", "wiki_delete_node":
 			if runtime.Str("task-id") == "" {
 				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--task-id is required for %s scenario", scenario).WithParam("--task-id")
 			}
@@ -113,11 +104,6 @@ var DriveTaskResult = common.Shortcut{
 				Desc("[1] Query wiki move task result").
 				Set("task_id", taskID).
 				Params(map[string]interface{}{"task_type": "move"})
-		case "wiki_move_to_drive":
-			dry.GET("/open-apis/wiki/v2/tasks/:task_id").
-				Desc("[1] Query wiki move-to-drive task result").
-				Set("task_id", taskID).
-				Params(map[string]interface{}{"task_type": wikiMoveToDriveTaskType})
 		case "wiki_delete_space":
 			dry.GET("/open-apis/wiki/v2/tasks/:task_id").
 				Desc("[1] Query wiki delete-space task result").
@@ -154,8 +140,6 @@ var DriveTaskResult = common.Shortcut{
 			result, err = queryTaskCheck(runtime, taskID)
 		case "wiki_move":
 			result, err = queryWikiMoveTask(runtime, taskID)
-		case "wiki_move_to_drive":
-			result, err = queryWikiMoveToDriveTask(runtime, taskID)
 		case "wiki_delete_space":
 			result, err = queryWikiDeleteSpaceTask(runtime, taskID)
 		case "wiki_delete_node":
@@ -260,7 +244,7 @@ func validateDriveTaskResultScopes(ctx context.Context, runtime *common.RuntimeC
 	switch scenario {
 	case "import", "export", "task_check":
 		required = []string{"drive:drive.metadata:readonly"}
-	case "wiki_move", "wiki_move_to_drive", "wiki_delete_space", "wiki_delete_node":
+	case "wiki_move", "wiki_delete_space", "wiki_delete_node":
 		required = []string{"wiki:space:read"}
 	}
 
@@ -502,75 +486,6 @@ func appendWikiMoveNodeFields(out, node map[string]interface{}) {
 	out["has_child"] = common.GetBool(node, "has_child")
 }
 
-// queryWikiMoveToDriveTask returns the normalized status and final Drive
-// resource fields for wiki +move-to-drive. The task endpoint uses a dedicated
-// result object with numeric status codes: 0 success, 1 processing, -1 failure.
-func queryWikiMoveToDriveTask(runtime *common.RuntimeContext, taskID string) (map[string]interface{}, error) {
-	if err := validate.ResourceName(taskID, "--task-id"); err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--task-id").WithCause(err)
-	}
-
-	data, err := runtime.CallAPITyped(
-		"GET",
-		fmt.Sprintf("/open-apis/wiki/v2/tasks/%s", validate.EncodePathSegment(taskID)),
-		map[string]interface{}{"task_type": wikiMoveToDriveTaskType},
-		nil,
-	)
-	if err != nil {
-		return nil, err
-	}
-
-	task := common.GetMap(data, "task")
-	if task == nil {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki task response missing task")
-	}
-	result := common.GetMap(task, wikiMoveToDriveResultKey)
-	if result == nil {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki task response missing %s", wikiMoveToDriveResultKey)
-	}
-	statusCode, ok := common.GetFloatOK(result, "status")
-	if !ok {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki task response has missing or non-numeric %s.status", wikiMoveToDriveResultKey)
-	}
-	if statusCode != -1 && statusCode != 0 && statusCode != 1 {
-		return nil, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"wiki task response has unsupported %s.status: %v",
-			wikiMoveToDriveResultKey,
-			statusCode,
-		)
-	}
-
-	resolvedTaskID := common.GetString(task, "task_id")
-	if resolvedTaskID == "" {
-		resolvedTaskID = taskID
-	}
-	status := int(statusCode)
-	statusMsg := strings.TrimSpace(common.GetString(result, "status_msg"))
-	if statusMsg == "" {
-		switch {
-		case status == 0:
-			statusMsg = "success"
-		case status < 0:
-			statusMsg = "failure"
-		default:
-			statusMsg = "processing"
-		}
-	}
-
-	return map[string]interface{}{
-		"scenario":   "wiki_move_to_drive",
-		"task_id":    resolvedTaskID,
-		"ready":      status == 0,
-		"failed":     status < 0,
-		"status":     status,
-		"status_msg": statusMsg,
-		"obj_token":  common.GetString(result, "obj_token"),
-		"obj_type":   common.GetString(result, "obj_type"),
-		"url":        common.GetString(result, "url"),
-	}, nil
-}
-
 // queryWikiDeleteSpaceTask returns the normalized status of an async wiki
 // delete-space task. The backend reports a single delete_space_result object
 // rather than the per-node array used by wiki move.

shortcuts/drive/drive_task_result_test.go

@@ -66,13 +66,6 @@ func TestDriveTaskResultValidateErrorsByScenario(t *testing.T) {
 			},
 			wantErr: "--task-id is required",
 		},
-		{
-			name: "wiki move to Drive missing task id",
-			flags: map[string]string{
-				"scenario": "wiki_move_to_drive",
-			},
-			wantErr: "--task-id is required",
-		},
 	}
 
 	for _, tt := range tests {
@@ -433,174 +426,13 @@ func TestDriveTaskResultWikiMoveIncludesFlattenedNodeFields(t *testing.T) {
 	}
 }
 
-func TestDriveTaskResultDryRunWikiMoveToDriveIncludesTaskTypeParam(t *testing.T) {
-	t.Parallel()
-
-	cmd := &cobra.Command{Use: "drive +task_result"}
-	cmd.Flags().String("scenario", "", "")
-	cmd.Flags().String("ticket", "", "")
-	cmd.Flags().String("task-id", "", "")
-	cmd.Flags().String("file-token", "", "")
-	if err := cmd.Flags().Set("scenario", "wiki_move_to_drive"); err != nil {
-		t.Fatalf("set --scenario: %v", err)
-	}
-	if err := cmd.Flags().Set("task-id", "raw-task-signature"); err != nil {
-		t.Fatalf("set --task-id: %v", err)
-	}
-
-	runtime := common.TestNewRuntimeContext(cmd, nil)
-	dry := DriveTaskResult.DryRun(context.Background(), runtime)
-	if dry == nil {
-		t.Fatal("DryRun returned nil")
-	}
-
-	data, err := json.Marshal(dry)
-	if err != nil {
-		t.Fatalf("marshal dry run: %v", err)
-	}
-	var got struct {
-		API []struct {
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
-	if err := json.Unmarshal(data, &got); err != nil {
-		t.Fatalf("unmarshal dry run json: %v", err)
-	}
-	if len(got.API) != 1 || got.API[0].Params["task_type"] != "move_wiki_to_docs" {
-		t.Fatalf("wiki move-to-drive dry run = %#v", got.API)
-	}
-}
-
-func TestDriveTaskResultWikiMoveToDriveStatuses(t *testing.T) {
-	tests := []struct {
-		name       string
-		status     int
-		statusMsg  string
-		wantReady  bool
-		wantFailed bool
-	}{
-		{name: "success", status: 0, statusMsg: "success", wantReady: true},
-		{name: "processing fallback label", status: 1, wantReady: false},
-		{name: "failure", status: -1, statusMsg: "failure", wantFailed: true},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			factory, stdout, _, registry := cmdutil.TestFactory(t, driveTestConfig())
-			registry.Register(&httpmock.Stub{
-				Method: "GET",
-				URL:    "/open-apis/wiki/v2/tasks/raw-task-signature",
-				Body: map[string]interface{}{
-					"code": 0,
-					"data": map[string]interface{}{
-						"task": map[string]interface{}{
-							// The external handler may omit task.task_id, so the
-							// result must retain the signed request ID.
-							"move_wiki_to_docs_result": map[string]interface{}{
-								"status":     tt.status,
-								"status_msg": tt.statusMsg,
-								"obj_token":  "docxABC",
-								"obj_type":   "docx",
-								"url":        "https://example.feishu.cn/docx/docxABC",
-							},
-						},
-					},
-				},
-			})
-
-			err := mountAndRunDrive(t, DriveTaskResult, []string{
-				"+task_result",
-				"--scenario", "wiki_move_to_drive",
-				"--task-id", "raw-task-signature",
-				"--as", "user",
-			}, factory, stdout)
-			if err != nil {
-				t.Fatalf("mountAndRunDrive() error = %v", err)
-			}
-
-			data := decodeDriveEnvelope(t, stdout)
-			if data["scenario"] != "wiki_move_to_drive" || data["task_id"] != "raw-task-signature" {
-				t.Fatalf("unexpected envelope = %#v", data)
-			}
-			if data["ready"] != tt.wantReady || data["failed"] != tt.wantFailed {
-				t.Fatalf("readiness fields = %#v", data)
-			}
-			if tt.statusMsg == "" && data["status_msg"] != "processing" {
-				t.Fatalf("status_msg = %#v, want processing fallback", data["status_msg"])
-			}
-			if data["obj_token"] != "docxABC" || data["obj_type"] != "docx" || data["url"] == "" {
-				t.Fatalf("result fields = %#v", data)
-			}
-		})
-	}
-}
-
-func TestDriveTaskResultWikiMoveToDriveRejectsMissingResult(t *testing.T) {
-	factory, stdout, _, registry := cmdutil.TestFactory(t, driveTestConfig())
-	registry.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/wiki/v2/tasks/raw-task-signature",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{"task": map[string]interface{}{}},
-		},
-	})
-
-	err := mountAndRunDrive(t, DriveTaskResult, []string{
-		"+task_result",
-		"--scenario", "wiki_move_to_drive",
-		"--task-id", "raw-task-signature",
-		"--as", "user",
-	}, factory, stdout)
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeInvalidResponse {
-		t.Fatalf("error = %T %v, want internal/invalid_response", err, err)
-	}
-}
-
-func TestDriveTaskResultWikiMoveToDriveRejectsMalformedStatus(t *testing.T) {
-	for name, rawStatus := range map[string]interface{}{
-		"null":          nil,
-		"string":        "processing",
-		"fractional":    0.5,
-		"unknown value": 2,
-	} {
-		t.Run(name, func(t *testing.T) {
-			factory, stdout, _, registry := cmdutil.TestFactory(t, driveTestConfig())
-			registry.Register(&httpmock.Stub{
-				Method: "GET",
-				URL:    "/open-apis/wiki/v2/tasks/raw-task-signature",
-				Body: map[string]interface{}{
-					"code": 0,
-					"data": map[string]interface{}{
-						"task": map[string]interface{}{
-							"move_wiki_to_docs_result": map[string]interface{}{"status": rawStatus},
-						},
-					},
-				},
-			})
-
-			err := mountAndRunDrive(t, DriveTaskResult, []string{
-				"+task_result",
-				"--scenario", "wiki_move_to_drive",
-				"--task-id", "raw-task-signature",
-				"--as", "user",
-			}, factory, stdout)
-			problem, ok := errs.ProblemOf(err)
-			if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeInvalidResponse {
-				t.Fatalf("error = %T %v, want internal/invalid_response", err, err)
-			}
-		})
-	}
-}
-
 func TestValidateDriveTaskResultScopesWikiScenariosRequireWikiScope(t *testing.T) {
 	t.Parallel()
 
-	// Every Wiki scenario reads Wiki task status, so all must require
-	// wiki:space:read. A single table keeps this invariant explicit without
-	// duplicating near-identical test functions.
-	for _, scenario := range []string{"wiki_move", "wiki_move_to_drive", "wiki_delete_space", "wiki_delete_node"} {
+	// wiki_move, wiki_delete_space and wiki_delete_node all read wiki task
+	// status, so all must require wiki:space:read. A single table keeps this
+	// invariant explicit without duplicating near-identical test functions.
+	for _, scenario := range []string{"wiki_move", "wiki_delete_space", "wiki_delete_node"} {
 		t.Run(scenario+"/rejects missing scope", func(t *testing.T) {
 			t.Parallel()
 			runtime := newDriveTaskResultRuntimeWithScopes(t, core.AsUser, "drive:drive.metadata:readonly")

shortcuts/drive/shortcuts.go

@@ -32,6 +32,7 @@ func Shortcuts() []common.Shortcut {
 		DriveTaskResult,
 		DriveApplyPermission,
 		DriveMemberAdd,
+		DrivePermissionGetSetting,
 		DriveSecureLabelList,
 		DriveSecureLabelUpdate,
 		DriveSearch,

shortcuts/drive/shortcuts_test.go

@@ -38,6 +38,7 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+task_result",
 		"+apply-permission",
 		"+member-add",
+		"+permission-get-setting",
 		"+secure-label-list",
 		"+secure-label-update",
 		"+search",

shortcuts/slides/slides_screenshot.go

@@ -22,10 +22,7 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-const (
-	defaultSlidesScreenshotDir = ".lark-slides/screenshots"
-	maxSlidesPerScreenshot     = 10
-)
+const defaultSlidesScreenshotDir = ".lark-slides/screenshots"
 
 var unsafeScreenshotFileCharRegex = regexp.MustCompile(`[^A-Za-z0-9._-]+`)
 
@@ -35,7 +32,7 @@ var unsafeScreenshotFileCharRegex = regexp.MustCompile(`[^A-Za-z0-9._-]+`)
 var SlidesScreenshot = common.Shortcut{
 	Service:     "slides",
 	Command:     "+screenshot",
-	Description: "Save up to 10 slide screenshots to local files without printing Base64 image data",
+	Description: "Save slide screenshots to local files without printing Base64 image data",
 	Risk:        "read",
 	Scopes:      []string{},
 	// The screenshot API is allowlist-gated for only a few apps, so do not
@@ -45,8 +42,8 @@ var SlidesScreenshot = common.Shortcut{
 	AuthTypes:         []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides; list mode only"},
-		{Name: "slide-id", Type: "string_array", Desc: "slide page identifier (repeat for multiple slides; max 10 pages per request)"},
-		{Name: "slide-number", Type: "int_array", Desc: "slide page number (repeat for multiple slides; max 10 pages per request)"},
+		{Name: "slide-id", Type: "string_array", Desc: "slide page identifier (repeat for multiple slides)"},
+		{Name: "slide-number", Type: "int_array", Desc: "slide page number (repeat for multiple slides)"},
 		{Name: "content", Desc: "slide XML content to render directly instead of fetching existing slides", Input: []string{common.File, common.Stdin}},
 		{Name: "output-dir", Default: defaultSlidesScreenshotDir, Desc: "relative directory for saved screenshots"},
 		{Name: "output-name", Desc: "file name stem for --content render output"},
@@ -73,17 +70,12 @@ var SlidesScreenshot = common.Shortcut{
 					return err
 				}
 			}
-			slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
-			slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
-			if err != nil {
+			if _, err := normalizeSlideNumbers(runtime.IntArray("slide-number")); err != nil {
 				return err
 			}
-			if len(slideIDs) == 0 && len(slideNumbers) == 0 {
+			if !hasSlideScreenshotSelector(runtime) {
 				return slidesScreenshotFlagErrorf("--slide-id or --slide-number is required")
 			}
-			if err := validateSlidesScreenshotSelectorLimit(len(slideIDs) + len(slideNumbers)); err != nil {
-				return err
-			}
 		}
 		if _, err := validateScreenshotOutputDir(runtime, runtime.Str("output-dir")); err != nil {
 			return err
@@ -106,9 +98,6 @@ var SlidesScreenshot = common.Shortcut{
 		if len(slideIDs) == 0 && len(slideNumbers) == 0 {
 			return common.NewDryRunAPI().Set("error", "--slide-id or --slide-number is required")
 		}
-		if err := validateSlidesScreenshotSelectorLimit(len(slideIDs) + len(slideNumbers)); err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
-		}
 
 		presentationID := ref.Token
 		dry := common.NewDryRunAPI()
@@ -156,9 +145,6 @@ var SlidesScreenshot = common.Shortcut{
 		if len(slideIDs) == 0 && len(slideNumbers) == 0 {
 			return slidesScreenshotFlagErrorf("--slide-id or --slide-number is required")
 		}
-		if err := validateSlidesScreenshotSelectorLimit(len(slideIDs) + len(slideNumbers)); err != nil {
-			return err
-		}
 		outputDir := runtime.Str("output-dir")
 		safeOutputDir, err := ensureScreenshotOutputDir(runtime, outputDir)
 		if err != nil {
@@ -281,12 +267,8 @@ func normalizeSlideNumbers(values []int) ([]int, error) {
 	return out, nil
 }
 
-func validateSlidesScreenshotSelectorLimit(count int) error {
-	if count > maxSlidesPerScreenshot {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "too many slide selectors: got %d, maximum is %d", count, maxSlidesPerScreenshot).
-			WithHint("request at most 10 pages at a time")
-	}
-	return nil
+func hasSlideScreenshotSelector(runtime *common.RuntimeContext) bool {
+	return len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0
 }
 
 func slidesScreenshotFlagErrorf(format string, args ...interface{}) error {

shortcuts/slides/slides_screenshot_test.go

@@ -271,37 +271,6 @@ func TestSlidesScreenshotListRequiresSelector(t *testing.T) {
 	}
 }
 
-func TestSlidesScreenshotListRejectsMoreThanTenSelectors(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-
-	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
-		"+screenshot",
-		"--presentation", "pres_abc",
-		"--slide-number", "1",
-		"--slide-number", "2",
-		"--slide-number", "3",
-		"--slide-number", "4",
-		"--slide-number", "5",
-		"--slide-number", "6",
-		"--slide-number", "7",
-		"--slide-number", "8",
-		"--slide-number", "9",
-		"--slide-number", "10",
-		"--slide-number", "11",
-		"--as", "user",
-	})
-	if err == nil {
-		t.Fatal("expected error")
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("error = %v, want typed validation error", err)
-	}
-	if problem.Hint != "request at most 10 pages at a time" {
-		t.Fatalf("hint = %q, want max 10 pages guidance", problem.Hint)
-	}
-}
-
 func TestSlidesScreenshotRenderContentWritesFile(t *testing.T) {
 	dir := t.TempDir()
 	withSlidesTestWorkingDir(t, dir)

shortcuts/slides/slides_xml_get.go

@@ -15,14 +15,12 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// SlidesXMLGet fetches the full XML presentation content. When --output is
-// provided it writes to a local file; otherwise it returns the XML in the
-// standard JSON envelope. Use --slide-id or --slide-number to fetch one page,
-// and use --raw for direct XML stdout.
+// SlidesXMLGet fetches the full XML presentation content and writes it to a
+// local file, keeping the terminal output small for large decks.
 var SlidesXMLGet = common.Shortcut{
 	Service:     "slides",
 	Command:     "+xml-get",
-	Description: "Fetch presentation XML or one slide XML",
+	Description: "Fetch full presentation XML and save it to a local file",
 	Risk:        "read",
 	Scopes:      []string{"slides:presentation:read"},
 	// wiki:node:read is required only when --presentation is a wiki URL.
@@ -30,10 +28,7 @@ var SlidesXMLGet = common.Shortcut{
 	AuthTypes:         []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
-		{Name: "output", Desc: "local XML output path; must be a relative path within the current directory; existing file is overwritten; omit to return XML in the JSON envelope"},
-		{Name: "raw", Type: "bool", Desc: "print raw XML to stdout instead of the JSON envelope; incompatible with --output and --jq"},
-		{Name: "slide-id", Desc: "slide page identifier; omit both slide selectors to fetch full presentation XML"},
-		{Name: "slide-number", Type: "int", Desc: "1-based slide page number; omit both slide selectors to fetch full presentation XML"},
+		{Name: "output", Desc: "local XML output path; existing file is overwritten", Required: true},
 		{Name: "revision-id", Type: "int", Default: "-1", Desc: "presentation revision_id; -1 means latest"},
 		{Name: "remove-attr-id", Type: "bool", Desc: "remove XML id attributes in the returned content; useful for read-only inspection, not precise block editing"},
 	},
@@ -42,33 +37,19 @@ var SlidesXMLGet = common.Shortcut{
 		if err != nil {
 			return err
 		}
-		if revisionID := runtime.Int("revision-id"); revisionID < -1 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--revision-id must be -1 or a non-negative integer").WithParam("--revision-id")
-		}
 		if ref.Kind == "wiki" {
 			if err := runtime.EnsureScopes([]string{"wiki:node:read"}); err != nil {
 				return err
 			}
 		}
-		if err := validateSlidesXMLGetSelector(runtime); err != nil {
-			return err
+		if strings.TrimSpace(runtime.Str("output")) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output cannot be empty").WithParam("--output")
 		}
-		outputPath := strings.TrimSpace(runtime.Str("output"))
-		if outputPath != "" {
-			if _, err := runtime.ResolveSavePath(outputPath); err != nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output invalid: %v", err).WithParam("--output").WithCause(err)
-			}
+		if _, err := runtime.ResolveSavePath(runtime.Str("output")); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output invalid: %v", err).WithParam("--output").WithCause(err)
 		}
-		if runtime.Bool("raw") {
-			if outputPath != "" {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--raw cannot be used with --output").WithParam("--raw")
-			}
-			if runtime.JqExpr != "" {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--raw cannot be used with --jq").WithParam("--raw")
-			}
-			if runtime.Changed("format") && runtime.Format != "json" {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--raw cannot be used with --format %s", runtime.Format).WithParam("--raw")
-			}
+		if runtime.Int("revision-id") < -1 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--revision-id must be -1 or a non-negative integer").WithParam("--revision-id")
 		}
 		return nil
 	},
@@ -81,39 +62,25 @@ var SlidesXMLGet = common.Shortcut{
 		dry := common.NewDryRunAPI()
 		if ref.Kind == "wiki" {
 			presentationID = "<resolved_slides_token>"
-			dry.Desc("2-step orchestration: resolve wiki → fetch presentation XML").
+			dry.Desc("2-step orchestration: resolve wiki → fetch full presentation XML").
 				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("Fetch presentation XML")
+			dry.Desc("Fetch full presentation XML and save it to a local file")
 		}
 		params := map[string]interface{}{
 			"revision_id": runtime.Int("revision-id"),
 		}
-		slideID := strings.TrimSpace(runtime.Str("slide-id"))
-		slideNumber := runtime.Int("slide-number")
-		if slideID != "" {
-			params["slide_id"] = slideID
-		}
-		if slideNumber > 0 {
-			params["slide_number"] = slideNumber
-		}
-		if slideID == "" && slideNumber == 0 && runtime.Bool("remove-attr-id") {
+		if runtime.Bool("remove-attr-id") {
 			params["remove_attr_id"] = true
 		}
-		path := fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s", validate.EncodePathSegment(presentationID))
-		if slideID != "" || slideNumber > 0 {
-			path += "/slide"
-		}
-		dry.GET(path).Params(params)
-		if outputPath := strings.TrimSpace(runtime.Str("output")); outputPath != "" {
-			return dry.Set("output", outputPath).Set("stdout_content", "suppressed; XML content is saved to --output during execution")
-		}
-		if runtime.Bool("raw") {
-			return dry.Set("output", "<stdout>").Set("stdout_content", "raw XML content is printed to stdout during execution")
-		}
-		return dry.Set("output", "<stdout>").Set("stdout_content", "JSON envelope with XML content is printed to stdout during execution")
+		dry.GET(fmt.Sprintf(
+			"/open-apis/slides_ai/v1/xml_presentations/%s",
+			validate.EncodePathSegment(presentationID),
+		)).
+			Params(params)
+		return dry.Set("output", runtime.Str("output")).Set("stdout_content", "suppressed; XML content is saved to --output during execution")
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		ref, err := parsePresentationRef(runtime.Str("presentation"))
@@ -125,167 +92,53 @@ var SlidesXMLGet = common.Shortcut{
 			return err
 		}
 
-		if err := validateSlidesXMLGetSelector(runtime); err != nil {
-			return err
-		}
 		params := map[string]interface{}{
 			"revision_id": runtime.Int("revision-id"),
 		}
-
-		slideID := strings.TrimSpace(runtime.Str("slide-id"))
-		slideNumber := runtime.Int("slide-number")
-		content, out, err := fetchSlidesXMLGetContent(runtime, presentationID, params, slideID, slideNumber)
-		if err != nil {
-			return err
-		}
-		outputPath := strings.TrimSpace(runtime.Str("output"))
-		return outputSlidesXMLGetContent(runtime, content, outputPath, out)
-	},
-}
-
-func validateSlidesXMLGetSelector(runtime *common.RuntimeContext) error {
-	slideID := strings.TrimSpace(runtime.Str("slide-id"))
-	slideNumber := runtime.Int("slide-number")
-	if runtime.Changed("slide-id") && slideID == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slide-id cannot be empty").WithParam("--slide-id")
-	}
-	if slideID != "" && slideNumber > 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slide-id cannot be used with --slide-number").WithParam("--slide-id")
-	}
-	if runtime.Changed("slide-number") && slideNumber < 1 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--slide-number must be a positive integer").WithParam("--slide-number")
-	}
-	if (slideID != "" || slideNumber > 0) && runtime.Bool("remove-attr-id") {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--remove-attr-id is only supported when fetching full presentation XML").WithParam("--remove-attr-id")
-	}
-	return nil
-}
-
-func fetchSlidesXMLGetContent(runtime *common.RuntimeContext, presentationID string, params map[string]interface{}, slideID string, slideNumber int) (string, map[string]interface{}, error) {
-	if slideID != "" || slideNumber > 0 {
-		if slideID != "" {
-			params["slide_id"] = slideID
-		}
-		if slideNumber > 0 {
-			params["slide_number"] = slideNumber
+		if runtime.Bool("remove-attr-id") {
+			params["remove_attr_id"] = true
 		}
 		data, err := runtime.CallAPITyped(
 			"GET",
-			fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(presentationID)),
+			fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s", validate.EncodePathSegment(presentationID)),
 			params,
 			nil,
 		)
 		if err != nil {
-			return "", nil, err
+			return err
 		}
-		slide := common.GetMap(data, "slide")
-		content := common.GetString(slide, "content")
+
+		presentation := common.GetMap(data, "xml_presentation")
+		content := common.GetString(presentation, "content")
 		if content == "" {
-			return "", nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "slides xml get returned empty slide.content")
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "slides xml get returned empty xml_presentation.content")
 		}
-		slideOut := map[string]interface{}{
-			"content": content,
+		outputPath := runtime.Str("output")
+		result, err := runtime.FileIO().Save(outputPath, fileio.SaveOptions{
+			ContentType:   "application/xml",
+			ContentLength: int64(len(content)),
+		}, bytes.NewReader([]byte(content)))
+		if err != nil {
+			return common.WrapSaveErrorTyped(err)
 		}
-		actualSlideID := common.GetString(slide, "slide_id")
-		if actualSlideID == "" {
-			actualSlideID = slideID
-		}
-		if actualSlideID != "" {
-			slideOut["slide_id"] = actualSlideID
-		}
-		if slideNumber > 0 {
-			slideOut["slide_number"] = slideNumber
+		resolvedPath, err := runtime.ResolveSavePath(outputPath)
+		if err != nil {
+			return errs.NewInternalError(errs.SubtypeFileIO, "resolve saved XML path %s: %v", outputPath, err).WithCause(err)
 		}
+
 		out := map[string]interface{}{
 			"xml_presentation_id": presentationID,
-			"scope":               "slide",
-			"slide":               slideOut,
+			"path":                resolvedPath,
+			"size":                result.Size(),
+			"content_saved":       true,
 		}
-		if actualSlideID != "" {
-			out["slide_id"] = actualSlideID
-		}
-		if slideNumber > 0 {
-			out["slide_number"] = slideNumber
-		}
-		if revisionID := common.GetFloat(data, "revision_id"); revisionID > 0 {
+		if revisionID := common.GetFloat(presentation, "revision_id"); revisionID > 0 {
 			out["revision_id"] = int(revisionID)
-			slideOut["revision_id"] = int(revisionID)
 		}
-		return content, out, nil
-	}
-
-	if runtime.Bool("remove-attr-id") {
-		params["remove_attr_id"] = true
-	}
-	data, err := runtime.CallAPITyped(
-		"GET",
-		fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s", validate.EncodePathSegment(presentationID)),
-		params,
-		nil,
-	)
-	if err != nil {
-		return "", nil, err
-	}
-
-	presentation := common.GetMap(data, "xml_presentation")
-	content := common.GetString(presentation, "content")
-	if content == "" {
-		return "", nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "slides xml get returned empty xml_presentation.content")
-	}
-	presentationOut := map[string]interface{}{
-		"content": content,
-	}
-	out := map[string]interface{}{
-		"xml_presentation_id": presentationID,
-		"scope":               "presentation",
-		"xml_presentation":    presentationOut,
-	}
-	if revisionID := common.GetFloat(presentation, "revision_id"); revisionID > 0 {
-		out["revision_id"] = int(revisionID)
-		presentationOut["revision_id"] = int(revisionID)
-	}
-	if runtime.Bool("remove-attr-id") {
-		out["remove_attr_id"] = true
-	}
-	return content, out, nil
-}
-
-func outputSlidesXMLGetContent(runtime *common.RuntimeContext, content string, outputPath string, out map[string]interface{}) error {
-	if outputPath == "" {
-		if !runtime.Bool("raw") {
-			runtime.OutFormatRaw(out, nil, nil)
-			return nil
-		}
-		if _, err := fmt.Fprint(runtime.IO().Out, content); err != nil {
-			return errs.NewInternalError(errs.SubtypeFileIO, "write XML content to stdout: %v", err).WithCause(err)
+		if runtime.Bool("remove-attr-id") {
+			out["remove_attr_id"] = true
 		}
+		runtime.Out(out, nil)
 		return nil
-	}
-
-	result, err := runtime.FileIO().Save(outputPath, fileio.SaveOptions{
-		ContentType:   "application/xml",
-		ContentLength: int64(len(content)),
-	}, bytes.NewReader([]byte(content)))
-	if err != nil {
-		return common.WrapSaveErrorTyped(err)
-	}
-	resolvedPath, err := runtime.ResolveSavePath(outputPath)
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeFileIO, "resolve saved XML path %s: %v", outputPath, err).WithCause(err)
-	}
-
-	fileOut := map[string]interface{}{
-		"xml_presentation_id": out["xml_presentation_id"],
-		"scope":               out["scope"],
-		"path":                resolvedPath,
-		"size":                result.Size(),
-		"content_saved":       true,
-	}
-	for _, key := range []string{"revision_id", "remove_attr_id", "slide_id", "slide_number"} {
-		if value, ok := out[key]; ok {
-			fileOut[key] = value
-		}
-	}
-	runtime.Out(fileOut, nil)
-	return nil
+	},
 }

shortcuts/slides/slides_xml_get_test.go

@@ -5,7 +5,6 @@ package slides
 
 import (
 	"errors"
-	"fmt"
 	"net/http"
 	"net/url"
 	"os"
@@ -92,226 +91,6 @@ func TestSlidesXMLGetWritesContentToFileAndSuppressesXML(t *testing.T) {
 	}
 }
 
-func TestSlidesXMLGetReturnsContentEnvelopeWhenOutputOmitted(t *testing.T) {
-	dir := t.TempDir()
-	withSlidesTestWorkingDir(t, dir)
-
-	xml := `<presentation><slide id="s1"><shape id="a">hello</shape></slide></presentation>`
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"xml_presentation": map[string]interface{}{
-					"content": xml,
-				},
-			},
-		},
-	})
-
-	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
-		"+xml-get",
-		"--presentation", "pres_abc",
-		"--as", "user",
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	data := decodeShortcutData(t, stdout)
-	presentation := data["xml_presentation"].(map[string]interface{})
-	if got := presentation["content"]; got != xml {
-		t.Fatalf("content = %q, want %q", got, xml)
-	}
-	if got := data["xml_presentation_id"]; got != "pres_abc" {
-		t.Fatalf("xml_presentation_id = %v, want pres_abc", got)
-	}
-	if strings.Contains(stdout.String(), "content_saved") {
-		t.Fatalf("stdout should not contain file metadata: %s", stdout.String())
-	}
-}
-
-func TestSlidesXMLGetJqFiltersContentEnvelopeWhenOutputOmitted(t *testing.T) {
-	dir := t.TempDir()
-	withSlidesTestWorkingDir(t, dir)
-
-	xml := `<presentation><slide id="s1"><shape id="a">hello</shape></slide></presentation>`
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"xml_presentation": map[string]interface{}{
-					"content": xml,
-				},
-			},
-		},
-	})
-
-	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
-		"+xml-get",
-		"--presentation", "pres_abc",
-		"--jq", ".data.xml_presentation.content",
-		"--as", "user",
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if got := strings.TrimSpace(stdout.String()); got != xml {
-		t.Fatalf("stdout = %q, want XML content %q", got, xml)
-	}
-}
-
-func TestSlidesXMLGetPrintsRawContentWhenRaw(t *testing.T) {
-	dir := t.TempDir()
-	withSlidesTestWorkingDir(t, dir)
-
-	xml := `<presentation><slide id="s1"><shape id="a">hello</shape></slide></presentation>`
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"xml_presentation": map[string]interface{}{
-					"content": xml,
-				},
-			},
-		},
-	})
-
-	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
-		"+xml-get",
-		"--presentation", "pres_abc",
-		"--raw",
-		"--as", "user",
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if got := stdout.String(); got != xml {
-		t.Fatalf("stdout = %q, want raw XML %q", got, xml)
-	}
-}
-
-func TestSlidesXMLGetFetchesSingleSlideByIDToFile(t *testing.T) {
-	dir := t.TempDir()
-	withSlidesTestWorkingDir(t, dir)
-
-	xml := `<slide id="slide_1"><data><shape id="a"/></data></slide>`
-	var capturedQuery url.Values
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"slide": map[string]interface{}{
-					"slide_id": "slide_1",
-					"content":  xml,
-				},
-				"revision_id": 8,
-			},
-		},
-		OnMatch: func(req *http.Request) {
-			capturedQuery = req.URL.Query()
-		},
-	})
-
-	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
-		"+xml-get",
-		"--presentation", "pres_abc",
-		"--slide-id", "slide_1",
-		"--output", "slide_1.xml",
-		"--as", "user",
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if got := capturedQuery.Get("slide_id"); got != "slide_1" {
-		t.Fatalf("slide_id query = %q, want slide_1", got)
-	}
-	if got := capturedQuery.Get("revision_id"); got != "-1" {
-		t.Fatalf("revision_id query = %q, want -1", got)
-	}
-	path := filepath.Join(dir, "slide_1.xml")
-	got, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatalf("read saved slide XML: %v", err)
-	}
-	if string(got) != xml {
-		t.Fatalf("saved XML = %q, want %q", got, xml)
-	}
-	data := decodeShortcutData(t, stdout)
-	if data["scope"] != "slide" {
-		t.Fatalf("scope = %v, want slide", data["scope"])
-	}
-	if data["slide_id"] != "slide_1" {
-		t.Fatalf("slide_id = %v, want slide_1", data["slide_id"])
-	}
-	if data["content_saved"] != true {
-		t.Fatalf("content_saved = %v, want true", data["content_saved"])
-	}
-}
-
-func TestSlidesXMLGetFetchesSingleSlideByNumberEnvelope(t *testing.T) {
-	dir := t.TempDir()
-	withSlidesTestWorkingDir(t, dir)
-
-	xml := `<slide id="slide_2"><data><shape id="b"/></data></slide>`
-	var capturedQuery url.Values
-	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"slide": map[string]interface{}{
-					"slide_id": "slide_2",
-					"content":  xml,
-				},
-				"revision_id": 9,
-			},
-		},
-		OnMatch: func(req *http.Request) {
-			capturedQuery = req.URL.Query()
-		},
-	})
-
-	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
-		"+xml-get",
-		"--presentation", "pres_abc",
-		"--slide-number", "2",
-		"--as", "user",
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if got := capturedQuery.Get("slide_number"); got != "2" {
-		t.Fatalf("slide_number query = %q, want 2", got)
-	}
-	data := decodeShortcutData(t, stdout)
-	if data["scope"] != "slide" {
-		t.Fatalf("scope = %v, want slide", data["scope"])
-	}
-	if data["slide_number"] != float64(2) {
-		t.Fatalf("slide_number = %v, want 2", data["slide_number"])
-	}
-	slide := data["slide"].(map[string]interface{})
-	if slide["content"] != xml {
-		t.Fatalf("content = %q, want %q", slide["content"], xml)
-	}
-	if slide["slide_id"] != "slide_2" {
-		t.Fatalf("slide.slide_id = %v, want slide_2", slide["slide_id"])
-	}
-}
-
 func TestSlidesXMLGetResolvesWikiPresentation(t *testing.T) {
 	dir := t.TempDir()
 	withSlidesTestWorkingDir(t, dir)
@@ -384,134 +163,3 @@ func TestSlidesXMLGetRejectsUnsafeOutputPath(t *testing.T) {
 		t.Fatalf("param = %q, want --output", validationErr.Param)
 	}
 }
-
-func TestSlidesXMLGetRejectsRevisionIDBelowMinusOneBeforeAPICall(t *testing.T) {
-	for _, dryRun := range []bool{false, true} {
-		t.Run(fmt.Sprintf("dry-run=%t", dryRun), func(t *testing.T) {
-			f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-
-			args := []string{
-				"+xml-get",
-				"--presentation", "pres_abc",
-				"--revision-id", "-2",
-				"--as", "user",
-			}
-			if dryRun {
-				args = append(args, "--dry-run")
-			}
-			err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, args)
-			if err == nil {
-				t.Fatal("expected invalid revision-id error, got nil")
-			}
-			problem, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("expected typed error, got %T %v", err, err)
-			}
-			if problem.Category != errs.CategoryValidation {
-				t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryValidation)
-			}
-			if problem.Subtype != errs.SubtypeInvalidArgument {
-				t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeInvalidArgument)
-			}
-			var validationErr *errs.ValidationError
-			if !errors.As(err, &validationErr) {
-				t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
-			}
-			if validationErr.Param != "--revision-id" {
-				t.Fatalf("param = %q, want --revision-id", validationErr.Param)
-			}
-		})
-	}
-}
-
-func TestSlidesXMLGetRejectsConflictingSlideSelectors(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
-		"+xml-get",
-		"--presentation", "pres_abc",
-		"--slide-id", "slide_1",
-		"--slide-number", "1",
-		"--as", "user",
-	})
-	if err == nil {
-		t.Fatal("expected selector conflict error, got nil")
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error, got %T %v", err, err)
-	}
-	if problem.Category != errs.CategoryValidation {
-		t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryValidation)
-	}
-	if problem.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeInvalidArgument)
-	}
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) {
-		t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
-	}
-	if validationErr.Param != "--slide-id" {
-		t.Fatalf("param = %q, want --slide-id", validationErr.Param)
-	}
-}
-
-func TestSlidesXMLGetRejectsEmptySlideID(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
-		"+xml-get",
-		"--presentation", "pres_abc",
-		"--slide-id", " ",
-		"--as", "user",
-	})
-	if err == nil {
-		t.Fatal("expected empty slide-id error, got nil")
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error, got %T %v", err, err)
-	}
-	if problem.Category != errs.CategoryValidation {
-		t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryValidation)
-	}
-	if problem.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeInvalidArgument)
-	}
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) {
-		t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
-	}
-	if validationErr.Param != "--slide-id" {
-		t.Fatalf("param = %q, want --slide-id", validationErr.Param)
-	}
-}
-
-func TestSlidesXMLGetRejectsRemoveAttrIDForSingleSlide(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
-	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
-		"+xml-get",
-		"--presentation", "pres_abc",
-		"--slide-number", "1",
-		"--remove-attr-id",
-		"--as", "user",
-	})
-	if err == nil {
-		t.Fatal("expected remove-attr-id validation error, got nil")
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error, got %T %v", err, err)
-	}
-	if problem.Category != errs.CategoryValidation {
-		t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryValidation)
-	}
-	if problem.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeInvalidArgument)
-	}
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) {
-		t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
-	}
-	if validationErr.Param != "--remove-attr-id" {
-		t.Fatalf("param = %q, want --remove-attr-id", validationErr.Param)
-	}
-}

shortcuts/vc/helpers.go

@@ -1,50 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package vc
-
-import (
-	"errors"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/registry"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-const (
-	meetingQueryUserScope = "vc:meeting.meetingevent:read"
-	meetingQueryBotScope  = "vc:meeting.bot.join:write"
-)
-
-func normalizeMeetingQueryPermissionError(runtime *common.RuntimeContext, err error) error {
-	if runtime == nil {
-		return err
-	}
-	var permissionErr *errs.PermissionError
-	if !errors.As(err, &permissionErr) || permissionErr == nil {
-		return err
-	}
-
-	switch {
-	case runtime.As() == core.AsUser && permissionErr.Code == output.LarkErrUserScopeInsufficient:
-		permissionErr.Message = "access denied for user identity; recommended scope: " + meetingQueryUserScope
-		permissionErr.WithHint("for user identity, run `lark-cli auth login --scope %q` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", meetingQueryUserScope)
-		permissionErr.WithMissingScopes(meetingQueryUserScope)
-		return err
-	case runtime.As() == core.AsBot && permissionErr.Code == output.LarkErrAppScopeNotEnabled:
-		permissionErr.Message = "access denied for bot identity; recommended scope: " + meetingQueryBotScope
-		permissionErr.WithHint("ask the app developer to enable scope %s", meetingQueryBotScope)
-		permissionErr.WithMissingScopes(meetingQueryBotScope)
-		if runtime.Config != nil {
-			consoleURL := registry.BuildConsoleScopeURL(runtime.Config.Brand, runtime.Config.AppID, meetingQueryBotScope)
-			if consoleURL != "" {
-				permissionErr.WithConsoleURL(consoleURL)
-			}
-		}
-		return err
-	default:
-		return err
-	}
-}

shortcuts/vc/helpers_test.go

@@ -1,207 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package vc
-
-import (
-	"errors"
-	"net/url"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-func bareMeetingQueryRuntime(as core.Identity) *common.RuntimeContext {
-	return common.TestNewRuntimeContextWithIdentity(&cobra.Command{Use: "test"}, defaultConfig(), as)
-}
-
-func TestNormalizeMeetingQueryPermissionError_NilRuntimeReturnsOriginalError(t *testing.T) {
-	original := errs.NewPermissionError(errs.SubtypeMissingScope, "permission failure").
-		WithCode(output.LarkErrUserScopeInsufficient)
-	if got := normalizeMeetingQueryPermissionError(nil, original); got != original {
-		t.Fatalf("got %v, want original error %v", got, original)
-	}
-}
-
-func TestNormalizeMeetingQueryPermissionError_TypedNilReturnsOriginalError(t *testing.T) {
-	var permissionErr *errs.PermissionError
-	var original error = permissionErr
-	if got := normalizeMeetingQueryPermissionError(bareMeetingQueryRuntime(core.AsUser), original); got != original {
-		t.Fatalf("got %v, want original error %v", got, original)
-	}
-}
-
-func assertMeetingQueryPermissionError(t *testing.T, err error, identity core.Identity, code int) {
-	t.Helper()
-
-	var pe *errs.PermissionError
-	if !errors.As(err, &pe) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
-	}
-	if pe.Category != errs.CategoryAuthorization {
-		t.Fatalf("Category = %q, want %q", pe.Category, errs.CategoryAuthorization)
-	}
-	if pe.Subtype != errs.SubtypeMissingScope && pe.Subtype != errs.SubtypeAppScopeNotApplied {
-		t.Fatalf("Subtype = %q, want a missing-scope subtype", pe.Subtype)
-	}
-	if pe.Identity != string(identity) {
-		t.Fatalf("Identity = %q, want %q", pe.Identity, identity)
-	}
-
-	wantScope := meetingQueryUserScope
-	if identity.IsBot() {
-		wantScope = meetingQueryBotScope
-	}
-	if !strings.Contains(pe.Hint, wantScope) {
-		t.Fatalf("Hint = %q, want recommended scope %q", pe.Hint, wantScope)
-	}
-	if len(pe.MissingScopes) != 1 || pe.MissingScopes[0] != wantScope {
-		t.Fatalf("MissingScopes = %v, want only recommended scope %q", pe.MissingScopes, wantScope)
-	}
-	if strings.Contains(pe.Hint, "either compatible scope") {
-		t.Fatalf("Hint = %q, must not repeat the OR-scope explanation from message", pe.Hint)
-	}
-	switch code {
-	case output.LarkErrAppScopeNotEnabled:
-		if strings.Contains(pe.Hint, "auth login") {
-			t.Fatalf("Hint = %q, app-scope error must not recommend user login", pe.Hint)
-		}
-		if !strings.Contains(pe.Hint, "app developer") {
-			t.Fatalf("Hint = %q, want app developer guidance", pe.Hint)
-		}
-		if pe.ConsoleURL == "" {
-			t.Fatal("ConsoleURL is empty, want identity-specific developer-console URL")
-		}
-		if strings.Contains(pe.ConsoleURL, url.QueryEscape(meetingQueryUserScope)) || !strings.Contains(pe.ConsoleURL, url.QueryEscape(meetingQueryBotScope)) {
-			t.Fatalf("ConsoleURL = %q, want only bot scope", pe.ConsoleURL)
-		}
-	case output.LarkErrUserScopeInsufficient:
-		if !strings.Contains(pe.Hint, "auth login --scope") {
-			t.Fatalf("Hint = %q, want auth login guidance", pe.Hint)
-		}
-		if pe.ConsoleURL != "" {
-			t.Fatalf("ConsoleURL = %q, user-scope error must not expose a developer-console URL", pe.ConsoleURL)
-		}
-	default:
-		t.Fatalf("unexpected code %d", code)
-	}
-}
-
-func TestNormalizeMeetingQueryPermissionError_RecommendsScopeForMatchingIdentity(t *testing.T) {
-	cases := []struct {
-		name     string
-		identity core.Identity
-		code     int
-		subtype  errs.Subtype
-	}{
-		{name: "user_with_user_scope_error", identity: core.AsUser, code: output.LarkErrUserScopeInsufficient, subtype: errs.SubtypeMissingScope},
-		{name: "bot_with_app_scope_error", identity: core.AsBot, code: output.LarkErrAppScopeNotEnabled, subtype: errs.SubtypeAppScopeNotApplied},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			wantScope := meetingQueryUserScope
-			if tc.identity == core.AsBot {
-				wantScope = meetingQueryBotScope
-			}
-			wantMessage := "access denied for " + string(tc.identity) + " identity; recommended scope: " + wantScope
-			original := errs.NewPermissionError(tc.subtype, "upstream permission failure").
-				WithCode(tc.code).
-				WithLogID("log-id").
-				WithRetryable().
-				WithIdentity(string(tc.identity)).
-				WithMissingScopes(meetingQueryUserScope, meetingQueryBotScope).
-				WithRequestedScopes("requested:scope").
-				WithGrantedScopes("granted:scope")
-			if tc.identity == core.AsBot {
-				original.ConsoleURL = "https://example.com/scopes"
-			}
-			original.Troubleshooter = "https://example.com/troubleshoot"
-
-			got := normalizeMeetingQueryPermissionError(bareMeetingQueryRuntime(tc.identity), original)
-			var pe *errs.PermissionError
-			if !errors.As(got, &pe) {
-				t.Fatalf("got %T, want *errs.PermissionError", got)
-			}
-			if got != original || pe != original {
-				t.Fatal("normalizer did not return the original permission error")
-			}
-			if pe.Code != tc.code || pe.Subtype != tc.subtype || pe.LogID != "log-id" || !pe.Retryable {
-				t.Fatalf("diagnostics changed: %+v", pe.Problem)
-			}
-			if pe.Troubleshooter != original.Troubleshooter {
-				t.Fatalf("Troubleshooter = %q, want %q", pe.Troubleshooter, original.Troubleshooter)
-			}
-			if pe.Message != wantMessage {
-				t.Fatalf("Message = %q, want %q", pe.Message, wantMessage)
-			}
-			if tc.identity == core.AsBot {
-				consoleURL, err := url.Parse(pe.ConsoleURL)
-				if err != nil {
-					t.Fatalf("ConsoleURL = %q is invalid: %v", pe.ConsoleURL, err)
-				}
-				if consoleURL.Host == "" || consoleURL.Query().Get("clientID") != "test-app" || consoleURL.Query().Get("scopes") != meetingQueryBotScope {
-					t.Fatalf("ConsoleURL = %q, want test-app and only bot scope", pe.ConsoleURL)
-				}
-			} else if pe.ConsoleURL != "" {
-				t.Fatalf("ConsoleURL = %q, user-scope error must not expose a developer-console URL", pe.ConsoleURL)
-			}
-			assertMeetingQueryPermissionError(t, got, tc.identity, tc.code)
-		})
-	}
-}
-
-func TestNormalizeMeetingQueryPermissionError_PassesThroughNonMatchingErrors(t *testing.T) {
-	cases := []struct {
-		name     string
-		identity core.Identity
-		err      error
-	}{
-		{
-			name:     "user_with_app_scope_error",
-			identity: core.AsUser,
-			err: errs.NewPermissionError(errs.SubtypeAppScopeNotApplied, "app scope error").
-				WithCode(output.LarkErrAppScopeNotEnabled),
-		},
-		{
-			name:     "bot_with_user_scope_error",
-			identity: core.AsBot,
-			err: errs.NewPermissionError(errs.SubtypeMissingScope, "user scope error").
-				WithCode(output.LarkErrUserScopeInsufficient),
-		},
-		{
-			name:     "auto_with_user_scope_error",
-			identity: core.AsAuto,
-			err: errs.NewPermissionError(errs.SubtypeMissingScope, "auto identity").
-				WithCode(output.LarkErrUserScopeInsufficient),
-		},
-		{
-			name: "bot_not_in_meeting",
-			err:  errs.NewPermissionError(errs.SubtypePermissionDenied, "not in meeting").WithCode(10005),
-		},
-		{
-			name: "not_in_gray",
-			err: errs.NewPermissionError(errs.SubtypePermissionDenied, "not in gray").
-				WithCode(20017),
-		},
-		{name: "plain_error", err: errors.New("boom")},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			identity := tc.identity
-			if identity == "" {
-				identity = core.AsBot
-			}
-			if got := normalizeMeetingQueryPermissionError(bareMeetingQueryRuntime(identity), tc.err); got != tc.err {
-				t.Fatalf("got %T %v, want original error %T %v", got, got, tc.err, tc.err)
-			}
-		})
-	}
-}

shortcuts/vc/vc_meeting_events.go

@@ -52,13 +52,9 @@ var VCMeetingEvents = common.Shortcut{
 	Command:     "+meeting-events",
 	Description: "List meeting events by meeting ID",
 	Risk:        "read",
-	// UAT exposes user-granted scopes, so the framework can preflight the user
-	// recommendation. TAT has no scope metadata; keep the bot recommendation
-	// conditional so it is available to diagnostics without a local preflight.
-	UserScopes:           []string{meetingQueryUserScope},
-	ConditionalBotScopes: []string{meetingQueryBotScope},
-	AuthTypes:            []string{"user", "bot"},
-	HasFormat:            true,
+	Scopes:      []string{"vc:meeting.meetingevent:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "meeting-id", Required: true, Desc: "meeting ID to query"},
 		{Name: "start", Desc: "time lower bound (ISO 8601, YYYY-MM-DD, or Unix seconds)"},
@@ -105,7 +101,7 @@ var VCMeetingEvents = common.Shortcut{
 		}
 		data, events, hasMore, pageToken, err := fetchMeetingEvents(ctx, runtime, startTime, endTime)
 		if err != nil {
-			return normalizeMeetingQueryPermissionError(runtime, err)
+			return err
 		}
 		events = compactMeetingEvents(events)
 		identity, identityWarning := meetingEventsCurrentIdentity(runtime)

shortcuts/vc/vc_meeting_events_test.go

@@ -7,7 +7,6 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
-	"net/url"
 	"reflect"
 	"strings"
 	"testing"
@@ -18,7 +17,6 @@ import (
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -420,21 +418,6 @@ func TestMeetingEvents_Validation_PageAllIgnoresInvalidPageSize(t *testing.T) {
 	}
 }
 
-func TestMeetingEvents_UsesUserScopePreflightAndBotScopeHint(t *testing.T) {
-	if got := VCMeetingEvents.ScopesForIdentity("user"); !reflect.DeepEqual(got, []string{meetingQueryUserScope}) {
-		t.Fatalf("ScopesForIdentity(user) = %v, want %v", got, []string{meetingQueryUserScope})
-	}
-	if got := VCMeetingEvents.ScopesForIdentity("bot"); len(got) != 0 {
-		t.Fatalf("ScopesForIdentity(bot) = %v, want no bot preflight scopes", got)
-	}
-	if got := VCMeetingEvents.DeclaredScopesForIdentity("user"); !reflect.DeepEqual(got, []string{meetingQueryUserScope}) {
-		t.Fatalf("DeclaredScopesForIdentity(user) = %v, want %v", got, []string{meetingQueryUserScope})
-	}
-	if got := VCMeetingEvents.DeclaredScopesForIdentity("bot"); !reflect.DeepEqual(got, []string{meetingQueryBotScope}) {
-		t.Fatalf("DeclaredScopesForIdentity(bot) = %v, want %v", got, []string{meetingQueryBotScope})
-	}
-}
-
 func TestMeetingEvents_Validation_InvalidPageSizeReturnsFlagError(t *testing.T) {
 	runtime := newMeetingEventsRuntime()
 	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
@@ -654,63 +637,6 @@ func TestMeetingEvents_ExecuteJSON(t *testing.T) {
 	}
 }
 
-func TestMeetingEvents_Execute_NormalizesMeetingScopeError(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    vcMeetingEventsAPIPath,
-		Status: 400,
-		Body: map[string]interface{}{
-			"code": output.LarkErrAppScopeNotEnabled,
-			"msg":  "access denied",
-			"error": map[string]interface{}{
-				"permission_violations": []interface{}{
-					map[string]interface{}{"subject": meetingQueryUserScope},
-					map[string]interface{}{"subject": meetingQueryBotScope},
-				},
-			},
-		},
-	})
-
-	err := mountAndRun(t, VCMeetingEvents, []string{
-		"+meeting-events",
-		"--meeting-id", "7628568141510692381",
-		"--format", "json",
-		"--as", "bot",
-	}, f, stdout)
-	if err == nil {
-		t.Fatal("expected permission error")
-	}
-	reg.Verify(t)
-
-	var permissionErr *errs.PermissionError
-	if !errors.As(err, &permissionErr) {
-		t.Fatalf("error = %T %v, want *errs.PermissionError", err, err)
-	}
-	if permissionErr.Code != output.LarkErrAppScopeNotEnabled {
-		t.Fatalf("Code = %d, want %d", permissionErr.Code, output.LarkErrAppScopeNotEnabled)
-	}
-	if permissionErr.Identity != "bot" {
-		t.Fatalf("Identity = %q, want bot", permissionErr.Identity)
-	}
-	wantMessage := "access denied for bot identity; recommended scope: " + meetingQueryBotScope
-	if permissionErr.Message != wantMessage {
-		t.Fatalf("Message = %q, want %q", permissionErr.Message, wantMessage)
-	}
-	if !strings.Contains(permissionErr.Hint, meetingQueryBotScope) {
-		t.Fatalf("Hint = %q, want bot scope %q", permissionErr.Hint, meetingQueryBotScope)
-	}
-	if len(permissionErr.MissingScopes) != 1 || permissionErr.MissingScopes[0] != meetingQueryBotScope {
-		t.Fatalf("MissingScopes = %v, want only bot scope %q", permissionErr.MissingScopes, meetingQueryBotScope)
-	}
-	if permissionErr.ConsoleURL == "" {
-		t.Fatal("ConsoleURL is empty, want identity-specific developer-console URL")
-	}
-	if strings.Contains(permissionErr.ConsoleURL, url.QueryEscape(meetingQueryUserScope)) || !strings.Contains(permissionErr.ConsoleURL, url.QueryEscape(meetingQueryBotScope)) {
-		t.Fatalf("ConsoleURL = %q, want only bot scope", permissionErr.ConsoleURL)
-	}
-}
-
 func TestMeetingEvents_ExecuteJSON_BotIdentityErrorDoesNotBlockEvents(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, false, ""))

shortcuts/vc/vc_meeting_list_active.go

@@ -23,13 +23,9 @@ var VCMeetingListActive = common.Shortcut{
 	Command:     "+meeting-list-active",
 	Description: "List active meetings for the current identity or target user",
 	Risk:        "read",
-	// UAT exposes user-granted scopes, so the framework can preflight the user
-	// recommendation. TAT has no scope metadata; keep the bot recommendation
-	// conditional so it is available to diagnostics without a local preflight.
-	UserScopes:           []string{meetingQueryUserScope},
-	ConditionalBotScopes: []string{meetingQueryBotScope},
-	AuthTypes:            []string{"user", "bot"},
-	HasFormat:            true,
+	Scopes:      []string{"vc:meeting.meetingevent:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "user-id", Desc: "target user ID when using bot identity"},
 	},
@@ -54,7 +50,7 @@ var VCMeetingListActive = common.Shortcut{
 		}
 		data, err := runtime.CallAPITyped(http.MethodGet, vcMeetingListActiveAPIPath, params, nil)
 		if err != nil {
-			return normalizeMeetingQueryPermissionError(runtime, err)
+			return err
 		}
 		if data == nil {
 			data = map[string]interface{}{}

shortcuts/vc/vc_meeting_test.go

@@ -608,18 +608,9 @@ func TestMeetingListActive_DryRun_UserIdentity(t *testing.T) {
 	}
 }
 
-func TestMeetingListActive_UsesUserScopePreflightAndBotScopeHint(t *testing.T) {
-	if got := VCMeetingListActive.ScopesForIdentity("user"); len(got) != 1 || got[0] != meetingQueryUserScope {
-		t.Fatalf("ScopesForIdentity(user) = %v, want [%s]", got, meetingQueryUserScope)
-	}
-	if got := VCMeetingListActive.ScopesForIdentity("bot"); len(got) != 0 {
-		t.Fatalf("ScopesForIdentity(bot) = %v, want no bot preflight scopes", got)
-	}
-	if got := VCMeetingListActive.DeclaredScopesForIdentity("user"); len(got) != 1 || got[0] != meetingQueryUserScope {
-		t.Fatalf("DeclaredScopesForIdentity(user) = %v, want [%s]", got, meetingQueryUserScope)
-	}
-	if got := VCMeetingListActive.DeclaredScopesForIdentity("bot"); len(got) != 1 || got[0] != meetingQueryBotScope {
-		t.Fatalf("DeclaredScopesForIdentity(bot) = %v, want [%s]", got, meetingQueryBotScope)
+func TestMeetingListActive_ScopeMatchesEventReadPermission(t *testing.T) {
+	if len(VCMeetingListActive.Scopes) != 1 || VCMeetingListActive.Scopes[0] != "vc:meeting.meetingevent:read" {
+		t.Fatalf("scopes = %#v, want [vc:meeting.meetingevent:read]", VCMeetingListActive.Scopes)
 	}
 }
 

shortcuts/wiki/shortcuts.go

@@ -9,7 +9,6 @@ import "github.com/larksuite/cli/shortcuts/common"
 func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		WikiMove,
-		WikiMoveToDrive,
 		WikiNodeCreate,
 		WikiDeleteSpace,
 		WikiSpaceList,

shortcuts/wiki/wiki_move_to_drive.go

@@ -1,415 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package wiki
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-const (
-	// These are fixed backend wire values. Keep them unchanged even though the
-	// shortcut and its continuation scenario use the user-facing Drive name.
-	wikiMoveToDriveTaskType = "move_wiki_to_docs"
-	wikiMoveToDriveResult   = "move_wiki_to_docs_result"
-
-	wikiMoveToDriveStatusSuccess    = 0
-	wikiMoveToDriveStatusProcessing = 1
-	wikiMoveToDriveStatusFailure    = -1
-)
-
-var (
-	wikiMoveToDrivePollAttempts = 30
-	wikiMoveToDrivePollInterval = 2 * time.Second
-)
-
-// WikiMoveToDrive moves a Wiki node out of its knowledge space and into a
-// Drive folder. The API always creates an async task, so the shortcut polls the
-// Wiki task endpoint and returns a resumable command when the bounded window
-// expires.
-var WikiMoveToDrive = common.Shortcut{
-	Service:     "wiki",
-	Command:     "+move-to-drive",
-	Description: "Move a wiki node to a Drive folder, polling the async task until it finishes",
-	Risk:        "write",
-	// The move endpoint's wiki:wiki / wiki:node:move /
-	// space:document:move list is an OR-set, while Shortcut.Scopes is an
-	// ALL-required preflight. Use the registry's highest-priority candidate
-	// plus the read scope required by the task-status endpoint.
-	Scopes:    []string{"space:document:move", "wiki:space:read"},
-	AuthTypes: []string{"user", "bot"},
-	Flags: []common.Flag{
-		{Name: "node-token", Desc: "wiki node_token to move out of the knowledge space", Required: true},
-		{Name: "folder-token", Desc: "target Drive folder token; omit to move to the calling identity's personal-space root"},
-	},
-	Tips: []string{
-		"The source must be a wiki node_token, not the backing document's obj_token; use wiki +node-get when unsure.",
-		"Omit --folder-token to move the document to the calling identity's personal-space root.",
-		"Moving out of Wiki removes the node from the Wiki tree and replaces inherited Wiki permissions with the target Drive folder's permission model.",
-		"The move is asynchronous; if the bounded poll times out, continue with the next_command returned in the output.",
-	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateWikiMoveToDriveSpec(readWikiMoveToDriveSpec(runtime))
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return buildWikiMoveToDriveDryRun(readWikiMoveToDriveSpec(runtime))
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		spec := readWikiMoveToDriveSpec(runtime)
-		out, err := runWikiMoveToDrive(ctx, wikiMoveToDriveAPI{runtime: runtime}, runtime, spec)
-		if err != nil {
-			return err
-		}
-		runtime.Out(out, nil)
-		return nil
-	},
-}
-
-type wikiMoveToDriveSpec struct {
-	NodeToken   string
-	FolderToken string
-}
-
-func (spec wikiMoveToDriveSpec) RequestBody() map[string]interface{} {
-	body := map[string]interface{}{}
-	if spec.FolderToken != "" {
-		body["folder_token"] = spec.FolderToken
-	}
-	return body
-}
-
-type wikiMoveToDriveTaskStatus struct {
-	TaskID    string
-	Status    int
-	StatusMsg string
-	ObjToken  string
-	ObjType   string
-	URL       string
-}
-
-func (s wikiMoveToDriveTaskStatus) Ready() bool {
-	return s.Status == wikiMoveToDriveStatusSuccess
-}
-
-func (s wikiMoveToDriveTaskStatus) Failed() bool {
-	return s.Status < wikiMoveToDriveStatusSuccess
-}
-
-func (s wikiMoveToDriveTaskStatus) StatusLabel() string {
-	if label := strings.TrimSpace(s.StatusMsg); label != "" {
-		return label
-	}
-	switch {
-	case s.Ready():
-		return "success"
-	case s.Failed():
-		return "failure"
-	default:
-		return "processing"
-	}
-}
-
-type wikiMoveToDriveClient interface {
-	MoveWikiToDrive(ctx context.Context, spec wikiMoveToDriveSpec) (string, error)
-	GetMoveWikiToDriveTask(ctx context.Context, taskID string) (wikiMoveToDriveTaskStatus, error)
-}
-
-type wikiMoveToDriveAPI struct {
-	runtime *common.RuntimeContext
-}
-
-func (api wikiMoveToDriveAPI) MoveWikiToDrive(ctx context.Context, spec wikiMoveToDriveSpec) (string, error) {
-	data, err := api.runtime.CallAPITyped(
-		"POST",
-		fmt.Sprintf(
-			"/open-apis/wiki/v2/nodes/%s/move_wiki_to_docs",
-			validate.EncodePathSegment(spec.NodeToken),
-		),
-		nil,
-		spec.RequestBody(),
-	)
-	if err != nil {
-		return "", err
-	}
-
-	taskID := common.GetString(data, "task_id")
-	if taskID == "" {
-		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki move-to-drive response missing task_id")
-	}
-	return taskID, nil
-}
-
-func (api wikiMoveToDriveAPI) GetMoveWikiToDriveTask(ctx context.Context, taskID string) (wikiMoveToDriveTaskStatus, error) {
-	data, err := api.runtime.CallAPITyped(
-		"GET",
-		fmt.Sprintf("/open-apis/wiki/v2/tasks/%s", validate.EncodePathSegment(taskID)),
-		map[string]interface{}{"task_type": wikiMoveToDriveTaskType},
-		nil,
-	)
-	if err != nil {
-		return wikiMoveToDriveTaskStatus{}, err
-	}
-	return parseWikiMoveToDriveTaskStatus(taskID, common.GetMap(data, "task"))
-}
-
-func readWikiMoveToDriveSpec(runtime *common.RuntimeContext) wikiMoveToDriveSpec {
-	return wikiMoveToDriveSpec{
-		NodeToken:   strings.TrimSpace(runtime.Str("node-token")),
-		FolderToken: strings.TrimSpace(runtime.Str("folder-token")),
-	}
-}
-
-func validateWikiMoveToDriveSpec(spec wikiMoveToDriveSpec) error {
-	if spec.NodeToken == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--node-token is required").WithParam("--node-token")
-	}
-	if err := validateOptionalResourceName(spec.NodeToken, "--node-token"); err != nil {
-		return err
-	}
-	return validateOptionalResourceName(spec.FolderToken, "--folder-token")
-}
-
-func buildWikiMoveToDriveDryRun(spec wikiMoveToDriveSpec) *common.DryRunAPI {
-	dry := common.NewDryRunAPI().Desc(
-		"2-step orchestration: move wiki node to Drive -> poll wiki move-to-drive task result",
-	)
-	dry.POST(fmt.Sprintf(
-		"/open-apis/wiki/v2/nodes/%s/move_wiki_to_docs",
-		validate.EncodePathSegment(spec.NodeToken),
-	)).
-		Desc("[1] Move wiki node to Drive").
-		Body(spec.RequestBody())
-	dry.GET("/open-apis/wiki/v2/tasks/:task_id").
-		Desc("[2] Poll wiki move-to-drive task result").
-		Set("task_id", "<task_id>").
-		Params(map[string]interface{}{"task_type": wikiMoveToDriveTaskType})
-	return dry
-}
-
-func runWikiMoveToDrive(
-	ctx context.Context,
-	client wikiMoveToDriveClient,
-	runtime *common.RuntimeContext,
-	spec wikiMoveToDriveSpec,
-) (map[string]interface{}, error) {
-	folderLabel := "personal-space root"
-	if spec.FolderToken != "" {
-		folderLabel = common.MaskToken(spec.FolderToken)
-	}
-	fmt.Fprintf(
-		runtime.IO().ErrOut,
-		"Moving wiki node %s to Drive folder %s...\n",
-		common.MaskToken(spec.NodeToken),
-		folderLabel,
-	)
-
-	taskID, err := client.MoveWikiToDrive(ctx, spec)
-	if err != nil {
-		return nil, err
-	}
-
-	fmt.Fprintf(runtime.IO().ErrOut, "Wiki move-to-drive is async, polling task %s...\n", taskID)
-	status, ready, err := pollWikiMoveToDriveTask(ctx, client, runtime, taskID)
-	if err != nil {
-		return nil, err
-	}
-
-	out := map[string]interface{}{
-		"node_token":   spec.NodeToken,
-		"folder_token": spec.FolderToken,
-		"task_id":      taskID,
-		"ready":        ready,
-		"failed":       status.Failed(),
-		"status":       status.Status,
-		"status_msg":   status.StatusLabel(),
-		"obj_token":    status.ObjToken,
-		"obj_type":     status.ObjType,
-		"url":          status.URL,
-	}
-	if !ready {
-		nextCommand := wikiMoveToDriveTaskResultCommand(taskID, runtime.As(), wikiMoveToDriveProfileName(runtime))
-		fmt.Fprintf(runtime.IO().ErrOut, "Wiki move-to-drive task is still in progress. Continue with: %s\n", nextCommand)
-		out["timed_out"] = true
-		out["next_command"] = nextCommand
-	}
-	return out, nil
-}
-
-func pollWikiMoveToDriveTask(
-	ctx context.Context,
-	client wikiMoveToDriveClient,
-	runtime *common.RuntimeContext,
-	taskID string,
-) (wikiMoveToDriveTaskStatus, bool, error) {
-	lastStatus := wikiMoveToDriveTaskStatus{
-		TaskID: taskID,
-		Status: wikiMoveToDriveStatusProcessing,
-	}
-	var lastErr error
-	hadSuccessfulPoll := false
-
-	for attempt := 1; attempt <= wikiMoveToDrivePollAttempts; attempt++ {
-		if attempt > 1 {
-			select {
-			case <-ctx.Done():
-				return lastStatus, false, wrapWikiMoveToDrivePollContextError(
-					ctx.Err(), taskID, runtime.As(), wikiMoveToDriveProfileName(runtime),
-				)
-			case <-time.After(wikiMoveToDrivePollInterval):
-			}
-		}
-
-		status, err := client.GetMoveWikiToDriveTask(ctx, taskID)
-		if err != nil {
-			if contextErr := ctx.Err(); contextErr != nil {
-				return lastStatus, false, wrapWikiMoveToDrivePollContextError(
-					contextErr, taskID, runtime.As(), wikiMoveToDriveProfileName(runtime),
-				)
-			}
-			lastErr = err
-			fmt.Fprintf(runtime.IO().ErrOut, "Wiki move-to-drive status attempt %d/%d failed: %v\n", attempt, wikiMoveToDrivePollAttempts, err)
-			continue
-		}
-		lastStatus = status
-		hadSuccessfulPoll = true
-
-		if status.Ready() {
-			fmt.Fprintln(runtime.IO().ErrOut, "Wiki move-to-drive task completed successfully.")
-			return status, true, nil
-		}
-		if status.Failed() {
-			return status, false, errs.NewAPIError(
-				errs.SubtypeServerError,
-				"wiki move-to-drive task %s failed: %s",
-				taskID,
-				status.StatusLabel(),
-			)
-		}
-
-		fmt.Fprintf(
-			runtime.IO().ErrOut,
-			"Wiki move-to-drive status %d/%d: %s\n",
-			attempt,
-			wikiMoveToDrivePollAttempts,
-			status.StatusLabel(),
-		)
-	}
-
-	if err := ctx.Err(); err != nil {
-		return lastStatus, false, wrapWikiMoveToDrivePollContextError(
-			err, taskID, runtime.As(), wikiMoveToDriveProfileName(runtime),
-		)
-	}
-
-	if !hadSuccessfulPoll && lastErr != nil {
-		hint := fmt.Sprintf(
-			"the wiki move-to-drive task was created but every status poll failed (task_id=%s)\nretry status lookup with: %s",
-			taskID,
-			wikiMoveToDriveTaskResultCommand(taskID, runtime.As(), wikiMoveToDriveProfileName(runtime)),
-		)
-		if _, ok := errs.ProblemOf(lastErr); ok {
-			return lastStatus, false, appendWikiProblemHint(lastErr, hint)
-		}
-		return lastStatus, false, errs.NewInternalError(errs.SubtypeUnknown, "%s", lastErr.Error()).
-			WithHint("%s", hint).
-			WithCause(lastErr)
-	}
-
-	return lastStatus, false, nil
-}
-
-func parseWikiMoveToDriveTaskStatus(taskID string, task map[string]interface{}) (wikiMoveToDriveTaskStatus, error) {
-	if task == nil {
-		return wikiMoveToDriveTaskStatus{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki task response missing task")
-	}
-
-	result := common.GetMap(task, wikiMoveToDriveResult)
-	if result == nil {
-		return wikiMoveToDriveTaskStatus{}, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"wiki task response missing %s",
-			wikiMoveToDriveResult,
-		)
-	}
-	statusCode, ok := common.GetFloatOK(result, "status")
-	if !ok {
-		return wikiMoveToDriveTaskStatus{}, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"wiki task response has missing or non-numeric %s.status",
-			wikiMoveToDriveResult,
-		)
-	}
-	if statusCode != wikiMoveToDriveStatusFailure &&
-		statusCode != wikiMoveToDriveStatusSuccess &&
-		statusCode != wikiMoveToDriveStatusProcessing {
-		return wikiMoveToDriveTaskStatus{}, errs.NewInternalError(
-			errs.SubtypeInvalidResponse,
-			"wiki task response has unsupported %s.status: %v",
-			wikiMoveToDriveResult,
-			statusCode,
-		)
-	}
-
-	status := wikiMoveToDriveTaskStatus{
-		TaskID:    common.GetString(task, "task_id"),
-		Status:    int(statusCode),
-		StatusMsg: common.GetString(result, "status_msg"),
-		ObjToken:  common.GetString(result, "obj_token"),
-		ObjType:   common.GetString(result, "obj_type"),
-		URL:       common.GetString(result, "url"),
-	}
-	if status.TaskID == "" {
-		status.TaskID = taskID
-	}
-	return status, nil
-}
-
-// Preserve the originating identity and profile so a resumed status lookup
-// uses the same credential context that created the async task.
-func wikiMoveToDriveTaskResultCommand(taskID string, identity core.Identity, profileName string) string {
-	asFlag := string(identity)
-	if asFlag == "" {
-		asFlag = "user"
-	}
-	profileFlag := ""
-	if profileName != "" {
-		profileFlag = fmt.Sprintf(" --profile %s", profileName)
-	}
-	return fmt.Sprintf(
-		"lark-cli%s drive +task_result --scenario wiki_move_to_drive --task-id %s --as %s",
-		profileFlag,
-		taskID,
-		asFlag,
-	)
-}
-
-func wikiMoveToDriveProfileName(runtime *common.RuntimeContext) string {
-	if runtime == nil || runtime.Config == nil {
-		return ""
-	}
-	return runtime.Config.ProfileName
-}
-
-func wrapWikiMoveToDrivePollContextError(err error, taskID string, identity core.Identity, profileName string) error {
-	if err == nil {
-		return nil
-	}
-	subtype := errs.SubtypeNetworkTransport
-	message := "wiki move-to-drive task polling cancelled: %s"
-	if errors.Is(err, context.DeadlineExceeded) {
-		subtype = errs.SubtypeNetworkTimeout
-		message = "wiki move-to-drive task polling deadline exceeded: %s"
-	}
-	return errs.NewNetworkError(subtype, message, err).
-		WithHint("the task may still be running; retry status lookup with: %s", wikiMoveToDriveTaskResultCommand(taskID, identity, profileName)).
-		WithCause(err)
-}

shortcuts/wiki/wiki_move_to_drive_test.go

@@ -1,481 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package wiki
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"net/http"
-	"reflect"
-	"strings"
-	"sync"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-type fakeWikiMoveToDriveClient struct {
-	moveTaskID string
-	moveErr    error
-	taskStatus []wikiMoveToDriveTaskStatus
-	taskErrs   []error
-	taskHooks  []func()
-
-	moveSpecs []wikiMoveToDriveSpec
-	taskCalls []string
-}
-
-func (fake *fakeWikiMoveToDriveClient) MoveWikiToDrive(ctx context.Context, spec wikiMoveToDriveSpec) (string, error) {
-	fake.moveSpecs = append(fake.moveSpecs, spec)
-	if fake.moveErr != nil {
-		return "", fake.moveErr
-	}
-	return fake.moveTaskID, nil
-}
-
-func (fake *fakeWikiMoveToDriveClient) GetMoveWikiToDriveTask(ctx context.Context, taskID string) (wikiMoveToDriveTaskStatus, error) {
-	idx := len(fake.taskCalls)
-	fake.taskCalls = append(fake.taskCalls, taskID)
-	if idx < len(fake.taskHooks) && fake.taskHooks[idx] != nil {
-		fake.taskHooks[idx]()
-	}
-	if idx < len(fake.taskErrs) && fake.taskErrs[idx] != nil {
-		return wikiMoveToDriveTaskStatus{TaskID: taskID, Status: wikiMoveToDriveStatusProcessing}, fake.taskErrs[idx]
-	}
-	if idx < len(fake.taskStatus) {
-		status := fake.taskStatus[idx]
-		if status.TaskID == "" {
-			status.TaskID = taskID
-		}
-		return status, nil
-	}
-	return wikiMoveToDriveTaskStatus{TaskID: taskID, Status: wikiMoveToDriveStatusProcessing}, nil
-}
-
-var wikiMoveToDrivePollMu sync.Mutex
-
-func withSingleWikiMoveToDrivePoll(t *testing.T) {
-	withWikiMoveToDrivePoll(t, 1)
-}
-
-func withWikiMoveToDrivePoll(t *testing.T, attempts int) {
-	t.Helper()
-	wikiMoveToDrivePollMu.Lock()
-
-	previousAttempts, previousInterval := wikiMoveToDrivePollAttempts, wikiMoveToDrivePollInterval
-	wikiMoveToDrivePollAttempts, wikiMoveToDrivePollInterval = attempts, 0
-	t.Cleanup(func() {
-		wikiMoveToDrivePollAttempts, wikiMoveToDrivePollInterval = previousAttempts, previousInterval
-		wikiMoveToDrivePollMu.Unlock()
-	})
-}
-
-func newWikiMoveToDriveRuntime(t *testing.T, identity core.Identity) (*common.RuntimeContext, *bytes.Buffer) {
-	t.Helper()
-	cfg := wikiTestConfig()
-	factory, _, stderr, _ := cmdutil.TestFactory(t, cfg)
-	runtime := common.TestNewRuntimeContextWithIdentity(nil, cfg, identity)
-	runtime.Factory = factory
-	return runtime, stderr
-}
-
-func TestWikiMoveToDriveDeclaredContract(t *testing.T) {
-	t.Parallel()
-
-	wantScopes := []string{"space:document:move", "wiki:space:read"}
-	if !reflect.DeepEqual(WikiMoveToDrive.Scopes, wantScopes) {
-		t.Fatalf("WikiMoveToDrive.Scopes = %v, want %v", WikiMoveToDrive.Scopes, wantScopes)
-	}
-	if WikiMoveToDrive.Risk != "write" {
-		t.Fatalf("WikiMoveToDrive.Risk = %q, want write", WikiMoveToDrive.Risk)
-	}
-}
-
-func TestValidateWikiMoveToDriveSpec(t *testing.T) {
-	t.Parallel()
-
-	t.Run("requires node token", func(t *testing.T) {
-		err := validateWikiMoveToDriveSpec(wikiMoveToDriveSpec{})
-		requireWikiValidationParams(t, err, "--node-token")
-	})
-
-	t.Run("rejects unsafe folder token", func(t *testing.T) {
-		err := validateWikiMoveToDriveSpec(wikiMoveToDriveSpec{
-			NodeToken:   "wikcnABC",
-			FolderToken: "../folder",
-		})
-		requireWikiValidationParams(t, err, "--folder-token")
-		cause := errors.Unwrap(err)
-		if cause == nil || !errors.Is(err, cause) {
-			t.Fatal("validation error must preserve its path-validation cause")
-		}
-	})
-
-	t.Run("accepts optional folder", func(t *testing.T) {
-		err := validateWikiMoveToDriveSpec(wikiMoveToDriveSpec{NodeToken: "wikcnABC"})
-		if err != nil {
-			t.Fatalf("validateWikiMoveToDriveSpec() error = %v", err)
-		}
-	})
-}
-
-func TestWikiMoveToDriveRequestBodyOmitsEmptyFolder(t *testing.T) {
-	t.Parallel()
-
-	withoutFolder := (wikiMoveToDriveSpec{NodeToken: "wikcnABC"}).RequestBody()
-	if _, exists := withoutFolder["folder_token"]; exists {
-		t.Fatalf("empty folder_token must be omitted, got %#v", withoutFolder)
-	}
-
-	withFolder := (wikiMoveToDriveSpec{NodeToken: "wikcnABC", FolderToken: "fldABC"}).RequestBody()
-	if withFolder["folder_token"] != "fldABC" {
-		t.Fatalf("RequestBody() = %#v, want folder_token=fldABC", withFolder)
-	}
-}
-
-func TestBuildWikiMoveToDriveDryRun(t *testing.T) {
-	t.Parallel()
-
-	steps := decodeDryRunAPIs(t, buildWikiMoveToDriveDryRun(wikiMoveToDriveSpec{
-		NodeToken:   "wikcnABC",
-		FolderToken: "fldABC",
-	}))
-	if len(steps) != 2 {
-		t.Fatalf("len(api) = %d, want 2", len(steps))
-	}
-	if steps[0].Method != "POST" || steps[0].URL != "/open-apis/wiki/v2/nodes/wikcnABC/move_wiki_to_docs" {
-		t.Fatalf("POST step = %#v", steps[0])
-	}
-	if steps[0].Body["folder_token"] != "fldABC" {
-		t.Fatalf("POST body = %#v", steps[0].Body)
-	}
-	if steps[1].Method != "GET" || steps[1].URL != "/open-apis/wiki/v2/tasks/%3Ctask_id%3E" {
-		t.Fatalf("GET step = %#v", steps[1])
-	}
-	if steps[1].Params["task_type"] != wikiMoveToDriveTaskType {
-		t.Fatalf("task params = %#v", steps[1].Params)
-	}
-}
-
-func TestParseWikiMoveToDriveTaskStatus(t *testing.T) {
-	t.Parallel()
-
-	t.Run("success with task id fallback and result fields", func(t *testing.T) {
-		status, err := parseWikiMoveToDriveTaskStatus("signed-task-id", map[string]interface{}{
-			"move_wiki_to_docs_result": map[string]interface{}{
-				"status":     float64(0),
-				"status_msg": "success",
-				"obj_token":  "docxABC",
-				"obj_type":   "docx",
-				"url":        "https://example.feishu.cn/docx/docxABC",
-			},
-		})
-		if err != nil {
-			t.Fatalf("parseWikiMoveToDriveTaskStatus() error = %v", err)
-		}
-		if status.TaskID != "signed-task-id" || !status.Ready() || status.Failed() {
-			t.Fatalf("status = %+v", status)
-		}
-		if status.ObjToken != "docxABC" || status.ObjType != "docx" || status.URL == "" {
-			t.Fatalf("result fields = %+v", status)
-		}
-	})
-
-	t.Run("rejects missing dedicated result", func(t *testing.T) {
-		_, err := parseWikiMoveToDriveTaskStatus("task", map[string]interface{}{})
-		problem, ok := errs.ProblemOf(err)
-		if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeInvalidResponse {
-			t.Fatalf("error = %T %v, want internal/invalid_response", err, err)
-		}
-	})
-
-	t.Run("rejects missing status", func(t *testing.T) {
-		_, err := parseWikiMoveToDriveTaskStatus("task", map[string]interface{}{
-			"move_wiki_to_docs_result": map[string]interface{}{},
-		})
-		problem, ok := errs.ProblemOf(err)
-		if !ok || problem.Subtype != errs.SubtypeInvalidResponse {
-			t.Fatalf("error = %T %v, want invalid_response", err, err)
-		}
-	})
-
-	for name, rawStatus := range map[string]interface{}{
-		"null":          nil,
-		"string":        "processing",
-		"fractional":    0.5,
-		"unknown value": 2,
-	} {
-		t.Run("rejects "+name+" status", func(t *testing.T) {
-			_, err := parseWikiMoveToDriveTaskStatus("task", map[string]interface{}{
-				"move_wiki_to_docs_result": map[string]interface{}{"status": rawStatus},
-			})
-			problem, ok := errs.ProblemOf(err)
-			if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeInvalidResponse {
-				t.Fatalf("error = %T %v, want internal/invalid_response", err, err)
-			}
-		})
-	}
-}
-
-func TestRunWikiMoveToDriveSuccess(t *testing.T) {
-	withSingleWikiMoveToDrivePoll(t)
-	runtime, stderr := newWikiMoveToDriveRuntime(t, core.AsUser)
-	client := &fakeWikiMoveToDriveClient{
-		moveTaskID: "raw-task-signature",
-		taskStatus: []wikiMoveToDriveTaskStatus{{
-			Status:    wikiMoveToDriveStatusSuccess,
-			StatusMsg: "success",
-			ObjToken:  "docxABC",
-			ObjType:   "docx",
-			URL:       "https://example.feishu.cn/docx/docxABC",
-		}},
-	}
-
-	out, err := runWikiMoveToDrive(context.Background(), client, runtime, wikiMoveToDriveSpec{
-		NodeToken:   "wikcnABC",
-		FolderToken: "fldABC",
-	})
-	if err != nil {
-		t.Fatalf("runWikiMoveToDrive() error = %v", err)
-	}
-	if out["task_id"] != "raw-task-signature" || out["ready"] != true || out["failed"] != false {
-		t.Fatalf("output = %#v", out)
-	}
-	if out["obj_token"] != "docxABC" || out["obj_type"] != "docx" || out["url"] == "" {
-		t.Fatalf("output result fields = %#v", out)
-	}
-	if len(client.moveSpecs) != 1 || client.moveSpecs[0].FolderToken != "fldABC" {
-		t.Fatalf("move specs = %#v", client.moveSpecs)
-	}
-	if !strings.Contains(stderr.String(), "completed successfully") {
-		t.Fatalf("stderr = %q", stderr.String())
-	}
-}
-
-func TestRunWikiMoveToDriveTimeoutReturnsResumeCommand(t *testing.T) {
-	withSingleWikiMoveToDrivePoll(t)
-	runtime, _ := newWikiMoveToDriveRuntime(t, core.AsBot)
-	runtime.Config.ProfileName = "secondary"
-	client := &fakeWikiMoveToDriveClient{
-		moveTaskID: "raw-task-signature",
-		taskStatus: []wikiMoveToDriveTaskStatus{{Status: wikiMoveToDriveStatusProcessing}},
-	}
-
-	out, err := runWikiMoveToDrive(context.Background(), client, runtime, wikiMoveToDriveSpec{NodeToken: "wikcnABC"})
-	if err != nil {
-		t.Fatalf("runWikiMoveToDrive() error = %v", err)
-	}
-	if out["ready"] != false || out["failed"] != false || out["timed_out"] != true {
-		t.Fatalf("timeout output = %#v", out)
-	}
-	nextCommand, _ := out["next_command"].(string)
-	if !strings.HasPrefix(nextCommand, "lark-cli --profile secondary drive +task_result") ||
-		!strings.Contains(nextCommand, "--scenario wiki_move_to_drive") ||
-		!strings.Contains(nextCommand, "--as bot") {
-		t.Fatalf("next_command = %q", nextCommand)
-	}
-}
-
-func TestPollWikiMoveToDriveContinuesFromProcessingToSuccess(t *testing.T) {
-	withWikiMoveToDrivePoll(t, 2)
-	runtime, _ := newWikiMoveToDriveRuntime(t, core.AsUser)
-	client := &fakeWikiMoveToDriveClient{
-		taskStatus: []wikiMoveToDriveTaskStatus{
-			{Status: wikiMoveToDriveStatusProcessing},
-			{Status: wikiMoveToDriveStatusSuccess, ObjToken: "docxABC"},
-		},
-	}
-
-	status, ready, err := pollWikiMoveToDriveTask(context.Background(), client, runtime, "signed-task-id")
-	if err != nil || !ready || !status.Ready() || status.ObjToken != "docxABC" {
-		t.Fatalf("status=%+v ready=%t err=%v", status, ready, err)
-	}
-	if len(client.taskCalls) != 2 {
-		t.Fatalf("task calls = %v, want two attempts", client.taskCalls)
-	}
-}
-
-func TestPollWikiMoveToDriveRecoversFromTransientError(t *testing.T) {
-	withWikiMoveToDrivePoll(t, 2)
-	runtime, _ := newWikiMoveToDriveRuntime(t, core.AsUser)
-	requestTimeout := errs.NewNetworkError(errs.SubtypeNetworkTimeout, "temporary request timeout").
-		WithCause(context.DeadlineExceeded)
-	client := &fakeWikiMoveToDriveClient{
-		taskErrs: []error{requestTimeout},
-		taskStatus: []wikiMoveToDriveTaskStatus{
-			{},
-			{Status: wikiMoveToDriveStatusSuccess, ObjToken: "docxABC"},
-		},
-	}
-
-	status, ready, err := pollWikiMoveToDriveTask(context.Background(), client, runtime, "signed-task-id")
-	if err != nil || !ready || !status.Ready() || status.ObjToken != "docxABC" {
-		t.Fatalf("status=%+v ready=%t err=%v", status, ready, err)
-	}
-	if len(client.taskCalls) != 2 {
-		t.Fatalf("task calls = %v, want two attempts", client.taskCalls)
-	}
-}
-
-func TestPollWikiMoveToDriveDoesNotSwallowFinalCancellation(t *testing.T) {
-	withWikiMoveToDrivePoll(t, 2)
-	runtime, _ := newWikiMoveToDriveRuntime(t, core.AsUser)
-	ctx, cancel := context.WithCancel(context.Background())
-	client := &fakeWikiMoveToDriveClient{
-		taskStatus: []wikiMoveToDriveTaskStatus{{Status: wikiMoveToDriveStatusProcessing}},
-		taskErrs:   []error{nil, context.Canceled},
-		taskHooks:  []func(){nil, cancel},
-	}
-
-	_, ready, err := pollWikiMoveToDriveTask(ctx, client, runtime, "signed-task-id")
-	if ready || !errors.Is(err, context.Canceled) {
-		t.Fatalf("ready=%t err=%T %v, want preserved context cancellation", ready, err, err)
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Category != errs.CategoryNetwork || problem.Subtype != errs.SubtypeNetworkTransport {
-		t.Fatalf("error = %T %v, want network/transport", err, err)
-	}
-}
-
-func TestRunWikiMoveToDriveFailureIsTypedAPIError(t *testing.T) {
-	withSingleWikiMoveToDrivePoll(t)
-	runtime, _ := newWikiMoveToDriveRuntime(t, core.AsUser)
-	client := &fakeWikiMoveToDriveClient{
-		moveTaskID: "raw-task-signature",
-		taskStatus: []wikiMoveToDriveTaskStatus{{Status: wikiMoveToDriveStatusFailure, StatusMsg: "failure"}},
-	}
-
-	_, err := runWikiMoveToDrive(context.Background(), client, runtime, wikiMoveToDriveSpec{NodeToken: "wikcnABC"})
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Category != errs.CategoryAPI || problem.Subtype != errs.SubtypeServerError {
-		t.Fatalf("error = %T %v, want api/server_error", err, err)
-	}
-}
-
-func TestPollWikiMoveToDrivePreservesTypedPollError(t *testing.T) {
-	withSingleWikiMoveToDrivePoll(t)
-	runtime, _ := newWikiMoveToDriveRuntime(t, core.AsUser)
-	cause := errors.New("connection reset")
-	upstream := errs.NewNetworkError(errs.SubtypeNetworkTransport, "poll failed").
-		WithCode(503).
-		WithHint("retry upstream").
-		WithCause(cause)
-	client := &fakeWikiMoveToDriveClient{taskErrs: []error{upstream}}
-
-	_, ready, err := pollWikiMoveToDriveTask(context.Background(), client, runtime, "raw-task-signature")
-	if ready || err != upstream {
-		t.Fatalf("ready=%t err=%T %v, want original typed error", ready, err, err)
-	}
-	if !errors.Is(err, cause) {
-		t.Fatal("typed poll error must preserve its cause")
-	}
-	problem, _ := errs.ProblemOf(err)
-	if problem.Code != 503 || !strings.Contains(problem.Hint, "retry upstream") || !strings.Contains(problem.Hint, "wiki_move_to_drive") {
-		t.Fatalf("problem = %+v", problem)
-	}
-}
-
-func TestWrapWikiMoveToDrivePollContextError(t *testing.T) {
-	t.Parallel()
-
-	err := wrapWikiMoveToDrivePollContextError(context.DeadlineExceeded, "task-id", core.AsUser, "secondary")
-	if !errors.Is(err, context.DeadlineExceeded) {
-		t.Fatal("wrapped deadline must preserve context.DeadlineExceeded")
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Category != errs.CategoryNetwork || problem.Subtype != errs.SubtypeNetworkTimeout {
-		t.Fatalf("error = %T %v, want network/timeout", err, err)
-	}
-	if !strings.Contains(problem.Hint, "wiki_move_to_drive") || !strings.Contains(problem.Hint, "--profile secondary") {
-		t.Fatalf("hint = %q", problem.Hint)
-	}
-}
-
-func TestWikiMoveToDriveExecuteCallsPostAndTaskEndpoint(t *testing.T) {
-	withSingleWikiMoveToDrivePoll(t)
-	factory, stdout, _, registry := cmdutil.TestFactory(t, wikiTestConfig())
-
-	moveStub := &httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/wiki/v2/nodes/wikcnABC/move_wiki_to_docs",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{"task_id": "raw-task-signature"},
-		},
-	}
-	registry.Register(moveStub)
-
-	var taskQuery string
-	taskStub := &httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/wiki/v2/tasks/raw-task-signature",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"task": map[string]interface{}{
-					// The external handler currently omits task.task_id for this
-					// task type, so the CLI must preserve the signed request ID.
-					"move_wiki_to_docs_result": map[string]interface{}{
-						"status":     0,
-						"status_msg": "success",
-						"obj_token":  "docxABC",
-						"obj_type":   "docx",
-						"url":        "https://example.feishu.cn/docx/docxABC",
-					},
-				},
-			},
-		},
-	}
-	taskStub.OnMatch = func(req *http.Request) { taskQuery = req.URL.RawQuery }
-	registry.Register(taskStub)
-
-	err := mountAndRunWiki(t, WikiMoveToDrive, []string{
-		"+move-to-drive",
-		"--node-token", "wikcnABC",
-		"--folder-token", "fldABC",
-		"--as", "user",
-	}, factory, stdout)
-	if err != nil {
-		t.Fatalf("mountAndRunWiki() error = %v", err)
-	}
-
-	body := decodeWikiCapturedJSONBody(t, moveStub)
-	if body["folder_token"] != "fldABC" {
-		t.Fatalf("captured POST body = %#v", body)
-	}
-	if !strings.Contains(taskQuery, "task_type=move_wiki_to_docs") {
-		t.Fatalf("task query = %q", taskQuery)
-	}
-	data := decodeWikiEnvelope(t, stdout)
-	if data["task_id"] != "raw-task-signature" || data["ready"] != true || data["obj_token"] != "docxABC" {
-		t.Fatalf("output = %#v", data)
-	}
-}
-
-func TestWikiMoveToDriveExecuteRejectsMissingTaskID(t *testing.T) {
-	factory, stdout, _, registry := cmdutil.TestFactory(t, wikiTestConfig())
-	registry.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/wiki/v2/nodes/wikcnABC/move_wiki_to_docs",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{},
-		},
-	})
-
-	err := mountAndRunWiki(t, WikiMoveToDrive, []string{
-		"+move-to-drive",
-		"--node-token", "wikcnABC",
-		"--as", "user",
-	}, factory, stdout)
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeInvalidResponse {
-		t.Fatalf("error = %T %v, want internal/invalid_response", err, err)
-	}
-}

sidecar/server-demo/handler_test.go

@@ -18,7 +18,6 @@ import (
 	"testing"
 
 	extcred "github.com/larksuite/cli/extension/credential"
-	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/sidecar"
@@ -586,15 +585,11 @@ func TestProxyHandler_StripsClientSuppliedAuthHeaders(t *testing.T) {
 }
 
 func TestBuildAllowedHosts(t *testing.T) {
-	feishu := core.Endpoints{
-		Open:     "https://open.feishu.cn",
-		Accounts: "https://accounts.feishu.cn",
-		MCP:      "https://mcp.feishu.cn",
+	feishu := struct{ Open, Accounts, MCP string }{
+		"https://open.feishu.cn", "https://accounts.feishu.cn", "https://mcp.feishu.cn",
 	}
-	lark := core.Endpoints{
-		Open:     "https://open.larksuite.com",
-		Accounts: "https://accounts.larksuite.com",
-		MCP:      "https://mcp.larksuite.com",
+	lark := struct{ Open, Accounts, MCP string }{
+		"https://open.larksuite.com", "https://accounts.larksuite.com", "https://mcp.larksuite.com",
 	}
 	hosts := buildAllowedHosts(feishu, lark)
 	// feishu hosts

skill-template/domains/drive.md

@@ -3,7 +3,6 @@
 
 ## 快速决策
 
-- 用户要把**已有 Wiki 节点移出知识库，放到 Drive 文件夹或“我的空间”根目录**：切到 `lark-wiki`，使用 `lark-cli wiki +move-to-drive`；不要把 Wiki token 直接交给 `drive +move`。执行前确认源节点与目标位置。
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 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`。

skill-template/domains/wiki.md

@@ -7,7 +7,6 @@
 ## 快速决策
 
 - 用户要**整理 / 盘点 / 归类 / 重构知识库、个人文档库、文档库目录或 Wiki 节点结构**，或要生成整理方案、目标目录树、移动计划时，不要只使用 Wiki 节点 API。必须先阅读 [`../lark-drive/references/lark-drive-workflow-knowledge-organize.md`](../lark-drive/references/lark-drive-workflow-knowledge-organize.md)，该 workflow 负责 Drive / Wiki / 个人文档库的统一入口解析、资源盘点、分类计划、写前确认和结果验证。
-- 用户要把**已有 Wiki 节点移出知识库，放到 Drive 文件夹或“我的空间”根目录**：使用 `wiki +move-to-drive`，不要使用 `wiki +move` 或 `drive +move`。执行前确认源节点与目标位置。
 - 用户给的是知识库 URL（`.../wiki/<token>`），且后续要查成员/加成员/删成员：先调用 `lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'` 获取 `space_id`，后续成员接口统一使用 `space_id`。
 - 用户要**删除**知识空间（`wiki +delete-space`）但只给了名称或 URL：**不能**把名称 / URL 原样传给 `--space-id`，必须先解析出真实 `space_id`。解析方式：
   - URL（`.../wiki/<token>`）：`lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}' --format json`，读 `data.node.space_id`。
@@ -38,4 +37,4 @@
 - `我的文档库` / `My Document Library` / `我的知识库` / `个人知识库` / `my_library` 都应视为 **Wiki personal library**，不是 Drive 根目录
 - 处理这类目标时，先解析 `my_library` 对应的真实 `space_id`，再执行 `wiki +move`、`wiki +node-create` 或其他 Wiki 写操作
 - 不要因为缺少显式 `space_id` 就退化成 `drive +move`
-- 如果用户明确说的是 Drive 文件夹、云空间根目录、`我的空间`，再按源对象分流：源对象是 Wiki 节点时用 `wiki +move-to-drive`，源对象已在 Drive 时用 `drive +move`
+- 如果用户明确说的是 Drive 文件夹、云空间根目录、`我的空间`，才进入 Drive 域处理

skills/lark-apps/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-apps
 version: 1.0.0
-description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、HTML静态站点发布、本地全栈开发、云端生成迭代、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、应用角色与成员管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、应用角色/角色成员、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
+description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、HTML静态站点发布、本地全栈开发、云端生成迭代、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、线上日志、接口请求量、错误量、延迟、访问量、环境变量时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -12,15 +12,15 @@ metadata:
 
 妙搭应用属于用户资产。默认用 `--as user`；认证、scope、exit-10、高风险确认、`_notice` 等通用处理只读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不要在本 skill 里复制。妙搭应用有三条开发路径：**本地全栈**（拉源码本地写）/ **HTML 托管**（发布静态产物）/ **云端会话**（妙搭 AI 生成）。
 
-## 身份与授权
+## 身份与一次性授权
 
-妙搭应用是用户的个人资产，统一 `--as user`（见开头）。已有用户身份可用时直接执行业务命令，**不要为了预防权限问题主动重新登录**，否则可能中断原任务并触发不必要的设备授权。仅当 CLI 明确返回未登录或缺少本域 scope 时，一次性执行：
+妙搭应用是用户的个人资产，统一 `--as user`（见开头）。**首次操作前先一次性把本域 scope 全拿到**，避免每条命令首次跑都触发新一轮授权，或未授权直接打到 openapi 导致服务端报错：
 
 ```bash
 lark-cli auth login --domain apps
 ```
 
-因缺权限失败（`error.subtype == "missing_scope"`）时的通用处理见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，同样按 `--domain apps` 授权；授权成功后只恢复原业务操作，不扩展任务范围。
+因缺权限失败（`error.subtype == "missing_scope"`）时的通用处理见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，同样按 `--domain apps` 授权。
 
 ## 意图路由
 
@@ -33,19 +33,17 @@ lark-cli auth login --domain apps
 | 查单个应用详情（类型、名称、发布状态等） | `+get --app-id <app_id>` | [`lark-apps-get.md`](references/lark-apps-get.md) |
 | 改应用名或描述 | `+update` | [`lark-apps-update.md`](references/lark-apps-update.md) |
 | 发布本地 `index.html` 或静态目录为可访问 URL | `+html-publish` | [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md) |
-| 开发已有应用 / 初始化本地仓库（开发方式已定为本地后；先解析 app_id，勿 `+create` 新建） | `+init`（或手动 `+git-credential-init` + 原生 git）。**执行前必读** [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md)；修改源码还须遵守下方「平台资源与应用源码边界」 | [`lark-apps-init.md`](references/lark-apps-init.md), [`lark-apps-git-credential.md`](references/lark-apps-git-credential.md) |
+| 开发已有应用 / 初始化本地仓库（开发方式已定为本地后；先解析 app_id，勿 `+create` 新建） | `+init`（或手动 `+git-credential-init` + 原生 git）。**执行前必读** [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md)，含端到端流程和领域规则 | [`lark-apps-init.md`](references/lark-apps-init.md), [`lark-apps-git-credential.md`](references/lark-apps-git-credential.md) |
 | 本地开发时 `.env.local` 损坏/丢失，重新拉取启动期环境变量 | `+env-pull` | [`lark-apps-env-pull.md`](references/lark-apps-env-pull.md) |
 | 管理应用环境变量（查看/设置/删除） | `+env-list`, `+env-set`, `+env-delete` | [`lark-apps-env.md`](references/lark-apps-env.md) |
 | 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`, `+log-get`, `+trace-list`, `+trace-get`, `+metric-list`, `+analytics-list` | [`lark-apps-observability.md`](references/lark-apps-observability.md) |
 | 看表 / 看结构 / 初始化多环境 / 导入导出数据 / 变更追溯 / 行级审计 / dev→online 发布 / 时间点恢复 / 查 DB 用量 | `+db-table-list`、`+db-table-get`、`+db-env-create`、`+db-data-export`/`+db-data-import`、`+db-changelog-list`、`+db-audit-status`/`+db-audit-enable`/`+db-audit-disable`/`+db-audit-list`、`+db-env-diff`/`+db-env-migrate`、`+db-recovery-diff`/`+db-recovery-apply`、`+db-quota-get` | [`lark-apps-db.md`](references/lark-apps-db.md) |
-| 逐条执行 SQL（SELECT / DML / DDL）；建表 / 改表 / 写 SQL 的平台规范 | `+db-execute` | [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)（含「平台 SQL 规范」：审计列 / RLS / `user_profile` / 禁用 SQL / PG 陷阱） |
+| 逐条执行 SQL（SELECT / DML / DDL） | `+db-execute` | [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md) |
 | 管理应用文件存储：上传/下载本地文件、列出/查看/删除已存文件、生成临时分享链接、查存储用量 | `+file-upload`/`+file-download`/`+file-list`/`+file-get`/`+file-sign`/`+file-delete`/`+file-quota-get` | [`lark-apps-file.md`](references/lark-apps-file.md) |
 | **部署/上线全栈应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | `+release-create`（部署上线动作）, `+release-get`（轮询发布结果，finished 给 online_url / failed 给 error_logs）, `+release-list` | [`lark-apps-release-create.md`](references/lark-apps-release-create.md), [`lark-apps-release-get.md`](references/lark-apps-release-get.md), [`lark-apps-release-list.md`](references/lark-apps-release-list.md) |
 | 设置或查看运行时可见范围 | `+access-scope-set`, `+access-scope-get` | 对应 access-scope reference |
-| 管理 `app_...` 应用内角色、角色成员，或查询用户匹配角色 | `+role-list/get/create/update/delete`, `+role-member-list/add/remove`, `+role-match-list` | [`lark-apps-role.md`](references/lark-apps-role.md) |
 | 云端 Agent 生成/迭代应用（开发方式已定为云端后） | `+session-create` -> `+chat` -> `+session-get` | [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) |
 | 管理妙搭应用开放 API Key（创建/查看/启停/重置/删除凭证；密钥仅 create/reset 一次性返回） | `+openapi-key-list/get/create/update/enable/disable/delete/reset` | [`lark-apps-openapi-key.md`](references/lark-apps-openapi-key.md) |
-| 管理妙搭应用自动化触发器（定时/记录变更/Webhook/飞书审批四类触发器的查询/创建/更新/启停；Webhook URL·Token 一次性回显、不落盘） | `+automation-list/get/create/update/enable/disable` | [`lark-apps-automation.md`](references/lark-apps-automation.md) |
 | 查看某次会话某一轮（turn）的回复消息（含仍在生成中的本轮）/ 导出上一轮模型回复（"这一轮回复了什么""上一轮的回复""导出某轮消息"） | 先 `+session-get`（取 `latest_turn.turn_id`）-> `+session-messages-list --turn-id <id>`（仅 user 身份；分页用 `--page-token`） | [`lark-apps-session-messages-list.md`](references/lark-apps-session-messages-list.md) |
 | 外部能力(AI模型能力和飞书平台能力)集成/插件/Plugin/Capability | `+plugin-install`, `+plugin-list`, `+plugin-uninstall` | [`lark-apps-plugin-install.md`](references/lark-apps-plugin-install.md), [`lark-apps-plugin-uninstall.md`](references/lark-apps-plugin-uninstall.md), [`lark-apps-plugin-list.md`](references/lark-apps-plugin-list.md) |
 
@@ -79,15 +77,10 @@ lark-cli auth login --domain apps
 - 发布态链接来源：html → `+html-publish` 的 `data.url`；全栈 → `+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`。
 - **可见范围**：发布态链接（html 的 `data.url`、全栈的 `online_url`）默认仅**创建者可见**，发给他人对方会无权限打不开。当可分享链接交付给用户前，先告知当前仅本人可见，再询问是否用 `+access-scope-set`（`tenant`/`public`/`specific`）放开（可先 `+access-scope-get` 查当前范围）。
 
-## 平台资源与应用源码边界
+## 能力边界
 
-- `apps +role-*` 只管理平台角色资源；修改已初始化应用的源码（包括当前目录已经是应用项目）时，先查看工作区 `.agents/skills/`，完整读取与任务匹配的领域 skill，再按其路由读取所需 reference。角色鉴权或运行态角色管理读应用内 `authz-guide`，不能用本 skill 的平台命令参考推断运行时合同。
-- `lark-cli` 只用于开发过程中的平台资源核验或变更。应用运行时代码必须使用工程内领域 skill 规定的 SDK，禁止通过 `exec` 或子进程调用 `lark-cli`。
-- 平台回读出的当前资源 ID、名称和成员只用于事实核验，不自动构成业务策略；除非需求或应用内领域 skill 明确定义，禁止把当前样本硬编码成 allowlist、denylist、只读集合或权限规则。
-- 实现领域 SDK 时，以实际包导出的类型和应用内领域 reference 记录的入参、响应路径为准；禁止修改 ambient `.d.ts`、补造宽松类型或强制断言，让猜测的 SDK 结构仅在本地“编译通过”。
-- typecheck/build 成功不等于合同正确。交付前逐项核对每个 SDK 调用的入参、响应取值路径和策略分支；涉及更新、删除等不同动作时，分别验证各自动作所需的完整状态，不能复用更弱的前置判断。
-- 源码任务交付前确认新增页面、Controller、Module 已接入真实 router/bootstrap，并运行项目现有 typecheck/build；只创建未接线文件不算完成。
-- `+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限；应用协作者/开发权限仍需使用妙搭 Web。自动化触发器请用 `+automation-*`（见「意图路由」）。
+- lark-cli **不支持**配置应用的权限（应用内 RBAC、成员角色、协作者权限）/ 自动化。`+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限。
+- 用户要配置权限 / 自动化时，引导其使用开发态连接前往云端开发（妙搭 web）处理。
 
 ## app_id 获取
 
@@ -107,4 +100,4 @@ lark-cli auth login --domain apps
 ## 高影响动作：确认与预授权
 
 - **预授权判定**：判断用户是否表达了"放手做完、不用中途逐步问我"的意图——明确免确认（如"别问 / 直接做 / 自己定"），或要求一气呵成做到完成（如"做完部署上线给我"）。是 → 整个流程按合理默认往下走、不再逐步确认（含 clone 到派生目录、发布等）；否 → 缺失参数（如目录）该问就问、高影响动作先确认。
-- **禁止预授权判定底线**（即便已预授权也不豁免）：① 会删/丢数据或不可逆的 DB 操作（判据见 [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)）先 `--dry-run` 确认；② `+role-delete`、`+role-member-remove --all`、批量移除成员必须先确认 app、role、成员范围和后果，不能从泛化"直接做"推导出 `--yes`；命令式“删除/移除某对象”只确定操作目标，不等于用户已确认不可逆后果，未明确确认时应在说明影响后停下请求确认；③ `+html-publish` 体积超限时（判据见 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)），立即停止并转述超限项。
+- **禁止预授权判定底线**（即便已预授权也不豁免）：① 会删/丢数据或不可逆的 DB 操作（判据见 [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)）先 `--dry-run` 确认；② `+html-publish` 体积超限时（判据见 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)），立即停止并转述超限项。

skills/lark-apps/references/lark-apps-access-scope-set.md

@@ -37,4 +37,4 @@ lark-cli apps +access-scope-set --app-id app_xxx --scope specific \
 
 若服务端返回"应用未发布/需先发布才能设置可见范围"，把这一情况转述给用户并询问是否现在发布，得到同意后再 `+release-create`，不要把这个 hint 当指令自动发布。
 
-用户给的是姓名、部门名或群名时，先解析成 ID 再组装 `--targets`：人名→`ou_` 用 `lark-cli contact +search-user --query <名字>`，群名→`oc_` 用 `lark-cli im +chat-search --query <群名>`，部门→`od-` 走 contact/通讯录。多候选时展示名称和 ID 让用户选，不要要求用户手填 `ou_` / `od-` / `oc_`。
+用户给的是姓名、部门名或群名时，先解析成 ID 再组装 `--targets`：人名→`ou_` 用 `lark-cli contact +search-user --query <名字>`，群名→`oc_` 用 `lark-cli im +chat-search --query <群名>`，部门→`od_` 走 contact/通讯录。多候选时展示名称和 ID 让用户选，不要要求用户手填 `ou_` / `od_` / `oc_`。

skills/lark-apps/references/lark-apps-automation.md

@@ -1,164 +0,0 @@
-# apps automation 触发器命令族 SOP
-
-管理妙搭应用的自动化触发器（定时 / 记录变更 / Webhook / 飞书审批四类）。全部操作需 `--as user`（AuthType: user）。`--help` 是参数细节的完整来源；本文件只记录 Agent 不看就会做错的领域规则。
-
-## 何时用本 skill（路由锚点）
-
-**当用户消息里出现「妙搭应用名 / app_id」+ 以下任一意图，路由本 skill，不要走 lark-event 或 lark-openapi-explorer：**
-
-- 「（每天 / 定时 / 每 N 小时 / 每周 X）自动跑 / 自动触发 / 定时同步」→ `+automation-create --trigger-type cron`
-- 「数据表 / 记录 / 表里 X 字段（新增 / 更新 / 删除 / 变化）时（触发 / 通知 / 处理）」→ `+automation-create --trigger-type record-change`
-- 「（webhook / 外部回调 / 外部系统调用 / HTTP 触发）」→ `+automation-create --trigger-type webhook`
-- 「（审批 / 报销 / 请假 / 出差）（通过 / 拒绝 / 提交 / 撤回）后自动 X」→ `+automation-create --trigger-type feishu-approval`
-- 「这个应用配了哪些（自动化 / 触发器 / 定时任务）」→ `+automation-list`
-- 「（暂停 / 停用 / 先别自动跑 / 关掉自动触发）某个（触发器 / 定时任务 / 自动化）」→ `+automation-disable`（不是 update 改条件、不是 delete——本 skill 不提供删除）
-- 「换 / 重置 webhook 回调地址 / URL」→ `+automation-update --reset-url --app-env <preview|runtime>`
-- 「换 / 重置 / 轮换 webhook token / bearer」→ `+automation-update --reset-token`
-
-**边界（防误路由）**：`lark-event` 是**实时事件流消费**（agent 长连接订阅事件），不管妙搭应用触发器的**配置**；用户说「配 / 设置一个触发器」而不是「订阅事件流」时，本 skill 才是正确选择。「审批通过触发」在妙搭应用语境下属于本 skill 的 `feishu-approval` 类型，不是 lark-event。
-
-### 回应「怎么配」类问题的正确姿势
-
-用户问「怎么配 / 怎么设置一个 X 触发器」时，**先展示完整命令模板 + 你对核心参数的推断**（让用户能确认你理解对了），再追问缺失的必填项（`--name` 之类）或可选项。**不要跳过展示、直接连环追问**，那样用户没法确认你有没有理解意图。
-
-示范：用户说「报销审批一旦通过就自动触发处理，怎么配？」
-- ✅ 正确：先写出「这是 feishu-approval 类型，命令模板：`apps +automation-create --app-id <id> --name <name> --trigger-type feishu-approval --event-type approval_instance --instance-status APPROVED [--approval-code <code>]`。需要你确认：(1) 触发器名 `<name>`；(2) 是否限定特定审批流程——限定就传 `--approval-code`（从飞书审批管理后台拿），不传则匹配所有审批定义」。
-- ❌ 错误：直接问「叫什么名字？监听哪个审批？」——用户没法确认你有没有把「审批通过」映射到 `--event-type approval_instance --instance-status APPROVED`。
-
-同理，cron/record-change/webhook 三类的「怎么配」都遵循此模式：先给命令 + 参数推断，后追问缺项。
-
-## 命令路由
-
-| 命令 | 用途 | Risk |
-|---|---|---|
-| `+automation-list` | 列出应用所有触发器（可按类型过滤、`--all` 聚合翻页） | read |
-| `+automation-get` | 查看单个触发器完整配置（Webhook Bearer Token 恒脱敏） | read |
-| `+automation-create` | 创建触发器，四类共用一条命令，按 `--trigger-type` 分派 | write |
-| `+automation-update` | 改条件/描述，或经专用 flag 管理 Webhook URL·Token | high-risk-write |
-| `+automation-enable` | 启用触发器（`status→enabled`，开始自动触发） | write |
-| `+automation-disable` | 停用触发器（`status→disabled`，停止触发，不删除） | write |
-
-触发器以 **应用内唯一的 `--name`** 定位（不是 id）。所有单条命令都用 `--app-id` + `--name`；名字忘了先 `+automation-list` 查。
-
-## 四类触发器 payload
-
-`--trigger-type` 用面向 Agent 的 kebab-case（`cron` / `record-change` / `webhook` / `feishu-approval`），CLI 内部转 snake_case 下推。类型专属 flag 只在对应类型生效。
-
-### cron（定时）
-
-```bash
-+automation-create --app-id <id> --name daily --trigger-type cron \
-  --cron '0 9 * * *' [--timezone Asia/Shanghai]
-```
-
-- `--cron` 是**五段式**（`minute hour day month weekday`），非六段。
-- **最小间隔 30 分钟**：`--cron '* * * * *'`（每分钟）或 `*/n`（n<30）会被 CLI 本地拦截报错；后端也会二次校验。
-- `--timezone` 缺省补 `Asia/Shanghai`（IANA 时区名）。
-
-### record-change（记录变更）
-
-```bash
-+automation-create --app-id <id> --name onUpd --trigger-type record-change \
-  --table <table_name> --event UPDATE [--fields '["status"]']
-```
-
-- `--event` 是**大写枚举**：`INSERT` / `UPDATE` / `UPSERT` / `DELETE`（CLI 会 uppercase，但请按枚举传）。
-- `--table` 是应用数据库里的**表名**（对应 `+db-table-list` / `+db-table-get` 输出里 `.name` 字段的值），必填。妙搭应用的 dataloom 表以名称作为稳定标识符，没有独立的 `table_id`。
-- `--fields` 是 JSON 字符串数组，仅对 `UPDATE`/`UPSERT` 有意义；`'["*"]'` 表示监听所有字段；不传表示不限定字段。
-
-### webhook（外部回调）
-
-```bash
-+automation-create --app-id <id> --name hook --trigger-type webhook \
-  [--white-ip-list '["1.1.1.1","2.2.2.2"]']
-```
-
-- 创建时可选 `--white-ip-list`（JSON 字符串数组）限制回调来源 IP。
-- 回调 URL 分 **preview / runtime 两套**，创建时不回显；用 `+automation-get` 查当前配置，用 `+automation-update --reset-url --app-env <preview|runtime>` 轮换。
-- Bearer Token 是回调鉴权凭证，见下方「凭证脱敏与一次性回显」。
-
-### feishu-approval（飞书审批）
-
-```bash
-+automation-create --app-id <id> --name apv --trigger-type feishu-approval \
-  --event-type approval_instance --instance-status APPROVED [--approval-code <code>]
-```
-
-- `--event-type` 必填，取 `approval_instance` 或 `approval_task`，决定状态用哪套 flag：
-  - `approval_instance` → `--instance-status`（可重复）
-  - `approval_task` → `--task-status`（可重复）
-- **领域规则**：状态按 `event-type` 分桶校验，两桶枚举**不完全相同**（`PENDING`/`APPROVED`/`REJECTED`/`REVERTED`/`OVERTIME_CLOSE`/`OVERTIME_RECOVER` 两桶共享；`TRANSFERRED`/`ROLLBACK`/`DONE` 仅 task 有；`CANCELED`/`DELETED` 仅 instance 有）；传错桶的状态会被 CLI 本地拦截，错误信息会打印该桶的合法值列表。具体枚举见命令 `--help`。
-
-## approval-code 获取路径
-
-`--approval-code` **可选**。不传时匹配所有审批定义；要限定某个审批流程时，从**飞书审批管理后台**获取具体的 code 传给它。触发器 OpenAPI 不提供审批定义查询能力，具体 code 需去审批管理后台查。
-
-## 凭证脱敏与一次性回显（安全关键）
-
-- `+automation-get` / `+automation-list`：**恒不返回明文 Bearer Token**——`trigger_condition.token_value` 被抹为 `null`。用户想知道「token 是什么」时，list/get 都查不到明文。
-- `+automation-update --enable-token` / `--reset-token`：明文 Bearer Token **仅当次 stdout 回显一次**，同时 stderr 打印一次性告警：
-  ```text
-  warning: this bearer token is shown only once and is NOT stored by lark-cli — copy it now and store it in your own secret manager.
-  ```
-- Webhook URL 同理：`--reset-url` 后新 URL 仅当次回显一次，旧 URL 立即失效。
-- CLI 不落盘任何明文 token/URL（不写 cache / config / recent / debug log / 错误信息）。
-- **Token 丢失只能 reset**：找不回，唯一恢复方式是 `+automation-update --reset-token`（旧 token 同时失效）。
-
-## 高危确认
-
-`+automation-update` 整体是 `high-risk-write`，任何一次调用都需显式 `--yes`；缺少时框架会要求确认（退出码 10）。**不要自动补 `--yes`**——需用户明确确认后再加。以下 Webhook 动作 flag 尤其不可逆：
-
-- `--reset-url`（旧回调 URL 立即失效，需配 `--app-env preview|runtime`）
-- `--reset-token`（旧 token 立即失效）
-- `--disable-token`（关闭 token 校验，**不可逆**）
-
-四个 Webhook 动作 flag（`--reset-url` / `--enable-token` / `--disable-token` / `--reset-token`）**每次只能传一个**。不确定影响时先跑 `--dry-run` 看将发出的请求（不含明文）。
-
-### 执行前必须完成的确认步骤（高危写强制协议）
-
-**在带 `--yes` 执行任何高危写之前，Agent 必须先完成以下 3 件事**，缺一不可——即使用户口气很急、即使命令一眼就明：
-
-1. **确认目标唯一**：不允许"猜名字"或"批量试所有可能的名字"。若不确定 `--name`，先 `+automation-list --app-id <id>` 让用户在候选中点名；`--name` 不明的绝不执行写操作，更不要 for 循环批量试。
-2. **确认可选参数已定**：`--reset-url` 必须由用户明确指定 `--app-env preview` 还是 `runtime`；不要默认取 runtime 或 preview。同一触发器的 preview/runtime 是两条独立的 URL，误重置另一条不可回退。
-3. **告知不可逆后果并等确认**：把即将发生的 3 件事复述给用户——（a）旧 URL/Token 立即永久失效；（b）新 URL/Token 仅当次回显一次、CLI 不保存；（c）本次操作无法撤销——等用户回复"确认"再加 `--yes` 跑。
-
-只要有一项没做，就先跟用户对齐、不要执行。这些是 skill 层的护栏，不是 CLI 层的（CLI 只强制 `--yes`，不强制上面 3 件事）。
-
-## ⚠️ 安全告警：无鉴权公网回调组合态
-
-`--disable-token`（关闭 Bearer Token 校验，不可逆）**叠加** `--white-ip-list '[]'`（清空 IP 白名单）会让 Webhook 触发器进入「**无鉴权公网回调**」组合态——**任何来源都能触发该 Webhook**，没有任何一道防线拦截。
-
-- 两道防线：Token 校验（谁能调）+ IP 白名单（从哪能调）。**不要同时关闭这两道防线。**
-- 若确需关闭 Token（例如对端无法带 Bearer 头），务必**保留 IP 白名单**收敛来源；反之若要放开 IP，务必**保留 Token 校验**。
-- 用户同时要求「关 token 校验 + 清空 IP 白名单」时，Agent 的正确响应是**在识别到该请求的第一时间**（不要等命令跑失败才补警告）向用户输出以下 3 件事，再等确认——不要只描述"没有任何防线"就停下：
-  1. 复述后果：这会形成无鉴权公网回调，任何来源都能触发。
-  2. **主动给出替代方案**：明确建议"要么只关 Token 保留 IP 白名单，要么只放开 IP 保留 Token"，让用户在保留一道防线的两条备选里选一条。
-  3. 只有用户明确回复"我理解风险、就是要两道都关"时，才继续按高危写协议（见上节「执行前必须完成的确认步骤」）走。
-
-## 默认 disabled
-
-`+automation-create` 创建后触发器**默认 disabled**，不会自动触发。需 `+automation-enable` 才开始按条件自动运行（且触发器执行的是**线上已发布**的应用代码——应用未发布时即便 enable 也不会有实际效果）。
-
-**Agent 行为约束**：用户只说"创建/配一个触发器"时，**不要**主动在同一个 turn 里 `+automation-enable`。让用户自己在下一轮决定是否启用；主动启用会：
-- 让 webhook 类型立即可被外部调用（原本用户可能只是想"备好 URL 稍后用"）
-- 让 cron 到点真实触发（原本用户可能想"先建好观察配置"）
-- 让 record-change 立即响应表变更
-
-创建成功后的推荐话术：`已创建 <name>，当前 disabled；需要真正开始自动运行时告诉我，我用 +automation-enable 启用它。` **不要**在创建成功后立即启用，即使 skill 里说"需 enable 才自动触发"——这条是给用户的说明，不是给 agent 的行动指令。
-
-## 常见错误与决策场景
-
-| 现象 / 用户意图 | 正确处理 |
-|---|---|
-| 创建报名字冲突（`--name` 应用内唯一） | 换名或加后缀重试 |
-| cron 报非法 / 间隔过小 | 检查是否五段式、分钟字段是否 `*` 或 `*/n`(n<30) |
-| `--reset-url` 报缺 app-env | 补 `--app-env preview` 或 `--app-env runtime` |
-| 想把 cron 触发器改成 webhook（跨类型改） | update 不支持换类型，本 skill 也不提供删除。旧触发器只能 `+automation-disable` 停用（保留在应用里），另建一个 webhook 触发器；若要真正清理旧触发器，请到妙搭 web 手动删除 |
-| 触发器 enable 了但不触发 | 确认应用**已发布**；触发器跑的是线上已发布代码 |
-| 「token 泄露了」 | 优先 `+automation-update --reset-token --yes` 轮换（旧 token 立即失效），而非直接 disable-token 关校验 |
-| 「回调 URL 泄露了」 | `+automation-update --reset-url --app-env <env> --yes` 轮换 |
-
-## 不在本 skill 范围
-
-- 审批定义查询、Webhook 消费端实现、实时触发日志 tail：本期不支持。
-- 身份选择、权限不足处理、exit-10 审批、通用「禁输出密钥」红线、高风险操作通用框架：见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不在此重复。

skills/lark-apps/references/lark-apps-db-execute.md

@@ -2,11 +2,9 @@
 
 经妙搭服务端在应用数据库执行 SQL。运行时命令事实以 `lark-cli apps +db-execute --help` 为准。
 
-> **写 SQL 前先看文末「平台 SQL 规范」**：妙搭底层是 PostgreSQL + 一层平台约束，SQL 内容不符合会被服务端直接拒或建出行为不对的表。最容易踩的三条：① 建业务表必须带 4 个审计列（`_created_at`/`_updated_at`/`_created_by`/`_updated_by`）+ 启用 RLS + 4 条 policy，一次调用里写全；② 人员字段用内置复合类型 `user_profile`（写入 `ROW('<user_id>')::user_profile`，查询解引用 `(field).user_id`）；③ `CREATE/DROP DATABASE·SCHEMA·USER·ROLE`、非白名单 `CREATE EXTENSION`、平台保留表 `auth`/`users` 会被硬拒，`online` 环境禁 DDL。
-
 ## 何时用
 
-用于通过妙搭服务端执行应用数据库 SQL。不要从环境变量里取连接串裸连数据库；本地调试也走这个 shortcut。写什么样的 SQL（平台约束、建表模板、`user_profile`、审计列、禁用 SQL、PG 陷阱）见文末「平台 SQL 规范」。
+用于通过妙搭服务端执行应用数据库 SQL。不要从环境变量里取连接串裸连数据库；本地调试也走这个 shortcut。
 
 ## 命令骨架
 
@@ -44,185 +42,3 @@ lark-cli apps +db-execute --app-id app_xxx --environment dev --sql - --yes < /Us
 - 多语句失败时，失败前的语句可能已经 commit 落地。不要整批重跑；按错误 message/hint 修失败语句，并从剩余语句继续。
 - 如果需要原子性，让用户在 SQL 内显式写 `BEGIN` / `COMMIT`，不要假设 CLI 会包事务。
 - 不要把数据库连接串从 env 中取出来裸连。
-
----
-
-# 平台 SQL 规范
-
-上面讲命令怎么调，这里讲**该写出什么样的 SQL**：妙搭底层是 PostgreSQL + 一层平台约束（RLS、审计列、`user_profile` 复合类型、禁用 SQL 白名单），不符合会被服务端直接拒或建出行为不对的表。看表 / 看结构用 [`+db-table-list`/`+db-table-get`](lark-apps-db.md)，别手写系统表查询模拟。
-
-## 平台禁用 SQL（硬拒绝）
-
-以下命中会被服务端拒，`error`（`type:"api"`）的 message/hint 会说明原因——先按 hint 修再重试，不要反复重试同一句。
-
-| 类别 | 禁止 |
-|---|---|
-| 数据库级 | `CREATE / DROP / ALTER DATABASE` |
-| Schema 级 | `CREATE / DROP SCHEMA` |
-| 用户 / 角色级 | `CREATE / DROP USER`、`CREATE / DROP / ALTER ROLE` |
-| Owner 切换 | `REASSIGN OWNED` / `DROP OWNED` |
-
-## 建表规范（CREATE TABLE）
-
-新建业务表必须：4 个审计列 + 启用 RLS + 4 条默认 policy，**放在同一次 `+db-execute` 调用里**（RLS / policy / COMMENT / INDEX 一起）。裸表名，不写 `public.` 或 schema 前缀。
-
-```sql
-CREATE TABLE IF NOT EXISTS <table> (
-  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-  -- ... 业务列 ...
-  name varchar(100) NOT NULL,
-  _created_at TIMESTAMP(3) WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  _created_by user_profile DEFAULT (
-    CASE
-      WHEN current_setting('app.user_id', TRUE) = '' THEN NULL
-      ELSE concat('(', current_setting('app.user_id', TRUE), ')')::user_profile
-    END
-  ),
-  _updated_at TIMESTAMP(3) WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  _updated_by user_profile DEFAULT (
-    CASE
-      WHEN current_setting('app.user_id', TRUE) = '' THEN NULL
-      ELSE concat('(', current_setting('app.user_id', TRUE), ')')::user_profile
-    END
-  )
-);
-
-ALTER TABLE <table> ENABLE ROW LEVEL SECURITY;
-
-CREATE POLICY service_role_bypass_policy ON <table>
-  TO service_role USING (true);
-
-CREATE POLICY "修改全部数据" ON <table>
-  AS PERMISSIVE FOR ALL TO authenticated USING (true);
-
-CREATE POLICY "查看全部数据" ON <table>
-  AS PERMISSIVE FOR SELECT TO authenticated, anon USING (true);
-
-CREATE POLICY "修改本人数据" ON <table>
-  AS PERMISSIVE FOR ALL TO authenticated USING (
-    (current_setting('app.user_id'::text) = ANY (ARRAY[]::text[]))
-    AND (current_setting('app.user_id'::text) = ((_created_by).user_id)::text)
-  );
-```
-
-建表流程：先 `+db-table-list` / `+db-table-get` 确认表不存在或看现有结构 → 生成 DDL → 向用户展示影响并取得授权 → `+db-execute ... --yes` 执行。
-
-## 审计列
-
-- 平台自动维护的四列固定叫 `_created_at` / `_updated_at` / `_created_by` / `_updated_by`（**下划线开头**）。查询 / 排序 / 过滤一律用这些名字，别写 `created_at`。
-- `_created_at` / `_updated_at` 在 INSERT 时可省略（有默认值）；需要业务归属时显式写 `_created_by` / `_updated_by`。
-- UPDATE 业务字段时建议同步 `_updated_at = CURRENT_TIMESTAMP` 和 `_updated_by`。
-
-## `user_profile` 复合类型
-
-平台内置类型 `(user_id varchar, name varchar, email varchar, avatar text, status integer)`，无需创建。**业务 SQL 只允许访问 `(field).user_id`**，不要依赖 `name` / `email` / `avatar` / `status`（可能为空或过期）。
-
-```sql
--- 写入 / 更新：用 ROW()::user_profile，更新时替换整个字段，不改单个属性
-INSERT INTO teacher (teacher_profile, class_id)
-VALUES (ROW('<user_id>')::user_profile, gen_random_uuid());
-
-UPDATE teacher SET teacher_profile = ROW('<user_id>')::user_profile
-WHERE (teacher_profile).user_id = '<old_user_id>';
-
--- 查询 / 过滤：解引用取 user_id；raw SQL 返回给前端前必须解引用，别直接返回复合类型
-SELECT (teacher_profile).user_id AS teacher_profile, class_id FROM teacher;
-
--- 索引 / 唯一性：表达式列用三重括号；表达式唯一性用 CREATE UNIQUE INDEX，
--- 不能用 ALTER TABLE ADD CONSTRAINT UNIQUE（不支持表达式列）
-CREATE INDEX idx_teacher_user_id ON teacher (((teacher_profile).user_id));
-CREATE UNIQUE INDEX uk_teacher_user_id ON teacher (((teacher_profile).user_id));
-```
-
-## DDL 规则
-
-| 场景 | 做法 |
-|---|---|
-| 加列 | `ALTER TABLE <t> ADD COLUMN IF NOT EXISTS <col> <type>`，相关 `COMMENT ON` 同次执行 |
-| 加索引 | `CREATE INDEX IF NOT EXISTS idx_<t>_<cols> ON <t>(...)` |
-| JSONB 类型声明 | 必须 `COMMENT ON COLUMN <t>.<col> IS '@type { ... }'` 声明 TypeScript 类型，和 CREATE / ALTER 同次调用 |
-| 加 NOT NULL 列 | 必须带 `DEFAULT` 让存量行自动填：`ADD COLUMN <col> <type> NOT NULL DEFAULT <值>` |
-| 删表 / 删列 | 有业务数据默认禁止；必须用户明确授权后才执行，并说明数据丢失风险 |
-| 强约束 | `UNIQUE` / `FOREIGN KEY` / `NOT NULL` 默认谨慎，不确定不加 |
-
-**多环境库加约束前先查 online 存量**：`dev` 干净不代表 `online` 干净，约束发布到 online 会撞线上存量数据而失败。发布前一律先用 `--environment online` 查清楚，按约束类型分三种：
-
-- **加唯一约束（`UNIQUE` / 唯一索引）**：线上不能有重复值。先查重复，有则先清理再加：
-
-  ```bash
-  lark-cli apps +db-execute --app-id app_xxx --environment online --sql \
-    "SELECT <cols>, count(*) FROM t GROUP BY <cols> HAVING count(*) > 1" --yes
-  ```
-
-- **已有列改 `NOT NULL`（收紧约束）**：线上该列不能有 NULL。先查 NULL 行数，有就先回填（`UPDATE t SET <col> = <默认值> WHERE <col> IS NULL`）再加约束：
-
-  ```bash
-  lark-cli apps +db-execute --app-id app_xxx --environment online --sql \
-    "SELECT count(*) FROM t WHERE <col> IS NULL" --yes
-  ```
-
-- **新加 `NOT NULL` 字段**：必须带 `DEFAULT`，且要求线上该表**无存量数据**，否则发布报错。线上已有数据时别直接加，改走三步安全变更：先 `ADD COLUMN <col> <type>`（可空）→ 回填 `UPDATE t SET <col> = <值>` → 再 `ALTER COLUMN <col> SET NOT NULL`。先查线上行数判断走哪条：
-
-  ```bash
-  lark-cli apps +db-execute --app-id app_xxx --environment online --sql \
-    "SELECT count(*) FROM t" --yes
-  ```
-
-## SELECT 规则
-
-| 规则 | 要求                                                               |
-|---|------------------------------------------------------------------|
-| 行数 | 结果集有硬上限（平台限制 1000 行），超限**报错而非静默截断**；大表必须显式 `LIMIT`、聚合或游标分页       |
-| 分页 | 大表优先游标分页 `WHERE id > <last_id> ORDER BY id LIMIT n`，避免大 `OFFSET` |
-| user_profile | 返回给前端前解引用：`(owner).user_id AS owner`                             |
-| 统计 | 总数用 `count(*)`、分组用 `GROUP BY`，别把全量拉到 agent 侧再统计                  |
-| 慢查询 | 用 `EXPLAIN (ANALYZE, BUFFERS)`；大表 Seq Scan 考虑加索引                 |
-
-## DML 规则
-
-**INSERT**
-- UUID 主键省略，交给 `DEFAULT gen_random_uuid()`；外键 UUID 用子查询取父表 id，不手写。
-- NOT NULL 且无默认值的列必须给值；批量 INSERT 每行列数一致。
-- 需要幂等用 `ON CONFLICT ... DO NOTHING / DO UPDATE`。
-- 标量子查询必须保证单行，非唯一条件加 `ORDER BY ... LIMIT 1`。
-
-**UPDATE**
-- **必须有明确 `WHERE`，禁止无条件 UPDATE**。
-- 用户说「修改 / 更新 / 改一下」数据时用 UPDATE，**禁止 DELETE + INSERT** 模式。
-- 更新 `user_profile` / 复合类型时替换整个字段。
-- 批量更新前影响范围不明确，先 `SELECT count(*)` 给用户确认。
-
-**DELETE / TRUNCATE**（属会丢数据的高影响操作，按上面「Agent 规则」的确认流程走）
-- 已有表 / 已有数据默认禁止；先 `SELECT count(*)` 展示命中行数、取得用户明确授权，再带 `--yes` 执行。
-- `TRUNCATE` 影响整表，视同高风险删除。
-
-```sql
-UPDATE task
-SET status = 'done', _updated_at = CURRENT_TIMESTAMP, _updated_by = ROW('<user_id>')::user_profile
-WHERE id = (SELECT id FROM task WHERE title = '梳理需求' ORDER BY _created_at DESC LIMIT 1);
-```
-
-## 常见 PostgreSQL 陷阱
-
-| 陷阱 | 正确做法 |
-|---|---|
-| 表名带 schema 前缀 | 业务表一律裸表名 `FROM orders`，别写 `public.orders` |
-| 保留字作标识符 | 避免 `user` / `order` / `desc` / `offset` / `references` 等 |
-| 内联 COMMENT | 禁止 `col TEXT COMMENT 'xx'`，用独立 `COMMENT ON COLUMN` |
-| 手写系统表查结构 | 常规结构查询用 `+db-table-list` / `+db-table-get`，别手写 `information_schema` / `pg_indexes` 模拟 |
-| 空数组类型不明 | 写 `ARRAY[]::text[]` 或 `'{}'::text[]` |
-| `ROUND` 报错 | 用 `ROUND(num::numeric, n)` 或 `ROUND(num::double precision)` |
-| `DISTINCT` + 窗口函数 | 分两层查询，先 DISTINCT 再窗口函数 |
-| MySQL 方言 | 不用 `SHOW TABLES` / `DESCRIBE` / 内联 `COMMENT`；用 `+db-table-*` 和 `COMMENT ON` |
-| 多语句以为自动回滚 | `A; B; C` 不自动包事务，B 失败时 A 已提交；要原子性显式 `BEGIN; ... COMMIT;`（见上「命令骨架」「Agent 规则」） |
-
-## 数据类型与设计
-
-| 项目 | 规则 |
-|---|---|
-| 主键 | 默认 `id uuid PRIMARY KEY DEFAULT gen_random_uuid()` |
-| 命名 | 表名单数、全小写、snake_case、无冗余后缀 |
-| 枚举 / 状态 | 用 `varchar(255)`，值用小写英文 + 下划线 |
-| JSONB | 必须 `COMMENT ON COLUMN ... IS '@type { ... }'` 声明类型 |
-| 附件 / 图片 | URL 用 `TEXT`，命名 `xxx_url` |
-| 约束 | `UNIQUE` / `FOREIGN KEY` / `NOT NULL` 默认谨慎，新增 NOT NULL 列优先带 `DEFAULT` |

skills/lark-apps/references/lark-apps-db.md

@@ -4,7 +4,7 @@
 
 ## 何时用
 
-用户要看应用里有哪些表 / 某张表的结构、把单库应用拆成 dev/online 多环境、把数据导进导出表、查谁在什么时候改了表结构或表数据、开关行级审计、把开发环境的库结构发布到线上、把库恢复到过去某个时间点、或看数据库用量时。逐条执行 SQL 走 [`+db-execute`](lark-apps-db-execute.md)；文件存储（上传/下载文件）走 [`lark-apps-file.md`](lark-apps-file.md)。**建表 / 改表 / 写 SQL 的平台内容规范**（审计列、RLS、`user_profile`、禁用 SQL、PG 陷阱）见 [`lark-apps-db-execute.md`](lark-apps-db-execute.md) 的「平台 SQL 规范」。
+用户要看应用里有哪些表 / 某张表的结构、把单库应用拆成 dev/online 多环境、把数据导进导出表、查谁在什么时候改了表结构或表数据、开关行级审计、把开发环境的库结构发布到线上、把库恢复到过去某个时间点、或看数据库用量时。逐条执行 SQL 走 [`+db-execute`](lark-apps-db-execute.md)；文件存储（上传/下载文件）走 [`lark-apps-file.md`](lark-apps-file.md)。
 
 ## 命令一览
 

skills/lark-apps/references/lark-apps-role.md

@@ -1,133 +0,0 @@
-# apps role 域命令（应用角色）
-
-管理妙搭应用内的平台角色、角色成员，以及查询某个用户命中的角色。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；身份、授权和高风险确认遵循本域 [`SKILL.md`](../SKILL.md)。
-
-## 何时用
-
-用户要列出、查看、创建、更新或删除某个妙搭应用内的平台角色，管理角色的用户、部门或群成员，或查询某个用户在应用中命中的角色时使用。多维表格 / Base 的角色与权限走 `lark-base`；设置谁能访问应用走 `+access-scope-*`，不要路由到本命令域。
-
-## 命令一览
-
-| 命令 | 做什么 | 关键参数 |
-|---|---|---|
-| `+role-list` | 分页列出角色，或按名称筛选角色 | `--app-id`、`--name`、`--page-size`/`--page-token` |
-| `+role-get` | 根据真实 `role_id` 读取角色详情 | `--app-id`、`--role-id` |
-| `+role-match-list` | 查询指定用户命中的角色 | `--app-id`、`--user-id` |
-| `+role-create` | 创建角色 | `--app-id`、`--name`、`--description`、`--role-id` |
-| `+role-update` | 更新角色名称或描述 | `--app-id`、`--role-id`、`--name`/`--description` |
-| `+role-delete` | 永久删除角色 | `--app-id`、`--role-id`、`--yes` |
-| `+role-member-list` | 查询角色的用户、部门和群成员 | `--app-id`、`--role-id`、`--member-type` |
-| `+role-member-add` | 向角色添加用户、部门或群成员 | `--app-id`、`--role-id`、`--users`/`--departments`/`--chats` |
-| `+role-member-remove` | 定向移除或清空角色成员 | `--app-id`、`--role-id`、成员参数或 `--all`、`--yes` |
-
-## 约定（先读）
-
-- `app_...` 标识的是妙搭应用，其角色和成员只使用 `apps +role-*` / `apps +role-member-*`；不要改走 Base 角色命令或裸 bitable API。
-- 角色名称不是 `role_id`。只有名称时优先用 `+role-list --name` 精确解析；若已取得完整分页列表，也可从中证明精确名称唯一命中。0 条如实报告，多条让用户消歧，唯一命中后才使用返回的真实 ID。
-- `+role-list` 返回 `has_more=true` 时，用本页 `page_token` 继续查询，直到 `has_more=false`；不要根据 `total` 补造条目。
-- `+role-list`、`+role-get`、`+role-match-list` 的角色数据分别位于 `data.items`、`data.role`、`data.roles`，不要混用。
-- 同一角色的写入及依赖该写入结果的操作必须串行。不同角色的独立操作只有在每次写入可单独追溯、失败不影响其它目标且分别验收时才可并行；否则保持串行。互不依赖的名称解析或只读查询可并行。
-
-## 各命令
-
-### 查询角色
-
-```bash
-lark-cli apps +role-list --app-id <app_id> --page-size 100
-lark-cli apps +role-list --app-id <app_id> --name '<exact_name>'
-lark-cli apps +role-get --app-id <app_id> --role-id <role_id>
-lark-cli apps +role-match-list --app-id <app_id> --user-id <ou_x>
-```
-
-整理角色列表时保留 `role_id`、`name` 和 `description`。不要猜测未知 `role_id`，也不要从同名候选中静默选择。
-`items=[]` 时直接报告当前没有角色；不要为表格补造“无”或 `N/A` 占位行。
-`+role-match-list --user-id` 只接受 `ou_...`；用户给的是姓名、邮箱或手机号时，先解析唯一 open ID，再查询命中角色。
-
-### 创建与更新
-
-```bash
-lark-cli apps +role-create --app-id <app_id> --name '<name>' \
-  --description '<description>'
-
-# 只修改名称
-lark-cli apps +role-update --app-id <app_id> --role-id <role_id> \
-  --name '<new_name>' --as user --format json
-
-# 只修改描述
-lark-cli apps +role-update --app-id <app_id> --role-id <role_id> \
-  --description '<new_description>' --as user --format json
-```
-
-- `--description` 和创建时的 `--role-id` 可选；仅在确实需要稳定 ID 时传 `--role-id`，创建后不能修改。
-- 更新时只传用户明确要求变更的字段。
-- 成功响应中的角色位于 `data.role`。只有用户要求独立验证，或结果将用于后续高风险操作时，才额外执行 `+role-get`。
-
-### 删除角色
-
-普通“删除某角色”请求只说明目标，**不等于不可逆确认**。如果用户尚未明确确认删除后果，本轮只能定位角色、读取完整成员并说明影响，最后请求确认；不得在同一轮自动追加 `--yes`。用户已明确确认不可逆删除时才继续。
-
-只有名称时仍按上述规则唯一解析，优先使用 `+role-list --name`。目标写前已不存在时立即停止，如实说明本次是 no-op、没有执行删除，不能把“当前不存在”表述为“删除成功”。
-
-删除前读取准确角色和完整成员范围，向用户说明 app、role、`users` / `departments` / `chats` 影响；得到不可逆删除确认后才使用 `--yes`：
-
-```bash
-lark-cli apps +role-get --app-id <app_id> --role-id <role_id>
-lark-cli apps +role-member-list --app-id <app_id> --role-id <role_id>
-lark-cli apps +role-delete --app-id <app_id> --role-id <role_id> --yes
-```
-
-成功响应包含匹配的 `data.role_id` 和 `data.deleted=true`。只有用户明确要求独立验证删除结果时，才再用 `+role-list --name` 检查目标 ID 已不存在。
-
-### 成员 ID 解析
-
-成员 flags 只接受 open ID：用户 `ou_...`、部门 `od-...`、群 `oc_...`。用户已提供对应类型的合法 open ID 时直接使用；只有名称或邮箱时才解析。
-对象类型以用户语义为准，不能互换解析器：用户走通讯录用户搜索，部门走部门搜索，群走群搜索。
-
-```bash
-# 用户：每个姓名或邮箱单独查询。
-lark-cli contact +search-user --query '<姓名或邮箱>' \
-  --exclude-external-users --page-size 30
-
-# 部门：拉完分页，只接受唯一的 open_department_id。
-lark-cli api POST /open-apis/contact/v3/departments/search \
-  --params '{"user_id_type":"open_id","department_id_type":"open_department_id","page_size":50}' \
-  --data '{"query":"<部门名称>"}'
-
-# 群：拉完分页，只接受名称精确匹配的唯一 chat_id。
-lark-cli im +chat-search --query '<群名称>' --page-size 50
-```
-
-- 只接受与输入姓名、邮箱或群名精确匹配的唯一结果；部门搜索只接受完整 query 的唯一 `od-...`。0 条、多条或分页未完成时停止写入并让用户补充或消歧。
-- 多个对象逐个解析。全部解析成功且总数不超过 100 后，按类型放入一次成员写入；任一对象失败时不要部分写入，也不要自动拆批。
-
-### 成员操作
-
-```bash
-# 省略 --member-type，返回完整 users / departments / chats。
-lark-cli apps +role-member-list --app-id <app_id> --role-id <role_id>
-
-lark-cli apps +role-member-add --app-id <app_id> --role-id <role_id> \
-  --users ou_x,ou_y --departments od-x --chats oc_x
-
-lark-cli apps +role-member-remove --app-id <app_id> --role-id <role_id> \
-  --users ou_x --yes
-
-# 清空成员，不删除角色。
-lark-cli apps +role-member-remove --app-id <app_id> --role-id <role_id> \
-  --all --yes
-```
-
-- `+role-member-list` 不分页；`--member-type` 只返回选中类型的字段，未返回的成员字段表示“未查询”而不是空。影响确认或完整比较时必须省略它。
-- 汇总 `--member-type` 结果时明确这是过滤投影，不得据此断言角色没有其它类型成员。
-- 用户要求 CLI 原生 table 时，直接执行 `+role-member-list --format table`；可原样转发或做事实摘要，不要先取 JSON 再手工重建一张替代表格。
-- 写入和依赖其结果的回读不得放进同一个并发批次；必须等待写入完整返回成功后，再单独发起回读。误并发时只能以写入完成后的新回读作为结果证据。
-- 添加前仅在用户要求独立证明或确认其他成员类型未变化时读取完整基线，并在写后完整回读；否则成功响应即可作为结果。
-- 定向移除前确认准确成员及影响。若需要证明结果，写后完整回读；不要把过滤结果当作完整成员集合。
-- `--all` 前读取完整成员范围并确认；成功后执行一次无过滤 `+role-member-list`，确认三个成员数组均为空。
-
-## 权限
-
-| 操作 | 所需 scope |
-|---|---|
-| list / get / member-list / match-list | `spark:app:read` |
-| create / update / delete / member-add / member-remove | `spark:app:write` |

skills/lark-base/SKILL.md

@@ -122,7 +122,7 @@ metadata:
 
 ## Dashboard / Workflow / Role
 
-- Dashboard 的复杂点是 block 的 `data_config`，不是 list/get/create/delete 命令参数。创建或更新 block 前先读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)，组件必须串行创建；`+dashboard-arrange` 是服务端智能布局，仅在用户明确要求重排/美化、或对本次会话从零新建的仪表盘做收尾整理时执行。`+dashboard-block-get-data` 读取图表最终计算结果，不返回 block 名称、类型、布局或 `data_config`；需要元数据先用 `+dashboard-block-get`。
+- Dashboard 的复杂点是 block 的 `data_config`，不是 list/get/create/delete 命令参数。创建或更新 block 前先读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)，组件必须串行创建；`+dashboard-arrange` 是服务端智能布局，只在用户明确要求重排/美化时执行。`+dashboard-block-get-data` 读取图表最终计算结果，不返回 block 名称、类型、布局或 `data_config`；需要元数据先用 `+dashboard-block-get`。
 - Workflow 的复杂点是 `steps` 结构。创建、更新或解释完整 workflow 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；enable/disable/list 只需确认 workflow ID、当前启停状态和用户意图。
 - Role 的复杂点是权限 JSON。角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)；`+role-create` 只支持自定义角色；`+role-update` 是 delta merge；角色 create/update 或解读完整配置时读权限 JSON SSOT [role-config.md](references/role-config.md)。`+role-delete` 只适用于自定义角色，系统角色不可删除；删除角色和关闭高级权限前必须确认目标和影响。
 

skills/lark-base/references/dashboard-block-data-config.md

@@ -90,10 +90,6 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 
 `sort.order`：`asc`（升序）/ `desc`（降序）
 
-只要写 `sort` 对象，就需要明确排序方向。CLI 会把 `sort.type` 为 `group` 或 `view` 且缺少 `order` 的情况规范化为 `order:"asc"`；`sort.type:"value"` 必须显式写 `order:"asc"` 或 `order:"desc"`，因为指标值排序方向会改变业务含义。
-
-如果表中行序就是业务顺序，首次创建 block 时就一次性设置 `sort:{"type":"view","order":"asc"}` 保留行序，避免创建后再二次更新排序条件。
-
 示例 — 柱状图按销售额降序：
 
 ```json
@@ -173,10 +169,9 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 - 长度/结构
   - `group_by` 最多 2 个；每项 `field_name` 必填
   - `group_by[].sort.type` 取值 `group|value|view`；`order` 取值 `asc|desc`
-- 规范化（CLI 自动处理；`--no-validate` 时不生效，`data_config` 原样透传给后端）
+- 规范化（CLI 自动处理）
   - `series[].rollup` 自动转成大写（如 `sum` → `SUM`）
   - `group_by[].sort.type/order` 自动转成小写
-  - `group_by[].sort.type` 为 `group` 或 `view` 且缺少 `order` 时，自动补 `order:"asc"`；`value` 排序不会自动补方向
 - 本地校验（可通过 `--no-validate` 跳过）
   - `+dashboard-block-create` 默认对 `data_config` 做轻量校验；失败会聚合错误并给出修复建议
   - `+dashboard-block-update` 不做强类型校验，由后端验证具体字段
@@ -269,35 +264,14 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 
 漏斗图（流程转化）：
 
-先判断用户要看的数值语义：
-
-- **当前数量**：统计每个当前状态/阶段下有多少记录，例如“各环节当前数量”“当前阶段分布”。源表有状态/阶段字段时，直接用 `count_all:true` + `group_by`。
-- **累计数量**：统计到达该阶段及其后续阶段（后缀和）的累计数量，例如“流程转化”“从 A 到 B 各环节转化”。此口径假设流程单向、无跳阶/回退、记录不删除；不满足时须用状态变更历史，不能对当前快照累加。如果表中已有累计数量字段或阶段汇总表，直接用该字段画漏斗图；否则先计算累计数量，创建并写入 helper 汇总表后再画图。
-
-当前数量：
-
 ```json
 {
   "table_name": "表名",
-  "count_all": true,
+  "series": [{ "field_name": "数值字段", "rollup": "SUM" }],
   "group_by": [{ "field_name": "状态字段", "mode": "integrated" }]
 }
 ```
 
-累计数量：
-
-```json
-{
-  "table_name": "流程汇总表名",
-  "series": [{ "field_name": "累计数量", "rollup": "SUM" }],
-  "group_by": [{ "field_name": "阶段字段", "mode": "integrated", "sort": {"type":"view","order":"asc"} }]
-}
-```
-
-如果只有当前状态数据但用户要看流程转化，需要先按业务阶段顺序计算每个阶段的累计数量，再创建 helper 汇总表（如：阶段、累计数量），用 `+record-batch-create` 一次写入后，按“累计数量”模板创建漏斗图。helper 表行序就是业务顺序时，首次创建 block 时一次性设置好 `group_by.sort`。
-
-> ⚠️ 注意:helper 汇总表仅用于源表无法直接聚合出目标形态的场景（如上面的累计数量漏斗图）。只要能在源表上直接用 `group_by` + `rollup`（含 `AVERAGE`）算出，就不需要新建 helper 表。
-
 词云（文本频率）：
 
 ```json

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

@@ -19,19 +19,12 @@ Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**
 | 修改组件 | `+dashboard-block-update` | 先读 block 现状，再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 决定替换哪些顶层 key |
 | 查看仪表盘有哪些组件 | `+dashboard-get` 或 `+dashboard-block-list` | 本页下方「查看仪表盘」 |
 | 读取图表计算结果 | `+dashboard-block-get-data` | 返回图表最终数据协议；需要 block 元数据先用 `+dashboard-block-get` |
-| 智能重排组件布局 | `+dashboard-arrange` | 用户明确要求重排，或本次会话新建仪表盘的收尾整理；无法指定精确位置 |
+| 智能重排组件布局 | `+dashboard-arrange` | 只在用户明确要求重排时执行；无法指定精确位置 |
 
 ## 典型场景工作流
 
 ### 场景 1：从 0 到 1 创建仪表盘
 
-从 0 到 1 创建仪表盘时，按用户需求规划组件的类型和数量，并注意以下要点：
-
-- 聚合方式：创建指标卡或分布图时优先把聚合写进 `data_config`，只有 Top N、字段取值探索、复杂筛选校验或 helper 汇总表场景才先用 `+data-query`。
-- Dry-run 边界：已按模板构造的简单指标卡、分布图、趋势图不需要逐个 `--dry-run` 后再真实创建；只有在调试 JSON、检查请求体、复杂自造 `data_config` 或处理 API validation 错误时才 dry-run。
-- 验证方式：通过创建接口返回值确认创建成功与否,只在结果不确定时用 `+dashboard-get` 或 `+dashboard-block-list` 确认仪表盘和组件存在,或调用 `+dashboard-block-get-data`读取计算结果验证。
-- 布局方式：`+dashboard-arrange` 仅两种情况使用：① 用户明确要求美化/重排；② 本次会话中从零新建的仪表盘，建完组件后做一次性布局整理。不是创建成功的必要步骤。
-
 示例：搭建一个销售数据分析仪表盘
 
 ```bash
@@ -70,7 +63,6 @@ lark-cli base +dashboard-block-create \
 
 # 第 5 步：组件创建完成后，使用 arrange 命令智能重排布局（可选但推荐）
 # 默认布局可能不够美观，arrange 会根据组件数量和类型自动优化布局
-# 若用户没有要求美化/重排，可先跳过此步骤；这不影响仪表盘和组件是否已创建成功
 lark-cli base +dashboard-arrange \
   --base-token xxx \
   --dashboard-id blk_xxx
@@ -133,12 +125,11 @@ lark-cli base +dashboard-block-update \
   --dashboard-id blk_xxx \
   --block-id chtxxxxxxxx \
   --data-config '{...}'
-
 ```
 
 ### 场景 4：重排仪表盘布局
 
-当用户明确要求对已有仪表盘进行布局重排或美化时使用（对本次会话从零新建的仪表盘，可在建完组件后直接做一次性整理，见场景 1）。
+当用户明确要求对已有仪表盘进行布局重排或美化时使用。
 
 > [!CAUTION]
 > - 排列结果是**服务端智能推荐**，不一定完全符合用户预期

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

@@ -347,30 +347,28 @@ value 使用预定义关键字机制，第一个元素为字符串常量名称
 |------|------|------|------|
 | `format` | string | 是 | 固定为 `"flat"`，表示返回扁平化的对象数组 |
 
-## CLI 出参详情
-
-CLI 输出标准信封 `{ok, identity, data}`（失败时为 `{ok:false, identity, error}`）。
+## API 出参详情
 
 **成功时：**
 
 ```json
-{"ok": true, "identity": "user", "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}}
+{"code": 0, "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}, "msg": ""}
 ```
 
 **失败时：**
 
 ```json
-{"ok": false, "identity": "user", "error": {"type": "api", "subtype": "unknown", "code": 800004006, "message": "...does not exist in table schema", "hint": "...", "log_id": "..."}}
+{"code": 800004006, "data": {"error": {"code": 800004006, ...}}, "msg": "DSL validation failed"}
 ```
 
 **Response 字段：**
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `ok` | bool | 是否成功 |
-| `identity` | string | 执行身份：`user` / `bot` |
-| `data.main_data` | []object | 查询结果数组，每个元素为一行数据（成功时） |
-| `error` | object | 失败时的 typed 错误，含 `type` / `subtype` / `code` / `message` / `hint` / `log_id` |
+| `code` | int | 状态码，0 为成功 |
+| `msg` | string | 错误信息 |
+| `data.main_data` | []object | 查询结果数组，每个元素为一行数据 |
+| `data.error` | object | 失败时的错误详情 |
 
 每行数据的字段值封装在 CellValue 中：
 

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

@@ -63,7 +63,6 @@ lark-cli calendar event.attendees create \
 - 时间参数是 **Unix 秒字符串**（非 ISO 8601）。
 - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天；单日全天日程两者相同。
 - 手动拆成“创建日程 + 添加参会人”两步时，若第二步失败，建议删除刚创建的空日程，避免遗留无参会人的日程。
-- 设置会议 owner：`+create` 不支持，需用完整 API 命令在 `vchat.meeting_settings.owner_id` 中设置，且必须同时设置 `vchat.vc_type` 为 `vc`（代表该日程为 VC 视频会议）。仅当以应用（bot）身份在应用日历上操作时生效；owner 必须为用户身份（`ou_` open_id），不能为非用户或外部租户用户。
 
 ## 参会人类型
 

skills/lark-drive/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-drive
 version: 1.0.0
-description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
+description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -20,12 +20,12 @@ metadata:
 
 ## 快速决策
 
-- 用户要把**已有 Wiki 节点移出知识库，放到 Drive 文件夹或“我的空间”根目录**：切到 `lark-wiki`，使用 `lark-cli wiki +move-to-drive`；不要把 Wiki token 直接交给 `drive +move`。这是会改变文档归属和权限继承的写操作，执行前确认源节点与目标位置。
 - 用户要**复制文档 / 创建副本 / 另存为副本**时，使用 `lark-cli drive files copy`。先用 `lark-cli schema drive.files.copy --format json` 确认参数；如果来源是 wiki URL/token，先用 `lark-cli drive +inspect` 获取底层 `token` 和 `type`，不要把 wiki token 直接当 `file_token`。`params.file_token` 传源文档 token，`data.folder_token` 传目标文件夹 token，`data.name` 传副本名称，`data.type` 传源文件类型（如 `docx` / `sheet` / `bitable` / `slides`）。示例：`lark-cli drive files copy --params '{"file_token":"<DOC_TOKEN>"}' --data '{"folder_token":"<FOLDER_TOKEN>","name":"<COPY_NAME>","type":"docx"}'`。如返回 `confirmation_required`，按 `lark-shared` 高风险审批协议向用户确认后，在原命令末尾追加 `--yes` 重试。
 - 用户要**识别飞书 / doubao 云空间 URL 的类型和 token**时，可以先按 URL 路径形态做轻量判断；当路径已明确指向 docx / sheet / bitable / slides / file / folder 等资源时，可直接提取对应 token/type。传入 wiki URL、需要识别标题或 canonical URL、URL/token 有歧义，或后续操作依赖底层真实资源时，再使用 `lark-cli drive +inspect --url '<url>'` 进行识别；具体用法、失败处理和边界见 [`references/lark-drive-inspect.md`](references/lark-drive-inspect.md)。
 - 高风险写操作（删除、公开权限修改、owner 转移、版本删除/回滚、批量移动/覆盖/同步）必须同时满足三个条件才执行：目标已解析为该操作可直接使用的执行对象，执行细节已明确到可直接调用命令（例如删除的 file-token/type、公开权限修改的共享范围、owner 转移的目标 owner、版本删除/回滚的 version id、移动/覆盖/同步的目标位置和冲突策略），且用户在本轮明确确认执行这些具体目标和执行细节。用户只说“删除没用的文件”“开放/共享给大家”“改成开放”“覆盖/移动这些”只表示目标状态；先只读发现并列出候选、权限档位或执行方案，停止等待用户确认。
 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要“权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`knowledge_organize`](references/lark-drive-workflow-knowledge-organize.md) workflow。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
+- 用户要**查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置**，优先使用 `lark-cli drive +permission-get-setting`；它只读取目标自身设置，不递归审计文件夹子文档权限。裸 token 必须显式传 `--type`。
 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--created-by-me`，原始创建者语义）、"我负责/owner 的"（→ `--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
 - 用户要**获取文档评论列表**时，优先使用 `lark-cli drive +list-comments --url '<url>'`，不要优先手写 `drive file.comments list`；支持妙搭 apps 的 `/page/<token>` URL；具体使用方式先阅读 [`references/lark-drive-list-comments.md`](references/lark-drive-list-comments.md)。
 - 妙搭 apps 评论场景：除新增全文/局部评论不支持外，评论列表、批量查询、解决/恢复、回复创建/读取/更新/删除、reaction 添加/删除等评论管理能力已支持；使用原生命令时文档类型传 `apps`（`file_type=apps`），裸 token 调 shortcut 时传 `--type apps`。
@@ -116,6 +116,7 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 ### 权限能力入口
 
 - 用户要管理 Drive 文档/文件协作者、公开权限、授权当前应用访问文档，或处理 `permission.public.patch` 的 `91009` / `91010` / `91011` / `91012` 错误时，先读 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。
+- 用户要查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置，使用 [`+permission-get-setting`](references/lark-drive-permission-get-setting.md)；如果要递归审计文件夹下子文档权限，再进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
 - 用户只是没有访问权限并希望向 owner 申请访问，优先使用 [`+apply-permission`](references/lark-drive-apply-permission.md)。
 - 普通 scope、身份或登录问题仍按 [`lark-shared`](../lark-shared/SKILL.md) 处理；不要把租户安全策略、对外分享、密级拦截简单归类为缺 scope。
 
@@ -159,6 +160,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+inspect`](references/lark-drive-inspect.md) | 检视 URL 的类型、标题和 canonical token；wiki URL 会自动解包到底层文档。 |
 | [`+apply-permission`](references/lark-drive-apply-permission.md) | 以 user 身份向文档 owner 申请访问权限。 |
 | [`+member-add`](references/lark-drive-member-add.md) | 添加一个或最多 10 个 Drive 文档、文件、文件夹或 wiki 节点协作者/授权成员；封装 Drive permission member create/batch_create，真实写入需要 `--yes`。 |
+| [`+permission-get-setting`](references/lark-drive-permission-get-setting.md) | 查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置；支持 URL 或裸 token + `--type`；不递归读取文件夹子文档权限。 |
 | [`+secure-label-list`](references/lark-drive-secure-label.md) | 列出当前用户可用的密级标签。 |
 | [`+secure-label-update`](references/lark-drive-secure-label.md) | 更新 Drive 文件或文档的密级标签。 |
 

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

@@ -5,16 +5,15 @@
 
 将文件或文件夹移动到用户云空间（云盘/云存储）的其他位置。
 
-## 与 Wiki 移动 shortcut 的区别
+## 与 `wiki +move` 的区别
 
 - `drive +move` 只处理 **Drive 文件夹树内部** 的位置调整，目标位置用 `--folder-token` 表示
 - `wiki +move` 处理的是 **Wiki 知识空间 / 页面层级**：要么移动已有 Wiki 节点，要么把 Drive 文档迁入 Wiki
-- `wiki +move-to-drive` 把 **已有 Wiki 节点移出知识库**，放到 Drive 文件夹或“我的空间”根目录
-- 如果用户说“移动到某个文件夹”“移动到我的空间根目录”，还要判断源对象：源对象已在 Drive 时使用 `drive +move`；源对象是 Wiki 节点时使用 `wiki +move-to-drive`
+- 如果用户说“移动到某个文件夹”“移动到我的空间根目录”，应使用 `drive +move`
 - 如果用户说“移动到某个知识库 / 页面下”“迁入 Wiki / 知识空间”，应使用 `wiki +move`
 - 如果用户说“移动到我的文档库 / 我的知识库 / 个人知识库 / my_library”，不要使用 `drive +move`；先按 Wiki 目标处理
 - `我的文档库` 不是 Drive root folder，也不是 `--folder-token` 省略后的默认目的地
-- `drive +move` 不支持 Wiki 文档；Wiki 节点到 Drive 应使用 `wiki +move-to-drive`，目标是 Wiki 时使用 `wiki +move`
+- `drive +move` 不支持 wiki 文档；如果目标是 Wiki，不要尝试用 `drive +move` 代替
 
 ## 不要误用到 `我的文档库`
 
@@ -118,5 +117,4 @@ lark-cli drive +task_result \
 ## 参考
 
 - [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
-- [wiki +move-to-drive](../../lark-wiki/references/lark-wiki-move-to-drive.md) -- 将 Wiki 节点移出知识库并放入 Drive
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-permission-get-setting.md

@@ -0,0 +1,78 @@
+# drive +permission-get-setting（查询权限设置）
+
+本 skill 对应 shortcut：`lark-cli drive +permission-get-setting`。它读取文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置。
+
+## 适用场景
+
+- 用户明确要查看“权限设置”“分享设置”“公开访问 / 协作者管理 / 安全 / 评论权限”。
+- 输入是 Lark / Drive URL，或已经拿到裸 token 并能明确资源类型。
+- 只需要读取当前目标自身设置，不需要递归扫描子文件、子文件夹或文档权限。
+
+如果用户要做文件夹下所有文档的权限风险报告、批量整改、owner 转移或密级标签治理，进入 [`lark-drive-workflow-permission-governance.md`](lark-drive-workflow-permission-governance.md)。
+
+## 命令
+
+```bash
+# 通过 URL 查询，type 会从 URL 自动推断
+lark-cli drive +permission-get-setting \
+  --token "https://example.feishu.cn/drive/folder/fldcnxxxxxxxxx" \
+  --as user --format json
+
+# 通过裸 folder token 查询
+lark-cli drive +permission-get-setting \
+  --token "fldcnxxxxxxxxx" --type folder \
+  --as bot --format json
+
+# 通过 docx URL 查询
+lark-cli drive +permission-get-setting \
+  --token "https://example.feishu.cn/docx/doxcnxxxxxxxxx" \
+  --as user --format json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token` | 是 | 目标 URL 或裸 token。URL 会自动推断 token 和 type；裸 token 必须同时传 `--type`。 |
+| `--type` | 裸 token 必填 | 目标类型。可选值：`doc`、`sheet`、`file`、`wiki`、`bitable`、`docx`、`mindnote`、`minutes`、`slides`、`folder`。 |
+
+URL 与显式 `--type` 不一致时会被拒绝。身份与输出格式沿用全局参数约定：按需使用 `--as user|bot`；自动化解析时使用 `--format json`。权限取决于当前身份是否能访问目标，以及应用 / 用户授权是否满足 API 要求。
+
+## 输出
+
+成功时 `data` 只返回 `permission_public`，并完整透传服务端当前返回的权限设置：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "permission_public": {
+      "comment_entity": "anyone_can_edit",
+      "external_access_entity": "open",
+      "link_share_entity": "anyone_readable",
+      "lock_switch": false,
+      "manage_collaborator_entity": "collaborator_can_edit",
+      "security_entity": "only_full_access",
+      "share_entity": "same_tenant"
+    }
+  }
+}
+```
+
+`permission_public` 是服务端当前返回的完整权限设置对象。
+
+## 边界
+
+- 只读操作，不修改权限，不需要 `--yes`。
+- 只查询目标自身设置；对文件夹不会递归读取子文件夹或子文档权限。
+
+## 常见错误
+
+| 症状 | 原因 | 处理 |
+|------|------|------|
+| `--token is required` | 没传目标 | 传目标 URL 或裸 token。 |
+| `--type is required when --token is a bare token` | 裸 token 无法自动推断类型 | 补充 `--type docx|folder|file|...`。 |
+| `unsupported --token URL` | URL 不是当前 parser 支持的文档、文件、wiki 或 folder 路径 | 确认 URL 类型；裸 token 场景直接传 `--token` 和 `--type`。 |
+| `--type ... conflicts with URL path type ...` | URL 已能推断类型，但显式 `--type` 不一致 | 删除 `--type`，或改成与 URL 匹配的类型。 |
+| Permission denied / missing scope | 当前身份无目标访问权或缺 `docs:permission.setting:read` 授权 | 按 [`lark-shared`](../../lark-shared/SKILL.md) 处理。bot 不能访问用户私有目标时，改用 `--as user` 或先授权 bot。 |

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

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-查询异步任务结果。该 shortcut 聚合了导入、导出、移动/删除文件夹、Wiki 节点 / 文档迁入 Wiki、Wiki 节点移出 Wiki 等多种异步任务的结果查询，统一接口方便调用。
+查询异步任务结果。该 shortcut 聚合了导入、导出、移动/删除文件夹、Wiki 节点 / 文档迁入 Wiki 等多种异步任务的结果查询，统一接口方便调用。
 
 > [!IMPORTANT]
 > 对于 `import` 场景，如果使用 `--as bot` 且这次查询**已经拿到最终在线文档目标**（`ready=true` 且返回了最终 `token` / `url`），CLI 会**再次尝试为当前 CLI 用户自动授予该资源的 `full_access`（可管理权限）**。
@@ -41,11 +41,6 @@ lark-cli drive +task_result \
   --scenario wiki_move \
   --task-id <TASK_ID>
 
-# 查询 Wiki 节点移出知识库任务结果（wiki +move-to-drive 异步超时后的续跑）
-lark-cli drive +task_result \
-  --scenario wiki_move_to_drive \
-  --task-id <TASK_ID>
-
 # 查询 Wiki 删除知识空间任务结果（wiki +delete-space 异步超时后的续跑）
 lark-cli drive +task_result \
   --scenario wiki_delete_space \
@@ -56,9 +51,9 @@ lark-cli drive +task_result \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--scenario` | 是 | 任务场景，可选值：`import`、`export`、`task_check`、`wiki_move`、`wiki_move_to_drive`、`wiki_delete_space`、`wiki_delete_node` |
+| `--scenario` | 是 | 任务场景，可选值：`import` (导入任务)、`export` (导出任务)、`task_check` (移动/删除文件夹任务)、`wiki_move` (Wiki 移动任务)、`wiki_delete_space` (Wiki 删除知识空间任务) |
 | `--ticket` | 条件必填 | 异步任务 ticket，**import/export 场景必填** |
-| `--task-id` | 条件必填 | 异步任务 ID，**task_check 及所有 wiki 场景必填**；必须原样传递完整 ID |
+| `--task-id` | 条件必填 | 异步任务 ID，**task_check / wiki_move / wiki_delete_space 场景必填** |
 | `--file-token` | 条件必填 | 导出任务对应的源文档 token，**export 场景必填** |
 
 ## 场景说明
@@ -69,9 +64,7 @@ lark-cli drive +task_result \
 | `export` | 文档导出任务（如云文档导出为 PDF/Word） | `--ticket`、`--file-token` |
 | `task_check` | 文件夹移动/删除任务 | `--task-id` |
 | `wiki_move` | Wiki 移动任务（`wiki +move` 的 docs-to-wiki 异步流程，超时后续跑用） | `--task-id` |
-| `wiki_move_to_drive` | Wiki 节点移出知识库任务（`wiki +move-to-drive` 超时后续跑用） | `--task-id` |
 | `wiki_delete_space` | Wiki 删除知识空间任务（`wiki +delete-space` 的异步流程，超时后续跑用） | `--task-id` |
-| `wiki_delete_node` | Wiki 删除节点任务（`wiki +node-delete` 的异步流程，超时后续跑用） | `--task-id` |
 
 ## 返回结果
 
@@ -203,29 +196,6 @@ lark-cli drive +task_result \
 - `space_id`、`obj_token`、`obj_type`、`title` 等：从首个 `move_results[0].node` 平铺到顶层，方便直接引用
 - `move_results`: 保留完整列表（适用于一次任务移动多个文档的场景）
 
-### Wiki_move_to_drive 场景返回
-
-```json
-{
-  "scenario": "wiki_move_to_drive",
-  "task_id": "<OPAQUE_TASK_ID>",
-  "ready": true,
-  "failed": false,
-  "status": 0,
-  "status_msg": "success",
-  "obj_token": "doxcnXXX",
-  "obj_type": "docx",
-  "url": "https://example.feishu.cn/docx/doxcnXXX"
-}
-```
-
-**字段说明：**
-- `ready`: `move_wiki_to_docs_result.status=0` 时为 `true`
-- `failed`: `status<0` 时为 `true`；`status=1` 表示仍在处理
-- `status` / `status_msg`: 协议返回的数值状态与可读消息；不要把字符串状态当作成功值解析
-- `obj_token` / `obj_type` / `url`: 成功后新 Drive 文档的资源信息
-- `task_id`: 签名后的 opaque ID，可能包含多个连字符；服务端响应省略 `task.task_id` 时回退为请求中的完整 ID
-
 ### Wiki_delete_space 场景返回
 
 ```json
@@ -286,26 +256,6 @@ lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID> --as user
 
 > **身份保持一致**：续跑命令的 `--as` 必须与原 `wiki +move` 调用一致；`wiki +move` 的 `next_command` 已自动带上正确的 `--as`。
 
-### 配合 wiki +move-to-drive 使用
-
-```bash
-# 1. 把 Wiki 节点移到 Drive 文件夹；省略 --folder-token 表示当前身份的“我的空间”根目录
-lark-cli wiki +move-to-drive \
-  --node-token <WIKI_NODE_TOKEN> \
-  --folder-token <TARGET_FOLDER_TOKEN> \
-  --as user
-# 若轮询窗口内完成：直接返回 ready=true、obj_token、obj_type 和 url
-# 若轮询窗口结束仍未完成：返回 ready=false、完整 task_id、timed_out=true 和 next_command
-
-# 2. 使用完整 task_id 和相同身份续跑
-lark-cli drive +task_result \
-  --scenario wiki_move_to_drive \
-  --task-id <COMPLETE_TASK_ID> \
-  --as user
-```
-
-> **调用上下文和 ID 都要保持原样**：续跑的 `--profile` 与 `--as` 必须与初始移动一致；`task_id` 可能包含多个连字符，不要拆分或截断。`wiki +move-to-drive` 返回的 `next_command` 会保留 profile 与身份。
-
 ### 配合 wiki +delete-space 使用
 
 ```bash
@@ -341,9 +291,7 @@ lark-cli drive +export-download --file-token <EXPORTED_FILE_TOKEN>
 | export | `drive:drive.metadata:readonly` |
 | task_check | `drive:drive.metadata:readonly` |
 | wiki_move | `wiki:space:read` |
-| wiki_move_to_drive | `wiki:space:read` |
 | wiki_delete_space | `wiki:space:read` |
-| wiki_delete_node | `wiki:space:read` |
 
 > [!NOTE]
 > `import` 场景在 `--as bot` 且任务最终就绪时，还可能额外尝试一次协作者授权；如果 `permission_grant.status = failed`，请根据失败信息检查应用是否具备相应的文档协作者授权能力。
@@ -351,5 +299,4 @@ lark-cli drive +export-download --file-token <EXPORTED_FILE_TOKEN>
 ## 参考
 
 - [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
-- [wiki +move-to-drive](../../lark-wiki/references/lark-wiki-move-to-drive.md) -- 将 Wiki 节点移出知识库并放入 Drive
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-workflow-permission-governance-commands.md

@@ -15,6 +15,8 @@
 lark-cli drive +inspect --url '<url>' --as user --format json
 ```
 
+`drive +inspect` 不支持 Drive folder。`/drive/folder/<folder_token>` 直接解析为 `type=folder` + `token=<folder_token>`；需要读取文件夹自身权限设置时使用 `drive +permission-get-setting --token '<folder_token>' --type folder`。
+
 `/wiki/space/<space_id>` URL 是 Wiki space 范围，不要用 `drive +inspect` 当作单文档解析；直接提取 `space_id` 后进入 `DISCOVER_TARGETS`。
 
 ## 目标发现
@@ -25,16 +27,16 @@ lark-cli drive +inspect --url '<url>' --as user --format json
 lark-cli wiki +node-list \
   --space-id '<space_id>' --page-size 50 \
   --page-all --page-limit 0 \
-  --as user --format json
+  --as user --format json # quality-gate: requires a resolved numeric space ID ...
 
 lark-cli wiki +node-list \
   --space-id '<space_id>' --parent-node-token '<node_token>' --page-size 50 \
   --page-all --page-limit 0 \
-  --as user --format json
+  --as user --format json # quality-gate: requires a resolved numeric space ID ...
 
 lark-cli wiki +node-list \
   --space-id '<space_id>' --page-token '<PAGE_TOKEN>' --page-size 50 \
-  --as user --format json
+  --as user --format json # quality-gate: requires a resolved numeric space ID ...
 ```
 
 解析返回时使用 `data.nodes`，不要读取顶层 `items`。`--page-limit 0` 表示当前层分页不设页数上限；`--page-all` 只覆盖当前 `space-id` / `parent-node-token` 范围内的分页，不会递归子节点。节点 `has_child=true` 时，必须继续以该节点的 `node_token` 作为 `--parent-node-token` 递归读取。
@@ -61,14 +63,30 @@ lark-cli drive metas batch_query \
   --as user --format json
 ```
 
-读取 public permission：
+读取权限设置：
 
 ```bash
-lark-cli drive permission.public get \
-  --params '{"token":"<token>","type":"<type>"}' \
+lark-cli drive +permission-get-setting \
+  --token '<url-or-token>' --type '<type>' \
   --as user --format json
 ```
 
+裸 folder token 必须显式传 `--type folder`：
+
+```bash
+lark-cli drive +permission-get-setting \
+  --token '<folder_token>' --type folder \
+  --as user --format json
+```
+
+通过 URL 读取权限设置时可以省略 `--type`：
+
+```bash
+lark-cli drive +permission-get-setting \
+  --token '<url>' \
+  --as user --format json # quality-gate: requires a recognized Lark Drive URL ...
+```
+
 按需读取访问统计：
 
 ```bash
@@ -160,7 +178,7 @@ lark-cli drive +secure-label-list \
 ```bash
 lark-cli drive +secure-label-update \
   --token '<url>' \
-  --label-id '<label-id>' --as user --format json
+  --label-id '<label-id>' --as user --format json # quality-gate: requires a resolved numeric label ID ...
 
 lark-cli drive +secure-label-update \
   --token '<bare-token>' --type '<type>' \

skills/lark-drive/references/lark-drive-workflow-permission-governance-outputs.md

@@ -27,7 +27,7 @@
 - 多目标明确列表默认输出逐目标诊断摘要；不要因为目标数大于 1 就套用容器递归发现报告。
 - 用户可见结论默认跟随用户当前语言。用户用中文提问时输出中文，用户用英文提问时输出英文；混合语言时跟随主要语言。
 - 单目标公开性判断默认输出业务表达，不直接展示 `link_share_entity`、`external_access_entity`、`external_access` 等底层字段名；只有用户要求 raw evidence、排障，或完整清单 / artifact 场景才展示底层字段。
-- 中文用户可见输出中，`permission_public` / `public permission` 默认译为“文档公共访问和协作权限设置”；可在摘要里简称“公共访问与协作设置”。它在官方语义中包含链接分享、对外分享、协作者管理、复制内容、创建副本、打印、下载和评论；具体可判断字段以当前 CLI schema 和实际响应为准。只有命令名、schema 字段、raw evidence、排障信息和完整 artifact 字段名保留英文原文。
+- 中文用户可见输出中，`permission_public` / `public permission` 默认译为“目标公共访问和协作权限设置”；可在摘要里简称“公共访问与协作设置”。优先按实际返回字段解释公开访问、分享、协作者管理、安全与评论设置；复制内容、创建副本、打印、下载等字段只有在当前 CLI schema 和实际响应返回时才可判断。只有命令名、schema 字段、raw evidence、排障信息和完整 artifact 字段名保留英文原文。
 - 容器目标默认输出安全诊断报告摘要：一句话结论、覆盖情况、风险分级、优先处理对象、建议下一步和剩余限制。
 - 容器目标不要把风险按数量机械排序；外部公开、允许对外分享、缺失密级标签优先于复制 / 下载 / 评论这类依赖策略的候选项。
 - 用户没有提供明确 policy 时，使用“候选风险 / 待复核 / 待策略确认”，不要写“违规 / 已泄露 / 已外部访问”。
@@ -36,7 +36,7 @@
 - 当摘要未展示全部风险对象时，必须明确“完整清单包含 <count> 条”，并提供生成 Markdown / CSV / 飞书文档风险清单或整改 dry-run 的下一步。
 - 只要发现需要处理的对象，最终回复必须给出可执行下一步 CTA。不能因为默认只读，就只报告风险后结束。
 - 完整风险清单是后续治理选择的输入；Markdown / CSV / 飞书文档报告必须使用同一套字段和稳定 `risk_id`。
-- 写入前必须使用确认模板；权限申请、文档公共访问和协作权限设置修改、owner 转移、密级标签更新分别确认。
+- 写入前必须使用确认模板；权限申请、目标公共访问和协作权限设置修改、owner 转移、密级标签更新分别确认。
 - 最终回复必须包含已完成事项、验证结果和剩余限制；异步权限申请审批不能表述为已完成授权。
 
 ## Semantic Rendering
@@ -75,7 +75,7 @@
 | `lock_switch=true` | `lock_state=locked_not_inheriting` | 已限制权限，不再继承父级页面权限 | The node is locked and no longer inherits parent-page permissions |
 | `lock_switch=false` | `lock_state=not_locked_or_inheriting` | 未限制权限，可能继承父级页面权限 | The node is not locked and may inherit parent-page permissions |
 | field absent / unsupported | `<state>=unknown` | 当前 schema 未返回，无法判断 | The current schema did not return this field, so it is unknown |
-| `check_scope=current_public_permission_only` | `check_scope=current_public_permission_only` | 本次判断的是当前文档公共访问和协作权限设置，不是协作者名单或历史权限变更审计 | This check covers current public access and collaboration settings, not collaborator-list or historical permission-change auditing |
+| `check_scope=current_public_permission_only` | `check_scope=current_public_permission_only` | 本次判断的是当前目标公共访问和协作权限设置，不是协作者名单或历史权限变更审计 | This check covers the target's current public access and collaboration settings, not collaborator-list or historical permission-change auditing |
 | `sec_label_name` missing | `sec_label=missing` | 缺少密级标签 | Security label is missing |
 
 ## 定位与治理动作
@@ -165,7 +165,7 @@ Evidence fields:
 
 覆盖情况：
 - 用户提供目标：<input_target_count>；成功解析：<resolved_count>
-- 成功读取文档公共访问和协作权限设置：<permission_checked_count>；读取失败 / 不支持 / 无权限：<failed_or_unsupported_count>
+- 成功读取目标公共访问和协作权限设置：<permission_checked_count>；读取失败 / 不支持 / 无权限：<failed_or_unsupported_count>
 
 逐目标结果（1-10 个目标默认全部展示；超过 10 个时按 `摘要清单展开规则` 展示，并提示生成完整风险清单）：
 
@@ -233,7 +233,7 @@ URL：<url-or-token-if-url-unavailable>
 
 覆盖情况：
 - 当前身份可见目标：<visible_count>
-- 已成功检查文档公共访问和协作权限设置：<permission_checked_count>
+- 已成功检查目标公共访问和协作权限设置：<permission_checked_count>
 - 读取失败 / 已删除 / 无权限：<failed_count>
 - 未覆盖能力：<collaborator_list / inheritance / audit_log / view_records / none>
 
@@ -355,8 +355,8 @@ Agent 必须回复：
 - 字段变更：
   - <risk_id> <path> (<url-or-token>): <field> <old> -> <new>
 - 跳过项：<unsupported / no manage_public / unsupported type / missing policy>
-- 验证方式：执行后重新读取 <元数据 / 文档公共访问和协作权限设置>
-- 有限回滚范围：<文档公共访问和协作权限设置快照字段 / 不适用>
+- 验证方式：执行后重新读取 <元数据 / 目标公共访问和协作权限设置>
+- 有限回滚范围：<目标公共访问和协作权限设置快照字段 / 不适用>
 
 请确认是否进入写入确认。
 ```
@@ -407,8 +407,8 @@ Agent 必须回复：
 - 风险：<risk_level>
 - 字段变更：
   - <field>: <old> -> <new>
-- 验证方式：执行后重新读取 <元数据 / 文档公共访问和协作权限设置>
-- 有限回滚材料：<文档公共访问和协作权限设置快照 / 不适用>
+- 验证方式：执行后重新读取 <元数据 / 目标公共访问和协作权限设置>
+- 有限回滚材料：<目标公共访问和协作权限设置快照 / 不适用>
 
 请确认是否执行。
 ```
@@ -419,6 +419,6 @@ Agent 必须回复：
 已完成：<read checks / writes>
 验证：<fresh read result or async permission-request approval note>
 清单状态：<risk_id status updates / not applicable>
-回滚材料：<文档公共访问和协作权限设置快照 / 不适用>
+回滚材料：<目标公共访问和协作权限设置快照 / 不适用>
 剩余限制：<unsupported_checks / partial facts / approvals>
 ```

skills/lark-drive/references/lark-drive-workflow-permission-governance.md

@@ -38,7 +38,7 @@ Risk / Structure: `R2` / `S2`
 - 目录组织、迁移、归档或清理；这类需求应使用知识整理 workflow。
 - 内容审查、过期内容判断或知识质量评分。
 - backup owner 补充、部门 / 项目负责人绑定、协作者创建 / 撤销、成员列表审计；本 workflow 只支持把 owner 转移给每个目标明确指定的新 owner，不建模 backup owner 或负责人绑定关系。
-- 文件夹自身公开权限审计或修复。`drive permission.public get` / `patch` 不支持 `type=folder`；必须记录到 `unsupported_checks`，然后继续读取文件夹下其他支持的文档事实。
+- 文件夹自身公开权限审计或修复。文件夹自身权限设置可以用 `drive +permission-get-setting` 读取；写入是否支持必须以运行时 schema 和明确需求为准，不能猜测执行 `patch type=folder`。
 - 当前身份无法枚举到的不可见文档的完整发现；只能处理已发现目标，或用户显式提供的 URL / token。
 - 未按范围确认的批量写入。
 
@@ -53,7 +53,7 @@ Risk / Structure: `R2` / `S2`
 | `PARSE_INTENT` | 本文件、[`lark-drive-workflow.md`](lark-drive-workflow.md)、[`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) |
 | `TARGET_INSPECT` | [`lark-drive-inspect.md`](lark-drive-inspect.md) |
 | `DISCOVER_TARGETS` | 容器范围时读取 [`../../lark-wiki/references/lark-wiki-node-list.md`](../../lark-wiki/references/lark-wiki-node-list.md) 或 [`lark-drive-files-list.md`](lark-drive-files-list.md) |
-| `FACT_READ` | `lark-cli schema drive.metas.batch_query`；涉及公开权限时再读取 `lark-cli schema drive.permission.public.get`；涉及活跃度、访问复核或生命周期判断时再读取 `lark-cli schema drive.file.statistics.get` 和 `lark-cli schema drive.file.view_records.list` |
+| `FACT_READ` | `lark-cli schema drive.metas.batch_query`；涉及权限设置读取时使用 `drive +permission-get-setting`；涉及活跃度、访问复核或生命周期判断时再读取 `lark-cli schema drive.file.statistics.get` 和 `lark-cli schema drive.file.view_records.list` |
 | `RISK_ASSESS` | 本文件的 `Risk Classification` |
 | `EXEC_CONFIRM` | 只为用户选择的动作读取 [`lark-drive-apply-permission.md`](lark-drive-apply-permission.md)、[`lark-drive-secure-label.md`](lark-drive-secure-label.md)，或 `lark-cli schema drive.permission.public.patch` / `lark-cli schema drive.permission.members.transfer_owner`；需要确认模板时读取 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) |
 | `EXECUTE` | 复用 `EXEC_CONFIRM` 已加载且已确认的写命令上下文 |
@@ -76,9 +76,9 @@ Risk / Structure: `R2` / `S2`
 | State | Protocol Step | Agent MUST Do | User-Facing Output | wait_for_user | Next State |
 |-------|---------------|---------------|--------------------|---------------|------------|
 | `PARSE_INTENT` | `route` / `scope` | 解析 intent、target scope、desired policy，以及只读审计、单目标公开性判断、权限申请、owner 转移还是修复模式；单目标公开性判断设置 `intent=public_exposure_check`、`target_scope=single_resource` | 范围确认；如果缺少目标、新 owner 或期望动作，只问一个澄清问题 | 缺少 target / new owner / action，或容器范围需要用户确认时为 `true` | `TARGET_INSPECT` |
-| `TARGET_INSPECT` | `scope` | 解析单资源、明确列表、Wiki space / node、Drive folder；保留原始 URL、scope type、canonical token/type | 目标范围表，包含 scope、title/type/token status | 除非解析失败，否则为 `false` | `DISCOVER_TARGETS` or `FACT_READ` |
+| `TARGET_INSPECT` | `scope` | 解析单资源、明确列表、Wiki space / node、Drive folder；Drive folder 直接从 URL 路径或显式 `type=folder` 解析，不调用 `drive +inspect`；保留原始 URL、scope type、canonical token/type | 目标范围表，包含 scope、title/type/token status | 除非解析失败，否则为 `false` | `DISCOVER_TARGETS` or `FACT_READ` |
 | `DISCOVER_TARGETS` | `scope` / `read` | 对 Wiki space / node 或 Drive folder 递归只读枚举，归一化为 `discovered_targets`；记录 `discovery_blockers` | 发现进度和覆盖摘要；不展示内部 cursor/token，除非用户要求 | 除非发现范围无法确认或全部被阻断，否则为 `false` | `FACT_READ` |
-| `FACT_READ` | `read` | 对直接目标或 `discovered_targets` 执行 `drive metas batch_query`；对支持的非 folder 目标执行 `drive permission.public get`；当 `intent=public_exposure_check` 且 `target_scope=single_resource` 时，可复用 `drive +inspect` 返回的 title / URL / type，只补读文档公共访问和协作权限设置；在用户要求活跃度 / 访问复核 / 生命周期判断时读取访问统计和访问记录 | 权限事实摘要、coverage summary、activity facts 和 unsupported checks | 除非所有目标都被 auth 阻断，否则为 `false` | `RISK_ASSESS` |
+| `FACT_READ` | `read` | 对直接目标或 `discovered_targets` 执行 `drive metas batch_query`；对支持的文件、文件夹或云文档目标执行 `drive +permission-get-setting` 读取自身权限设置；当 `intent=public_exposure_check` 且 `target_scope=single_resource` 时，可复用 `drive +inspect` 返回的 title / URL / type，只补读目标公共访问和协作权限设置；在用户要求活跃度 / 访问复核 / 生命周期判断时读取访问统计和访问记录 | 权限事实摘要、coverage summary、activity facts 和 unsupported checks | 除非所有目标都被 auth 阻断，否则为 `false` | `RISK_ASSESS` |
 | `RISK_ASSESS` | `assess/plan` | 对每个可审计目标生成 `per_target_permission_assessment` 并分类证据；如用户提供 policy，则对照 policy；`public_exposure_check + single_resource` 只渲染单目标结论，不生成 `risk_id`；owner 转移路径生成 `owner_transfer_candidates` / `owner_transfer_plan`；治理路径构建可定位风险清单、访问复核清单、dry-run 整改计划或候选修复计划，完整清单必须生成稳定 `risk_id` | 带 priority、URL、risk_id、owner、sec_label 的 findings、confidence、review items、建议动作和下一步 CTA；单目标公开性判断只输出结论和关键字段 | 治理路径为 `true`，单目标公开性判断为 `false` | `EXEC_CONFIRM` or `DONE` |
 | `EXEC_CONFIRM` | `confirm` | 展示准确写入范围、command family、target count、risk、verification method | 确认请求 | `true` | `EXECUTE` or `DONE` |
 | `EXECUTE` | `execute` | 只执行 `Command Map` 中已确认的写入 | 进度 / 结果摘要 | 除非被阻断，否则为 `false` | `VERIFY` |
@@ -91,21 +91,21 @@ Risk / Structure: `R2` / `S2`
 
 | State | Allowed Command Families | Purpose |
 |-------|--------------------------|---------|
-| `TARGET_INSPECT` | `drive +inspect` | 解析 URL、type、canonical token、title 和 wiki unwrap data |
+| `TARGET_INSPECT` | `drive +inspect` | 解析非 folder URL、type、canonical token、title 和 wiki unwrap data；Drive folder 不支持 `+inspect`，必须从 URL 路径或显式 `type=folder` 直接解析 |
 | `DISCOVER_TARGETS` | `wiki +node-list` | 递归发现 Wiki space / node 下当前身份可见的节点 |
 | `DISCOVER_TARGETS` | `drive files list` | 递归发现 Drive folder 下当前身份可见的文件和子文件夹 |
 | `FACT_READ` | `drive metas batch_query` | 读取 title、URL、owner 和 secure-label metadata |
-| `FACT_READ` | `drive permission.public get` | 读取支持类型的文档公共访问和协作权限设置，包括链接分享、对外分享、协作者管理、复制内容、创建副本、打印、下载和评论 |
+| `FACT_READ` | `drive +permission-get-setting` | 读取支持类型的文件、文件夹或云文档自身权限设置，包括公开访问、分享、协作者管理、安全与评论 |
 | `FACT_READ` | `drive file.statistics get` | 在用户要求活跃度、闲置暴露、生命周期或访问复核时读取文件访问统计 |
 | `FACT_READ` | `drive file.view_records list` | 在用户要求最近访问人、访问复核或低活跃证据时读取访问记录 |
 | `EXEC_CONFIRM` | `drive +secure-label-list` | 提议 label update 前解析可用 secure-label IDs |
-| `EXEC_CONFIRM` | `drive permission.members auth` | 文档公共访问和协作权限设置修改前检查 `action=manage_public` |
+| `EXEC_CONFIRM` | `drive permission.members auth` | 目标公共访问和协作权限设置修改前检查 `action=manage_public` |
 | `EXEC_CONFIRM` | `lark-cli schema drive.permission.members.transfer_owner` | owner 转移前读取当前字段、支持类型和高风险写入门禁 |
 | `EXECUTE` | `drive +apply-permission` | 向 owner 提交 view/edit access request；只允许单目标、小列表或已明确确认的候选列表逐个执行 |
 | `EXECUTE` | `drive permission.public patch` | 修改已确认的 public/link settings；必须传 `--yes` |
 | `EXECUTE` | `drive permission.members transfer_owner` | 转移已确认目标的 owner；必须传 `--yes` |
 | `EXECUTE` | `drive +secure-label-update` | 设置已确认的 secure-label ID |
-| `VERIFY` | `drive metas batch_query`, `drive permission.public get` | 验证支持的 metadata，包括 owner、secure-label 和文档公共访问与协作权限设置变更；权限申请只能表述为已发起 |
+| `VERIFY` | `drive metas batch_query`, `drive +permission-get-setting` | 验证支持的 metadata，包括 owner、secure-label 和目标公共访问与协作权限设置变更；权限申请只能表述为已发起 |
 
 ## Command Patterns
 
@@ -119,9 +119,9 @@ Risk / Structure: `R2` / `S2`
 
 1. "所有文档"只表示当前身份在确认范围内可枚举到的文档。不可见、无权限、API 不返回或工具预算不足的部分必须进入 `discovery_blockers` 或 `unsupported_checks`。
 2. 发现阶段必须生成稳定 `path`。不要只保存 title；同名文档必须能通过 path 或 token 区分。
-3. 只把 `drive.permission.public.get` 当前 schema 支持的类型加入公开权限可审计目标。已知支持包括 `doc`、`sheet`、`file`、`wiki`、`bitable`、`docx`、`mindnote`、`minutes`、`slides`；未来新增类型以运行时 schema 为准。
+3. 权限设置读取使用 `drive +permission-get-setting`，目标类型包括 `doc`、`sheet`、`file`、`wiki`、`bitable`、`docx`、`mindnote`、`minutes`、`slides`、`folder`；未来新增类型以 shortcut 和 OpenAPI 元数据为准。
 4. `minutes` 只能作为 `partial_public_permission` 目标：可读取 / 修改公开权限和 owner 转移能力以运行时 schema 为准，但 `drive metas batch_query` 当前不支持 `minutes`，URL、owner、密级等 metadata 可能进入 `unsupported_checks`。
-5. `folder` 只作为递归容器，不执行 `permission.public get` / `patch`。如果用户明确要求 owner 转移且 schema 支持 `folder`，必须按 owner-transfer 写入规则单独确认。`shortcut`、`catalog` 或缺少 stable token/type 的条目必须记录为 unsupported，除非后续 API 明确解析出支持目标。
+5. `folder` 作为递归容器时先枚举子资源；如用户明确要查询文件夹自身权限设置，可对该文件夹单独执行 `drive +permission-get-setting --token <folder_token> --type folder`。不要执行 raw `permission.public patch type=folder`，除非 schema 和需求都明确支持。`shortcut`、`catalog` 或缺少 stable token/type 的条目必须记录为 unsupported，除非后续 API 明确解析出支持目标。
 6. 对大范围目标输出进度时，只展示已扫描容器数、已发现目标数、已审计目标数、剩余队列或 blocker；不要默认展示内部 page token / cursor。
 
 Wiki space / node 发现：
@@ -133,7 +133,7 @@ Wiki space / node 发现：
 
 Drive folder 发现：
 
-1. `/drive/folder/<folder_token>` 解析为 `target_scope=drive_folder`。文件夹自身公开权限不支持；继续枚举其子文档。
+1. `/drive/folder/<folder_token>` 解析为 `target_scope=drive_folder`。默认继续枚举其子文档；只有用户明确要求文件夹自身权限设置时，才额外调用 `drive +permission-get-setting --token <folder_token> --type folder` 读取该文件夹自身设置。
 2. 按 [`lark-drive-files-list.md`](lark-drive-files-list.md) 递归处理 `data.files`、`has_more` 和 `next_page_token`。不要把第一页数量当作完整范围。
 3. 只对返回项中的 `folder` 继续递归；对子文档按 `type + token` 归一化为 `discovered_targets`。
 4. 如果某个目录分页失败、无 continuation token、权限不足或 API 报错，只阻断该目录分支，并在 `discovery_blockers` 中记录；继续处理其他可枚举分支。
@@ -141,11 +141,11 @@ Drive folder 发现：
 ## Fact Read Rules
 
 1. `drive metas batch_query` 单次最多 200 个 `request_docs`；当 `targets` 或 `discovered_targets` 超过 200 个时，必须分批读取并合并结果。
-2. `drive permission.public get` 没有批量读取接口；对支持目标逐个读取。单个目标失败时记录 `unsupported_checks` 或 `partial`，不要阻断其他目标。
+2. `drive +permission-get-setting` 没有批量读取接口；对支持目标逐个读取。单个目标失败时记录 `unsupported_checks` 或 `partial`，不要阻断其他目标。
 3. 对 Wiki 发现目标，公开权限读取优先使用 `type=wiki` + `node_token`；metadata 可使用 `obj_type` + `obj_token` 补充 title、owner、URL 和 `sec_label_name`。
 4. 当 intent 是 `list_permission_settings` 时，只输出权限设置清单和覆盖限制，不主动生成修复计划。
 5. 单目标、多目标明确列表和容器发现目标都必须复用同一套逐目标事实读取与语义归一逻辑；差异只体现在目标来源、coverage summary 和输出聚合。
-6. `permission_public` 用户可见含义是“文档公共访问和协作权限设置”，语义以官方 OpenAPI 字段说明为准，同时兼容当前 CLI schema 返回的字段：优先使用 `external_access_entity`，缺失时才用 `external_access` boolean 映射为 `open` / `closed`；`manage_collaborator_entity`、`copy_entity`、`lock_switch` 等字段缺失时标记为 unknown，不要伪造；未识别字段保留在 raw evidence / partial note 中。
+6. `permission_public` 用户可见含义是“目标公共访问和协作权限设置”，语义以官方 OpenAPI 字段说明为准，同时兼容当前 CLI schema 返回的字段：优先使用 `external_access_entity`，缺失时才用 `external_access` boolean 映射为 `open` / `closed`；`manage_collaborator_entity`、`copy_entity`、`lock_switch` 等字段缺失时标记为 unknown，不要伪造；未识别字段保留在 raw evidence / partial note 中。
 7. `drive file.statistics get` 和 `drive file.view_records list` 只在用户要求最近访问、活跃度、闲置暴露、访问复核，或用户提供的 policy 明确依赖活跃度时执行；不要为普通权限审计默认读取访问记录。
 8. 访问统计 / 访问记录当前只对 `doc`、`docx`、`sheet`、`bitable`、`mindnote`、`wiki`、`file` 作为支持类型处理。其他类型必须进入 `unsupported_checks`，不能推断活跃度。
 9. `view_records` 是访问证据，不是权限列表。没有返回访问记录只能表述为“未获得最近访问证据”或“低活跃候选”，不能表述为“无人有权限”。
@@ -162,17 +162,17 @@ Drive folder 发现：
 - `PolicyReview`：复制、创建副本、打印、下载、评论等依赖 policy 的设置；没有明确 policy 时不要称为高风险。
 - `Unknown`：读取失败、已删除、无权限、API 不支持、协作者名单 / 继承链 / DLP / AI 索引 / 审计日志未覆盖。
 
-每个可审计目标都必须先归一化为 `per_target_permission_assessment`，再按 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) 的 `Semantic Rendering` 渲染。`public_exposure_check` 只是 `target_count=1` 的轻量渲染模式；它和多目标、容器诊断复用同一套语义字段与风险分类。该判断只覆盖当前文档公共访问和协作权限设置，不审计协作者名单、历史权限变更、完整继承链或审计日志。
+每个可审计目标都必须先归一化为 `per_target_permission_assessment`，再按 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) 的 `Semantic Rendering` 渲染。`public_exposure_check` 只是 `target_count=1` 的轻量渲染模式；它和多目标、容器诊断复用同一套语义字段与风险分类。该判断只覆盖当前目标公共访问和协作权限设置，不审计协作者名单、历史权限变更、完整继承链或审计日志。
 
 `AI 检索暴露候选风险` 只是基于权限和标签的代理标签。除非另有工具明确返回索引状态，否则不要声称某个文档已经被 Agent、Copilot 或 RAG 索引。
 
 ## 写入规则
 
-- 文档公共访问和协作权限设置修改（`drive permission.public patch`）属于高风险写入。请求确认前，必须展示 target title、token、current setting、desired setting 和准确 field changes。
+- 目标公共访问和协作权限设置修改（`drive permission.public patch`）属于高风险写入。请求确认前，必须展示 target title、token、current setting、desired setting 和准确 field changes。
 - 如果 `manage_public_auth.auth_result=false`，禁止 patch。告诉用户需要具备 manage-public 权限的用户，或由 owner 操作。
-- `drive permission.public get` 只用于 `drive +inspect` 或 `DISCOVER_TARGETS` 可解析且运行时 schema 支持的目标类型；类型集合不要硬编码，执行时以 `lark-cli schema drive.permission.public.get` 为准。
+- 权限设置读取使用 `drive +permission-get-setting`；裸 token 必须传 `--type`，URL 可以自动推断。写入仍使用 `drive permission.public patch`，只 patch 已解析且 schema 明确支持的类型和字段，不要把读取支持的 `folder` 自动外推为可写入。
 - 不要 patch 已解析类型不支持的字段。对于 wiki 目标，必须省略 schema 明确标注为 wiki 不支持的字段。
-- 不要在同一个写入确认中合并密级标签更新和文档公共访问与协作权限设置修改；必须分别确认。
+- 不要在同一个写入确认中合并密级标签更新和目标公共访问与协作权限设置修改；必须分别确认。
 - `drive +apply-permission` 默认不批量执行；每次调用都会向 owner 发送通知。
 - `permission_request_candidates` 可以来自用户直接提供的目标、明确列表或容器发现目标；只要能构造 token、type、权限类型和申请理由，就可以进入候选。不要因为目标不在 `discovered_targets` 中而拒绝单目标 / 小列表权限申请。
 - 容器范围内的"统一申请权限"必须先产出 `permission_request_candidates`。未展示候选目标、数量、权限类型和 owner 通知影响前，禁止调用 `drive +apply-permission`。
@@ -182,8 +182,8 @@ Drive folder 发现：
 - 批量 owner 转移必须逐个顺序执行；失败项进入结果清单，不要重复执行已成功目标。`remove_old_owner=true` 或 `old_owner_perm` 降权必须单独在确认中高亮。
 - 用户要求“生成整改方案 / dry-run / 先看看会改什么”时，只生成 `remediation_plan`，不执行任何写命令。dry-run 必须包含 target count、field changes、跳过原因、验证方式和有限回滚范围。
 - 用户基于完整风险清单选择对象时，必须先解析 `risk_id`、风险分组、URL 或 artifact 中 `selected=true` 的行，生成 `selected_risk_items`。无法匹配到当前 `risk_manifest` 的选择必须要求用户重新确认或重新读取清单。
-- 针对 `selected_risk_items` 生成 dry-run 前，必须重新读取所选目标的 `drive permission.public get`；如果当前设置和清单快照不同，标记为 `changed_since_report` 并跳过或要求用户确认更新后的计划。
-- 执行 `drive permission.public patch` 前，必须把当前 `public_permission_facts` 中会被改动的字段保存为 `public_permission_snapshots`。该快照只用于文档公共访问和协作权限设置字段的有限回滚说明，不覆盖协作者、owner、继承权限或密级标签。
+- 针对 `selected_risk_items` 生成 dry-run 前，必须重新读取所选目标的 `drive +permission-get-setting`；如果当前设置和清单快照不同，标记为 `changed_since_report` 并跳过或要求用户确认更新后的计划。
+- 执行 `drive permission.public patch` 前，必须把当前 `public_permission_facts` 中会被改动的字段保存为 `public_permission_snapshots`。该快照只用于目标公共访问和协作权限设置字段的有限回滚说明，不覆盖协作者、owner、继承权限或密级标签。
 - 如果用户要求批量收紧权限，必须按风险分层和目标顺序逐个执行；失败项进入结果清单，不要因为单个失败而重复执行已成功目标。
 - 遇到 secure-label downgrade error `1063013` 时，停止重试，并告诉用户需要在文档 UI 中完成审批。
 

skills/lark-slides/SKILL.md

@@ -10,40 +10,34 @@ metadata:
 
 # slides (v1)
 
-**CRITICAL — 全局硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。**
-
-**CRITICAL — 图片至关重要：必须有意识的主动多用图片！素材图使用生图工具和搜图工具，缺图时用生图工具生成配图补足；背景图必须使用生图工具，且生图指令中必须明确要求不要出现任何文字。**
-
-**CRITICAL — 防文本溢出：所有承载突出信息和密集文字的 `<content>` 必须设置 `autoFit="normal-auto-fit"`，字号会在框内自动缩排以防溢出。**
-
 ## Quick Reference
 
 | 用户需求 | 优先动作 | 关键文档 / 命令 |
 |----------|----------|-----------------|
 | 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
-| 从模板创建或编辑已有本地 PPTX | 导入 PPTX 为 Slides | `lark-slides-pptx-template-workflows.md` |
+| 已有 PPT 大幅改写 | 多页整页重建用 `+replace-pages`，单页局部编辑用 `+replace-slide` | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
 | 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
-| 读取或分析已有 PPT | 解析 slides/wiki token，用 shortcut 回读全文 XML 或读取单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get` |
-| 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面，一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` |
+| 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
+| 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面 | `slides +screenshot`、`lark-slides-screenshot.md` |
 | 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 |
-| 绘制图表 | 原生图表用 `<chart>`，其他用 `<shape>` + `<line>`，只有复杂 Mermaid、SVG 用 `<whiteboard>` | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` |
-| 绘制表格 | 优先用 `rect` 和 `text` 模拟，其他用 `<table>` | `xml-schema-quick-ref.md` |
-| 使用图标 | 禁止盲猜 `iconType`，必须先检索 IconPark，再写 `<icon iconType="...">`，图标必须填充颜色并和背景有足够对比，禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`iconpark.md` |
+| 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表 | 使用原生 `<chart>` 元素 | `xml-schema-quick-ref.md` |
+| 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `<whiteboard>` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) |
+| 使用语义图标 | 先检索 IconPark，再写 `<icon iconType="...">` | `iconpark_tool.py search → resolve`、`iconpark.md` |
 | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
 
 **CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
 
+**CRITICAL — PPT 生成与模板编辑硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。多用生图，辅助搜图，必须要图文并茂。不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。生成背景图时必须在 prompt 中明确要求不要出现任何文字。用户指定 PPT 模板时，用 lark-drive 技能导入成 lark slides，回读理解每页版式后，直接在该 slides 上编辑，可以填改文字和图片、按需增删模板页，必须严格沿用原版式和字体，只改内容不做设计，完成后回读并微调，凝练文字或缩减字号消除文字溢出，调整 shape 顺序或位置避免文字遮挡。**
+
 **CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。**
 
 **CRITICAL — 新建演示文稿或大幅改写页面时，生成 XML 前 MUST 读取 [visual-planning.md](references/visual-planning.md)，确保 `layout_type`、`visual_focus`、`text_density` 实际改变页面几何、主视觉和文本量。**
 
-**CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)。**
+**CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。**
 
-**CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create --slides`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前，MUST 先把待提交 XML 保存到本地文件并运行 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)；`summary.error_count` 必须为 0 才能调用接口。**
-
-**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险。**
+**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险；XML 语法和文本重叠静态检查优先使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)。**
 
 **CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
 
@@ -85,13 +79,14 @@ lark-cli auth login --domain slides
 - 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md)
 - 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)
 - 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
+- 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
 - 图标：[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py)
 - 排障：[`troubleshooting.md`](references/troubleshooting.md)
 - 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml)
 
 ## Workflow
 
-> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要适当，排版要留白。
+> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。
 
 ### Design Ideas
 
@@ -129,9 +124,7 @@ lark-cli auth login --domain slides
 - 不要用低对比文字或低对比图标，例如浅灰字压在浅色背景上。
 - 不要让装饰线穿过文字，或让页脚、来源、编号挤压主体内容。
 - 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。
-- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。
-- 不要使用 emoji。
-- 不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。
+- 不要留下占位文案、示例公司名、示例日期或与用户主题无关的内容。
 
 ### 创建方式选择
 
@@ -147,11 +140,9 @@ lark-cli auth login --domain slides
 > [!IMPORTANT]
 > `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
 
-### 生成流程
-
 ```text
 Step 1: 需求澄清 & 读取知识
-  - 澄清主题、受众、页数、风格；若用户上传 PPTX 作为模板，按顶部『用户自定义模板』规则处理
+  - 澄清主题、受众、页数、风格
   - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
 
 Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json
@@ -162,11 +153,10 @@ Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json
 Step 3: 按 slide_plan.json 生成 XML → 创建
   - 逐页消费 plan：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量
   - 缺少真实素材时必须用 `fallback_if_missing` 生成 XML-native 兜底视觉；不要留空
-  - 调用创建或整页替换接口前，先保存待提交 XML 并运行 xml_text_overlap_lint.py；error_count 不为 0 必须先修
   - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
 
 Step 4: 审查 & 交付
-  - 创建完成后，必须用 `slides +xml-get` 读取全文 XML，并按 validation-checklist.md 做显式验证记录
+  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
   - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
   - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
 ```
@@ -183,7 +173,7 @@ lark-cli slides xml_presentation.slide create \
   --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
   <style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
   <data>
-    <!-- 在这里放置 shape、line、table、chart 等元素 -->
+    在这里放置 shape、line、table、chart、whiteboard 等元素
   </data>
 </slide>' '{slide:{content:$content}}')"
 
@@ -257,12 +247,11 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 | Shortcut | 说明 |
 |----------|------|
 | [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传） |
-| [`+xml-get`](references/lark-slides-xml-get.md) | 读取全文或单页 XML，并可保存到本地文件，避免终端输出被截断 |
 | [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
 | [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
 | [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面：先创建新页到旧页前，再删除旧页；适合已有 Slides 的多页大改，不新建链接 |
 
-没有 Shortcut 覆盖时使用原生 API。高频资源：`slides +xml-get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
+没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
 
 ```bash
 lark-cli schema slides.<resource>.<method>   # 调用 API 前必须先查看参数结构
@@ -273,7 +262,7 @@ lark-cli slides <resource> <method> [flags] # 调用 API
 
 ## 核心规则
 
-1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；模板、风格和大纲只能作为规划输入，不能绕过规划层
+1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；风格和大纲只能作为规划输入，不能绕过规划层
 2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
 3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
 4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内

skills/lark-slides/references/asset-planning.md

@@ -6,6 +6,7 @@
 
 ## Core Rules
 
+- `asset_need` is metadata only. It can guide page design, but it must not require web search, local download, media upload, or external tools.
 - Every planned asset must include a fallback visual plan. The fallback can use native charts, tables, whiteboard diagrams, placeholder regions, or XML shapes, text, and arrows as appropriate.
 - Asset needs must serve the page's `key_message` and `visual_focus`. Do not add decorative assets that do not clarify the page.
 - Prefer a few high-value asset plans over one asset on every page. For a 6-page technical or business deck, plan assets on at least 3 pages when the content allows.

skills/lark-slides/references/examples.md

@@ -2,90 +2,263 @@
 
 本文档提供与 CLI schema 一致的调用示例，XML 内容均遵循 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
 
-> **重要**：新建 PPT 请使用 `slides +create --slides`，传入由 `<slide>` XML 字符串组成的 JSON 数组；每个元素必须是一页完整的 `<slide>`。复杂内容建议先创建空白 PPT，再通过 `xml_presentation.slide.create` 逐页添加。完整 `<presentation>` XML 可用于本地 lint 或读取，但不能直接作为 `+create` 的提交参数。
+> **重要**：创建 PPT 请优先使用 `slides +create`；实际页面内容请使用 `xml_presentation.slide.create` 逐页添加。
 
 ## 目录
 
-- [示例 1：可靠创建 6 页 PPT](#示例-1可靠创建-6-页-ppt)
+- [示例 1: 使用 Shortcut 创建空白演示文稿](#示例-1-使用-shortcut-创建空白演示文稿)
+- [示例 2: 创建后添加第一页](#示例-2-创建后添加第一页)
+- [示例 3: 读取 XML 内容](#示例-3-读取-xml-内容)
+- [示例 4: 在指定页面前插入新幻灯片](#示例-4-在指定页面前插入新幻灯片)
+- [示例 5: 删除幻灯片](#示例-5-删除幻灯片)
+- [示例 6: 从文件读取 XML 后添加页面](#示例-6-从文件读取-xml-后添加页面)
 - [示例 7: +replace-slide + block_insert 给已有页加图](#示例-7-replace-slide--block_insert-给已有页加图)
 - [示例 8: +replace-slide + block_replace 替换一个块](#示例-8-replace-slide--block_replace-替换一个块)
 
-## 示例 1：可靠创建 6 页 PPT
-
-### 1. 写入规划文件
+## 示例 1: 使用 Shortcut 创建空白演示文稿
 
 ```bash
-DECK_DIR=".lark-slides/plan/reliable-six-page-ppt"
-mkdir -p "$DECK_DIR"
-
-# 按 planning-layer.md 写入 "$DECK_DIR/slide_plan.json"，
-# 至少记录 6 页的顺序和标题。
+lark-cli slides +create --title "项目汇报"
 ```
 
-### 2. 为每页保存独立 XML
+预期返回结构：
 
-每个文件都是完整的 `<slide>`。下面的循环会生成 6 个独立 XML 文件；实际项目中可将每页主体替换为规划内容。
+```json
+{
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "title": "项目汇报",
+    "revision_id": 1
+  }
+}
+```
+
+## 示例 2: 创建后添加第一页
 
 ```bash
-titles=("主题与结论" "问题背景" "核心方法" "关键数据" "执行计划" "总结与行动")
-for i in {1..6}; do
-  printf -v page '%02d' "$i"
-  cat > "$DECK_DIR/slide-$page.xml" <<XML
-<slide xmlns="http://www.larkoffice.com/sml/2.0"><style><fill><fillColor color="rgb(248,250,252)"/></fill></style><data><shape type="rect" topLeftX="56" topLeftY="56" width="12" height="428"><fill><fillColor color="rgb(37,99,235)"/></fill></shape><shape type="text" topLeftX="100" topLeftY="160" width="760" height="90"><content textType="title" autoFit="normal-auto-fit"><p>${titles[$((i-1))]}</p></content></shape><shape type="text" topLeftX="100" topLeftY="290" width="700" height="70"><content textType="body" autoFit="normal-auto-fit"><p>页面主体内容。</p></content></shape></data></slide>
-XML
+PRESENTATION_ID=$(lark-cli slides +create --title "季度复盘" | jq -r '.data.xml_presentation_id')
+
+lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(245, 245, 245)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"72\" width=\"760\" height=\"90\"><content textType=\"title\"><p>2024 Q3 季度复盘</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"190\" width=\"520\" height=\"220\"><content textType=\"body\"><p>关键结论</p><ul><li><p>收入增长 30%</p></li><li><p>重点项目全部上线</p></li><li><p>用户满意度持续提升</p></li></ul></content></shape><shape type=\"rect\" topLeftX=\"660\" topLeftY=\"180\" width=\"180\" height=\"140\"><fill><fillColor color=\"rgba(100, 149, 237, 0.25)\"/></fill><border color=\"rgb(100, 149, 237)\" width=\"2\"/></shape></data><note><content textType=\"body\"><p>讲述时先给结论，再补充数据。</p></content></note></slide>"
+  }
+}'
+```
+
+## 示例 3: 读取 XML 内容
+
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}'
+```
+
+提取 XML 内容：
+
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' | jq -r '.data.xml_presentation.content'
+```
+
+预期返回结构：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "xml_presentation": {
+      "presentation_id": "slides_example_presentation_id",
+      "revision_id": 3,
+      "content": "<presentation xmlns=\"http://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
+    }
+  }
+}
+```
+
+## 示例 4: 在指定页面前插入新幻灯片
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新增页面</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"180\"><content textType=\"body\"><p>这是新增页面的正文。</p></content></shape></data></slide>"
+  },
+  "before_slide_id": "sld_before_target"
+}'
+```
+
+预期返回结构：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "slide_id": "slide_example_id",
+    "revision_id": 100
+  }
+}
+```
+
+## 示例 5: 删除幻灯片
+
+```bash
+lark-cli slides xml_presentation.slide delete --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "slide_id": "slide_example_id"
+}'
+```
+
+预期返回结构：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "revision_id": 101
+  }
+}
+```
+
+## 示例 6: 从文件读取 XML 后添加页面
+
+先准备 `slide.xml`：
+
+```xml
+<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <data>
+    <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+      <content textType="title">
+        <p>从文件加载</p>
+      </content>
+    </shape>
+  </data>
+</slide>
+```
+
+先创建演示文稿：
+
+```bash
+PRESENTATION_ID=$(lark-cli slides +create --title "从文件添加页面" | jq -r '.data.xml_presentation_id')
+```
+
+再用 `jq` 组装请求体，从文件添加页面：
+
+```bash
+lark-cli slides xml_presentation.slide create --as user \
+  --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" \
+  --data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
+```
+
+## 示例 7: +replace-slide + block_insert 给已有页加图
+
+只想在已有页上加一张图、不动其他元素——走 shortcut `+replace-slide`，`block_insert` 追加到页末（或用 `insert_before_block_id` 指定位置）。
+
+```bash
+PID="slides_example_presentation_id"
+SID="slide_example_id"
+
+# 1. 上传图片拿 file_token
+TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user \
+  | jq -r '.data.file_token')
+
+# 2. block_insert 到页面末尾（省略 insert_before_block_id）
+# 注：<img .../> 是自闭合标签，CLI 不会展开（只有 <shape/> 会被补 <content/>）
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts "$(jq -n --arg token "$TOKEN" \
+    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")}]')"
+```
+
+预期返回：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "slide_id": "slide_example_id",
+    "parts_count": 1,
+    "revision_id": 102
+  }
+}
+```
+
+## 示例 8: +replace-slide + block_replace 替换一个块
+
+已知某块的 3 位 short element ID（从 `slide.get` 返回 XML 里读），整块换掉。`replacement` 根元素的 `id` 会由 CLI 自动注入为 `block_id`，无需手写；若写了 `<shape/>` 自闭合形式，CLI 也会自动补 `<content/>`。
+
+```bash
+lark-cli slides +replace-slide --as user \
+  --presentation slides_example_presentation_id \
+  --slide-id slide_example_id \
+  --parts '[
+    {
+      "action": "block_replace",
+      "block_id": "bab",
+      "replacement": "<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"
+    }
+  ]'
+# CLI 实际发送的 replacement 根元素会带 id="bab"，即使手写时省略了
+```
+
+失败时（3350001 错误，CLI 在 error 字段中给出 hint）：
+
+```json
+{
+  "ok": false,
+  "identity": "user",
+  "error": {
+    "type": "api",
+    "subtype": "unknown",
+    "code": 3350001,
+    "message": "API error: [3350001] invalid param",
+    "hint": "common causes: (1) block_id not found in current slide ..."
+  }
+}
+```
+
+整批作为原子事务，任一 part 失败则整批不生效；按 `error.hint` 检查 `block_id`、XML 结构或页面边界后重发。
+
+## 常见处理技巧
+
+### 获取最新 revision_id
+
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' | jq '.data.xml_presentation.revision_id'
+```
+
+### 批量插入多页
+
+```bash
+#!/bin/bash
+
+PRESENTATION_ID="slides_example_presentation_id"
+
+slides=(
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 1</p></content></shape></data></slide>'
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 2</p></content></shape></data></slide>'
+)
+
+for slide_xml in "${slides[@]}"; do
+  payload=$(jq -n --arg content "$slide_xml" '{slide:{content:$content}}')
+  lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data "$payload"
 done
 ```
 
-### 3. 逐页运行 lint
-
-提交前检查每个独立 XML。`summary.error_count` 必须为 `0`，否则先修复 XML 或布局问题。
+### 本地校验 XML 基本语法
 
 ```bash
-for slide_xml in "$DECK_DIR"/slide-0{1,2,3,4,5,6}.xml; do
-  python3 skills/lark-slides/scripts/xml_text_overlap_lint.py \
-    --input "$slide_xml" | tee "${slide_xml%.xml}.lint.json"
-done
-
-test "$(jq -s 'map(.summary.error_count) | add' "$DECK_DIR"/slide-0{1,2,3,4,5,6}.lint.json)" = "0"
+xmllint --noout presentation.xml
 ```
 
-### 4. 使用 `+create` 创建 6 页 PPT
-
-`--slides` 接收由 6 个完整 `<slide>` XML 字符串组成的 JSON 数组；使用 `jq --rawfile` 避免手动处理 XML 引号和换行。
-
-```bash
-lark-cli slides +create --as user \
-  --title "可靠创建 6 页 PPT" \
-  --slides "$(jq -n \
-    --rawfile s1 "$DECK_DIR/slide-01.xml" \
-    --rawfile s2 "$DECK_DIR/slide-02.xml" \
-    --rawfile s3 "$DECK_DIR/slide-03.xml" \
-    --rawfile s4 "$DECK_DIR/slide-04.xml" \
-    --rawfile s5 "$DECK_DIR/slide-05.xml" \
-    --rawfile s6 "$DECK_DIR/slide-06.xml" \
-    '[$s1, $s2, $s3, $s4, $s5, $s6]')" \
-  > "$DECK_DIR/create.json"
-create_status=$?
-
-if [ "$create_status" -ne 0 ]; then
-  exit "$create_status"
-fi
-
-if ! PRESENTATION_ID=$(jq -er '.data.xml_presentation_id | strings | select(length > 0)' "$DECK_DIR/create.json"); then
-  echo "missing non-empty data.xml_presentation_id in $DECK_DIR/create.json" >&2
-  exit 1
-fi
-echo "$PRESENTATION_ID" > "$DECK_DIR/xml_presentation_id"
-```
-
-如果创建中途失败，先保存已经返回的 `xml_presentation_id`，再回读确认实际已创建页数。
-
-### 5. 用 `+xml-get` 回读全文 XML
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PRESENTATION_ID" \
-  --output "$DECK_DIR/readback.xml" \
-  --json | tee "$DECK_DIR/readback.json"
-```
+### 真实示例
 
+- [slides_demo.xml](slides_demo.xml) 提供了更完整的页面示例，包含 `theme`、渐变填充、图片、图标和备注内容。

skills/lark-slides/references/iconpark.md

@@ -1,6 +1,6 @@
 # IconPark 图标
 
-IconPark 图标通过 `<icon>` 写入 slides XML，`iconType` 必须来自本 skill 的离线索引，避免凭记忆拼路径。
+IconPark 图标通过 `<icon>` 写入 slides XML，`iconType` 必须来自本 skill 的离线索引或已验证模板，避免凭记忆拼路径。
 
 ## 机器优先流程
 
@@ -25,7 +25,7 @@ python3 skills/lark-slides/scripts/iconpark_tool.py list-categories
 - 默认先检索：语义图标需求必须先用 `iconpark_tool.py search --limit 8` 或 `--limit 10`，让 agent 从候选里结合版面语义二次判断；不要阅读全文索引，也不要编造不存在的 `iconType`。
 - 图标用于概念提示、步骤、状态、指标、角色和导航；不要用无关装饰图标填充版面。
 - 常用尺寸：行内状态图标 16-24px，卡片标题图标 28-40px，主视觉图标 56-96px。
-- 视觉规范要求图标设置非透明 `fillColor`，显式指定颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
+- 图标必须显式指定颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
 - 查不到合适图标时，用 shape、line、text 画 XML-native fallback，不留空图标位。
 
 ## 高频示例

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

@@ -5,14 +5,6 @@
 
 创建一个新的飞书幻灯片演示文稿，可选一步添加页面内容。
 
-- 禁止：从完整 <presentation> XML 解析/拆分/重序列化生成提交 payload。
-- 推荐：提交源直接就是单页 <slide> XML；+create --slides 只接受已经人工/程序直接生成的 slide 数组，不接受由
-      presentation 动态拆出来的数组。
-
-- 最稳：复杂 deck 默认空 deck + 单页 slide create，每次只提交一个 <slide>。
-
-- 注意：复杂 XML 不适合直接塞命令行，中文、引号、特殊字符较多时，直接拼接 --slides 容易发生 shell 转义或截断。建议将每页 XML 保存为独立文件，使用 `jq --rawfile` 组装 JSON 数组，避免手动处理 XML 引号和换行。
-
 ## 命令
 
 ```bash
@@ -32,18 +24,6 @@ lark-cli slides +create --title "项目汇报" --as bot
 lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
 ```
 
-复杂内容建议按页保存 XML，再用 `jq --rawfile` 组装 `--slides` 参数：
-
-```bash
-lark-cli slides +create --as user --title "项目汇报" \
-  --slides "$(jq -n \
-    --rawfile s1 .lark-slides/plan/project/slide-01.xml \
-    --rawfile s2 .lark-slides/plan/project/slide-02.xml \
-    '[$s1, $s2]')"
-```
-
-`--rawfile` 会把文件内容作为字符串读入 JSON，自动处理 XML 中的引号和换行；不要手动拼接带大量转义符的 JSON 字符串。
-
 ## 返回值
 
 工具成功执行后，返回一个 JSON 对象，包含以下字段：
@@ -153,4 +133,5 @@ lark-cli slides xml_presentation.slide create --as user \
 
 ## 相关命令
 
-- [slides +xml-get](lark-slides-xml-get.md) — 读取 PPT 内容并保存到本地文件
+- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 添加幻灯片页面
+- [xml_presentations get](lark-slides-xml-presentations-get.md) — 读取 PPT 内容

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

@@ -125,3 +125,4 @@ lark-cli slides +replace-slide --as user \
 
 - [+create](lark-slides-create.md) — 新建 PPT（支持 `@` 占位符自动上传图片）
 - [+replace-slide](lark-slides-replace-slide.md) — 给已有页加图 / 换图（`block_insert` / `block_replace`）
+- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 创建 slide 页面（拿到 file_token 后塞进 XML）

skills/lark-slides/references/lark-slides-pptx-template-workflows.md

@@ -1,89 +0,0 @@
-# PPT Template Rewrite Principles
-
-本页只约束“用户指定 PPT 模板、底稿、已有 PPTX/PDF/Slides，并要求基于它二次创作”的场景。核心原则：模板不是风格参考，而是必须沿用的编辑底稿。
-
-## Import First
-
-用户指定 PPT 模板时，先把模板导入成 Lark Slides。后续写入目标是导入后的 Slides，不是新建一个脱离模板的 deck，也不是先在本地重画 PPTX 再导入。
-
-直接使用以下命令，不需要先加载 `lark-drive` skill：
-
-```bash
-lark-cli drive +import --as user --file "<template.pptx>" --type slides --json
-```
-
-可选参数：用 `--name "<title>"` 指定导入后的 Slides 标题；用 `--folder-token <FOLDER_TOKEN>` 指定目标文件夹。若返回 `ready=false` / `timed_out=true`，直接执行返回值里的 `next_command`；等价形式是：
-
-```bash
-lark-cli drive +task_result --scenario import --ticket <TICKET>
-```
-
-导入后必须回读 Slides 内容，理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。回读结果是模板二创的事实来源。
-
-## Read Before Editing
-
-编辑任何 PPT 页面前，必须先阅读该页面。
-
-如果当前上下文中没有该页内容，必须重新读取页面；这里的“当前上下文”不包含 System Prompt。不能只凭记忆、文件名、缩略图印象或模板整体风格判断来编辑具体页面。
-
-阅读页面时至少判断：
-
-- 该页原本承担的角色，例如封面、章节页、目录、流程、对比、数据、总结。
-- 该页的主要版式结构，例如图文关系、箭头、时间线、节点、表格、图表、左右对照、背景图或产品图。
-- 哪些文本框、shape 标签、表格单元格或图表标签承载内容。
-- 原页面的字体、字号、颜色、对齐、层级和留白关系。
-
-## Edit The Imported Slides Directly
-
-理解页面后，直接在导入后的 Slides 上编辑。允许的操作包括：
-
-- 填写、替换、凝练或删除文字。
-- 替换或补充图片。
-- 更新图表、表格、数字标签或节点标签里的内容。
-- 按需复制、删除或重排模板页。
-- 在源页面没有合适承载位置时，做局部、小范围新增元素。
-
-新增元素只能补足内容缺口，不能成为新的主版式。页面主体仍应由模板原有版式承载。
-
-## Preserve Design
-
-模板二创必须严格沿用原版式和字体，只改内容，不做设计。
-
-默认保留：
-
-- 页面布局、视觉层级、留白和对齐关系。
-- 原字体、字号体系、颜色、文本框位置和 shape 顺序。
-- 背景图、图片、logo、图表、表格、装饰形状、线条、图标和页面结构。
-- 模板中不同页型之间的差异。
-
-不要把模板页改造成统一的通用卡片、白板、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。
-
-## Content Only
-
-内容必须优先进入原页面已有的文本框、shape 标签、节点、表格单元格、图表标签或注释容器。
-
-如果原容器空间不足，优先：
-
-- 凝练文字。
-- 降低字号但保持原字体体系。
-- 拆分到页面已有的邻近容器。
-- 使用模板已有的注释、标签或补充说明区域。
-- 复制同页或同模板中的原生容器样式做局部补充。
-
-不要为了容纳长文案而重画页面主体结构。不要用新增大卡片遮住原图表、箭头、图片、背景或关键 shape。
-
-## Readback And Tune
-
-完成编辑后必须回读结果，并逐页微调。
-
-回读时重点检查：
-
-- 文字是否溢出、截断、压线或超出容器。
-- 文本是否遮挡图片、图表、shape、箭头、节点或其他文字。
-- shape 顺序是否导致内容被覆盖或遮住。
-- 新内容是否仍然落在模板原有版式中，而不是覆盖模板结构。
-- 字体、字号、颜色、对齐和层级是否仍贴近原页。
-
-发现文字溢出时，优先凝练文字或缩减字号。发现遮挡时，调整 shape 顺序、局部位置或复用原有空白区域解决。只有在这些方法都不能满足内容表达时，才做局部新增或删除。
-
-模板二创的完成标准不是“生成了一套看起来统一的新 PPT”，而是“原模板的版式、字体和视觉结构仍清晰存在，内容已经被准确替换，并且回读后没有溢出和遮挡”。

skills/lark-slides/references/lark-slides-replace-pages.md

@@ -89,7 +89,7 @@ lark-cli slides +replace-pages --as user \
 
 ## 使用建议
 
-1. 大幅改写前先 `slides +xml-get` 保存当前 XML，并记录要替换页面的 `slide_id`。
+1. 大幅改写前先 `xml_presentations.get` 保存当前 XML，并记录要替换页面的 `slide_id`。
 2. 生成只含 `slide_id` 的 `pages.json` 后先跑 `--dry-run` 或 `--validate-only`。
 3. 默认不要开 `--continue-on-error`，除非能接受部分页面已替换。
 4. 替换后再回读全文 XML 并截图检查，确认页序、视觉和文本没有破损。

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

@@ -47,7 +47,7 @@ lark-cli slides +replace-slide --as user \
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
-| `--slide-id` | 是 | 页面 ID（`xml_presentation.slide.get` / `slides +xml-get` 都能拿到） |
+| `--slide-id` | 是 | 页面 ID（`xml_presentation.slide.get` / `xml_presentations.get` 都能拿到） |
 | `--parts` | 是 | JSON 数组（`[{...}, ...]`），单次最多 200 条。支持 `@<file>` 和 `-`（stdin）读取 |
 | `--revision-id` | 否 | 基础版本号；默认 `-1` 表示基于最新版执行；传具体版本号时，服务端以该版本为 base 执行；**传不存在的版本号（超过当前 revision）返回 3350002** |
 | `--tid` | 否 | 并发事务 ID；多人协作长事务才用，单次单人调用留空 |

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

@@ -4,7 +4,7 @@
 
 获取幻灯片页面截图并保存为本地图片文件。默认用于已存在 PPT 页面截图；传入 `--content` 时用于直接渲染单个 `<slide>` XML 片段预览。本 shortcut 会在 CLI 进程内解码并写入文件，stdout 只返回文件路径、大小、页面 ID 等元信息，避免把图片 Base64 输出给模型。
 
-注意：该截图能力受应用白名单限制，绝大多数应用不可用。若截图失败，记录错误即可；不要引导用户申请 `slides:presentation:screenshot` 权限。后续按 `validation-checklist.md` 走非截图验证，不要声称已完成截图验收。
+注意：该截图能力受应用白名单限制，绝大多数应用不可用。截图失败时不要引导用户申请 `slides:presentation:screenshot` 权限；记录错误后降级到 XML 读回、结构 lint、文本重叠检查等非截图检查路径。
 
 ## 命令
 
@@ -26,8 +26,8 @@ lark-cli slides +screenshot --as user \
 | 参数 | 必需 | 说明 |
 |------|------|------|
 | `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL，或解析后为 slides 的 `/wiki/` URL。传 `--content` 时不能使用 |
-| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
-| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
+| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入 |
+| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入 |
 | `--content` | render 模式必需 | 要直接渲染的 `<slide>` XML 片段；支持直接传值、`@file`、`-` stdin。传入后不能同时传 `--slide-id` / `--slide-number` |
 | `--output-dir` | 否 | 输出目录，默认 `.lark-slides/screenshots`；必须是当前目录内的相对路径 |
 | `--output-name` | 否 | render 模式的输出文件名 stem；未指定时优先用返回的 `slide_id`，否则用 `rendered-slide`。若目标文件已存在，会自动追加递增后缀避免覆盖 |
@@ -44,8 +44,6 @@ lark-cli slides +screenshot --as user \
 
 ### 多页截图
 
-一次不要超过 10 页；如需更多页面，分批调用。
-
 ```bash
 lark-cli slides +screenshot --as user \
   --presentation slides_example_presentation_id \
@@ -92,6 +90,5 @@ lark-cli slides +screenshot --as user \
 2. 已存在 PPT 页面截图时，不传 `--content`，用 `--presentation` + `--slide-id` 或 `--slide-number`。
 3. 本地 XML 预览时，传 `--content @file` 或 `--content -`，内容应为单个 `<slide>` XML 片段；此时不要传 `--presentation` / `--slide-id` / `--slide-number`。
 4. `slide_id` 是页面 short ID，页码请用 `--slide-number`。
-5. list 模式一次最多传 10 页（`--slide-id` + `--slide-number` 合计小于等于 10）；更多页面请分批截图。
-6. list 模式默认文件名包含 presentation ID、页码和/或 slide ID；文件已存在时自动追加 `_2`、`_3` 等后缀，避免覆盖旧截图。
-7. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。
+5. list 模式默认文件名包含 presentation ID、页码和/或 slide ID；文件已存在时自动追加 `_2`、`_3` 等后缀，避免覆盖旧截图。
+6. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。

skills/lark-slides/references/lark-slides-xml-get.md

@@ -1,100 +0,0 @@
-# slides +xml-get（读取 XML）
-
-读取已有演示文稿的完整 XML，或按 `slide_id` / 页码读取单页 XML。适合创建后验收、编辑前备份、获取 `slide_id` / `revision_id`，以及排查空白页、破图、文本溢出等问题。相比直接调用底层 `xml_presentations.get` / `xml_presentation.slide.get`，本 shortcut 会自动解析 Slides URL / Wiki URL，并可把 XML 保存到本地文件，避免终端输出被截断。
-
-## 命令
-
-
-```bash
-lark-cli slides +xml-get \
-  --as user \
-  --presentation <slides_url_or_xml_presentation_id> \
-  --output .lark-slides/plan/<deck-id>/readback.xml
-```
-
-## 参数
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
-| `--output` | 否 | 本地 XML 保存路径，必须是当前工作目录内的相对路径，不能传绝对路径。传入时 XML 内容保存到文件，stdout 只返回保存后的绝对路径、大小等简短元信息；省略时默认返回 JSON envelope |
-| `--slide-id` | 否 | 页面 short ID；传入后只读取该页 XML。不能和 `--slide-number` 同时使用 |
-| `--slide-number` | 否 | 1-based 页码；传入后只读取该页 XML。不能和 `--slide-id` 同时使用 |
-| `--revision-id` | 否 | 读取指定版本；默认 `-1`，表示最新版本 |
-| `--remove-attr-id` | 否 | 仅全文读取可用。移除返回 XML 中的 `id` 属性；适合只读检查，不适合精确块级编辑 |
-| `--raw` | 否 | 省略 `--output` 时直接把 XML 原文写到 stdout，不包 JSON envelope。不能和 `--output` / `--jq` / 非 json `--format` 同时使用 |
-| `--dry-run` | 否 | 预览将调用的 API 和输出方式，不读取真实 XML |
-
-## 输出到文件
-
-推荐普通工作流都传 `--output`，尤其是中大型 PPT。`--output` 必须是当前工作目录内的相对路径，例如 `.lark-slides/plan/$PID/readback.xml`，不要传 `/tmp/readback.xml` 这类绝对路径。XML 会写入本地文件，stdout 只保留元信息，便于后续脚本读取。
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --output .lark-slides/plan/$PID/readback.xml
-```
-
-成功输出中的 `data` 类似：
-
-```json
-{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "path": "/abs/path/.lark-slides/plan/slides_example_presentation_id/readback.xml",
-  "size": 123456,
-  "content_saved": true,
-  "revision_id": 12
-}
-```
-
-其中 `path` 是 CLI 解析后的绝对路径。
-
-如果传入 `--remove-attr-id`，返回元信息中会包含 `"remove_attr_id": true`。
-
-## 读取单页
-
-已知页面 short ID 时，用 `--slide-id`：
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --slide-id "$SID" \
-  --output .lark-slides/plan/$PID/slide-$SID.xml
-```
-
-已知页码时，用 `--slide-number`（页码从 1 开始）：
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --slide-number 2 \
-  --output .lark-slides/plan/$PID/slide-2.xml
-```
-
-单页模式底层调用 `xml_presentation.slide.get`，返回或保存的是单个 `<slide>` XML 片段。`--slide-id` 和 `--slide-number` 不能同时传；`--remove-attr-id` 只支持全文读取。
-
-## 输出到终端
-
-省略 `--output` 时，CLI 默认输出 JSON envelope，XML 位于 `data.xml_presentation.content`（全文）或 `data.slide.content`（单页）。这个模式适合配合 `--jq` 临时提取：
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --jq '.data.xml_presentation.content'
-```
-
-需要把 XML 原文直接写到 stdout 时，加 `--raw`：
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "$PID" \
-  --slide-number 2 \
-  --raw
-```
-
-## 相关命令
-
-- [slides +screenshot](lark-slides-screenshot.md) - 获取页面截图做视觉验证
-- [slides +replace-slide](lark-slides-replace-slide.md) - 局部替换或插入页面元素
-- [slides +replace-pages](lark-slides-replace-pages.md) - 多页整页重建
-- [xml_presentations get](lark-slides-xml-presentations-get.md) - 底层原生 API 参考

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

@@ -0,0 +1,220 @@
+# lark-slides xml_presentation.slide create
+
+## 用途
+
+在指定的 XML 演示文稿中创建新的幻灯片页面，通常用于给 `slides +create` 创建出的空白 PPT 逐页补充内容。
+
+## 命令
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '<json_params>' --data '<json_data>'
+```
+
+## 参数说明
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--params` | JSON string | 是 | 路径参数与查询参数 |
+| `--data` | JSON string | 是 | 请求体，包含新页面内容 |
+
+### params JSON 结构
+
+```json
+{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "revision_id": -1,
+  "tid": "idMock"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `xml_presentation_id` | string | 是 | 目标演示文稿的唯一标识符 |
+| `revision_id` | integer | 否 | 演示文稿版本号，`-1` 表示最新版本 |
+| `tid` | string | 否 | 锁的事务 ID |
+
+### data JSON 结构
+
+```json
+{
+  "slide": {
+    "slide_id": "slide_example_id",
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\">...</slide>"
+  },
+  "before_slide_id": "slide_before_target"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `slide.slide_id` | string | 否 | 幻灯片页面 short ID |
+| `slide.content` | string | 否 | 新幻灯片的 XML 内容 |
+| `before_slide_id` | string | 否 | 插入到指定页面之前 |
+
+## slide XML 结构
+
+`slide.content` 是一个完整的 `<slide>` 元素，遵循 SML 2.0 Schema：
+
+```xml
+<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <data>
+    <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+      <content textType="title">
+        <p>标题</p>
+      </content>
+    </shape>
+  </data>
+</slide>
+```
+
+详细格式请参考 [xml-format-guide.md](xml-format-guide.md) 和 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
+
+## 使用示例
+
+### 在末尾添加幻灯片
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新页面标题</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"180\"><content textType=\"body\"><p>内容文本</p></content></shape></data></slide>"
+  }
+}'
+```
+
+### 在指定页面前插入幻灯片
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>插入的标题页</p></content></shape></data></slide>"
+  },
+  "before_slide_id": "slide_before_target"
+}'
+```
+
+### 带图形元素的幻灯片
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"520\" height=\"120\"><content textType=\"title\"><p>数据展示</p></content></shape><shape type=\"rect\" topLeftX=\"700\" topLeftY=\"100\" width=\"200\" height=\"150\"><fill><fillColor color=\"rgb(100, 149, 237)\"/></fill></shape></data></slide>"
+  }
+}'
+```
+
+### 从文件读取 XML
+
+```bash
+# 先创建 slide.xml 文件
+cat > slide.xml << 'EOF'
+<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <data>
+    <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+      <content textType="title">
+        <p>从文件加载</p>
+      </content>
+    </shape>
+    <shape type="text" topLeftX="80" topLeftY="200" width="800" height="180">
+      <content textType="body">
+        <p>这是从文件读取的幻灯片内容</p>
+      </content>
+    </shape>
+  </data>
+</slide>
+EOF
+
+# 然后创建幻灯片
+lark-cli slides xml_presentation.slide create --as user \
+  --params '{"xml_presentation_id":"slides_example_presentation_id"}' \
+  --data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
+```
+
+## 返回值
+
+成功时返回创建的幻灯片信息：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "slide_id": "slide_example_id",
+    "revision_id": 100
+  }
+}
+```
+
+### 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.slide_id` | string | 新幻灯片的唯一标识 |
+| `data.revision_id` | integer | 演示文稿最新版本号 |
+
+## slide 元素可用子元素
+
+| 元素 | 说明 |
+|------|------|
+| `<style>` | 页面样式（背景填充） |
+| `<data>` | 图形元素容器（shape、img、table、chart、whiteboard 等） |
+| `<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）。
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
+| 400 | XML 格式错误 | 检查 `slide.content` 是否是完整 `<slide>` 元素 |
+| 400 | 请求体结构错误 | 检查是否按 `slide.content` 和 `before_slide_id` 包装 |
+| 403 | 权限不足 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope |
+| 3350001 | XML 非 well-formed 或服务端参数校验失败 | 优先检查未转义字符：文本 `Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2` |
+
+## 注意事项
+
+1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentation.slide.create` 查看最新的参数结构
+2. **slide.content 格式**: 必须是完整的 `<slide>` 元素，不是整个 presentation
+3. **命名空间建议**: 协议标准写法应带 `xmlns`，例如 `<slide xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
+4. **fill / border 写法**: 颜色填充使用 `<fill><fillColor color="..."/></fill>`，边框常用 `<border color="..." width="2"/>`
+5. **插入位置**: 通过 `before_slide_id` 指定插入目标，而不是用 `position`
+6. **JSON 转义**: 如果直接内联 XML，需要正确转义双引号
+7. **建议**: 先使用 `xml_presentations.get` 获取现有结构，再添加新页面
+
+## 批量添加建议
+
+如果需要添加多张幻灯片，建议先明确每一页的 `before_slide_id`，或直接按最终顺序逐页追加：
+
+```bash
+#!/bin/bash
+
+PRESENTATION_ID="slides_example_presentation_id"
+
+declare -a slides=(
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 1</p></content></shape></data></slide>'
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 2</p></content></shape></data></slide>'
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 3</p></content></shape></data></slide>'
+)
+
+for slide_xml in "${slides[@]}"; do
+  payload=$(jq -n --arg content "$slide_xml" '{slide:{content:$content}}')
+  lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data "$payload"
+done
+```
+
+## 相关命令
+
+- [slides +create](lark-slides-create.md) - 创建空白 PPT
+- [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
+- [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
+- [xml-format-guide.md](xml-format-guide.md) - XML 格式详细规范
+- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - Schema 快速参考