feat: inline slides reference docs into help output

Embed the lark-slides reference docs (xml-schema-quick-ref.md and each shortcut's command guide) directly into the CLI help output so that agents can discover XML syntax and shortcut usage without reading separate markdown files.

- PrepareDomainHelp: append XML schema quick reference for slides domain
- PrepareShortcutHelp: embed shortcut-specific reference docs for +create, +xml-get, +screenshot, +media-upload, +replace-slide, +replace-pages, +history-list, +history-revert, +history-revert-status
- Add contract tests for all reference mappings and re-render idempotency
- +screenshot excludes the shared XML reference (user feedback)

.github/CODEOWNERS

@@ -1,4 +1,7 @@
+/go.mod @liangshuo-1
+/go.sum @liangshuo-1
 /internal/ @liangshuo-1
+/shortcuts/common/ @liangshuo-1
 
 # Last match wins: existing domains below are exempt, only new skills/ entries need review.
 /skills/ @liangshuo-1

.github/workflows/semantic-review.yml

@@ -25,19 +25,16 @@ jobs:
         with:
           script: |
             const run = context.payload.workflow_run;
-            if (run.name !== "CI") throw new Error(`unexpected workflow name: ${run.name}`);
-            let workflowPath = run.path || "";
-            if (!workflowPath) {
-              const workflowId = Number(run.workflow_id || 0);
-              if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
-              const { data: workflow } = await github.rest.actions.getWorkflow({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                workflow_id: workflowId,
-              });
-              workflowPath = workflow.path || "";
-            }
-            if (workflowPath !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflowPath}`);
+            const workflowId = Number(run.workflow_id || 0);
+            if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
+            const { data: workflow } = await github.rest.actions.getWorkflow({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: workflowId,
+            });
+            if (workflow.name !== "CI") throw new Error(`unexpected workflow name: ${workflow.name}`);
+            if (workflow.path !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflow.path}`);
+            if (run.path && run.path !== workflow.path) throw new Error(`workflow path mismatch: ${run.path}`);
             if (run.event !== "pull_request") throw new Error(`unexpected event: ${run.event}`);
             if (run.repository.id !== context.payload.repository.id) throw new Error("repository id mismatch");
             if (run.repository.full_name !== context.payload.repository.full_name) throw new Error("repository name mismatch");
@@ -253,19 +250,16 @@ jobs:
         with:
           script: |
             const run = context.payload.workflow_run;
-            if (run.name !== "CI") throw new Error(`unexpected workflow name: ${run.name}`);
-            let workflowPath = run.path || "";
-            if (!workflowPath) {
-              const workflowId = Number(run.workflow_id || 0);
-              if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
-              const { data: workflow } = await github.rest.actions.getWorkflow({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                workflow_id: workflowId,
-              });
-              workflowPath = workflow.path || "";
-            }
-            if (workflowPath !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflowPath}`);
+            const workflowId = Number(run.workflow_id || 0);
+            if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
+            const { data: workflow } = await github.rest.actions.getWorkflow({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: workflowId,
+            });
+            if (workflow.name !== "CI") throw new Error(`unexpected workflow name: ${workflow.name}`);
+            if (workflow.path !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflow.path}`);
+            if (run.path && run.path !== workflow.path) throw new Error(`workflow path mismatch: ${run.path}`);
             if (run.event !== "pull_request") throw new Error(`unexpected event: ${run.event}`);
             if (run.conclusion !== "success") throw new Error(`unexpected conclusion: ${run.conclusion}`);
             if (run.repository.id !== context.payload.repository.id) throw new Error("repository id mismatch");

CHANGELOG.md

@@ -2,6 +2,90 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.80] - 2026-07-29
+
+### Features
+
+- **drive**: add +member-list shortcut (#1795)
+- **drive**: add +permission-get-setting shortcut (#1738)
+- propagate invocation metadata (#2097)
+
+### Documentation
+
+- **slides**: 补齐 shortcut 参数说明，修正 +xml-get --output 必填标注 (#2088)
+- **slides**: +create 的参数下沉到 create.md，主 skill 只留路由 (#2096)
+
+### Tests
+
+- **e2e**: wait for base role update visibility (#2087)
+
+### Misc
+
+- Feat/detect line text overlap (#2069)
+
+## [v1.0.79] - 2026-07-28
+
+### Features
+
+- **slides**: update xsd (#2067)
+
+### Bug Fixes
+
+- **ci**: validate static workflow identity (#2015)
+- **sheets**: recognize OFL0X local office tokens (#2063)
+
+### Documentation
+
+- **calendar**: clarify identity selection by event ownership (#2071)
+- **slides**: add formula inline element syntax to quick-ref (#2077)
+
+## [v1.0.78] - 2026-07-27
+
+### Features
+
+- event description support rich text (#1975)
+
+### Bug Fixes
+
+- **slides**: restrict canvas overflow checks
+- **slides**: upgrade text overflow to error above 10px threshold
+- **slides**: detect letterSpacing-driven text overflow
+- **slides**: downgrade background-decoration text overflow to info
+- **slides**: allow chartParsedValues roundtrip tag
+- refine character width estimation for lark-slides text lint
+- **slides**: preserve info lint severity
+- **slides**: text may over flow shape
+- exempt ghost text from slides lint
+
+## [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
@@ -1638,6 +1722,10 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.80]: https://github.com/larksuite/cli/releases/tag/v1.0.80
+[v1.0.79]: https://github.com/larksuite/cli/releases/tag/v1.0.79
+[v1.0.78]: https://github.com/larksuite/cli/releases/tag/v1.0.78
+[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

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)
+	}
+}

cmd/service/affordance.go

@@ -66,6 +66,7 @@ func PrepareDomainHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 			fmt.Fprintf(&b, "\n\nDomain guide (concepts, command choice, conventions): lark-cli skills read %s", skill)
 		}
 	}
+	appendSlidesXMLQuickReference(&b, cmd, skillFS)
 	cmd.Long = b.String()
 	return true
 }
@@ -116,6 +117,90 @@ const (
 	shortcutBaseAnnotation = "affordance-shortcut-base"
 )
 
+const slidesXMLQuickReferencePath = "lark-slides/references/xml-schema-quick-ref.md"
+
+// slidesShortcutReferencePaths maps each Slides shortcut to its primary
+// command guide. XML-consuming shortcuts also include the shared schema
+// reference because their command guide accepts XML but does not repeat the
+// complete element grammar.
+var slidesShortcutReferencePaths = map[string][]string{
+	"+create": {
+		"lark-slides/references/lark-slides-create.md",
+		slidesXMLQuickReferencePath,
+	},
+	"+xml-get": {
+		"lark-slides/references/lark-slides-xml-presentations-get.md",
+	},
+	"+screenshot": {
+		"lark-slides/references/lark-slides-screenshot.md",
+	},
+	"+media-upload": {
+		"lark-slides/references/lark-slides-media-upload.md",
+	},
+	"+replace-slide": {
+		"lark-slides/references/lark-slides-replace-slide.md",
+		"lark-slides/references/lark-slides-edit-workflows.md",
+		slidesXMLQuickReferencePath,
+	},
+	"+replace-pages": {
+		"lark-slides/references/lark-slides-replace-pages.md",
+		"lark-slides/references/lark-slides-edit-workflows.md",
+		slidesXMLQuickReferencePath,
+	},
+	"+history-list": {
+		"lark-slides/references/lark-slides-history.md",
+	},
+	"+history-revert": {
+		"lark-slides/references/lark-slides-history.md",
+	},
+	"+history-revert-status": {
+		"lark-slides/references/lark-slides-history.md",
+	},
+}
+
+// appendSlidesXMLQuickReference adds the embedded XML schema summary to the
+// slides domain help. The reference file is already shipped in the skill
+// content tree, so help and the standalone skill reader share one source of
+// truth instead of maintaining a second, drifting copy in Go.
+func appendSlidesXMLQuickReference(b *strings.Builder, cmd *cobra.Command, skillFS fs.FS) {
+	if cmd.Name() != "slides" || skillFS == nil {
+		return
+	}
+	content, err := fs.ReadFile(skillFS, slidesXMLQuickReferencePath)
+	if err != nil || len(content) == 0 {
+		return
+	}
+	b.WriteString("\n\nEmbedded XML syntax quick reference:\n")
+	b.Write(content)
+}
+
+func readSlidesShortcutReferences(cmd *cobra.Command, skillFS fs.FS) ([]string, bool) {
+	if cmdmeta.Domain(cmd) != "slides" || skillFS == nil {
+		return nil, false
+	}
+	paths, ok := slidesShortcutReferencePaths[cmd.Name()]
+	if !ok {
+		return nil, false
+	}
+
+	var contents []string
+	for _, path := range paths {
+		content, err := fs.ReadFile(skillFS, path)
+		if err != nil || len(content) == 0 {
+			continue
+		}
+		contents = append(contents, fmt.Sprintf("Embedded command reference: %s\n%s", path, content))
+	}
+	return contents, len(contents) > 0
+}
+
+func appendSlidesShortcutReferences(b *strings.Builder, contents []string) {
+	for _, content := range contents {
+		b.WriteString("\n\n")
+		b.WriteString(content)
+	}
+}
+
 // setMethodHelpData records the coordinates PrepareMethodHelp needs (storing a
 // few strings is the only build-time cost; the overlay stays untouched).
 func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, paramsOnly string) {
@@ -171,11 +256,11 @@ func PrepareMethodHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 }
 
 // PrepareShortcutHelp composes a +-prefixed shortcut's Long from its affordance
-// overlay — the same top layout as method help (description, Risk, guidance
-// block, related skills) minus the schema pointer, which shortcuts have none
-// of. Returns false when the command is not a shortcut or carries no overlay
-// entry, so shortcuts without guidance keep the default help plus the bottom
-// risk/tips append.
+// overlay and any embedded command references — the same top layout as method
+// help (description, Risk, guidance block, related skills) minus the schema
+// pointer, which shortcuts have none of. Returns false when the command is not
+// a shortcut, or when it has neither an overlay nor an embedded reference, so
+// ordinary shortcuts keep the default help plus the bottom risk/tips append.
 //
 // The lead is the command's pristine base (captureHelpBase): a shortcut that
 // set a hand-authored Long in PostMount (e.g. the docs shortcuts' "agents MUST
@@ -191,12 +276,17 @@ func PrepareShortcutHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 	if src, _ := cmdmeta.SourceOf(cmd); src != cmdmeta.SourceShortcut {
 		return false
 	}
-	raw, ok := affordanceRaw(cmd)
-	if !ok {
-		return false
+	references, hasReferences := readSlidesShortcutReferences(cmd, skillFS)
+
+	var a meta.Affordance
+	hasAffordance := false
+	if raw, ok := affordanceRaw(cmd); ok {
+		if parsed, parsedOK := (meta.Method{Affordance: raw}).ParsedAffordance(); parsedOK {
+			a = parsed
+			hasAffordance = true
+		}
 	}
-	a, ok := (meta.Method{Affordance: raw}).ParsedAffordance()
-	if !ok {
+	if !hasAffordance && !hasReferences {
 		return false
 	}
 	if len(a.Tips) == 0 {
@@ -211,6 +301,7 @@ func PrepareShortcutHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 		b.WriteString(block)
 	}
 	writeRelatedSkills(&b, a.Skills, skillFS)
+	appendSlidesShortcutReferences(&b, references)
 
 	cmd.Long = b.String()
 	return true

cmd/service/affordance_test.go

@@ -264,6 +264,94 @@ func TestPrepareShortcutHelp_PreservesPostMountLong(t *testing.T) {
 	}
 }
 
+func TestPrepareShortcutHelp_SlidesReferenceWithoutAffordance(t *testing.T) {
+	sc := &cobra.Command{Use: "+xml-get", Short: "Fetch presentation XML"}
+	cmdmeta.SetSource(sc, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetDomain(sc, "slides")
+	cmdmeta.SetAffordanceRef(sc, "slides", "+xml-get")
+	cmdutil.SetRisk(sc, "read")
+
+	skillFS := fstest.MapFS{
+		"lark-slides/references/lark-slides-xml-presentations-get.md": {
+			Data: []byte("# slides +xml-get\n\nRead the presentation XML."),
+		},
+	}
+	if !PrepareShortcutHelp(sc, skillFS) {
+		t.Fatal("PrepareShortcutHelp returned false for a Slides shortcut with an embedded reference")
+	}
+	for _, want := range []string{
+		"Fetch presentation XML",
+		"Risk: read",
+		"Embedded command reference: lark-slides/references/lark-slides-xml-presentations-get.md",
+		"Read the presentation XML.",
+	} {
+		if !strings.Contains(sc.Long, want) {
+			t.Errorf("Slides shortcut help missing %q:\n%s", want, sc.Long)
+		}
+	}
+	PrepareShortcutHelp(sc, skillFS)
+	if got := strings.Count(sc.Long, "Embedded command reference:"); got != 1 {
+		t.Fatalf("embedded reference appended %d times after re-render, want 1:\n%s", got, sc.Long)
+	}
+}
+
+func TestSlidesShortcutReferenceMapping(t *testing.T) {
+	want := map[string]string{
+		"+create":                "lark-slides/references/lark-slides-create.md",
+		"+xml-get":               "lark-slides/references/lark-slides-xml-presentations-get.md",
+		"+screenshot":            "lark-slides/references/lark-slides-screenshot.md",
+		"+media-upload":          "lark-slides/references/lark-slides-media-upload.md",
+		"+replace-slide":         "lark-slides/references/lark-slides-replace-slide.md",
+		"+replace-pages":         "lark-slides/references/lark-slides-replace-pages.md",
+		"+history-list":          "lark-slides/references/lark-slides-history.md",
+		"+history-revert":        "lark-slides/references/lark-slides-history.md",
+		"+history-revert-status": "lark-slides/references/lark-slides-history.md",
+	}
+
+	for command, path := range want {
+		t.Run(command, func(t *testing.T) {
+			sc := &cobra.Command{Use: command, Short: command}
+			cmdmeta.SetSource(sc, cmdmeta.SourceShortcut, false)
+			cmdmeta.SetDomain(sc, "slides")
+			skillFS := fstest.MapFS{
+				path: {Data: []byte("reference content")},
+			}
+			contents, ok := readSlidesShortcutReferences(sc, skillFS)
+			if !ok || len(contents) == 0 {
+				t.Fatalf("shortcut %q has no mapped reference", command)
+			}
+			if !strings.Contains(contents[0], "Embedded command reference: "+path) {
+				t.Fatalf("shortcut %q mapped content does not include %q:\n%s", command, path, contents[0])
+			}
+		})
+	}
+}
+
+func TestSlidesScreenshotHelpDoesNotIncludeXMLQuickReference(t *testing.T) {
+	sc := &cobra.Command{Use: "+screenshot", Short: "Save screenshots"}
+	cmdmeta.SetSource(sc, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetDomain(sc, "slides")
+	skillFS := fstest.MapFS{
+		"lark-slides/references/lark-slides-screenshot.md": {
+			Data: []byte("# slides +screenshot\n\nSave screenshots."),
+		},
+		slidesXMLQuickReferencePath: {
+			Data: []byte("# XML Schema Quick Reference"),
+		},
+	}
+
+	contents, ok := readSlidesShortcutReferences(sc, skillFS)
+	if !ok {
+		t.Fatal("screenshot shortcut should have a primary reference")
+	}
+	if len(contents) != 1 {
+		t.Fatalf("screenshot reference count = %d, want 1: %#v", len(contents), contents)
+	}
+	if strings.Contains(contents[0], "XML Schema Quick Reference") {
+		t.Fatalf("screenshot help must not include the XML quick reference:\n%s", contents[0])
+	}
+}
+
 // domainCmd wires a domain-tagged command with a subcommand under a root, the
 // shape PrepareDomainHelp expects.
 func domainCmd(short, long string) *cobra.Command {
@@ -306,3 +394,51 @@ func TestPrepareDomainHelp_FallsBackToShort(t *testing.T) {
 		t.Errorf("Short should seed Long when no hand-authored Long exists; got:\n%s", dom.Long)
 	}
 }
+
+func TestPrepareDomainHelp_SlidesIncludesEmbeddedXMLReference(t *testing.T) {
+	root := &cobra.Command{Use: "root"}
+	dom := &cobra.Command{Use: "slides", Short: "Slides"}
+	cmdmeta.SetDomain(dom, "slides")
+	dom.AddCommand(&cobra.Command{Use: "+create", Short: "Create", Run: func(*cobra.Command, []string) {}})
+	root.AddCommand(dom)
+
+	const quickReference = `# XML Schema Quick Reference
+
+<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+  <slide>
+    <data>
+      <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+        <content textType="title"><p>Title</p></content>
+      </shape>
+    </data>
+  </slide>
+</presentation>
+
+<table><colgroup><col/></colgroup><tr><td><content><p>A</p></content></td></tr></table>
+<chart><chartPlotArea/><chartData/></chart>`
+	skillFS := fstest.MapFS{
+		"lark-slides/SKILL.md":                           {Data: []byte("# slides")},
+		"lark-slides/references/xml-schema-quick-ref.md": {Data: []byte(quickReference)},
+	}
+
+	if !PrepareDomainHelp(dom, skillFS) {
+		t.Fatal("PrepareDomainHelp returned false for slides domain")
+	}
+	for _, want := range []string{
+		"Embedded XML syntax quick reference:",
+		`<presentation xmlns="http://www.larkoffice.com/sml/2.0"`,
+		"<shape type=\"text\"",
+		"<content",
+		"topLeftX",
+		"<table>",
+		"<chart>",
+	} {
+		if !strings.Contains(dom.Long, want) {
+			t.Errorf("slides help missing XML reference marker %q:\n%s", want, dom.Long)
+		}
+	}
+	PrepareDomainHelp(dom, skillFS)
+	if got := strings.Count(dom.Long, "Embedded XML syntax quick reference:"); got != 1 {
+		t.Fatalf("slides XML reference appended %d times after re-render, want 1:\n%s", got, dom.Long)
+	}
+}

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/secheader.go

@@ -26,6 +26,7 @@ const (
 	HeaderShortcut    = "X-Cli-Shortcut"
 	HeaderExecutionId = "X-Cli-Execution-Id"
 	HeaderAgentTrace  = "X-Agent-Trace"
+	HeaderAgentName   = "X-Agent-Name"
 
 	SourceValue = "lark-cli"
 
@@ -55,6 +56,9 @@ func BaseSecurityHeaders() http.Header {
 	if v := envvars.AgentTrace(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}
+	if v := envvars.AgentName(); v != "" {
+		h.Set(HeaderAgentName, v)
+	}
 	return h
 }
 

internal/cmdutil/secheader_test.go

@@ -263,9 +263,34 @@ func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// HeaderAgentTrace injection (via BaseSecurityHeaders)
+// Agent headers injected via BaseSecurityHeaders
 // ---------------------------------------------------------------------------
 
+func TestBaseSecurityHeaders_NoAgentNameHeaderWhenEnvUnset(t *testing.T) {
+	t.Setenv(envvars.CliAgentName, "")
+	h := BaseSecurityHeaders()
+	if v := h.Get(HeaderAgentName); v != "" {
+		t.Fatalf("BaseSecurityHeaders() included %s = %q, want absent when env unset", HeaderAgentName, v)
+	}
+}
+
+func TestBaseSecurityHeaders_IncludesAgentNameHeaderWhenEnvSet(t *testing.T) {
+	const agentName = "sample-agent"
+	t.Setenv(envvars.CliAgentName, agentName)
+	h := BaseSecurityHeaders()
+	if v := h.Get(HeaderAgentName); v != agentName {
+		t.Fatalf("BaseSecurityHeaders()[%s] = %q, want %q", HeaderAgentName, v, agentName)
+	}
+}
+
+func TestBaseSecurityHeaders_NoAgentNameHeaderWhenEnvInvalid(t *testing.T) {
+	t.Setenv(envvars.CliAgentName, "agent\r\nX-Evil: attack")
+	h := BaseSecurityHeaders()
+	if v := h.Get(HeaderAgentName); v != "" {
+		t.Fatalf("BaseSecurityHeaders() included %s = %q, want absent for invalid input", HeaderAgentName, v)
+	}
+}
+
 func TestBaseSecurityHeaders_NoAgentTraceHeaderWhenEnvUnset(t *testing.T) {
 	t.Setenv(envvars.CliAgentTrace, "")
 	h := BaseSecurityHeaders()

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/envvars/read_test.go

@@ -16,16 +16,18 @@ func TestAgentName_EmptyWhenEnvUnset(t *testing.T) {
 }
 
 func TestAgentName_ReturnsCleanValue(t *testing.T) {
-	t.Setenv(CliAgentName, "claude-code")
-	if got := AgentName(); got != "claude-code" {
-		t.Fatalf("AgentName() = %q, want %q", got, "claude-code")
+	const agentName = "sample-agent"
+	t.Setenv(CliAgentName, agentName)
+	if got := AgentName(); got != agentName {
+		t.Fatalf("AgentName() = %q, want %q", got, agentName)
 	}
 }
 
 func TestAgentName_TrimsWhitespace(t *testing.T) {
-	t.Setenv(CliAgentName, "  cursor  ")
-	if got := AgentName(); got != "cursor" {
-		t.Fatalf("AgentName() = %q, want %q (whitespace trimmed)", got, "cursor")
+	const agentName = "sample-agent"
+	t.Setenv(CliAgentName, "  "+agentName+"  ")
+	if got := AgentName(); got != agentName {
+		t.Fatalf("AgentName() = %q, want %q (whitespace trimmed)", got, agentName)
 	}
 }
 

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,12 +1,12 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.76",
+  "version": "1.0.80",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@larksuite/cli",
-      "version": "1.0.76",
+      "version": "1.0.80",
       "cpu": [
         "x64",
         "arm64",

package.json

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

scripts/semantic-review-workflow.test.sh

@@ -176,7 +176,15 @@ if ! grep -Fq "if: always() && github.event.workflow_run.conclusion == 'success'
   exit 1
 fi
 
-require_in_step "$summary_verify_step" 'workflowPath !== ".github/workflows/ci.yml"' "PR quality summary must verify the triggering workflow path"
+if grep -Fq 'run.name !== "CI"' "$workflow"; then
+  echo "semantic-review must not use the dynamic workflow run name as workflow identity" >&2
+  exit 1
+fi
+
+require_in_step "$summary_verify_step" 'github.rest.actions.getWorkflow' "PR quality summary must resolve static workflow metadata"
+require_in_step "$summary_verify_step" 'workflow.name !== "CI"' "PR quality summary must verify the static workflow name"
+require_in_step "$summary_verify_step" 'workflow.path !== ".github/workflows/ci.yml"' "PR quality summary must verify the static workflow path"
+require_in_step "$summary_verify_step" 'run.path && run.path !== workflow.path' "PR quality summary must reject workflow path metadata mismatches"
 require_in_step "$summary_verify_step" 'run.event !== "pull_request"' "PR quality summary must only handle pull_request workflow_run events"
 require_in_step "$summary_verify_step" 'run.repository.id !== context.payload.repository.id' "PR quality summary must verify workflow_run repository id"
 require_in_step "$summary_verify_step" 'const targetHeadSha = run.head_sha' "PR quality summary must use the CI run head SHA as the verified PR head"
@@ -201,7 +209,10 @@ require_in_step "$summary_publish_step" 'CI_QUALITY_SUMMARY_BASE_SHA' "PR qualit
 require_in_step "$summary_publish_step" 'CI_QUALITY_SUMMARY_RUN_ID' "PR quality summary publisher must receive verified workflow run id"
 require_in_step "$summary_publish_step" 'require("./scripts/ci-quality-summary-publish.js")' "PR quality summary publisher must use the shared CI publisher script"
 
-require_in_step "$verify_step" 'workflowPath !== ".github/workflows/ci.yml"' "semantic-review must verify the triggering workflow path"
+require_in_step "$verify_step" 'github.rest.actions.getWorkflow' "semantic-review must resolve static workflow metadata"
+require_in_step "$verify_step" 'workflow.name !== "CI"' "semantic-review must verify the static workflow name"
+require_in_step "$verify_step" 'workflow.path !== ".github/workflows/ci.yml"' "semantic-review must verify the static workflow path"
+require_in_step "$verify_step" 'run.path && run.path !== workflow.path' "semantic-review must reject workflow path metadata mismatches"
 require_in_step "$verify_step" 'run.repository.id !== context.payload.repository.id' "semantic-review must verify workflow_run repository id"
 require_in_step "$verify_step" 'run.event !== "pull_request"' "semantic-review must only handle pull_request workflow_run events"
 require_in_step "$verify_step" 'run.conclusion !== "success"' "semantic-review must only consume successful CI runs"

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_form_execute_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"encoding/json"
 	"strings"
 	"testing"
 
@@ -250,7 +251,8 @@ func TestBaseFormQuestionsExecuteList(t *testing.T) {
 				"total": 2,
 				"questions": []interface{}{
 					map[string]interface{}{"id": "q_001", "title": "您的姓名", "required": true, "description": nil},
-					map[string]interface{}{"id": "q_002", "title": "您的年龄", "required": false, "description": nil},
+					map[string]interface{}{"id": "q_002", "title": "发票抬头", "required": false, "description": nil,
+						"visible_rule": map[string]interface{}{"logic": "and", "conditions": []interface{}{[]interface{}{"q_001", "==", "是"}}}},
 				},
 			},
 		},
@@ -258,9 +260,14 @@ func TestBaseFormQuestionsExecuteList(t *testing.T) {
 	if err := runShortcut(t, BaseFormQuestionsList, []string{"+form-questions-list", "--base-token", "app_x", "--table-id", "tbl_x", "--form-id", "vew_form1"}, factory, stdout); err != nil {
 		t.Fatalf("err=%v", err)
 	}
-	if got := stdout.String(); !strings.Contains(got, `"q_001"`) || !strings.Contains(got, `"total": 2`) {
+	got := stdout.String()
+	if !strings.Contains(got, `"q_001"`) || !strings.Contains(got, `"total": 2`) {
 		t.Fatalf("stdout=%s", got)
 	}
+	// The list output must forward visible_rule verbatim so agents can read existing display conditions.
+	if !strings.Contains(got, `"visible_rule"`) {
+		t.Fatalf("visible_rule missing from list output: %s", got)
+	}
 }
 
 func TestBaseFormQuestionsExecuteCreate(t *testing.T) {
@@ -296,11 +303,49 @@ func TestBaseFormQuestionsExecuteCreate(t *testing.T) {
 			t.Fatalf("expected error for invalid questions JSON")
 		}
 	})
+
+	t.Run("visible_rule passthrough", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		stub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/forms/vew_form1/questions",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"questions": []interface{}{
+						map[string]interface{}{"id": "q_new1", "title": "发票抬头"},
+					},
+				},
+			},
+		}
+		reg.Register(stub)
+		args := []string{"+form-questions-create", "--base-token", "app_x", "--table-id", "tbl_x", "--form-id", "vew_form1",
+			"--questions", `[{"type":"text","title":"发票抬头","visible_rule":{"logic":"and","conditions":[["是否需要发票","==","是"]]}}]`}
+		if err := runShortcut(t, BaseFormQuestionsCreate, args, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		var body struct {
+			Questions []map[string]interface{} `json:"questions"`
+		}
+		if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+			t.Fatalf("captured body json err=%v body=%s", err, string(stub.CapturedBody))
+		}
+		if len(body.Questions) != 1 {
+			t.Fatalf("questions=%#v", body.Questions)
+		}
+		rule, ok := body.Questions[0]["visible_rule"].(map[string]interface{})
+		if !ok {
+			t.Fatalf("visible_rule not forwarded verbatim: body=%s", string(stub.CapturedBody))
+		}
+		if rule["logic"] != "and" {
+			t.Fatalf("visible_rule logic not preserved: %#v", rule)
+		}
+	})
 }
 
 func TestBaseFormQuestionsExecuteUpdate(t *testing.T) {
 	factory, stdout, reg := newExecuteFactory(t)
-	reg.Register(&httpmock.Stub{
+	stub := &httpmock.Stub{
 		Method: "PATCH",
 		URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/forms/vew_form1/questions",
 		Body: map[string]interface{}{
@@ -311,15 +356,29 @@ func TestBaseFormQuestionsExecuteUpdate(t *testing.T) {
 				},
 			},
 		},
-	})
+	}
+	reg.Register(stub)
 	args := []string{"+form-questions-update", "--base-token", "app_x", "--table-id", "tbl_x", "--form-id", "vew_form1",
-		"--questions", `[{"id":"q_001","title":"更新后的问题","required":true}]`}
+		"--questions", `[{"id":"q_001","title":"更新后的问题","required":true,"visible_rule":{"logic":"and","conditions":[["q_002","==","是"]]}}]`}
 	if err := runShortcut(t, BaseFormQuestionsUpdate, args, factory, stdout); err != nil {
 		t.Fatalf("err=%v", err)
 	}
 	if got := stdout.String(); !strings.Contains(got, `"questions"`) || !strings.Contains(got, `"q_001"`) {
 		t.Fatalf("stdout=%s", got)
 	}
+	// visible_rule must be forwarded verbatim to the API (transcribe faithfully).
+	var body struct {
+		Questions []map[string]interface{} `json:"questions"`
+	}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("captured body json err=%v body=%s", err, string(stub.CapturedBody))
+	}
+	if len(body.Questions) != 1 {
+		t.Fatalf("questions=%#v", body.Questions)
+	}
+	if _, ok := body.Questions[0]["visible_rule"].(map[string]interface{}); !ok {
+		t.Fatalf("visible_rule not forwarded verbatim: body=%s", string(stub.CapturedBody))
+	}
 }
 
 func TestBaseFormQuestionsExecuteDelete(t *testing.T) {

shortcuts/base/base_form_questions_create.go

@@ -25,14 +25,21 @@ var BaseFormQuestionsCreate = common.Shortcut{
 		{Name: "base-token", Desc: "Base token (base_token)", Required: true},
 		{Name: "table-id", Desc: "table ID", Required: true},
 		{Name: "form-id", Desc: "form ID", Required: true},
-		{Name: "questions", Desc: `questions JSON array, max 10 items. Each item requires "title"(field title) and "type"(text/number/select/datetime/user/attachment/location). Optional fields: "description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown/1=vertical/2=horizontal,select only),"multiple"(bool,select/user),"options"([{"name":"opt","hue":"Blue"}],select only),"style"({"type":"plain/phone/url/email/barcode/rating","precision":2,"format":"yyyy/MM/dd","icon":"star","min":1,"max":5}). E.g. '[{"type":"text","title":"Your name","required":true}]'`, Required: true},
+		{Name: "questions", Desc: `questions JSON array, max 10 items. Each item requires "title"(field title) and "type"(text/number/select/datetime/user/attachment/location). Optional fields: "description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown/1=vertical/2=horizontal,select only),"multiple"(bool,select/user),"options"([{"name":"opt","hue":"Blue"}],select only),"style"({"type":"plain/phone/url/email/barcode/rating","precision":2,"format":"yyyy/MM/dd","icon":"star","min":1,"max":5}),"visible_rule"(display condition; same shape as view filter {"logic":"and","conditions":[["前序题目","==","是"]]}, field references another question's title/id, empty/absent = always shown). E.g. '[{"type":"text","title":"Your name","required":true}]'`, Required: true},
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
+		api := common.NewDryRunAPI().
 			POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id/questions").
 			Set("base_token", runtime.Str("base-token")).
 			Set("table_id", runtime.Str("table-id")).
 			Set("form_id", runtime.Str("form-id"))
+		// Transcribe the questions body verbatim so the preview shows exactly
+		// what would be sent (including optional fields like visible_rule).
+		var questions []interface{}
+		if err := json.Unmarshal([]byte(runtime.Str("questions")), &questions); err == nil {
+			api.Body(map[string]interface{}{"questions": questions})
+		}
+		return api
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		baseToken := runtime.Str("base-token")

shortcuts/base/base_form_questions_update.go

@@ -25,14 +25,26 @@ var BaseFormQuestionsUpdate = common.Shortcut{
 		{Name: "base-token", Desc: "Base token (base_token)", Required: true},
 		{Name: "table-id", Desc: "table ID", Required: true},
 		{Name: "form-id", Desc: "form ID", Required: true},
-		{Name: "questions", Desc: `questions JSON array, max 10 items, each item must include "id". Supported fields: "id"(required),"title","description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown,1=vertical,2=horizontal,select only). E.g. '[{"id":"q_001","title":"Updated?","required":true}]'`, Required: true},
+		{Name: "questions", Desc: `questions JSON array, max 10 items, each item must include "id". Update uses full question overwrite semantics: omitted/empty fields are written as defaults/empty, so run +form-questions-list first and include existing values you want to keep. Supported fields: "id"(required),"title","description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown,1=vertical,2=horizontal,select only),"visible_rule"(display condition; same shape as view filter {"logic":"and","conditions":[["前序题目","==","是"]]}, field references another question's title/id; pass null or omit to clear). E.g. '[{"id":"q_001","title":"Updated?","required":true}]'`, Required: true},
+	},
+	Tips: []string{
+		"Update uses full question overwrite semantics, not a patch.",
+		"Run +form-questions-list first and include existing title/description/required/option_display_mode/visible_rule values you want to keep.",
+		"Omitted fields reset to defaults; empty strings, null, and empty arrays are written as empty/clear when accepted by the API.",
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
+		api := common.NewDryRunAPI().
 			PATCH("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id/questions").
 			Set("base_token", runtime.Str("base-token")).
 			Set("table_id", runtime.Str("table-id")).
 			Set("form_id", runtime.Str("form-id"))
+		// Transcribe the questions body verbatim so the preview shows exactly
+		// what would be sent (including optional fields like visible_rule).
+		var questions []interface{}
+		if err := json.Unmarshal([]byte(runtime.Str("questions")), &questions); err == nil {
+			api.Body(map[string]interface{}{"questions": questions})
+		}
+		return api
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		baseToken := runtime.Str("base-token")

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

@@ -783,6 +783,20 @@ func TestBaseJSONExamplesLiveInFlagDescriptions(t *testing.T) {
 				`JSON array of question IDs to delete, max 10 items, e.g. '["q_001","q_002"]'`,
 			},
 		},
+		{
+			name:     "form question create visible_rule",
+			shortcut: BaseFormQuestionsCreate,
+			wantHelp: []string{
+				`"visible_rule"(display condition; same shape as view filter`,
+			},
+		},
+		{
+			name:     "form question update visible_rule",
+			shortcut: BaseFormQuestionsUpdate,
+			wantHelp: []string{
+				`"visible_rule"(display condition; same shape as view filter`,
+			},
+		},
 		{
 			name:     "record search json",
 			shortcut: BaseRecordSearch,
@@ -1028,6 +1042,39 @@ func TestBaseFieldUpdateHelpGuidesAgents(t *testing.T) {
 	}
 }
 
+func TestBaseFormQuestionsUpdateHelpGuidesFullOverwrite(t *testing.T) {
+	parent := &cobra.Command{Use: "base"}
+	BaseFormQuestionsUpdate.Mount(parent, &cmdutil.Factory{})
+	cmd := parent.Commands()[0]
+
+	help := cmd.Flags().FlagUsages()
+	wantHelp := []string{
+		"Update uses full question overwrite semantics",
+		"run +form-questions-list first",
+		"include existing values you want to keep",
+		"pass null or omit to clear",
+	}
+	for _, want := range wantHelp {
+		if !strings.Contains(help, want) {
+			t.Fatalf("flag help missing %q:\n%s", want, help)
+		}
+	}
+
+	tips := strings.Join(cmdutil.GetTips(cmd), "\n")
+	wantTips := []string{
+		"full question overwrite semantics, not a patch",
+		"Run +form-questions-list first",
+		"title/description/required/option_display_mode/visible_rule",
+		"Omitted fields reset to defaults",
+		"empty strings, null, and empty arrays are written as empty/clear",
+	}
+	for _, want := range wantTips {
+		if !strings.Contains(tips, want) {
+			t.Fatalf("tips missing %q:\n%s", want, tips)
+		}
+	}
+}
+
 func TestBaseAttachmentHelpGuidesAgents(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -2056,8 +2103,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")
@@ -2357,6 +2404,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)
@@ -2425,6 +2473,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 {
@@ -2473,6 +2522,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)
@@ -2484,6 +2534,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()
@@ -2520,6 +2597,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)
@@ -2554,6 +2632,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/calendar/calendar_agenda.go

@@ -250,6 +250,8 @@ var CalendarAgenda = common.Shortcut{
 					}
 				}
 
+				collapseDescription(e)
+
 				filtered = append(filtered, e)
 			}
 		}

shortcuts/calendar/calendar_create.go

@@ -20,7 +20,6 @@ import (
 func buildEventData(runtime *common.RuntimeContext, startTs, endTs string) map[string]interface{} {
 	eventData := map[string]interface{}{
 		"summary":          runtime.Str("summary"),
-		"description":      runtime.Str("description"),
 		"start_time":       map[string]string{"timestamp": startTs},
 		"end_time":         map[string]string{"timestamp": endTs},
 		"attendee_ability": "can_modify_event",
@@ -33,6 +32,9 @@ func buildEventData(runtime *common.RuntimeContext, startTs, endTs string) map[s
 	if rrule := runtime.Str("rrule"); rrule != "" {
 		eventData["recurrence"] = rrule
 	}
+	if description := descriptionToSend(runtime); description != "" {
+		eventData["description_rich"] = description
+	}
 	return eventData
 }
 
@@ -118,7 +120,7 @@ var CalendarCreate = common.Shortcut{
 		{Name: "summary", Desc: "event title"},
 		{Name: "start", Desc: "start time (ISO 8601)", Required: true},
 		{Name: "end", Desc: "end time (ISO 8601)", Required: true},
-		{Name: "description", Desc: "event description"},
+		{Name: "description", Desc: "event description as Markdown (@file or - for stdin); the unified description field. Supports bold/italic/underline/strikethrough, links, headings (`#`..`###`), blockquotes (`>`), ordered/unordered lists, horizontal rules (`---`), GFM tables, and images (`![name](url)`; a remote URL is used as-is, and a local image path relative to and inside the current working directory is auto-uploaded to Lark drive and rendered inline — absolute/out-of-cwd paths are rejected). A Lark doc URL (bare or as a Markdown link) is auto-resolved to an inline doc-mention chip showing its title. Inside a GFM table cell, stack multiple lines with `<br>`; each line may itself be an ordered/unordered list item, image or styled text (e.g. `1. a<br>2. b`, `- x<br>- y`, `![p](url)<br>**bold**`).", Input: []string{common.File, common.Stdin}},
 		{Name: "attendee-ids", Desc: "attendee IDs, comma-separated (supports user ou_, chat oc_, room omm_)"},
 		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
 		{Name: "rrule", Desc: "recurrence rule (rfc5545)"},
@@ -231,6 +233,9 @@ var CalendarCreate = common.Shortcut{
 		if err != nil {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
 		}
+		if err := resolveDescriptionImages(runtime, calendarId); err != nil {
+			return err
+		}
 
 		eventData := buildEventData(runtime, startTs, endTs)
 

shortcuts/calendar/calendar_get.go

@@ -81,6 +81,7 @@ type calendarEvent struct {
 	OrganizerCalendarID string                    `json:"organizer_calendar_id,omitempty"`
 	Summary             string                    `json:"summary,omitempty"`
 	Description         string                    `json:"description,omitempty"`
+	DescriptionRich     string                    `json:"description_rich,omitempty"`
 	StartTime           *calendarEventTime        `json:"start_time,omitempty"`
 	EndTime             *calendarEventTime        `json:"end_time,omitempty"`
 	VChat               *calendarEventVChat       `json:"vchat,omitempty"`
@@ -169,7 +170,7 @@ func buildCalendarEventOutput(event *calendarEvent) (map[string]interface{}, err
 	if status, _ := out["status"].(string); status != "cancelled" {
 		delete(out, "status")
 	}
-
+	collapseDescription(out)
 	return out, nil
 }
 

shortcuts/calendar/calendar_test.go

@@ -988,9 +988,15 @@ func TestUpdate_PatchEventOnly(t *testing.T) {
 	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
 		t.Fatalf("unmarshal captured patch body: %v", err)
 	}
-	if body["summary"] != "Updated Meeting" || body["description"] != "Updated description" {
+	// --description is the unified field, treated as rich text and sent as
+	// description_rich; the CLI never sends the plain description field
+	// (mutually exclusive downstream).
+	if body["summary"] != "Updated Meeting" || body["description_rich"] != "Updated description" {
 		t.Fatalf("unexpected patch body: %#v", body)
 	}
+	if _, ok := body["description"]; ok {
+		t.Fatalf("plain description must not be sent, got: %#v", body)
+	}
 	if body["need_notification"] != false {
 		t.Fatalf("need_notification = %#v, want false", body["need_notification"])
 	}
@@ -1364,6 +1370,62 @@ func TestAgenda_Success(t *testing.T) {
 	}
 }
 
+func TestAgenda_UnifiesDescriptionRich(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/events/instance_view",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{
+						"event_id":         "evt_rich",
+						"summary":          "Rich",
+						"status":           "confirmed",
+						"description":      "[测试]\n友情提醒",
+						"description_rich": "友情提醒",
+						"start_time":       map[string]interface{}{"timestamp": "1742515200"},
+						"end_time":         map[string]interface{}{"timestamp": "1742518800"},
+					},
+					map[string]interface{}{
+						"event_id":    "evt_plain",
+						"summary":     "Plain",
+						"status":      "confirmed",
+						"description": "just text",
+						"start_time":  map[string]interface{}{"timestamp": "1742515200"},
+						"end_time":    map[string]interface{}{"timestamp": "1742518800"},
+					},
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarAgenda, []string{
+		"+agenda",
+		"--start", "2025-03-21",
+		"--end", "2025-03-21",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	// Read exposes a single unified description field: it carries the rich
+	// (Markdown) value when present, and the plain text otherwise. The internal
+	// description_rich key is never surfaced.
+	if !strings.Contains(out, "\"description\": \"友情提醒\"") {
+		t.Errorf("expected rich value surfaced under description, got: %s", out)
+	}
+	if !strings.Contains(out, "\"description\": \"just text\"") {
+		t.Errorf("expected plain description surfaced for plain-only event, got: %s", out)
+	}
+	if strings.Contains(out, "description_rich") {
+		t.Errorf("description_rich must not appear in output, got: %s", out)
+	}
+}
+
 func TestAgenda_EmptyResult(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 
@@ -3375,6 +3437,72 @@ func TestGet_Success_FlattensAndConvertsTimes(t *testing.T) {
 	}
 }
 
+func TestGet_UnifiesDescriptionRich(t *testing.T) {
+	// Read exposes a single unified description field carrying the rich value
+	// when present, and the plain text otherwise; description_rich is dropped.
+	t.Run("rich present", func(t *testing.T) {
+		f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_rich",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "success",
+				"data": map[string]interface{}{
+					"event": map[string]interface{}{
+						"event_id":         "evt_rich",
+						"summary":          "Rich",
+						"description":      "[表格]",
+						"description_rich": "| a | b |\n| --- | --- |\n| c | d |",
+						"start_time":       map[string]interface{}{"timestamp": "1742515200", "timezone": "Asia/Shanghai"},
+						"end_time":         map[string]interface{}{"timestamp": "1742518800", "timezone": "Asia/Shanghai"},
+					},
+				},
+			},
+		})
+		if err := mountAndRun(t, CalendarGet, []string{"+get", "--calendar-id", "cal_test123", "--event-id", "evt_rich", "--as", "bot"}, f, stdout); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		out := stdout.String()
+		if !strings.Contains(out, "| a | b |") {
+			t.Errorf("expected rich value surfaced under description, got: %s", out)
+		}
+		if strings.Contains(out, "description_rich") {
+			t.Errorf("description_rich must not appear in output, got: %s", out)
+		}
+	})
+
+	// When only a plain description exists, it is surfaced under description.
+	t.Run("only plain surfaces under description", func(t *testing.T) {
+		f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_plain",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "success",
+				"data": map[string]interface{}{
+					"event": map[string]interface{}{
+						"event_id":    "evt_plain",
+						"summary":     "Plain",
+						"description": "just text",
+						"start_time":  map[string]interface{}{"timestamp": "1742515200", "timezone": "Asia/Shanghai"},
+						"end_time":    map[string]interface{}{"timestamp": "1742518800", "timezone": "Asia/Shanghai"},
+					},
+				},
+			},
+		})
+		if err := mountAndRun(t, CalendarGet, []string{"+get", "--calendar-id", "cal_test123", "--event-id", "evt_plain", "--as", "bot"}, f, stdout); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		out := stdout.String()
+		if !strings.Contains(out, "\"description\": \"just text\"") {
+			t.Errorf("expected plain description surfaced, got: %s", out)
+		}
+		if strings.Contains(out, "description_rich") {
+			t.Errorf("description_rich must not appear in output, got: %s", out)
+		}
+	})
+}
+
 func TestGet_CancelledStatus_PreservesStatus(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 

shortcuts/calendar/calendar_update.go

@@ -29,7 +29,7 @@ var CalendarUpdate = common.Shortcut{
 		{Name: "event-id", Desc: "event ID to update", Required: true},
 		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
 		{Name: "summary", Desc: "event title"},
-		{Name: "description", Desc: "event description"},
+		{Name: "description", Desc: "event description as Markdown (@file or - for stdin); the unified description field. Supports bold/italic/underline/strikethrough, links, headings (`#`..`###`), blockquotes (`>`), ordered/unordered lists, horizontal rules (`---`), GFM tables, and images (`![name](url)`; a remote URL is used as-is, and a local image path relative to and inside the current working directory is auto-uploaded to Lark drive and rendered inline — absolute/out-of-cwd paths are rejected). A Lark doc URL (bare or as a Markdown link) is auto-resolved to an inline doc-mention chip showing its title. Inside a GFM table cell, stack multiple lines with `<br>`; each line may itself be an ordered/unordered list item, image or styled text (e.g. `1. a<br>2. b`, `- x<br>- y`, `![p](url)<br>**bold**`). Passing an empty string clears the description.", Input: []string{common.File, common.Stdin}},
 		{Name: "start", Desc: "new start time (ISO 8601); requires --end"},
 		{Name: "end", Desc: "new end time (ISO 8601); requires --start"},
 		{Name: "rrule", Desc: "recurrence rule (rfc5545)"},
@@ -109,11 +109,13 @@ func buildCalendarUpdateEventData(runtime *common.RuntimeContext) (map[string]in
 	body := map[string]interface{}{}
 	hasFields := false
 
-	for _, field := range []string{"summary", "description"} {
-		if runtime.Cmd.Flags().Changed(field) {
-			body[field] = runtime.Str(field)
-			hasFields = true
-		}
+	if runtime.Cmd.Flags().Changed("summary") {
+		body["summary"] = runtime.Str("summary")
+		hasFields = true
+	}
+	if runtime.Cmd.Flags().Changed("description") {
+		body["description_rich"] = runtime.Str("description")
+		hasFields = true
 	}
 	if runtime.Cmd.Flags().Changed("rrule") {
 		rrule := strings.TrimSpace(runtime.Str("rrule"))
@@ -356,6 +358,12 @@ func executeCalendarUpdate(ctx context.Context, runtime *common.RuntimeContext)
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --event-id").WithParam("--event-id")
 	}
 
+	if runtime.Cmd.Flags().Changed("description") {
+		if err := resolveDescriptionImages(runtime, calendarID); err != nil {
+			return err
+		}
+	}
+
 	body, hasEventFields, err := buildCalendarUpdateEventData(runtime)
 	if err != nil {
 		return err
@@ -428,8 +436,10 @@ func calendarUpdateResult(eventID string, event map[string]interface{}, addedCou
 	if summary, _ := event["summary"].(string); summary != "" {
 		result["summary"] = summary
 	}
-	if description, _ := event["description"].(string); description != "" {
-		result["description"] = description
+	if rich, _ := event["description_rich"].(string); rich != "" {
+		result["description"] = rich
+	} else if plain, _ := event["description"].(string); plain != "" {
+		result["description"] = plain
 	}
 	if start := formatCalendarEventTime(event["start_time"]); start != "" {
 		result["start"] = start

shortcuts/calendar/description_rich_images.go

@@ -0,0 +1,172 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"fmt"
+	"image"
+
+	// Register the common image decoders so DecodeConfig can read intrinsic
+	// dimensions for PNG/JPEG/GIF sources.
+	_ "image/gif"
+	_ "image/jpeg"
+	_ "image/png"
+	"net/url"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const calendarMediaParentType = "calendar"
+
+var markdownImageRe = regexp.MustCompile(`!\[([^\]]*)\]\(([^)]*)\)`)
+
+func resolveDescriptionImages(runtime *common.RuntimeContext, calendarID string) error {
+	md := runtime.Str("description")
+	if md == "" || !strings.Contains(md, "![") {
+		return nil
+	}
+	rewritten, changed, err := uploadLocalDescriptionImages(runtime, calendarID, md)
+	if err != nil {
+		return err
+	}
+	if changed {
+		if err := runtime.Cmd.Flags().Set("description", rewritten); err != nil {
+			return errs.NewInternalError(errs.SubtypeUnknown, "failed to update --description after image upload: %v", err).WithCause(err)
+		}
+	}
+	return nil
+}
+
+func uploadLocalDescriptionImages(runtime *common.RuntimeContext, calendarID, md string) (string, bool, error) {
+	matches := markdownImageRe.FindAllStringSubmatchIndex(md, -1)
+	if len(matches) == 0 {
+		return md, false, nil
+	}
+	var out strings.Builder
+	last := 0
+	changed := false
+	cache := map[string]string{}
+	for _, m := range matches {
+		altStart, altEnd, srcStart, srcEnd := m[2], m[3], m[4], m[5]
+		src := strings.TrimSpace(md[srcStart:srcEnd])
+		if !isLocalImageSrc(src) {
+			continue
+		}
+		alt := md[altStart:altEnd]
+		uploadedURL, err := resolveLocalImage(runtime, calendarID, src, alt, cache)
+		if err != nil {
+			return "", false, err
+		}
+		out.WriteString(md[last:srcStart])
+		out.WriteString(uploadedURL)
+		last = srcEnd
+		changed = true
+	}
+	if !changed {
+		return md, false, nil
+	}
+	out.WriteString(md[last:])
+	return out.String(), true, nil
+}
+
+func resolveLocalImage(runtime *common.RuntimeContext, calendarID, src, alt string, cache map[string]string) (string, error) {
+	localPath := localImagePath(src)
+	if cached, ok := cache[localPath]; ok {
+		return cached, nil
+	}
+
+	safePath, err := validate.SafeInputPath(localPath)
+	if err != nil {
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"--description image %q could not be read: %v", src, err).
+			WithParam("--description").
+			WithHint("reference local images by a path inside the current working directory (e.g. ./images/pic.png; cd there first), or use an already-uploaded Lark image URL").
+			WithCause(err)
+	}
+
+	info, err := runtime.FileIO().Stat(localPath)
+	if err != nil {
+		return "", common.WrapInputStatErrorTyped(err)
+	}
+
+	fileToken, err := common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
+		FilePath:   localPath,
+		FileName:   filepath.Base(safePath),
+		FileSize:   info.Size(),
+		ParentType: calendarMediaParentType,
+		ParentNode: &calendarID,
+	})
+	if err != nil {
+		return "", err
+	}
+
+	width, height := decodeImageDimensions(runtime, localPath)
+	uploadedURL := buildCalendarImagePreviewURL(runtime.Config.Brand, fileToken, width, height, info.Size())
+	cache[localPath] = uploadedURL
+	return uploadedURL, nil
+}
+
+func decodeImageDimensions(runtime *common.RuntimeContext, path string) (int, int) {
+	f, err := runtime.FileIO().Open(path)
+	if err != nil {
+		return 0, 0
+	}
+	defer f.Close()
+	cfg, _, err := image.DecodeConfig(f)
+	if err != nil {
+		return 0, 0
+	}
+	return cfg.Width, cfg.Height
+}
+
+func isLocalImageSrc(src string) bool {
+	if src == "" {
+		return false
+	}
+	lower := strings.ToLower(src)
+	switch {
+	case strings.HasPrefix(lower, "http://"), strings.HasPrefix(lower, "https://"), strings.HasPrefix(lower, "data:"):
+		return false
+	case strings.HasPrefix(lower, "file://"):
+		return true
+	}
+	if i := strings.Index(src, "://"); i > 0 {
+		return false
+	}
+	return true
+}
+
+func localImagePath(src string) string {
+	s := strings.TrimSpace(src)
+	if strings.HasPrefix(strings.ToLower(s), "file://") {
+		if u, err := url.Parse(s); err == nil && u.Path != "" {
+			s = u.Path
+		}
+	}
+	if decoded, err := url.PathUnescape(s); err == nil {
+		return decoded
+	}
+	return s
+}
+
+func buildCalendarImagePreviewURL(brand core.LarkBrand, fileToken string, width, height int, size int64) string {
+	host := "internal-api-drive-stream.feishu.cn"
+	if brand == core.BrandLark {
+		host = "internal-api-drive-stream.larksuite.com"
+	}
+	u := fmt.Sprintf("https://%s/space/api/box/stream/download/preview/%s?preview_type=16", host, fileToken)
+	if width > 0 && height > 0 {
+		u += fmt.Sprintf("&im_w=%d&im_h=%d", width, height)
+	}
+	if size > 0 {
+		u += fmt.Sprintf("&im_size=%d", size)
+	}
+	return u
+}

shortcuts/calendar/description_rich_images_test.go

@@ -0,0 +1,279 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"image"
+	"image/png"
+	"net/url"
+	"os"
+	"path/filepath"
+	"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"
+)
+
+func TestIsLocalImageSrc(t *testing.T) {
+	cases := []struct {
+		src  string
+		want bool
+	}{
+		{"./images/pic.png", true},
+		{"images/pic.png", true},
+		{"../assets/a.png", true},
+		{"/Users/me/Desktop/a.png", true},
+		{`C:\Users\me\a.png`, true},
+		{"file:///Users/me/a.png", true},
+		{"图片和附件/测试图片.png", true},
+		{"https://example.com/a.png", false},
+		{"http://example.com/a.png", false},
+		{"HTTPS://EXAMPLE.com/a.png", false},
+		{"data:image/png;base64,iVBOR", false},
+		{"ftp://host/a.png", false},
+		{"", false},
+	}
+	for _, c := range cases {
+		if got := isLocalImageSrc(c.src); got != c.want {
+			t.Errorf("isLocalImageSrc(%q) = %v, want %v", c.src, got, c.want)
+		}
+	}
+}
+
+func TestLocalImagePath(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"images/pic.png", "images/pic.png"},
+		{"images/my%20pic.png", "images/my pic.png"},
+		{"file:///Users/me/a.png", "/Users/me/a.png"},
+	}
+	for _, c := range cases {
+		if got := localImagePath(c.in); got != c.want {
+			t.Errorf("localImagePath(%q) = %q, want %q", c.in, got, c.want)
+		}
+	}
+}
+
+// TestBuildCalendarImagePreviewURL guards the contract the OpenAPI service
+// relies on: a Lark host (so token extraction triggers) whose final path
+// segment is exactly the uploaded file token.
+func TestBuildCalendarImagePreviewURL(t *testing.T) {
+	for _, tc := range []struct {
+		brand    core.LarkBrand
+		hostFrag string
+	}{
+		{core.BrandFeishu, "feishu.cn"},
+		{core.BrandLark, "larksuite"},
+	} {
+		raw := buildCalendarImagePreviewURL(tc.brand, "boxcnTOKEN123", 416, 306, 142568)
+		u, err := url.Parse(raw)
+		if err != nil {
+			t.Fatalf("built URL not parseable: %v", err)
+		}
+		if !strings.Contains(u.Host, tc.hostFrag) {
+			t.Errorf("brand %s host = %q, want fragment %q", tc.brand, u.Host, tc.hostFrag)
+		}
+		segs := strings.Split(strings.Trim(u.Path, "/"), "/")
+		if last := segs[len(segs)-1]; last != "boxcnTOKEN123" {
+			t.Errorf("last path segment = %q, want token", last)
+		}
+		q := u.Query()
+		if q.Get("im_w") != "416" || q.Get("im_h") != "306" || q.Get("im_size") != "142568" {
+			t.Errorf("dimension params missing: im_w=%q im_h=%q im_size=%q", q.Get("im_w"), q.Get("im_h"), q.Get("im_size"))
+		}
+	}
+
+	// With unknown dimensions the helper params are omitted entirely.
+	raw := buildCalendarImagePreviewURL(core.BrandFeishu, "boxcnTOKEN123", 0, 0, 0)
+	if strings.Contains(raw, "im_w") || strings.Contains(raw, "im_size") {
+		t.Errorf("expected no dimension params for unknown size, got %q", raw)
+	}
+}
+
+// TestUploadLocalDescriptionImages_RemoteUntouched verifies remote/data images
+// pass through unchanged and never trigger an upload (runtime unused → nil).
+func TestUploadLocalDescriptionImages_RemoteUntouched(t *testing.T) {
+	md := "text ![a](https://example.com/a.png) more ![b](data:image/png;base64,xx)"
+	got, changed, err := uploadLocalDescriptionImages(nil, "cal", md)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if changed {
+		t.Errorf("changed = true, want false")
+	}
+	if got != md {
+		t.Errorf("markdown mutated: %q", got)
+	}
+}
+
+// TestCreate_UploadsLocalDescriptionImage runs +create with a local image path,
+// mocks the drive upload, and asserts the create body's description_rich carries
+// the uploaded token (not the local path).
+func TestCreate_UploadsLocalDescriptionImage(t *testing.T) {
+	dir := t.TempDir()
+	orig, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Chdir(orig)
+	if err := os.WriteFile(filepath.Join(dir, "pic.png"), []byte("PNGDATA"), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	uploadStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"file_token": "boxcnTOKEN123"}},
+	}
+	reg.Register(uploadStub)
+
+	createStub := &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_001",
+				"summary":    "Pic",
+				"start_time": map[string]interface{}{"timestamp": "1742515200"},
+				"end_time":   map[string]interface{}{"timestamp": "1742518800"},
+			},
+		}},
+	}
+	reg.Register(createStub)
+
+	runErr := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Pic",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--description", "![pic](./pic.png)",
+		"--as", "bot",
+	}, f, stdout)
+	if runErr != nil {
+		t.Fatalf("unexpected error: %v", runErr)
+	}
+
+	if uploadStub.CapturedBody == nil {
+		t.Fatalf("expected drive upload to be called")
+	}
+	if createStub.CapturedBody == nil {
+		t.Fatalf("expected create event to be called")
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(createStub.CapturedBody, &body); err != nil {
+		t.Fatalf("create body unmarshal: %v", err)
+	}
+	dr, _ := body["description_rich"].(string)
+	if !strings.Contains(dr, "boxcnTOKEN123") {
+		t.Fatalf("description_rich should contain uploaded token, got %q", dr)
+	}
+	if strings.Contains(dr, "./pic.png") {
+		t.Fatalf("local path should be rewritten away, got %q", dr)
+	}
+}
+
+// TestCreate_LocalImageCarriesDimensions verifies a real decodable image's
+// intrinsic width/height and byte size are appended to the rewritten drive URL
+// (so the facade can populate originalWidth/originalHeight and the client can
+// render the image inline).
+func TestCreate_LocalImageCarriesDimensions(t *testing.T) {
+	dir := t.TempDir()
+	orig, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Chdir(orig)
+
+	var buf bytes.Buffer
+	if err := png.Encode(&buf, image.NewRGBA(image.Rect(0, 0, 5, 7))); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "pic.png"), buf.Bytes(), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"file_token": "boxcnTOKEN123"}},
+	})
+	createStub := &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_001",
+				"summary":    "Pic",
+				"start_time": map[string]interface{}{"timestamp": "1742515200"},
+				"end_time":   map[string]interface{}{"timestamp": "1742518800"},
+			},
+		}},
+	}
+	reg.Register(createStub)
+
+	runErr := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Pic",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--description", "![pic](./pic.png)",
+		"--as", "bot",
+	}, f, stdout)
+	if runErr != nil {
+		t.Fatalf("unexpected error: %v", runErr)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(createStub.CapturedBody, &body); err != nil {
+		t.Fatalf("create body unmarshal: %v", err)
+	}
+	dr, _ := body["description_rich"].(string)
+	if !strings.Contains(dr, "im_w=5") || !strings.Contains(dr, "im_h=7") {
+		t.Fatalf("description_rich should carry image dimensions, got %q", dr)
+	}
+	if !strings.Contains(dr, "im_size=") {
+		t.Fatalf("description_rich should carry image byte size, got %q", dr)
+	}
+}
+
+// TestCreate_LocalImageAbsolutePathRejected verifies an out-of-cwd absolute path
+// yields a typed --description validation error before any API call.
+func TestCreate_LocalImageAbsolutePathRejected(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	runErr := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Pic",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--description", "![p](/etc/hosts)",
+		"--as", "bot",
+	}, f, stdout)
+	if runErr == nil {
+		t.Fatalf("expected error for absolute image path")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(runErr, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", runErr, runErr)
+	}
+	if ve.Param != "--description" {
+		t.Errorf("param = %q, want --description", ve.Param)
+	}
+}

shortcuts/calendar/helpers.go

@@ -30,6 +30,26 @@ func resolveStartEnd(runtime *common.RuntimeContext) (string, string) {
 	return startInput, endInput
 }
 
+func collapseDescription(event map[string]interface{}) {
+	if event == nil {
+		return
+	}
+	rich, _ := event["description_rich"].(string)
+	plain, _ := event["description"].(string)
+	delete(event, "description_rich")
+	switch {
+	case rich != "":
+		event["description"] = rich
+	case plain != "":
+		event["description"] = plain
+	default:
+		delete(event, "description")
+	}
+}
+func descriptionToSend(runtime *common.RuntimeContext) string {
+	return runtime.Str("description")
+}
+
 func hasExplicitBotFlag(cmd *cobra.Command) bool {
 	if cmd == nil {
 		return false

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/drive/drive_member_list.go

@@ -0,0 +1,325 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/url"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type driveMemberListSpec struct {
+	Token    string
+	Type     string
+	Fields   string
+	PermType string
+}
+
+var driveMemberListTypes = []string{
+	"doc", "sheet", "file", "wiki", "bitable", "docx",
+	"mindnote", "minutes", "slides", "folder",
+}
+
+var driveMemberListFields = []string{"name", "type", "avatar", "external_label"}
+var driveMemberListPermTypes = []string{"container", "single_page"}
+
+var driveMemberListURLPathToType = []struct {
+	Prefix string
+	Type   string
+}{
+	{"/drive/folder/", "folder"},
+	{"/docx/", "docx"},
+	{"/doc/", "doc"},
+	{"/sheets/", "sheet"},
+	{"/base/", "bitable"},
+	{"/bitable/", "bitable"},
+	{"/wiki/", "wiki"},
+	{"/file/", "file"},
+	{"/mindnotes/", "mindnote"},
+	{"/slides/", "slides"},
+	{"/minutes/", "minutes"},
+}
+
+func readDriveMemberListSpec(runtime *common.RuntimeContext) (driveMemberListSpec, error) {
+	token, resourceType, err := resolveDriveMemberListTarget(runtime.Str("token"), runtime.Str("type"))
+	if err != nil {
+		return driveMemberListSpec{}, err
+	}
+	fields, err := normalizeDriveMemberListFields(runtime.Str("fields"), runtime.Changed("fields"))
+	if err != nil {
+		return driveMemberListSpec{}, err
+	}
+	permType, err := normalizeDriveMemberListPermType(runtime.Str("perm-type"), resourceType, runtime.Changed("perm-type"))
+	if err != nil {
+		return driveMemberListSpec{}, err
+	}
+	return driveMemberListSpec{
+		Token:    token,
+		Type:     resourceType,
+		Fields:   fields,
+		PermType: permType,
+	}, nil
+}
+
+func resolveDriveMemberListTarget(raw, explicitType string) (token, resourceType string, err error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--token is required").WithParam("--token")
+	}
+
+	explicitType, err = normalizeDriveMemberListEnumValue(explicitType, driveMemberListTypes, "--type")
+	if err != nil {
+		return "", "", err
+	}
+
+	if strings.Contains(raw, "://") {
+		parsed, parseErr := url.Parse(raw)
+		if parseErr != nil || parsed.Hostname() == "" {
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--token URL is malformed: %q", raw).WithParam("--token")
+		}
+		ref, ok := parseDriveMemberListResourceURLPath(parsed.Path)
+		if !ok {
+			return "", "", errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"unsupported --token URL %q: pass a recognized Lark Drive document/folder URL or a bare token with --type",
+				raw,
+			).WithParam("--token")
+		}
+		if explicitType != "" && explicitType != ref.Type {
+			return "", "", errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"--type %q conflicts with URL path type %q; remove --type or use a matching value",
+				explicitType,
+				ref.Type,
+			).WithParam("--type")
+		}
+		if err := validate.ResourceName(ref.Token, "--token"); err != nil {
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+		}
+		return ref.Token, ref.Type, nil
+	}
+
+	if explicitType == "" {
+		return "", "", errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--type is required when --token is a bare token; accepted values: %s",
+			strings.Join(driveMemberListTypes, ", "),
+		).WithParam("--type")
+	}
+	if err := validate.ResourceName(raw, "--token"); err != nil {
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+	}
+	return raw, explicitType, nil
+}
+
+func parseDriveMemberListResourceURLPath(path string) (common.ResourceRef, bool) {
+	for _, mapping := range driveMemberListURLPathToType {
+		if !strings.HasPrefix(path, mapping.Prefix) {
+			continue
+		}
+		token := path[len(mapping.Prefix):]
+		token = strings.TrimRight(token, "/")
+		if idx := strings.IndexByte(token, '/'); idx >= 0 {
+			token = token[:idx]
+		}
+		token = strings.TrimSpace(token)
+		if token == "" {
+			return common.ResourceRef{}, false
+		}
+		return common.ResourceRef{Type: mapping.Type, Token: token}, true
+	}
+	return common.ResourceRef{}, false
+}
+
+func normalizeDriveMemberListFields(raw string, changed bool) (string, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		if changed {
+			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--fields cannot be blank; allowed: %s, *", strings.Join(driveMemberListFields, ", ")).WithParam("--fields")
+		}
+		return "", nil
+	}
+
+	parts := strings.Split(raw, ",")
+	fields := make([]string, 0, len(parts))
+	seen := make(map[string]bool, len(parts))
+	for _, part := range parts {
+		field := strings.ToLower(strings.TrimSpace(part))
+		if field == "" {
+			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--fields contains an empty field; allowed: %s, *", strings.Join(driveMemberListFields, ", ")).WithParam("--fields")
+		}
+		if field == "*" {
+			if len(parts) != 1 {
+				return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--fields=* cannot be combined with other fields").WithParam("--fields")
+			}
+			return "*", nil
+		}
+		if !driveMemberListFieldAllowed(field) {
+			return "", errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"invalid value %q for --fields, allowed: %s, *",
+				strings.TrimSpace(part),
+				strings.Join(driveMemberListFields, ", "),
+			).WithParam("--fields")
+		}
+		if !seen[field] {
+			fields = append(fields, field)
+			seen[field] = true
+		}
+	}
+	return strings.Join(fields, ","), nil
+}
+
+func driveMemberListFieldAllowed(field string) bool {
+	for _, allowed := range driveMemberListFields {
+		if field == allowed {
+			return true
+		}
+	}
+	return false
+}
+
+func normalizeDriveMemberListPermType(raw, resourceType string, changed bool) (string, error) {
+	permType, err := normalizeDriveMemberListEnumValue(raw, driveMemberListPermTypes, "--perm-type")
+	if err != nil {
+		return "", err
+	}
+	if resourceType != "wiki" && changed {
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--perm-type only applies when resource type is wiki; got %q", resourceType).WithParam("--perm-type")
+	}
+	return permType, nil
+}
+
+func normalizeDriveMemberListEnumValue(raw string, allowed []string, flagName string) (string, error) {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		return "", nil
+	}
+	for _, candidate := range allowed {
+		if strings.EqualFold(value, candidate) {
+			return candidate, nil
+		}
+	}
+	return "", errs.NewValidationError(
+		errs.SubtypeInvalidArgument,
+		"invalid value %q for %s, allowed: %s",
+		value,
+		flagName,
+		strings.Join(allowed, ", "),
+	).WithParam(flagName)
+}
+
+func (s driveMemberListSpec) apiPath() string {
+	return fmt.Sprintf("/open-apis/drive/v1/permissions/%s/members", validate.EncodePathSegment(s.Token))
+}
+
+func (s driveMemberListSpec) params() map[string]interface{} {
+	params := map[string]interface{}{"type": s.Type}
+	if s.Fields != "" {
+		params["fields"] = s.Fields
+	}
+	if s.PermType != "" {
+		params["perm_type"] = s.PermType
+	}
+	return params
+}
+
+// DriveMemberList lists collaborator/member permissions on a Drive resource.
+var DriveMemberList = common.Shortcut{
+	Service:     "drive",
+	Command:     "+member-list",
+	Description: "List collaborator/member permissions on a Drive document, file, folder, or wiki node",
+	Risk:        "read",
+	Scopes:      []string{"docs:permission.member:retrieve"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "token", Desc: "target URL or bare token (doc/sheet/file/wiki/bitable/docx/mindnote/minutes/slides/folder)", Required: true},
+		{Name: "type", Desc: "target type; auto-inferred from URL, required for bare tokens"},
+		{Name: "fields", Desc: "optional collaborator fields to return: name,type,avatar,external_label or *"},
+		{Name: "perm-type", Desc: "wiki permission scope filter; one of container|single_page"},
+	},
+	Tips: []string{
+		"--token accepts a Lark URL or bare token; pass --type when using a bare token.",
+		"Use --type folder for Drive folders.",
+		"--fields is omitted by default; pass --fields '*' or a comma-separated subset when extra collaborator fields are needed.",
+		"--perm-type only applies to wiki nodes.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := readDriveMemberListSpec(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec, err := readDriveMemberListSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			Desc("List Drive collaborator/member permissions").
+			GET(spec.apiPath()).
+			Params(spec.params())
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec, err := readDriveMemberListSpec(runtime)
+		if err != nil {
+			return err
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Listing Drive members for %s %s...\n", spec.Type, common.MaskToken(spec.Token))
+		data, err := runtime.CallAPITyped("GET", spec.apiPath(), spec.params(), nil)
+		if err != nil {
+			return err
+		}
+		if items, ok := data["items"].([]interface{}); ok {
+			fmt.Fprintf(runtime.IO().ErrOut, "Found %d Drive member(s)\n", len(items))
+		}
+		runtime.OutFormat(data, nil, func(w io.Writer) {
+			renderDriveMemberListPretty(w, data)
+		})
+		return nil
+	},
+}
+
+func renderDriveMemberListPretty(w io.Writer, data map[string]interface{}) {
+	items, _ := data["items"].([]interface{})
+	if len(items) == 0 {
+		fmt.Fprintln(w, "No Drive members found.")
+		return
+	}
+	for i, raw := range items {
+		member, _ := raw.(map[string]interface{})
+		fmt.Fprintf(w, "[%d] %s\n", i+1, driveMemberListValue(member["member_id"]))
+		fmt.Fprintf(w, "    member_type: %s\n", driveMemberListValue(member["member_type"]))
+		fmt.Fprintf(w, "    perm:        %s\n", driveMemberListValue(member["perm"]))
+		if permType := driveMemberListValue(member["perm_type"]); permType != "-" {
+			fmt.Fprintf(w, "    perm_type:   %s\n", permType)
+		}
+		if memberType := driveMemberListValue(member["type"]); memberType != "-" {
+			fmt.Fprintf(w, "    type:        %s\n", memberType)
+		}
+		if name := driveMemberListValue(member["name"]); name != "-" {
+			fmt.Fprintf(w, "    name:        %s\n", name)
+		}
+		if avatar := driveMemberListValue(member["avatar"]); avatar != "-" {
+			fmt.Fprintf(w, "    avatar:      %s\n", avatar)
+		}
+		if label, ok := member["external_label"]; ok {
+			fmt.Fprintf(w, "    external_label: %v\n", label)
+		}
+		fmt.Fprintln(w)
+	}
+}
+
+func driveMemberListValue(v interface{}) string {
+	if s, ok := v.(string); ok && s != "" {
+		return s
+	}
+	return "-"
+}

shortcuts/drive/drive_member_list_test.go

@@ -0,0 +1,426 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"encoding/json"
+	"net/http"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func newDriveMemberListRuntime(t *testing.T, token, docType, fields, permType string) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "drive +member-list"}
+	cmd.Flags().String("token", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("fields", "", "")
+	cmd.Flags().String("perm-type", "", "")
+	for name, value := range map[string]string{
+		"token":     token,
+		"type":      docType,
+		"fields":    fields,
+		"perm-type": permType,
+	} {
+		if value == "" {
+			continue
+		}
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set --%s: %v", name, err)
+		}
+	}
+	return common.TestNewRuntimeContext(cmd, driveTestConfig())
+}
+
+func TestDriveMemberListSpecResolvesTargets(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		token    string
+		docType  string
+		wantTok  string
+		wantType string
+	}{
+		{
+			name:     "folder URL",
+			token:    "https://example.feishu.cn/drive/folder/fldTok?from=share",
+			wantTok:  "fldTok",
+			wantType: "folder",
+		},
+		{
+			name:     "docx URL",
+			token:    "https://example.feishu.cn/docx/doxTok",
+			wantTok:  "doxTok",
+			wantType: "docx",
+		},
+		{
+			name:     "bare folder token",
+			token:    " fldTok ",
+			docType:  " folder ",
+			wantTok:  "fldTok",
+			wantType: "folder",
+		},
+		{
+			name:     "mindnotes URL",
+			token:    "https://example.feishu.cn/mindnotes/mndTok",
+			wantTok:  "mndTok",
+			wantType: "mindnote",
+		},
+		{
+			name:     "minutes URL",
+			token:    "https://example.feishu.cn/minutes/obTok",
+			wantTok:  "obTok",
+			wantType: "minutes",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDriveMemberListRuntime(t, tt.token, tt.docType, "", "")
+			spec, err := readDriveMemberListSpec(runtime)
+			if err != nil {
+				t.Fatalf("read spec: %v", err)
+			}
+			if spec.Token != tt.wantTok || spec.Type != tt.wantType {
+				t.Fatalf("spec token/type = %q/%q, want %q/%q", spec.Token, spec.Type, tt.wantTok, tt.wantType)
+			}
+		})
+	}
+}
+
+func TestDriveMemberListSpecValidationErrorsAreTyped(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		token       string
+		docType     string
+		fields      string
+		permType    string
+		wantParam   string
+		wantMessage string
+	}{
+		{
+			name:        "missing token",
+			wantParam:   "--token",
+			wantMessage: "--token is required",
+		},
+		{
+			name:        "bare token without type",
+			token:       "doxTok",
+			wantParam:   "--type",
+			wantMessage: "--type is required",
+		},
+		{
+			name:        "unsupported URL",
+			token:       "https://example.feishu.cn/calendar/calTok",
+			wantParam:   "--token",
+			wantMessage: "unsupported --token URL",
+		},
+		{
+			name:        "URL type conflict",
+			token:       "https://example.feishu.cn/docx/doxTok",
+			docType:     "folder",
+			wantParam:   "--type",
+			wantMessage: "conflicts with URL path type",
+		},
+		{
+			name:        "invalid bare token",
+			token:       "../bad",
+			docType:     "folder",
+			wantParam:   "--token",
+			wantMessage: "--token",
+		},
+		{
+			name:        "invalid type",
+			token:       "doxTok",
+			docType:     "comment",
+			wantParam:   "--type",
+			wantMessage: "invalid value",
+		},
+		{
+			name:        "invalid fields",
+			token:       "doxTok",
+			docType:     "docx",
+			fields:      "name,unknown",
+			wantParam:   "--fields",
+			wantMessage: "invalid value",
+		},
+		{
+			name:        "star mixed with fields",
+			token:       "doxTok",
+			docType:     "docx",
+			fields:      "*,name",
+			wantParam:   "--fields",
+			wantMessage: "cannot be combined",
+		},
+		{
+			name:        "perm type rejected for non-wiki",
+			token:       "doxTok",
+			docType:     "docx",
+			permType:    "single_page",
+			wantParam:   "--perm-type",
+			wantMessage: "only applies when resource type is wiki",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDriveMemberListRuntime(t, tt.token, tt.docType, tt.fields, tt.permType)
+			_, err := readDriveMemberListSpec(runtime)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %v", err, err)
+			}
+			if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("problem = %s/%s, want validation/invalid_argument", problem.Category, problem.Subtype)
+			}
+			validationErr, ok := err.(*errs.ValidationError)
+			if !ok {
+				t.Fatalf("error type = %T, want *errs.ValidationError", err)
+			}
+			if validationErr.Param != tt.wantParam {
+				t.Fatalf("param = %q, want %q", validationErr.Param, tt.wantParam)
+			}
+			if !strings.Contains(err.Error(), tt.wantMessage) {
+				t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantMessage)
+			}
+		})
+	}
+}
+
+func TestDriveMemberListSpecParams(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		token    string
+		docType  string
+		fields   string
+		permType string
+		want     map[string]interface{}
+	}{
+		{
+			name:    "default omits optional params",
+			token:   "doxTok",
+			docType: "docx",
+			want:    map[string]interface{}{"type": "docx"},
+		},
+		{
+			name:    "fields canonicalized and deduplicated",
+			token:   "doxTok",
+			docType: "docx",
+			fields:  "Name,avatar,name",
+			want:    map[string]interface{}{"type": "docx", "fields": "name,avatar"},
+		},
+		{
+			name:     "wiki accepts perm type",
+			token:    "wikTok",
+			docType:  "WIKI",
+			fields:   "*",
+			permType: "SINGLE_PAGE",
+			want:     map[string]interface{}{"type": "wiki", "fields": "*", "perm_type": "single_page"},
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDriveMemberListRuntime(t, tt.token, tt.docType, tt.fields, tt.permType)
+			spec, err := readDriveMemberListSpec(runtime)
+			if err != nil {
+				t.Fatalf("read spec: %v", err)
+			}
+			if got := spec.params(); !reflect.DeepEqual(got, tt.want) {
+				t.Fatalf("params = %#v, want %#v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestDriveMemberListDryRunIncludesGETRequest(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+	err := mountAndRunDrive(t, DriveMemberList, []string{
+		"+member-list",
+		"--token", "https://example.feishu.cn/drive/folder/fldTok",
+		"--fields", "*",
+		"--dry-run",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var got struct {
+		Data struct {
+			API []struct {
+				Method string                 `json:"method"`
+				URL    string                 `json:"url"`
+				Params map[string]interface{} `json:"params"`
+			} `json:"api"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("decode dry-run output: %v\n%s", err, stdout.String())
+	}
+	if len(got.Data.API) != 1 {
+		t.Fatalf("api count = %d, want 1", len(got.Data.API))
+	}
+	api := got.Data.API[0]
+	if api.Method != "GET" || api.URL != "/open-apis/drive/v1/permissions/fldTok/members" {
+		t.Fatalf("api = %#v", api)
+	}
+	if api.Params["type"] != "folder" || api.Params["fields"] != "*" {
+		t.Fatalf("params = %#v", api.Params)
+	}
+	if _, ok := api.Params["perm_type"]; ok {
+		t.Fatalf("perm_type should be omitted for folder: %#v", api.Params)
+	}
+}
+
+func TestDriveMemberListExecutePreservesRawData(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, stdout, stderr, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	var capturedQuery string
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/permissions/doxTok/members",
+		OnMatch: func(req *http.Request) {
+			capturedQuery = req.URL.RawQuery
+		},
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "success",
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{
+						"member_id":      "ou_x",
+						"member_type":    "openid",
+						"perm":           "view",
+						"type":           "user",
+						"name":           "zhangsan",
+						"server_future":  "preserved",
+						"external_label": true,
+					},
+				},
+				"server_top_level": "preserved",
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveMemberList, []string{
+		"+member-list",
+		"--token", "doxTok",
+		"--type", "docx",
+		"--fields", "name,type,external_label",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(capturedQuery, "type=docx") ||
+		!strings.Contains(capturedQuery, "fields=name%2Ctype%2Cexternal_label") {
+		t.Fatalf("captured query = %q", capturedQuery)
+	}
+	data := decodeDriveEnvelope(t, stdout)
+	if data["server_top_level"] != "preserved" {
+		t.Fatalf("server_top_level = %#v", data["server_top_level"])
+	}
+	for _, key := range []string{"token", "type", "count"} {
+		if _, ok := data[key]; ok {
+			t.Fatalf("data[%s] = %#v, want omitted", key, data[key])
+		}
+	}
+	items, _ := data["items"].([]interface{})
+	if len(items) != 1 {
+		t.Fatalf("items = %#v, want one item", data["items"])
+	}
+	item, _ := items[0].(map[string]interface{})
+	if item["server_future"] != "preserved" || item["external_label"] != true {
+		t.Fatalf("item future fields not preserved: %#v", item)
+	}
+	if !strings.Contains(stderr.String(), "Found 1 Drive member") {
+		t.Fatalf("stderr = %q, want count log", stderr.String())
+	}
+}
+
+func TestDriveMemberListDeclaresScopeAndIdentities(t *testing.T) {
+	t.Parallel()
+
+	if !reflect.DeepEqual(DriveMemberList.Scopes, []string{"docs:permission.member:retrieve"}) {
+		t.Fatalf("Scopes = %v, want docs:permission.member:retrieve", DriveMemberList.Scopes)
+	}
+	if !reflect.DeepEqual(DriveMemberList.AuthTypes, []string{"user", "bot"}) {
+		t.Fatalf("AuthTypes = %v, want [user bot]", DriveMemberList.AuthTypes)
+	}
+}
+
+func TestDriveMemberListPrettyOutput(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v1/permissions/wikTok/members",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "success",
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{
+						"member_id":   "ou_x",
+						"member_type": "openid",
+						"perm":        "view",
+						"perm_type":   "single_page",
+						"type":        "user",
+						"name":        "zhangsan",
+					},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveMemberList, []string{
+		"+member-list",
+		"--token", "wikTok",
+		"--type", "wiki",
+		"--perm-type", "single_page",
+		"--format", "pretty",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"[1] ou_x", "member_type: openid", "perm_type:   single_page", "name:        zhangsan"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("pretty output missing %q:\n%s", want, out)
+		}
+	}
+}

shortcuts/drive/drive_permission_get_setting.go

@@ -0,0 +1,241 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/url"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type drivePermissionGetSettingSpec struct {
+	Token string
+	Type  string
+}
+
+var drivePermissionGetSettingTypes = []string{
+	"doc", "sheet", "file", "wiki", "bitable", "docx",
+	"mindnote", "minutes", "slides", "folder",
+}
+
+var drivePermissionGetSettingURLPathToType = []struct {
+	Prefix string
+	Type   string
+}{
+	{"/drive/folder/", "folder"},
+	{"/docx/", "docx"},
+	{"/doc/", "doc"},
+	{"/sheets/", "sheet"},
+	{"/base/", "bitable"},
+	{"/bitable/", "bitable"},
+	{"/wiki/", "wiki"},
+	{"/file/", "file"},
+	{"/mindnotes/", "mindnote"},
+	{"/slides/", "slides"},
+	{"/minutes/", "minutes"},
+}
+
+func readDrivePermissionGetSettingSpec(runtime *common.RuntimeContext) (drivePermissionGetSettingSpec, error) {
+	rawToken := strings.TrimSpace(runtime.Str("token"))
+	explicitType := strings.ToLower(strings.TrimSpace(runtime.Str("type")))
+
+	if rawToken == "" {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--token is required",
+		).WithParam("--token")
+	}
+
+	if explicitType != "" && !drivePermissionGetSettingTypeAllowed(explicitType) {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"invalid --type %q: allowed values are %s",
+			explicitType,
+			strings.Join(drivePermissionGetSettingTypes, ", "),
+		).WithParam("--type")
+	}
+
+	if strings.Contains(rawToken, "://") {
+		ref, ok := parseDrivePermissionGetSettingResourceURL(rawToken)
+		if !ok {
+			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"unsupported --token URL %q: pass a recognized Lark Drive document/folder URL or a bare token with --type",
+				rawToken,
+			).WithParam("--token")
+		}
+		if explicitType != "" && explicitType != ref.Type {
+			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"--type %q conflicts with URL path type %q; remove --type or use a matching value",
+				explicitType,
+				ref.Type,
+			).WithParam("--type")
+		}
+		if err := validate.ResourceName(ref.Token, "--token"); err != nil {
+			return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+		}
+		return drivePermissionGetSettingSpec{Token: ref.Token, Type: ref.Type}, nil
+	}
+
+	if explicitType == "" {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--type is required when --token is a bare token (allowed: %s)",
+			strings.Join(drivePermissionGetSettingTypes, ", "),
+		).WithParam("--type")
+	}
+
+	if err := validate.ResourceName(rawToken, "--token"); err != nil {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+	}
+	return drivePermissionGetSettingSpec{Token: rawToken, Type: explicitType}, nil
+}
+
+func parseDrivePermissionGetSettingResourceURL(rawURL string) (common.ResourceRef, bool) {
+	parsed, err := url.Parse(strings.TrimSpace(rawURL))
+	if err != nil || parsed.Hostname() == "" {
+		return common.ResourceRef{}, false
+	}
+
+	for _, mapping := range drivePermissionGetSettingURLPathToType {
+		if !strings.HasPrefix(parsed.Path, mapping.Prefix) {
+			continue
+		}
+		token := parsed.Path[len(mapping.Prefix):]
+		token = strings.TrimRight(token, "/")
+		if idx := strings.IndexByte(token, '/'); idx >= 0 {
+			token = token[:idx]
+		}
+		token = strings.TrimSpace(token)
+		if token == "" {
+			return common.ResourceRef{}, false
+		}
+		return common.ResourceRef{Type: mapping.Type, Token: token}, true
+	}
+
+	return common.ResourceRef{}, false
+}
+
+func drivePermissionGetSettingTypeAllowed(docType string) bool {
+	for _, allowed := range drivePermissionGetSettingTypes {
+		if docType == allowed {
+			return true
+		}
+	}
+	return false
+}
+
+func (s drivePermissionGetSettingSpec) url(runtime *common.RuntimeContext) string {
+	if runtime != nil && runtime.Config != nil {
+		if u := common.BuildResourceURL(runtime.Config.Brand, s.Type, s.Token); u != "" {
+			return u
+		}
+	}
+	return common.BuildResourceURL("", s.Type, s.Token)
+}
+
+func (s drivePermissionGetSettingSpec) params() map[string]interface{} {
+	return map[string]interface{}{"type": s.Type}
+}
+
+func (s drivePermissionGetSettingSpec) apiPath() string {
+	return drivePermissionPublicV2Path(s.Token)
+}
+
+func drivePermissionPublicV2Path(token string) string {
+	return fmt.Sprintf("/open-apis/drive/v2/permissions/%s/public", validate.EncodePathSegment(token))
+}
+
+func drivePermissionGetSettingPermissionPublic(data map[string]interface{}) (map[string]interface{}, error) {
+	permissionPublic := common.GetMap(data, "permission_public")
+	if permissionPublic == nil {
+		return nil, errs.NewInternalError(
+			errs.SubtypeInvalidResponse,
+			"drive permission get response missing data.permission_public",
+		)
+	}
+	return permissionPublic, nil
+}
+
+// DrivePermissionGetSetting queries permission_public settings for a Drive
+// document, file, wiki node, or folder.
+var DrivePermissionGetSetting = common.Shortcut{
+	Service:     "drive",
+	Command:     "+permission-get-setting",
+	Description: "Get public access, sharing, collaborator management, security, and comment permission settings",
+	Risk:        "read",
+	Scopes:      []string{"docs:permission.setting:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "token", Desc: "target URL or bare token (doc/sheet/file/wiki/bitable/docx/mindnote/minutes/slides/folder)", Required: true},
+		{Name: "type", Desc: "target type; auto-inferred from URL, required for bare tokens", Enum: drivePermissionGetSettingTypes},
+	},
+	Tips: []string{
+		"--token accepts a Lark URL or bare token; pass --type when using a bare token.",
+		"Use --type folder for Drive folders. This shortcut reads the target's own permission settings; it does not recurse into child documents.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := readDrivePermissionGetSettingSpec(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec, err := readDrivePermissionGetSettingSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			Desc("Get Drive permission settings").
+			GET(spec.apiPath()).
+			Params(spec.params())
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec, err := readDrivePermissionGetSettingSpec(runtime)
+		if err != nil {
+			return err
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Getting permission settings for %s %s...\n", spec.Type, common.MaskToken(spec.Token))
+		data, err := runtime.CallAPITyped(
+			"GET",
+			spec.apiPath(),
+			spec.params(),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+
+		permissionPublic, err := drivePermissionGetSettingPermissionPublic(data)
+		if err != nil {
+			return err
+		}
+		permissionPublicPretty, err := json.MarshalIndent(permissionPublic, "", "  ")
+		if err != nil {
+			return errs.NewInternalError(
+				errs.SubtypeInvalidResponse,
+				"encode drive permission settings for pretty output",
+			).WithCause(err)
+		}
+
+		out := map[string]interface{}{"permission_public": permissionPublic}
+		runtime.OutFormat(out, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Type:  %s\n", spec.Type)
+			fmt.Fprintf(w, "Token: %s\n", spec.Token)
+			if url := spec.url(runtime); url != "" {
+				fmt.Fprintf(w, "URL:   %s\n", url)
+			}
+			fmt.Fprintf(w, "Permission settings:\n%s\n", permissionPublicPretty)
+		})
+		return nil
+	},
+}

shortcuts/drive/drive_permission_get_setting_test.go

@@ -0,0 +1,438 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func newDrivePermissionGetSettingRuntime(t *testing.T, token, docType string) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "drive +permission-get-setting"}
+	cmd.Flags().String("token", "", "")
+	cmd.Flags().String("type", "", "")
+	if token != "" {
+		if err := cmd.Flags().Set("token", token); err != nil {
+			t.Fatalf("set --token: %v", err)
+		}
+	}
+	if docType != "" {
+		if err := cmd.Flags().Set("type", docType); err != nil {
+			t.Fatalf("set --type: %v", err)
+		}
+	}
+	return common.TestNewRuntimeContext(cmd, driveTestConfig())
+}
+
+func TestDrivePermissionGetSettingSpecResolvesTargets(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		token    string
+		docType  string
+		wantTok  string
+		wantType string
+	}{
+		{
+			name:     "folder URL",
+			token:    "https://example.feishu.cn/drive/folder/fldTok?from=share",
+			wantTok:  "fldTok",
+			wantType: "folder",
+		},
+		{
+			name:     "docx URL",
+			token:    "https://example.feishu.cn/docx/doxTok",
+			wantTok:  "doxTok",
+			wantType: "docx",
+		},
+		{
+			name:     "file URL",
+			token:    "https://example.feishu.cn/file/boxTok",
+			wantTok:  "boxTok",
+			wantType: "file",
+		},
+		{
+			name:     "wiki URL",
+			token:    "https://example.feishu.cn/wiki/wikTok",
+			wantTok:  "wikTok",
+			wantType: "wiki",
+		},
+		{
+			name:     "minutes URL",
+			token:    "https://example.feishu.cn/minutes/obTok",
+			wantTok:  "obTok",
+			wantType: "minutes",
+		},
+		{
+			name:     "mindnotes URL",
+			token:    "https://example.feishu.cn/mindnotes/mndTok",
+			wantTok:  "mndTok",
+			wantType: "mindnote",
+		},
+		{
+			name:     "bare folder token",
+			token:    " fldTok ",
+			docType:  " folder ",
+			wantTok:  "fldTok",
+			wantType: "folder",
+		},
+		{
+			name:     "bare file token",
+			token:    "boxTok",
+			docType:  "file",
+			wantTok:  "boxTok",
+			wantType: "file",
+		},
+		{
+			name:     "bare wiki token",
+			token:    "wikTok",
+			docType:  "wiki",
+			wantTok:  "wikTok",
+			wantType: "wiki",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
+			spec, err := readDrivePermissionGetSettingSpec(runtime)
+			if err != nil {
+				t.Fatalf("read spec: %v", err)
+			}
+			if spec.Token != tt.wantTok {
+				t.Fatalf("Token = %q, want %q", spec.Token, tt.wantTok)
+			}
+			if spec.Type != tt.wantType {
+				t.Fatalf("Type = %q, want %q", spec.Type, tt.wantType)
+			}
+		})
+	}
+}
+
+func TestDrivePermissionGetSettingSpecValidationErrorsAreTyped(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		token       string
+		docType     string
+		wantParam   string
+		wantMessage string
+	}{
+		{
+			name:        "missing token",
+			wantParam:   "--token",
+			wantMessage: "--token is required",
+		},
+		{
+			name:        "bare token without type",
+			token:       "doxTok",
+			wantParam:   "--type",
+			wantMessage: "--type is required",
+		},
+		{
+			name:        "unsupported URL",
+			token:       "https://example.feishu.cn/calendar/calTok",
+			wantParam:   "--token",
+			wantMessage: "unsupported --token URL",
+		},
+		{
+			name:        "URL type conflict",
+			token:       "https://example.feishu.cn/docx/doxTok",
+			docType:     "sheet",
+			wantParam:   "--type",
+			wantMessage: "conflicts with URL path type",
+		},
+		{
+			name:        "invalid bare token",
+			token:       "../bad",
+			docType:     "folder",
+			wantParam:   "--token",
+			wantMessage: "--token",
+		},
+		{
+			name:        "invalid type",
+			token:       "doxTok",
+			docType:     "comment",
+			wantParam:   "--type",
+			wantMessage: "invalid --type",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
+			_, err := readDrivePermissionGetSettingSpec(runtime)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %v", err, err)
+			}
+			if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("problem = %s/%s, want validation/invalid_argument", problem.Category, problem.Subtype)
+			}
+			if validationErr, ok := err.(*errs.ValidationError); ok {
+				if validationErr.Param != tt.wantParam {
+					t.Fatalf("param = %q, want %q", validationErr.Param, tt.wantParam)
+				}
+			} else {
+				t.Fatalf("error type = %T, want *errs.ValidationError", err)
+			}
+			if !strings.Contains(err.Error(), tt.wantMessage) {
+				t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantMessage)
+			}
+		})
+	}
+}
+
+func TestDrivePermissionGetSettingDryRunIncludesGETRequest(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		token    string
+		docType  string
+		wantURL  string
+		wantType string
+	}{
+		{
+			name:     "folder URL",
+			token:    "https://example.feishu.cn/drive/folder/fldTok",
+			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
+			wantType: "folder",
+		},
+		{
+			name:     "bare folder token",
+			token:    "fldTok",
+			docType:  "folder",
+			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
+			wantType: "folder",
+		},
+		{
+			name:     "docx URL",
+			token:    "https://example.feishu.cn/docx/doxTok",
+			wantURL:  "/open-apis/drive/v2/permissions/doxTok/public",
+			wantType: "docx",
+		},
+		{
+			name:     "bare wiki token",
+			token:    "wikTok",
+			docType:  "wiki",
+			wantURL:  "/open-apis/drive/v2/permissions/wikTok/public",
+			wantType: "wiki",
+		},
+		{
+			name:     "file URL",
+			token:    "https://example.feishu.cn/file/boxTok",
+			wantURL:  "/open-apis/drive/v2/permissions/boxTok/public",
+			wantType: "file",
+		},
+		{
+			name:     "minutes URL",
+			token:    "https://example.feishu.cn/minutes/obTok",
+			wantURL:  "/open-apis/drive/v2/permissions/obTok/public",
+			wantType: "minutes",
+		},
+		{
+			name:     "mindnotes URL",
+			token:    "https://example.feishu.cn/mindnotes/mndTok",
+			wantURL:  "/open-apis/drive/v2/permissions/mndTok/public",
+			wantType: "mindnote",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
+			dry := DrivePermissionGetSetting.DryRun(context.Background(), runtime)
+			if dry == nil {
+				t.Fatal("DryRun returned nil")
+			}
+			data, err := json.Marshal(dry)
+			if err != nil {
+				t.Fatalf("marshal dry-run: %v", err)
+			}
+			out := string(data)
+			for _, want := range []string{
+				`"` + tt.wantURL + `"`,
+				`"GET"`,
+				`"type":"` + tt.wantType + `"`,
+			} {
+				if !strings.Contains(out, want) {
+					t.Fatalf("dry-run output missing %q:\n%s", want, out)
+				}
+			}
+			if strings.Contains(out, `"folder_token"`) {
+				t.Fatalf("dry-run output contains folder_token, want omitted:\n%s", out)
+			}
+		})
+	}
+}
+
+func TestDrivePermissionGetSettingExecutePreservesPermissionPublic(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v2/permissions/doxTok/public?type=docx",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"permission_public": map[string]interface{}{
+					"link_share_entity":          "closed",
+					"external_access_entity":     "closed",
+					"security_entity":            "anyone_can_view",
+					"comment_entity":             "anyone_can_view",
+					"share_entity":               "anyone",
+					"manage_collaborator_entity": "collaborator_can_view",
+					"lock_switch":                false,
+					"server_future_field":        "preserved",
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePermissionGetSetting, []string{
+		"+permission-get-setting",
+		"--token", "doxTok",
+		"--type", "docx",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	for _, key := range []string{"type", "token", "url"} {
+		if _, ok := data[key]; ok {
+			t.Fatalf("data[%s] = %#v, want field omitted", key, data[key])
+		}
+	}
+	permissionPublic, _ := data["permission_public"].(map[string]interface{})
+	if permissionPublic == nil {
+		t.Fatalf("permission_public missing in output: %#v", data)
+	}
+	for key, want := range map[string]interface{}{
+		"link_share_entity":          "closed",
+		"external_access_entity":     "closed",
+		"security_entity":            "anyone_can_view",
+		"comment_entity":             "anyone_can_view",
+		"share_entity":               "anyone",
+		"manage_collaborator_entity": "collaborator_can_view",
+		"lock_switch":                false,
+		"server_future_field":        "preserved",
+	} {
+		if permissionPublic[key] != want {
+			t.Fatalf("permission_public[%s] = %#v, want %#v", key, permissionPublic[key], want)
+		}
+	}
+}
+
+func TestDrivePermissionGetSettingExecuteRejectsMissingPermissionPublic(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v2/permissions/doxTok/public?type=docx",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{"unexpected": "response"},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePermissionGetSetting, []string{
+		"+permission-get-setting",
+		"--token", "doxTok",
+		"--type", "docx",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected invalid response error, got nil")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeInvalidResponse {
+		t.Fatalf("problem = %#v, want internal/invalid_response", problem)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout should be empty on invalid response, got %s", stdout.String())
+	}
+}
+
+func TestDrivePermissionGetSettingExecutePrettyFormatIncludesPermissionPublic(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v2/permissions/doxTok/public?type=docx",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"permission_public": map[string]interface{}{
+					"link_share_entity":   "closed",
+					"server_future_field": "preserved",
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePermissionGetSetting, []string{
+		"+permission-get-setting",
+		"--token", "doxTok",
+		"--type", "docx",
+		"--format", "pretty",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	for _, want := range []string{
+		"Permission settings:",
+		`"link_share_entity": "closed"`,
+		`"server_future_field": "preserved"`,
+	} {
+		if !strings.Contains(stdout.String(), want) {
+			t.Fatalf("pretty output missing %q:\n%s", want, stdout.String())
+		}
+	}
+}
+
+func TestDrivePermissionGetSettingDeclaresScopeAndIdentities(t *testing.T) {
+	t.Parallel()
+
+	if !reflect.DeepEqual(DrivePermissionGetSetting.Scopes, []string{"docs:permission.setting:read"}) {
+		t.Fatalf("Scopes = %v, want docs:permission.setting:read", DrivePermissionGetSetting.Scopes)
+	}
+	if !reflect.DeepEqual(DrivePermissionGetSetting.AuthTypes, []string{"user", "bot"}) {
+		t.Fatalf("AuthTypes = %v, want [user bot]", DrivePermissionGetSetting.AuthTypes)
+	}
+	for _, flag := range DrivePermissionGetSetting.Flags {
+		if flag.Name == "token" && !flag.Required {
+			t.Fatal("--token must be declared required")
+		}
+	}
+}

shortcuts/drive/shortcuts.go

@@ -32,6 +32,8 @@ func Shortcuts() []common.Shortcut {
 		DriveTaskResult,
 		DriveApplyPermission,
 		DriveMemberAdd,
+		DriveMemberList,
+		DrivePermissionGetSetting,
 		DriveSecureLabelList,
 		DriveSecureLabelUpdate,
 		DriveSearch,

shortcuts/drive/shortcuts_test.go

@@ -39,6 +39,8 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+task_result",
 		"+apply-permission",
 		"+member-add",
+		"+member-list",
+		"+permission-get-setting",
 		"+secure-label-list",
 		"+secure-label-update",
 		"+search",

shortcuts/sheets/backward/lark_sheets_float_images.go

@@ -17,9 +17,10 @@ import (
 )
 
 // Drive media parent_type values for uploading an image into a spreadsheet.
-// Native spreadsheets use "sheet_image"; imported "office" spreadsheets carry a
-// synthetic token prefixed with "fake_office_" (being renamed to
-// "local_office_") and the backend requires "office_sheet_file" instead.
+// Native spreadsheets use "sheet_image"; imported "office" spreadsheets use a
+// legacy synthetic-token prefix or a 28-character token whose interleaved
+// product/region marker is "OFL0X". The backend requires
+// "office_sheet_file" for those imported spreadsheets.
 const (
 	sheetImageParentType      = "sheet_image"
 	officeSheetFileParentType = "office_sheet_file"
@@ -27,22 +28,37 @@ const (
 	localOfficePrefix         = "local_office_"
 )
 
-// officePrefixes are the synthetic token prefixes an imported "office"
-// spreadsheet may carry. The prefix is being renamed from "fake_office_" to
-// "local_office_"; accept either so image uploads keep working across the
-// rename.
+// officePrefixes are the legacy synthetic token prefixes an imported "office"
+// spreadsheet may carry.
 var officePrefixes = []string{fakeOfficePrefix, localOfficePrefix}
 
-// sheetMediaParentType returns the drive media parent_type to use when
-// uploading an image whose parent_node is spreadsheetToken, mapping either the
-// "fake_office_" or "local_office_" imported-spreadsheet token prefix to
-// "office_sheet_file".
-func sheetMediaParentType(spreadsheetToken string) string {
+func isOfficeSpreadsheet(spreadsheetToken string) bool {
 	for _, prefix := range officePrefixes {
 		if strings.HasPrefix(spreadsheetToken, prefix) {
-			return officeSheetFileParentType
+			return true
 		}
 	}
+	if len(spreadsheetToken) != 28 {
+		return false
+	}
+	// The five-character marker occupies positions 5, 10, 15, 20, and 25
+	// (1-based) in the interleaved token.
+	marker := []byte{
+		spreadsheetToken[4],
+		spreadsheetToken[9],
+		spreadsheetToken[14],
+		spreadsheetToken[19],
+		spreadsheetToken[24],
+	}
+	return string(marker) == "OFL0X"
+}
+
+// sheetMediaParentType returns the drive media parent_type to use when
+// uploading an image whose parent_node is spreadsheetToken.
+func sheetMediaParentType(spreadsheetToken string) string {
+	if isOfficeSpreadsheet(spreadsheetToken) {
+		return officeSheetFileParentType
+	}
 	return sheetImageParentType
 }
 

shortcuts/sheets/backward/lark_sheets_sheet_media_upload_test.go

@@ -105,7 +105,7 @@ func TestSheetMediaUploadDryRunSmallFileOfficeParentType(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, sheetsTestConfig())
 	err := mountAndRunSheets(t, SheetMediaUpload, []string{
 		"+media-upload",
-		"--spreadsheet-token", "fake_office_abc123",
+		"--spreadsheet-token", "aaaaOaaaaFaaaaLaaaa0aaaaXaaa",
 		"--file", "img.png",
 		"--dry-run", "--as", "user",
 	}, f, stdout)
@@ -117,10 +117,10 @@ func TestSheetMediaUploadDryRunSmallFileOfficeParentType(t *testing.T) {
 		t.Fatalf("dry-run should use upload_all for small file, got: %s", out)
 	}
 	if !strings.Contains(out, `"office_sheet_file"`) {
-		t.Fatalf("dry-run should include parent_type=office_sheet_file for fake_office_ token, got: %s", out)
+		t.Fatalf("dry-run should include parent_type=office_sheet_file for interleaved OFL0X token, got: %s", out)
 	}
 	if strings.Contains(out, `"sheet_image"`) {
-		t.Fatalf("dry-run must not emit sheet_image for fake_office_ token, got: %s", out)
+		t.Fatalf("dry-run must not emit sheet_image for interleaved OFL0X token, got: %s", out)
 	}
 }
 
@@ -239,7 +239,7 @@ func TestSheetMediaUploadExecuteSuccess(t *testing.T) {
 }
 
 // TestSheetMediaUploadExecuteOfficeParentType confirms that an imported
-// "office" spreadsheet (token prefixed with "fake_office_") uploads with
+// "office" spreadsheet (token carrying the interleaved "OFL0X" marker) uploads with
 // parent_type=office_sheet_file instead of the native sheet_image.
 func TestSheetMediaUploadExecuteOfficeParentType(t *testing.T) {
 	dir := t.TempDir()
@@ -259,7 +259,7 @@ func TestSheetMediaUploadExecuteOfficeParentType(t *testing.T) {
 	}
 	reg.Register(stub)
 
-	const officeToken = "fake_office_abc123"
+	const officeToken = "aaaaOaaaaFaaaaLaaaa0aaaaXaaa"
 	err := mountAndRunSheets(t, SheetMediaUpload, []string{
 		"+media-upload",
 		"--spreadsheet-token", officeToken,

shortcuts/sheets/helpers.go

@@ -53,9 +53,10 @@ func sheetsInputStatError(flag string, err error) error {
 }
 
 // Drive media parent_type values for uploading an image into a spreadsheet.
-// Native spreadsheets use "sheet_image"; imported "office" spreadsheets carry a
-// synthetic token prefixed with "fake_office_" (being renamed to
-// "local_office_") and the backend requires "office_sheet_file" instead.
+// Native spreadsheets use "sheet_image"; imported "office" spreadsheets use a
+// legacy synthetic-token prefix or a 28-character token whose interleaved
+// product/region marker is "OFL0X". The backend requires
+// "office_sheet_file" for those imported spreadsheets.
 const (
 	sheetImageParentType      = "sheet_image"
 	officeSheetFileParentType = "office_sheet_file"
@@ -63,21 +64,38 @@ const (
 	localOfficePrefix         = "local_office_"
 )
 
-// officePrefixes are the synthetic token prefixes an imported "office"
-// spreadsheet may carry. The prefix is being renamed from "fake_office_" to
-// "local_office_"; accept either so image uploads keep working across the
-// rename.
+// officePrefixes are the legacy synthetic token prefixes an imported "office"
+// spreadsheet may carry.
 var officePrefixes = []string{fakeOfficePrefix, localOfficePrefix}
 
+func isOfficeSpreadsheet(spreadsheetToken string) bool {
+	for _, prefix := range officePrefixes {
+		if strings.HasPrefix(spreadsheetToken, prefix) {
+			return true
+		}
+	}
+	if len(spreadsheetToken) != 28 {
+		return false
+	}
+	// The five-character marker occupies positions 5, 10, 15, 20, and 25
+	// (1-based) in the interleaved token.
+	marker := []byte{
+		spreadsheetToken[4],
+		spreadsheetToken[9],
+		spreadsheetToken[14],
+		spreadsheetToken[19],
+		spreadsheetToken[24],
+	}
+	return string(marker) == "OFL0X"
+}
+
 // sheetMediaParentType returns the drive media parent_type to use when
 // uploading an image whose parent_node is spreadsheetToken. It is the single
 // place that maps a spreadsheet token to its parent_type so every image-upload
 // entry point (and its dry-run preview) stays consistent.
 func sheetMediaParentType(spreadsheetToken string) string {
-	for _, prefix := range officePrefixes {
-		if strings.HasPrefix(spreadsheetToken, prefix) {
-			return officeSheetFileParentType
-		}
+	if isOfficeSpreadsheet(spreadsheetToken) {
+		return officeSheetFileParentType
 	}
 	return sheetImageParentType
 }

shortcuts/sheets/sheet_media_parent_type_test.go

@@ -25,8 +25,9 @@ import (
 
 // TestSheetMediaParentType pins the token→parent_type mapping that every
 // sheets image-upload entry point funnels through. Native spreadsheet tokens
-// use "sheet_image"; imported "office" spreadsheets carry a "fake_office_" or
-// "local_office_" synthetic token and must upload with "office_sheet_file".
+// use "sheet_image"; imported "office" spreadsheets use either a legacy
+// prefix or the interleaved "OFL0X" marker and must upload with
+// "office_sheet_file".
 func TestSheetMediaParentType(t *testing.T) {
 	t.Parallel()
 	cases := []struct {
@@ -40,6 +41,13 @@ func TestSheetMediaParentType(t *testing.T) {
 		{"fake_office token, only the prefix", fakeOfficePrefix, officeSheetFileParentType},
 		{"local_office imported token", "local_office_abc123", officeSheetFileParentType},
 		{"local_office token, only the prefix", localOfficePrefix, officeSheetFileParentType},
+		{"interleaved OFL0X office token", "aaaaOaaaaFaaaaLaaaa0aaaaXaaa", officeSheetFileParentType},
+		{"interleaved exlcn token", "abcdeefghxijkllmnopcqrstnuv", sheetImageParentType},
+		{"interleaved shtcn native token", "abcdsefghhijkltmnopcqrstnuv", sheetImageParentType},
+		{"interleaved pptcn token", "abcdpefghpijkltmnopcqrstnuv", sheetImageParentType},
+		{"interleaved wodcn token", "abcdwefghoijkldmnopcqrstnuv", sheetImageParentType},
+		{"interleaved OFL0X marker with short length", "aaaaOaaaaFaaaaLaaaa0aaaaXaa", sheetImageParentType},
+		{"interleaved OFL0X marker with long length", "aaaaOaaaaFaaaaLaaaa0aaaaXaaaa", sheetImageParentType},
 		{"fake_office prefix mid-string is not matched", "shtfake_office_abc", sheetImageParentType},
 		{"local_office prefix mid-string is not matched", "shtlocal_office_abc", sheetImageParentType},
 	}
@@ -57,7 +65,7 @@ func TestSheetMediaParentType(t *testing.T) {
 // to end (the Execute path the dry-run tests don't reach), asserting the
 // parent_type that actually goes out on the wire is derived from the token: a
 // native spreadsheet uploads as sheet_image, an imported "office" spreadsheet
-// (fake_office_-prefixed token) as office_sheet_file.
+// (legacy prefix or interleaved OFL0X marker) as office_sheet_file.
 func TestUploadSheetImage_ParentType(t *testing.T) {
 	cases := []struct {
 		name           string
@@ -67,6 +75,7 @@ func TestUploadSheetImage_ParentType(t *testing.T) {
 		{"native spreadsheet", "shtcnTOK123", sheetImageParentType},
 		{"fake_office imported spreadsheet", "fake_office_abc123", officeSheetFileParentType},
 		{"local_office imported spreadsheet", "local_office_abc123", officeSheetFileParentType},
+		{"interleaved OFL0X imported spreadsheet", "aaaaOaaaaFaaaaLaaaa0aaaaXaaa", officeSheetFileParentType},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {

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
+}

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

@@ -28,7 +28,7 @@
 ## 各命令
 
 ### +file-list
-列出应用文件，支持精确过滤：`--name`（文件名）、`--path`（远端路径）、`--type`（MIME 类型）、`--size-gt`/`--size-lt`（字节）、`--uploaded-since`/`--uploaded-until`（上传时间区间，时间格式见末尾）。分页 `--page-size`（默认 20）/ `--page-token`。列表每项给名称、路径、大小、类型、上传时间（pretty 表格即这 5 列）；上传者、下载地址（如有）仅在 JSON 输出里，单文件详情用 `+file-get`。
+列出应用文件，支持精确过滤：`--name`（文件名）、`--path`（远端路径）、`--type`（MIME 类型）、`--size-gt`/`--size-lt`（字节）、`--uploaded-since`/`--uploaded-until`（上传时间区间，时间格式见末尾）。分页 `--page-size`（默认 20，范围 1..200）/ `--page-token`。列表每项给名称、路径、大小、类型、上传时间（pretty 表格即这 5 列）；上传者、下载地址（如有）仅在 JSON 输出里，单文件详情用 `+file-get`。
 
 ```bash
 lark-cli apps +file-list --app-id app_xxx

skills/lark-base/SKILL.md

@@ -29,7 +29,7 @@ metadata:
 ## 使用边界
 
 - Base 业务操作只使用 `lark-cli base +...` shortcut，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`。
-- 本轮 Base 不依赖 `lark-cli schema`。SKILL 只保留路由、风险和复杂 JSON/DSL；简单命令由命令自身的参数、tips 和错误恢复承接。
+- 执行 update 前必须先查当前 shortcut 的 `--help` 或对应 reference。若命令要求完整配置，首次请求必须基于可信的当前配置执行 read-modify-write：只修改用户明确指定的内容，保留其他仍适用的可写配置，并按命令要求的结构提交。若命令支持局部／delta update，按其契约提交最小合法 payload；不得以不完整请求试错补参。
 - 用户要把 Excel / CSV / `.base` 导入成 Base 时，先转 `lark-cli drive +import --type bitable`，导入完成后再回到 Base 命令。
 - 认证、初始化、scope、身份切换、权限不足恢复属于 `lark-shared`；Base 文档只保留会影响 Base 路径选择的权限规则。
 
@@ -57,12 +57,12 @@ metadata:
 | 写记录 | `+record-upsert` / `+record-batch-create` / `+record-batch-update` | 必读 [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) 和 [lark-base-cell-value.md](references/lark-base-cell-value.md) |
 | 附件字段 | `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` | 附件不要伪造成普通 CellValue；上传走本地文件，下载/删除按 file token 或字段定位 |
 | 删除记录 / 分享记录链接 / 历史 | `+record-delete` / `+record-share-link-create` / `+record-history-list` | 删除前确认 record；分享链接最多 100 条；历史读 [lark-base-record-history-list.md](references/lark-base-record-history-list.md)，只查单条记录，不做整表审计 |
-| 管理视图 | `+view-*` | `+view-set-filter` 读 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)；其余配置先 get 现状，再按返回结构更新 |
+| 管理视图 | `+view-*` | `+view-set-filter` 读 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)（filter 条件结构见公共协议 [lark-base-filter-condition.md](references/lark-base-filter-condition.md)）；其余配置先 get 现状，再按返回结构更新 |
 | 一次性聚合统计 | `+data-query` | 必读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) 和入口 [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md)；完整 DSL 再读 [lark-base-data-query.md](references/lark-base-data-query.md) |
 | 公式字段 | `+field-create/update --json '{"type":"formula",...}'` | 必读 [formula-field-guide.md](references/formula-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
 | Lookup 字段 | `+field-create/update --json '{"type":"lookup",...}'` | 必读 [lookup-field-guide.md](references/lookup-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
 | 表单提交 | `+form-submit` | 先读 [lark-base-form-detail.md](references/lark-base-form-detail.md) 获取题目、filter 和附件所需 `base_token`；提交 JSON 读 [lark-base-form-submit.md](references/lark-base-form-submit.md) |
-| 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md) |
+| 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)；题目显隐条件 `visible_rule` 结构见公共协议 [lark-base-filter-condition.md](references/lark-base-filter-condition.md) |
 | 其他表单管理 | `+form-list/get/detail/create/update/delete` / `+form-questions-list/delete` | `+form-detail` 读 [lark-base-form-detail.md](references/lark-base-form-detail.md)；删除前确认目标表单 |
 | 仪表盘与组件 | `+dashboard-*` / `+dashboard-block-*` | 提到图表/看板/block 时先读 [lark-base-dashboard.md](references/lark-base-dashboard.md)；组件 `data_config` 读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)；读取图表计算结果用 `+dashboard-block-get-data` |
 | Workflow | `+workflow-*` | 创建/更新或理解 steps 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；list/get/enable/disable 只处理 workflow ID 与启停状态 |
@@ -104,19 +104,19 @@ metadata:
 
 ## 写入前置规则
 
-- 更新前先看命令说明：需要完整提交时，先读取并补齐当前配置，只改用户指定的内容，再按命令要求提交；支持局部修改时，按命令说明和 reference 提交最小合法 payload。
 - 优先用写入返回确认结果；返回信息不足或任务明确要求核验时，再读回。
 - 写记录前先读字段结构；只写存储字段。系统字段、附件字段、`formula`、`lookup` 不作为普通记录写入目标。
 - 附件上传、下载、删除走专用 `+record-*-attachment` 命令。
 - 写字段前先读 [lark-base-field-json.md](references/lark-base-field-json.md)；涉及 `formula` / `lookup` 时必须读 [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)。
 - 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回；跨表场景还要读取目标表结构。
-- 删除、角色更新、字段更新等高风险操作遵循 CLI 的 confirmation gate；目标不明确时先用 get/list 消歧。
+- 删除、角色更新、字段更新、表单提交（`+form-submit`）等高风险操作遵循 CLI 的 confirmation gate，必须带 `--yes`；目标不明确时先用 get/list 消歧。
 - 批量写入单批最多 200 条；连续写同一表时串行执行，遇到 `1254291` 按短暂等待后重试处理。
 - `select` 字段只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
 
 ## 表单与视图细节
 
-- `+form-submit` 前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
+- `+form-submit` 是高风险写操作，必须带 `--yes` 确认；调用前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
+- `+form-questions-update` 是题目配置全量覆盖，不是 patch；未传字段会回落默认值，传空字符串 / `null` / 空数组会直接写入空或清空。更新前先 `+form-questions-list` 读取当前题目，把要保留的 `title` / `description` / `required` / `option_display_mode` / `visible_rule` 等字段带回请求。
 - 表单附件不要写进 `fields`，放在 `--json.attachments`；提交附件时必须同时传表单所属 Base 的 `--base-token`。
 - `+view-set-filter` 是唯一保留的 view reference；sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状，保留未修改字段，只替换用户要求变更的配置。
 - 视图适合持久化、共享和 UI 复用；一次性筛选/排序可先用 `+record-list` / `+record-search` 的 filter/sort 验证结果，再按需要沉淀为持久视图。
@@ -147,13 +147,14 @@ metadata:
 ## 保留 Reference
 
 - [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md)：查询/统计/全局结论的选路 SOP
-- [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md) / [lark-base-data-query.md](references/lark-base-data-query.md)：聚合查询入口 fewshot 与 DSL SSOT
+- [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md) / [lark-base-data-query.md](references/lark-base-data-query.md)：聚合查询入口 fewshot 与 DSL SSOT；`+data-query` 的 `filters` 结构是独立对象 DSL，不使用公共 tuple filter 协议
 - [lark-base-cell-value.md](references/lark-base-cell-value.md)：记录 CellValue 构造
 - [lark-base-field-json.md](references/lark-base-field-json.md)：字段 JSON 构造
 - [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)：公式与 lookup 字段
 - [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md)：字段创建/更新命令级补充
 - [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) / [lark-base-record-history-list.md](references/lark-base-record-history-list.md)：记录写入 JSON 与历史返回解释
 - [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)：视图筛选 JSON
+- [lark-base-filter-condition.md](references/lark-base-filter-condition.md)：视图 filter、记录 `--filter-json`、表单 `visible_rule` 的 tuple 条件结构公共协议 SSOT；不适用于 `+data-query`
 - [lark-base-form-detail.md](references/lark-base-form-detail.md) / [lark-base-form-submit.md](references/lark-base-form-submit.md) / [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)：表单详情、提交和复杂 JSON
 - [lark-base-dashboard.md](references/lark-base-dashboard.md) / [dashboard-block-data-config.md](references/dashboard-block-data-config.md) / [lark-base-dashboard-block-get-data.md](references/lark-base-dashboard-block-get-data.md)：仪表盘、组件配置与图表结果协议
 - [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) / [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)：workflow 入口与 steps JSON SSOT

skills/lark-base/references/lark-base-filter-condition.md

@@ -0,0 +1,179 @@
+# Base Filter 条件结构（公共协议）
+
+Filter 是一组「字段/操作符/值」条件的组合，用 `logic`（`and` / `or`）把多条 `conditions` 连接起来，用于描述「满足什么条件」。视图筛选 `filter`、记录读取/搜索的 `--filter-json`、表单题目显隐条件 `visible_rule` 复用同一套 tuple 结构，本文件是其公共协议（SSOT）。
+
+## 0. 适用范围
+
+本协议只适用于以下场景：
+
+- `+view-set-filter` / `+view-get-filter` 的视图筛选配置。
+- `+record-list --filter-json` / `+record-search --filter-json` 的结构化记录筛选。
+- `+form-questions-create` / `+form-questions-update` 中的 `visible_rule` 显隐条件。
+
+本协议**不适用于 `+data-query`**。`+data-query` 支持过滤，但使用的是 LiteQuery DSL 的 `filters` 对象结构：`{"type":1,"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["有效"]}]}`，不是这里的 tuple 条件 `["状态","==","有效"]`。构造 `+data-query --dsl` 时请阅读 [lark-base-data-query.md](lark-base-data-query.md) 的 FilterGroup / Condition 章节。
+
+## 1. 顶层结构
+
+- 必须是 JSON 对象。
+- 顶层结构是 `{logic?, conditions?}`。
+- `logic` 默认 `and`；推荐只用 canonical 值 `and` / `or`。
+- `conditions` 默认空数组。
+- 每条条件写成 tuple：`[field, operator, value?]`。
+- `empty` / `non_empty` 可写成 2 项：`[field, "empty"]`、`[field, "non_empty"]`。
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["状态", "intersects", ["Doing"]],
+    ["负责人", "intersects", [{ "id": "ou_xxx" }]],
+    ["截止时间", "empty"]
+  ]
+}
+```
+
+清空写法：
+
+```json
+{
+  "conditions": []
+}
+```
+
+## 2. operator
+
+可用 operator：
+- `==`
+- `!=`
+- `>`
+- `>=`
+- `<`
+- `<=`
+- `intersects`
+- `disjoint`
+- `empty`
+- `non_empty`
+
+## 3. value 写法
+
+value 类型取决于条件引用对象（字段 / 题目）的类型。
+
+### `text`
+
+用字符串：
+
+```json
+["标题", "intersects", "发布"]
+```
+
+### `location`
+
+location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度筛选；优先使用 `intersects` 做包含匹配，例如查深圳：
+
+```json
+["位置", "intersects", "深圳"]
+```
+
+不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
+
+### `number` / `auto_number`
+
+用数字：
+
+```json
+["工时", ">=", 3.5]
+```
+
+### `select`
+
+用选项名数组：
+
+```json
+["状态", "intersects", ["Doing", "Blocked"]]
+```
+
+### `user` / `created_by` / `updated_by`
+
+用对象数组：
+
+> **人员筛选：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
+
+```json
+["负责人", "intersects", [{ "id": "ou_xxx" }]]
+```
+
+### `group_chat`
+
+用对象数组：
+
+> **群组筛选：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
+
+```json
+["负责群", "intersects", [{ "id": "oc_xxx" }]]
+```
+
+### `link`
+
+用记录 id 对象数组：
+
+```json
+["关联任务", "intersects", [{ "id": "rec_xxx" }]]
+```
+
+### `checkbox`
+
+用布尔值：
+
+```json
+["完成", "==", true]
+```
+
+### `datetime` / `created_at` / `updated_at`
+
+用相对时间关键字或 `ExactDate(...)`：
+
+```json
+["截止时间", "==", "ExactDate(2026-01-01)"]
+```
+
+```json
+["截止时间", "==", "ExactDate(2026-01-01 11:30)"]
+```
+
+```json
+["截止时间", "==", "Today"]
+```
+
+可用关键字：
+- `Today`
+- `Yesterday`
+- `Tomorrow`
+
+### `formula` / `lookup`
+
+- 筛选值类型由字段计算结果类型动态决定。
+- 拿不准时，先把 `value` 当作单个字符串填入做一次尝试。
+- 如果报错，再按错误提示把 `value` 改成对应类型。
+
+字符串示例：
+
+```json
+["风险说明", "intersects", "高风险"]
+```
+
+数字示例：
+
+```json
+["汇总分", ">=", 80]
+```
+
+## 4. 易错点
+
+- 不要再写旧对象风格：`{"field_name":...,"operator":...}`。
+- `user` / `group_chat` / `link` 不要写成单个标量。
+- `empty` / `non_empty` 不要硬塞无意义的 value。
+- 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
+- `formula` / `lookup` 的 value 形状不固定；拿不准时先读当前配置或字段定义，或根据错误提示修正类型。
+
+## 5. 参考
+- [lookup-field-guide.md](lookup-field-guide.md)

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

@@ -19,10 +19,7 @@ lark-cli base +form-questions-create \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[
-    {"type":"text","title":"您的姓名是？","required":true},
-    {"type":"text","title":"您的联系方式是？","required":false}
-  ]'
+  --questions '[{"type":"text","title":"您的姓名是？","required":true},{"type":"text","title":"您的联系方式是？","required":false}]'
 
 # 添加单选题（带选项）
 lark-cli base +form-questions-create \
@@ -50,6 +47,13 @@ lark-cli base +form-questions-create \
   --table-id <table_id> \
   --form-id <form_id> \
   --questions '[{"type":"text","title":"反馈建议","description":"更多详情请查看[帮助文档](https://example.com/help)"}]'  
+
+# 添加带显隐条件（visible_rule）的问题：当「是否需要发票」选择「是」时才显示「发票抬头」
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"type":"select","title":"是否需要发票","required":true,"options":[{"name":"是","hue":"Blue"},{"name":"否","hue":"Gray"}]},{"type":"text","title":"发票抬头","visible_rule":{"logic":"and","conditions":[["是否需要发票","==","是"]]}}]'
 ```
 
 ## 参数
@@ -78,6 +82,7 @@ lark-cli base +form-questions-create \
 | `multiple`            | 否 | 是否多选（`select`/`user` 类型有效，bool） |
 | `options`             | 否 | 选项列表（仅 `select` 有效）：`[{"name":"选项1","hue":"Blue"}]`，hue 可选：`Red`/`Orange`/`Yellow`/`Green`/`Blue`/`Purple`/`Gray` |
 | `style`               | 否 | 字段样式配置（见下方说明） |
+| `visible_rule`        | 否 | 题目显隐条件（见下方「`visible_rule` 显隐条件」） |
 
 ### `style` 字段说明
 
@@ -88,6 +93,30 @@ lark-cli base +form-questions-create \
 | `number`（评分） | `{"type":"rating","icon":"star","min":1,"max":5}` | icon 可选：`star`/`heart`/`thumbsup`/`fire`/`smile`/`lightning`/`flower`/`number` |
 | `datetime` | `{"format":"yyyy/MM/dd"}` | format 可选：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy` |
 
+### `visible_rule` 显隐条件
+
+> **仅当用户明确要求为题目设置显隐条件（显示/隐藏逻辑）时，才需要读下面的结构说明；否则忽略本节。**
+
+`visible_rule` 控制题目在表单中的显示/隐藏：当条件满足时题目显示，不满足时隐藏；不传或 `conditions` 为空数组则题目始终显示。
+
+- **结构与视图筛选 `filter` 完全一致**，即 `{logic?, conditions?}`，共用同一套公共协议。
+- 与视图 `filter` 唯一的区别：`conditions` 中的 `field` 引用的是**同一表单内其他题目的题目名称或题目 ID**（推荐用题目 ID 以避免重名歧义），而不是数据表字段。
+- **只能引用前序题目**：条件只能引用排在当前题目之前的题目——创建时按 `questions` 数组顺序判定（可引用同批次更靠前的新题目或表单中已有题目），不支持循环引用。
+- 引用的题目必须真实存在，否则会报错。
+- 列出题目（`+form-questions-list`）会在每个题目对象中**原样返回** `visible_rule`；未设置显隐条件的题目返回 `null` 或 `conditions` 为空数组。
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["是否需要发票", "==", "是"],
+    ["报销金额", ">=", 1000]
+  ]
+}
+```
+
+详细的 `visible_rule` 结构（顶层规则、operator 列表、各题目类型的 value 写法）请阅读 [lark-base-filter-condition.md](lark-base-filter-condition.md)。
+
 ## 输出格式
 
 返回创建成功的问题列表：
@@ -115,4 +144,5 @@ lark-cli base +form-questions-create \
 ## 参考
 
 - [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-base-filter-condition.md](lark-base-filter-condition.md) — `visible_rule` / `filter` 条件结构公共协议
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-base/references/lark-base-form-questions-update.md

@@ -2,40 +2,60 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-批量更新多维表格表单/问卷中的问题（标题、描述、是否必填）。
+批量更新多维表格表单/问卷中的问题配置（标题、描述、是否必填、显隐条件等）。
+
+> [!CAUTION]
+> `+form-questions-update` 是**题目配置全量覆盖**，不是 patch。对每个传入的题目，未携带的属性会回落为默认值，显式传空字符串 / `null` / 空数组会直接写入空或清空；如果要保留现有属性，必须先用 `+form-questions-list` 查出现状，再把要保留的字段一起带回 `--questions`。
 
 ## 命令
 
 ```bash
-# 更新一个问题的标题
-lark-cli base +form-questions-update \
+# 先读取现有题目配置，作为 read-modify-write 的基线
+lark-cli base +form-questions-list \
   --base-token <base_token> \
   --table-id <table_id> \
-  --form-id <form_id> \
-  --questions '[{"id":"q_001","title":"您的真实姓名是？"}]'
+  --form-id <form_id>
 
-# 同时更新多个问题
+# 更新一个问题的标题，同时带回要保留的 required / description / visible_rule 等字段
 lark-cli base +form-questions-update \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[
-    {"id":"q_001","title":"姓名（必填）","required":true},
-    {"id":"q_002","title":"联系方式","required":false}
-  ]'
+  --questions '[{"id":"q_001","title":"您的真实姓名是？","description":"请填写真实姓名","required":true,"visible_rule":null}]'
+
+# 同时更新多个问题；每个对象都应是该题目的目标完整配置
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_001","title":"姓名（必填）","required":true},{"id":"q_002","title":"联系方式","required":false}]'
   
-# 更新问题描述（纯文本）
+# 更新问题描述（纯文本），同时带回要保留的 title / required / visible_rule
 lark-cli base +form-questions-update \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[{"id":"q_001","description":"请填写您的真实姓名"}]'
-# 更新问题描述（含链接）
+  --questions '[{"id":"q_001","title":"您的姓名","description":"请填写您的真实姓名","required":true,"visible_rule":null}]'
+# 更新问题描述（含链接），同时带回要保留的 title / required / visible_rule
 lark-cli base +form-questions-update \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[{"id":"q_001","description":"更多说明请参考[帮助文档](https://example.com/help)"}]'  
+  --questions '[{"id":"q_001","title":"反馈建议","description":"更多说明请参考[帮助文档](https://example.com/help)","required":false,"visible_rule":null}]'
+
+# 更新题目显隐条件（visible_rule），同时带回要保留的 title / description / required
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_002","title":"发票抬头","description":"","required":false,"visible_rule":{"logic":"and","conditions":[["q_001","==","是"]]}}]'
+
+# 清空题目显隐条件（使题目始终显示），同时带回要保留的 title / description / required
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_002","title":"发票抬头","description":"","required":false,"visible_rule":null}]'
 ```
 
 ## 参数
@@ -52,15 +72,46 @@ lark-cli base +form-questions-update \
 
 ## `--questions` 格式
 
-每个问题对象必须包含 `id`，其余字段按需传入：
+每个问题对象必须包含 `id`。注意：对象不是增量 patch，而是该题目的目标完整配置；未携带字段会按服务端默认值重建。
 
 | 字段 | 必填 | 说明 |
 |------|------|------|
 | `id` | **是** | 问题 ID（field_id），不可修改 |
-| `title` | 否 | 新的问题标题 |
-| `description` | 否 | 新的问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
-| `required` | 否 | 是否必填 |
-| `option_display_mode` | 否 | 选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向 |
+| `title` | 否 | 目标问题标题；省略会回落为字段名，传空字符串会写入空标题（若服务端允许） |
+| `description` | 否 | 目标问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`）；省略或传空字符串都会清空描述 |
+| `required` | 否 | 目标是否必填；省略会回落为 `false` |
+| `option_display_mode` | 否 | 目标选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向；省略会回落默认展示方式 |
+| `visible_rule` | 否 | 目标题目显隐条件；传完整 `{logic, conditions}` 对象覆盖，传 `null` 或省略都会清空（见下方说明） |
+
+## 全量覆盖语义
+
+- 先执行 `+form-questions-list`，读取被更新题目的当前 `id`、`title`、`description`、`required`、`option_display_mode`、`visible_rule`。
+- 构造 `--questions` 时，只改用户明确要求变化的字段；所有仍要保留的字段必须按当前值一并传回。
+- 不要用“只传要改的字段”的方式更新题目。比如只传 `{"id":"q_002","title":"新标题"}` 会让 `description` 清空、`required` 回落为 `false`、`visible_rule` 清空。
+- 用户明确要求清空时才传空值：`description:""` 清空描述，`visible_rule:null` 清空显隐条件，`conditions:[]` 也表示无条件显示。
+
+### `visible_rule` 显隐条件
+
+> **仅当用户明确要求为题目设置或修改显隐条件（显示/隐藏逻辑）时，才需要读下面的结构说明；否则忽略本节。**
+
+`visible_rule` 控制题目显示/隐藏，**结构与视图筛选 `filter` 完全一致**（`{logic?, conditions?}`），共用同一套公共协议。
+
+- `conditions` 中的 `field` 引用**同一表单内其他题目的题目名称或题目 ID**（推荐用题目 ID）。
+- 更新时按表单中题目的**实际顺序**判定，只能引用排在当前题目之前的题目；不支持循环引用。
+- 更新 `visible_rule` 需传**完整**的 `{logic, conditions}` 对象（整体覆盖）；要保留现有显隐条件就必须把当前 `visible_rule` 原样带回；传 `null`、省略 `visible_rule` 或传空 `conditions` 都会使题目始终显示。
+- 列出题目（`+form-questions-list`）会在每个题目对象中**原样返回** `visible_rule`；未设置显隐条件的题目返回 `null` 或 `conditions` 为空数组。
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["q_001", "==", "是"],
+    ["q_003", ">=", 1000]
+  ]
+}
+```
+
+详细的 `visible_rule` 结构（顶层规则、operator 列表、各题目类型的 value 写法）请阅读 [lark-base-filter-condition.md](lark-base-filter-condition.md)。
 
 ## 输出格式
 
@@ -82,11 +133,13 @@ lark-cli base +form-questions-update \
 > [!CAUTION]
 > 这是**写入操作** — 执行前必须向用户确认。
 
-1. 先用 `+form-questions-list` 获取现有问题及其 `id`
-2. 构造包含 `id` 的更新数组
-3. 执行命令并报告更新结果
+1. 先用 `+form-questions-list` 获取现有问题及其 `id` 和完整配置。
+2. 以现有配置为基线，只修改用户明确要求变化的字段；要保留的字段必须原样带回。
+3. 构造包含 `id` 和目标完整配置的更新数组。
+4. 执行命令并报告更新结果。
 
 ## 参考
 
 - [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-base-filter-condition.md](lark-base-filter-condition.md) — `visible_rule` / `filter` 条件结构公共协议
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-base/references/lark-base-form-submit.md

@@ -4,6 +4,8 @@
 
 通过表单分享链接填写并提交多维表格表单。仅支持分享模式（share_token），支持填写普通字段值和上传本地文件作为附件。
 
+> **⚠️ 高风险写操作（high-risk-write）：** 本命令会向表单写入并提交数据，属于高风险写操作，必须额外传递 `--yes` 进行确认，否则会返回 `confirmation_required` 错误并退出。当用户明确要求提交且目标表单无歧义时，直接附加 `--yes`，无需再次询问。
+
 ## 填写前必读：先获取表单详情
 
 **在调用 `+form-submit` 之前，必须先使用 `+form-detail` 获取表单详情。** 原因如下：
@@ -21,10 +23,11 @@ lark-cli base +form-detail --share-token <share_token>
 
 # 2️⃣ 根据返回的 questions 列表，按 type 格式化值、检查 required、判断 filter 条件
 
-# 3️⃣ 再提交
+# 3️⃣ 再提交（高风险写操作，必须带 --yes）
 lark-cli base +form-submit \
   --share-token <share_token> \
-  --json '{"fields":{...}}'
+  --json '{"fields":{...}}' \
+  --yes
 ```
 
 `+form-detail` 的返回中要重点读取 `questions[].type`、`questions[].required`、题目 `filter` 和附件场景所需的 `data.base_token`。
@@ -35,7 +38,8 @@ lark-cli base +form-submit \
 # 基本提交（填写普通字段）
 lark-cli base +form-submit \
   --share-token <share_token> \
-  --json '{"fields":{"服务评分":5,"评价内容":"服务态度好"}}'
+  --json '{"fields":{"服务评分":5,"评价内容":"服务态度好"}}' \
+  --yes
 
 # 带附件提交（需要额外提供 --base-token）
 lark-cli base +form-submit \
@@ -47,15 +51,17 @@ lark-cli base +form-submit \
       "附件字段名": ["./report.pdf", "./photo.png"],
       "另一个附件字段": ["./doc.docx"]
     }
-  }'
+  }' \
+  --yes
 
 # 使用应用身份（bot）
 lark-cli base +form-submit \
   --share-token <share_token> \
   --json '{"fields":{...}}' \
-  --as bot
+  --as bot \
+  --yes
 
-# 预览 API 调用（不实际执行）
+# 预览 API 调用（不实际执行，dry-run 无需 --yes）
 lark-cli base +form-submit \
   --share-token <share_token> \
   --json '{"fields":{...}}' \
@@ -69,6 +75,7 @@ lark-cli base +form-submit \
 | `--share-token <token>` | 是 | 表单分享 Token（必填），从表单分享链接中提取 |
 | `--base-token <token>` | 条件必填 | Base token；**当 `--json` 包含 `attachments` 时必须提供**，用于将附件上传到 Base Drive Media |
 | `--json <json>` | 是 | JSON 对象，包含 `"fields"`（普通字段值）和 `"attachments"`（附件上传），详见下方说明 |
+| `--yes` | 是 | 确认高风险写操作。本命令为 high-risk-write，不带 `--yes` 会返回 `confirmation_required` |
 | `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
 | `--as` | 否 | 身份：user（默认）\| bot |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
@@ -138,7 +145,8 @@ https://www.example.com/share/base/form/shrbcvST8eZy0vk8zjVZ1CAXNye
 ```bash
 lark-cli base +form-submit \
   --share-token shrbcvST8eZy0vk8zjVZ1CAXNye \
-  --json '{"fields":{...}}'
+  --json '{"fields":{...}}' \
+  --yes
 ```
 
 ## 输出格式
@@ -158,6 +166,7 @@ lark-cli base +form-submit \
 
 ## 提示
 
+- **本命令为高风险写操作（high-risk-write），必须额外传递 `--yes` 确认**，否则返回 `confirmation_required` 并以非零码退出；`--dry-run` 预览除外
 - 本命令仅支持通过表单分享链接（share_token）提交，不支持通过 base_token + table_id + view_id 方式提交
 - **当 `--json` 包含 `attachments` 时，必须额外提供 `--base-token`**，因为附件上传到 Base Drive Media 需要指定目标 Base
 - 附件字段只需在 `--json.attachments` 中提供本地路径即可，CLI 自动完成校验、并行上传、Token 获取和合并写入

skills/lark-base/references/lark-base-view-set-filter.md

@@ -4,142 +4,13 @@
 
 更新视图筛选配置。
 
-## 1. 顶层规则
+## 1. filter 结构
+
+`--json` 就是一个 filter 条件对象，结构见公共协议 SSOT [lark-base-filter-condition.md](lark-base-filter-condition.md)，即 `{logic?, conditions?}`。此处 `conditions` 中的 `field` 引用**数据表字段名或字段 id**。
 
-- `--json` 必须是 JSON 对象。
-- 顶层结构是 `{logic?, conditions?}`。
-- `logic` 默认 `and`；推荐只用 canonical 值 `and` / `or`。
-- `conditions` 默认空数组。
-- 每条条件写成 tuple：`[field, operator, value?]`。
-- `empty` / `non_empty` 可写成 2 项：`[field, "empty"]`、`[field, "non_empty"]`。
 - 支持 `filter` 的视图类型：`grid`、`kanban`、`gallery`、`calendar`、`gantt`。
 
-## 2. operator
-
-可用 operator：
-- `==`
-- `!=`
-- `>`
-- `>=`
-- `<`
-- `<=`
-- `intersects`
-- `disjoint`
-- `empty`
-- `non_empty`
-
-## 3. value 写法
-
-### `text`
-
-用字符串：
-
-```json
-["标题", "intersects", "发布"]
-```
-
-### `location`
-
-location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度筛选；优先使用 `intersects` 做包含匹配，例如查深圳：
-
-```json
-["位置", "intersects", "深圳"]
-```
-
-不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
-
-### `number` / `auto_number`
-
-用数字：
-
-```json
-["工时", ">=", 3.5]
-```
-
-### `select`
-
-用选项名数组：
-
-```json
-["状态", "intersects", ["Doing", "Blocked"]]
-```
-
-### `user` / `created_by` / `updated_by`
-
-用对象数组：
-
-> **人员筛选：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
-
-```json
-["负责人", "intersects", [{ "id": "ou_xxx" }]]
-```
-
-### `group_chat`
-
-用对象数组：
-
-> **群组筛选：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
-
-```json
-["负责群", "intersects", [{ "id": "oc_xxx" }]]
-```
-
-### `link`
-
-用记录 id 对象数组：
-
-```json
-["关联任务", "intersects", [{ "id": "rec_xxx" }]]
-```
-
-### `checkbox`
-
-用布尔值：
-
-```json
-["完成", "==", true]
-```
-
-### `datetime` / `created_at` / `updated_at`
-
-用相对时间关键字或 `ExactDate(...)`：
-
-```json
-["截止时间", "==", "ExactDate(2026-01-01)"]
-```
-
-```json
-["截止时间", "==", "ExactDate(2026-01-01 11:30)"]
-```
-
-```json
-["截止时间", "==", "Today"]
-```
-
-可用关键字：
-- `Today`
-- `Yesterday`
-- `Tomorrow`
-
-### `formula` / `lookup`
-
-- 筛选值类型由字段计算结果类型动态决定。
-- 拿不准时，先把 `value` 当作单个字符串填入做一次尝试。
-- 如果报错，再按错误提示把 `value` 改成对应类型。
-
-字符串示例：
-
-```json
-["风险说明", "intersects", "高风险"]
-```
-
-数字示例：
-
-```json
-["汇总分", ">=", 80]
-```
-
-## 4. 推荐命令
+## 2. 推荐命令
 
 ```bash
 lark-cli base +view-set-filter \
@@ -149,7 +20,7 @@ lark-cli base +view-set-filter \
   --json '{"logic":"and","conditions":[["状态","intersects",["Doing"]],["负责人","intersects",[{"id":"ou_xxx"}]],["截止时间","empty"]]}'
 ```
 
-## 5. JSON 写法
+## 3. JSON 写法
 
 ```json
 {
@@ -170,14 +41,16 @@ lark-cli base +view-set-filter \
 }
 ```
 
-## 6. 使用建议
+完整的 operator 列表与各字段类型的 value 写法（`text` / `number` / `select` / `user` / `datetime` / `formula` / `lookup` 等），见 [lark-base-filter-condition.md](lark-base-filter-condition.md)。
+
+## 4. 使用建议
 
 - 先读取当前筛选配置，理解现有 `logic` 和 `conditions` 的组合关系；只替换用户要求变更的条件，未提到的条件默认保留。
 - 优先传字段 id，不要依赖字段名。
 - 拿不准字段 type 或真实取值时，先用 `+field-list` / `+record-list` 确认，再按对应字段类型的 value 写法构造条件；别按字段名猜 type、凭印象猜枚举取值。
 - 需要清空全部筛选时，直接传 `{"conditions":[]}`。
 
-## 7. 易错点
+## 5. 易错点
 
 - 本 tuple DSL 由 `+view-set-filter` 与 `+record-list` / `+record-search` 的 `--filter-json` 共用；不要写成 `+data-query` 的对象风格 `{"field_name":...,"operator":...}`（会报校验失败）。
 - 标量类字段（`text` / `number` / `datetime` 等）的 value 用标量、别包成数组（各类型详见 value 写法一节）。
@@ -186,6 +59,7 @@ lark-cli base +view-set-filter \
 - 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
 - `formula` / `lookup` 的 value 形状不固定；拿不准时先读当前 filter 或字段定义，或根据错误提示修正类型。
 
-## 8. 参考
+## 6. 参考
 
+- [lark-base-filter-condition.md](lark-base-filter-condition.md)：filter/visible_rule 条件结构公共协议 SSOT
 - [lookup-field-guide.md](lookup-field-guide.md)