chore: release v1.0.77 (#2051)

--slide-id used the cobra StringArray flag type, which only accepts
repeated flags and does not split comma-separated values, unlike
--slide-number (int_array -> cobra IntSlice) which already supported
CSV input. This made the two selector flags inconsistent.

Switch --slide-id to the string_slice flag type (cobra StringSlice),
which natively supports both comma-separated and repeated values, and
update the flag readers from StrArray to StrSlice. normalizeSlideIDs
already trims/dedupes/filters blanks, and
validateSlidesScreenshotSelectorLimit already caps the combined
selector count, so both continue to apply unchanged to CSV input.

Add tests covering --slide-id CSV parsing, whitespace/duplicate
normalization, and the >10 selector limit via CSV, mirroring the
existing --slide-number coverage.

Address review feedback:
- Fix "comma-separate" -> "comma-separated" wording in the --slide-id
  flag description (CodeRabbit).
- Set LARKSUITE_CLI_CONFIG_DIR to t.TempDir() in the new screenshot
  tests, per the AGENTS.md testing convention, so local configuration
  state cannot leak into or be modified by the suite.
- Add a dry-run E2E test (tests/cli_e2e/slides) that pins --slide-id
  CSV parsing through the built CLI binary and asserts the emitted
  slide_ids request body, per the AGENTS.md dry-run E2E requirement
  for shortcut flag/param changes.
- Update the lark-slides skill reference to document that --slide-id
  and --slide-number both accept comma-separated values, not just
  repeated flags, so agents can discover the new syntax.

.github/workflows/release.yml

@@ -9,7 +9,40 @@ permissions:
   contents: read
 
 jobs:
-  goreleaser:
+  preflight:
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: '22.14.0'
+
+      - name: Validate tag and commit
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          node scripts/release-preflight.js --tag "$TAG"
+          git fetch origin main
+          HEAD_SHA="$(git rev-parse --verify 'HEAD^{commit}')"
+          MAIN_SHA="$(git rev-parse --verify 'FETCH_HEAD^{commit}')"
+          TAG_SHA="$(git rev-parse --verify "refs/tags/${TAG}^{commit}")"
+          if [[ "$TAG_SHA" != "$HEAD_SHA" ]]; then
+            echo "Tag ${TAG} does not resolve to the checked-out HEAD commit." >&2
+            exit 1
+          fi
+          if ! git merge-base --is-ancestor "$HEAD_SHA" "$MAIN_SHA"; then
+            echo "Tag ${TAG} does not point to a commit contained in origin/main." >&2
+            exit 1
+          fi
+
+  build-release:
+    needs: preflight
     runs-on: ubuntu-22.04
     permissions:
       contents: write
@@ -26,35 +59,79 @@ jobs:
         with:
           python-version: '3.x'
 
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: '22.14.0'
+          registry-url: 'https://registry.npmjs.org'
+          package-manager-cache: false
+
+      - name: Install pinned npm
+        run: npm install --global npm@11.16.0
+
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # v6
         with:
           version: '~> v2'
           args: release --clean
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Include release checksums
+        run: |
+          set -euo pipefail
+          test -s dist/checksums.txt
+          (cd dist && sha256sum --check checksums.txt)
+          cp dist/checksums.txt checksums.txt
+
+      - name: Collect release asset
+        run: |
+          set -euo pipefail
+          mkdir npm-publish-asset
+          cp dist/*.tar.gz dist/*.zip dist/checksums.txt npm-publish-asset/
+
+      - name: Upload release asset
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: npm-publish-asset-${{ github.run_id }}
+          path: npm-publish-asset/
+          if-no-files-found: error
+          overwrite: true
 
   publish-npm:
-    needs: goreleaser
+    needs: build-release
     runs-on: ubuntu-22.04
+    environment: npm-production
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
         with:
-          node-version: '20'
+          node-version: '22.14.0'
           registry-url: 'https://registry.npmjs.org'
+          package-manager-cache: false
 
-      - name: Download checksums from release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install pinned npm
+        run: npm install --global npm@11.16.0
+
+      - name: Download release asset
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: npm-publish-asset-${{ github.run_id }}
+          path: npm-publish-asset
+
+      - name: Verify npm publish asset
         run: |
           set -euo pipefail
-          TAG="${GITHUB_REF_NAME}"
-          gh release download "${TAG}" --pattern checksums.txt --dir .
-          test -s checksums.txt || { echo "checksums.txt missing or empty for ${TAG}"; exit 1; }
+          (cd npm-publish-asset && sha256sum --check checksums.txt)
+          cp npm-publish-asset/checksums.txt checksums.txt
+          PACK_JSON="$(npm pack --ignore-scripts --json)"
+          PACK_FILE="$(node -e 'const p=JSON.parse(process.argv[1]); if(p.length!==1 || !p[0].filename) process.exit(1); process.stdout.write(p[0].filename)' "$PACK_JSON")"
+          test -s "$PACK_FILE"
+          tar -tzf "$PACK_FILE" | grep -qx 'package/checksums.txt'
+          rm "$PACK_FILE"
 
       - name: Publish to npm
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npm publish --access public

CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.77] - 2026-07-24
+
+### Features
+
+- introducing official card icon (#1973)
+- **apps**: validate +file-list --page-size against server (0, 200] range (#2007)
+- **apps**: support absolute and relative upload paths (#2005)
+- **slides**: fill xml-schema-quick-ref gaps that forced XSD fallback (#2026)
+- **slides**: add layout density lint for sparse/empty containers (#2022)
+- add risk-control protection (#1910)
+
+### Bug Fixes
+
+- **slides**: normalize presentation flag aliases (#2032)
+- **base**: classify +form-submit as high-risk-write (#1969)
+- **slides**: declare screenshot scope
+- **slides**: support CSV multi-value for --slide-id in screenshot (#2047)
+
+### Documentation
+
+- **skill**: clarify scope handling for query expansion (#2030)
+- **base**: clarify complete and partial updates (#1993)
+- **skills**: clarify callout child rules (#2048)
+
+### Misc
+
+- fix/task id handling (#2023)
+- fix/task search pagination (#2041)
+
+## [v1.0.75] - 2026-07-22
+
+### Features
+
+- add okr single create shortcut & skill text opti (#1941)
+- **calendar**: auto-add bot self as attendee and note user-only search (#1991)
+
+### Bug Fixes
+
+- **base**: improve table shortcut behavior & guidance (#1803)
+- issue#1935 & whiteboard shortcut reformat (#1980)
+- remove legacy shortcut (#1997)
+- **e2e**: inject shared credentials by identity (#1995)
+
+### Documentation
+
+- **skill**: describe html5 block xml usage (#1380)
+- clarify fetch metadata and user cites (#1981)
+- add topic move collector workflow (#1473)
+- update lark doc HTML size limit (#2001)
+- **base**: align record write schema guidance (#2000)
+
+### Tests
+
+- **e2e**: declare request identities explicitly (#2004)
+
+### Misc
+
+- harden npm release publishing (#1918)
+
 ## [v1.0.74] - 2026-07-21
 
 ### Features
@@ -1608,6 +1667,8 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.77]: https://github.com/larksuite/cli/releases/tag/v1.0.77
+[v1.0.75]: https://github.com/larksuite/cli/releases/tag/v1.0.75
 [v1.0.74]: https://github.com/larksuite/cli/releases/tag/v1.0.74
 [v1.0.73]: https://github.com/larksuite/cli/releases/tag/v1.0.73
 [v1.0.72]: https://github.com/larksuite/cli/releases/tag/v1.0.72

Makefile

@@ -51,7 +51,7 @@ script-test:
 	bash scripts/resolve-changed-from.test.sh
 	bash scripts/ci-workflow.test.sh
 	bash scripts/semantic-review-workflow.test.sh
-	$(NODE) --test scripts/e2e_domains.test.js scripts/fetch_e2e_tat.test.js scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js
+	$(NODE) --test scripts/e2e_domains.test.js scripts/fetch_e2e_tat.test.js scripts/install.test.js scripts/release-preflight.test.js scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js
 
 # ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta

README.md

@@ -285,6 +285,29 @@ To reduce these risks, the tool enables default security protections at multiple
 
 We recommend using the Lark/Feishu bot integrated with this tool as a private conversational assistant. Do not add it to group chats or allow other users to interact with it, to avoid abuse of permissions or data leakage.
 
+To reduce the security risks associated with access token theft, the CLI sends a minimal set of risk-control signals with OpenAPI requests made to exact official Feishu/Lark HTTPS domains. These signals are used to help identify anomalous API activity. This protection is enabled by default. The information sent is limited to:
+
+- Operating system type: macOS, Windows, or Linux
+- Device hardware model: for example, Mac17,9
+
+To disable this protection for the current workspace, run:
+
+```bash
+lark-cli config risk-control off
+```
+
+To enable this protection for the current workspace, run:
+
+```bash
+lark-cli config risk-control on
+```
+
+To restore the default policy for the current workspace, run:
+
+```bash
+lark-cli config risk-control default
+```
+
 Please fully understand all usage risks. By using this tool, you are deemed to voluntarily assume all related responsibilities.
 
 ## Star History

README.zh.md

@@ -286,6 +286,29 @@ lark-cli schema im.messages.delete
 
 我们建议您将对接本工具的飞书机器人作为私人对话助手使用，请勿将其拉入群聊或允许其他用户与其交互，以避免权限被滥用或数据泄露。
 
+为降低访问令牌被盗用后的安全风险，CLI 在向飞书/Lark 官方 HTTPS 精确域名发起 OpenAPI 请求时，会随请求发送一组最小化的风控信号，用于辅助识别异常调用行为。该保护默认开启，发送的信息仅包括：
+
+- 操作系统类型：macOS、Windows 或 Linux
+- 设备的硬件产品型号：例如 Mac17,9
+
+如需让当前 workspace 退出该保护，可执行以下命令：
+
+```bash
+lark-cli config risk-control off
+```
+
+如需开启当前 workspace 的保护，可执行以下命令：
+
+```bash
+lark-cli config risk-control on
+```
+
+恢复当前 workspace 默认策略可执行：
+
+```bash
+lark-cli config risk-control default
+```
+
 请您充分知悉全部使用风险，使用本工具即视为您自愿承担相关所有责任。
 
 ## Star History

cmd/config/config.go

@@ -31,6 +31,7 @@ func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(NewCmdConfigShow(f, nil))
 	cmd.AddCommand(NewCmdConfigDefaultAs(f))
 	cmd.AddCommand(NewCmdConfigStrictMode(f))
+	cmd.AddCommand(NewCmdConfigRiskControl(f))
 	cmd.AddCommand(NewCmdConfigPolicy(f))
 	cmd.AddCommand(NewCmdConfigPlugins(f))
 	cmd.AddCommand(NewCmdConfigKeychainDowngrade(f))

cmd/config/risk_control.go

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+)
+
+// NewCmdConfigRiskControl creates the workspace risk-control policy command.
+func NewCmdConfigRiskControl(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "risk-control [on|off|default]",
+		Short: "Manage workspace account-protection policy",
+		Long: `View or set the account-protection risk-control policy for this workspace.
+
+Account protection is on by default. Use off to opt this workspace out, on to
+opt it back in explicitly, or default to remove the explicit preference.`,
+		Args: cobra.MaximumNArgs(1),
+		// This is persistent workspace policy, not credential management.
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			cmd.SilenceUsage = true
+			return nil
+		},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			config, err := core.LoadOrNotConfigured()
+			if err != nil {
+				return err
+			}
+			if len(args) == 0 {
+				printRiskControl(f, config)
+				return nil
+			}
+
+			switch args[0] {
+			case "on":
+				enabled := true
+				config.RiskControl = &enabled
+			case "off":
+				enabled := false
+				config.RiskControl = &enabled
+			case "default":
+				config.RiskControl = nil
+			default:
+				return errs.NewValidationError(errs.SubtypeInvalidArgument,
+					"invalid risk-control value %q, valid values: on | off | default", args[0])
+			}
+
+			if err := core.SaveMultiAppConfig(config); err != nil {
+				return errs.NewInternalError(errs.SubtypeStorage,
+					"failed to save risk-control policy: %v", err).WithCause(err)
+			}
+			fmt.Fprintf(f.IOStreams.ErrOut, "Risk control set to %s (workspace)\n", args[0])
+			return nil
+		},
+	}
+	cmdutil.SetRisk(cmd, cmdutil.RiskWrite)
+	return cmd
+}
+
+func printRiskControl(f *cmdutil.Factory, config *core.MultiAppConfig) {
+	source := "default"
+	if config.RiskControl != nil {
+		source = "workspace"
+	}
+	fmt.Fprintf(f.IOStreams.Out, "risk-control: %s (source: %s)\n", riskControlState(config.RiskControlEnabled()), source)
+}
+
+func riskControlState(enabled bool) string {
+	if enabled {
+		return "on"
+	}
+	return "off"
+}

cmd/config/risk_control_test.go

@@ -0,0 +1,130 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+)
+
+func TestRiskControlWorkspacePolicy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	config := &core.MultiAppConfig{Apps: []core.AppConfig{{
+		AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
+	}}}
+	if err := core.SaveMultiAppConfig(config); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	cmd := NewCmdConfigRiskControl(f)
+	cmd.SetArgs([]string{"off"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("set off: %v", err)
+	}
+	loaded, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded.RiskControl == nil || *loaded.RiskControl {
+		t.Fatalf("RiskControl = %v, want explicit false", loaded.RiskControl)
+	}
+	if !strings.Contains(stderr.String(), "set to off") {
+		t.Fatalf("stderr = %q", stderr.String())
+	}
+
+	stdout.Reset()
+	cmd = NewCmdConfigRiskControl(f)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("show: %v", err)
+	}
+	if got := stdout.String(); got != "risk-control: off (source: workspace)\n" {
+		t.Fatalf("stdout = %q", got)
+	}
+
+	cmd = NewCmdConfigRiskControl(f)
+	cmd.SetArgs([]string{"on"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("set on: %v", err)
+	}
+	loaded, err = core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded.RiskControl == nil || !*loaded.RiskControl {
+		t.Fatalf("RiskControl = %v, want explicit true", loaded.RiskControl)
+	}
+
+	cmd = NewCmdConfigRiskControl(f)
+	cmd.SetArgs([]string{"default"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("reset default: %v", err)
+	}
+	loaded, err = core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded.RiskControl != nil {
+		t.Fatalf("RiskControl = %v, want nil", loaded.RiskControl)
+	}
+
+	stdout.Reset()
+	cmd = NewCmdConfigRiskControl(f)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("show default: %v", err)
+	}
+	if got := stdout.String(); got != "risk-control: on (source: default)\n" {
+		t.Fatalf("stdout = %q", got)
+	}
+}
+
+func TestRiskControlWorkspacePolicyRejectsInvalidValue(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{Apps: []core.AppConfig{{
+		AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
+	}}}); err != nil {
+		t.Fatal(err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	cmd := NewCmdConfigRiskControl(f)
+	cmd.SetArgs([]string{"invalid"})
+	err := cmd.Execute()
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("error = %T %v, want *errs.ValidationError", err, err)
+	}
+	if validationErr.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype = %q, want %q", validationErr.Subtype, errs.SubtypeInvalidArgument)
+	}
+}
+
+func TestRiskControlWorkspacePolicyAllowedWithExternalCredentials(t *testing.T) {
+	f := newConfigFactoryWithExternalProvider(t)
+	config := &core.MultiAppConfig{Apps: []core.AppConfig{{
+		AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
+	}}}
+	if err := core.SaveMultiAppConfig(config); err != nil {
+		t.Fatal(err)
+	}
+
+	cmd := NewCmdConfig(f)
+	cmd.SetArgs([]string{"risk-control", "off"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("set off with external credentials: %v", err)
+	}
+
+	loaded, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded.RiskControl == nil || *loaded.RiskControl {
+		t.Fatalf("RiskControl = %v, want explicit false", loaded.RiskControl)
+	}
+}

internal/cmdutil/factory_default.go

@@ -22,6 +22,7 @@ import (
 	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/riskcontrol"
 	_ "github.com/larksuite/cli/internal/security/contentsafety" // register content safety provider
 	"github.com/larksuite/cli/internal/transport"
 	_ "github.com/larksuite/cli/internal/vfs/localfileio" // register default FileIO provider
@@ -33,7 +34,7 @@ import (
 //	Phase 1: HttpClient (no credential dependency)
 //	Phase 2: Credential (sole data source for account info)
 //	Phase 3: Config derived from Credential
-//	Phase 4: LarkClient derived from Credential
+//	Phase 4: LarkClient derived from Credential and workspace policy
 func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 	streams = normalizeStreams(streams)
 	f := &Factory{
@@ -54,9 +55,10 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 
 	// Phase 0: FileIO provider (no dependency)
 	f.FileIOProvider = fileio.GetProvider()
+	workspaceConfig := core.NewConfigSnapshot()
 
 	// Phase 1: HttpClient (no credential dependency)
-	f.HttpClient = cachedHttpClientFunc(f)
+	f.HttpClient = cachedHttpClientFunc(f, workspaceConfig)
 
 	// Phase 2: Credential (sole data source)
 	// Keychain is read via closure so callers can replace f.Keychain after construction.
@@ -67,7 +69,7 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 		ErrOut:     f.IOStreams.ErrOut,
 	})
 
-	// Phase 3: Config derived from Credential via an explicit conversion boundary.
+	// Phase 3: Runtime config contains resolved account data only.
 	f.Config = sync.OnceValues(func() (*core.CliConfig, error) {
 		acct, err := f.Credential.ResolveAccount(context.Background())
 		if err != nil {
@@ -78,8 +80,9 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 		return cfg, nil
 	})
 
-	// Phase 4: LarkClient from Credential (placeholder AppSecret)
-	f.LarkClient = cachedLarkClientFunc(f)
+	// Phase 4: LarkClient composes account data and workspace policy at the SDK
+	// transport boundary.
+	f.LarkClient = cachedLarkClientFunc(f, workspaceConfig)
 
 	return f
 }
@@ -108,13 +111,16 @@ func safeRedirectPolicy(req *http.Request, via []*http.Request) error {
 // .StderrIsTerminal field, which tests set directly.
 var warnIfProxied = transport.WarnIfProxied
 
-func cachedHttpClientFunc(f *Factory) func() (*http.Client, error) {
+func cachedHttpClientFunc(f *Factory, workspaceConfig workspaceConfigSource) func() (*http.Client, error) {
 	return sync.OnceValues(func() (*http.Client, error) {
 		if f.IOStreams.StderrIsTerminal {
 			warnIfProxied(f.IOStreams.ErrOut)
 		}
 
+		hostSignalSource := resolveSDKHostSignalSource(workspaceConfig)
+
 		var rt http.RoundTripper = transport.Shared()
+		rt = riskcontrol.NewTransport(rt, hostSignalSource)
 		rt = &RetryTransport{Base: rt}
 		rt = &SecurityHeaderTransport{Base: rt}
 		rt = &auth.SecurityPolicyTransport{Base: rt} // Add our global response interceptor
@@ -128,7 +134,7 @@ func cachedHttpClientFunc(f *Factory) func() (*http.Client, error) {
 	})
 }
 
-func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
+func cachedLarkClientFunc(f *Factory, workspaceConfig workspaceConfigSource) func() (*lark.Client, error) {
 	return sync.OnceValues(func() (*lark.Client, error) {
 		acct, err := f.Credential.ResolveAccount(context.Background())
 		if err != nil {
@@ -142,8 +148,15 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 		if f.IOStreams.StderrIsTerminal {
 			warnIfProxied(f.IOStreams.ErrOut)
 		}
+		hostSignalSource := resolveSDKHostSignalSource(workspaceConfig)
+		var sdkBase http.RoundTripper = transport.Shared()
+		// The innermost SDK boundary always strips reserved host-signal headers;
+		// a nil source makes it strip-only when workspace policy disables signal
+		// collection.
+		sdkBase = riskcontrol.NewTransport(sdkBase, hostSignalSource)
+		sdkTransport := wrapSDKTransport(sdkBase)
 		opts = append(opts, lark.WithHttpClient(&http.Client{
-			Transport:     buildSDKTransport(),
+			Transport:     sdkTransport,
 			CheckRedirect: safeRedirectPolicy,
 		}))
 		ep := core.ResolveEndpoints(acct.Brand)
@@ -152,9 +165,8 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 	})
 }
 
-func buildSDKTransport() http.RoundTripper {
-	var sdkTransport http.RoundTripper = transport.Shared()
-	sdkTransport = &RetryTransport{Base: sdkTransport}
+func wrapSDKTransport(next http.RoundTripper) http.RoundTripper {
+	var sdkTransport http.RoundTripper = &RetryTransport{Base: next}
 	sdkTransport = &UserAgentTransport{Base: sdkTransport}
 	sdkTransport = &BuildHeaderTransport{Base: sdkTransport}
 	sdkTransport = &auth.SecurityPolicyTransport{Base: sdkTransport}

internal/cmdutil/factory_http_test.go

@@ -6,10 +6,15 @@ package cmdutil
 import (
 	"io"
 	"testing"
+
+	"github.com/larksuite/cli/internal/core"
 )
 
 func TestCachedHttpClientFunc_ReturnsSameInstance(t *testing.T) {
-	fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{ErrOut: io.Discard}})
+	isEnabled := false
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "test-app"})
+	f.IOStreams.ErrOut = io.Discard
+	fn := cachedHttpClientFunc(f, staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &isEnabled}})
 
 	c1, err := fn()
 	if err != nil {
@@ -29,7 +34,10 @@ func TestCachedHttpClientFunc_ReturnsSameInstance(t *testing.T) {
 }
 
 func TestCachedHttpClientFunc_HasTimeout(t *testing.T) {
-	fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{ErrOut: io.Discard}})
+	isEnabled := false
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "test-app"})
+	f.IOStreams.ErrOut = io.Discard
+	fn := cachedHttpClientFunc(f, staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &isEnabled}})
 	c, _ := fn()
 	if c.Timeout == 0 {
 		t.Error("expected non-zero timeout")
@@ -37,7 +45,10 @@ func TestCachedHttpClientFunc_HasTimeout(t *testing.T) {
 }
 
 func TestCachedHttpClientFunc_HasRedirectPolicy(t *testing.T) {
-	fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{ErrOut: io.Discard}})
+	isEnabled := false
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "test-app"})
+	f.IOStreams.ErrOut = io.Discard
+	fn := cachedHttpClientFunc(f, staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &isEnabled}})
 	c, _ := fn()
 	if c.CheckRedirect == nil {
 		t.Error("expected CheckRedirect to be set (safeRedirectPolicy)")

internal/cmdutil/factory_proxy_warn_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	_ "github.com/larksuite/cli/extension/credential/env" // registers the env-backed account provider
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/envvars"
 )
 
@@ -36,13 +37,15 @@ var proxyWarnGateCases = []struct {
 // TestCachedHttpClientFunc_ProxyWarnGate verifies the http-client init path
 // invokes WarnIfProxied only when stderr is an interactive terminal.
 func TestCachedHttpClientFunc_ProxyWarnGate(t *testing.T) {
+	isEnabled := false
 	for _, tc := range proxyWarnGateCases {
 		t.Run(tc.name, func(t *testing.T) {
 			calls := installProxyWarnSpy(t)
 
-			fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{
-				ErrOut: io.Discard, StderrIsTerminal: tc.terminal,
-			}})
+			f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "test-app"})
+			f.IOStreams.ErrOut = io.Discard
+			f.IOStreams.StderrIsTerminal = tc.terminal
+			fn := cachedHttpClientFunc(f, staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &isEnabled}})
 			if _, err := fn(); err != nil {
 				t.Fatalf("http client init: %v", err)
 			}
@@ -73,7 +76,7 @@ func TestCachedLarkClientFunc_ProxyWarnGate(t *testing.T) {
 			// normalizeStreams copies the struct (out := *s), so the
 			// StderrIsTerminal field survives into f.IOStreams.
 			f := NewDefault(&IOStreams{ErrOut: io.Discard, StderrIsTerminal: tc.terminal}, InvocationContext{})
-			if _, err := cachedLarkClientFunc(f)(); err != nil {
+			if _, err := cachedLarkClientFunc(f, nil)(); err != nil {
 				t.Fatalf("lark client init: %v", err)
 			}
 

internal/cmdutil/localfile.go

@@ -0,0 +1,36 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"io/fs"
+
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// StatLocalFile returns metadata for a path in the process filesystem namespace.
+// It is intended for advisory validation; callers must validate the opened file
+// again before using its contents.
+func StatLocalFile(path string) (fs.FileInfo, error) {
+	localPath, err := validate.LocalInputPath(path)
+	if err != nil {
+		return nil, &fileio.PathValidationError{Err: err}
+	}
+	return vfs.Stat(localPath)
+}
+
+// OpenLocalFile opens a path in the process filesystem namespace.
+// Absolute and relative paths are accepted. It is the shared replacement for
+// direct os.Open/os.ReadFile use in commands that intentionally read local
+// paths outside the workspace sandbox. Callers inspect the returned descriptor
+// before reading so validation and use apply to the same opened file.
+func OpenLocalFile(path string) (fs.File, error) {
+	localPath, err := validate.LocalInputPath(path)
+	if err != nil {
+		return nil, &fileio.PathValidationError{Err: err}
+	}
+	return vfs.Open(localPath)
+}

internal/cmdutil/localfile_test.go

@@ -0,0 +1,96 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"errors"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+func TestOpenLocalFile_AcceptsAbsoluteAndParentRelativePaths(t *testing.T) {
+	root := t.TempDir()
+	workDir := filepath.Join(root, "work")
+	if err := os.Mkdir(workDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(root, "input.txt")
+	if err := os.WriteFile(path, []byte("content"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	TestChdir(t, workDir)
+
+	for _, input := range []string{path, filepath.Join("..", "input.txt")} {
+		f, err := OpenLocalFile(input)
+		if err != nil {
+			t.Fatalf("OpenLocalFile(%q) error = %v", input, err)
+		}
+		got, readErr := io.ReadAll(f)
+		closeErr := f.Close()
+		if readErr != nil || closeErr != nil || string(got) != "content" {
+			t.Fatalf("OpenLocalFile(%q) content=%q read=%v close=%v", input, got, readErr, closeErr)
+		}
+	}
+}
+
+func TestOpenLocalFile_RejectsInvalidInput(t *testing.T) {
+	if _, err := OpenLocalFile("input\n.txt"); !errors.Is(err, fileio.ErrPathValidation) {
+		t.Fatalf("OpenLocalFile() error = %v, want ErrPathValidation", err)
+	}
+}
+
+func TestStatLocalFile_ReturnsMetadata(t *testing.T) {
+	info, err := StatLocalFile(t.TempDir())
+	if err != nil {
+		t.Fatalf("StatLocalFile() error = %v", err)
+	}
+	if !info.IsDir() {
+		t.Fatalf("StatLocalFile() mode = %v, want directory", info.Mode())
+	}
+}
+
+func TestOpenLocalFile_DoesNotStatBeforeOpen(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "input.txt")
+	if err := os.WriteFile(path, []byte("content"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	previous := vfs.DefaultFS
+	counting := &countingLocalFileFS{FS: previous}
+	vfs.DefaultFS = counting
+	t.Cleanup(func() { vfs.DefaultFS = previous })
+
+	f, err := OpenLocalFile(path)
+	if err != nil {
+		t.Fatalf("OpenLocalFile() error = %v", err)
+	}
+	if err := f.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if counting.openCalls != 1 || counting.statCalls != 0 {
+		t.Fatalf("OpenLocalFile() calls: Open=%d Stat=%d, want Open=1 Stat=0", counting.openCalls, counting.statCalls)
+	}
+}
+
+type countingLocalFileFS struct {
+	vfs.FS
+	openCalls int
+	statCalls int
+}
+
+func (f *countingLocalFileFS) Open(name string) (*os.File, error) {
+	f.openCalls++
+	return f.FS.Open(name)
+}
+
+func (f *countingLocalFileFS) Stat(name string) (fs.FileInfo, error) {
+	f.statCalls++
+	return f.FS.Stat(name)
+}

internal/cmdutil/risk_control.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/riskcontrol"
+)
+
+type workspaceConfigSource interface {
+	MultiAppConfig() (*core.MultiAppConfig, error)
+}
+
+// resolveSDKHostSignalSource applies workspace policy at the SDK transport
+// boundary.
+func resolveSDKHostSignalSource(config workspaceConfigSource) riskcontrol.Source {
+	if config == nil {
+		return nil
+	}
+	workspace, configErr := config.MultiAppConfig()
+	// Default-on means an existing config with no explicit preference. Absent
+	// or unreadable config cannot authorize host-signal collection.
+	if configErr != nil || !workspace.RiskControlEnabled() {
+		return nil
+	}
+	return riskcontrol.NewHostSource()
+}

internal/cmdutil/risk_control_test.go

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/larksuite/cli/internal/core"
+)
+
+type staticWorkspaceConfig struct {
+	config *core.MultiAppConfig
+	err    error
+}
+
+func (s staticWorkspaceConfig) MultiAppConfig() (*core.MultiAppConfig, error) {
+	return s.config, s.err
+}
+
+func TestResolveSDKHostSignalSource(t *testing.T) {
+	disabled := false
+	tests := []struct {
+		name       string
+		config     workspaceConfigSource
+		wantSource bool
+	}{
+		{name: "workspace default on", config: staticWorkspaceConfig{config: &core.MultiAppConfig{}}, wantSource: true},
+		{name: "workspace opt-out", config: staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &disabled}}},
+		{name: "missing config", config: staticWorkspaceConfig{err: errors.New("file does not exist")}},
+		{name: "unreadable config", config: staticWorkspaceConfig{err: errors.New("permission denied")}},
+		{name: "nil config value", config: staticWorkspaceConfig{}},
+		{name: "nil config source"},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			got := resolveSDKHostSignalSource(test.config)
+			if (got != nil) != test.wantSource {
+				t.Fatalf("resolveSDKHostSignalSource() = %T, wantSource %t", got, test.wantSource)
+			}
+		})
+	}
+}

internal/cmdutil/transport_test.go

@@ -15,6 +15,7 @@ import (
 
 	exttransport "github.com/larksuite/cli/extension/transport"
 	internalauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/riskcontrol"
 )
 
 type roundTripFunc func(*http.Request) (*http.Response, error)
@@ -91,13 +92,13 @@ func TestRetryTransport_DefaultNoRetry(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// buildSDKTransport chain composition
+// wrapSDKTransport chain composition
 // ---------------------------------------------------------------------------
 
-func TestBuildSDKTransport_IncludesRetryTransport(t *testing.T) {
-	transport := buildSDKTransport()
+func TestWrapSDKTransport_IncludesRetryTransport(t *testing.T) {
+	transport := wrapSDKTransport(riskcontrol.NewTransport(http.DefaultTransport, nil))
 
-	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → Base
+	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → RiskControl → Base
 	sec, ok := transport.(*internalauth.SecurityPolicyTransport)
 	if !ok {
 		t.Fatalf("outer transport type = %T, want *auth.SecurityPolicyTransport", transport)
@@ -110,18 +111,23 @@ func TestBuildSDKTransport_IncludesRetryTransport(t *testing.T) {
 	if !ok {
 		t.Fatalf("layer after BuildHeader = %T, want *UserAgentTransport", bh.Base)
 	}
-	if _, ok := ua.Base.(*RetryTransport); !ok {
+	retry, ok := ua.Base.(*RetryTransport)
+	if !ok {
 		t.Fatalf("inner transport type = %T, want *RetryTransport", ua.Base)
 	}
+	if _, ok := retry.Base.(*riskcontrol.Transport); !ok {
+		t.Fatalf("layer after Retry = %T, want *riskcontrol.Transport", retry.Base)
+	}
 }
 
-func TestBuildSDKTransport_WithExtension(t *testing.T) {
+func TestWrapSDKTransport_WithExtension(t *testing.T) {
+	previous := exttransport.GetProvider()
 	exttransport.Register(&stubTransportProvider{})
-	t.Cleanup(func() { exttransport.Register(nil) })
+	t.Cleanup(func() { exttransport.Register(previous) })
 
-	transport := buildSDKTransport()
+	transport := wrapSDKTransport(riskcontrol.NewTransport(http.DefaultTransport, nil))
 
-	// Chain: extensionMiddleware → SecurityPolicy → BuildHeader → UserAgent → Retry → Base
+	// Chain: extensionMiddleware → SecurityPolicy → BuildHeader → UserAgent → Retry → RiskControl → Base
 	mid, ok := transport.(*extensionMiddleware)
 	if !ok {
 		t.Fatalf("outer transport type = %T, want *extensionMiddleware", transport)
@@ -138,17 +144,23 @@ func TestBuildSDKTransport_WithExtension(t *testing.T) {
 	if !ok {
 		t.Fatalf("layer after BuildHeader = %T, want *UserAgentTransport", bh.Base)
 	}
-	if _, ok := ua.Base.(*RetryTransport); !ok {
+	retry, ok := ua.Base.(*RetryTransport)
+	if !ok {
 		t.Fatalf("innermost transport type = %T, want *RetryTransport", ua.Base)
 	}
+	if _, ok := retry.Base.(*riskcontrol.Transport); !ok {
+		t.Fatalf("layer after Retry = %T, want *riskcontrol.Transport", retry.Base)
+	}
 }
 
-func TestBuildSDKTransport_WithoutExtension(t *testing.T) {
+func TestWrapSDKTransport_WithoutExtension(t *testing.T) {
+	previous := exttransport.GetProvider()
 	exttransport.Register(nil)
+	t.Cleanup(func() { exttransport.Register(previous) })
 
-	transport := buildSDKTransport()
+	transport := wrapSDKTransport(riskcontrol.NewTransport(http.DefaultTransport, nil))
 
-	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → Base
+	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → RiskControl → Base
 	sec, ok := transport.(*internalauth.SecurityPolicyTransport)
 	if !ok {
 		t.Fatalf("outer transport type = %T, want *auth.SecurityPolicyTransport", transport)
@@ -161,9 +173,13 @@ func TestBuildSDKTransport_WithoutExtension(t *testing.T) {
 	if !ok {
 		t.Fatalf("layer after BuildHeader = %T, want *UserAgentTransport", bh.Base)
 	}
-	if _, ok := ua.Base.(*RetryTransport); !ok {
+	retry, ok := ua.Base.(*RetryTransport)
+	if !ok {
 		t.Fatalf("inner transport type = %T, want *RetryTransport", ua.Base)
 	}
+	if _, ok := retry.Base.(*riskcontrol.Transport); !ok {
+		t.Fatalf("layer after Retry = %T, want *riskcontrol.Transport", retry.Base)
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -261,6 +277,40 @@ func (buildTamperingInterceptor) PreRoundTrip(req *http.Request) func(*http.Resp
 	return nil
 }
 
+type riskHeaderTamperingInterceptor struct{}
+
+func (riskHeaderTamperingInterceptor) PreRoundTrip(req *http.Request) func(*http.Response, error) {
+	req.Header.Set(riskcontrol.HeaderOSType, "extension-value")
+	req.Header.Set(riskcontrol.HeaderProductModel, "extension-value")
+	return nil
+}
+
+func TestWrapSDKTransport_StripsExtensionRiskHeaders(t *testing.T) {
+	previous := exttransport.GetProvider()
+	exttransport.Register(&stubTransportProvider{interceptor: riskHeaderTamperingInterceptor{}})
+	t.Cleanup(func() { exttransport.Register(previous) })
+
+	var received http.Header
+	network := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		received = req.Header.Clone()
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+	})
+	req, err := http.NewRequest(http.MethodGet, "https://open.feishu.cn/open-apis/test", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Authorization", "Bearer token")
+
+	resp, err := wrapSDKTransport(riskcontrol.NewTransport(network, nil)).RoundTrip(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if received.Get(riskcontrol.HeaderOSType) != "" || received.Get(riskcontrol.HeaderProductModel) != "" {
+		t.Fatalf("extension risk headers reached network: %v", received)
+	}
+}
+
 // TestBuildHeaderTransport_SDKChain_OverridesTamperedHeader verifies that the
 // X-Cli-Build header is force-written by BuildHeaderTransport in the SDK
 // transport chain, even when an extension tries to delete or spoof it. This
@@ -277,7 +327,7 @@ func TestBuildHeaderTransport_SDKChain_OverridesTamperedHeader(t *testing.T) {
 	exttransport.Register(&stubTransportProvider{interceptor: buildTamperingInterceptor{}})
 	t.Cleanup(func() { exttransport.Register(nil) })
 
-	// Replicate the SDK chain layering used by buildSDKTransport.
+	// Replicate the SDK chain layering used by wrapSDKTransport.
 	var base http.RoundTripper = http.DefaultTransport
 	base = &RetryTransport{Base: base}
 	base = &UserAgentTransport{Base: base}

internal/core/config.go

@@ -60,11 +60,18 @@ func (a *AppConfig) ProfileName() string {
 // MultiAppConfig is the multi-app config file format.
 type MultiAppConfig struct {
 	StrictMode  StrictMode  `json:"strictMode,omitempty"`
+	RiskControl *bool       `json:"riskControl,omitempty"`
 	CurrentApp  string      `json:"currentApp,omitempty"`
 	PreviousApp string      `json:"previousApp,omitempty"`
 	Apps        []AppConfig `json:"apps"`
 }
 
+// RiskControlEnabled resolves the workspace policy. An omitted preference
+// keeps the default-on account-protection behavior.
+func (m *MultiAppConfig) RiskControlEnabled() bool {
+	return m != nil && (m.RiskControl == nil || *m.RiskControl)
+}
+
 // CurrentAppConfig returns the currently active app config.
 // Resolution priority: profileOverride > CurrentApp field > Apps[0].
 func (m *MultiAppConfig) CurrentAppConfig(profileOverride string) *AppConfig {

internal/core/config_snapshot.go

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package core
+
+import (
+	"io/fs"
+	"sync"
+)
+
+// ConfigSnapshot lazily captures one stable view of config.json for a CLI
+// invocation. All runtime consumers share the same load result so account and
+// workspace policy resolution cannot observe different file revisions. Callers
+// must treat the returned config as read-only.
+type ConfigSnapshot struct {
+	load func() (*MultiAppConfig, error)
+}
+
+// NewConfigSnapshot creates a lazily loaded invocation-scoped config snapshot.
+func NewConfigSnapshot() *ConfigSnapshot {
+	return newConfigSnapshot(LoadMultiAppConfig)
+}
+
+func newConfigSnapshot(load func() (*MultiAppConfig, error)) *ConfigSnapshot {
+	if load == nil {
+		return &ConfigSnapshot{}
+	}
+	return &ConfigSnapshot{load: sync.OnceValues(load)}
+}
+
+// MultiAppConfig returns the captured persistent config and load error.
+func (s *ConfigSnapshot) MultiAppConfig() (*MultiAppConfig, error) {
+	if s == nil || s.load == nil {
+		return nil, fs.ErrNotExist
+	}
+	return s.load()
+}

internal/core/config_snapshot_test.go

@@ -0,0 +1,58 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package core
+
+import (
+	"errors"
+	"io/fs"
+	"testing"
+)
+
+func TestConfigSnapshotLoadsOnce(t *testing.T) {
+	calls := 0
+	want := &MultiAppConfig{}
+	snapshot := newConfigSnapshot(func() (*MultiAppConfig, error) {
+		calls++
+		return want, nil
+	})
+
+	for range 2 {
+		config, err := snapshot.MultiAppConfig()
+		if err != nil {
+			t.Fatal(err)
+		}
+		if config != want {
+			t.Fatal("snapshot returned a different config instance")
+		}
+	}
+	if calls != 1 {
+		t.Fatalf("config loads = %d, want 1", calls)
+	}
+}
+
+func TestConfigSnapshotZeroValueIsMissing(t *testing.T) {
+	config, err := (&ConfigSnapshot{}).MultiAppConfig()
+	if config != nil || !errors.Is(err, fs.ErrNotExist) {
+		t.Fatalf("MultiAppConfig() = (%v, %v), want (nil, fs.ErrNotExist)", config, err)
+	}
+}
+
+func TestConfigSnapshotCachesError(t *testing.T) {
+	calls := 0
+	want := errors.New("load failed")
+	snapshot := newConfigSnapshot(func() (*MultiAppConfig, error) {
+		calls++
+		return nil, want
+	})
+
+	for range 2 {
+		config, err := snapshot.MultiAppConfig()
+		if config != nil || !errors.Is(err, want) {
+			t.Fatalf("MultiAppConfig() = (%v, %v), want (nil, %v)", config, err, want)
+		}
+	}
+	if calls != 1 {
+		t.Fatalf("config loads = %d, want 1", calls)
+	}
+}

internal/core/config_test.go

@@ -60,7 +60,9 @@ func TestAppConfig_LangOmitEmpty(t *testing.T) {
 }
 
 func TestMultiAppConfig_RoundTrip(t *testing.T) {
+	disabled := false
 	config := &MultiAppConfig{
+		RiskControl: &disabled,
 		Apps: []AppConfig{{
 			AppId: "cli_test", AppSecret: PlainSecret("s"),
 			Brand: BrandLark, Lang: "zh", Users: []AppUser{},
@@ -84,6 +86,9 @@ func TestMultiAppConfig_RoundTrip(t *testing.T) {
 	if got.Apps[0].Brand != BrandLark {
 		t.Errorf("Brand = %q, want %q", got.Apps[0].Brand, BrandLark)
 	}
+	if got.RiskControl == nil || *got.RiskControl {
+		t.Errorf("RiskControl = %v, want explicit false", got.RiskControl)
+	}
 }
 
 func TestResolveConfigFromMulti_RejectsSecretKeyMismatch(t *testing.T) {

internal/riskcontrol/osmodel.go

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package deviceinfo collects the platform hardware product model and the
+// platform values used by device-related risk-control headers.
+package riskcontrol
+
+import (
+	"runtime"
+	"strings"
+	"sync"
+	"unicode"
+	"unicode/utf8"
+
+	"golang.org/x/net/http/httpguts"
+)
+
+// OSType is the server-side risk-control operating-system enum.
+type OSType string
+
+// OS type enum values for X-Agent-Os-Type.
+const (
+	OSTypeUnknown = "0"
+	OSTypeWindows = "1"
+	OSTypeLinux   = "2"
+	OSTypeMacOS   = "3"
+)
+
+const (
+	// TerminalTypePC is the fixed X-Agent-Terminal-Type value for the CLI.
+	TerminalTypePC = "1"
+
+	// Unknown is used when the hardware product model cannot be collected.
+	Unknown = "Unknown"
+
+	// deviceModelMaxBytes bounds the value added to X-Agent-Device-Type.
+	// Device models are short identifiers; a larger value is treated as
+	// malformed rather than truncated so the header never misrepresents it.
+	deviceModelMaxBytes = 256
+)
+
+// Snapshot contains the deliberately small risk-control signal set.
+// ProductModel is omitted when the platform cannot provide a safe value.
+type Snapshot struct {
+	OSType       OSType
+	ProductModel string
+}
+
+// Source supplies one immutable process-level snapshot.
+type Source interface {
+	Snapshot() Snapshot
+}
+
+// HostSource lazily reads host signals once, after outbound policy authorizes
+// the first request. Failed probes are cached and are not retried per request.
+type HostSource struct {
+	once      sync.Once
+	value     Snapshot
+	readModel func() string
+}
+
+// NewHostSource creates the production host signal source.
+func NewHostSource() *HostSource {
+	return &HostSource{readModel: readDeviceModel}
+}
+
+// Snapshot returns the cached host signal snapshot.
+func (s *HostSource) Snapshot() Snapshot {
+	if s == nil {
+		return Snapshot{}
+	}
+	s.once.Do(func() {
+		readModel := s.readModel
+		if readModel == nil {
+			readModel = readDeviceModel
+		}
+		s.value = Snapshot{
+			OSType:       GetOSType(OSName()),
+			ProductModel: normalizeDeviceModel(readModel()),
+		}
+	})
+	return s.value
+}
+
+// normalizeModel removes non-printable characters and returns a model only
+// when the remaining text is safe to use as an HTTP header value. Input that
+// cannot produce a valid model is rejected so Get can fall back to Unknown.
+func normalizeDeviceModel(model string) string {
+	if !utf8.ValidString(model) {
+		return ""
+	}
+	model = strings.Map(func(r rune) rune {
+		switch {
+		case r == '\r' || r == '\n' || r == '\x00':
+			return -1
+		case unicode.IsSpace(r):
+			return ' '
+		case unicode.IsPrint(r):
+			return r
+		default:
+			return -1
+		}
+	}, model)
+
+	model = strings.Join(strings.Fields(model), " ")
+
+	if model == "" || len(model) > deviceModelMaxBytes {
+		return ""
+	}
+	if !httpguts.ValidHeaderFieldValue(model) {
+		return ""
+	}
+	return model
+}
+
+// GetOSType maps a platform name to the X-Agent-Os-Type enum.
+func GetOSType(osName string) OSType {
+	switch osName {
+	case "Windows":
+		return OSTypeWindows
+	case "Linux":
+		return OSTypeLinux
+	case "MacOS":
+		return OSTypeMacOS
+	default:
+		return OSTypeUnknown
+	}
+}
+
+// OSName returns the platform name used by GetOSType.
+func OSName() string {
+	switch runtime.GOOS {
+	case "darwin":
+		return "MacOS"
+	case "windows":
+		return "Windows"
+	case "linux":
+		return "Linux"
+	default:
+		return runtime.GOOS
+	}
+}

internal/riskcontrol/osmodel_darwin.go

@@ -0,0 +1,27 @@
+//go:build darwin
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import "golang.org/x/sys/unix"
+
+// readDeviceModel reads the current product key first and falls back to the
+// legacy model key. Trying both keys is more robust than branching on a macOS
+// version because virtualized or restricted environments may expose only one.
+func readDeviceModel() string {
+	return readDarwinDeviceModel(unix.Sysctl)
+}
+
+func readDarwinDeviceModel(readSysctl func(string) (string, error)) string {
+	for _, key := range [...]string{"hw.product", "hw.model"} {
+		model, err := readSysctl(key)
+		if err == nil {
+			if model = normalizeDeviceModel(model); model != "" {
+				return model
+			}
+		}
+	}
+	return ""
+}

internal/riskcontrol/osmodel_darwin_test.go

@@ -0,0 +1,48 @@
+//go:build darwin
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"errors"
+	"reflect"
+	"testing"
+)
+
+func TestReadDarwinDeviceModelPrefersProductAndFallsBackToModel(t *testing.T) {
+	t.Run("product available", func(t *testing.T) {
+		var keys []string
+		got := readDarwinDeviceModel(func(key string) (string, error) {
+			keys = append(keys, key)
+			if key == "hw.product" {
+				return "Mac16,1", nil
+			}
+			return "", errors.New("unexpected fallback")
+		})
+		if got != "Mac16,1" {
+			t.Fatalf("model = %q, want %q", got, "Mac16,1")
+		}
+		if want := []string{"hw.product"}; !reflect.DeepEqual(keys, want) {
+			t.Fatalf("sysctl keys = %v, want %v", keys, want)
+		}
+	})
+
+	t.Run("product unavailable", func(t *testing.T) {
+		var keys []string
+		got := readDarwinDeviceModel(func(key string) (string, error) {
+			keys = append(keys, key)
+			if key == "hw.model" {
+				return "MacBookPro18,3", nil
+			}
+			return "", errors.New("not available")
+		})
+		if got != "MacBookPro18,3" {
+			t.Fatalf("model = %q, want %q", got, "MacBookPro18,3")
+		}
+		if want := []string{"hw.product", "hw.model"}; !reflect.DeepEqual(keys, want) {
+			t.Fatalf("sysctl keys = %v, want %v", keys, want)
+		}
+	})
+}

internal/riskcontrol/osmodel_linux.go

@@ -0,0 +1,17 @@
+//go:build linux
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+// readDeviceModel returns a stable device model for Linux. DMI and device-tree
+// values vary widely and can expose the host or virtualization platform when
+// the CLI runs in a container or sandbox.
+func readDeviceModel() string {
+	return readLinuxDeviceModel()
+}
+
+func readLinuxDeviceModel() string {
+	return "linux"
+}

internal/riskcontrol/osmodel_linux_test.go

@@ -0,0 +1,20 @@
+//go:build linux
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import "testing"
+
+func TestReadDeviceModelReturnsLinux(t *testing.T) {
+	if got := readDeviceModel(); got != "linux" {
+		t.Fatalf("readDeviceModel() = %q, want %q", got, "linux")
+	}
+}
+
+func TestReadLinuxDeviceModel(t *testing.T) {
+	if got := readLinuxDeviceModel(); got != "linux" {
+		t.Fatalf("readLinuxDeviceModel() = %q, want %q", got, "linux")
+	}
+}

internal/riskcontrol/osmodel_other.go

@@ -0,0 +1,11 @@
+//go:build !darwin && !windows && !linux
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+// readDeviceModel returns an empty model on unsupported platforms.
+func readDeviceModel() string {
+	return ""
+}

internal/riskcontrol/osmodel_test.go

@@ -0,0 +1,143 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"unicode"
+)
+
+func TestHostSourceCachesNonEmptyModel(t *testing.T) {
+	calls := 0
+	s := &HostSource{readModel: func() string {
+		calls++
+		return "  MacBookPro18,3\n"
+	}}
+
+	if got := s.Snapshot(); got.ProductModel != "MacBookPro18,3" {
+		t.Fatalf("first Snapshot().ProductModel = %q, want %q", got.ProductModel, "MacBookPro18,3")
+	}
+	if got := s.Snapshot(); got.ProductModel != "MacBookPro18,3" {
+		t.Fatalf("second Snapshot().ProductModel = %q, want cached model", got.ProductModel)
+	}
+	if calls != 1 {
+		t.Fatalf("read called %d times, want 1", calls)
+	}
+}
+
+func TestHostSourceCachesEmptyModel(t *testing.T) {
+	calls := 0
+	s := &HostSource{readModel: func() string {
+		calls++
+		return ""
+	}}
+
+	if got := s.Snapshot(); got.ProductModel != "" {
+		t.Fatalf("first Snapshot().ProductModel = %q, want empty", got.ProductModel)
+	}
+	if got := s.Snapshot(); got.ProductModel != "" {
+		t.Fatalf("second Snapshot().ProductModel = %q, want cached empty result", got.ProductModel)
+	}
+	if calls != 1 {
+		t.Fatalf("read called %d times, want 1", calls)
+	}
+}
+
+func TestHostSourceReadsOnceAcrossConcurrentCalls(t *testing.T) {
+	var calls atomic.Int32
+	s := &HostSource{readModel: func() string {
+		calls.Add(1)
+		return "ThinkPad X1 Carbon"
+	}}
+
+	const goroutines = 32
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+	for i := 0; i < goroutines; i++ {
+		go func() {
+			defer wg.Done()
+			snapshot := s.Snapshot()
+			if snapshot.ProductModel != "ThinkPad X1 Carbon" {
+				t.Errorf("Snapshot().ProductModel = %q, want %q", snapshot.ProductModel, "ThinkPad X1 Carbon")
+			}
+		}()
+	}
+	wg.Wait()
+
+	if got := calls.Load(); got != 1 {
+		t.Fatalf("read called %d times, want 1", got)
+	}
+}
+
+func TestNormalizeDeviceModel(t *testing.T) {
+	tests := []struct {
+		name  string
+		model string
+		want  string
+	}{
+		{name: "trims surrounding whitespace", model: "  MacBookPro18,3\n", want: "MacBookPro18,3"},
+		{name: "trims device tree terminator", model: "Raspberry Pi 5\x00", want: "Raspberry Pi 5"},
+		{name: "allows printable Unicode", model: "联想 ThinkPad X1", want: "联想 ThinkPad X1"},
+		{name: "rejects empty", model: " \t\r\n"},
+		{name: "rejects invalid UTF-8", model: string([]byte{'M', 0xff, '1'})},
+		{name: "removes CRLF", model: "model\r\nname", want: "modelname"},
+		{name: "normalizes tab", model: "model\tname", want: "model name"},
+		{name: "removes NUL", model: "model\x00name", want: "modelname"},
+		{name: "removes control character", model: "model\x1fname", want: "modelname"},
+		{name: "removes DEL", model: "model\x7fname", want: "modelname"},
+		{name: "normalizes Unicode line separator", model: "model\u2028name", want: "model name"},
+		{name: "collapses whitespace", model: "  model\t \u00a0 name  ", want: "model name"},
+		{name: "accepts maximum byte length", model: strings.Repeat("a", deviceModelMaxBytes), want: strings.Repeat("a", deviceModelMaxBytes)},
+		{name: "rejects overlong value", model: strings.Repeat("a", deviceModelMaxBytes+1)},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := normalizeDeviceModel(tt.model); got != tt.want {
+				t.Fatalf("normalizeDeviceModel(%q) = %q, want %q", tt.model, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestNormalizeDeviceModelRemovesHTTPControlBytes(t *testing.T) {
+	for value := 0; value <= 0x7f; value++ {
+		if value >= 0x20 && value < 0x7f {
+			continue
+		}
+		t.Run(fmt.Sprintf("0x%02x", value), func(t *testing.T) {
+			model := "model" + string(rune(value)) + "name"
+			want := "modelname"
+			if value != '\r' && value != '\n' && value != '\x00' && unicode.IsSpace(rune(value)) {
+				want = "model name"
+			}
+			if got := normalizeDeviceModel(model); got != want {
+				t.Fatalf("normalizeDeviceModel(%q) = %q, want %q", model, got, want)
+			}
+		})
+	}
+}
+
+func TestGetOSType(t *testing.T) {
+	tests := []struct {
+		name string
+		want OSType
+	}{
+		{name: "Windows", want: OSTypeWindows},
+		{name: "Linux", want: OSTypeLinux},
+		{name: "MacOS", want: OSTypeMacOS},
+		{name: "unknown", want: OSTypeUnknown},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := GetOSType(tt.name); got != tt.want {
+				t.Errorf("GetOSType(%q) = %q, want %q", tt.name, got, tt.want)
+			}
+		})
+	}
+}

internal/riskcontrol/osmodel_windows.go

@@ -0,0 +1,44 @@
+//go:build windows
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import "golang.org/x/sys/windows/registry"
+
+// systemInfoRegistryPaths lists registry locations in device-model lookup order.
+var systemInfoRegistryPaths = [...]string{
+	`HARDWARE\DESCRIPTION\System\BIOS`,
+	`SYSTEM\CurrentControlSet\Control\SystemInformation`,
+	`SYSTEM\HardwareConfig\Current`,
+}
+
+// readDeviceModel returns the first product name found in the Windows registry.
+func readDeviceModel() string {
+	return readWindowsDeviceModel(readWindowsRegistryModel)
+}
+
+func readWindowsRegistryModel(path string) (string, error) {
+	key, err := registry.OpenKey(registry.LOCAL_MACHINE, path, registry.READ)
+	if err != nil {
+		return "", err
+	}
+	defer key.Close()
+
+	model, _, err := key.GetStringValue("SystemProductName")
+	return model, err
+}
+
+func readWindowsDeviceModel(readRegistryModel func(string) (string, error)) string {
+	for _, path := range systemInfoRegistryPaths {
+		model, err := readRegistryModel(path)
+		if err != nil {
+			continue
+		}
+		if model = normalizeDeviceModel(model); model != "" {
+			return model
+		}
+	}
+	return ""
+}

internal/riskcontrol/osmodel_windows_test.go

@@ -0,0 +1,78 @@
+//go:build windows
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"errors"
+	"reflect"
+	"testing"
+)
+
+func TestReadWindowsDeviceModelFallback(t *testing.T) {
+	readError := errors.New("registry read failed")
+	tests := []struct {
+		name      string
+		values    map[string]string
+		errors    map[string]error
+		want      string
+		wantPaths []string
+	}{
+		{
+			name:      "first path wins",
+			values:    map[string]string{systemInfoRegistryPaths[0]: "Surface Laptop"},
+			want:      "Surface Laptop",
+			wantPaths: []string{systemInfoRegistryPaths[0]},
+		},
+		{
+			name: "read failure falls back",
+			errors: map[string]error{
+				systemInfoRegistryPaths[0]: readError,
+			},
+			values: map[string]string{
+				systemInfoRegistryPaths[1]: "ThinkPad X1 Carbon",
+			},
+			want:      "ThinkPad X1 Carbon",
+			wantPaths: systemInfoRegistryPaths[:2],
+		},
+		{
+			name: "empty normalized value falls back",
+			values: map[string]string{
+				systemInfoRegistryPaths[0]: " \r\n\x00",
+				systemInfoRegistryPaths[1]: "Latitude 7450",
+			},
+			want:      "Latitude 7450",
+			wantPaths: systemInfoRegistryPaths[:2],
+		},
+		{
+			name: "all paths fail",
+			errors: map[string]error{
+				systemInfoRegistryPaths[0]: readError,
+				systemInfoRegistryPaths[1]: readError,
+				systemInfoRegistryPaths[2]: readError,
+			},
+			wantPaths: systemInfoRegistryPaths[:],
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var paths []string
+			got := readWindowsDeviceModel(func(path string) (string, error) {
+				paths = append(paths, path)
+				if err := tt.errors[path]; err != nil {
+					return "", err
+				}
+				return tt.values[path], nil
+			})
+			if got != tt.want {
+				t.Fatalf("model = %q, want %q", got, tt.want)
+			}
+			if !reflect.DeepEqual(paths, tt.wantPaths) {
+				t.Fatalf("registry paths = %v, want %v", paths, tt.wantPaths)
+			}
+		})
+	}
+}

internal/riskcontrol/transport.go

@@ -0,0 +1,138 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/larksuite/cli/internal/core"
+	internaltransport "github.com/larksuite/cli/internal/transport"
+)
+
+const (
+	HeaderProductModel = "X-Agent-Device-Type"
+	HeaderOSType       = "X-Agent-Os-Type"
+)
+
+var restrictedHeaders = [...]string{HeaderProductModel, HeaderOSType}
+
+// Transport is the feature's final outbound boundary. It removes caller- or
+// extension-supplied signal headers first and writes trusted values only after
+// authorizing an official SDK origin and authentication state.
+type Transport struct {
+	next   http.RoundTripper
+	source Source
+}
+
+// NewTransport creates the final SDK outbound policy boundary. A nil source
+// disables collection and injection while preserving restricted-header
+// stripping for opt-out and extension-credential requests.
+func NewTransport(next http.RoundTripper, source Source) *Transport {
+	if next == nil {
+		next = internaltransport.Fallback()
+	}
+	return &Transport{
+		next:   next,
+		source: source,
+	}
+}
+
+// RoundTrip implements http.RoundTripper.
+func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error) {
+	req = req.Clone(req.Context())
+	if req.Header == nil {
+		req.Header = make(http.Header)
+	}
+	stripRestrictedHeaders(req.Header)
+
+	if t.source != nil && t.routeAllowsSignals(req) {
+		snapshot := t.source.Snapshot()
+		if isSupportedOSType(snapshot.OSType) {
+			req.Header.Set(HeaderOSType, string(snapshot.OSType))
+		}
+		if model := normalizeDeviceModel(snapshot.ProductModel); model != "" {
+			req.Header.Set(HeaderProductModel, model)
+		}
+	}
+	return t.next.RoundTrip(req)
+}
+
+func isSupportedOSType(value OSType) bool {
+	switch value {
+	case OSTypeWindows, OSTypeLinux, OSTypeMacOS:
+		return true
+	default:
+		return false
+	}
+}
+
+func stripRestrictedHeaders(header http.Header) {
+	for name := range header {
+		for _, restricted := range restrictedHeaders {
+			if strings.EqualFold(name, restricted) {
+				delete(header, name)
+				break
+			}
+		}
+	}
+}
+
+type origin struct {
+	scheme string
+	host   string
+	port   string
+}
+
+var officialFeishuOrigins = [...]origin{
+	apiOrigin(core.BrandFeishu, core.ResolveEndpoints(core.BrandFeishu).Open),
+	apiOrigin(core.BrandLark, core.ResolveEndpoints(core.BrandLark).Open),
+	apiOrigin(core.BrandFeishu, core.ResolveEndpoints(core.BrandFeishu).Accounts),
+	apiOrigin(core.BrandLark, core.ResolveEndpoints(core.BrandLark).Accounts),
+}
+
+func (t *Transport) routeAllowsSignals(req *http.Request) bool {
+	if req == nil || req.URL == nil {
+		return false
+	}
+	return isOfficialFeishuOrigin(originOf(req.URL))
+}
+
+func originOf(value *url.URL) origin {
+	if value == nil {
+		return origin{}
+	}
+	scheme := strings.ToLower(value.Scheme)
+	port := value.Port()
+	if port == "" {
+		switch scheme {
+		case "https":
+			port = "443"
+		case "http":
+			port = "80"
+		}
+	}
+	return origin{scheme: scheme, host: strings.ToLower(value.Hostname()), port: port}
+}
+
+func apiOrigin(brand core.LarkBrand, endpointURL string) origin {
+	endpoint, err := url.Parse(endpointURL)
+	if err != nil {
+		return origin{}
+	}
+	return originOf(endpoint)
+}
+
+func isOfficialFeishuOrigin(candidate origin) bool {
+	if candidate.scheme != "https" || candidate.port != "443" {
+		return false
+	}
+	for _, official := range officialFeishuOrigins {
+		if candidate == official {
+			return true
+		}
+	}
+	return false
+}

internal/riskcontrol/transport_test.go

@@ -0,0 +1,124 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"net/http"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
+type countingSource struct {
+	calls atomic.Int32
+}
+
+func (s *countingSource) Snapshot() Snapshot {
+	s.calls.Add(1)
+	return Snapshot{OSType: OSTypeMacOS, ProductModel: "Mac16,1"}
+}
+
+type staticSource Snapshot
+
+func (s staticSource) Snapshot() Snapshot { return Snapshot(s) }
+
+func TestTransportAuthorizesBeforeCollecting(t *testing.T) {
+	tests := []struct {
+		name          string
+		requestURL    string
+		authorization string
+		wantSignals   bool
+	}{
+		{name: "authenticated official HTTPS", requestURL: "https://open.feishu.cn/open-apis/test", authorization: "Bearer token", wantSignals: true},
+		{name: "Lark official HTTPS", requestURL: "https://open.larksuite.com/open-apis/test", authorization: "Bearer token", wantSignals: true},
+		{name: "official explicit HTTPS port", requestURL: "https://OPEN.FEISHU.CN:443/open-apis/test", authorization: "Bearer token", wantSignals: true},
+		{name: "unauthenticated", requestURL: "https://open.feishu.cn/open-apis/test", wantSignals: true},
+		{name: "official non-OpenAPI origin", requestURL: "https://accounts.feishu.cn/open-apis/test", authorization: "Bearer token", wantSignals: true},
+		{name: "off domain", requestURL: "https://example.com/test", authorization: "Bearer token", wantSignals: false},
+		{name: "lookalike", requestURL: "https://open.feishu.cn.evil.example/test", authorization: "Bearer token", wantSignals: false},
+		{name: "plain HTTP", requestURL: "http://open.feishu.cn/test", authorization: "Bearer token", wantSignals: false},
+		{name: "non-default port", requestURL: "https://open.feishu.cn:8443/test", authorization: "Bearer token", wantSignals: false},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			source := &countingSource{}
+			var received http.Header
+			base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+				received = req.Header.Clone()
+				return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+			})
+			req, err := http.NewRequest(http.MethodGet, test.requestURL, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+			req.Header.Set("Authorization", test.authorization)
+			req.Header.Set(HeaderOSType, "caller-value")
+			req.Header.Set(HeaderProductModel, "caller-value")
+			req.Header["x-agent-device-type"] = []string{"non-canonical-caller-value"}
+
+			resp, err := NewTransport(base, source).RoundTrip(req)
+			if err != nil {
+				t.Fatal(err)
+			}
+			resp.Body.Close()
+
+			gotSignals := received.Get(HeaderOSType) != ""
+			if gotSignals != test.wantSignals {
+				t.Fatalf("signals present = %t, want %t; headers=%v", gotSignals, test.wantSignals, received)
+			}
+			wantCalls := int32(0)
+			if test.wantSignals {
+				wantCalls = 1
+			}
+			if got := source.calls.Load(); got != wantCalls {
+				t.Fatalf("Snapshot calls = %d, want %d", got, wantCalls)
+			}
+			if got := req.Header.Get(HeaderOSType); got != "caller-value" {
+				t.Fatalf("caller request OS header = %q, want unchanged", got)
+			}
+			if got := req.Header.Get(HeaderProductModel); got != "caller-value" {
+				t.Fatalf("caller request product-model header = %q, want unchanged", got)
+			}
+			if !test.wantSignals {
+				for name := range received {
+					if strings.EqualFold(name, HeaderProductModel) || strings.EqualFold(name, HeaderOSType) {
+						t.Fatalf("restricted header leaked as %q", name)
+					}
+				}
+			}
+		})
+	}
+}
+
+func TestTransportValidatesSourceSnapshot(t *testing.T) {
+	var received http.Header
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		received = req.Header.Clone()
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+	})
+	req, err := http.NewRequest(http.MethodGet, "https://open.feishu.cn/open-apis/test", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Authorization", "Bearer token")
+
+	resp, err := NewTransport(base, staticSource{
+		OSType:       OSType("unsupported"),
+		ProductModel: "unsafe\nvalue",
+	}).RoundTrip(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if received.Get(HeaderOSType) == "" && received.Get(HeaderProductModel) == "" {
+		t.Fatalf("no signals collected: %v", received)
+	}
+}

internal/validate/path.go

@@ -17,6 +17,13 @@ func SafeInputPath(path string) (string, error) {
 	return localfileio.SafeInputPath(path)
 }
 
+// LocalInputPath validates a local input path without restricting it to the
+// current working directory. It delegates to localfileio.LocalInputPath so
+// command validation and shared local-file readers use one policy.
+func LocalInputPath(path string) (string, error) {
+	return localfileio.LocalInputPath(path)
+}
+
 // SafeEnvDirPath validates an environment-provided application directory path.
 // Delegates to localfileio.SafeEnvDirPath.
 func SafeEnvDirPath(path, envName string) (string, error) {

internal/validate/path_test.go

@@ -211,6 +211,18 @@ func TestSafeLocalFlagPath(t *testing.T) {
 	}
 }
 
+func TestLocalInputPath_AllowsLocalPathsAndRejectsUnsafeCharacters(t *testing.T) {
+	for _, path := range []string{"/tmp/report.pdf", "../report.pdf"} {
+		got, err := LocalInputPath(path)
+		if err != nil || got != path {
+			t.Fatalf("LocalInputPath(%q) = %q, %v; want unchanged path", path, got, err)
+		}
+	}
+	if _, err := LocalInputPath("report\n.pdf"); err == nil {
+		t.Fatal("LocalInputPath() unexpectedly accepted a control character")
+	}
+}
+
 func TestSafeUploadPath_AllowsTempFileAbsolutePath(t *testing.T) {
 	// GIVEN: a real temp file (absolute path under os.TempDir())
 	f, err := os.CreateTemp("", "upload-test-*.bin")

internal/vfs/localfileio/path.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"path/filepath"
 	"strings"
+	"unicode"
 
 	"github.com/larksuite/cli/internal/charcheck"
 	"github.com/larksuite/cli/internal/vfs"
@@ -22,6 +23,32 @@ func SafeInputPath(path string) (string, error) {
 	return safePath(path, "--file")
 }
 
+// LocalInputPath validates an input path in the process local filesystem
+// namespace. It intentionally does not impose cwd containment or canonicalize
+// the path: absolute paths, parent-relative paths, and symlink traversal retain
+// their normal OS semantics. Character validation remains mandatory because
+// paths are user-controlled and may appear in errors or progress output.
+func LocalInputPath(path string) (string, error) {
+	if strings.TrimSpace(path) == "" {
+		return "", fmt.Errorf("local input path must not be empty")
+	}
+	if strings.IndexFunc(path, unicode.IsControl) >= 0 {
+		return "", fmt.Errorf("local input path must not contain control characters")
+	}
+	if err := charcheck.RejectControlChars(path, "local input path"); err != nil {
+		return "", err
+	}
+	if err := validateLocalInputPlatform(path); err != nil {
+		return "", err
+	}
+	return path, nil
+}
+
+func isWindowsNonLocalNamespace(path string) bool {
+	normalized := strings.ReplaceAll(path, "/", `\`)
+	return strings.HasPrefix(normalized, `\\`) || strings.HasPrefix(normalized, `\??\`)
+}
+
 // SafeLocalFlagPath validates a flag value as a local file path.
 // Empty values and http/https URLs are returned unchanged without validation.
 func SafeLocalFlagPath(flagName, value string) (string, error) {
@@ -29,7 +56,7 @@ func SafeLocalFlagPath(flagName, value string) (string, error) {
 		return value, nil
 	}
 	if _, err := SafeInputPath(value); err != nil {
-		return "", fmt.Errorf("%s: %v", flagName, err)
+		return "", fmt.Errorf("%s: %w", flagName, err)
 	}
 	return value, nil
 }

internal/vfs/localfileio/path_local_other.go

@@ -0,0 +1,8 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !windows
+
+package localfileio
+
+func validateLocalInputPlatform(string) error { return nil }

internal/vfs/localfileio/path_local_windows.go

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build windows
+
+package localfileio
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+)
+
+func validateLocalInputPlatform(path string) error {
+	if isWindowsNonLocalNamespace(path) {
+		return fmt.Errorf("local input path must not use a Windows network or device namespace")
+	}
+
+	cleaned := filepath.Clean(path)
+	volume := filepath.VolumeName(cleaned)
+	remainder := strings.TrimLeft(cleaned[len(volume):], `\/`)
+	for _, component := range strings.FieldsFunc(remainder, func(r rune) bool {
+		return r == '\\' || r == '/'
+	}) {
+		if component == "." || component == ".." {
+			continue
+		}
+		if !filepath.IsLocal(component) {
+			return fmt.Errorf("local input path contains a reserved Windows path component %q", component)
+		}
+	}
+	return nil
+}

internal/vfs/localfileio/path_local_windows_test.go

@@ -0,0 +1,27 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build windows
+
+package localfileio
+
+import "testing"
+
+func TestLocalInputPath_RejectsWindowsNetworkDeviceAndReservedPaths(t *testing.T) {
+	for _, input := range []string{
+		`\\server\share\report.pdf`,
+		`//server/share/report.pdf`,
+		`\\.\pipe\upload`,
+		`\\?\C:\Users\agent\report.pdf`,
+		`\\?\UNC\server\share\report.pdf`,
+		`\??\C:\Users\agent\report.pdf`,
+		`C:\Users\agent\NUL.txt`,
+		`CON`,
+	} {
+		t.Run(input, func(t *testing.T) {
+			if _, err := LocalInputPath(input); err == nil {
+				t.Fatalf("LocalInputPath(%q) unexpectedly succeeded", input)
+			}
+		})
+	}
+}

internal/vfs/localfileio/path_test.go

@@ -4,6 +4,7 @@
 package localfileio
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -71,6 +72,72 @@ func TestSafeOutputPath_RejectsPathTraversalAndDangerousInput(t *testing.T) {
 	}
 }
 
+func TestLocalInputPath_AllowsLocalNamespaceWithoutRewriting(t *testing.T) {
+	for _, input := range []string{
+		"/tmp/report.pdf",
+		"../outside/report.pdf",
+		"./report.pdf",
+		"nested/../report.pdf",
+		`C:\Users\agent\report.pdf`,
+		"报告.pdf",
+	} {
+		t.Run(input, func(t *testing.T) {
+			got, err := LocalInputPath(input)
+			if err != nil {
+				t.Fatalf("LocalInputPath(%q) error = %v", input, err)
+			}
+			if got != input {
+				t.Fatalf("LocalInputPath(%q) = %q, want path preserved verbatim", input, got)
+			}
+		})
+	}
+}
+
+func TestWindowsNonLocalNamespace(t *testing.T) {
+	for _, input := range []string{
+		`\\server\share\report.pdf`,
+		`//server/share/report.pdf`,
+		`\\.\pipe\upload`,
+		`\\?\C:\Users\agent\report.pdf`,
+		`\\?\UNC\server\share\report.pdf`,
+		`\??\C:\Users\agent\report.pdf`,
+	} {
+		if !isWindowsNonLocalNamespace(input) {
+			t.Errorf("isWindowsNonLocalNamespace(%q) = false, want true", input)
+		}
+	}
+
+	for _, input := range []string{
+		`C:\Users\agent\report.pdf`,
+		`C:/Users/agent/report.pdf`,
+		`..\outside\report.pdf`,
+		`.\report.pdf`,
+	} {
+		if isWindowsNonLocalNamespace(input) {
+			t.Errorf("isWindowsNonLocalNamespace(%q) = true, want false", input)
+		}
+	}
+}
+
+func TestLocalInputPath_RejectsEmptyControlAndDangerousUnicode(t *testing.T) {
+	for _, input := range []string{
+		"",
+		"   ",
+		"file\x00.txt",
+		"file\tname.txt",
+		"file\nname.txt",
+		"file\rname.txt",
+		"file\u202Ename.txt",
+		"file\u200Bname.txt",
+	} {
+		t.Run(fmt.Sprintf("%q", input), func(t *testing.T) {
+			if _, err := LocalInputPath(input); err == nil {
+				t.Fatalf("LocalInputPath(%q) unexpectedly succeeded", input)
+			}
+		})
+	}
+}
+
 func TestSafeOutputPath_ReturnsCanonicalAbsolutePath(t *testing.T) {
 	// GIVEN: a clean temp directory as CWD
 	dir := t.TempDir()

package-lock.json

@@ -1,15 +1,16 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.11",
+  "version": "1.0.77",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@larksuite/cli",
-      "version": "1.0.11",
+      "version": "1.0.77",
       "cpu": [
         "x64",
-        "arm64"
+        "arm64",
+        "riscv64"
       ],
       "hasInstallScript": true,
       "license": "MIT",

package.json

@@ -1,12 +1,13 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.74",
+  "version": "1.0.77",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"
   },
   "scripts": {
-    "postinstall": "node scripts/install.js"
+    "postinstall": "node scripts/install.js",
+    "release:check": "node scripts/release-preflight.js"
   },
   "os": [
     "darwin",

scripts/install.js

@@ -265,10 +265,7 @@ function getExpectedChecksum(archiveName, checksumsDir) {
   const checksumsPath = path.join(dir, "checksums.txt");
 
   if (!fs.existsSync(checksumsPath)) {
-    console.error(
-      "[WARN] checksums.txt not found, skipping checksum verification"
-    );
-    return null;
+    throw new Error(`[SECURITY] checksums.txt not found at ${checksumsPath}`);
   }
 
   const content = fs.readFileSync(checksumsPath, "utf8");
@@ -286,7 +283,14 @@ function getExpectedChecksum(archiveName, checksumsDir) {
 }
 
 function verifyChecksum(archivePath, expectedHash) {
-  if (expectedHash === null) return;
+  if (typeof expectedHash !== "string" || expectedHash.length === 0) {
+    throw new Error("[SECURITY] Expected checksum is missing or invalid");
+  }
+  if (!/^[0-9a-f]{64}$/i.test(expectedHash)) {
+    throw new Error(
+      "[SECURITY] Expected checksum must be a 64-character hexadecimal SHA-256 digest"
+    );
+  }
 
   // Stream the file to avoid loading the entire archive into memory.
   // Archives can be 10-100MB; streaming keeps RSS constant.

scripts/install.test.js

@@ -52,11 +52,12 @@ describe("getExpectedChecksum", () => {
     );
   });
 
-  it("returns null when checksums.txt does not exist", () => {
+  it("throws [SECURITY]-prefixed Error when checksums.txt does not exist", () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "checksum-test-"));
-    // No checksums.txt in dir
-    const result = getExpectedChecksum("anything.tar.gz", dir);
-    assert.equal(result, null);
+    assert.throws(
+      () => getExpectedChecksum("anything.tar.gz", dir),
+      { message: /^\[SECURITY\] checksums\.txt not found/ }
+    );
   });
 
   it("skips malformed lines and still finds valid entry", () => {
@@ -106,7 +107,7 @@ describe("verifyChecksum", () => {
     verifyChecksum(filePath, hash);
   });
 
-  it("matches case-insensitively", () => {
+  it("accepts a valid uppercase 64-character hex hash", () => {
     const content = "case test";
     const filePath = makeTmpFile(content);
     const hash = sha256(content).toUpperCase();
@@ -114,6 +115,40 @@ describe("verifyChecksum", () => {
     verifyChecksum(filePath, hash);
   });
 
+  for (const [name, expectedHash] of [
+    ["null", null],
+    ["empty", ""],
+    ["non-string", 123],
+  ]) {
+    it(`throws [SECURITY]-prefixed Error for ${name} expected hash`, () => {
+      const filePath = makeTmpFile("real content");
+      assert.throws(
+        () => verifyChecksum(filePath, expectedHash),
+        (err) => {
+          assert.match(err.message, /^\[SECURITY\]/);
+          assert.match(err.message, /Expected checksum is missing or invalid/);
+          return true;
+        }
+      );
+    });
+  }
+
+  it("throws [SECURITY] format Error for an incorrectly sized hash", () => {
+    const filePath = makeTmpFile("real content");
+    assert.throws(
+      () => verifyChecksum(filePath, "abc123"),
+      { message: /^\[SECURITY\] Expected checksum must be a 64-character hexadecimal SHA-256 digest$/ }
+    );
+  });
+
+  it("throws [SECURITY] format Error for a non-hex hash", () => {
+    const filePath = makeTmpFile("real content");
+    assert.throws(
+      () => verifyChecksum(filePath, "g".repeat(64)),
+      { message: /^\[SECURITY\] Expected checksum must be a 64-character hexadecimal SHA-256 digest$/ }
+    );
+  });
+
   it("throws [SECURITY]-prefixed Error on mismatch", () => {
     const filePath = makeTmpFile("real content");
     assert.throws(

scripts/release-preflight.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const STABLE_VERSION_PATTERN = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
+
+function isStableVersion(value) {
+  return typeof value === "string" && STABLE_VERSION_PATTERN.test(value);
+}
+
+function releaseError(message, observed, hint) {
+  return { ok: false, error: { type: "release_preflight", message, observed, hint } };
+}
+
+function validateReleasePreflight(packageJson, packageLockJson, tag) {
+  const packageVersion = packageJson?.version;
+  const lockVersion = packageLockJson?.version;
+  const lockRootVersion = packageLockJson?.packages?.[""]?.version;
+  const observed = {
+    packageVersion: packageVersion ?? null,
+    lockVersion: lockVersion ?? null,
+    lockRootVersion: lockRootVersion ?? null,
+    tagVersion: null,
+  };
+
+  for (const [field, value] of [
+    ["package.json.version", packageVersion],
+    ["package-lock.json.version", lockVersion],
+    ['package-lock.json.packages[""].version', lockRootVersion],
+  ]) {
+    if (!isStableVersion(value)) {
+      return releaseError(
+        `${field} must be a stable release version in X.Y.Z form`,
+        observed,
+        "Use the same stable X.Y.Z version in all package fields; prerelease and build metadata are not allowed for production releases.",
+      );
+    }
+  }
+
+  if (packageVersion !== lockVersion || packageVersion !== lockRootVersion) {
+    return releaseError(
+      "Package version fields do not match",
+      observed,
+      "Synchronize package.json.version and both package-lock.json version fields.",
+    );
+  }
+
+  if (tag === undefined) {
+    return { ok: true, data: observed };
+  }
+  if (typeof tag !== "string" || !tag.startsWith("v") || !isStableVersion(tag.slice(1))) {
+    return releaseError(
+      "--tag must use the stable release form vX.Y.Z",
+      { ...observed, tag },
+      `Use --tag v${packageVersion}; prerelease and build metadata are not allowed for production releases.`,
+    );
+  }
+
+  const tagVersion = tag.slice(1);
+  if (tagVersion !== packageVersion) {
+    return releaseError(
+      "Tag version does not match the package version",
+      { ...observed, tagVersion, tag },
+      `Use --tag v${packageVersion}.`,
+    );
+  }
+  return { ok: true, data: { ...observed, tagVersion } };
+}
+
+function writeResult(result) {
+  (result.ok ? process.stdout : process.stderr).write(`${JSON.stringify(result)}\n`);
+  if (!result.ok) process.exitCode = 1;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  let tag;
+  if (args.length === 2 && args[0] === "--tag") {
+    tag = args[1];
+  } else if (args.length !== 0) {
+    writeResult(releaseError(
+      "Expected no arguments or --tag vX.Y.Z",
+      { arguments: args },
+      "Run release:check without arguments or pass exactly one --tag value.",
+    ));
+    return;
+  }
+
+  const repoRoot = path.resolve(__dirname, "..");
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+    const packageLockJson = JSON.parse(fs.readFileSync(path.join(repoRoot, "package-lock.json"), "utf8"));
+    writeResult(validateReleasePreflight(packageJson, packageLockJson, tag));
+  } catch (error) {
+    writeResult(releaseError(
+      "Could not read release package metadata",
+      { reason: error.message },
+      "Ensure package.json and package-lock.json exist and contain valid JSON.",
+    ));
+  }
+}
+
+module.exports = { validateReleasePreflight };
+
+if (require.main === module) main();

scripts/release-preflight.test.js

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+const assert = require("node:assert/strict");
+const { describe, it } = require("node:test");
+
+const { validateReleasePreflight } = require("./release-preflight");
+
+function metadata(version = "1.2.3") {
+  return {
+    packageJson: { version },
+    packageLockJson: {
+      version,
+      packages: { "": { version } },
+    },
+  };
+}
+
+function assertRejected(result) {
+  assert.equal(result.ok, false);
+  assert.equal(result.error.type, "release_preflight");
+  assert.equal(typeof result.error.message, "string");
+}
+
+describe("validateReleasePreflight", () => {
+  it("accepts matching stable package, lock, and tag versions", () => {
+    const { packageJson, packageLockJson } = metadata();
+
+    assert.deepEqual(
+      validateReleasePreflight(packageJson, packageLockJson, "v1.2.3"),
+      {
+        ok: true,
+        data: {
+          packageVersion: "1.2.3",
+          lockVersion: "1.2.3",
+          lockRootVersion: "1.2.3",
+          tagVersion: "1.2.3",
+        },
+      },
+    );
+  });
+
+  it("rejects non-stable or inconsistent package metadata", () => {
+    const prerelease = metadata("1.2.3-beta.1");
+    const topLevelMismatch = metadata();
+    topLevelMismatch.packageLockJson.version = "1.2.4";
+    const rootMismatch = metadata();
+    rootMismatch.packageLockJson.packages[""].version = "1.2.4";
+
+    for (const { packageJson, packageLockJson } of [
+      prerelease,
+      topLevelMismatch,
+      rootMismatch,
+    ]) {
+      assertRejected(validateReleasePreflight(packageJson, packageLockJson));
+    }
+  });
+
+  it("rejects an invalid or mismatched release tag", () => {
+    const { packageJson, packageLockJson } = metadata();
+
+    for (const tag of ["1.2.3", "v1.2.3-beta.1", "v1.2.4"]) {
+      assertRejected(validateReleasePreflight(packageJson, packageLockJson, tag));
+    }
+  });
+});

scripts/tag-release.sh

@@ -3,49 +3,48 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "${REPO_ROOT}"
 
-# Read version from package.json
-VERSION=$(node -p "require('${REPO_ROOT}/package.json').version")
-
-if [ -z "$VERSION" ]; then
-  echo "Error: could not read version from package.json" >&2
-  exit 1
-fi
-
+VERSION=$(node -p "require('./package.json').version")
 TAG="v${VERSION}"
 
+node "${SCRIPT_DIR}/release-preflight.js" --tag "${TAG}"
+
 echo "Version: ${VERSION}"
 echo "Tag: ${TAG}"
 
-# Check if tag already exists locally
-if git rev-parse "$TAG" >/dev/null 2>&1; then
-  echo "Tag ${TAG} already exists locally, skipping."
-  exit 0
-fi
-
-# Check if tag already exists on remote
-if git ls-remote --tags origin "$TAG" | grep -q "$TAG"; then
-  echo "Tag ${TAG} already exists on remote, skipping."
-  exit 0
-fi
-
-# Ensure package.json changes are committed before tagging
-if git diff --name-only | grep -q 'package.json' || git diff --cached --name-only | grep -q 'package.json'; then
-  echo "Error: package.json has uncommitted changes. Please commit before tagging." >&2
+CURRENT_BRANCH=$(git branch --show-current)
+if [ "${CURRENT_BRANCH}" != "main" ]; then
+  echo "Error: releases must be tagged from main; current branch is '${CURRENT_BRANCH}'." >&2
   exit 1
 fi
 
-# Ensure current branch is pushed to remote before tagging
-CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-LOCAL_SHA=$(git rev-parse HEAD)
-REMOTE_SHA=$(git rev-parse "origin/${CURRENT_BRANCH}" 2>/dev/null || echo "")
-if [ "$LOCAL_SHA" != "$REMOTE_SHA" ]; then
-  echo "Error: local branch '${CURRENT_BRANCH}' is not in sync with remote. Please push your commits first." >&2
+if ! git diff --quiet HEAD -- package.json package-lock.json; then
+  echo "Error: package.json or package-lock.json has uncommitted changes. Please commit them before tagging." >&2
   exit 1
 fi
 
-# Create and push tag
-git tag "$TAG"
-git push origin "$TAG"
+git fetch origin main
 
-echo "Successfully created and pushed tag ${TAG}"
+HEAD_SHA=$(git rev-parse HEAD)
+FETCHED_MAIN_SHA=$(git rev-parse "FETCH_HEAD^{commit}")
+if [ "${HEAD_SHA}" != "${FETCHED_MAIN_SHA}" ]; then
+  echo "Error: HEAD must exactly match origin/main before tagging." >&2
+  exit 1
+fi
+
+if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+  echo "Error: local tag ${TAG} already exists." >&2
+  exit 1
+fi
+
+REMOTE_TAG=$(git ls-remote --tags origin "refs/tags/${TAG}")
+if [ -n "${REMOTE_TAG}" ]; then
+  echo "Error: remote tag ${TAG} already exists." >&2
+  exit 1
+fi
+
+git tag "${TAG}" "${HEAD_SHA}"
+git push origin "refs/tags/${TAG}"
+
+echo "Successfully pushed tag ${TAG}"

shortcuts/apps/apps_file_list.go

@@ -12,10 +12,23 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+// maxFileListPageSize 是 file_list 分页上限，与后端 paas_storage checkMaxKeys 的 (0, 200] 契约对齐：
+// page_size > 200 服务端直接返回 ErrInvalidRequest("maxKeys not in range (0, 200]")。CLI 前置校验避免无谓往返。
+// 注：服务端对 page_size<=0 会兜底为默认值，但 CLI 默认已是 20、显式传 <1 属误用，故与其它 list 命令一致地按 [1, 200] 校验。
+const maxFileListPageSize = 200
+
+// validateFileListPageSize 前置校验 --page-size ∈ [1, maxFileListPageSize]，与后端 checkMaxKeys 的 (0, 200] 契约对齐。
+func validateFileListPageSize(n int) error {
+	if n < 1 || n > maxFileListPageSize {
+		return appsValidationParamError("--page-size", "--page-size must be between 1 and %d", maxFileListPageSize)
+	}
+	return nil
+}
+
 // AppsFileList lists files in a Miaoda app's storage (cursor pagination)。
 //
 // GET /apps/{app_id}/storage/file_list。过滤器：--name / --path / --type / --size-gt /
-// --size-lt / --uploaded-since / --uploaded-until（精确或区间），分页 --page-size/--page-token。
+// --size-lt / --uploaded-since / --uploaded-until（精确或区间），分页 --page-size(1..200)/--page-token。
 // file 域不分 dev/online，无 --env。
 //
 // pretty 渲染 5 列：file_name / path / size / type / uploaded_at；空结果打 "No files found."。
@@ -41,13 +54,17 @@ var AppsFileList = common.Shortcut{
 		{Name: "size-lt", Type: "int", Desc: "filter: size less than (bytes)"},
 		{Name: "uploaded-since", Desc: "filter: uploaded at or after; relative (7d/2h/30s) | date (2026-04-15) | datetime (2026-04-15T10:00:00) | ISO 8601 w/ TZ (bare date/datetime read in local timezone)"},
 		{Name: "uploaded-until", Desc: "filter: uploaded at or before; relative (7d/2h/30s) | date (2026-04-15) | datetime (2026-04-15T10:00:00) | ISO 8601 w/ TZ (bare date/datetime read in local timezone)"},
-		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "page size (1..200)"},
 		{Name: "page-token", Desc: "pagination cursor from previous response"},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
 		}
+		// page_size 前置校验：对齐后端 checkMaxKeys 的 (0, 200] 契约，避免 >200 触发服务端 ErrInvalidRequest。
+		if err := validateFileListPageSize(rctx.Int("page-size")); err != nil {
+			return err
+		}
 		// 设计原则三：<timestamp> 多格式 → 归一化为 RFC3339 UTC，回写到 flag 供 buildFileListParams 透传。
 		for _, f := range []string{"uploaded-since", "uploaded-until"} {
 			if strings.TrimSpace(rctx.Str(f)) == "" {

shortcuts/apps/apps_file_list_test.go

@@ -82,6 +82,34 @@ func TestAppsFileList_RequiresAppID(t *testing.T) {
 	}
 }
 
+// TestAppsFileList_PageSizeOutOfRange 验证 --page-size 超出 (0, 200] 契约时前置报 --page-size 校验错误，不发请求。
+func TestAppsFileList_PageSizeOutOfRange(t *testing.T) {
+	for _, ps := range []string{"0", "201", "500"} {
+		factory, stdout, _ := newAppsExecuteFactory(t)
+		err := runAppsShortcut(t, AppsFileList,
+			[]string{"+file-list", "--app-id", "app_x", "--page-size", ps, "--as", "user"}, factory, stdout)
+		var ve *errs.ValidationError
+		if !errors.As(err, &ve) {
+			t.Fatalf("page-size=%s: err = %T %v, want *errs.ValidationError", ps, err, err)
+		}
+		if ve.Param != "--page-size" {
+			t.Fatalf("page-size=%s: Param = %q, want --page-size", ps, ve.Param)
+		}
+	}
+}
+
+// TestAppsFileList_PageSizeBoundaryOK 验证边界值 1 与 200 通过校验（dry-run 不报错并把 page_size 下发）。
+func TestAppsFileList_PageSizeBoundaryOK(t *testing.T) {
+	for _, ps := range []string{"1", "200"} {
+		factory, stdout, _ := newAppsExecuteFactory(t)
+		if err := runAppsShortcut(t, AppsFileList,
+			[]string{"+file-list", "--app-id", "app_x", "--page-size", ps, "--dry-run", "--as", "user"},
+			factory, stdout); err != nil {
+			t.Fatalf("page-size=%s: dry-run err=%v", ps, err)
+		}
+	}
+}
+
 // 过滤器 + 分页全部进 query（size-gt/lt 走 int，uploaded_since/until 原样）。
 func TestAppsFileList_DryRunSendsFiltersAndPagination(t *testing.T) {
 	factory, stdout, _ := newAppsExecuteFactory(t)

shortcuts/apps/apps_file_upload.go

@@ -14,7 +14,6 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -47,21 +46,7 @@ var AppsFileUpload = common.Shortcut{
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
 		}
-		f := strings.TrimSpace(rctx.Str("file"))
-		if f == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file is required").WithParam("--file")
-		}
-		st, err := rctx.FileIO().Stat(f)
-		if err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: %v", err).WithParam("--file").WithCause(err)
-		}
-		if st.IsDir() {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file must be a file, not a directory").WithParam("--file")
-		}
-		if st.Size() > fileUploadMaxBytes {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "file size %d bytes exceeds the 100 MB upload limit", st.Size()).WithParam("--file")
-		}
-		return nil
+		return rctx.ValidateLocalFileFlag("file", fileUploadMaxBytes)
 	},
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		appID, _ := requireAppID(rctx.Str("app-id"))
@@ -76,9 +61,9 @@ var AppsFileUpload = common.Shortcut{
 			return err
 		}
 		localPath := strings.TrimSpace(rctx.Str("file"))
-		content, err := cmdutil.ReadInputFile(rctx.FileIO(), localPath)
+		content, err := rctx.ReadLocalFileFlag("file", fileUploadMaxBytes)
 		if err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: %v", err).WithParam("--file").WithCause(err)
+			return err
 		}
 		fileName := filepath.Base(localPath)
 		contentType := mimeByExt(fileName)

shortcuts/apps/apps_file_upload_test.go

@@ -12,6 +12,7 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 
@@ -58,22 +59,17 @@ func TestAppsFileUpload_RejectsDirectory(t *testing.T) {
 	}
 }
 
-// TestAppsFileUpload_DryRunPreUpload 验证 dry-run 输出 POST file_pre_upload，body.file_name 取文件 basename。
+// TestAppsFileUpload_DryRunPreUpload verifies that dry-run validates the local
+// file and previews the pre-upload request without reading or uploading it.
 func TestAppsFileUpload_DryRunPreUpload(t *testing.T) {
-	// Validate 会 Stat --file（在 DryRun 之前），故 dry-run 也需要真实存在的文件。
-	dir := t.TempDir()
-	if err := os.WriteFile(filepath.Join(dir, "logo.png"), []byte("x"), 0o600); err != nil {
+	absolutePath := filepath.Join(t.TempDir(), "logo.png")
+	if err := os.WriteFile(absolutePath, []byte("not-read-by-dry-run"), 0o600); err != nil {
 		t.Fatal(err)
 	}
-	oldWD, _ := os.Getwd()
-	if err := os.Chdir(dir); err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(func() { _ = os.Chdir(oldWD) })
 
 	factory, stdout, _ := newAppsExecuteFactory(t)
 	if err := runAppsShortcut(t, AppsFileUpload,
-		[]string{"+file-upload", "--app-id", "app_x", "--file", "logo.png", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		[]string{"+file-upload", "--app-id", "app_x", "--file", absolutePath, "--dry-run", "--as", "user"}, factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
 	var env dryRunAPIEnvelope
@@ -87,6 +83,18 @@ func TestAppsFileUpload_DryRunPreUpload(t *testing.T) {
 	}
 }
 
+func TestAppsFileUpload_DryRunRejectsMissingFile(t *testing.T) {
+	missingAbsolutePath := filepath.Join(t.TempDir(), "does-not-exist", "logo.png")
+
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsFileUpload,
+		[]string{"+file-upload", "--app-id", "app_x", "--file", missingAbsolutePath, "--dry-run", "--as", "user"}, factory, stdout)
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) || validationErr.Subtype != errs.SubtypeInvalidArgument || validationErr.Param != "--file" {
+		t.Fatalf("error = %T %v, want invalid_argument for --file", err, err)
+	}
+}
+
 // 三步直传：pre-upload → 客户端 PUT 字节 → callback。
 func TestAppsFileUpload_EndToEnd(t *testing.T) {
 	var putBody []byte
@@ -149,6 +157,142 @@ func TestAppsFileUpload_EndToEnd(t *testing.T) {
 	}
 }
 
+// TestAppsFileUpload_AcceptsAbsolutePath verifies that file-upload can read an
+// absolute path outside the current working directory.
+func TestAppsFileUpload_AcceptsAbsolutePath(t *testing.T) {
+	var putBody []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPut {
+			w.WriteHeader(http.StatusMethodNotAllowed)
+			return
+		}
+		putBody, _ = io.ReadAll(r.Body)
+		w.Header().Set("ETag", `"etag-abs"`)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	// Keep the process cwd unchanged so the temporary file is outside it.
+	dir := t.TempDir()
+	absFile := filepath.Join(dir, "report.pdf")
+	if !filepath.IsAbs(absFile) {
+		t.Fatalf("test setup: %q is not absolute", absFile)
+	}
+	if err := os.WriteFile(absFile, []byte("PDFBYTES"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/storage/file_pre_upload",
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"upload_url": srv.URL, "upload_id": "up-abs"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/storage/file_upload_callback",
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"file_name": "report.pdf", "path": "/1858537546760999.pdf", "size_bytes": 8,
+		}},
+	})
+
+	if err := runAppsShortcut(t, AppsFileUpload,
+		[]string{"+file-upload", "--app-id", "app_x", "--file", absFile, "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute with absolute path err=%v", err)
+	}
+	if string(putBody) != "PDFBYTES" {
+		t.Fatalf("PUT body = %q, want file bytes", putBody)
+	}
+}
+
+func TestAppsFileUpload_AcceptsParentRelativePathOutsideCWD(t *testing.T) {
+	var putBody []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		putBody, _ = io.ReadAll(r.Body)
+		w.Header().Set("ETag", `"etag-parent"`)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	root := t.TempDir()
+	workDir := filepath.Join(root, "work")
+	if err := os.Mkdir(workDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "report.pdf"), []byte("PARENT"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	oldWD, _ := os.Getwd()
+	if err := os.Chdir(workDir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(oldWD) })
+
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/storage/file_pre_upload",
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"upload_url": srv.URL, "upload_id": "up-parent"}},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/storage/file_upload_callback",
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"file_name": "report.pdf", "path": "/parent.pdf", "size_bytes": 6,
+		}},
+	})
+
+	if err := runAppsShortcut(t, AppsFileUpload,
+		[]string{"+file-upload", "--app-id", "app_x", "--file", filepath.Join("..", "report.pdf"), "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute with parent-relative path err=%v", err)
+	}
+	if string(putBody) != "PARENT" {
+		t.Fatalf("PUT body = %q, want PARENT", putBody)
+	}
+}
+
+func TestAppsFileUpload_RejectsFileAboveLimit(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "too-large.bin")
+	f, err := os.Create(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Truncate(fileUploadMaxBytes + 1); err != nil {
+		_ = f.Close()
+		t.Fatal(err)
+	}
+	if err := f.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err = runAppsShortcut(t, AppsFileUpload,
+		[]string{"+file-upload", "--app-id", "app_x", "--file", path, "--as", "user"}, factory, stdout)
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) || validationErr.Param != "--file" {
+		t.Fatalf("error = %T %v, want --file ValidationError", err, err)
+	}
+	if !strings.Contains(validationErr.Error(), "limit") {
+		t.Fatalf("error = %v, want size limit context", validationErr)
+	}
+}
+
+func TestAppsFileUpload_RejectsDeviceWithoutReadingIt(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("/dev/zero is unavailable on Windows")
+	}
+	if _, err := os.Stat("/dev/zero"); err != nil {
+		t.Skipf("/dev/zero unavailable: %v", err)
+	}
+
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsFileUpload,
+		[]string{"+file-upload", "--app-id", "app_x", "--file", "/dev/zero", "--as", "user"}, factory, stdout)
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) || validationErr.Param != "--file" {
+		t.Fatalf("error = %T %v, want --file ValidationError", err, err)
+	}
+	if !strings.Contains(validationErr.Error(), "regular file") {
+		t.Fatalf("error = %v, want non-regular-file context", validationErr)
+	}
+}
+
 // TestSanitizeUploadFileName_Cases 验证 sanitizeUploadFileName：空格转 %20、去 TOS 非法字符、全非法兜底、非 ASCII 百分号编码。
 func TestSanitizeUploadFileName_Cases(t *testing.T) {
 	cases := []struct{ in, want string }{

shortcuts/base/base_dryrun_ops_test.go

@@ -104,6 +104,22 @@ func TestDryRunFieldOps(t *testing.T) {
 	assertDryRunContains(t, dryRunFieldUpdate(ctx, rt), "PUT /open-apis/base/v3/bases/app_x/tables/tbl_1/fields/fld_1")
 	assertDryRunContains(t, dryRunFieldDelete(ctx, rt), "DELETE /open-apis/base/v3/bases/app_x/tables/tbl_1/fields/fld_1")
 	assertDryRunContains(t, dryRunFieldSearchOptions(ctx, rt), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/fields/fld_1/options", "offset=3", "limit=30", "query=open")
+
+	autoNumberRT := newBaseTestRuntime(
+		map[string]string{
+			"base-token": "app_x",
+			"table-id":   "tbl_1",
+			"field-id":   "fld_1",
+			"json":       `{"name":"编号","type":"auto_number","style":{"rules":[{"type":"text","text":"TASK-"},{"type":"created_time","date_format":"yyyyMM"},{"type":"text","text":"-"},{"type":"incremental_number","length":4}]}}`,
+		},
+		nil,
+		nil,
+	)
+	autoNumberDR := dryRunFieldUpdate(ctx, autoNumberRT)
+	assertDryRunContains(t, autoNumberDR, "PUT /open-apis/base/v3/bases/app_x/tables/tbl_1/fields/fld_1", `"name":"编号"`, `"type":"auto_number"`, `"rules":[`, `"length":4`)
+	if out := autoNumberDR.Format(); strings.Contains(out, "auto_serial") || strings.Contains(out, "reformat_existing_records") || strings.Contains(out, "/open-apis/bitable/v1/") {
+		t.Fatalf("auto_number dry-run must stay on v3 field JSON, got:\n%s", out)
+	}
 }
 
 func TestDryRunRecordOps(t *testing.T) {
@@ -117,7 +133,7 @@ func TestDryRunRecordOps(t *testing.T) {
 	)
 	assertDryRunContains(t, dryRunRecordList(ctx, listRT), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/records", "offset=0", "limit=200", "view_id=viw_1", "field_id=Name", "field_id=Age")
 
-	listFieldNamesAliasRT := newBaseTestRuntimeWithSlices(
+	listFieldNamesAliasRT := newBaseTestRuntimeWithArrays(
 		map[string]string{"base-token": "app_x", "table-id": "tbl_1"},
 		map[string][]string{"field-names": {"Name", "Age"}},
 		nil,

shortcuts/base/base_execute_test.go

@@ -81,6 +81,37 @@ func runShortcutWithAuthTypes(t *testing.T, shortcut common.Shortcut, authTypes
 	return parent.ExecuteContext(context.Background())
 }
 
+func assertInvalidArgumentValidation(t *testing.T, err error, wantParam string, wantParams []string, messageContains string) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected invalid-argument validation error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected invalid-argument validation problem, got %T %v", err, err)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected ValidationError, got %T %v", err, err)
+	}
+	if validationErr.Param != wantParam {
+		t.Fatalf("param=%q, want %q", validationErr.Param, wantParam)
+	}
+	if wantParams != nil {
+		if len(validationErr.Params) != len(wantParams) {
+			t.Fatalf("params=%#v, want %v", validationErr.Params, wantParams)
+		}
+		for i, want := range wantParams {
+			if validationErr.Params[i].Name != want {
+				t.Fatalf("params=%#v, want %v", validationErr.Params, wantParams)
+			}
+		}
+	}
+	if messageContains != "" && !strings.Contains(err.Error(), messageContains) {
+		t.Fatalf("err=%v, want message containing %q", err, messageContains)
+	}
+}
+
 func TestBaseWorkspaceExecuteCreate(t *testing.T) {
 	factory, stdout, reg := newExecuteFactory(t)
 	stderr, _ := factory.IOStreams.ErrOut.(*bytes.Buffer)
@@ -818,8 +849,189 @@ func TestBaseFieldExecuteUpdate(t *testing.T) {
 	if err := runShortcut(t, BaseFieldUpdate, []string{"+field-update", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "fld_x", "--json", `{"name":"Amount","type":"number"}`, "--yes"}, factory, stdout); err != nil {
 		t.Fatalf("err=%v", err)
 	}
-	if got := stdout.String(); !strings.Contains(got, `"updated": true`) || !strings.Contains(got, `"fld_x"`) {
-		t.Fatalf("stdout=%s", got)
+	got := stdout.String()
+	for _, want := range []string{`"updated": true`, `"fld_x"`, `"field_get_recommended": true`, `"next_step": "field_get"`, `"verification_hint"`} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("stdout missing %q:\n%s", want, got)
+		}
+	}
+}
+
+func TestFieldUpdateResultAlwaysRecommendsReadback(t *testing.T) {
+	tests := []struct {
+		name         string
+		field        interface{}
+		submitted    map[string]interface{}
+		hintContains []string
+	}{
+		{
+			name:         "direct complex server type overrides simple submitted type",
+			field:        map[string]interface{}{"type": "auto_number"},
+			submitted:    map[string]interface{}{"type": "number"},
+			hintContains: []string{`submitted type "number"`, `server returned type "auto_number"`},
+		},
+		{
+			name:         "nested simple server type still recommends readback",
+			field:        map[string]interface{}{"field": map[string]interface{}{"type": "number"}},
+			submitted:    map[string]interface{}{"type": "auto_number"},
+			hintContains: []string{`submitted type "auto_number"`, `server returned type "number"`},
+		},
+		{
+			name:         "submitted simple type still recommends readback when response omits type",
+			field:        map[string]interface{}{"id": "fld_x"},
+			submitted:    map[string]interface{}{"type": "text"},
+			hintContains: []string{`type "text"`, "cannot determine the previous type"},
+		},
+		{
+			name:         "missing type is conservative",
+			field:        map[string]interface{}{"id": "fld_x"},
+			submitted:    map[string]interface{}{"name": "Amount"},
+			hintContains: []string{"unknown or uncommon field type", "+field-get"},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := fieldUpdateResult(map[string]interface{}{"field": tc.field, "updated": true}, tc.submitted)
+			if got["field_get_recommended"] != true || got["next_step"] != "field_get" {
+				t.Fatalf("result=%#v, want readback recommendation", got)
+			}
+			hint, _ := got["verification_hint"].(string)
+			for _, want := range tc.hintContains {
+				if !strings.Contains(hint, want) {
+					t.Fatalf("verification_hint=%q, want substring %q", hint, want)
+				}
+			}
+		})
+	}
+}
+
+func TestBaseFieldExecuteUpdateNoopReturnsAPIError(t *testing.T) {
+	factory, stdout, reg := newExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "PUT",
+		URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields/fld_x",
+		Body: map[string]interface{}{
+			"code": 800070003,
+			"msg":  "no operation produced",
+		},
+	})
+	err := runShortcut(t, BaseFieldUpdate, []string{"+field-update", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "fld_x", "--json", `{"name":"Amount","type":"number"}`, "--yes"}, factory, stdout)
+	if err == nil {
+		t.Fatal("expected the API no-op response to surface as an error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected a typed API error, got %T %v", err, err)
+	}
+	if p.Category != errs.CategoryAPI || p.Subtype != errs.SubtypeUnknown || p.Code != 800070003 {
+		t.Fatalf("category/subtype/code=%s/%s/%d", p.Category, p.Subtype, p.Code)
+	}
+	var apiErr *errs.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("expected APIError, got %T %v", err, err)
+	}
+	if got := stdout.String(); strings.TrimSpace(got) != "" {
+		t.Fatalf("no success envelope should be emitted on a no-op API error:\n%s", got)
+	}
+}
+
+func TestBaseFieldExecuteUpdateAutoNumberUsesV3FieldJSON(t *testing.T) {
+	factory, stdout, reg := newExecuteFactory(t)
+	stub := &httpmock.Stub{
+		Method: "PUT",
+		URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields/fld_x",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"field": map[string]interface{}{"id": "fld_x", "name": "编号", "type": "auto_number"},
+			},
+		},
+	}
+	reg.Register(stub)
+	jsonBody := `{"name":"编号","type":"auto_number","style":{"rules":[{"type":"text","text":"TASK-"},{"type":"created_time","date_format":"yyyyMM"},{"type":"text","text":"-"},{"type":"incremental_number","length":4}]}}`
+	if err := runShortcut(t, BaseFieldUpdate, []string{"+field-update", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "fld_x", "--json", jsonBody, "--yes"}, factory, stdout); err != nil {
+		t.Fatalf("err=%v", err)
+	}
+	gotBody := string(stub.CapturedBody)
+	for _, want := range []string{
+		`"name":"编号"`,
+		`"type":"auto_number"`,
+		`"rules":[`,
+		`"date_format":"yyyyMM"`,
+		`"length":4`,
+	} {
+		if !strings.Contains(gotBody, want) {
+			t.Fatalf("request body missing %q:\n%s", want, gotBody)
+		}
+	}
+	for _, forbidden := range []string{"auto_serial", "reformat_existing_records", `"type":1005`} {
+		if strings.Contains(gotBody, forbidden) {
+			t.Fatalf("request body must not contain v1 field %q:\n%s", forbidden, gotBody)
+		}
+	}
+	got := stdout.String()
+	for _, want := range []string{`"updated": true`, `"fld_x"`, `"field_get_recommended": true`, `"next_step": "field_get"`, `"verification_hint"`} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("stdout missing %q:\n%s", want, got)
+		}
+	}
+	for _, forbidden := range []string{`"reformat_existing_records"`} {
+		if strings.Contains(got, forbidden) {
+			t.Fatalf("stdout must not expose %q:\n%s", forbidden, got)
+		}
+	}
+}
+
+func TestBaseFieldExecuteUpdateDoesNotRejectExtraJSONKeys(t *testing.T) {
+	factory, stdout, reg := newExecuteFactory(t)
+	stub := &httpmock.Stub{
+		Method: "PUT",
+		URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields/fld_x",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"id": "fld_x", "name": "编号", "type": "auto_number"},
+		},
+	}
+	reg.Register(stub)
+	// Unknown v3 keys are forwarded unchanged; the server remains the source of
+	// truth for whether a field-update property is supported.
+	jsonBody := `{"name":"编号","type":"auto_number","style":{"rules":[{"type":"incremental_number","length":4}]},"reformat_existing_records":true}`
+	if err := runShortcut(t, BaseFieldUpdate, []string{"+field-update", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "fld_x", "--json", jsonBody, "--yes"}, factory, stdout); err != nil {
+		t.Fatalf("err=%v", err)
+	}
+	if gotBody := string(stub.CapturedBody); !strings.Contains(gotBody, `"reformat_existing_records":true`) {
+		t.Fatalf("request body must preserve unknown v3 key:\n%s", gotBody)
+	}
+	if got := stdout.String(); !strings.Contains(got, `"updated": true`) {
+		t.Fatalf("expected successful update, got: %s", got)
+	}
+}
+
+func TestBaseFieldValidateAllowsRatingMaxAboveLimit(t *testing.T) {
+	ctx := context.Background()
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		runtime  *common.RuntimeContext
+	}{
+		{
+			name:     "create",
+			shortcut: BaseFieldCreate,
+			runtime:  newBaseTestRuntime(map[string]string{"base-token": "app_x", "table-id": "tbl_x", "json": `{"name":"评分","type":"number","style":{"type":"rating","icon":"star","min":0,"max":20}}`}, nil, nil),
+		},
+		{
+			name:     "update",
+			shortcut: BaseFieldUpdate,
+			runtime:  newBaseTestRuntime(map[string]string{"base-token": "app_x", "table-id": "tbl_x", "field-id": "fld_x", "json": `{"name":"评分","type":"number","style":{"type":"rating","icon":"star","min":0,"max":20}}`}, nil, nil),
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if err := tc.shortcut.Validate(ctx, tc.runtime); err != nil {
+				t.Fatalf("rating max above 10 should not be blocked by CLI validation: %v", err)
+			}
+		})
 	}
 }
 
@@ -1091,8 +1303,32 @@ func TestBaseFieldExecuteCRUD(t *testing.T) {
 		if err := runShortcut(t, BaseFieldCreate, []string{"+field-create", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `{"name":"Status","type":"text"}`}, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
 		}
-		if got := stdout.String(); !strings.Contains(got, `"created": true`) || !strings.Contains(got, `"fld_new"`) {
-			t.Fatalf("stdout=%s", got)
+		got := stdout.String()
+		for _, want := range []string{`"created": true`, `"fld_new"`, `"field_get_recommended": false`, `"next_step": "done"`, `"verification_hint"`} {
+			if !strings.Contains(got, want) {
+				t.Fatalf("stdout missing %q:\n%s", want, got)
+			}
+		}
+	})
+
+	t.Run("create generated field recommends readback", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{"id": "fld_auto", "name": "编号", "type": "auto_number"},
+			},
+		})
+		if err := runShortcut(t, BaseFieldCreate, []string{"+field-create", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `{"name":"编号","type":"auto_number"}`}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		got := stdout.String()
+		for _, want := range []string{`"created": true`, `"fld_auto"`, `"field_get_recommended": true`, `"next_step": "field_get"`, `"verification_hint"`} {
+			if !strings.Contains(got, want) {
+				t.Fatalf("stdout missing %q:\n%s", want, got)
+			}
 		}
 	})
 
@@ -1139,11 +1375,58 @@ func TestBaseFieldExecuteCRUD(t *testing.T) {
 		if len(fields) != 2 {
 			t.Fatalf("fields len=%d output=%#v", len(fields), data)
 		}
+		if data["field_get_recommended"] != false || data["next_step"] != "done" || data["verification_hint"] == nil {
+			t.Fatalf("simple batch create must carry field_get_recommended:false + next_step:done + verification_hint: %#v", data)
+		}
 		if !strings.Contains(string(firstStub.CapturedBody), `"name":"A"`) || !strings.Contains(string(secondStub.CapturedBody), `"name":"B"`) {
 			t.Fatalf("unexpected request bodies: %s / %s", firstStub.CapturedBody, secondStub.CapturedBody)
 		}
 	})
 
+	t.Run("create array with generated field recommends readback", func(t *testing.T) {
+		oldDelay := fieldCreateBatchDelay
+		fieldCreateBatchDelay = 0
+		t.Cleanup(func() { fieldCreateBatchDelay = oldDelay })
+
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields",
+			BodyFilter: func(body []byte) bool {
+				return strings.Contains(string(body), `"name":"Title"`)
+			},
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{"id": "fld_title", "name": "Title", "type": "text"},
+			},
+		})
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/fields",
+			BodyFilter: func(body []byte) bool {
+				return strings.Contains(string(body), `"name":"编号"`)
+			},
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{"id": "fld_no", "name": "编号", "type": "auto_number"},
+			},
+		})
+
+		if err := runShortcut(t, BaseFieldCreate, []string{"+field-create", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `[{"name":"Title","type":"text"},{"name":"编号","type":"auto_number"}]`}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		if data["created"] != true || data["total"] != float64(2) {
+			t.Fatalf("unexpected output: %#v", data)
+		}
+		if _, ok := data["fields"].([]interface{}); !ok {
+			t.Fatalf("batch create must keep fields array: %#v", data)
+		}
+		if data["field_get_recommended"] != true || data["next_step"] != "field_get" || data["verification_hint"] == nil {
+			t.Fatalf("batch with auto_number must recommend readback: %#v", data)
+		}
+	})
+
 	t.Run("delete", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
@@ -1318,6 +1601,32 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
+	t.Run("list field names alias preserves quoted commas and at-sign names", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "field_id=A%2CB&field_id=%40Owner&limit=1&offset=0",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"fields":         []interface{}{"A,B", "@Owner"},
+					"record_id_list": []interface{}{"rec_alias_special"},
+					"data":           []interface{}{[]interface{}{"value-1", "value-2"}},
+					"total":          1,
+				},
+			},
+		})
+		if err := runShortcut(t, BaseRecordList, []string{
+			"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--limit", "1",
+			"--field-names", `"A,B",@Owner`, "--format", "json",
+		}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if got := stdout.String(); !strings.Contains(got, `"rec_alias_special"`) {
+			t.Fatalf("stdout=%s", got)
+		}
+	})
+
 	t.Run("list json format", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
@@ -1614,28 +1923,162 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
-	t.Run("list legacy fields flag rejected", func(t *testing.T) {
-		factory, stdout, _ := newExecuteFactory(t)
-		err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--fields", "Name"}, factory, stdout)
-		if err == nil || !strings.Contains(err.Error(), "unknown flag: --fields") {
+	t.Run("list fields alias accepts JSON array projection", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "field_id=Name&field_id=Age&limit=1&offset=0",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"fields":         []interface{}{"Name", "Age"},
+					"record_id_list": []interface{}{"rec_fields"},
+					"data":           []interface{}{[]interface{}{"Alice", 18}},
+					"total":          1,
+				},
+			},
+		})
+		if err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--limit", "1", "--fields", `["Name","Age"]`, "--format", "json"}, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
 		}
+		if got := stdout.String(); !strings.Contains(got, `"rec_fields"`) || !strings.Contains(got, `"Alice"`) {
+			t.Fatalf("stdout=%s", got)
+		}
 	})
 
-	t.Run("list field ids and field names alias are mutually exclusive", func(t *testing.T) {
-		factory, stdout, _ := newExecuteFactory(t)
-		err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "Name", "--field-names", "Age"}, factory, stdout)
-		if err == nil || !strings.Contains(err.Error(), "--field-id and --field-names are mutually exclusive") {
+	t.Run("list field names alias accepts repeated projection", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "field_id=Name&field_id=Age&limit=1&offset=0",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"fields":         []interface{}{"Name", "Age"},
+					"record_id_list": []interface{}{"rec_fields"},
+					"data":           []interface{}{[]interface{}{"Alice", 18}},
+					"total":          1,
+				},
+			},
+		})
+		if err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--limit", "1", "--field-names", "Name", "--field-names", "Age", "--format", "json"}, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
 		}
+		if got := stdout.String(); !strings.Contains(got, `"rec_fields"`) || !strings.Contains(got, `"Alice"`) {
+			t.Fatalf("stdout=%s", got)
+		}
 	})
 
-	t.Run("list legacy fields flag rejected in dry-run", func(t *testing.T) {
+	t.Run("list projection aliases report only supplied ambiguous inputs", func(t *testing.T) {
+		baseArgs := []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x"}
+		cases := []struct {
+			name       string
+			args       []string
+			wantParam  string
+			wantParams []string
+		}{
+			{name: "canonical and fields alias", args: []string{"--field-id", "Name", "--fields", `["Age"]`}, wantParam: "--field-id", wantParams: []string{"--field-id", "--fields"}},
+			{name: "canonical and field names alias", args: []string{"--field-id", "Name", "--field-names", "Age"}, wantParam: "--field-id", wantParams: []string{"--field-id", "--field-names"}},
+			{name: "compatibility aliases", args: []string{"--fields", `["Name"]`, "--field-names", "Age"}, wantParam: "--fields", wantParams: []string{"--fields", "--field-names"}},
+		}
+		for _, tc := range cases {
+			t.Run(tc.name, func(t *testing.T) {
+				factory, stdout, _ := newExecuteFactory(t)
+				args := append(append([]string{}, baseArgs...), tc.args...)
+				err := runShortcut(t, BaseRecordList, args, factory, stdout)
+				assertInvalidArgumentValidation(t, err, tc.wantParam, tc.wantParams, "mutually exclusive")
+				var validationErr *errs.ValidationError
+				if !errors.As(err, &validationErr) || validationErr.Hint != "Use only --field-id for projection." {
+					t.Fatalf("hint=%q, want canonical projection guidance", validationErr.Hint)
+				}
+			})
+		}
+	})
+
+	t.Run("search json conflict reports each supplied projection parameter", func(t *testing.T) {
 		factory, stdout, _ := newExecuteFactory(t)
-		err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--fields", "Name", "--dry-run"}, factory, stdout)
-		if err == nil || !strings.Contains(err.Error(), "unknown flag: --fields") {
+		err := runShortcut(t, BaseRecordSearch, []string{
+			"+record-search", "--base-token", "app_x", "--table-id", "tbl_x",
+			"--json", `{"keyword":"Alice","search_fields":["Name"]}`,
+			"--field-names", "Age",
+		}, factory, stdout)
+		assertInvalidArgumentValidation(t, err, "--json", []string{"--json", "--field-names"}, "mutually exclusive")
+		var validationErr *errs.ValidationError
+		if !errors.As(err, &validationErr) || !strings.Contains(validationErr.Hint, "inside --json") {
+			t.Fatalf("hint=%q, want JSON-body guidance", validationErr.Hint)
+		}
+	})
+
+	t.Run("list canonical and alias projections reject duplicates consistently", func(t *testing.T) {
+		cases := []struct {
+			name  string
+			args  []string
+			param string
+		}{
+			{name: "canonical", args: []string{"--field-id", "Cost--USD", "--field-id", "Cost--USD"}, param: "--field-id"},
+			{name: "fields alias", args: []string{"--fields", `["Cost--USD","Cost--USD"]`}, param: "--fields"},
+			{name: "field names alias", args: []string{"--field-names", "Cost--USD", "--field-names", "Cost--USD"}, param: "--field-names"},
+		}
+		for _, tc := range cases {
+			t.Run(tc.name, func(t *testing.T) {
+				factory, stdout, _ := newExecuteFactory(t)
+				args := append([]string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x"}, tc.args...)
+				err := runShortcut(t, BaseRecordList, args, factory, stdout)
+				assertInvalidArgumentValidation(t, err, tc.param, []string{tc.param}, "duplicate field id")
+			})
+		}
+	})
+
+	t.Run("search fields alias accepts JSON array projection", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		searchStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/search",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"fields":         []interface{}{"Name", "Age"},
+					"record_id_list": []interface{}{"rec_search"},
+					"data":           []interface{}{[]interface{}{"Alice", 18}},
+				},
+			},
+		}
+		reg.Register(searchStub)
+		if err := runShortcut(t, BaseRecordSearch, []string{
+			"+record-search", "--base-token", "app_x", "--table-id", "tbl_x",
+			"--keyword", "Alice", "--search-field", "Name", "--fields", `["Name","Age"]`, "--format", "json",
+		}, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
 		}
+		if body := string(searchStub.CapturedBody); !strings.Contains(body, `"select_fields":["Name","Age"]`) {
+			t.Fatalf("captured body=%s", body)
+		}
+	})
+
+	t.Run("get field names alias accepts repeated projection", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		batchStub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/batch_get",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"record_id_list": []interface{}{"rec_1"},
+					"fields":         []interface{}{"Name", "Age"},
+					"data":           []interface{}{[]interface{}{"Alice", 18}},
+				},
+			},
+		}
+		reg.Register(batchStub)
+		if err := runShortcut(t, BaseRecordGet, []string{
+			"+record-get", "--base-token", "app_x", "--table-id", "tbl_x", "--record-id", "rec_1",
+			"--field-names", "Name", "--field-names", "Age", "--format", "json",
+		}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if body := string(batchStub.CapturedBody); !strings.Contains(body, `"select_fields":["Name","Age"]`) {
+			t.Fatalf("request body=%s", body)
+		}
 	})
 
 	t.Run("get", func(t *testing.T) {
@@ -1992,16 +2435,14 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 			Body: map[string]interface{}{
 				"code": 0,
 				"data": map[string]interface{}{
-					"fields":         []interface{}{"Name"},
 					"record_id_list": []interface{}{"rec_1", "rec_2"},
-					"data":           []interface{}{[]interface{}{"Alice"}, []interface{}{"Bob"}},
 				},
 			},
 		})
-		if err := runShortcut(t, BaseRecordBatchCreate, []string{"+record-batch-create", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `{"fields":["Name"],"rows":[["Alice"],["Bob"]]}`}, factory, stdout); err != nil {
+		if err := runShortcut(t, BaseRecordBatchCreate, []string{"+record-batch-create", "--base-token", "app_x", "--table-id", "tbl_x", "--json", `{"create_records":[{"Name":"Alice"},{"Name":"Bob"}]}`}, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
 		}
-		if got := stdout.String(); !strings.Contains(got, `"record_id_list"`) || !strings.Contains(got, `"rec_1"`) || !strings.Contains(got, `"Alice"`) {
+		if got := stdout.String(); !strings.Contains(got, `"record_id_list"`) || !strings.Contains(got, `"rec_1"`) {
 			t.Fatalf("stdout=%s", got)
 		}
 	})

shortcuts/base/base_form_submit.go

@@ -26,7 +26,7 @@ var BaseFormSubmit = common.Shortcut{
 	Service:     "base",
 	Command:     "+form-submit",
 	Description: "Submit a form (fill and submit form data)",
-	Risk:        "write",
+	Risk:        "high-risk-write",
 	Scopes:      []string{"base:form:update", "docs:document.media:upload"},
 	AuthTypes:   authTypes(),
 	HasFormat:   true,
@@ -39,6 +39,7 @@ var BaseFormSubmit = common.Shortcut{
 		`Example (no attachments): --share-token shrXXXX --json '{"fields":{"Service Rating":5,"Review":"Good service"}}'`,
 		`Example (with attachments): --share-token shrXXXX --base-token basXXX --json '{"fields":{"Service Rating":5},"attachments":{"Attachment":["./report.pdf"]}}'`,
 		`Cell values in "fields" follow lark-base-cell-value.md conventions; "attachments" maps field names to local file path arrays — the CLI uploads them in parallel and merges them into the submission.`,
+		baseHighRiskYesTip,
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateFormSubmit(runtime)

shortcuts/base/base_shortcuts_test.go

@@ -28,23 +28,16 @@ func newBaseTestRuntime(stringFlags map[string]string, boolFlags map[string]bool
 }
 
 func newBaseTestRuntimeWithArrays(stringFlags map[string]string, stringArrayFlags map[string][]string, boolFlags map[string]bool, intFlags map[string]int) *common.RuntimeContext {
-	return newBaseTestRuntimeWithArraysAndSlices(stringFlags, stringArrayFlags, nil, boolFlags, intFlags)
-}
-
-func newBaseTestRuntimeWithSlices(stringFlags map[string]string, stringSliceFlags map[string][]string, boolFlags map[string]bool, intFlags map[string]int) *common.RuntimeContext {
-	return newBaseTestRuntimeWithArraysAndSlices(stringFlags, nil, stringSliceFlags, boolFlags, intFlags)
-}
-
-func newBaseTestRuntimeWithArraysAndSlices(stringFlags map[string]string, stringArrayFlags map[string][]string, stringSliceFlags map[string][]string, boolFlags map[string]bool, intFlags map[string]int) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "test"}
 	for name := range stringFlags {
 		cmd.Flags().String(name, "", "")
 	}
 	for name := range stringArrayFlags {
-		cmd.Flags().StringArray(name, nil, "")
-	}
-	for name := range stringSliceFlags {
-		cmd.Flags().StringSlice(name, nil, "")
+		if name == "field-names" {
+			cmd.Flags().StringSlice(name, nil, "")
+		} else {
+			cmd.Flags().StringArray(name, nil, "")
+		}
 	}
 	for name := range boolFlags {
 		cmd.Flags().Bool(name, false, "")
@@ -61,11 +54,6 @@ func newBaseTestRuntimeWithArraysAndSlices(stringFlags map[string]string, string
 			_ = cmd.Flags().Set(name, value)
 		}
 	}
-	for name, values := range stringSliceFlags {
-		for _, value := range values {
-			_ = cmd.Flags().Set(name, value)
-		}
-	}
 	for name, value := range boolFlags {
 		if value {
 			_ = cmd.Flags().Set(name, "true")
@@ -477,6 +465,40 @@ func TestBaseLimitPageSizeAliasIsHidden(t *testing.T) {
 	}
 }
 
+func TestBaseRecordProjectionAliasesAreHidden(t *testing.T) {
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+	}{
+		{name: "record list", shortcut: BaseRecordList},
+		{name: "record search", shortcut: BaseRecordSearch},
+		{name: "record get", shortcut: BaseRecordGet},
+	}
+
+	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]
+
+			primary := cmd.Flags().Lookup("field-id")
+			if primary == nil || primary.Hidden {
+				t.Fatalf("public projection flag --field-id missing or hidden: %#v", primary)
+			}
+			help := cmd.Flags().FlagUsages()
+			for _, aliasName := range []string{"fields", "field-names"} {
+				alias := cmd.Flags().Lookup(aliasName)
+				if alias == nil || !alias.Hidden {
+					t.Fatalf("projection alias --%s should exist and be hidden: %#v", aliasName, alias)
+				}
+				if strings.Contains(help, "--"+aliasName) {
+					t.Fatalf("help should not include hidden --%s:\n%s", aliasName, help)
+				}
+			}
+		})
+	}
+}
+
 func TestBaseDashboardHelpGuidesAgents(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -779,7 +801,8 @@ func TestBaseJSONExamplesLiveInFlagDescriptions(t *testing.T) {
 			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`,
+				"create_records contains one field map per record",
+				`{"create_records":[{"Name":"Task A","Status":"Todo"},{"Name":"Task B","Score":20}]}`,
 			},
 		},
 		{
@@ -823,9 +846,13 @@ func TestBaseRecordWriteHelpGuidesAgents(t *testing.T) {
 				"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",
+				"Sub-record/child-record path",
+				"set that link field to a parent record reference array",
+				`{"Parent Link":[{"id":"rec_xxx"}]}`,
+				"do not look for parent_record_id or a separate child-record API",
 				"CellValue happy path: text/phone/url",
-				"select -> \"Todo\"",
-				"multi-select -> [\"Tag A\",\"Tag B\"]",
+				"select (multiple=false) -> \"Todo\"",
+				"select (multiple=true) -> [\"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"}]`,
@@ -839,11 +866,11 @@ func TestBaseRecordWriteHelpGuidesAgents(t *testing.T) {
 			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",
+				"Happy path field: create_records",
+				"create_records is an array of independent record field maps",
+				`{"create_records":[{"Name":"Task A","Status":"Todo"},{"Name":"Task B","Score":20}]}`,
 				"use +field-list to confirm real writable fields",
-				"Batch create supports max 200 rows per call",
+				"Batch create supports max 200 records per call",
 				"do not immediately +record-list the same table",
 				"CellValue happy path: text/phone/url",
 				`ID-based CellValue: user/group/link fields use arrays like [{"id":"ou_xxx"}]`,
@@ -973,11 +1000,17 @@ func TestBaseFieldUpdateHelpGuidesAgents(t *testing.T) {
 			t.Fatalf("flag help missing %q:\n%s", want, help)
 		}
 	}
+	if strings.Contains(help, "reformat-existing-records") {
+		t.Fatalf("+field-update must not expose a --reformat-existing-records flag:\n%s", help)
+	}
 
 	tips := strings.Join(cmdutil.GetTips(cmd), "\n")
 	wantTips := []string{
 		`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"}]`,
+		`Example auto_number update: lark-cli base +field-update`,
+		`When --json.type is "auto_number", updating the numbering rules also reapplies them to existing numbers`,
+		"just submit the target field definition and do not add extra low-level parameters",
 		"full field-definition PUT semantics",
 		"Read the current field first with +field-get",
 		"Type conversion is allowlist-based",
@@ -990,6 +1023,9 @@ func TestBaseFieldUpdateHelpGuidesAgents(t *testing.T) {
 			t.Fatalf("tips missing %q:\n%s", want, tips)
 		}
 	}
+	if strings.Contains(tips, "--reformat-existing-records") {
+		t.Fatalf("+field-update tips must not ask agents to pass --reformat-existing-records:\n%s", tips)
+	}
 }
 
 func TestBaseAttachmentHelpGuidesAgents(t *testing.T) {
@@ -1112,6 +1148,10 @@ func TestBaseFieldValidate(t *testing.T) {
 	if err := BaseFieldUpdate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "field-id": "fld_1", "json": `{"name":"f1","type":"formula"}`}, map[string]bool{"i-have-read-guide": true}, nil)); err != nil {
 		t.Fatalf("formula update validate err=%v", err)
 	}
+	autoNumberJSON := `{"name":"编号","type":"auto_number","style":{"rules":[{"type":"text","text":"TASK-"},{"type":"created_time","date_format":"yyyyMM"},{"type":"incremental_number","length":4}]}}`
+	if err := BaseFieldUpdate.Validate(ctx, newBaseTestRuntime(map[string]string{"base-token": "b", "table-id": "t", "field-id": "fld_1", "json": autoNumberJSON}, nil, nil)); err != nil {
+		t.Fatalf("auto number update validate err=%v", err)
+	}
 }
 
 func TestBaseTableValidate(t *testing.T) {
@@ -1233,13 +1273,89 @@ func TestBaseRecordValidate(t *testing.T) {
 	)); err != nil {
 		t.Fatalf("record search json with sort-json validate err=%v", err)
 	}
-	if err := BaseRecordSearch.Validate(ctx, newBaseTestRuntime(
+	err := BaseRecordSearch.Validate(ctx, newBaseTestRuntime(
 		map[string]string{"base-token": "b", "table-id": "tbl_1", "json": `{"keyword":"Alice","search_fields":["Name"]}`, "keyword": "Bob"},
 		nil,
 		nil,
-	)); err == nil || !strings.Contains(err.Error(), "--json is mutually exclusive") {
-		t.Fatalf("err=%v", err)
+	))
+	assertInvalidArgumentValidation(t, err, "--json", []string{"--json", "--keyword"}, "mutually exclusive")
+	err = BaseRecordSearch.Validate(ctx, newBaseTestRuntimeWithArrays(
+		map[string]string{"base-token": "b", "table-id": "tbl_1", "json": `{"keyword":"Alice","search_fields":["Name"]}`, "fields": "Name"},
+		map[string][]string{"field-id": {"fld_name"}},
+		nil,
+		nil,
+	))
+	assertInvalidArgumentValidation(t, err, "--json", []string{"--json", "--field-id", "--fields"}, "mutually exclusive")
+}
+
+func TestBaseRecordSearchProjectionLimit(t *testing.T) {
+	ctx := context.Background()
+	fields := make([]string, 51)
+	for i := range fields {
+		fields[i] = "Field " + strconv.Itoa(i+1)
 	}
+
+	if err := BaseRecordSearch.Validate(ctx, newBaseTestRuntimeWithArrays(
+		map[string]string{"base-token": "b", "table-id": "tbl_1", "keyword": "Alice"},
+		map[string][]string{"search-field": {"Name"}, "field-id": fields[:50]},
+		nil,
+		nil,
+	)); err != nil {
+		t.Fatalf("50 projection fields should be accepted: %v", err)
+	}
+
+	err := BaseRecordSearch.Validate(ctx, newBaseTestRuntimeWithArrays(
+		map[string]string{"base-token": "b", "table-id": "tbl_1", "keyword": "Alice"},
+		map[string][]string{"search-field": {"Name"}, "field-id": fields},
+		nil,
+		nil,
+	))
+	assertInvalidArgumentValidation(t, err, "--field-id", []string{"--field-id"}, "maximum limit of 50")
+
+	body, marshalErr := json.Marshal(map[string]interface{}{
+		"keyword":       "Alice",
+		"search_fields": []string{"Name"},
+		"select_fields": fields,
+	})
+	if marshalErr != nil {
+		t.Fatalf("marshal search body: %v", marshalErr)
+	}
+	err = BaseRecordSearch.Validate(ctx, newBaseTestRuntime(
+		map[string]string{"base-token": "b", "table-id": "tbl_1", "json": string(body)},
+		nil,
+		nil,
+	))
+	assertInvalidArgumentValidation(t, err, "--json", []string{"--json"}, "maximum limit of 50")
+}
+
+func TestRecordSearchJSONNullProjectionIsOmitted(t *testing.T) {
+	runtime := newBaseTestRuntime(map[string]string{
+		"json": `{"keyword":"Alice","search_fields":["Name"],"select_fields":null,"sort":{"sort_config":[{"field":"Updated","desc":true}]}}`,
+	}, nil, nil)
+	body, err := recordSearchJSONBody(runtime)
+	if err != nil {
+		t.Fatalf("recordSearchJSONBody() error = %v", err)
+	}
+	if _, exists := body["select_fields"]; exists {
+		t.Fatalf("select_fields:null must normalize to omitted, body=%#v", body)
+	}
+	if sortConfig, ok := body["sort"].([]interface{}); !ok || len(sortConfig) != 1 {
+		t.Fatalf("sort normalization must continue after omitting null select_fields, body=%#v", body)
+	}
+}
+
+func TestBaseRecordSearchJSONProjectionParamIgnoresFlagLikeFieldNames(t *testing.T) {
+	ctx := context.Background()
+	err := BaseRecordSearch.Validate(ctx, newBaseTestRuntime(
+		map[string]string{
+			"base-token": "b",
+			"table-id":   "tbl_1",
+			"json":       `{"keyword":"cost","search_fields":["Name"],"select_fields":["Cost--USD","Cost--USD"]}`,
+		},
+		nil,
+		nil,
+	))
+	assertInvalidArgumentValidation(t, err, "--json", []string{"--json"}, "duplicate field id")
 }
 
 func TestBasePaginationValidationRejectsOutOfRange(t *testing.T) {
@@ -1940,8 +2056,8 @@ func TestBaseFormSubmitShortcut(t *testing.T) {
 		if s.Service != "base" {
 			t.Fatalf("Service=%q want base", s.Service)
 		}
-		if s.Risk != "write" {
-			t.Fatalf("Risk=%q want write", s.Risk)
+		if s.Risk != "high-risk-write" {
+			t.Fatalf("Risk=%q want high-risk-write", s.Risk)
 		}
 		if !s.HasFormat {
 			t.Fatal("HasFormat should be true")
@@ -2241,6 +2357,7 @@ func TestExecuteFormSubmit(t *testing.T) {
 			"+form-submit",
 			"--share-token", "shr_exec1",
 			"--json", `{"fields":{"Name":"Alice","Rating":5}}`,
+			"--yes",
 		}
 		if err := runShortcut(t, BaseFormSubmit, args, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
@@ -2309,6 +2426,7 @@ func TestExecuteFormSubmit(t *testing.T) {
 			"--share-token", "shr_exec6",
 			"--base-token", "bas_exec6",
 			"--json", `{"attachments":{"File":["./nonexistent.pdf"]}}`,
+			"--yes",
 		}
 		err := runShortcut(t, BaseFormSubmit, args, factory, stdout)
 		if err == nil {
@@ -2357,6 +2475,7 @@ func TestExecuteFormSubmit(t *testing.T) {
 			"--share-token", "shr_dedup",
 			"--base-token", "bas_dedup",
 			"--json", `{"attachments":{"FieldA":["./shared.pdf"],"FieldB":["./shared.pdf"]}}`,
+			"--yes",
 		}
 		if err := runShortcut(t, BaseFormSubmit, args, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
@@ -2368,6 +2487,33 @@ func TestExecuteFormSubmit(t *testing.T) {
 	})
 }
 
+// TestFormSubmitRequiresConfirmation pins the high-risk-write classification:
+// without --yes the runner's confirmation gate must fire before Execute runs,
+// returning a typed confirmation_required error and touching no API.
+func TestFormSubmitRequiresConfirmation(t *testing.T) {
+	if BaseFormSubmit.Risk != "high-risk-write" {
+		t.Fatalf("Risk=%q want high-risk-write", BaseFormSubmit.Risk)
+	}
+
+	factory, stdout, _ := newExecuteFactory(t)
+	args := []string{
+		"+form-submit",
+		"--share-token", "shr_confirm",
+		"--json", `{"fields":{"Rating":5}}`,
+	}
+	err := runShortcut(t, BaseFormSubmit, args, factory, stdout)
+	if err == nil {
+		t.Fatal("expected confirmation_required error without --yes")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T: %v", err, err)
+	}
+	if problem.Subtype != errs.SubtypeConfirmationRequired {
+		t.Fatalf("subtype=%q want %q", problem.Subtype, errs.SubtypeConfirmationRequired)
+	}
+}
+
 func TestUploadAttachmentsParallel(t *testing.T) {
 	t.Run("single file upload via execute path", func(t *testing.T) {
 		tmpDir := t.TempDir()
@@ -2404,6 +2550,7 @@ func TestUploadAttachmentsParallel(t *testing.T) {
 			"--share-token", "shr_para1",
 			"--base-token", "bas_para1",
 			"--json", `{"attachments":{"Doc":["./doc.txt"]}}`,
+			"--yes",
 		}
 		if err := runShortcut(t, BaseFormSubmit, args, factory, stdout); err != nil {
 			t.Fatalf("err=%v", err)
@@ -2438,6 +2585,7 @@ func TestUploadAttachmentsParallel(t *testing.T) {
 			"--share-token", "shr_err",
 			"--base-token", "bas_err",
 			"--json", `{"attachments":{"Bad":["./bad.txt"]}}`,
+			"--yes",
 		}
 		err := runShortcut(t, BaseFormSubmit, args, factory, stdout)
 		if err == nil {

shortcuts/base/field_ops.go

@@ -5,6 +5,7 @@ package base
 
 import (
 	"context"
+	"fmt"
 	"strings"
 	"time"
 
@@ -36,7 +37,10 @@ func dryRunFieldGet(_ context.Context, runtime *common.RuntimeContext) *common.D
 
 func dryRunFieldCreate(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 	pc := newParseCtx(runtime)
-	bodies, _ := parseFieldCreateBodies(pc, runtime.Str("json"))
+	bodies, err := parseFieldCreateBodies(pc, runtime.Str("json"))
+	if err != nil {
+		return common.NewDryRunAPI().Desc(fmt.Sprintf("dry-run validation failed: %v", err))
+	}
 	dr := common.NewDryRunAPI().
 		Set("base_token", runtime.Str("base-token")).
 		Set("table_id", baseTableID(runtime))
@@ -48,7 +52,10 @@ func dryRunFieldCreate(_ context.Context, runtime *common.RuntimeContext) *commo
 
 func dryRunFieldUpdate(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 	pc := newParseCtx(runtime)
-	body, _ := parseJSONObject(pc, runtime.Str("json"), "json")
+	body, err := parseJSONObject(pc, runtime.Str("json"), "json")
+	if err != nil {
+		return common.NewDryRunAPI().Desc(fmt.Sprintf("dry-run validation failed: %v", err))
+	}
 	return common.NewDryRunAPI().
 		PUT("/open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id").
 		Body(body).
@@ -166,10 +173,10 @@ func executeFieldCreate(runtime *common.RuntimeContext) error {
 		fields = append(fields, data)
 	}
 	if len(fields) == 1 {
-		runtime.Out(map[string]interface{}{"field": fields[0], "created": true}, nil)
+		runtime.Out(fieldCreateResult(map[string]interface{}{"field": fields[0], "created": true}, bodies[0]), nil)
 		return nil
 	}
-	runtime.Out(map[string]interface{}{"fields": fields, "created": true, "total": len(fields)}, nil)
+	runtime.Out(fieldCreateBatchResult(map[string]interface{}{"fields": fields, "created": true, "total": len(fields)}, bodies), nil)
 	return nil
 }
 
@@ -197,10 +204,101 @@ func executeFieldUpdate(runtime *common.RuntimeContext) error {
 	if err != nil {
 		return err
 	}
-	runtime.Out(map[string]interface{}{"field": data, "updated": true}, nil)
+	runtime.Out(fieldUpdateResult(map[string]interface{}{"field": data, "updated": true}, body), nil)
 	return nil
 }
 
+func fieldCreateResult(result map[string]interface{}, submitted map[string]interface{}) map[string]interface{} {
+	readbackRecommended, reason := fieldWriteReadbackRecommendation(submitted, "create")
+	return attachFieldReadbackRecommendation(result, readbackRecommended, reason)
+}
+
+// fieldCreateBatchResult attaches the same top-level readback contract to a
+// multi-field create. It recommends +field-get when any submitted field is a
+// computed/linked/generated (or unknown) type, so agents know when to verify
+// server state without breaking the existing fields/total structure.
+func fieldCreateBatchResult(result map[string]interface{}, submitted []map[string]interface{}) map[string]interface{} {
+	recommend := false
+	reason := "simple fields created successfully; use +field-get only when extra properties or explicit verification are needed"
+	for _, body := range submitted {
+		if rec, r := fieldWriteReadbackRecommendation(body, "create"); rec {
+			recommend = true
+			reason = r
+			break
+		}
+	}
+	return attachFieldReadbackRecommendation(result, recommend, reason)
+}
+
+func fieldUpdateResult(result map[string]interface{}, submitted map[string]interface{}) map[string]interface{} {
+	returnedType := normalizeFieldType(fieldResultType(result["field"]))
+	submittedType := normalizeFieldType(common.GetString(submitted, "type"))
+	readbackRecommended, reason := fieldUpdateReadbackRecommendation(returnedType, submittedType)
+	return attachFieldReadbackRecommendation(result, readbackRecommended, reason)
+}
+
+func fieldUpdateReadbackRecommendation(returnedType, submittedType string) (bool, string) {
+	if returnedType != "" && submittedType != "" && returnedType != submittedType {
+		return true, fmt.Sprintf("field update submitted type %q but the server returned type %q; run +field-get and verify record values before declaring completion", submittedType, returnedType)
+	}
+
+	fieldType := returnedType
+	if fieldType == "" {
+		fieldType = submittedType
+	}
+	if recommended, reason := fieldTypeReadbackRecommendation(fieldType, "update"); recommended {
+		return true, reason + "; sample record values when generated, computed, or converted values are in scope"
+	}
+	return true, fmt.Sprintf("field update request succeeded for type %q, but +field-update cannot determine the previous type; run +field-get and sample record values if the type changed before declaring completion", fieldType)
+}
+
+func attachFieldReadbackRecommendation(result map[string]interface{}, readbackRecommended bool, reason string) map[string]interface{} {
+	result["field_get_recommended"] = readbackRecommended
+	result["verification_hint"] = reason
+	if readbackRecommended {
+		result["next_step"] = "field_get"
+	} else {
+		result["next_step"] = "done"
+	}
+	return result
+}
+
+func fieldWriteReadbackRecommendation(submitted map[string]interface{}, operation string) (bool, string) {
+	fieldType := normalizeFieldType(common.GetString(submitted, "type"))
+	return fieldTypeReadbackRecommendation(fieldType, operation)
+}
+
+func fieldTypeReadbackRecommendation(fieldType, operation string) (bool, string) {
+	fieldType = normalizeFieldType(fieldType)
+	switch fieldType {
+	case "formula", "lookup", "auto_number", "link":
+		return true, fmt.Sprintf("computed, linked, or generated field %s should be verified with +field-get before declaring completion", operation)
+	case "text", "number", "select", "datetime", "checkbox", "user", "group_chat", "attachment", "location":
+		return false, fmt.Sprintf("simple field %s returned successfully; use +field-get only when extra properties or explicit verification are needed", operation)
+	default:
+		return true, "unknown or uncommon field type; run +field-get to avoid assuming the submitted JSON fully describes server state"
+	}
+}
+
+func normalizeFieldType(fieldType string) string {
+	return strings.ToLower(strings.TrimSpace(fieldType))
+}
+
+func fieldResultType(value interface{}) string {
+	field, ok := value.(map[string]interface{})
+	if !ok {
+		return ""
+	}
+	if fieldType := strings.ToLower(strings.TrimSpace(common.GetString(field, "type"))); fieldType != "" {
+		return fieldType
+	}
+	nested, ok := field["field"].(map[string]interface{})
+	if !ok {
+		return ""
+	}
+	return strings.ToLower(strings.TrimSpace(common.GetString(nested, "type")))
+}
+
 func executeFieldDelete(runtime *common.RuntimeContext) error {
 	baseToken := runtime.Str("base-token")
 	tableIDValue := baseTableID(runtime)

shortcuts/base/field_search_options.go

@@ -27,7 +27,7 @@ var BaseFieldSearchOptions = common.Shortcut{
 	},
 	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.",
+		"Use only for select fields, whether multiple is false or true.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if err := validateLimitPageSizeAlias(runtime); err != nil {

shortcuts/base/field_update.go

@@ -27,7 +27,9 @@ var BaseFieldUpdate = common.Shortcut{
 		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`,
+		`Example auto_number update: lark-cli base +field-update --base-token <base_token> --table-id <table_id> --field-id "编号" --json '{"name":"编号","type":"auto_number","style":{"rules":[{"type":"text","text":"TASK-"},{"type":"created_time","date_format":"yyyyMM"},{"type":"text","text":"-"},{"type":"incremental_number","length":4}]}}' --yes`,
 		"Update uses full field-definition PUT semantics. Read the current field first with +field-get, then send the target state.",
+		`When --json.type is "auto_number", updating the numbering rules also reapplies them to existing numbers; just submit the target field definition and do not add extra low-level parameters.`,
 		"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.",
 		"Agent hint: use the lark-base skill's field-update guide for JSON shape, type-conversion rules, and limits.",

shortcuts/base/helpers_test.go

@@ -238,14 +238,14 @@ func TestRecordSelectionHelpers(t *testing.T) {
 		t.Fatalf("err=%v", err)
 	}
 
-	fields, err = resolveRecordGetSelectFields(nil, map[string]interface{}{"select_fields": []interface{}{"Name"}})
+	fields, err = resolveRecordGetSelectFields(nil, "--field-id", map[string]interface{}{"select_fields": []interface{}{"Name"}})
 	if err != nil || !reflect.DeepEqual(fields, []string{"Name"}) {
 		t.Fatalf("fields=%v err=%v", fields, err)
 	}
-	if _, err := resolveRecordGetSelectFields([]string{"Name"}, map[string]interface{}{"select_fields": []interface{}{"Age"}}); err == nil || !strings.Contains(err.Error(), "mutually exclusive") {
+	if _, err := resolveRecordGetSelectFields([]string{"Name"}, "--field-id", map[string]interface{}{"select_fields": []interface{}{"Age"}}); err == nil || !strings.Contains(err.Error(), "mutually exclusive") {
 		t.Fatalf("err=%v", err)
 	}
-	if _, err := resolveRecordGetSelectFields(nil, map[string]interface{}{"select_fields": []interface{}{}}); err == nil || !strings.Contains(err.Error(), "must not be empty") {
+	if _, err := resolveRecordGetSelectFields(nil, "--field-id", map[string]interface{}{"select_fields": []interface{}{}}); err == nil || !strings.Contains(err.Error(), "must not be empty") {
 		t.Fatalf("err=%v", err)
 	}
 

shortcuts/base/record_batch_create.go

@@ -19,12 +19,13 @@ var BaseRecordBatchCreate = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		tableRefFlag(true),
-		{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},
+		{Name: "json", Desc: `batch create JSON object; create_records contains one field map per record, e.g. {"create_records":[{"Name":"Task A","Status":"Todo"},{"Name":"Task B","Score":20}]}`, 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.",
+		"Happy path field: create_records is an array of independent record field maps.",
+		`Example: {"create_records":[{"Name":"Task A","Status":"Todo"},{"Name":"Task B","Score":20}]}.`,
 		"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.",
+		"Batch create supports max 200 records per call.",
 		"After batch-creating known helper rows, use the returned record IDs and your submitted rows; do not immediately +record-list the same table unless you need server-normalized formula/lookup values or failure diagnosis.",
 		"Use the record-batch-create guide for command limits and edge cases.",
 	}, recordCellValueHappyPathTips...),

shortcuts/base/record_get.go

@@ -21,7 +21,9 @@ var BaseRecordGet = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		{Name: "record-id", Type: "string_array", Desc: "record ID (repeatable)"},
-		{Name: "field-id", Type: "string_array", Desc: "field ID or name to project; repeat to keep only needed columns"},
+		recordProjectionFieldFlag("field ID or name to project; repeat to keep only needed columns"),
+		recordProjectionAliasFlag("fields"),
+		recordProjectionAliasFlag("field-names"),
 		{Name: "json", Desc: `JSON object with record_id_list, e.g. {"record_id_list":["rec_xxx"]}`},
 		recordReadFormatFlag(),
 	},

shortcuts/base/record_list.go

@@ -20,8 +20,9 @@ var BaseRecordList = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		tableRefFlag(true),
-		recordListFieldRefFlag(),
-		recordListFieldNamesAliasFlag(),
+		recordProjectionFieldFlag("field ID or name to include; repeat to project only needed fields"),
+		recordProjectionAliasFlag("fields"),
+		recordProjectionAliasFlag("field-names"),
 		recordListViewRefFlag(),
 		recordFilterFlag(),
 		recordSortFlag(),
@@ -44,9 +45,6 @@ var BaseRecordList = common.Shortcut{
 		"Use --field-id repeatedly to keep output small and aligned with the task.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if err := validateRecordListFieldAlias(runtime); err != nil {
-			return err
-		}
 		if err := validateRecordReadFormat(runtime); err != nil {
 			return err
 		}
@@ -61,6 +59,9 @@ var BaseRecordList = common.Shortcut{
 				return err
 			}
 		}
+		if _, err := recordProjectionFields(runtime); err != nil {
+			return err
+		}
 		return validateRecordQueryOptions(runtime)
 	},
 	DryRun: dryRunRecordList,
@@ -72,22 +73,6 @@ var BaseRecordList = common.Shortcut{
 	},
 }
 
-func recordListFieldRefFlag() common.Flag {
-	flag := fieldRefFlag(false)
-	flag.Type = "string_array"
-	flag.Desc = "field ID or name to include; repeat to project only needed fields"
-	return flag
-}
-
-func recordListFieldNamesAliasFlag() common.Flag {
-	return common.Flag{
-		Name:   "field-names",
-		Type:   "string_slice",
-		Desc:   "hidden alias for --field-id; accepts comma-separated field names",
-		Hidden: true,
-	}
-}
-
 func recordListViewRefFlag() common.Flag {
 	flag := viewRefFlag(false)
 	flag.Desc = "view ID or name; omit for reading all table records, or set to read a user-specified or temporary filtered/sorted view"
@@ -102,10 +87,3 @@ func recordReadFormatFlag() common.Flag {
 		Desc:    "output format: markdown (default) | json",
 	}
 }
-
-func validateRecordListFieldAlias(runtime *common.RuntimeContext) error {
-	if runtime.Changed("field-id") && runtime.Changed("field-names") {
-		return baseFlagErrorf("--field-id and --field-names are mutually exclusive; use --field-id")
-	}
-	return nil
-}

shortcuts/base/record_ops.go

@@ -5,18 +5,21 @@ package base
 
 import (
 	"context"
+	"errors"
 	"net/url"
 	"strconv"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
 const maxRecordSelectionCount = 200
 const maxBatchGetSelectFieldCount = 100
+const maxRecordSearchSelectFieldCount = 50
 
 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.`,
+	`CellValue happy path: text/phone/url -> "text"; number/currency/percent/rating -> 12.5; select (multiple=false) -> "Todo"; select (multiple=true) -> ["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.",
@@ -46,7 +49,6 @@ func validateRecordSelection(runtime *common.RuntimeContext) error {
 
 func resolveRecordSelection(runtime *common.RuntimeContext) (recordSelection, error) {
 	recordIDs := runtime.StrArray("record-id")
-	fieldIDs := runtime.StrArray("field-id")
 	jsonRaw := strings.TrimSpace(runtime.Str("json"))
 	if len(recordIDs) > 0 && jsonRaw != "" {
 		return recordSelection{}, baseFlagErrorf("--record-id and --json are mutually exclusive")
@@ -69,7 +71,11 @@ func resolveRecordSelection(runtime *common.RuntimeContext) (recordSelection, er
 		if err != nil {
 			return recordSelection{}, err
 		}
-		selectFields, err := resolveRecordGetSelectFields(fieldIDs, body)
+		projectionFields, err := recordProjectionFields(runtime)
+		if err != nil {
+			return recordSelection{}, err
+		}
+		selectFields, err := resolveRecordGetSelectFields(projectionFields, recordProjectionParam(runtime), body)
 		if err != nil {
 			return recordSelection{}, err
 		}
@@ -83,7 +89,11 @@ func resolveRecordSelection(runtime *common.RuntimeContext) (recordSelection, er
 	if err != nil {
 		return recordSelection{}, err
 	}
-	selectFields, err := resolveRecordGetSelectFields(fieldIDs, nil)
+	projectionFields, err := recordProjectionFields(runtime)
+	if err != nil {
+		return recordSelection{}, err
+	}
+	selectFields, err := resolveRecordGetSelectFields(projectionFields, recordProjectionParam(runtime), nil)
 	if err != nil {
 		return recordSelection{}, err
 	}
@@ -104,20 +114,20 @@ func normalizeRecordIDs(values interface{}) ([]string, error) {
 	})
 }
 
-func resolveRecordGetSelectFields(flagFields []string, body map[string]interface{}) ([]string, error) {
+func resolveRecordGetSelectFields(flagFields []string, projectionParam string, body map[string]interface{}) ([]string, error) {
 	fromFlags, err := normalizeRecordGetSelectFields(flagFields)
 	if err != nil {
-		return nil, err
+		return nil, withValidationParam(err, projectionParam)
 	}
 	if body == nil {
 		return fromFlags, nil
 	}
 	rawJSONFields, ok := body["select_fields"]
-	if !ok {
+	if !ok || rawJSONFields == nil {
 		return fromFlags, nil
 	}
 	if len(fromFlags) > 0 {
-		return nil, baseFlagErrorf(`--field-id and --json field "select_fields" are mutually exclusive`)
+		return nil, baseFlagErrorf(`%s and --json field "select_fields" are mutually exclusive`, projectionParam)
 	}
 	items, ok := rawJSONFields.([]interface{})
 	if !ok {
@@ -128,18 +138,26 @@ func resolveRecordGetSelectFields(flagFields []string, body map[string]interface
 	}
 	normalized, err := normalizeRecordGetSelectFields(items)
 	if err != nil {
-		return nil, err
+		return nil, withValidationParam(err, "--json")
 	}
 	return normalized, nil
 }
 
 func normalizeRecordGetSelectFields(values interface{}) ([]string, error) {
+	return normalizeRecordSelectFields(values, maxBatchGetSelectFieldCount)
+}
+
+func normalizeRecordSearchSelectFields(values interface{}) ([]string, error) {
+	return normalizeRecordSelectFields(values, maxRecordSearchSelectFieldCount)
+}
+
+func normalizeRecordSelectFields(values interface{}, max int) ([]string, error) {
 	return normalizeStringList(values, stringListNormalizeOptions{
 		typeError:     "field selection must be a string array",
 		itemName:      "field selection item",
 		duplicateName: "field id",
 		limitName:     "field selection",
-		max:           maxBatchGetSelectFieldCount,
+		max:           max,
 		allowNil:      true,
 		allowEmpty:    true,
 	})
@@ -211,7 +229,11 @@ func dryRunRecordList(_ context.Context, runtime *common.RuntimeContext) *common
 	params := url.Values{}
 	params.Set("offset", strconv.Itoa(offset))
 	params.Set("limit", strconv.Itoa(limit))
-	for _, field := range recordListFields(runtime) {
+	fields, err := recordProjectionFields(runtime)
+	if err != nil {
+		return common.NewDryRunAPI()
+	}
+	for _, field := range fields {
 		params.Add("field_id", field)
 	}
 	if viewID := runtime.Str("view-id"); viewID != "" {
@@ -375,11 +397,121 @@ func validateRecordJSON(runtime *common.RuntimeContext) error {
 	return err
 }
 
-func recordListFields(runtime *common.RuntimeContext) []string {
-	if runtime.Changed("field-names") {
-		return runtime.StrSlice("field-names")
+func recordProjectionFieldFlag(desc string) common.Flag {
+	flag := fieldRefFlag(false)
+	flag.Type = "string_array"
+	flag.Desc = desc
+	return flag
+}
+
+func recordProjectionAliasFlag(name string) common.Flag {
+	flagType := "string_array"
+	if name == "field-names" {
+		// Preserve the original compatibility contract: --field-names uses
+		// pflag's CSV parser, including quoted commas, and treats @ literally.
+		flagType = "string_slice"
 	}
-	return runtime.StrArray("field-id")
+	return common.Flag{
+		Name:   name,
+		Type:   flagType,
+		Desc:   "hidden alias for --field-id projection",
+		Hidden: true,
+	}
+}
+
+func recordProjectionParam(runtime *common.RuntimeContext) string {
+	switch {
+	case runtime.Changed("fields"):
+		return "--fields"
+	case runtime.Changed("field-names"):
+		return "--field-names"
+	default:
+		return "--field-id"
+	}
+}
+
+func withValidationParam(err error, param string) error {
+	if err == nil || param == "" {
+		return err
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		return err
+	}
+	reason := validationErr.Error()
+	// The caller knows which input produced this validation error. Replace any
+	// params inferred from the rendered message: field values such as Cost--USD
+	// must not be mistaken for a --USD flag.
+	validationErr.Param = param
+	validationErr.Params = []errs.InvalidParam{{Name: param, Reason: reason}}
+	return err
+}
+
+func recordProjectionFields(runtime *common.RuntimeContext) ([]string, error) {
+	return recordProjectionFieldsWithLimit(runtime, maxBatchGetSelectFieldCount)
+}
+
+func recordSearchProjectionFields(runtime *common.RuntimeContext) ([]string, error) {
+	return recordProjectionFieldsWithLimit(runtime, maxRecordSearchSelectFieldCount)
+}
+
+func recordProjectionFieldsWithLimit(runtime *common.RuntimeContext, max int) ([]string, error) {
+	fieldIDs := runtime.StrArray("field-id")
+	fieldIDsSet := runtime.Changed("field-id")
+	fieldsSet := runtime.Changed("fields")
+	fieldNamesSet := runtime.Changed("field-names")
+	projectionParams := make([]string, 0, 3)
+	if fieldIDsSet {
+		projectionParams = append(projectionParams, "--field-id")
+	}
+	if fieldsSet {
+		projectionParams = append(projectionParams, "--fields")
+	}
+	if fieldNamesSet {
+		projectionParams = append(projectionParams, "--field-names")
+	}
+	if len(projectionParams) > 1 {
+		invalidParams := make([]errs.InvalidParam, 0, len(projectionParams))
+		for _, param := range projectionParams {
+			invalidParams = append(invalidParams, errs.InvalidParam{Name: param, Reason: "mutually exclusive"})
+		}
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s are mutually exclusive", strings.Join(projectionParams, " and ")).
+			WithParam(projectionParams[0]).
+			WithParams(invalidParams...).
+			WithHint("Use only --field-id for projection.")
+	}
+	if fieldsSet {
+		return recordProjectionAliasFields(runtime, "fields", max)
+	}
+	if fieldNamesSet {
+		return recordProjectionAliasFields(runtime, "field-names", max)
+	}
+	fields, err := normalizeRecordSelectFields(fieldIDs, max)
+	return fields, withValidationParam(err, "--field-id")
+}
+
+func recordProjectionAliasFields(runtime *common.RuntimeContext, flagName string, max int) ([]string, error) {
+	var fields []string
+	if flagName == "field-names" {
+		fields = runtime.StrSlice(flagName)
+	} else {
+		pc := newParseCtx(runtime)
+		values := runtime.StrArray(flagName)
+		fields = make([]string, 0, len(values))
+		for _, raw := range values {
+			parsed, err := parseStringListFlexible(pc, raw, flagName)
+			if err != nil {
+				return nil, withValidationParam(err, "--"+flagName)
+			}
+			fields = append(fields, parsed...)
+		}
+	}
+	if len(fields) == 0 {
+		err := baseFlagErrorf("--%s must include at least one field", flagName)
+		return nil, withValidationParam(err, "--"+flagName)
+	}
+	normalized, err := normalizeRecordSelectFields(fields, max)
+	return normalized, withValidationParam(err, "--"+flagName)
 }
 
 func executeRecordList(runtime *common.RuntimeContext) error {
@@ -392,7 +524,10 @@ func executeRecordList(runtime *common.RuntimeContext) error {
 	}
 	limit := getPaginationLimit(runtime)
 	params := map[string]interface{}{"offset": offset, "limit": limit}
-	fields := recordListFields(runtime)
+	fields, err := recordProjectionFields(runtime)
+	if err != nil {
+		return err
+	}
 	if len(fields) > 0 {
 		params["field_id"] = fields
 	}

shortcuts/base/record_query.go

@@ -9,6 +9,7 @@ import (
 	"net/url"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -174,7 +175,10 @@ func recordSearchFlagBody(runtime *common.RuntimeContext) (map[string]interface{
 	if len(searchFields) > 0 {
 		body["search_fields"] = searchFields
 	}
-	selectFields := recordListFields(runtime)
+	selectFields, err := recordSearchProjectionFields(runtime)
+	if err != nil {
+		return nil, err
+	}
 	if len(selectFields) > 0 {
 		body["select_fields"] = selectFields
 	}
@@ -203,6 +207,19 @@ func recordSearchJSONBody(runtime *common.RuntimeContext) (map[string]interface{
 }
 
 func normalizeRecordSearchJSONBody(body map[string]interface{}) error {
+	if rawSelectFields, ok := body["select_fields"]; ok {
+		if rawSelectFields == nil {
+			delete(body, "select_fields")
+		} else {
+			selectFields, err := normalizeRecordSearchSelectFields(rawSelectFields)
+			if err != nil {
+				return withValidationParam(err, "--json")
+			}
+			if len(selectFields) > 0 {
+				body["select_fields"] = selectFields
+			}
+		}
+	}
 	if rawSort, ok := body["sort"]; ok {
 		if sortConfig, err := normalizeRecordSortValue(rawSort, "--json.sort"); err == nil {
 			body["sort"] = sortConfig
@@ -219,8 +236,20 @@ func validateRecordSearchFlags(runtime *common.RuntimeContext) error {
 	}
 	jsonRaw := strings.TrimSpace(runtime.Str("json"))
 	if jsonRaw != "" {
-		if recordSearchHasJSONExclusiveFlagInputs(runtime) {
-			return baseFlagErrorf("--json is mutually exclusive with keyword/search/projection/pagination flags; put those fields inside --json, or omit --json")
+		if exclusiveParams := recordSearchJSONExclusiveFlagParams(runtime); len(exclusiveParams) > 0 {
+			allParams := append([]string{"--json"}, exclusiveParams...)
+			invalidParams := make([]errs.InvalidParam, 0, len(allParams))
+			for _, param := range allParams {
+				invalidParams = append(invalidParams, errs.InvalidParam{Name: param, Reason: "mutually exclusive"})
+			}
+			return errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"--json is mutually exclusive with %s",
+				strings.Join(exclusiveParams, " and "),
+			).
+				WithParam("--json").
+				WithParams(invalidParams...).
+				WithHint("Put keyword, search, projection, view, and pagination fields inside --json, or omit --json.")
 		}
 		_, err := recordSearchJSONBody(runtime)
 		return err
@@ -242,17 +271,31 @@ func validateRecordSearchFlags(runtime *common.RuntimeContext) error {
 			return err
 		}
 	}
+	if _, err := recordSearchProjectionFields(runtime); err != nil {
+		return err
+	}
 	return validateRecordQueryOptions(runtime)
 }
 
-func recordSearchHasJSONExclusiveFlagInputs(runtime *common.RuntimeContext) bool {
-	return strings.TrimSpace(runtime.Str("keyword")) != "" ||
-		len(runtime.StrArray("search-field")) > 0 ||
-		len(recordListFields(runtime)) > 0 ||
-		runtime.Str("view-id") != "" ||
-		runtime.Changed("offset") ||
-		runtime.Changed("limit") ||
-		runtime.Changed("page-size")
+func recordSearchJSONExclusiveFlagParams(runtime *common.RuntimeContext) []string {
+	names := []string{
+		"keyword",
+		"search-field",
+		"field-id",
+		"fields",
+		"field-names",
+		"view-id",
+		"offset",
+		"limit",
+		"page-size",
+	}
+	params := make([]string, 0, len(names))
+	for _, name := range names {
+		if runtime.Changed(name) {
+			params = append(params, "--"+name)
+		}
+	}
+	return params
 }
 
 func formatRecordQueryPriorityTip() string {

shortcuts/base/record_search.go

@@ -23,7 +23,9 @@ var BaseRecordSearch = common.Shortcut{
 		{Name: "json", Desc: `record search JSON object for the full request body, e.g. {"keyword":"Alice","search_fields":["Name"],"select_fields":["Name","Status"],"filter":{"logic":"and","conditions":[]},"sort":[{"field":"Updated","desc":true}],"limit":50}; escape hatch for advanced cases`},
 		{Name: "keyword", Desc: "keyword for record search; required unless --json is used"},
 		{Name: "search-field", Type: "string_array", Desc: "field ID or name to search; repeat for multiple fields; required unless --json is used"},
-		recordListFieldRefFlag(),
+		recordProjectionFieldFlag("field ID or name to include; repeat to project only needed fields"),
+		recordProjectionAliasFlag("fields"),
+		recordProjectionAliasFlag("field-names"),
 		recordListViewRefFlag(),
 		recordFilterFlag(),
 		recordSortFlag(),

shortcuts/base/record_upsert.go

@@ -26,6 +26,7 @@ var BaseRecordUpsert = common.Shortcut{
 		"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.",
+		"Sub-record/child-record path: when a one-way/two-way link field represents hierarchy, create a normal record and set that link field to a parent record reference array, e.g. {\"Parent Link\":[{\"id\":\"rec_xxx\"}]}; do not look for parent_record_id or a separate child-record API.",
 		"Use the record-upsert guide for command limits and edge cases.",
 	}, recordCellValueHappyPathTips...),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/calendar/calendar_create.go

@@ -67,6 +67,25 @@ func parseAttendees(attendeesStr string, currentUserId string) ([]map[string]str
 	return attendees, nil
 }
 
+// selfAttendeeId resolves the open_id of the identity running the command so it
+// can be auto-added to the attendee list, mirroring how a human user is joined
+// to their own events. For a user it comes from config; for a bot it is fetched
+// from /bot/v3/info. If the bot lookup fails, we warn and return "" so the event
+// is still created with the explicitly requested attendees.
+func selfAttendeeId(runtime *common.RuntimeContext) string {
+	if !runtime.IsBot() {
+		return runtime.UserOpenId()
+	}
+	info, err := runtime.BotInfo()
+	if err != nil {
+		fmt.Fprintf(runtime.IO().ErrOut,
+			"[calendar +create] warning: could not resolve bot identity to add it as an attendee (%v); proceeding without the bot\n",
+			err)
+		return ""
+	}
+	return info.OpenID
+}
+
 func attendeesIncludeRoom(attendees []map[string]string) bool {
 	for _, attendee := range attendees {
 		if attendee["type"] == "resource" || attendee["room_id"] != "" {
@@ -176,7 +195,9 @@ var CalendarCreate = common.Shortcut{
 		eventData := buildEventData(runtime, startTs, endTs)
 		attendeesStr := runtime.Str("attendee-ids")
 		if attendeesStr != "" {
-			// Note: dry-run doesn't network resolve the current user's open_id.
+			// Note: dry-run doesn't network resolve the running identity's own
+			// open_id (user from config, bot from /bot/v3/info), so the auto-joined
+			// self attendee is not shown here.
 			attendees, err := parseAttendees(attendeesStr, "")
 			if err != nil {
 				return common.NewDryRunAPI().Set("error", err.Error())
@@ -228,11 +249,8 @@ var CalendarCreate = common.Shortcut{
 
 		// Add attendees if specified
 		if attendeesStr := runtime.Str("attendee-ids"); attendeesStr != "" {
-			currentUserId := ""
-			if !runtime.IsBot() {
-				currentUserId = runtime.UserOpenId()
-			}
-			attendees, err := parseAttendees(attendeesStr, currentUserId)
+			selfId := selfAttendeeId(runtime)
+			attendees, err := parseAttendees(attendeesStr, selfId)
 			if err != nil {
 				return withParam(err, "--attendee-ids")
 			}

shortcuts/calendar/calendar_test.go

@@ -251,6 +251,136 @@ func TestCreate_WithAttendees_Success(t *testing.T) {
 	}
 }
 
+func TestCreate_WithAttendees_AsBot_AddsBotSelf(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/bot/v3/info",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"bot": map[string]interface{}{
+				"open_id":  "ou_botself",
+				"app_name": "Test Bot",
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id": "evt_bot",
+					"summary":  "Bot Sync",
+					"start_time": map[string]interface{}{
+						"timestamp": "1742515200",
+					},
+					"end_time": map[string]interface{}{
+						"timestamp": "1742518800",
+					},
+				},
+			},
+		},
+	})
+	attendeesStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/events/evt_bot/attendees",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(attendeesStub)
+
+	err := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Bot Sync",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--attendee-ids", "ou_user1",
+		"--as", "bot",
+	}, f, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if attendeesStub.CapturedBody == nil {
+		t.Fatal("attendees API was not called")
+	}
+	if !bytes.Contains(attendeesStub.CapturedBody, []byte("ou_botself")) {
+		t.Fatalf("expected bot open_id ou_botself in attendees request, got: %s", attendeesStub.CapturedBody)
+	}
+	if !bytes.Contains(attendeesStub.CapturedBody, []byte("ou_user1")) {
+		t.Fatalf("expected requested attendee ou_user1 in attendees request, got: %s", attendeesStub.CapturedBody)
+	}
+}
+
+func TestCreate_WithAttendees_AsBot_BotInfoFails_ProceedsWithoutBot(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/bot/v3/info",
+		Body: map[string]interface{}{
+			"code": 99991663, "msg": "app ticket invalid",
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id": "evt_nobot",
+					"summary":  "Bot Sync",
+					"start_time": map[string]interface{}{
+						"timestamp": "1742515200",
+					},
+					"end_time": map[string]interface{}{
+						"timestamp": "1742518800",
+					},
+				},
+			},
+		},
+	})
+	attendeesStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/events/evt_nobot/attendees",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(attendeesStub)
+
+	err := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Bot Sync",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--attendee-ids", "ou_user1",
+		"--as", "bot",
+	}, f, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if attendeesStub.CapturedBody == nil {
+		t.Fatal("attendees API was not called")
+	}
+	if !bytes.Contains(attendeesStub.CapturedBody, []byte("ou_user1")) {
+		t.Fatalf("expected requested attendee ou_user1 in attendees request, got: %s", attendeesStub.CapturedBody)
+	}
+	if bytes.Contains(attendeesStub.CapturedBody, []byte("ou_botself")) {
+		t.Fatalf("bot open_id should be absent when /bot/v3/info fails, got: %s", attendeesStub.CapturedBody)
+	}
+}
+
 func TestCreate_WithAttendees_APIError_RollsBack(t *testing.T) {
 	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
 

shortcuts/common/localfile.go

@@ -0,0 +1,146 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"errors"
+	"io"
+	"io/fs"
+	"math"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/validate"
+)
+
+// ValidateLocalFileFlag validates that a local input path exists, is a regular
+// file, and does not exceed maxBytes. Absolute and relative paths use
+// the process filesystem namespace.
+func (ctx *RuntimeContext) ValidateLocalFileFlag(flagName string, maxBytes int64) error {
+	path, param, err := ctx.localFileFlag(flagName, maxBytes)
+	if err != nil {
+		return err
+	}
+
+	info, err := cmdutil.StatLocalFile(path)
+	if err != nil {
+		return localFileReadError(param, path, "inspect", err)
+	}
+	if err := localFileRegularError(param, path, info.Mode()); err != nil {
+		return err
+	}
+	if info.Size() > maxBytes {
+		return localFileSizeError(param, path, info.Size(), maxBytes)
+	}
+	return nil
+}
+
+// ReadLocalFileFlag is the shared replacement for direct os.ReadFile calls in
+// shortcuts. It accepts absolute and relative paths, enforces a hard size
+// limit, and returns command-facing typed errors.
+func (ctx *RuntimeContext) ReadLocalFileFlag(flagName string, maxBytes int64) (data []byte, retErr error) {
+	path, param, err := ctx.localFileFlag(flagName, maxBytes)
+	if err != nil {
+		return nil, err
+	}
+	f, err := cmdutil.OpenLocalFile(path)
+	if err != nil {
+		return nil, localFileReadError(param, path, "open", err)
+	}
+	defer func() {
+		if err := f.Close(); err != nil && retErr == nil {
+			data = nil
+			retErr = errs.NewInternalError(errs.SubtypeFileIO, "cannot close %s %q: %v", param, path, err).WithCause(err)
+		}
+	}()
+
+	openedInfo, err := f.Stat()
+	if err != nil {
+		return nil, localFileReadError(param, path, "inspect opened", err)
+	}
+	if err := localFileRegularError(param, path, openedInfo.Mode()); err != nil {
+		return nil, err
+	}
+	if openedInfo.Size() > maxBytes {
+		return nil, localFileSizeError(param, path, openedInfo.Size(), maxBytes)
+	}
+
+	readLimit := maxBytes + 1
+	if maxBytes == math.MaxInt64 {
+		readLimit = maxBytes
+	}
+	data, err = io.ReadAll(io.LimitReader(f, readLimit))
+	if err != nil {
+		return nil, localFileReadError(param, path, "read", err)
+	}
+	if int64(len(data)) > maxBytes {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"%s %q grew beyond the %d-byte limit while being read", param, path, maxBytes).
+			WithParam(param)
+	}
+	return data, nil
+}
+
+func (ctx *RuntimeContext) localFileFlag(flagName string, maxBytes int64) (path, param string, err error) {
+	name, param, err := localFileFlagNames(flagName)
+	if err != nil {
+		return "", "", err
+	}
+	if ctx == nil || ctx.Cmd == nil {
+		return "", param, errs.NewInternalError(errs.SubtypeUnknown, "cannot read %s: runtime command is unavailable", param)
+	}
+
+	path = strings.TrimSpace(ctx.Str(name))
+	if path == "" {
+		return "", param, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s is required", param).WithParam(param)
+	}
+	if _, err := validate.LocalInputPath(path); err != nil {
+		return "", param, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid %s path: %v", param, err).
+			WithParam(param).
+			WithCause(err)
+	}
+	if maxBytes < 0 {
+		return "", param, errs.NewInternalError(errs.SubtypeUnknown, "invalid read limit configured for %s", param)
+	}
+	return path, param, nil
+}
+
+func localFileRegularError(param, path string, mode fs.FileMode) error {
+	if mode.IsRegular() {
+		return nil
+	}
+	return errs.NewValidationError(errs.SubtypeInvalidArgument,
+		"%s %q is not a regular file", param, path).
+		WithParam(param)
+}
+
+func localFileReadError(param, path, op string, cause error) error {
+	if errors.Is(cause, fileio.ErrPathValidation) {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid %s %q: %v", param, path, cause).
+			WithParam(param).
+			WithCause(cause)
+	}
+	if errors.Is(cause, fs.ErrNotExist) {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s %q does not exist", param, path).
+			WithParam(param).
+			WithCause(cause)
+	}
+	return errs.NewInternalError(errs.SubtypeFileIO, "cannot %s %s %q: %v", op, param, path, cause).WithCause(cause)
+}
+
+func localFileSizeError(param, path string, size, limit int64) error {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument,
+		"%s %q is %d bytes; limit is %d bytes", param, path, size, limit).
+		WithParam(param)
+}
+
+func localFileFlagNames(flagName string) (name, param string, err error) {
+	name = strings.TrimLeft(strings.TrimSpace(flagName), "-")
+	if name == "" {
+		return "", "", errs.NewInternalError(errs.SubtypeUnknown, "local file flag name must not be empty")
+	}
+	return name, "--" + name, nil
+}

shortcuts/common/localfile_test.go

@@ -0,0 +1,95 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/spf13/cobra"
+)
+
+func TestReadLocalFileFlag_AcceptsAbsolutePath(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "input.txt")
+	if err := os.WriteFile(path, []byte("content"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	rctx := localFileTestRuntime(t, path)
+
+	if err := rctx.ValidateLocalFileFlag("file", 7); err != nil {
+		t.Fatalf("ValidateLocalFileFlag() error = %v", err)
+	}
+	got, err := rctx.ReadLocalFileFlag("file", 7)
+	if err != nil || string(got) != "content" {
+		t.Fatalf("ReadLocalFileFlag() = %q, %v; want content", got, err)
+	}
+}
+
+func TestValidateLocalFileFlag_ReturnsTypedInputErrors(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		path func(t *testing.T) string
+		max  int64
+	}{
+		{name: "invalid characters", path: func(*testing.T) string { return "input\n.txt" }, max: 10},
+		{name: "missing file", path: func(t *testing.T) string { return filepath.Join(t.TempDir(), "missing") }, max: 10},
+		{name: "directory", path: func(t *testing.T) string { return t.TempDir() }, max: 10},
+		{name: "too large", path: func(t *testing.T) string {
+			path := filepath.Join(t.TempDir(), "large")
+			if err := os.WriteFile(path, []byte("123456"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			return path
+		}, max: 5},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			err := localFileTestRuntime(t, tc.path(t)).ValidateLocalFileFlag("file", tc.max)
+			var validationErr *errs.ValidationError
+			if !errors.As(err, &validationErr) || validationErr.Subtype != errs.SubtypeInvalidArgument || validationErr.Param != "--file" {
+				t.Fatalf("error = %T %v, want invalid_argument for --file", err, err)
+			}
+		})
+	}
+}
+
+func TestReadLocalFileFlag_ReturnsTypedInputErrors(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		path func(t *testing.T) string
+		max  int64
+	}{
+		{name: "invalid characters", path: func(*testing.T) string { return "input\n.txt" }, max: 10},
+		{name: "missing file", path: func(t *testing.T) string { return filepath.Join(t.TempDir(), "missing") }, max: 10},
+		{name: "directory", path: func(t *testing.T) string { return t.TempDir() }, max: 10},
+		{name: "too large", path: func(t *testing.T) string {
+			path := filepath.Join(t.TempDir(), "large")
+			if err := os.WriteFile(path, []byte("123456"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			return path
+		}, max: 5},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := localFileTestRuntime(t, tc.path(t)).ReadLocalFileFlag("file", tc.max)
+			var validationErr *errs.ValidationError
+			if !errors.As(err, &validationErr) || validationErr.Subtype != errs.SubtypeInvalidArgument || validationErr.Param != "--file" {
+				t.Fatalf("error = %T %v, want invalid_argument for --file", err, err)
+			}
+		})
+	}
+}
+
+func localFileTestRuntime(t *testing.T, path string) *RuntimeContext {
+	t.Helper()
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("file", "", "")
+	if err := cmd.Flags().Set("file", path); err != nil {
+		t.Fatal(err)
+	}
+	return &RuntimeContext{ctx: context.Background(), Cmd: cmd}
+}

shortcuts/okr/okr_batch_create.go

@@ -24,9 +24,12 @@ type batchCreateKR struct {
 
 // batchCreateObjective represents an objective in the batch create input.
 type batchCreateObjective struct {
-	Text    string          `json:"text"`
-	Mention []string        `json:"mention,omitempty"`
-	KRs     []batchCreateKR `json:"krs,omitempty"`
+	Text         string          `json:"text"`
+	Mention      []string        `json:"mention,omitempty"`
+	Notes        string          `json:"notes,omitempty"`
+	NotesMention []string        `json:"notes_mention,omitempty"`
+	CategoryID   string          `json:"category_id,omitempty"`
+	KRs          []batchCreateKR `json:"krs,omitempty"`
 }
 
 // createdObjective tracks a created objective and its KR IDs for output.
@@ -49,6 +52,25 @@ func parseBatchCreateInput(input string) ([]batchCreateObjective, error) {
 		if strings.TrimSpace(obj.Text) == "" {
 			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "objective[%d].text is required and cannot be empty", i).WithParam("--input")
 		}
+		if obj.Notes != "" && strings.TrimSpace(obj.Notes) == "" {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "objective[%d].notes cannot be blank when provided", i).WithParam("--input")
+		}
+		if obj.Notes == "" && len(obj.NotesMention) > 0 {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "objective[%d].notes is required when notes_mention is provided", i).WithParam("--input")
+		}
+		for j, mention := range obj.NotesMention {
+			if strings.TrimSpace(mention) == "" {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "objective[%d].notes_mention[%d] cannot be empty", i, j).WithParam("--input")
+			}
+		}
+		if obj.CategoryID != "" {
+			if strings.TrimSpace(obj.CategoryID) == "" {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "objective[%d].category_id cannot be blank when provided", i).WithParam("--input")
+			}
+			if id, err := strconv.ParseInt(obj.CategoryID, 10, 64); err != nil || id <= 0 {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "objective[%d].category_id must be a positive int64", i).WithParam("--input")
+			}
+		}
 		for j, kr := range obj.KRs {
 			if strings.TrimSpace(kr.Text) == "" {
 				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "objective[%d].krs[%d].text is required and cannot be empty", i, j).WithParam("--input")
@@ -59,11 +81,24 @@ func parseBatchCreateInput(input string) ([]batchCreateObjective, error) {
 }
 
 // createObjective calls the API to create an objective.
-func createObjective(ctx context.Context, runtime *common.RuntimeContext, cycleID, userIDType string, obj batchCreateObjective) (string, error) {
+func effectiveBatchObjectiveCategoryID(defaultCategoryID string, obj batchCreateObjective) string {
+	if obj.CategoryID != "" {
+		return obj.CategoryID
+	}
+	return defaultCategoryID
+}
+
+func createObjective(ctx context.Context, runtime *common.RuntimeContext, cycleID, userIDType, defaultCategoryID string, obj batchCreateObjective) (string, error) {
 	content := BuildContentBlock(obj.Text, obj.Mention)
 	body := map[string]interface{}{
 		"content": content,
 	}
+	if obj.Notes != "" {
+		body["notes"] = BuildContentBlock(obj.Notes, obj.NotesMention)
+	}
+	if categoryID := effectiveBatchObjectiveCategoryID(defaultCategoryID, obj); categoryID != "" {
+		body["category_id"] = categoryID
+	}
 	queryParams := map[string]interface{}{
 		"cycle_id":     cycleID,
 		"user_id_type": userIDType,
@@ -156,6 +191,7 @@ var OKRBatchCreate = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "cycle-id", Desc: "OKR cycle ID (int64)", Required: true},
 		{Name: "input", Desc: "JSON array of objectives: [{\"text\":\"...\",\"mention\":[\"...\"],\"krs\":[{\"text\":\"...\",\"mention\":[\"...\"]}]}]", Input: []string{common.File, common.Stdin}, Required: true},
+		{Name: "category-id", Desc: "default objective category ID for objectives that do not set category_id"},
 		{Name: "user-id-type", Default: "open_id", Desc: "user ID type: open_id | union_id | user_id"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -171,6 +207,15 @@ var OKRBatchCreate = common.Shortcut{
 		if _, err := parseBatchCreateInput(input); err != nil {
 			return err
 		}
+		categoryID := runtime.Str("category-id")
+		if categoryID != "" {
+			if err := common.RejectDangerousCharsTyped("--category-id", categoryID); err != nil {
+				return err
+			}
+			if id, err := strconv.ParseInt(categoryID, 10, 64); err != nil || id <= 0 {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--category-id must be a positive int64").WithParam("--category-id")
+			}
+		}
 
 		idType := runtime.Str("user-id-type")
 		if idType != "open_id" && idType != "union_id" && idType != "user_id" {
@@ -182,6 +227,7 @@ var OKRBatchCreate = common.Shortcut{
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		cycleID := runtime.Str("cycle-id")
 		userIDType := runtime.Str("user-id-type")
+		defaultCategoryID := runtime.Str("category-id")
 		objectives, _ := parseBatchCreateInput(runtime.Str("input"))
 
 		apis := common.NewDryRunAPI()
@@ -192,6 +238,12 @@ var OKRBatchCreate = common.Shortcut{
 			objBody := map[string]interface{}{
 				"content": objContent,
 			}
+			if obj.Notes != "" {
+				objBody["notes"] = BuildContentBlock(obj.Notes, obj.NotesMention)
+			}
+			if categoryID := effectiveBatchObjectiveCategoryID(defaultCategoryID, obj); categoryID != "" {
+				objBody["category_id"] = categoryID
+			}
 			objParams := map[string]interface{}{
 				"cycle_id":     cycleID,
 				"user_id_type": userIDType,
@@ -227,6 +279,7 @@ var OKRBatchCreate = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		cycleID := runtime.Str("cycle-id")
 		userIDType := runtime.Str("user-id-type")
+		defaultCategoryID := runtime.Str("category-id")
 		objectives, err := parseBatchCreateInput(runtime.Str("input"))
 		if err != nil {
 			return err
@@ -241,7 +294,7 @@ var OKRBatchCreate = common.Shortcut{
 			}
 
 			// Create objective
-			objectiveID, err := createObjective(ctx, runtime, cycleID, userIDType, obj)
+			objectiveID, err := createObjective(ctx, runtime, cycleID, userIDType, defaultCategoryID, obj)
 			if err != nil {
 				if len(created) == 0 {
 					return err

shortcuts/okr/okr_batch_create_test.go

@@ -6,6 +6,8 @@ package okr
 import (
 	"bytes"
 	"errors"
+	"io"
+	"net/http"
 	"strings"
 	"testing"
 
@@ -14,6 +16,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/spf13/cobra"
+	"github.com/tidwall/gjson"
 )
 
 func batchCreateTestConfig(t *testing.T) *core.CliConfig {
@@ -43,6 +46,15 @@ const validBatchCreateInput = `[
   {"text":"Objective 2","krs":[{"text":"KR 2.1"},{"text":"KR 2.2"}]}
 ]`
 
+const validBatchCreateInputWithNotes = `[
+  {"text":"Objective 1","notes":"Objective notes","notes_mention":["ou_note"],"krs":[{"text":"KR 1.1"}]}
+]`
+
+const validBatchCreateInputWithCategory = `[
+  {"text":"Objective 1","category_id":"222","krs":[{"text":"KR 1.1"}]},
+  {"text":"Objective 2","krs":[]}
+]`
+
 // --- Validate tests ---
 
 func TestBatchCreateValidate_MissingCycleID(t *testing.T) {
@@ -197,6 +209,46 @@ func TestBatchCreateValidate_EmptyKRText(t *testing.T) {
 	}
 }
 
+func TestBatchCreateValidate_EmptyObjectiveNotesMention(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, batchCreateTestConfig(t))
+	err := runBatchCreateShortcut(t, f, stdout, []string{
+		"+batch-create",
+		"--cycle-id", "123",
+		"--input", `[{"text":"Obj 1","notes":"Notes","notes_mention":[" "]}]`,
+	})
+	if err == nil {
+		t.Fatal("expected error for empty objective notes mention")
+	}
+	validationErr, ok := err.(*errs.ValidationError)
+	if !ok || validationErr.Param != "--input" {
+		t.Fatalf("expected param --input, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "objective[0].notes_mention[0]") {
+		t.Fatalf("expected error to mention objective[0].notes_mention[0], got: %v", err)
+	}
+}
+
+func TestBatchCreateValidate_NotesMentionRequiresNotes(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, batchCreateTestConfig(t))
+	err := runBatchCreateShortcut(t, f, stdout, []string{
+		"+batch-create",
+		"--cycle-id", "123",
+		"--input", `[{"text":"Obj 1","notes_mention":["ou_note"]}]`,
+	})
+	if err == nil {
+		t.Fatal("expected error for notes_mention without notes")
+	}
+	validationErr, ok := err.(*errs.ValidationError)
+	if !ok || validationErr.Param != "--input" {
+		t.Fatalf("expected param --input, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "objective[0].notes is required when notes_mention is provided") {
+		t.Fatalf("expected error to mention missing notes, got: %v", err)
+	}
+}
+
 func TestBatchCreateValidate_InvalidUserIDType(t *testing.T) {
 	t.Parallel()
 	f, stdout, _, _ := cmdutil.TestFactory(t, batchCreateTestConfig(t))
@@ -323,6 +375,49 @@ func TestBatchCreateDryRun(t *testing.T) {
 	}
 }
 
+func TestBatchCreateDryRun_WithObjectiveNotes(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, batchCreateTestConfig(t))
+	err := runBatchCreateShortcut(t, f, stdout, []string{
+		"+batch-create",
+		"--cycle-id", "123",
+		"--input", validBatchCreateInputWithNotes,
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if !strings.Contains(output, "Objective notes") {
+		t.Fatalf("dry-run output should contain objective notes, got: %s", output)
+	}
+	if !strings.Contains(output, "ou_note") {
+		t.Fatalf("dry-run output should contain objective notes mention, got: %s", output)
+	}
+}
+
+func TestBatchCreateDryRun_WithCategoryID(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, batchCreateTestConfig(t))
+	err := runBatchCreateShortcut(t, f, stdout, []string{
+		"+batch-create",
+		"--cycle-id", "123",
+		"--category-id", "111",
+		"--input", validBatchCreateInputWithCategory,
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if got := gjson.Get(output, "data.api.0.body.category_id").String(); got != "222" {
+		t.Fatalf("first objective category_id = %q, want per-objective override 222; output: %s", got, output)
+	}
+	if got := gjson.Get(output, "data.api.2.body.category_id").String(); got != "111" {
+		t.Fatalf("second objective category_id = %q, want default 111; output: %s", got, output)
+	}
+}
+
 // --- Execute tests ---
 
 func TestBatchCreateExecute_Success(t *testing.T) {
@@ -380,6 +475,94 @@ func TestBatchCreateExecute_Success(t *testing.T) {
 	}
 }
 
+func TestBatchCreateExecute_ObjectiveWithNotes(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, reg := cmdutil.TestFactory(t, batchCreateTestConfig(t))
+	var objectiveBody []byte
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/okr/v2/cycles/123/objectives",
+		OnMatch: func(req *http.Request) {
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Fatalf("read objective request body: %v", err)
+			}
+			objectiveBody = body
+		},
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"objective_id": "100",
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/okr/v2/objectives/100/key_results",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"key_result_id": "200",
+			},
+		},
+	})
+	err := runBatchCreateShortcut(t, f, stdout, []string{
+		"+batch-create",
+		"--cycle-id", "123",
+		"--input", validBatchCreateInputWithNotes,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !gjson.GetBytes(objectiveBody, "notes.blocks.0.paragraph.elements.0.text_run.text").Exists() {
+		t.Fatalf("objective request body missing notes: %s", string(objectiveBody))
+	}
+	if got := gjson.GetBytes(objectiveBody, "notes.blocks.0.paragraph.elements.0.text_run.text").String(); got != "Objective notes" {
+		t.Fatalf("notes text = %q, want Objective notes; body: %s", got, string(objectiveBody))
+	}
+	if got := gjson.GetBytes(objectiveBody, "notes.blocks.0.paragraph.elements.1.mention.user_id").String(); got != "ou_note" {
+		t.Fatalf("notes mention = %q, want ou_note; body: %s", got, string(objectiveBody))
+	}
+}
+
+func TestBatchCreateExecute_ObjectiveWithCategoryID(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, reg := cmdutil.TestFactory(t, batchCreateTestConfig(t))
+	var objectiveBody []byte
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/okr/v2/cycles/123/objectives",
+		OnMatch: func(req *http.Request) {
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Fatalf("read objective request body: %v", err)
+			}
+			objectiveBody = body
+		},
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"objective_id": "100",
+			},
+		},
+	})
+	err := runBatchCreateShortcut(t, f, stdout, []string{
+		"+batch-create",
+		"--cycle-id", "123",
+		"--category-id", "7249339036661170180",
+		"--input", `[{"text":"Obj 1"}]`,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := gjson.GetBytes(objectiveBody, "category_id").String(); got != "7249339036661170180" {
+		t.Fatalf("category_id = %q, want 7249339036661170180; body: %s", got, string(objectiveBody))
+	}
+}
+
 func TestBatchCreateExecute_APIErrorOnObjective(t *testing.T) {
 	t.Parallel()
 	f, stdout, _, reg := cmdutil.TestFactory(t, batchCreateTestConfig(t))

shortcuts/okr/okr_create.go

@@ -0,0 +1,394 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package okr
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// createParams holds the parsed parameters for single-object create operations.
+type createParams struct {
+	Level       string
+	CycleID     string
+	ObjectiveID string
+	Style       string
+	Content     *ContentBlock
+	Notes       *ContentBlock
+	CategoryID  string
+	UserIDType  string
+}
+
+type createContentMultipleJSONValuesError struct{}
+
+func (createContentMultipleJSONValuesError) Error() string {
+	return "multiple JSON values"
+}
+
+var errCreateContentMultipleJSONValues createContentMultipleJSONValuesError
+
+type okrCreateRequestBody struct {
+	Content    *ContentBlock `json:"content"`
+	Notes      *ContentBlock `json:"notes,omitempty"`
+	CategoryID string        `json:"category_id,omitempty"`
+}
+
+type okrCreateObjectiveQuery struct {
+	CycleID    string
+	UserIDType string
+}
+
+type okrCreateKeyResultQuery struct {
+	ObjectiveID string
+	UserIDType  string
+}
+
+type okrCreateObjectiveResponse struct {
+	ObjectiveID string
+}
+
+type okrCreateKeyResultResponse struct {
+	KeyResultID string
+}
+
+type okrCreateObjectiveOutput struct {
+	Level       string `json:"level"`
+	ObjectiveID string `json:"objective_id"`
+}
+
+type okrCreateKeyResultOutput struct {
+	Level       string `json:"level"`
+	ObjectiveID string `json:"objective_id"`
+	KeyResultID string `json:"key_result_id"`
+}
+
+func decodeCreateContentStrict(inputStr string, target interface{}, param, message string) error {
+	dec := json.NewDecoder(bytes.NewReader([]byte(inputStr)))
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(target); err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, message, err).
+			WithParam(param).
+			WithCause(err)
+	}
+	var trailing interface{}
+	if err := dec.Decode(&trailing); !errors.Is(err, io.EOF) {
+		if err == nil {
+			err = errCreateContentMultipleJSONValues
+		}
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, message, err).
+			WithParam(param).
+			WithCause(err)
+	}
+	return nil
+}
+
+func parseCreateContentValue(inputStr, param, style string) (*ContentBlock, error) {
+	if style == "simple" {
+		var sp SemiPlainContent
+		if err := decodeCreateContentStrict(inputStr, &sp, param, fmt.Sprintf("%s must be valid semi-plain JSON: {\"text\":\"...\",\"mention\":[\"...\"]}: %%s", param)); err != nil {
+			return nil, err
+		}
+		if strings.TrimSpace(sp.Text) == "" {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s text is required and cannot be empty", param).WithParam(param)
+		}
+		for i, mention := range sp.Mention {
+			if strings.TrimSpace(mention) == "" {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s mention[%d] cannot be empty", param, i).WithParam(param)
+			}
+		}
+		if len(sp.Docs) > 0 || len(sp.Images) > 0 {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s docs and images are not supported in simple style input; use richtext style or remove these fields", param).WithParam(param)
+		}
+		return sp.ToContentBlock(), nil
+	}
+
+	var cb ContentBlock
+	if err := decodeCreateContentStrict(inputStr, &cb, param, fmt.Sprintf("%s must be valid ContentBlock JSON: %%s", param)); err != nil {
+		return nil, err
+	}
+	if len(cb.Blocks) == 0 {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s must contain at least one block", param).WithParam(param)
+	}
+
+	hasNonEmptyParagraph := false
+	for _, block := range cb.Blocks {
+		if block.Paragraph != nil && len(block.Paragraph.Elements) > 0 {
+			hasNonEmptyParagraph = true
+			break
+		}
+		if block.Gallery != nil && len(block.Gallery.Images) > 0 {
+			hasNonEmptyParagraph = true
+			break
+		}
+	}
+	if !hasNonEmptyParagraph {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s cannot be empty", param).WithParam(param)
+	}
+	return &cb, nil
+}
+
+func projectCreateRequestBody(body okrCreateRequestBody) map[string]interface{} {
+	result := map[string]interface{}{
+		"content": body.Content,
+	}
+	if body.Notes != nil {
+		result["notes"] = body.Notes
+	}
+	if body.CategoryID != "" {
+		result["category_id"] = body.CategoryID
+	}
+	return result
+}
+
+func projectCreateObjectiveQuery(query okrCreateObjectiveQuery) map[string]interface{} {
+	return map[string]interface{}{
+		"cycle_id":     query.CycleID,
+		"user_id_type": query.UserIDType,
+	}
+}
+
+func projectCreateKeyResultQuery(query okrCreateKeyResultQuery) map[string]interface{} {
+	return map[string]interface{}{
+		"objective_id": query.ObjectiveID,
+		"user_id_type": query.UserIDType,
+	}
+}
+
+func projectCreateObjectiveResponse(data map[string]interface{}) (*okrCreateObjectiveResponse, error) {
+	objectiveID, ok := data["objective_id"].(string)
+	if !ok || objectiveID == "" {
+		return nil, errs.NewInternalError(errs.SubtypeUnknown, "create objective response missing objective_id")
+	}
+	return &okrCreateObjectiveResponse{ObjectiveID: objectiveID}, nil
+}
+
+func projectCreateKeyResultResponse(data map[string]interface{}) (*okrCreateKeyResultResponse, error) {
+	keyResultID, ok := data["key_result_id"].(string)
+	if !ok || keyResultID == "" {
+		return nil, errs.NewInternalError(errs.SubtypeUnknown, "create key result response missing key_result_id")
+	}
+	return &okrCreateKeyResultResponse{KeyResultID: keyResultID}, nil
+}
+
+// parseCreateParams parses and validates flags from runtime into request-ready parameters.
+func parseCreateParams(runtime *common.RuntimeContext) (*createParams, error) {
+	p := &createParams{
+		Level:       runtime.Str("level"),
+		CycleID:     runtime.Str("cycle-id"),
+		ObjectiveID: runtime.Str("objective-id"),
+		Style:       runtime.Str("style"),
+		CategoryID:  runtime.Str("category-id"),
+		UserIDType:  runtime.Str("user-id-type"),
+	}
+
+	contentStr := runtime.Str("content")
+	if contentStr == "" {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is required").WithParam("--content")
+	}
+	if err := common.RejectDangerousCharsTyped("--content", contentStr); err != nil {
+		return nil, err
+	}
+	content, err := parseCreateContentValue(contentStr, "--content", p.Style)
+	if err != nil {
+		return nil, err
+	}
+	p.Content = content
+
+	if notesStr := runtime.Str("notes"); notesStr != "" {
+		if p.Level != "objective" {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--notes is only supported when --level=objective").WithParam("--notes")
+		}
+		if err := common.RejectDangerousCharsTyped("--notes", notesStr); err != nil {
+			return nil, err
+		}
+		notes, err := parseCreateContentValue(notesStr, "--notes", p.Style)
+		if err != nil {
+			return nil, err
+		}
+		p.Notes = notes
+	}
+	if p.CategoryID != "" {
+		if p.Level != "objective" {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--category-id is only supported when --level=objective").WithParam("--category-id")
+		}
+		if err := common.RejectDangerousCharsTyped("--category-id", p.CategoryID); err != nil {
+			return nil, err
+		}
+		if id, err := strconv.ParseInt(p.CategoryID, 10, 64); err != nil || id <= 0 {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--category-id must be a positive int64").WithParam("--category-id")
+		}
+	}
+	return p, nil
+}
+
+// OKRCreate creates a single objective or key result.
+var OKRCreate = common.Shortcut{
+	Service:     "okr",
+	Command:     "+create",
+	Description: "Create a single OKR objective or key result",
+	Risk:        "write",
+	Scopes:      []string{"okr:okr.content:writeonly"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "level", Desc: "create level: objective | key-result", Required: true, Enum: []string{"objective", "key-result"}},
+		{Name: "cycle-id", Desc: "OKR cycle ID (required for level=objective)"},
+		{Name: "objective-id", Desc: "objective ID (required for level=key-result)"},
+		{Name: "style", Default: "simple", Desc: "input style for content: simple (semi-plain text JSON) | richtext (ContentBlock JSON)", Enum: []string{"simple", "richtext"}},
+		{Name: "content", Desc: "content: semi-plain JSON {\"text\":\"...\",\"mention\":[\"...\"]} (simple) or ContentBlock JSON (richtext)", Required: true, Input: []string{common.File, common.Stdin}},
+		{Name: "notes", Desc: "objective notes: semi-plain JSON {\"text\":\"...\",\"mention\":[\"...\"]} (simple) or ContentBlock JSON (richtext)", Input: []string{common.File, common.Stdin}},
+		{Name: "category-id", Desc: "objective category ID; use only when classification is requested or the tenant requires categories"},
+		{Name: "user-id-type", Default: "open_id", Desc: "user ID type: open_id | union_id | user_id"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		level := runtime.Str("level")
+		if level != "objective" && level != "key-result" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--level must be one of: objective | key-result").WithParam("--level")
+		}
+
+		style := runtime.Str("style")
+		if style != "simple" && style != "richtext" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--style must be one of: simple | richtext").WithParam("--style")
+		}
+
+		idType := runtime.Str("user-id-type")
+		if idType != "open_id" && idType != "union_id" && idType != "user_id" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--user-id-type must be one of: open_id | union_id | user_id").WithParam("--user-id-type")
+		}
+
+		switch level {
+		case "objective":
+			if runtime.Str("objective-id") != "" {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--objective-id cannot be used when --level=objective").WithParam("--objective-id")
+			}
+			cycleID := runtime.Str("cycle-id")
+			if cycleID == "" {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--cycle-id is required when --level=objective").WithParam("--cycle-id")
+			}
+			if err := common.RejectDangerousCharsTyped("--cycle-id", cycleID); err != nil {
+				return err
+			}
+			if id, err := strconv.ParseInt(cycleID, 10, 64); err != nil || id <= 0 {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--cycle-id must be a positive int64").WithParam("--cycle-id")
+			}
+		case "key-result":
+			if runtime.Str("cycle-id") != "" {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--cycle-id cannot be used when --level=key-result").WithParam("--cycle-id")
+			}
+			objectiveID := runtime.Str("objective-id")
+			if objectiveID == "" {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--objective-id is required when --level=key-result").WithParam("--objective-id")
+			}
+			if err := common.RejectDangerousCharsTyped("--objective-id", objectiveID); err != nil {
+				return err
+			}
+			if id, err := strconv.ParseInt(objectiveID, 10, 64); err != nil || id <= 0 {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--objective-id must be a positive int64").WithParam("--objective-id")
+			}
+		}
+
+		_, err := parseCreateParams(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		p, err := parseCreateParams(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().
+				POST("").
+				Desc(fmt.Sprintf("Dry-run skipped: %s", err.Error()))
+		}
+
+		body := projectCreateRequestBody(okrCreateRequestBody{Content: p.Content, Notes: p.Notes, CategoryID: p.CategoryID})
+
+		if p.Level == "objective" {
+			params := projectCreateObjectiveQuery(okrCreateObjectiveQuery{
+				CycleID:    p.CycleID,
+				UserIDType: p.UserIDType,
+			})
+			return common.NewDryRunAPI().
+				POST("/open-apis/okr/v2/cycles/:cycle_id/objectives").
+				Set("cycle_id", p.CycleID).
+				Params(params).
+				Body(body).
+				Desc("Create OKR objective")
+		}
+
+		params := projectCreateKeyResultQuery(okrCreateKeyResultQuery{
+			ObjectiveID: p.ObjectiveID,
+			UserIDType:  p.UserIDType,
+		})
+		return common.NewDryRunAPI().
+			POST("/open-apis/okr/v2/objectives/:objective_id/key_results").
+			Set("objective_id", p.ObjectiveID).
+			Params(params).
+			Body(body).
+			Desc("Create OKR key result")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		p, err := parseCreateParams(runtime)
+		if err != nil {
+			return err
+		}
+
+		body := projectCreateRequestBody(okrCreateRequestBody{Content: p.Content, Notes: p.Notes, CategoryID: p.CategoryID})
+
+		if p.Level == "objective" {
+			queryParams := projectCreateObjectiveQuery(okrCreateObjectiveQuery{
+				CycleID:    p.CycleID,
+				UserIDType: p.UserIDType,
+			})
+			path := fmt.Sprintf("/open-apis/okr/v2/cycles/%s/objectives", p.CycleID)
+			data, err := runtime.CallAPITyped("POST", path, queryParams, body)
+			if err != nil {
+				return wrapOkrNetworkErr(err, "failed to create objective")
+			}
+			resp, err := projectCreateObjectiveResponse(data)
+			if err != nil {
+				return err
+			}
+			result := okrCreateObjectiveOutput{
+				Level:       p.Level,
+				ObjectiveID: resp.ObjectiveID,
+			}
+
+			runtime.OutFormat(result, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "Created OKR objective [%s]\n", resp.ObjectiveID)
+			})
+			return nil
+		}
+
+		queryParams := projectCreateKeyResultQuery(okrCreateKeyResultQuery{
+			ObjectiveID: p.ObjectiveID,
+			UserIDType:  p.UserIDType,
+		})
+		path := fmt.Sprintf("/open-apis/okr/v2/objectives/%s/key_results", p.ObjectiveID)
+		data, err := runtime.CallAPITyped("POST", path, queryParams, body)
+		if err != nil {
+			return wrapOkrNetworkErr(err, "failed to create key result")
+		}
+		resp, err := projectCreateKeyResultResponse(data)
+		if err != nil {
+			return err
+		}
+		result := okrCreateKeyResultOutput{
+			Level:       p.Level,
+			ObjectiveID: p.ObjectiveID,
+			KeyResultID: resp.KeyResultID,
+		}
+
+		runtime.OutFormat(result, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Created OKR key-result [%s] under objective [%s]\n", resp.KeyResultID, p.ObjectiveID)
+		})
+		return nil
+	},
+}

shortcuts/okr/okr_create_test.go

@@ -0,0 +1,707 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package okr
+
+import (
+	"bytes"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/spf13/cobra"
+	"github.com/tidwall/gjson"
+)
+
+func createTestConfig(t *testing.T) *core.CliConfig {
+	t.Helper()
+	return &core.CliConfig{
+		AppID:     "test-okr-create",
+		AppSecret: patchTestValue(),
+		Brand:     core.BrandFeishu,
+	}
+}
+
+func runCreateShortcut(t *testing.T, f *cmdutil.Factory, stdout *bytes.Buffer, args []string) error {
+	t.Helper()
+	parent := &cobra.Command{Use: "okr"}
+	OKRCreate.Mount(parent, f)
+	parent.SetArgs(args)
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	if stdout != nil {
+		stdout.Reset()
+	}
+	return parent.Execute()
+}
+
+func runCreateShortcutWithStdin(t *testing.T, f *cmdutil.Factory, stdout *bytes.Buffer, stdin string, args []string) error {
+	t.Helper()
+	f.IOStreams.In = strings.NewReader(stdin)
+	return runCreateShortcut(t, f, stdout, args)
+}
+
+const (
+	validCreateSimpleJSON     = `{"text":"test objective","mention":["ou_123"]}`
+	validCreateRichTextJSON   = `{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"test content"}}]}}]}`
+	emptyCreateRichTextJSON   = `{"blocks":[]}`
+	blankCreateRichTextJSON   = `{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[]}}]}`
+	validCreateObjectiveArgs1 = "+create"
+)
+
+func TestCreateValidate_MissingLevel(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		validCreateObjectiveArgs1,
+		"--cycle-id", "123",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil || !strings.Contains(err.Error(), "level") {
+		t.Fatalf("expected --level required error, got: %v", err)
+	}
+}
+
+func TestCreateValidate_InvalidLevel(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "invalid",
+		"--cycle-id", "123",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil {
+		t.Fatal("expected invalid level error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected typed invalid argument error, got: %v", err)
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--level" {
+		t.Fatalf("expected param --level, got: %v", err)
+	}
+}
+
+func TestCreateValidate_MissingCycleIDForObjective(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil {
+		t.Fatal("expected missing cycle-id error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected typed invalid argument error, got: %v", err)
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--cycle-id" {
+		t.Fatalf("expected param --cycle-id, got: %v", err)
+	}
+}
+
+func TestCreateValidate_InvalidCycleID(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "abc",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil {
+		t.Fatal("expected invalid cycle-id error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected typed invalid argument error, got: %v", err)
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--cycle-id" {
+		t.Fatalf("expected param --cycle-id, got: %v", err)
+	}
+}
+
+func TestCreateValidate_MissingObjectiveIDForKR(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "key-result",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil {
+		t.Fatal("expected missing objective-id error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected typed invalid argument error, got: %v", err)
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--objective-id" {
+		t.Fatalf("expected param --objective-id, got: %v", err)
+	}
+}
+
+func TestCreateValidate_RejectObjectiveIDForObjective(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--objective-id", "456",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil {
+		t.Fatal("expected objective-id rejection")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--objective-id" {
+		t.Fatalf("expected param --objective-id, got: %v", err)
+	}
+}
+
+func TestCreateValidate_RejectCycleIDForKeyResult(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "key-result",
+		"--cycle-id", "123",
+		"--objective-id", "456",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil {
+		t.Fatal("expected cycle-id rejection")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--cycle-id" {
+		t.Fatalf("expected param --cycle-id, got: %v", err)
+	}
+}
+
+func TestCreateValidate_RejectNotesForKeyResult(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "key-result",
+		"--objective-id", "456",
+		"--content", validCreateSimpleJSON,
+		"--notes", `{"text":"objective only notes"}`,
+	})
+	if err == nil {
+		t.Fatal("expected notes rejection for key-result")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--notes" {
+		t.Fatalf("expected param --notes, got: %v", err)
+	}
+}
+
+func TestCreateValidate_RejectCategoryIDForKeyResult(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "key-result",
+		"--objective-id", "456",
+		"--content", validCreateSimpleJSON,
+		"--category-id", "123",
+	})
+	if err == nil {
+		t.Fatal("expected category-id rejection for key-result")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--category-id" {
+		t.Fatalf("expected param --category-id, got: %v", err)
+	}
+}
+
+func TestCreateValidate_ContentAndNotesCannotBothReadStdin(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcutWithStdin(t, f, stdout, `{"text":"stdin content"}`, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--content", "-",
+		"--notes", "-",
+	})
+	if err == nil {
+		t.Fatal("expected duplicate stdin error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--notes" {
+		t.Fatalf("expected param --notes, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "stdin (-) can only be used by one flag") {
+		t.Fatalf("expected duplicate stdin error, got: %v", err)
+	}
+}
+
+func TestCreateValidate_InvalidObjectiveID(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "key-result",
+		"--objective-id", "0",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil {
+		t.Fatal("expected invalid objective-id error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected typed invalid argument error, got: %v", err)
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--objective-id" {
+		t.Fatalf("expected param --objective-id, got: %v", err)
+	}
+}
+
+func TestCreateValidate_InvalidStyle(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--style", "invalid",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil {
+		t.Fatal("expected invalid style error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--style" {
+		t.Fatalf("expected param --style, got: %v", err)
+	}
+}
+
+func TestCreateValidate_InvalidUserIDType(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--content", validCreateSimpleJSON,
+		"--user-id-type", "invalid",
+	})
+	if err == nil {
+		t.Fatal("expected invalid user-id-type error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--user-id-type" {
+		t.Fatalf("expected param --user-id-type, got: %v", err)
+	}
+}
+
+func TestCreateValidate_MissingContent(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+	})
+	if err == nil || !strings.Contains(err.Error(), "content") {
+		t.Fatalf("expected required content error, got: %v", err)
+	}
+}
+
+func TestCreateValidate_InvalidSimpleContentJSON(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--style", "simple",
+		"--content", "not-json",
+	})
+	if err == nil {
+		t.Fatal("expected invalid simple json error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--content" {
+		t.Fatalf("expected param --content, got: %v", err)
+	}
+}
+
+func TestCreateValidate_EmptySimpleText(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--style", "simple",
+		"--content", `{"text":"   "}`,
+	})
+	if err == nil {
+		t.Fatal("expected empty simple text error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--content" {
+		t.Fatalf("expected param --content, got: %v", err)
+	}
+}
+
+func TestCreateValidate_EmptySimpleMention(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--style", "simple",
+		"--content", `{"text":"test","mention":[""]}`,
+	})
+	if err == nil {
+		t.Fatal("expected empty simple mention error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--content" {
+		t.Fatalf("expected param --content, got: %v", err)
+	}
+}
+
+func TestCreateValidate_SimpleContentRejectsDocsImages(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--style", "simple",
+		"--content", `{"text":"test","docs":[{"title":"doc","url":"https://example.com"}],"images":["img"]}`,
+	})
+	if err == nil {
+		t.Fatal("expected docs/images rejection")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--content" {
+		t.Fatalf("expected param --content, got: %v", err)
+	}
+}
+
+func TestCreateValidate_SimpleContentRejectsUnknownFields(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--style", "simple",
+		"--content", `{"text":"test","mentions":["ou_123"]}`,
+	})
+	if err == nil {
+		t.Fatal("expected unknown simple content field error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--content" {
+		t.Fatalf("expected param --content, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "unknown field") {
+		t.Fatalf("expected unknown field error, got: %v", err)
+	}
+}
+
+func TestCreateValidate_InvalidRichTextJSON(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--style", "richtext",
+		"--content", "not-json",
+	})
+	if err == nil {
+		t.Fatal("expected invalid richtext json error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--content" {
+		t.Fatalf("expected param --content, got: %v", err)
+	}
+}
+
+func TestCreateValidate_RichTextRejectsUnknownFields(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--style", "richtext",
+		"--content", `{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"test content"}}]}}],"mentions":["ou_123"]}`,
+	})
+	if err == nil {
+		t.Fatal("expected unknown richtext content field error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Param != "--content" {
+		t.Fatalf("expected param --content, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "unknown field") {
+		t.Fatalf("expected unknown field error, got: %v", err)
+	}
+}
+
+func TestCreateValidate_EmptyRichTextContent(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	for _, content := range []string{emptyCreateRichTextJSON, blankCreateRichTextJSON} {
+		err := runCreateShortcut(t, f, stdout, []string{
+			"+create",
+			"--level", "objective",
+			"--cycle-id", "123",
+			"--style", "richtext",
+			"--content", content,
+		})
+		if err == nil {
+			t.Fatalf("expected empty richtext error for %s", content)
+		}
+		var ve *errs.ValidationError
+		if !errors.As(err, &ve) || ve.Param != "--content" {
+			t.Fatalf("expected param --content, got: %v", err)
+		}
+	}
+}
+
+func TestCreateDryRun_Objective(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--content", validCreateSimpleJSON,
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if got := gjson.Get(output, "data.api.0.method").String(); got != "POST" {
+		t.Fatalf("dry-run method = %q, want POST; output: %s", got, output)
+	}
+	if got := gjson.Get(output, "data.api.0.url").String(); got != "/open-apis/okr/v2/cycles/123/objectives" {
+		t.Fatalf("dry-run url = %q, want objective create path; output: %s", got, output)
+	}
+	if gjson.Get(output, "data.api.0.params.cycle_id").String() != "123" {
+		t.Fatalf("expected query params in dry-run, got: %s", output)
+	}
+	if gjson.Get(output, "data.api.0.params.user_id_type").String() != "open_id" {
+		t.Fatalf("expected default user-id-type in dry-run, got: %s", output)
+	}
+	if got := gjson.Get(output, "data.api.0.body.content.blocks.0.paragraph.elements.0.text_run.text").String(); got != "test objective" {
+		t.Fatalf("dry-run content text = %q, want test objective; output: %s", got, output)
+	}
+	if got := gjson.Get(output, "data.api.0.body.content.blocks.0.paragraph.elements.1.mention.user_id").String(); got != "ou_123" {
+		t.Fatalf("dry-run mention user_id = %q, want ou_123; output: %s", got, output)
+	}
+}
+
+func TestCreateDryRun_ObjectiveWithNotes(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--content", validCreateSimpleJSON,
+		"--notes", `{"text":"objective notes","mention":["ou_note"]}`,
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if got := gjson.Get(output, "data.api.0.body.notes.blocks.0.paragraph.elements.0.text_run.text").String(); got != "objective notes" {
+		t.Fatalf("dry-run notes text = %q, want objective notes; output: %s", got, output)
+	}
+	if got := gjson.Get(output, "data.api.0.body.notes.blocks.0.paragraph.elements.1.mention.user_id").String(); got != "ou_note" {
+		t.Fatalf("dry-run notes mention user_id = %q, want ou_note; output: %s", got, output)
+	}
+}
+
+func TestCreateDryRun_ObjectiveWithCategoryID(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--content", validCreateSimpleJSON,
+		"--category-id", "7249339036661170180",
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if got := gjson.Get(output, "data.api.0.body.category_id").String(); got != "7249339036661170180" {
+		t.Fatalf("dry-run category_id = %q, want 7249339036661170180; output: %s", got, output)
+	}
+}
+
+func TestCreateDryRun_KeyResult(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "key-result",
+		"--objective-id", "456",
+		"--style", "richtext",
+		"--content", validCreateRichTextJSON,
+		"--user-id-type", "union_id",
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if got := gjson.Get(output, "data.api.0.method").String(); got != "POST" {
+		t.Fatalf("dry-run method = %q, want POST; output: %s", got, output)
+	}
+	if got := gjson.Get(output, "data.api.0.url").String(); got != "/open-apis/okr/v2/objectives/456/key_results" {
+		t.Fatalf("dry-run url = %q, want key result create path; output: %s", got, output)
+	}
+	if gjson.Get(output, "data.api.0.params.objective_id").String() != "456" {
+		t.Fatalf("expected objective-id query param in dry-run, got: %s", output)
+	}
+	if gjson.Get(output, "data.api.0.params.user_id_type").String() != "union_id" {
+		t.Fatalf("expected query params in dry-run, got: %s", output)
+	}
+	if got := gjson.Get(output, "data.api.0.body.content.blocks.0.paragraph.elements.0.text_run.text").String(); got != "test content" {
+		t.Fatalf("dry-run richtext content = %q, want test content; output: %s", got, output)
+	}
+}
+
+func TestCreateExecute_ObjectiveSuccess(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, reg := cmdutil.TestFactory(t, createTestConfig(t))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/okr/v2/cycles/123/objectives",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"objective_id": "1001",
+			},
+		},
+	})
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--content", validCreateSimpleJSON,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data := decodeEnvelope(t, stdout)
+	level, _ := data["level"].(string)
+	if level != "objective" {
+		t.Fatalf("expected level objective, got %v", data["level"])
+	}
+	if data["objective_id"] != "1001" {
+		t.Fatalf("expected objective_id=1001, got %v", data["objective_id"])
+	}
+}
+
+func TestCreateExecute_KeyResultSuccess(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, reg := cmdutil.TestFactory(t, createTestConfig(t))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/okr/v2/objectives/456/key_results",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"key_result_id": "2001",
+			},
+		},
+	})
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "key-result",
+		"--objective-id", "456",
+		"--content", validCreateSimpleJSON,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data := decodeEnvelope(t, stdout)
+	level, _ := data["level"].(string)
+	if level != "key-result" {
+		t.Fatalf("expected level key-result, got %v", data["level"])
+	}
+	if data["key_result_id"] != "2001" {
+		t.Fatalf("expected key_result_id=2001, got %v", data["key_result_id"])
+	}
+	if data["objective_id"] != "456" {
+		t.Fatalf("expected objective_id=456, got %v", data["objective_id"])
+	}
+}
+
+func TestCreateExecute_ObjectiveAPITypedErrorPassThrough(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, reg := cmdutil.TestFactory(t, createTestConfig(t))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/okr/v2/cycles/123/objectives",
+		Status: 400,
+		Body: map[string]interface{}{
+			"code": 1001001,
+			"msg":  "invalid parameters",
+		},
+	})
+	err := runCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--level", "objective",
+		"--cycle-id", "123",
+		"--content", validCreateSimpleJSON,
+	})
+	if err == nil {
+		t.Fatal("expected API error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryAPI {
+		t.Fatalf("expected typed API error, got: %v", err)
+	}
+}
+
+func TestCreateExecute_KeyResultRawErrorWrappedAsNetworkError(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, createTestConfig(t))
+	raw := errors.New("dial tcp: i/o timeout")
+	got := wrapOkrNetworkErr(raw, "failed to create key result")
+	problem, ok := errs.ProblemOf(got)
+	if !ok || problem.Category != errs.CategoryNetwork || problem.Subtype != errs.SubtypeNetworkTransport {
+		t.Fatalf("expected network transport error, got: %v", got)
+	}
+	if !errors.Is(got, raw) {
+		t.Fatal("expected wrapped raw error to be preserved")
+	}
+	if stdout.String() != "" || f == nil {
+		// keep the test factory referenced so the helper wiring stays exercised
+	}
+}

shortcuts/okr/okr_cycle_list.go

@@ -64,6 +64,10 @@ func isCurrentActiveCycle(cycle *Cycle, now time.Time) bool {
 	cycleStart := time.UnixMilli(startMs).UTC()
 	cycleEnd := time.UnixMilli(endMs).UTC()
 	nowUTC := now.UTC()
+	// Month cycles only
+	if cycleStart.AddDate(1, 0, -1) == cycleEnd {
+		return false
+	}
 
 	// Check time range: now must be >= start and <= end
 	if nowUTC.Before(cycleStart) || nowUTC.After(cycleEnd) {
@@ -78,6 +82,7 @@ func isCurrentActiveCycle(cycle *Cycle, now time.Time) bool {
 	return status == CycleStatusDefault || status == CycleStatusNormal
 }
 
+// OKRListCycles
 var OKRListCycles = common.Shortcut{
 	Service:     "okr",
 	Command:     "+cycle-list",
@@ -89,7 +94,9 @@ var OKRListCycles = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "user-id", Desc: "user ID", Required: true},
 		{Name: "user-id-type", Default: "open_id", Desc: "user ID type: open_id | union_id | user_id"},
-		{Name: "time-range", Desc: "specify time range. Use Format as YYYY-MM--YYYY-MM. leave empty to fetch all user cycles."},
+		{Name: "time-range", Desc: "local post-filter applied after the requested page is fetched. Format: YYYY-MM--YYYY-MM. Leave empty to keep the page unfiltered."},
+		{Name: "page-size", Type: "int", Default: "100", Desc: "page size, range 1-100"},
+		{Name: "page-token", Desc: "pagination token from previous response"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		idType := runtime.Str("user-id-type")
@@ -110,18 +117,29 @@ var OKRListCycles = common.Shortcut{
 				return err
 			}
 		}
+		if _, err := common.ValidatePageSizeTyped(runtime, "page-size", 100, 1, 100); err != nil {
+			return err
+		}
+		if pageToken := runtime.Str("page-token"); pageToken != "" {
+			if err := common.RejectDangerousCharsTyped("--page-token", pageToken); err != nil {
+				return err
+			}
+		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		params := map[string]interface{}{
 			"user_id":      runtime.Str("user-id"),
 			"user_id_type": runtime.Str("user-id-type"),
-			"page_size":    100,
+			"page_size":    runtime.Int("page-size"),
+		}
+		if pageToken := runtime.Str("page-token"); pageToken != "" {
+			params["page_token"] = pageToken
 		}
 		return common.NewDryRunAPI().
 			GET("/open-apis/okr/v2/cycles").
 			Params(params).
-			Desc("List OKR cycles for user, paginated at 100 per page, filtered by time-range")
+			Desc("List one page of OKR cycles for user; --time-range is a local post-filter on the returned page")
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		userID := runtime.Str("user-id")
@@ -140,53 +158,35 @@ var OKRListCycles = common.Shortcut{
 			hasRange = true
 		}
 
-		// Paginated fetch of all cycles
 		queryParams := map[string]interface{}{
 			"user_id":      userID,
 			"user_id_type": userIDType,
-			"page_size":    "100",
+			"page_size":    runtime.Int("page-size"),
+		}
+		if pageToken := runtime.Str("page-token"); pageToken != "" {
+			queryParams["page_token"] = pageToken
 		}
 
 		var allCycles []Cycle
-		page := 0
-		for {
-			if err := ctx.Err(); err != nil {
-				return err
-			}
-			if page > 0 {
-				select {
-				case <-ctx.Done():
-					return ctx.Err()
-				case <-time.After(500 * time.Millisecond):
-				}
-			}
-			page++
-
-			data, err := runtime.CallAPITyped("GET", "/open-apis/okr/v2/cycles", queryParams, nil)
-			if err != nil {
-				return err
-			}
-
-			itemsRaw, _ := data["items"].([]interface{})
-			for _, item := range itemsRaw {
-				raw, err := json.Marshal(item)
-				if err != nil {
-					continue
-				}
-				var cycle Cycle
-				if err := json.Unmarshal(raw, &cycle); err != nil {
-					continue
-				}
-				allCycles = append(allCycles, cycle)
-			}
-
-			hasMore, pageToken := common.PaginationMeta(data)
-			if !hasMore || pageToken == "" {
-				break
-			}
-			queryParams["page_token"] = pageToken
+		data, err := runtime.CallAPITyped("GET", "/open-apis/okr/v2/cycles", queryParams, nil)
+		if err != nil {
+			return err
 		}
 
+		itemsRaw, _ := data["items"].([]interface{})
+		for _, item := range itemsRaw {
+			raw, err := json.Marshal(item)
+			if err != nil {
+				continue
+			}
+			var cycle Cycle
+			if err := json.Unmarshal(raw, &cycle); err != nil {
+				continue
+			}
+			allCycles = append(allCycles, cycle)
+		}
+		hasMore, nextPageToken := common.PaginationMeta(data)
+
 		// Filter by time-range overlap
 		var filtered []Cycle
 		for i := range allCycles {
@@ -212,7 +212,8 @@ var OKRListCycles = common.Shortcut{
 
 		runtime.OutFormat(map[string]interface{}{
 			"cycles":                respCycles,
-			"total":                 len(respCycles),
+			"has_more":              hasMore,
+			"page_token":            nextPageToken,
 			"current_active_cycles": currentActiveCycles,
 		}, nil, func(w io.Writer) {
 			fmt.Fprintf(w, "Found %d cycle(s)\n", len(respCycles))

shortcuts/okr/okr_cycle_list_test.go

@@ -5,6 +5,8 @@ package okr
 
 import (
 	"bytes"
+	"net/http"
+	"net/url"
 	"strconv"
 	"strings"
 	"testing"
@@ -12,6 +14,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -120,6 +123,27 @@ func TestCycleListValidate_StartAfterEndTimeRange(t *testing.T) {
 	}
 }
 
+func TestCycleListValidate_InvalidPageSize(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, cycleListTestConfig(t))
+	err := runCycleListShortcut(t, f, stdout, []string{
+		"+cycle-list",
+		"--user-id", "ou-123",
+		"--page-size", "101",
+	})
+	if err == nil {
+		t.Fatal("expected error for invalid --page-size")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected validation invalid_argument problem, got: %v", err)
+	}
+	validationErr, ok := err.(*errs.ValidationError)
+	if !ok || validationErr.Param != "--page-size" {
+		t.Fatalf("expected param --page-size, got: %v", err)
+	}
+}
+
 func TestCycleListValidate_ValidNoTimeRange(t *testing.T) {
 	t.Parallel()
 	f, stdout, _, reg := cmdutil.TestFactory(t, cycleListTestConfig(t))
@@ -214,6 +238,9 @@ func TestCycleListDryRun(t *testing.T) {
 	if !strings.Contains(output, "/open-apis/okr/v2/cycles") {
 		t.Fatalf("dry-run output should contain API path, got: %s", output)
 	}
+	if !strings.Contains(output, "\"page_size\": 100") {
+		t.Fatalf("dry-run output should contain default page_size=100, got: %s", output)
+	}
 }
 
 func TestCycleListDryRun_WithTimeRange(t *testing.T) {
@@ -234,6 +261,28 @@ func TestCycleListDryRun_WithTimeRange(t *testing.T) {
 	}
 }
 
+func TestCycleListDryRun_WithPagination(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, cycleListTestConfig(t))
+	err := runCycleListShortcut(t, f, stdout, []string{
+		"+cycle-list",
+		"--user-id", "ou-789",
+		"--page-size", "20",
+		"--page-token", "next-page",
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if !strings.Contains(output, "\"page_size\": 20") {
+		t.Fatalf("dry-run output should contain page_size=20, got: %s", output)
+	}
+	if !strings.Contains(output, "\"page_token\": \"next-page\"") {
+		t.Fatalf("dry-run output should contain page_token, got: %s", output)
+	}
+}
+
 // --- Execute tests ---
 
 func TestCycleListExecute_NoCycles(t *testing.T) {
@@ -454,9 +503,11 @@ func TestCycleListExecute_WithCycles(t *testing.T) {
 	if len(cycles) != 2 {
 		t.Fatalf("cycles count = %d, want 2", len(cycles))
 	}
-	total, _ := data["total"].(float64)
-	if int(total) != 2 {
-		t.Fatalf("total = %v, want 2", total)
+	if _, ok := data["total"]; ok {
+		t.Fatal("total should not be present in response")
+	}
+	if hasMore, _ := data["has_more"].(bool); hasMore {
+		t.Fatalf("has_more = %v, want false", hasMore)
 	}
 
 	// Check current_active_cycles - should only contain cycle-active
@@ -555,10 +606,13 @@ func TestCycleListExecute_Pagination(t *testing.T) {
 	t.Parallel()
 	f, stdout, _, reg := cmdutil.TestFactory(t, cycleListTestConfig(t))
 
-	// First page
+	var gotQuery url.Values
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
 		URL:    "/open-apis/okr/v2/cycles",
+		OnMatch: func(req *http.Request) {
+			gotQuery = req.URL.Query()
+		},
 		Body: map[string]interface{}{
 			"code": 0,
 			"msg":  "ok",
@@ -578,38 +632,31 @@ func TestCycleListExecute_Pagination(t *testing.T) {
 		},
 	})
 
-	// Second page
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/okr/v2/cycles",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"data": map[string]interface{}{
-				"items": []interface{}{
-					map[string]interface{}{
-						"id":           "cycle-p2",
-						"start_time":   "1738368000000",
-						"end_time":     "1743465600000",
-						"cycle_status": 1,
-						"owner":        map[string]interface{}{"owner_type": "user", "user_id": "ou-1"},
-					},
-				},
-			},
-		},
-	})
-
 	err := runCycleListShortcut(t, f, stdout, []string{
 		"+cycle-list",
 		"--user-id", "ou-123",
+		"--page-size", "1",
+		"--page-token", "start_page",
 	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
+	if got := gotQuery.Get("page_size"); got != "1" {
+		t.Fatalf("query page_size = %q, want 1", got)
+	}
+	if got := gotQuery.Get("page_token"); got != "start_page" {
+		t.Fatalf("query page_token = %q, want start_page", got)
+	}
 	data := decodeEnvelope(t, stdout)
 	cycles, _ := data["cycles"].([]interface{})
-	if len(cycles) != 2 {
-		t.Fatalf("cycles count = %d, want 2", len(cycles))
+	if len(cycles) != 1 {
+		t.Fatalf("cycles count = %d, want 1", len(cycles))
+	}
+	if hasMore, _ := data["has_more"].(bool); !hasMore {
+		t.Fatalf("has_more = %v, want true", hasMore)
+	}
+	if pageToken, _ := data["page_token"].(string); pageToken != "next_page" {
+		t.Fatalf("page_token = %q, want next_page", pageToken)
 	}
 }
 

shortcuts/okr/okr_progress_list.go

@@ -28,6 +28,8 @@ var OKRListProgress = common.Shortcut{
 		{Name: "target-type", Desc: "target type: objective | key_result", Required: true, Enum: []string{"objective", "key_result"}},
 		{Name: "user-id-type", Default: "open_id", Desc: "user ID type: open_id | union_id | user_id"},
 		{Name: "department-id-type", Default: "open_department_id", Desc: "department ID type: department_id | open_department_id"},
+		{Name: "page-size", Type: "int", Default: "100", Desc: "page size, range 1-100"},
+		{Name: "page-token", Desc: "pagination token from previous response"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		targetID := runtime.Str("target-id")
@@ -55,6 +57,14 @@ var OKRListProgress = common.Shortcut{
 		if deptIDType != "department_id" && deptIDType != "open_department_id" {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--department-id-type must be one of: department_id | open_department_id").WithParam("--department-id-type")
 		}
+		if _, err := common.ValidatePageSizeTyped(runtime, "page-size", 100, 1, 100); err != nil {
+			return err
+		}
+		if pageToken := runtime.Str("page-token"); pageToken != "" {
+			if err := common.RejectDangerousCharsTyped("--page-token", pageToken); err != nil {
+				return err
+			}
+		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -63,7 +73,10 @@ var OKRListProgress = common.Shortcut{
 		params := map[string]interface{}{
 			"user_id_type":       runtime.Str("user-id-type"),
 			"department_id_type": runtime.Str("department-id-type"),
-			"page_size":          100,
+			"page_size":          runtime.Int("page-size"),
+		}
+		if pageToken := runtime.Str("page-token"); pageToken != "" {
+			params["page_token"] = pageToken
 		}
 
 		switch targetType {
@@ -91,7 +104,10 @@ var OKRListProgress = common.Shortcut{
 		queryParams := map[string]interface{}{
 			"user_id_type":       userIDType,
 			"department_id_type": deptIDType,
-			"page_size":          "100",
+			"page_size":          runtime.Int("page-size"),
+		}
+		if pageToken := runtime.Str("page-token"); pageToken != "" {
+			queryParams["page_token"] = pageToken
 		}
 
 		var apiPath string
@@ -103,36 +119,29 @@ var OKRListProgress = common.Shortcut{
 		}
 
 		var allProgress []*Progress
-		for {
-			if err := ctx.Err(); err != nil {
-				return err
-			}
-
-			data, err := runtime.CallAPITyped("GET", apiPath, queryParams, nil)
-			if err != nil {
-				return err
-			}
-
-			itemsRaw, _ := data["items"].([]interface{})
-			for _, item := range itemsRaw {
-				raw, err := json.Marshal(item)
-				if err != nil {
-					continue
-				}
-				var progress Progress
-				if err := json.Unmarshal(raw, &progress); err != nil {
-					continue
-				}
-				allProgress = append(allProgress, &progress)
-			}
-
-			hasMore, pageToken := common.PaginationMeta(data)
-			if !hasMore || pageToken == "" {
-				break
-			}
-			queryParams["page_token"] = pageToken
+		if err := ctx.Err(); err != nil {
+			return err
 		}
 
+		data, err := runtime.CallAPITyped("GET", apiPath, queryParams, nil)
+		if err != nil {
+			return err
+		}
+
+		itemsRaw, _ := data["items"].([]interface{})
+		for _, item := range itemsRaw {
+			raw, err := json.Marshal(item)
+			if err != nil {
+				continue
+			}
+			var progress Progress
+			if err := json.Unmarshal(raw, &progress); err != nil {
+				continue
+			}
+			allProgress = append(allProgress, &progress)
+		}
+		hasMore, pageToken := common.PaginationMeta(data)
+
 		// Convert to response format
 		respProgress := make([]*RespProgress, 0, len(allProgress))
 		for _, p := range allProgress {
@@ -141,7 +150,8 @@ var OKRListProgress = common.Shortcut{
 
 		runtime.OutFormat(map[string]interface{}{
 			"progress_list": respProgress,
-			"total":         len(respProgress),
+			"has_more":      hasMore,
+			"page_token":    pageToken,
 		}, nil, func(w io.Writer) {
 			fmt.Fprintf(w, "Found %d progress(es)\n", len(respProgress))
 			for _, p := range respProgress {

shortcuts/okr/okr_progress_list_test.go

@@ -5,11 +5,14 @@ package okr
 
 import (
 	"bytes"
+	"net/http"
+	"net/url"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -123,6 +126,28 @@ func TestProgressListValidate_InvalidDepartmentIDType(t *testing.T) {
 	}
 }
 
+func TestProgressListValidate_InvalidPageSize(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressListTestConfig(t))
+	err := runProgressListShortcut(t, f, stdout, []string{
+		"+progress-list",
+		"--target-id", "123",
+		"--target-type", "objective",
+		"--page-size", "0",
+	})
+	if err == nil {
+		t.Fatal("expected error for invalid --page-size")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected validation invalid_argument problem, got: %v", err)
+	}
+	validationErr, ok := err.(*errs.ValidationError)
+	if !ok || validationErr.Param != "--page-size" {
+		t.Fatalf("expected param --page-size, got: %v", err)
+	}
+}
+
 // --- DryRun tests ---
 
 func TestProgressListDryRun_Objective(t *testing.T) {
@@ -144,6 +169,9 @@ func TestProgressListDryRun_Objective(t *testing.T) {
 	if !strings.Contains(output, "GET") {
 		t.Fatalf("dry-run output should contain GET method, got: %s", output)
 	}
+	if !strings.Contains(output, "\"page_size\": 100") {
+		t.Fatalf("dry-run output should contain default page_size=100, got: %s", output)
+	}
 }
 
 func TestProgressListDryRun_KeyResult(t *testing.T) {
@@ -164,14 +192,41 @@ func TestProgressListDryRun_KeyResult(t *testing.T) {
 	}
 }
 
+func TestProgressListDryRun_WithPagination(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressListTestConfig(t))
+	err := runProgressListShortcut(t, f, stdout, []string{
+		"+progress-list",
+		"--target-id", "123456789",
+		"--target-type", "objective",
+		"--page-size", "25",
+		"--page-token", "next-page",
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if !strings.Contains(output, "\"page_size\": 25") {
+		t.Fatalf("dry-run output should contain page_size=25, got: %s", output)
+	}
+	if !strings.Contains(output, "\"page_token\": \"next-page\"") {
+		t.Fatalf("dry-run output should contain page_token, got: %s", output)
+	}
+}
+
 // --- Execute tests ---
 
 func TestProgressListExecute_Success_Objective(t *testing.T) {
 	t.Parallel()
 	f, stdout, _, reg := cmdutil.TestFactory(t, progressListTestConfig(t))
+	var gotQuery url.Values
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
 		URL:    "/open-apis/okr/v2/objectives/123456789/progresses",
+		OnMatch: func(req *http.Request) {
+			gotQuery = req.URL.Query()
+		},
 		Body: map[string]interface{}{
 			"code": 0,
 			"msg":  "ok",
@@ -191,7 +246,8 @@ func TestProgressListExecute_Success_Objective(t *testing.T) {
 						},
 					},
 				},
-				"has_more": false,
+				"has_more":   true,
+				"page_token": "next_page",
 			},
 		},
 	})
@@ -199,15 +255,32 @@ func TestProgressListExecute_Success_Objective(t *testing.T) {
 		"+progress-list",
 		"--target-id", "123456789",
 		"--target-type", "objective",
+		"--page-size", "50",
+		"--page-token", "start_page",
 	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
+	if got := gotQuery.Get("page_size"); got != "50" {
+		t.Fatalf("query page_size = %q, want 50", got)
+	}
+	if got := gotQuery.Get("page_token"); got != "start_page" {
+		t.Fatalf("query page_token = %q, want start_page", got)
+	}
 	data := decodeEnvelope(t, stdout)
 	records, _ := data["progress_list"].([]interface{})
 	if len(records) != 1 {
 		t.Fatalf("expected 1 progress, got %d", len(records))
 	}
+	if _, ok := data["total"]; ok {
+		t.Fatal("total should not be present in response")
+	}
+	if hasMore, _ := data["has_more"].(bool); !hasMore {
+		t.Fatalf("has_more = %v, want true", hasMore)
+	}
+	if pageToken, _ := data["page_token"].(string); pageToken != "next_page" {
+		t.Fatalf("page_token = %q, want next_page", pageToken)
+	}
 }
 
 func TestProgressListExecute_Success_KeyResult(t *testing.T) {

shortcuts/okr/shortcuts.go

@@ -18,6 +18,7 @@ func Shortcuts() []common.Shortcut {
 		OKRUpdateProgressRecord,
 		OKRDeleteProgressRecord,
 		OKRUploadImage,
+		OKRCreate,
 		OKRBatchCreate,
 		OKRReorder,
 		OKRWeight,

shortcuts/okr/shortcuts_test.go

@@ -12,6 +12,12 @@ import (
 func TestShortcutsRegistration(t *testing.T) {
 	convey.Convey("Shortcuts() returns all commands", t, func() {
 		list := Shortcuts()
-		convey.So(len(list), convey.ShouldBeGreaterThan, 0)
+		commands := make([]string, 0, len(list))
+		for _, shortcut := range list {
+			commands = append(commands, shortcut.Command)
+		}
+		convey.So(commands, convey.ShouldContain, "+create")
+		convey.So(commands, convey.ShouldContain, "+batch-create")
+		convey.So(commands, convey.ShouldContain, "+patch")
 	})
 }

shortcuts/slides/shortcuts.go

@@ -3,11 +3,24 @@
 
 package slides
 
-import "github.com/larksuite/cli/shortcuts/common"
+import (
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+var presentationFlagAliases = []string{
+	"presentation-id",
+	"presentation-token",
+	"token",
+	"presentation_id",
+	"xml-presentation-id",
+	"url",
+}
 
 // Shortcuts returns all slides shortcuts.
 func Shortcuts() []common.Shortcut {
-	return []common.Shortcut{
+	all := []common.Shortcut{
 		SlidesCreate,
 		SlidesMediaUpload,
 		SlidesReplaceSlide,
@@ -18,4 +31,39 @@ func Shortcuts() []common.Shortcut {
 		SlidesHistoryRevert,
 		SlidesHistoryRevertStatus,
 	}
+	for i := range all {
+		if hasPresentationFlag(all[i].Flags) {
+			all[i].PostMount = withPresentationFlagAliases(all[i].PostMount)
+		}
+	}
+	return all
+}
+
+func hasPresentationFlag(flags []common.Flag) bool {
+	for _, flag := range flags {
+		if flag.Name == "presentation" {
+			return true
+		}
+	}
+	return false
+}
+
+// withPresentationFlagAliases accepts common agent-generated spellings for
+// --presentation without registering extra flags. The aliases therefore stay
+// out of help and completion while resolving to the canonical flag at parse
+// time, matching the zero-round-trip compatibility used by Sheets.
+func withPresentationFlagAliases(prev func(cmd *cobra.Command)) func(cmd *cobra.Command) {
+	return func(cmd *cobra.Command) {
+		if prev != nil {
+			prev(cmd)
+		}
+		cmd.Flags().SetNormalizeFunc(func(_ *pflag.FlagSet, name string) pflag.NormalizedName {
+			for _, alias := range presentationFlagAliases {
+				if name == alias {
+					return pflag.NormalizedName("presentation")
+				}
+			}
+			return pflag.NormalizedName(name)
+		})
+	}
 }

shortcuts/slides/shortcuts_alias_test.go

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestWithPresentationFlagAliases(t *testing.T) {
+	for _, alias := range presentationFlagAliases {
+		t.Run(alias, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("presentation", "", "presentation reference")
+			withPresentationFlagAliases(nil)(cmd)
+
+			if err := cmd.Flags().Parse([]string{"--" + alias, "presABC"}); err != nil {
+				t.Fatalf("--%s should resolve to --presentation: %v", alias, err)
+			}
+			got, err := cmd.Flags().GetString("presentation")
+			if err != nil {
+				t.Fatalf("read --presentation: %v", err)
+			}
+			if got != "presABC" {
+				t.Fatalf("--%s set --presentation to %q, want presABC", alias, got)
+			}
+			if usage := cmd.Flags().FlagUsages(); strings.Contains(usage, "--"+alias) {
+				t.Fatalf("hidden compatibility alias --%s leaked into help:\n%s", alias, usage)
+			}
+		})
+	}
+}
+
+func TestShortcutsAttachPresentationFlagAliases(t *testing.T) {
+	count := 0
+	for _, shortcut := range Shortcuts() {
+		if !hasPresentationFlag(shortcut.Flags) {
+			continue
+		}
+		count++
+		if shortcut.PostMount == nil {
+			t.Errorf("%s has --presentation but no compatibility normalizer", shortcut.Command)
+			continue
+		}
+
+		cmd := &cobra.Command{Use: shortcut.Command}
+		cmd.Flags().String("presentation", "", "presentation reference")
+		shortcut.PostMount(cmd)
+		if err := cmd.Flags().Parse([]string{"--token", "presABC"}); err != nil {
+			t.Errorf("%s did not normalize --token: %v", shortcut.Command, err)
+			continue
+		}
+		got, err := cmd.Flags().GetString("presentation")
+		if err != nil {
+			t.Errorf("%s could not read --presentation: %v", shortcut.Command, err)
+			continue
+		}
+		if got != "presABC" {
+			t.Errorf("%s normalized --token to %q, want presABC", shortcut.Command, got)
+		}
+	}
+	if count == 0 {
+		t.Fatal("expected at least one slides shortcut with --presentation")
+	}
+}

shortcuts/slides/slides_screenshot.go

@@ -37,15 +37,13 @@ var SlidesScreenshot = common.Shortcut{
 	Command:     "+screenshot",
 	Description: "Save up to 10 slide screenshots to local files without printing Base64 image data",
 	Risk:        "read",
-	Scopes:      []string{},
-	// The screenshot API is allowlist-gated for only a few apps, so do not
-	// advertise/preflight its scope. Let the API fail and let callers degrade.
+	Scopes:      []string{"slides:presentation:screenshot"},
 	// wiki:node:read is required only when --presentation is a wiki URL.
 	ConditionalScopes: []string{"wiki:node:read"},
 	AuthTypes:         []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides; list mode only"},
-		{Name: "slide-id", Type: "string_array", Desc: "slide page identifier (repeat for multiple slides; max 10 pages per request)"},
+		{Name: "slide-id", Type: "string_slice", Desc: "slide page identifier (repeat or comma-separated for multiple slides; max 10 pages per request)"},
 		{Name: "slide-number", Type: "int_array", Desc: "slide page number (repeat for multiple slides; max 10 pages per request)"},
 		{Name: "content", Desc: "slide XML content to render directly instead of fetching existing slides", Input: []string{common.File, common.Stdin}},
 		{Name: "output-dir", Default: defaultSlidesScreenshotDir, Desc: "relative directory for saved screenshots"},
@@ -57,7 +55,7 @@ var SlidesScreenshot = common.Shortcut{
 			if strings.TrimSpace(runtime.Str("content")) == "" {
 				return slidesScreenshotFlagErrorf("--content cannot be empty")
 			}
-			if len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
+			if len(normalizeSlideIDs(runtime.StrSlice("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
 				return slidesScreenshotFlagErrorf("--content cannot be used with --slide-id or --slide-number")
 			}
 			if runtime.Changed("presentation") {
@@ -73,7 +71,7 @@ var SlidesScreenshot = common.Shortcut{
 					return err
 				}
 			}
-			slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
+			slideIDs := normalizeSlideIDs(runtime.StrSlice("slide-id"))
 			slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
 			if err != nil {
 				return err
@@ -98,7 +96,7 @@ var SlidesScreenshot = common.Shortcut{
 		if err != nil {
 			return common.NewDryRunAPI().Set("error", err.Error())
 		}
-		slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
+		slideIDs := normalizeSlideIDs(runtime.StrSlice("slide-id"))
 		slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
 		if err != nil {
 			return common.NewDryRunAPI().Set("error", err.Error())
@@ -148,7 +146,7 @@ var SlidesScreenshot = common.Shortcut{
 			return err
 		}
 
-		slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
+		slideIDs := normalizeSlideIDs(runtime.StrSlice("slide-id"))
 		slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
 		if err != nil {
 			return err
@@ -200,7 +198,7 @@ func dryRunRenderScreenshot(runtime *common.RuntimeContext) *common.DryRunAPI {
 	if strings.TrimSpace(content) == "" {
 		return common.NewDryRunAPI().Set("error", "--content cannot be empty")
 	}
-	if len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
+	if len(normalizeSlideIDs(runtime.StrSlice("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
 		return common.NewDryRunAPI().Set("error", "--content cannot be used with --slide-id or --slide-number")
 	}
 	if runtime.Changed("presentation") {
@@ -219,7 +217,7 @@ func executeRenderScreenshot(runtime *common.RuntimeContext) error {
 	if strings.TrimSpace(content) == "" {
 		return slidesScreenshotFlagErrorf("--content cannot be empty")
 	}
-	if len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
+	if len(normalizeSlideIDs(runtime.StrSlice("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0 {
 		return slidesScreenshotFlagErrorf("--content cannot be used with --slide-id or --slide-number")
 	}
 	if runtime.Changed("presentation") {

shortcuts/slides/slides_screenshot_test.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"testing"
 
@@ -17,23 +18,19 @@ import (
 )
 
 func TestSlidesScreenshotDeclaredScopes(t *testing.T) {
-	if got := SlidesScreenshot.ScopesForIdentity("user"); len(got) != 0 {
-		t.Fatalf("user preflight scopes = %#v, want empty", got)
+	base := []string{"slides:presentation:screenshot"}
+	if got := SlidesScreenshot.ScopesForIdentity("user"); !reflect.DeepEqual(got, base) {
+		t.Fatalf("user preflight scopes = %#v, want %#v", got, base)
 	}
-	if got := SlidesScreenshot.ScopesForIdentity("bot"); len(got) != 0 {
-		t.Fatalf("bot preflight scopes = %#v, want empty", got)
+	if got := SlidesScreenshot.ScopesForIdentity("bot"); !reflect.DeepEqual(got, base) {
+		t.Fatalf("bot preflight scopes = %#v, want %#v", got, base)
 	}
 
 	got := SlidesScreenshot.DeclaredScopesForIdentity("user")
-	want := []string{"wiki:node:read"}
-	if len(got) != len(want) || got[0] != want[0] {
+	want := []string{"slides:presentation:screenshot", "wiki:node:read"}
+	if !reflect.DeepEqual(got, want) {
 		t.Fatalf("declared scopes = %#v, want %#v", got, want)
 	}
-	for _, scope := range got {
-		if scope == "slides:presentation:screenshot" {
-			t.Fatalf("declared scopes must not advertise screenshot scope: %#v", got)
-		}
-	}
 }
 
 func TestSlidesScreenshotWritesFilesAndSuppressesBase64(t *testing.T) {
@@ -188,6 +185,139 @@ func TestSlidesScreenshotListBySlideNumber(t *testing.T) {
 	}
 }
 
+func TestSlidesScreenshotListBySlideIDCSV(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide_images",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"slide_images": []map[string]interface{}{
+					{
+						"slide_id": "slide_1",
+						"format":   1,
+						"data":     base64.StdEncoding.EncodeToString([]byte("png-bytes-1")),
+					},
+					{
+						"slide_id": "slide_2",
+						"format":   1,
+						"data":     base64.StdEncoding.EncodeToString([]byte("png-bytes-2")),
+					},
+				},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-id", "slide_1,slide_2",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var body struct {
+		SlideIDs []string `json:"slide_ids"`
+	}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode request body: %v", err)
+	}
+	if len(body.SlideIDs) != 2 || body.SlideIDs[0] != "slide_1" || body.SlideIDs[1] != "slide_2" {
+		t.Fatalf("slide_ids = %#v, want [slide_1 slide_2]", body.SlideIDs)
+	}
+
+	path1 := filepath.Join(dir, defaultSlidesScreenshotDir, "pres_abc_slide_1.png")
+	if _, err := os.ReadFile(path1); err != nil {
+		t.Fatalf("read first CSV slide screenshot: %v", err)
+	}
+	path2 := filepath.Join(dir, defaultSlidesScreenshotDir, "pres_abc_slide_2.png")
+	if _, err := os.ReadFile(path2); err != nil {
+		t.Fatalf("read second CSV slide screenshot: %v", err)
+	}
+}
+
+func TestSlidesScreenshotListBySlideIDCSVDeduplicatesAndTrims(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide_images",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"slide_images": []map[string]interface{}{
+					{
+						"slide_id": "slide_1",
+						"format":   1,
+						"data":     base64.StdEncoding.EncodeToString([]byte("png-bytes-1")),
+					},
+					{
+						"slide_id": "slide_2",
+						"format":   1,
+						"data":     base64.StdEncoding.EncodeToString([]byte("png-bytes-2")),
+					},
+				},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	// CSV with a duplicate and blank segments should normalize the same way
+	// normalizeSlideIDs already does for repeated --slide-id flags.
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-id", "slide_1, slide_2,slide_1,",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var body struct {
+		SlideIDs []string `json:"slide_ids"`
+	}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode request body: %v", err)
+	}
+	if len(body.SlideIDs) != 2 || body.SlideIDs[0] != "slide_1" || body.SlideIDs[1] != "slide_2" {
+		t.Fatalf("slide_ids = %#v, want deduplicated [slide_1 slide_2]", body.SlideIDs)
+	}
+}
+
+func TestSlidesScreenshotListRejectsMoreThanTenSlideIDsCSV(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-id", "s1,s2,s3,s4,s5,s6,s7,s8,s9,s10,s11",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error = %v, want typed validation error", err)
+	}
+	if problem.Hint != "request at most 10 pages at a time" {
+		t.Fatalf("hint = %q, want max 10 pages guidance", problem.Hint)
+	}
+}
+
 func TestSlidesScreenshotAvoidsOverwritingExistingFile(t *testing.T) {
 	dir := t.TempDir()
 	withSlidesTestWorkingDir(t, dir)
@@ -390,6 +520,27 @@ func TestSlidesScreenshotRenderRejectsSlideSelectors(t *testing.T) {
 	}
 }
 
+func TestSlidesScreenshotRenderRejectsSlideNumberSelector(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	// Exercises the --slide-number-only side of the --content conflict check
+	// (TestSlidesScreenshotRenderRejectsSlideSelectors above only covers the
+	// --slide-id side of that same `||` condition).
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--content", `<slide xmlns="http://www.larkoffice.com/sml/2.0"><data></data></slide>`,
+		"--slide-number", "1",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "--content cannot be used with --slide-id or --slide-number") {
+		t.Fatalf("error = %v, want content/slide selector conflict", err)
+	}
+}
+
 func TestSlidesScreenshotRenderRejectsListOnlyFlags(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
 

shortcuts/task/shortcuts.go

@@ -10,6 +10,7 @@ import (
 	"io"
 	"net/http"
 	"net/url"
+	"regexp"
 	"strings"
 	"time"
 
@@ -100,6 +101,40 @@ func extractTaskGuid(input string) string {
 	return extractTasklistGuid(input)
 }
 
+var taskDisplayNumberPattern = regexp.MustCompile(`^t[0-9]+$`)
+
+func parseTaskGUID(input string) (string, error) {
+	input = strings.TrimSpace(input)
+	invalid := func(format string, args ...interface{}) *errs.ValidationError {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...).
+			WithParam("--task-id").
+			WithHint("provide the Task OpenAPI GUID or a task applink containing guid=")
+	}
+
+	if input == "" {
+		return "", invalid("task ID is empty")
+	}
+
+	lowerInput := strings.ToLower(input)
+	if strings.HasPrefix(lowerInput, "http://") || strings.HasPrefix(lowerInput, "https://") {
+		u, err := url.Parse(input)
+		if err != nil {
+			return "", invalid("invalid task applink: %v", err).WithCause(err)
+		}
+		guid := strings.TrimSpace(u.Query().Get("guid"))
+		if guid == "" {
+			return "", invalid("task applink is missing a non-empty guid query parameter")
+		}
+		return guid, nil
+	}
+
+	if taskDisplayNumberPattern.MatchString(input) {
+		return "", invalid("task display number %q is not a Task OpenAPI GUID", input)
+	}
+
+	return input, nil
+}
+
 func buildTaskCreateBody(runtime *common.RuntimeContext) (map[string]interface{}, error) {
 	body := make(map[string]interface{})
 

shortcuts/task/shortcuts_test.go

@@ -4,8 +4,11 @@
 package task
 
 import (
+	"errors"
+	"net/url"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/smartystreets/goconvey/convey"
 )
 
@@ -15,3 +18,80 @@ func TestShortcutsRegistration(t *testing.T) {
 		convey.So(len(list), convey.ShouldBeGreaterThan, 0)
 	})
 }
+
+func TestParseTaskGUID(t *testing.T) {
+	t.Run("accepts GUIDs and task applinks", func(t *testing.T) {
+		tests := []struct {
+			name  string
+			input string
+			want  string
+		}{
+			{name: "opaque GUID", input: "task-guid-123", want: "task-guid-123"},
+			{name: "trimmed GUID", input: "  task-guid-123  ", want: "task-guid-123"},
+			{
+				name:  "task applink",
+				input: "https://applink.larksuite.com/client/todo/detail?guid=task-guid-123",
+				want:  "task-guid-123",
+			},
+		}
+
+		for _, tt := range tests {
+			t.Run(tt.name, func(t *testing.T) {
+				got, err := parseTaskGUID(tt.input)
+				if err != nil {
+					t.Fatalf("parseTaskGUID(%q) error = %v", tt.input, err)
+				}
+				if got != tt.want {
+					t.Fatalf("parseTaskGUID(%q) = %q, want %q", tt.input, got, tt.want)
+				}
+			})
+		}
+	})
+
+	t.Run("rejects unusable task identifiers", func(t *testing.T) {
+		for _, input := range []string{
+			"",
+			"https://applink.larksuite.com/client/todo/detail",
+			"https://%",
+			"t12345",
+		} {
+			t.Run(input, func(t *testing.T) {
+				_, err := parseTaskGUID(input)
+				if err == nil {
+					t.Fatalf("parseTaskGUID(%q) error = nil, want typed validation error", input)
+				}
+
+				problem, ok := errs.ProblemOf(err)
+				if !ok {
+					t.Fatalf("parseTaskGUID(%q) error type = %T, want typed error", input, err)
+				}
+				if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+					t.Fatalf("problem = %s/%s, want %s/%s", problem.Category, problem.Subtype, errs.CategoryValidation, errs.SubtypeInvalidArgument)
+				}
+				if problem.Hint == "" {
+					t.Fatal("problem hint is empty")
+				}
+
+				var validationErr *errs.ValidationError
+				if !errors.As(err, &validationErr) {
+					t.Fatalf("error type = %T, want *errs.ValidationError", err)
+				}
+				if validationErr.Param != "--task-id" {
+					t.Fatalf("param = %q, want %q", validationErr.Param, "--task-id")
+				}
+			})
+		}
+	})
+
+	t.Run("preserves applink parse cause", func(t *testing.T) {
+		_, err := parseTaskGUID("https://%")
+		if err == nil {
+			t.Fatal("parseTaskGUID() error = nil, want URL parse error")
+		}
+
+		var urlErr *url.Error
+		if !errors.As(err, &urlErr) {
+			t.Fatalf("error chain = %T %v, want *url.Error cause", err, err)
+		}
+	})
+}

shortcuts/task/task_complete.go

@@ -25,45 +25,59 @@ var CompleteTask = common.Shortcut{
 	HasFormat:   true,
 
 	Flags: []common.Flag{
-		{Name: "task-id", Desc: "task id", Required: true},
+		{Name: "task-id", Desc: "task GUID or task applink URL", Required: true},
+	},
+
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := parseTaskGUID(runtime.Str("task-id"))
+		return err
 	},
 
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		body := buildCompleteBody()
-		taskId := url.PathEscape(runtime.Str("task-id"))
+		taskGUID, err := parseTaskGUID(runtime.Str("task-id"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		taskID := url.PathEscape(taskGUID)
 		return common.NewDryRunAPI().
-			GET("/open-apis/task/v2/tasks/" + taskId).
+			GET("/open-apis/task/v2/tasks/" + taskID).
 			Desc("get current task status").
 			Params(map[string]interface{}{"user_id_type": "open_id"}).
-			PATCH("/open-apis/task/v2/tasks/" + taskId).
+			PATCH("/open-apis/task/v2/tasks/" + taskID).
 			Desc("complete task if not completed").
 			Params(map[string]interface{}{"user_id_type": "open_id"}).
 			Body(body)
 	},
 
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		taskId := url.PathEscape(runtime.Str("task-id"))
+		taskGUID, err := parseTaskGUID(runtime.Str("task-id"))
+		if err != nil {
+			return err
+		}
+		taskID := url.PathEscape(taskGUID)
 
 		params := map[string]interface{}{"user_id_type": "open_id"}
 
 		var data map[string]interface{}
 
 		// 1. Get current task status
-		getData, err := callTaskAPITyped(runtime, http.MethodGet, "/open-apis/task/v2/tasks/"+taskId, params, nil)
+		getData, err := callTaskAPITyped(runtime, http.MethodGet, "/open-apis/task/v2/tasks/"+taskID, params, nil)
 		if err != nil {
 			return err
 		}
 
 		taskData, _ := getData["task"].(map[string]interface{})
 		completedAtStr, _ := taskData["completed_at"].(string)
+		alreadyCompleted := completedAtStr != "" && completedAtStr != "0"
 
 		// 2. If already completed, directly return success
-		if completedAtStr != "" && completedAtStr != "0" {
+		if alreadyCompleted {
 			data = getData
 		} else {
 			// 3. Complete the task
 			body := buildCompleteBody()
-			data, err = callTaskAPITyped(runtime, http.MethodPatch, "/open-apis/task/v2/tasks/"+taskId, params, body)
+			data, err = callTaskAPITyped(runtime, http.MethodPatch, "/open-apis/task/v2/tasks/"+taskID, params, body)
 			if err != nil {
 				return err
 			}
@@ -73,11 +87,19 @@ var CompleteTask = common.Shortcut{
 		guid, _ := task["guid"].(string)
 		urlVal, _ := task["url"].(string)
 		urlVal = truncateTaskURL(urlVal)
+		completedAt, _ := task["completed_at"].(string)
+		status := "todo"
+		if completedAt != "" && completedAt != "0" {
+			status = "done"
+		}
 
 		// Standardized write output: return resource identifiers
 		outData := map[string]interface{}{
-			"guid": guid,
-			"url":  urlVal,
+			"guid":              guid,
+			"url":               urlVal,
+			"status":            status,
+			"completed_at":      completedAt,
+			"already_completed": alreadyCompleted,
 		}
 
 		runtime.OutFormat(outData, nil, func(w io.Writer) {

shortcuts/task/task_complete_test.go

@@ -4,9 +4,12 @@
 package task
 
 import (
+	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/httpmock"
 )
 
@@ -45,6 +48,9 @@ func TestCompleteTask(t *testing.T) {
 			formatFlag:  "json",
 			expectedOutput: []string{
 				`"guid": "task-789"`,
+				`"status": "done"`,
+				`"completed_at": "1775174400000"`,
+				`"already_completed": false`,
 			},
 		},
 	}
@@ -109,3 +115,98 @@ func TestCompleteTask(t *testing.T) {
 		})
 	}
 }
+
+func TestTaskCompleteAcceptsTaskApplink(t *testing.T) {
+	f, stdout, _, reg := taskShortcutTestFactory(t)
+	warmTenantToken(t, f, reg)
+
+	for _, method := range []string{"GET", "PATCH"} {
+		reg.Register(&httpmock.Stub{
+			Method: method,
+			URL:    "/open-apis/task/v2/tasks/task-guid-applink",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "success",
+				"data": map[string]interface{}{
+					"task": map[string]interface{}{
+						"guid":         "task-guid-applink",
+						"summary":      "Applink task",
+						"completed_at": map[string]string{"GET": "0", "PATCH": "1775174400000"}[method],
+						"url":          "https://example.com/task-guid-applink",
+					},
+				},
+			},
+		})
+	}
+
+	err := runMountedTaskShortcut(t, CompleteTask, []string{
+		"+complete",
+		"--task-id", "https://applink.larksuite.com/client/todo/detail?guid=task-guid-applink",
+		"--format", "json",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("CompleteTask error = %v", err)
+	}
+	reg.Verify(t)
+	if !strings.Contains(stdout.String(), `"guid": "task-guid-applink"`) {
+		t.Fatalf("output = %s, want normalized task GUID", stdout.String())
+	}
+}
+
+func TestTaskCompleteAlreadyCompletedReturnsServerState(t *testing.T) {
+	f, stdout, _, reg := taskShortcutTestFactory(t)
+	warmTenantToken(t, f, reg)
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/task/v2/tasks/task-guid-done",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"task": map[string]interface{}{
+					"guid":         "task-guid-done",
+					"summary":      "Already done",
+					"completed_at": "1775174400000",
+					"url":          "https://example.com/task-guid-done",
+				},
+			},
+		},
+	})
+
+	err := runMountedTaskShortcut(t, CompleteTask, []string{
+		"+complete", "--task-id", "task-guid-done", "--format", "json", "--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("CompleteTask error = %v", err)
+	}
+	reg.Verify(t)
+
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode output: %v\n%s", err, stdout.String())
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	if data["status"] != "done" || data["completed_at"] != "1775174400000" || data["already_completed"] != true {
+		t.Fatalf("completion state = %#v, want done/already_completed server state", data)
+	}
+}
+
+func TestTaskCompleteRejectsDisplayNumberBeforeRead(t *testing.T) {
+	f, stdout, _, reg := taskShortcutTestFactory(t)
+	warmTenantToken(t, f, reg)
+
+	err := runMountedTaskShortcut(t, CompleteTask, []string{
+		"+complete", "--task-id", "t12345", "--format", "json", "--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("CompleteTask error = nil, want invalid task ID error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("error = %T %v, want typed invalid-argument error", err, err)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) || validationErr.Param != "--task-id" {
+		t.Fatalf("error param = %#v, want --task-id", validationErr)
+	}
+}

shortcuts/task/task_query_helpers.go

@@ -24,6 +24,14 @@ func splitAndTrimCSV(input string) []string {
 	return out
 }
 
+func buildSearchPageParams(pageToken string) map[string]interface{} {
+	params := map[string]interface{}{}
+	if pageToken != "" {
+		params["page_token"] = pageToken
+	}
+	return params
+}
+
 func parseTimeRangeMillis(input string) (string, string, error) {
 	if strings.TrimSpace(input) == "" {
 		return "", "", nil

shortcuts/task/task_query_helpers_test.go

@@ -37,6 +37,31 @@ func TestSplitAndTrimCSV(t *testing.T) {
 	}
 }
 
+func TestBuildSearchPageParams(t *testing.T) {
+	tests := []struct {
+		name      string
+		pageToken string
+		wantToken string
+		wantKey   bool
+	}{
+		{name: "first page omits token"},
+		{name: "subsequent page includes token", pageToken: "pt_123", wantToken: "pt_123", wantKey: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			params := buildSearchPageParams(tt.pageToken)
+			got, present := params["page_token"]
+			if present != tt.wantKey {
+				t.Fatalf("page_token present = %v, want %v; params = %#v", present, tt.wantKey, params)
+			}
+			if tt.wantKey && got != tt.wantToken {
+				t.Fatalf("page_token = %v, want %q", got, tt.wantToken)
+			}
+		})
+	}
+}
+
 func TestOutputTaskSummary(t *testing.T) {
 	tests := []struct {
 		name string

shortcuts/task/task_search.go

@@ -44,8 +44,10 @@ var SearchTask = common.Shortcut{
 		if err != nil {
 			return common.NewDryRunAPI().Set("error", err.Error())
 		}
+		params := buildSearchPageParams(runtime.Str("page-token"))
 		return common.NewDryRunAPI().
 			POST("/open-apis/task/v2/tasks/search").
+			Params(params).
 			Body(body).
 			Desc("Then GET /open-apis/task/v2/tasks/:guid for each search hit to render standard output")
 	},
@@ -74,9 +76,9 @@ var SearchTask = common.Shortcut{
 		var lastPageToken string
 		var lastHasMore bool
 		var notice string
-		currentBody := body
+		params := buildSearchPageParams(runtime.Str("page-token"))
 		for page := 0; page < pageLimit; page++ {
-			data, err := callTaskAPITyped(runtime, http.MethodPost, "/open-apis/task/v2/tasks/search", nil, currentBody)
+			data, err := callTaskAPITyped(runtime, http.MethodPost, "/open-apis/task/v2/tasks/search", params, body)
 			if err != nil {
 				return err
 			}
@@ -90,7 +92,7 @@ var SearchTask = common.Shortcut{
 			if !lastHasMore || lastPageToken == "" {
 				break
 			}
-			currentBody["page_token"] = lastPageToken
+			params["page_token"] = lastPageToken
 		}
 
 		enriched := make([]map[string]interface{}, 0, len(rawItems))
@@ -183,9 +185,6 @@ func buildTaskSearchBody(runtime *common.RuntimeContext) (map[string]interface{}
 	if len(filter) > 0 {
 		body["filter"] = filter
 	}
-	if pageToken := runtime.Str("page-token"); pageToken != "" {
-		body["page_token"] = pageToken
-	}
 	return body, nil
 }
 

shortcuts/task/task_search_pagination_test.go

@@ -0,0 +1,129 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"reflect"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestSearchPaginationUsesQueryToken(t *testing.T) {
+	tests := []struct {
+		name     string
+		shortcut common.Shortcut
+		command  string
+		url      string
+	}{
+		{
+			name:     "tasks",
+			shortcut: SearchTask,
+			command:  "+search",
+			url:      "/open-apis/task/v2/tasks/search",
+		},
+		{
+			name:     "tasklists",
+			shortcut: SearchTasklist,
+			command:  "+tasklist-search",
+			url:      "/open-apis/task/v2/tasklists/search",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f, stdout, _, reg := taskShortcutTestFactory(t)
+			warmTenantToken(t, f, reg)
+
+			var pageTokens []string
+			reg.Register(searchPaginationStub(t, tt.url, "next_pt", true, &pageTokens))
+			reg.Register(searchPaginationStub(t, tt.url, "", false, &pageTokens))
+
+			shortcut := tt.shortcut
+			shortcut.AuthTypes = []string{"bot", "user"}
+			err := runMountedTaskShortcut(t, shortcut, []string{
+				tt.command,
+				"--query", "pagination",
+				"--page-token", "initial_pt",
+				"--page-limit", "2",
+				"--as", "bot",
+				"--format", "json",
+			}, f, stdout)
+			if err != nil {
+				t.Fatalf("search command failed: %v", err)
+			}
+
+			want := []string{"initial_pt", "next_pt"}
+			if !reflect.DeepEqual(pageTokens, want) {
+				t.Fatalf("search page tokens = %#v, want %#v", pageTokens, want)
+			}
+		})
+	}
+}
+
+func assertSearchDryRunPageToken(t *testing.T, preview *common.DryRunAPI, want string) {
+	t.Helper()
+
+	data, err := preview.MarshalJSON()
+	if err != nil {
+		t.Fatalf("marshal search dry-run preview: %v", err)
+	}
+	var envelope struct {
+		API []struct {
+			Params map[string]interface{} `json:"params"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(data, &envelope); err != nil {
+		t.Fatalf("decode search dry-run preview: %v", err)
+	}
+	if len(envelope.API) != 1 {
+		t.Fatalf("search dry-run API call count = %d, want 1; preview = %s", len(envelope.API), data)
+	}
+	call := envelope.API[0]
+	if got, _ := call.Params["page_token"].(string); got != want {
+		t.Fatalf("search dry-run params.page_token = %q, want %q; preview = %s", got, want, data)
+	}
+	if _, present := call.Body["page_token"]; present {
+		t.Fatalf("search dry-run body unexpectedly contains page_token; preview = %s", data)
+	}
+}
+
+func searchPaginationStub(t *testing.T, endpoint, responseToken string, hasMore bool, capturedTokens *[]string) *httpmock.Stub {
+	t.Helper()
+	return &httpmock.Stub{
+		Method: http.MethodPost,
+		URL:    endpoint,
+		OnMatch: func(req *http.Request) {
+			*capturedTokens = append(*capturedTokens, req.URL.Query().Get("page_token"))
+
+			body, err := io.ReadAll(req.Body)
+			if err != nil {
+				t.Errorf("read search request body: %v", err)
+				return
+			}
+			var payload map[string]interface{}
+			if err := json.Unmarshal(body, &payload); err != nil {
+				t.Errorf("decode search request body: %v", err)
+				return
+			}
+			if _, present := payload["page_token"]; present {
+				t.Errorf("search request body unexpectedly contains page_token: %s", body)
+			}
+		},
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "success",
+			"data": map[string]interface{}{
+				"has_more":   hasMore,
+				"page_token": responseToken,
+				"items":      []interface{}{},
+			},
+		},
+	}
+}

shortcuts/task/task_search_test.go

@@ -37,9 +37,12 @@ func TestBuildTaskSearchBody(t *testing.T) {
 			check: func(t *testing.T, body map[string]interface{}) {
 				filter := body["filter"].(map[string]interface{})
 				dueTime := filter["due_time"].(map[string]interface{})
-				if body["query"] != "release" || body["page_token"] != "pt_123" {
+				if body["query"] != "release" {
 					t.Fatalf("unexpected body: %#v", body)
 				}
+				if _, present := body["page_token"]; present {
+					t.Fatalf("body unexpectedly contains page_token: %#v", body)
+				}
 				if len(filter["creator_ids"].([]string)) != 2 || filter["is_completed"] != true {
 					t.Fatalf("unexpected filter: %#v", filter)
 				}
@@ -104,9 +107,10 @@ func TestBuildTaskSearchBody(t *testing.T) {
 
 func TestSearchTask_DryRun(t *testing.T) {
 	tests := []struct {
-		name      string
-		setup     func(*cobra.Command)
-		wantParts []string
+		name          string
+		setup         func(*cobra.Command)
+		wantPageToken string
+		wantParts     []string
 	}{
 		{
 			name: "valid dry run",
@@ -114,7 +118,8 @@ func TestSearchTask_DryRun(t *testing.T) {
 				_ = cmd.Flags().Set("query", "demo")
 				_ = cmd.Flags().Set("page-token", "pt_demo")
 			},
-			wantParts: []string{"POST /open-apis/task/v2/tasks/search", `"query":"demo"`},
+			wantPageToken: "pt_demo",
+			wantParts:     []string{`"query":"demo"`},
 		},
 		{
 			name: "dry run error on invalid due",
@@ -143,7 +148,11 @@ func TestSearchTask_DryRun(t *testing.T) {
 					t.Fatalf("Validate() error = %v", err)
 				}
 			}
-			out := SearchTask.DryRun(nil, runtime).Format()
+			preview := SearchTask.DryRun(nil, runtime)
+			if tt.wantPageToken != "" {
+				assertSearchDryRunPageToken(t, preview, tt.wantPageToken)
+			}
+			out := preview.Format()
 			for _, want := range tt.wantParts {
 				if !strings.Contains(out, want) {
 					t.Fatalf("dry run output missing %q: %s", want, out)

shortcuts/task/task_tasklist_search.go

@@ -41,8 +41,10 @@ var SearchTasklist = common.Shortcut{
 		if err != nil {
 			return common.NewDryRunAPI().Set("error", err.Error())
 		}
+		params := buildSearchPageParams(runtime.Str("page-token"))
 		return common.NewDryRunAPI().
 			POST("/open-apis/task/v2/tasklists/search").
+			Params(params).
 			Body(body).
 			Desc("Then GET /open-apis/task/v2/tasklists/:guid for each search hit to render standard output")
 	},
@@ -71,9 +73,9 @@ var SearchTasklist = common.Shortcut{
 		var lastPageToken string
 		var lastHasMore bool
 		var notice string
-		currentBody := body
+		params := buildSearchPageParams(runtime.Str("page-token"))
 		for page := 0; page < pageLimit; page++ {
-			data, err := callTaskAPITyped(runtime, http.MethodPost, "/open-apis/task/v2/tasklists/search", nil, currentBody)
+			data, err := callTaskAPITyped(runtime, http.MethodPost, "/open-apis/task/v2/tasklists/search", params, body)
 			if err != nil {
 				return err
 			}
@@ -87,7 +89,7 @@ var SearchTasklist = common.Shortcut{
 			if !lastHasMore || lastPageToken == "" {
 				break
 			}
-			currentBody["page_token"] = lastPageToken
+			params["page_token"] = lastPageToken
 		}
 
 		tasklists := make([]map[string]interface{}, 0, len(rawItems))
@@ -170,9 +172,6 @@ func buildTasklistSearchBody(runtime *common.RuntimeContext) (map[string]interfa
 	if len(filter) > 0 {
 		body["filter"] = filter
 	}
-	if pageToken := runtime.Str("page-token"); pageToken != "" {
-		body["page_token"] = pageToken
-	}
 	return body, nil
 }
 

shortcuts/task/task_tasklist_search_test.go

@@ -33,8 +33,8 @@ func TestBuildTasklistSearchBody(t *testing.T) {
 			check: func(t *testing.T, body map[string]interface{}) {
 				filter := body["filter"].(map[string]interface{})
 				createTime := filter["create_time"].(map[string]interface{})
-				if body["page_token"] != "pt_tl" {
-					t.Fatalf("unexpected body: %#v", body)
+				if _, present := body["page_token"]; present {
+					t.Fatalf("body unexpectedly contains page_token: %#v", body)
 				}
 				if filter["user_id"].([]string)[0] != "ou_creator" {
 					t.Fatalf("unexpected filter: %#v", filter)
@@ -80,9 +80,10 @@ func TestBuildTasklistSearchBody(t *testing.T) {
 
 func TestSearchTasklist_DryRun(t *testing.T) {
 	tests := []struct {
-		name      string
-		setup     func(*cobra.Command)
-		wantParts []string
+		name          string
+		setup         func(*cobra.Command)
+		wantPageToken string
+		wantParts     []string
 	}{
 		{
 			name: "valid dry run",
@@ -90,7 +91,8 @@ func TestSearchTasklist_DryRun(t *testing.T) {
 				_ = cmd.Flags().Set("query", "Q2")
 				_ = cmd.Flags().Set("page-token", "pt_tl")
 			},
-			wantParts: []string{"POST /open-apis/task/v2/tasklists/search", `"query":"Q2"`},
+			wantPageToken: "pt_tl",
+			wantParts:     []string{`"query":"Q2"`},
 		},
 		{
 			name: "dry run error on invalid create time",
@@ -116,7 +118,11 @@ func TestSearchTasklist_DryRun(t *testing.T) {
 					t.Fatalf("Validate() error = %v", err)
 				}
 			}
-			out := SearchTasklist.DryRun(nil, runtime).Format()
+			preview := SearchTasklist.DryRun(nil, runtime)
+			if tt.wantPageToken != "" {
+				assertSearchDryRunPageToken(t, preview, tt.wantPageToken)
+			}
+			out := preview.Format()
 			for _, want := range tt.wantParts {
 				if !strings.Contains(out, want) {
 					t.Fatalf("dry run output missing %q: %s", want, out)

shortcuts/task/task_update.go

@@ -27,27 +27,42 @@ var UpdateTask = common.Shortcut{
 	HasFormat:   true,
 
 	Flags: []common.Flag{
-		{Name: "task-id", Desc: "task id (comma-separated for multiple)", Required: true},
+		{Name: "task-id", Desc: "task GUID or task applink URL (comma-separated for multiple)", Required: true},
 		{Name: "summary", Desc: "task title"},
 		{Name: "description", Desc: "task description"},
 		{Name: "due", Desc: "due date (ISO 8601 / date:YYYY-MM-DD / relative:+2d / ms timestamp)"},
 		{Name: "data", Desc: "JSON payload for task object"},
 	},
 
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := parseTaskGUIDs(runtime.Str("task-id"))
+		return err
+	},
+
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		body, err := buildTaskUpdateBody(runtime)
 		if err != nil {
 			return common.NewDryRunAPI().Set("error", err.Error())
 		}
-		taskIds := strings.Split(runtime.Str("task-id"), ",")
-		taskId := url.PathEscape(strings.TrimSpace(taskIds[0]))
-		return common.NewDryRunAPI().
-			PATCH("/open-apis/task/v2/tasks/" + taskId).
-			Params(map[string]interface{}{"user_id_type": "open_id"}).
-			Body(body)
+		taskIDs, err := parseTaskGUIDs(runtime.Str("task-id"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		preview := common.NewDryRunAPI()
+		for _, taskID := range taskIDs {
+			preview.PATCH("/open-apis/task/v2/tasks/" + url.PathEscape(taskID)).
+				Params(map[string]interface{}{"user_id_type": "open_id"}).
+				Body(body)
+		}
+		return preview
 	},
 
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		taskIDs, err := parseTaskGUIDs(runtime.Str("task-id"))
+		if err != nil {
+			return err
+		}
+
 		body, err := buildTaskUpdateBody(runtime)
 		if err != nil {
 			// buildTaskUpdateBody already returns a typed validation error;
@@ -55,17 +70,11 @@ var UpdateTask = common.Shortcut{
 			return err
 		}
 
-		taskIds := strings.Split(runtime.Str("task-id"), ",")
 		var updatedTasks []map[string]interface{}
 
-		for _, taskId := range taskIds {
-			taskId = strings.TrimSpace(taskId)
-			if taskId == "" {
-				continue
-			}
-
+		for _, taskID := range taskIDs {
 			params := map[string]interface{}{"user_id_type": "open_id"}
-			data, err := callTaskAPITyped(runtime, http.MethodPatch, "/open-apis/task/v2/tasks/"+url.PathEscape(taskId), params, body)
+			data, err := callTaskAPITyped(runtime, http.MethodPatch, "/open-apis/task/v2/tasks/"+url.PathEscape(taskID), params, body)
 			if err != nil {
 				return err
 			}
@@ -76,19 +85,28 @@ var UpdateTask = common.Shortcut{
 			}
 		}
 
+		updateFields, _ := body["update_fields"].([]string)
 		var tasks []map[string]interface{}
 		for _, task := range updatedTasks {
 			guid, _ := task["guid"].(string)
 			urlVal, _ := task["url"].(string)
 			urlVal = truncateTaskURL(urlVal)
+			confirmed := make(map[string]interface{})
+			for _, field := range updateFields {
+				if value, ok := task[field]; ok {
+					confirmed[field] = value
+				}
+			}
 			tasks = append(tasks, map[string]interface{}{
-				"guid": guid,
-				"url":  urlVal,
+				"guid":      guid,
+				"url":       urlVal,
+				"confirmed": confirmed,
 			})
 		}
 		// Standardized write output: return resource identifiers
 		outData := map[string]interface{}{
-			"tasks": tasks,
+			"updated_fields": updateFields,
+			"tasks":          tasks,
 		}
 
 		runtime.OutFormat(outData, &output.Meta{Count: len(updatedTasks)}, func(w io.Writer) {
@@ -112,6 +130,26 @@ var UpdateTask = common.Shortcut{
 	},
 }
 
+func parseTaskGUIDs(input string) ([]string, error) {
+	parts := strings.Split(input, ",")
+	taskGUIDs := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if strings.TrimSpace(part) == "" {
+			continue
+		}
+		guid, err := parseTaskGUID(part)
+		if err != nil {
+			return nil, err
+		}
+		taskGUIDs = append(taskGUIDs, guid)
+	}
+	if len(taskGUIDs) == 0 {
+		_, err := parseTaskGUID("")
+		return nil, err
+	}
+	return taskGUIDs, nil
+}
+
 func buildTaskUpdateBody(runtime *common.RuntimeContext) (map[string]interface{}, error) {
 	taskObj := make(map[string]interface{})
 	var updateFields []string

shortcuts/task/task_update_test.go

@@ -0,0 +1,201 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package task
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+func TestParseTaskGUIDs(t *testing.T) {
+	got, err := parseTaskGUIDs(" task-guid-1, https://applink.larksuite.com/client/todo/detail?guid=task-guid-2 ")
+	if err != nil {
+		t.Fatalf("parseTaskGUIDs() error = %v", err)
+	}
+	want := []string{"task-guid-1", "task-guid-2"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("parseTaskGUIDs() = %v, want %v", got, want)
+	}
+
+	_, err = parseTaskGUIDs("task-guid-1,t12345")
+	if err == nil {
+		t.Fatal("parseTaskGUIDs() error = nil, want invalid display-number error")
+	}
+}
+
+func TestTaskUpdateDryRunPreviewsEveryTaskID(t *testing.T) {
+	cmd := &cobra.Command{}
+	cmd.Flags().String("task-id", "task-guid-1,https://applink.larksuite.com/client/todo/detail?guid=task-guid-2", "")
+	cmd.Flags().String("summary", "updated", "")
+	cmd.Flags().String("description", "", "")
+	cmd.Flags().String("due", "", "")
+	cmd.Flags().String("data", "", "")
+
+	preview := UpdateTask.DryRun(context.Background(), &common.RuntimeContext{Cmd: cmd})
+	payload, err := json.Marshal(preview)
+	if err != nil {
+		t.Fatalf("marshal dry-run preview: %v", err)
+	}
+
+	var got struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+			Body   map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(payload, &got); err != nil {
+		t.Fatalf("decode dry-run preview: %v", err)
+	}
+	if len(got.API) != 2 {
+		t.Fatalf("dry-run API calls = %d, want 2; payload: %s", len(got.API), payload)
+	}
+
+	wantURLs := []string{
+		"/open-apis/task/v2/tasks/task-guid-1",
+		"/open-apis/task/v2/tasks/task-guid-2",
+	}
+	for i, call := range got.API {
+		if call.Method != "PATCH" {
+			t.Errorf("api[%d].method = %q, want PATCH", i, call.Method)
+		}
+		if call.URL != wantURLs[i] {
+			t.Errorf("api[%d].url = %q, want %q", i, call.URL, wantURLs[i])
+		}
+		if !reflect.DeepEqual(call.Params, map[string]interface{}{"user_id_type": "open_id"}) {
+			t.Errorf("api[%d].params = %#v", i, call.Params)
+		}
+		if !reflect.DeepEqual(call.Body, got.API[0].Body) {
+			t.Errorf("api[%d].body = %#v, want same body as first call %#v", i, call.Body, got.API[0].Body)
+		}
+	}
+}
+
+func TestTaskUpdateNormalizesAllIDsAndReturnsConfirmedFields(t *testing.T) {
+	f, stdout, _, reg := taskShortcutTestFactory(t)
+	warmTenantToken(t, f, reg)
+
+	first := &httpmock.Stub{
+		Method: "PATCH",
+		URL:    "/open-apis/task/v2/tasks/task-guid-1",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"task": map[string]interface{}{
+					"guid":        "task-guid-1",
+					"url":         "https://example.com/task-guid-1",
+					"summary":     "server summary one",
+					"description": "server description one",
+				},
+			},
+		},
+	}
+	second := &httpmock.Stub{
+		Method: "PATCH",
+		URL:    "/open-apis/task/v2/tasks/task-guid-2",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"task": map[string]interface{}{
+					"guid":    "task-guid-2",
+					"url":     "https://example.com/task-guid-2",
+					"summary": "server summary two",
+				},
+			},
+		},
+	}
+	reg.Register(first)
+	reg.Register(second)
+
+	err := runMountedTaskShortcut(t, UpdateTask, []string{
+		"+update",
+		"--task-id", "task-guid-1,https://applink.larksuite.com/client/todo/detail?guid=task-guid-2",
+		"--summary", "requested summary",
+		"--description", "requested description",
+		"--format", "json",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("UpdateTask error = %v", err)
+	}
+	reg.Verify(t)
+
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode output: %v\n%s", err, stdout.String())
+	}
+	data, ok := envelope["data"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("data = %#v, want object", envelope["data"])
+	}
+	if got := stringSlice(data["updated_fields"]); !reflect.DeepEqual(got, []string{"summary", "description"}) {
+		t.Fatalf("updated_fields = %v, want [summary description]", got)
+	}
+
+	tasks, ok := data["tasks"].([]interface{})
+	if !ok || len(tasks) != 2 {
+		t.Fatalf("tasks = %#v, want two tasks", data["tasks"])
+	}
+	firstTask := tasks[0].(map[string]interface{})
+	if firstTask["guid"] != "task-guid-1" || firstTask["url"] != "https://example.com/task-guid-1" {
+		t.Fatalf("first task identifiers = %#v", firstTask)
+	}
+	if got := firstTask["confirmed"]; !reflect.DeepEqual(got, map[string]interface{}{
+		"summary": "server summary one", "description": "server description one",
+	}) {
+		t.Fatalf("first confirmed = %#v", got)
+	}
+
+	secondTask := tasks[1].(map[string]interface{})
+	if got := secondTask["confirmed"]; !reflect.DeepEqual(got, map[string]interface{}{
+		"summary": "server summary two",
+	}) {
+		t.Fatalf("second confirmed = %#v; omitted server fields must not be echoed from the request", got)
+	}
+}
+
+func TestTaskUpdateValidatesEveryIDBeforeFirstWrite(t *testing.T) {
+	f, stdout, _, reg := taskShortcutTestFactory(t)
+	warmTenantToken(t, f, reg)
+
+	err := runMountedTaskShortcut(t, UpdateTask, []string{
+		"+update",
+		"--task-id", "task-guid-1,t12345",
+		"--summary", "must not be written",
+		"--format", "json",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("UpdateTask error = nil, want invalid task ID error")
+	}
+
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("error = %T %v, want typed invalid-argument error", err, err)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) || validationErr.Param != "--task-id" {
+		t.Fatalf("error param = %#v, want --task-id", validationErr)
+	}
+}
+
+func stringSlice(value interface{}) []string {
+	items, _ := value.([]interface{})
+	result := make([]string, 0, len(items))
+	for _, item := range items {
+		if str, ok := item.(string); ok {
+			result = append(result, str)
+		}
+	}
+	return result
+}

shortcuts/whiteboard/shortcuts.go

@@ -12,6 +12,7 @@ func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		WhiteboardUpdate,
 		WhiteboardUpdateOld,
+		WhiteboardExport,
 		WhiteboardQuery,
 	}
 }

shortcuts/whiteboard/whiteboard_export.go

@@ -0,0 +1,728 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+package whiteboard
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/shortcuts/common"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+)
+
+const (
+	// WhiteboardExportAsPreview exports a whiteboard preview image.
+	WhiteboardExportAsPreview = "preview"
+	// WhiteboardExportAsSvg exports a whiteboard as SVG.
+	WhiteboardExportAsSvg = "svg"
+	// WhiteboardExportAsSource exports Mermaid or PlantUML source extracted from the whiteboard.
+	WhiteboardExportAsSource = "source"
+	// WhiteboardExportAsRaw exports the raw whiteboard node payload.
+	WhiteboardExportAsRaw = "raw"
+
+	// Legacy output type names accepted for backward compatibility.
+	WhiteboardQueryAsImage = "image"
+	// WhiteboardQueryAsSvg is deprecated; use WhiteboardExportAsSvg.
+	WhiteboardQueryAsSvg  = WhiteboardExportAsSvg
+	WhiteboardQueryAsCode = "code"
+	// WhiteboardQueryAsRaw is deprecated; use WhiteboardExportAsRaw.
+	WhiteboardQueryAsRaw = WhiteboardExportAsRaw
+)
+
+// SyntaxType identifies the diagram syntax extracted from whiteboard code blocks.
+type SyntaxType int
+
+const (
+	// SyntaxTypePlantUML marks PlantUML code blocks.
+	SyntaxTypePlantUML SyntaxType = 1
+	// SyntaxTypeMermaid marks Mermaid code blocks.
+	SyntaxTypeMermaid SyntaxType = 2
+)
+
+// SyntaxTypeNameMap maps whiteboard syntax types to their CLI output names.
+var SyntaxTypeNameMap = map[SyntaxType]string{
+	SyntaxTypePlantUML: "plantuml",
+	SyntaxTypeMermaid:  "mermaid",
+}
+
+// SyntaxTypeExtensionMap maps whiteboard syntax types to their default file extensions.
+var SyntaxTypeExtensionMap = map[SyntaxType]string{
+	SyntaxTypePlantUML: ".puml",
+	SyntaxTypeMermaid:  ".mmd",
+}
+
+// String returns the CLI-facing name for the syntax type.
+func (s SyntaxType) String() string {
+	return SyntaxTypeNameMap[s]
+}
+
+// ExtensionName returns the default file extension for the syntax type.
+func (s SyntaxType) ExtensionName() string {
+	return SyntaxTypeExtensionMap[s]
+}
+
+// IsValid reports whether the syntax type is one of the supported whiteboard code syntaxes.
+func (s SyntaxType) IsValid() bool {
+	return s == SyntaxTypePlantUML || s == SyntaxTypeMermaid
+}
+
+var wbExportScopes = []string{"board:whiteboard:node:read"}
+var wbExportAuthTypes = []string{"user", "bot"}
+var wbExportFlags = []common.Flag{
+	{Name: "whiteboard-token", Desc: "whiteboard token of the whiteboard. You will need read permission to download preview image.", Required: true},
+	{Name: "output-type", Desc: "output whiteboard as: preview | svg | source | raw.", Required: true, Enum: []string{"preview", "svg", "source", "raw"}},
+	{Name: "output", Desc: "output path. It is required when --output-type preview. If not specified when --output-type svg/source/raw, it will output directly.", Required: false},
+	{Name: "overwrite", Desc: "overwrite existing file if it exists", Required: false, Type: "bool"},
+}
+
+var wbQueryFlags = []common.Flag{
+	{Name: "whiteboard-token", Desc: "whiteboard token of the whiteboard. You will need read permission to download preview image.", Required: true},
+	{Name: "output_as", Desc: "output whiteboard as: image | svg | code | raw.", Required: true, Enum: []string{"image", "svg", "code", "raw"}},
+	{Name: "output", Desc: "output path. It is required when output as image. If not specified when --output_as svg/code/raw, it will output directly.", Required: false},
+	{Name: "overwrite", Desc: "overwrite existing file if it exists", Required: false, Type: "bool"},
+}
+
+func wbExportOutputType(runtime *common.RuntimeContext) (string, string) {
+	normalized, ok := normalizeWhiteboardExportOutputType(runtime.Str("output-type"))
+	if !ok {
+		return "", "--output-type"
+	}
+	return normalized, "--output-type"
+}
+
+func wbQueryOutputType(runtime *common.RuntimeContext) (string, string) {
+	normalized, ok := normalizeLegacyWhiteboardExportOutputType(runtime.Str("output_as"))
+	if !ok {
+		return "", "--output_as"
+	}
+	return normalized, "--output_as"
+}
+
+func normalizeWhiteboardExportOutputType(outputType string) (string, bool) {
+	switch outputType {
+	case WhiteboardExportAsPreview:
+		return WhiteboardExportAsPreview, true
+	case WhiteboardExportAsSvg:
+		return WhiteboardExportAsSvg, true
+	case WhiteboardExportAsSource:
+		return WhiteboardExportAsSource, true
+	case WhiteboardExportAsRaw:
+		return WhiteboardExportAsRaw, true
+	default:
+		return "", false
+	}
+}
+
+func normalizeLegacyWhiteboardExportOutputType(outputType string) (string, bool) {
+	switch outputType {
+	case WhiteboardQueryAsImage:
+		return WhiteboardExportAsPreview, true
+	case WhiteboardQueryAsCode:
+		return WhiteboardExportAsSource, true
+	default:
+		return normalizeWhiteboardExportOutputType(outputType)
+	}
+}
+
+func wbExportOutputTypeError(param string) *errs.ValidationError {
+	if param == "--output_as" {
+		return errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--output_as flag must be one of: image | svg | code | raw",
+		).WithParam("--output_as")
+	}
+	return errs.NewValidationError(
+		errs.SubtypeInvalidArgument,
+		"--output-type flag must be one of: preview | svg | source | raw",
+	).WithParam("--output-type")
+}
+
+func wbExportValidate(ctx context.Context, runtime *common.RuntimeContext) error {
+	return wbExportValidateWithOutputType(ctx, runtime, wbExportOutputType)
+}
+
+func wbQueryValidate(ctx context.Context, runtime *common.RuntimeContext) error {
+	return wbExportValidateWithOutputType(ctx, runtime, wbQueryOutputType)
+}
+
+func wbExportValidateWithOutputType(ctx context.Context, runtime *common.RuntimeContext, outputTypeFn func(*common.RuntimeContext) (string, string)) error {
+	// Check if token contains control characters
+	token := runtime.Str("whiteboard-token")
+	if err := common.RejectDangerousCharsTyped("--whiteboard-token", token); err != nil {
+		return err
+	}
+	outputType, outputTypeParam := outputTypeFn(runtime)
+	if outputType == "" {
+		return wbExportOutputTypeError(outputTypeParam)
+	}
+
+	out := runtime.Str("output")
+	if out != "" {
+		if _, err := runtime.ResolveSavePath(out); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid output path: %s", err).WithParam("--output").WithCause(err)
+		}
+	}
+	if out == "" && outputType == WhiteboardExportAsPreview {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "need a output path to export whiteboard as preview").WithParam("--output")
+	}
+	return nil
+}
+
+func wbExportDryRun(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	return wbExportDryRunWithOutputType(ctx, runtime, wbExportOutputType)
+}
+
+func wbQueryDryRun(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	return wbExportDryRunWithOutputType(ctx, runtime, wbQueryOutputType)
+}
+
+func wbExportDryRunWithOutputType(ctx context.Context, runtime *common.RuntimeContext, outputTypeFn func(*common.RuntimeContext) (string, string)) *common.DryRunAPI {
+	outputType, outputTypeParam := outputTypeFn(runtime)
+	token := runtime.Str("whiteboard-token")
+	switch outputType {
+	case WhiteboardExportAsPreview:
+		return common.NewDryRunAPI().
+			GET(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/download_as_image", common.MaskToken(url.PathEscape(token)))).
+			Desc("Export preview image of given whiteboard")
+	case WhiteboardExportAsSource:
+		return common.NewDryRunAPI().
+			GET(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", common.MaskToken(url.PathEscape(token)))).
+			Desc("Extract Mermaid/Plantuml source from given whiteboard")
+	case WhiteboardExportAsRaw:
+		return common.NewDryRunAPI().
+			GET(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", common.MaskToken(url.PathEscape(token)))).
+			Desc("Extract raw nodes structure from given whiteboard")
+	case WhiteboardExportAsSvg:
+		return common.NewDryRunAPI().
+			POST(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/export", common.MaskToken(url.PathEscape(token)))).
+			Body(map[string]string{"export_type": "svg"}).
+			Desc("Export SVG of given whiteboard")
+	default:
+		if outputTypeParam == "--output_as" {
+			return common.NewDryRunAPI().Desc("invalid --output_as flag, must be one of: image | svg | code | raw")
+		}
+		return common.NewDryRunAPI().Desc("invalid --output-type flag, must be one of: preview | svg | source | raw")
+	}
+}
+
+func wbExportExecute(ctx context.Context, runtime *common.RuntimeContext) error {
+	return wbExportExecuteWithOutputType(ctx, runtime, wbExportOutputType)
+}
+
+func wbQueryExecute(ctx context.Context, runtime *common.RuntimeContext) error {
+	return wbExportExecuteWithOutputType(ctx, runtime, wbQueryOutputType)
+}
+
+func wbExportExecuteWithOutputType(ctx context.Context, runtime *common.RuntimeContext, outputTypeFn func(*common.RuntimeContext) (string, string)) error {
+	token := runtime.Str("whiteboard-token")
+	outDir := runtime.Str("output")
+	outputType, outputTypeParam := outputTypeFn(runtime)
+	switch outputType {
+	case WhiteboardExportAsPreview:
+		return exportWhiteboardPreview(ctx, runtime, token, outDir)
+	case WhiteboardExportAsSvg:
+		return exportWhiteboardSvg(runtime, token, outDir)
+	case WhiteboardExportAsSource:
+		return exportWhiteboardCode(runtime, token, outDir)
+	case WhiteboardExportAsRaw:
+		return exportWhiteboardRaw(runtime, token, outDir)
+	default:
+		return wbExportOutputTypeError(outputTypeParam)
+	}
+}
+
+const WhiteboardExportDescription = "Export an existing whiteboard as preview image, SVG, source code or raw nodes structure."
+
+// WhiteboardExport registers the `whiteboard +export` shortcut.
+var WhiteboardExport = common.Shortcut{
+	Service:     "whiteboard",
+	Command:     "+export",
+	Description: WhiteboardExportDescription,
+	Risk:        "read",
+	Scopes:      wbExportScopes,
+	AuthTypes:   wbExportAuthTypes,
+	Flags:       wbExportFlags,
+	HasFormat:   true,
+	Validate:    wbExportValidate,
+	DryRun:      wbExportDryRun,
+	Execute:     wbExportExecute,
+}
+
+// WhiteboardQuery registers the hidden, backward-compatible `whiteboard +query` shortcut.
+var WhiteboardQuery = common.Shortcut{
+	Service:     "whiteboard",
+	Command:     "+query",
+	Description: WhiteboardExportDescription,
+	Risk:        "read",
+	Scopes:      wbExportScopes,
+	AuthTypes:   wbExportAuthTypes,
+	Flags:       wbQueryFlags,
+	HasFormat:   true,
+	Hidden:      true,
+	Validate:    wbQueryValidate,
+	DryRun:      wbQueryDryRun,
+	Execute:     wbQueryExecute,
+}
+
+// exportReq defines the request body for whiteboard export APIs.
+type exportReq struct {
+	ExportType string `json:"export_type"`
+}
+
+// exportResp models the whiteboard export response envelope.
+type exportResp struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+	Data struct {
+		Content  string `json:"content"`
+		MimeType string `json:"mime_type"`
+	} `json:"data"`
+}
+
+// exportWhiteboardSvg exports a whiteboard as SVG and writes it to stdout or a file.
+func exportWhiteboardSvg(runtime *common.RuntimeContext, wbToken, outDir string) error {
+	reqBody := exportReq{ExportType: "svg"}
+	req := &larkcore.ApiReq{
+		HttpMethod: http.MethodPost,
+		ApiPath:    fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/export", url.PathEscape(wbToken)),
+		Body:       reqBody,
+	}
+
+	resp, err := runtime.DoAPI(req)
+	if err != nil {
+		return wrapWbNetworkErr(err, "export whiteboard svg failed: %v", err)
+	}
+
+	var exportData exportResp
+	if err := json.Unmarshal(resp.RawBody, &exportData); err == nil {
+		if exportData.Code != 0 {
+			subtype := errs.SubtypeUnknown
+			if resp.StatusCode == http.StatusNotFound {
+				subtype = errs.SubtypeNotFound
+			}
+			return errs.NewAPIError(subtype, "export whiteboard svg failed: %s", exportData.Msg).WithCode(exportData.Code)
+		}
+	} else if resp.StatusCode == http.StatusOK {
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "parse export response failed: %v", err).WithCause(err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		body := common.TruncateStr(strings.TrimSpace(string(resp.RawBody)), 500)
+		if resp.StatusCode >= 500 {
+			return errs.NewNetworkError(errs.SubtypeNetworkServer, "export whiteboard svg failed: HTTP %d: %s", resp.StatusCode, body).
+				WithCode(resp.StatusCode).
+				WithRetryable()
+		}
+		subtype := errs.SubtypeUnknown
+		if resp.StatusCode == http.StatusNotFound {
+			subtype = errs.SubtypeNotFound
+		}
+		return errs.NewAPIError(subtype, "export whiteboard svg failed: HTTP %d: %s", resp.StatusCode, body).
+			WithCode(resp.StatusCode)
+	}
+
+	svgBytes, err := base64.StdEncoding.DecodeString(exportData.Data.Content)
+	if err != nil {
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "decode svg base64 failed: %v", err).WithCause(err)
+	}
+
+	if outDir == "" {
+		runtime.OutFormat(map[string]interface{}{
+			"svg_content": string(svgBytes),
+		}, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "%s\n", string(svgBytes))
+		})
+		return nil
+	}
+
+	finalPath, size, err := saveOutputFile(outDir, ".svg", wbToken, runtime, bytes.NewReader(svgBytes))
+	if err != nil {
+		return err
+	}
+
+	runtime.OutFormat(map[string]interface{}{
+		"svg_path":   finalPath,
+		"size_bytes": size,
+	}, nil, func(w io.Writer) {
+		fmt.Fprintf(w, "SVG saved to %s\n", finalPath)
+		fmt.Fprintf(w, "File size: %d bytes", size)
+	})
+	return nil
+}
+
+func exportWhiteboardPreview(ctx context.Context, runtime *common.RuntimeContext, wbToken, outDir string) error {
+	req := &larkcore.ApiReq{
+		HttpMethod: http.MethodGet,
+		ApiPath:    fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/download_as_image", url.PathEscape(wbToken)),
+	}
+	// Execute API request. The preview endpoint streams raw image bytes (not a
+	// JSON envelope), so classify by HTTP status: 5xx is retryable network,
+	// while 4xx remains an API-side rejection.
+	resp, err := runtime.DoAPI(req, larkcore.WithFileDownload())
+	if err != nil {
+		return wrapWbNetworkErr(err, "get whiteboard preview failed: %v", err)
+	}
+	if resp.StatusCode >= 400 {
+		body := common.TruncateStr(strings.TrimSpace(string(resp.RawBody)), 500)
+		if resp.StatusCode >= 500 {
+			return errs.NewNetworkError(errs.SubtypeNetworkServer, "get whiteboard preview failed: HTTP %d: %s", resp.StatusCode, body).
+				WithCode(resp.StatusCode).
+				WithRetryable()
+		}
+		subtype := errs.SubtypeUnknown
+		if resp.StatusCode == http.StatusNotFound {
+			subtype = errs.SubtypeNotFound
+		}
+		return errs.NewAPIError(subtype, "get whiteboard preview failed: HTTP %d: %s", resp.StatusCode, body).
+			WithCode(resp.StatusCode)
+	}
+
+	finalPath, size, err := saveWhiteboardPreviewOutput(outDir, wbToken, runtime, resp.Header, bytes.NewReader(resp.RawBody))
+	if err != nil {
+		return err
+	}
+
+	runtime.OutFormat(map[string]interface{}{
+		"preview_image_path": finalPath,
+		"size_bytes":         size,
+	}, nil, func(w io.Writer) {
+		fmt.Fprintf(w, "Preview image saved to %s\n", finalPath)
+		fmt.Fprintf(w, "Image size: %d bytes", size)
+	})
+	return nil
+}
+
+type wbNodesResp struct {
+	Data struct {
+		Nodes []interface{} `json:"nodes"`
+	} `json:"data"`
+}
+
+func fetchWhiteboardNodes(runtime *common.RuntimeContext, wbToken string) (*wbNodesResp, error) {
+	data, err := runtime.CallAPITyped(http.MethodGet, fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", url.PathEscape(wbToken)), nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	var nodes wbNodesResp
+	rawNodes, _ := data["nodes"]
+	if rawNodes != nil {
+		var ok bool
+		nodes.Data.Nodes, ok = rawNodes.([]interface{})
+		if !ok {
+			return nil, wbInvalidResponse("get whiteboard nodes failed: data.nodes must be an array")
+		}
+	}
+	return &nodes, nil
+}
+
+type syntaxInfo struct {
+	code       string
+	syntaxType SyntaxType
+}
+
+func exportWhiteboardCode(runtime *common.RuntimeContext, wbToken, outDir string) error {
+	wbNodes, err := fetchWhiteboardNodes(runtime, wbToken)
+	if err != nil {
+		return err
+	}
+	if wbNodes == nil || wbNodes.Data.Nodes == nil {
+		runtime.OutFormat(map[string]interface{}{
+			"msg": "whiteboard is empty",
+		}, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Whiteboard is empty\n")
+		})
+		return nil
+	}
+
+	var syntaxBlocks []syntaxInfo
+	for _, node := range wbNodes.Data.Nodes {
+		nodeMap, ok := node.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		syntax, ok := nodeMap["syntax"]
+		if !ok {
+			continue
+		}
+		syntaxMap, ok := syntax.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		code, _ := syntaxMap["code"].(string)
+		var syntaxType SyntaxType
+		switch v := syntaxMap["syntax_type"].(type) {
+		case json.Number:
+			// runtime.ClassifyAPIResponse decodes the response with UseNumber,
+			// so numeric fields arrive as json.Number rather than float64.
+			if n, err := v.Int64(); err == nil {
+				syntaxType = SyntaxType(n)
+			}
+		case float64:
+			syntaxType = SyntaxType(v)
+		case SyntaxType:
+			syntaxType = v
+		}
+		if code != "" && syntaxType.IsValid() {
+			syntaxBlocks = append(syntaxBlocks, syntaxInfo{code: code, syntaxType: syntaxType})
+		}
+	}
+
+	if len(syntaxBlocks) == 0 {
+		runtime.OutFormat(map[string]interface{}{
+			"msg": "no code blocks found in whiteboard",
+		}, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "No code blocks found in whiteboard\n")
+		})
+		return nil
+	}
+	// 目前的标准操作是导出到单一文件，和 Doc 展示画板代码块采用相同的逻辑
+	// 如果有需求，可以调整到导出到多个文件的模式
+	if len(syntaxBlocks) > 1 {
+		runtime.OutFormat(map[string]interface{}{
+			"msg": "multiple code blocks found, cannot export directly",
+		}, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Multiple code blocks found, cannot export directly\n")
+		})
+		return nil
+	}
+	block := syntaxBlocks[0]
+
+	if outDir == "" {
+		runtime.OutFormat(map[string]interface{}{
+			"code":        block.code,
+			"syntax_type": block.syntaxType.String(),
+		}, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "%s\n", block.code)
+		})
+		return nil
+	}
+
+	finalPath, _, err := saveOutputFile(outDir, block.syntaxType.ExtensionName(), wbToken, runtime, strings.NewReader(block.code))
+	if err != nil {
+		return err
+	}
+
+	runtime.OutFormat(map[string]interface{}{
+		"output_path": finalPath,
+	}, nil, func(w io.Writer) {
+		fmt.Fprintf(w, "Whiteboard code saved to %s\n", finalPath)
+	})
+
+	return nil
+}
+
+func exportWhiteboardRaw(runtime *common.RuntimeContext, wbToken, outDir string) error {
+	wbNodes, err := fetchWhiteboardNodes(runtime, wbToken)
+	if err != nil {
+		return err
+	}
+	if wbNodes == nil || wbNodes.Data.Nodes == nil {
+		runtime.OutFormat(map[string]interface{}{
+			"msg": "whiteboard is empty",
+		}, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Whiteboard is empty\n")
+		})
+		return nil
+	}
+
+	jsonData, err := json.MarshalIndent(wbNodes.Data, "", "  ")
+	if err != nil {
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "cannot marshal whiteboard data: %s", err).WithCause(err)
+	}
+
+	if outDir == "" {
+		runtime.OutFormat(wbNodes.Data, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "%s\n", string(jsonData))
+		})
+		return nil
+	}
+
+	finalPath, _, err := saveOutputFile(outDir, ".json", wbToken, runtime, bytes.NewReader(jsonData))
+	if err != nil {
+		return err
+	}
+
+	runtime.OutFormat(map[string]interface{}{
+		"output_path": finalPath,
+	}, nil, func(w io.Writer) {
+		fmt.Fprintf(w, "Whiteboard raw node structure saved to %s\n", finalPath)
+	})
+
+	return nil
+}
+
+func saveOutputFile(outPath, ext, token string, runtime *common.RuntimeContext, data io.Reader) (string, int64, error) {
+	// Step 1: Get final output path
+	info, err := runtime.FileIO().Stat(outPath)
+	var finalPath string
+	if err == nil && info.IsDir() {
+		finalPath = filepath.Join(outPath, fmt.Sprintf("whiteboard_%s%s", token, ext))
+	} else {
+		// Fix extension in path
+		currentExt := filepath.Ext(outPath)
+		if currentExt != ext {
+			if currentExt != "" {
+				outPath = outPath[:len(outPath)-len(currentExt)]
+			}
+			outPath += ext
+		}
+		finalPath = outPath
+	}
+	if _, err := runtime.ResolveSavePath(finalPath); err != nil { // double check
+		return "", 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid output path: %s", err).WithParam("--output").WithCause(err)
+	}
+
+	// Step 2: Check overwrite
+	_, err = runtime.FileIO().Stat(finalPath)
+	if err == nil {
+		if !runtime.Bool("overwrite") {
+			return "", 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "file already exists: %s (use --overwrite to overwrite)", finalPath).WithParam("--overwrite")
+		}
+	} else if !os.IsNotExist(err) {
+		return "", 0, errs.NewInternalError(errs.SubtypeFileIO, "cannot check file existence: %s", err).WithCause(err)
+	}
+
+	// Step 3: Save file
+	var contentType string
+	switch ext {
+	case ".png":
+		contentType = "image/png"
+	case ".jpg", ".jpeg":
+		contentType = "image/jpeg"
+	case ".svg":
+		contentType = "image/svg+xml"
+	case ".json":
+		contentType = "application/json"
+	case ".mmd", ".puml":
+		contentType = "text/plain"
+	}
+
+	savResult, err := runtime.FileIO().Save(finalPath, fileio.SaveOptions{
+		ContentType: contentType,
+	}, data)
+	if err != nil {
+		return "", 0, wbSaveError(err)
+	}
+
+	return finalPath, savResult.Size(), nil
+}
+
+var whiteboardPreviewContentTypeExt = map[string]string{
+	"image/jpeg": ".jpg",
+	"image/png":  ".png",
+}
+
+func saveWhiteboardPreviewOutput(outPath, token string, runtime *common.RuntimeContext, header http.Header, data io.Reader) (string, int64, error) {
+	contentType := header.Get("Content-Type")
+	ext, err := whiteboardPreviewExtFromContentType(contentType)
+	if err != nil {
+		return "", 0, err
+	}
+	finalPath, err := whiteboardPreviewOutputPath(outPath, ext, token, runtime)
+	if err != nil {
+		return "", 0, err
+	}
+	return saveResolvedOutputFile(finalPath, contentType, runtime, data)
+}
+
+func whiteboardPreviewExtFromContentType(contentType string) (string, error) {
+	mediaType, _, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		mediaType = strings.TrimSpace(strings.Split(contentType, ";")[0])
+	}
+	if ext, ok := whiteboardPreviewContentTypeExt[strings.ToLower(mediaType)]; ok {
+		return ext, nil
+	}
+	if strings.TrimSpace(contentType) == "" {
+		contentType = "<empty>"
+	}
+	return "", errs.NewInternalError(
+		errs.SubtypeInvalidResponse,
+		"get whiteboard preview failed: expected image/png or image/jpeg response, got Content-Type: %s",
+		contentType,
+	)
+}
+
+func whiteboardPreviewOutputPath(outPath, ext, token string, runtime *common.RuntimeContext) (string, error) {
+	info, err := runtime.FileIO().Stat(outPath)
+	if err == nil && info.IsDir() {
+		finalPath := filepath.Join(outPath, fmt.Sprintf("whiteboard_%s%s", token, ext))
+		if _, err := runtime.ResolveSavePath(finalPath); err != nil {
+			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid output path: %s", err).WithParam("--output").WithCause(err)
+		}
+		return finalPath, nil
+	}
+	if err != nil && !os.IsNotExist(err) {
+		return "", errs.NewInternalError(errs.SubtypeFileIO, "cannot check output path: %s", err).WithCause(err)
+	}
+
+	currentExt := strings.ToLower(filepath.Ext(outPath))
+	if currentExt == "" || currentExt == "." {
+		finalPath := strings.TrimSuffix(outPath, ".") + ext
+		if _, err := runtime.ResolveSavePath(finalPath); err != nil {
+			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid output path: %s", err).WithParam("--output").WithCause(err)
+		}
+		return finalPath, nil
+	}
+	if !isWhiteboardPreviewImageExt(currentExt) {
+		return "", errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"invalid preview output extension %q; use .png, .jpg, .jpeg, a directory, or a path without extension",
+			currentExt,
+		).WithParam("--output")
+	}
+	if !whiteboardPreviewExtMatches(currentExt, ext) {
+		return "", errs.NewValidationError(
+			errs.SubtypeFailedPrecondition,
+			"preview response is %s but output path has extension %s; use a matching extension or omit the extension",
+			ext,
+			currentExt,
+		).WithParam("--output")
+	}
+	if _, err := runtime.ResolveSavePath(outPath); err != nil {
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid output path: %s", err).WithParam("--output").WithCause(err)
+	}
+	return outPath, nil
+}
+
+func isWhiteboardPreviewImageExt(ext string) bool {
+	return ext == ".png" || ext == ".jpg" || ext == ".jpeg"
+}
+
+func whiteboardPreviewExtMatches(outputExt, responseExt string) bool {
+	if responseExt == ".jpg" {
+		return outputExt == ".jpg" || outputExt == ".jpeg"
+	}
+	return outputExt == responseExt
+}
+
+func saveResolvedOutputFile(finalPath, contentType string, runtime *common.RuntimeContext, data io.Reader) (string, int64, error) {
+	_, err := runtime.FileIO().Stat(finalPath)
+	if err == nil {
+		if !runtime.Bool("overwrite") {
+			return "", 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "file already exists: %s (use --overwrite to overwrite)", finalPath).WithParam("--overwrite")
+		}
+	} else if !os.IsNotExist(err) {
+		return "", 0, errs.NewInternalError(errs.SubtypeFileIO, "cannot check file existence: %s", err).WithCause(err)
+	}
+
+	savResult, err := runtime.FileIO().Save(finalPath, fileio.SaveOptions{
+		ContentType: contentType,
+	}, data)
+	if err != nil {
+		return "", 0, wbSaveError(err)
+	}
+	return finalPath, savResult.Size(), nil
+}

shortcuts/whiteboard/whiteboard_export_test.go

@@ -9,6 +9,7 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"errors"
+	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
@@ -211,6 +212,73 @@ func TestWhiteboardQuery_Validate_TypedErrors(t *testing.T) {
 	}
 }
 
+// TestWhiteboardExport_Validate verifies the canonical +export flag spelling
+// and output type names while legacy +query validation remains covered above.
+func TestWhiteboardExport_Validate(t *testing.T) {
+	ctx := context.Background()
+	chdirTemp(t)
+
+	tests := []struct {
+		name      string
+		flags     map[string]string
+		wantErr   bool
+		wantParam string
+	}{
+		{
+			name: "valid: preview with output",
+			flags: map[string]string{
+				"whiteboard-token": "test-token-123",
+				"output-type":      "preview",
+				"output":           "output",
+			},
+		},
+		{
+			name: "valid: source without output",
+			flags: map[string]string{
+				"whiteboard-token": "test-token-123",
+				"output-type":      "source",
+			},
+		},
+		{
+			name: "invalid: preview without output",
+			flags: map[string]string{
+				"whiteboard-token": "test-token-123",
+				"output-type":      "preview",
+			},
+			wantErr:   true,
+			wantParam: "--output",
+		},
+		{
+			name: "invalid: bad output-type value",
+			flags: map[string]string{
+				"whiteboard-token": "test-token-123",
+				"output-type":      "image",
+			},
+			wantErr:   true,
+			wantParam: "--output-type",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := WhiteboardExport.Validate(ctx, newTestRuntime(tt.flags, nil))
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("WhiteboardExport.Validate() error = %v, wantErr %v", err, tt.wantErr)
+			}
+			if err == nil {
+				return
+			}
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("error is not *errs.ValidationError: %T", err)
+			}
+			if ve.Param != tt.wantParam {
+				t.Fatalf("Param = %q, want %q", ve.Param, tt.wantParam)
+			}
+		})
+	}
+}
+
 // TestExportWhiteboardPreview_HTTPError locks the download-path failure
 // behavior: a failed preview download surfaces as a typed errs.* envelope, not
 // a flat legacy error.
@@ -284,7 +352,7 @@ func TestWhiteboardQuery_DryRun(t *testing.T) {
 				"output":           "output.png",
 			},
 			wantMethod: "GET",
-			wantPath:   "/open-apis/board/v1/whiteboards/test-token-123/download_as_image",
+			wantPath:   "/open-apis/board/v1/whiteboards/test...-123/download_as_image",
 		},
 		{
 			name: "dry run code",
@@ -293,7 +361,7 @@ func TestWhiteboardQuery_DryRun(t *testing.T) {
 				"output_as":        "code",
 			},
 			wantMethod: "GET",
-			wantPath:   "/open-apis/board/v1/whiteboards/test-token-123/nodes",
+			wantPath:   "/open-apis/board/v1/whiteboards/test...-123/nodes",
 		},
 		{
 			name: "dry run raw",
@@ -302,7 +370,7 @@ func TestWhiteboardQuery_DryRun(t *testing.T) {
 				"output_as":        "raw",
 			},
 			wantMethod: "GET",
-			wantPath:   "/open-apis/board/v1/whiteboards/test-token-123/nodes",
+			wantPath:   "/open-apis/board/v1/whiteboards/test...-123/nodes",
 		},
 	}
 
@@ -313,6 +381,29 @@ func TestWhiteboardQuery_DryRun(t *testing.T) {
 			if dryRun == nil {
 				t.Fatalf("WhiteboardQuery.DryRun() returned nil")
 			}
+			var got struct {
+				API []struct {
+					Method string                 `json:"method"`
+					URL    string                 `json:"url"`
+					Body   map[string]interface{} `json:"body"`
+				} `json:"api"`
+			}
+			data, err := json.Marshal(dryRun)
+			if err != nil {
+				t.Fatalf("Marshal() error = %v", err)
+			}
+			if err := json.Unmarshal(data, &got); err != nil {
+				t.Fatalf("Unmarshal() error = %v; data=%s", err, string(data))
+			}
+			if len(got.API) != 1 {
+				t.Fatalf("api len = %d, want 1; data=%s", len(got.API), string(data))
+			}
+			if got.API[0].Method != tt.wantMethod {
+				t.Fatalf("method = %q, want %q; data=%s", got.API[0].Method, tt.wantMethod, string(data))
+			}
+			if got.API[0].URL != tt.wantPath {
+				t.Fatalf("url = %q, want %q; data=%s", got.API[0].URL, tt.wantPath, string(data))
+			}
 		})
 	}
 }
@@ -391,6 +482,32 @@ func TestWhiteboardQuery_ShortcutRegistration(t *testing.T) {
 	if len(WhiteboardQuery.Flags) == 0 {
 		t.Errorf("WhiteboardQuery.Flags is empty, expected at least one flag")
 	}
+	if !WhiteboardQuery.Hidden {
+		t.Errorf("WhiteboardQuery should be hidden because +export is the canonical command")
+	}
+
+	// Verify WhiteboardExport is the visible canonical shortcut.
+	if WhiteboardExport.Command != "+export" {
+		t.Errorf("WhiteboardExport.Command = %q, want \"+export\"", WhiteboardExport.Command)
+	}
+	if WhiteboardExport.Service != "whiteboard" {
+		t.Errorf("WhiteboardExport.Service = %q, want \"whiteboard\"", WhiteboardExport.Service)
+	}
+	if WhiteboardExport.Hidden {
+		t.Errorf("WhiteboardExport should be visible")
+	}
+	if flag := shortcutFlag(WhiteboardExport, "output_as"); flag != nil {
+		t.Errorf("WhiteboardExport --output_as should not be registered; got %#v", *flag)
+	}
+	if flag := shortcutFlag(WhiteboardExport, "output-type"); flag == nil || flag.Hidden {
+		t.Errorf("WhiteboardExport --output-type should exist and be visible")
+	}
+	if flag := shortcutFlag(WhiteboardQuery, "output_as"); flag == nil || flag.Hidden {
+		t.Errorf("WhiteboardQuery --output_as should exist and remain visible on the hidden legacy command")
+	}
+	if flag := shortcutFlag(WhiteboardQuery, "output-type"); flag != nil {
+		t.Errorf("WhiteboardQuery --output-type should not be registered; got %#v", *flag)
+	}
 }
 
 // TestSaveOutputFile verifies output saving, overwrite handling, and extension-specific paths.
@@ -862,10 +979,11 @@ func TestExportWhiteboardPreview(t *testing.T) {
 
 	// Mock download preview image API response with RawBody
 	reg.Register(&httpmock.Stub{
-		Method:  "GET",
-		URL:     "/open-apis/board/v1/whiteboards/test-token-preview/download_as_image",
-		Status:  200,
-		RawBody: []byte("fake PNG image data"),
+		Method:      "GET",
+		URL:         "/open-apis/board/v1/whiteboards/test-token-preview/download_as_image",
+		Status:      200,
+		RawBody:     []byte("fake PNG image data"),
+		ContentType: "image/png",
 	})
 
 	args := []string{"+query", "--whiteboard-token", "test-token-preview", "--output_as", "image", "--output", "output", "--overwrite"}
@@ -883,6 +1001,158 @@ func TestExportWhiteboardPreview(t *testing.T) {
 	}
 }
 
+// TestExportWhiteboardPreview_UsesContentTypeExtension verifies preview image
+// downloads are saved according to the API response Content-Type rather than a
+// hard-coded PNG suffix.
+func TestExportWhiteboardPreview_UsesContentTypeExtension(t *testing.T) {
+	factory, stdout, reg := newExecuteFactory(t)
+	chdirTemp(t)
+
+	reg.Register(&httpmock.Stub{
+		Method:      "GET",
+		URL:         "/open-apis/board/v1/whiteboards/test-token-preview-jpeg/download_as_image",
+		Status:      200,
+		RawBody:     []byte("fake JPEG image data"),
+		ContentType: "image/jpeg",
+	})
+
+	args := []string{"+export", "--whiteboard-token", "test-token-preview-jpeg", "--output-type", "preview", "--output", "output", "--overwrite"}
+	if err := runShortcut(t, WhiteboardExport, args, factory, stdout); err != nil {
+		t.Fatalf("err=%v", err)
+	}
+
+	if _, err := os.Stat("output.png"); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("output.png should not exist when response Content-Type is image/jpeg, stat err=%v", err)
+	}
+	data, err := os.ReadFile("output.jpg")
+	if err != nil {
+		t.Fatalf("ReadFile() error: %v", err)
+	}
+	if string(data) != "fake JPEG image data" {
+		t.Fatalf("image content = %q, want %q", string(data), "fake JPEG image data")
+	}
+}
+
+func TestExportWhiteboardPreview_RejectsNonImageContentTypeWithoutSiblingOverwrite(t *testing.T) {
+	factory, stdout, reg := newExecuteFactory(t)
+	chdirTemp(t)
+
+	if err := os.WriteFile("report.html", []byte("keep me"), 0644); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+	reg.Register(&httpmock.Stub{
+		Method:      "GET",
+		URL:         "/open-apis/board/v1/whiteboards/test-token-preview-html/download_as_image",
+		Status:      200,
+		RawBody:     []byte("<html>bad gateway</html>"),
+		ContentType: "text/html; charset=utf-8",
+	})
+
+	args := []string{"+export", "--whiteboard-token", "test-token-preview-html", "--output-type", "preview", "--output", "report.png", "--overwrite"}
+	err := runShortcut(t, WhiteboardExport, args, factory, stdout)
+	if err == nil {
+		t.Fatal("expected error for non-image preview response")
+	}
+	assertInvalidResponse(t, err)
+
+	data, readErr := os.ReadFile("report.html")
+	if readErr != nil {
+		t.Fatalf("ReadFile() error: %v", readErr)
+	}
+	if string(data) != "keep me" {
+		t.Fatalf("report.html was overwritten: %q", string(data))
+	}
+	if _, statErr := os.Stat("report.png"); !errors.Is(statErr, os.ErrNotExist) {
+		t.Fatalf("report.png should not be written on invalid response, stat err=%v", statErr)
+	}
+}
+
+func TestExportWhiteboardPreview_IgnoresContentDispositionExtension(t *testing.T) {
+	factory, stdout, reg := newExecuteFactory(t)
+	chdirTemp(t)
+
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/board/v1/whiteboards/test-token-preview-disposition/download_as_image",
+		Status:  200,
+		RawBody: []byte("fake JPEG image data"),
+		Headers: http.Header{
+			"Content-Type":        []string{"image/jpeg"},
+			"Content-Disposition": []string{`attachment; filename="payload.sh"`},
+		},
+	})
+
+	args := []string{"+export", "--whiteboard-token", "test-token-preview-disposition", "--output-type", "preview", "--output", "output", "--overwrite"}
+	if err := runShortcut(t, WhiteboardExport, args, factory, stdout); err != nil {
+		t.Fatalf("err=%v", err)
+	}
+
+	if _, err := os.Stat("output.sh"); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("output.sh should not be created from Content-Disposition, stat err=%v", err)
+	}
+	data, err := os.ReadFile("output.jpg")
+	if err != nil {
+		t.Fatalf("ReadFile() error: %v", err)
+	}
+	if string(data) != "fake JPEG image data" {
+		t.Fatalf("image content = %q, want %q", string(data), "fake JPEG image data")
+	}
+}
+
+func TestExportWhiteboardPreview_RejectsMismatchedExplicitExtension(t *testing.T) {
+	factory, stdout, reg := newExecuteFactory(t)
+	chdirTemp(t)
+
+	reg.Register(&httpmock.Stub{
+		Method:      "GET",
+		URL:         "/open-apis/board/v1/whiteboards/test-token-preview-mismatch/download_as_image",
+		Status:      200,
+		RawBody:     []byte("fake JPEG image data"),
+		ContentType: "image/jpeg",
+	})
+
+	args := []string{"+export", "--whiteboard-token", "test-token-preview-mismatch", "--output-type", "preview", "--output", "report.png", "--overwrite"}
+	err := runShortcut(t, WhiteboardExport, args, factory, stdout)
+	if err == nil {
+		t.Fatal("expected error for mismatched explicit extension")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("error is not *errs.ValidationError: %T (%v)", err, err)
+	}
+	if ve.Subtype != errs.SubtypeFailedPrecondition || ve.Param != "--output" {
+		t.Fatalf("validation details = subtype %q param %q, want %q --output", ve.Subtype, ve.Param, errs.SubtypeFailedPrecondition)
+	}
+	if _, statErr := os.Stat("report.jpg"); !errors.Is(statErr, os.ErrNotExist) {
+		t.Fatalf("report.jpg should not be created when explicit path mismatches, stat err=%v", statErr)
+	}
+}
+
+func TestExportWhiteboardPreview_AllowsMatchingExplicitExtension(t *testing.T) {
+	factory, stdout, reg := newExecuteFactory(t)
+	chdirTemp(t)
+
+	reg.Register(&httpmock.Stub{
+		Method:      "GET",
+		URL:         "/open-apis/board/v1/whiteboards/test-token-preview-matching/download_as_image",
+		Status:      200,
+		RawBody:     []byte("fake JPEG image data"),
+		ContentType: "image/jpeg",
+	})
+
+	args := []string{"+export", "--whiteboard-token", "test-token-preview-matching", "--output-type", "preview", "--output", "report.jpeg", "--overwrite"}
+	if err := runShortcut(t, WhiteboardExport, args, factory, stdout); err != nil {
+		t.Fatalf("err=%v", err)
+	}
+	data, err := os.ReadFile("report.jpeg")
+	if err != nil {
+		t.Fatalf("ReadFile() error: %v", err)
+	}
+	if string(data) != "fake JPEG image data" {
+		t.Fatalf("image content = %q, want %q", string(data), "fake JPEG image data")
+	}
+}
+
 // TestExportWhiteboardRaw_EmptyNodes verifies raw export reports empty whiteboards.
 func TestExportWhiteboardRaw_EmptyNodes(t *testing.T) {
 	factory, stdout, reg := newExecuteFactory(t)
@@ -1522,3 +1792,12 @@ func chdirTemp(t *testing.T) {
 	}
 	t.Cleanup(func() { os.Chdir(orig) })
 }
+
+func shortcutFlag(shortcut common.Shortcut, name string) *common.Flag {
+	for i := range shortcut.Flags {
+		if shortcut.Flags[i].Name == name {
+			return &shortcut.Flags[i]
+		}
+	}
+	return nil
+}

shortcuts/whiteboard/whiteboard_query.go

@@ -1,494 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-package whiteboard
-
-import (
-	"bytes"
-	"context"
-	"encoding/base64"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"os"
-	"path/filepath"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/shortcuts/common"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-)
-
-const (
-	// WhiteboardQueryAsImage exports a whiteboard preview image.
-	WhiteboardQueryAsImage = "image"
-	// WhiteboardQueryAsSvg exports a whiteboard as SVG.
-	WhiteboardQueryAsSvg = "svg"
-	// WhiteboardQueryAsCode exports Mermaid or PlantUML source extracted from the whiteboard.
-	WhiteboardQueryAsCode = "code"
-	// WhiteboardQueryAsRaw exports the raw whiteboard node payload.
-	WhiteboardQueryAsRaw = "raw"
-)
-
-// SyntaxType identifies the diagram syntax extracted from whiteboard code blocks.
-type SyntaxType int
-
-const (
-	// SyntaxTypePlantUML marks PlantUML code blocks.
-	SyntaxTypePlantUML SyntaxType = 1
-	// SyntaxTypeMermaid marks Mermaid code blocks.
-	SyntaxTypeMermaid SyntaxType = 2
-)
-
-// SyntaxTypeNameMap maps whiteboard syntax types to their CLI output names.
-var SyntaxTypeNameMap = map[SyntaxType]string{
-	SyntaxTypePlantUML: "plantuml",
-	SyntaxTypeMermaid:  "mermaid",
-}
-
-// SyntaxTypeExtensionMap maps whiteboard syntax types to their default file extensions.
-var SyntaxTypeExtensionMap = map[SyntaxType]string{
-	SyntaxTypePlantUML: ".puml",
-	SyntaxTypeMermaid:  ".mmd",
-}
-
-// String returns the CLI-facing name for the syntax type.
-func (s SyntaxType) String() string {
-	return SyntaxTypeNameMap[s]
-}
-
-// ExtensionName returns the default file extension for the syntax type.
-func (s SyntaxType) ExtensionName() string {
-	return SyntaxTypeExtensionMap[s]
-}
-
-// IsValid reports whether the syntax type is one of the supported whiteboard code syntaxes.
-func (s SyntaxType) IsValid() bool {
-	return s == SyntaxTypePlantUML || s == SyntaxTypeMermaid
-}
-
-// WhiteboardQuery registers the `whiteboard +query` shortcut.
-var WhiteboardQuery = common.Shortcut{
-	Service:     "whiteboard",
-	Command:     "+query",
-	Description: "Query a existing whiteboard, export it as preview image or raw nodes structure.",
-	Risk:        "read",
-	Scopes:      []string{"board:whiteboard:node:read"},
-	AuthTypes:   []string{"user", "bot"},
-	Flags: []common.Flag{
-		{Name: "whiteboard-token", Desc: "whiteboard token of the whiteboard. You will need read permission to download preview image.", Required: true},
-		{Name: "output_as", Desc: "output whiteboard as: image | svg | code | raw.", Required: true},
-		{Name: "output", Desc: "output directory. It is required when output as image. If not specified when --output_as svg/code/raw, it will output directly.", Required: false},
-		{Name: "overwrite", Desc: "overwrite existing file if it exists", Required: false, Type: "bool"},
-	},
-	HasFormat: true,
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		// Check if token contains control characters
-		token := runtime.Str("whiteboard-token")
-		if err := common.RejectDangerousCharsTyped("--whiteboard-token", token); err != nil {
-			return err
-		}
-		out := runtime.Str("output")
-		if out != "" {
-			if _, err := runtime.ResolveSavePath(out); err != nil {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid output path: %s", err).WithParam("--output").WithCause(err)
-			}
-		}
-		if out == "" && runtime.Str("output_as") == WhiteboardQueryAsImage {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "need a output directory to query whiteboard as image").WithParam("--output")
-		}
-
-		as := runtime.Str("output_as")
-		if as != WhiteboardQueryAsImage && as != WhiteboardQueryAsSvg && as != WhiteboardQueryAsCode && as != WhiteboardQueryAsRaw {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output_as flag must be one of: image | svg | code | raw").WithParam("--output_as")
-		}
-		return nil
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		as := runtime.Str("output_as")
-		token := runtime.Str("whiteboard-token")
-		switch as {
-		case WhiteboardQueryAsImage:
-			return common.NewDryRunAPI().
-				GET(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/download_as_image", common.MaskToken(url.PathEscape(token)))).
-				Desc("Export preview image of given whiteboard")
-		case WhiteboardQueryAsCode:
-			return common.NewDryRunAPI().
-				GET(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", common.MaskToken(url.PathEscape(token)))).
-				Desc("Extract Mermaid/Plantuml code from given whiteboard")
-		case WhiteboardQueryAsRaw:
-			return common.NewDryRunAPI().
-				GET(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", common.MaskToken(url.PathEscape(token)))).
-				Desc("Extract raw nodes structure from given whiteboard")
-		case WhiteboardQueryAsSvg:
-			return common.NewDryRunAPI().
-				POST(fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/export", common.MaskToken(url.PathEscape(token)))).
-				Body(map[string]string{"export_type": "svg"}).
-				Desc("Export SVG of given whiteboard")
-		default:
-			return common.NewDryRunAPI().Desc("invalid --output_as flag, must be one of: image | svg | code | raw")
-		}
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		// 构建 API 请求
-		token := runtime.Str("whiteboard-token")
-		outDir := runtime.Str("output")
-		as := runtime.Str("output_as")
-		switch as {
-		case WhiteboardQueryAsImage:
-			return exportWhiteboardPreview(ctx, runtime, token, outDir)
-		case WhiteboardQueryAsSvg:
-			return exportWhiteboardSvg(runtime, token, outDir)
-		case WhiteboardQueryAsCode:
-			return exportWhiteboardCode(runtime, token, outDir)
-		case WhiteboardQueryAsRaw:
-			return exportWhiteboardRaw(runtime, token, outDir)
-		default:
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output_as flag must be one of: image | svg | code | raw").WithParam("--output_as")
-		}
-
-	},
-}
-
-// exportReq defines the request body for whiteboard export APIs.
-type exportReq struct {
-	ExportType string `json:"export_type"`
-}
-
-// exportResp models the whiteboard export response envelope.
-type exportResp struct {
-	Code int    `json:"code"`
-	Msg  string `json:"msg"`
-	Data struct {
-		Content  string `json:"content"`
-		MimeType string `json:"mime_type"`
-	} `json:"data"`
-}
-
-// exportWhiteboardSvg exports a whiteboard as SVG and writes it to stdout or a file.
-func exportWhiteboardSvg(runtime *common.RuntimeContext, wbToken, outDir string) error {
-	reqBody := exportReq{ExportType: "svg"}
-	req := &larkcore.ApiReq{
-		HttpMethod: http.MethodPost,
-		ApiPath:    fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/export", url.PathEscape(wbToken)),
-		Body:       reqBody,
-	}
-
-	resp, err := runtime.DoAPI(req)
-	if err != nil {
-		return wrapWbNetworkErr(err, "export whiteboard svg failed: %v", err)
-	}
-
-	var exportData exportResp
-	if err := json.Unmarshal(resp.RawBody, &exportData); err == nil {
-		if exportData.Code != 0 {
-			subtype := errs.SubtypeUnknown
-			if resp.StatusCode == http.StatusNotFound {
-				subtype = errs.SubtypeNotFound
-			}
-			return errs.NewAPIError(subtype, "export whiteboard svg failed: %s", exportData.Msg).WithCode(exportData.Code)
-		}
-	} else if resp.StatusCode == http.StatusOK {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "parse export response failed: %v", err).WithCause(err)
-	}
-
-	if resp.StatusCode != http.StatusOK {
-		body := common.TruncateStr(strings.TrimSpace(string(resp.RawBody)), 500)
-		if resp.StatusCode >= 500 {
-			return errs.NewNetworkError(errs.SubtypeNetworkServer, "export whiteboard svg failed: HTTP %d: %s", resp.StatusCode, body).
-				WithCode(resp.StatusCode).
-				WithRetryable()
-		}
-		subtype := errs.SubtypeUnknown
-		if resp.StatusCode == http.StatusNotFound {
-			subtype = errs.SubtypeNotFound
-		}
-		return errs.NewAPIError(subtype, "export whiteboard svg failed: HTTP %d: %s", resp.StatusCode, body).
-			WithCode(resp.StatusCode)
-	}
-
-	svgBytes, err := base64.StdEncoding.DecodeString(exportData.Data.Content)
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "decode svg base64 failed: %v", err).WithCause(err)
-	}
-
-	if outDir == "" {
-		runtime.OutFormat(map[string]interface{}{
-			"svg_content": string(svgBytes),
-		}, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "%s\n", string(svgBytes))
-		})
-		return nil
-	}
-
-	finalPath, size, err := saveOutputFile(outDir, ".svg", wbToken, runtime, bytes.NewReader(svgBytes))
-	if err != nil {
-		return err
-	}
-
-	runtime.OutFormat(map[string]interface{}{
-		"svg_path":   finalPath,
-		"size_bytes": size,
-	}, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "SVG saved to %s\n", finalPath)
-		fmt.Fprintf(w, "File size: %d bytes", size)
-	})
-	return nil
-}
-
-func exportWhiteboardPreview(ctx context.Context, runtime *common.RuntimeContext, wbToken, outDir string) error {
-	req := &larkcore.ApiReq{
-		HttpMethod: http.MethodGet,
-		ApiPath:    fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/download_as_image", url.PathEscape(wbToken)),
-	}
-	// Execute API request. The preview endpoint streams raw image bytes (not a
-	// JSON envelope), so classify by HTTP status: 5xx is retryable network,
-	// while 4xx remains an API-side rejection.
-	resp, err := runtime.DoAPI(req, larkcore.WithFileDownload())
-	if err != nil {
-		return wrapWbNetworkErr(err, "get whiteboard preview failed: %v", err)
-	}
-	if resp.StatusCode >= 400 {
-		body := common.TruncateStr(strings.TrimSpace(string(resp.RawBody)), 500)
-		if resp.StatusCode >= 500 {
-			return errs.NewNetworkError(errs.SubtypeNetworkServer, "get whiteboard preview failed: HTTP %d: %s", resp.StatusCode, body).
-				WithCode(resp.StatusCode).
-				WithRetryable()
-		}
-		subtype := errs.SubtypeUnknown
-		if resp.StatusCode == http.StatusNotFound {
-			subtype = errs.SubtypeNotFound
-		}
-		return errs.NewAPIError(subtype, "get whiteboard preview failed: HTTP %d: %s", resp.StatusCode, body).
-			WithCode(resp.StatusCode)
-	}
-
-	finalPath, size, err := saveOutputFile(outDir, ".png", wbToken, runtime, bytes.NewReader(resp.RawBody))
-	if err != nil {
-		return err
-	}
-
-	runtime.OutFormat(map[string]interface{}{
-		"preview_image_path": finalPath,
-		"size_bytes":         size,
-	}, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "Preview image saved to %s\n", finalPath)
-		fmt.Fprintf(w, "Image size: %d bytes", size)
-	})
-	return nil
-}
-
-type wbNodesResp struct {
-	Data struct {
-		Nodes []interface{} `json:"nodes"`
-	} `json:"data"`
-}
-
-func fetchWhiteboardNodes(runtime *common.RuntimeContext, wbToken string) (*wbNodesResp, error) {
-	data, err := runtime.CallAPITyped(http.MethodGet, fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/nodes", url.PathEscape(wbToken)), nil, nil)
-	if err != nil {
-		return nil, err
-	}
-	var nodes wbNodesResp
-	rawNodes, _ := data["nodes"]
-	if rawNodes != nil {
-		var ok bool
-		nodes.Data.Nodes, ok = rawNodes.([]interface{})
-		if !ok {
-			return nil, wbInvalidResponse("get whiteboard nodes failed: data.nodes must be an array")
-		}
-	}
-	return &nodes, nil
-}
-
-type syntaxInfo struct {
-	code       string
-	syntaxType SyntaxType
-}
-
-func exportWhiteboardCode(runtime *common.RuntimeContext, wbToken, outDir string) error {
-	wbNodes, err := fetchWhiteboardNodes(runtime, wbToken)
-	if err != nil {
-		return err
-	}
-	if wbNodes == nil || wbNodes.Data.Nodes == nil {
-		runtime.OutFormat(map[string]interface{}{
-			"msg": "whiteboard is empty",
-		}, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "Whiteboard is empty\n")
-		})
-		return nil
-	}
-
-	var syntaxBlocks []syntaxInfo
-	for _, node := range wbNodes.Data.Nodes {
-		nodeMap, ok := node.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		syntax, ok := nodeMap["syntax"]
-		if !ok {
-			continue
-		}
-		syntaxMap, ok := syntax.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		code, _ := syntaxMap["code"].(string)
-		var syntaxType SyntaxType
-		switch v := syntaxMap["syntax_type"].(type) {
-		case json.Number:
-			// runtime.ClassifyAPIResponse decodes the response with UseNumber,
-			// so numeric fields arrive as json.Number rather than float64.
-			if n, err := v.Int64(); err == nil {
-				syntaxType = SyntaxType(n)
-			}
-		case float64:
-			syntaxType = SyntaxType(v)
-		case SyntaxType:
-			syntaxType = v
-		}
-		if code != "" && syntaxType.IsValid() {
-			syntaxBlocks = append(syntaxBlocks, syntaxInfo{code: code, syntaxType: syntaxType})
-		}
-	}
-
-	if len(syntaxBlocks) == 0 {
-		runtime.OutFormat(map[string]interface{}{
-			"msg": "no code blocks found in whiteboard",
-		}, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "No code blocks found in whiteboard\n")
-		})
-		return nil
-	}
-	// 目前的标准操作是导出到单一文件，和 Doc 展示画板代码块采用相同的逻辑
-	// 如果有需求，可以调整到导出到多个文件的模式
-	if len(syntaxBlocks) > 1 {
-		runtime.OutFormat(map[string]interface{}{
-			"msg": "multiple code blocks found, cannot export directly",
-		}, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "Multiple code blocks found, cannot export directly\n")
-		})
-		return nil
-	}
-	block := syntaxBlocks[0]
-
-	if outDir == "" {
-		runtime.OutFormat(map[string]interface{}{
-			"code":        block.code,
-			"syntax_type": block.syntaxType.String(),
-		}, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "%s\n", block.code)
-		})
-		return nil
-	}
-
-	finalPath, _, err := saveOutputFile(outDir, block.syntaxType.ExtensionName(), wbToken, runtime, strings.NewReader(block.code))
-	if err != nil {
-		return err
-	}
-
-	runtime.OutFormat(map[string]interface{}{
-		"output_path": finalPath,
-	}, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "Whiteboard code saved to %s\n", finalPath)
-	})
-
-	return nil
-}
-
-func exportWhiteboardRaw(runtime *common.RuntimeContext, wbToken, outDir string) error {
-	wbNodes, err := fetchWhiteboardNodes(runtime, wbToken)
-	if err != nil {
-		return err
-	}
-	if wbNodes == nil || wbNodes.Data.Nodes == nil {
-		runtime.OutFormat(map[string]interface{}{
-			"msg": "whiteboard is empty",
-		}, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "Whiteboard is empty\n")
-		})
-		return nil
-	}
-
-	jsonData, err := json.MarshalIndent(wbNodes.Data, "", "  ")
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "cannot marshal whiteboard data: %s", err).WithCause(err)
-	}
-
-	if outDir == "" {
-		runtime.OutFormat(wbNodes.Data, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "%s\n", string(jsonData))
-		})
-		return nil
-	}
-
-	finalPath, _, err := saveOutputFile(outDir, ".json", wbToken, runtime, bytes.NewReader(jsonData))
-	if err != nil {
-		return err
-	}
-
-	runtime.OutFormat(map[string]interface{}{
-		"output_path": finalPath,
-	}, nil, func(w io.Writer) {
-		fmt.Fprintf(w, "Whiteboard raw node structure saved to %s\n", finalPath)
-	})
-
-	return nil
-}
-
-func saveOutputFile(outPath, ext, token string, runtime *common.RuntimeContext, data io.Reader) (string, int64, error) {
-	// Step 1: Get final output path
-	info, err := runtime.FileIO().Stat(outPath)
-	var finalPath string
-	if err == nil && info.IsDir() {
-		finalPath = filepath.Join(outPath, fmt.Sprintf("whiteboard_%s%s", token, ext))
-	} else {
-		// Fix extension in path
-		currentExt := filepath.Ext(outPath)
-		if currentExt != ext {
-			if currentExt != "" {
-				outPath = outPath[:len(outPath)-len(currentExt)]
-			}
-			outPath += ext
-		}
-		finalPath = outPath
-	}
-	if _, err := runtime.ResolveSavePath(finalPath); err != nil { // double check
-		return "", 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid output path: %s", err).WithParam("--output").WithCause(err)
-	}
-
-	// Step 2: Check overwrite
-	_, err = runtime.FileIO().Stat(finalPath)
-	if err == nil {
-		if !runtime.Bool("overwrite") {
-			return "", 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "file already exists: %s (use --overwrite to overwrite)", finalPath).WithParam("--overwrite")
-		}
-	} else if !os.IsNotExist(err) {
-		return "", 0, errs.NewInternalError(errs.SubtypeFileIO, "cannot check file existence: %s", err).WithCause(err)
-	}
-
-	// Step 3: Save file
-	var contentType string
-	switch ext {
-	case ".png":
-		contentType = "image/png"
-	case ".svg":
-		contentType = "image/svg+xml"
-	case ".json":
-		contentType = "application/json"
-	case ".mmd", ".puml":
-		contentType = "text/plain"
-	}
-
-	savResult, err := runtime.FileIO().Save(finalPath, fileio.SaveOptions{
-		ContentType: contentType,
-	}, data)
-	if err != nil {
-		return "", 0, wbSaveError(err)
-	}
-
-	return finalPath, savResult.Size(), nil
-}

shortcuts/whiteboard/whiteboard_update_test.go

@@ -255,6 +255,7 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 	got := Shortcuts()
 	want := []string{
 		"+update",
+		"+export",
 		"+query",
 	}