Merge remote-tracking branch 'origin/main' into feat/lark-sheets-refactor

# Conflicts:
#	internal/cmdutil/factory_default.go
#	internal/transport/warn_test.go
#	internal/util/proxy.go

cmd/config/init_interactive.go

@@ -16,7 +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/util"
+	"github.com/larksuite/cli/internal/transport"
 )
 
 // configInitResult holds the result of the interactive config init flow.
@@ -179,7 +179,7 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 	// Step 1: Request app registration (begin)
 	// Use the shared proxy-plugin-aware transport so registration traffic is not
 	// a bypass of proxy plugin mode.
-	httpClient := util.NewHTTPClient(0)
+	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,8 +19,8 @@ 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"
-	"github.com/larksuite/cli/internal/util"
 )
 
 // DoctorOptions holds inputs for the doctor command.
@@ -155,7 +155,7 @@ func networkChecks(ctx context.Context, opts *DoctorOptions, ep core.Endpoints)
 
 	// Use the shared proxy-plugin-aware transport so connectivity checks reflect
 	// the real egress path (and are blocked when proxy plugin fails closed).
-	httpClient := util.NewHTTPClient(0)
+	httpClient := transport.NewHTTPClient(0)
 	mcpURL := ep.MCP + "/mcp"
 
 	type probeResult struct {

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, f.IOStreams.IsTerminal)
+		transport.WarnIfProxied(f.IOStreams.ErrOut, f.IOStreams.IsTerminal)
 
-		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, f.IOStreams.IsTerminal)
+		transport.WarnIfProxied(f.IOStreams.ErrOut, f.IOStreams.IsTerminal)
 		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/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/registry/remote.go

@@ -17,7 +17,7 @@ import (
 
 	"github.com/larksuite/cli/internal/build"
 	"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"
 )
@@ -181,7 +181,7 @@ func saveCachedMerged(data []byte, meta CacheMeta) error {
 func fetchRemoteMerged(localVersion string) (data []byte, reg *MergedRegistry, err error) {
 	// Route through the shared proxy-plugin-aware transport so remote API
 	// definition fetches honor proxy plugin mode instead of bypassing it.
-	client := util.NewHTTPClient(fetchTimeout)
+	client := transport.NewHTTPClient(fetchTimeout)
 	req, err := http.NewRequest("GET", remoteMetaURL(localVersion), nil)
 	if err != nil {
 		return nil, nil, err

internal/transport/config.go

@@ -1,14 +1,15 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-// Package proxyplugin implements the ~/.lark-cli/proxy_config.json based security proxy plugin mode.
+// 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.
 //
-// It supports:
-// - forcing all outbound HTTP(S) requests through a fixed HTTP proxy
-// - trusting an additional root CA PEM bundle for MITM/inspection proxies
-//
-// Environment variables override matching values from proxy_config.json.
-package proxyplugin
+// 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"
@@ -222,21 +223,6 @@ func (c *Config) proxyURL() (*url.URL, error) {
 	return u, nil
 }
 
-// redactProxyURL masks userinfo (username:password) in a proxy URL.
-// Handles both scheme-prefixed ("http://user:pass@host") and bare formats.
-func redactProxyURL(raw string) string {
-	u, err := url.Parse(raw)
-	if err == nil && u.User != nil {
-		u.User = url.User("***")
-		return u.String()
-	}
-	// Fallback: handle "user:pass@proxy:8080"
-	if at := strings.LastIndex(raw, "@"); at > 0 {
-		return "***@" + raw[at+1:]
-	}
-	return raw
-}
-
 // 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) {

internal/transport/config_test.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"net/http"

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

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"crypto/tls"

internal/transport/tls_ca_test.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"crypto/rand"

internal/transport/transport.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"fmt"
@@ -16,7 +16,7 @@ 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 SharedTransport call.
+// http.DefaultTransport on every pluginTransport call.
 var cachedBlockedTransport = sync.OnceValue(buildBlockedTransport)
 
 func buildBlockedTransport() http.RoundTripper {
@@ -28,7 +28,7 @@ func buildProxyPluginTransport() http.RoundTripper {
 	if !ok {
 		// Cannot clone the stdlib transport. Fail closed with a concrete
 		// *http.Transport (not a bare RoundTripper) so downcasting callers such
-		// as util.FallbackTransport cannot silently degrade this into a
+		// 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))
 	}
@@ -51,9 +51,9 @@ func buildProxyPluginTransport() http.RoundTripper {
 	return t
 }
 
-// SharedTransport returns the proxy plugin transport when proxy plugin mode is
+// 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 SharedTransport() (http.RoundTripper, bool) {
+func pluginTransport() (http.RoundTripper, bool) {
 	cfg, err := Load()
 	if err != nil {
 		return cachedBlockedTransport(), true
@@ -68,7 +68,7 @@ func SharedTransport() (http.RoundTripper, bool) {
 // 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 util.FallbackTransport cannot silently degrade a fail-closed
+// 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 {

internal/transport/transport_test.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package proxyplugin
+package transport
 
 import (
 	"io"
@@ -20,21 +20,21 @@ func resetProxyPluginState() {
 	cachedBlockedTransport = sync.OnceValue(buildBlockedTransport)
 }
 
-func TestSharedTransport_NotConfigured(t *testing.T) {
+func TestPluginTransport_NotConfigured(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
 
-	tr, ok := SharedTransport()
+	tr, ok := pluginTransport()
 	if ok {
-		t.Fatalf("SharedTransport() ok = true, want false")
+		t.Fatalf("pluginTransport() ok = true, want false")
 	}
 	if tr != nil {
-		t.Fatalf("SharedTransport() transport = %T, want nil", tr)
+		t.Fatalf("pluginTransport() transport = %T, want nil", tr)
 	}
 }
 
-func TestSharedTransport_EnabledReturnsFixedProxy(t *testing.T) {
+func TestPluginTransport_EnabledReturnsFixedProxy(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
@@ -46,13 +46,13 @@ func TestSharedTransport_EnabledReturnsFixedProxy(t *testing.T) {
   "LARKSUITE_CLI_CA_PATH": ""
 }`), 0600)
 
-	rt, ok := SharedTransport()
+	rt, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
 	tr, ok := rt.(*http.Transport)
 	if !ok {
-		t.Fatalf("SharedTransport() = %T, want *http.Transport", rt)
+		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 {
@@ -63,7 +63,7 @@ func TestSharedTransport_EnabledReturnsFixedProxy(t *testing.T) {
 	}
 }
 
-func TestSharedTransport_InvalidConfigWithNonTransportDefaultFailsClosed(t *testing.T) {
+func TestPluginTransport_InvalidConfigWithNonTransportDefaultFailsClosed(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
@@ -72,12 +72,12 @@ func TestSharedTransport_InvalidConfigWithNonTransportDefaultFailsClosed(t *test
 
 	writeFile(t, Path(), []byte(`{`), 0600)
 
-	rt, ok := SharedTransport()
+	rt, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
 	if rt == http.DefaultTransport {
-		t.Fatalf("SharedTransport() returned http.DefaultTransport, want fail-closed transport")
+		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 {
@@ -88,23 +88,23 @@ func TestSharedTransport_InvalidConfigWithNonTransportDefaultFailsClosed(t *test
 	}
 }
 
-func TestSharedTransport_InvalidConfigReturnsCachedInstance(t *testing.T) {
+func TestPluginTransport_InvalidConfigReturnsCachedInstance(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
 
 	writeFile(t, Path(), []byte(`{`), 0600)
 
-	a, ok := SharedTransport()
+	a, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
-	b, ok := SharedTransport()
+	b, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
 	if a != b {
-		t.Fatalf("SharedTransport() returned different instances on repeated calls; blocked transport must be cached")
+		t.Fatalf("pluginTransport() returned different instances on repeated calls; blocked transport must be cached")
 	}
 }
 
@@ -148,13 +148,13 @@ func TestBuildProxyPluginTransport_NonTransportDefaultFailsClosed(t *testing.T)
 	}
 }
 
-// TestSharedTransport_InvalidConfigBlockerIsConcreteTransport guards the
-// fail-closed invariant that util.FallbackTransport relies on: even when
+// 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, util.FallbackTransport would downcast-fail and
+// were a bare RoundTripper, Fallback would downcast-fail and
 // silently degrade it into a direct-egress transport.
-func TestSharedTransport_InvalidConfigBlockerIsConcreteTransport(t *testing.T) {
+func TestPluginTransport_InvalidConfigBlockerIsConcreteTransport(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
 	resetProxyPluginState()
@@ -163,12 +163,12 @@ func TestSharedTransport_InvalidConfigBlockerIsConcreteTransport(t *testing.T) {
 
 	writeFile(t, Path(), []byte(`{`), 0600)
 
-	rt, ok := SharedTransport()
+	rt, ok := pluginTransport()
 	if !ok {
-		t.Fatal("SharedTransport() ok = false, want true")
+		t.Fatal("pluginTransport() ok = false, want true")
 	}
 	if _, isTransport := rt.(*http.Transport); !isTransport {
-		t.Fatalf("SharedTransport() blocked transport = %T, want *http.Transport so FallbackTransport cannot degrade it to direct egress", rt)
+		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"}})

internal/transport/warn.go

@@ -1,20 +1,17 @@
 // 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"
-	"time"
 
 	"github.com/larksuite/cli/internal/envvars"
-	"github.com/larksuite/cli/internal/proxyplugin"
 )
 
 // Proxy environment constants control shared transport proxy behavior.
@@ -47,9 +44,9 @@ 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 proxyplugin.Load() sync.Once cache.
+// mode without the process-global Load() sync.Once cache.
 var proxyPluginStatus = func() (addr, caPath string, enabled bool) {
-	cfg, err := proxyplugin.Load()
+	cfg, err := Load()
 	if err != nil || !cfg.Enabled() {
 		return "", "", false
 	}
@@ -90,13 +87,12 @@ func WarnIfProxied(w io.Writer, interactive bool) {
 	}
 	proxyWarningOnce.Do(func() {
 		// Proxy plugin mode overrides env proxies and LARK_CLI_NO_PROXY (see
-		// SharedTransport), 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.
+		// 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, proxyplugin.Path())
+				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
@@ -117,75 +113,3 @@ func WarnIfProxied(w io.Writer, interactive bool) {
 			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 {
-	// proxy plugin mode overrides all other proxy behavior (env proxies and
-	// LARK_CLI_NO_PROXY), per operator intent.
-	if t, ok := proxyplugin.SharedTransport(); ok {
-		return t
-	}
-	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.
-//
-// Fail-closed invariant: proxyplugin always expresses its blocked/fail-closed
-// transport as a concrete *http.Transport (see proxyplugin.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 FallbackTransport() *http.Transport {
-	if t, ok := SharedTransport().(*http.Transport); ok {
-		return t
-	}
-	return noProxyTransport()
-}
-
-// NewHTTPClient returns an *http.Client whose Transport is the shared,
-// proxy-plugin-aware base (see SharedTransport). 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: SharedTransport(),
-		Timeout:   timeout,
-	}
-}

internal/transport/warn_test.go

@@ -1,44 +1,17 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-package util
+package transport
 
 import (
 	"bytes"
-	"net/http"
-	"os"
 	"strings"
 	"sync"
 	"testing"
-	"time"
 
 	"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()
-	// Ensure developer machine env doesn't accidentally enable proxy plugin mode
-	// and change expectations for SharedTransport().
-	unsetEnv(t, envvars.CliProxyEnable)
-	unsetEnv(t, envvars.CliProxyAddress)
-	unsetEnv(t, envvars.CliCAPath)
-}
-
 // TestDetectProxyEnv verifies proxy environment detection priority and empty-state behavior.
 func TestDetectProxyEnv(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
@@ -61,88 +34,11 @@ func TestDetectProxyEnv(t *testing.T) {
 	}
 }
 
-// TestSharedTransport_DefaultReturnsStdlibSingleton verifies the default shared transport.
-func TestSharedTransport_DefaultReturnsStdlibSingleton(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(t)
-	t.Setenv(EnvNoProxy, "")
-	tr := SharedTransport()
-	if tr != http.DefaultTransport {
-		t.Error("SharedTransport should return http.DefaultTransport when LARK_CLI_NO_PROXY is unset")
-	}
-}
-
-// TestSharedTransport_NoProxyReturnsClone verifies that disabling proxying returns a cloned transport.
-func TestSharedTransport_NoProxyReturnsClone(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(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")
-	}
-}
-
-// TestSharedTransport_NoProxyIsCachedSingleton verifies singleton caching for the no-proxy transport.
-func TestSharedTransport_NoProxyIsCachedSingleton(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(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")
-	}
-}
-
-// TestSharedTransport_EnvUnsetAfterSetFallsBackToDefault verifies fallback to the stdlib transport after unsetting EnvNoProxy.
-func TestSharedTransport_EnvUnsetAfterSetFallsBackToDefault(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(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)
-	}
-}
-
-// TestSharedTransport_NoProxyOverridesSystemProxy verifies that EnvNoProxy disables system proxies.
-func TestSharedTransport_NoProxyOverridesSystemProxy(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(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")
-	}
-}
-
 // 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)
-	// Reset the once guard for this test
+	resetProxyPluginState()
 	proxyWarningOnce = sync.Once{}
 
 	t.Setenv("HTTPS_PROXY", "http://corp-proxy:3128")
@@ -166,6 +62,7 @@ func TestWarnIfProxied_WithProxy(t *testing.T) {
 func TestWarnIfProxied_WithoutProxy(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
+	resetProxyPluginState()
 	proxyWarningOnce = sync.Once{}
 
 	for _, k := range proxyEnvKeys {
@@ -197,10 +94,11 @@ func TestWarnIfProxied_SilentWhenNonInteractive(t *testing.T) {
 	}
 }
 
-// TestWarnIfProxied_SilentWhenDisabled verifies that EnvNoProxy suppresses warnings.
+// 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")
@@ -218,6 +116,7 @@ func TestWarnIfProxied_SilentWhenDisabled(t *testing.T) {
 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")
@@ -274,7 +173,7 @@ func TestWarnIfProxied_ProxyPluginEnabled(t *testing.T) {
 }
 
 // TestWarnIfProxied_ProxyPluginCustomCAWarns verifies that when a custom CA is
-// trusted, the warning surfaces the TLS-interception capability (V3).
+// trusted, the warning surfaces the TLS-interception capability.
 func TestWarnIfProxied_ProxyPluginCustomCAWarns(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	unsetProxyPluginEnv(t)
@@ -301,25 +200,6 @@ func TestWarnIfProxied_ProxyPluginCustomCAWarns(t *testing.T) {
 	}
 }
 
-// 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)
-	t.Setenv(EnvNoProxy, "")
-
-	c := NewHTTPClient(7 * time.Second)
-	if c.Transport == nil {
-		t.Fatal("NewHTTPClient transport is nil; want shared transport")
-	}
-	if c.Transport != SharedTransport() {
-		t.Errorf("NewHTTPClient transport = %v, want SharedTransport()", c.Transport)
-	}
-	if c.Timeout != 7*time.Second {
-		t.Errorf("NewHTTPClient timeout = %v, want 7s", c.Timeout)
-	}
-}
-
 // TestWarnIfProxied_ProxyPluginEnabledRedactsCredentials verifies the plugin
 // warning never leaks credentials embedded in the configured proxy address.
 func TestWarnIfProxied_ProxyPluginEnabledRedactsCredentials(t *testing.T) {
@@ -348,8 +228,6 @@ func TestWarnIfProxied_ProxyPluginEnabledRedactsCredentials(t *testing.T) {
 
 // TestRedactProxyURL verifies redaction of proxy credentials across supported formats.
 func TestRedactProxyURL(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	unsetProxyPluginEnv(t)
 	tests := []struct {
 		input string
 		want  string
@@ -376,6 +254,7 @@ func TestRedactProxyURL(t *testing.T) {
 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")

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(),
 	}
 }
 

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_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") {

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{})
@@ -251,20 +270,19 @@ func TestBaseRecordReadHelpGuidesAgents(t *testing.T) {
 			name:     "record search",
 			shortcut: BaseRecordSearch,
 			wantHelp: []string{
-				"requires keyword/search_fields",
-				"optional select_fields/view_id/offset/limit",
+				`record search JSON object, e.g. {"keyword":"Alice","search_fields":["Name"],"select_fields":["Name","Status"],"limit":50}`,
+				"for keyword search only",
 				"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>"]`,
+				"Happy path fields: keyword (string), search_fields",
 				"search_fields length 1-20",
 				"limit range 1-200 defaults to 10",
 				"view_id scopes search to records in that view",
 				"Default output is markdown",
 				"only for keyword search",
 				"lark-base record read SOP",
+				"inventing search JSON",
 			},
 		},
 		{
@@ -311,6 +329,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, e.g. {"keyword":"Alice","search_fields":["Name"],"select_fields":["Name","Status"],"limit":50}`,
+			},
+		},
+		{
+			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 +741,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",

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_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

shortcuts/base/record_search.go

@@ -20,17 +20,15 @@ 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, e.g. {"keyword":"Alice","search_fields":["Name"],"select_fields":["Name","Status"],"limit":50}; for keyword search only`, Required: true},
 		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.",
 		"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.",
+		"Use +record-search only for keyword search; for structured conditions, sorting, Top/Bottom N, or global conclusions, follow the lark-base record read SOP instead of inventing search JSON.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if err := validateRecordReadFormat(runtime); err != nil {

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

@@ -917,9 +917,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
 }
@@ -1105,8 +1103,11 @@ 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")
@@ -1117,9 +1118,4 @@ func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f
 	}
 	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
 

skill-template/domains/base.md

@@ -8,7 +8,7 @@
    - `lark-cli base records create` ❌
 2. **优先使用 Shortcut** — 有 Shortcut 的操作不要手拼原生 API
 3. **写记录前** — 先调用 `table.fields list` 获取字段 `type/ui_type`，再读 [lark-base-cell-value.md](../../skills/lark-base/references/lark-base-cell-value.md)；该文档是 CellValue 的 source of truth
-4. **写字段前** — 先读 [lark-base-shortcut-field-properties.md](../../skills/lark-base/references/lark-base-shortcut-field-properties.md) 确认字段类型 JSON 结构
+4. **写字段前** — 先读 [lark-base-field-json.md](../../skills/lark-base/references/lark-base-field-json.md) 确认字段类型 JSON 结构
 5. **筛选查询前** — 先读 [lark-base-view-set-filter.md](../../skills/lark-base/references/lark-base-view-set-filter.md)，当前 `base/v3` 通过 `view.filter update + table.records list` 组合完成筛选读取
 6. **批量上限 200 条/次** — 同一表建议串行写入，并在批次间延迟 0.5–1 秒
 7. **改名和删除按明确意图执行** — 视图重命名这类低风险改名操作，目标和新名称明确时可直接执行；删除记录 / 字段 / 表时，只要用户已经明确要求删除且目标明确，也可直接执行，不需要再补一次确认
@@ -113,7 +113,7 @@ lark-cli wiki spaces.get_node --params '{"token":"Pgrrwvr***********UnRb"}'
 
 ## 参考文档
 
-- [lark-base-shortcut-field-properties.md](../../skills/lark-base/references/lark-base-shortcut-field-properties.md) — 字段类型 JSON 配置
+- [lark-base-field-json.md](../../skills/lark-base/references/lark-base-field-json.md) — 字段类型 JSON 配置
 - [lark-base-cell-value.md](../../skills/lark-base/references/lark-base-cell-value.md) — CellValue source of truth
 - [lark-base-view-set-filter.md](../../skills/lark-base/references/lark-base-view-set-filter.md) — 查询筛选指南（filter / operator / sort / 分页）
-- [examples.md](../../skills/lark-base/references/examples.md) — 完整操作示例（建表、筛选、更新）
+- 具体命令示例由命令 --help 内置 tips 承接；复杂 JSON 只读上方保留 reference

skills/lark-base/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-base
 version: 1.2.2
-description: "当需要用 lark-cli 操作飞书多维表格（Base）时调用：搜索 Base、建表、字段管理、记录读写、记录分享链接、视图配置、历史查询，以及角色/表单/仪表盘管理/工作流；也适用于把旧的 +table / +field / +record 写法改成当前命令写法。涉及字段设计、公式字段、查找引用、跨表计算、行级派生指标、数据分析需求时也必须使用本 skill。"
+description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限；遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入转 lark-drive，认证/授权转 lark-shared。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -10,353 +10,151 @@ metadata:
 
 # base
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。
-> **执行前必做：** 执行任何 `base` 命令前，必须先阅读对应命令的 reference 文档，再调用命令。
-> **查询类任务必做：** 涉及筛选、排序、Top/Bottom N、聚合、多表关联、查询后写入或判断全局结论时，必须先阅读 [`references/lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md)，再选择 `record / view / data-query` 路径。
-> **命名约定：** Base 业务命令仅使用 `lark-cli base +...` 形式；解析 Wiki 链接使用 `lark-cli wiki +node-get`。
-> **分流规则：** 如果用户要“把本地文件导入成 Base / 多维表格 / bitable”，第一步不是 `base`，而是 `lark-cli drive +import --type bitable`；导入完成后再回到 `lark-cli base +...` 做表内操作。
+## 何时使用
 
-## 1. 何时使用本 Skill
+使用本 skill：
 
-### 1.1 触发条件
+- 用户明确提到 Base / 多维表格 / bitable，或给出 `/base/` 链接。
+- 用户要在 Base 内建表、改表、管理字段、写记录、查记录、配视图。
+- 用户要在 Base 内做公式字段、lookup 字段、跨表计算、派生指标、筛选聚合、TopN、统计分析。
+- 用户要管理 Base 表单、仪表盘、workflow、高级权限或角色。
+- 用户要把旧 Base 聚合式命令或旧写法迁移到当前 `lark-cli base +...` shortcut。
 
-以下场景应使用本 skill：
+不要使用本 skill：
 
-- 用户明确要操作飞书多维表格 / Base。
-- 用户要建表、改表、查表、删表，或管理字段、记录、视图。
-- 用户要做公式字段、lookup 字段、派生指标、跨表计算。
-- 用户要做临时统计、聚合分析、比较排序、求最值。
-- 用户要管理 workflow、dashboard、表单、角色权限。
-- 用户给出 `/base/{token}` 链接。
-- 用户给出 `/wiki/{token}` 链接，且最终解析为 `bitable`。
-- 用户要把旧的 Base 聚合式写法改成当前原子命令写法，例如把旧 `+table / +field / +record / +view / +history / +workspace` 改写成当前命令。
+- 只是认证、初始化配置、切换身份、处理 scope 或权限授权恢复，转 `lark-shared`。
+- 把本地 Excel / CSV / `.base` 导入成 Base，转 `lark-drive +import --type bitable`。
+- 泛化数据分析、字段设计、公式讨论，但没有 Base/多维表格上下文。
 
-以下场景不应使用本 skill：
+## 使用边界
 
-- 用户只是做认证、初始化配置、切换 `--as user/bot`、处理 scope。此时先读 `../lark-shared/SKILL.md`。
-- 用户只是泛化地讨论“数据分析 / 字段设计”，但并不在 Base 场景中。不要因为提到“统计 / 公式 / lookup”就误触发。
+- Base 业务操作只使用 `lark-cli base +...` shortcut，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`。
+- 本轮 Base 不依赖 `lark-cli schema`。SKILL 只保留路由、风险和复杂 JSON/DSL；简单命令由命令自身的参数、tips 和错误恢复承接。
+- 用户要把 Excel / CSV / `.base` 导入成 Base 时，先转 `lark-cli drive +import --type bitable`，导入完成后再回到 Base 命令。
+- 用户只给 Base 名称或关键词时，先用 `lark-cli drive +search --query <keyword> --doc-types bitable` 定位资源。
+- Base 命令必须先有 `base_token` 或可解析出的 Base URL。没有 token 时：用户要新建就用 `+base-create`；用户给标题/关键词就搜 `lark-cli drive +search --query "<base title>" --doc-types bitable --only-title --as user`；仍无法定位时，反问用户具体是哪一个 Base。
+- 认证、初始化、scope、身份切换、权限不足恢复属于 `lark-shared`；Base 文档只保留会影响 Base 路径选择的权限规则。
 
-### 1.2 前置约束
+## 快速路由
 
-1. 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。
-2. Base 业务命令仅使用 `lark-cli base +...` 形式的 shortcut 命令。
-3. 如果输入是 Wiki 链接或 Wiki token，并且用户想读取/操作其中的 Base，先执行 `lark-cli wiki +node-get --node-token <wiki_url_or_token>`；当返回 `data.obj_type=bitable` 时，把 `data.obj_token` 当作 `--base-token`。不要把 URL 里的 `/wiki/{token}` 当成 Base token。（旧的 `--token` flag 仍可用，但已 deprecated，会在 stderr 打印迁移提示。）
-4. 定位到命令后，先读该命令对应的 reference，再执行命令。
-5. 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，第一步不是 `base`，而是 `lark-cli drive +import --type bitable`；导入完成后再回到 `lark-cli base +...` 做表内操作。
-6. 不要在 Base 场景改走 `lark-cli api /open-apis/bitable/v1/...`。
-7. 如果用户只给 Base 名称、关键词，或说“帮我找一个多维表格”，先通过 `lark-cli drive +search --query <keyword> --doc-types bitable` 搜索 Base / 多维表格资源；拿到 Base URL 后再使用本 skill 的 `base +...` 命令。复杂搜索再读 [`../lark-drive/references/lark-drive-search.md`](../lark-drive/references/lark-drive-search.md)：标题精确匹配、限定 owner（`--mine` / `--creator-ids`，owner 语义非"最初创建人"）/群/文件夹/时间范围、只搜标题/评论、分页/全量搜索。
+| 用户目标 | 优先命令 | 何时读 reference |
+|---|---|---|
+| 查 Base 本体 | `+base-get` | 用返回确认 Base 名称、owner、权限和可继续操作的 token |
+| 创建/复制 Base | `+base-create` / `+base-copy` | 写入后报告新 Base 标识；注意返回中的 `permission_grant` |
+| 管理表 | `+table-list/get/create/update/delete` | `+table-create --fields` 复杂时读 `lark-base-field-json.md` |
+| 列/查/删字段 | `+field-list/get/delete/search-options` | 写入前用 list/get 确认字段类型、选项、ID；删除前确认目标字段 |
+| 创建/更新字段 | `+field-create` / `+field-update` | 必读 `lark-base-field-json.md`；公式读 `formula-field-guide.md`；lookup 读 `lookup-field-guide.md`；命令细节读 `lark-base-field-create.md` / `lark-base-field-update.md` |
+| 读记录明细 | `+record-get` / `+record-list` / `+record-search` | 涉及筛选、排序、Top/Bottom N、聚合、多表关联、全局结论时读 `lark-base-data-analysis-sop.md` |
+| 写记录 | `+record-upsert` / `+record-batch-create` / `+record-batch-update` | 必读对应 record reference 和 `lark-base-cell-value.md` |
+| 附件字段 | `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` | 附件不要伪造成普通 CellValue；上传走本地文件，下载/删除按 file token 或字段定位 |
+| 删除记录 / 分享记录链接 / 历史 | `+record-delete` / `+record-share-link-create` / `+record-history-list` | 删除前确认 record；分享链接最多 100 条；历史读 `lark-base-record-history-list.md`，只查单条记录，不做整表审计 |
+| 管理视图 | `+view-*` | `+view-set-filter` 读 `lark-base-view-set-filter.md`；其余配置先 get 现状，再按返回结构更新 |
+| 一次性聚合统计 | `+data-query` | 必读 `lark-base-data-analysis-sop.md` 和入口 `lark-base-data-query-guide.md`；完整 DSL 再读 `lark-base-data-query.md` |
+| 公式字段 | `+field-create/update --json '{"type":"formula",...}'` | 必读 `formula-field-guide.md`，读后再加隐藏确认 flag `--i-have-read-guide` |
+| Lookup 字段 | `+field-create/update --json '{"type":"lookup",...}'` | 必读 `lookup-field-guide.md`，读后再加隐藏确认 flag `--i-have-read-guide` |
+| 表单提交 | `+form-submit` | 先读 `lark-base-form-detail.md` 获取题目、filter 和附件所需 `base_token`；提交 JSON 读 `lark-base-form-submit.md` |
+| 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读对应 form-questions reference |
+| 其他表单管理 | `+form-list/get/detail/create/update/delete` / `+form-questions-list/delete` | `+form-detail` 读 `lark-base-form-detail.md`；删除前确认目标表单 |
+| 仪表盘与组件 | `+dashboard-*` / `+dashboard-block-*` | 提到图表/看板/block 时先读 `lark-base-dashboard.md`；组件 `data_config` 读 `dashboard-block-data-config.md`；读取图表计算结果用 `+dashboard-block-get-data` |
+| Workflow | `+workflow-*` | 创建/更新或理解 steps 时读入口 `lark-base-workflow-guide.md` 和 steps JSON SSOT `lark-base-workflow-schema.md`；list/get/enable/disable 只处理 workflow ID 与启停状态 |
+| 高级权限与角色 | `+advperm-*` / `+role-*` | 角色操作先读入口 `lark-base-role-guide.md`；角色 create/update 或解读完整配置再读权限 JSON SSOT `role-config.md`；系统角色不可删除；关闭高级权限会影响自定义角色 |
 
-## 2. 模块与命令导航
+## Base 心智模型
 
-本章按“先选模块，再选命令”的方式组织。先判断用户目标属于哪个大模块，再进入对应子模块，按要求阅读 reference 后执行命令。
+- Base 曾用名 Bitable；返回字段、错误或旧文档里的 `bitable` 多为历史兼容，不代表应改走裸 API 或另一套命令。
+- 表、字段、视图、workflow、dashboard block 的名称和 ID 必须来自真实返回，不要凭用户口述猜。
+- 存储字段可写；系统字段、`formula`、`lookup` 只读；附件字段走专用 attachment 命令。
+- 一次性统计、筛选、TopN 优先用 `+data-query` 或临时视图；需要长期显示在表中时，才新增 `formula` / `lookup` 字段。
+- `formula` 适合常规计算、条件判断、文本/日期处理和长期派生指标；`lookup` 适合明确的跨表查找、筛选后取值或聚合引用。
+- 写入、分析、公式、lookup、workflow、dashboard 前，先读取真实结构：表、字段、视图、关联表和 dashboard block 名称都以命令返回为准。
+- 跨表场景必须读取目标表结构；link 单元格中的关联 `record_id` 只是连接键，最终回答要回查并展示用户可读字段。
 
-### 2.1 模块地图
+## 身份与权限降级
 
-| 大模块 | 处理什么问题 | 包含的小模块 / 能力 |
-|------|-------------|-------------------|
-| Base 模块 | 管理 Base 本体，或从链接进入 Base 场景 | `base-create / base-get / base-copy`，Base / Wiki 链接解析 |
-| 表与数据模块 | 管理 Base 内部结构与日常数据操作 | `table / field / record / view` |
-| 公式 / Lookup 模块 | 处理派生字段、条件判断、跨表计算、固定查找引用 | `formula / lookup` 字段创建与更新 |
-| 数据分析模块 | 做一次性筛选、分组、聚合分析 | `data-query` |
-| Workflow 模块 | 管理自动化流程 | `workflow-list / get / create / update / enable / disable` |
-| Dashboard 模块 | 管理仪表盘和图表组件 | `dashboard-* / dashboard-block-*` |
-| 表单模块 | 管理表单和表单题目 | `form-* / form-questions-*` |
-| 权限与角色模块 | 管理高级权限和自定义角色 | `advperm-* / role-*` |
+- 默认显式使用 `--as user` 操作用户资源；只有用户明确要求应用身份时，才直接用 `--as bot`。
+- user 身份报 scope/授权不足，或错误中包含 `permission_violations` / `hint`，先转 `lark-shared` 做用户授权恢复，不要直接降级 bot。
+- user 身份报资源级无访问且无授权恢复提示时，才可用 `--as bot` 重试一次；bot 仍失败就停止重试并按权限错误处理。
+- `91403` 或明确不可访问错误不要循环换身份重试。
+- `+base-create` / `+base-copy` 若用 bot 身份执行，关注返回中的 `permission_grant`，并把用户是否可打开新 Base 告知用户。
 
-### 2.2 Base 模块
+## 查询与统计规则
 
-用于管理 Base 本体，或从用户给出的链接进入后续 Base 操作。  
-模块索引：[`references/lark-base-workspace.md`](references/lark-base-workspace.md)
+涉及查询、统计或判断结论时，先阅读 `references/lark-base-data-analysis-sop.md`，并遵守：
 
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `lark-cli drive +search --query <keyword> --doc-types bitable` | 按名称、关键词查找 Base / 多维表格 / bitable | 复杂搜索再读 [`../lark-drive/references/lark-drive-search.md`](../lark-drive/references/lark-drive-search.md) | 先定位资源，再回到 `base +...` 操作表内数据 |
-| `+base-create` | 创建新的 Base | [`lark-base-base-create.md`](references/lark-base-base-create.md)、[`lark-base-workspace.md`](references/lark-base-workspace.md) | 写入操作；执行前先读 reference；`--folder-token`、`--time-zone` 都是可选项 |
-| `+base-get` | 获取 Base 信息 | [`lark-base-base-get.md`](references/lark-base-base-get.md)、[`lark-base-workspace.md`](references/lark-base-workspace.md) | 适合确认 Base 本体信息，不替代表/字段结构读取 |
-| `+base-copy` | 复制已有 Base | [`lark-base-base-copy.md`](references/lark-base-base-copy.md)、[`lark-base-workspace.md`](references/lark-base-workspace.md) | 写入操作；执行前先读 reference；复制成功后应主动返回新 Base 标识信息 |
-
-### 2.3 表与数据模块
-
-这是最常用的大模块，包含 `table / field / record / view` 四类子模块。  
-补充示例：[`references/examples.md`](references/examples.md)，适合需要串联 table / record / view 完整操作链路时再读。
-
-#### 2.3.1 Table 子模块
-
-子模块索引：[`references/lark-base-table.md`](references/lark-base-table.md)
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+table-list / +table-get` | 列出数据表，或获取单个表详情 | [`lark-base-table-list.md`](references/lark-base-table-list.md)、[`lark-base-table-get.md`](references/lark-base-table-get.md) | `+table-list` 只能串行执行；`+table-get` 适合删除/修改前确认目标 |
-| `+table-create / +table-update / +table-delete` | 创建、更新或删除数据表 | [`lark-base-table-create.md`](references/lark-base-table-create.md)、[`lark-base-table-update.md`](references/lark-base-table-update.md)、[`lark-base-table-delete.md`](references/lark-base-table-delete.md) | 创建适合一次性建表；更新前先确认目标表；删除时用户已明确目标可直接执行并带 `--yes` |
-
-#### 2.3.2 Field 子模块
-
-普通字段管理走这里；如果字段类型是 `formula` 或 `lookup`，转到下方“公式 / Lookup 模块”。  
-子模块索引：[`references/lark-base-field.md`](references/lark-base-field.md)
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+field-list / +field-get` | 列出字段结构，或获取单个字段详情 | [`lark-base-field-list.md`](references/lark-base-field-list.md)、[`lark-base-field-get.md`](references/lark-base-field-get.md) | 写记录、写字段、做分析前常先读 `+field-list`；`+field-list` 只能串行执行；`+field-get` 适合删除/更新前确认目标 |
-| `+field-create / +field-update / +field-delete` | 创建、更新或删除普通字段 | [`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-field-delete.md`](references/lark-base-field-delete.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 写字段前先看字段属性规范；如果涉及类型转换，直接按 `+field-update` 中的字段类型变更规则执行，只在安全白名单内考虑原地转换；如果类型是 `formula / lookup`，先转去读对应 guide；更新或删除时用户已明确目标可直接执行并带 `--yes` |
-| `+field-search-options` | 查询字段可选项 | [`lark-base-field-search-options.md`](references/lark-base-field-search-options.md) | 适合单选/多选等选项型字段 |
-
-#### 2.3.3 Record 子模块
-
-子模块索引：[`references/lark-base-record.md`](references/lark-base-record.md)、[`references/lark-base-history.md`](references/lark-base-history.md)
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+record-search / +record-list / +record-get` | 按关键词检索记录、读取记录明细 / 分页导出，或按 ID 获取一条或多条记录 | [`lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md) | 记录读取统一先读 data analysis SOP：已知 `record_id` 用 `+record-get`；明确关键词用 `+record-search`；普通明细用 `+record-list`；明确筛选 / 排序 / Top N 用临时视图投影后 `+record-list --view-id`；统计聚合才分流到 `+data-query`；`+record-get` 支持重复 `--record-id` 或 `--json` 读取多条记录 |
-| `+record-upsert / +record-batch-create / +record-batch-update` | 创建、更新或批量写入记录 | [`lark-base-record-upsert.md`](references/lark-base-record-upsert.md)、[`lark-base-record-batch-create.md`](references/lark-base-record-batch-create.md)、[`lark-base-record-batch-update.md`](references/lark-base-record-batch-update.md)、[`lark-base-cell-value.md`](references/lark-base-cell-value.md) | 写前先 `+field-list`；只写存储字段；`+record-batch-update` 为同值更新（同一 patch 应用到多条记录）；批量单次不超过 `200` 条；附件不要走这里 |
-| `+record-upload-attachment` | 给已有记录上传一个或多个附件 | 看 `lark-cli base +record-upload-attachment --help` | 附件上传专用链路，不要用 `+record-upsert` / `+record-batch-*` 伪造附件值；不支持 `--name` |
-| `+record-download-attachment` | 下载一个或多个 Base 附件到本地 | 看 `lark-cli base +record-download-attachment --help` | Base 附件必须用这个命令下载；用其他下载入口可能失败 |
-| `+record-remove-attachment` | 删除附件字段里的一个或多个附件 | 看 `lark-cli base +record-remove-attachment --help` | 删除操作；确认目标后带 `--yes` |
-| `+record-delete` | 删除一条或多条记录 | [`lark-base-record-delete.md`](references/lark-base-record-delete.md) | 删除多条时重复传 `--record-id` 指定多个记录；用户已明确目标可直接执行并带 `--yes` |
-| `+record-history-list` | 查询指定记录的变更历史 | [`lark-base-record-history-list.md`](references/lark-base-record-history-list.md) | 按 `table-id + record-id` 查询，不支持整表扫描；`+record-history-list` 只能串行执行 |
-| `+record-share-link-create` | 为一条或多条记录生成分享链接 | [`lark-base-record-share-link-create.md`](references/lark-base-record-share-link-create.md) | 单次最多 100 条；重复 record_id 会自动去重；适合分享单条记录或批量分享场景 |
-
-#### 2.3.4 View 子模块
-
-子模块索引：[`references/lark-base-view.md`](references/lark-base-view.md)
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+view-list / +view-get` | 列出视图，或获取视图详情 | [`lark-base-view-list.md`](references/lark-base-view-list.md)、[`lark-base-view-get.md`](references/lark-base-view-get.md) | `+view-list` 只能串行执行；`+view-get` 适合查看已有视图配置 |
-| `+view-create / +view-delete / +view-rename` | 创建、删除或重命名视图 | [`lark-base-view-create.md`](references/lark-base-view-create.md)、[`lark-base-view-delete.md`](references/lark-base-view-delete.md)、[`lark-base-view-rename.md`](references/lark-base-view-rename.md) | 创建前先确认表和视图类型；删除前先确认目标；用户已明确新名字时可直接重命名 |
-| `+view-get-filter / +view-set-filter` | 读取或配置筛选条件 | [`lark-base-view-get-filter.md`](references/lark-base-view-get-filter.md)、[`lark-base-view-set-filter.md`](references/lark-base-view-set-filter.md)、[`lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md) | 常与 `+record-list` 组合，用于按视图筛选读取 |
-| `+view-get-sort / +view-set-sort` | 读取或配置排序 | [`lark-base-view-get-sort.md`](references/lark-base-view-get-sort.md)、[`lark-base-view-set-sort.md`](references/lark-base-view-set-sort.md) | 字段名必须来自真实结构 |
-| `+view-get-group / +view-set-group` | 读取或配置分组 | [`lark-base-view-get-group.md`](references/lark-base-view-get-group.md)、[`lark-base-view-set-group.md`](references/lark-base-view-set-group.md) | 字段名必须来自真实结构 |
-| `+view-get-visible-fields / +view-set-visible-fields` | 读取或配置视图可见字段 | [`lark-base-view-get-visible-fields.md`](references/lark-base-view-get-visible-fields.md)、[`lark-base-view-set-visible-fields.md`](references/lark-base-view-set-visible-fields.md) | 用于控制视图中的字段顺序与可见性；字段名必须来自真实结构 |
-| `+view-get-card / +view-set-card` | 读取或配置卡片视图 | [`lark-base-view-get-card.md`](references/lark-base-view-get-card.md)、[`lark-base-view-set-card.md`](references/lark-base-view-set-card.md) | 适合卡片展示场景 |
-| `+view-get-timebar / +view-set-timebar` | 读取或配置时间轴视图 | [`lark-base-view-get-timebar.md`](references/lark-base-view-get-timebar.md)、[`lark-base-view-set-timebar.md`](references/lark-base-view-set-timebar.md) | 适合时间线展示场景 |
-
-### 2.4 公式 / Lookup 模块
-
-只要用户诉求涉及派生指标、条件判断、文本处理、日期差、跨表计算、跨表筛选后取值，都要先判断是否进入本模块。
-
-默认优先考虑 `formula`：适合常规计算、条件判断、文本处理、日期差、跨表聚合，以及需要长期显示在表里的派生结果。  
-只有当用户明确要求 `lookup`，或场景天然符合 `from / select / where / aggregate` 这种固定查找建模时，再使用 `lookup`。
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+field-create`（`type=formula`） | 创建公式字段 | [`formula-field-guide.md`](references/formula-field-guide.md)、[`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 没读 guide 前不要直接创建 |
-| `+field-update`（`type=formula`） | 更新公式字段 | [`formula-field-guide.md`](references/formula-field-guide.md)、[`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 先拿当前表结构 |
-| `+field-create`（`type=lookup`） | 创建 lookup 字段 | [`lookup-field-guide.md`](references/lookup-field-guide.md)、[`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 没读 guide 前不要直接创建 |
-| `+field-update`（`type=lookup`） | 更新 lookup 字段 | [`lookup-field-guide.md`](references/lookup-field-guide.md)、[`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 跨表时还要拿目标表结构 |
-
-### 2.5 数据分析模块
-
-用于一次性分析和临时聚合查询。用户要的是“这次算出来的结果”，而不是把结果沉淀成字段时，优先进入本模块。
-
-进入本模块前先确认几件事：
-
-- `+data-query` 只做聚合查询（分组、过滤、排序、聚合计算），不用于列出原始记录或逐条明细。
-- 调用者必须是目标多维表格的管理员，拥有目标多维表格的 FA（Full Access / 完全访问权限），否则会返回权限错误。
-- `+data-query` 只支持白名单字段类型；`formula`、`lookup`、附件、系统字段、关联等字段不能用于 `dimensions / measures / filters / sort`。
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+data-query` | 做分组统计、SUM / AVG / COUNT / MAX / MIN、条件筛选后的聚合分析 | [`lark-base-data-query.md`](references/lark-base-data-query.md) | 字段名必须精确匹配真实字段名；不要用 `+record-list` / `+record-search` 拉全量再手算；`+data-query` 不返回原始记录；使用前先确认权限和字段类型是否受支持 |
-
-### 2.6 Workflow 模块
-
-这是高约束模块。执行任何 workflow 命令前，都必须先读对应命令文档和 schema。  
-模块索引：[`references/lark-base-workflow.md`](references/lark-base-workflow.md)
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+workflow-list / +workflow-get` | 列出 workflow，或获取完整 workflow 结构 | [`lark-base-workflow-list.md`](references/lark-base-workflow-list.md)、[`lark-base-workflow-get.md`](references/lark-base-workflow-get.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | `+workflow-list` 只返回摘要且只能串行执行；需要完整结构时用 `+workflow-get` |
-| `+workflow-create / +workflow-update` | 创建或更新 workflow | [`lark-base-workflow-create.md`](references/lark-base-workflow-create.md)、[`lark-base-workflow-update.md`](references/lark-base-workflow-update.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 先读 schema；禁止凭自然语言猜 `type`；先确认真实表名和字段名 |
-| `+workflow-enable / +workflow-disable` | 启用或停用 workflow | [`lark-base-workflow-enable.md`](references/lark-base-workflow-enable.md)、[`lark-base-workflow-disable.md`](references/lark-base-workflow-disable.md)、[`lark-base-workflow-schema.md`](references/lark-base-workflow-schema.md) | 启用或停用前先确认目标 workflow；`workflow_id` 与 `table_id` 需按前缀区分 |
-
-### 2.7 Dashboard 模块
-
-当用户提到“仪表盘、dashboard、数据看板、图表、可视化、block、组件、添加组件、创建图表”等关键词时，进入本模块，并先阅读 [`lark-base-dashboard.md`](references/lark-base-dashboard.md)。
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+dashboard-list / +dashboard-get` | 列出仪表盘，或获取仪表盘详情 | [`lark-base-dashboard-list.md`](references/lark-base-dashboard-list.md)、[`lark-base-dashboard-get.md`](references/lark-base-dashboard-get.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 进入仪表盘语义后先读 guide；`+dashboard-list` 只能串行执行 |
-| `+dashboard-create / +dashboard-update / +dashboard-delete` | 创建、更新或删除仪表盘 | [`lark-base-dashboard-create.md`](references/lark-base-dashboard-create.md)、[`lark-base-dashboard-update.md`](references/lark-base-dashboard-update.md)、[`lark-base-dashboard-delete.md`](references/lark-base-dashboard-delete.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md) | 创建前先明确看板目标和展示场景；更新前先读取当前配置；删除前先确认目标 |
-| `+dashboard-block-list / +dashboard-block-get` | 列出图表组件，或获取单个 block 详情 | [`lark-base-dashboard-block-list.md`](references/lark-base-dashboard-block-list.md)、[`lark-base-dashboard-block-get.md`](references/lark-base-dashboard-block-get.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | `+dashboard-block-list` 只能串行执行；查看配置细节时读 block config 文档 |
-| `+dashboard-block-get-data` | 获取图表组件的计算结果 | [`lark-base-dashboard-block-get-data.md`](references/lark-base-dashboard-block-get-data.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | 适合读取图表组件的最终计算结果；此命令不返回 block 元数据，只返回计算结果 |
-| `+dashboard-block-create / +dashboard-block-update / +dashboard-block-delete` | 创建、更新或删除图表组件 | [`lark-base-dashboard-block-create.md`](references/lark-base-dashboard-block-create.md)、[`lark-base-dashboard-block-update.md`](references/lark-base-dashboard-block-update.md)、[`lark-base-dashboard-block-delete.md`](references/lark-base-dashboard-block-delete.md)、[`lark-base-dashboard.md`](references/lark-base-dashboard.md)、[`dashboard-block-data-config.md`](references/dashboard-block-data-config.md) | 涉及 `data_config`、图表类型、filter 时要读 block config 文档；删除前先确认目标 |
-
-### 2.8 表单模块
-
-用于管理表单本体和表单题目。  
-模块索引：[`references/lark-base-form.md`](references/lark-base-form.md)、[`references/lark-base-form-questions.md`](references/lark-base-form-questions.md)  
-表单问题相关操作依赖 `form-id`；具体获取方式见 `form-list` 和 `form-create` 的 reference。
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+form-list / +form-get` | 列出表单，或获取单个表单 | [`lark-base-form-list.md`](references/lark-base-form-list.md)、[`lark-base-form-get.md`](references/lark-base-form-get.md) | `+form-list` 可用来获取 `form-id`；`+form-get` 适合查看已有表单配置 |
-| `+form-detail` | 通过表单分享链接获取表单详情（含题目列表、字段类型、校验规则） | [`lark-base-form-detail.md`](references/lark-base-form-detail.md) | 只读；仅需 `--share-token`（从分享链接提取），不需要 base-token/table-id/form-id；返回的 `questions` 可直接用于 `+form-submit` 构造参数 |
-| `+form-submit` | 通过表单分享链接填写并提交表单（支持普通字段 + 附件上传） | [`lark-base-form-submit.md`](references/lark-base-form-submit.md) | 写入操作；仅支持 share_token 模式；**当 `--json` 包含 attachments 时必须额外提供 `--base-token`**（附件上传到 Base Drive Media 需要）；附件通过 `--json.attachments` 传入本地路径，CLI 自动并行上传 |
-| `+form-create / +form-update / +form-delete` | 创建、更新或删除表单 | [`lark-base-form-create.md`](references/lark-base-form-create.md)、[`lark-base-form-update.md`](references/lark-base-form-update.md)、[`lark-base-form-delete.md`](references/lark-base-form-delete.md) | 创建后可继续进入表单问题相关操作；更新或删除前先确认目标表单 |
-| `+form-questions-list` | 列出表单题目 | [`lark-base-form-questions-list.md`](references/lark-base-form-questions-list.md) | 适合查看已有题目结构 |
-| `+form-questions-create / +form-questions-update / +form-questions-delete` | 创建、更新或删除题目 | [`lark-base-form-questions-create.md`](references/lark-base-form-questions-create.md)、[`lark-base-form-questions-update.md`](references/lark-base-form-questions-update.md)、[`lark-base-form-questions-delete.md`](references/lark-base-form-questions-delete.md) | 先确认 `form-id`；更新或删除前先确认题目目标 |
-
-### 2.9 权限与角色模块
-
-用于启用高级权限，以及管理 Base 自定义角色。  
-涉及 `+advperm-enable / +advperm-disable / +role-*` 时，操作用户必须为 Base 管理员，否则会返回权限错误。
-
-| 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 |
-|------|------------------|----------------|----------|
-| `+advperm-enable / +advperm-disable` | 启用或停用高级权限 | [`lark-base-advperm-enable.md`](references/lark-base-advperm-enable.md)、[`lark-base-advperm-disable.md`](references/lark-base-advperm-disable.md) | 管理角色前必须先启用；停用是高风险操作，会使已有自定义角色失效 |
-| `+role-list / +role-get` | 列出角色，或获取角色详情 | [`lark-base-role-list.md`](references/lark-base-role-list.md)、[`lark-base-role-get.md`](references/lark-base-role-get.md)、[`role-config.md`](references/role-config.md) | `+role-list` 只能串行执行；`+role-get` 适合查看完整权限配置 |
-| `+role-create / +role-update / +role-delete` | 创建、更新或删除角色 | [`lark-base-role-create.md`](references/lark-base-role-create.md)、[`lark-base-role-update.md`](references/lark-base-role-update.md)、[`lark-base-role-delete.md`](references/lark-base-role-delete.md)、[`role-config.md`](references/role-config.md) | `+role-create` 仅支持 `custom_role`；`+role-update` 采用 Delta Merge，`role_name` 和 `role_type` 即使不改也必须传当前值；`+role-delete` 不可逆 |
-
-## 3. 多维表格通用知识
-
-飞书多维表格英文名是 `Base`，曾用名 `Bitable`；因此旧文档、返回字段、参数名或错误信息里出现 `bitable` 多属历史兼容，不代表应改用另一套命令体系。
-
-### 3.1 字段分类与可写性
-
-| 字段类型 | 含义 | 能否直接作为 `+record-upsert / +record-batch-create / +record-batch-update` 写入目标 | 说明 |
-|----------|------|-----------------------------------------------------------|------|
-| 存储字段 | 真实存用户输入的数据 | 可以 | 常见如文本、数字、日期、单选、多选、人员、关联 |
-| 附件字段 | 存储文件附件 | 不应直接按普通字段写 | 上传附件走 `+record-upload-attachment`；下载附件走 `+record-download-attachment`；删除附件走 `+record-remove-attachment` |
-| 地理位置字段 | 存储坐标并由平台解析地址 | 可以 | 写入必须使用 `{lng,lat}`；读取、筛选和转文本等场景使用 `full_address` 字符串；只有公式能访问坐标 |
-| 系统字段 | 平台自动维护 | 不可以 | 常见如创建时间、更新时间、创建人、修改人、自动编号 |
-| `formula` 字段 | 通过表达式计算 | 不可以 | 只读字段 |
-| `lookup` 字段 | 通过跨表规则查找引用 | 不可以 | 只读字段 |
-
-### 3.2 任务选路心智模型
-
-| 用户诉求 | 优先方案 | 不要误走 |
-|---------|----------|----------|
-| 一次性分析 / 临时统计 | `+data-query` | 不要用 `+record-list` / `+record-search` 拉全量后手算 |
-| 要把结果长期显示在表里 | `formula` 字段 | 不要只给一次性手工分析结果 |
-| 用户明确要求 lookup，或天然是固定查找配置 | `lookup` 字段 | 不要默认先上 lookup；先判断 formula 是否更合适 |
-| 读取原始记录明细 / 关键词检索 / 导出 | `+record-search / +record-list / +record-get` | 不要拿 `+data-query` 当取数命令 |
-| 上传附件到记录 | `+record-upload-attachment` | 不要用 `+record-upsert` / `+record-batch-*` 伪造附件值 |
-| 下载记录里的附件文件 | `+record-download-attachment --record-id <record_id> --output <dir>`，可加 `--file-token <file_token>` 只下指定附件 | Base 附件必须用这个命令下载；用其他下载入口可能失败 |
-| 写入地理位置 | `+record-upsert` / `+record-batch-*` 传 `{lng,lat}` | 不要把纯地址文本当成 CellValue |
-| 基于视图做筛选读取 | `+view-set-filter` + `+record-list` | 不要跳过视图筛选直接猜条件 |
-| 本地 Excel / CSV / `.base` 导入为 Base | `lark-cli drive +import --type bitable` | 不要误走 `+base-create`、`+table-create` 或 `+record-upsert` |
-
-### 3.3 查询执行契约
-
-涉及查询、统计或判断结论时，先阅读 [`references/lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md)，并遵守以下高优先级规则：
-
-1. `+record-list` 默认页、固定 `--limit` 和本地 `jq` 只能证明已读取范围内的事实，不能直接支撑全局最值、全量计数、Top/Bottom N、异常识别或分组结论。
-2. 能由 Base 表达的筛选、排序、投影、聚合、分组和限制，应在 Base 云端查询服务中执行；不要先拉明细到本地上下文再手工筛选排序。
+1. `+record-list` 的默认页、固定 `--limit` 和本地 `jq` 只能证明已读取范围内的事实，不能直接支撑全局最值、全量计数、Top/Bottom N、异常识别或分组结论。
+2. 能由 Base 表达的筛选、排序、投影、聚合、分组和限制，应在 Base 云端查询能力中执行；不要先拉明细到本地上下文再手工筛选排序。
 3. `has_more=true` 或等价分页信号表示当前结果不是全量；除非用户只要样例/前 N 条，不能基于该页回答全局问题。
 4. 多表查询必须先确认关系字段和连接键；link 单元格里的 `record_id` 是关系键，不是用户可读答案。
 5. 最终答案必须能追溯到真实表、真实字段、查询范围、筛选/排序/聚合条件和必要的连接键。
+6. 一次性分析优先用 `+data-query` 或临时视图；要把结果长期显示在表里，才考虑新增 `formula` / `lookup` 字段。
+7. `+data-query` 返回聚合结果，不返回原始记录明细；需要输出实体字段时，用聚合结果中的业务 key 或 record_id 再走 record 路径回查。
 
-### 3.4 表名、字段名与表达式引用
+## 写入前置规则
 
-1. 表名、字段名必须精确匹配真实返回，来源应是 `+table-list / +table-get / +field-list`。
-2. 不要凭自然语言猜名称，不要自行改写用户口述中的表名、字段名。
-3. `formula / lookup / data-query / workflow` 中出现的名称同样必须精确匹配；表达式引用、where 条件、DSL 字段名、workflow 配置都遵守同一规则。
-4. 跨表场景必须额外读取目标表结构，不能只看当前表。
+- 写记录前先读字段结构；只写存储字段。系统字段、附件字段、`formula`、`lookup` 不作为普通记录写入目标。
+- 附件上传、下载、删除走专用 `+record-*-attachment` 命令。
+- 写字段前先读 `lark-base-field-json.md`；涉及 `formula` / `lookup` 时必须读对应 guide。
+- 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回；跨表场景还要读取目标表结构。
+- 删除、角色更新、字段更新等高风险操作遵循 CLI 的 confirmation gate；目标不明确时先用 get/list 消歧。
+- 批量写入单批最多 200 条；连续写同一表时串行执行，遇到 `1254291` 按短暂等待后重试处理。
+- `+record-batch-update` 是“同值批量更新”：同一份 patch 应用到全部 `record_id_list`，不要拿它做逐行不同值映射。
+- select/multiselect 写入未知选项可能触发平台新增选项；不是要新增时，先用 `+field-list` 或 `+field-search-options` 确认可选值。
 
-### 3.5 Token 与链接
+## 表单与视图细节
 
-这是高优先级章节。只要用户输入里出现链接、token，或报错涉及 `baseToken` / `wiki_token` / `obj_token`，都应优先回到这里检查。
+- `+form-submit` 前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
+- 表单附件不要写进 `fields`，放在 `--json.attachments`；提交附件时必须同时传表单所属 Base 的 `--base-token`。
+- `+view-set-filter` 是唯一保留的 view reference；sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状，保留未修改字段，只替换用户要求变更的配置。
+- 临时视图适合一次性筛选/排序后读取；如果筛选结果对用户后续查看有价值，应保留为持久视图并说明名称和用途。
 
-| 输入类型 | 正确处理方式 | 说明 |
-|---------|--------------|------|
-| 直接 Base 链接 `/base/{token}` | 直接提取 token 作为 `--base-token` | 不要把完整 URL 直接作为 `--base-token` |
-| Wiki 链接 `/wiki/{token}` | 先用下方 fast path 解析 `data.obj_token` | 不要把 `wiki_token` 直接当 `--base-token`；如果这一步失败，再看 [`lark-wiki-node-get.md`](../lark-wiki/references/lark-wiki-node-get.md) |
-| URL 中的 `?table={id}` | 先按前缀判断对象类型 | `tbl` 开头表示数据表 `table-id`，可作为 `--table-id`；`blk` 开头表示仪表盘 `dashboard-ID`；`wkf` 开头表示 `workflow-ID`；`ldx` 开头表示内嵌文档，不要一律当成 `--table-id` |
-| URL 中的 `?view={id}` | 提取为 `--view-id` | 适合直接定位视图 |
+## Token 与链接
 
-Wiki Base fast path:
+| 输入类型 | 含义 / 正确处理方式 |
+|---|---|
+| `/base/{token}` | 普通 Base 链接；提取 `/base/` 后的 token 作为 `--base-token` |
+| `/wiki/{token}` | Wiki 节点链接；先 `wiki +node-get`，当 `data.obj_type=bitable` 时使用 `data.obj_token` 作为 `--base-token` |
+| `/base/{token}?table={id}` | `table` 参数用于定位 Base 内对象：`tbl` 开头是数据表 `--table-id`；`blk` 开头是 dashboard ID；`wkf` 开头是 workflow ID |
+| `/base/{token}?view={id}` | `view` 参数用于定位表视图，提取为 `--view-id`；通常还需要确认 `table` 参数或先查表结构 |
+| `/share/base/form/{shareToken}` | 表单分享链接；这是表单 share token，走 `+form-detail` / `+form-submit --share-token <shareToken>` |
+| `/share/base/view/{shareToken}` | 视图分享链接；具有分享权限语义，暂不支持用 CLI 直接访问，引导用户在浏览器或飞书客户端打开 |
+| `/share/base/dashboard/{shareToken}` | 仪表盘分享链接；具有分享权限语义，暂不支持用 CLI 直接访问，引导用户在浏览器或飞书客户端打开 |
+| `/record/{shareToken}` | 记录分享链接；暂不支持用 CLI 直接访问，引导用户在浏览器或飞书客户端打开。若用户想生成现有记录的分享链接，用 `+record-share-link-create --base-token <base_token> --table-id <table_id> --record-ids <record_id>` |
+| `/base/workspace/{token}` | BaseApp / workspace 链接；暂不支持用 CLI 直接访问 |
 
-```bash
-BASE_TOKEN="$(lark-cli wiki +node-get --as user --node-token "<wiki_url_or_token>" --jq '.data | select(.obj_type == "bitable") | .obj_token')"
-```
+`wiki +node-get` 返回非 `bitable` 时，不继续使用 Base 命令：`docx` 转文档，`sheet` 转表格，其他云空间对象转对应 skill 或 drive。
 
-| `lark-cli wiki +node-get` 返回的 `data.obj_type` | 后续路线 | 说明 |
-|-----------------------------------------------|----------|------|
-| `bitable` | 优先走 `lark-cli base +...` | 如果 shortcut 不覆盖，再用 `lark-cli base <resource> <method>`；不要改走 `lark-cli api /open-apis/bitable/v1/...` |
-| `docx` | 转到文档 / Drive 相关 skill | 不继续使用本 skill 的 Base 命令 |
-| `sheet` | 转到 Sheets 相关 skill | 不继续使用本 skill 的 Base 命令 |
-| `slides` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 |
-| `mindnote` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 |
+## Dashboard / Workflow / Role
 
-### 3.6 身份选择与权限降级策略
+- Dashboard 的复杂点是 block 的 `data_config`，不是 list/get/create/delete 命令参数。创建或更新 block 前先读 `dashboard-block-data-config.md`，组件必须串行创建；`+dashboard-arrange` 是服务端智能布局，只在用户明确要求重排/美化时执行。`+dashboard-block-get-data` 读取图表最终计算结果，不返回 block 名称、类型、布局或 `data_config`；需要元数据先用 `+dashboard-block-get`。
+- Workflow 的复杂点是 `steps` 结构。创建、更新或解释完整 workflow 时读入口 `lark-base-workflow-guide.md` 和 steps JSON SSOT `lark-base-workflow-schema.md`；enable/disable/list 只需确认 workflow ID、当前启停状态和用户意图。
+- Role 的复杂点是权限 JSON。角色操作先读入口 `lark-base-role-guide.md`；`+role-create` 只支持自定义角色；`+role-update` 是 delta merge；角色 create/update 或解读完整配置时读权限 JSON SSOT `role-config.md`。`+role-delete` 只适用于自定义角色，系统角色不可删除；删除角色和关闭高级权限前必须确认目标和影响。
 
-多维表格通常属于用户的个人或团队资源。**默认应优先使用 `--as user`（用户身份）执行所有 Base 操作**，始终显式指定身份。
+## 常见恢复
 
-- **`--as user`（推荐）**：以当前登录用户身份操作其有权访问的 Base。执行前先完成用户授权：
+| 错误 / 现象 | 恢复动作 |
+|---|---|
+| `param baseToken is invalid` / `base_token invalid` | 检查是否把 wiki token、workspace token 或完整 URL 当成了 `--base-token`；按 `Token 与链接` 重新定位真实 Base token |
+| `not found` 且输入来自 Wiki 链接 | 优先检查是否把 wiki token 当成 base token，不要立刻改走裸 API |
+| `1254045` 字段名不存在 | 重新 `+field-list`，使用真实字段名或字段 ID；注意空格、大小写和跨表字段 |
+| `1254015` 字段值类型不匹配 | 先 `+field-list`，再按 `lark-base-cell-value.md` 构造 CellValue |
+| 日期 / 人员 / 超链接字段报格式错误 | 日期用 `YYYY-MM-DD HH:mm:ss`；人员用 `[{ "id": "ou_xxx" }]`；超链接用 URL 或 markdown link 字符串 |
+| formula / lookup 创建失败 | 先读 `formula-field-guide.md` / `lookup-field-guide.md`，再按 guide 重建请求 |
+| `ignored_fields` / `READONLY` | 移除只读字段，只写存储字段 |
+| `1254104` | 批量超过 200，分批调用 |
+| `1254291` | 并发写冲突，串行写入并在批次间短暂等待 |
+| `91403` | 无权限访问该 Base，按 `lark-shared` 权限流程处理，不要盲目重试 |
 
-```bash
-lark-cli auth login --domain base
-```
+## 保留 Reference
 
-- **`--as bot`（降级）**：仅当 user 身份权限不足、且 bot 身份确实拥有目标 Base 的访问权限时，才降级使用。bot 看不到用户私有资源，行为以应用身份执行。
-
-**执行规则**：
-
-1. 所有操作默认先用 `--as user`。
-2. 若 user 身份返回权限错误，先判断是否为**不可重试错误码**（如 `91403`）。若是，**立即停止**，不做任何重试或降级，直接按 `lark-shared` 权限不足处理流程引导用户解决。
-3. 非不可重试错误码时，检查错误响应中是否包含 `permission_violations` / `hint` 等提权引导信息：
-   - **有提权引导**：按 `lark-shared` 权限不足处理流程，先引导用户完成 user 身份提权（`auth login --scope`）；确认提权成功后，以 `--as user` 重试。
-   - **无提权引导**（如资源级无访问权限、非 scope 不足）：切换到 `--as bot` 重试**一次**。
-4. 若 bot 身份仍然返回权限错误，**立即停止重试**，根据错误响应按 `lark-shared` 流程引导用户解决（引导去开发者后台开通 scope 或确认资源访问权限）。
-5. 只有在用户明确要求"用应用身份 / bot 身份操作"，才跳过 user 直接使用 `--as bot`。
-
-## 4. 执行规则
-
-### 4.1 标准执行顺序
-
-1. 先判断任务属于哪个模块，选对命令族。
-2. 如果用户给了链接，先解析 token，不要把 wiki token、完整 URL 或其他对象 ID 误当成 `base_token`。
-3. 如果是查询类任务，先判断问题范围，阅读 data analysis SOP，再决定使用 `record / view / data-query`。
-4. 先拿结构，再写命令，避免猜表名、字段名、表达式引用。
-5. 定位到命令后，先读对应 reference，再执行命令。
-6. 执行命令，并按返回结果判断下一步。
-7. 回复时返回关键结果和后续可继续操作的信息，方便 agent 链式执行下一步。
-
-### 4.2 不可违反规则
-
-1. 先拿结构，再写命令；至少先拿当前表结构，跨表时还要拿目标表结构。
-2. 不要猜表名、字段名、表达式引用，一律以真实返回为准。
-3. 只使用原子命令；不要回退到旧的聚合式 `+table / +field / +record / +view / +history / +workspace`。
-4. 写记录前先读字段结构；先 `+field-list`，再按 [`lark-base-cell-value.md`](references/lark-base-cell-value.md) 构造 CellValue。
-5. 写字段前先看字段属性规范；先读 `lark-base-shortcut-field-properties.md`，再构造 `+field-create / +field-update` 的 JSON。
-6. 只写可写字段；系统字段、附件字段、`formula`、`lookup` 默认不作为普通记录写入目标。
-7. 聚合分析与取数分流；统计走 `+data-query`，关键词检索走 `+record-search`，明细走 `+record-list / +record-get`。
-8. 筛选查询按视图能力执行；先用 `+view-set-filter` 配置筛选，再结合 `+record-list` 读取。
-9. 全局查询不得基于默认分页、小 `--limit` 或未证明全量的本地 `jq` 结果下结论。
-10. Base 场景不要改走裸 API，不要切去 `lark-cli api /open-apis/bitable/v1/...`。
-11. 统一使用 `--base-token`。
-12. workflow 场景先读 schema，不要凭自然语言猜 `type`。
-13. dashboard 场景先读 guide；提到图表、看板、block 就先进入 dashboard 模块。
-14. formula / lookup 场景先读 guide；没读 guide 前不要直接创建或更新。
-
-### 4.3 并发、分页与批量限制
-
-- `+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list / +dashboard-list / +dashboard-block-list / +workflow-list` 禁止并发调用，只能串行执行。
-- `+record-list` 分页时，`--limit` 最大 `200`；先拉首批并检查 `has_more`，只有用户明确需要更多数据时再继续翻页。
-- 批量写入时，单批不超过 `200` 条。
-- 连续写入同一表时，必须串行写入，批次间延迟 `0.5–1` 秒。
-
-### 4.4 确认与回复规则
-
-- 视图重命名时，用户已明确“把哪个视图改成什么名字”时，`+view-rename` 直接执行即可。
-- 更新字段或删除记录 / 字段 / 表时，如果用户已经明确目标，`+field-update / +record-delete / +field-delete / +table-delete` 可直接执行，并带 `--yes`。
-- 删除目标仍有歧义时，先用 `+record-get / +field-get / +table-get` 或相应 list 命令确认。
-- `+base-create / +base-copy` 成功后，回复中必须主动返回新 Base 的标识信息；若结果带可访问链接，也应一并返回。
-- 若 Base 由 bot 身份创建或复制，shortcut 会自动尝试为当前 CLI 用户补授 `full_access`，并在输出中返回 `permission_grant`；agent 不需要再手动编排单独授权。owner 转移必须单独确认，禁止擅自执行。
-
-## 5. 常见错误与恢复
-
-| 错误 / 现象 | 含义 | 恢复动作 |
-|-------------|------|----------|
-| `1254064` | 日期格式错误 | 传 `YYYY-MM-DD HH:mm:ss` 字符串，不要写相对时间 |
-| `1254068` | 超链接格式错误 | `"https://example.com"` 或 `"[文本](https://example.com)"` |
-| `1254066` | 人员字段错误 | `[{ "id": "ou_xxx" }]` |
-| `1254045` | 字段名不存在 | 检查字段名（含空格、大小写） |
-| `1254015` | 字段值类型不匹配 | 先 `+field-list`，再按类型构造 |
-| `param baseToken is invalid` / `base_token invalid` | 把 wiki token、workspace token 或其他 token 当成了 `base_token` | 如果输入来自 `/wiki/...`，先用 `lark-cli wiki +node-get --node-token <wiki_url_or_token>` 取真实 `data.obj_token`；当 `data.obj_type=bitable` 时，用 `data.obj_token` 作为 `--base-token` 重试，不要改走 `bitable/v1` |
-| `not found` 且用户给的是 wiki 链接 | 常见于把 wiki token 当成 base token | 优先回退检查 wiki 解析，而不是改走 `bitable/v1` |
-| formula / lookup 创建失败 | 指南未读或结构不合法 | 先读 `formula-field-guide.md` / `lookup-field-guide.md`，再按 guide 重建请求 |
-| `ignored_fields` / `READONLY` | 只读字段被当成可写字段，常见于系统字段、formula、lookup | 移除只读字段，只写存储字段；计算结果交给 formula / lookup / 系统字段自动产出 |
-| `1254104` | 批量超 200 条 | 分批调用 |
-| `1254291` | 并发写冲突 | 串行写入 + 批次间延迟 |
-| `91403` | 无权限访问该 Base | **不要重试**。按 `lark-shared` 权限不足处理流程引导用户解决权限问题 |
+- `lark-base-data-analysis-sop.md`：查询/统计/全局结论的选路 SOP
+- `lark-base-data-query-guide.md` / `lark-base-data-query.md`：聚合查询入口 fewshot 与 DSL SSOT
+- `lark-base-cell-value.md`：记录 CellValue 构造
+- `lark-base-field-json.md`：字段 JSON 构造
+- `formula-field-guide.md` / `lookup-field-guide.md`：公式与 lookup 字段
+- `lark-base-field-create.md` / `lark-base-field-update.md`：字段创建/更新命令级补充
+- `lark-base-record-upsert.md` / `lark-base-record-batch-create.md` / `lark-base-record-batch-update.md` / `lark-base-record-history-list.md`：记录写入 JSON 与历史返回解释
+- `lark-base-view-set-filter.md`：视图筛选 JSON
+- `lark-base-form-detail.md` / `lark-base-form-submit.md` / `lark-base-form-questions-create.md` / `lark-base-form-questions-update.md`：表单详情、提交和复杂 JSON
+- `lark-base-dashboard.md` / `dashboard-block-data-config.md` / `lark-base-dashboard-block-get-data.md`：仪表盘、组件配置与图表结果协议
+- `lark-base-workflow-guide.md` / `lark-base-workflow-schema.md`：workflow 入口与 steps JSON SSOT
+- `lark-base-role-guide.md` / `role-config.md`：角色入口与权限 JSON SSOT

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

@@ -1,6 +1,6 @@
-# dashboard block data_config 参考
+# dashboard block data_config SSOT
 
-Block 的 `data_config` 字段因 `type` 不同而变化。本文档描述所有共享结构。
+Block 的 `data_config` 字段因 `type` 不同而变化。本文档是 dashboard block `data_config` 的单一事实来源（SSOT），包含组件类型、字段结构、筛选格式、约束和可复制模板。
 
 ## 支持的组件类型（`type` 枚举）
 

skills/lark-base/references/examples.md

@@ -1,140 +0,0 @@
-# 飞书多维表格使用场景完整示例（base）
-
-本文档提供基于 `lark-cli base +...` shortcut 的完整示例。
-
-> **返回**: [SKILL.md](../SKILL.md) | **参考**: [shortcut 字段 JSON 规范](lark-base-shortcut-field-properties.md) · [CellValue 规范](lark-base-cell-value.md)
-
----
-
-## 场景 1：用 unified Shortcut 快速建表
-
-适合已经明确字段结构、希望一次性完成建表的场景。
-
-```bash
-lark-cli base +table-create \
-  --base-token bascnXXXXXXXX \
-  --name "客户管理表" \
-  --fields '[
-    {"name":"客户名称","type":"text","description":"主标题字段"},
-    {"name":"负责人","type":"user","multiple":false,"description":"用于标记客户跟进的直接负责人"},
-    {"name":"签约日期","type":"datetime"},
-    {"name":"状态","type":"select","multiple":false,"options":[{"name":"进行中"},{"name":"已完成"}]}
-  ]'
-```
-
----
-
-## 场景 2：创建数据表并查看字段
-
-适合需要先建表、再确认字段结构的场景。
-
-### 步骤 1：在已有 Base 中创建数据表
-
-```bash
-lark-cli base +table-create \
-  --base-token bascnXXXXXXXX \
-  --name "客户管理表"
-```
-
-### 步骤 2：列出字段
-
-```bash
-lark-cli base +field-list \
-  --base-token bascnXXXXXXXX \
-  --table-id tblXXXXXXXX \
-  --limit 100
-```
-
-> 提示：Base token 统一通过 `--base-token` 传入；表 ID 统一通过 `--table-id` 传入。
-
----
-
-## 场景 3：创建、读取、更新单条记录
-
-### 新增记录
-
-```bash
-lark-cli base +record-upsert \
-  --base-token bascnXXXXXXXX \
-  --table-id tblXXXXXXXX \
-  --json '{
-    "客户名称":"字节跳动",
-    "负责人":[{"id":"ou_xxx"}],
-    "状态":"进行中"
-  }'
-```
-
-### 列出记录
-
-```bash
-lark-cli base +record-list \
-  --base-token bascnXXXXXXXX \
-  --table-id tblXXXXXXXX \
-  --limit 100
-```
-
-### 更新记录
-
-```bash
-lark-cli base +record-upsert \
-  --base-token bascnXXXXXXXX \
-  --table-id tblXXXXXXXX \
-  --record-id recXXXXXXXX \
-  --json '{
-    "状态":"已完成"
-  }'
-```
-
-### 删除记录
-
-```bash
-lark-cli base +record-delete \
-  --base-token bascnXXXXXXXX \
-  --table-id tblXXXXXXXX \
-  --record-id recXXXXXXXX \
-  --yes
-```
-
----
-
-## 场景 4：配置视图筛选后按视图读取记录
-
-需要筛选查询时，推荐先写视图筛选，再通过 `view_id` 读取记录。
-
-### 更新视图筛选条件
-
-```bash
-lark-cli base +view-set-filter \
-  --base-token bascnXXXXXXXX \
-  --table-id tblXXXXXXXX \
-  --view-id vewXXXXXXXX \
-  --json '{
-    "logic":"and",
-    "conditions":[
-      {
-        "field_name":"状态",
-        "operator":"is",
-        "value":["进行中"]
-      }
-    ]
-  }'
-```
-
-### 按视图读取记录
-
-```bash
-lark-cli base +record-list \
-  --base-token bascnXXXXXXXX \
-  --table-id tblXXXXXXXX \
-  --view-id vewXXXXXXXX \
-  --limit 100
-```
-
----
-
-## 场景 5：什么时候优先用 Shortcut
-
-- 需要一次性建表并附带字段、视图时，优先 `lark-cli base +table-create`
-- 需要按业务字段名做 upsert 时，优先 `lark-cli base +record-upsert`
-- 需要配置筛选视图时，优先 `lark-cli base +view-set-filter`
-- 需要记录历史时，优先 `lark-cli base +record-history-list`

skills/lark-base/references/lark-base-advperm-disable.md

@@ -1,83 +0,0 @@
-# base +advperm-disable
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-停用指定 Base 的高级权限。停用后自定义角色等高级权限功能将不可用。
-
-## 推荐命令
-
-```bash
-# 停用高级权限
-lark-cli base +advperm-disable \
-  --base-token VwGhbYCXQaYGMzsWlEZcBbfMnod
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token，27 位字母数字字符串 |
-
-## API 入参详情
-
-**HTTP 方法和路径：**
-
-```
-PUT /open-apis/base/v3/bases/:base_token/advperm/enable?enable=false
-```
-
-**Path 参数：**
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `base_token` | 是 | Base 的唯一标识，27 位字母数字字符串 |
-
-**Query 参数：**
-
-| 参数 | 必填 | 类型 | 说明 |
-|------|------|------|------|
-| `enable` | 是 | bool | 固定为 `false`，表示停用高级权限 |
-
-## API 出参详情
-
-**Response：**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `code` | int32 | 错误码，0 表示成功 |
-| `message` | string | 错误信息 |
-| `data` | string | 成功时为空 |
-
-## 返回值
-
-命令成功后输出 JSON：
-
-```json
-{
-  "ok": true,
-  "data": {
-    "success": true
-  }
-}
-```
-
-## 工作流
-
-> [!CAUTION]
-> 这是**高风险写入操作** — 停用高级权限会影响所有已配置的自定义角色，执行前必须向用户确认。
-
-1. 向用户确认 `--base-token`，并提醒停用会影响已有角色配置
-2. 执行命令
-3. 确认返回 `code: 0` 表示停用成功
-
-## 坑点
-
-- ⚠️ **操作用户必须为 Base 管理员**：非管理员调用会返回权限错误
-- ⚠️ **停用影响已有角色**：停用高级权限后，已创建的自定义角色将失效
-- ⚠️ **API 路径版本**：本接口使用 `base/v3`，路径必须从原始文档提取，不要用 WebSearch 补全
-- ⚠️ **data 字段是 JSON 字符串**：响应中 `data` 是 string 类型（非 object），需要双重解析
-
-## 参考
-
-- [lark-base](../SKILL.md) — 多维表格全部命令
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-base/references/lark-base-advperm-enable.md

@@ -1,80 +0,0 @@
-# base +advperm-enable
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-启用指定 Base 的高级权限。启用后可使用自定义角色等高级权限功能。
-
-## 推荐命令
-
-```bash
-# 启用高级权限
-lark-cli base +advperm-enable \
-  --base-token VwGh**************Mnod
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token，27 位字母数字字符串 |
-
-## API 入参详情
-
-**HTTP 方法和路径：**
-
-```
-PUT /open-apis/base/v3/bases/:base_token/advperm/enable?enable=true
-```
-
-**Path 参数：**
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `base_token` | 是 | Base 的唯一标识，27 位字母数字字符串 |
-
-**Query 参数：**
-
-| 参数 | 必填 | 类型 | 说明 |
-|------|------|------|------|
-| `enable` | 是 | bool | 固定为 `true`，表示启用高级权限 |
-
-## API 出参详情
-
-**Response：**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `code` | int32 | 错误码，0 表示成功 |
-| `message` | string | 错误信息 |
-| `data` | string | 成功时为空 |
-
-## 返回值
-
-命令成功后输出 JSON：
-
-```json
-{
-  "ok": true,
-  "data": {
-    "success": true
-  }
-}
-```
-
-## 工作流
-
-1. 向用户确认 `--base-token`
-2. 执行命令
-3. 确认返回 `code: 0` 表示启用成功
-
-## 坑点
-
-- ⚠️ **操作用户必须为 Base 管理员**：非管理员调用会返回权限错误
-- ⚠️ **API 路径版本**：本接口使用 `base/v3`，路径必须从原始文档提取，不要用 WebSearch 补全
-- ⚠️ **data 字段是 JSON 字符串**：响应中 `data` 是 string 类型（非 object），需要双重解析
-- ⚠️ **启用后才能管理角色**：`+role-create / +role-update / +role-delete` 等角色操作需要先启用高级权限
-
-## 参考
-
-- [lark-base](../SKILL.md) — 多维表格全部命令
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -1,74 +0,0 @@
-# base +base-copy
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-复制一个已有 Base；可选只复制结构，不复制内容。
-
-## 推荐命令
-
-```bash
-lark-cli base +base-copy \
-  --base-token app_xxx \
-  --name "Copied Base"
-
-lark-cli base +base-copy \
-  --base-token app_xxx \
-  --name "Copied Base" \
-  --folder-token fld_xxx \
-  --time-zone Asia/Shanghai \
-  --without-content
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | 源 Base Token |
-| `--name <name>` | 否 | 新 Base 名称 |
-| `--folder-token <token>` | 否 | 目标文件夹 token |
-| `--time-zone <tz>` | 否 | 时区，如 `Asia/Shanghai` |
-| `--without-content` | 否 | 只复制结构，不复制内容 |
-
-## API 入参详情
-
-**HTTP 方法和路径：**
-
-```
-POST /open-apis/base/v3/bases/:base_token/copy
-```
-
-## 返回重点
-
-- 返回 `base`。
-- CLI 会额外标记 `copied: true`。
-- 回复结果时，必须主动返回新 Base 的可访问链接：
-  - 优先使用返回结果中的 `base.url`
-  - 同时返回新 Base 的 token
-  - 如果本次返回没有 `url`，至少返回新 Base 的名称和 token
-
-> [!IMPORTANT]
-> 如果 Base 是**以应用身份（bot）复制**出来的，shortcut 会在复制成功后自动尝试为当前 CLI 用户添加该 Base 的 `full_access`（管理员）权限，并在输出中附带 `permission_grant` 字段。
->
-> `permission_grant.status` 语义如下：
-> - `granted`：当前 CLI 用户已获得该 Base 的管理员权限
-> - `skipped`：Base 已复制成功，但没有可授权的当前 CLI 用户，或复制结果缺少可授权 token
-> - `failed`：Base 已复制成功，但自动授权失败；结果中会包含失败原因，用户可稍后重试授权，或继续使用应用身份（bot）处理该 Base
->
-> 回复复制结果时，除 `base token` 和可访问链接外，还必须明确告知用户 `permission_grant` 的结果。
->
-> **仍然不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
-
-## 工作流
-
-> [!CAUTION]
-> 这是**写入操作** — 执行前必须向用户确认。
-
-1. 先确认源 Base Token。
-2. `--name`、`--folder-token`、`--time-zone` 都是可选项；用户没要求时不要为这些可选参数额外追问。
-3. 只要结构时，显式传 `--without-content`。
-4. 复制成功后，整理并返回：新 Base 名称、token，以及响应中已有的可访问链接。
-
-## 参考
-
-- [lark-base-workspace.md](lark-base-workspace.md) — base / workspace 索引页
-- [lark-base-base-create.md](lark-base-base-create.md) — 创建全新 Base

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

@@ -1,68 +0,0 @@
-# base +base-create
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-创建一个新的 Base；可选指定父文件夹和时区。
-
-## 推荐命令
-
-```bash
-lark-cli base +base-create \
-  --name "New Base"
-
-lark-cli base +base-create \
-  --name "项目管理" \
-  --folder-token fld_xxx \
-  --time-zone Asia/Shanghai
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--name <name>` | 是 | 新 Base 名称 |
-| `--folder-token <token>` | 否 | 目标文件夹 token |
-| `--time-zone <tz>` | 否 | 时区，如 `Asia/Shanghai` |
-
-## API 入参详情
-
-**HTTP 方法和路径：**
-
-```
-POST /open-apis/base/v3/bases
-```
-
-## 返回重点
-
-- 返回 `base`。
-- CLI 会额外标记 `created: true`。
-- 回复结果时，必须主动返回新 Base 的可访问链接：
-  - 优先使用返回结果中的 `base.url`
-  - 同时返回新 Base 的 token
-  - 如果本次返回没有 `url`，至少返回新 Base 的名称和 token
-
-> [!IMPORTANT]
-> 如果 Base 是**以应用身份（bot）创建**的，shortcut 会在创建成功后自动尝试为当前 CLI 用户添加该 Base 的 `full_access`（管理员）权限，并在输出中附带 `permission_grant` 字段。
->
-> `permission_grant.status` 语义如下：
-> - `granted`：当前 CLI 用户已获得该 Base 的管理员权限
-> - `skipped`：Base 已创建成功，但没有可授权的当前 CLI 用户，或创建结果缺少可授权 token
-> - `failed`：Base 已创建成功，但自动授权失败；结果中会包含失败原因，用户可稍后重试授权，或继续使用应用身份（bot）处理该 Base
->
-> 回复创建结果时，除 `base token` 和可访问链接外，还必须明确告知用户 `permission_grant` 的结果。
->
-> **仍然不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
-
-## 工作流
-
-> [!CAUTION]
-> 这是**写入操作** — 执行前必须向用户确认。
-
-1. 先确认 Base 名称。
-2. `--folder-token`、`--time-zone` 都是可选项；用户没要求时不要为此额外追问。
-3. 创建成功后，整理并返回：Base 名称、token，以及响应中已有的可访问链接。
-
-## 参考
-
-- [lark-base-workspace.md](lark-base-workspace.md) — base / workspace 索引页
-- [lark-base-base-copy.md](lark-base-base-copy.md) — 复制 Base

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

@@ -1,39 +0,0 @@
-# base +base-get
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-读取一个 Base 的详情。
-
-## 推荐命令
-
-```bash
-lark-cli base +base-get \
-  --base-token app_xxx
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token |
-
-## API 入参详情
-
-**HTTP 方法和路径：**
-
-```
-GET /open-apis/base/v3/bases/:base_token
-```
-
-## 返回重点
-
-- 返回 `base`，通常包含 `base_token / name / url` 等信息。
-
-## 坑点
-
-- ⚠️ 先确认传入的是 `base_token`，不是 `workspace_token`。
-- ⚠️ 如果最初输入来自 `/wiki/...`，不要直接把 `wiki_token` 当 `--base-token`；若报 `param baseToken is invalid` / `base_token invalid`，先用 `lark-cli wiki spaces get_node` 取 `node.obj_token`，再重试 `+base-get`。
-
-## 参考
-
-- [lark-base-workspace.md](lark-base-workspace.md) — base 索引页

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

@@ -1,83 +0,0 @@
-# base +dashboard-arrange
-
-> **前置条件：** 先阅读 [lark-base-dashboard.md](lark-base-dashboard.md) 了解整体工作流
-
-自动重新排列仪表盘组件布局。服务端根据组件数量和类型进行智能布局优化。
-
-## 使用场景
-
-| 场景 | 说明 |
-|------|------|
-| **从 0 到 1 搭建后** | 使用 `+dashboard-create` 和 `+dashboard-block-create` 创建仪表盘后，默认布局可能不够工整美观，推荐使用本命令做一次整体重排 |
-| **用户明确要求** | 用户主动要求对已有仪表盘进行布局重排或美化时 |
-
-> [!CAUTION]
-> - **不建议**在已有仪表盘上自动调用此命令，除非用户明确要求
-> - 排列结果是**服务端智能推荐**，不一定完全符合用户预期
-> - 无法指定具体位置（如"第一排放 A，第二排放 B"），排列逻辑是**自适应**的
-
-## 推荐命令
-
-```bash
-# 基础用法
-lark-cli base +dashboard-arrange \
-  --base-token xxx \
-  --dashboard-id blk_xxx
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token |
-| `--dashboard-id <id>` | 是 | 仪表盘 ID |
-| `--user-id-type <type>` | 否 | 用户 ID 类型：open_id / union_id / user_id |
-| `--dry-run` | 否 | 预览 API 调用，不执行 |
-
-## 返回示例
-
-```json
-{
-  "dashboard_id": "blk_xxx",
-  "name": "数据分析",
-  "blocks": [
-    {
-      "block_id": "chtbxxxx",
-      "block_name": "总销售额",
-      "block_type": "statistics",
-      "layout": {
-        "x": 0,
-        "y": 0,
-        "w": 6,
-        "h": 6
-      }
-    },
-    {
-      "block_id": "chtbcrxxxx",
-      "block_name": "月度趋势",
-      "block_type": "column",
-      "layout": {
-        "x": 6,
-        "y": 0,
-        "w": 6,
-        "h": 6
-      }
-    }
-  ],
-  "arranged": true
-}
-```
-
-## 返回重点
-
-| 字段 | 说明 |
-|------|------|
-| `blocks[].layout` | 重排后的布局信息，包含 x/y/w/h |
-| `arranged` | 是否重排成功 |
-
-> [!CAUTION]
-> 这是**写入操作** — 执行前必须向用户确认。
-
-## 参考
-
-- [lark-base-dashboard.md](lark-base-dashboard.md) — dashboard 模块指引

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

@@ -1,108 +0,0 @@
-# base +dashboard-block-create
-
-> **前置条件：** 先阅读 [lark-base-dashboard.md](lark-base-dashboard.md) 了解整体工作流
-> **关键：** 创建前必须阅读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解组件类型和 data_config 结构
-
-在仪表盘中创建一个组件（Block）。
-
-## 关键约束
-
-- **`type` 创建后不可修改**，创建时务必选对
-- **`data_config` 结构随 `type` 变化**，不同组件类型字段不同，**⚠️ 必须阅读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解如何构造**
-- **组件创建必须串行执行**，不能并发
-
-## 推荐命令
-
-```bash
-# 简单示例：创建一个指标卡（统计记录数）
-lark-cli base +dashboard-block-create \
-  --base-token xxx \
-  --dashboard-id blk_xxx \
-  --name "总记录数" \
-  --type statistics \
-  --data-config '{"table_name":"订单表","count_all":true}'
-
-# 文本组件示例（Markdown 富文本）
-lark-cli base +dashboard-block-create \
-  --base-token xxx \
-  --dashboard-id blk_xxx \
-  --name "说明文字" \
-  --type text \
-  --data-config '{"text":"# 标题\n## 副标题\n**加粗** *斜体* ~~删除~~\n1. 列表1\n2. 列表2"}'
-
-# 复杂配置用文件传入
-lark-cli base +dashboard-block-create \
-  --base-token xxx \
-  --dashboard-id blk_xxx \
-  --name "销售额趋势" \
-  --type line \
-  --data-config @config.json
-```
-
-完整流程参考 [lark-base-dashboard.md](lark-base-dashboard.md) 的「场景 1：从 0 到 1 创建仪表盘」
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token |
-| `--dashboard-id <id>` | 是 | 仪表盘 ID（从 `+dashboard-list/get` 获取） |
-| `--name <name>` | **是** | 组件名称（允许重名） |
-| `--type <type>` | **是** | 组件类型，见下方枚举值。**不同 type 对应不同的 data_config 结构**，常用：`column`(柱状图)、`line`(折线图)、`pie`(饼图)、`statistics`(指标卡)、`text`(文本) |
-| `--data-config <json>` | 否 | 数据配置 JSON，**结构随 type 变化**。**⚠️ 必须阅读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解如何构造**。创建时会做本地校验，更新时由后端校验 |
-| `--user-id-type <type>` | 否 | 用户 ID 类型，filter 涉及人员字段时使用 |
-| `--dry-run` | 否 | 预览 API 调用，不执行 |
-
-### type 枚举值
-
-| 值 | 说明 |
-|----|------|
-| `column` | 柱状图 |
-| `bar` | 条形图 |
-| `line` | 折线图 |
-| `pie` | 饼图 |
-| `ring` | 环形图 |
-| `area` | 面积图 |
-| `combo` | 组合图 |
-| `scatter` | 散点图 |
-| `funnel` | 漏斗图 |
-| `wordCloud` | 词云 |
-| `radar` | 雷达图 |
-| `statistics` | 指标卡 |
-| `text` | 文本（支持 Markdown） |
-
-## 返回示例
-
-```json
-{
-  "block": {
-    "block_id": "chtxxxxxxxx",
-    "name": "总记录数",
-    "type": "statistics",
-    "data_config": {
-      "table_name": "电商交易明细",
-      "count_all": true
-    }
-  },
-  "created": true
-}
-```
-
-## 返回重点
-
-| 字段 | 说明 |
-|------|------|
-| `block.block_id` | 组件 ID，后续编辑/删除需要用到，务必记录 |
-| `block.name` | 组件名称 |
-| `block.type` | 组件类型 |
-| `block.data_config` | 实际创建的数据配置（可能包含后端自动添加的默认值）|
-| `created` | 是否创建成功 |
-
-> [!CAUTION]
-> 这是**写入操作** — 执行前必须向用户确认。
-
-
-## 参考
-
-- [lark-base-dashboard.md](lark-base-dashboard.md) — dashboard 模块指引
-- [dashboard-block-data-config.md](dashboard-block-data-config.md) — data_config 结构、图表类型、filter 规则

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

@@ -1,46 +0,0 @@
-# base +dashboard-block-delete
-
-> **前置条件：** 先阅读 [lark-base-dashboard.md](lark-base-dashboard.md) 了解整体工作流。
-
-删除仪表盘中的一个组件（Block），不可恢复。
-
-## 推荐命令
-
-```bash
-lark-cli base +dashboard-block-delete \
-  --base-token bascn***************CtadY \
-  --dashboard-id blkxxx \
-  --block-id chtxxxxxxxx
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token |
-| `--dashboard-id <id>` | 是 | 仪表盘 ID |
-| `--block-id <id>` | 是 | Block ID |
-| `--dry-run` | 否 | 预览 API 调用，不执行 |
-
-## 返回示例
-
-```json
-{
-  "block_id": "chtxxxxxxxx",
-  "deleted": true
-}
-```
-
-## 返回重点
-
-| 字段 | 说明 |
-|------|------|
-| `block_id` | 被删除的组件 ID |
-| `deleted` | 是否删除成功 |
-
-> [!CAUTION]
-> 这是**写入操作**且**不可逆** — 执行前必须向用户确认。
-
-## 参考
-
-- [lark-base-dashboard.md](lark-base-dashboard.md) — dashboard 模块指引