docs(sheets): mirror unified AI() formula docs from spec

Sync the lark-sheets AI formula skill from sheet-skill-spec (SoT) after
the product change that merges all AI formulas into one AI() function:

- formula-translation reference: single =AI(prompt, [range]) function with
  syntax (incl. variadic =AI(part1, part2, ...) concatenation), per-case
  usage table (translate / sentiment / classify / extract / summarize /
  rewrite / generate / cleanup / keywords / multi-cell prompt), and
  prompt best practices
- formula-verify reference + --ai-only flag def: unified AI() wording
- flag_defs_gen.go regenerated from flag-defs.json
- lark_sheet_formula_verify.go: drop stale AI_WRITE / AI_CLASSIFY names
  in the ai_only comment, reference the unified AI() function

Co-authored-by: TRAE CLI <noreply@bytedance.com>

AGENTS.md

@@ -105,6 +105,20 @@ Signatures that are easy to guess wrong:
 
 Program output (JSON envelopes) goes to stdout. Progress, warnings, hints go to stderr. Mixing them corrupts pipe chains.
 
+### Typed data over loose maps
+
+Parse `map[string]interface{}` into a typed struct at the boundary — one projection function per shape — and let everything downstream consume struct fields, not string keys. A typo'd map key compiles fine and fails at runtime, which an agent then debugs blind.
+
+Use distinct types when two values could be swapped silently: see `internal/meta.Token` — a bare string compiles on either side of a string/string signature, a distinct type does not.
+
+Legacy loose-map code exists in older paths. Match its call sites when touching it, but do not copy the pattern into new code.
+
+### Transcribe faithfully — no silent fallbacks
+
+When code echoes input onward (request previews, transformations, proxies), transcribe verbatim. A `default:` branch that coerces unrecognized input into a plausible value ("unknown HTTP verb → GET") makes the output lie, and an agent reasons from the lie.
+
+The same rule applies to flag combinations and internal wiring: if a requested option cannot be honored, return a typed validation error — never silently substitute another behavior and exit 0. Silent guesses (defaulting a missing identity, discarding writes on a nil writer) are bugs even when every current caller happens to avoid them.
+
 ### Use `vfs.*` instead of `os.*`
 
 All filesystem access goes through `internal/vfs`. This enables test mocking.
@@ -116,6 +130,7 @@ CLI arguments are untrusted (they come from AI agents). Call `validate.SafeInput
 ### Tests
 
 - Every behavior change needs a test alongside the change.
+- A contract test must fail if the implementation is reverted. If you can undo the code change and the suite stays green, the contract is not pinned — assert the new field/behavior directly, not a happy-path substring.
 - `cmdutil.TestFactory(t, config)` for test factories.
 - `t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())` to isolate config state.
 

cmd/api/api.go

@@ -130,6 +130,13 @@ func buildAPIRequest(opts *APIOptions) (client.RawApiRequest, *cmdutil.FileUploa
 	stdin := opts.Factory.IOStreams.In
 	fileIO := opts.Factory.ResolveFileIO(opts.Ctx)
 
+	if opts.Method == "" {
+		return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"HTTP method must not be empty").
+			WithHint("pass the verb as the first argument, e.g. lark-cli api GET /open-apis/...").
+			WithParam("<method>")
+	}
+
 	// Validate --file mutual exclusions first.
 	if err := cmdutil.ValidateFileFlag(opts.File, opts.Params, opts.Data, opts.Output, opts.PageAll, opts.Method); err != nil {
 		return client.RawApiRequest{}, nil, err
@@ -243,9 +250,9 @@ func apiRun(opts *APIOptions) error {
 
 	if opts.DryRun {
 		if fileMeta != nil {
-			return cmdutil.PrintDryRunWithFile(f.IOStreams.Out, request, config, opts.Format, fileMeta.FieldName, fileMeta.FilePath, fileMeta.FormFields)
+			return cmdutil.PrintDryRunWithFile(request, config, dryRunOutputOptions(f, opts), *fileMeta)
 		}
-		return apiDryRun(f, request, config, opts.Format)
+		return apiDryRun(f, request, config, opts)
 	}
 	// Identity info is now included in the JSON envelope; skip stderr printing.
 	// cmdutil.PrintIdentity(f.IOStreams.ErrOut, opts.As, config, f.IdentityAutoDetected)
@@ -297,8 +304,19 @@ func apiRun(opts *APIOptions) error {
 	return nil
 }
 
-func apiDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.CliConfig, format string) error {
-	return cmdutil.PrintDryRun(f.IOStreams.Out, request, config, format)
+func apiDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.CliConfig, opts *APIOptions) error {
+	return cmdutil.PrintDryRun(request, config, dryRunOutputOptions(f, opts))
+}
+
+func dryRunOutputOptions(f *cmdutil.Factory, opts *APIOptions) cmdutil.DryRunOutputOptions {
+	return cmdutil.DryRunOutputOptions{
+		Format:      opts.Format,
+		JqExpr:      opts.JqExpr,
+		CommandPath: opts.Cmd.CommandPath(),
+		Identity:    opts.As,
+		Out:         f.IOStreams.Out,
+		ErrOut:      f.IOStreams.ErrOut,
+	}
 }
 
 func apiPaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, commandPath string, pagOpts client.PaginationOptions) error {

cmd/api/api_test.go

@@ -69,7 +69,7 @@ func TestApiCmd_FlagParsing(t *testing.T) {
 }
 
 func TestApiCmd_DryRun(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
@@ -79,12 +79,42 @@ func TestApiCmd_DryRun(t *testing.T) {
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	output := stdout.String()
-	if !strings.Contains(output, "Dry Run") {
-		t.Error("expected dry run output")
+	var got map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("dry-run stdout is not JSON: %v\nstdout:\n%s\nstderr:\n%s", err, stdout.String(), stderr.String())
 	}
-	if !strings.Contains(output, "/open-apis/test") {
-		t.Error("expected path in dry run output")
+	if got["ok"] != true || got["identity"] != "bot" || got["dry_run"] != true {
+		t.Fatalf("unexpected dry-run envelope: %#v", got)
+	}
+	data, ok := got["data"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("data = %#v, want object", got["data"])
+	}
+	api, ok := data["api"].([]interface{})
+	if !ok || len(api) != 1 {
+		t.Fatalf("api = %#v, want one call", data["api"])
+	}
+	call, ok := api[0].(map[string]interface{})
+	if !ok || call["url"] != "/open-apis/test" {
+		t.Fatalf("api[0] = %#v", api[0])
+	}
+	if strings.Contains(stdout.String(), "=== Dry Run ===") {
+		t.Fatalf("stdout should not contain dry-run banner: %s", stdout.String())
+	}
+}
+
+func TestApiCmd_DryRunWithJq(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	cmd := newTestApiCmd(f, nil)
+	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--dry-run", "--jq", ".data.api[0].url"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := strings.TrimSpace(stdout.String()); got != "/open-apis/test" {
+		t.Fatalf("jq output = %q, want /open-apis/test", got)
 	}
 }
 
@@ -152,6 +182,22 @@ func TestApiCmd_MissingArgs(t *testing.T) {
 	}
 }
 
+func TestApiCmd_EmptyMethodRejected(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	cmd := newTestApiCmd(f, nil)
+	cmd.SetArgs([]string{"", "/open-apis/test", "--as", "bot", "--dry-run"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected validation error for empty HTTP method")
+	}
+	if !strings.Contains(err.Error(), "method") {
+		t.Fatalf("error should name the method argument, got: %v", err)
+	}
+}
+
 func TestApiCmd_InvalidParamsJSON(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -1000,11 +1046,23 @@ func TestApiCmd_DryRunWithFile(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	out := stdout.String()
-	if !strings.Contains(out, "image") {
-		t.Errorf("expected dry-run output to mention file field, got: %s", out)
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("dry-run stdout is not JSON: %v\n%s", err, out)
 	}
-	if !strings.Contains(out, "Dry Run") {
-		t.Errorf("expected dry-run header, got: %s", out)
+	if env["dry_run"] != true {
+		t.Fatalf("dry_run = %#v, want true", env["dry_run"])
+	}
+	data := env["data"].(map[string]interface{})
+	api := data["api"].([]interface{})
+	call := api[0].(map[string]interface{})
+	body := call["body"].(map[string]interface{})
+	file := body["file"].(map[string]interface{})
+	if file["field"] != "image" || file["path"] != tmpFile {
+		t.Fatalf("unexpected file dry-run body: %#v", body)
+	}
+	if strings.Contains(out, "=== Dry Run ===") {
+		t.Fatalf("stdout should not contain dry-run banner: %s", out)
 	}
 }
 

cmd/service/service.go

@@ -403,9 +403,9 @@ func serviceMethodRun(opts *ServiceMethodOptions) error {
 
 	if opts.DryRun {
 		if fileMeta != nil {
-			return cmdutil.PrintDryRunWithFile(f.IOStreams.Out, request, config, opts.Format, fileMeta.FieldName, fileMeta.FilePath, fileMeta.FormFields)
+			return cmdutil.PrintDryRunWithFile(request, config, serviceDryRunOutputOptions(f, opts), *fileMeta)
 		}
-		return serviceDryRun(f, request, config, opts.Format)
+		return serviceDryRun(f, request, config, opts)
 	}
 
 	if opts.Method.Risk == cmdutil.RiskHighRiskWrite {
@@ -667,8 +667,19 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 	return request, nil, nil
 }
 
-func serviceDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.CliConfig, format string) error {
-	return cmdutil.PrintDryRun(f.IOStreams.Out, request, config, format)
+func serviceDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.CliConfig, opts *ServiceMethodOptions) error {
+	return cmdutil.PrintDryRun(request, config, serviceDryRunOutputOptions(f, opts))
+}
+
+func serviceDryRunOutputOptions(f *cmdutil.Factory, opts *ServiceMethodOptions) cmdutil.DryRunOutputOptions {
+	return cmdutil.DryRunOutputOptions{
+		Format:      opts.Format,
+		JqExpr:      opts.JqExpr,
+		CommandPath: opts.Cmd.CommandPath(),
+		Identity:    opts.As,
+		Out:         f.IOStreams.Out,
+		ErrOut:      f.IOStreams.ErrOut,
+	}
 }
 
 func servicePaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, commandPath string, pagOpts client.PaginationOptions, checkErr func(interface{}, core.Identity) error) error {

cmd/service/service_test.go

@@ -224,13 +224,39 @@ func TestServiceMethod_DryRun_PathParam(t *testing.T) {
 			if err := cmd.Execute(); err != nil {
 				t.Fatalf("unexpected error: %v", err)
 			}
-			if !strings.Contains(stdout.String(), tt.wantInURL) {
-				t.Errorf("expected URL containing %q, got:\n%s", tt.wantInURL, stdout.String())
+			var got map[string]interface{}
+			if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+				t.Fatalf("dry-run stdout is not JSON: %v\n%s", err, stdout.String())
+			}
+			if got["ok"] != true || got["dry_run"] != true {
+				t.Fatalf("unexpected dry-run envelope: %#v", got)
+			}
+			data := got["data"].(map[string]interface{})
+			api := data["api"].([]interface{})
+			call := api[0].(map[string]interface{})
+			if call["url"] != tt.wantInURL {
+				t.Errorf("url = %q, want %q\nstdout:\n%s", call["url"], tt.wantInURL, stdout.String())
 			}
 		})
 	}
 }
 
+func TestServiceMethod_DryRunWithJq(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, driveSpec(), driveMethod("GET", nil), "get", "files", nil)
+	cmd.SetArgs([]string{
+		"--params", `{"file_token":"boxcn123abc"}`,
+		"--dry-run",
+		"--jq", ".data.api[0].url",
+	})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got, want := strings.TrimSpace(stdout.String()), "/open-apis/drive/v1/files/boxcn123abc/copy"; got != want {
+		t.Fatalf("jq output = %q, want %q", got, want)
+	}
+}
+
 func TestServiceMethod_PathParamRejectsTraversal(t *testing.T) {
 	tests := []struct {
 		name      string
@@ -318,8 +344,12 @@ func TestServiceMethod_PaginationParamSkippedWithPageAll(t *testing.T) {
 	if err != nil {
 		t.Fatalf("expected no error with --page-all skipping page_size, got: %v", err)
 	}
-	if !strings.Contains(stdout.String(), "Dry Run") {
-		t.Error("expected dry-run output")
+	var got map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("dry-run stdout is not JSON: %v\n%s", err, stdout.String())
+	}
+	if got["dry_run"] != true {
+		t.Fatalf("dry_run = %#v, want true", got["dry_run"])
 	}
 }
 
@@ -1081,11 +1111,23 @@ func TestServiceMethod_FileUpload_DryRun(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	out := stdout.String()
-	if !strings.Contains(out, "image") {
-		t.Errorf("expected dry-run output to mention file field, got: %s", out)
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("dry-run stdout is not JSON: %v\n%s", err, out)
 	}
-	if !strings.Contains(out, "Dry Run") {
-		t.Errorf("expected dry-run header, got: %s", out)
+	if env["dry_run"] != true {
+		t.Fatalf("dry_run = %#v, want true", env["dry_run"])
+	}
+	data := env["data"].(map[string]interface{})
+	api := data["api"].([]interface{})
+	call := api[0].(map[string]interface{})
+	body := call["body"].(map[string]interface{})
+	file := body["file"].(map[string]interface{})
+	if file["field"] != "image" || file["path"] != tmpFile {
+		t.Fatalf("unexpected file dry-run body: %#v", body)
+	}
+	if strings.Contains(out, "=== Dry Run ===") {
+		t.Fatalf("stdout should not contain dry-run banner: %s", out)
 	}
 }
 

internal/cmdutil/dryrun.go

@@ -8,15 +8,29 @@ import (
 	"fmt"
 	"io"
 	"net/url"
+	"regexp"
 	"sort"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/util"
 )
 
+var dryRunURLPlaceholderRE = regexp.MustCompile(`:([A-Za-z_][A-Za-z0-9_]*)`)
+
+// DryRunOutputOptions controls dry-run stdout/stderr rendering.
+type DryRunOutputOptions struct {
+	Format      string
+	JqExpr      string
+	CommandPath string
+	Identity    core.Identity
+	Out         io.Writer
+	ErrOut      io.Writer
+}
+
 // DryRunAPICall describes a single API call in dry-run output.
 type DryRunAPICall struct {
 	Desc   string                 `json:"desc,omitempty"`
@@ -26,12 +40,21 @@ type DryRunAPICall struct {
 	Body   interface{}            `json:"body,omitempty"`
 }
 
+// DryRunContext is the execution context shared by every dry-run preview:
+// which app would make the call and, when known, as which user. The identity
+// itself lives at the envelope top level, not here.
+type DryRunContext struct {
+	AppID      string `json:"app_id,omitempty"`
+	UserOpenID string `json:"user_open_id,omitempty"`
+}
+
 // DryRunAPI is the builder and result type for dry-run output.
 // URL templates use :param placeholders; Set stores actual values; MarshalJSON and Format resolve them.
 type DryRunAPI struct {
-	desc  string
-	calls []DryRunAPICall
-	extra map[string]interface{}
+	desc    string
+	calls   []DryRunAPICall
+	context *DryRunContext
+	extra   map[string]interface{}
 }
 
 func NewDryRunAPI() *DryRunAPI {
@@ -40,30 +63,22 @@ func NewDryRunAPI() *DryRunAPI {
 
 // --- HTTP method builders (add a call, return self for chaining) ---
 
-func (d *DryRunAPI) GET(url string) *DryRunAPI {
-	d.calls = append(d.calls, DryRunAPICall{Method: "GET", URL: url})
+// call appends a request with the method transcribed verbatim, so previews
+// never misreport what the real client would send.
+func (d *DryRunAPI) call(method, url string) *DryRunAPI {
+	d.calls = append(d.calls, DryRunAPICall{Method: method, URL: url})
 	return d
 }
 
-func (d *DryRunAPI) POST(url string) *DryRunAPI {
-	d.calls = append(d.calls, DryRunAPICall{Method: "POST", URL: url})
-	return d
-}
+func (d *DryRunAPI) GET(url string) *DryRunAPI { return d.call("GET", url) }
 
-func (d *DryRunAPI) PUT(url string) *DryRunAPI {
-	d.calls = append(d.calls, DryRunAPICall{Method: "PUT", URL: url})
-	return d
-}
+func (d *DryRunAPI) POST(url string) *DryRunAPI { return d.call("POST", url) }
 
-func (d *DryRunAPI) DELETE(url string) *DryRunAPI {
-	d.calls = append(d.calls, DryRunAPICall{Method: "DELETE", URL: url})
-	return d
-}
+func (d *DryRunAPI) PUT(url string) *DryRunAPI { return d.call("PUT", url) }
 
-func (d *DryRunAPI) PATCH(url string) *DryRunAPI {
-	d.calls = append(d.calls, DryRunAPICall{Method: "PATCH", URL: url})
-	return d
-}
+func (d *DryRunAPI) DELETE(url string) *DryRunAPI { return d.call("DELETE", url) }
+
+func (d *DryRunAPI) PATCH(url string) *DryRunAPI { return d.call("PATCH", url) }
 
 // Body sets the request body on the last added call.
 func (d *DryRunAPI) Body(body interface{}) *DryRunAPI {
@@ -98,12 +113,26 @@ func (d *DryRunAPI) Set(key string, value interface{}) *DryRunAPI {
 	return d
 }
 
+// Context records the calling app/user under data.context; empty values are
+// omitted, and a fully empty context is not emitted at all.
+func (d *DryRunAPI) Context(appID, userOpenID string) *DryRunAPI {
+	if appID == "" && userOpenID == "" {
+		return d
+	}
+	d.context = &DryRunContext{AppID: appID, UserOpenID: userOpenID}
+	return d
+}
+
 // resolveURL replaces :key placeholders in url with path-escaped values from extra.
 func (d *DryRunAPI) resolveURL(rawURL string) string {
-	for k, v := range d.extra {
-		rawURL = strings.ReplaceAll(rawURL, ":"+k, url.PathEscape(fmt.Sprintf("%v", v)))
-	}
-	return rawURL
+	return dryRunURLPlaceholderRE.ReplaceAllStringFunc(rawURL, func(token string) string {
+		name := token[1:]
+		value, ok := d.extra[name]
+		if !ok {
+			return token
+		}
+		return url.PathEscape(fmt.Sprintf("%v", value))
+	})
 }
 
 // MarshalJSON serializes as {"description": "...", "api": [...calls with resolved URLs], ...extra}.
@@ -118,13 +147,17 @@ func (d *DryRunAPI) MarshalJSON() ([]byte, error) {
 			Body:   c.Body,
 		}
 	}
-	m := make(map[string]interface{}, len(d.extra)+2)
+	m := make(map[string]interface{}, len(d.extra)+3)
+	for k, v := range d.extra {
+		m[k] = v
+	}
+	// Typed fields win over same-named extra keys.
 	if d.desc != "" {
 		m["description"] = d.desc
 	}
 	m["api"] = resolved
-	for k, v := range d.extra {
-		m[k] = v
+	if d.context != nil {
+		m["context"] = d.context
 	}
 	return json.Marshal(m)
 }
@@ -154,11 +187,7 @@ func (d *DryRunAPI) Format() string {
 			u += "?" + encodeParams(c.Params)
 		}
 
-		method := c.Method
-		if method == "" {
-			method = "GET"
-		}
-		b.WriteString(method)
+		b.WriteString(c.Method)
 		b.WriteByte(' ')
 		b.WriteString(u)
 		b.WriteByte('\n')
@@ -215,83 +244,74 @@ func encodeParams(params map[string]interface{}) string {
 	return vals.Encode()
 }
 
-// PrintDryRunWithFile outputs a dry-run summary for file upload requests.
-// Instead of serializing the Formdata body, it shows file metadata.
-func PrintDryRunWithFile(w io.Writer, request client.RawApiRequest, config *core.CliConfig, format, fileField, filePath string, formFields any) error {
-	dr := NewDryRunAPI()
-	switch request.Method {
-	case "POST":
-		dr.POST(request.URL)
-	case "PUT":
-		dr.PUT(request.URL)
-	case "PATCH":
-		dr.PATCH(request.URL)
-	case "DELETE":
-		dr.DELETE(request.URL)
-	default:
-		dr.GET(request.URL)
-	}
+// buildDryRunPreview assembles the shared preview skeleton: HTTP method, URL,
+// query params, and the app/user context common to every dry-run.
+func buildDryRunPreview(request client.RawApiRequest, config *core.CliConfig) *DryRunAPI {
+	dr := NewDryRunAPI().call(request.Method, request.URL)
 	if len(request.Params) > 0 {
 		dr.Params(request.Params)
 	}
-	filePathDisplay := filePath
+	// Identity is reported at the envelope top level, not duplicated here.
+	dr.Context(config.AppID, config.UserOpenId)
+	return dr
+}
+
+// PrintDryRunWithFile outputs a dry-run summary for file upload requests.
+// Instead of serializing the Formdata body, it shows file metadata.
+func PrintDryRunWithFile(request client.RawApiRequest, config *core.CliConfig, opts DryRunOutputOptions, file FileUploadMeta) error {
+	dr := buildDryRunPreview(request, config)
+	filePathDisplay := file.FilePath
 	if filePathDisplay == "" {
 		filePathDisplay = "<stdin>"
 	}
 	fileInfo := map[string]any{
-		"file": map[string]string{"field": fileField, "path": filePathDisplay},
+		"file": map[string]string{"field": file.FieldName, "path": filePathDisplay},
 	}
-	if formFields != nil {
-		fileInfo["form_fields"] = formFields
+	if file.FormFields != nil {
+		fileInfo["form_fields"] = file.FormFields
 	}
 	fileInfo["options"] = []string{"WithFileUpload"}
 	dr.Body(fileInfo)
-	dr.Set("as", string(request.As))
-	dr.Set("appId", config.AppID)
-	if config.UserOpenId != "" {
-		dr.Set("userOpenId", config.UserOpenId)
-	}
-	fmt.Fprintln(w, "=== Dry Run ===")
-	if format == "pretty" {
-		fmt.Fprint(w, dr.Format())
-	} else {
-		output.PrintJson(w, dr)
-	}
-	return nil
+	return WriteDryRun(dr, opts)
 }
 
 // PrintDryRun outputs a standardised dry-run summary using DryRunAPI.
 // When format is "pretty", outputs human-readable text; otherwise JSON.
-func PrintDryRun(w io.Writer, request client.RawApiRequest, config *core.CliConfig, format string) error {
-	dr := NewDryRunAPI()
-	switch request.Method {
-	case "POST":
-		dr.POST(request.URL)
-	case "PUT":
-		dr.PUT(request.URL)
-	case "PATCH":
-		dr.PATCH(request.URL)
-	case "DELETE":
-		dr.DELETE(request.URL)
-	default:
-		dr.GET(request.URL)
-	}
-	if len(request.Params) > 0 {
-		dr.Params(request.Params)
-	}
+func PrintDryRun(request client.RawApiRequest, config *core.CliConfig, opts DryRunOutputOptions) error {
+	dr := buildDryRunPreview(request, config)
 	if !util.IsNil(request.Data) {
 		dr.Body(request.Data)
 	}
-	dr.Set("as", string(request.As))
-	dr.Set("appId", config.AppID)
-	if config.UserOpenId != "" {
-		dr.Set("userOpenId", config.UserOpenId)
-	}
-	fmt.Fprintln(w, "=== Dry Run ===")
-	if format == "pretty" {
-		fmt.Fprint(w, dr.Format())
-	} else {
-		output.PrintJson(w, dr)
-	}
-	return nil
+	return WriteDryRun(dr, opts)
+}
+
+// WriteDryRun emits a DryRunAPI using the shared dry-run output contract.
+// Identity may be empty; the envelope omits it rather than guessing.
+func WriteDryRun(dr *DryRunAPI, opts DryRunOutputOptions) error {
+	if dr == nil {
+		return errs.NewInternalError(errs.SubtypeUnknown, "dry-run produced no request preview")
+	}
+	// The JqExpr guard is defensive: every entry point already rejects --jq
+	// combined with --format pretty via output.ValidateJqFlags.
+	if opts.Format == "pretty" && opts.JqExpr == "" {
+		// A nil ErrOut only skips the banner decoration (mirroring
+		// WriteSuccessEnvelope's warning path); the payload write to Out
+		// must fail loudly rather than be silently discarded.
+		if opts.ErrOut != nil {
+			fmt.Fprintln(opts.ErrOut, "=== Dry Run ===")
+		}
+		// stdout carries its own marker so logs that drop stderr still show
+		// this was a preview, not an executed request.
+		fmt.Fprintln(opts.Out, "# dry-run: request not sent")
+		fmt.Fprint(opts.Out, dr.Format())
+		return nil
+	}
+	return output.WriteSuccessEnvelope(dr, output.SuccessEnvelopeOptions{
+		CommandPath: opts.CommandPath,
+		Identity:    string(opts.Identity),
+		DryRun:      true,
+		JqExpr:      opts.JqExpr,
+		Out:         opts.Out,
+		ErrOut:      opts.ErrOut,
+	})
 }

internal/cmdutil/dryrun_test.go

@@ -6,9 +6,12 @@ package cmdutil
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
+	"io"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/core"
 )
@@ -66,11 +69,31 @@ func TestDryRunAPI_ResolveURL(t *testing.T) {
 	}
 }
 
+func TestDryRunAPI_ResolveURLMatchesFullPlaceholderOnly(t *testing.T) {
+	dr := NewDryRunAPI().
+		GET("/open-apis/task/v2/tasks/:assignee_id").
+		Set("assignee", "ou_bot")
+
+	text := dr.Format()
+	if strings.Contains(text, "ou_bot_id") {
+		t.Fatalf("prefix placeholder key corrupted longer token: %s", text)
+	}
+	if !strings.Contains(text, ":assignee_id") {
+		t.Fatalf("missing unresolved placeholder, got: %s", text)
+	}
+
+	dr.Set("assignee_id", "ou_abc/123")
+	text = dr.Format()
+	if !strings.Contains(text, "/open-apis/task/v2/tasks/ou_abc%2F123") {
+		t.Fatalf("expected full placeholder replacement with path escaping, got: %s", text)
+	}
+}
+
 func TestDryRunAPI_MarshalJSON(t *testing.T) {
 	dr := NewDryRunAPI().
 		Desc("test api").
 		GET("/open-apis/test").
-		Set("as", "user")
+		Set("note", "audit")
 
 	data, err := json.Marshal(dr)
 	if err != nil {
@@ -83,8 +106,8 @@ func TestDryRunAPI_MarshalJSON(t *testing.T) {
 	if m["description"] != "test api" {
 		t.Errorf("expected description, got: %v", m["description"])
 	}
-	if m["as"] != "user" {
-		t.Errorf("expected as=user, got: %v", m["as"])
+	if m["note"] != "audit" {
+		t.Errorf("expected note=audit, got: %v", m["note"])
 	}
 	api, ok := m["api"].([]interface{})
 	if !ok || len(api) != 1 {
@@ -123,31 +146,67 @@ func TestDryRunAPI_ExtraFieldsOnly(t *testing.T) {
 
 func TestPrintDryRun_JSON(t *testing.T) {
 	var buf bytes.Buffer
-	err := PrintDryRun(&buf, client.RawApiRequest{
+	var errBuf bytes.Buffer
+	err := PrintDryRun(client.RawApiRequest{
 		Method: "GET",
 		URL:    "/open-apis/test",
 		As:     "user",
-	}, &core.CliConfig{AppID: "app123"}, "json")
+	}, &core.CliConfig{AppID: "app123"}, DryRunOutputOptions{
+		Format:      "json",
+		CommandPath: "lark-cli api",
+		Identity:    core.AsUser,
+		Out:         &buf,
+		ErrOut:      &errBuf,
+	})
 	if err != nil {
 		t.Fatalf("PrintDryRun failed: %v", err)
 	}
 	out := buf.String()
-	if !strings.Contains(out, "=== Dry Run ===") {
-		t.Errorf("expected header, got: %s", out)
+	if strings.Contains(out, "=== Dry Run ===") {
+		t.Fatalf("JSON stdout must not contain banner, got: %s", out)
 	}
-	if !strings.Contains(out, "app123") {
-		t.Errorf("expected appId in output, got: %s", out)
+	var env map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &env); err != nil {
+		t.Fatalf("dry-run stdout is not JSON: %v\n%s", err, out)
+	}
+	if env["ok"] != true || env["identity"] != "user" || env["dry_run"] != true {
+		t.Fatalf("unexpected envelope: %#v", env)
+	}
+	data, ok := env["data"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("unexpected data: %#v", env["data"])
+	}
+	dctx, ok := data["context"].(map[string]interface{})
+	if !ok || dctx["app_id"] != "app123" {
+		t.Fatalf("unexpected data.context: %#v", data["context"])
+	}
+	if _, exists := data["as"]; exists {
+		t.Fatalf("data.as must not appear; identity lives at the envelope top level: %#v", data)
+	}
+	api, ok := data["api"].([]interface{})
+	if !ok || len(api) != 1 {
+		t.Fatalf("api = %#v, want one call", data["api"])
+	}
+	call, ok := api[0].(map[string]interface{})
+	if !ok || call["url"] != "/open-apis/test" {
+		t.Fatalf("api[0] = %#v", api[0])
 	}
 }
 
 func TestPrintDryRun_Pretty(t *testing.T) {
 	var buf bytes.Buffer
-	err := PrintDryRun(&buf, client.RawApiRequest{
+	var errBuf bytes.Buffer
+	err := PrintDryRun(client.RawApiRequest{
 		Method: "POST",
 		URL:    "/open-apis/test",
 		Data:   map[string]interface{}{"key": "val"},
 		As:     "bot",
-	}, &core.CliConfig{AppID: "app456"}, "pretty")
+	}, &core.CliConfig{AppID: "app456"}, DryRunOutputOptions{
+		Format:   "pretty",
+		Identity: core.AsBot,
+		Out:      &buf,
+		ErrOut:   &errBuf,
+	})
 	if err != nil {
 		t.Fatalf("PrintDryRun failed: %v", err)
 	}
@@ -155,6 +214,136 @@ func TestPrintDryRun_Pretty(t *testing.T) {
 	if !strings.Contains(out, "POST /open-apis/test") {
 		t.Errorf("expected POST line in pretty output, got: %s", out)
 	}
+	if !strings.HasPrefix(out, "# dry-run: request not sent\n") {
+		t.Fatalf("pretty stdout should start with the dry-run marker, got: %s", out)
+	}
+	if strings.Contains(out, "=== Dry Run ===") {
+		t.Fatalf("pretty stdout must not contain banner, got: %s", out)
+	}
+	if !strings.Contains(errBuf.String(), "=== Dry Run ===") {
+		t.Fatalf("pretty stderr should contain banner, got: %s", errBuf.String())
+	}
+}
+
+func TestPrintDryRun_WithJqUsesEnvelope(t *testing.T) {
+	var buf bytes.Buffer
+	err := PrintDryRun(client.RawApiRequest{
+		Method: "GET",
+		URL:    "/open-apis/test",
+		As:     "bot",
+	}, &core.CliConfig{AppID: "app123"}, DryRunOutputOptions{
+		Format:   "json",
+		JqExpr:   ".data.api[0].url",
+		Identity: core.AsBot,
+		Out:      &buf,
+		ErrOut:   io.Discard,
+	})
+	if err != nil {
+		t.Fatalf("PrintDryRun failed: %v", err)
+	}
+	if got := strings.TrimSpace(buf.String()); got != "/open-apis/test" {
+		t.Fatalf("jq output = %q, want /open-apis/test", got)
+	}
+}
+
+func TestPrintDryRunWithFile_JSONEnvelope(t *testing.T) {
+	var buf bytes.Buffer
+	err := PrintDryRunWithFile(client.RawApiRequest{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_all",
+		As:     "bot",
+	}, &core.CliConfig{AppID: "app123", UserOpenId: "ou_tester"}, DryRunOutputOptions{
+		Format:   "json",
+		Identity: core.AsBot,
+		Out:      &buf,
+		ErrOut:   io.Discard,
+	}, FileUploadMeta{FieldName: "file", FilePath: "report.txt", FormFields: map[string]any{"parent": "fld"}})
+	if err != nil {
+		t.Fatalf("PrintDryRunWithFile failed: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &env); err != nil {
+		t.Fatalf("dry-run stdout is not JSON: %v\n%s", err, buf.String())
+	}
+	if env["dry_run"] != true {
+		t.Fatalf("dry_run = %#v, want true", env["dry_run"])
+	}
+	data := env["data"].(map[string]interface{})
+	api := data["api"].([]interface{})
+	call := api[0].(map[string]interface{})
+	body := call["body"].(map[string]interface{})
+	file := body["file"].(map[string]interface{})
+	if file["path"] != "report.txt" {
+		t.Fatalf("file body = %#v", body)
+	}
+	dctx, ok := data["context"].(map[string]interface{})
+	if !ok || dctx["app_id"] != "app123" || dctx["user_open_id"] != "ou_tester" {
+		t.Fatalf("unexpected data.context: %#v", data["context"])
+	}
+	for _, legacy := range []string{"as", "appId", "userOpenId"} {
+		if _, exists := data[legacy]; exists {
+			t.Fatalf("legacy key %q must not appear in data: %#v", legacy, data)
+		}
+	}
+}
+
+func TestPrintDryRun_MethodTranscribedVerbatim(t *testing.T) {
+	var buf bytes.Buffer
+	err := PrintDryRun(client.RawApiRequest{
+		Method: "OPTIONS",
+		URL:    "/open-apis/test",
+		As:     "bot",
+	}, &core.CliConfig{AppID: "app123"}, DryRunOutputOptions{
+		Format:   "json",
+		Identity: core.AsBot,
+		Out:      &buf,
+		ErrOut:   io.Discard,
+	})
+	if err != nil {
+		t.Fatalf("PrintDryRun failed: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &env); err != nil {
+		t.Fatalf("dry-run stdout is not JSON: %v\n%s", err, buf.String())
+	}
+	call := env["data"].(map[string]interface{})["api"].([]interface{})[0].(map[string]interface{})
+	if call["method"] != "OPTIONS" {
+		t.Fatalf("method = %#v, want OPTIONS transcribed verbatim (not coerced to GET)", call["method"])
+	}
+}
+
+func TestPrintDryRun_EmptyConfigOmitsContext(t *testing.T) {
+	var buf bytes.Buffer
+	err := PrintDryRun(client.RawApiRequest{
+		Method: "GET",
+		URL:    "/open-apis/test",
+	}, &core.CliConfig{}, DryRunOutputOptions{
+		Format: "json",
+		Out:    &buf,
+		ErrOut: io.Discard,
+	})
+	if err != nil {
+		t.Fatalf("PrintDryRun failed: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(buf.Bytes(), &env); err != nil {
+		t.Fatalf("dry-run stdout is not JSON: %v\n%s", err, buf.String())
+	}
+	data := env["data"].(map[string]interface{})
+	if _, exists := data["context"]; exists {
+		t.Fatalf("empty app/user context must be omitted entirely, got: %#v", data["context"])
+	}
+}
+
+func TestWriteDryRun_NilPreviewIsInternalError(t *testing.T) {
+	err := WriteDryRun(nil, DryRunOutputOptions{Format: "json", Out: io.Discard})
+	if err == nil {
+		t.Fatal("WriteDryRun(nil) should fail instead of emitting an empty preview")
+	}
+	var internal *errs.InternalError
+	if !errors.As(err, &internal) {
+		t.Fatalf("expected *errs.InternalError, got %T: %v", err, err)
+	}
 }
 
 func TestDryRunFormatValue(t *testing.T) {

internal/output/envelope.go

@@ -7,6 +7,7 @@ package output
 type Envelope struct {
 	OK                 bool                   `json:"ok"`
 	Identity           string                 `json:"identity,omitempty"`
+	DryRun             bool                   `json:"dry_run,omitempty"`
 	Data               interface{}            `json:"data,omitempty"`
 	Meta               *Meta                  `json:"meta,omitempty"`
 	ContentSafetyAlert interface{}            `json:"_content_safety_alert,omitempty"`

internal/output/envelope_success.go

@@ -9,6 +9,7 @@ import "io"
 type SuccessEnvelopeOptions struct {
 	CommandPath string
 	Identity    string
+	DryRun      bool
 	JqExpr      string
 	Out         io.Writer
 	ErrOut      io.Writer
@@ -41,6 +42,7 @@ func WriteSuccessEnvelope(data interface{}, opts SuccessEnvelopeOptions) error {
 	env := Envelope{
 		OK:       true,
 		Identity: opts.Identity,
+		DryRun:   opts.DryRun,
 		Data:     data,
 		Notice:   GetNotice(),
 	}

internal/output/envelope_success_test.go

@@ -104,6 +104,47 @@ func TestWriteSuccessEnvelope_JqUsesEnvelope(t *testing.T) {
 	}
 }
 
+func TestWriteSuccessEnvelope_DryRunMarker(t *testing.T) {
+	var out strings.Builder
+
+	err := WriteSuccessEnvelope(map[string]interface{}{"api": []interface{}{}}, SuccessEnvelopeOptions{
+		Identity: "bot",
+		DryRun:   true,
+		Out:      &out,
+	})
+	if err != nil {
+		t.Fatalf("WriteSuccessEnvelope() error = %v", err)
+	}
+
+	var env map[string]interface{}
+	if err := json.Unmarshal([]byte(out.String()), &env); err != nil {
+		t.Fatalf("invalid JSON output: %v\n%s", err, out.String())
+	}
+	if env["ok"] != true || env["identity"] != "bot" || env["dry_run"] != true {
+		t.Fatalf("unexpected dry-run envelope: %#v", env)
+	}
+	if _, ok := env["data"].(map[string]interface{}); !ok {
+		t.Fatalf("data = %#v, want object", env["data"])
+	}
+}
+
+func TestWriteSuccessEnvelope_DryRunJqUsesEnvelope(t *testing.T) {
+	var out strings.Builder
+
+	err := WriteSuccessEnvelope(map[string]interface{}{"api": []interface{}{}}, SuccessEnvelopeOptions{
+		Identity: "bot",
+		DryRun:   true,
+		JqExpr:   ".dry_run",
+		Out:      &out,
+	})
+	if err != nil {
+		t.Fatalf("WriteSuccessEnvelope() error = %v", err)
+	}
+	if strings.TrimSpace(out.String()) != "true" {
+		t.Fatalf("jq output = %q, want true", out.String())
+	}
+}
+
 func TestWriteSuccessEnvelope_JqWarnsWhenSafetyAlertFiltered(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "warn")
 	extcs.Register(&mockProvider{

internal/qualitygate/rules/dryrun.go

@@ -878,16 +878,23 @@ func extractDryRunJSON(raw []byte) (facts.DryRunRequest, int, error) {
 	var firstErr error
 	for start >= 0 {
 		var preview struct {
-			API []facts.DryRunRequest `json:"api"`
+			API  []facts.DryRunRequest `json:"api"`
+			Data struct {
+				API []facts.DryRunRequest `json:"api"`
+			} `json:"data"`
 		}
 		dec := json.NewDecoder(bytes.NewReader(raw[start:]))
 		if err := dec.Decode(&preview); err == nil {
-			if len(preview.API) == 0 {
+			api := preview.API
+			if len(api) == 0 {
+				api = preview.Data.API
+			}
+			if len(api) == 0 {
 				if firstErr == nil {
 					firstErr = errNoDryRunAPI
 				}
 			} else {
-				return preview.API[0], len(preview.API), nil
+				return api[0], len(api), nil
 			}
 		} else if firstErr == nil {
 			firstErr = err

internal/qualitygate/rules/dryrun_test.go

@@ -33,6 +33,17 @@ func TestExtractDryRunJSONSkipsBanner(t *testing.T) {
 	}
 }
 
+func TestExtractDryRunJSONReadsSuccessEnvelope(t *testing.T) {
+	raw := `{"ok":true,"dry_run":true,"data":{"api":[{"method":"GET","url":"/open-apis/test"}]}}`
+	got, apiCallCount, err := extractDryRunJSON([]byte(raw))
+	if err != nil {
+		t.Fatalf("extractDryRunJSON() error = %v", err)
+	}
+	if got.Method != "GET" || got.URL != "/open-apis/test" || apiCallCount != 1 {
+		t.Fatalf("got request=%#v apiCallCount=%d, want enveloped GET and count 1", got, apiCallCount)
+	}
+}
+
 func TestExtractDryRunJSONSkipsBannerWithBraces(t *testing.T) {
 	raw := "banner {not json}\n{\"api\":[{\"method\":\"GET\",\"url\":\"/open-apis/test\"}]}\n"
 	got, apiCallCount, err := extractDryRunJSON([]byte(raw))

shortcuts/application/slash_command_delete_test.go

@@ -81,16 +81,19 @@ func TestSlashCommandDelete_ByNameDryRun(t *testing.T) {
 	if err != nil {
 		t.Fatalf("execute: %v", err)
 	}
-	var got struct {
-		Description string `json:"description"`
-		API         []struct {
-			Desc   string `json:"desc"`
-			Method string `json:"method"`
-		} `json:"api"`
+	var envlp struct {
+		Data struct {
+			Description string `json:"description"`
+			API         []struct {
+				Desc   string `json:"desc"`
+				Method string `json:"method"`
+			} `json:"api"`
+		} `json:"data"`
 	}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+	if err := json.Unmarshal(stdout.Bytes(), &envlp); err != nil {
 		t.Fatalf("json: %v", err)
 	}
+	got := envlp.Data
 	if !strings.Contains(got.Description, "HIGH-RISK") || strings.Contains(got.Description, "resolve command_id") {
 		t.Fatalf("top-level description must contain only the risk context: %q", got.Description)
 	}

shortcuts/application/slash_command_update_test.go

@@ -100,16 +100,19 @@ func TestSlashCommandUpdate_ByNameDryRunDescriptions(t *testing.T) {
 	if err != nil {
 		t.Fatalf("execute: %v", err)
 	}
-	var got struct {
-		Description string `json:"description"`
-		API         []struct {
-			Desc   string `json:"desc"`
-			Method string `json:"method"`
-		} `json:"api"`
+	var envlp struct {
+		Data struct {
+			Description string `json:"description"`
+			API         []struct {
+				Desc   string `json:"desc"`
+				Method string `json:"method"`
+			} `json:"api"`
+		} `json:"data"`
 	}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+	if err := json.Unmarshal(stdout.Bytes(), &envlp); err != nil {
 		t.Fatalf("json: %v", err)
 	}
+	got := envlp.Data
 	if strings.Contains(got.Description, "resolve command_id") {
 		t.Fatalf("resolve description must be attached to GET, not top-level: %q", got.Description)
 	}
@@ -128,15 +131,18 @@ func TestSlashCommandUpdate_ByIDDryRunEncodesTrimmedPathSegment(t *testing.T) {
 	if err != nil {
 		t.Fatalf("execute: %v", err)
 	}
-	var got struct {
-		API []struct {
-			Desc string `json:"desc"`
-			URL  string `json:"url"`
-		} `json:"api"`
+	var envlp struct {
+		Data struct {
+			API []struct {
+				Desc string `json:"desc"`
+				URL  string `json:"url"`
+			} `json:"api"`
+		} `json:"data"`
 	}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+	if err := json.Unmarshal(stdout.Bytes(), &envlp); err != nil {
 		t.Fatalf("json: %v", err)
 	}
+	got := envlp.Data
 	wantURL := slashCommandBasePath + "/id%2Fwith%20space%3Fx"
 	if len(got.API) != 1 || got.API[0].URL != wantURL || got.API[0].Desc == "" {
 		t.Fatalf("dry-run call = %#v, want encoded URL %q with description", got.API, wantURL)

shortcuts/apps/apps_analytics_test.go

@@ -23,19 +23,21 @@ func TestAppsAnalyticsList_DryRunUsesNanoseconds(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Method string                 `json:"method"`
+				URL    string                 `json:"url"`
+				Body   map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 	}
-	if env.API[0].Method != "POST" || env.API[0].URL != "/open-apis/spark/v1/apps/app_x/query_analytics_data" {
-		t.Fatalf("method/url = %s %s", env.API[0].Method, env.API[0].URL)
+	if env.Data.API[0].Method != "POST" || env.Data.API[0].URL != "/open-apis/spark/v1/apps/app_x/query_analytics_data" {
+		t.Fatalf("method/url = %s %s", env.Data.API[0].Method, env.Data.API[0].URL)
 	}
-	body := env.API[0].Body
+	body := env.Data.API[0].Body
 	if _, ok := body["start_timestamp_ns"]; !ok {
 		t.Fatalf("analytics dry-run missing start_timestamp_ns: %#v", body)
 	}
@@ -92,14 +94,16 @@ func TestAppsAnalyticsList_PageViewDesktopSeriesSetsDeviceFilter(t *testing.T) {
 				t.Fatalf("dry-run err=%v", err)
 			}
 			var env struct {
-				API []struct {
-					Body map[string]interface{} `json:"body"`
-				} `json:"api"`
+				Data struct {
+					API []struct {
+						Body map[string]interface{} `json:"body"`
+					} `json:"api"`
+				} `json:"data"`
 			}
 			if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
 				t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 			}
-			filter := env.API[0].Body["filter"].(map[string]interface{})
+			filter := env.Data.API[0].Body["filter"].(map[string]interface{})
 			deviceTypes := filter["device_types"].([]interface{})
 			if len(deviceTypes) != 1 || deviceTypes[0] != "desktop" {
 				t.Fatalf("device_types = %#v", deviceTypes)

shortcuts/apps/apps_automation_create.go

@@ -0,0 +1,253 @@
+// 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

@@ -0,0 +1,265 @@
+// 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

@@ -0,0 +1,38 @@
+// 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

@@ -0,0 +1,70 @@
+// 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

@@ -0,0 +1,73 @@
+// 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

@@ -0,0 +1,117 @@
+// 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

@@ -0,0 +1,159 @@
+// 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

@@ -0,0 +1,219 @@
+// 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

@@ -0,0 +1,23 @@
+// 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

@@ -0,0 +1,174 @@
+// 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

@@ -0,0 +1,385 @@
+// 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

@@ -0,0 +1,444 @@
+// 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

@@ -0,0 +1,131 @@
+// 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

@@ -0,0 +1,110 @@
+// 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_db_audit_test.go

@@ -101,14 +101,16 @@ func TestAppsDBAuditEnable_DryRunAndSuccess(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Method string                 `json:"method"`
+				URL    string                 `json:"url"`
+				Body   map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
-	a := env.API[0]
+	a := env.Data.API[0]
 	if a.Method != "POST" || a.URL != dbAuditSetURL || a.Body["enabled"] != true || a.Body["retention"] != "30d" || a.Body["table"] != "orders" {
 		t.Fatalf("dry-run = %s %s body=%v", a.Method, a.URL, a.Body)
 	}
@@ -136,13 +138,15 @@ func TestAppsDBAuditDisable_DryRunAndSuccess(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 	var env struct {
-		API []struct {
-			Body map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Body map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
-	if env.API[0].Body["enabled"] != false || env.API[0].Body["table"] != "orders" {
-		t.Fatalf("dry-run body=%v (want enabled:false)", env.API[0].Body)
+	if env.Data.API[0].Body["enabled"] != false || env.Data.API[0].Body["table"] != "orders" {
+		t.Fatalf("dry-run body=%v (want enabled:false)", env.Data.API[0].Body)
 	}
 
 	factory2, stdout2, reg := newAppsExecuteFactory(t)
@@ -178,14 +182,16 @@ func TestAppsDBAuditList_DryRunJoinsTables(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Method string                 `json:"method"`
+				URL    string                 `json:"url"`
+				Params map[string]interface{} `json:"params"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
-	a := env.API[0]
+	a := env.Data.API[0]
 	if a.Method != "GET" || a.URL != dbAuditListURL || a.Params["tables"] != "orders,users" {
 		t.Fatalf("dry-run = %s %s tables=%v", a.Method, a.URL, a.Params["tables"])
 	}

shortcuts/apps/apps_db_changelog_list_test.go

@@ -37,13 +37,7 @@ func TestAppsDBChangelogList_DryRunFiltersAndTimeNormalize(t *testing.T) {
 			"--change-id", "01J", "--since", "2026-01-01", "--page-size", "5", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	a := env.API[0]
 	if a.Method != "GET" || a.URL != dbChangelogURL {

shortcuts/apps/apps_db_data_export_test.go

@@ -71,13 +71,7 @@ func TestAppsDBDataExport_DryRunFormatFromOutput(t *testing.T) {
 		if err := runAppsShortcut(t, AppsDBDataExport, args, factory, stdout); err != nil {
 			t.Fatalf("dry-run err=%v", err)
 		}
-		var env struct {
-			API []struct {
-				Method string                 `json:"method"`
-				URL    string                 `json:"url"`
-				Params map[string]interface{} `json:"params"`
-			} `json:"api"`
-		}
+		var env dryRunAPIEnvelope
 		_ = json.Unmarshal([]byte(stdout.String()), &env)
 		a := env.API[0]
 		if a.Method != "GET" || a.URL != dbDataExportURL {

shortcuts/apps/apps_db_data_import_test.go

@@ -97,14 +97,7 @@ func TestAppsDBDataImport_DryRunMultipartShape(t *testing.T) {
 		[]string{"+db-data-import", "--app-id", "app_x", "--file", "orders.csv", "--environment", "dev", "--dry-run", "--yes", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	a := env.API[0]
 	if a.Method != "POST" || a.URL != dbDataImportURL {
@@ -131,12 +124,11 @@ func TestAppsDBDataImport_DryRunOmitsEnvWhenUnset(t *testing.T) {
 		[]string{"+db-data-import", "--app-id", "app_x", "--file", "orders.csv", "--dry-run", "--yes", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	if len(env.API) != 1 {
+		t.Fatalf("dry-run API calls = %d, want 1; stdout=%s", len(env.API), stdout.String())
+	}
 	p := env.API[0].Params
 	if _, ok := p["env"]; ok {
 		t.Fatalf("no --environment → env key must be omitted, got params=%v", p)
@@ -174,11 +166,7 @@ func TestAppsDBDataImport_TableDefaultsToFileBasename(t *testing.T) {
 		[]string{"+db-data-import", "--app-id", "app_x", "--file", "customers.json", "--dry-run", "--yes", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	if env.API[0].Params["table"] != "customers" {
 		t.Fatalf("expected table=customers (from file basename) in params, got %v", env.API[0].Params)

shortcuts/apps/apps_db_env_recovery_quota_test.go

@@ -30,13 +30,7 @@ func TestAppsDBEnvDiff_DryRunBody(t *testing.T) {
 		[]string{"+db-env-diff", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	a := env.API[0]
 	if a.Method != "POST" || a.URL != dbEnvMigrateURL || a.Body["dry_run"] != true {
@@ -91,11 +85,7 @@ func TestAppsDBEnvMigrate_DryRunBody(t *testing.T) {
 		[]string{"+db-env-migrate", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Body map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	if env.API[0].Body["dry_run"] != false {
 		t.Fatalf("dry-run body=%v (want dry_run:false)", env.API[0].Body)
@@ -180,13 +170,7 @@ func TestAppsDBRecoveryDiff_DryRunNormalizesTarget(t *testing.T) {
 		[]string{"+db-recovery-diff", "--app-id", "app_x", "--target", "2026-04-15", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	a := env.API[0]
 	if a.Method != "POST" || a.URL != dbRecoveryURL || a.Body["dry_run"] != true {
@@ -331,14 +315,11 @@ func TestAppsDBQuotaGet_DryRunOmitsEnvWhenUnset(t *testing.T) {
 		[]string{"+db-quota-get", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
+	if len(env.API) != 1 {
+		t.Fatalf("dry-run API calls = %d, want 1; stdout=%s", len(env.API), stdout.String())
+	}
 	a := env.API[0]
 	if a.Method != "GET" || a.URL != dbQuotaURL {
 		t.Fatalf("dry-run = %s %s", a.Method, a.URL)

shortcuts/apps/apps_db_execute_test.go

@@ -165,14 +165,7 @@ func TestAppsDBExecute_DryRunSendsTransactionalFalse(t *testing.T) {
 		factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
 		t.Fatalf("decode: %v\n%s", err, stdout.String())
 	}
@@ -254,11 +247,7 @@ func TestAppsDBExecute_FileReadsSQLIntoBody(t *testing.T) {
 		factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Body map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
 		t.Fatalf("decode: %v\n%s", err, stdout.String())
 	}

shortcuts/apps/apps_db_table_get_test.go

@@ -79,11 +79,7 @@ func TestAppsDBTableGet_NonPrettyFormatsOmitFormatQuery(t *testing.T) {
 			if err := runAppsShortcut(t, AppsDBTableGet, args, factory, stdout); err != nil {
 				t.Fatalf("dry-run err=%v", err)
 			}
-			var env struct {
-				API []struct {
-					Params map[string]interface{} `json:"params"`
-				} `json:"api"`
-			}
+			var env dryRunAPIEnvelope
 			if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
 				t.Fatalf("decode: %v", err)
 			}

shortcuts/apps/apps_db_table_list_test.go

@@ -165,13 +165,7 @@ func TestAppsDBTableList_DryRunSendsPaginationAndEnv(t *testing.T) {
 		factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 	}
@@ -196,11 +190,7 @@ func TestAppsDBTableList_DoesNotSendIncludeStatsQuery(t *testing.T) {
 		factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
 		t.Fatalf("decode: %v", err)
 	}

shortcuts/apps/apps_env_test.go

@@ -149,11 +149,7 @@ func TestAppsEnvVarList_DryRunIncludesScene(t *testing.T) {
 	}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var dryRun struct {
-		API []struct {
-			Body map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var dryRun dryRunAPIEnvelope
 	if err := json.Unmarshal(stdout.Bytes(), &dryRun); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 	}
@@ -228,11 +224,7 @@ func TestAppsEnvVarSet_OnlineDryRunDoesNotRequireYes(t *testing.T) {
 			t.Fatalf("dry-run missing %q: %s", want, got)
 		}
 	}
-	var dryRun struct {
-		API []struct {
-			Body map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var dryRun dryRunAPIEnvelope
 	if err := json.Unmarshal([]byte(got), &dryRun); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, got)
 	}
@@ -353,13 +345,7 @@ func TestAppsEnvVarDelete_OnlineDryRunDoesNotRequireYes(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 
-	var dryRun struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var dryRun dryRunAPIEnvelope
 	got := stdout.String()
 	if err := json.Unmarshal([]byte(got), &dryRun); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, got)

shortcuts/apps/apps_file_delete_test.go

@@ -48,13 +48,7 @@ func TestAppsFileDelete_DryRunSendsPaths(t *testing.T) {
 		[]string{"+file-delete", "--app-id", "app_x", "--path", "/a.png", "--path", "/b.png", "--yes", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	a := env.API[0]
 	if a.Method != "POST" || a.URL != fileDeleteURL {

shortcuts/apps/apps_file_download_test.go

@@ -41,12 +41,7 @@ func TestAppsFileDownload_DryRunSignsFirst(t *testing.T) {
 		[]string{"+file-download", "--app-id", "app_x", "--path", "/x.png", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string `json:"method"`
-			URL    string `json:"url"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	if env.API[0].Method != "POST" || env.API[0].URL != fileSignURLForDownload {
 		t.Fatalf("dry-run = %s %s (want POST sign)", env.API[0].Method, env.API[0].URL)

shortcuts/apps/apps_file_get_test.go

@@ -46,13 +46,7 @@ func TestAppsFileGet_DryRunSendsPathQuery(t *testing.T) {
 		[]string{"+file-get", "--app-id", "app_x", "--path", "/x.png", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	if env.API[0].Method != "GET" || env.API[0].URL != fileGetURL || env.API[0].Params["path"] != "/x.png" {
 		t.Fatalf("dry-run = %s %s params=%v", env.API[0].Method, env.API[0].URL, env.API[0].Params)

shortcuts/apps/apps_file_list_test.go

@@ -95,13 +95,7 @@ func TestAppsFileList_DryRunSendsFiltersAndPagination(t *testing.T) {
 		factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 	}
@@ -139,11 +133,7 @@ func TestAppsFileList_DryRunOmitsEmptyFilters(t *testing.T) {
 		[]string{"+file-list", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	for _, banned := range []string{"name", "path", "type", "size_gt", "size_lt", "uploaded_since", "uploaded_until", "page_token"} {
 		if _, ok := env.API[0].Params[banned]; ok {

shortcuts/apps/apps_file_sign_test.go

@@ -22,13 +22,7 @@ func TestAppsFileSign_DryRunBody(t *testing.T) {
 		[]string{"+file-sign", "--app-id", "app_x", "--path", "/x.png", "--expires-in", "3600", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	a := env.API[0]
 	if a.Method != "POST" || a.URL != fileSignURL || a.Body["path"] != "/x.png" {

shortcuts/apps/apps_file_upload_test.go

@@ -76,13 +76,7 @@ func TestAppsFileUpload_DryRunPreUpload(t *testing.T) {
 		[]string{"+file-upload", "--app-id", "app_x", "--file", "logo.png", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	_ = json.Unmarshal([]byte(stdout.String()), &env)
 	a := env.API[0]
 	if a.Method != "POST" || a.URL != "/open-apis/spark/v1/apps/app_x/storage/file_pre_upload" {

shortcuts/apps/apps_init_test.go

@@ -737,15 +737,12 @@ func newAppsExecuteFactoryWithStderr(t *testing.T) (*cmdutil.Factory, *bytes.Buf
 }
 
 func TestAppsInit_Req1_Wording(t *testing.T) {
-	// The --dry-run output is a flat object (DryRunAPI marshals to top-level keys
-	// description/scaffold/api/...), NOT wrapped in {"data":...}, so parse stdout
-	// directly rather than via parseEnvelopeData.
 	factory, stdout, _ := newAppsExecuteFactoryWithStderr(t)
 	if err := runAppsShortcut(t, AppsInit, []string{"+init", "--app-id", "app_x", "--as", "user", "--dry-run"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var data map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &data); err != nil {
+	data, err := decodeDryRunDataMap(stdout.Bytes())
+	if err != nil {
 		t.Fatalf("decode dry-run output: %v (raw=%q)", err, stdout.String())
 	}
 	desc, _ := data["description"].(string)
@@ -1447,8 +1444,8 @@ func TestAppsInit_DryRun_DescribesEnvPull(t *testing.T) {
 	if err := runAppsShortcut(t, AppsInit, []string{"+init", "--app-id", "app_x", "--dir", dir, "--as", "user", "--dry-run"}, factory, stdout); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	var m map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &m); err != nil {
+	m, err := decodeDryRunDataMap(stdout.Bytes())
+	if err != nil {
 		t.Fatalf("decode dry-run: %v (raw=%q)", err, stdout.String())
 	}
 	ep, _ := m["env_pull"].(string)

shortcuts/apps/apps_logs_test.go

@@ -25,13 +25,7 @@ func TestAppsLogList_DryRunBuildsSearchLogsBody(t *testing.T) {
 	if err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 	}

shortcuts/apps/apps_metrics_test.go

@@ -39,13 +39,7 @@ func TestAppsMetricList_DryRunUsesSeconds(t *testing.T) {
 	if err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 	}
@@ -90,11 +84,7 @@ func TestAppsMetricList_AutoDownSampleByRange(t *testing.T) {
 			if err != nil {
 				t.Fatalf("dry-run err=%v", err)
 			}
-			var env struct {
-				API []struct {
-					Body map[string]interface{} `json:"body"`
-				} `json:"api"`
-			}
+			var env dryRunAPIEnvelope
 			if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
 				t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 			}

shortcuts/apps/apps_traces_test.go

@@ -24,13 +24,7 @@ func TestAppsTraceList_DryRunBuildsSearchTracesBody(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 	}
@@ -73,13 +67,7 @@ func TestAppsTraceGet_DryRunBuildsGetTraceBody(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-	}
+	var env dryRunAPIEnvelope
 	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
 		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
 	}

shortcuts/apps/automation_common.go

@@ -0,0 +1,453 @@
+// 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

@@ -0,0 +1,381 @@
+// 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

@@ -0,0 +1,57 @@
+// 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/dryrun_test.go

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+type dryRunAPICall struct {
+	Method string                 `json:"method"`
+	URL    string                 `json:"url"`
+	Params map[string]interface{} `json:"params"`
+	Body   map[string]interface{} `json:"body"`
+}
+
+type dryRunAPIEnvelope struct {
+	API []dryRunAPICall
+}
+
+func (e *dryRunAPIEnvelope) UnmarshalJSON(data []byte) error {
+	var raw struct {
+		Data struct {
+			API []dryRunAPICall `json:"api"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+	e.API = raw.Data.API
+	return nil
+}
+
+func decodeDryRunDataMap(data []byte) (map[string]interface{}, error) {
+	var raw struct {
+		Data map[string]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return nil, err
+	}
+	if raw.Data == nil {
+		return nil, fmt.Errorf("dry-run stdout is not a success envelope: %s", data)
+	}
+	return raw.Data, nil
+}

shortcuts/apps/git_credential_test.go

@@ -38,25 +38,27 @@ func TestAppsGitCredentialInitDryRunRequestShape(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 	var payload struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-			Body   interface{}            `json:"body"`
-		} `json:"api"`
-		Mode         string   `json:"mode"`
-		Action       string   `json:"action"`
-		AppID        string   `json:"app_id"`
-		MetadataFile string   `json:"metadata_file"`
-		LocalEffects []string `json:"local_effects"`
+		Data struct {
+			API []struct {
+				Method string                 `json:"method"`
+				URL    string                 `json:"url"`
+				Params map[string]interface{} `json:"params"`
+				Body   interface{}            `json:"body"`
+			} `json:"api"`
+			Mode         string   `json:"mode"`
+			Action       string   `json:"action"`
+			AppID        string   `json:"app_id"`
+			MetadataFile string   `json:"metadata_file"`
+			LocalEffects []string `json:"local_effects"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal([]byte(stdout.String()), &payload); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if len(payload.API) != 1 {
-		t.Fatalf("api len = %d, want 1", len(payload.API))
+	if len(payload.Data.API) != 1 {
+		t.Fatalf("api len = %d, want 1", len(payload.Data.API))
 	}
-	call := payload.API[0]
+	call := payload.Data.API[0]
 	if call.Method != "GET" {
 		t.Fatalf("method = %q, want GET", call.Method)
 	}
@@ -69,19 +71,19 @@ func TestAppsGitCredentialInitDryRunRequestShape(t *testing.T) {
 	if call.Body != nil {
 		t.Fatalf("body = %#v, want nil", call.Body)
 	}
-	if payload.Mode != "api-plus-local-setup" {
-		t.Fatalf("mode = %q", payload.Mode)
+	if payload.Data.Mode != "api-plus-local-setup" {
+		t.Fatalf("mode = %q", payload.Data.Mode)
 	}
-	if payload.Action != "initialize_local_git_credential" {
-		t.Fatalf("action = %q", payload.Action)
+	if payload.Data.Action != "initialize_local_git_credential" {
+		t.Fatalf("action = %q", payload.Data.Action)
 	}
-	if payload.AppID != "app_xxx" {
-		t.Fatalf("app_id = %q", payload.AppID)
+	if payload.Data.AppID != "app_xxx" {
+		t.Fatalf("app_id = %q", payload.Data.AppID)
 	}
-	if !strings.HasSuffix(payload.MetadataFile, filepath.Join("spark", "app_xxx", "git.json")) {
-		t.Fatalf("metadata_file = %q", payload.MetadataFile)
+	if !strings.HasSuffix(payload.Data.MetadataFile, filepath.Join("spark", "app_xxx", "git.json")) {
+		t.Fatalf("metadata_file = %q", payload.Data.MetadataFile)
 	}
-	assertStringSliceEqual(t, payload.LocalEffects, []string{
+	assertStringSliceEqual(t, payload.Data.LocalEffects, []string{
 		"save the issued PAT in the local system credential store",
 		"write app-scoped git credential metadata",
 		"configure a URL-scoped Git credential helper in global git config when possible",
@@ -96,32 +98,34 @@ func TestAppsGitCredentialListDryRunDescribesLocalReads(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 	var payload struct {
-		Description string        `json:"description"`
-		API         []interface{} `json:"api"`
-		Mode        string        `json:"mode"`
-		Action      string        `json:"action"`
-		StorageRoot string        `json:"storage_root"`
-		Reads       []string      `json:"reads"`
+		Data struct {
+			Description string        `json:"description"`
+			API         []interface{} `json:"api"`
+			Mode        string        `json:"mode"`
+			Action      string        `json:"action"`
+			StorageRoot string        `json:"storage_root"`
+			Reads       []string      `json:"reads"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal([]byte(stdout.String()), &payload); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if payload.Description != "Preview local Git credential listing (no API call, read-only local state)." {
-		t.Fatalf("description = %q", payload.Description)
+	if payload.Data.Description != "Preview local Git credential listing (no API call, read-only local state)." {
+		t.Fatalf("description = %q", payload.Data.Description)
 	}
-	if len(payload.API) != 0 {
-		t.Fatalf("api len = %d, want 0", len(payload.API))
+	if len(payload.Data.API) != 0 {
+		t.Fatalf("api len = %d, want 0", len(payload.Data.API))
 	}
-	if payload.Mode != "local-read-only" {
-		t.Fatalf("mode = %q", payload.Mode)
+	if payload.Data.Mode != "local-read-only" {
+		t.Fatalf("mode = %q", payload.Data.Mode)
 	}
-	if payload.Action != "list_local_git_credentials" {
-		t.Fatalf("action = %q", payload.Action)
+	if payload.Data.Action != "list_local_git_credentials" {
+		t.Fatalf("action = %q", payload.Data.Action)
 	}
-	if !strings.HasSuffix(payload.StorageRoot, filepath.Join("spark")) {
-		t.Fatalf("storage_root = %q", payload.StorageRoot)
+	if !strings.HasSuffix(payload.Data.StorageRoot, filepath.Join("spark")) {
+		t.Fatalf("storage_root = %q", payload.Data.StorageRoot)
 	}
-	assertStringSliceEqual(t, payload.Reads, []string{
+	assertStringSliceEqual(t, payload.Data.Reads, []string{
 		"scan app-scoped git credential metadata under the CLI config directory",
 		"derive per-app repository URLs and local credential status from local metadata",
 	})
@@ -135,36 +139,38 @@ func TestAppsGitCredentialRemoveDryRunDescribesLocalCleanup(t *testing.T) {
 		t.Fatalf("dry-run err=%v", err)
 	}
 	var payload struct {
-		Description  string        `json:"description"`
-		API          []interface{} `json:"api"`
-		Mode         string        `json:"mode"`
-		Action       string        `json:"action"`
-		AppID        string        `json:"app_id"`
-		MetadataFile string        `json:"metadata_file"`
-		Effects      []string      `json:"effects"`
+		Data struct {
+			Description  string        `json:"description"`
+			API          []interface{} `json:"api"`
+			Mode         string        `json:"mode"`
+			Action       string        `json:"action"`
+			AppID        string        `json:"app_id"`
+			MetadataFile string        `json:"metadata_file"`
+			Effects      []string      `json:"effects"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal([]byte(stdout.String()), &payload); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if payload.Description != "Preview local Git credential cleanup (no API call; would clean up local-only state)." {
-		t.Fatalf("description = %q", payload.Description)
+	if payload.Data.Description != "Preview local Git credential cleanup (no API call; would clean up local-only state)." {
+		t.Fatalf("description = %q", payload.Data.Description)
 	}
-	if len(payload.API) != 0 {
-		t.Fatalf("api len = %d, want 0", len(payload.API))
+	if len(payload.Data.API) != 0 {
+		t.Fatalf("api len = %d, want 0", len(payload.Data.API))
 	}
-	if payload.Mode != "local-cleanup-only" {
-		t.Fatalf("mode = %q", payload.Mode)
+	if payload.Data.Mode != "local-cleanup-only" {
+		t.Fatalf("mode = %q", payload.Data.Mode)
 	}
-	if payload.Action != "remove_local_git_credential" {
-		t.Fatalf("action = %q", payload.Action)
+	if payload.Data.Action != "remove_local_git_credential" {
+		t.Fatalf("action = %q", payload.Data.Action)
 	}
-	if payload.AppID != "app_xxx" {
-		t.Fatalf("app_id = %q", payload.AppID)
+	if payload.Data.AppID != "app_xxx" {
+		t.Fatalf("app_id = %q", payload.Data.AppID)
 	}
-	if !strings.HasSuffix(payload.MetadataFile, filepath.Join("spark", "app_xxx", "git.json")) {
-		t.Fatalf("metadata_file = %q", payload.MetadataFile)
+	if !strings.HasSuffix(payload.Data.MetadataFile, filepath.Join("spark", "app_xxx", "git.json")) {
+		t.Fatalf("metadata_file = %q", payload.Data.MetadataFile)
 	}
-	assertStringSliceEqual(t, payload.Effects, []string{
+	assertStringSliceEqual(t, payload.Data.Effects, []string{
 		"read app-scoped git credential metadata",
 		"remove the saved PAT from the local system credential store",
 		"remove the app-scoped Git helper from global git config when present",

shortcuts/apps/shortcuts.go

@@ -76,6 +76,13 @@ 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,11 +20,12 @@ 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）= 63。
-func TestAppsShortcuts_Returns64(t *testing.T) {
+//   - 3 plugin（install/uninstall/list）
+//   - 6 automation（list/get/create/update/enable/disable）= 70。
+func TestAppsShortcuts_Returns70(t *testing.T) {
 	got := Shortcuts()
-	if len(got) != 64 {
-		t.Fatalf("Shortcuts() returned %d entries, want 64", len(got))
+	if len(got) != 70 {
+		t.Fatalf("Shortcuts() returned %d entries, want 70", len(got))
 	}
 }
 

shortcuts/common/runner.go

@@ -1153,14 +1153,19 @@ func handleShortcutDryRun(f *cmdutil.Factory, rctx *RuntimeContext, s *Shortcut)
 		return ValidationErrorf("--dry-run is not supported for %s %s", s.Service, s.Command).
 			WithParam("--dry-run")
 	}
-	fmt.Fprintln(f.IOStreams.ErrOut, "=== Dry Run ===")
 	dryResult := s.DryRun(rctx.ctx, rctx)
-	if rctx.Format == "pretty" {
-		fmt.Fprint(f.IOStreams.Out, dryResult.Format())
-	} else {
-		output.PrintJson(f.IOStreams.Out, dryResult)
+	if dryResult != nil {
+		// Same data.context contract as the service/api dry-run paths.
+		dryResult.Context(rctx.Config.AppID, rctx.UserOpenId())
 	}
-	return nil
+	return cmdutil.WriteDryRun(dryResult, cmdutil.DryRunOutputOptions{
+		Format:      rctx.Format,
+		JqExpr:      rctx.JqExpr,
+		CommandPath: rctx.Cmd.CommandPath(),
+		Identity:    rctx.As(),
+		Out:         f.IOStreams.Out,
+		ErrOut:      f.IOStreams.ErrOut,
+	})
 }
 
 // rejectPositionalArgs returns a cobra.PositionalArgs that rejects any

shortcuts/common/runner_jq_test.go

@@ -6,6 +6,7 @@ package common
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"io"
 	"strings"
 	"testing"
@@ -229,6 +230,75 @@ func TestRunShortcut_JqRuntimeError_PropagatesError(t *testing.T) {
 	}
 }
 
+func TestRunShortcut_DryRunJSONUsesEnvelope(t *testing.T) {
+	s := &Shortcut{
+		Service:   "test",
+		Command:   "test-shortcut",
+		AuthTypes: []string{"bot"},
+		DryRun: func(ctx context.Context, rctx *RuntimeContext) *cmdutil.DryRunAPI {
+			return cmdutil.NewDryRunAPI().GET("/open-apis/test")
+		},
+		Execute: func(ctx context.Context, rctx *RuntimeContext) error {
+			t.Fatal("Execute should not run in dry-run")
+			return nil
+		},
+	}
+	f := newTestFactory()
+	cmd := newTestShortcutCmd(s, f)
+	cmd.Flags().Set("dry-run", "true")
+	cmd.Flags().Set("as", "bot")
+
+	if err := runShortcut(cmd, f, s, false); err != nil {
+		t.Fatalf("runShortcut() error = %v", err)
+	}
+	stdout := f.IOStreams.Out.(*bytes.Buffer)
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("dry-run stdout is not JSON: %v\n%s", err, stdout.String())
+	}
+	if env["ok"] != true || env["identity"] != "bot" || env["dry_run"] != true {
+		t.Fatalf("unexpected dry-run envelope: %#v", env)
+	}
+	data := env["data"].(map[string]interface{})
+	api := data["api"].([]interface{})
+	call := api[0].(map[string]interface{})
+	if call["url"] != "/open-apis/test" {
+		t.Fatalf("api[0] = %#v", call)
+	}
+	dctx, ok := data["context"].(map[string]interface{})
+	if !ok || dctx["app_id"] != "test" {
+		t.Fatalf("runner must inject data.context like the service/api paths, got: %#v", data["context"])
+	}
+}
+
+func TestRunShortcut_DryRunWithJq(t *testing.T) {
+	s := &Shortcut{
+		Service:   "test",
+		Command:   "test-shortcut",
+		AuthTypes: []string{"bot"},
+		DryRun: func(ctx context.Context, rctx *RuntimeContext) *cmdutil.DryRunAPI {
+			return cmdutil.NewDryRunAPI().GET("/open-apis/test")
+		},
+		Execute: func(ctx context.Context, rctx *RuntimeContext) error {
+			t.Fatal("Execute should not run in dry-run")
+			return nil
+		},
+	}
+	f := newTestFactory()
+	cmd := newTestShortcutCmd(s, f)
+	cmd.Flags().Set("dry-run", "true")
+	cmd.Flags().Set("jq", ".dry_run")
+	cmd.Flags().Set("as", "bot")
+
+	if err := runShortcut(cmd, f, s, false); err != nil {
+		t.Fatalf("runShortcut() error = %v", err)
+	}
+	stdout := f.IOStreams.Out.(*bytes.Buffer)
+	if got := strings.TrimSpace(stdout.String()); got != "true" {
+		t.Fatalf("jq output = %q, want true", got)
+	}
+}
+
 func TestRuntimeContext_Out_WithoutJq_NormalOutput(t *testing.T) {
 	rctx, stdout, _ := newJqTestContext("", "")
 

shortcuts/drive/drive_add_comment_test.go

@@ -45,6 +45,16 @@ func decodeJSONMap(t *testing.T, raw string) map[string]interface{} {
 	return data
 }
 
+func dryRunDataMap(t *testing.T, raw string) map[string]interface{} {
+	t.Helper()
+	out := decodeJSONMap(t, raw)
+	data, ok := out["data"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("dry-run data is %T, want map[string]interface{}\nstdout:\n%s", out["data"], raw)
+	}
+	return data
+}
+
 func mustMapValue(t *testing.T, value interface{}, path string) map[string]interface{} {
 	t.Helper()
 
@@ -1628,8 +1638,8 @@ func TestDryRunSlidesDirectURL(t *testing.T) {
 	if !strings.Contains(stdout.String(), "slide block comment") {
 		t.Fatalf("dry-run output missing slide block comment: %s", stdout.String())
 	}
-	out := decodeJSONMap(t, stdout.String())
-	api := mustSliceValue(t, out["api"], "api")
+	out := dryRunDataMap(t, stdout.String())
+	api := mustSliceValue(t, out["api"], "data.api")
 	call := mustMapValue(t, api[0], "api[0]")
 	body := mustMapValue(t, call["body"], "api[0].body")
 	anchor := mustMapValue(t, body["anchor"], "api[0].body.anchor")
@@ -1656,8 +1666,8 @@ func TestDryRunBaseDirectURL(t *testing.T) {
 	if !strings.Contains(stdout.String(), "record-local comment") {
 		t.Fatalf("dry-run output missing record-local comment: %s", stdout.String())
 	}
-	out := decodeJSONMap(t, stdout.String())
-	api := mustSliceValue(t, out["api"], "api")
+	out := dryRunDataMap(t, stdout.String())
+	api := mustSliceValue(t, out["api"], "data.api")
 	call := mustMapValue(t, api[0], "api[0]")
 	body := mustMapValue(t, call["body"], "api[0].body")
 	anchor := mustMapValue(t, body["anchor"], "api[0].body.anchor")
@@ -1699,8 +1709,8 @@ func TestDryRunWikiResolvesToSlides(t *testing.T) {
 	if !strings.Contains(stdout.String(), "slide block comment") {
 		t.Fatalf("dry-run output missing slide block comment: %s", stdout.String())
 	}
-	out := decodeJSONMap(t, stdout.String())
-	api := mustSliceValue(t, out["api"], "api")
+	out := dryRunDataMap(t, stdout.String())
+	api := mustSliceValue(t, out["api"], "data.api")
 	call := mustMapValue(t, api[0], "api[0]")
 	body := mustMapValue(t, call["body"], "api[0].body")
 	anchor := mustMapValue(t, body["anchor"], "api[0].body.anchor")
@@ -1736,8 +1746,8 @@ func TestDryRunWikiSlidesInvalidBlockIDSurfaces(t *testing.T) {
 	if !strings.Contains(stdout.String(), "slide --block-id must be") || !strings.Contains(stdout.String(), "shape_2") {
 		t.Fatalf("dry-run output missing block-id format error: %s", stdout.String())
 	}
-	out := decodeJSONMap(t, stdout.String())
-	api := mustSliceValue(t, out["api"], "api")
+	out := dryRunDataMap(t, stdout.String())
+	api := mustSliceValue(t, out["api"], "data.api")
 	if len(api) != 0 {
 		t.Fatalf("dry-run should not preview API calls with malformed block-id: %s", stdout.String())
 	}
@@ -1821,8 +1831,8 @@ func TestDryRunFileDirectURL(t *testing.T) {
 	if !strings.Contains(stdout.String(), "verify supported file metadata") {
 		t.Fatalf("dry-run output missing supported file metadata verification step: %s", stdout.String())
 	}
-	out := decodeJSONMap(t, stdout.String())
-	api := mustSliceValue(t, out["api"], "api")
+	out := dryRunDataMap(t, stdout.String())
+	api := mustSliceValue(t, out["api"], "data.api")
 	if len(api) != 2 {
 		t.Fatalf("expected 2 dry-run api calls, got %d\nstdout:\n%s", len(api), stdout.String())
 	}

shortcuts/drive/drive_list_comments.go

@@ -6,6 +6,7 @@ package drive
 import (
 	"context"
 	"fmt"
+	"net/url"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
@@ -19,7 +20,7 @@ const (
 	driveListCommentsDefaultScope        = "all"
 )
 
-var driveListCommentsTypes = []string{"doc", "docx", "sheet", "file", "slides", "bitable", "base", "wiki"}
+var driveListCommentsTypes = []string{"doc", "docx", "sheet", "file", "slides", "bitable", "base", "apps", "wiki"}
 
 type driveListCommentsRef struct {
 	Token      string
@@ -43,17 +44,17 @@ type driveListCommentsSpec struct {
 }
 
 // DriveListComments lists document comments through the Drive comments API,
-// while accepting Wiki URLs/tokens and resolving them to the underlying object.
+// while accepting Wiki URLs/tokens and Miaoda /page/<token> apps URLs.
 var DriveListComments = common.Shortcut{
 	Service:           "drive",
 	Command:           "+list-comments",
-	Description:       "List comments for doc/docx/sheet/file/slides/base(bitable), with URL parsing and Wiki token unwrapping",
+	Description:       "List comments for doc/docx/sheet/file/slides/base(bitable)/apps, with URL parsing and Wiki token unwrapping",
 	Risk:              "read",
 	Scopes:            []string{"docs:document.comment:read"},
 	ConditionalScopes: []string{"wiki:node:retrieve"},
 	AuthTypes:         []string{"user", "bot"},
 	Flags: []common.Flag{
-		{Name: "url", Desc: "recommended: Lark/Feishu document URL (doc/docx/sheet/file/slides/base/bitable/wiki); Wiki URLs are unwrapped automatically"},
+		{Name: "url", Desc: "recommended: Lark/Feishu document URL (doc/docx/sheet/file/slides/base/bitable/apps/wiki); apps Miaoda URLs use /page/<token>; Wiki URLs are unwrapped automatically"},
 		{Name: "token", Desc: "document token, Wiki token, or document URL; bare tokens require --type"},
 		{Name: "type", Desc: "document type for bare --token; optional for URLs but must match the URL type when provided", Enum: driveListCommentsTypes},
 		{Name: "solved-status", Default: driveListCommentsDefaultSolvedStatus, Desc: "comment solved filter: false=unresolved, true=solved, all=all comments", Enum: []string{"false", "true", "all"}},
@@ -165,29 +166,60 @@ func resolveDriveListCommentsInput(urlInput, tokenInput, explicitType string) (d
 		if !driveListCommentsTypeSupported(refType) {
 			return driveListCommentsRef{}, errs.NewValidationError(
 				errs.SubtypeInvalidArgument,
-				"unsupported %s resource type %q; comments list supports doc, docx, sheet, file, slides, bitable/base, and wiki",
+				"unsupported %s resource type %q; comments list supports doc, docx, sheet, file, slides, bitable/base, apps, and wiki",
 				sourceFlag,
 				refType,
 			).WithParam(sourceFlag)
 		}
 		return driveListCommentsRef{Token: ref.Token, Type: refType, SourceFlag: sourceFlag}, nil
 	}
+	if token, ok := parseDriveListCommentsAppsURL(raw); ok {
+		const refType = "apps"
+		if inputType != "" && inputType != refType {
+			return driveListCommentsRef{}, errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"--type %q conflicts with URL path type %q; remove --type or use a matching value",
+				inputType,
+				refType,
+			).WithParam("--type")
+		}
+		return driveListCommentsRef{Token: token, Type: refType, SourceFlag: sourceFlag}, nil
+	}
 
 	if strings.Contains(raw, "://") {
-		return driveListCommentsRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported %s URL %q: use a recognized Lark document URL or pass a bare token with --type", sourceFlag, raw).WithParam(sourceFlag)
+		return driveListCommentsRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported %s URL %q: use a recognized Lark document URL, a Miaoda /page/<token> URL, or pass a bare token with --type", sourceFlag, raw).WithParam(sourceFlag)
 	}
 	if strings.ContainsAny(raw, "/?#") {
 		return driveListCommentsRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid bare token %q: remove path/query fragments or pass a recognized Lark document URL", raw).WithParam(sourceFlag)
 	}
 	if inputType == "" {
-		return driveListCommentsRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--type is required when %s is a bare token (allowed: doc, docx, sheet, file, slides, bitable, base, wiki)", sourceFlag).WithParam("--type")
+		return driveListCommentsRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--type is required when %s is a bare token (allowed: doc, docx, sheet, file, slides, bitable, base, apps, wiki)", sourceFlag).WithParam("--type")
 	}
 	if !driveListCommentsTypeSupported(inputType) {
-		return driveListCommentsRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --type %q; allowed: doc, docx, sheet, file, slides, bitable, base, wiki", inputType).WithParam("--type")
+		return driveListCommentsRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --type %q; allowed: doc, docx, sheet, file, slides, bitable, base, apps, wiki", inputType).WithParam("--type")
 	}
 	return driveListCommentsRef{Token: raw, Type: inputType, SourceFlag: sourceFlag}, nil
 }
 
+func parseDriveListCommentsAppsURL(rawURL string) (string, bool) {
+	u, err := url.Parse(strings.TrimSpace(rawURL))
+	if err != nil || u.Scheme == "" || u.Host == "" {
+		return "", false
+	}
+
+	path := strings.Trim(u.Path, "/")
+	parts := strings.Split(path, "/")
+	if len(parts) < 2 || parts[0] != "page" {
+		return "", false
+	}
+
+	token := strings.TrimSpace(parts[1])
+	if token == "" {
+		return "", false
+	}
+	return token, true
+}
+
 func normalizeDriveListCommentsType(docType string) string {
 	switch strings.TrimSpace(docType) {
 	case "base":
@@ -199,7 +231,7 @@ func normalizeDriveListCommentsType(docType string) string {
 
 func driveListCommentsTypeSupported(docType string) bool {
 	switch normalizeDriveListCommentsType(docType) {
-	case "doc", "docx", "sheet", "file", "slides", "bitable", "wiki":
+	case "doc", "docx", "sheet", "file", "slides", "bitable", "apps", "wiki":
 		return true
 	default:
 		return false
@@ -231,7 +263,7 @@ func resolveDriveListCommentsTarget(ctx context.Context, runtime *common.Runtime
 	if !driveListCommentsTypeSupported(objType) || objType == "wiki" {
 		return driveListCommentsTarget{}, errs.NewValidationError(
 			errs.SubtypeInvalidArgument,
-			"wiki resolved to %q, but comments list only supports doc, docx, sheet, file, slides, and bitable",
+			"wiki resolved to %q, but comments list only supports doc, docx, sheet, file, slides, bitable, and apps",
 			objType,
 		).WithParam(ref.SourceFlag)
 	}

shortcuts/drive/drive_list_comments_test.go

@@ -46,6 +46,32 @@ func TestResolveDriveListCommentsInput(t *testing.T) {
 			wantResource: "wikiResource",
 			wantType:     "wiki",
 		},
+		{
+			name:         "bare apps token",
+			rawInput:     "appsResource",
+			docType:      "apps",
+			wantResource: "appsResource",
+			wantType:     "apps",
+		},
+		{
+			name:         "miaoda page url",
+			urlInput:     "https://bytedance.feishu.cn/page/appsResource/?from=home",
+			wantResource: "appsResource",
+			wantType:     "apps",
+		},
+		{
+			name:         "token flag also accepts miaoda page url",
+			rawInput:     "https://bytedance.feishu.cn/page/appsResource/",
+			wantResource: "appsResource",
+			wantType:     "apps",
+		},
+		{
+			name:      "miaoda page url type conflict",
+			urlInput:  "https://bytedance.feishu.cn/page/appsResource/",
+			docType:   "docx",
+			wantErr:   "conflicts",
+			wantParam: "--type",
+		},
 		{
 			name:      "url and token mutually exclusive",
 			urlInput:  "https://example.larksuite.com/docx/docxResource",
@@ -72,6 +98,19 @@ func TestResolveDriveListCommentsInput(t *testing.T) {
 			wantErr:   "unsupported",
 			wantParam: "--url",
 		},
+		{
+			name:      "unsupported miaoda url path",
+			urlInput:  "https://bytedance.feishu.cn/app/appsResource",
+			wantErr:   "Miaoda /page/<token>",
+			wantParam: "--url",
+		},
+		{
+			name:      "invalid bare token type",
+			rawInput:  "appsResource",
+			docType:   "folder",
+			wantErr:   "invalid --type",
+			wantParam: "--type",
+		},
 	}
 
 	for _, tt := range tests {
@@ -96,6 +135,50 @@ func TestResolveDriveListCommentsInput(t *testing.T) {
 	}
 }
 
+func TestParseDriveListCommentsAppsURL(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		rawURL    string
+		wantToken string
+		wantOK    bool
+	}{
+		{
+			name:      "page url",
+			rawURL:    "https://bytedance.feishu.cn/page/appsResource?from=home",
+			wantToken: "appsResource",
+			wantOK:    true,
+		},
+		{
+			name:   "bare token is not url",
+			rawURL: "appsResource",
+		},
+		{
+			name:   "non page path",
+			rawURL: "https://bytedance.feishu.cn/app/appsResource",
+		},
+		{
+			name:   "empty page token",
+			rawURL: "https://bytedance.feishu.cn/page/%20",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			gotToken, gotOK := parseDriveListCommentsAppsURL(tt.rawURL)
+			if gotOK != tt.wantOK {
+				t.Fatalf("ok = %v, want %v", gotOK, tt.wantOK)
+			}
+			if gotToken != tt.wantToken {
+				t.Fatalf("token = %q, want %q", gotToken, tt.wantToken)
+			}
+		})
+	}
+}
+
 func TestValidateDriveListCommentsSpec(t *testing.T) {
 	t.Parallel()
 
@@ -228,6 +311,14 @@ func TestBuildDriveListCommentsParams(t *testing.T) {
 	if _, ok := sheetParams["need_relation"]; ok {
 		t.Fatalf("need_relation should be ignored for non-docx: %#v", sheetParams)
 	}
+
+	appsParams := buildDriveListCommentsParams(allPartialSpec, "apps")
+	if got := appsParams["file_type"]; got != "apps" {
+		t.Fatalf("apps file_type = %#v, want apps", got)
+	}
+	if _, ok := appsParams["need_relation"]; ok {
+		t.Fatalf("need_relation should be ignored for apps: %#v", appsParams)
+	}
 }
 
 func TestDriveListCommentsExecuteDocx(t *testing.T) {
@@ -353,3 +444,84 @@ func TestDriveListCommentsExecuteWikiResolvesToDocx(t *testing.T) {
 		t.Fatalf("file_type = %q, want docx", got)
 	}
 }
+
+func TestDriveListCommentsExecuteWikiRejectsUnsupportedResolvedType(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "success",
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "folder",
+					"obj_token": "folderResource",
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveListComments, []string{
+		"+list-comments",
+		"--token", "wikiResource",
+		"--type", "wiki",
+		"--as", "user",
+	}, f, stdout)
+	if err == nil || !strings.Contains(err.Error(), "supports doc, docx, sheet, file, slides, bitable, and apps") {
+		t.Fatalf("expected unsupported resolved type error, got %v", err)
+	}
+	assertDriveListCommentsValidationError(t, err, "--token")
+}
+
+func TestDriveListCommentsExecuteAppsPageURL(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/files/appsResource/comments",
+		OnMatch: func(req *http.Request) {
+			query := req.URL.Query()
+			if got := query.Get("file_type"); got != "apps" {
+				t.Errorf("file_type = %q, want apps", got)
+			}
+			if got := query.Get("is_solved"); got != "false" {
+				t.Errorf("is_solved = %q, want false", got)
+			}
+			if got := query.Get("need_relation"); got != "" {
+				t.Errorf("need_relation = %q, want omitted for apps", got)
+			}
+		},
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "success",
+			"data": map[string]interface{}{
+				"items": []map[string]interface{}{
+					{"comment_id": "comment_apps_1", "is_solved": false},
+				},
+				"has_more": false,
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveListComments, []string{
+		"+list-comments",
+		"--url", "https://bytedance.feishu.cn/page/appsResource/",
+		"--need-relation",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := decodeJSONMap(t, stdout.String())
+	data := mustMapValue(t, out["data"], "data")
+	if got := mustStringField(t, data, "file_token", "data.file_token"); got != "appsResource" {
+		t.Fatalf("file_token = %q, want appsResource", got)
+	}
+	if got := mustStringField(t, data, "file_type", "data.file_type"); got != "apps" {
+		t.Fatalf("file_type = %q, want apps", got)
+	}
+	if got := data["count"]; got != float64(1) {
+		t.Fatalf("count = %#v, want 1", got)
+	}
+}

shortcuts/drive/drive_member_add_test.go

@@ -518,15 +518,17 @@ func TestDriveMemberAdd_PermDefaultsToView(t *testing.T) {
 	}
 
 	var got struct {
-		API []struct {
-			Body map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Body map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if got.API[0].Body["perm"] != "view" {
-		t.Fatalf("perm = %v, want view", got.API[0].Body["perm"])
+	if got.Data.API[0].Body["perm"] != "view" {
+		t.Fatalf("perm = %v, want view", got.Data.API[0].Body["perm"])
 	}
 }
 
@@ -625,18 +627,20 @@ func TestDriveMemberAdd_DryRunAcceptsAppID(t *testing.T) {
 	}
 
 	var got struct {
-		API []struct {
-			Body map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Body map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if got.API[0].Body["member_type"] != "appid" {
-		t.Fatalf("member_type = %v, want appid", got.API[0].Body["member_type"])
+	if got.Data.API[0].Body["member_type"] != "appid" {
+		t.Fatalf("member_type = %v, want appid", got.Data.API[0].Body["member_type"])
 	}
-	if _, ok := got.API[0].Body["type"]; ok {
-		t.Fatalf("type = %v, want omitted for appid", got.API[0].Body["type"])
+	if _, ok := got.Data.API[0].Body["type"]; ok {
+		t.Fatalf("type = %v, want omitted for appid", got.Data.API[0].Body["type"])
 	}
 }
 
@@ -660,15 +664,17 @@ func TestDriveMemberAdd_DryRunAcceptsWikiSpaceID(t *testing.T) {
 	}
 
 	var got struct {
-		API []struct {
-			Body map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Body map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if got.API[0].Body["member_type"] != "wikispaceid" || got.API[0].Body["type"] != "wiki_space_viewer" {
-		t.Fatalf("body = %#v, want wikispaceid + wiki_space_viewer", got.API[0].Body)
+	if got.Data.API[0].Body["member_type"] != "wikispaceid" || got.Data.API[0].Body["type"] != "wiki_space_viewer" {
+		t.Fatalf("body = %#v, want wikispaceid + wiki_space_viewer", got.Data.API[0].Body)
 	}
 }
 
@@ -792,20 +798,22 @@ func TestDriveMemberAdd_DryRunInfersTypeAndDefaultsWikiPermType(t *testing.T) {
 	}
 
 	var got struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Method string                 `json:"method"`
+				URL    string                 `json:"url"`
+				Params map[string]interface{} `json:"params"`
+				Body   map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if len(got.API) != 1 {
-		t.Fatalf("api count = %d, want 1; stdout=%s", len(got.API), stdout.String())
+	if len(got.Data.API) != 1 {
+		t.Fatalf("api count = %d, want 1; stdout=%s", len(got.Data.API), stdout.String())
 	}
-	api := got.API[0]
+	api := got.Data.API[0]
 	if api.Method != "POST" || api.URL != "/open-apis/drive/v1/permissions/wikTok/members" {
 		t.Fatalf("api = %#v", api)
 	}
@@ -836,19 +844,21 @@ func TestDriveMemberAdd_DryRunAcceptsUppercaseEnumsForDocx(t *testing.T) {
 	}
 
 	var got struct {
-		API []struct {
-			Params map[string]interface{} `json:"params"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Params map[string]interface{} `json:"params"`
+				Body   map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if got.API[0].Params["type"] != "docx" {
-		t.Fatalf("params.type = %v, want docx", got.API[0].Params["type"])
+	if got.Data.API[0].Params["type"] != "docx" {
+		t.Fatalf("params.type = %v, want docx", got.Data.API[0].Params["type"])
 	}
-	if got.API[0].Body["member_type"] != "openid" || got.API[0].Body["perm"] != "edit" {
-		t.Fatalf("body = %#v, want canonical lowercase enum values", got.API[0].Body)
+	if got.Data.API[0].Body["member_type"] != "openid" || got.Data.API[0].Body["perm"] != "edit" {
+		t.Fatalf("body = %#v, want canonical lowercase enum values", got.Data.API[0].Body)
 	}
 }
 
@@ -872,19 +882,21 @@ func TestDriveMemberAdd_DryRunAcceptsUppercaseWikiPermType(t *testing.T) {
 	}
 
 	var got struct {
-		API []struct {
-			Params map[string]interface{} `json:"params"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Params map[string]interface{} `json:"params"`
+				Body   map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if got.API[0].Params["type"] != "wiki" {
-		t.Fatalf("params.type = %v, want wiki", got.API[0].Params["type"])
+	if got.Data.API[0].Params["type"] != "wiki" {
+		t.Fatalf("params.type = %v, want wiki", got.Data.API[0].Params["type"])
 	}
-	if got.API[0].Body["member_type"] != "openid" || got.API[0].Body["perm"] != "edit" || got.API[0].Body["perm_type"] != "container" {
-		t.Fatalf("body = %#v, want canonical lowercase enum values", got.API[0].Body)
+	if got.Data.API[0].Body["member_type"] != "openid" || got.Data.API[0].Body["perm"] != "edit" || got.Data.API[0].Body["perm_type"] != "container" {
+		t.Fatalf("body = %#v, want canonical lowercase enum values", got.Data.API[0].Body)
 	}
 }
 
@@ -949,19 +961,21 @@ func TestDriveMemberAdd_DryRunBatch(t *testing.T) {
 	}
 
 	var got struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
+		Data struct {
+			API []struct {
+				Method string                 `json:"method"`
+				URL    string                 `json:"url"`
+				Body   map[string]interface{} `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
 	}
-	if len(got.API) != 1 {
-		t.Fatalf("api count = %d, want 1", len(got.API))
+	if len(got.Data.API) != 1 {
+		t.Fatalf("api count = %d, want 1", len(got.Data.API))
 	}
-	api := got.API[0]
+	api := got.Data.API[0]
 	if api.Method != "POST" || api.URL != "/open-apis/drive/v1/permissions/shtcnTok/members/batch_create" {
 		t.Fatalf("api = %#v", api)
 	}

shortcuts/minutes/minutes_apply_permission.go

@@ -0,0 +1,74 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// MinutesApplyPermission applies for view or edit permission on a minute.
+var MinutesApplyPermission = common.Shortcut{
+	Service:     "minutes",
+	Command:     "+apply-permission",
+	Description: "Apply for view or edit permission on a minute",
+	Risk:        "write",
+	Scopes:      []string{"minutes:permission:apply"},
+	AuthTypes:   []string{"user"},
+	Flags: []common.Flag{
+		{Name: "minute-token", Desc: "minute token", Required: true},
+		{Name: "perm", Desc: "permission to apply for", Required: true, Enum: []string{"view", "edit"}},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
+		if minuteToken == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-token is required").WithParam("--minute-token")
+		}
+		if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--minute-token")
+		}
+		perm := strings.TrimSpace(runtime.Str("perm"))
+		if perm == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--perm is required").WithParam("--perm")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
+		return common.NewDryRunAPI().
+			POST(minutesApplyPermissionPath(minuteToken)).
+			Body(minutesApplyPermissionBody(runtime))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
+		perm := strings.TrimSpace(runtime.Str("perm"))
+
+		_, err := runtime.CallAPITyped(http.MethodPost, minutesApplyPermissionPath(minuteToken), nil, map[string]interface{}{"perm": perm})
+		if err != nil {
+			return err
+		}
+
+		runtime.OutFormat(map[string]interface{}{
+			"minute_token": minuteToken,
+			"perm":         perm,
+		}, nil, nil)
+		return nil
+	},
+}
+
+func minutesApplyPermissionPath(minuteToken string) string {
+	return fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/permissions/apply", validate.EncodePathSegment(minuteToken))
+}
+
+func minutesApplyPermissionBody(runtime *common.RuntimeContext) map[string]interface{} {
+	return map[string]interface{}{
+		"perm": strings.TrimSpace(runtime.Str("perm")),
+	}
+}

shortcuts/minutes/minutes_apply_permission_test.go

@@ -0,0 +1,192 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/spf13/cobra"
+)
+
+const minutesApplyPermissionTestToken = "obcnexampleminute"
+
+func TestMinutesApplyPermission_Validate(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	tests := []struct {
+		name    string
+		args    []string
+		wantErr string
+	}{
+		{
+			name:    "missing minute token",
+			args:    []string{"+apply-permission", "--perm", "view", "--as", "user"},
+			wantErr: "required flag(s) \"minute-token\" not set",
+		},
+		{
+			name:    "missing perm",
+			args:    []string{"+apply-permission", "--minute-token", minutesApplyPermissionTestToken, "--as", "user"},
+			wantErr: "required flag(s) \"perm\" not set",
+		},
+		{
+			name:    "invalid perm",
+			args:    []string{"+apply-permission", "--minute-token", minutesApplyPermissionTestToken, "--perm", "full_access", "--as", "user"},
+			wantErr: "allowed: view, edit",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			parent := &cobra.Command{Use: "minutes"}
+			MinutesApplyPermission.Mount(parent, f)
+			parent.SetArgs(tt.args)
+			parent.SilenceErrors = true
+			parent.SilenceUsage = true
+			err := parent.Execute()
+			if err == nil {
+				t.Fatalf("expected error, got nil")
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("error should contain %q, got: %s", tt.wantErr, err.Error())
+			}
+		})
+	}
+}
+
+func TestMinutesApplyPermission_ValidateTypedMinuteToken(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	parent := &cobra.Command{Use: "minutes"}
+	MinutesApplyPermission.Mount(parent, f)
+	parent.SetArgs([]string{"+apply-permission", "--minute-token", "..", "--perm", "view", "--as", "user"})
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	err := parent.Execute()
+	if err == nil {
+		t.Fatalf("expected error, got nil")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("want *errs.ValidationError, got %T", err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("subtype=%q", ve.Subtype)
+	}
+	if ve.Param != "--minute-token" {
+		t.Errorf("param=%q", ve.Param)
+	}
+}
+
+func TestMinutesApplyPermission_ValidateTypedPerm(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	parent := &cobra.Command{Use: "minutes"}
+	MinutesApplyPermission.Mount(parent, f)
+	parent.SetArgs([]string{"+apply-permission", "--minute-token", minutesApplyPermissionTestToken, "--perm", "full_access", "--as", "user"})
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	err := parent.Execute()
+	if err == nil {
+		t.Fatalf("expected error, got nil")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("want *errs.ValidationError, got %T", err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("subtype=%q", ve.Subtype)
+	}
+	if ve.Param != "--perm" {
+		t.Errorf("param=%q", ve.Param)
+	}
+}
+
+func TestMinutesApplyPermission_DryRun(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	err := mountAndRun(t, MinutesApplyPermission, []string{
+		"+apply-permission",
+		"--minute-token", minutesApplyPermissionTestToken,
+		"--perm", "view",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, "POST") {
+		t.Errorf("expected POST method, got:\n%s", out)
+	}
+	if !strings.Contains(out, "/open-apis/minutes/v1/minutes/"+minutesApplyPermissionTestToken+"/permissions/apply") {
+		t.Errorf("expected apply-permission endpoint, got:\n%s", out)
+	}
+	if !strings.Contains(out, `"perm": "view"`) && !strings.Contains(out, `"perm":"view"`) {
+		t.Errorf("expected perm body, got:\n%s", out)
+	}
+}
+
+func TestMinutesApplyPermission_Execute(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	stub := &httpmock.Stub{
+		Method: http.MethodPost,
+		URL:    "/open-apis/minutes/v1/minutes/" + minutesApplyPermissionTestToken + "/permissions/apply",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, MinutesApplyPermission, []string{
+		"+apply-permission",
+		"--minute-token", minutesApplyPermissionTestToken,
+		"--perm", "edit",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var requestBody struct {
+		Perm string `json:"perm"`
+	}
+	if err := json.Unmarshal(stub.CapturedBody, &requestBody); err != nil {
+		t.Fatalf("unmarshal request body: %v", err)
+	}
+	if requestBody.Perm != "edit" {
+		t.Errorf("request perm = %q, want edit", requestBody.Perm)
+	}
+
+	var envelope struct {
+		Data struct {
+			MinuteToken string `json:"minute_token"`
+			Perm        string `json:"perm"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("unmarshal stdout: %v", err)
+	}
+	if envelope.Data.MinuteToken != minutesApplyPermissionTestToken {
+		t.Errorf("data.minute_token = %q, want %q", envelope.Data.MinuteToken, minutesApplyPermissionTestToken)
+	}
+	if envelope.Data.Perm != "edit" {
+		t.Errorf("data.perm = %q, want edit", envelope.Data.Perm)
+	}
+}

shortcuts/minutes/minutes_detail.go

@@ -70,7 +70,7 @@ func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minu
 		if isMinutesDetailProcessingError(err) {
 			markMinutesDetailProcessing(result, minuteToken, artifactFlags, "minute metadata is still being generated")
 		} else if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailNoReadPermissionCode {
-			result.Error = fmt.Sprintf("No read permission for minute %s. Ask the minute owner for minute file read permission", minuteToken)
+			result.Error = fmt.Sprintf("No read permission for minute %s. Ask the user before running: minutes +apply-permission --minute-token %s --perm view", minuteToken, minuteToken)
 		} else {
 			result.Error = fmt.Sprintf("failed to query minute: %v", err)
 		}

shortcuts/minutes/minutes_speaker_replace.go

@@ -135,7 +135,7 @@ func minutesSpeakerReplaceError(err error, minuteToken, sourceSpeaker string) er
 	switch p.Code {
 	case minutesSpeakerReplaceNoEditPermission:
 		p.Message = fmt.Sprintf("No edit permission for minute %q: cannot replace the transcript speaker.", minuteToken)
-		p.Hint = "Ask the minute owner for minute edit permission"
+		p.Hint = fmt.Sprintf("Ask the user before running: minutes +apply-permission --minute-token %s --perm edit", minuteToken)
 	case minutesSpeakerReplaceSpeakerNotFoundCode:
 		p.Subtype = errs.SubtypeNotFound
 		p.Message = fmt.Sprintf("Speaker not found in minute %q: source speaker %q does not match an existing speaker in the transcript.", minuteToken, sourceSpeaker)

shortcuts/minutes/minutes_speaker_replace_test.go

@@ -361,7 +361,7 @@ func TestMinutesSpeakerReplace_NoEditPermission(t *testing.T) {
 	if !strings.Contains(p.Message, minutesSpeakerReplaceTestToken) {
 		t.Errorf("message should include minute token, got: %s", p.Message)
 	}
-	if !strings.Contains(p.Hint, "edit permission") {
-		t.Errorf("hint should mention edit permission, got: %s", p.Hint)
+	if !strings.Contains(p.Hint, "+apply-permission") {
+		t.Errorf("hint should mention apply-permission, got: %s", p.Hint)
 	}
 }

shortcuts/minutes/minutes_summary_todo_test.go

@@ -400,8 +400,8 @@ func TestMinutesTodo_NoEditPermission(t *testing.T) {
 	if !strings.Contains(p.Message, minutesSummaryTodoTestToken) {
 		t.Errorf("message should include minute token, got: %s", p.Message)
 	}
-	if !strings.Contains(p.Hint, "edit permission") {
-		t.Errorf("hint should mention edit permission, got: %s", p.Hint)
+	if !strings.Contains(p.Hint, "+apply-permission") {
+		t.Errorf("hint should mention apply-permission, got: %s", p.Hint)
 	}
 }
 

shortcuts/minutes/minutes_todo.go

@@ -288,6 +288,6 @@ func minutesTodoError(err error, minuteToken string) error {
 	}
 	p.Subtype = errs.SubtypePermissionDenied
 	p.Message = fmt.Sprintf("No edit permission for minute %q: cannot update todos.", minuteToken)
-	p.Hint = "Ask the minute owner for minute edit permission"
+	p.Hint = fmt.Sprintf("Ask the user before running: minutes +apply-permission --minute-token %s --perm edit", minuteToken)
 	return err
 }

shortcuts/minutes/minutes_update.go

@@ -79,6 +79,6 @@ func minutesUpdateError(err error, minuteToken string) error {
 		return err
 	}
 	p.Message = fmt.Sprintf("No edit permission for minute %q: cannot update the title.", minuteToken)
-	p.Hint = "Ask the minute owner for minute edit permission"
+	p.Hint = fmt.Sprintf("Ask the user before running: minutes +apply-permission --minute-token %s --perm edit", minuteToken)
 	return err
 }

shortcuts/minutes/minutes_update_test.go

@@ -171,7 +171,7 @@ func TestMinutesUpdate_NoEditPermission(t *testing.T) {
 	if !strings.Contains(p.Message, minutesUpdateTestToken) {
 		t.Errorf("message should include minute token, got: %s", p.Message)
 	}
-	if !strings.Contains(p.Hint, "edit permission") {
-		t.Errorf("hint should mention edit permission, got: %s", p.Hint)
+	if !strings.Contains(p.Hint, "+apply-permission") {
+		t.Errorf("hint should mention apply-permission, got: %s", p.Hint)
 	}
 }

shortcuts/minutes/minutes_word_replace.go

@@ -139,7 +139,7 @@ func minutesWordReplaceError(err error, minuteToken string) error {
 	case minutesWordReplaceNoEditPermission:
 		p.Subtype = errs.SubtypePermissionDenied
 		p.Message = fmt.Sprintf("No edit permission for minute %q: cannot replace transcript words.", minuteToken)
-		p.Hint = "Ask the minute owner for minute edit permission"
+		p.Hint = fmt.Sprintf("Ask the user before running: minutes +apply-permission --minute-token %s --perm edit", minuteToken)
 	case minutesWordReplaceOthersEditing:
 		p.Subtype = errs.SubtypeConflict
 		p.Message = fmt.Sprintf("Minute %q transcript is being edited by someone else.", minuteToken)

shortcuts/minutes/shortcuts.go

@@ -12,6 +12,7 @@ func Shortcuts() []common.Shortcut {
 		MinutesDownload,
 		MinutesUpload,
 		MinutesUpdate,
+		MinutesApplyPermission,
 		MinutesSummary,
 		MinutesTodo,
 		MinutesSpeakerReplace,

shortcuts/sheets/data/flag-defs.json

@@ -51,6 +51,13 @@
         "type": "bool",
         "required": "optional",
         "desc": "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."
+      },
+      {
+        "name": "ai-only",
+        "kind": "own",
+        "type": "bool",
+        "required": "optional",
+        "desc": "Only verify AI formulas (the unified =AI(prompt, [range]) function that drives translation / classification / sentiment / extraction / summary / rewrite via natural language), skipping the 7 Excel-error scan of ordinary formulas. AI formulas compute asynchronously: small batches settle quickly, while a larger batch legitimately returns some pending (still computing) - re-check later."
       }
     ]
   },

shortcuts/sheets/flag_defs_gen.go

@@ -654,6 +654,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "range", Kind: "own", Type: "string_slice", Required: "optional", Desc: "Optional A1 ranges (e.g. `A1:Z200`); repeat or comma-separate for multiple ranges. Omit to scan each sheet's current_region."},
 			{Name: "max-locations", Kind: "own", Type: "int", Required: "optional", Desc: "Max locations / samples per error type; default 20.", Default: "20"},
 			{Name: "exit-on-error", Kind: "own", Type: "bool", Required: "optional", Desc: "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."},
+			{Name: "ai-only", Kind: "own", Type: "bool", Required: "optional", Desc: "Only verify AI formulas (the unified =AI(prompt, [range]) function that drives translation / classification / sentiment / extraction / summary / rewrite via natural language), skipping the 7 Excel-error scan of ordinary formulas. AI formulas compute asynchronously: small batches settle quickly, while a larger batch legitimately returns some pending (still computing) - re-check later."},
 		},
 	},
 	"+history-list": {

shortcuts/sheets/helpers_test.go

@@ -197,7 +197,7 @@ func TestSheetHelpersValidationMetadata(t *testing.T) {
 // api call's body. The dry-run output format is:
 //
 //	=== Dry Run ===
-//	{ "api": [{...}], ... }
+//	{ "ok": true, "dry_run": true, "data": { "api": [{...}], ... } }
 //
 // Tests use this to assert the One-OpenAPI wire body is constructed
 // correctly without exercising the real endpoint.
@@ -220,7 +220,7 @@ func parseDryRunAPI(t *testing.T, sc common.Shortcut, args []string) []interface
 		t.Fatalf("dry-run failed: %v\noutput=%s", err, out)
 	}
 	dryRun := decodeDryRunRaw(t, out)
-	calls, _ := dryRun["api"].([]interface{})
+	calls, _ := dryRunAPIEntries(dryRun)
 	return calls
 }
 
@@ -240,7 +240,7 @@ func decodeDryRunRaw(t *testing.T, out string) map[string]interface{} {
 func decodeDryRunFirstCall(t *testing.T, out string) map[string]interface{} {
 	t.Helper()
 	dryRun := decodeDryRunRaw(t, out)
-	calls, ok := dryRun["api"].([]interface{})
+	calls, ok := dryRunAPIEntries(dryRun)
 	if !ok || len(calls) == 0 {
 		t.Fatalf("dry-run api array empty or wrong shape: %#v", dryRun)
 	}
@@ -252,6 +252,15 @@ func decodeDryRunFirstCall(t *testing.T, out string) map[string]interface{} {
 	return body
 }
 
+func dryRunAPIEntries(dryRun map[string]interface{}) ([]interface{}, bool) {
+	if data, ok := dryRun["data"].(map[string]interface{}); ok {
+		calls, ok := data["api"].([]interface{})
+		return calls, ok
+	}
+	calls, ok := dryRun["api"].([]interface{})
+	return calls, ok
+}
+
 // decodeToolInput parses the JSON-string `input` field embedded in a
 // dry-run body whose tool_name matches `expected`. Returns the decoded
 // tool input map so tests can assert on specific input fields.

shortcuts/sheets/lark_sheet_formula_verify.go

@@ -27,7 +27,7 @@ import (
 var FormulaVerify = common.Shortcut{
 	Service:     "sheets",
 	Command:     "+formula-verify",
-	Description: "Scan formulas / cell errors and return a recalc.py-shaped status report (success / errors_found / partial).",
+	Description: "Scan formulas / cell errors and return a recalc.py-shaped status report (success / errors_found / partial). Use --ai-only to poll AI-formula compute status only.",
 	Risk:        "read",
 	Scopes:      []string{"sheets:spreadsheet:read"},
 	AuthTypes:   []string{"user", "bot"},
@@ -136,6 +136,15 @@ func formulaVerifyInput(runtime *common.RuntimeContext, token string) map[string
 	if runtime.Changed("max-locations") {
 		input["max_locations_per_error"] = runtime.Int("max-locations")
 	}
+	// ai_only routes verify_formula to the AI-formula-only branch (BE-1): the
+	// backend skips the ordinary 7-Excel-error worksheet scan and only reads AI
+	// formula compute status (the unified =AI(prompt, [range]) function) via the
+	// container-layer AIManager. AI formulas compute asynchronously, so this is a
+	// polling probe — one call returns current status, callers re-invoke until
+	// pending clears.
+	if runtime.Bool("ai-only") {
+		input["ai_only"] = true
+	}
 	return input
 }
 

shortcuts/sheets/lark_sheet_formula_verify_test.go

@@ -62,6 +62,23 @@ func TestFormulaVerify_DryRun(t *testing.T) {
 				"max_locations_per_error": float64(5),
 			},
 		},
+		{
+			name: "ai_only — AI-formula-only polling probe",
+			args: []string{"--url", testURL, "--ai-only"},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+				"ai_only":  true,
+			},
+		},
+		{
+			name: "ai_only coexists with range selector",
+			args: []string{"--url", testURL, "--ai-only", "--range", "A1:Z200"},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+				"ai_only":  true,
+				"ranges":   []interface{}{"A1:Z200"},
+			},
+		},
 	}
 
 	for _, tt := range tests {

shortcuts/sheets/lark_sheet_history_test.go

@@ -158,7 +158,7 @@ func dryRunFirstCallURL(t *testing.T, sc common.Shortcut, args []string) string
 		t.Fatalf("dry-run failed: %v\noutput=%s", err, out)
 	}
 	dryRun := decodeDryRunRaw(t, out)
-	calls, ok := dryRun["api"].([]interface{})
+	calls, ok := dryRunAPIEntries(dryRun)
 	if !ok || len(calls) == 0 {
 		t.Fatalf("dry-run api array empty or wrong shape: %#v", dryRun)
 	}

shortcuts/slides/slides_replace_pages_test.go

@@ -270,10 +270,11 @@ func TestReplacePagesDryRunPlansOnly(t *testing.T) {
 	if err := json.Unmarshal(stdout.Bytes(), &out); err != nil {
 		t.Fatalf("decode dry-run: %v\nraw=%s", err, stdout.String())
 	}
-	if out["xml_presentation_id"] != "pres_abc" {
-		t.Fatalf("xml_presentation_id = %v", out["xml_presentation_id"])
+	data, _ := out["data"].(map[string]interface{})
+	if data["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v", data["xml_presentation_id"])
 	}
-	plan, _ := out["plan"].([]interface{})
+	plan, _ := data["plan"].([]interface{})
 	if len(plan) != 1 {
 		t.Fatalf("plan len = %d, want 1", len(plan))
 	}
@@ -281,7 +282,7 @@ func TestReplacePagesDryRunPlansOnly(t *testing.T) {
 	if item["old_slide_id"] != "old2" || item["action"] != "create_before_then_delete_old" {
 		t.Fatalf("plan item = %#v", item)
 	}
-	api, _ := out["api"].([]interface{})
+	api, _ := data["api"].([]interface{})
 	if len(api) != 2 {
 		t.Fatalf("api len = %d, want create/delete plan", len(api))
 	}

shortcuts/slides/slides_screenshot.go

@@ -22,7 +22,10 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-const defaultSlidesScreenshotDir = ".lark-slides/screenshots"
+const (
+	defaultSlidesScreenshotDir = ".lark-slides/screenshots"
+	maxSlidesPerScreenshot     = 10
+)
 
 var unsafeScreenshotFileCharRegex = regexp.MustCompile(`[^A-Za-z0-9._-]+`)
 
@@ -32,7 +35,7 @@ var unsafeScreenshotFileCharRegex = regexp.MustCompile(`[^A-Za-z0-9._-]+`)
 var SlidesScreenshot = common.Shortcut{
 	Service:     "slides",
 	Command:     "+screenshot",
-	Description: "Save slide screenshots to local files without printing Base64 image data",
+	Description: "Save up to 10 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
@@ -42,8 +45,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)"},
-		{Name: "slide-number", Type: "int_array", Desc: "slide page number (repeat for multiple slides)"},
+		{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: "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"},
@@ -70,12 +73,17 @@ var SlidesScreenshot = common.Shortcut{
 					return err
 				}
 			}
-			if _, err := normalizeSlideNumbers(runtime.IntArray("slide-number")); err != nil {
+			slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
+			slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
+			if err != nil {
 				return err
 			}
-			if !hasSlideScreenshotSelector(runtime) {
+			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
+			}
 		}
 		if _, err := validateScreenshotOutputDir(runtime, runtime.Str("output-dir")); err != nil {
 			return err
@@ -98,6 +106,9 @@ 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()
@@ -145,6 +156,9 @@ 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 {
@@ -267,8 +281,12 @@ func normalizeSlideNumbers(values []int) ([]int, error) {
 	return out, nil
 }
 
-func hasSlideScreenshotSelector(runtime *common.RuntimeContext) bool {
-	return len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0
+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 slidesScreenshotFlagErrorf(format string, args ...interface{}) error {

shortcuts/slides/slides_screenshot_test.go

@@ -271,6 +271,37 @@ 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,12 +15,14 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// SlidesXMLGet fetches the full XML presentation content and writes it to a
-// local file, keeping the terminal output small for large decks.
+// 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.
 var SlidesXMLGet = common.Shortcut{
 	Service:     "slides",
 	Command:     "+xml-get",
-	Description: "Fetch full presentation XML and save it to a local file",
+	Description: "Fetch presentation XML or one slide XML",
 	Risk:        "read",
 	Scopes:      []string{"slides:presentation:read"},
 	// wiki:node:read is required only when --presentation is a wiki URL.
@@ -28,7 +30,10 @@ 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; existing file is overwritten", 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: "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"},
 	},
@@ -37,19 +42,33 @@ 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 strings.TrimSpace(runtime.Str("output")) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output cannot be empty").WithParam("--output")
+		if err := validateSlidesXMLGetSelector(runtime); err != nil {
+			return err
 		}
-		if _, err := runtime.ResolveSavePath(runtime.Str("output")); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output invalid: %v", err).WithParam("--output").WithCause(err)
+		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 runtime.Int("revision-id") < -1 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--revision-id must be -1 or a non-negative integer").WithParam("--revision-id")
+		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")
+			}
 		}
 		return nil
 	},
@@ -62,25 +81,39 @@ var SlidesXMLGet = common.Shortcut{
 		dry := common.NewDryRunAPI()
 		if ref.Kind == "wiki" {
 			presentationID = "<resolved_slides_token>"
-			dry.Desc("2-step orchestration: resolve wiki → fetch full presentation XML").
+			dry.Desc("2-step orchestration: resolve wiki → fetch 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 full presentation XML and save it to a local file")
+			dry.Desc("Fetch presentation XML")
 		}
 		params := map[string]interface{}{
 			"revision_id": runtime.Int("revision-id"),
 		}
-		if runtime.Bool("remove-attr-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") {
 			params["remove_attr_id"] = true
 		}
-		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")
+		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")
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		ref, err := parsePresentationRef(runtime.Str("presentation"))
@@ -92,53 +125,167 @@ var SlidesXMLGet = common.Shortcut{
 			return err
 		}
 
+		if err := validateSlidesXMLGetSelector(runtime); err != nil {
+			return err
+		}
 		params := map[string]interface{}{
 			"revision_id": runtime.Int("revision-id"),
 		}
-		if runtime.Bool("remove-attr-id") {
-			params["remove_attr_id"] = true
+
+		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
 		}
 		data, err := runtime.CallAPITyped(
 			"GET",
-			fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s", validate.EncodePathSegment(presentationID)),
+			fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(presentationID)),
 			params,
 			nil,
 		)
 		if err != nil {
-			return err
+			return "", nil, err
 		}
-
-		presentation := common.GetMap(data, "xml_presentation")
-		content := common.GetString(presentation, "content")
+		slide := common.GetMap(data, "slide")
+		content := common.GetString(slide, "content")
 		if content == "" {
-			return errs.NewInternalError(errs.SubtypeInvalidResponse, "slides xml get returned empty xml_presentation.content")
+			return "", nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "slides xml get returned empty slide.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)
+		slideOut := map[string]interface{}{
+			"content": content,
 		}
-		resolvedPath, err := runtime.ResolveSavePath(outputPath)
-		if err != nil {
-			return errs.NewInternalError(errs.SubtypeFileIO, "resolve saved XML path %s: %v", outputPath, err).WithCause(err)
+		actualSlideID := common.GetString(slide, "slide_id")
+		if actualSlideID == "" {
+			actualSlideID = slideID
+		}
+		if actualSlideID != "" {
+			slideOut["slide_id"] = actualSlideID
+		}
+		if slideNumber > 0 {
+			slideOut["slide_number"] = slideNumber
 		}
-
 		out := map[string]interface{}{
 			"xml_presentation_id": presentationID,
-			"path":                resolvedPath,
-			"size":                result.Size(),
-			"content_saved":       true,
+			"scope":               "slide",
+			"slide":               slideOut,
 		}
-		if revisionID := common.GetFloat(presentation, "revision_id"); revisionID > 0 {
+		if actualSlideID != "" {
+			out["slide_id"] = actualSlideID
+		}
+		if slideNumber > 0 {
+			out["slide_number"] = slideNumber
+		}
+		if revisionID := common.GetFloat(data, "revision_id"); revisionID > 0 {
 			out["revision_id"] = int(revisionID)
+			slideOut["revision_id"] = int(revisionID)
 		}
-		if runtime.Bool("remove-attr-id") {
-			out["remove_attr_id"] = true
-		}
-		runtime.Out(out, nil)
-		return nil
-	},
+		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)
+		}
+		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,6 +5,7 @@ package slides
 
 import (
 	"errors"
+	"fmt"
 	"net/http"
 	"net/url"
 	"os"
@@ -91,6 +92,226 @@ 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)
@@ -163,3 +384,134 @@ 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/task/task_upload_attachment_test.go

@@ -508,7 +508,8 @@ func TestUploadAttachmentTask_DryRun(t *testing.T) {
 			if err := json.Unmarshal([]byte(out), &dry); err != nil {
 				t.Fatalf("dry-run output is not JSON: %v\n%s", err, out)
 			}
-			calls, _ := dry["api"].([]interface{})
+			data, _ := dry["data"].(map[string]interface{})
+			calls, _ := data["api"].([]interface{})
 			if len(calls) != 1 {
 				t.Fatalf("expected 1 api call in dry-run, got %d: %v", len(calls), calls)
 			}

shortcuts/vc/vc_notes.go

@@ -68,7 +68,7 @@ func minutesReadError(err error, minuteToken string) error {
 		return err
 	}
 	p.Message = fmt.Sprintf("No read permission for minute %s: cannot query the minute.", minuteToken)
-	p.Hint = "Ask the minute owner for minute file read permission"
+	p.Hint = fmt.Sprintf("Ask the user before running: minutes +apply-permission --minute-token %s --perm view", minuteToken)
 	return err
 }
 

shortcuts/vc/vc_notes_test.go

@@ -1255,7 +1255,7 @@ func TestMinutesReadError_ProblemOf_EnrichesMessage(t *testing.T) {
 		t.Errorf("error message not enriched: %q", errMsg)
 	}
 	hint, _ := note["hint"].(string)
-	if !strings.Contains(hint, "minute file read permission") {
+	if !strings.Contains(hint, "+apply-permission") {
 		t.Errorf("hint not surfaced: %q", hint)
 	}
 }

skills/lark-apps/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-apps
 version: 1.0.0
-description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、HTML静态站点发布、本地全栈开发、云端生成迭代、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、线上日志、接口请求量、错误量、延迟、访问量、环境变量时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
+description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、HTML静态站点发布、本地全栈开发、云端生成迭代、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -44,6 +44,7 @@ lark-cli auth login --domain apps
 | 设置或查看运行时可见范围 | `+access-scope-set`, `+access-scope-get` | 对应 access-scope reference |
 | 云端 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,8 +80,8 @@ lark-cli auth login --domain apps
 
 ## 能力边界
 
-- lark-cli **不支持**配置应用的权限（应用内 RBAC、成员角色、协作者权限）/ 自动化。`+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限。
-- 用户要配置权限 / 自动化时，引导其使用开发态连接前往云端开发（妙搭 web）处理。
+- lark-cli **不支持**配置应用的权限（应用内 RBAC、成员角色、协作者权限）。`+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限。
+- 用户要配置权限时，引导其使用开发态链接前往云端开发（妙搭 web）处理。自动化触发器请用 `+automation-*`（见「意图路由」）。
 
 ## app_id 获取
 

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

@@ -0,0 +1,164 @@
+# 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-openapi-key.md

@@ -76,4 +76,4 @@ CLI 提供三种互斥的 scope 表达方式：
 ## 不在本 skill 范围
 
 - OpenAPI spec 全量导出、实时日志 tail、Webhook 消费、多鉴权方式：本期不支持。
-- 身份选择、权限不足处理（`permission_violations`→`console_url`）、exit-10 审批、通用"禁输出密钥"红线、高风险操作通用框架：见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不在此重复。
+- 身份选择、权限不足处理（`missing_scopes`→`console_url`）、exit-10 审批、通用"禁输出密钥"红线、高风险操作通用框架：见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不在此重复。

skills/lark-base/SKILL.md

@@ -85,7 +85,7 @@ metadata:
 ## 身份与权限降级
 
 - 默认显式使用 `--as user` 操作用户资源；只有用户明确要求应用身份时，才直接用 `--as bot`。
-- user 身份报 scope/授权不足，或错误中包含 `permission_violations` / `hint`，先转 `lark-shared` 做用户授权恢复，不要直接降级 bot。
+- user 身份报 scope/授权不足，或错误中包含 `missing_scopes` / `hint`，先转 `lark-shared` 做用户授权恢复，不要直接降级 bot。
 - user 身份报资源级无访问且无授权恢复提示时，才可用 `--as bot` 重试一次；bot 仍失败就停止重试并按权限错误处理。
 - `91403` 或明确不可访问错误不要循环换身份重试。
 - `+base-create` / `+base-copy` 若用 bot 身份执行，关注返回中的 `permission_grant`，并把用户是否可打开新 Base 告知用户。

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

@@ -98,21 +98,21 @@ lark-cli base +dashboard-block-get \
 
 ## 返回结构总览
 
-服务端响应外层仍然是标准 OpenAPI 包装：
+CLI 成功输出使用标准 `{ok, identity, data}` 信封：
 
 ```json
 {
-  "code": 0,
-  "msg": "success",
+  "ok": true,
+  "identity": "user",
   "data": {
-    "dimensions": [...],
-    "measures": [...],
-    "main_data": [...]
+    "dimensions": [],
+    "measures": [],
+    "main_data": []
   }
 }
 ```
 
-其中 `data` 就是 CLI 图表协议本体。不同图表类型的 `data` 结构略有不同：
+其中 `identity` 是本次调用实际使用的身份，`data` 是 CLI 图表协议本体。不同图表类型的 `data` 结构略有不同：
 
 | 图表类型 | 一定有 | 可能有 |
 |----------|--------|--------|

skills/lark-doc/references/lark-doc-xml-extended-blocks.md

@@ -15,6 +15,7 @@ OKR block 可用 XML 格式完整表达。创建前先参考 [`lark-okr`](../../
     <okr-progress>
       <p>O 进展</p>
       <checkbox done="true">事项</checkbox>
+      <ul><li>列表项内可包含 <a href="https://example.com">链接</a></li></ul>
     </okr-progress>
     <okr-key-result key-result-id="KEY_RESULT_ID" status="risk" percent="60" score="80">
       <p>KR 描述</p>
@@ -31,4 +32,4 @@ OKR block 可用 XML 格式完整表达。创建前先参考 [`lark-okr`](../../
 - `okr-objective` / `okr-key-result`
   - 可更新 `status`、`percent`、`score`；`percent` / `score` 取值 0-100，`status` 取值 `unset`/`normal`/`risk`/`extended`。
   - 不可更新 objective 和 key-result 内容描述。
-- `okr-progress` 承载进展内容，支持更新。支持内嵌 `<p>`、`<checkbox>`、`<grid>`、`<img>`。
+- `okr-progress` 承载进展内容，支持更新。直接子节点支持 `<p>`、`<checkbox>`、`<grid>`、`<img>`、`<source>`、`<ol>`、`<ul>`、`<h1>` 到 `<h9>`。

skills/lark-drive/SKILL.md

@@ -26,7 +26,8 @@ metadata:
 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、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。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
 - 用户要**搜文档 / 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`；具体使用方式先阅读 [`references/lark-drive-list-comments.md`](references/lark-drive-list-comments.md)。
+- 用户要**获取文档评论列表**时，优先使用 `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`。
 - 用户要**根据文档评论定位正文位置**，例如 根据评论 review 文档、根据评论内容回看文档、区分多处相同引用文本时，对于 docx 类型（`file_type=docx`）的文档支持通过 `drive +list-comments --need-relation` 返回评论位置，其他类型会静默忽略该参数；具体用法需要先阅读 [`references/lark-drive-comment-location.md`](references/lark-drive-comment-location.md) 了解。
 - 用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，仍按资源类型、URL 路径和 token 路由到本 skill；不要因为域名不是飞书而回退到 WebFetch。
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
@@ -63,6 +64,7 @@ metadata:
 | `/doc/` | `https://example.larksuite.com/doc/doccnxxxxxxxxx`     | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
 | `/wiki/` | `https://example.larksuite.com/wiki/wikcnxxxxxxxxx`    | `wiki_token` | 不能直接当底层 `file_token`；优先用 `drive +inspect` 解包获取 `obj_token` |
 | `/sheets/` | `https://example.larksuite.com/sheets/shtcnxxxxxxxxx`  | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
+| `/page/` | `https://example.feishu.cn/page/N1BWmMrqndT5ZcamAIBcnvDLnOf/` | apps token | 妙搭 apps 类型；用于评论列表时直接作为 `file_token`，`file_type=apps` |
 | `/drive/folder/` | `https://example.larksuite.com/drive/folder/fldcnxxxx` | `folder_token` | URL 路径中的 token 作为文件夹 token 使用 |
 
 ### Wiki 链接特殊处理
@@ -82,7 +84,7 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 | 添加全文评论 | `file_token` | 不传 `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc`/`docx`/`file` 的 wiki URL |
 | 下载文件 | `file_token` | 从文件 URL 中直接提取 |
 | 上传文件 | `folder_token` / `wiki_node_token` | 目标位置的 token |
-| 列出文档评论 | URL 或 `file_token` | 优先使用 `drive +list-comments --url '<url>'`；wiki URL/token 会自动解析到底层真实 token/type |
+| 列出文档评论 | URL 或 `file_token` | 优先使用 `drive +list-comments --url '<url>'`；wiki URL/token 会自动解析到底层真实 token/type；妙搭 apps URL 使用 `/page/<token>` |
 
 ### 评论能力入口
 
@@ -107,7 +109,7 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 |----------|------|----------|
 | `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
-| `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable） |
+| `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable/apps） |
 | `232140101` / `232140100` / `233523001`（常见于 `drive +import` 的 `job_error_msg`） | 同一位置下存在并发导入 / 创建操作 | 批量导入到同一文件夹、根目录或同一 `--target-token` 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突 |
 
 ### 权限能力入口
@@ -142,7 +144,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+push`](references/lark-drive-push.md) | 将本地目录推送到 Drive 文件夹，支持 skip / smart / overwrite 与确认后删除远端。 |
 | [`+create-shortcut`](references/lark-drive-create-shortcut.md) | 在另一个文件夹里创建现有 Drive 文件的快捷方式。 |
 | [`+add-comment`](references/lark-drive-add-comment.md) | 给 doc/docx/file/sheet/slides/base(bitable) 添加评论，也支持解析到这些类型的 wiki URL；评论统计、回复和 reaction 细则见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。 |
-| [`+list-comments`](references/lark-drive-list-comments.md) | 获取 doc/docx/sheet/file/slides/base(bitable) 评论列表；优先传 URL，支持 wiki 自动解包。 |
+| [`+list-comments`](references/lark-drive-list-comments.md) | 获取 doc/docx/sheet/file/slides/base(bitable)/apps 评论列表；优先传 URL，支持 wiki 自动解包和妙搭 `/page/<token>` URL。 |
 | [`+export`](references/lark-drive-export.md) | 将 doc/docx/sheet/bitable/slides 导出为本地文件。 |
 | [`+export-download`](references/lark-drive-export-download.md) | 根据导出产物的 file_token 下载文件。 |
 | [`+import`](references/lark-drive-import.md) | 将本地文件导入为飞书在线文档、表格、多维表格或幻灯片。 |

skills/lark-drive/references/lark-drive-list-comments.md

@@ -2,7 +2,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和权限处理。
 
-列出 doc/docx/sheet/file/slides/base(bitable) 的评论卡片。优先传用户给出的完整 URL，shortcut 会自动识别类型；如果传 wiki URL 或 `--token <wiki_token> --type wiki`，会先解析到真实文档。
+列出 doc/docx/sheet/file/slides/base(bitable)/apps 的评论卡片。优先传用户给出的完整 URL，shortcut 会自动识别类型；apps 为妙搭类型，支持 `/page/<token>` URL；如果传 wiki URL 或 `--token <wiki_token> --type wiki`，会先解析到真实文档。
 
 ## 重要默认口径
 
@@ -40,6 +40,10 @@ lark-cli drive +list-comments \
 lark-cli drive +list-comments \
   --url "https://example.larksuite.com/sheets/<SHEET_TOKEN>"
 
+# 妙搭 apps URL 使用 /page/<token>，shortcut 会识别为 file_type=apps。
+lark-cli drive +list-comments \
+  --url "https://example.feishu.cn/page/<APPS_TOKEN>/"
+
 # wiki URL 会自动解包。
 lark-cli drive +list-comments \
   --url "https://example.larksuite.com/wiki/<WIKI_TOKEN>"
@@ -55,6 +59,11 @@ lark-cli drive +list-comments \
   --type sheet \
   --page-size 100
 
+# 妙搭裸 apps token 需要显式声明 --type apps。
+lark-cli drive +list-comments \
+  --token "<APPS_TOKEN>" \
+  --type apps
+
 # docx 需要评论定位关系时再带 need-relation；非 docx 会静默忽略。
 lark-cli drive +list-comments \
   --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" \
@@ -77,9 +86,9 @@ lark-cli drive +list-comments \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--url` | 与 `--token` 二选一 | 推荐入口。支持 doc/docx/sheet/file/slides/base/bitable/wiki URL；wiki URL 会自动解析到真实文档。 |
+| `--url` | 与 `--token` 二选一 | 推荐入口。支持 doc/docx/sheet/file/slides/base/bitable/apps/wiki URL；apps 妙搭 URL 使用 `/page/<token>`；wiki URL 会自动解析到真实文档。 |
 | `--token` | 与 `--url` 二选一 | 裸 token 或 URL。裸 token 必须搭配 `--type`；wiki token 使用 `--type wiki`。 |
-| `--type` | 裸 token 时必填 | 传 token 对应类型：`doc`、`docx`、`sheet`、`file`、`slides`、`bitable`、`base`、`wiki`。wiki token 使用 `wiki`；传 `base` 时，CLI 会按 `bitable` 类型处理。 |
+| `--type` | 裸 token 时必填 | 传 token 对应类型：`doc`、`docx`、`sheet`、`file`、`slides`、`bitable`、`base`、`apps`、`wiki`。wiki token 使用 `wiki`；传 `base` 时，CLI 会按 `bitable` 类型处理。 |
 | `--solved-status` | 否 | `false` / `true` / `all`，默认 `false`。`false` 查未解决评论；`true` 查已解决评论；`all` 查全部评论。 |
 | `--comment-scope` | 否 | `all` / `whole` / `partial`，默认 `all`。`all` 查全部范围；`whole` 查全文评论；`partial` 查局部评论。 |
 | `--need-reaction` | 否 | 是否返回评论卡片上的 reaction 数据；只有用户明确需要 reaction 时才带。 |
@@ -90,7 +99,7 @@ lark-cli drive +list-comments \
 ## 行为说明
 
 - `--comment-scope all` 查全部范围；`whole` 查全文评论；`partial` 查局部/选区评论。
-- 当用户已经给出完整 URL 时，原样传给 `--url`；不要先提取 token 再重组成其他类型 URL。比如 sheet 保留 `/sheets/<token>`，wiki 保留 `/wiki/<token>`。
+- 当用户已经给出完整 URL 时，原样传给 `--url`；不要先提取 token 再重组成其他类型 URL。比如 sheet 保留 `/sheets/<token>`，wiki 保留 `/wiki/<token>`，妙搭 apps 保留 `/page/<token>`。
 - URL 输入时不需要传 `--type`；如果 URL 类型和显式 `--type` 冲突，shortcut 会返回 validation error，建议移除 `--type`。
 - wiki 输入会自动解析到真实文档，再查询评论列表。JSON 输出不额外返回 wiki token 或 wiki node。
 - 输出中的 `items` 保留评论卡片字段，外层补充 `file_token`、`file_type`、`has_more`、`page_token`、`count`；`count` 是当前页返回的评论卡片数。是否继续分页以 `has_more` 为准，而不是只看 `page_token` 是否存在。

skills/lark-drive/references/lark-drive-member-add.md

@@ -54,7 +54,7 @@ lark-cli drive +member-add \
 }
 ```
 
-批量部分失败时，`partial` 为 `true`，CLI 以非零退出码返回 `error.type=partial_failure`。检查 `error.detail` 中的 `requested_count`、`succeeded_count`、`members`、`missing_member_ids` 和可选的 `mismatched_member_ids`。响应顺序不影响匹配结果。
+批量部分失败时，`partial` 为 `true`，同一份结果以 `ok:false` 部分失败信封写到 **stdout**（stderr 不再输出单独的错误信封），CLI 以非零退出码结束。检查 `data` 中的 `requested_count`、`succeeded_count`、`members`、`missing_member_ids` 和可选的 `mismatched_member_ids`。响应顺序不影响匹配结果。
 
 ## 行为说明
 

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

@@ -17,11 +17,11 @@
 | `summary.deleted_local` | 启用 `--delete-local --yes` 时删除的本地文件数 |
 | `items[]` | 每个文件的明细（`rel_path` / `file_token` / `source_id` / `action` / 失败时的 `error`） |
 
-`summary.failed > 0` 时命令以 **非零状态码**（`exit=1`，`error.type=partial_failure`）退出，且同一份 `summary + items` 会在 `error.detail` 里返回；脚本/agent 直接通过 exit code 判断成败即可，不需要再去解 `summary.failed`。
+`summary.failed > 0` 时命令以 **非零状态码**（`exit=1`）退出：同一份 `summary + items` 会以 `ok:false` 部分失败信封写到 **stdout**（字段在 `data.summary` / `data.items`），stderr 不再输出单独的错误信封；脚本/agent 直接通过 exit code 判断成败即可，不需要再去解 `summary.failed`。
 
 ## 远端同名文件冲突
 
-如果 Drive 中多个条目映射到同一个 `rel_path`，默认直接失败（`error.type=duplicate_remote_path`），且不会下载、覆盖或删除任何本地文件。只有“多个 `type=file` 同名”的场景支持显式策略；`file-folder` 这类异构冲突始终直接失败。
+如果 Drive 中多个条目映射到同一个 `rel_path`，默认直接失败（stderr 类型化错误信封：`error.type=validation`、`error.subtype=failed_precondition`，`error.params[]` 逐条列出冲突的 `rel_path` 及碰撞条目），且不会下载、覆盖或删除任何本地文件。只有“多个 `type=file` 同名”的场景支持显式策略；`file-folder` 这类异构冲突始终直接失败。
 
 | 策略 | 行为 |
 |------|------|
@@ -80,7 +80,7 @@ lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 
 - `--delete-local`（无 `--yes`）→ Validate 直接报错：`--delete-local requires --yes`，没有任何下载、列表请求或删除发生。
 - `--delete-local --yes`，**且下载阶段全部成功** → 扫一遍 `--local-dir` 下所有常规文件，把不在云端清单里的逐个 `os.Remove`。**只删常规文件，不删目录**：远端文件夹被删除后，对应本地目录会保留空壳。
-- `--delete-local --yes`，**但下载阶段有任何条目失败** → **跳过整个删除阶段**，命令以 `partial_failure` 非零退出。设计意图：避免出现"前面下载失败、后面继续删本地文件"的半同步状态；操作者修好下载错误后再重跑即可。
+- `--delete-local --yes`，**但下载阶段有任何条目失败** → **跳过整个删除阶段**，命令以 `ok:false` 部分失败结果非零退出。设计意图：避免出现"前面下载失败、后面继续删本地文件"的半同步状态；操作者修好下载错误后再重跑即可。
 - 远端同名文件冲突且使用默认 `fail` → 在下载阶段前失败，删除阶段不会运行。
 - 不传 `--delete-local` → `summary.deleted_local` 永远是 0；命令对本地"多余"文件视而不见。
 

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

@@ -24,7 +24,7 @@
 
 ## 远端同名文件冲突
 
-如果 Drive 中多个条目映射到同一个 `rel_path`，默认直接失败（`error.type=duplicate_remote_path`），且不会上传、覆盖或进入 `--delete-remote` 删除阶段。只有“多个 `type=file` 同名”的场景支持显式策略；`file-folder` 这类异构冲突始终直接失败。
+如果 Drive 中多个条目映射到同一个 `rel_path`，默认直接失败（stderr 类型化错误信封：`error.type=validation`、`error.subtype=failed_precondition`，`error.params[]` 逐条列出冲突的 `rel_path` 及碰撞条目），且不会上传、覆盖或进入 `--delete-remote` 删除阶段。只有“多个 `type=file` 同名”的场景支持显式策略；`file-folder` 这类异构冲突始终直接失败。
 
 | 策略 | 行为 |
 |------|------|

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

@@ -19,7 +19,7 @@
 
 ## 远端同名文件冲突
 
-如果 Drive 中多个条目映射到同一个 `rel_path`，`+status` 会在下载/hash 前直接失败，返回 `error.type=duplicate_remote_path`，并在 `error.detail.duplicates_remote[]` 中列出该路径下所有冲突条目的 `file_token`、`type`、名称、大小和时间字段；其中 `created_time`、`modified_time` 缺失时会省略，`size` 在缺失或为 `0` 时都可能被省略。不要把这种情况当成普通 `modified`；它表示同步域本身有歧义，需要先整理云端结构，或在 `+pull` / `+push` 中仅对“duplicate file”场景显式选择冲突策略。
+如果 Drive 中多个条目映射到同一个 `rel_path`，`+status` 会在下载/hash 前直接失败，在 stderr 返回类型化错误信封（`error.type=validation`、`error.subtype=failed_precondition`）；`error.params[]` 每条的 `name` 是冲突的 `rel_path`，`reason` 枚举该路径下所有碰撞条目（`type` + `file_token`）。不要把这种情况当成普通 `modified`；它表示同步域本身有歧义，需要先整理云端结构，或在 `+pull` / `+push` 中仅对“duplicate file”场景显式选择冲突策略。
 
 ## 命令
 
@@ -76,20 +76,18 @@ lark-cli drive +status \
 ```json
 {
   "ok": false,
+  "identity": "user",
   "error": {
-    "type": "duplicate_remote_path",
-    "message": "multiple Drive entries map to the same rel_path",
-    "detail": {
-      "duplicates_remote": [
-        {
-          "rel_path": "dup.txt",
-          "entries": [
-            {"file_token": "<full_file_token>", "type": "file", "name": "dup.txt", "size": 5, "created_time": "1730000000", "modified_time": "1730000000"},
-            {"file_token": "<folder_token>", "type": "folder", "name": "dup.txt", "created_time": "1730000060", "modified_time": "1730000060"}
-          ]
-        }
-      ]
-    }
+    "type": "validation",
+    "subtype": "failed_precondition",
+    "message": "1 rel_path(s) map to multiple Drive entries",
+    "hint": "resolve the duplicate remote files first: re-run +pull with --on-duplicate-remote=rename (downloads each with a hashed suffix), or use --on-duplicate-remote=newest|oldest (supported by +pull/+sync/+push) to pick one, or delete the extra remote files; a plain retry will not help",
+    "params": [
+      {
+        "name": "dup.txt",
+        "reason": "2 Drive entries collide here: file <full_file_token>, folder <folder_token>"
+      }
+    ]
   }
 }
 ```

skills/lark-minutes/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-minutes
 version: 1.0.0
-description: "飞书妙记：搜索妙记、查看妙记基础信息、下载/上传音视频、读取或编辑妙记的产物内容、改标题、替换说话人/关键词。当给出minute_token、本地音视频文件，要查/改/转妙记产物时使用；本地音视频转纪要/逐字稿优先走本 skill，不要用 ffmpeg/whisper 本地转写。不负责：获取会议关联妙记，或仅按自然语言标题定位纪要"
+description: "飞书妙记：搜索妙记、查看妙记基础信息、下载/上传音视频、读取或编辑妙记的产物内容、改标题、替换说话人/关键词、申请妙记查看/编辑权限。当给出minute_token、本地音视频文件，要查/改/转妙记产物，或用户明确要主动申请妙记权限时使用；本地音视频转纪要/逐字稿优先走本 skill，不要用 ffmpeg/whisper 本地转写。不负责：获取会议关联妙记，或仅按自然语言标题定位纪要"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -31,6 +31,7 @@ metadata:
 | [`+download`](references/lark-minutes-download.md) | 下载妙记音视频媒体文件 |
 | [`+upload`](references/lark-minutes-upload.md) | 上传 file_token 生成妙记 |
 | [`+update`](references/lark-minutes-update.md) | 更新妙记标题 |
+| `+apply-permission` | 申请妙记查看或编辑权限 |
 | [`+speaker-replace`](references/lark-minutes-speaker-replace.md) | 替换妙记逐字稿中的说话人（须先 `lark-cli api GET .../speakerlist` 取 `speaker_id`） |
 | `+word-replace` | 批量替换逐字稿关键词（详见 `lark-cli minutes +word-replace --help`） |
 | [`+summary`](references/lark-minutes-summary.md) | 替换妙记 AI 总结全文 |
@@ -52,6 +53,7 @@ metadata:
 | 在妙记里增加 / 更改 / 删除 AI 待办 | `+todo`（**禁止走 lark-task**） |
 | 替换妙记的AI 总结 | `+summary` |
 | 重命名妙记/改妙记标题 | `+update` |
+| 申请妙记权限（查看/编辑） | `+apply-permission --perm view\|edit` |
 | 替换说话人/把 A 的发言改成 B/重新归属发言人/把外部（非飞书）说话人改成飞书用户" | 先 `lark-cli api GET .../transcript/speakerlist` 取 `speaker_id`，再 [`minutes +speaker-replace`](references/lark-minutes-speaker-replace.md)；`--from-speaker-id` 只传 id，不传展示名 |
 | 批量替换逐字稿关键词 | `+word-replace` |
 | 用户同时提到"会议/开会"和"妙记" | 先 [lark-vc](../lark-vc/SKILL.md)（`+search` → `+recording`）获取 `minute_token`，再本 skill |
@@ -75,8 +77,21 @@ metadata:
 2. 如果是会议 / 日程上下文中的妙记基础信息，先通过 VC/Calendar 链路拿到 `minute_token`，再调用 `minutes minutes get`。
 3. 用户意图不明确时，默认先给基础元信息，帮助确认是否命中目标妙记。
 
+### 3. 申请妙记权限
 
-### 3. 上传音视频文件生成妙记（并可继续获取纪要 / 逐字稿）
+遇到妙记没有查看或编辑权限时，引导用户申请对应权限；只有用户明确要申请时，才调用 `minutes +apply-permission`。
+
+只有当用户明确要求"申请查看权限"、"申请编辑权限"、"帮我申请这条妙记权限"时，才调用：
+
+```bash
+lark-cli minutes +apply-permission --minute-token <token> --perm view|edit
+```
+
+这是向妙记所有者发起权限申请，不代表立即获得权限。
+
+**安全约束**：遇到无权限错误时，不要自动调用 `+apply-permission`；先把无权限事实告知用户，只有用户明确要求申请权限时才发起申请。
+
+### 4. 上传音视频文件生成妙记（并可继续获取纪要 / 逐字稿）
 
 1. 当用户说"把音视频文件转成纪要""把录音转成逐字稿/文字稿/撰写文字""把 mp4/mp3 转成总结/待办/章节"时，也先走这个入口。
 2. **处理流程**：
@@ -120,9 +135,9 @@ lark-cli minutes +todo --minute-token <token> --as user --todos '[
 
 **更新 / 删除前**：先用 `minutes +detail --minute-tokens <token> --todo` 读取 `todos[].todo_id`（按 `content` 匹配目标条目；列表顺序不保证稳定，**不要**用"第 2 条"代替 `todo_id`）。
 
-**无编辑权限**：若 CLI 返回 `error.type=no_edit_permission`，表示对**这条妙记**没有编辑权，应请所有者授权；**不要**误走 `auth login --scope`。
+**无编辑权限**：若 CLI 返回 `error.subtype=permission_denied`，表示对**这条妙记**没有编辑权，应请所有者授权；**不要**误走 `auth login --scope`。
 
-**逐字稿关键词替换无命中**：`minutes +word-replace` 时，若 CLI 返回 `error.type=words_not_found`，表示传入的 `source_word` 在该妙记逐字稿中**一个都没匹配到**，未做任何替换。这是**参数问题不是权限问题**：先用 `minutes +detail --minute-tokens <token> --transcript` 读取当前逐字稿，核对 `source_word` 的精确写法与大小写后重试。
+**逐字稿关键词替换无命中**：`minutes +word-replace` 时，若 CLI 返回 `error.subtype=not_found`，表示传入的 `source_word` 在该妙记逐字稿中**一个都没匹配到**，未做任何替换。这是**参数问题不是权限问题**：先用 `minutes +detail --minute-tokens <token> --transcript` 读取当前逐字稿，核对 `source_word` 的精确写法与大小写后重试。
 
 **替换 AI 总结全文**：见 [minutes +summary](references/lark-minutes-summary.md)。
 

skills/lark-minutes/references/lark-minutes-todo.md

@@ -126,8 +126,8 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add -
 | 未指定操作 | 单条模式传 `--operation`，或批量传 `--todos` |
 | `--todos` 与单条 flags 冲突 | 二选一 |
 | `todos[i]` 校验失败 | 检查该条 `operation` 与字段组合 |
-| `error.type` = `no_edit_permission` | **妙记资源无编辑权**：向妙记所有者申请该妙记的编辑/协作权限；**不要**走 `auth login --scope` |
-| 缺少 OAuth scope（`permission_violations` 含 `minutes:minutes:update`） | `lark-cli auth login --scope "minutes:minutes:update"` |
+| `error.subtype` = `permission_denied` | **妙记资源无编辑权**：向妙记所有者申请该妙记的编辑/协作权限；**不要**走 `auth login --scope` |
+| 缺少 OAuth scope（`error.missing_scopes` 含 `minutes:minutes:update`） | `lark-cli auth login --scope "minutes:minutes:update"` |
 
 ## 参考