feat: add base record filter and sort json flags (#1228)

* feat: add base record filter and sort json flags

* test: cover base record query flags

CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.46] - 2026-06-02
+
+### Features
+
+- **im**: Add card message format support (#1218)
+- **im**: Resolve markdown blank-line formatting inconsistency in post messages (#1216)
+- **vc**: Inline transcript from artifacts API and add keywords (#1206)
+- **transport**: Add proxy plugin mode for CLI HTTP transport (#1181)
+- **agent**: Increase agent trace max length to 1024 (#1211)
+- **shortcuts**: Unconditionally inject `--format` flag for all shortcuts (#1156)
+
+### Bug Fixes
+
+- **cli**: Remove FLAGS section from root `--help` (#1226)
+- **cli**: Stop root `--help` listing per-command flags as global (#1223)
+
+### Refactor
+
+- **transport**: Own all HTTP transport in `internal/transport`, fix util layering inversion (#1213)
+
+### Documentation
+
+- **base**: Optimize base skill references (#1171)
+- **drive**: Add Lark Drive knowledge organization workflow (#1028)
+
+## [v1.0.45] - 2026-06-01
+
+### Features
+
+- **errors**: Add typed envelope contract for auth-domain errors (#1135)
+- **platform**: Support multiple policy rules per plugin (#1182)
+
+### Bug Fixes
+
+- **vc**: Add domain boundaries and enrich `+notes` (#1172)
+- **whiteboard**: Fix whiteboard skill (#1180)
+
+### Refactor
+
+- **auth**: Update login hint and split-flow docs (#1201)
+
 ## [v1.0.44] - 2026-05-29
 
 ### Features
@@ -948,6 +989,8 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.46]: https://github.com/larksuite/cli/releases/tag/v1.0.46
+[v1.0.45]: https://github.com/larksuite/cli/releases/tag/v1.0.45
 [v1.0.44]: https://github.com/larksuite/cli/releases/tag/v1.0.44
 [v1.0.43]: https://github.com/larksuite/cli/releases/tag/v1.0.43
 [v1.0.42]: https://github.com/larksuite/cli/releases/tag/v1.0.42

cmd/config/init_interactive.go

@@ -6,7 +6,6 @@ package config
 import (
 	"context"
 	"fmt"
-	"net/http"
 
 	"github.com/charmbracelet/huh"
 	"github.com/larksuite/cli/internal/build"
@@ -17,6 +16,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/transport"
 )
 
 // configInitResult holds the result of the interactive config init flow.
@@ -177,7 +177,9 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	}
 
 	// Step 1: Request app registration (begin)
-	httpClient := &http.Client{}
+	// Use the shared proxy-plugin-aware transport so registration traffic is not
+	// a bypass of proxy plugin mode.
+	httpClient := transport.NewHTTPClient(0)
 	authResp, err := larkauth.RequestAppRegistration(httpClient, larkBrand, f.IOStreams.ErrOut)
 	if err != nil {
 		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration failed: %v", err).WithCause(err)

cmd/doctor/doctor.go

@@ -19,6 +19,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/identitydiag"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/update"
 )
 
@@ -152,7 +153,9 @@ func networkChecks(ctx context.Context, opts *DoctorOptions, ep core.Endpoints)
 		}
 	}
 
-	httpClient := &http.Client{}
+	// Use the shared proxy-plugin-aware transport so connectivity checks reflect
+	// the real egress path (and are blocked when proxy plugin fails closed).
+	httpClient := transport.NewHTTPClient(0)
 	mcpURL := ep.MCP + "/mcp"
 
 	type probeResult struct {

cmd/root.go

@@ -48,20 +48,6 @@ EXAMPLES:
     # Generic API call
     lark-cli api GET /open-apis/calendar/v4/calendars
 
-FLAGS:
-    --params <json>       URL/query parameters JSON
-    --data <json>         request body JSON (POST/PATCH/PUT/DELETE)
-    --as <type>           identity type: user | bot
-    --format <fmt>        output format: json (default) | ndjson | table | csv | pretty
-    --page-all            automatically paginate through all pages
-    --page-size <N>       page size (0 = use API default)
-    --page-limit <N>      max pages to fetch with --page-all (default: 10, 0 for unlimited)
-    --page-delay <MS>     delay in ms between pages (default: 200, only with --page-all)
-    -o, --output <path>   output file path for binary responses
-    --jq <expr>           jq expression to filter JSON output
-    -q <expr>             shorthand for --jq
-    --dry-run             print request without executing
-
 AI AGENT SKILLS:
     lark-cli pairs with AI agent skills (Claude Code, etc.) that
     teach the agent Lark API patterns, best practices, and workflows.

internal/auth/transport.go

@@ -14,7 +14,7 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/errclass"
-	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/transport"
 )
 
 // SecurityPolicyTransport is an http.RoundTripper that intercepts all responses
@@ -28,7 +28,7 @@ func (t *SecurityPolicyTransport) base() http.RoundTripper {
 	if t.Base != nil {
 		return t.Base
 	}
-	return util.FallbackTransport()
+	return transport.Fallback()
 }
 
 // RoundTrip implements http.RoundTripper.

internal/cmdutil/factory_default.go

@@ -23,7 +23,7 @@ import (
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/registry"
 	_ "github.com/larksuite/cli/internal/security/contentsafety" // register content safety provider
-	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/transport"
 	_ "github.com/larksuite/cli/internal/vfs/localfileio" // register default FileIO provider
 )
 
@@ -102,15 +102,15 @@ func safeRedirectPolicy(req *http.Request, via []*http.Request) error {
 
 func cachedHttpClientFunc(f *Factory) func() (*http.Client, error) {
 	return sync.OnceValues(func() (*http.Client, error) {
-		util.WarnIfProxied(f.IOStreams.ErrOut)
+		transport.WarnIfProxied(f.IOStreams.ErrOut)
 
-		var transport http.RoundTripper = util.SharedTransport()
-		transport = &RetryTransport{Base: transport}
-		transport = &SecurityHeaderTransport{Base: transport}
-		transport = &auth.SecurityPolicyTransport{Base: transport} // Add our global response interceptor
-		transport = wrapWithExtension(transport)
+		var rt http.RoundTripper = transport.Shared()
+		rt = &RetryTransport{Base: rt}
+		rt = &SecurityHeaderTransport{Base: rt}
+		rt = &auth.SecurityPolicyTransport{Base: rt} // Add our global response interceptor
+		rt = wrapWithExtension(rt)
 		client := &http.Client{
-			Transport:     transport,
+			Transport:     rt,
 			Timeout:       30 * time.Second,
 			CheckRedirect: safeRedirectPolicy,
 		}
@@ -129,7 +129,7 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 			lark.WithLogLevel(larkcore.LogLevelError),
 			lark.WithHeaders(BaseSecurityHeaders()),
 		}
-		util.WarnIfProxied(f.IOStreams.ErrOut)
+		transport.WarnIfProxied(f.IOStreams.ErrOut)
 		opts = append(opts, lark.WithHttpClient(&http.Client{
 			Transport:     buildSDKTransport(),
 			CheckRedirect: safeRedirectPolicy,
@@ -141,7 +141,7 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 }
 
 func buildSDKTransport() http.RoundTripper {
-	var sdkTransport http.RoundTripper = util.SharedTransport()
+	var sdkTransport http.RoundTripper = transport.Shared()
 	sdkTransport = &RetryTransport{Base: sdkTransport}
 	sdkTransport = &UserAgentTransport{Base: sdkTransport}
 	sdkTransport = &BuildHeaderTransport{Base: sdkTransport}

internal/cmdutil/secheader.go

@@ -41,7 +41,7 @@ const (
 
 	officialModulePath = "github.com/larksuite/cli"
 
-	agentTraceMaxLen = 256
+	agentTraceMaxLen = 1024
 )
 
 // UserAgentValue returns the User-Agent value: "lark-cli/{version}".

internal/cmdutil/transport.go

@@ -9,7 +9,7 @@ import (
 	"time"
 
 	exttransport "github.com/larksuite/cli/extension/transport"
-	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/transport"
 )
 
 // RetryTransport is an http.RoundTripper that retries on 5xx responses
@@ -24,7 +24,7 @@ func (t *RetryTransport) base() http.RoundTripper {
 	if t.Base != nil {
 		return t.Base
 	}
-	return util.FallbackTransport()
+	return transport.Fallback()
 }
 
 func (t *RetryTransport) delay() time.Duration {
@@ -69,7 +69,7 @@ func (t *UserAgentTransport) RoundTrip(req *http.Request) (*http.Response, error
 	if t.Base != nil {
 		return t.Base.RoundTrip(req)
 	}
-	return util.FallbackTransport().RoundTrip(req)
+	return transport.Fallback().RoundTrip(req)
 }
 
 // BuildHeaderTransport is an http.RoundTripper that force-writes the
@@ -87,7 +87,7 @@ func (t *BuildHeaderTransport) RoundTrip(req *http.Request) (*http.Response, err
 	if t.Base != nil {
 		return t.Base.RoundTrip(req)
 	}
-	return util.FallbackTransport().RoundTrip(req)
+	return transport.Fallback().RoundTrip(req)
 }
 
 // SecurityHeaderTransport is an http.RoundTripper that injects CLI security
@@ -100,7 +100,7 @@ func (t *SecurityHeaderTransport) base() http.RoundTripper {
 	if t.Base != nil {
 		return t.Base
 	}
-	return util.FallbackTransport()
+	return transport.Fallback()
 }
 
 // RoundTrip implements http.RoundTripper.

internal/cmdutil/transport_test.go

@@ -332,7 +332,7 @@ func TestBuildHeaderTransport_OverridesEvenWithoutTamper(t *testing.T) {
 
 // TestBuildHeaderTransport_NilBase_UsesFallback verifies that when Base is nil,
 // the transport still sets X-Cli-Build and routes the request through
-// util.FallbackTransport rather than panicking. This covers the fallback
+// transport.Fallback rather than panicking. This covers the fallback
 // branch in RoundTrip that is otherwise unreachable with a non-nil Base.
 func TestBuildHeaderTransport_NilBase_UsesFallback(t *testing.T) {
 	var receivedBuild string

internal/envvars/envvars.go

@@ -20,4 +20,8 @@ const (
 	CliContentSafetyMode = "LARKSUITE_CLI_CONTENT_SAFETY_MODE"
 
 	CliAgentTrace = "LARKSUITE_CLI_AGENT_TRACE"
+
+	CliProxyEnable  = "LARKSUITE_CLI_PROXY_ENABLE"
+	CliProxyAddress = "LARKSUITE_CLI_PROXY_ADDRESS"
+	CliCAPath       = "LARKSUITE_CLI_CA_PATH"
 )

internal/registry/remote.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -178,7 +179,9 @@ func saveCachedMerged(data []byte, meta CacheMeta) error {
 // localVersion is sent as data_version query param for server-side version comparison.
 // Returns (data, reg, err). A nil reg means the version is unchanged (not modified).
 func fetchRemoteMerged(localVersion string) (data []byte, reg *MergedRegistry, err error) {
-	client := &http.Client{Timeout: fetchTimeout}
+	// Route through the shared proxy-plugin-aware transport so remote API
+	// definition fetches honor proxy plugin mode instead of bypassing it.
+	client := transport.NewHTTPClient(fetchTimeout)
 	req, err := http.NewRequest("GET", remoteMetaURL(localVersion), nil)
 	if err != nil {
 		return nil, nil, err

internal/transport/config.go

@@ -0,0 +1,243 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package transport owns how the CLI assembles its outbound HTTP transport: the
+// shared base RoundTripper (Shared/Fallback/NewHTTPClient), the LARK_CLI_NO_PROXY
+// direct-egress clone, and the ~/.lark-cli/proxy_config.json proxy-plugin mode.
+//
+// Proxy-plugin mode forces all outbound HTTP(S) requests through a fixed loopback
+// proxy, optionally trusting an extra root CA PEM bundle for TLS-inspection
+// proxies, and fails closed on misconfiguration. Environment variables override
+// matching values from proxy_config.json.
+package transport
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+
+	"github.com/larksuite/cli/internal/binding"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// ConfigFileName is the fixed config file name under core.GetConfigDir().
+const (
+	ConfigFileName = "proxy_config.json"
+)
+
+// Config is the on-disk config format. Keys intentionally mirror env var names.
+type Config struct {
+	// Enable turns on proxy plugin transport handling.
+	Enable bool `json:"LARKSUITE_CLI_PROXY_ENABLE"`
+
+	// Proxy is the fixed HTTP proxy address used for all outbound requests.
+	Proxy string `json:"LARKSUITE_CLI_PROXY_ADDRESS"`
+
+	// CAPath points to an extra PEM bundle trusted for proxy TLS interception.
+	CAPath string `json:"LARKSUITE_CLI_CA_PATH"`
+}
+
+// Path returns the absolute path to the proxy plugin config file.
+func Path() string {
+	return filepath.Join(core.GetConfigDir(), ConfigFileName)
+}
+
+// loadOnce guards one-time proxy config loading for process-wide transport reuse.
+var loadOnce sync.Once
+
+// loadCfg stores the cached proxy config after the first successful Load call.
+var loadCfg *Config
+
+// loadErr stores the cached Load error observed during the first load attempt.
+var loadErr error
+
+// Load reads ~/.lark-cli/proxy_config.json once and caches the parsed result.
+// Environment variables (CliProxyEnable/CliProxyAddress/CliCAPath) take precedence over config file values.
+//
+// Returns (nil, nil) only when:
+//   - the config file does not exist AND
+//   - none of the proxy-related env vars are present.
+func Load() (*Config, error) {
+	loadOnce.Do(func() {
+		// Start from env-only config if any proxy env var is present.
+		cfg, hasEnv, err := loadFromEnv()
+		if err != nil {
+			loadErr = err
+			return
+		}
+
+		p := Path()
+		if _, err := vfs.Stat(p); err != nil {
+			if errors.Is(err, os.ErrNotExist) {
+				// No file: return env-only config (if any), else nil.
+				if hasEnv {
+					loadCfg = cfg
+				} else {
+					loadCfg = nil
+				}
+				loadErr = nil
+				return
+			}
+			loadErr = fmt.Errorf("failed to stat proxy plugin config %q: %w", p, err)
+			return
+		}
+		// Security hardening: this config dictates where ALL outbound CLI traffic
+		// egresses and which extra CA is trusted, so a file another local user or
+		// process can tamper with (symlink, foreign owner, group/world-writable)
+		// could redirect credential traffic. Audit it the same way the CA file is.
+		safePath, err := binding.AssertSecurePath(binding.AuditParams{
+			TargetPath:            p,
+			Label:                 ConfigFileName,
+			AllowReadableByOthers: true, // config is not a secret; only writability/owner/symlink matter
+		})
+		if err != nil {
+			loadErr = fmt.Errorf("unsafe proxy plugin config %q: %w", p, err)
+			return
+		}
+		b, err := vfs.ReadFile(safePath)
+		if err != nil {
+			loadErr = fmt.Errorf("failed to read proxy plugin config %q: %w", p, err)
+			return
+		}
+		var fileCfg Config
+		if err := json.Unmarshal(b, &fileCfg); err != nil {
+			loadErr = fmt.Errorf("invalid proxy plugin config %q: %w", p, err)
+			return
+		}
+
+		// Merge: file base + env overrides.
+		if cfg == nil {
+			cfg = &fileCfg
+		} else {
+			*cfg = fileCfg
+			applyEnvOverrides(cfg)
+		}
+		loadCfg = cfg
+	})
+	return loadCfg, loadErr
+}
+
+// Enabled reports whether proxy plugin mode is enabled.
+func (c *Config) Enabled() bool { return c != nil && c.Enable }
+
+// loadFromEnv builds a config from proxy-related environment variables only.
+// It reports whether any proxy-related environment variable was present.
+func loadFromEnv() (*Config, bool, error) {
+	_, hasEnable := os.LookupEnv(envvars.CliProxyEnable)
+	_, hasProxy := os.LookupEnv(envvars.CliProxyAddress)
+	_, hasCA := os.LookupEnv(envvars.CliCAPath)
+	hasAny := hasEnable || hasProxy || hasCA
+	if !hasAny {
+		return nil, false, nil
+	}
+	cfg := &Config{}
+	if err := applyEnvOverrides(cfg); err != nil {
+		return nil, true, err
+	}
+	return cfg, true, nil
+}
+
+// applyEnvOverrides copies proxy-related environment variable values into cfg.
+func applyEnvOverrides(cfg *Config) error {
+	if v, ok := os.LookupEnv(envvars.CliProxyEnable); ok {
+		b, err := parseBoolEnv(envvars.CliProxyEnable, v)
+		if err != nil {
+			return err
+		}
+		cfg.Enable = b
+	}
+	if v, ok := os.LookupEnv(envvars.CliProxyAddress); ok {
+		cfg.Proxy = v
+	}
+	if v, ok := os.LookupEnv(envvars.CliCAPath); ok {
+		cfg.CAPath = v
+	}
+	return nil
+}
+
+// parseBoolEnv accepts common boolean spellings used in environment variables.
+func parseBoolEnv(name, raw string) (bool, error) {
+	s := strings.TrimSpace(strings.ToLower(raw))
+	if s == "" {
+		// Treat empty as false when explicitly present.
+		return false, nil
+	}
+	switch s {
+	case "1", "true", "on", "yes", "y":
+		return true, nil
+	case "0", "false", "off", "no", "n":
+		return false, nil
+	}
+	if b, err := strconv.ParseBool(s); err == nil {
+		return b, nil
+	}
+	return false, fmt.Errorf("invalid %s %q (want true/false/1/0)", name, raw)
+}
+
+// proxyURL validates the fixed configured proxy configuration and returns its URL.
+func (c *Config) proxyURL() (*url.URL, error) {
+	raw := strings.TrimSpace(c.Proxy)
+	if raw == "" {
+		return nil, fmt.Errorf("%s is empty", envvars.CliProxyAddress)
+	}
+	redacted := redactProxyURL(raw)
+	u, err := url.Parse(raw)
+	if err != nil {
+		// Do not wrap the raw url.Parse error: its string embeds the original
+		// URL, which can contain userinfo (user:password). Return a redacted,
+		// generic message instead.
+		return nil, fmt.Errorf("invalid %s %q: malformed URL", envvars.CliProxyAddress, redacted)
+	}
+	if u.Scheme != "http" {
+		return nil, fmt.Errorf("invalid %s %q: scheme must be http", envvars.CliProxyAddress, redacted)
+	}
+	if u.Host == "" {
+		return nil, fmt.Errorf("invalid %s %q: missing host", envvars.CliProxyAddress, redacted)
+	}
+	// Security hardening: only allow a loopback proxy. This prevents accidental
+	// cross-machine proxying of credentials/traffic.
+	if u.Hostname() != "127.0.0.1" {
+		return nil, fmt.Errorf("invalid %s %q: host must be 127.0.0.1", envvars.CliProxyAddress, redacted)
+	}
+	if u.Port() == "" {
+		return nil, fmt.Errorf("invalid %s %q: explicit port is required", envvars.CliProxyAddress, redacted)
+	}
+	if u.Path != "" {
+		return nil, fmt.Errorf("invalid %s %q: path is not allowed", envvars.CliProxyAddress, redacted)
+	}
+	if u.RawQuery != "" {
+		return nil, fmt.Errorf("invalid %s %q: query is not allowed", envvars.CliProxyAddress, redacted)
+	}
+	if u.Fragment != "" {
+		return nil, fmt.Errorf("invalid %s %q: fragment is not allowed", envvars.CliProxyAddress, redacted)
+	}
+	return u, nil
+}
+
+// ApplyToTransport clones base and applies proxy plugin settings to the clone.
+// Caller owns the returned *http.Transport.
+func (c *Config) ApplyToTransport(base *http.Transport) (*http.Transport, error) {
+	if base == nil {
+		base = http.DefaultTransport.(*http.Transport)
+	}
+	u, err := c.proxyURL()
+	if err != nil {
+		return nil, err
+	}
+
+	t := base.Clone()
+	t.Proxy = http.ProxyURL(u) // fixed proxy overrides environment proxy vars
+	if err := applyExtraRootCA(t, c.CAPath); err != nil {
+		return nil, err
+	}
+	return t, nil
+}

internal/transport/config_test.go

@@ -0,0 +1,372 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/larksuite/cli/internal/envvars"
+)
+
+// unsetEnv clears key for the duration of the test and restores its original value.
+func unsetEnv(t *testing.T, key string) {
+	t.Helper()
+	old, had := os.LookupEnv(key)
+	_ = os.Unsetenv(key)
+	t.Cleanup(func() {
+		if had {
+			_ = os.Setenv(key, old)
+		} else {
+			_ = os.Unsetenv(key)
+		}
+	})
+}
+
+// unsetProxyPluginEnv clears proxy-related environment variables for deterministic tests.
+func unsetProxyPluginEnv(t *testing.T) {
+	t.Helper()
+	unsetEnv(t, envvars.CliProxyEnable)
+	unsetEnv(t, envvars.CliProxyAddress)
+	unsetEnv(t, envvars.CliCAPath)
+}
+
+// writeFile creates parent directories and writes test data for fixtures.
+func writeFile(t *testing.T, path string, data []byte, perm os.FileMode) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	if err := os.WriteFile(path, data, perm); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+}
+
+// TestLoad_MissingFileReturnsNil verifies that Load reports no config when no file
+// or proxy environment overrides exist.
+func TestLoad_MissingFileReturnsNil(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	loadOnce = sync.Once{}
+	loadCfg = nil
+	loadErr = nil
+	unsetProxyPluginEnv(t)
+	// TestLoad_MissingFileReturnsNil must reset loadOnce, loadCfg, and loadErr
+	// because multiple tests in this package share the package-level Load()
+	// cache via sync.Once.
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if cfg != nil {
+		t.Fatalf("Load() = %#v, want nil (missing file)", cfg)
+	}
+}
+
+// TestApplyToTransport_SetsProxy verifies that a valid proxy config installs a fixed proxy.
+func TestApplyToTransport_SetsProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	loadOnce = sync.Once{}
+	loadCfg = nil
+	loadErr = nil
+	unsetProxyPluginEnv(t)
+
+	cfgPath := Path()
+	writeFile(t, cfgPath, []byte(`{
+  "LARKSUITE_CLI_PROXY_ENABLE": true,
+  "LARKSUITE_CLI_PROXY_ADDRESS": "http://127.0.0.1:3128",
+  "LARKSUITE_CLI_CA_PATH": ""
+}`), 0600)
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if cfg == nil || !cfg.Enabled() {
+		t.Fatalf("cfg.Enabled() = %v, want true", cfg)
+	}
+
+	base := http.DefaultTransport.(*http.Transport)
+	tr, err := cfg.ApplyToTransport(base)
+	if err != nil {
+		t.Fatalf("ApplyToTransport() error = %v", err)
+	}
+	if tr.Proxy == nil {
+		t.Fatal("Proxy func is nil, want fixed proxy")
+	}
+	u, err := tr.Proxy(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err != nil {
+		t.Fatalf("Proxy() error = %v", err)
+	}
+	if u == nil || u.String() != "http://127.0.0.1:3128" {
+		t.Fatalf("Proxy() = %v, want http://127.0.0.1:3128", u)
+	}
+}
+
+// TestLoad_RejectsNonLoopbackProxy verifies that proxy mode rejects non-loopback proxies.
+func TestLoad_RejectsNonLoopbackProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	loadOnce = sync.Once{}
+	loadCfg = nil
+	loadErr = nil
+	unsetProxyPluginEnv(t)
+
+	cfgPath := Path()
+	writeFile(t, cfgPath, []byte(`{
+  "LARKSUITE_CLI_PROXY_ENABLE": true,
+  "LARKSUITE_CLI_PROXY_ADDRESS": "http://10.0.0.1:3128",
+  "LARKSUITE_CLI_CA_PATH": ""
+}`), 0600)
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if cfg == nil || !cfg.Enabled() {
+		t.Fatalf("cfg.Enabled() = %v, want true", cfg)
+	}
+	_, err = cfg.ApplyToTransport(http.DefaultTransport.(*http.Transport))
+	if err == nil {
+		t.Fatal("ApplyToTransport() error = nil, want invalid proxy host error")
+	}
+}
+
+// TestConfig_ProxyURLRejectsUnsupportedParts verifies the configured proxy validator
+// rejects URLs with missing ports, paths, queries, and fragments.
+func TestConfig_ProxyURLRejectsUnsupportedParts(t *testing.T) {
+	cases := []struct {
+		name string
+		raw  string
+		want string
+	}{
+		{
+			name: "missing explicit port",
+			raw:  "http://127.0.0.1",
+			want: "explicit port is required",
+		},
+		{
+			name: "trailing slash path",
+			raw:  "http://127.0.0.1:3128/",
+			want: "path is not allowed",
+		},
+		{
+			name: "query string",
+			raw:  "http://127.0.0.1:3128?foo=bar",
+			want: "query is not allowed",
+		},
+		{
+			name: "fragment",
+			raw:  "http://127.0.0.1:3128#frag",
+			want: "fragment is not allowed",
+		},
+	}
+
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := (&Config{Proxy: tt.raw}).proxyURL()
+			if err == nil {
+				t.Fatalf("proxyURL() error = nil, want substring %q", tt.want)
+			}
+			if !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("proxyURL() error = %q, want substring %q", err, tt.want)
+			}
+		})
+	}
+}
+
+// TestLoad_EnvOnlyConfig verifies that proxy settings can come entirely from environment variables.
+func TestLoad_EnvOnlyConfig(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	loadOnce = sync.Once{}
+	loadCfg = nil
+	loadErr = nil
+
+	t.Setenv(envvars.CliProxyEnable, "true")
+	t.Setenv(envvars.CliProxyAddress, "http://127.0.0.1:7777")
+	t.Setenv(envvars.CliCAPath, "")
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if cfg == nil || !cfg.Enabled() {
+		t.Fatalf("cfg.Enabled() = %v, want true", cfg)
+	}
+	tr, err := cfg.ApplyToTransport(http.DefaultTransport.(*http.Transport))
+	if err != nil {
+		t.Fatalf("ApplyToTransport() error = %v", err)
+	}
+	u, err := tr.Proxy(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err != nil {
+		t.Fatalf("Proxy() error = %v", err)
+	}
+	if u == nil || u.String() != "http://127.0.0.1:7777" {
+		t.Fatalf("Proxy() = %v, want http://127.0.0.1:7777", u)
+	}
+}
+
+// TestLoad_EnvOverridesFile verifies that proxy environment variables override file values.
+func TestLoad_EnvOverridesFile(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	loadOnce = sync.Once{}
+	loadCfg = nil
+	loadErr = nil
+
+	// File enables with one proxy.
+	cfgPath := Path()
+	writeFile(t, cfgPath, []byte(`{
+  "LARKSUITE_CLI_PROXY_ENABLE": true,
+  "LARKSUITE_CLI_PROXY_ADDRESS": "http://127.0.0.1:3128",
+  "LARKSUITE_CLI_CA_PATH": ""
+}`), 0600)
+
+	// Env overrides: disable + different proxy (should be irrelevant once disabled).
+	t.Setenv(envvars.CliProxyEnable, "false")
+	t.Setenv(envvars.CliProxyAddress, "http://127.0.0.1:9999")
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if cfg == nil {
+		t.Fatalf("Load() = nil, want non-nil (file exists)")
+	}
+	if cfg.Enabled() {
+		t.Fatalf("cfg.Enabled() = true, want false (env override)")
+	}
+}
+
+// TestConfig_ProxyURLMalformedDoesNotLeakUserinfo verifies that a malformed proxy
+// URL containing credentials does not leak those credentials in the error string.
+// url.Parse error strings embed the original URL, so wrapping them with %w would
+// expose user:password.
+func TestConfig_ProxyURLMalformedDoesNotLeakUserinfo(t *testing.T) {
+	// Invalid percent-encoding in host makes url.Parse fail while userinfo is present.
+	raw := "http://user:s3cret@%zz"
+	_, err := (&Config{Proxy: raw}).proxyURL()
+	if err == nil {
+		t.Fatal("proxyURL() error = nil, want malformed URL error")
+	}
+	if strings.Contains(err.Error(), "s3cret") {
+		t.Fatalf("proxyURL() error leaks password: %q", err)
+	}
+	if strings.Contains(err.Error(), "user:") {
+		t.Fatalf("proxyURL() error leaks username: %q", err)
+	}
+	if !strings.Contains(err.Error(), "malformed URL") {
+		t.Fatalf("proxyURL() error = %q, want it to mention malformed URL", err)
+	}
+	// The redacted form should still be present for diagnostics.
+	if !strings.Contains(err.Error(), "***") {
+		t.Fatalf("proxyURL() error = %q, want redacted userinfo marker", err)
+	}
+}
+
+// resetLoadState resets the package-level Load() cache for deterministic tests.
+func resetLoadState() {
+	loadOnce = sync.Once{}
+	loadCfg = nil
+	loadErr = nil
+}
+
+// TestLoad_RejectsWorldWritableConfig verifies that a world-writable proxy config
+// is rejected rather than silently trusted (it could be tampered with by other
+// local processes to redirect credential traffic).
+func TestLoad_RejectsWorldWritableConfig(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("POSIX permission semantics")
+	}
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	resetLoadState()
+	unsetProxyPluginEnv(t)
+
+	p := Path()
+	writeFile(t, p, []byte(`{"LARKSUITE_CLI_PROXY_ENABLE":true,"LARKSUITE_CLI_PROXY_ADDRESS":"http://127.0.0.1:3128"}`), 0600)
+	// Chmod (not WriteFile perm) so umask cannot strip the world-writable bit.
+	if err := os.Chmod(p, 0o666); err != nil {
+		t.Fatalf("Chmod: %v", err)
+	}
+
+	_, err := Load()
+	if err == nil {
+		t.Fatal("Load() error = nil, want unsafe-config error for world-writable file")
+	}
+	if !strings.Contains(err.Error(), "world-writable") {
+		t.Fatalf("Load() error = %q, want world-writable rejection", err)
+	}
+}
+
+// TestLoad_RejectsGroupWritableConfig verifies group-writable configs are rejected.
+func TestLoad_RejectsGroupWritableConfig(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("POSIX permission semantics")
+	}
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	resetLoadState()
+	unsetProxyPluginEnv(t)
+
+	p := Path()
+	writeFile(t, p, []byte(`{"LARKSUITE_CLI_PROXY_ENABLE":true,"LARKSUITE_CLI_PROXY_ADDRESS":"http://127.0.0.1:3128"}`), 0600)
+	if err := os.Chmod(p, 0o660); err != nil {
+		t.Fatalf("Chmod: %v", err)
+	}
+
+	_, err := Load()
+	if err == nil {
+		t.Fatal("Load() error = nil, want unsafe-config error for group-writable file")
+	}
+	if !strings.Contains(err.Error(), "group-writable") {
+		t.Fatalf("Load() error = %q, want group-writable rejection", err)
+	}
+}
+
+// TestLoad_RejectsSymlinkConfig verifies that a symlinked proxy config is rejected,
+// preventing redirection of the trusted config path to an attacker-controlled file.
+func TestLoad_RejectsSymlinkConfig(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symlink creation is privileged on Windows")
+	}
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	resetLoadState()
+	unsetProxyPluginEnv(t)
+
+	// Real file lives elsewhere; the config path is a symlink to it.
+	real := filepath.Join(dir, "real_proxy_config.json")
+	writeFile(t, real, []byte(`{"LARKSUITE_CLI_PROXY_ENABLE":true,"LARKSUITE_CLI_PROXY_ADDRESS":"http://127.0.0.1:3128"}`), 0600)
+	if err := os.Symlink(real, Path()); err != nil {
+		t.Fatalf("Symlink: %v", err)
+	}
+
+	_, err := Load()
+	if err == nil {
+		t.Fatal("Load() error = nil, want unsafe-config error for symlinked file")
+	}
+	if !strings.Contains(err.Error(), "symlink") {
+		t.Fatalf("Load() error = %q, want symlink rejection", err)
+	}
+}
+
+// TestLoad_AcceptsSecureConfig verifies the audit does not break the normal case:
+// an owner-only 0600 config still loads.
+func TestLoad_AcceptsSecureConfig(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	resetLoadState()
+	unsetProxyPluginEnv(t)
+
+	writeFile(t, Path(), []byte(`{"LARKSUITE_CLI_PROXY_ENABLE":true,"LARKSUITE_CLI_PROXY_ADDRESS":"http://127.0.0.1:3128"}`), 0600)
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error = %v, want nil for secure 0600 config", err)
+	}
+	if cfg == nil || !cfg.Enabled() {
+		t.Fatalf("cfg.Enabled() = %v, want true", cfg)
+	}
+}

internal/transport/shared.go

@@ -0,0 +1,83 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"net/http"
+	"os"
+	"sync"
+	"time"
+)
+
+// Shared returns the base http.RoundTripper for all CLI HTTP clients.
+//
+// Precedence (highest first):
+//  1. proxy-plugin mode — force traffic through a fixed loopback proxy;
+//     FAIL-CLOSED when the plugin config exists but is invalid.
+//  2. LARK_CLI_NO_PROXY — direct egress, proxy disabled.
+//  3. http.DefaultTransport — the stdlib process-wide singleton (honors
+//     HTTP(S)_PROXY), so every client shares one connection pool / TLS cache.
+//
+// The returned RoundTripper MUST NOT be mutated. Callers that need a customized
+// transport should assert to *http.Transport and Clone() it. A shared base is
+// required so persistConn read/write goroutines are reused; cloning per call
+// leaks them until IdleConnTimeout (~90s) fires.
+func Shared() http.RoundTripper {
+	// Proxy-plugin mode overrides everything, INCLUDING LARK_CLI_NO_PROXY. When
+	// the plugin config exists but is invalid, pluginTransport returns a
+	// fail-closed transport with ok=true and we return it here — we MUST NOT
+	// fall through to the NO_PROXY / DefaultTransport direct-egress paths below.
+	if t, ok := pluginTransport(); ok {
+		return t
+	}
+	if os.Getenv(EnvNoProxy) != "" {
+		return noProxyTransport()
+	}
+	return http.DefaultTransport
+}
+
+// Fallback returns a shared *http.Transport. It is a thin wrapper over Shared
+// retained so modules already on the leak-free singleton path (internal/auth,
+// internal/cmdutil transport decorators) do not have to migrate. New code
+// should prefer Shared and treat the base as an http.RoundTripper.
+//
+// Fail-closed invariant: pluginTransport always expresses its blocked transport
+// as a concrete *http.Transport (see failClosedTransport), so the assertion
+// below preserves the block. The noProxyTransport() fallback is therefore only
+// reached when no proxy plugin is configured and some external code replaced
+// http.DefaultTransport with a non-*http.Transport — a case with no fail-closed
+// intent, where a proxy-disabled transport is acceptable.
+func Fallback() *http.Transport {
+	if t, ok := Shared().(*http.Transport); ok {
+		return t
+	}
+	return noProxyTransport()
+}
+
+// NewHTTPClient returns an *http.Client whose Transport is the shared,
+// proxy-plugin-aware base (see Shared). Prefer this over a bare &http.Client{}
+// for outbound requests: a bare client falls back to http.DefaultTransport and
+// therefore silently bypasses proxy plugin mode (fixed proxy + trusted CA, or
+// fail-closed), creating an audit blind spot.
+//
+// A zero timeout means no client-level timeout (callers relying on context
+// deadlines pass 0).
+func NewHTTPClient(timeout time.Duration) *http.Client {
+	return &http.Client{
+		Transport: Shared(),
+		Timeout:   timeout,
+	}
+}
+
+// noProxyTransport is a proxy-disabled clone of http.DefaultTransport, lazily
+// built the first time LARK_CLI_NO_PROXY is observed set.
+var noProxyTransport = sync.OnceValue(func() *http.Transport {
+	def, ok := http.DefaultTransport.(*http.Transport)
+	if !ok {
+		return &http.Transport{}
+	}
+	t := def.Clone()
+	t.Proxy = nil
+	return t
+})

internal/transport/shared_test.go

@@ -0,0 +1,156 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"net/http"
+	"net/url"
+	"testing"
+	"time"
+)
+
+// TestShared_DefaultReturnsStdlibSingleton verifies the default shared transport.
+func TestShared_DefaultReturnsStdlibSingleton(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv(EnvNoProxy, "")
+	if Shared() != http.DefaultTransport {
+		t.Error("Shared should return http.DefaultTransport when LARK_CLI_NO_PROXY is unset")
+	}
+}
+
+// TestShared_NoProxyReturnsClone verifies that disabling proxying returns a cloned transport.
+func TestShared_NoProxyReturnsClone(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv(EnvNoProxy, "1")
+	tr := Shared()
+	if tr == http.DefaultTransport {
+		t.Fatal("Shared should return a clone, not DefaultTransport, when LARK_CLI_NO_PROXY is set")
+	}
+	ht, ok := tr.(*http.Transport)
+	if !ok {
+		t.Fatalf("expected *http.Transport, got %T", tr)
+	}
+	if ht.Proxy != nil {
+		t.Error("no-proxy transport should have Proxy == nil")
+	}
+}
+
+// TestShared_NoProxyIsCachedSingleton verifies singleton caching for the no-proxy transport.
+func TestShared_NoProxyIsCachedSingleton(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv(EnvNoProxy, "1")
+	if Shared() != Shared() {
+		t.Error("repeated Shared calls with LARK_CLI_NO_PROXY set must return the same instance")
+	}
+}
+
+// TestShared_EnvUnsetAfterSetFallsBackToDefault verifies fallback to the stdlib
+// transport after unsetting LARK_CLI_NO_PROXY.
+func TestShared_EnvUnsetAfterSetFallsBackToDefault(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	// Simulate a process that first runs with LARK_CLI_NO_PROXY=1 (populating
+	// the no-proxy singleton), then unsets it. Subsequent calls must return
+	// http.DefaultTransport, NOT the cached no-proxy clone.
+	t.Setenv(EnvNoProxy, "1")
+	if Shared() == http.DefaultTransport {
+		t.Fatal("precondition: first call with env set should not return DefaultTransport")
+	}
+
+	t.Setenv(EnvNoProxy, "")
+	if after := Shared(); after != http.DefaultTransport {
+		t.Errorf("after unsetting LARK_CLI_NO_PROXY, Shared must return http.DefaultTransport, got %T", after)
+	}
+}
+
+// TestShared_NoProxyOverridesSystemProxy verifies that LARK_CLI_NO_PROXY disables system proxies.
+func TestShared_NoProxyOverridesSystemProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv("HTTPS_PROXY", "http://should-be-ignored:8888")
+	t.Setenv(EnvNoProxy, "1")
+
+	ht, ok := Shared().(*http.Transport)
+	if !ok {
+		t.Fatalf("expected *http.Transport, got %T", Shared())
+	}
+	if ht.Proxy != nil {
+		t.Error("LARK_CLI_NO_PROXY should override system proxy settings")
+	}
+}
+
+// TestNewHTTPClient verifies the factory wires the shared proxy-plugin-aware
+// transport (instead of a bare client that bypasses proxy plugin mode).
+func TestNewHTTPClient(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	t.Setenv(EnvNoProxy, "")
+
+	c := NewHTTPClient(7 * time.Second)
+	if c.Transport == nil {
+		t.Fatal("NewHTTPClient transport is nil; want shared transport")
+	}
+	if c.Transport != Shared() {
+		t.Errorf("NewHTTPClient transport = %v, want Shared()", c.Transport)
+	}
+	if c.Timeout != 7*time.Second {
+		t.Errorf("NewHTTPClient timeout = %v, want 7s", c.Timeout)
+	}
+}
+
+// TestShared_PluginOverridesNoProxy locks the contract that proxy-plugin mode wins
+// over LARK_CLI_NO_PROXY: even with NO_PROXY set, an enabled plugin forces the proxy.
+func TestShared_PluginOverridesNoProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	t.Setenv(EnvNoProxy, "1") // NO_PROXY set, but the plugin must win
+	resetProxyPluginState()
+
+	writeFile(t, Path(), []byte(`{
+  "LARKSUITE_CLI_PROXY_ENABLE": true,
+  "LARKSUITE_CLI_PROXY_ADDRESS": "http://127.0.0.1:3128"
+}`), 0600)
+
+	tr, ok := Shared().(*http.Transport)
+	if !ok {
+		t.Fatalf("Shared() = %T, want proxy *http.Transport, not the NO_PROXY clone", tr)
+	}
+	u, err := tr.Proxy(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err != nil || u == nil || u.String() != "http://127.0.0.1:3128" {
+		t.Fatalf("Proxy() = %v, %v; plugin must override NO_PROXY with the fixed proxy", u, err)
+	}
+}
+
+// TestShared_MalformedConfigFailsClosedEvenWithNoProxy locks the most dangerous
+// invariant of the fold: a malformed proxy_config.json must FAIL CLOSED, never
+// fall through to direct egress — not even to the LARK_CLI_NO_PROXY clone.
+func TestShared_MalformedConfigFailsClosedEvenWithNoProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	t.Setenv(EnvNoProxy, "1")
+	resetProxyPluginState()
+
+	writeFile(t, Path(), []byte(`{`), 0600) // malformed
+
+	rt := Shared()
+	if rt == http.DefaultTransport {
+		t.Fatal("malformed config returned http.DefaultTransport — fail OPEN")
+	}
+	if rt == noProxyTransport() {
+		t.Fatal("malformed config fell through to the NO_PROXY direct-egress clone — fail OPEN")
+	}
+	resp, err := rt.RoundTrip(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err == nil {
+		t.Fatalf("RoundTrip() err = nil (resp=%v); malformed config must fail closed", resp)
+	}
+}

internal/transport/tls_ca.go

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"crypto/tls"
+	"crypto/x509"
+	"fmt"
+	"net/http"
+	"path/filepath"
+	"strings"
+
+	"github.com/larksuite/cli/internal/binding"
+	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// applyExtraRootCA augments t with an additional PEM bundle used for configured proxy
+// TLS interception.
+func applyExtraRootCA(t *http.Transport, caPath string) error {
+	caPath = strings.TrimSpace(caPath)
+	if caPath == "" {
+		return nil
+	}
+	if !filepath.IsAbs(caPath) {
+		return fmt.Errorf("invalid %s %q: must be an absolute path to a PEM file", envvars.CliCAPath, caPath)
+	}
+	safeCAPath, err := binding.AssertSecurePath(binding.AuditParams{
+		TargetPath:            caPath,
+		Label:                 envvars.CliCAPath,
+		AllowReadableByOthers: true,
+	})
+	if err != nil {
+		return fmt.Errorf("unsafe %s %q: %w", envvars.CliCAPath, caPath, err)
+	}
+	pemBytes, err := vfs.ReadFile(safeCAPath)
+	if err != nil {
+		return fmt.Errorf("failed to read %s %q: %w", envvars.CliCAPath, caPath, err)
+	}
+
+	// Augment the system trust store. Do NOT silently discard a SystemCertPool
+	// error: falling back to an empty pool would make this transport trust ONLY
+	// the extra CA (dropping all system roots), which narrows trust unexpectedly
+	// and could break TLS to legitimate endpoints. Fail closed instead.
+	pool, err := x509.SystemCertPool()
+	if err != nil {
+		return fmt.Errorf("failed to load system cert pool for %s: %w", envvars.CliCAPath, err)
+	}
+	if pool == nil {
+		pool = x509.NewCertPool()
+	}
+	if ok := pool.AppendCertsFromPEM(pemBytes); !ok {
+		return fmt.Errorf("invalid %s %q: no certificates parsed from PEM", envvars.CliCAPath, caPath)
+	}
+
+	if t.TLSClientConfig == nil {
+		t.TLSClientConfig = &tls.Config{}
+	} else {
+		// Clone to avoid mutating shared config from the base transport.
+		t.TLSClientConfig = t.TLSClientConfig.Clone()
+	}
+	if t.TLSClientConfig.MinVersion == 0 || t.TLSClientConfig.MinVersion < tls.VersionTLS12 {
+		t.TLSClientConfig.MinVersion = tls.VersionTLS12
+	}
+	t.TLSClientConfig.RootCAs = pool
+	return nil
+}

internal/transport/tls_ca_test.go

@@ -0,0 +1,173 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/pem"
+	"math/big"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// mustCreateTestCertPEM generates a short-lived self-signed CA certificate for tests.
+func mustCreateTestCertPEM(t *testing.T) []byte {
+	t.Helper()
+
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("GenerateKey() error = %v", err)
+	}
+
+	der, err := x509.CreateCertificate(rand.Reader, &x509.Certificate{
+		SerialNumber: big.NewInt(1),
+		Subject: pkix.Name{
+			CommonName: "proxyplugin-test-ca",
+		},
+		NotBefore:             time.Now().Add(-time.Hour),
+		NotAfter:              time.Now().Add(time.Hour),
+		KeyUsage:              x509.KeyUsageCertSign | x509.KeyUsageCRLSign,
+		IsCA:                  true,
+		BasicConstraintsValid: true,
+	}, &x509.Certificate{
+		SerialNumber: big.NewInt(1),
+		Subject: pkix.Name{
+			CommonName: "proxyplugin-test-ca",
+		},
+		NotBefore:             time.Now().Add(-time.Hour),
+		NotAfter:              time.Now().Add(time.Hour),
+		KeyUsage:              x509.KeyUsageCertSign | x509.KeyUsageCRLSign,
+		IsCA:                  true,
+		BasicConstraintsValid: true,
+	}, &key.PublicKey, key)
+	if err != nil {
+		t.Fatalf("CreateCertificate() error = %v", err)
+	}
+
+	return pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
+}
+
+// TestApplyExtraRootCA_EmptyPathIsNoop verifies that an empty CA path leaves the transport unchanged.
+func TestApplyExtraRootCA_EmptyPathIsNoop(t *testing.T) {
+	tr := &http.Transport{}
+
+	if err := applyExtraRootCA(tr, "   "); err != nil {
+		t.Fatalf("applyExtraRootCA() error = %v", err)
+	}
+	if tr.TLSClientConfig != nil {
+		t.Fatalf("TLSClientConfig = %#v, want nil", tr.TLSClientConfig)
+	}
+}
+
+// TestApplyExtraRootCA_RejectsRelativePath verifies that CA paths must be absolute.
+func TestApplyExtraRootCA_RejectsRelativePath(t *testing.T) {
+	tr := &http.Transport{}
+
+	err := applyExtraRootCA(tr, "ca.pem")
+	if err == nil || !strings.Contains(err.Error(), "must be an absolute path") {
+		t.Fatalf("applyExtraRootCA() error = %v, want absolute-path error", err)
+	}
+}
+
+// TestApplyExtraRootCA_RejectsMissingFile verifies missing PEM bundles fail before file reads.
+func TestApplyExtraRootCA_RejectsMissingFile(t *testing.T) {
+	tr := &http.Transport{}
+
+	err := applyExtraRootCA(tr, filepath.Join(t.TempDir(), "missing.pem"))
+	if err == nil || !strings.Contains(err.Error(), "unsafe") {
+		t.Fatalf("applyExtraRootCA() error = %v, want unsafe path error", err)
+	}
+}
+
+// TestApplyExtraRootCA_RejectsInvalidPEM verifies validation of malformed PEM bundles.
+func TestApplyExtraRootCA_RejectsInvalidPEM(t *testing.T) {
+	caPath := filepath.Join(t.TempDir(), "invalid.pem")
+	writeFile(t, caPath, []byte("not a pem"), 0600)
+
+	tr := &http.Transport{}
+	err := applyExtraRootCA(tr, caPath)
+	if err == nil || !strings.Contains(err.Error(), "no certificates parsed from PEM") {
+		t.Fatalf("applyExtraRootCA() error = %v, want invalid PEM error", err)
+	}
+}
+
+// TestApplyExtraRootCA_RejectsInsecureCAPath verifies CA paths are safety-checked
+// before reading the configured file.
+func TestApplyExtraRootCA_RejectsInsecureCAPath(t *testing.T) {
+	caPath := filepath.Join(t.TempDir(), "ca.pem")
+	writeFile(t, caPath, mustCreateTestCertPEM(t), 0600)
+	if err := os.Chmod(caPath, 0666); err != nil {
+		t.Fatalf("Chmod() error = %v", err)
+	}
+
+	tr := &http.Transport{}
+	err := applyExtraRootCA(tr, caPath)
+	if err == nil || !strings.Contains(err.Error(), "unsafe") {
+		t.Fatalf("applyExtraRootCA() error = %v, want unsafe path error", err)
+	}
+	if tr.TLSClientConfig != nil {
+		t.Fatalf("TLSClientConfig = %#v, want nil", tr.TLSClientConfig)
+	}
+}
+
+// TestApplyExtraRootCA_SetsTLSConfigWhenMissing verifies initialization of TLSClientConfig when absent.
+func TestApplyExtraRootCA_SetsTLSConfigWhenMissing(t *testing.T) {
+	caPath := filepath.Join(t.TempDir(), "ca.pem")
+	writeFile(t, caPath, mustCreateTestCertPEM(t), 0600)
+
+	tr := &http.Transport{}
+	if err := applyExtraRootCA(tr, caPath); err != nil {
+		t.Fatalf("applyExtraRootCA() error = %v", err)
+	}
+	if tr.TLSClientConfig == nil {
+		t.Fatal("TLSClientConfig = nil, want initialized config")
+	}
+	if tr.TLSClientConfig.RootCAs == nil {
+		t.Fatal("RootCAs = nil, want cert pool")
+	}
+}
+
+// TestApplyExtraRootCA_ClonesExistingTLSConfig verifies cloning when the base transport already has TLS settings.
+func TestApplyExtraRootCA_ClonesExistingTLSConfig(t *testing.T) {
+	caPath := filepath.Join(t.TempDir(), "ca.pem")
+	writeFile(t, caPath, mustCreateTestCertPEM(t), 0600)
+
+	original := &tls.Config{ServerName: "open.feishu.cn"}
+	tr := &http.Transport{TLSClientConfig: original}
+	if err := applyExtraRootCA(tr, caPath); err != nil {
+		t.Fatalf("applyExtraRootCA() error = %v", err)
+	}
+	if tr.TLSClientConfig == original {
+		t.Fatal("TLSClientConfig pointer reused, want clone")
+	}
+	if tr.TLSClientConfig.ServerName != original.ServerName {
+		t.Fatalf("ServerName = %q, want %q", tr.TLSClientConfig.ServerName, original.ServerName)
+	}
+	if tr.TLSClientConfig.RootCAs == nil {
+		t.Fatal("RootCAs = nil, want cert pool")
+	}
+}
+
+// TestApplyExtraRootCA_PreservesHigherTLSMinVersion verifies that adding a CA
+// does not relax an existing stricter TLS version floor.
+func TestApplyExtraRootCA_PreservesHigherTLSMinVersion(t *testing.T) {
+	caPath := filepath.Join(t.TempDir(), "ca.pem")
+	writeFile(t, caPath, mustCreateTestCertPEM(t), 0600)
+
+	tr := &http.Transport{TLSClientConfig: &tls.Config{MinVersion: tls.VersionTLS13}}
+	if err := applyExtraRootCA(tr, caPath); err != nil {
+		t.Fatalf("applyExtraRootCA() error = %v", err)
+	}
+	if tr.TLSClientConfig.MinVersion != tls.VersionTLS13 {
+		t.Fatalf("MinVersion = %x, want %x", tr.TLSClientConfig.MinVersion, tls.VersionTLS13)
+	}
+}

internal/transport/transport.go

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"fmt"
+	"net/http"
+	"net/url"
+	"sync"
+)
+
+// proxyPluginTransport is a fixed-proxy clone of http.DefaultTransport (with optional
+// custom root CA), lazily built on first use when proxy plugin mode is enabled.
+var proxyPluginTransport = sync.OnceValue(buildProxyPluginTransport)
+
+// cachedBlockedTransport is a fail-closed transport cached on first use when
+// the proxy plugin config exists but is invalid. This avoids cloning
+// http.DefaultTransport on every pluginTransport call.
+var cachedBlockedTransport = sync.OnceValue(buildBlockedTransport)
+
+func buildBlockedTransport() http.RoundTripper {
+	return failClosedTransport(fmt.Errorf("proxy plugin config is invalid: %w", loadErr))
+}
+
+func buildProxyPluginTransport() http.RoundTripper {
+	def, ok := http.DefaultTransport.(*http.Transport)
+	if !ok {
+		// Cannot clone the stdlib transport. Fail closed with a concrete
+		// *http.Transport (not a bare RoundTripper) so downcasting callers such
+		// as Fallback cannot silently degrade this into a
+		// direct-egress transport.
+		return failClosedTransport(fmt.Errorf("proxy plugin transport unavailable: http.DefaultTransport is %T, want *http.Transport", http.DefaultTransport))
+	}
+
+	cfg, err := Load()
+	if err != nil {
+		// Fail closed: config file exists but is malformed/unreadable — do not
+		// silently fall back to direct egress.
+		return blockedTransport(def, fmt.Errorf("proxy plugin config is invalid: %w", err))
+	}
+	if cfg == nil || !cfg.Enabled() {
+		return def
+	}
+	t, err := cfg.ApplyToTransport(def)
+	if err != nil {
+		// Fail closed: do not silently fall back to direct egress when the
+		// operator explicitly enabled proxy plugin mode.
+		return blockedTransport(def, fmt.Errorf("proxy plugin enabled but config is invalid: %w", err))
+	}
+	return t
+}
+
+// pluginTransport returns the proxy plugin transport when proxy plugin mode is
+// configured. The bool return is false when the plugin is not configured or not enabled.
+func pluginTransport() (http.RoundTripper, bool) {
+	cfg, err := Load()
+	if err != nil {
+		return cachedBlockedTransport(), true
+	}
+	if cfg == nil || !cfg.Enabled() {
+		return nil, false
+	}
+	return proxyPluginTransport(), true
+}
+
+// failClosedTransport returns a *http.Transport that always fails RoundTrip with
+// err. It clones http.DefaultTransport when possible (preserving dial/timeout
+// tuning); otherwise it builds a minimal transport. Returning a concrete
+// *http.Transport (rather than a bare RoundTripper) is required so downcasting
+// callers such as Fallback cannot silently degrade a fail-closed
+// signal into a direct-egress transport.
+func failClosedTransport(err error) *http.Transport {
+	if def, ok := http.DefaultTransport.(*http.Transport); ok {
+		return blockedTransport(def, err)
+	}
+	return &http.Transport{
+		Proxy: func(*http.Request) (*url.URL, error) {
+			return nil, err
+		},
+	}
+}
+
+func blockedTransport(base *http.Transport, err error) *http.Transport {
+	blocked := base.Clone()
+	blocked.Proxy = func(*http.Request) (*url.URL, error) {
+		return nil, err
+	}
+	return blocked
+}

internal/transport/transport_test.go

@@ -0,0 +1,195 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"testing"
+)
+
+func resetProxyPluginState() {
+	loadOnce = sync.Once{}
+	loadCfg = nil
+	loadErr = nil
+	proxyPluginTransport = sync.OnceValue(buildProxyPluginTransport)
+	cachedBlockedTransport = sync.OnceValue(buildBlockedTransport)
+}
+
+func TestPluginTransport_NotConfigured(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+
+	tr, ok := pluginTransport()
+	if ok {
+		t.Fatalf("pluginTransport() ok = true, want false")
+	}
+	if tr != nil {
+		t.Fatalf("pluginTransport() transport = %T, want nil", tr)
+	}
+}
+
+func TestPluginTransport_EnabledReturnsFixedProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+
+	cfgPath := Path()
+	writeFile(t, cfgPath, []byte(`{
+  "LARKSUITE_CLI_PROXY_ENABLE": true,
+  "LARKSUITE_CLI_PROXY_ADDRESS": "http://127.0.0.1:3128",
+  "LARKSUITE_CLI_CA_PATH": ""
+}`), 0600)
+
+	rt, ok := pluginTransport()
+	if !ok {
+		t.Fatal("pluginTransport() ok = false, want true")
+	}
+	tr, ok := rt.(*http.Transport)
+	if !ok {
+		t.Fatalf("pluginTransport() = %T, want *http.Transport", rt)
+	}
+	u, err := tr.Proxy(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err != nil {
+		t.Fatalf("Proxy() error = %v", err)
+	}
+	if u == nil || u.String() != "http://127.0.0.1:3128" {
+		t.Fatalf("Proxy() = %v, want http://127.0.0.1:3128", u)
+	}
+}
+
+func TestPluginTransport_InvalidConfigWithNonTransportDefaultFailsClosed(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	restoreDefaultTransport := replaceDefaultTransport(okRoundTripper{})
+	defer restoreDefaultTransport()
+
+	writeFile(t, Path(), []byte(`{`), 0600)
+
+	rt, ok := pluginTransport()
+	if !ok {
+		t.Fatal("pluginTransport() ok = false, want true")
+	}
+	if rt == http.DefaultTransport {
+		t.Fatalf("pluginTransport() returned http.DefaultTransport, want fail-closed transport")
+	}
+	resp, err := rt.RoundTrip(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err == nil {
+		t.Fatalf("RoundTrip() error = nil, response = %#v; want fail-closed error", resp)
+	}
+	if resp != nil {
+		t.Fatalf("RoundTrip() response = %#v, want nil", resp)
+	}
+}
+
+func TestPluginTransport_InvalidConfigReturnsCachedInstance(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+
+	writeFile(t, Path(), []byte(`{`), 0600)
+
+	a, ok := pluginTransport()
+	if !ok {
+		t.Fatal("pluginTransport() ok = false, want true")
+	}
+	b, ok := pluginTransport()
+	if !ok {
+		t.Fatal("pluginTransport() ok = false, want true")
+	}
+	if a != b {
+		t.Fatalf("pluginTransport() returned different instances on repeated calls; blocked transport must be cached")
+	}
+}
+
+func TestBuildProxyPluginTransport_InvalidConfigFailsClosed(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+
+	writeFile(t, Path(), []byte(`{`), 0600)
+
+	rt := buildProxyPluginTransport()
+	if rt == http.DefaultTransport {
+		t.Fatalf("buildProxyPluginTransport() returned http.DefaultTransport, want fail-closed transport")
+	}
+	resp, err := rt.RoundTrip(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err == nil {
+		t.Fatalf("RoundTrip() error = nil, response = %#v; want fail-closed error", resp)
+	}
+	if resp != nil {
+		t.Fatalf("RoundTrip() response = %#v, want nil", resp)
+	}
+}
+
+func TestBuildProxyPluginTransport_NonTransportDefaultFailsClosed(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	restoreDefaultTransport := replaceDefaultTransport(okRoundTripper{})
+	defer restoreDefaultTransport()
+
+	rt := buildProxyPluginTransport()
+	if rt == http.DefaultTransport {
+		t.Fatalf("buildProxyPluginTransport() returned http.DefaultTransport, want fail-closed transport")
+	}
+	resp, err := rt.RoundTrip(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err == nil {
+		t.Fatalf("RoundTrip() error = nil, response = %#v; want fail-closed error", resp)
+	}
+	if resp != nil {
+		t.Fatalf("RoundTrip() response = %#v, want nil", resp)
+	}
+}
+
+// TestPluginTransport_InvalidConfigBlockerIsConcreteTransport guards the
+// fail-closed invariant that Fallback relies on: even when
+// http.DefaultTransport is not an *http.Transport, an invalid proxy config must
+// produce a blocked transport that is itself a concrete *http.Transport. If it
+// were a bare RoundTripper, Fallback would downcast-fail and
+// silently degrade it into a direct-egress transport.
+func TestPluginTransport_InvalidConfigBlockerIsConcreteTransport(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	restoreDefaultTransport := replaceDefaultTransport(okRoundTripper{})
+	defer restoreDefaultTransport()
+
+	writeFile(t, Path(), []byte(`{`), 0600)
+
+	rt, ok := pluginTransport()
+	if !ok {
+		t.Fatal("pluginTransport() ok = false, want true")
+	}
+	if _, isTransport := rt.(*http.Transport); !isTransport {
+		t.Fatalf("pluginTransport() blocked transport = %T, want *http.Transport so Fallback cannot degrade it to direct egress", rt)
+	}
+	// Must remain fail-closed.
+	resp, err := rt.RoundTrip(&http.Request{URL: &url.URL{Scheme: "https", Host: "open.feishu.cn"}})
+	if err == nil {
+		t.Fatalf("RoundTrip() error = nil, response = %#v; want fail-closed error", resp)
+	}
+	if resp != nil {
+		t.Fatalf("RoundTrip() response = %#v, want nil", resp)
+	}
+}
+
+type okRoundTripper struct{}
+
+func (okRoundTripper) RoundTrip(*http.Request) (*http.Response, error) {
+	return &http.Response{StatusCode: http.StatusOK, Body: io.NopCloser(strings.NewReader(""))}, nil
+}
+
+func replaceDefaultTransport(rt http.RoundTripper) func() {
+	original := http.DefaultTransport
+	http.DefaultTransport = rt
+	return func() {
+		http.DefaultTransport = original
+	}
+}

internal/transport/warn.go

@@ -1,18 +1,20 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package util
+package transport
 
 import (
 	"fmt"
 	"io"
-	"net/http"
 	"net/url"
 	"os"
 	"strings"
 	"sync"
+
+	"github.com/larksuite/cli/internal/envvars"
 )
 
+// Proxy environment constants control shared transport proxy behavior.
 const (
 	// EnvNoProxy disables automatic proxy support when set to any non-empty value.
 	EnvNoProxy = "LARK_CLI_NO_PROXY"
@@ -36,8 +38,21 @@ func DetectProxyEnv() (key, value string) {
 	return "", ""
 }
 
+// proxyWarningOnce ensures proxy environment warnings are emitted at most once.
 var proxyWarningOnce sync.Once
 
+// proxyPluginStatus reports the configured proxy plugin address, the extra
+// trusted CA path (if any), and whether proxy plugin mode is enabled. It is
+// indirected through a package variable so tests can simulate plugin-enabled
+// mode without the process-global Load() sync.Once cache.
+var proxyPluginStatus = func() (addr, caPath string, enabled bool) {
+	cfg, err := Load()
+	if err != nil || !cfg.Enabled() {
+		return "", "", false
+	}
+	return cfg.Proxy, cfg.CAPath, true
+}
+
 // redactProxyURL masks userinfo (username:password) in a proxy URL.
 // Handles both scheme-prefixed ("http://user:pass@host") and bare ("user:pass@host") formats.
 func redactProxyURL(raw string) string {
@@ -60,6 +75,22 @@ func redactProxyURL(raw string) string {
 // are redacted. Safe to call multiple times; only the first call prints.
 func WarnIfProxied(w io.Writer) {
 	proxyWarningOnce.Do(func() {
+		// Proxy plugin mode overrides env proxies and LARK_CLI_NO_PROXY (see
+		// Shared), so its warning and disable instructions take precedence.
+		// Emitting the env-proxy warning here would be misleading: it tells the
+		// user to set LARK_CLI_NO_PROXY=1, which does NOT disable the plugin proxy.
+		if addr, caPath, enabled := proxyPluginStatus(); enabled {
+			fmt.Fprintf(w, "[lark-cli] [WARN] proxy plugin enabled: all requests (including credentials) are forced through %s. To disable, set %s=false or remove %s.\n",
+				redactProxyURL(addr), envvars.CliProxyEnable, Path())
+			if strings.TrimSpace(caPath) != "" {
+				// A custom CA means upstream TLS can be intercepted/inspected by
+				// the proxy (MITM). Surface it so the operator is aware traffic
+				// (including Bearer tokens) is decryptable on this host.
+				fmt.Fprintf(w, "[lark-cli] [WARN] proxy plugin trusts a custom CA (%s); TLS to upstreams can be intercepted/inspected by this proxy.\n",
+					caPath)
+			}
+			return
+		}
 		if os.Getenv(EnvNoProxy) != "" {
 			return
 		}
@@ -71,48 +102,3 @@ func WarnIfProxied(w io.Writer) {
 			key, redactProxyURL(val), EnvNoProxy)
 	})
 }
-
-// noProxyTransport is a proxy-disabled clone of http.DefaultTransport,
-// lazily built the first time LARK_CLI_NO_PROXY is observed set.
-var noProxyTransport = sync.OnceValue(func() *http.Transport {
-	def, ok := http.DefaultTransport.(*http.Transport)
-	if !ok {
-		return &http.Transport{}
-	}
-	t := def.Clone()
-	t.Proxy = nil
-	return t
-})
-
-// SharedTransport returns the base http.RoundTripper for CLI HTTP clients.
-//
-// By default it returns http.DefaultTransport — the stdlib-provided
-// process-wide singleton — so every HTTP client in the process shares one
-// TCP connection pool, TLS session cache, and HTTP/2 state. When
-// LARK_CLI_NO_PROXY is set it returns a separate proxy-disabled singleton
-// clone; LARK_CLI_NO_PROXY is checked on every call, but the clone is built
-// at most once.
-//
-// The returned RoundTripper MUST NOT be mutated. Callers that need a
-// customized transport should assert to *http.Transport and Clone() it.
-// Using a shared base is required so persistConn readLoop/writeLoop
-// goroutines are reused; cloning per call leaks them until IdleConnTimeout
-// (~90s) fires.
-func SharedTransport() http.RoundTripper {
-	if os.Getenv(EnvNoProxy) != "" {
-		return noProxyTransport()
-	}
-	return http.DefaultTransport
-}
-
-// FallbackTransport returns a shared *http.Transport singleton. It is a
-// thin wrapper over SharedTransport retained so modules that were already
-// on the leak-free singleton path (internal/auth, internal/cmdutil
-// transport decorators) do not have to migrate. New code should prefer
-// SharedTransport and treat the base as an http.RoundTripper.
-func FallbackTransport() *http.Transport {
-	if t, ok := SharedTransport().(*http.Transport); ok {
-		return t
-	}
-	return noProxyTransport()
-}

internal/transport/warn_test.go

@@ -0,0 +1,258 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package transport
+
+import (
+	"bytes"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/larksuite/cli/internal/envvars"
+)
+
+// TestDetectProxyEnv verifies proxy environment detection priority and empty-state behavior.
+func TestDetectProxyEnv(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+
+	// Clear all proxy env vars first
+	for _, k := range proxyEnvKeys {
+		t.Setenv(k, "")
+	}
+
+	key, val := DetectProxyEnv()
+	if key != "" || val != "" {
+		t.Errorf("expected no proxy, got %s=%s", key, val)
+	}
+
+	t.Setenv("HTTPS_PROXY", "http://proxy:8888")
+	key, val = DetectProxyEnv()
+	if key != "HTTPS_PROXY" || val != "http://proxy:8888" {
+		t.Errorf("expected HTTPS_PROXY=http://proxy:8888, got %s=%s", key, val)
+	}
+}
+
+// TestWarnIfProxied_WithProxy verifies that proxy detection emits a warning.
+func TestWarnIfProxied_WithProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	proxyWarningOnce = sync.Once{}
+
+	t.Setenv("HTTPS_PROXY", "http://corp-proxy:3128")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	out := buf.String()
+	if out == "" {
+		t.Error("expected warning output when proxy is set")
+	}
+	if !bytes.Contains([]byte(out), []byte("HTTPS_PROXY")) {
+		t.Errorf("warning should mention HTTPS_PROXY, got: %s", out)
+	}
+	if !bytes.Contains([]byte(out), []byte(EnvNoProxy)) {
+		t.Errorf("warning should mention %s, got: %s", EnvNoProxy, out)
+	}
+}
+
+// TestWarnIfProxied_WithoutProxy verifies that no warning is emitted without proxy settings.
+func TestWarnIfProxied_WithoutProxy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	proxyWarningOnce = sync.Once{}
+
+	for _, k := range proxyEnvKeys {
+		t.Setenv(k, "")
+	}
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	if buf.Len() != 0 {
+		t.Errorf("expected no output when no proxy is set, got: %s", buf.String())
+	}
+}
+
+// TestWarnIfProxied_SilentWhenDisabled verifies that LARK_CLI_NO_PROXY suppresses warnings.
+func TestWarnIfProxied_SilentWhenDisabled(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	proxyWarningOnce = sync.Once{}
+
+	t.Setenv("HTTPS_PROXY", "http://proxy:8080")
+	t.Setenv(EnvNoProxy, "1")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	if buf.Len() != 0 {
+		t.Errorf("expected no warning when proxy is disabled, got: %s", buf.String())
+	}
+}
+
+// TestWarnIfProxied_OnlyOnce verifies that proxy warnings are emitted only once.
+func TestWarnIfProxied_OnlyOnce(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	proxyWarningOnce = sync.Once{}
+
+	t.Setenv("HTTP_PROXY", "http://proxy:1234")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+	first := buf.String()
+
+	WarnIfProxied(&buf)
+	second := buf.String()
+
+	if first == "" {
+		t.Error("expected warning on first call")
+	}
+	if second != first {
+		t.Error("expected no additional output on second call")
+	}
+}
+
+// TestWarnIfProxied_ProxyPluginEnabled verifies that when proxy plugin mode is
+// enabled, the warning describes the plugin proxy and the correct disable method
+// (LARKSUITE_CLI_PROXY_ENABLE=false) instead of the misleading LARK_CLI_NO_PROXY
+// instruction — even when env proxy and LARK_CLI_NO_PROXY are also set.
+func TestWarnIfProxied_ProxyPluginEnabled(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	proxyWarningOnce = sync.Once{}
+
+	old := proxyPluginStatus
+	proxyPluginStatus = func() (string, string, bool) { return "http://127.0.0.1:3128", "", true }
+	t.Cleanup(func() { proxyPluginStatus = old })
+
+	// Plugin mode overrides these; the warning must still be the plugin one.
+	t.Setenv("HTTPS_PROXY", "http://corp-proxy:8080")
+	t.Setenv(EnvNoProxy, "1")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+	out := buf.String()
+
+	if !strings.Contains(out, "127.0.0.1:3128") {
+		t.Errorf("warning should mention the plugin proxy address, got: %s", out)
+	}
+	if !strings.Contains(out, envvars.CliProxyEnable) {
+		t.Errorf("warning should mention %s as the disable method, got: %s", envvars.CliProxyEnable, out)
+	}
+	if strings.Contains(out, "Set "+EnvNoProxy+"=1") {
+		t.Errorf("warning must NOT give the misleading %s disable instruction when plugin is enabled, got: %s", EnvNoProxy, out)
+	}
+	// No custom CA configured -> no interception warning.
+	if strings.Contains(out, "custom CA") {
+		t.Errorf("warning should not mention a custom CA when none is configured, got: %s", out)
+	}
+}
+
+// TestWarnIfProxied_ProxyPluginCustomCAWarns verifies that when a custom CA is
+// trusted, the warning surfaces the TLS-interception capability.
+func TestWarnIfProxied_ProxyPluginCustomCAWarns(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	proxyWarningOnce = sync.Once{}
+
+	old := proxyPluginStatus
+	proxyPluginStatus = func() (string, string, bool) {
+		return "http://127.0.0.1:3128", "/etc/lark/extra_ca.pem", true
+	}
+	t.Cleanup(func() { proxyPluginStatus = old })
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+	out := buf.String()
+
+	if !strings.Contains(out, "custom CA") {
+		t.Errorf("warning should mention the custom CA, got: %s", out)
+	}
+	if !strings.Contains(out, "/etc/lark/extra_ca.pem") {
+		t.Errorf("warning should include the CA path, got: %s", out)
+	}
+	if !strings.Contains(out, "intercept") {
+		t.Errorf("warning should mention TLS interception, got: %s", out)
+	}
+}
+
+// TestWarnIfProxied_ProxyPluginEnabledRedactsCredentials verifies the plugin
+// warning never leaks credentials embedded in the configured proxy address.
+func TestWarnIfProxied_ProxyPluginEnabledRedactsCredentials(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	proxyWarningOnce = sync.Once{}
+
+	old := proxyPluginStatus
+	proxyPluginStatus = func() (string, string, bool) { return "http://user:s3cret@127.0.0.1:3128", "", true }
+	t.Cleanup(func() { proxyPluginStatus = old })
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+	out := buf.String()
+
+	if strings.Contains(out, "s3cret") {
+		t.Errorf("plugin warning leaked password, got: %s", out)
+	}
+	if strings.Contains(out, "user:") {
+		t.Errorf("plugin warning leaked username, got: %s", out)
+	}
+	if !strings.Contains(out, "***@127.0.0.1:3128") {
+		t.Errorf("plugin warning should contain redacted proxy URL, got: %s", out)
+	}
+}
+
+// TestRedactProxyURL verifies redaction of proxy credentials across supported formats.
+func TestRedactProxyURL(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"http://proxy:8080", "http://proxy:8080"},
+		{"http://user:pass@proxy:8080", "http://***@proxy:8080/"},
+		{"http://user:p%40ss@proxy:8080/path", "http://***@proxy:8080/path"},
+		{"http://user@proxy:8080", "http://***@proxy:8080/"},
+		{"socks5://admin:secret@10.0.0.1:1080", "socks5://***@10.0.0.1:1080/"},
+		{"user:pass@proxy:8080", "***@proxy:8080"},
+		{"admin:s3cret@10.0.0.1:3128", "***@10.0.0.1:3128"},
+		{"not-a-url", "not-a-url"},
+		{"", ""},
+	}
+	for _, tt := range tests {
+		got := redactProxyURL(tt.input)
+		if got != tt.want {
+			t.Errorf("redactProxyURL(%q) = %q, want %q", tt.input, got, tt.want)
+		}
+	}
+}
+
+// TestWarnIfProxied_RedactsCredentials verifies that warning output never leaks credentials.
+func TestWarnIfProxied_RedactsCredentials(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
+	proxyWarningOnce = sync.Once{}
+
+	t.Setenv("HTTPS_PROXY", "http://admin:s3cret@proxy:8080")
+
+	var buf bytes.Buffer
+	WarnIfProxied(&buf)
+
+	out := buf.String()
+	if bytes.Contains([]byte(out), []byte("s3cret")) {
+		t.Errorf("warning should not contain proxy password, got: %s", out)
+	}
+	if bytes.Contains([]byte(out), []byte("admin")) {
+		t.Errorf("warning should not contain proxy username, got: %s", out)
+	}
+	if !bytes.Contains([]byte(out), []byte("***@proxy:8080")) {
+		t.Errorf("warning should contain redacted proxy URL, got: %s", out)
+	}
+}

internal/update/update.go

@@ -17,7 +17,7 @@ import (
 	"time"
 
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -64,7 +64,7 @@ func httpClient() *http.Client {
 	}
 	return &http.Client{
 		Timeout:   fetchTimeout,
-		Transport: util.SharedTransport(),
+		Transport: transport.Shared(),
 	}
 }
 

internal/util/proxy_test.go

@@ -1,204 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package util
-
-import (
-	"bytes"
-	"net/http"
-	"sync"
-	"testing"
-)
-
-func TestDetectProxyEnv(t *testing.T) {
-	// Clear all proxy env vars first
-	for _, k := range proxyEnvKeys {
-		t.Setenv(k, "")
-	}
-
-	key, val := DetectProxyEnv()
-	if key != "" || val != "" {
-		t.Errorf("expected no proxy, got %s=%s", key, val)
-	}
-
-	t.Setenv("HTTPS_PROXY", "http://proxy:8888")
-	key, val = DetectProxyEnv()
-	if key != "HTTPS_PROXY" || val != "http://proxy:8888" {
-		t.Errorf("expected HTTPS_PROXY=http://proxy:8888, got %s=%s", key, val)
-	}
-}
-
-func TestSharedTransport_DefaultReturnsStdlibSingleton(t *testing.T) {
-	t.Setenv(EnvNoProxy, "")
-	tr := SharedTransport()
-	if tr != http.DefaultTransport {
-		t.Error("SharedTransport should return http.DefaultTransport when LARK_CLI_NO_PROXY is unset")
-	}
-}
-
-func TestSharedTransport_NoProxyReturnsClone(t *testing.T) {
-	t.Setenv(EnvNoProxy, "1")
-	tr := SharedTransport()
-	if tr == http.DefaultTransport {
-		t.Fatal("SharedTransport should return a clone, not DefaultTransport, when LARK_CLI_NO_PROXY is set")
-	}
-	ht, ok := tr.(*http.Transport)
-	if !ok {
-		t.Fatalf("expected *http.Transport, got %T", tr)
-	}
-	if ht.Proxy != nil {
-		t.Error("no-proxy transport should have Proxy == nil")
-	}
-}
-
-func TestSharedTransport_NoProxyIsCachedSingleton(t *testing.T) {
-	t.Setenv(EnvNoProxy, "1")
-	a := SharedTransport()
-	b := SharedTransport()
-	if a != b {
-		t.Error("repeated SharedTransport calls with LARK_CLI_NO_PROXY set must return the same instance")
-	}
-}
-
-func TestSharedTransport_EnvUnsetAfterSetFallsBackToDefault(t *testing.T) {
-	// Simulate a process that first runs with LARK_CLI_NO_PROXY=1 (populating
-	// the no-proxy singleton), then unsets it. Subsequent calls must return
-	// http.DefaultTransport, NOT the cached no-proxy clone.
-	t.Setenv(EnvNoProxy, "1")
-	noProxy := SharedTransport()
-	if noProxy == http.DefaultTransport {
-		t.Fatal("precondition: first call with env set should not return DefaultTransport")
-	}
-
-	t.Setenv(EnvNoProxy, "")
-	after := SharedTransport()
-	if after != http.DefaultTransport {
-		t.Errorf("after unsetting LARK_CLI_NO_PROXY, SharedTransport must return http.DefaultTransport, got %T (%p)", after, after)
-	}
-}
-
-func TestSharedTransport_NoProxyOverridesSystemProxy(t *testing.T) {
-	t.Setenv("HTTPS_PROXY", "http://should-be-ignored:8888")
-	t.Setenv(EnvNoProxy, "1")
-
-	ht, ok := SharedTransport().(*http.Transport)
-	if !ok {
-		t.Fatalf("expected *http.Transport, got %T", SharedTransport())
-	}
-	if ht.Proxy != nil {
-		t.Error("LARK_CLI_NO_PROXY should override system proxy settings")
-	}
-}
-
-func TestWarnIfProxied_WithProxy(t *testing.T) {
-	// Reset the once guard for this test
-	proxyWarningOnce = sync.Once{}
-
-	t.Setenv("HTTPS_PROXY", "http://corp-proxy:3128")
-
-	var buf bytes.Buffer
-	WarnIfProxied(&buf)
-
-	out := buf.String()
-	if out == "" {
-		t.Error("expected warning output when proxy is set")
-	}
-	if !bytes.Contains([]byte(out), []byte("HTTPS_PROXY")) {
-		t.Errorf("warning should mention HTTPS_PROXY, got: %s", out)
-	}
-	if !bytes.Contains([]byte(out), []byte(EnvNoProxy)) {
-		t.Errorf("warning should mention %s, got: %s", EnvNoProxy, out)
-	}
-}
-
-func TestWarnIfProxied_WithoutProxy(t *testing.T) {
-	proxyWarningOnce = sync.Once{}
-
-	for _, k := range proxyEnvKeys {
-		t.Setenv(k, "")
-	}
-
-	var buf bytes.Buffer
-	WarnIfProxied(&buf)
-
-	if buf.Len() != 0 {
-		t.Errorf("expected no output when no proxy is set, got: %s", buf.String())
-	}
-}
-
-func TestWarnIfProxied_SilentWhenDisabled(t *testing.T) {
-	proxyWarningOnce = sync.Once{}
-
-	t.Setenv("HTTPS_PROXY", "http://proxy:8080")
-	t.Setenv(EnvNoProxy, "1")
-
-	var buf bytes.Buffer
-	WarnIfProxied(&buf)
-
-	if buf.Len() != 0 {
-		t.Errorf("expected no warning when proxy is disabled, got: %s", buf.String())
-	}
-}
-
-func TestWarnIfProxied_OnlyOnce(t *testing.T) {
-	proxyWarningOnce = sync.Once{}
-
-	t.Setenv("HTTP_PROXY", "http://proxy:1234")
-
-	var buf bytes.Buffer
-	WarnIfProxied(&buf)
-	first := buf.String()
-
-	WarnIfProxied(&buf)
-	second := buf.String()
-
-	if first == "" {
-		t.Error("expected warning on first call")
-	}
-	if second != first {
-		t.Error("expected no additional output on second call")
-	}
-}
-
-func TestRedactProxyURL(t *testing.T) {
-	tests := []struct {
-		input string
-		want  string
-	}{
-		{"http://proxy:8080", "http://proxy:8080"},
-		{"http://user:pass@proxy:8080", "http://***@proxy:8080/"},
-		{"http://user:p%40ss@proxy:8080/path", "http://***@proxy:8080/path"},
-		{"http://user@proxy:8080", "http://***@proxy:8080/"},
-		{"socks5://admin:secret@10.0.0.1:1080", "socks5://***@10.0.0.1:1080/"},
-		{"user:pass@proxy:8080", "***@proxy:8080"},
-		{"admin:s3cret@10.0.0.1:3128", "***@10.0.0.1:3128"},
-		{"not-a-url", "not-a-url"},
-		{"", ""},
-	}
-	for _, tt := range tests {
-		got := redactProxyURL(tt.input)
-		if got != tt.want {
-			t.Errorf("redactProxyURL(%q) = %q, want %q", tt.input, got, tt.want)
-		}
-	}
-}
-
-func TestWarnIfProxied_RedactsCredentials(t *testing.T) {
-	proxyWarningOnce = sync.Once{}
-
-	t.Setenv("HTTPS_PROXY", "http://admin:s3cret@proxy:8080")
-
-	var buf bytes.Buffer
-	WarnIfProxied(&buf)
-
-	out := buf.String()
-	if bytes.Contains([]byte(out), []byte("s3cret")) {
-		t.Errorf("warning should not contain proxy password, got: %s", out)
-	}
-	if bytes.Contains([]byte(out), []byte("admin")) {
-		t.Errorf("warning should not contain proxy username, got: %s", out)
-	}
-	if !bytes.Contains([]byte(out), []byte("***@proxy:8080")) {
-		t.Errorf("warning should contain redacted proxy URL, got: %s", out)
-	}
-}

package.json

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

shortcuts/base/base_advperm_disable.go

@@ -25,6 +25,10 @@ var BaseAdvpermDisable = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
 	},
+	Tips: []string{
+		baseHighRiskYesTip,
+		"Disabling advanced permissions invalidates existing custom roles; confirm the target Base before passing --yes.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")

shortcuts/base/base_advperm_enable.go

@@ -25,6 +25,9 @@ var BaseAdvpermEnable = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
 	},
+	Tips: []string{
+		"Caller must be a Base admin; enable advanced permissions before creating or updating roles.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")

shortcuts/base/base_copy.go

@@ -24,6 +24,11 @@ var BaseBaseCopy = common.Shortcut{
 		{Name: "without-content", Type: "bool", Desc: "copy structure only"},
 		{Name: "time-zone", Desc: "time zone, e.g. Asia/Shanghai"},
 	},
+	Tips: []string{
+		`Example: lark-cli base +base-copy --base-token <base_token> --name "Copy of Project Tracker"`,
+		"Use --without-content when the user wants only structure.",
+		"If copied as bot, output may include permission_grant; report it so the user knows whether they can open the new Base.",
+	},
 	DryRun: dryRunBaseCopy,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeBaseCopy(runtime)

shortcuts/base/base_create.go

@@ -22,6 +22,10 @@ var BaseBaseCreate = common.Shortcut{
 		{Name: "folder-token", Desc: "folder token for destination"},
 		{Name: "time-zone", Desc: "time zone, e.g. Asia/Shanghai"},
 	},
+	Tips: []string{
+		`Example: lark-cli base +base-create --name "Project Tracker" --time-zone Asia/Shanghai`,
+		"If created as bot, output may include permission_grant; report it so the user knows whether they can open the new Base.",
+	},
 	DryRun: dryRunBaseCreate,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeBaseCreate(runtime)

shortcuts/base/base_data_query.go

@@ -20,7 +20,12 @@ var BaseDataQuery = common.Shortcut{
 	AuthTypes:   authTypes(),
 	Flags: []common.Flag{
 		baseTokenFlag(true),
-		{Name: "dsl", Desc: "query JSON DSL (LiteQuery Protocol)", Required: true},
+		{Name: "dsl", Desc: "query JSON DSL; read lark-base-data-query-guide.md first, then lark-base-data-query.md for the full DSL SSOT", Required: true},
+	},
+	Tips: []string{
+		"Use +data-query for server-side aggregation, grouping, filtering, sorting, and Top N queries.",
+		"Read lark-base-data-query-guide.md for common fewshots; use lark-base-data-query.md only when the full DSL reference is needed.",
+		"`dimensions` and `measures` cannot both be empty.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		var dsl map[string]interface{}

shortcuts/base/base_dryrun_ops_test.go

@@ -71,6 +71,29 @@ func TestDryRunRecordOps(t *testing.T) {
 	)
 	assertDryRunContains(t, dryRunRecordList(ctx, listRT), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/records", "offset=0", "limit=200", "view_id=viw_1", "field_id=Name", "field_id=Age")
 
+	filteredListRT := newBaseTestRuntimeWithArrays(
+		map[string]string{
+			"base-token":  "app_x",
+			"table-id":    "tbl_1",
+			"filter-json": `{"logic":"and","conditions":[["Status","==","Todo"],["Score",">=",80]]}`,
+			"sort-json":   `[{"field":"Due","desc":true}]`,
+		},
+		nil,
+		nil,
+		map[string]int{"limit": 20},
+	)
+	assertDryRunContains(
+		t,
+		dryRunRecordList(ctx, filteredListRT),
+		"GET /open-apis/base/v3/bases/app_x/tables/tbl_1/records",
+		"limit=20",
+		"filter=%7B",
+		"Status",
+		"Todo",
+		"sort=%5B",
+		"Due",
+	)
+
 	commaFieldRT := newBaseTestRuntimeWithArrays(
 		map[string]string{"base-token": "app_x", "table-id": "tbl_1"},
 		map[string][]string{"field-id": {"A,B", "C"}},
@@ -99,6 +122,33 @@ func TestDryRunRecordOps(t *testing.T) {
 		`"limit":500`,
 	)
 
+	searchFlagRT := newBaseTestRuntimeWithArrays(
+		map[string]string{
+			"base-token":  "app_x",
+			"table-id":    "tbl_1",
+			"keyword":     "Alice",
+			"view-id":     "viw_1",
+			"filter-json": `{"logic":"and","conditions":[["Status","!=","Done"]]}`,
+			"sort-json":   `[{"field":"Updated At","desc":true}]`,
+		},
+		map[string][]string{
+			"search-field": {"Name"},
+			"field-id":     {"Name", "Status"},
+		},
+		nil,
+		map[string]int{"limit": 20},
+	)
+	assertDryRunContains(
+		t,
+		dryRunRecordSearch(ctx, searchFlagRT),
+		"POST /open-apis/base/v3/bases/app_x/tables/tbl_1/records/search",
+		`"keyword":"Alice"`,
+		`"search_fields":["Name"]`,
+		`"select_fields":["Name","Status"]`,
+		`"filter":{"conditions":[["Status","!=","Done"]],"logic":"and"}`,
+		`"sort":[{"desc":true,"field":"Updated At"}]`,
+	)
+
 	upsertCreateRT := newBaseTestRuntime(
 		map[string]string{"base-token": "app_x", "table-id": "tbl_1", "json": `{"Name":"A"}`},
 		nil, nil,

shortcuts/base/base_execute_test.go

@@ -515,7 +515,7 @@ func TestBaseObjectJSONShortcutsRejectArrayInDryRun(t *testing.T) {
 			if !strings.Contains(err.Error(), "--json must be a JSON object") {
 				t.Fatalf("err=%v", err)
 			}
-			if !strings.Contains(err.Error(), "lark-base skill") {
+			if !strings.Contains(err.Error(), "match the documented shape") {
 				t.Fatalf("err=%v", err)
 			}
 			if strings.Contains(err.Error(), "array") {
@@ -974,7 +974,7 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 				"+record-search",
 				"--base-token", "app_x",
 				"--table-id", "tbl_x",
-				"--json", `{"view_id":"vew_x","keyword":"Created","search_fields":["Title","fld_owner"],"select_fields":["Title","fld_owner"],"offset":0,"limit":2}`,
+				"--json", `{"view_id":"vew_x","keyword":"Created","search_fields":["Title","fld_owner"],"select_fields":["Title","fld_owner"],"filter":{"logic":"and","conditions":[["Status","!=","Done"]]},"sort":{"sort_config":[{"field":"Updated At","desc":true},{"field":"Title","desc":false}]},"offset":0,"limit":2}`,
 				"--format", "json",
 			},
 			factory,
@@ -990,12 +990,121 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			!strings.Contains(body, `"keyword":"Created"`) ||
 			!strings.Contains(body, `"search_fields":["Title","fld_owner"]`) ||
 			!strings.Contains(body, `"select_fields":["Title","fld_owner"]`) ||
+			!strings.Contains(body, `"filter":{"conditions":[["Status","!=","Done"]],"logic":"and"}`) ||
+			!strings.Contains(body, `"sort":[{"desc":true,"field":"Updated At"},{"desc":false,"field":"Title"}]`) ||
 			!strings.Contains(body, `"offset":0`) ||
 			!strings.Contains(body, `"limit":2`) {
 			t.Fatalf("captured body=%s", body)
 		}
 	})
 
+	t.Run("search with flag filter sort and projection", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		searchStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/search",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"fields":         []interface{}{"Title", "Status"},
+					"field_id_list":  []interface{}{"fld_title", "fld_status"},
+					"record_id_list": []interface{}{"rec_1"},
+					"data":           []interface{}{[]interface{}{"Created by AI", "Todo"}},
+					"has_more":       false,
+				},
+			},
+		}
+		reg.Register(searchStub)
+		if err := runShortcut(
+			t,
+			BaseRecordSearch,
+			[]string{
+				"+record-search",
+				"--base-token", "app_x",
+				"--table-id", "tbl_x",
+				"--keyword", "Created",
+				"--search-field", "Title",
+				"--field-id", "Title",
+				"--field-id", "Status",
+				"--filter-json", `{"logic":"and","conditions":[["Status","==","Todo"],["Score",">=",80]]}`,
+				"--sort-json", `[{"field":"Updated At","desc":true},{"field":"Title","desc":false}]`,
+				"--limit", "20",
+				"--format", "json",
+			},
+			factory,
+			stdout,
+		); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		var body map[string]interface{}
+		if err := json.Unmarshal(searchStub.CapturedBody, &body); err != nil {
+			t.Fatalf("captured body json err=%v body=%s", err, string(searchStub.CapturedBody))
+		}
+		if body["keyword"] != "Created" || body["limit"].(float64) != 20 {
+			t.Fatalf("captured body=%#v", body)
+		}
+		filter := body["filter"].(map[string]interface{})
+		if filter["logic"] != "and" {
+			t.Fatalf("filter=%#v", filter)
+		}
+		conditions := filter["conditions"].([]interface{})
+		if len(conditions) != 2 {
+			t.Fatalf("conditions=%#v", conditions)
+		}
+		sortConfig := body["sort"].([]interface{})
+		if len(sortConfig) != 2 {
+			t.Fatalf("sort=%#v", sortConfig)
+		}
+		firstSort := sortConfig[0].(map[string]interface{})
+		if firstSort["field"] != "Updated At" || firstSort["desc"] != true {
+			t.Fatalf("sort=%#v", sortConfig)
+		}
+	})
+
+	t.Run("search with filter json file", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		tmp := t.TempDir()
+		withBaseWorkingDir(t, tmp)
+		if err := os.WriteFile(filepath.Join(tmp, "filter.json"), []byte(`{"logic":"or","conditions":[["Status","==","Todo"]]}`), 0600); err != nil {
+			t.Fatalf("write filter err=%v", err)
+		}
+		searchStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/search",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"fields":         []interface{}{"Title"},
+					"record_id_list": []interface{}{"rec_1"},
+					"data":           []interface{}{[]interface{}{"A"}},
+					"has_more":       false,
+				},
+			},
+		}
+		reg.Register(searchStub)
+		if err := runShortcut(
+			t,
+			BaseRecordSearch,
+			[]string{
+				"+record-search",
+				"--base-token", "app_x",
+				"--table-id", "tbl_x",
+				"--keyword", "A",
+				"--search-field", "Title",
+				"--filter-json", "@filter.json",
+				"--format", "json",
+			},
+			factory,
+			stdout,
+		); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		body := string(searchStub.CapturedBody)
+		if !strings.Contains(body, `"filter":{"conditions":[["Status","==","Todo"]],"logic":"or"}`) {
+			t.Fatalf("captured body=%s", body)
+		}
+	})
+
 	t.Run("search markdown format", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{

shortcuts/base/base_form_create.go

@@ -25,6 +25,9 @@ var BaseFormCreate = common.Shortcut{
 		{Name: "name", Desc: "form name", Required: true},
 		{Name: "description", Desc: `form description (plain text or markdown link like [text](https://example.com))`},
 	},
+	Tips: []string{
+		"Record the returned form_id; form question create/list/update/delete commands need it.",
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms").

shortcuts/base/base_form_delete.go

@@ -22,6 +22,10 @@ var BaseFormDelete = common.Shortcut{
 		{Name: "table-id", Desc: "table ID", Required: true},
 		{Name: "form-id", Desc: "form ID", Required: true},
 	},
+	Tips: []string{
+		"Use +form-list or +form-get first when the form target is ambiguous.",
+		baseHighRiskYesTip,
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			DELETE("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id").

shortcuts/base/base_form_list.go

@@ -23,7 +23,7 @@ var BaseFormsList = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "Base token (base_token)", Required: true},
 		{Name: "table-id", Desc: "table ID", Required: true},
-		{Name: "page-size", Type: "int", Default: "100", Desc: "page size per request (max 100)"},
+		{Name: "page-size", Type: "int", Default: "100", Desc: "page size per request, max 100"},
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().

shortcuts/base/base_form_questions_delete.go

@@ -25,6 +25,9 @@ var BaseFormQuestionsDelete = common.Shortcut{
 		{Name: "form-id", Desc: "form ID", Required: true},
 		{Name: "question-ids", Desc: `JSON array of question IDs to delete, max 10 items, e.g. '["q_001","q_002"]'`, Required: true},
 	},
+	Tips: []string{
+		baseHighRiskYesTip,
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			DELETE("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id/questions").

shortcuts/base/base_form_questions_list.go

@@ -25,6 +25,9 @@ var BaseFormQuestionsList = common.Shortcut{
 		{Name: "table-id", Desc: "table ID", Required: true},
 		{Name: "form-id", Desc: "form ID", Required: true},
 	},
+	Tips: []string{
+		"Use returned question id values for +form-questions-update and +form-questions-delete.",
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			GET("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id/questions").

shortcuts/base/base_get.go

@@ -17,7 +17,10 @@ var BaseBaseGet = common.Shortcut{
 	Scopes:      []string{"base:app:read"},
 	AuthTypes:   authTypes(),
 	Flags:       []common.Flag{baseTokenFlag(true)},
-	DryRun:      dryRunBaseGet,
+	Tips: []string{
+		"Use a real Base token; workspace tokens and wiki tokens are not accepted by this command.",
+	},
+	DryRun: dryRunBaseGet,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeBaseGet(runtime)
 	},

shortcuts/base/base_role_create.go

@@ -25,7 +25,12 @@ var BaseRoleCreate = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
-		{Name: "json", Desc: `body JSON (AdvPermBaseRoleConfig), e.g. {"role_name":"Reviewer","role_type":"custom_role","table_rule_map":{...}}`, Required: true},
+		{Name: "json", Desc: "role config JSON; read lark-base-role-guide.md and role-config.md before constructing permissions", Required: true},
+	},
+	Tips: []string{
+		"Requires advanced permissions to be enabled and the caller to be a Base admin.",
+		"Use lark-base-role-guide.md as the entry guide and role-config.md as the role permission JSON SSOT.",
+		"Create supports custom_role only.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

shortcuts/base/base_role_delete.go

@@ -26,6 +26,12 @@ var BaseRoleDelete = common.Shortcut{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "role-id", Desc: "role ID (e.g. rolxxxxxx4)", Required: true},
 	},
+	Tips: []string{
+		baseHighRiskYesTip,
+		"Requires advanced permissions to be enabled and the caller to be a Base admin.",
+		"Only custom roles can be deleted; system roles cannot be deleted.",
+		"Use +role-get first if the role target is ambiguous, then pass --yes to confirm deletion.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")

shortcuts/base/base_role_get.go

@@ -27,6 +27,10 @@ var BaseRoleGet = common.Shortcut{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "role-id", Desc: "role ID (e.g. rolxxxxxx4)", Required: true},
 	},
+	Tips: []string{
+		"Requires advanced permissions to be enabled and the caller to be a Base admin.",
+		"Use before +role-update to inspect the current full permission config.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")

shortcuts/base/base_role_list.go

@@ -26,6 +26,10 @@ var BaseRoleList = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
 	},
+	Tips: []string{
+		"Requires advanced permissions to be enabled and the caller to be a Base admin.",
+		"Returns role summaries; use +role-get for the full permission config.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")

shortcuts/base/base_role_update.go

@@ -26,7 +26,13 @@ var BaseRoleUpdate = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "role-id", Desc: "role ID (e.g. rolxxxxxx4)", Required: true},
-		{Name: "json", Desc: `body JSON (delta AdvPermBaseRoleConfig), e.g. {"role_name":"New Name","role_type":"custom_role","table_rule_map":{...}}`, Required: true},
+		{Name: "json", Desc: "delta role config JSON; read lark-base-role-guide.md and role-config.md before changing permissions", Required: true},
+	},
+	Tips: []string{
+		baseHighRiskYesTip,
+		"Requires advanced permissions to be enabled and the caller to be a Base admin.",
+		"Update is a delta merge: only changed fields are updated, others remain unchanged.",
+		"Use lark-base-role-guide.md as the entry guide and role-config.md as the role permission JSON SSOT.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

shortcuts/base/base_shortcut_helpers.go

@@ -63,7 +63,7 @@ func loadJSONInput(pc *parseCtx, raw string, flagName string) (string, error) {
 }
 
 func jsonInputTip(flagName string) string {
-	return fmt.Sprintf("tip: pass a valid JSON directly, or use --%s @file.json; use the lark-base skill or this command's reference to find the expected body", flagName)
+	return fmt.Sprintf("tip: pass a valid JSON directly, or use --%s @file.json; for complex JSON/DSL, read the lark-base reference and match the documented shape", flagName)
 }
 
 func formatJSONError(flagName string, target string, err error) error {

shortcuts/base/base_shortcuts_test.go

@@ -198,6 +198,25 @@ func TestBaseDeleteShortcutsRisk(t *testing.T) {
 	}
 }
 
+func TestBaseHighRiskShortcutsTipsGuideAgents(t *testing.T) {
+	for _, shortcut := range Shortcuts() {
+		if shortcut.Risk != "high-risk-write" {
+			continue
+		}
+		parent := &cobra.Command{Use: "base"}
+		shortcut.Mount(parent, &cmdutil.Factory{})
+		cmd := parent.Commands()[0]
+		flag := cmd.Flags().Lookup("yes")
+		if flag == nil {
+			t.Fatalf("%s missing --yes flag", shortcut.Command)
+		}
+		tips := strings.Join(cmdutil.GetTips(cmd), "\n")
+		if !strings.Contains(tips, "pass --yes without asking again") {
+			t.Fatalf("%s tips missing agent guidance:\n%s", shortcut.Command, tips)
+		}
+	}
+}
+
 func TestBaseFieldCreateHelpHidesReadGuideFlag(t *testing.T) {
 	parent := &cobra.Command{Use: "base"}
 	BaseFieldCreate.Mount(parent, &cmdutil.Factory{})
@@ -235,36 +254,39 @@ func TestBaseRecordReadHelpGuidesAgents(t *testing.T) {
 			wantHelp: []string{
 				"field ID or name to include; repeat to project only needed fields",
 				"view ID or name; omit for reading all table records, or set to read a user-specified or temporary filtered/sorted view",
+				`filter JSON object or @file`,
+				`sort JSON array or @file`,
 				"pagination size, range 1-200",
 				"output format: markdown (default) | json",
 			},
 			wantTips: []string{
 				"lark-cli base +record-list --base-token <base_token> --table-id <table_id> --limit 50",
 				"lark-cli base +record-list --base-token <base_token> --table-id <table_id> --field-id Name --field-id Status --limit 50",
+				"Text equality filter",
+				"Option intersection filter",
+				"Query priority",
 				"Default output is markdown",
 				"Use --field-id repeatedly to keep output small",
-				"Use --view-id when the user asks for a specific view or after creating a temporary filtered/sorted view",
-				"lark-base record read SOP",
 			},
 		},
 		{
 			name:     "record search",
 			shortcut: BaseRecordSearch,
 			wantHelp: []string{
-				"requires keyword/search_fields",
-				"optional select_fields/view_id/offset/limit",
+				`record search JSON object for the full request body, e.g. {"keyword":"Alice","search_fields":["Name"],"select_fields":["Name","Status"],"filter":{"logic":"and","conditions":[]},"sort":[{"field":"Updated","desc":true}],"limit":50}; escape hatch for advanced cases`,
+				"keyword for record search",
+				"field ID or name to search",
+				`filter JSON object or @file`,
+				`sort JSON array or @file`,
 				"output format: markdown (default) | json",
 			},
 			wantTips: []string{
-				`lark-cli base +record-search --base-token <base_token> --table-id <table_id> --json`,
-				`"select_fields":["Name","Status"]`,
-				`JSON shape: {"keyword":"<text>","search_fields":["<field_id_or_name>"]`,
-				"search_fields length 1-20",
-				"limit range 1-200 defaults to 10",
-				"view_id scopes search to records in that view",
+				"Example: lark-cli base +record-search",
+				"Example with filter/sort JSON",
+				"Text equality filter",
+				"Query priority",
+				"Use --json only when you need to pass the full search body directly",
 				"Default output is markdown",
-				"only for keyword search",
-				"lark-base record read SOP",
 			},
 		},
 		{
@@ -311,6 +333,401 @@ func TestBaseRecordReadHelpGuidesAgents(t *testing.T) {
 	}
 }
 
+func TestBaseDashboardHelpGuidesAgents(t *testing.T) {
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		wantTips []string
+	}{
+		{
+			name:     "dashboard list",
+			shortcut: BaseDashboardList,
+			wantTips: []string{
+				"Use returned dashboard_id values",
+			},
+		},
+		{
+			name:     "dashboard get",
+			shortcut: BaseDashboardGet,
+			wantTips: []string{
+				"block-level details",
+			},
+		},
+		{
+			name:     "dashboard create",
+			shortcut: BaseDashboardCreate,
+			wantTips: []string{
+				"Record the returned dashboard_id",
+			},
+		},
+		{
+			name:     "dashboard update",
+			shortcut: BaseDashboardUpdate,
+			wantTips: []string{},
+		},
+		{
+			name:     "dashboard delete",
+			shortcut: BaseDashboardDelete,
+			wantTips: []string{
+				"lark-cli base +dashboard-delete --base-token <base_token> --dashboard-id <dashboard_id> --yes",
+				"also deletes its blocks",
+				"pass --yes",
+			},
+		},
+		{
+			name:     "dashboard arrange",
+			shortcut: BaseDashboardArrange,
+			wantTips: []string{
+				"not deterministic or position-specific",
+			},
+		},
+		{
+			name:     "dashboard block list",
+			shortcut: BaseDashboardBlockList,
+			wantTips: []string{
+				"lark-cli base +dashboard-block-list --base-token <base_token> --dashboard-id <dashboard_id>",
+				"Use returned block_id and type values",
+			},
+		},
+		{
+			name:     "dashboard block get",
+			shortcut: BaseDashboardBlockGet,
+			wantTips: []string{
+				"lark-cli base +dashboard-block-get --base-token <base_token> --dashboard-id <dashboard_id> --block-id <block_id>",
+				"metadata such as name, type, layout, and data_config",
+				"computed chart result",
+			},
+		},
+		{
+			name:     "dashboard block get data",
+			shortcut: BaseDashboardBlockGetData,
+			wantTips: []string{
+				"lark-cli base +dashboard-block-get-data --base-token <base_token> --block-id <block_id>",
+				"does not need --dashboard-id",
+				"computed chart protocol JSON",
+			},
+		},
+		{
+			name:     "dashboard block create",
+			shortcut: BaseDashboardBlockCreate,
+			wantTips: []string{
+				`lark-cli base +dashboard-block-create --base-token <base_token> --dashboard-id <dashboard_id> --name "Order Count" --type statistics --data-config '{"table_name":"Orders","count_all":true}'`,
+				`--type text --data-config '{"text":"# Sales Dashboard"}'`,
+				"+table-list and +field-list",
+				"not table_id or field_id",
+				"dashboard-block-data-config.md as the SSOT",
+				"do not invent data_config from natural language",
+				"sequentially",
+			},
+		},
+		{
+			name:     "dashboard block update",
+			shortcut: BaseDashboardBlockUpdate,
+			wantTips: []string{
+				`lark-cli base +dashboard-block-update --base-token <base_token> --dashboard-id <dashboard_id> --block-id <block_id> --name "Total Sales"`,
+				`--data-config '{"series":[{"field_name":"Amount","rollup":"SUM"}]}'`,
+				"dashboard-block-data-config.md as the SSOT",
+				"do not invent data_config from natural language",
+				"Block type cannot be changed",
+				"top-level keys",
+			},
+		},
+		{
+			name:     "dashboard block delete",
+			shortcut: BaseDashboardBlockDelete,
+			wantTips: []string{
+				"lark-cli base +dashboard-block-delete --base-token <base_token> --dashboard-id <dashboard_id> --block-id <block_id> --yes",
+				"pass --yes",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			parent := &cobra.Command{Use: "base"}
+			tt.shortcut.Mount(parent, &cmdutil.Factory{})
+			cmd := parent.Commands()[0]
+
+			tips := strings.Join(cmdutil.GetTips(cmd), "\n")
+			for _, want := range tt.wantTips {
+				if !strings.Contains(tips, want) {
+					t.Fatalf("tips missing %q:\n%s", want, tips)
+				}
+			}
+		})
+	}
+}
+
+func TestBaseWorkflowHelpGuidesAgents(t *testing.T) {
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		wantTips []string
+	}{
+		{
+			name:     "workflow list",
+			shortcut: BaseWorkflowList,
+			wantTips: []string{
+				"workflow_id values with wkf prefix",
+				"auto-paginates",
+			},
+		},
+		{
+			name:     "workflow get",
+			shortcut: BaseWorkflowGet,
+			wantTips: []string{
+				"workflow-id must start with wkf",
+				"steps may be an empty array",
+				"Use +workflow-get before +workflow-update",
+				"lark-base-workflow-schema.md",
+			},
+		},
+		{
+			name:     "workflow create",
+			shortcut: BaseWorkflowCreate,
+			wantTips: []string{
+				"lark-cli base +workflow-create --base-token <base_token> --json @workflow.json",
+				"client_token is required",
+				"New workflows are created disabled",
+				"+table-list and +field-list",
+				"Step ids must be unique",
+				"lark-base-workflow-guide.md as the entry guide",
+				"lark-base-workflow-schema.md as the steps JSON SSOT",
+				"do not invent steps[].type/data/next/children from natural language",
+			},
+		},
+		{
+			name:     "workflow update",
+			shortcut: BaseWorkflowUpdate,
+			wantTips: []string{
+				"lark-cli base +workflow-update --base-token <base_token> --workflow-id <workflow_id> --json @workflow.json",
+				"PUT uses full replacement semantics",
+				"Use +workflow-get first",
+				"keep title/status/steps fields",
+				"workflow-id must start with wkf",
+				"Updating does not enable or disable",
+				"do not invent steps[].type/data/next/children from natural language",
+			},
+		},
+		{
+			name:     "workflow enable",
+			shortcut: BaseWorkflowEnable,
+			wantTips: []string{
+				"workflow-id must start with wkf",
+				"does not modify steps",
+				"New workflows are created disabled",
+			},
+		},
+		{
+			name:     "workflow disable",
+			shortcut: BaseWorkflowDisable,
+			wantTips: []string{
+				"workflow-id must start with wkf",
+				"does not delete the workflow or its steps",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			parent := &cobra.Command{Use: "base"}
+			tt.shortcut.Mount(parent, &cmdutil.Factory{})
+			cmd := parent.Commands()[0]
+
+			tips := strings.Join(cmdutil.GetTips(cmd), "\n")
+			for _, want := range tt.wantTips {
+				if !strings.Contains(tips, want) {
+					t.Fatalf("tips missing %q:\n%s", want, tips)
+				}
+			}
+		})
+	}
+}
+
+func TestBaseJSONExamplesLiveInFlagDescriptions(t *testing.T) {
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		wantHelp []string
+	}{
+		{
+			name:     "table create fields",
+			shortcut: BaseTableCreate,
+			wantHelp: []string{
+				`field JSON array for create, e.g. [{"name":"Title","type":"text"}`,
+			},
+		},
+		{
+			name:     "view set filter",
+			shortcut: BaseViewSetFilter,
+			wantHelp: []string{
+				`filter JSON object, e.g. {"logic":"and","conditions":[["Status","==","Todo"]]}`,
+			},
+		},
+		{
+			name:     "view set sort",
+			shortcut: BaseViewSetSort,
+			wantHelp: []string{
+				`sort_config JSON object, e.g. {"sort_config":[{"field":"Priority","desc":true}]}`,
+				`use {"sort_config":[]} to clear`,
+			},
+		},
+		{
+			name:     "view set group",
+			shortcut: BaseViewSetGroup,
+			wantHelp: []string{
+				`group JSON object with group_config array, e.g. {"group_config":[{"field":"Status","desc":false}]}`,
+			},
+		},
+		{
+			name:     "view set card",
+			shortcut: BaseViewSetCard,
+			wantHelp: []string{
+				`card JSON object, e.g. {"cover_field":"Cover"} or {"cover_field":null} to clear`,
+			},
+		},
+		{
+			name:     "view set timebar",
+			shortcut: BaseViewSetTimebar,
+			wantHelp: []string{
+				`timebar JSON object with start_time, end_time, title, e.g. {"start_time":"Start Date","end_time":"End Date","title":"Name"}`,
+			},
+		},
+		{
+			name:     "view set visible fields",
+			shortcut: BaseViewSetVisibleFields,
+			wantHelp: []string{
+				`visible fields JSON object, e.g. {"visible_fields":["Name","Status"]}`,
+			},
+		},
+		{
+			name:     "form question delete",
+			shortcut: BaseFormQuestionsDelete,
+			wantHelp: []string{
+				`JSON array of question IDs to delete, max 10 items, e.g. '["q_001","q_002"]'`,
+			},
+		},
+		{
+			name:     "record search json",
+			shortcut: BaseRecordSearch,
+			wantHelp: []string{
+				`record search JSON object for the full request body, e.g. {"keyword":"Alice","search_fields":["Name"],"select_fields":["Name","Status"],"filter":{"logic":"and","conditions":[]},"sort":[{"field":"Updated","desc":true}],"limit":50}; escape hatch for advanced cases`,
+			},
+		},
+		{
+			name:     "record upsert json",
+			shortcut: BaseRecordUpsert,
+			wantHelp: []string{
+				`record field map JSON object, e.g. {"Name":"Alice","Status":"Todo"}; do not wrap in fields`,
+			},
+		},
+		{
+			name:     "record batch create json",
+			shortcut: BaseRecordBatchCreate,
+			wantHelp: []string{
+				`batch create JSON object, e.g. {"fields":["Name","Status"],"rows":[["Task A","Todo"],["Task B",null]]}; rows follow fields order`,
+			},
+		},
+		{
+			name:     "record batch update json",
+			shortcut: BaseRecordBatchUpdate,
+			wantHelp: []string{
+				`batch update JSON object, e.g. {"record_id_list":["rec_xxx"],"patch":{"Status":"Done"}}; same patch applies to all records`,
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			parent := &cobra.Command{Use: "base"}
+			tt.shortcut.Mount(parent, &cmdutil.Factory{})
+			cmd := parent.Commands()[0]
+
+			help := cmd.Flags().FlagUsages()
+			for _, want := range tt.wantHelp {
+				if !strings.Contains(help, want) {
+					t.Fatalf("flag help missing %q:\n%s", want, help)
+				}
+			}
+		})
+	}
+}
+
+func TestBaseRecordWriteHelpGuidesAgents(t *testing.T) {
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		wantTips []string
+	}{
+		{
+			name:     "record upsert",
+			shortcut: BaseRecordUpsert,
+			wantTips: []string{
+				"Happy path JSON is a top-level field map",
+				"Without --record-id this creates a record",
+				"does not auto-upsert by business key",
+				"use +field-list to confirm real writable fields",
+				"do not write system fields, formula, lookup, or attachment fields",
+				"CellValue happy path: text/phone/url",
+				"select -> \"Todo\"",
+				"multi-select -> [\"Tag A\",\"Tag B\"]",
+				"datetime -> \"2026-03-24 10:00:00\"",
+				"checkbox -> true/false",
+				`ID-based CellValue: user/group/link fields use arrays like [{"id":"ou_xxx"}]`,
+				`location uses {"lng":116.397428,"lat":39.90923}`,
+				"Do not guess user/chat/linked-record IDs or location coordinates",
+				"lark-base-cell-value.md",
+				"do not invent values for fields not covered by the happy path",
+			},
+		},
+		{
+			name:     "record batch create",
+			shortcut: BaseRecordBatchCreate,
+			wantTips: []string{
+				"Happy path fields: fields is the column order",
+				"rows is an array of row arrays",
+				"may use null for empty cells",
+				"use +field-list to confirm real writable fields",
+				"Batch create supports max 200 rows per call",
+				"CellValue happy path: text/phone/url",
+				`ID-based CellValue: user/group/link fields use arrays like [{"id":"ou_xxx"}]`,
+				"lark-base-cell-value.md",
+				"do not invent values for fields not covered by the happy path",
+			},
+		},
+		{
+			name:     "record batch update",
+			shortcut: BaseRecordBatchUpdate,
+			wantTips: []string{
+				"Happy path fields: record_id_list is the target record IDs",
+				"patch is a field map applied unchanged to every target record",
+				"Do not use +record-batch-update for per-row different values",
+				"use +field-list to confirm real writable fields",
+				"Batch update supports max 200 records per call",
+				"CellValue happy path: text/phone/url",
+				`ID-based CellValue: user/group/link fields use arrays like [{"id":"ou_xxx"}]`,
+				"lark-base-cell-value.md",
+				"do not invent values for fields not covered by the happy path",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			parent := &cobra.Command{Use: "base"}
+			tt.shortcut.Mount(parent, &cmdutil.Factory{})
+			cmd := parent.Commands()[0]
+
+			tips := strings.Join(cmdutil.GetTips(cmd), "\n")
+			for _, want := range tt.wantTips {
+				if !strings.Contains(tips, want) {
+					t.Fatalf("tips missing %q:\n%s", want, tips)
+				}
+			}
+		})
+	}
+}
+
 func TestBaseFieldUpdateHelpGuidesAgents(t *testing.T) {
 	parent := &cobra.Command{Use: "base"}
 	BaseFieldUpdate.Mount(parent, &cmdutil.Factory{})
@@ -328,7 +745,7 @@ func TestBaseFieldUpdateHelpGuidesAgents(t *testing.T) {
 
 	tips := strings.Join(cmdutil.GetTips(cmd), "\n")
 	wantTips := []string{
-		`lark-cli base +field-update --base-token <base_token> --table-id <table_id> --field-id <field_id> --json '{"name":"Status","type":"text"}'`,
+		`lark-cli base +field-update --base-token <base_token> --table-id <table_id> --field-id "Status" --json '{"name":"Status","type":"text"}' --yes`,
 		`"type":"select","multiple":false,"options":[{"name":"Todo"},{"name":"Done"}]`,
 		"full field-definition PUT semantics",
 		"Read the current field first with +field-get",
@@ -472,11 +889,11 @@ func TestBaseTableValidate(t *testing.T) {
 
 func TestBaseRecordValidate(t *testing.T) {
 	ctx := context.Background()
-	if BaseRecordList.Validate != nil {
-		t.Fatalf("record list validate should be nil for repeatable --field-id")
+	if BaseRecordList.Validate == nil {
+		t.Fatalf("record list validate should reject invalid query flags before dry-run")
 	}
 	if BaseRecordSearch.Validate == nil {
-		t.Fatalf("record search validate should reject invalid JSON before dry-run")
+		t.Fatalf("record search validate should reject invalid JSON/query flags before dry-run")
 	}
 	if BaseRecordGet.Validate == nil {
 		t.Fatalf("record get validate should reject invalid record selection before dry-run")
@@ -487,6 +904,58 @@ func TestBaseRecordValidate(t *testing.T) {
 	if err := BaseRecordUpsert.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "tbl_1", "json": `{"Name":"Alice"}`}, nil, nil)); err != nil {
 		t.Fatalf("record upsert map validate err=%v", err)
 	}
+	if err := BaseRecordList.Validate(ctx, newBaseTestRuntime(
+		map[string]string{"base-token": "b", "table-id": "tbl_1", "filter-json": `{"logic":"and","conditions":[["Status","==","Todo"]]}`},
+		nil,
+		nil,
+	)); err != nil {
+		t.Fatalf("record list filter-json validate err=%v", err)
+	}
+	if err := BaseRecordList.Validate(ctx, newBaseTestRuntime(
+		map[string]string{"base-token": "b", "table-id": "tbl_1", "filter-json": `[["Status","==","Todo"]]`},
+		nil,
+		nil,
+	)); err == nil || !strings.Contains(err.Error(), "--filter-json must be a JSON object") {
+		t.Fatalf("err=%v", err)
+	}
+	if err := BaseRecordList.Validate(ctx, newBaseTestRuntimeWithArrays(
+		map[string]string{"base-token": "b", "table-id": "tbl_1", "sort-json": `[{"field":"F1"},{"field":"F2"},{"field":"F3"},{"field":"F4"},{"field":"F5"},{"field":"F6"},{"field":"F7"},{"field":"F8"},{"field":"F9"},{"field":"F10"},{"field":"F11"}]`},
+		nil,
+		nil,
+		nil,
+	)); err == nil || !strings.Contains(err.Error(), "sort supports at most 10 sort conditions") {
+		t.Fatalf("err=%v", err)
+	}
+	if err := BaseRecordSearch.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "tbl_1"}, nil, nil)); err == nil || !strings.Contains(err.Error(), "--keyword is required unless --json is used") {
+		t.Fatalf("err=%v", err)
+	}
+	if err := BaseRecordSearch.Validate(ctx, newBaseTestRuntimeWithArrays(
+		map[string]string{"base-token": "b", "table-id": "tbl_1", "keyword": "Alice"},
+		map[string][]string{"search-field": {"Name"}},
+		nil,
+		nil,
+	)); err != nil {
+		t.Fatalf("record search flag validate err=%v", err)
+	}
+	if err := BaseRecordSearch.Validate(ctx, newBaseTestRuntime(
+		map[string]string{
+			"base-token": "b",
+			"table-id":   "tbl_1",
+			"json":       `{"keyword":"Alice","search_fields":["Name"],"sort":{"sort_config":[{"field":"Updated","desc":true}]}}`,
+			"sort-json":  `[{"field":"Title","desc":false}]`,
+		},
+		nil,
+		nil,
+	)); err != nil {
+		t.Fatalf("record search json with sort-json validate err=%v", err)
+	}
+	if err := BaseRecordSearch.Validate(ctx, newBaseTestRuntime(
+		map[string]string{"base-token": "b", "table-id": "tbl_1", "json": `{"keyword":"Alice","search_fields":["Name"]}`, "keyword": "Bob"},
+		nil,
+		nil,
+	)); err == nil || !strings.Contains(err.Error(), "--json is mutually exclusive") {
+		t.Fatalf("err=%v", err)
+	}
 }
 
 func TestBaseViewValidate(t *testing.T) {

shortcuts/base/dashboard_arrange.go

@@ -22,6 +22,9 @@ var BaseDashboardArrange = common.Shortcut{
 		dashboardIDFlag(true),
 		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
 	},
+	Tips: []string{
+		"Server-side smart layout is not deterministic or position-specific; use only when the user asks to arrange or beautify a dashboard.",
+	},
 	DryRun: dryRunDashboardArrange,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeDashboardArrange(runtime)

shortcuts/base/dashboard_block_create.go

@@ -25,10 +25,19 @@ var BaseDashboardBlockCreate = common.Shortcut{
 		dashboardIDFlag(true),
 		{Name: "name", Desc: "block name", Required: true},
 		{Name: "type", Desc: "block type: column(柱状图)|bar(条形图)|line(折线图)|pie(饼图)|ring(环形图)|area(面积图)|combo(组合图)|scatter(散点图)|funnel(漏斗图)|wordCloud(词云)|radar(雷达图)|statistics(指标卡)|text(文本). Read dashboard-block-data-config.md before creating.", Required: true},
-		{Name: "data-config", Desc: "data config JSON object (table_name, series, count_all, group_by, filter, etc.)"},
-		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
+		{Name: "data-config", Desc: "data_config JSON object; read dashboard-block-data-config.md for the SSOT"},
+		{Name: "user-id-type", Desc: "user ID type for user fields in filters: open_id / union_id / user_id"},
 		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},
 	},
+	Tips: []string{
+		`lark-cli base +dashboard-block-create --base-token <base_token> --dashboard-id <dashboard_id> --name "Order Count" --type statistics --data-config '{"table_name":"Orders","count_all":true}'`,
+		`lark-cli base +dashboard-block-create --base-token <base_token> --dashboard-id <dashboard_id> --name "Dashboard Note" --type text --data-config '{"text":"# Sales Dashboard"}'`,
+		"Before creating data-backed blocks, use +table-list and +field-list to confirm real table and field names.",
+		"data_config uses table and field names, not table_id or field_id.",
+		"Read dashboard-block-data-config.md as the SSOT for chart templates, filters, metric rules, and type-specific fields; do not invent data_config from natural language.",
+		"Record the returned block_id; block update/delete/get-data commands need it.",
+		"Create dashboard blocks sequentially; do not parallelize multiple block creates for the same dashboard.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		pc := newParseCtx(runtime)
 		if runtime.Bool("no-validate") {

shortcuts/base/dashboard_block_delete.go

@@ -22,6 +22,10 @@ var BaseDashboardBlockDelete = common.Shortcut{
 		dashboardIDFlag(true),
 		blockIDFlag(true),
 	},
+	Tips: []string{
+		"lark-cli base +dashboard-block-delete --base-token <base_token> --dashboard-id <dashboard_id> --block-id <block_id> --yes",
+		baseHighRiskYesTip,
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			DELETE("/open-apis/base/v3/bases/:base_token/dashboards/:dashboard_id/blocks/:block_id").

shortcuts/base/dashboard_block_get.go

@@ -24,6 +24,11 @@ var BaseDashboardBlockGet = common.Shortcut{
 		blockIDFlag(true),
 		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
 	},
+	Tips: []string{
+		"lark-cli base +dashboard-block-get --base-token <base_token> --dashboard-id <dashboard_id> --block-id <block_id>",
+		"Use this command for block metadata such as name, type, layout, and data_config.",
+		"Use +dashboard-block-get-data when you need the computed chart result instead of metadata.",
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		params := map[string]interface{}{}
 		if uid := strings.TrimSpace(runtime.Str("user-id-type")); uid != "" {

shortcuts/base/dashboard_block_get_data.go

@@ -23,6 +23,7 @@ var BaseDashboardBlockGetData = common.Shortcut{
 	},
 	Tips: []string{
 		"lark-cli base +dashboard-block-get-data --base-token <base_token> --block-id <block_id>",
+		"This command does not need --dashboard-id.",
 		"Use +dashboard-block-get first when you need block metadata like name, type, or data_config.",
 		"This command returns computed chart protocol JSON directly, not wrapped block metadata.",
 		"Text blocks do not have computed chart data; this shortcut is for chart/statistics blocks.",

shortcuts/base/dashboard_block_list.go

@@ -21,9 +21,13 @@ var BaseDashboardBlockList = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		dashboardIDFlag(true),
-		{Name: "page-size", Desc: "page size (max 100)"},
+		{Name: "page-size", Desc: "page size, default 20, max 100"},
 		{Name: "page-token", Desc: "pagination token"},
 	},
+	Tips: []string{
+		"lark-cli base +dashboard-block-list --base-token <base_token> --dashboard-id <dashboard_id>",
+		"Use returned block_id and type values for +dashboard-block-get/update/delete/get-data.",
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		params := map[string]interface{}{}
 		if ps := strings.TrimSpace(runtime.Str("page-size")); ps != "" {

shortcuts/base/dashboard_block_update.go

@@ -24,10 +24,18 @@ var BaseDashboardBlockUpdate = common.Shortcut{
 		dashboardIDFlag(true),
 		blockIDFlag(true),
 		{Name: "name", Desc: "new block name"},
-		{Name: "data-config", Desc: "data config JSON. For chart types: table_name, series|count_all, group_by, filter. For text type: text (markdown supported). See dashboard-block-data-config.md for details."},
-		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
+		{Name: "data-config", Desc: "data_config JSON object; read dashboard-block-data-config.md for the SSOT"},
+		{Name: "user-id-type", Desc: "user ID type for user fields in filters: open_id / union_id / user_id"},
 		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},
 	},
+	Tips: []string{
+		`lark-cli base +dashboard-block-update --base-token <base_token> --dashboard-id <dashboard_id> --block-id <block_id> --name "Total Sales"`,
+		`lark-cli base +dashboard-block-update --base-token <base_token> --dashboard-id <dashboard_id> --block-id <block_id> --data-config '{"series":[{"field_name":"Amount","rollup":"SUM"}]}'`,
+		"Read dashboard-block-data-config.md as the SSOT for data_config templates, filters, metric rules, and type-specific fields; do not invent data_config from natural language.",
+		"Use +dashboard-block-get first to inspect the current data_config before replacing nested values.",
+		"Block type cannot be changed; delete and recreate the block to change chart type.",
+		"data_config update merges top-level keys, but each provided key is replaced as a whole.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		pc := newParseCtx(runtime)
 		if runtime.Bool("no-validate") {

shortcuts/base/dashboard_create.go

@@ -20,7 +20,10 @@ var BaseDashboardCreate = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		{Name: "name", Desc: "dashboard name", Required: true},
-		{Name: "theme-style", Desc: "theme style"},
+		{Name: "theme-style", Desc: "theme style, defaults to platform default when omitted"},
+	},
+	Tips: []string{
+		"Record the returned dashboard_id; dashboard block create/get/update/delete/arrange commands need it.",
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		body := map[string]interface{}{}

shortcuts/base/dashboard_delete.go

@@ -21,6 +21,11 @@ var BaseDashboardDelete = common.Shortcut{
 		baseTokenFlag(true),
 		dashboardIDFlag(true),
 	},
+	Tips: []string{
+		"lark-cli base +dashboard-delete --base-token <base_token> --dashboard-id <dashboard_id> --yes",
+		"Deleting a dashboard also deletes its blocks and cannot be recovered.",
+		baseHighRiskYesTip,
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			DELETE("/open-apis/base/v3/bases/:base_token/dashboards/:dashboard_id").

shortcuts/base/dashboard_get.go

@@ -21,6 +21,9 @@ var BaseDashboardGet = common.Shortcut{
 		baseTokenFlag(true),
 		dashboardIDFlag(true),
 	},
+	Tips: []string{
+		"Use +dashboard-block-list or +dashboard-block-get when you need block-level details.",
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			GET("/open-apis/base/v3/bases/:base_token/dashboards/:dashboard_id").

shortcuts/base/dashboard_list.go

@@ -20,9 +20,12 @@ var BaseDashboardList = common.Shortcut{
 	HasFormat:   true,
 	Flags: []common.Flag{
 		baseTokenFlag(true),
-		{Name: "page-size", Desc: "page size (max 100)"},
+		{Name: "page-size", Desc: "page size, max 100"},
 		{Name: "page-token", Desc: "pagination token"},
 	},
+	Tips: []string{
+		"Use returned dashboard_id values for +dashboard-get, +dashboard-block-list, and +dashboard-block-create.",
+	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		params := map[string]interface{}{}
 		if ps := strings.TrimSpace(runtime.Str("page-size")); ps != "" {

shortcuts/base/dashboard_update.go

@@ -21,7 +21,7 @@ var BaseDashboardUpdate = common.Shortcut{
 		baseTokenFlag(true),
 		dashboardIDFlag(true),
 		{Name: "name", Desc: "new dashboard name"},
-		{Name: "theme-style", Desc: "theme style"},
+		{Name: "theme-style", Desc: "theme style, leave empty to keep current theme"},
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		body := map[string]interface{}{}

shortcuts/base/field_create.go

@@ -23,7 +23,8 @@ var BaseFieldCreate = common.Shortcut{
 		{Name: "i-have-read-guide", Type: "bool", Desc: "set only after you have read the formula/lookup guide for those field types", Hidden: true},
 	},
 	Tips: []string{
-		`Example: --json '{"name":"Status","type":"text"}'`,
+		`Example text: lark-cli base +field-create --base-token <base_token> --table-id <table_id> --json '{"name":"Status","type":"text"}'`,
+		`Example select: lark-cli base +field-create --base-token <base_token> --table-id <table_id> --json '{"name":"Status","type":"select","multiple":false,"options":[{"name":"Todo"},{"name":"Done"}]}'`,
 		"Agent hint: use the lark-base skill's field-create guide for usage and limits.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/field_delete.go

@@ -17,7 +17,11 @@ var BaseFieldDelete = common.Shortcut{
 	Scopes:      []string{"base:field:delete"},
 	AuthTypes:   authTypes(),
 	Flags:       []common.Flag{baseTokenFlag(true), tableRefFlag(true), fieldRefFlag(true)},
-	DryRun:      dryRunFieldDelete,
+	Tips: []string{
+		baseHighRiskYesTip,
+		`Example: lark-cli base +field-delete --base-token <base_token> --table-id <table_id> --field-id "Status" --yes`,
+	},
+	DryRun: dryRunFieldDelete,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeFieldDelete(runtime)
 	},

shortcuts/base/field_get.go

@@ -17,7 +17,12 @@ var BaseFieldGet = common.Shortcut{
 	Scopes:      []string{"base:field:read"},
 	AuthTypes:   authTypes(),
 	Flags:       []common.Flag{baseTokenFlag(true), tableRefFlag(true), fieldRefFlag(true)},
-	DryRun:      dryRunFieldGet,
+	Tips: []string{
+		`Example: lark-cli base +field-get --base-token <base_token> --table-id <table_id> --field-id "Status"`,
+		"field-id accepts a field ID (fld...) or the field name from the current table.",
+		"Returns full field configuration; use it as the baseline before +field-update.",
+	},
+	DryRun: dryRunFieldGet,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeFieldGet(runtime)
 	},

shortcuts/base/field_list.go

@@ -20,7 +20,7 @@ var BaseFieldList = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
-		{Name: "limit", Type: "int", Default: "100", Desc: "pagination size"},
+		{Name: "limit", Type: "int", Default: "100", Desc: "pagination size, range 1-200"},
 	},
 	DryRun: dryRunFieldList,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/field_search_options.go

@@ -22,7 +22,11 @@ var BaseFieldSearchOptions = common.Shortcut{
 		fieldRefFlag(true),
 		{Name: "keyword", Desc: "keyword for option query"},
 		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
-		{Name: "limit", Type: "int", Default: "30", Desc: "pagination size"},
+		{Name: "limit", Type: "int", Default: "30", Desc: "pagination size, default 30"},
+	},
+	Tips: []string{
+		`Example: lark-cli base +field-search-options --base-token <base_token> --table-id <table_id> --field-id "Status" --keyword "Do"`,
+		"Use only for fields with options, such as select or multi-select fields.",
 	},
 	DryRun: dryRunFieldSearchOptions,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/field_update.go

@@ -24,8 +24,9 @@ var BaseFieldUpdate = common.Shortcut{
 		{Name: "i-have-read-guide", Type: "bool", Desc: "acknowledge reading formula/lookup guide before creating or updating those field types", Hidden: true},
 	},
 	Tips: []string{
-		`Example: lark-cli base +field-update --base-token <base_token> --table-id <table_id> --field-id <field_id> --json '{"name":"Status","type":"text"}'`,
-		`Example: lark-cli base +field-update --base-token <base_token> --table-id <table_id> --field-id <field_id> --json '{"name":"Status","type":"select","multiple":false,"options":[{"name":"Todo"},{"name":"Done"}]}'`,
+		baseHighRiskYesTip,
+		`Example text: lark-cli base +field-update --base-token <base_token> --table-id <table_id> --field-id "Status" --json '{"name":"Status","type":"text"}' --yes`,
+		`Example select: lark-cli base +field-update --base-token <base_token> --table-id <table_id> --field-id "Status" --json '{"name":"Status","type":"select","multiple":false,"options":[{"name":"Todo"},{"name":"Done"}]}' --yes`,
 		"Update uses full field-definition PUT semantics. Read the current field first with +field-get, then send the target state.",
 		"Type conversion is allowlist-based: only use CLI for safe conversions; otherwise migrate through a new field, or ask the user to finish high-risk conversions in the web UI.",
 		"Formula and lookup updates require reading the corresponding guide first.",

shortcuts/base/helpers_test.go

@@ -38,7 +38,7 @@ func TestParseHelpers(t *testing.T) {
 	if err != nil || obj["name"] != "demo" {
 		t.Fatalf("obj=%v err=%v", obj, err)
 	}
-	if _, err := parseJSONObject(testPC, `[1]`, "json"); err == nil || !strings.Contains(err.Error(), "--json must be a JSON object") || !strings.Contains(err.Error(), "lark-base skill") || strings.Contains(err.Error(), "array") {
+	if _, err := parseJSONObject(testPC, `[1]`, "json"); err == nil || !strings.Contains(err.Error(), "--json must be a JSON object") || !strings.Contains(err.Error(), "match the documented shape") || strings.Contains(err.Error(), "array") {
 		t.Fatalf("err=%v", err)
 	}
 	if _, err := parseJSONObject(testPC, `null`, "json"); err == nil || !strings.Contains(err.Error(), "--json must be a JSON object") {
@@ -66,7 +66,7 @@ func TestParseHelpers(t *testing.T) {
 	if _, err := parseStringListFlexible(testPC, `[1]`, "fields"); err == nil || !strings.Contains(err.Error(), "invalid JSON string array") {
 		t.Fatalf("err=%v", err)
 	}
-	if _, err := parseJSONValue(testPC, "{", "json"); err == nil || !strings.Contains(err.Error(), "tip: pass a valid JSON directly") || !strings.Contains(err.Error(), "@file.json") || !strings.Contains(err.Error(), "lark-base skill") {
+	if _, err := parseJSONValue(testPC, "{", "json"); err == nil || !strings.Contains(err.Error(), "tip: pass a valid JSON directly") || !strings.Contains(err.Error(), "@file.json") || !strings.Contains(err.Error(), "complex JSON/DSL") {
 		t.Fatalf("err=%v", err)
 	}
 	if !reflect.DeepEqual(parseStringList("m,n"), []string{"m", "n"}) {
@@ -334,11 +334,11 @@ func TestJSONInputHelpers(t *testing.T) {
 		t.Fatalf("err=%v", err)
 	}
 	syntaxErr := formatJSONError("json", "object", &json.SyntaxError{Offset: 7})
-	if !strings.Contains(syntaxErr.Error(), "near byte 7") || !strings.Contains(syntaxErr.Error(), "tip: pass a valid JSON directly") || !strings.Contains(syntaxErr.Error(), "@file.json") || !strings.Contains(syntaxErr.Error(), "lark-base skill") {
+	if !strings.Contains(syntaxErr.Error(), "near byte 7") || !strings.Contains(syntaxErr.Error(), "tip: pass a valid JSON directly") || !strings.Contains(syntaxErr.Error(), "@file.json") || !strings.Contains(syntaxErr.Error(), "complex JSON/DSL") {
 		t.Fatalf("syntaxErr=%v", syntaxErr)
 	}
 	typeErr := formatJSONError("json", "object", &json.UnmarshalTypeError{Field: "filter_info"})
-	if !strings.Contains(typeErr.Error(), `field "filter_info"`) || !strings.Contains(typeErr.Error(), "tip: pass a valid JSON directly") || !strings.Contains(typeErr.Error(), "@file.json") || !strings.Contains(typeErr.Error(), "lark-base skill") {
+	if !strings.Contains(typeErr.Error(), `field "filter_info"`) || !strings.Contains(typeErr.Error(), "tip: pass a valid JSON directly") || !strings.Contains(typeErr.Error(), "@file.json") || !strings.Contains(typeErr.Error(), "complex JSON/DSL") {
 		t.Fatalf("typeErr=%v", typeErr)
 	}
 }

shortcuts/base/high_risk.go

@@ -0,0 +1,6 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+const baseHighRiskYesTip = "This is a high-risk write command. If the user explicitly requested it and the target is unambiguous, pass --yes without asking again."

shortcuts/base/record_batch_create.go

@@ -19,13 +19,14 @@ var BaseRecordBatchCreate = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		tableRefFlag(true),
-		{Name: "json", Desc: "batch create JSON object", Required: true},
-	},
-	Tips: []string{
-		`Example: --json '{"fields":["Title","Status"],"rows":[["Task A","Open"],["Task B","Done"]]}'`,
-		"Agent hint: use the lark-base skill's record-batch-create guide for usage and limits.",
-		"Agent hint: use lark-base-cell-value.md as the source of truth for each CellValue.",
+		{Name: "json", Desc: `batch create JSON object, e.g. {"fields":["Name","Status"],"rows":[["Task A","Todo"],["Task B",null]]}; rows follow fields order`, Required: true},
 	},
+	Tips: append([]string{
+		"Happy path fields: fields is the column order; rows is an array of row arrays; each row must match fields order and may use null for empty cells.",
+		"Before writing, use +field-list to confirm real writable fields; do not write system fields, formula, lookup, or attachment fields as normal CellValue.",
+		"Batch create supports max 200 rows per call.",
+		"Use the record-batch-create guide for command limits and edge cases.",
+	}, recordCellValueHappyPathTips...),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateRecordJSON(runtime)
 	},

shortcuts/base/record_batch_update.go

@@ -19,13 +19,14 @@ var BaseRecordBatchUpdate = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		tableRefFlag(true),
-		{Name: "json", Desc: "batch update JSON object", Required: true},
-	},
-	Tips: []string{
-		`Example: --json '{"record_id_list":["recXXX"],"patch":{"Status":"Done"}}'`,
-		"Agent hint: use the lark-base skill's record-batch-update guide for usage and limits.",
-		"Agent hint: use lark-base-cell-value.md as the source of truth for each patch CellValue.",
+		{Name: "json", Desc: `batch update JSON object, e.g. {"record_id_list":["rec_xxx"],"patch":{"Status":"Done"}}; same patch applies to all records`, Required: true},
 	},
+	Tips: append([]string{
+		"Happy path fields: record_id_list is the target record IDs; patch is a field map applied unchanged to every target record.",
+		"Do not use +record-batch-update for per-row different values; call +record-upsert per record or use another supported flow.",
+		"Before writing, use +field-list to confirm real writable fields; do not write system fields, formula, lookup, or attachment fields as normal CellValue.",
+		"Batch update supports max 200 records per call; use the record-batch-update guide for command limits and edge cases.",
+	}, recordCellValueHappyPathTips...),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateRecordJSON(runtime)
 	},

shortcuts/base/record_delete.go

@@ -22,6 +22,10 @@ var BaseRecordDelete = common.Shortcut{
 		{Name: "record-id", Type: "string_array", Desc: "record ID (repeatable)"},
 		{Name: "json", Desc: `JSON object with record_id_list, e.g. {"record_id_list":["rec_xxx"]}`},
 	},
+	Tips: []string{
+		baseHighRiskYesTip,
+		`Example: lark-cli base +record-delete --base-token <base_token> --table-id <table_id> --record-id <record_id_1> --record-id <record_id_2> --yes`,
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateRecordSelection(runtime)
 	},

shortcuts/base/record_history_list.go

@@ -21,7 +21,11 @@ var BaseRecordHistoryList = common.Shortcut{
 		tableRefFlag(true),
 		recordRefFlag(true),
 		{Name: "max-version", Type: "int", Desc: "max version for next page"},
-		{Name: "page-size", Type: "int", Default: "30", Desc: "pagination size"},
+		{Name: "page-size", Type: "int", Default: "30", Desc: "pagination size, max 50"},
+	},
+	Tips: []string{
+		`Example: lark-cli base +record-history-list --base-token <base_token> --table-id <table_id> --record-id <record_id>`,
+		"This reads one record's history only; it is not a table-wide audit scan.",
 	},
 	DryRun: dryRunRecordHistoryList,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/record_list.go

@@ -22,6 +22,8 @@ var BaseRecordList = common.Shortcut{
 		tableRefFlag(true),
 		recordListFieldRefFlag(),
 		recordListViewRefFlag(),
+		recordFilterFlag(),
+		recordSortFlag(),
 		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
 		{Name: "limit", Type: "int", Default: "100", Desc: "pagination size, range 1-200"},
 		recordReadFormatFlag(),
@@ -29,10 +31,21 @@ var BaseRecordList = common.Shortcut{
 	Tips: []string{
 		"Example: lark-cli base +record-list --base-token <base_token> --table-id <table_id> --limit 50",
 		"Example with projection: lark-cli base +record-list --base-token <base_token> --table-id <table_id> --field-id Name --field-id Status --limit 50",
+		`Text equality filter: --filter-json '{"logic":"and","conditions":[["Title","==","Launch plan"]]}'`,
+		`Text contains/like filter: --filter-json '{"logic":"and","conditions":[["Title","intersects","urgent"]]}'`,
+		`Number equality filter: --filter-json '{"logic":"and","conditions":[["Score","==",95]]}'`,
+		`Date equality filter: --filter-json '{"logic":"and","conditions":[["Due Date","==","ExactDate(2026-06-02)"]]}'`,
+		`Option intersection filter: --filter-json '{"logic":"and","conditions":[["Tags","intersects",["P0","Blocked"]]]}'`,
+		`Sort priority follows --sort-json array order: --sort-json '[{"field":"Updated","desc":true},{"field":"Title","desc":false}]'`,
+		formatRecordQueryPriorityTip(),
 		"Default output is markdown; pass --format json to get the raw JSON envelope.",
 		"Use --field-id repeatedly to keep output small and aligned with the task.",
-		"Use --view-id when the user asks for a specific view or after creating a temporary filtered/sorted view.",
-		"For structured filters, sorting, Top/Bottom N, and link fields, follow the lark-base record read SOP.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := validateRecordReadFormat(runtime); err != nil {
+			return err
+		}
+		return validateRecordQueryOptions(runtime)
 	},
 	DryRun: dryRunRecordList,
 	PostMount: func(cmd *cobra.Command) {

shortcuts/base/record_ops.go

@@ -15,6 +15,13 @@ import (
 const maxRecordSelectionCount = 200
 const maxBatchGetSelectFieldCount = 100
 
+var recordCellValueHappyPathTips = []string{
+	`CellValue happy path: text/phone/url -> "text"; number/currency/percent/rating -> 12.5; select -> "Todo"; multi-select -> ["Tag A","Tag B"]; datetime -> "2026-03-24 10:00:00"; checkbox -> true/false.`,
+	`ID-based CellValue: user/group/link fields use arrays like [{"id":"ou_xxx"}], [{"id":"oc_xxx"}], [{"id":"rec_xxx"}]; location uses {"lng":116.397428,"lat":39.90923}; null clears a cell when allowed.`,
+	"Do not guess user/chat/linked-record IDs or location coordinates; resolve them first with the relevant contact/im/record lookup flow.",
+	"Use lark-base-cell-value.md for complex CellValue shapes and special field types; do not invent values for fields not covered by the happy path.",
+}
+
 type recordSelection struct {
 	recordIDs    []string
 	selectFields []string
@@ -210,6 +217,9 @@ func dryRunRecordList(_ context.Context, runtime *common.RuntimeContext) *common
 	if viewID := runtime.Str("view-id"); viewID != "" {
 		params.Set("view_id", viewID)
 	}
+	if err := applyRecordQueryToURLValues(runtime, params); err != nil {
+		return common.NewDryRunAPI()
+	}
 	path := "/open-apis/base/v3/bases/:base_token/tables/:table_id/records?" + params.Encode()
 	return common.NewDryRunAPI().
 		GET(path).
@@ -230,8 +240,12 @@ func dryRunRecordGet(_ context.Context, runtime *common.RuntimeContext) *common.
 }
 
 func dryRunRecordSearch(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	pc := newParseCtx(runtime)
-	body, _ := parseJSONObject(pc, runtime.Str("json"), "json")
+	var body map[string]interface{}
+	if strings.TrimSpace(runtime.Str("json")) != "" {
+		body, _ = recordSearchJSONBody(runtime)
+	} else {
+		body, _ = recordSearchFlagBody(runtime)
+	}
 	return common.NewDryRunAPI().
 		POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/records/search").
 		Body(body).
@@ -381,6 +395,9 @@ func executeRecordList(runtime *common.RuntimeContext) error {
 	if viewID := runtime.Str("view-id"); viewID != "" {
 		params["view_id"] = viewID
 	}
+	if err := applyRecordQueryToParams(runtime, params); err != nil {
+		return err
+	}
 	data, err := baseV3Call(runtime, "GET", baseV3Path("bases", runtime.Str("base-token"), "tables", baseTableID(runtime), "records"), params, nil)
 	if err != nil {
 		return err
@@ -413,8 +430,13 @@ func executeRecordGet(runtime *common.RuntimeContext) error {
 }
 
 func executeRecordSearch(runtime *common.RuntimeContext) error {
-	pc := newParseCtx(runtime)
-	body, err := parseJSONObject(pc, runtime.Str("json"), "json")
+	var body map[string]interface{}
+	var err error
+	if strings.TrimSpace(runtime.Str("json")) != "" {
+		body, err = recordSearchJSONBody(runtime)
+	} else {
+		body, err = recordSearchFlagBody(runtime)
+	}
 	if err != nil {
 		return err
 	}

shortcuts/base/record_query.go

@@ -0,0 +1,248 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	recordFilterJSONFlag = "filter-json"
+	recordSortJSONFlag   = "sort-json"
+	recordSortMaxCount   = 10
+)
+
+func recordFilterFlag() common.Flag {
+	return common.Flag{
+		Name:  recordFilterJSONFlag,
+		Desc:  `filter JSON object or @file, same shape as view filter JSON; overrides --view-id view filters`,
+		Input: []string{common.File},
+	}
+}
+
+func recordSortFlag() common.Flag {
+	return common.Flag{
+		Name:  recordSortJSONFlag,
+		Desc:  `sort JSON array or @file, e.g. [{"field":"Updated","desc":true}]; also accepts {"sort_config":[...]}; order is priority; max 10`,
+		Input: []string{common.File},
+	}
+}
+
+func validateRecordQueryOptions(runtime *common.RuntimeContext) error {
+	if _, err := parseRecordFilterFlag(runtime); err != nil {
+		return err
+	}
+	_, err := parseRecordSortFlag(runtime)
+	return err
+}
+
+func parseRecordFilterFlag(runtime *common.RuntimeContext) (interface{}, error) {
+	filterRaw := strings.TrimSpace(runtime.Str(recordFilterJSONFlag))
+	if filterRaw == "" {
+		return nil, nil
+	}
+	pc := newParseCtx(runtime)
+	return parseJSONObject(pc, filterRaw, recordFilterJSONFlag)
+}
+
+func parseRecordSortFlag(runtime *common.RuntimeContext) ([]interface{}, error) {
+	sortRaw := strings.TrimSpace(runtime.Str(recordSortJSONFlag))
+	if sortRaw == "" {
+		return nil, nil
+	}
+	pc := newParseCtx(runtime)
+	value, err := parseJSONValue(pc, sortRaw, recordSortJSONFlag)
+	if err != nil {
+		return nil, err
+	}
+	return normalizeRecordSortValue(value, "--"+recordSortJSONFlag)
+}
+
+func normalizeRecordSortValue(value interface{}, label string) ([]interface{}, error) {
+	var sortConfig []interface{}
+	if parsed, ok := value.([]interface{}); ok {
+		sortConfig = parsed
+	} else if obj, ok := value.(map[string]interface{}); ok {
+		rawSortConfig, ok := obj["sort_config"]
+		if !ok {
+			return nil, common.FlagErrorf("%s must be a JSON array or an object with sort_config array", label)
+		}
+		parsed, ok := rawSortConfig.([]interface{})
+		if !ok {
+			return nil, common.FlagErrorf("%s.sort_config must be a JSON array", label)
+		}
+		sortConfig = parsed
+	} else {
+		return nil, common.FlagErrorf("%s must be a JSON array or an object with sort_config array", label)
+	}
+	if len(sortConfig) > recordSortMaxCount {
+		return nil, common.FlagErrorf("sort supports at most %d sort conditions; got %d", recordSortMaxCount, len(sortConfig))
+	}
+	return sortConfig, nil
+}
+
+func marshalRecordQueryFlag(flagName string, value interface{}) (string, error) {
+	data, err := json.Marshal(value)
+	if err != nil {
+		return "", common.FlagErrorf("--%s cannot encode JSON: %v", flagName, err)
+	}
+	return string(data), nil
+}
+
+func applyRecordQueryToParams(runtime *common.RuntimeContext, params map[string]interface{}) error {
+	filter, err := parseRecordFilterFlag(runtime)
+	if err != nil {
+		return err
+	}
+	if filter != nil {
+		filterJSON, err := marshalRecordQueryFlag(recordFilterJSONFlag, filter)
+		if err != nil {
+			return err
+		}
+		params["filter"] = filterJSON
+	}
+	sortConfig, err := parseRecordSortFlag(runtime)
+	if err != nil {
+		return err
+	}
+	if len(sortConfig) > 0 {
+		sortJSON, err := marshalRecordQueryFlag(recordSortJSONFlag, sortConfig)
+		if err != nil {
+			return err
+		}
+		params["sort"] = sortJSON
+	}
+	return nil
+}
+
+func applyRecordQueryToURLValues(runtime *common.RuntimeContext, params url.Values) error {
+	filter, err := parseRecordFilterFlag(runtime)
+	if err != nil {
+		return err
+	}
+	if filter != nil {
+		filterJSON, err := marshalRecordQueryFlag(recordFilterJSONFlag, filter)
+		if err != nil {
+			return err
+		}
+		params["filter"] = []string{filterJSON}
+	}
+	sortConfig, err := parseRecordSortFlag(runtime)
+	if err != nil {
+		return err
+	}
+	if len(sortConfig) > 0 {
+		sortJSON, err := marshalRecordQueryFlag(recordSortJSONFlag, sortConfig)
+		if err != nil {
+			return err
+		}
+		params["sort"] = []string{sortJSON}
+	}
+	return nil
+}
+
+func applyRecordQueryToBody(runtime *common.RuntimeContext, body map[string]interface{}) error {
+	filter, err := parseRecordFilterFlag(runtime)
+	if err != nil {
+		return err
+	}
+	if filter != nil {
+		body["filter"] = filter
+	}
+	sortConfig, err := parseRecordSortFlag(runtime)
+	if err != nil {
+		return err
+	}
+	if len(sortConfig) > 0 {
+		body["sort"] = sortConfig
+	}
+	return nil
+}
+
+func recordSearchFlagBody(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	body := map[string]interface{}{}
+	if keyword := strings.TrimSpace(runtime.Str("keyword")); keyword != "" {
+		body["keyword"] = keyword
+	}
+	searchFields := runtime.StrArray("search-field")
+	if len(searchFields) > 0 {
+		body["search_fields"] = searchFields
+	}
+	selectFields := recordListFields(runtime)
+	if len(selectFields) > 0 {
+		body["select_fields"] = selectFields
+	}
+	if viewID := runtime.Str("view-id"); viewID != "" {
+		body["view_id"] = viewID
+	}
+	offset := runtime.Int("offset")
+	if offset < 0 {
+		offset = 0
+	}
+	body["offset"] = offset
+	body["limit"] = common.ParseIntBounded(runtime, "limit", 1, 200)
+	return body, applyRecordQueryToBody(runtime, body)
+}
+
+func recordSearchJSONBody(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	pc := newParseCtx(runtime)
+	body, err := parseJSONObject(pc, runtime.Str("json"), "json")
+	if err != nil {
+		return nil, err
+	}
+	if err := normalizeRecordSearchJSONBody(body); err != nil {
+		return nil, err
+	}
+	return body, applyRecordQueryToBody(runtime, body)
+}
+
+func normalizeRecordSearchJSONBody(body map[string]interface{}) error {
+	if rawSort, ok := body["sort"]; ok {
+		if sortConfig, err := normalizeRecordSortValue(rawSort, "--json.sort"); err == nil {
+			body["sort"] = sortConfig
+		} else {
+			return err
+		}
+	}
+	return nil
+}
+
+func validateRecordSearchFlags(runtime *common.RuntimeContext) error {
+	if err := validateRecordReadFormat(runtime); err != nil {
+		return err
+	}
+	jsonRaw := strings.TrimSpace(runtime.Str("json"))
+	if jsonRaw != "" {
+		if recordSearchHasJSONExclusiveFlagInputs(runtime) {
+			return common.FlagErrorf("--json is mutually exclusive with keyword/search/projection/pagination flags; put those fields inside --json, or omit --json")
+		}
+		_, err := recordSearchJSONBody(runtime)
+		return err
+	}
+	if strings.TrimSpace(runtime.Str("keyword")) == "" {
+		return common.FlagErrorf("--keyword is required unless --json is used")
+	}
+	if len(runtime.StrArray("search-field")) == 0 {
+		return common.FlagErrorf("--search-field is required unless --json is used")
+	}
+	return validateRecordQueryOptions(runtime)
+}
+
+func recordSearchHasJSONExclusiveFlagInputs(runtime *common.RuntimeContext) bool {
+	return strings.TrimSpace(runtime.Str("keyword")) != "" ||
+		len(runtime.StrArray("search-field")) > 0 ||
+		len(recordListFields(runtime)) > 0 ||
+		runtime.Str("view-id") != "" ||
+		runtime.Changed("offset") ||
+		runtime.Changed("limit")
+}
+
+func formatRecordQueryPriorityTip() string {
+	return fmt.Sprintf("Query priority: --%s overrides --view-id's view filter JSON; --%s overrides --view-id's view sort config.", recordFilterJSONFlag, recordSortJSONFlag)
+}

shortcuts/base/record_query_test.go

@@ -0,0 +1,161 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"encoding/json"
+	"net/url"
+	"strings"
+	"testing"
+)
+
+func TestNormalizeRecordSortValue(t *testing.T) {
+	t.Run("array", func(t *testing.T) {
+		sortConfig, err := normalizeRecordSortValue([]interface{}{
+			map[string]interface{}{"field": "Updated", "desc": true},
+		}, "--sort-json")
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if len(sortConfig) != 1 {
+			t.Fatalf("sortConfig=%#v", sortConfig)
+		}
+	})
+
+	t.Run("wrapped sort_config", func(t *testing.T) {
+		sortConfig, err := normalizeRecordSortValue(map[string]interface{}{
+			"sort_config": []interface{}{
+				map[string]interface{}{"field": "Updated", "desc": false},
+			},
+		}, "--json.sort")
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		first := sortConfig[0].(map[string]interface{})
+		if first["field"] != "Updated" || first["desc"] != false {
+			t.Fatalf("sortConfig=%#v", sortConfig)
+		}
+	})
+
+	t.Run("invalid wrapper", func(t *testing.T) {
+		_, err := normalizeRecordSortValue(map[string]interface{}{"sort": []interface{}{}}, "--sort-json")
+		if err == nil || !strings.Contains(err.Error(), "sort_config array") {
+			t.Fatalf("err=%v", err)
+		}
+	})
+
+	t.Run("invalid sort_config type", func(t *testing.T) {
+		_, err := normalizeRecordSortValue(map[string]interface{}{"sort_config": "Updated"}, "--sort-json")
+		if err == nil || !strings.Contains(err.Error(), "--sort-json.sort_config must be a JSON array") {
+			t.Fatalf("err=%v", err)
+		}
+	})
+
+	t.Run("invalid scalar", func(t *testing.T) {
+		_, err := normalizeRecordSortValue("Updated", "--sort-json")
+		if err == nil || !strings.Contains(err.Error(), "must be a JSON array") {
+			t.Fatalf("err=%v", err)
+		}
+	})
+}
+
+func TestApplyRecordQueryToParams(t *testing.T) {
+	runtime := newBaseTestRuntime(
+		map[string]string{
+			"filter-json": `{"logic":"and","conditions":[["Status","==","Todo"]]}`,
+			"sort-json":   `{"sort_config":[{"field":"Updated","desc":true}]}`,
+		},
+		nil,
+		nil,
+	)
+	params := map[string]interface{}{"view_id": "viw_1"}
+	if err := applyRecordQueryToParams(runtime, params); err != nil {
+		t.Fatalf("err=%v", err)
+	}
+	if params["view_id"] != "viw_1" {
+		t.Fatalf("params=%#v", params)
+	}
+	var filter map[string]interface{}
+	if err := json.Unmarshal([]byte(params["filter"].(string)), &filter); err != nil {
+		t.Fatalf("filter err=%v", err)
+	}
+	if filter["logic"] != "and" {
+		t.Fatalf("filter=%#v", filter)
+	}
+	var sortConfig []interface{}
+	if err := json.Unmarshal([]byte(params["sort"].(string)), &sortConfig); err != nil {
+		t.Fatalf("sort err=%v", err)
+	}
+	firstSort := sortConfig[0].(map[string]interface{})
+	if firstSort["field"] != "Updated" || firstSort["desc"] != true {
+		t.Fatalf("sort=%#v", sortConfig)
+	}
+}
+
+func TestApplyRecordQueryToURLValues(t *testing.T) {
+	runtime := newBaseTestRuntime(
+		map[string]string{
+			"filter-json": `{"logic":"or","conditions":[["Score",">",90]]}`,
+			"sort-json":   `[{"field":"Score","desc":false}]`,
+		},
+		nil,
+		nil,
+	)
+	params := url.Values{"view_id": {"viw_1"}}
+	if err := applyRecordQueryToURLValues(runtime, params); err != nil {
+		t.Fatalf("err=%v", err)
+	}
+	if got := params.Get("view_id"); got != "viw_1" {
+		t.Fatalf("view_id=%q", got)
+	}
+	if !strings.Contains(params.Get("filter"), `"logic":"or"`) || !strings.Contains(params.Get("sort"), `"field":"Score"`) {
+		t.Fatalf("params=%#v", params)
+	}
+}
+
+func TestRecordSearchJSONBodyAppliesQueryFlagOverrides(t *testing.T) {
+	runtime := newBaseTestRuntime(
+		map[string]string{
+			"json":        `{"keyword":"urgent","search_fields":["Title"],"filter":{"logic":"and","conditions":[["Status","==","Done"]]},"sort":{"sort_config":[{"field":"Updated","desc":false}]}}`,
+			"filter-json": `{"logic":"and","conditions":[["Status","==","Todo"]]}`,
+			"sort-json":   `[{"field":"Score","desc":true}]`,
+		},
+		nil,
+		nil,
+	)
+	body, err := recordSearchJSONBody(runtime)
+	if err != nil {
+		t.Fatalf("err=%v", err)
+	}
+	filter := body["filter"].(map[string]interface{})
+	conditions := filter["conditions"].([]interface{})
+	statusCondition := conditions[0].([]interface{})
+	if statusCondition[2] != "Todo" {
+		t.Fatalf("filter=%#v", filter)
+	}
+	sortConfig := body["sort"].([]interface{})
+	firstSort := sortConfig[0].(map[string]interface{})
+	if firstSort["field"] != "Score" || firstSort["desc"] != true {
+		t.Fatalf("sort=%#v", sortConfig)
+	}
+}
+
+func TestRecordSearchJSONBodyNormalizesWrappedSort(t *testing.T) {
+	runtime := newBaseTestRuntime(
+		map[string]string{
+			"json": `{"keyword":"urgent","search_fields":["Title"],"sort":{"sort_config":[{"field":"Updated","desc":false}]}}`,
+		},
+		nil,
+		nil,
+	)
+	body, err := recordSearchJSONBody(runtime)
+	if err != nil {
+		t.Fatalf("err=%v", err)
+	}
+	sortConfig := body["sort"].([]interface{})
+	firstSort := sortConfig[0].(map[string]interface{})
+	if firstSort["field"] != "Updated" || firstSort["desc"] != false {
+		t.Fatalf("sort=%#v", sortConfig)
+	}
+}

shortcuts/base/record_search.go

@@ -20,23 +20,34 @@ var BaseRecordSearch = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		tableRefFlag(true),
-		{Name: "json", Desc: `record search JSON object; requires keyword/search_fields, optional select_fields/view_id/offset/limit`, Required: true},
+		{Name: "json", Desc: `record search JSON object for the full request body, e.g. {"keyword":"Alice","search_fields":["Name"],"select_fields":["Name","Status"],"filter":{"logic":"and","conditions":[]},"sort":[{"field":"Updated","desc":true}],"limit":50}; escape hatch for advanced cases`},
+		{Name: "keyword", Desc: "keyword for record search; required unless --json is used"},
+		{Name: "search-field", Type: "string_array", Desc: "field ID or name to search; repeat for multiple fields; required unless --json is used"},
+		recordListFieldRefFlag(),
+		recordListViewRefFlag(),
+		recordFilterFlag(),
+		recordSortFlag(),
+		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
+		{Name: "limit", Type: "int", Default: "10", Desc: "pagination size, range 1-200"},
 		recordReadFormatFlag(),
 	},
 	Tips: []string{
-		`Example: lark-cli base +record-search --base-token <base_token> --table-id <table_id> --json '{"keyword":"Alice","search_fields":["Name"],"select_fields":["Name","Status"],"limit":50}'`,
-		`JSON shape: {"keyword":"<text>","search_fields":["<field_id_or_name>"],"select_fields":["<field_id_or_name>"],"view_id":"<view_id_or_name>","offset":0,"limit":10}.`,
+		`Happy path fields: keyword (string), search_fields (1-20 field names/ids), select_fields (optional projection, <=50), view_id (optional), offset (default 0), limit (default 10, range 1-200).`,
 		"JSON constraints: keyword length >=1; search_fields length 1-20; select_fields length <=50; offset >=0 defaults to 0; limit range 1-200 defaults to 10.",
 		"view_id scopes search to records in that view; when select_fields is omitted, returned fields follow that view's visible fields.",
+		`Example: lark-cli base +record-search --base-token <base_token> --table-id <table_id> --keyword Alice --search-field Name --field-id Name --field-id Status --limit 20`,
+		`Example with filter/sort JSON: lark-cli base +record-search --base-token <base_token> --table-id <table_id> --keyword Alice --search-field Name --filter-json @filter.json --sort-json '[{"field":"Updated","desc":true}]'`,
+		`Text equality filter: --filter-json '{"logic":"and","conditions":[["Title","==","Launch plan"]]}'`,
+		`Text contains/like filter: --filter-json '{"logic":"and","conditions":[["Title","intersects","urgent"]]}'`,
+		`Option intersection filter: --filter-json '{"logic":"and","conditions":[["Tags","intersects",["P0","Blocked"]]]}'`,
+		`Sort priority follows --sort-json array order.`,
+		formatRecordQueryPriorityTip(),
+		"Use +record-search for keyword matching; use --filter-json for structured conditions and --sort-json for result ordering.",
+		"Use --json only when you need to pass the full search body directly.",
 		"Default output is markdown; pass --format json to get the raw JSON envelope.",
-		"Use +record-search only for keyword search; use a filtered view plus +record-list for structured conditions.",
-		"Agent hint: follow the lark-base record read SOP for record read routing and limits.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if err := validateRecordReadFormat(runtime); err != nil {
-			return err
-		}
-		return validateRecordJSON(runtime)
+		return validateRecordSearchFlags(runtime)
 	},
 	DryRun: dryRunRecordSearch,
 	PostMount: func(cmd *cobra.Command) {

shortcuts/base/record_share_link_create.go

@@ -22,8 +22,9 @@ var BaseRecordShareLinkCreate = common.Shortcut{
 		{Name: "record-ids", Type: "string_slice", Desc: "record IDs to generate share links for (comma-separated or repeatable, max 100)", Required: true},
 	},
 	Tips: []string{
-		`Single record:  --base-token xxx --table-id tblxxx --record-ids recxxx`,
-		`Multiple records: --base-token xxx --table-id tblxxx --record-ids rec001,rec002,rec003`,
+		`Example: lark-cli base +record-share-link-create --base-token <base_token> --table-id <table_id> --record-ids <record_id>`,
+		"Max 100 record IDs per call; duplicate IDs are ignored.",
+		"Output record_share_links maps record_id to URL; records without permission or missing records may be absent.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateRecordShareBatch(runtime)

shortcuts/base/record_upload_attachment.go

@@ -117,6 +117,7 @@ var BaseRecordRemoveAttachment = common.Shortcut{
 		{Name: "file-token", Type: "string_array", Desc: "attachment file_token to remove from the target cell; repeat to remove multiple attachments; max 50 tokens", Required: true},
 	},
 	Tips: []string{
+		baseHighRiskYesTip,
 		`Example: lark-cli base +record-remove-attachment --base-token <base_token> --table-id <table_id> --record-id <record_id> --field-id <attachment_field_id> --file-token <file_token> --yes`,
 		`Repeat --file-token to remove multiple attachments from the same cell in one call.`,
 		`This is a high-risk write command and requires --yes.`,

shortcuts/base/record_upsert.go

@@ -20,12 +20,14 @@ var BaseRecordUpsert = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		recordRefFlag(false),
-		{Name: "json", Desc: "record JSON object: Map<FieldNameOrID, CellValue>", Required: true},
-	},
-	Tips: []string{
-		`Example: --json '{"Name":"Alice"}'`,
-		"Agent hint: use the lark-base skill's record-upsert guide for usage and limits.",
+		{Name: "json", Desc: `record field map JSON object, e.g. {"Name":"Alice","Status":"Todo"}; do not wrap in fields`, Required: true},
 	},
+	Tips: append([]string{
+		"Happy path JSON is a top-level field map: each key is a real field name or field ID, each value is that field's CellValue.",
+		"Without --record-id this creates a record; with --record-id this updates that record. It does not auto-upsert by business key.",
+		"Before writing, use +field-list to confirm real writable fields; do not write system fields, formula, lookup, or attachment fields as normal CellValue.",
+		"Use the record-upsert guide for command limits and edge cases.",
+	}, recordCellValueHappyPathTips...),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateRecordJSON(runtime)
 	},

shortcuts/base/table_create.go

@@ -20,7 +20,11 @@ var BaseTableCreate = common.Shortcut{
 		baseTokenFlag(true),
 		{Name: "name", Desc: "table name", Required: true},
 		{Name: "view", Desc: "view JSON object/array for create"},
-		{Name: "fields", Desc: "field JSON array for create"},
+		{Name: "fields", Desc: `field JSON array for create, e.g. [{"name":"Title","type":"text"},{"name":"Status","type":"select","options":[{"name":"Todo"},{"name":"Done"}]}]`},
+	},
+	Tips: []string{
+		"Before using --fields, read lark-base-field-json.md or rely on the same field JSON shape used by +field-create; do not invent field properties.",
+		"The first --fields item replaces the default field.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateTableCreate(runtime)

shortcuts/base/table_delete.go

@@ -17,7 +17,12 @@ var BaseTableDelete = common.Shortcut{
 	Scopes:      []string{"base:table:delete"},
 	AuthTypes:   authTypes(),
 	Flags:       []common.Flag{baseTokenFlag(true), tableRefFlag(true)},
-	DryRun:      dryRunTableDelete,
+	Tips: []string{
+		`Example: lark-cli base +table-delete --base-token <base_token> --table-id "Old Tasks" --yes`,
+		"table-id accepts a table ID (tbl...) or the table name in the current Base.",
+		baseHighRiskYesTip,
+	},
+	DryRun: dryRunTableDelete,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeTableDelete(runtime)
 	},

shortcuts/base/table_get.go

@@ -17,7 +17,11 @@ var BaseTableGet = common.Shortcut{
 	Scopes:      []string{"base:table:read", "base:field:read", "base:view:read"},
 	AuthTypes:   authTypes(),
 	Flags:       []common.Flag{baseTokenFlag(true), tableRefFlag(true)},
-	DryRun:      dryRunTableGet,
+	Tips: []string{
+		`Example: lark-cli base +table-get --base-token <base_token> --table-id "Tasks"`,
+		"table-id accepts a table ID (tbl...) or the table name in the current Base.",
+	},
+	DryRun: dryRunTableGet,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeTableGet(runtime)
 	},

shortcuts/base/table_list.go

@@ -19,7 +19,7 @@ var BaseTableList = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
-		{Name: "limit", Type: "int", Default: "50", Desc: "pagination limit"},
+		{Name: "limit", Type: "int", Default: "50", Desc: "pagination size, range 1-100"},
 	},
 	DryRun: dryRunTableList,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/view_create.go

@@ -19,11 +19,13 @@ var BaseViewCreate = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		tableRefFlag(true),
-		{Name: "json", Desc: "view JSON object/array", Required: true},
+		{Name: "json", Desc: "view JSON object/array; type defaults to grid; type range: grid, kanban, gallery, calendar, gantt", Required: true},
 	},
 	Tips: []string{
-		`Example: --json '{"name":"Main","type":"grid"}'`,
-		"Agent hint: use the lark-base skill's view-create guide for usage and limits.",
+		`Example: lark-cli base +view-create --base-token <base_token> --table-id <table_id> --json '{"name":"Main","type":"grid"}'`,
+		`Minimal: --json '{"name":"Main"}' creates a grid view.`,
+		"Do not pass form as a view type; form views are managed through form commands.",
+		`Use +view-set-visible-fields after creation when the user needs a specific field order or visibility.`,
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewCreate(runtime)

shortcuts/base/view_delete.go

@@ -17,7 +17,11 @@ var BaseViewDelete = common.Shortcut{
 	Scopes:      []string{"base:view:write_only"},
 	AuthTypes:   authTypes(),
 	Flags:       []common.Flag{baseTokenFlag(true), tableRefFlag(true), viewRefFlag(true)},
-	DryRun:      dryRunViewDelete,
+	Tips: []string{
+		baseHighRiskYesTip,
+		`Example: lark-cli base +view-delete --base-token <base_token> --table-id <table_id> --view-id "Old View" --yes`,
+	},
+	DryRun: dryRunViewDelete,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeViewDelete(runtime)
 	},

shortcuts/base/view_list.go

@@ -20,7 +20,7 @@ var BaseViewList = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
-		{Name: "limit", Type: "int", Default: "100", Desc: "pagination size"},
+		{Name: "limit", Type: "int", Default: "100", Desc: "pagination size, range 1-200"},
 	},
 	DryRun: dryRunViewList,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/view_set_card.go

@@ -20,11 +20,12 @@ var BaseViewSetCard = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		viewRefFlag(true),
-		{Name: "json", Desc: "card JSON object", Required: true},
+		{Name: "json", Desc: `card JSON object, e.g. {"cover_field":"Cover"} or {"cover_field":null} to clear`, Required: true},
 	},
 	Tips: []string{
-		`Example: --json '{"cover_field":"fldCover"}'`,
-		"Agent hint: use the lark-base skill's view-set-card guide for usage and limits.",
+		"Supported view types: gallery, kanban.",
+		"cover_field should be an attachment field id/name, or null to clear.",
+		"Use +view-get-card first when updating an existing card view configuration.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONObject(runtime)

shortcuts/base/view_set_filter.go

@@ -20,10 +20,9 @@ var BaseViewSetFilter = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		viewRefFlag(true),
-		{Name: "json", Desc: "filter JSON object", Required: true},
+		{Name: "json", Desc: `filter JSON object, e.g. {"logic":"and","conditions":[["Status","==","Todo"]]}`, Required: true},
 	},
 	Tips: []string{
-		`Example: --json '{"logic":"and","conditions":[["fldStatus","==","Todo"]]}'`,
 		"Agent hint: use the lark-base skill's view-set-filter guide for usage and limits.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/view_set_group.go

@@ -20,11 +20,13 @@ var BaseViewSetGroup = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		viewRefFlag(true),
-		{Name: "json", Desc: "group JSON object", Required: true},
+		{Name: "json", Desc: `group JSON object with group_config array, e.g. {"group_config":[{"field":"Status","desc":false}]}; use {"group_config":[]} to clear`, Required: true},
 	},
 	Tips: []string{
-		`Example: --json '{"group_config":[{"field":"fldStatus","desc":false}]}'`,
-		"Agent hint: use the lark-base skill's view-set-group guide for usage and limits.",
+		"Supported view types: grid, kanban, gantt.",
+		"Use a JSON object, not a bare array; grouping fields must be supported by the current view.",
+		"group_config supports max 3 group items.",
+		"Use +view-get-group first when modifying an existing grouping configuration.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONObject(runtime)

shortcuts/base/view_set_sort.go

@@ -20,11 +20,13 @@ var BaseViewSetSort = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		viewRefFlag(true),
-		{Name: "json", Desc: "sort_config JSON object", Required: true},
+		{Name: "json", Desc: `sort_config JSON object, e.g. {"sort_config":[{"field":"Priority","desc":true}]}; use {"sort_config":[]} to clear; max 10 items`, Required: true},
 	},
 	Tips: []string{
-		`Example: --json '{"sort_config":[{"field":"fldPriority","desc":true}]}'`,
-		"Agent hint: use the lark-base skill's view-set-sort guide for usage and limits.",
+		"Supported view types: grid, kanban, gallery, gantt.",
+		"Use a JSON object, not a bare array; sorting fields must be supported by the current view.",
+		"sort_config supports max 10 sort items.",
+		"Use +view-get-sort first when modifying an existing sort configuration.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONObject(runtime)

shortcuts/base/view_set_timebar.go

@@ -20,11 +20,12 @@ var BaseViewSetTimebar = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		viewRefFlag(true),
-		{Name: "json", Desc: "timebar JSON object", Required: true},
+		{Name: "json", Desc: `timebar JSON object with start_time, end_time, title, e.g. {"start_time":"Start Date","end_time":"End Date","title":"Name"}`, Required: true},
 	},
 	Tips: []string{
-		`Example: --json '{"start_time":"fldStart","end_time":"fldEnd","title":"fldTitle"}'`,
-		"Agent hint: use the lark-base skill's view-set-timebar guide for usage and limits.",
+		"Supported view types: calendar, gantt.",
+		"start_time, end_time, and title are required; use date/time fields for start_time and end_time.",
+		"Use +view-get-timebar first when modifying an existing timebar configuration.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONObject(runtime)

shortcuts/base/view_set_visible_fields.go

@@ -20,11 +20,12 @@ var BaseViewSetVisibleFields = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		viewRefFlag(true),
-		{Name: "json", Desc: `visible fields JSON object with "visible_fields"`, Required: true},
+		{Name: "json", Desc: `visible fields JSON object, e.g. {"visible_fields":["Name","Status"]}`, Required: true},
 	},
 	Tips: []string{
-		`Example: --json '{"visible_fields":["fldXXX"]}'`,
-		"Agent hint: use the lark-base skill's view-set-visible-fields guide for usage and limits.",
+		"Supported view types: grid, kanban, gallery, calendar, gantt.",
+		"Use a JSON object, not a bare array; primary field may be forced to the first position by the API.",
+		"visible_fields controls both visibility and order; include every field that should remain visible.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONObject(runtime)

shortcuts/base/workflow_create.go

@@ -19,7 +19,15 @@ var BaseWorkflowCreate = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
-		{Name: "json", Desc: `workflow body JSON, e.g. {"title":"My Workflow","steps":[...]}`, Required: true},
+		{Name: "json", Desc: "workflow body JSON; read lark-base-workflow-guide.md and lark-base-workflow-schema.md before constructing steps", Required: true},
+	},
+	Tips: []string{
+		"lark-cli base +workflow-create --base-token <base_token> --json @workflow.json",
+		"client_token is required and should be unique per create request.",
+		"New workflows are created disabled; call +workflow-enable after creation when the user wants it active.",
+		"Before constructing steps, use +table-list and +field-list to confirm real table and field names.",
+		"Step ids must be unique, and every next/children link must reference an existing step id.",
+		"Use lark-base-workflow-guide.md as the entry guide and lark-base-workflow-schema.md as the steps JSON SSOT; do not invent steps[].type/data/next/children from natural language.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

shortcuts/base/workflow_disable.go

@@ -21,6 +21,10 @@ var BaseWorkflowDisable = common.Shortcut{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "workflow-id", Desc: "workflow ID (wkf... prefix)", Required: true},
 	},
+	Tips: []string{
+		"workflow-id must start with wkf; do not pass a tbl table ID from the same URL.",
+		"Disable only changes workflow state; it does not delete the workflow or its steps.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")

shortcuts/base/workflow_enable.go

@@ -21,6 +21,11 @@ var BaseWorkflowEnable = common.Shortcut{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "workflow-id", Desc: "workflow ID (wkf... prefix)", Required: true},
 	},
+	Tips: []string{
+		"workflow-id must start with wkf; do not pass a tbl table ID from the same URL.",
+		"Enable only changes workflow state; it does not modify steps.",
+		"New workflows are created disabled; enable after creation only when the user wants it active.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")

shortcuts/base/workflow_get.go

@@ -20,7 +20,13 @@ var BaseWorkflowGet = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "workflow-id", Desc: "workflow ID (wkf... prefix)", Required: true},
-		{Name: "user-id-type", Desc: "user ID type for creator/updater fields", Enum: []string{"open_id", "union_id", "user_id"}},
+		{Name: "user-id-type", Desc: "user ID type for creator/updater fields, default open_id", Enum: []string{"open_id", "union_id", "user_id"}},
+	},
+	Tips: []string{
+		"workflow-id must start with wkf; use +workflow-list if the ID is unknown.",
+		"steps may be an empty array; that is valid for an unconfigured workflow.",
+		"Use +workflow-get before +workflow-update, then edit the returned definition and keep fields you do not intend to change.",
+		"Read lark-base-workflow-schema.md when interpreting or reusing returned steps.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

shortcuts/base/workflow_list.go

@@ -20,7 +20,11 @@ var BaseWorkflowList = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "status", Desc: "filter by status", Enum: []string{"enabled", "disabled"}},
-		{Name: "page-size", Type: "int", Default: "100", Desc: "page size per request (max 100)"},
+		{Name: "page-size", Type: "int", Default: "100", Desc: "page size per request, max 100"},
+	},
+	Tips: []string{
+		"Returns workflow_id values with wkf prefix; pass those IDs to +workflow-get/enable/disable/update.",
+		"This shortcut auto-paginates and returns all matched workflows.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

shortcuts/base/workflow_update.go

@@ -20,7 +20,16 @@ var BaseWorkflowUpdate = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "workflow-id", Desc: "workflow ID (wkf... prefix)", Required: true},
-		{Name: "json", Desc: `workflow body JSON, e.g. {"title":"New Title","steps":[...]}`, Required: true},
+		{Name: "json", Desc: "workflow body JSON; read lark-base-workflow-guide.md and lark-base-workflow-schema.md before replacing steps", Required: true},
+	},
+	Tips: []string{
+		"lark-cli base +workflow-update --base-token <base_token> --workflow-id <workflow_id> --json @workflow.json",
+		"PUT uses full replacement semantics; omitting steps clears the existing workflow steps.",
+		"Use +workflow-get first, then edit the returned definition and keep title/status/steps fields you do not intend to change.",
+		"workflow-id must start with wkf; do not pass a tbl table ID.",
+		"Step ids must be unique, and every next/children link must reference an existing step id.",
+		"Updating does not enable or disable a workflow; call +workflow-enable or +workflow-disable separately.",
+		"Use lark-base-workflow-guide.md as the entry guide and lark-base-workflow-schema.md as the steps JSON SSOT; do not invent steps[].type/data/next/children from natural language.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {

shortcuts/common/runner.go

@@ -860,9 +860,7 @@ func newRuntimeContext(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut, conf
 	}
 	rctx.larkSDK = sdk
 
-	if s.HasFormat {
-		rctx.Format = rctx.Str("format")
-	}
+	rctx.Format = rctx.Str("format")
 	rctx.JqExpr, _ = cmd.Flags().GetString("jq")
 	return rctx, nil
 }
@@ -1026,17 +1024,15 @@ func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f
 	}
 
 	cmd.Flags().Bool("dry-run", false, "print request without executing")
-	if s.HasFormat {
+	if cmd.Flags().Lookup("format") == nil {
 		cmd.Flags().String("format", "json", "output format: json (default) | pretty | table | ndjson | csv")
+		cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+			return []string{"json", "pretty", "table", "ndjson", "csv"}, cobra.ShellCompDirectiveNoFileComp
+		})
 	}
 	if s.Risk == "high-risk-write" {
 		cmd.Flags().Bool("yes", false, "confirm high-risk operation")
 	}
 	cmd.Flags().StringP("jq", "q", "", "jq expression to filter JSON output")
 	cmdutil.AddShortcutIdentityFlag(ctx, cmd, f, s.AuthTypes)
-	if s.HasFormat {
-		cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
-			return []string{"json", "pretty", "table", "ndjson", "csv"}, cobra.ShellCompDirectiveNoFileComp
-		})
-	}
 }

shortcuts/common/runner_format_universal_test.go

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+// TestShortcutMount_FormatFlagAlwaysRegistered verifies that --format is
+// injected for every shortcut regardless of the HasFormat field value.
+func TestShortcutMount_FormatFlagAlwaysRegistered(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	parent := &cobra.Command{Use: "root"}
+	shortcut := Shortcut{
+		Service:     "im",
+		Command:     "+message-send",
+		Description: "send message",
+		HasFormat:   false, // explicitly false — format must still be registered
+		Execute:     func(context.Context, *RuntimeContext) error { return nil },
+	}
+	shortcut.Mount(parent, f)
+
+	cmd, _, err := parent.Find([]string{"+message-send"})
+	if err != nil {
+		t.Fatalf("Find() error = %v", err)
+	}
+	flag := cmd.Flags().Lookup("format")
+	if flag == nil {
+		t.Fatal("--format flag not registered; expected it to be injected even when HasFormat is false")
+	}
+	if flag.DefValue != "json" {
+		t.Errorf("--format default = %q, want %q", flag.DefValue, "json")
+	}
+}

shortcuts/common/types.go

@@ -49,7 +49,7 @@ type Shortcut struct {
 	// Declarative fields (new framework).
 	AuthTypes []string // supported identities: "user", "bot" (default: ["user"])
 	Flags     []Flag   // flag definitions; --dry-run is auto-injected
-	HasFormat bool     // auto-inject --format flag (json|pretty|table|ndjson|csv)
+	HasFormat bool     // Deprecated: --format is now always injected; this field has no effect.
 	Tips      []string // optional tips shown in --help output
 	Hidden    bool     // hide from --help / tab completion (still executable); use when deprecating a command in favor of a replacement
 

shortcuts/im/convert_lib/card.go

@@ -50,11 +50,12 @@ var cardChartTypeNames = map[string]string{
 type interactiveConverter struct{}
 
 func (interactiveConverter) Convert(ctx *ConvertContext) string {
-	return convertCard(ctx.RawContent)
+	return convertCard(ctx.RawContent, ctx.Mentions)
 }
 
 // convertCard converts a raw interactive/card message content JSON to human-readable string.
-func convertCard(raw string) string {
+// mentions is the raw mentions array from the API response; pass nil when not available.
+func convertCard(raw string, mentions []interface{}) string {
 	var parsed cardObj
 	if err := json.Unmarshal([]byte(raw), &parsed); err != nil {
 		return "[interactive card]"
@@ -63,11 +64,19 @@ func convertCard(raw string) string {
 	// raw_card_content format: outer JSON has "json_card" string field
 	if jsonCard, ok := parsed["json_card"].(string); ok {
 		c := &cardConverter{mode: cardModeConcise}
-		if att, ok := parsed["json_attachment"].(string); ok && att != "" {
-			var attObj cardObj
-			if json.Unmarshal([]byte(att), &attObj) == nil {
-				c.attachment = attObj
+		switch att := parsed["json_attachment"].(type) {
+		case string:
+			if att != "" {
+				var attObj cardObj
+				if json.Unmarshal([]byte(att), &attObj) == nil {
+					c.attachment = attObj
+				}
 			}
+		case cardObj:
+			c.attachment = att
+		}
+		if len(mentions) > 0 {
+			c.mentionsByKey = buildMentionsByKey(mentions)
 		}
 		schema := 0
 		if s, ok := parsed["card_schema"].(float64); ok {
@@ -84,6 +93,22 @@ func convertCard(raw string) string {
 	return convertLegacyCard(parsed)
 }
 
+// buildMentionsByKey indexes the mentions array by key for O(1) lookup in convertAt.
+func buildMentionsByKey(mentions []interface{}) map[string]map[string]interface{} {
+	m := make(map[string]map[string]interface{}, len(mentions))
+	for _, raw := range mentions {
+		item, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		key, _ := item["key"].(string)
+		if key != "" {
+			m[key] = item
+		}
+	}
+	return m
+}
+
 // ── Legacy converter ──────────────────────────────────────────────────────────
 
 func convertLegacyCard(parsed cardObj) string {
@@ -158,8 +183,9 @@ func legacyExtractTexts(elements []interface{}, out *[]string) {
 // ── CardConverter ─────────────────────────────────────────────────────────────
 
 type cardConverter struct {
-	mode       cardMode
-	attachment cardObj
+	mode          cardMode
+	attachment    cardObj
+	mentionsByKey map[string]map[string]interface{}
 }
 
 func (c *cardConverter) convert(jsonCard string, hintSchema int) string {
@@ -1403,26 +1429,52 @@ func (c *cardConverter) convertAt(prop cardObj) string {
 	}
 	userName := ""
 	actualUserID := ""
+	fromMentions := false
 	if c.attachment != nil {
 		if atUsers, ok := c.attachment["at_users"].(cardObj); ok {
 			if userInfo, ok := atUsers[userID].(cardObj); ok {
 				userName, _ = userInfo["content"].(string)
 				actualUserID, _ = userInfo["user_id"].(string)
+				// When the backend populates mention_key (raw_card_content path), use
+				// mentions[] for the canonical name and the reading-app open_id, which is
+				// more accurate than the origKey-stored user_id in at_users.
+				if mentionKey, _ := userInfo["mention_key"].(string); mentionKey != "" {
+					if mention, ok := c.mentionsByKey[mentionKey]; ok {
+						if name, _ := mention["name"].(string); name != "" {
+							userName = name
+						}
+						if id := extractMentionOpenId(mention["id"]); id != "" {
+							actualUserID = id
+							fromMentions = true
+						}
+					}
+				}
 			}
 		}
 	}
 	if userName != "" {
 		if c.mode == cardModeDetailed {
 			if actualUserID != "" {
-				return fmt.Sprintf("@%s(user_id:%s)", userName, actualUserID)
+				label := "user_id"
+				if fromMentions {
+					label = "open_id"
+				}
+				return fmt.Sprintf("@%s(%s:%s)", userName, label, actualUserID)
 			}
 			return fmt.Sprintf("@%s(open_id:%s)", userName, userID)
 		}
-		return "@" + userName
+		if fromMentions && actualUserID != "" {
+			return fmt.Sprintf("@%s(%s)", userName, actualUserID)
+		}
+		return fmt.Sprintf("@%s(%s)", userName, userID)
 	}
 	if c.mode == cardModeDetailed {
 		if actualUserID != "" {
-			return fmt.Sprintf("@user(user_id:%s)", actualUserID)
+			label := "user_id"
+			if fromMentions {
+				label = "open_id"
+			}
+			return fmt.Sprintf("@user(%s:%s)", label, actualUserID)
 		}
 		return fmt.Sprintf("@user(open_id:%s)", userID)
 	}

shortcuts/im/convert_lib/card_test.go

@@ -27,14 +27,14 @@ func newTestCardConverter(mode cardMode) *cardConverter {
 
 func TestConvertCard(t *testing.T) {
 	rawCard := `{"json_card":"{\"schema\":1,\"header\":{\"title\":{\"content\":\"Card Title\"}},\"body\":{\"elements\":[{\"tag\":\"text\",\"property\":{\"content\":\"hello\"}},{\"tag\":\"button\",\"property\":{\"text\":{\"content\":\"Open\"},\"actions\":[{\"type\":\"open_url\",\"action\":{\"url\":\"https://example.com\"}}]}}]}}","json_attachment":"{\"persons\":{\"ou_1\":{\"content\":\"Alice\"}}}"}`
-	got := convertCard(rawCard)
+	got := convertCard(rawCard, nil)
 	want := "<card title=\"Card Title\">\nhello\n[Open](https://example.com)\n</card>"
 	if got != want {
 		t.Fatalf("convertCard(json_card) = %q, want %q", got, want)
 	}
 
 	legacy := `{"header":{"title":{"content":"Legacy Card"}},"elements":[{"tag":"div","text":{"content":"legacy body"}}]}`
-	gotLegacy := convertCard(legacy)
+	gotLegacy := convertCard(legacy, nil)
 	wantLegacy := "**Legacy Card**\nlegacy body"
 	if gotLegacy != wantLegacy {
 		t.Fatalf("convertCard(legacy) = %q, want %q", gotLegacy, wantLegacy)
@@ -243,6 +243,75 @@ func TestCardConverterMethods(t *testing.T) {
 	}
 }
 
+func TestConvertAtWithMentions(t *testing.T) {
+	mentions := []interface{}{
+		map[string]interface{}{
+			"key":  "@_user_1",
+			"id":   "ou_6b64bef911a5a3ea763df8ffd9258f59",
+			"name": "燕忠毅",
+		},
+	}
+	attachment := cardObj{
+		"at_users": cardObj{
+			"cde8a6c8": cardObj{
+				"user_id":     "754700000001",
+				"content":     "燕忠毅",
+				"mention_key": "@_user_1",
+			},
+		},
+	}
+
+	// Concise mode: should show @Name(open_id) when mention resolves.
+	concise := &cardConverter{
+		mode:          cardModeConcise,
+		attachment:    attachment,
+		mentionsByKey: buildMentionsByKey(mentions),
+	}
+	if got := concise.convertAt(cardObj{"userID": "cde8a6c8"}); got != "@燕忠毅(ou_6b64bef911a5a3ea763df8ffd9258f59)" {
+		t.Fatalf("convertAt(concise with mentions) = %q", got)
+	}
+
+	// Detailed mode: label should be open_id when resolved from mentions.
+	detailed := &cardConverter{
+		mode:          cardModeDetailed,
+		attachment:    attachment,
+		mentionsByKey: buildMentionsByKey(mentions),
+	}
+	if got := detailed.convertAt(cardObj{"userID": "cde8a6c8"}); got != "@燕忠毅(open_id:ou_6b64bef911a5a3ea763df8ffd9258f59)" {
+		t.Fatalf("convertAt(detailed with mentions) = %q", got)
+	}
+
+	// No mention_key: falls back to at_users.user_id with user_id label (existing behavior).
+	noMentionKey := &cardConverter{
+		mode: cardModeDetailed,
+		attachment: cardObj{
+			"at_users": cardObj{
+				"ou_at": cardObj{"content": "Bob", "user_id": "u_bob"},
+			},
+		},
+	}
+	if got := noMentionKey.convertAt(cardObj{"userID": "ou_at"}); got != "@Bob(user_id:u_bob)" {
+		t.Fatalf("convertAt(fallback no mention_key) = %q", got)
+	}
+
+	// mention_key present but mentionsByKey nil: still falls back gracefully.
+	nilMentions := &cardConverter{
+		mode: cardModeDetailed,
+		attachment: cardObj{
+			"at_users": cardObj{
+				"cde8a6c8": cardObj{
+					"user_id":     "754700000001",
+					"content":     "燕忠毅",
+					"mention_key": "@_user_1",
+				},
+			},
+		},
+	}
+	if got := nilMentions.convertAt(cardObj{"userID": "cde8a6c8"}); got != "@燕忠毅(user_id:754700000001)" {
+		t.Fatalf("convertAt(fallback nil mentionsByKey) = %q", got)
+	}
+}
+
 func TestCardConverterExtractTextHelpers(t *testing.T) {
 	c := newTestCardConverter(cardModeDetailed)