test: cover mail +watch default json envelope output

Co-authored-by: yballul-bytedance <273011618+yballul-bytedance@users.noreply.github.com>

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.67] - 2026-07-08
+
+### Features
+
+- **mail**: add message modify and trash shortcuts (#1567)
+- support whiteboard file inputs in docs XML (#1784)
+- **vc**: refine meeting-events output and reaction forwarding (#1674)
+- **affordance**: usage guidance for shortcuts and per-command skills (#1793)
+
+### Bug Fixes
+
+- accept opaque wiki node tokens (#1789)
+- **apps**: make db --environment optional, auto-select branch server-side (#1735)
+- preserve original filename in multipart file upload (#1767)
+
+### Documentation
+
+- restore one-time authorization guidance in lark-apps skill (#1794)
+
+### Misc
+
+- e2e: harden CLI E2E retry, cleanup, and domain selection (#1709)
+
 ## [v1.0.66] - 2026-07-07
 
 ### Features
@@ -1398,6 +1421,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.67]: https://github.com/larksuite/cli/releases/tag/v1.0.67
 [v1.0.66]: https://github.com/larksuite/cli/releases/tag/v1.0.66
 [v1.0.65]: https://github.com/larksuite/cli/releases/tag/v1.0.65
 [v1.0.64]: https://github.com/larksuite/cli/releases/tag/v1.0.64

affordance/README.md

@@ -10,18 +10,33 @@ step. Maintain these files alongside `skills/` and `shortcuts/`.
 A small, fixed markdown subset; each file describes one domain:
 
     # <domain>            optional `> skill: <name>` applies to every command below
-    ## <command>          the command as typed, minus `lark-cli <domain>`
+    ## <command>          the command as typed, minus `lark-cli <domain>`; a
+                          +-prefixed heading (## +create) targets that shortcut
     <lead paragraph>      when to use this command
     ### Avoid when        when not to use it / which command to use instead
     ### Prerequisites     what you must have first (e.g. an id, and where it comes from)
     ### Tips              gotchas and constraints
     ### Examples          **description** lines, each followed by a fenced command
+    ### Skills            bullet skill names, or name/relpath references
+                          (lark-contact/references/x.md), to read for usage;
+                          merged with the domain `> skill:` default (deduped,
+                          domain first)
     ### <other heading>   a custom section; flows through verbatim
 
 Reference another command with `[[command]]` — it renders as `command` in help.
 Under `Avoid when` it means "use that one instead"; under `Prerequisites`
 ("… from [[command]]") it means "get the input there first".
 
+Both service-API commands (`## messages get`) and `+`-prefixed shortcuts
+(`## +create`) take entries. A `### Skills` entry is a skill name (validated
+against `<name>/SKILL.md`) or a `name/relpath` reference into that skill
+(validated against the path); help drops any that don't resolve, so a typo shows
+nothing. Point a command at its own reference (e.g. `+search-user` →
+`lark-contact/references/lark-contact-search-user.md`) rather than re-listing the
+domain skill, which the `> skill:` default already covers. When a shortcut also
+sets a hand-authored `Tips` list in Go, the overlay's `### Tips` win — they
+replace the Go tips (not merged), so keep tips in one place.
+
 ## Example
 
     ## messages get
@@ -47,3 +62,5 @@ Under `Avoid when` it means "use that one instead"; under `Prerequisites`
   anything the schema and flags already show; the agent infers the rest.
 - Command-form headings resolve to method ids via the registry, so plural resource
   names (`messages`) map to the singular method id (`message`) automatically.
+  `+`-prefixed shortcut headings are matched verbatim (no plural/space folding),
+  so the heading must equal the shortcut command exactly (`## +history-revert`).

affordance/contact.md

@@ -1,6 +1,42 @@
 # contact
 > skill: lark-contact
 
+## +search-user
+The primary user lookup for user identity: search by keyword or email, resolve known ids with --user-ids, or get yourself with --user-ids me — it does by-id reads too, so as a user you rarely need `+get-user`. Each match returns an open_id and p2p_chat_id to chain into follow-ups.
+
+### Skills
+- lark-contact/references/lark-contact-search-user.md
+
+### Avoid when
+- Running as a bot — this shortcut is user-only; use [[+get-user]] instead (it supports bot identity)
+- You only need users' personal status for ids you already hold → use [[user_profiles batch_query]]
+
+### Examples
+
+**Find a user by name**
+```bash
+lark-cli contact +search-user --query "alice" --as user
+```
+
+**Fetch known users by open_id (me = yourself)**
+```bash
+lark-cli contact +search-user --user-ids "ou_3a8b****6a7b,me" --as user
+```
+
+## +get-user
+Fetch one user's profile by id, or your own with --user-id omitted. Use it under bot identity — `+search-user` is user-only.
+
+### Skills
+- lark-contact/references/lark-contact-get-user.md
+
+### Avoid when
+- You don't have the user's id yet, or want to match by name/keyword → use [[+search-user]]
+- Running as a user — [[+search-user]] --user-ids covers by-id reads and more in one tool
+
+### Tips
+- Self lookup (omit --user-id) needs user identity; a bot must pass --user-id
+- --user-id-type must match the id you pass (default open_id)
+
 ## user_profiles batch_query
 Bulk-fetch personal status and signature for user ids you already have.
 

cmd/api/api_test.go

@@ -4,10 +4,14 @@
 package api
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
+	"mime"
+	"mime/multipart"
 	"os"
+	"path/filepath"
 	"sort"
 	"strings"
 	"testing"
@@ -1069,3 +1073,157 @@ func TestApiCmd_JsonFlag_Accepted(t *testing.T) {
 		t.Errorf("expected method GET, got %s", gotOpts.Method)
 	}
 }
+
+// parseMultipartFilenames drives one api --file upload through the mock
+// transport and returns a map of field name -> part filename parsed from the
+// captured multipart body, plus the map of text form fields. It fails the test
+// if the captured request is not multipart/form-data.
+func parseMultipartFilenames(t *testing.T, stub *httpmock.Stub) (map[string]string, map[string]string) {
+	t.Helper()
+	ct := stub.CapturedHeaders.Get("Content-Type")
+	mediaType, params, err := mime.ParseMediaType(ct)
+	if err != nil {
+		t.Fatalf("parse Content-Type %q: %v", ct, err)
+	}
+	if !strings.HasPrefix(mediaType, "multipart/") {
+		t.Fatalf("Content-Type = %q, want multipart/*", mediaType)
+	}
+	filenames := map[string]string{}
+	fields := map[string]string{}
+	mr := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
+	for {
+		part, err := mr.NextPart()
+		if err != nil {
+			break
+		}
+		if fn := part.FileName(); fn != "" {
+			filenames[part.FormName()] = fn
+		} else {
+			buf := &bytes.Buffer{}
+			_, _ = buf.ReadFrom(part)
+			fields[part.FormName()] = buf.String()
+		}
+	}
+	return filenames, fields
+}
+
+func TestApiCmd_FileUpload_PreservesFilename(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile(filepath.Join(dir, "invoice.pdf"), []byte("%PDF-1.4 fake"), 0600); err != nil {
+		t.Fatalf("write test file: %v", err)
+	}
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/approval/v4/files/upload",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot", "--file", "invoice.pdf"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames, _ := parseMultipartFilenames(t, stub)
+	if got := filenames["file"]; got != "invoice.pdf" {
+		t.Fatalf("part filename for field %q = %q, want %q", "file", got, "invoice.pdf")
+	}
+}
+
+func TestApiCmd_FileUpload_FieldPrefixKeepsBasename(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0700); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "sub", "invoice.pdf"), []byte("%PDF-1.4 fake"), 0600); err != nil {
+		t.Fatalf("write test file: %v", err)
+	}
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/approval/v4/files/upload",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot", "--file", "upload=sub/invoice.pdf"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames, _ := parseMultipartFilenames(t, stub)
+	if _, ok := filenames["upload"]; !ok {
+		t.Fatalf("expected field name %q from field=path form, got fields %v", "upload", filenames)
+	}
+	if got := filenames["upload"]; got != "invoice.pdf" {
+		t.Fatalf("part filename for field %q = %q, want %q (basename only)", "upload", got, "invoice.pdf")
+	}
+}
+
+func TestApiCmd_FileUpload_WithDataFields(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile(filepath.Join(dir, "invoice.pdf"), []byte("%PDF-1.4 fake"), 0600); err != nil {
+		t.Fatalf("write test file: %v", err)
+	}
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/approval/v4/files/upload",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot",
+		"--file", "invoice.pdf", "--data", `{"type":"attachment"}`})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames, fields := parseMultipartFilenames(t, stub)
+	if got := filenames["file"]; got != "invoice.pdf" {
+		t.Fatalf("part filename = %q, want %q", got, "invoice.pdf")
+	}
+	if got := fields["type"]; got != "attachment" {
+		t.Fatalf("text field type = %q, want %q", got, "attachment")
+	}
+}
+
+func TestApiCmd_FileUpload_StdinFallsBackToUnknown(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.IOStreams.In = bytes.NewReader([]byte("stdin-bytes"))
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/approval/v4/files/upload",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot", "--file", "-"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames, _ := parseMultipartFilenames(t, stub)
+	if got := filenames["file"]; got != "unknown-file" {
+		t.Fatalf("stdin part filename = %q, want %q (no stable local name, fallback)", got, "unknown-file")
+	}
+}

cmd/auth/login.go

@@ -49,9 +49,6 @@ func NewCmdAuthLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.
 		Short: "Device Flow authorization login",
 		Long: `Device Flow authorization login.
 
-With no --scope/--domain/--recommend flag, this requests scopes for all known
-business domains (equivalent to --domain all); pass --domain or --scope to narrow it.
-
 For AI agents: this command blocks until the user completes authorization in the
 browser. If your harness or agent tool only delivers final turn messages, use --no-wait --json,
 send the verification URL (or QR code) to the user as your final message, end the turn, then
@@ -74,7 +71,7 @@ to generate QR codes (supports ASCII and PNG formats).`,
 	cmdutil.SetRisk(cmd, "write")
 
 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space- or comma-separated). Combines additively with --domain/--recommend")
-	cmd.Flags().BoolVar(&opts.Recommend, "recommend", false, "request scopes for all known domains (equivalent to --domain all)")
+	cmd.Flags().BoolVar(&opts.Recommend, "recommend", false, "request only recommended (auto-approve) scopes")
 	var helpBrand core.LarkBrand
 	if f != nil && f.Config != nil {
 		if cfg, err := f.Config(); err == nil && cfg != nil {
@@ -147,6 +144,33 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 
 	selectedDomains := opts.Domains
+	scopeLevel := "" // "common" or "all" (from interactive mode)
+
+	// Expand --domain all to all available domains (from_meta projects + shortcut services)
+	for _, d := range selectedDomains {
+		if strings.EqualFold(d, "all") {
+			selectedDomains = sortedKnownDomains(config.Brand)
+			break
+		}
+	}
+
+	// Validate domain names and suggest corrections for unknown ones
+	if len(selectedDomains) > 0 {
+		knownDomains := allKnownDomains(config.Brand)
+		for _, d := range selectedDomains {
+			if !knownDomains[d] {
+				if suggestion := suggestDomain(d, knownDomains); suggestion != "" {
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, did you mean %q?", d, suggestion).WithParam("--domain")
+				}
+				available := make([]string, 0, len(knownDomains))
+				for k := range knownDomains {
+					available = append(available, k)
+				}
+				sort.Strings(available)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, available domains: %s", d, strings.Join(available, ", ")).WithParam("--domain")
+			}
+		}
+	}
 
 	hasAnyOption := opts.Scope != "" || opts.Recommend || len(selectedDomains) > 0
 
@@ -154,51 +178,30 @@ func authLoginRun(opts *LoginOptions) error {
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--exclude requires --scope, --domain, or --recommend to be specified").WithParam("--exclude")
 	}
 
-	// scopeOnly is the one path that must never touch the domain catalog
-	// (remote or local): --scope given alone, with neither --domain nor
-	// --recommend. Every other path — including bare `auth login`, now that
-	// the interactive picker is gone — needs the legal domain set to resolve
-	// scopes.
-	scopeOnly := opts.Scope != "" && !opts.Recommend && len(selectedDomains) == 0
-
-	var remote map[string][]string
-	var remoteOK bool
-
-	if !scopeOnly {
-		// Pull the remote scopes.json once for this login (not cached); any
-		// read failure (network/timeout/non-2xx/malformed) silently falls back
-		// to the local full computation — no warning, no telemetry.
-		remote, remoteOK = larkauth.FetchRemoteScopes(config.Brand)
-		legalDomains, allLegalDomains := legalDomainsFor(remote, remoteOK, config.Brand)
-
-		// Expand --domain all against the resolved legal domain set.
-		for _, d := range selectedDomains {
-			if strings.EqualFold(d, "all") {
-				selectedDomains = allLegalDomains
-				break
+	if !hasAnyOption {
+		if !opts.JSON && f.IOStreams.IsTerminal {
+			result, err := runInteractiveLogin(f.IOStreams, lang.Base(), msg, config.Brand)
+			if err != nil {
+				return err
 			}
-		}
-
-		if len(selectedDomains) > 0 {
-			// Validate explicitly-supplied domain names and suggest corrections.
-			for _, d := range selectedDomains {
-				if !legalDomains[d] {
-					if suggestion := suggestDomain(d, legalDomains); suggestion != "" {
-						return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, did you mean %q?", d, suggestion).WithParam("--domain")
-					}
-					available := make([]string, 0, len(legalDomains))
-					for k := range legalDomains {
-						available = append(available, k)
-					}
-					sort.Strings(available)
-					return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown domain %q, available domains: %s", d, strings.Join(available, ", ")).WithParam("--domain")
-				}
+			if result == nil {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "no login options selected")
 			}
+			selectedDomains = result.Domains
+			scopeLevel = result.ScopeLevel
 		} else {
-			// Bare `auth login` and `--recommend` without `--domain` both span
-			// the full legal domain set now that the interactive picker and
-			// the local auto-approve filter are gone (--recommend ≡ --domain all).
-			selectedDomains = allLegalDomains
+			log(msg.HintHeader)
+			log("Common options:")
+			log(msg.HintCommon1)
+			log(msg.HintCommon2)
+			log(msg.HintCommon3)
+			log(msg.HintCommon4)
+			log("")
+			log("View all options:")
+			log(msg.HintFooter)
+			log("")
+			log("Note: this command blocks until authorization is complete. For non-streaming agent harnesses, use --no-wait --json, send the verification URL as the final message of the turn, then run --device-code in a later step after the user confirms authorization.")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "please specify the scopes to authorize").WithParam("--scope")
 		}
 	}
 
@@ -212,8 +215,19 @@ func authLoginRun(opts *LoginOptions) error {
 	// --scope, --domain, and --recommend combine additively so callers can,
 	// for example, request all `docs` scopes plus a few specific `drive`
 	// scopes in a single command.
-	if len(selectedDomains) > 0 {
-		candidateScopes := resolveScopesForDomains(selectedDomains, remote, remoteOK, config.Brand)
+	if len(selectedDomains) > 0 || opts.Recommend {
+		var candidateScopes []string
+		if len(selectedDomains) > 0 {
+			candidateScopes = collectScopesForDomains(selectedDomains, "user", config.Brand)
+		} else {
+			// --recommend without --domain: all domains
+			candidateScopes = collectScopesForDomains(sortedKnownDomains(config.Brand), "user", config.Brand)
+		}
+
+		// Filter to auto-approve scopes if --recommend or interactive "common"
+		if opts.Recommend || scopeLevel == "common" {
+			candidateScopes = registry.FilterAutoApproveScopes(candidateScopes)
+		}
 
 		if len(candidateScopes) == 0 && opts.Scope == "" {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "no matching scopes found, check domain/scope options")
@@ -368,10 +382,10 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 
 	if issue := ensureRequestedScopesGranted(finalScope, result.Token.Scope, msg, scopeSummary); issue != nil {
-		return handleLoginScopeIssue(opts, msg, f, issue, openId, userName, result.Token.StatusMessage)
+		return handleLoginScopeIssue(opts, msg, f, issue, openId, userName)
 	}
 
-	writeLoginSuccess(opts, msg, f, openId, userName, scopeSummary, result.Token.StatusMessage)
+	writeLoginSuccess(opts, msg, f, openId, userName, scopeSummary)
 	return nil
 }
 
@@ -451,10 +465,10 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 	}
 
 	if issue := ensureRequestedScopesGranted(requestedScope, result.Token.Scope, msg, scopeSummary); issue != nil {
-		return handleLoginScopeIssue(opts, msg, f, issue, openId, userName, result.Token.StatusMessage)
+		return handleLoginScopeIssue(opts, msg, f, issue, openId, userName)
 	}
 
-	writeLoginSuccess(opts, msg, f, openId, userName, scopeSummary, result.Token.StatusMessage)
+	writeLoginSuccess(opts, msg, f, openId, userName, scopeSummary)
 	return nil
 }
 
@@ -536,30 +550,6 @@ func collectScopesForDomains(domains []string, identity string, brand core.LarkB
 	return result
 }
 
-// resolveScopesForDomains resolves the scope set for the given domains. When
-// the remote scopes.json is available it takes the union of each domain's
-// user_scopes from the remote result (remote is authoritative, including
-// domains this CLI build doesn't know about locally); otherwise it falls back
-// to the local synthesis via collectScopesForDomains. Always returns a
-// deduplicated, alphabetically sorted slice.
-func resolveScopesForDomains(domains []string, remote map[string][]string, remoteOK bool, brand core.LarkBrand) []string {
-	if remoteOK {
-		set := make(map[string]bool)
-		for _, d := range domains {
-			for _, s := range remote[d] {
-				set[s] = true
-			}
-		}
-		out := make([]string, 0, len(set))
-		for s := range set {
-			out = append(out, s)
-		}
-		sort.Strings(out)
-		return out
-	}
-	return collectScopesForDomains(domains, "user", brand)
-}
-
 // allKnownDomains returns all valid auth domain names (from_meta projects +
 // shortcut services), excluding domains that have auth_domain set (they are
 // folded into their parent domain).
@@ -592,25 +582,6 @@ func sortedKnownDomains(brand core.LarkBrand) []string {
 	return domains
 }
 
-// legalDomainsFor returns the authoritative domain set for this login: the
-// remote scopes.json keys when available (a remote-listed domain unknown to
-// this CLI build is still legal), otherwise the local known-domain set.
-// Returns both a membership set (for --domain validation) and a sorted slice
-// (for `all` expansion and the bare-login/--recommend-without-domain default).
-func legalDomainsFor(remote map[string][]string, remoteOK bool, brand core.LarkBrand) (map[string]bool, []string) {
-	if remoteOK {
-		set := make(map[string]bool, len(remote))
-		sorted := make([]string, 0, len(remote))
-		for d := range remote {
-			set[d] = true
-			sorted = append(sorted, d)
-		}
-		sort.Strings(sorted)
-		return set, sorted
-	}
-	return allKnownDomains(brand), sortedKnownDomains(brand)
-}
-
 // shortcutSupportsIdentity checks if a shortcut supports the given identity ("user" or "bot").
 // Empty AuthTypes defaults to ["user"].
 func shortcutSupportsIdentity(sc common.Shortcut, identity string) bool {

cmd/auth/login_interactive.go

@@ -0,0 +1,188 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/charmbracelet/huh"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/shortcuts"
+)
+
+// domainMeta describes a domain for the interactive selector.
+type domainMeta struct {
+	Name        string
+	Title       string
+	Description string
+}
+
+// interactiveResult holds the user's selections from the interactive form.
+type interactiveResult struct {
+	Domains    []string
+	ScopeLevel string // "common" or "all"
+}
+
+// getDomainMetadata returns metadata for all known domains, sorted by name.
+func getDomainMetadata(lang string) []domainMeta {
+	seen := make(map[string]bool)
+	var domains []domainMeta
+
+	// 1. Domains from from_meta projects (skip domains with auth_domain)
+	for _, project := range registry.ListFromMetaProjects() {
+		if registry.HasAuthDomain(project) {
+			seen[project] = true
+			continue
+		}
+		dm := buildDomainMeta(project, lang)
+		domains = append(domains, dm)
+		seen[project] = true
+	}
+
+	// 2. Shortcut-only domains
+	shortcutOnlyNames := getShortcutOnlyDomainNames()
+	for _, name := range shortcutOnlyNames {
+		if !seen[name] {
+			dm := buildDomainMeta(name, lang)
+			domains = append(domains, dm)
+			seen[name] = true
+		}
+	}
+
+	// 3. Auto-discover remaining shortcut services that are listed as shortcut-only domains
+	//    (skip domains with auth_domain — they are folded into their parent)
+	shortcutOnlySet := make(map[string]bool)
+	for _, n := range shortcutOnlyNames {
+		shortcutOnlySet[n] = true
+	}
+	for _, sc := range shortcuts.AllShortcuts() {
+		if !seen[sc.Service] {
+			if shortcutOnlySet[sc.Service] && !registry.HasAuthDomain(sc.Service) {
+				dm := buildDomainMeta(sc.Service, lang)
+				domains = append(domains, dm)
+			}
+			seen[sc.Service] = true
+		}
+	}
+
+	sort.Slice(domains, func(i, j int) bool {
+		return domains[i].Name < domains[j].Name
+	})
+	return domains
+}
+
+// buildDomainMeta constructs a domainMeta for a given service name and language.
+// It reads from the service_descriptions.json config first, falling back to
+// from_meta spec fields if not found.
+func buildDomainMeta(name, lang string) domainMeta {
+	title := registry.GetServiceTitle(name, lang)
+	desc := registry.GetServiceDetailDescription(name, lang)
+	if title != "" || desc != "" {
+		return domainMeta{
+			Name:        name,
+			Title:       title,
+			Description: desc,
+		}
+	}
+	// Fallback: read from the typed service spec (legacy)
+	dm := domainMeta{Name: name}
+	if svc, ok := registry.ServiceTyped(name); ok {
+		dm.Title = svc.Title
+		dm.Description = svc.Description
+	}
+	return dm
+}
+
+// runInteractiveLogin shows an interactive TUI form for domain and permission selection.
+func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg, brand core.LarkBrand) (*interactiveResult, error) {
+	allDomains := getDomainMetadata(lang)
+
+	// Build multi-select options
+	options := make([]huh.Option[string], len(allDomains))
+	for i, dm := range allDomains {
+		var label string
+		switch {
+		case dm.Title != "" && dm.Description != "":
+			label = fmt.Sprintf("%-12s %s - %s", dm.Name, dm.Title, dm.Description)
+		case dm.Title != "":
+			label = fmt.Sprintf("%-12s %s", dm.Name, dm.Title)
+		default:
+			label = fmt.Sprintf("%-12s %s", dm.Name, dm.Description)
+		}
+		options[i] = huh.NewOption(label, dm.Name)
+	}
+
+	var selectedDomains []string
+	var permLevel string
+
+	// Phase 1a: domain selection
+	// Phase 1b: permission level (shown after domain selection completes)
+	form1 := huh.NewForm(
+		huh.NewGroup(
+			huh.NewMultiSelect[string]().
+				Title(msg.SelectDomains).
+				Description(msg.DomainHint).
+				Options(options...).
+				Value(&selectedDomains).
+				Validate(func(s []string) error {
+					if len(s) == 0 {
+						return fmt.Errorf(msg.ErrNoDomain)
+					}
+					return nil
+				}),
+		),
+		huh.NewGroup(
+			huh.NewSelect[string]().
+				Title(msg.PermLevel).
+				Options(
+					huh.NewOption(msg.PermCommon, "common"),
+					huh.NewOption(msg.PermAll, "all"),
+				).
+				Value(&permLevel),
+		),
+	).WithTheme(cmdutil.ThemeFeishu())
+
+	if err := form1.Run(); err != nil {
+		if err == huh.ErrUserAborted {
+			return nil, output.ErrBare(1)
+		}
+		return nil, err
+	}
+
+	if len(selectedDomains) == 0 {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "no domains selected").WithParam("--domain")
+	}
+
+	// Compute scope summary
+	scopes := collectScopesForDomains(selectedDomains, "user", brand)
+	if permLevel == "common" {
+		scopes = registry.FilterAutoApproveScopes(scopes)
+	}
+
+	// Print summary
+	permLabel := msg.PermAllLabel
+	if permLevel == "common" {
+		permLabel = msg.PermCommonLabel
+	}
+	fmt.Fprintf(ios.ErrOut, msg.Summary)
+	fmt.Fprintf(ios.ErrOut, msg.SummaryDomains, strings.Join(selectedDomains, ", "))
+	fmt.Fprintf(ios.ErrOut, msg.SummaryPerm, permLabel)
+	scopePreview := strings.Join(scopes, ", ")
+	if len(scopePreview) > 80 {
+		scopePreview = strings.Join(scopes[:3], ", ") + ", ..."
+	}
+	fmt.Fprintf(ios.ErrOut, msg.SummaryScopes, len(scopes), scopePreview)
+
+	return &interactiveResult{
+		Domains:    selectedDomains,
+		ScopeLevel: permLevel,
+	}, nil
+}

cmd/auth/login_messages.go

@@ -6,6 +6,21 @@ package auth
 import "github.com/larksuite/cli/internal/i18n"
 
 type loginMsg struct {
+	// Interactive UI (login_interactive.go)
+	SelectDomains   string
+	DomainHint      string
+	PermLevel       string
+	PermCommon      string
+	PermAll         string
+	Summary         string
+	SummaryDomains  string
+	SummaryPerm     string
+	SummaryScopes   string
+	PermAllLabel    string
+	PermCommonLabel string
+	ErrNoDomain     string
+	ConfirmAuth     string
+
 	// Non-interactive prompts (login.go)
 	OpenURL            string
 	WaitingAuth        string
@@ -19,9 +34,31 @@ type loginMsg struct {
 	NewlyGrantedScopes string
 	NoScopes           string
 	StatusHint         string
+
+	// Non-interactive hint (no flags)
+	HintHeader  string
+	HintCommon1 string
+	HintCommon2 string
+	HintCommon3 string
+	HintCommon4 string
+	HintFooter  string
 }
 
 var loginMsgZh = &loginMsg{
+	SelectDomains:   "选择要授权的业务域",
+	DomainHint:      "空格=选择, 回车=确认",
+	PermLevel:       "权限类型",
+	PermCommon:      "常用权限",
+	PermAll:         "全部权限",
+	Summary:         "\n摘要:\n",
+	SummaryDomains:  "  域:       %s\n",
+	SummaryPerm:     "  权限:     %s\n",
+	SummaryScopes:   "  Scopes (%d): %s\n\n",
+	PermAllLabel:    "全部权限",
+	PermCommonLabel: "常用权限",
+	ErrNoDomain:     "请至少选择一个业务域",
+	ConfirmAuth:     "确认授权?",
+
 	OpenURL:            "在浏览器中打开以下链接进行认证:\n\n",
 	WaitingAuth:        "等待用户授权...",
 	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout >= 600s。若你的 harness 或 agent 工具只会把最终回复发给用户，请改用 \"lark-cli auth login --no-wait --json\" 拿到 device_code 和 verification_url，把 verification_url 作为本轮最终消息发给用户并结束本轮；等用户回复已完成授权后，再在后续步骤运行 \"lark-cli auth login --device-code <code>\" 续上轮询。**不要在同一轮里展示 URL 后立刻阻塞执行 --device-code**，也不要短 timeout 反复重试；每次重启会作废上一轮的 device code，导致用户授权链接失效。**必须生成二维码并展示**: 你必须调用 lark-cli auth qrcode 将 verification_url 转为二维码，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。**关键：生成后必须在回复中展示图片**，仅生成文件不算完成，须用 image 标签或内联图片等方式将图片包含在回复中。**展示顺序**: 先输出 URL，再将二维码图片置于 URL 下方完整展示。**URL 输出规则**: 将 verification_url 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点）。",
@@ -34,9 +71,30 @@ var loginMsgZh = &loginMsg{
 	NewlyGrantedScopes: "  本次新授予 scopes: %s\n",
 	NoScopes:           "（空）",
 	StatusHint:         "可执行 `lark-cli auth status` 查看账号当前已授予的全部 scopes；",
+
+	HintHeader:  "请指定要授权的权限:\n",
+	HintCommon1: "  --recommend                     授权推荐权限",
+	HintCommon2: "  --domain all                    授权所有已知域的权限",
+	HintCommon3: "  --domain calendar,task          授权日历和任务域的权限",
+	HintCommon4: "  --domain calendar --recommend   授权日历域的推荐权限",
+	HintFooter:  "  lark-cli auth login --help",
 }
 
 var loginMsgEn = &loginMsg{
+	SelectDomains:   "Select domains to authorize",
+	DomainHint:      "Space=toggle, Enter=confirm",
+	PermLevel:       "Permission level",
+	PermCommon:      "Common scopes",
+	PermAll:         "All scopes",
+	Summary:         "\nSummary:\n",
+	SummaryDomains:  "  Domains:  %s\n",
+	SummaryPerm:     "  Level:    %s\n",
+	SummaryScopes:   "  Scopes (%d): %s\n\n",
+	PermAllLabel:    "All scopes",
+	PermCommonLabel: "Common scopes",
+	ErrNoDomain:     "please select at least one domain",
+	ConfirmAuth:     "Confirm authorization?",
+
 	OpenURL:            "Open this URL in your browser to authenticate:\n\n",
 	WaitingAuth:        "Waiting for user authorization...",
 	AgentTimeoutHint:   "[AI agent] This command blocks for up to ~10 minutes while waiting for the user to authorize in their browser. Make sure your runner's timeout is >= 600s. If your harness or agent tool only delivers final turn messages, use \"lark-cli auth login --no-wait --json\" to get device_code and verification_url, present verification_url to the user exactly as the final message of this turn, then end the turn; after the user replies that they authorized, run \"lark-cli auth login --device-code <code>\" in a later step to resume polling. **Do NOT show the URL and then immediately block on --device-code in the same turn**, and do not retry with a short timeout; each restart invalidates the previous device code and makes the earlier authorization URL useless.**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation.",
@@ -49,6 +107,13 @@ var loginMsgEn = &loginMsg{
 	NewlyGrantedScopes: "  Newly granted scopes: %s\n",
 	NoScopes:           "(none)",
 	StatusHint:         "Run `lark-cli auth status` to inspect all scopes currently granted to the account.",
+
+	HintHeader:  "Please specify the scopes to authorize:\n",
+	HintCommon1: "  --recommend                     authorize recommended scopes",
+	HintCommon2: "  --domain all                    authorize all known domain scopes",
+	HintCommon3: "  --domain calendar,task          authorize calendar and task scopes",
+	HintCommon4: "  --domain calendar --recommend   authorize calendar recommended scopes",
+	HintFooter:  "  lark-cli auth login --help",
 }
 
 // getLoginMsg returns the login message bundle for the given language.
@@ -58,3 +123,10 @@ func getLoginMsg(lang i18n.Lang) *loginMsg {
 	}
 	return loginMsgZh
 }
+
+// getShortcutOnlyDomainNames returns domain names that exist only as shortcuts
+// (not backed by from_meta service specs). Descriptions are now centralized in
+// service_descriptions.json.
+func getShortcutOnlyDomainNames() []string {
+	return []string{"base", "contact", "docs", "markdown", "apps", "note"}
+}

cmd/auth/login_messages_test.go

@@ -17,8 +17,8 @@ func TestGetLoginMsg_Zh(t *testing.T) {
 	if msg != loginMsgZh {
 		t.Error("expected zh message set")
 	}
-	if msg.OpenURL != "在浏览器中打开以下链接进行认证:\n\n" {
-		t.Errorf("unexpected OpenURL: %s", msg.OpenURL)
+	if msg.SelectDomains != "选择要授权的业务域" {
+		t.Errorf("unexpected SelectDomains: %s", msg.SelectDomains)
 	}
 }
 
@@ -27,8 +27,8 @@ func TestGetLoginMsg_En(t *testing.T) {
 	if msg != loginMsgEn {
 		t.Error("expected en message set")
 	}
-	if msg.OpenURL != "Open this URL in your browser to authenticate:\n\n" {
-		t.Errorf("unexpected OpenURL: %s", msg.OpenURL)
+	if msg.SelectDomains != "Select domains to authorize" {
+		t.Errorf("unexpected SelectDomains: %s", msg.SelectDomains)
 	}
 }
 
@@ -77,6 +77,24 @@ func TestLoginMsg_FormatStrings(t *testing.T) {
 		if got == msg.AuthorizedUser {
 			t.Errorf("%s AuthorizedUser has no format verb", lang)
 		}
+
+		// SummaryDomains should contain %s
+		got = fmt.Sprintf(msg.SummaryDomains, "calendar, task")
+		if got == msg.SummaryDomains {
+			t.Errorf("%s SummaryDomains has no format verb", lang)
+		}
+
+		// SummaryPerm should contain %s
+		got = fmt.Sprintf(msg.SummaryPerm, "all")
+		if got == msg.SummaryPerm {
+			t.Errorf("%s SummaryPerm has no format verb", lang)
+		}
+
+		// SummaryScopes should contain %d and %s
+		got = fmt.Sprintf(msg.SummaryScopes, 5, "a, b, c")
+		if got == msg.SummaryScopes {
+			t.Errorf("%s SummaryScopes has no format verb", lang)
+		}
 	}
 }
 

cmd/auth/login_result.go

@@ -140,15 +140,13 @@ func writeLoginScopeBreakdown(errOut *cmdutil.IOStreams, msg *loginMsg, summary
 }
 
 // writeLoginSuccess emits the successful login payload in either JSON or text
-// format together with the computed scope breakdown. statusMessage is the
-// authorization response's status_message text (e.g. pending-approval),
-// passed through verbatim into the JSON payload; text mode does not render it.
-func writeLoginSuccess(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory, openId, userName string, summary *loginScopeSummary, statusMessage string) {
+// format together with the computed scope breakdown.
+func writeLoginSuccess(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory, openId, userName string, summary *loginScopeSummary) {
 	if summary == nil {
 		summary = &loginScopeSummary{}
 	}
 	if opts.JSON {
-		b, _ := json.Marshal(authorizationCompletePayload(openId, userName, summary, nil, statusMessage))
+		b, _ := json.Marshal(authorizationCompletePayload(openId, userName, summary, nil))
 		fmt.Fprintln(f.IOStreams.Out, string(b))
 		return
 	}
@@ -163,17 +161,14 @@ func writeLoginSuccess(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory, op
 
 // handleLoginScopeIssue prints or returns a structured missing-scope result
 // while preserving a successful login outcome when authorization completed.
-// statusMessage is the authorization response's status_message text, passed
-// through into the JSON payload when authorization actually succeeded
-// (partial grant); it is unused on the failed-login path.
-func handleLoginScopeIssue(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory, issue *loginScopeIssue, openId, userName, statusMessage string) error {
+func handleLoginScopeIssue(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory, issue *loginScopeIssue, openId, userName string) error {
 	if issue == nil {
 		return nil
 	}
 	loginSucceeded := openId != ""
 	if opts.JSON {
 		if loginSucceeded {
-			b, _ := json.Marshal(authorizationCompletePayload(openId, userName, issue.Summary, issue, statusMessage))
+			b, _ := json.Marshal(authorizationCompletePayload(openId, userName, issue.Summary, issue))
 			fmt.Fprintln(f.IOStreams.Out, string(b))
 			return output.ErrBare(output.ExitAuth)
 		}
@@ -203,13 +198,7 @@ func handleLoginScopeIssue(opts *LoginOptions, msg *loginMsg, f *cmdutil.Factory
 
 // authorizationCompletePayload builds the JSON payload for a completed login,
 // optionally attaching a warning when requested scopes are missing.
-// statusMessage is the authorization response's status_message text (e.g.
-// "user hasn't chosen yet" / "tenant doesn't allow this" / "pending
-// approval"), passed through verbatim — the CLI does not parse, classify, or
-// truncate it. The key is always present; an empty string means
-// the upstream response carried no message, matching the stable-shape
-// convention used by the other summary fields above.
-func authorizationCompletePayload(openId, userName string, summary *loginScopeSummary, issue *loginScopeIssue, statusMessage string) map[string]interface{} {
+func authorizationCompletePayload(openId, userName string, summary *loginScopeSummary, issue *loginScopeIssue) map[string]interface{} {
 	if summary == nil {
 		summary = &loginScopeSummary{}
 	}
@@ -223,7 +212,6 @@ func authorizationCompletePayload(openId, userName string, summary *loginScopeSu
 		"already_granted": emptyIfNil(summary.AlreadyGranted),
 		"missing":         emptyIfNil(summary.Missing),
 		"granted":         emptyIfNil(summary.Granted),
-		"status_message":  statusMessage,
 	}
 	if issue != nil {
 		payload["warning"] = map[string]interface{}{

cmd/auth/login_result_test.go

@@ -40,7 +40,6 @@ func TestHandleLoginScopeIssue_FailedJSON_PreservesScopeTriple(t *testing.T) {
 		},
 		"", // openId empty -> loginSucceeded = false
 		"tester",
-		"", // statusMessage unused on the failed-login path
 	)
 
 	if err == nil {
@@ -60,24 +59,3 @@ func TestHandleLoginScopeIssue_FailedJSON_PreservesScopeTriple(t *testing.T) {
 		t.Errorf("MissingScopes = %v, want %v", permErr.MissingScopes, missing)
 	}
 }
-
-// TestAuthorizationCompletePayload_StatusMessage asserts that the
-// authorization response's status_message text is passed through into the
-// JSON payload verbatim (CLI does not parse/classify/truncate it), and
-// that the field is always present, using an empty string when there is no
-// message, consistent with the stable-output-shape convention already used
-// by "scope" and the other summary fields.
-func TestAuthorizationCompletePayload_StatusMessage(t *testing.T) {
-	summary := &loginScopeSummary{Granted: []string{"a:b:c"}}
-
-	p := authorizationCompletePayload("ou_x", "u", summary, nil, "审批中，请等待管理员处理")
-	if p["status_message"] != "审批中，请等待管理员处理" {
-		t.Fatalf("status_message = %v", p["status_message"])
-	}
-
-	// No message from upstream -> stable empty string, not an absent key.
-	p2 := authorizationCompletePayload("ou_x", "u", summary, nil, "")
-	if p2["status_message"] != "" {
-		t.Fatalf("empty status_message should be \"\", got %v", p2["status_message"])
-	}
-}

cmd/auth/login_test.go

@@ -9,7 +9,7 @@ import (
 	"errors"
 	"io"
 	"net/http"
-	"reflect"
+	"slices"
 	"sort"
 	"strings"
 	"testing"
@@ -202,6 +202,25 @@ func TestSortedKnownDomains(t *testing.T) {
 	}
 }
 
+func TestGetShortcutOnlyDomainNames_HaveDescriptions(t *testing.T) {
+	for _, name := range getShortcutOnlyDomainNames() {
+		zhDesc := registry.GetServiceDescription(name, "zh")
+		enDesc := registry.GetServiceDescription(name, "en")
+		if zhDesc == "" {
+			t.Errorf("missing zh description for shortcut-only domain %q", name)
+		}
+		if enDesc == "" {
+			t.Errorf("missing en description for shortcut-only domain %q", name)
+		}
+	}
+}
+
+func TestGetShortcutOnlyDomainNames_IncludesNote(t *testing.T) {
+	if !slices.Contains(getShortcutOnlyDomainNames(), "note") {
+		t.Fatal("shortcut-only domains must include note so auth login can select vc:note:read")
+	}
+}
+
 func TestCollectScopesForDomains(t *testing.T) {
 	projects := registry.ListFromMetaProjects()
 	if len(projects) == 0 {
@@ -241,81 +260,74 @@ func TestCollectScopesForDomains_NonexistentDomain(t *testing.T) {
 	}
 }
 
-func TestResolveScopesForDomains_RemoteUsed(t *testing.T) {
-	remote := map[string][]string{
-		"im":   {"im:message:send", "im:chat:read"},
-		"docs": {"docs:doc:read"},
+func TestGetDomainMetadata_IncludesFromMeta(t *testing.T) {
+	domains := getDomainMetadata("zh")
+	nameSet := make(map[string]bool)
+	for _, dm := range domains {
+		nameSet[dm.Name] = true
 	}
-	got := resolveScopesForDomains([]string{"im"}, remote, true, core.BrandFeishu)
-	want := []string{"im:chat:read", "im:message:send"} // deduped, ascending by sort.Strings
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("got %v, want %v", got, want)
-	}
-}
 
-func TestResolveScopesForDomains_UnionAcrossDomains(t *testing.T) {
-	remote := map[string][]string{
-		"im":   {"im:message:send"},
-		"docs": {"docs:doc:read"},
-	}
-	got := resolveScopesForDomains([]string{"im", "docs"}, remote, true, core.BrandFeishu)
-	want := []string{"docs:doc:read", "im:message:send"}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("got %v, want %v", got, want)
-	}
-}
-
-func TestResolveScopesForDomains_FallbackToLocal(t *testing.T) {
-	// remoteOK=false -> falls back to local collectScopesForDomains; im must yield non-empty local scopes
-	got := resolveScopesForDomains([]string{"im"}, nil, false, core.BrandFeishu)
-	if len(got) == 0 {
-		t.Fatal("fallback should return non-empty local scopes for im")
-	}
-}
-
-func TestLegalDomainsFor_RemoteUsed(t *testing.T) {
-	// includes "newbiz", a domain unknown to this CLI build, verifying a remote-listed domain is still legal
-	remote := map[string][]string{
-		"im":     {"im:message:send"},
-		"docs":   {"docs:doc:read"},
-		"newbiz": {"newbiz:thing:read"},
-	}
-	set, sorted := legalDomainsFor(remote, true, core.BrandFeishu)
-	wantSorted := []string{"docs", "im", "newbiz"} // remote keys, ascending by sort.Strings
-	if !reflect.DeepEqual(sorted, wantSorted) {
-		t.Fatalf("sorted = %v, want %v", sorted, wantSorted)
-	}
-	if len(set) != len(wantSorted) {
-		t.Fatalf("set size = %d, want %d", len(set), len(wantSorted))
-	}
-	for _, d := range wantSorted {
-		if !set[d] {
-			t.Errorf("set missing domain %q", d)
+	// from_meta projects must be present
+	for _, p := range registry.ListFromMetaProjects() {
+		if !nameSet[p] {
+			t.Errorf("from_meta project %q missing from getDomainMetadata", p)
 		}
 	}
-	if !set["newbiz"] {
-		t.Error("remote-listed domain unknown to this build should still be legal")
+}
+
+func TestGetDomainMetadata_IncludesShortcutOnlyDomains(t *testing.T) {
+	domains := getDomainMetadata("zh")
+	nameSet := make(map[string]bool)
+	for _, dm := range domains {
+		nameSet[dm.Name] = true
+	}
+
+	for _, name := range getShortcutOnlyDomainNames() {
+		if !nameSet[name] {
+			t.Errorf("shortcut-only domain %q missing from getDomainMetadata", name)
+		}
 	}
 }
 
-func TestLegalDomainsFor_FallbackToLocal(t *testing.T) {
-	// remoteOK=false -> falls back to local allKnownDomains/sortedKnownDomains
-	set, sorted := legalDomainsFor(nil, false, core.BrandFeishu)
-	if len(sorted) == 0 {
-		t.Fatal("fallback should return non-empty local domain slice")
-	}
-	// set and sorted are two views of the same local domain set and must correspond
-	if len(set) != len(sorted) {
-		t.Fatalf("set size %d != sorted size %d", len(set), len(sorted))
-	}
-	for _, d := range sorted {
-		if !set[d] {
-			t.Errorf("set missing local domain %q", d)
+func TestGetDomainMetadata_Sorted(t *testing.T) {
+	domains := getDomainMetadata("zh")
+	for i := 1; i < len(domains); i++ {
+		if domains[i].Name < domains[i-1].Name {
+			t.Errorf("not sorted: %q before %q", domains[i-1].Name, domains[i].Name)
 		}
 	}
-	// fallback adopts the local sort order directly, which must equal sortedKnownDomains
-	if want := sortedKnownDomains(core.BrandFeishu); !reflect.DeepEqual(sorted, want) {
-		t.Fatalf("sorted = %v, want sortedKnownDomains %v", sorted, want)
+}
+
+func TestGetDomainMetadata_HasTitleAndDescription(t *testing.T) {
+	domains := getDomainMetadata("zh")
+	for _, dm := range domains {
+		if dm.Title == "" {
+			t.Errorf("domain %q has empty Title", dm.Name)
+		}
+	}
+}
+
+func TestAuthLoginRun_NonTerminal_NoFlags_RejectsWithHint(t *testing.T) {
+	f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "cli_test", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	// TestFactory has IsTerminal=false by default
+	opts := &LoginOptions{Factory: f, Ctx: context.Background()}
+	err := authLoginRun(opts)
+	if err == nil {
+		t.Fatal("expected error for non-terminal without flags")
+	}
+	// Should mention specifying scopes
+	msg := err.Error()
+	if !strings.Contains(msg, "scopes") {
+		t.Errorf("expected error to mention scopes, got: %s", msg)
+	}
+	// Stderr should explain the split-flow path for non-streaming agents.
+	stderrStr := stderr.String()
+	for _, want := range []string{"--no-wait --json", "final message of the turn", "--device-code"} {
+		if !strings.Contains(stderrStr, want) {
+			t.Errorf("expected stderr to mention %q, got: %s", want, stderrStr)
+		}
 	}
 }
 
@@ -364,7 +376,7 @@ func TestWriteLoginSuccess_JSONIncludesScopeDiff(t *testing.T) {
 		NewlyGranted:   []string{"im:message:send"},
 		AlreadyGranted: []string{"im:message:reply"},
 		Granted:        []string{"im:message:send", "im:message:reply"},
-	}, "")
+	})
 
 	var data map[string]interface{}
 	if err := json.Unmarshal(stdout.Bytes(), &data); err != nil {
@@ -394,7 +406,7 @@ func TestHandleLoginScopeIssue_NonJSONAlignsWithLoginSuccess(t *testing.T) {
 			Missing:   []string{"im:message:send"},
 			Granted:   []string{"base:app:copy"},
 		},
-	}, "ou_user", "tester", "")
+	}, "ou_user", "tester")
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
@@ -436,7 +448,7 @@ func TestHandleLoginScopeIssue_JSONAlignsWithLoginSuccess(t *testing.T) {
 			Missing:   []string{"im:message:send"},
 			Granted:   []string{"base:app:copy"},
 		},
-	}, "ou_user", "tester", "")
+	}, "ou_user", "tester")
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
@@ -468,7 +480,7 @@ func TestWriteLoginSuccess_JSONEmptySlicesNotNull(t *testing.T) {
 
 	writeLoginSuccess(&LoginOptions{JSON: true}, getLoginMsg("en"), f, "ou_user", "tester", &loginScopeSummary{
 		Granted: []string{"offline_access"},
-	}, "")
+	})
 
 	var data map[string]interface{}
 	if err := json.Unmarshal(stdout.Bytes(), &data); err != nil {
@@ -553,7 +565,7 @@ func TestWriteLoginSuccess_TextOutputScenarios(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-			writeLoginSuccess(&LoginOptions{}, getLoginMsg("zh"), f, "ou_user", "tester", tt.summary, "")
+			writeLoginSuccess(&LoginOptions{}, getLoginMsg("zh"), f, "ou_user", "tester", tt.summary)
 
 			got := stderr.String()
 			for _, want := range tt.expectedPresent {
@@ -807,7 +819,7 @@ func TestWriteLoginSuccess_TextOutputEnglishIncludesStatusHintWhenNoMissingScope
 		Requested:    []string{"im:message:send"},
 		NewlyGranted: []string{"im:message:send"},
 		Granted:      []string{"im:message:send"},
-	}, "")
+	})
 
 	got := stderr.String()
 	for _, want := range []string{
@@ -1155,6 +1167,15 @@ func TestAuthLoginRun_JSONDeviceAuthorizationAgentHintIncludesRawURLGuidance(t *
 	}
 }
 
+func TestGetDomainMetadata_ExcludesEvent(t *testing.T) {
+	domains := getDomainMetadata("zh")
+	for _, dm := range domains {
+		if dm.Name == "event" {
+			t.Error("event should not appear in interactive domain list")
+		}
+	}
+}
+
 func TestAllKnownDomains_ExcludesAuthDomainChildren(t *testing.T) {
 	domains := allKnownDomains("")
 	if domains["whiteboard"] {
@@ -1179,3 +1200,12 @@ func TestCollectScopesForDomains_ExpandsAuthDomainChildren(t *testing.T) {
 		t.Error("collectScopesForDomains([docs]) should include whiteboard scopes (board:whiteboard:*)")
 	}
 }
+
+func TestGetDomainMetadata_ExcludesAuthDomainChildren(t *testing.T) {
+	domains := getDomainMetadata("zh")
+	for _, dm := range domains {
+		if dm.Name == "whiteboard" {
+			t.Error("whiteboard should not appear in interactive domain list (has auth_domain=docs)")
+		}
+	}
+}

cmd/root.go

@@ -679,7 +679,11 @@ func installTipsHelpFunc(root *cobra.Command) {
 			defaultHelp(cmd, args)
 			return
 		}
-		if service.PrepareMethodHelp(cmd) {
+		if service.PrepareMethodHelp(cmd, embeddedSkillContent) {
+			defaultHelp(cmd, args)
+			return
+		}
+		if service.PrepareShortcutHelp(cmd, embeddedSkillContent) {
 			defaultHelp(cmd, args)
 			return
 		}

cmd/service/affordance.go

@@ -71,11 +71,18 @@ func PrepareDomainHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 }
 
 // domainHelpBase returns the description to seed domain help with — the
-// hand-authored Long when present, else the Short — captured once into an
-// annotation so re-rendering reuses the pristine text instead of the
-// already-augmented Long.
+// hand-authored Long when present, else the Short.
 func domainHelpBase(cmd *cobra.Command) string {
-	if base, ok := cmd.Annotations[domainBaseAnnotation]; ok {
+	return captureHelpBase(cmd, domainBaseAnnotation)
+}
+
+// captureHelpBase records a command's pristine lead text once — its
+// hand-authored Long, or Short when Long is empty — into the given annotation,
+// so lazy re-renders compose onto the original text instead of onto an
+// already-augmented Long. This is what lets a shortcut's PostMount-authored
+// Long survive: it becomes the base the affordance block is appended below.
+func captureHelpBase(cmd *cobra.Command, key string) string {
+	if base, ok := cmd.Annotations[key]; ok {
 		return base
 	}
 	base := cmd.Long
@@ -85,7 +92,7 @@ func domainHelpBase(cmd *cobra.Command) string {
 	if cmd.Annotations == nil {
 		cmd.Annotations = map[string]string{}
 	}
-	cmd.Annotations[domainBaseAnnotation] = base
+	cmd.Annotations[key] = base
 	return base
 }
 
@@ -101,12 +108,12 @@ func methodLong(description, schemaPath, paramsOnly string) string {
 }
 
 // Annotation keys PrepareMethodHelp reads to rebuild a method command's Long.
+// The affordance overlay coordinates live in cmdmeta (shared with shortcuts).
 const (
-	affordanceServiceAnnotation = "affordance-service"
-	affordanceMethodAnnotation  = "affordance-method"
-	schemaPathAnnotation        = "method-schema-path"
-	paramsOnlyAnnotation        = "method-params-only"
-	domainBaseAnnotation        = "affordance-domain-base"
+	schemaPathAnnotation   = "method-schema-path"
+	paramsOnlyAnnotation   = "method-params-only"
+	domainBaseAnnotation   = "affordance-domain-base"
+	shortcutBaseAnnotation = "affordance-shortcut-base"
 )
 
 // setMethodHelpData records the coordinates PrepareMethodHelp needs (storing a
@@ -115,10 +122,7 @@ func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, params
 	if cmd.Annotations == nil {
 		cmd.Annotations = map[string]string{}
 	}
-	if service != "" && methodID != "" {
-		cmd.Annotations[affordanceServiceAnnotation] = service
-		cmd.Annotations[affordanceMethodAnnotation] = methodID
-	}
+	cmdmeta.SetAffordanceRef(cmd, service, methodID)
 	cmd.Annotations[schemaPathAnnotation] = schemaPath
 	if paramsOnly != "" {
 		cmd.Annotations[paramsOnlyAnnotation] = paramsOnly
@@ -128,8 +132,11 @@ func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, params
 // PrepareMethodHelp rebuilds a generated method command's Long with the agent
 // guidance at the TOP (Risk, then the affordance block, then the schema
 // pointer), returning false for non-method commands. The overlay is parsed
-// here — only when help is rendered.
-func PrepareMethodHelp(cmd *cobra.Command) bool {
+// here — only when help is rendered. skillFS (nil-safe) gates the related-skill
+// pointers: each is emitted only when it resolves in the skill tree (see
+// affordance.SkillStatPath), so a typo or a build without embedded skills never
+// prints a `skills read` that cannot be opened.
+func PrepareMethodHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 	ann := cmd.Annotations
 	if ann == nil {
 		return false
@@ -141,22 +148,15 @@ func PrepareMethodHelp(cmd *cobra.Command) bool {
 
 	var b strings.Builder
 	b.WriteString(cmd.Short)
-	if level, ok := cmdutil.GetRisk(cmd); ok {
-		// --yes asserts the USER confirmed; the agent must not self-approve.
-		if level == cmdutil.RiskHighRiskWrite {
-			fmt.Fprintf(&b, "\n\nRisk: %s (requires explicit user confirmation to execute; the agent must NOT add --yes on its own — only pass --yes after the user has confirmed)", level)
-		} else {
-			fmt.Fprintf(&b, "\n\nRisk: %s", level)
-		}
-	}
+	writeRisk(&b, cmd)
 
 	var skills []string
 	if raw, ok := affordanceRaw(cmd); ok {
-		if block := renderAffordance(meta.Method{Affordance: raw}); block != "" {
-			b.WriteString("\n\n")
-			b.WriteString(block)
-		}
 		if a, ok := (meta.Method{Affordance: raw}).ParsedAffordance(); ok {
+			if block := renderAffordanceValue(a); block != "" {
+				b.WriteString("\n\n")
+				b.WriteString(block)
+			}
 			skills = a.Skills
 		}
 	}
@@ -164,17 +164,95 @@ func PrepareMethodHelp(cmd *cobra.Command) bool {
 	fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
 	b.WriteString(ann[paramsOnlyAnnotation])
 
-	if len(skills) > 0 {
-		b.WriteString("\n\nWorkflow skill (end-to-end usage):")
-		for _, s := range skills {
-			fmt.Fprintf(&b, "\n  lark-cli skills read %s", s)
-		}
-	}
+	writeRelatedSkills(&b, skills, skillFS)
 
 	cmd.Long = b.String()
 	return true
 }
 
+// PrepareShortcutHelp composes a +-prefixed shortcut's Long from its affordance
+// overlay — the same top layout as method help (description, Risk, guidance
+// block, related skills) minus the schema pointer, which shortcuts have none
+// of. Returns false when the command is not a shortcut or carries no overlay
+// entry, so shortcuts without guidance keep the default help plus the bottom
+// risk/tips append.
+//
+// The lead is the command's pristine base (captureHelpBase): a shortcut that
+// set a hand-authored Long in PostMount (e.g. the docs shortcuts' "agents MUST
+// read the skill" directive) keeps it — the affordance block is appended below,
+// never clobbering it.
+//
+// Tips precedence (intentional, not a bug): the overlay's ### Tips win. The
+// shortcut's declarative Tips (the Go Tips field) are only a fallback used when
+// the overlay declares none; when the overlay has tips, the Go tips are dropped
+// (replaced, not merged) so tips never render twice. Authoring a ### Tips block
+// therefore silently retires that shortcut's Go Tips — consolidate into one.
+func PrepareShortcutHelp(cmd *cobra.Command, skillFS fs.FS) bool {
+	if src, _ := cmdmeta.SourceOf(cmd); src != cmdmeta.SourceShortcut {
+		return false
+	}
+	raw, ok := affordanceRaw(cmd)
+	if !ok {
+		return false
+	}
+	a, ok := (meta.Method{Affordance: raw}).ParsedAffordance()
+	if !ok {
+		return false
+	}
+	if len(a.Tips) == 0 {
+		a.Tips = cmdutil.GetTips(cmd)
+	}
+
+	var b strings.Builder
+	b.WriteString(captureHelpBase(cmd, shortcutBaseAnnotation))
+	writeRisk(&b, cmd)
+	if block := renderAffordanceValue(a); block != "" {
+		b.WriteString("\n\n")
+		b.WriteString(block)
+	}
+	writeRelatedSkills(&b, a.Skills, skillFS)
+
+	cmd.Long = b.String()
+	return true
+}
+
+// writeRisk appends the "Risk: <level>" line, warning agents not to self-approve
+// high-risk-write commands. A no-op when the command has no risk annotation.
+func writeRisk(b *strings.Builder, cmd *cobra.Command) {
+	level, ok := cmdutil.GetRisk(cmd)
+	if !ok {
+		return
+	}
+	// --yes asserts the USER confirmed; the agent must not self-approve.
+	if level == cmdutil.RiskHighRiskWrite {
+		fmt.Fprintf(b, "\n\nRisk: %s (requires explicit user confirmation to execute; the agent must NOT add --yes on its own — only pass --yes after the user has confirmed)", level)
+	} else {
+		fmt.Fprintf(b, "\n\nRisk: %s", level)
+	}
+}
+
+// writeRelatedSkills appends the "Related skills" block for the entries that
+// exist in skillFS. Nothing is written when skillFS is nil or no entry resolves,
+// so help never prints a `skills read` pointer that cannot be opened.
+func writeRelatedSkills(b *strings.Builder, skills []string, skillFS fs.FS) {
+	if skillFS == nil || len(skills) == 0 {
+		return
+	}
+	var avail []string
+	for _, s := range skills {
+		if _, err := fs.Stat(skillFS, affordance.SkillStatPath(s)); err == nil {
+			avail = append(avail, s)
+		}
+	}
+	if len(avail) == 0 {
+		return
+	}
+	b.WriteString("\n\nRelated skills (read for end-to-end usage):")
+	for _, s := range avail {
+		fmt.Fprintf(b, "\n  lark-cli skills read %s", s)
+	}
+}
+
 // affordanceLookup is the overlay source; a package var so tests can inject.
 var affordanceLookup = affordance.For
 
@@ -189,12 +267,8 @@ func RenderAffordanceForCmd(cmd *cobra.Command) string {
 }
 
 func affordanceRaw(cmd *cobra.Command) (json.RawMessage, bool) {
-	if cmd.Annotations == nil {
-		return nil, false
-	}
-	service := cmd.Annotations[affordanceServiceAnnotation]
-	methodID := cmd.Annotations[affordanceMethodAnnotation]
-	if service == "" || methodID == "" {
+	service, methodID, ok := cmdmeta.AffordanceRef(cmd)
+	if !ok {
 		return nil, false
 	}
 	return affordanceLookup(service, methodID)
@@ -207,7 +281,13 @@ func renderAffordance(m meta.Method) string {
 	if !ok {
 		return ""
 	}
+	return renderAffordanceValue(a)
+}
 
+// renderAffordanceValue renders an already-parsed affordance. Split from
+// renderAffordance so callers can render a value they have adjusted first (e.g.
+// a shortcut folding its declarative tips into an overlay that has none).
+func renderAffordanceValue(a meta.Affordance) string {
 	var sections []string
 	bullets := func(title string, items []string) {
 		var nonEmpty []string

cmd/service/affordance_test.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"strings"
 	"testing"
+	"testing/fstest"
 
 	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -70,8 +71,8 @@ func TestServiceMethod_AffordanceNotInLong(t *testing.T) {
 		t.Errorf("affordance must not be baked into Long (lazy):\n%s", cmd.Long)
 	}
 	// The lookup ref is recorded so the help path can resolve it later.
-	if cmd.Annotations[affordanceServiceAnnotation] != "im" || cmd.Annotations[affordanceMethodAnnotation] != "messages.create" {
-		t.Errorf("affordance ref annotations = %v, want im/messages.create", cmd.Annotations)
+	if svc, method, ok := cmdmeta.AffordanceRef(cmd); !ok || svc != "im" || method != "messages.create" {
+		t.Errorf("affordance ref = %q/%q (ok=%v), want im/messages.create", svc, method, ok)
 	}
 }
 
@@ -119,7 +120,7 @@ func TestPrepareMethodHelp(t *testing.T) {
 	m := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息"}
 	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
 
-	if !PrepareMethodHelp(cmd) {
+	if !PrepareMethodHelp(cmd, nil) {
 		t.Fatal("PrepareMethodHelp returned false for a service-method command")
 	}
 	long := cmd.Long
@@ -136,11 +137,133 @@ func TestPrepareMethodHelp(t *testing.T) {
 	}
 
 	// A non-service command (no schema-path annotation) is left untouched.
-	if PrepareMethodHelp(&cobra.Command{Use: "plain"}) {
+	if PrepareMethodHelp(&cobra.Command{Use: "plain"}, nil) {
 		t.Error("PrepareMethodHelp should return false for a non-service command")
 	}
 }
 
+// PrepareShortcutHelp composes a shortcut's Long from its overlay with the same
+// top layout as method help (no schema pointer), folding declarative tips when
+// the overlay declares none, and leaves shortcuts without an overlay entry (and
+// non-shortcut commands) for the default help path.
+func TestPrepareShortcutHelp(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(service, methodID string) (json.RawMessage, bool) {
+		if service == "calendar" && methodID == "+create" {
+			return json.RawMessage(`{"use_when":["高层创建日程"],"skills":["lark-calendar"]}`), true
+		}
+		return nil, false
+	}
+
+	sc := &cobra.Command{Use: "+create", Short: "Create an event"}
+	cmdmeta.SetSource(sc, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetAffordanceRef(sc, "calendar", "+create")
+	cmdutil.SetRisk(sc, "write")
+	cmdutil.SetTips(sc, []string{"start/end 收 ISO 8601"})
+
+	if !PrepareShortcutHelp(sc, nil) {
+		t.Fatal("PrepareShortcutHelp returned false for a shortcut with an overlay")
+	}
+	for _, want := range []string{"Create an event", "Risk: write", "When to use:", "高层创建日程", "Tips:", "start/end 收 ISO 8601"} {
+		if !strings.Contains(sc.Long, want) {
+			t.Errorf("shortcut Long missing %q:\n%s", want, sc.Long)
+		}
+	}
+	if strings.Contains(sc.Long, "Full parameter schema:") {
+		t.Errorf("shortcut Long must not carry a schema pointer:\n%s", sc.Long)
+	}
+
+	// No overlay entry -> leave it for the default help path.
+	bare := &cobra.Command{Use: "+bare", Short: "x"}
+	cmdmeta.SetSource(bare, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetAffordanceRef(bare, "calendar", "+bare")
+	if PrepareShortcutHelp(bare, nil) {
+		t.Error("PrepareShortcutHelp should return false when the shortcut has no overlay")
+	}
+
+	// Non-shortcut source is ignored even with a ref.
+	notSc := &cobra.Command{Use: "create", Short: "x"}
+	cmdmeta.SetAffordanceRef(notSc, "calendar", "+create")
+	if PrepareShortcutHelp(notSc, nil) {
+		t.Error("PrepareShortcutHelp should return false for a non-shortcut command")
+	}
+}
+
+// Related-skill pointers are gated on existence: a skill that resolves in the
+// skill FS renders, a typo is dropped (never print an unopenable `skills read`),
+// and a nil skill FS suppresses the whole block.
+func TestRelatedSkillsStatGating(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
+		return json.RawMessage(`{"use_when":["x"],"skills":["lark-real","lark-typo","lark-real/references/deep.md","lark-real/references/missing.md"]}`), true
+	}
+	skillFS := fstest.MapFS{
+		"lark-real/SKILL.md":           {Data: []byte("# real")},
+		"lark-real/references/deep.md": {Data: []byte("# deep")},
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	m := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "d"}
+
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
+	if !PrepareMethodHelp(cmd, skillFS) {
+		t.Fatal("PrepareMethodHelp returned false")
+	}
+	if !strings.Contains(cmd.Long, "skills read lark-real\n") {
+		t.Errorf("existing bare-name skill should render on its own line; got:\n%s", cmd.Long)
+	}
+	if strings.Contains(cmd.Long, "lark-typo") {
+		t.Errorf("nonexistent skill must be dropped, not printed as an unopenable pointer; got:\n%s", cmd.Long)
+	}
+	// A name/relpath reference to an existing file renders; a missing one drops.
+	if !strings.Contains(cmd.Long, "skills read lark-real/references/deep.md") {
+		t.Errorf("existing reference entry should render; got:\n%s", cmd.Long)
+	}
+	if strings.Contains(cmd.Long, "references/missing.md") {
+		t.Errorf("nonexistent reference must be dropped; got:\n%s", cmd.Long)
+	}
+
+	// nil skill FS: the whole Related-skills block is suppressed.
+	bare := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
+	PrepareMethodHelp(bare, nil)
+	if strings.Contains(bare.Long, "Related skills") {
+		t.Errorf("nil skillFS should suppress the skills block; got:\n%s", bare.Long)
+	}
+}
+
+// A shortcut that set a hand-authored Long (as the docs shortcuts do in
+// PostMount) keeps it as the lead: the affordance block is appended below, not
+// clobbered, and re-rendering does not double-append.
+func TestPrepareShortcutHelp_PreservesPostMountLong(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
+		return json.RawMessage(`{"use_when":["高层创建日程"]}`), true
+	}
+
+	const authored = "Custom docs help. AI agents MUST read the skill first."
+	sc := &cobra.Command{Use: "+create", Short: "Create", Long: authored}
+	cmdmeta.SetSource(sc, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetAffordanceRef(sc, "calendar", "+create")
+
+	if !PrepareShortcutHelp(sc, nil) {
+		t.Fatal("PrepareShortcutHelp returned false for a shortcut with an overlay")
+	}
+	if !strings.HasPrefix(sc.Long, authored) {
+		t.Errorf("hand-authored Long must lead, not be clobbered; got:\n%s", sc.Long)
+	}
+	if !strings.Contains(sc.Long, "When to use:") {
+		t.Errorf("affordance block should be appended below the base; got:\n%s", sc.Long)
+	}
+	// Re-render must reuse the captured base, not append the block twice.
+	PrepareShortcutHelp(sc, nil)
+	if n := strings.Count(sc.Long, "When to use:"); n != 1 {
+		t.Errorf("affordance appended %d times across re-renders, want 1:\n%s", n, sc.Long)
+	}
+}
+
 // domainCmd wires a domain-tagged command with a subcommand under a root, the
 // shape PrepareDomainHelp expects.
 func domainCmd(short, long string) *cobra.Command {

cmd/service/service_test.go

@@ -4,10 +4,14 @@
 package service
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
+	"mime"
+	"mime/multipart"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -1132,6 +1136,63 @@ func TestDetectFileFields(t *testing.T) {
 	}
 }
 
+// parseMultipartFilenames drives one service-method --file upload through the
+// mock transport and returns a map of field name -> part filename parsed from
+// the captured multipart body. Mirrors cmd/api's helper of the same name
+// (inlined here rather than shared, since the two live in different packages)
+// to give BuildFormdata's shared local-file fix a second real entry-point
+// covering it.
+func parseMultipartFilenames(t *testing.T, stub *httpmock.Stub) map[string]string {
+	t.Helper()
+	ct := stub.CapturedHeaders.Get("Content-Type")
+	mediaType, params, err := mime.ParseMediaType(ct)
+	if err != nil {
+		t.Fatalf("parse Content-Type %q: %v", ct, err)
+	}
+	if !strings.HasPrefix(mediaType, "multipart/") {
+		t.Fatalf("Content-Type = %q, want multipart/*", mediaType)
+	}
+	filenames := map[string]string{}
+	mr := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
+	for {
+		part, err := mr.NextPart()
+		if err != nil {
+			break
+		}
+		if fn := part.FileName(); fn != "" {
+			filenames[part.FormName()] = fn
+		}
+	}
+	return filenames
+}
+
+func TestServiceMethod_FileUpload_PreservesFilename(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, testConfig)
+
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile(filepath.Join(dir, "photo.jpg"), []byte("fake-image"), 0600); err != nil {
+		t.Fatalf("write test file: %v", err)
+	}
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/im/v1/images",
+		Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"image_key": "img_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdServiceMethod(f, imSpec(), imImageMethod(), "create", "images", nil)
+	cmd.SetArgs([]string{"--file", "photo.jpg", "--data", `{"image_type":"message"}`, "--as", "bot"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames := parseMultipartFilenames(t, stub)
+	if got := filenames["image"]; got != "photo.jpg" {
+		t.Fatalf("part filename for field %q = %q, want %q", "image", got, "photo.jpg")
+	}
+}
+
 func TestServiceMethod_JsonFlag_Accepted(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
 

go.mod

@@ -10,7 +10,7 @@ require (
 	github.com/gofrs/flock v0.8.1
 	github.com/google/uuid v1.6.0
 	github.com/itchyny/gojq v0.12.17
-	github.com/larksuite/oapi-sdk-go/v3 v3.5.4
+	github.com/larksuite/oapi-sdk-go/v3 v3.7.2
 	github.com/sergi/go-diff v1.4.0
 	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
 	github.com/smartystreets/goconvey v1.8.1

go.sum

@@ -79,8 +79,8 @@ github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORN
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
-github.com/larksuite/oapi-sdk-go/v3 v3.5.4 h1:U2S9x9LrfH++ZqJ+YAiUlqzCWJmVXhFdS8Z7rIBH8H0=
-github.com/larksuite/oapi-sdk-go/v3 v3.5.4/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
+github.com/larksuite/oapi-sdk-go/v3 v3.7.2 h1:SCIcXHRmtpQbiaZgDTDi1NYNCzrusi7ePJBR9uKoduE=
+github.com/larksuite/oapi-sdk-go/v3 v3.7.2/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
 github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
 github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=

internal/affordance/affordance.go

@@ -83,10 +83,9 @@ func commandFormResolver(service string) func(string) string {
 		}
 	}
 	return func(h string) string {
-		h = strings.TrimSpace(h)
-		if id, ok := byForm[h]; ok {
+		if id, ok := byForm[strings.TrimSpace(h)]; ok {
 			return id
 		}
-		return strings.ReplaceAll(h, " ", ".")
+		return headingToKey(h) // one home for the shortcut/method key convention
 	}
 }

internal/affordance/affordance_test.go

@@ -7,6 +7,8 @@ import (
 	"encoding/json"
 	"testing"
 	"testing/fstest"
+
+	"github.com/larksuite/cli/internal/meta"
 )
 
 // fixtureMD is a minimal affordance source: two methods, each with a lead
@@ -84,3 +86,38 @@ func TestParseDomainMD_ParagraphNotDropped(t *testing.T) {
 		t.Errorf("custom-section paragraph not flowed through: %+v", a.Extensions)
 	}
 }
+
+// The ### Skills section merges with the domain `> skill:` default: domain
+// first, then per-command entries, de-duplicated. A command with no ### Skills
+// still inherits the domain default.
+func TestParseDomainMD_SkillsMerge(t *testing.T) {
+	md := "# d\n> skill: lark-d\n\n" +
+		"## foo\ndoes foo.\n\n### Skills\n- lark-workflow\n- lark-d\n\n" + // lark-d duplicates the domain default
+		"## bar\ndoes bar.\n"
+	got := parseDomainMD([]byte(md), nil)
+
+	if a := got["foo"]; len(a.Skills) != 2 || a.Skills[0] != "lark-d" || a.Skills[1] != "lark-workflow" {
+		t.Errorf("foo skills = %v, want [lark-d lark-workflow] (domain first, deduped)", a.Skills)
+	}
+	if a := got["bar"]; len(a.Skills) != 1 || a.Skills[0] != "lark-d" {
+		t.Errorf("bar skills = %v, want [lark-d] (domain default inherited)", a.Skills)
+	}
+}
+
+// A +-prefixed shortcut heading keys verbatim (no space->dot folding), so it
+// matches the shortcut command as mounted.
+func TestParseDomainMD_ShortcutHeadingVerbatim(t *testing.T) {
+	md := "# d\n\n## +create\ncreate via shortcut.\n"
+	got := parseDomainMD([]byte(md), nil)
+	if _, ok := got["+create"]; !ok {
+		t.Errorf("shortcut heading should key as %q; got keys %v", "+create", keysOf(got))
+	}
+}
+
+func keysOf(m map[string]meta.Affordance) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}

internal/affordance/mdparse.go

@@ -19,6 +19,7 @@ import (
 //	### Prerequisites   -> prerequisites   (a "…来自 [[x]]" link is a sequence edge)
 //	### Tips            -> tips
 //	### Examples        -> examples: **description** + a ```fenced``` command
+//	### Skills          -> skills: bullet skill names, added to the domain default
 //	### <other>         -> extensions[] (custom section, flows through verbatim)
 //	[[cmd]]             -> a command reference, rendered as `cmd`
 //
@@ -34,16 +35,56 @@ var standardSection = map[string]string{
 	"Prerequisites": "prerequisites",
 	"Tips":          "tips",
 	"Examples":      "examples",
+	"Skills":        "skills",
+}
+
+// mergeSkills returns the domain-default skill followed by a command's own skill
+// entries, de-duplicated in author order and empties dropped. Backticks (left by
+// the shared bullet parse) are stripped so each entry is a bare skill name.
+func mergeSkills(domain string, extra []string) []string {
+	var out []string
+	seen := map[string]bool{}
+	add := func(s string) {
+		s = strings.Trim(strings.TrimSpace(s), "`")
+		if s == "" || seen[s] {
+			return
+		}
+		seen[s] = true
+		out = append(out, s)
+	}
+	add(domain)
+	for _, s := range extra {
+		add(s)
+	}
+	return out
 }
 
 func linkToBacktick(s string) string { return mdLink.ReplaceAllString(s, "`$1`") }
 
+// SkillStatPath maps a `### Skills` entry to the path (relative to the skill
+// tree) whose existence gates it: a bare skill name resolves to its SKILL.md,
+// while an entry containing a slash is a name/relative-path reference (e.g.
+// "lark-contact/references/lark-contact-search-user.md") and resolves to that
+// path directly. Both render as `lark-cli skills read <entry>` — the slash form
+// skills read already accepts — so a per-command entry can point at that
+// command's own reference file, not just re-point the domain skill.
+func SkillStatPath(entry string) string {
+	if strings.Contains(entry, "/") {
+		return entry
+	}
+	return entry + "/SKILL.md"
+}
+
 // headingToKey maps a command heading ("instances get") to its affordance key
 // ("instances.get"). The space→dot rule holds where the command form matches
 // the method id; domains whose resource names differ (e.g. plural "messages"
 // vs id segment "message") need the registry's authoritative resource↔id table.
 func headingToKey(h string) string {
-	return strings.ReplaceAll(strings.TrimSpace(h), " ", ".")
+	h = strings.TrimSpace(h)
+	if strings.HasPrefix(h, "+") { // shortcut command: key is the command verbatim
+		return h
+	}
+	return strings.ReplaceAll(h, " ", ".")
 }
 
 type mdSection struct {
@@ -82,6 +123,7 @@ func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affo
 		if len(useWhen) > 0 {
 			a.UseWhen = useWhen
 		}
+		var perCmdSkills []string
 		for _, s := range secs {
 			switch standardSection[s.label] {
 			case "avoid_when":
@@ -92,12 +134,14 @@ func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affo
 				a.Tips = s.items
 			case "examples":
 				a.Examples = s.cases
+			case "skills":
+				perCmdSkills = s.items
 			default:
 				a.Extensions = append(a.Extensions, meta.AffordanceSection{Label: s.label, Items: s.items})
 			}
 		}
-		if skill != "" {
-			a.Skills = []string{skill}
+		if s := mergeSkills(skill, perCmdSkills); len(s) > 0 {
+			a.Skills = s
 		}
 		out[curKey] = a
 	}
@@ -157,7 +201,7 @@ func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affo
 				inFence, fence = true, nil
 			} else {
 				inFence = false
-				sec.cases = append(sec.cases, meta.AffordanceCase{Description: pending, Command: strings.Join(fence, "\n")})
+				sec.cases = append(sec.cases, meta.AffordanceCase{Description: linkToBacktick(pending), Command: strings.Join(fence, "\n")})
 				pending = ""
 			}
 			continue

internal/auth/device_flow.go

@@ -34,7 +34,6 @@ type DeviceFlowTokenData struct {
 	ExpiresIn        int
 	RefreshExpiresIn int
 	Scope            string
-	StatusMessage    string // authorization result text from the response's status_message (e.g. pending-approval); passed through verbatim, not parsed
 }
 
 // DeviceFlowResult is the result of polling the token endpoint.
@@ -223,7 +222,6 @@ func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSec
 					ExpiresIn:        tokenExpiresIn,
 					RefreshExpiresIn: refreshExpiresIn,
 					Scope:            getStr(data, "scope"),
-					StatusMessage:    getStr(data, "status_message"),
 				},
 			}
 		}

internal/auth/device_flow_test.go

@@ -216,34 +216,3 @@ func TestPollDeviceToken_DefaultsZeroIntervalToFiveSeconds(t *testing.T) {
 		t.Fatalf("PollDeviceToken() sent %d requests before context cancellation, want 0", got)
 	}
 }
-
-// TestPollDeviceToken_SuccessIncludesStatusMessage asserts that the success
-// branch reads the token response's status_message field verbatim into
-// DeviceFlowTokenData.StatusMessage. The CLI is a pure passthrough here — no
-// parsing/classification of the text.
-func TestPollDeviceToken_SuccessIncludesStatusMessage(t *testing.T) {
-	t.Parallel()
-
-	reg := &httpmock.Registry{}
-	t.Cleanup(func() { reg.Verify(t) })
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    PathOAuthTokenV2,
-		Body: map[string]interface{}{
-			"access_token":             "test-token",
-			"refresh_token":            "test-token",
-			"expires_in":               7200,
-			"refresh_token_expires_in": 604800,
-			"scope":                    "a:b:c",
-			"status_message":           "审批中，请等待管理员处理",
-		},
-	})
-
-	result := PollDeviceToken(context.Background(), httpmock.NewClient(reg), "cli_a", "secret_b", core.BrandFeishu, "device-code", 1, 10, nil)
-	if result == nil || !result.OK || result.Token == nil {
-		t.Fatalf("PollDeviceToken() = %+v, want OK with a token", result)
-	}
-	if result.Token.StatusMessage != "审批中，请等待管理员处理" {
-		t.Fatalf("StatusMessage = %q, want the approval-pending text", result.Token.StatusMessage)
-	}
-}

internal/auth/remote_scopes.go

@@ -1,107 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/transport"
-)
-
-const (
-	remoteScopesPath    = "/lark-cli/apis/scopes.json"
-	remoteScopesTimeout = 1 * time.Second
-	maxRemoteScopesSize = 10 * 1024 * 1024 // 10MB, aligned with internal/registry/remote.go
-)
-
-// remoteScopesURLForTest is the injection seam for unit tests to point at an
-// httptest server. It is empty at runtime, where the brand-hardcoded production
-// URL is used, and must never carry an internal / non-production domain.
-var remoteScopesURLForTest string
-
-type remoteScopesFile struct {
-	Scopes map[string]remoteDomainScopes `json:"scopes"`
-}
-
-type remoteDomainScopes struct {
-	UserScopes   []string `json:"user_scopes"`
-	TenantScopes []string `json:"tenant_scopes"`
-}
-
-func remoteScopesURL(brand core.LarkBrand) string {
-	if remoteScopesURLForTest != "" {
-		return remoteScopesURLForTest
-	}
-	return core.ResolveOpenBaseURL(brand) + remoteScopesPath
-}
-
-// FetchRemoteScopes fetches and binary-validates the remote scopes.json.
-// It returns (domain -> user_scopes, true) when the whole file is usable, or
-// (nil, false) when the caller should fall back to the local set. Any failure
-// (network / timeout / non-2xx / empty / bad JSON / structure mismatch /
-// malformed scope) returns (nil, false) silently — no warning, no telemetry.
-func FetchRemoteScopes(brand core.LarkBrand) (map[string][]string, bool) {
-	client := transport.NewHTTPClient(remoteScopesTimeout)
-	req, err := http.NewRequest(http.MethodGet, remoteScopesURL(brand), nil)
-	if err != nil {
-		return nil, false
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, false
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return nil, false
-	}
-	body, err := io.ReadAll(io.LimitReader(resp.Body, maxRemoteScopesSize))
-	if err != nil || len(body) == 0 {
-		return nil, false
-	}
-	var file remoteScopesFile
-	if err := json.Unmarshal(body, &file); err != nil {
-		return nil, false
-	}
-	return validateRemoteScopes(file)
-}
-
-func validateRemoteScopes(file remoteScopesFile) (map[string][]string, bool) {
-	if len(file.Scopes) == 0 {
-		return nil, false
-	}
-	result := make(map[string][]string, len(file.Scopes))
-	for domain, ds := range file.Scopes {
-		if ds.UserScopes == nil { // missing user_scopes field / null → whole file untrusted
-			return nil, false
-		}
-		for _, s := range ds.UserScopes {
-			if !isValidScopeFormat(s) {
-				return nil, false
-			}
-		}
-		result[domain] = ds.UserScopes
-	}
-	return result, true
-}
-
-// isValidScopeFormat checks the service:resource:action shape: exactly three
-// ":"-separated segments, each non-empty. The resource segment may contain "."
-// (e.g. vc:meeting.meetingevent:read). i18n / tenant / version are not checked.
-func isValidScopeFormat(s string) bool {
-	parts := strings.Split(s, ":")
-	if len(parts) != 3 {
-		return false
-	}
-	for _, p := range parts {
-		if p == "" {
-			return false
-		}
-	}
-	return true
-}

internal/auth/remote_scopes_test.go

@@ -1,100 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/larksuite/cli/internal/core"
-)
-
-func withRemoteScopesURL(t *testing.T, url string) {
-	t.Helper()
-	prev := remoteScopesURLForTest
-	remoteScopesURLForTest = url
-	t.Cleanup(func() { remoteScopesURLForTest = prev })
-}
-
-func TestFetchRemoteScopes(t *testing.T) {
-	cases := []struct {
-		name    string
-		status  int
-		body    string
-		wantOK  bool
-		wantDom string
-		wantLen int
-	}{
-		{
-			name:    "whole usable returns all user_scopes incl unknown domain",
-			status:  200,
-			body:    `{"version":"1.5.3","scopes":{"bitable":{"i18n_name":{"zh_cn":"多维表格"},"user_scopes":["base:app:copy","base:app:create"],"tenant_scopes":["base:app:copy"]},"brandnewdomain":{"user_scopes":["newsvc:res:read"]}}}`,
-			wantOK:  true,
-			wantDom: "brandnewdomain",
-			wantLen: 1,
-		},
-		{name: "missing scopes key falls back", status: 200, body: `{"version":"1"}`, wantOK: false},
-		{name: "empty scopes falls back", status: 200, body: `{"scopes":{}}`, wantOK: false},
-		{name: "domain missing user_scopes falls back", status: 200, body: `{"scopes":{"im":{"i18n_name":{"zh_cn":"消息"}}}}`, wantOK: false},
-		{name: "malformed scope falls back", status: 200, body: `{"scopes":{"im":{"user_scopes":["im:message"]}}}`, wantOK: false},
-		{name: "non-2xx falls back", status: 500, body: `{"scopes":{"im":{"user_scopes":["im:message:send"]}}}`, wantOK: false},
-		{name: "empty body falls back", status: 200, body: ``, wantOK: false},
-		{name: "bad json falls back", status: 200, body: `{not json`, wantOK: false},
-		{name: "i18n/tenant missing still usable", status: 200, body: `{"scopes":{"im":{"user_scopes":["im:message:send_as_bot","vc:meeting.meetingevent:read"]}}}`, wantOK: true, wantDom: "im", wantLen: 2},
-		{name: "empty user_scopes array is usable", status: 200, body: `{"scopes":{"im":{"user_scopes":[]}}}`, wantOK: true, wantDom: "im", wantLen: 0},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-				w.WriteHeader(tc.status)
-				_, _ = w.Write([]byte(tc.body))
-			}))
-			t.Cleanup(srv.Close)
-			withRemoteScopesURL(t, srv.URL)
-
-			got, ok := FetchRemoteScopes(core.BrandFeishu)
-			if ok != tc.wantOK {
-				t.Fatalf("ok = %v, want %v", ok, tc.wantOK)
-			}
-			if tc.wantOK {
-				if _, exists := got[tc.wantDom]; !exists {
-					t.Fatalf("domain %q missing in result %v", tc.wantDom, got)
-				}
-				if len(got[tc.wantDom]) != tc.wantLen {
-					t.Fatalf("len(%s) = %d, want %d", tc.wantDom, len(got[tc.wantDom]), tc.wantLen)
-				}
-			}
-		})
-	}
-}
-
-func TestFetchRemoteScopesTimeoutFallsBack(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		time.Sleep(remoteScopesTimeout + 500*time.Millisecond)
-		_, _ = w.Write([]byte(`{"scopes":{"im":{"user_scopes":["im:message:send"]}}}`))
-	}))
-	t.Cleanup(srv.Close)
-	withRemoteScopesURL(t, srv.URL)
-
-	_, ok := FetchRemoteScopes(core.BrandFeishu)
-	if ok {
-		t.Fatal("expected fallback (ok=false) on timeout")
-	}
-}
-
-func TestRemoteScopesURLByBrand(t *testing.T) {
-	// With an empty seam the production URL is used: core.ResolveOpenBaseURL(brand) + path
-	remoteScopesURLForTest = ""
-	feishu := remoteScopesURL(core.BrandFeishu)
-	lark := remoteScopesURL(core.BrandLark)
-	if !strings.HasSuffix(feishu, "/lark-cli/apis/scopes.json") || !strings.Contains(feishu, "open.feishu.cn") {
-		t.Fatalf("feishu url unexpected: %s", feishu)
-	}
-	if !strings.Contains(lark, "open.larksuite.com") {
-		t.Fatalf("lark url unexpected: %s", lark)
-	}
-}

internal/cmdmeta/meta.go

@@ -2,9 +2,11 @@
 // SPDX-License-Identifier: MIT
 
 // Package cmdmeta is the single source of truth for command metadata that the
-// policy engine and the hook selector both consume. It wraps the existing
-// cmdutil annotations (risk_level, supportedIdentities) and adds the
-// "domain" axis that the hook selector and Rule path globs need.
+// policy engine, the hook selector, and help rendering consume. It wraps the
+// existing cmdutil annotations (risk_level, supportedIdentities) and adds the
+// "domain" axis that the hook selector and Rule path globs need, plus the
+// affordance ref (service, method id) that lets service-method and shortcut
+// help share one usage-guidance lookup path.
 //
 // Three axes:
 //
@@ -51,6 +53,12 @@ const (
 
 	sourceAnnotationKey    = "cmdmeta.source"
 	generatedAnnotationKey = "cmdmeta.generated"
+
+	// affordance{Service,Method}Key locate the command's usage-guidance overlay
+	// entry (see internal/affordance). Both service-method commands and
+	// +-prefixed shortcuts set these so help rendering shares one lookup path.
+	affordanceServiceKey = "cmdmeta.affordance.service"
+	affordanceMethodKey  = "cmdmeta.affordance.method"
 )
 
 // Meta groups the three command-level metadata axes consumed by the policy
@@ -125,6 +133,35 @@ func SetSource(cmd *cobra.Command, source Source, generated bool) {
 	}
 }
 
+// SetAffordanceRef records which affordance overlay entry (service, method id)
+// a command maps to, so help rendering can look up its usage guidance. Stored
+// on the command itself (no inheritance): each method / shortcut owns its ref.
+// A no-op if either coordinate is empty.
+func SetAffordanceRef(cmd *cobra.Command, service, method string) {
+	if service == "" || method == "" {
+		return
+	}
+	if cmd.Annotations == nil {
+		cmd.Annotations = map[string]string{}
+	}
+	cmd.Annotations[affordanceServiceKey] = service
+	cmd.Annotations[affordanceMethodKey] = method
+}
+
+// AffordanceRef returns the command's own affordance overlay coordinates.
+// ok is false when the command carries no ref.
+func AffordanceRef(cmd *cobra.Command) (service, method string, ok bool) {
+	if cmd.Annotations == nil {
+		return "", "", false
+	}
+	service = cmd.Annotations[affordanceServiceKey]
+	method = cmd.Annotations[affordanceMethodKey]
+	if service == "" || method == "" {
+		return "", "", false
+	}
+	return service, method, true
+}
+
 // Domain returns the nearest-ancestor domain for the command. Empty string
 // when no ancestor has the annotation -- this is the "unknown" state the
 // policy engine must treat as ALLOW.

internal/cmdutil/fileupload.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"fmt"
 	"io"
+	"path/filepath"
 	"strconv"
 	"strings"
 
@@ -128,7 +129,7 @@ func BuildFormdata(fileIO fileio.FileIO, fieldName, filePath string, isStdin boo
 				WithParam("--file").
 				WithCause(err)
 		}
-		fd.AddFile(fieldName, bytes.NewReader(data))
+		fd.AddFileWithName(fieldName, filepath.Base(filePath), bytes.NewReader(data))
 	}
 
 	// Add top-level JSON keys as text form fields.

internal/errclass/classify_test.go

@@ -113,6 +113,7 @@ func TestBuildAPIError_ExitCodeMatrix(t *testing.T) {
 		{"230027 user_not_authorized", 230027, errs.CategoryAuthorization, errs.SubtypeUserUnauthorized, 3, "PermissionError"},
 		{"1470403 task_permission_denied", 1470403, errs.CategoryAuthorization, errs.SubtypePermissionDenied, 3, "PermissionError"},
 		{"1470400 task_invalid_params", 1470400, errs.CategoryAPI, errs.SubtypeInvalidParameters, 1, "APIError"},
+		{"1062507 drive_parent_sibling_limit", 1062507, errs.CategoryAPI, errs.SubtypeQuotaExceeded, 1, "APIError"},
 		{"99991400 rate_limit", 99991400, errs.CategoryAPI, errs.SubtypeRateLimit, 1, "APIError"},
 		{"99991661 token_missing", 99991661, errs.CategoryAuthentication, errs.SubtypeTokenMissing, 3, "AuthenticationError"},
 		{"21000 challenge_required", 21000, errs.CategoryPolicy, errs.Subtype("challenge_required"), 6, "SecurityPolicyError"},

internal/errclass/codemeta_drive.go

@@ -17,6 +17,7 @@ var driveCodeMeta = map[int]CodeMeta{
 	1061043:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file size beyond limit
 	1061044:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // parent folder does not exist (upload)
 	1061101:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file quota exceeded
+	1062507:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // parent folder child count limit exceeded
 	1062009:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // actual size inconsistent with declared size
 	1063001:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // secure label invalid parameter
 	1063002:   {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // secure label permission denied

internal/meta/affordance.go

@@ -8,8 +8,11 @@ import "encoding/json"
 // Affordance is the typed usage guidance overlaid on a method. It is the single
 // model the envelope renderer and the command help both parse, so the
 // vocabulary is defined once; the JSON tags double as the envelope wire shape.
-// Skills entries are skill names (or name/path) rendered as runnable
-// `lark-cli skills read <entry>` pointers.
+// Skills entries are either a bare skill name (e.g. "lark-doc") or a
+// name/relative-path reference (e.g. "lark-contact/references/x.md"); both
+// render as runnable `lark-cli skills read <entry>` pointers. Help validates
+// each against the embedded skill tree (a name → its SKILL.md, a reference →
+// that path) and drops any that do not resolve.
 type Affordance struct {
 	UseWhen       []string            `json:"use_when,omitempty"`
 	AvoidWhen     []string            `json:"avoid_when,omitempty"`

internal/registry/loader.go

@@ -165,6 +165,9 @@ const DefaultScopeScore = 0
 
 var cachedScopePriorities map[string]int
 var cachedAutoApproveSet map[string]bool
+var cachedPlatformAutoApprove map[string]bool // from scope_priorities.json only
+var cachedOverrideAutoAllow map[string]bool   // from scope_overrides.json allow only
+var cachedOverrideAutoDeny map[string]bool    // from scope_overrides.json deny only
 
 // scopePriorityEntry is used to parse scope_priorities.json entries.
 type scopePriorityEntry struct {
@@ -261,6 +264,90 @@ func LoadAutoApproveSet() map[string]bool {
 	return cachedAutoApproveSet
 }
 
+// LoadPlatformAutoApproveSet returns scopes with AutoApprove rule on the platform
+// (from scope_priorities.json only, before overrides).
+func LoadPlatformAutoApproveSet() map[string]bool {
+	if cachedPlatformAutoApprove != nil {
+		return cachedPlatformAutoApprove
+	}
+	m := make(map[string]bool)
+	if data, err := registryFS.ReadFile("scope_priorities.json"); err == nil {
+		var entries []scopePriorityEntry
+		if json.Unmarshal(data, &entries) == nil {
+			for _, entry := range entries {
+				if entry.Recommend == "true" {
+					m[entry.ScopeName] = true
+				}
+			}
+		}
+	}
+	cachedPlatformAutoApprove = m
+	return cachedPlatformAutoApprove
+}
+
+// LoadOverrideAutoApproveAllow returns scopes explicitly listed in
+// scope_overrides.json recommend.allow (our desired additions).
+func LoadOverrideAutoApproveAllow() map[string]bool {
+	if cachedOverrideAutoAllow != nil {
+		return cachedOverrideAutoAllow
+	}
+	m := make(map[string]bool)
+	if data, err := registryFS.ReadFile("scope_overrides.json"); err == nil {
+		var wrapper struct {
+			AutoApprove struct {
+				Allow []string `json:"allow"`
+			} `json:"recommend"`
+		}
+		if json.Unmarshal(data, &wrapper) == nil {
+			for _, s := range wrapper.AutoApprove.Allow {
+				m[s] = true
+			}
+		}
+	}
+	cachedOverrideAutoAllow = m
+	return cachedOverrideAutoAllow
+}
+
+// LoadOverrideAutoApproveDeny returns scopes explicitly listed in
+// scope_overrides.json recommend.deny
+func LoadOverrideAutoApproveDeny() map[string]bool {
+	if cachedOverrideAutoDeny != nil {
+		return cachedOverrideAutoDeny
+	}
+	m := make(map[string]bool)
+	if data, err := registryFS.ReadFile("scope_overrides.json"); err == nil {
+		var wrapper struct {
+			AutoApprove struct {
+				Deny []string `json:"deny"`
+			} `json:"recommend"`
+		}
+		if json.Unmarshal(data, &wrapper) == nil {
+			for _, s := range wrapper.AutoApprove.Deny {
+				m[s] = true
+			}
+		}
+	}
+	cachedOverrideAutoDeny = m
+	return cachedOverrideAutoDeny
+}
+
+// IsAutoApproveScope returns true if the scope has AutoApprove rule.
+func IsAutoApproveScope(scope string) bool {
+	return LoadAutoApproveSet()[scope]
+}
+
+// FilterAutoApproveScopes filters a scope list to only include auto-approve scopes.
+func FilterAutoApproveScopes(scopes []string) []string {
+	autoApprove := LoadAutoApproveSet()
+	var result []string
+	for _, s := range scopes {
+		if autoApprove[s] {
+			result = append(result, s)
+		}
+	}
+	return result
+}
+
 // GetScopeScore returns the priority score for a scope, or DefaultScopeScore if not found.
 func GetScopeScore(scope string) int {
 	priorities := LoadScopePriorities()

internal/registry/registry_test.go

@@ -235,6 +235,83 @@ func TestLoadAutoApproveSet(t *testing.T) {
 	t.Logf("Auto-approve set has %d scopes", len(aaSet))
 }
 
+func TestLoadPlatformAutoApproveSet(t *testing.T) {
+	paaSet := LoadPlatformAutoApproveSet()
+	// This should only include scopes from scope_priorities.json with AutoApprove rule.
+	// It does NOT apply deny overrides.
+	if len(paaSet) == 0 {
+		t.Fatal("expected non-empty platform auto-approve set")
+	}
+
+	t.Logf("Platform auto-approve set has %d scopes", len(paaSet))
+}
+
+func TestLoadOverrideAutoApproveAllow(t *testing.T) {
+	allowSet := LoadOverrideAutoApproveAllow()
+	// recommend.allow in scope_overrides.json is intentionally empty:
+	// no scopes are special-cased into the auto-approve set anymore.
+	if len(allowSet) != 0 {
+		t.Errorf("expected empty override allow set, got %d entries", len(allowSet))
+	}
+}
+
+func TestLoadOverrideAutoApproveDeny(t *testing.T) {
+	denySet := LoadOverrideAutoApproveDeny()
+	// deny list may be empty if all entries are moved to _deny (commented out)
+	t.Logf("Override deny set has %d scopes", len(denySet))
+}
+
+func TestIsAutoApproveScope(t *testing.T) {
+	// Known auto-approve scope (recommend=true in scope_priorities.json)
+	if !IsAutoApproveScope("sheets:spreadsheet:read") {
+		t.Error("expected sheets:spreadsheet:read to be auto-approve")
+	}
+
+	// Completely unknown scope
+	if IsAutoApproveScope("zzz:unknown:scope") {
+		t.Error("expected unknown scope to NOT be auto-approve")
+	}
+}
+
+func TestFilterAutoApproveScopes(t *testing.T) {
+	scopes := []string{
+		"sheets:spreadsheet:read", // auto-approve (recommend=true in priorities)
+		"zzz:unknown:scope",       // not in auto-approve
+	}
+
+	result := FilterAutoApproveScopes(scopes)
+	if len(result) < 1 {
+		t.Fatal("expected at least 1 auto-approve scope in result")
+	}
+
+	// Check that sheets:spreadsheet:read is included
+	found := false
+	for _, s := range result {
+		if s == "sheets:spreadsheet:read" {
+			found = true
+		}
+		// Ensure unknown scopes are not included
+		if s == "zzz:unknown:scope" {
+			t.Error("unknown scope should not be in auto-approve result")
+		}
+	}
+	if !found {
+		t.Error("expected sheets:spreadsheet:read in result")
+	}
+}
+
+func TestFilterAutoApproveScopes_Empty(t *testing.T) {
+	result := FilterAutoApproveScopes(nil)
+	if result != nil {
+		t.Errorf("expected nil, got %v", result)
+	}
+
+	result = FilterAutoApproveScopes([]string{})
+	if result != nil {
+		t.Errorf("expected nil for empty input, got %v", result)
+	}
+}
+
 // --- Helper functions ---
 
 func TestGetRegistryDir(t *testing.T) {

internal/registry/remote_test.go

@@ -40,6 +40,9 @@ func resetInit() {
 	cachedAllScopes = nil
 	cachedScopePriorities = nil
 	cachedAutoApproveSet = nil
+	cachedPlatformAutoApprove = nil
+	cachedOverrideAutoAllow = nil
+	cachedOverrideAutoDeny = nil
 	refreshOnce = sync.Once{}
 	configuredBrand = ""
 	enableRemoteMeta = true // tests exercise remote logic

internal/registry/service_desc.go

@@ -58,6 +58,26 @@ func GetServiceDescription(name, lang string) string {
 	return loc.Description
 }
 
+// GetServiceTitle returns the localized title for a service domain.
+// Returns empty string if not found.
+func GetServiceTitle(name, lang string) string {
+	loc := getServiceLocale(name, lang)
+	if loc == nil {
+		return ""
+	}
+	return loc.Title
+}
+
+// GetServiceDetailDescription returns the localized detail description for a service domain.
+// Returns empty string if not found.
+func GetServiceDetailDescription(name, lang string) string {
+	loc := getServiceLocale(name, lang)
+	if loc == nil {
+		return ""
+	}
+	return loc.Description
+}
+
 // GetAuthDomain returns the auth_domain for a service, or "" if not set.
 // When auth_domain is set, the service's scopes are collected under the
 // parent domain during auth login.

package.json

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

shortcuts/base/record_json_shorthand_test.go

@@ -0,0 +1,73 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func mountBaseShortcutFlags(t *testing.T, s common.Shortcut, name string) *cobra.Command {
+	t.Helper()
+	parent := &cobra.Command{Use: "test"}
+	s.Mount(parent, &cmdutil.Factory{})
+	cmd, _, err := parent.Find([]string{name})
+	if err != nil {
+		t.Fatalf("Find(%s) error = %v", name, err)
+	}
+	return cmd
+}
+
+// record-list 获得 --json 简写
+func TestRecordListRegistersJSONShorthand(t *testing.T) {
+	cmd := mountBaseShortcutFlags(t, BaseRecordList, "+record-list")
+	fl := cmd.Flags().Lookup("json")
+	if fl == nil {
+		t.Fatal("+record-list missing --json shorthand")
+	}
+	if fl.Usage != "shorthand for --format json" {
+		t.Errorf("usage = %q, want shorthand", fl.Usage)
+	}
+	if def := cmd.Flags().Lookup("format").DefValue; def != "markdown" {
+		t.Errorf("format default = %q, want markdown (unchanged)", def)
+	}
+}
+
+// record-search / record-get 的 --json 保持请求体语义，不被覆盖（回归锚点）
+func TestRecordSearchGetKeepRequestBodyJSON(t *testing.T) {
+	for _, tc := range []struct {
+		name     string
+		shortcut common.Shortcut
+		cmdName  string
+	}{
+		{"record-search", BaseRecordSearch, "+record-search"},
+		{"record-get", BaseRecordGet, "+record-get"},
+	} {
+		cmd := mountBaseShortcutFlags(t, tc.shortcut, tc.cmdName)
+		fl := cmd.Flags().Lookup("json")
+		if fl == nil {
+			t.Fatalf("%s: --json (request body) missing", tc.name)
+		}
+		if strings.Contains(fl.Usage, "shorthand") {
+			t.Fatalf("%s: request-body --json overwritten by shorthand: %q", tc.name, fl.Usage)
+		}
+		if fl.Value.Type() != "string" {
+			t.Fatalf("%s: --json type = %q, want string", tc.name, fl.Value.Type())
+		}
+	}
+}
+
+// Enum 已接入：help 描述携带枚举后缀（框架对带 Enum 的 flag 自动追加 " (markdown|json)"）
+func TestRecordReadFormatFlagCarriesEnum(t *testing.T) {
+	cmd := mountBaseShortcutFlags(t, BaseRecordList, "+record-list")
+	usage := cmd.Flags().Lookup("format").Usage
+	if !strings.Contains(usage, "(markdown|json)") {
+		t.Fatalf("format usage missing enum suffix: %q", usage)
+	}
+}

shortcuts/base/record_list.go

@@ -85,6 +85,7 @@ func recordReadFormatFlag() common.Flag {
 	return common.Flag{
 		Name:    "format",
 		Default: "markdown",
+		Enum:    []string{"markdown", "json"},
 		Desc:    "output format: markdown (default) | json",
 	}
 }

shortcuts/common/runner.go

@@ -889,6 +889,7 @@ func (s Shortcut) mountDeclarative(ctx context.Context, parent *cobra.Command, f
 		}
 	}
 	cmdmeta.SetSource(cmd, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetAffordanceRef(cmd, shortcut.Service, shortcut.Command)
 	cmdutil.SetSupportedIdentities(cmd, shortcut.AuthTypes)
 	registerShortcutFlagsWithContext(ctx, cmd, f, &shortcut)
 	cmdutil.SetTips(cmd, shortcut.Tips)
@@ -1026,6 +1027,7 @@ func newRuntimeContext(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut, conf
 	}
 	rctx.larkSDK = sdk
 
+	applyJSONShorthand(cmd, s)
 	rctx.Format = rctx.Str("format")
 	rctx.JqExpr, _ = cmd.Flags().GetString("jq")
 	return rctx, nil
@@ -1171,6 +1173,75 @@ func registerShortcutFlags(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut)
 	registerShortcutFlagsWithContext(context.Background(), cmd, f, s)
 }
 
+// shortcutDeclaresJSONFlag reports whether the shortcut itself declares a flag
+// named "json" in its Flags list (custom semantics, e.g. event +subscribe's
+// pretty-print switch or base +record-search's request-body payload).
+// Framework-injected flags never appear in s.Flags, so this cleanly separates
+// "self-declared json" from "injected shorthand".
+func shortcutDeclaresJSONFlag(s *Shortcut) bool {
+	for _, fl := range s.Flags {
+		if fl.Name == "json" {
+			return true
+		}
+	}
+	return false
+}
+
+// shortcutFormatSupportsJSON reports whether the command's format flag accepts
+// "json": a self-declared format supports it only when its Enum lists "json";
+// a framework-injected default format (no format entry in s.Flags) always does.
+func shortcutFormatSupportsJSON(s *Shortcut) bool {
+	for _, fl := range s.Flags {
+		if fl.Name == "format" {
+			return slices.Contains(fl.Enum, "json")
+		}
+	}
+	return true // framework-injected: json (default) | pretty | table | ndjson | csv
+}
+
+// ensureJSONShorthand registers --json as a shorthand for --format json when:
+//  1. the command has a format flag (self-declared or framework-injected), AND
+//  2. that format supports "json" (see shortcutFormatSupportsJSON), AND
+//  3. no flag named "json" is registered yet — pflag panics on duplicate
+//     registration, and commands that declare their own --json (event
+//     +subscribe, base +record-search/-get) keep their custom semantics.
+func ensureJSONShorthand(cmd *cobra.Command, s *Shortcut) {
+	// A shortcut that declares its own "json" flag defines custom semantics
+	// (e.g. pretty-print switch, request-body payload) — never a shorthand.
+	if shortcutDeclaresJSONFlag(s) {
+		return
+	}
+	if cmd.Flags().Lookup("format") == nil {
+		return
+	}
+	if !shortcutFormatSupportsJSON(s) {
+		return
+	}
+	// Safety net: pflag panics on duplicate registration.
+	if cmd.Flags().Lookup("json") != nil {
+		return
+	}
+	cmd.Flags().Bool("json", false, "shorthand for --format json")
+}
+
+// applyJSONShorthand folds the injected --json shorthand into the format flag
+// itself, before rctx.Format caches it — so both the cached value (OutFormat,
+// ValidateJqFlags, dry-run) and later runtime.Str("format") reads observe
+// "json". An explicitly passed --format always wins over the shorthand (the
+// shorthand only fills in when the user did not choose a format). Shortcuts
+// that declare their own "json" flag keep its custom semantics untouched.
+func applyJSONShorthand(cmd *cobra.Command, s *Shortcut) {
+	if shortcutDeclaresJSONFlag(s) {
+		return
+	}
+	if cmd.Flags().Lookup("json") == nil || cmd.Flags().Changed("format") {
+		return
+	}
+	if set, _ := cmd.Flags().GetBool("json"); set {
+		_ = cmd.Flags().Set("format", "json")
+	}
+}
+
 func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut) {
 	for _, fl := range s.Flags {
 		desc := fl.Desc
@@ -1234,10 +1305,8 @@ func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f
 		cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 			return []string{"json", "pretty", "table", "ndjson", "csv"}, cobra.ShellCompDirectiveNoFileComp
 		})
-		if cmd.Flags().Lookup("json") == nil {
-			cmd.Flags().Bool("json", false, "shorthand for --format json")
-		}
 	}
+	ensureJSONShorthand(cmd, s)
 	if s.Risk == "high-risk-write" {
 		cmd.Flags().Bool("yes", false, "confirm high-risk operation")
 	}

shortcuts/common/runner_json_shorthand_test.go

@@ -0,0 +1,200 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+)
+
+const jsonShorthandUsage = "shorthand for --format json"
+
+func mountTestShortcut(t *testing.T, s Shortcut) *cobra.Command {
+	t.Helper()
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	parent := &cobra.Command{Use: "root"}
+	s.Mount(parent, f)
+	cmd, _, err := parent.Find([]string{s.Command})
+	if err != nil {
+		t.Fatalf("Find() error = %v", err)
+	}
+	return cmd
+}
+
+// 自定义 format 且 Enum 含 json → 注册简写（本次修复的核心行为）
+func TestJSONShorthand_CustomFormatWithJSONEnum_Registered(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "mail", Command: "+fake-triage", Description: "x",
+		Flags:   []Flag{{Name: "format", Default: "table", Enum: []string{"table", "json", "data"}, Desc: "fmt"}},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	fl := cmd.Flags().Lookup("json")
+	if fl == nil {
+		t.Fatal("--json not registered for custom-format shortcut whose Enum contains json")
+	}
+	if fl.Usage != jsonShorthandUsage {
+		t.Errorf("usage = %q, want %q", fl.Usage, jsonShorthandUsage)
+	}
+	// 默认输出格式不被改变
+	if def := cmd.Flags().Lookup("format").DefValue; def != "table" {
+		t.Errorf("format default = %q, want table", def)
+	}
+}
+
+// 自定义 format 但 Enum 不含 json → 不注册
+func TestJSONShorthand_CustomFormatWithoutJSONEnum_NotRegistered(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "x", Command: "+no-json", Description: "x",
+		Flags:   []Flag{{Name: "format", Default: "csv", Enum: []string{"csv", "table"}, Desc: "fmt"}},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	if cmd.Flags().Lookup("json") != nil {
+		t.Fatal("--json must NOT be registered when format Enum lacks json")
+	}
+}
+
+// 自定义 format 但无 Enum（现状 triage 形态）→ 不注册（Enum 是判定依据）
+func TestJSONShorthand_CustomFormatNoEnum_NotRegistered(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "x", Command: "+legacy", Description: "x",
+		Flags:   []Flag{{Name: "format", Default: "table", Desc: "fmt"}},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	if cmd.Flags().Lookup("json") != nil {
+		t.Fatal("--json must NOT be registered when format has no Enum metadata")
+	}
+}
+
+// 自声明 json flag（subscribe 的 pretty / record-search 的请求体）→ 不覆盖、不 panic、语义保留
+func TestJSONShorthand_SelfDeclaredJSON_Preserved(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "event", Command: "+fake-subscribe", Description: "x",
+		Flags: []Flag{
+			{Name: "json", Type: "bool", Desc: "pretty-print JSON instead of NDJSON"},
+		},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	fl := cmd.Flags().Lookup("json")
+	if fl == nil {
+		t.Fatal("self-declared --json missing")
+	}
+	if fl.Usage != "pretty-print JSON instead of NDJSON" {
+		t.Errorf("self-declared --json usage overwritten: %q", fl.Usage)
+	}
+}
+
+// parseMounted mounts the shortcut and parses args against the command's FlagSet
+// (registration side effects included), without executing RunE.
+func parseMounted(t *testing.T, s Shortcut, args []string) *cobra.Command {
+	t.Helper()
+	cmd := mountTestShortcut(t, s)
+	if err := cmd.ParseFlags(args); err != nil {
+		t.Fatalf("ParseFlags(%v) error = %v", args, err)
+	}
+	return cmd
+}
+
+func customFormatShortcut() Shortcut {
+	return Shortcut{
+		Service: "mail", Command: "+fake-triage", Description: "x",
+		Flags:   []Flag{{Name: "format", Default: "table", Enum: []string{"table", "json", "data"}, Desc: "fmt"}},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	}
+}
+
+// --json 单独使用 → format 归一化为 json
+func TestApplyJSONShorthand_JSONAlone_SetsFormatJSON(t *testing.T) {
+	s := customFormatShortcut()
+	cmd := parseMounted(t, s, []string{"--json"})
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "json" {
+		t.Fatalf("format = %q, want json", got)
+	}
+}
+
+// 显式 --format 优先于 --json 简写：--format table --json → table
+func TestApplyJSONShorthand_ExplicitFormatWins(t *testing.T) {
+	s := customFormatShortcut()
+	cmd := parseMounted(t, s, []string{"--format", "table", "--json"})
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "table" {
+		t.Fatalf("format = %q, want table (explicit --format must win)", got)
+	}
+}
+
+// --format json --json → json（一致，无冲突）
+func TestApplyJSONShorthand_ExplicitJSONFormatConsistent(t *testing.T) {
+	s := customFormatShortcut()
+	cmd := parseMounted(t, s, []string{"--format", "json", "--json"})
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "json" {
+		t.Fatalf("format = %q, want json", got)
+	}
+}
+
+// 均不传 → 默认值不变
+func TestApplyJSONShorthand_NoFlags_DefaultUntouched(t *testing.T) {
+	s := customFormatShortcut()
+	cmd := parseMounted(t, s, nil)
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "table" {
+		t.Fatalf("format = %q, want table (default untouched)", got)
+	}
+}
+
+// 自声明 string 型 --json（record-search 形态：format+json 双声明）→ 归一化跳过
+func TestApplyJSONShorthand_SelfDeclaredStringJSON_Skipped(t *testing.T) {
+	s := Shortcut{
+		Service: "base", Command: "+fake-record-search", Description: "x",
+		Flags: []Flag{
+			{Name: "format", Default: "markdown", Enum: []string{"markdown", "json"}, Desc: "fmt"},
+			{Name: "json", Desc: "request body JSON object"},
+		},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	}
+	cmd := parseMounted(t, s, []string{"--json", `{"keyword":"Alice"}`})
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "markdown" {
+		t.Fatalf("format = %q, want markdown (self-declared json must not normalize)", got)
+	}
+	if got := cmd.Flags().Lookup("json").Value.String(); got != `{"keyword":"Alice"}` {
+		t.Fatalf("request-body --json corrupted: %q", got)
+	}
+}
+
+// 自声明 bool 型 --json（subscribe 形态：无自定义 format，框架注入 format）→ 归一化跳过
+func TestApplyJSONShorthand_SelfDeclaredBoolJSON_Skipped(t *testing.T) {
+	s := Shortcut{
+		Service: "event", Command: "+fake-subscribe", Description: "x",
+		Flags: []Flag{
+			{Name: "json", Type: "bool", Desc: "pretty-print JSON instead of NDJSON"},
+		},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	}
+	cmd := parseMounted(t, s, []string{"--json"})
+	applyJSONShorthand(cmd, &s)
+	// 注入的 format 默认即 json；这里断言的是 Changed 状态未被归一化污染
+	if cmd.Flags().Changed("format") {
+		t.Fatal("normalization must not touch format for shortcuts declaring their own --json")
+	}
+}
+
+// 无自定义 format（普通命令）→ 注入默认 format + 简写（现状回归）
+func TestJSONShorthand_DefaultInjectedFormat_StillRegistered(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "im", Command: "+plain", Description: "x",
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	fl := cmd.Flags().Lookup("json")
+	if fl == nil {
+		t.Fatal("--json missing on default-format shortcut (regression)")
+	}
+	if fl.Usage != jsonShorthandUsage {
+		t.Errorf("usage = %q, want %q", fl.Usage, jsonShorthandUsage)
+	}
+}

shortcuts/contact/contact_search_user.go

@@ -150,12 +150,10 @@ var ContactSearchUser = common.Shortcut{
 		{Name: "queries", Desc: "comma-separated keywords searched in parallel; output is a flat users[] with matched_query plus a queries[] sidecar"},
 	},
 	Tips: []string{
-		"Keyword search: lark-cli contact +search-user --query 'alice'",
-		"Look up by ID (or 'me' for self): lark-cli contact +search-user --user-ids 'ou_xxx,me'",
 		"Filter-only enumeration — users you've chatted with: lark-cli contact +search-user --has-chatted",
 		"Refine same-name hits: lark-cli contact +search-user --query '张三' --has-chatted --exclude-external-users",
 		"Multi-name fanout: lark-cli contact +search-user --queries 'alice,bob,张三'",
-		"open_id is the stable identifier for follow-up commands; on has_more=true add filters or tighten --query — there is no auto-pagination.",
+		"on has_more=true add filters or tighten --query — there is no auto-pagination.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateSearchUser(runtime)

shortcuts/drive/drive_push.go

@@ -623,6 +623,10 @@ func driveClassifyBatchFailure(err error) driveBatchFailureDecision {
 	case problem.Subtype == errs.SubtypeRateLimit || problem.Code == 99991400:
 		decision.Class = "rate_limited"
 		decision.Terminal = true
+	case problem.Code == 1062507:
+		decision.Class = "parent_sibling_limit"
+		decision.Terminal = true
+		decision.Hint = "The destination parent folder has reached its child-count limit. Clean up that folder, choose another --folder-token, or split the upload across subfolders before retrying."
 	case problem.Subtype == errs.SubtypeQuotaExceeded || problem.Code == 1061043:
 		decision.Class = "file_size_limit"
 	case problem.Code == 1062009:

shortcuts/drive/drive_push_test.go

@@ -1334,6 +1334,75 @@ func TestDrivePushAbortsAfterCreateFolderMissingScope(t *testing.T) {
 	}
 }
 
+func TestDrivePushAbortsAfterCreateFolderParentSiblingLimit(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll(filepath.Join("local", "a"), 0o755); err != nil {
+		t.Fatalf("MkdirAll a: %v", err)
+	}
+	if err := os.MkdirAll(filepath.Join("local", "b"), 0o755); err != nil {
+		t.Fatalf("MkdirAll b: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/create_folder",
+		Body: map[string]interface{}{
+			"code": 1062507,
+			"msg":  "parent node out of sibling num.",
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected partial failure, got nil\nstdout: %s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	if got := summary["aborted"]; got != true {
+		t.Fatalf("summary.aborted = %v, want true", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["rel_path"] != "a" || item["phase"] != "create_folder" || item["error_class"] != "parent_sibling_limit" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(1062507) || item["subtype"] != "quota_exceeded" || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	if got, _ := item["hint"].(string); !strings.Contains(got, "--folder-token") || !strings.Contains(got, "child-count limit") {
+		t.Fatalf("hint should explain the destination folder child-count limit, got item=%#v", item)
+	}
+	for _, item := range items {
+		if item["rel_path"] == "b" {
+			t.Fatalf("parent sibling limit must abort before b, got items=%#v", items)
+		}
+	}
+}
+
 func TestDrivePushDetectsLocalFileChangedBeforeUpload(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 

shortcuts/mail/mail_json_shorthand_test.go

@@ -0,0 +1,112 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// help 必须列出 --json 简写
+func TestMailTriageHelpListsJSONShorthand(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	if err := runMountedMailShortcutWithCobraOutput(t, MailTriage, []string{"+triage", "-h"}, f, stdout); err != nil {
+		t.Fatalf("help returned error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "shorthand for --format json") {
+		t.Fatalf("triage help missing --json shorthand\n%s", stdout.String())
+	}
+}
+
+func TestMailWatchHelpListsJSONShorthand(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	if err := runMountedMailShortcutWithCobraOutput(t, MailWatch, []string{"+watch", "-h"}, f, stdout); err != nil {
+		t.Fatalf("help returned error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "shorthand for --format json") {
+		t.Fatalf("watch help missing --json shorthand\n%s", stdout.String())
+	}
+}
+
+// 行为验证：--json 走 JSON 输出路径，不输出 table read hint
+func TestMailTriageJSONShorthandDoesNotEmitReadHint(t *testing.T) {
+	f, stdout, stderr, reg := mailShortcutTestFactory(t)
+	registerTriageReadHintStubs(reg)
+
+	err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--json", "--max", "1"}, f, stdout)
+	if err != nil {
+		t.Fatalf("triage --json returned error: %v", err)
+	}
+	reg.Verify(t)
+	if strings.Contains(stderr.String(), "tip: read full content:") {
+		t.Fatalf("--json must follow the JSON path, got table hint\nstderr=%s", stderr.String())
+	}
+	if !strings.Contains(stdout.String(), `"messages"`) {
+		t.Fatalf("--json stdout missing JSON payload\n%s", stdout.String())
+	}
+}
+
+// 等价性验证：--json 与 --format json 的 dry-run 输出一致
+func TestMailTriageJSONShorthandDryRunEquivalence(t *testing.T) {
+	f1, stdout1, _, _ := mailShortcutTestFactory(t)
+	if err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--json", "--max", "1", "--dry-run"}, f1, stdout1); err != nil {
+		t.Fatalf("--json --dry-run error: %v", err)
+	}
+	f2, stdout2, _, _ := mailShortcutTestFactory(t)
+	if err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--format", "json", "--max", "1", "--dry-run"}, f2, stdout2); err != nil {
+		t.Fatalf("--format json --dry-run error: %v", err)
+	}
+	if stdout1.String() != stdout2.String() {
+		t.Fatalf("dry-run outputs differ:\n--json:\n%s\n--format json:\n%s", stdout1.String(), stdout2.String())
+	}
+}
+
+// 优先级验证：显式 --format table 优先，--json 让位 → 仍走 table 路径
+func TestMailTriageExplicitTableWinsOverJSONShorthand(t *testing.T) {
+	f, stdout, stderr, reg := mailShortcutTestFactory(t)
+	registerTriageReadHintStubs(reg)
+
+	err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--format", "table", "--json", "--max", "1"}, f, stdout)
+	if err != nil {
+		t.Fatalf("triage returned error: %v", err)
+	}
+	if !strings.Contains(stderr.String(), "tip: read full content:") {
+		t.Fatalf("explicit --format table must win over --json (expected table hint)\nstderr=%s", stderr.String())
+	}
+}
+
+// 错误验证：Enum 硬校验
+func TestMailTriageEnumRejectsUnknownFormat(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--format", "bogus", "--max", "1", "--dry-run"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected validation error for --format bogus")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error = %T, want typed errs problem carrier", 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 ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("error = %T, want *errs.ValidationError", err)
+	}
+	if ve.Param != "--format" {
+		t.Fatalf("param = %q, want --format", ve.Param)
+	}
+	if !strings.Contains(problem.Message, `invalid value "bogus" for --format`) {
+		t.Fatalf("message = %q, want enum validation message", problem.Message)
+	}
+	if !strings.Contains(problem.Message, "table, json, data") {
+		t.Fatalf("message = %q, want allowed values list", problem.Message)
+	}
+}

shortcuts/mail/mail_read_help_test.go

@@ -94,7 +94,7 @@ func TestMailTriageTableHintRoutesSingleAndMultipleReads(t *testing.T) {
 	registerTriageReadHintStubs(reg)
 
 	err := runMountedMailShortcut(t, MailTriage, []string{
-		"+triage", "--max", "1",
+		"+triage", "--format", "table", "--max", "1",
 	}, f, stdout)
 	if err != nil {
 		t.Fatalf("triage returned error: %v", err)

shortcuts/mail/mail_triage.go

@@ -55,7 +55,7 @@ var MailTriage = common.Shortcut{
 	Scopes:      []string{"mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
-		{Name: "format", Default: "table", Desc: "output format: table | json | data (json/data output object with pagination fields)"},
+		{Name: "format", Default: "json", Enum: []string{"table", "json", "data"}, Desc: "output format: table | json | data (json/data output object with pagination fields)"},
 		{Name: "max", Type: "int", Default: "20", Desc: "maximum number of messages to fetch (1-400; auto-paginates internally)"},
 		{Name: "page-size", Type: "int", Desc: "alias for --max"},
 		{Name: "page-token", Desc: "pagination token from a previous response to fetch the next page"},

shortcuts/mail/mail_triage_test.go

@@ -1655,6 +1655,39 @@ func TestMailTriageMissingMessageMetadataStillGetsMailboxID(t *testing.T) {
 	}
 }
 
+// TestMailTriageDefaultFormatIsJSON verifies that with no --format flag the
+// command defaults to json and prints the paginated object to stdout, not the
+// human table.
+func TestMailTriageDefaultFormatIsJSON(t *testing.T) {
+	f, stdout, _, reg := mailShortcutTestFactory(t)
+	defer reg.Verify(t)
+
+	registerMailTriageListStub(reg, "me", []string{"msg_ok"}, false, "")
+	registerMailTriageBatchStub(reg, "me", []map[string]interface{}{
+		mailTriageBatchMessage("msg_ok", "Present"),
+	})
+
+	err := runMountedMailShortcut(t, MailTriage, []string{
+		"+triage",
+		"--filter", `{"folder_id":"INBOX"}`,
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeMailTriageJSONOutput(t, stdout) // fails to unmarshal if default were table
+	messages := mailTriageMessagesFromOutput(t, data)
+	if len(messages) != 1 {
+		t.Fatalf("expected 1 message, got %d", len(messages))
+	}
+	if _, ok := data["count"]; !ok {
+		t.Fatalf("default json output missing count field: %#v", data)
+	}
+	if _, ok := data["has_more"]; !ok {
+		t.Fatalf("default json output missing has_more field: %#v", data)
+	}
+}
+
 // TestMailTriageTableOutputPreservesMailboxContext verifies public mailbox table hints.
 func TestMailTriageTableOutputPreservesMailboxContext(t *testing.T) {
 	tests := []struct {
@@ -1678,7 +1711,7 @@ func TestMailTriageTableOutputPreservesMailboxContext(t *testing.T) {
 				mailTriageBatchMessage("msg_001", "Table message"),
 			})
 
-			args := []string{"+triage", "--max", "1", "--filter", `{"folder_id":"INBOX"}`}
+			args := []string{"+triage", "--format", "table", "--max", "1", "--filter", `{"folder_id":"INBOX"}`}
 			if tt.mailbox != "me" {
 				args = append(args, "--mailbox", tt.mailbox)
 			}
@@ -1719,6 +1752,7 @@ func TestMailTriageDefaultTableOutputPrintsSearchNoticeToStderr(t *testing.T) {
 
 	if err := runMountedMailShortcut(t, MailTriage, []string{
 		"+triage",
+		"--format", "table",
 		"--query", strings.Repeat("q", 81),
 	}, f, stdout); err != nil {
 		t.Fatalf("unexpected error: %v", err)

shortcuts/mail/mail_watch.go

@@ -99,7 +99,7 @@ var MailWatch = common.Shortcut{
 	Scopes:      []string{"mail:event", "mail:user_mailbox.event.mail_address:read", "mail:user_mailbox:readonly", "mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user"},
 	Flags: []common.Flag{
-		{Name: "format", Default: "data", Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
+		{Name: "format", Default: "json", Enum: []string{"json", "data"}, Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
 		{Name: "msg-format", Default: "metadata", Desc: "message payload mode: metadata(headers + meta, for triage/notification) | minimal(IDs and state only, no headers, for tracking read/folder changes) | plain_text_full(all metadata fields + full plain-text body) | event(raw WebSocket event, no API call, for debug) | full(full message including HTML body and attachments)"},
 		{Name: "output-dir", Desc: "Write each message as a JSON file (always full payload, regardless of --msg-format)"},
 		{Name: "mailbox", Default: "me", Desc: "email address (default: me)"},
@@ -385,12 +385,7 @@ var MailWatch = common.Shortcut{
 				}
 			}
 
-			switch outFormat {
-			case "json", "":
-				output.PrintNdjson(out, output.Envelope{OK: true, Identity: string(runtime.As()), Data: outputData})
-			case "data":
-				output.PrintNdjson(out, outputData)
-			}
+			output.PrintNdjson(out, watchOutputValue(outFormat, string(runtime.As()), outputData))
 		}
 
 		rawHandler := func(ctx context.Context, event *larkevent.EventReq) error {
@@ -687,6 +682,17 @@ func minimalWatchMessage(message map[string]interface{}) map[string]interface{}
 	return out
 }
 
+// watchOutputValue selects the per-event value that +watch prints as NDJSON:
+// "data" emits the bare payload; every other format (json — the default) wraps
+// it in an ok/identity/data envelope. Extracted from Execute so the default
+// envelope behavior is unit-testable without a live WebSocket.
+func watchOutputValue(outFormat, identity string, outputData interface{}) interface{} {
+	if outFormat == "data" {
+		return outputData
+	}
+	return output.Envelope{OK: true, Identity: identity, Data: outputData}
+}
+
 func watchFetchFailureValue(messageID, fetchFormat string, err error, eventBody map[string]interface{}) map[string]interface{} {
 	payload := map[string]interface{}{
 		"ok": false,

shortcuts/mail/mail_watch_test.go

@@ -885,3 +885,59 @@ func dryRunAPIsForMailWatchTest(t *testing.T, dry *common.DryRunAPI) []struct {
 	}
 	return payload.API
 }
+
+// TestWatchOutputValueDefaultIsJSONEnvelope verifies +watch's default format
+// (json) wraps each event in an ok/identity/data envelope, while --format data
+// emits the bare payload. Covers the default-format behavior without a live
+// WebSocket (addresses the coderabbitai review ask).
+func TestWatchOutputValueDefaultIsJSONEnvelope(t *testing.T) {
+	payload := map[string]interface{}{"message": map[string]interface{}{"message_id": "m1"}}
+
+	// default (json) → ok/identity/data envelope
+	b, err := json.Marshal(watchOutputValue("json", "user", payload))
+	if err != nil {
+		t.Fatalf("marshal json value: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(b, &env); err != nil {
+		t.Fatalf("unmarshal json value: %v", err)
+	}
+	if env["ok"] != true {
+		t.Fatalf("default json must have ok:true, got %s", b)
+	}
+	if env["identity"] != "user" {
+		t.Fatalf("default json must carry identity, got %s", b)
+	}
+	if _, ok := env["data"]; !ok {
+		t.Fatalf("default json must have data field, got %s", b)
+	}
+
+	// empty format (safety) also defaults to the json envelope
+	b3, err := json.Marshal(watchOutputValue("", "bot", payload))
+	if err != nil {
+		t.Fatalf("marshal empty-format value: %v", err)
+	}
+	var env3 map[string]interface{}
+	if err := json.Unmarshal(b3, &env3); err != nil {
+		t.Fatalf("unmarshal empty-format value: %v", err)
+	}
+	if env3["ok"] != true {
+		t.Fatalf("empty format should default to json envelope, got %s", b3)
+	}
+
+	// --format data → bare payload, no envelope
+	b2, err := json.Marshal(watchOutputValue("data", "user", payload))
+	if err != nil {
+		t.Fatalf("marshal data value: %v", err)
+	}
+	var bare map[string]interface{}
+	if err := json.Unmarshal(b2, &bare); err != nil {
+		t.Fatalf("unmarshal data value: %v", err)
+	}
+	if _, hasOK := bare["ok"]; hasOK {
+		t.Fatalf("--format data must be bare (no envelope), got %s", b2)
+	}
+	if _, hasMsg := bare["message"]; !hasMsg {
+		t.Fatalf("--format data payload should carry message, got %s", b2)
+	}
+}

skills/lark-drive/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-drive
 version: 1.0.0
-description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
+description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -21,6 +21,8 @@ metadata:
 ## 快速决策
 
 - 用户要**复制文档 / 创建副本 / 另存为副本**时，使用 `lark-cli drive files copy`。先用 `lark-cli schema drive.files.copy --format json` 确认参数；如果来源是 wiki URL/token，先用 `lark-cli drive +inspect` 获取底层 `token` 和 `type`，不要把 wiki token 直接当 `file_token`。`params.file_token` 传源文档 token，`data.folder_token` 传目标文件夹 token，`data.name` 传副本名称，`data.type` 传源文件类型（如 `docx` / `sheet` / `bitable` / `slides`）。示例：`lark-cli drive files copy --params '{"file_token":"<DOC_TOKEN>"}' --data '{"folder_token":"<FOLDER_TOKEN>","name":"<COPY_NAME>","type":"docx"}'`。如返回 `confirmation_required`，按 `lark-shared` 高风险审批协议向用户确认后，在原命令末尾追加 `--yes` 重试。
+- 用户要**识别飞书 / doubao 云空间 URL 的类型和 token**时，可以先按 URL 路径形态做轻量判断；当路径已明确指向 docx / sheet / bitable / slides / file / folder 等资源时，可直接提取对应 token/type。传入 wiki URL、需要识别标题或 canonical URL、URL/token 有歧义，或后续操作依赖底层真实资源时，再使用 `lark-cli drive +inspect --url '<url>'` 进行识别；具体用法、失败处理和边界见 [`references/lark-drive-inspect.md`](references/lark-drive-inspect.md)。
+- 高风险写操作（删除、公开权限修改、owner 转移、版本删除/回滚、批量移动/覆盖/同步）必须同时满足三个条件才执行：目标已解析为该操作可直接使用的执行对象，执行细节已明确到可直接调用命令（例如删除的 file-token/type、公开权限修改的共享范围、owner 转移的目标 owner、版本删除/回滚的 version id、移动/覆盖/同步的目标位置和冲突策略），且用户在本轮明确确认执行这些具体目标和执行细节。用户只说“删除没用的文件”“开放/共享给大家”“改成开放”“覆盖/移动这些”只表示目标状态；先只读发现并列出候选、权限档位或执行方案，停止等待用户确认。
 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要“权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--created-by-me`，原始创建者语义）、"我负责/owner 的"（→ `--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
@@ -162,7 +164,7 @@ lark-cli drive <resource> <method> [flags] # 调用 API
 
 > **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
 >
-> **高频原生命令：** 读取 Drive 文件夹清单时使用 `drive files list`，必须按 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md) 的模板通过 `--params` 传 `folder_token` / `page_token`，并手动处理分页；不要把 `--page-all` 输出直接交给 JSON 解析脚本。
+> **高频原生命令：** 读取 Drive 文件夹清单时使用 `drive files list`，使用前先读 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md)，按模板通过 `--params` 传参并手动处理分页；不要把 `--page-all` 输出直接交给 JSON 解析脚本。
 
 ### files
 
@@ -204,10 +206,12 @@ lark-cli drive <resource> <method> [flags] # 调用 API
 ### file.statistics
 
   - `get` — 获取文件统计信息
+    - 获取 docx / 文件统计信息时，建议优先使用 typed flags：`lark-cli drive file.statistics get --file-token <token> --file-type <type> --format json`；`--params` JSON 也支持，适合批量拼装或 raw 参数场景。
 
 ### file.view_records
 
   - `list` — 获取文档的访问者记录
+    - 查看 docx 最近访问记录、返回 open_id、最多 N 条时，建议优先使用 typed flags：`lark-cli drive file.view_records list --file-token <docx_token> --file-type docx --page-size <N> --viewer-id-type open_id --format json`；`--params` JSON 也支持，适合批量拼装、分页续跑或 raw 参数场景。
 
 ### file.comment.reply.reactions
 

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

@@ -7,6 +7,18 @@
 
 > [!CAUTION]
 > 这是**高风险写操作**。CLI 层要求显式传 `--yes`；如果用户已经明确要求删除且目标明确，直接执行并带上 `--yes`。
+> “目标明确”表示用户给出了可解析为 `file-token` + `type` 的具体 URL/token，或对你刚列出的可解析资源列表逐项/整批确认删除。按“没用的”“临时的”“疑似重复的”“全部旧文件”等描述搜索出来的候选属于待确认目标；这类请求先列候选、说明筛选依据和影响范围，然后停止等待确认。
+
+## 删除前门槛
+
+执行 `drive +delete --yes` 前同时满足：
+
+| 条件 | 可执行信号 |
+|------|------------|
+| 具体目标 | 单个可解析为 `file-token` + `type` 的 URL/token，或用户确认过且可解析的资源列表 |
+| 执行确认 | 用户在本轮明确说确认删除这些具体目标 |
+
+若缺少任一条件，使用 `drive +search`、`drive +inspect` 或只读 API 收集候选并回复待确认清单；启发式规则（打开时间、标题模式、owner、文件类型等）只能作为候选筛选依据，不能升级为删除确认。执行 `drive +delete` 时必须使用解析后的 `--file-token` 和 `--type`。
 
 ## 命令
 

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

@@ -41,12 +41,37 @@ lark-cli drive files list \
 
 也可以省略 `folder_token` 字段来请求根目录，但在 Agent 编排中建议显式传空字符串，避免把“忘记传参数”和“确认请求根目录”混在一起。
 
+## 按时间排序
+
+默认不要传 `order_by` / `direction`；服务端会按默认顺序返回。只有用户明确要求按创建时间或编辑时间排序时，才使用服务端排序参数。
+
+按创建时间升序列出当前文件夹直接子项：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","order_by":"CreatedTime","direction":"ASC","page_size":200}' \
+  --format json
+```
+
+按编辑时间降序列出当前文件夹直接子项：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","order_by":"EditedTime","direction":"DESC","page_size":200}' \
+  --format json
+```
+
+以上示例返回排序后的当前页；如果返回 `has_more=true`，保持相同 `folder_token` / `order_by` / `direction` / `page_size`，把 `next_page_token` 放入 `page_token` 继续翻页。
+
 ## 参数规则
 
 1. `folder_token` 必须放在 `--params` JSON 里；不要使用不存在的 `--folder-token` flag。
 2. `page_token` 必须放在 `--params` JSON 里；不要依赖 shell 变量拼接不完整的 JSON。
-3. `page_size` 建议显式设置为 `200`。如果服务端或环境返回参数错误，再降级到服务端允许的值，并记录降级原因。
-4. 调用前如果不确定字段结构，先运行 `lark-cli schema drive.files.list` 查看 `--params` 结构。
+3. 默认不要传 `order_by` / `direction`；只有用户明确要求按创建时间 / 编辑时间排序时才使用服务端排序参数。
+4. 排序参数映射：创建时间 -> `order_by:"CreatedTime"`；编辑时间 / 修改时间 -> `order_by:"EditedTime"`；升序 -> `direction:"ASC"`；降序 -> `direction:"DESC"`。不要省略排序参数后再用 Python / shell 客户端排序替代。
+5. 排序查询建议带 `page_size:200` 减少翻页；只有用户要求完整分页、递归盘点、大目录全量导出，或当前页返回 `has_more=true` 后继续翻页时，才加入 `page_token`。
+6. `page_size` 在分页、递归盘点或全量导出时建议显式设置为 `200`。如果服务端或环境返回参数错误，再降级到服务端允许的值，并记录降级原因。
+7. 调用前如果不确定字段结构，先运行 `lark-cli schema drive.files.list` 查看 `--params` 结构。
 
 ## 返回结构与解析
 

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

@@ -47,4 +47,6 @@ JSON 输出包含以下字段：
 - `--url` 为必填参数
 - 当 `--url` 是 bare token（非完整 URL）时，`--type` 也是必填的
 - wiki URL 会自动调用 `get_node` API 解包，输出中 `type` 和 `token` 是底层文档的类型和 token
+- `+inspect` 只用于识别/消歧；如果任务已能通过 URL 路径形态完成路由判断，不必把它作为所有 Drive 操作的通用前置步骤
+- `+inspect` 失败后不要自动切到写接口继续尝试，先按错误提示处理权限、scope 或链接问题
 - 支持 `--dry-run` 查看将调用的 API 步骤

skills/lark-drive/references/lark-drive-permission-guide.md

@@ -10,6 +10,18 @@
 
 如果用户只是想向文档 owner 申请访问权限，优先使用 [`lark-drive-apply-permission.md`](lark-drive-apply-permission.md)。
 
+## 公开权限修改前门槛
+
+公开权限修改是高风险写操作。执行 `drive permission.public patch --yes` 前同时确认：
+
+| 条件 | 可执行信号 |
+|------|------------|
+| 具体目标 | 单个 URL/token，或用户确认过的资源列表 |
+| 公开范围 | 用户明确选择组织内/互联网、可读/可编辑等具体 `link_share_entity` 档位 |
+| 执行确认 | 用户在本轮确认按该目标和范围执行 |
+
+“开放一下”“共享给大家”“让大家能看”只表达目标状态，不包含具体公开范围。先列出可选范围并停止等待用户选择；公开档位必须来自用户选择，CLI 的 `--yes` 只表示已获得用户对该档位的执行确认。
+
 ## 公开权限错误码
 
 调用 `lark-cli drive permission.public patch` 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。

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

@@ -143,6 +143,7 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 | `permission_denied` | `1061004` / HTTP 403 | 当前身份无权操作目标资源 | 停止重试，检查目标文件夹权限、身份类型（user / bot）和资源可见性 |
 | `invalid_api_parameters` | `1061002` | API 参数被服务端拒绝 | 停止重试，检查 `--folder-token`、覆盖模式、`file_token`、文件名和上传参数；不要对同一参数组合批量重试 |
 | `parent_node_missing` | `1061044` | 上传 / 建目录使用的父文件夹不存在或当前身份不可见 | 停止重试，检查 `--folder-token` 是否仍存在、是否有权限、父目录是否在 push 过程中被删除；不要继续上传同一目录树 |
+| `parent_sibling_limit` | `1062507` | 目标父文件夹单层子节点数量超过上限 | 停止重试，清理目标目录、换一个 `--folder-token`，或把上传内容拆到多个子目录 |
 | `rate_limited` | `99991400` | 触发频控 | 停止当前批次，退避后再重试 |
 | `server_error` | `1061001` / `2200` | Drive 服务端异常 | 停止当前批次，稍后重试；保留 `log_id` 便于排查 |
 

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

@@ -49,7 +49,7 @@ lark-cli mail +triage --page-size 10
 |------|------|------|
 | `--filter <json>` | — | 筛选条件（见下方字段说明） |
 | `--query <text>` | — | 全文搜索关键词 |
-| `--format <mode>` | `table` | `table` / `json` / `data`（`json` 和 `data` 均输出含分页信息的对象） |
+| `--format <mode>` | `json` | `json`（默认，输出含分页信息的对象）/ `data`（同 `json`）/ `table`（人类可读表格） |
 | `--max <n>` | `20` | 最大返回条数（1-400），内部自动分页拉取 |
 | `--page-size <n>` | — | `--max` 的别名，两者含义相同；同时指定时 `--page-size` 优先 |
 | `--page-token <token>` | — | 上一次响应返回的分页令牌，传入后从该位置继续拉取。令牌带 `search:` 或 `list:` 前缀，标识来源路径，不可混用 |

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

@@ -47,7 +47,7 @@ lark-cli mail +watch --print-output-schema
 |------|------|------|
 | `--mailbox <id>` | `me` | 订阅目标邮箱 |
 | `--msg-format <mode>` | `metadata` | 输出模式：`metadata` / `minimal` / `plain_text_full` / `full` / `event` |
-| `--format <mode>` | `table` | 输出样式：`table` / `json` / `data` |
+| `--format <mode>` | `json` | 输出样式：`json`（默认，带 ok/data 信封的 NDJSON 流）/ `data`（裸 NDJSON 流） |
 | `--folder-ids <json-array>` | — | 文件夹 ID 过滤，如 `["INBOX","SENT"]` |
 | `--folders <json-array>` | — | 文件夹名称过滤（与 `--folder-ids` 取并集） |
 | `--label-ids <json-array>` | — | 标签 ID 过滤，如 `["FLAGGED","IMPORTANT"]` |