fix: centralize resource URL parsing

* fix: decouple --json shorthand registration from default format injection

* fix: fold --json shorthand into format flag before consumption

* fix: enable --json shorthand for mail +triage and mail +watch

* fix: enable --json shorthand for base +record-list

* docs: document --json shorthand for triage, watch and record-list

* docs: clarify record-list JSON output for script consumption

* docs: guide agents to JSON output for machine consumption scenarios

* test: make test comments self-contained

* test: assert typed error metadata in enum validation test

* docs: correct mail +watch --format default and enum in skill doc

* docs: keep --json shorthand undocumented as a silent fallback

CHANGELOG.md

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

package.json

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

shortcuts/base/base_resolve.go

@@ -271,6 +271,9 @@ func resolveBaseURL(u *url.URL) map[string]interface{} {
 
 func resolveWikiBaseURL(runtime *common.RuntimeContext, u *url.URL) (map[string]interface{}, error) {
 	token := firstPathSegmentAfter(u.Path, "/wiki/")
+	if err := runtime.EnsureScopes([]string{"wiki:node:retrieve"}); err != nil {
+		return nil, err
+	}
 	data, err := runtime.CallAPITyped("GET", "/open-apis/wiki/v2/spaces/get_node", map[string]interface{}{"token": token}, nil)
 	if err != nil {
 		return nil, err
@@ -518,14 +521,8 @@ func pathSegmentExists(path, prefix string) bool {
 
 func firstPathSegmentAfter(path, prefix string) string {
 	path = normalizeResolvePath(path)
-	if !strings.HasPrefix(path, prefix) {
-		return ""
-	}
-	rest := path[len(prefix):]
-	if idx := strings.IndexByte(rest, '/'); idx >= 0 {
-		rest = rest[:idx]
-	}
-	return strings.TrimSpace(rest)
+	token, _ := common.PathSegmentAfterPrefix(path, prefix)
+	return token
 }
 
 func valueOrUnknown(s string) string {

shortcuts/base/record_json_shorthand_test.go

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

shortcuts/base/record_list.go

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

shortcuts/common/resource_url.go

@@ -78,6 +78,7 @@ var urlPathToType = []struct {
 	{"/chat/drive/", "folder"},
 	{"/docx/", "docx"},
 	{"/doc/", "doc"},
+	{"/spreadsheets/", "sheet"},
 	{"/sheets/", "sheet"},
 	{"/base/", "bitable"},
 	{"/bitable/", "bitable"},
@@ -117,21 +118,30 @@ func ParseResourceURL(rawURL string) (ResourceRef, bool) {
 	path := u.Path
 
 	for _, mapping := range urlPathToType {
-		if !strings.HasPrefix(path, mapping.Prefix) {
-			continue
+		if token, ok := PathSegmentAfterPrefix(path, mapping.Prefix); ok {
+			return ResourceRef{Type: mapping.Type, Token: token}, true
 		}
-		token := path[len(mapping.Prefix):]
-		// Trim trailing slashes and stop at the next path segment boundary.
-		token = strings.TrimRight(token, "/")
-		if idx := strings.IndexByte(token, '/'); idx >= 0 {
-			token = token[:idx]
-		}
-		token = strings.TrimSpace(token)
-		if token == "" {
-			return ResourceRef{}, false
-		}
-		return ResourceRef{Type: mapping.Type, Token: token}, true
 	}
 
 	return ResourceRef{}, false
 }
+
+// PathSegmentAfterPrefix returns the first non-empty path segment after prefix.
+// It only matches when path itself starts with prefix; query strings and
+// fragments must be parsed by the caller and are intentionally ignored.
+func PathSegmentAfterPrefix(path, prefix string) (string, bool) {
+	if !strings.HasPrefix(path, prefix) {
+		return "", false
+	}
+	rest := path[len(prefix):]
+	// Trim trailing slashes and stop at the next path segment boundary.
+	rest = strings.TrimRight(rest, "/")
+	if idx := strings.IndexByte(rest, '/'); idx >= 0 {
+		rest = rest[:idx]
+	}
+	rest = strings.TrimSpace(rest)
+	if rest == "" {
+		return "", false
+	}
+	return rest, true
+}

shortcuts/common/resource_url_test.go

@@ -23,6 +23,7 @@ func TestParseResourceURL(t *testing.T) {
 		{"docx", "https://xxx.feishu.cn/docx/doxcnABC", "docx", "doxcnABC", true},
 		{"doc", "https://xxx.feishu.cn/doc/doccnABC", "doc", "doccnABC", true},
 		{"sheet", "https://xxx.feishu.cn/sheets/shtcnABC", "sheet", "shtcnABC", true},
+		{"sheet via /spreadsheets/", "https://xxx.feishu.cn/spreadsheets/shtcnABC", "sheet", "shtcnABC", true},
 		{"bitable via /base/", "https://xxx.feishu.cn/base/bascnABC", "bitable", "bascnABC", true},
 		{"bitable via /bitable/", "https://xxx.feishu.cn/bitable/bascnABC", "bitable", "bascnABC", true},
 		{"wiki", "https://xxx.feishu.cn/wiki/wikcnABC", "wiki", "wikcnABC", true},
@@ -41,6 +42,8 @@ func TestParseResourceURL(t *testing.T) {
 		// With query parameters
 		{"with query", "https://xxx.feishu.cn/docx/doxcnABC?from=wiki", "docx", "doxcnABC", true},
 		{"with fragment", "https://xxx.feishu.cn/docx/doxcnABC#section", "docx", "doxcnABC", true},
+		{"query path does not hijack type", "https://xxx.feishu.cn/docx/doxcnABC?next=/wiki/wikcnBAD", "docx", "doxcnABC", true},
+		{"fragment path does not hijack type", "https://xxx.feishu.cn/sheets/shtcnABC#/wiki/wikcnBAD", "sheet", "shtcnABC", true},
 
 		// With trailing slash
 		{"trailing slash", "https://xxx.feishu.cn/docx/doxcnABC/", "docx", "doxcnABC", true},

shortcuts/common/runner.go

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

shortcuts/common/runner_json_shorthand_test.go

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

shortcuts/doc/doc_media_insert.go

@@ -49,7 +49,10 @@ var DocMediaInsert = common.Shortcut{
 	Description: "Insert a local image or file into a Lark document (4-step orchestration + auto-rollback); appends to end by default, or inserts relative to a text selection with --selection-with-ellipsis",
 	Risk:        "write",
 	Scopes:      []string{"docs:document.media:upload", "docx:document:write_only", "docx:document:readonly"},
-	AuthTypes:   []string{"user", "bot"},
+	ConditionalScopes: []string{
+		"wiki:node:retrieve",
+	},
+	AuthTypes: []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "file", Desc: "local file path (files > 20MB use multipart upload automatically)"},
 		{Name: "from-clipboard", Type: "bool", Desc: "read image from system clipboard instead of a local file (macOS/Windows built-in; Linux requires xclip, xsel or wl-paste)"},
@@ -534,6 +537,9 @@ func resolveDocxDocumentID(runtime *common.RuntimeContext, input string) (string
 		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx").WithParam("--doc")
 	case "wiki":
 		fmt.Fprintf(runtime.IO().ErrOut, "Resolving wiki node: %s\n", common.MaskToken(docRef.Token))
+		if err := runtime.EnsureScopes([]string{"wiki:node:retrieve"}); err != nil {
+			return "", err
+		}
 		data, err := runtime.CallAPITyped(
 			"GET",
 			"/open-apis/wiki/v2/spaces/get_node",

shortcuts/doc/doc_resource_cover.go

@@ -59,7 +59,10 @@ var DocResourceDownload = common.Shortcut{
 	Description: "Download a document resource (type=cover downloads the cover image content)",
 	Risk:        "read",
 	Scopes:      []string{"docx:document:readonly", "docs:document.media:download"},
-	AuthTypes:   []string{"user", "bot"},
+	ConditionalScopes: []string{
+		"wiki:node:retrieve",
+	},
+	AuthTypes: []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "doc", Desc: "document URL or document_id", Required: true},
 		{Name: "type", Default: docCoverResourceType, Desc: "resource type: cover"},
@@ -158,7 +161,10 @@ var DocResourceUpdate = common.Shortcut{
 	Description: "Upload and update a document resource (type=cover)",
 	Risk:        "write",
 	Scopes:      []string{"docx:document:readonly", "docx:document:write_only", "docs:document.media:upload"},
-	AuthTypes:   []string{"user", "bot"},
+	ConditionalScopes: []string{
+		"wiki:node:retrieve",
+	},
+	AuthTypes: []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "doc", Desc: "document URL or document_id", Required: true},
 		{Name: "type", Default: docCoverResourceType, Desc: "resource type: cover"},
@@ -260,7 +266,10 @@ var DocResourceDelete = common.Shortcut{
 	Description: "Delete a document resource (type=cover is idempotent when empty)",
 	Risk:        "write",
 	Scopes:      []string{"docx:document:readonly", "docx:document:write_only"},
-	AuthTypes:   []string{"user", "bot"},
+	ConditionalScopes: []string{
+		"wiki:node:retrieve",
+	},
+	AuthTypes: []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "doc", Desc: "document URL or document_id", Required: true},
 		{Name: "type", Default: docCoverResourceType, Desc: "resource type: cover"},

shortcuts/doc/docs_fetch_v2.go

@@ -151,12 +151,12 @@ func resolveFetchLang(runtime *common.RuntimeContext) string {
 
 // buildReadOption 拼装 read_option JSON；full/空模式返回 nil，让服务端走默认全文路径。
 func buildReadOption(runtime *common.RuntimeContext) map[string]interface{} {
-	mode := effectiveFetchReadMode(runtime)
+	mode := strings.TrimSpace(runtime.Str("scope"))
 	if mode == "" || mode == "full" {
 		return nil
 	}
 	ro := map[string]interface{}{"read_mode": mode}
-	if v := effectiveFetchStartBlockID(runtime, mode); v != "" {
+	if v := strings.TrimSpace(runtime.Str("start-block-id")); v != "" {
 		ro["start_block_id"] = v
 	}
 	if v := strings.TrimSpace(runtime.Str("end-block-id")); v != "" {
@@ -177,77 +177,6 @@ func buildReadOption(runtime *common.RuntimeContext) map[string]interface{} {
 	return ro
 }
 
-func effectiveFetchReadMode(runtime *common.RuntimeContext) string {
-	mode := rawFetchReadMode(runtime)
-	if shouldUseDocSelectionAnchor(runtime, mode) {
-		if anchor, _ := docSelectionAnchorStartBlockID(runtime); anchor != "" {
-			return "range"
-		}
-	}
-	return mode
-}
-
-func rawFetchReadMode(runtime *common.RuntimeContext) string {
-	mode := strings.TrimSpace(runtime.Str("scope"))
-	if mode == "" {
-		return "full"
-	}
-	return mode
-}
-
-func effectiveFetchStartBlockID(runtime *common.RuntimeContext, mode string) string {
-	if v := strings.TrimSpace(runtime.Str("start-block-id")); v != "" {
-		if anchor, ok, _ := parseFetchSelectionAnchor(v, "--start-block-id"); ok {
-			return anchor
-		}
-		return v
-	}
-	if mode == "range" && shouldUseDocSelectionAnchor(runtime, rawFetchReadMode(runtime)) {
-		if anchor, _ := docSelectionAnchorStartBlockID(runtime); anchor != "" {
-			return anchor
-		}
-	}
-	return ""
-}
-
-func shouldUseDocSelectionAnchor(runtime *common.RuntimeContext, mode string) bool {
-	if runtime.Changed("start-block-id") || runtime.Changed("end-block-id") {
-		return false
-	}
-	if runtime.Changed("scope") {
-		return mode == "range"
-	}
-	return mode == "" || mode == "full"
-}
-
-func docSelectionAnchorStartBlockID(runtime *common.RuntimeContext) (string, error) {
-	ref, err := parseDocumentRef(runtime.Str("doc"))
-	if err != nil {
-		return "", nil
-	}
-	anchor, ok, err := parseFetchSelectionAnchor(ref.Fragment, "--doc")
-	if err != nil || !ok {
-		return "", err
-	}
-	return anchor, nil
-}
-
-func parseFetchSelectionAnchor(raw, param string) (string, bool, error) {
-	value := strings.TrimSpace(raw)
-	value = strings.TrimPrefix(value, "#")
-	for _, prefix := range []string{"share-", "part-"} {
-		if !strings.HasPrefix(value, prefix) {
-			continue
-		}
-		anchorID := strings.TrimSpace(strings.TrimPrefix(value, prefix))
-		if anchorID == "" {
-			return "", false, errs.NewValidationError(errs.SubtypeInvalidArgument, "selection anchor id is required after %s", prefix).WithParam(param)
-		}
-		return prefix + anchorID, true, nil
-	}
-	return "", false, nil
-}
-
 // effectiveFetchDetail degrades detail options that cannot be represented by
 // non-XML exports. The original flag value is left intact so callers can still
 // surface an explicit warning in execute output.
@@ -279,10 +208,7 @@ func addFetchDetailDowngradeWarning(runtime *common.RuntimeContext, data map[str
 
 // validateReadModeFlags 客户端前置校验，服务端也会再校验一次。
 func validateReadModeFlags(runtime *common.RuntimeContext) error {
-	mode := effectiveFetchReadMode(runtime)
-	if err := validateFetchSelectionAnchorUsage(runtime, mode); err != nil {
-		return err
-	}
+	mode := strings.TrimSpace(runtime.Str("scope"))
 	if mode == "" || mode == "full" {
 		return nil
 	}
@@ -301,7 +227,7 @@ func validateReadModeFlags(runtime *common.RuntimeContext) error {
 	case "outline":
 		return nil
 	case "range":
-		if effectiveFetchStartBlockID(runtime, mode) == "" &&
+		if strings.TrimSpace(runtime.Str("start-block-id")) == "" &&
 			strings.TrimSpace(runtime.Str("end-block-id")) == "" {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "range mode requires --start-block-id or --end-block-id").WithParams(
 				errs.InvalidParam{Name: "--start-block-id", Reason: "provide --start-block-id or --end-block-id for range mode"},
@@ -323,42 +249,3 @@ func validateReadModeFlags(runtime *common.RuntimeContext) error {
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --scope %q", mode).WithParam("--scope")
 	}
 }
-
-func validateFetchSelectionAnchorUsage(runtime *common.RuntimeContext, mode string) error {
-	startBlockID := strings.TrimSpace(runtime.Str("start-block-id"))
-	endBlockID := strings.TrimSpace(runtime.Str("end-block-id"))
-
-	startAnchor, startIsAnchor, err := parseFetchSelectionAnchor(startBlockID, "--start-block-id")
-	if err != nil {
-		return err
-	}
-	_, endIsAnchor, err := parseFetchSelectionAnchor(endBlockID, "--end-block-id")
-	if err != nil {
-		return err
-	}
-	if endIsAnchor {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end-block-id does not support selection anchors; pass the #share anchor in --doc URL").WithParam("--end-block-id")
-	}
-	if !startIsAnchor {
-		_, _, err := parseFetchSelectionAnchorFromDoc(runtime)
-		return err
-	}
-	if mode != "range" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-block-id selection anchor %q requires --scope range", startAnchor).WithParam("--start-block-id")
-	}
-	if endBlockID != "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-block-id selection anchor %q cannot be combined with --end-block-id", startAnchor).WithParams(
-			errs.InvalidParam{Name: "--start-block-id", Reason: "selection anchors define the complete selected range"},
-			errs.InvalidParam{Name: "--end-block-id", Reason: "remove --end-block-id when --start-block-id is a selection anchor"},
-		)
-	}
-	return nil
-}
-
-func parseFetchSelectionAnchorFromDoc(runtime *common.RuntimeContext) (string, bool, error) {
-	ref, err := parseDocumentRef(runtime.Str("doc"))
-	if err != nil {
-		return "", false, nil
-	}
-	return parseFetchSelectionAnchor(ref.Fragment, "--doc")
-}

shortcuts/doc/docs_fetch_v2_test.go

@@ -180,63 +180,6 @@ func TestBuildFetchBodyIncludesReadOption(t *testing.T) {
 	}
 }
 
-func TestBuildFetchBodyUsesSelectionAnchorFragmentAsRangeStart(t *testing.T) {
-	t.Parallel()
-
-	runtime := newFetchBodyTestRuntime(context.Background())
-	mustSetFetchFlag(t, runtime, "doc", "https://example.larksuite.com/wiki/wikcnToken#share-CUE3d6Ykno2fkexEvt8cGF8Wnse")
-
-	body := buildFetchBody(runtime)
-	want := map[string]interface{}{
-		"read_mode":      "range",
-		"start_block_id": "share-CUE3d6Ykno2fkexEvt8cGF8Wnse",
-	}
-	if got := body["read_option"]; !reflect.DeepEqual(got, want) {
-		t.Fatalf("read_option = %#v, want %#v", got, want)
-	}
-}
-
-func TestBuildFetchBodyExplicitFullIgnoresSelectionAnchorFragment(t *testing.T) {
-	t.Parallel()
-
-	runtime := newFetchBodyTestRuntime(context.Background())
-	mustSetFetchFlag(t, runtime, "doc", "https://example.larksuite.com/wiki/wikcnToken#share-CUE3d6Ykno2fkexEvt8cGF8Wnse")
-	mustSetFetchFlag(t, runtime, "scope", "full")
-
-	body := buildFetchBody(runtime)
-	if _, ok := body["read_option"]; ok {
-		t.Fatalf("did not expect read_option for explicit full scope: %#v", body["read_option"])
-	}
-}
-
-func TestBuildFetchBodyDoesNotAutoReadOrdinaryFragment(t *testing.T) {
-	t.Parallel()
-
-	runtime := newFetchBodyTestRuntime(context.Background())
-	mustSetFetchFlag(t, runtime, "doc", "https://example.larksuite.com/wiki/wikcnToken#blk_plain")
-
-	body := buildFetchBody(runtime)
-	if _, ok := body["read_option"]; ok {
-		t.Fatalf("did not expect read_option for ordinary URL fragment: %#v", body["read_option"])
-	}
-}
-
-func TestBuildReadOptionNormalizesExplicitSelectionAnchorStart(t *testing.T) {
-	t.Parallel()
-
-	runtime := newFetchBodyTestRuntime(context.Background())
-	mustSetFetchFlag(t, runtime, "scope", "range")
-	mustSetFetchFlag(t, runtime, "start-block-id", "#part-CUE3d6Ykno2fkexEvt8cGF8Wnse")
-
-	want := map[string]interface{}{
-		"read_mode":      "range",
-		"start_block_id": "part-CUE3d6Ykno2fkexEvt8cGF8Wnse",
-	}
-	if got := buildReadOption(runtime); !reflect.DeepEqual(got, want) {
-		t.Fatalf("buildReadOption() = %#v, want %#v", got, want)
-	}
-}
-
 func TestBuildReadOptionModes(t *testing.T) {
 	t.Parallel()
 
@@ -378,31 +321,6 @@ func TestValidateReadModeFlagsRejectsInvalidScopeOptions(t *testing.T) {
 			},
 			wantParam: "--keyword",
 		},
-		{
-			name: "selection anchor cannot be end block",
-			setFlags: map[string]string{
-				"scope":        "range",
-				"end-block-id": "#share-CUE3d6Ykno2fkexEvt8cGF8Wnse",
-			},
-			wantParam: "--end-block-id",
-		},
-		{
-			name: "selection anchor start cannot combine with end block",
-			setFlags: map[string]string{
-				"scope":          "range",
-				"start-block-id": "#share-CUE3d6Ykno2fkexEvt8cGF8Wnse",
-				"end-block-id":   "blk_end",
-			},
-			wantParams: []string{"--start-block-id", "--end-block-id"},
-		},
-		{
-			name: "selection anchor start requires range",
-			setFlags: map[string]string{
-				"scope":          "section",
-				"start-block-id": "#share-CUE3d6Ykno2fkexEvt8cGF8Wnse",
-			},
-			wantParam: "--start-block-id",
-		},
 		{
 			name: "section needs start block",
 			setFlags: map[string]string{
@@ -457,19 +375,6 @@ func TestValidateReadModeFlagsAcceptsValidScopeOptions(t *testing.T) {
 				"end-block-id": "blk_end",
 			},
 		},
-		{
-			name: "range with selection anchor start",
-			setFlags: map[string]string{
-				"scope":          "range",
-				"start-block-id": "#share-CUE3d6Ykno2fkexEvt8cGF8Wnse",
-			},
-		},
-		{
-			name: "default scope with selection anchor fragment",
-			setFlags: map[string]string{
-				"doc": "https://example.larksuite.com/wiki/wikcnToken#share-CUE3d6Ykno2fkexEvt8cGF8Wnse",
-			},
-		},
 		{
 			name: "keyword with keyword",
 			setFlags: map[string]string{
@@ -979,7 +884,6 @@ func TestDocsFetchRejectsLegacyFlags(t *testing.T) {
 
 func newFetchBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "+fetch"}
-	cmd.Flags().String("doc", "doxcnFetchDryRun", "")
 	cmd.Flags().String("doc-format", fetchDefault("doc-format"), "")
 	cmd.Flags().String("detail", fetchDefault("detail"), "")
 	cmd.Flags().String("lang", fetchDefault("lang"), "")

shortcuts/doc/helpers.go

@@ -17,9 +17,8 @@ import (
 const docsSceneContextKey = "lark_cli_docs_scene"
 
 type documentRef struct {
-	Kind     string
-	Token    string
-	Fragment string
+	Kind  string
+	Token string
 }
 
 func parseDocumentRef(input string) (documentRef, error) {
@@ -28,14 +27,13 @@ func parseDocumentRef(input string) (documentRef, error) {
 		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--doc cannot be empty").WithParam("--doc")
 	}
 
-	if token, ok := extractDocumentToken(raw, "/wiki/"); ok {
-		return documentRef{Kind: "wiki", Token: token, Fragment: extractDocumentFragment(raw)}, nil
-	}
-	if token, ok := extractDocumentToken(raw, "/docx/"); ok {
-		return documentRef{Kind: "docx", Token: token, Fragment: extractDocumentFragment(raw)}, nil
-	}
-	if token, ok := extractDocumentToken(raw, "/doc/"); ok {
-		return documentRef{Kind: "doc", Token: token, Fragment: extractDocumentFragment(raw)}, nil
+	if ref, ok := common.ParseResourceURL(raw); ok {
+		switch ref.Type {
+		case "wiki", "docx", "doc":
+			return documentRef{Kind: ref.Type, Token: ref.Token}, nil
+		default:
+			return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --doc input %q: use a docx URL/token or a wiki URL that resolves to docx", raw).WithParam("--doc")
+		}
 	}
 	if strings.Contains(raw, "://") {
 		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --doc input %q: use a docx URL/token or a wiki URL that resolves to docx", raw).WithParam("--doc")
@@ -47,30 +45,6 @@ func parseDocumentRef(input string) (documentRef, error) {
 	return documentRef{Kind: "docx", Token: raw}, nil
 }
 
-func extractDocumentToken(raw, marker string) (string, bool) {
-	idx := strings.Index(raw, marker)
-	if idx < 0 {
-		return "", false
-	}
-	token := raw[idx+len(marker):]
-	if end := strings.IndexAny(token, "/?#"); end >= 0 {
-		token = token[:end]
-	}
-	token = strings.TrimSpace(token)
-	if token == "" {
-		return "", false
-	}
-	return token, true
-}
-
-func extractDocumentFragment(raw string) string {
-	idx := strings.Index(raw, "#")
-	if idx < 0 {
-		return ""
-	}
-	return strings.TrimSpace(raw[idx+1:])
-}
-
 // doDocAPI executes an OpenAPI request against the docs_ai endpoints and returns
 // the parsed "data" field from the standard Lark response envelope {code, msg, data}.
 // CallAPITyped lifts the x-tt-logid response header onto the typed error so log_id

shortcuts/doc/helpers_test.go

@@ -13,12 +13,11 @@ func TestParseDocumentRef(t *testing.T) {
 	t.Parallel()
 
 	tests := []struct {
-		name         string
-		input        string
-		wantKind     string
-		wantToken    string
-		wantFragment string
-		wantErr      string
+		name      string
+		input     string
+		wantKind  string
+		wantToken string
+		wantErr   string
 	}{
 		{
 			name:      "docx url",
@@ -33,11 +32,16 @@ func TestParseDocumentRef(t *testing.T) {
 			wantToken: "xxxxxx",
 		},
 		{
-			name:         "wiki url with selection anchor",
-			input:        "https://example.larksuite.com/wiki/xxxxxx#share-CUE3d6Ykno2fkexEvt8cGF8Wnse",
-			wantKind:     "wiki",
-			wantToken:    "xxxxxx",
-			wantFragment: "share-CUE3d6Ykno2fkexEvt8cGF8Wnse",
+			name:      "query path does not hijack docx url",
+			input:     "https://example.larksuite.com/docx/doxcn123?next=/wiki/wikcnBAD",
+			wantKind:  "docx",
+			wantToken: "doxcn123",
+		},
+		{
+			name:      "fragment path does not hijack docx url",
+			input:     "https://example.larksuite.com/docx/doxcn123#/wiki/wikcnBAD",
+			wantKind:  "docx",
+			wantToken: "doxcn123",
 		},
 		{
 			name:      "doc url",
@@ -81,9 +85,6 @@ func TestParseDocumentRef(t *testing.T) {
 			if got.Token != tt.wantToken {
 				t.Fatalf("parseDocumentRef(%q) token = %q, want %q", tt.input, got.Token, tt.wantToken)
 			}
-			if got.Fragment != tt.wantFragment {
-				t.Fatalf("parseDocumentRef(%q) fragment = %q, want %q", tt.input, got.Fragment, tt.wantFragment)
-			}
 		})
 	}
 }

shortcuts/drive/drive_add_comment.go

@@ -129,7 +129,8 @@ var DriveAddComment = common.Shortcut{
 		"docs:document.comment:create",
 		"docs:document.comment:write_only",
 	},
-	AuthTypes: []string{"user", "bot"},
+	ConditionalScopes: []string{"wiki:node:retrieve"},
+	AuthTypes:         []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "doc", Desc: "document URL/token, file URL/token, sheet/slides/base/bitable URL, or wiki URL that resolves to doc/docx/file/sheet/slides/base(bitable)", Required: true},
 		{Name: "type", Desc: "document type: doc, docx, file, sheet, slides, bitable, base (required when --doc is a bare token; auto-detected for URLs; use bitable as the wire value, base is accepted as a compatibility alias)", Enum: []string{"doc", "docx", "file", "sheet", "slides", "bitable", "base"}},
@@ -515,29 +516,17 @@ func parseCommentDocRef(input, docType string) (commentDocRef, error) {
 		return commentDocRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--doc cannot be empty").WithParam("--doc")
 	}
 
-	if token, ok := extractURLToken(raw, "/wiki/"); ok {
-		return commentDocRef{Kind: "wiki", Token: token}, nil
-	}
-	if token, ok := extractURLToken(raw, "/sheets/"); ok {
-		return commentDocRef{Kind: "sheet", Token: token}, nil
-	}
-	if token, ok := extractURLToken(raw, "/base/"); ok {
-		return commentDocRef{Kind: "base", Token: token}, nil
-	}
-	if token, ok := extractURLToken(raw, "/bitable/"); ok {
-		return commentDocRef{Kind: "base", Token: token}, nil
-	}
-	if token, ok := extractURLToken(raw, "/file/"); ok {
-		return commentDocRef{Kind: "file", Token: token}, nil
-	}
-	if token, ok := extractURLToken(raw, "/slides/"); ok {
-		return commentDocRef{Kind: "slides", Token: token}, nil
-	}
-	if token, ok := extractURLToken(raw, "/docx/"); ok {
-		return commentDocRef{Kind: "docx", Token: token}, nil
-	}
-	if token, ok := extractURLToken(raw, "/doc/"); ok {
-		return commentDocRef{Kind: "doc", Token: token}, nil
+	if ref, ok := common.ParseResourceURL(raw); ok {
+		kind := ref.Type
+		if kind == "bitable" {
+			kind = "base"
+		}
+		switch kind {
+		case "wiki", "sheet", "base", "file", "slides", "docx", "doc":
+			return commentDocRef{Kind: kind, Token: ref.Token}, nil
+		default:
+			return commentDocRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --doc input %q: use a doc/docx/file/sheet/slides/base/bitable URL, a token with --type, or a wiki URL that resolves to doc/docx/file/sheet/slides/base(bitable)", raw).WithParam("--doc")
+		}
 	}
 	if strings.Contains(raw, "://") {
 		return commentDocRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --doc input %q: use a doc/docx/file/sheet/slides/base/bitable URL, a token with --type, or a wiki URL that resolves to doc/docx/file/sheet/slides/base(bitable)", raw).WithParam("--doc")
@@ -583,6 +572,9 @@ func resolveCommentTarget(ctx context.Context, runtime *common.RuntimeContext, i
 	}
 
 	fmt.Fprintf(runtime.IO().ErrOut, "Resolving wiki node: %s\n", common.MaskToken(docRef.Token))
+	if err := runtime.EnsureScopes([]string{"wiki:node:retrieve"}); err != nil {
+		return resolvedCommentTarget{}, err
+	}
 	data, err := runtime.CallAPITyped(
 		"GET",
 		"/open-apis/wiki/v2/spaces/get_node",
@@ -1257,19 +1249,3 @@ func executeSlidesComment(runtime *common.RuntimeContext, docRef commentDocRef)
 	runtime.Out(out, nil)
 	return nil
 }
-
-func extractURLToken(raw, marker string) (string, bool) {
-	idx := strings.Index(raw, marker)
-	if idx < 0 {
-		return "", false
-	}
-	token := raw[idx+len(marker):]
-	if end := strings.IndexAny(token, "/?#"); end >= 0 {
-		token = token[:end]
-	}
-	token = strings.TrimSpace(token)
-	if token == "" {
-		return "", false
-	}
-	return token, true
-}

shortcuts/drive/drive_add_comment_test.go

@@ -98,6 +98,18 @@ func TestParseCommentDocRef(t *testing.T) {
 			wantKind:  "wiki",
 			wantToken: "xxxxxx",
 		},
+		{
+			name:      "query path does not hijack docx url",
+			input:     "https://example.larksuite.com/docx/doxcn123?next=/wiki/wikcnBAD",
+			wantKind:  "docx",
+			wantToken: "doxcn123",
+		},
+		{
+			name:      "fragment path does not hijack sheet url",
+			input:     "https://example.larksuite.com/sheets/sht123#/wiki/wikcnBAD",
+			wantKind:  "sheet",
+			wantToken: "sht123",
+		},
 		{
 			name:      "raw token with type docx",
 			input:     "xxxxxx",
@@ -2080,14 +2092,6 @@ func TestParseCommentDocRefPathLikeToken(t *testing.T) {
 	}
 }
 
-func TestExtractURLTokenEmptyAfterMarker(t *testing.T) {
-	t.Parallel()
-	_, ok := extractURLToken("https://example.com/sheets/", "/sheets/")
-	if ok {
-		t.Fatal("expected false for empty token after marker")
-	}
-}
-
 func TestSheetCommentExecuteAPIError(t *testing.T) {
 	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	reg.Register(&httpmock.Stub{

shortcuts/drive/drive_apply_permission.go

@@ -20,24 +20,6 @@ var permApplyTypes = []string{
 	"mindnote", "slides",
 }
 
-// permApplyURLMarkers maps document URL path markers to the `type` value the
-// apply-permission endpoint expects. Markers are disjoint strings (each begins
-// with "/" and ends with "/"), so a simple substring scan disambiguates them.
-var permApplyURLMarkers = []struct {
-	Marker string
-	Type   string
-}{
-	{"/wiki/", "wiki"},
-	{"/docx/", "docx"},
-	{"/sheets/", "sheet"},
-	{"/base/", "bitable"},
-	{"/bitable/", "bitable"},
-	{"/file/", "file"},
-	{"/mindnote/", "mindnote"},
-	{"/slides/", "slides"},
-	{"/doc/", "doc"},
-}
-
 // resolvePermApplyTarget extracts (token, type) from a user-supplied --token
 // value that may be either a bare token or a full document URL, plus an
 // optional explicit --type. Explicit --type wins over URL inference.
@@ -48,21 +30,17 @@ func resolvePermApplyTarget(raw, explicitType string) (token, docType string, er
 	}
 
 	if strings.Contains(raw, "://") {
-		for _, m := range permApplyURLMarkers {
-			if tok, ok := extractURLToken(raw, m.Marker); ok {
-				token = tok
-				if explicitType == "" {
-					docType = m.Type
-				}
-				break
-			}
-		}
-		if token == "" {
+		ref, ok := common.ParseResourceURL(raw)
+		if !ok {
 			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument,
 				"could not infer token from URL %q: supported paths are /docx/, /sheets/, /base/, /bitable/, /file/, /wiki/, /doc/, /mindnote/, /slides/. Pass a bare token with --type instead if the URL shape is unusual",
 				raw,
 			).WithParam("--token")
 		}
+		token = ref.Token
+		if explicitType == "" {
+			docType = ref.Type
+		}
 	} else {
 		token = raw
 	}
@@ -76,9 +54,25 @@ func resolvePermApplyTarget(raw, explicitType string) (token, docType string, er
 			strings.Join(permApplyTypes, ", "),
 		).WithParam("--type")
 	}
+	if !isPermApplyType(docType) {
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"unsupported --type %q; accepted values: %s",
+			docType,
+			strings.Join(permApplyTypes, ", "),
+		).WithParam("--type")
+	}
 	return token, docType, nil
 }
 
+func isPermApplyType(docType string) bool {
+	for _, allowed := range permApplyTypes {
+		if docType == allowed {
+			return true
+		}
+	}
+	return false
+}
+
 // DriveApplyPermission applies to the document owner for view or edit access
 // on behalf of the invoking user. Matches the open-apis endpoint
 // /open-apis/drive/v1/permissions/:token/members/apply.

shortcuts/drive/drive_apply_permission_test.go

@@ -42,6 +42,7 @@ func TestResolvePermApplyTarget_URLInference(t *testing.T) {
 		wantType string
 	}{
 		{"docx", "https://example.feishu.cn/docx/doxTok123?from=share", "doxTok123", "docx"},
+		{"query path does not hijack docx url", "https://example.feishu.cn/docx/doxTok123?next=/wiki/wikTokBAD", "doxTok123", "docx"},
 		{"sheets", "https://example.feishu.cn/sheets/shtTok456?sheet=abc", "shtTok456", "sheet"},
 		{"base", "https://example.feishu.cn/base/bscTok789", "bscTok789", "bitable"},
 		{"bitable", "https://example.feishu.cn/bitable/bscTok789", "bscTok789", "bitable"},
@@ -86,6 +87,14 @@ func TestResolvePermApplyTarget_UnrecognizedURL(t *testing.T) {
 	}
 }
 
+func TestResolvePermApplyTarget_UnsupportedURLType(t *testing.T) {
+	t.Parallel()
+	_, _, err := resolvePermApplyTarget("https://example.feishu.cn/drive/folder/fldTok123", "")
+	if err == nil || !strings.Contains(err.Error(), "unsupported --type") {
+		t.Fatalf("expected unsupported type error, got: %v", err)
+	}
+}
+
 func TestResolvePermApplyTarget_Empty(t *testing.T) {
 	t.Parallel()
 	_, _, err := resolvePermApplyTarget("   ", "docx")

shortcuts/mail/mail_json_shorthand_test.go

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

shortcuts/mail/mail_triage.go

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

shortcuts/mail/mail_watch.go

@@ -99,7 +99,7 @@ var MailWatch = common.Shortcut{
 	Scopes:      []string{"mail:event", "mail:user_mailbox.event.mail_address:read", "mail:user_mailbox:readonly", "mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user"},
 	Flags: []common.Flag{
-		{Name: "format", Default: "data", Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
+		{Name: "format", Default: "data", Enum: []string{"json", "data"}, Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
 		{Name: "msg-format", Default: "metadata", Desc: "message payload mode: metadata(headers + meta, for triage/notification) | minimal(IDs and state only, no headers, for tracking read/folder changes) | plain_text_full(all metadata fields + full plain-text body) | event(raw WebSocket event, no API call, for debug) | full(full message including HTML body and attachments)"},
 		{Name: "output-dir", Desc: "Write each message as a JSON file (always full payload, regardless of --msg-format)"},
 		{Name: "mailbox", Default: "me", Desc: "email address (default: me)"},

skills/lark-doc/SKILL.md

@@ -14,7 +14,7 @@ metadata:
 
 ```bash
 # 常用示例
-lark-cli docs +fetch --doc "文档URL或token，后缀有 #share-... 锚点时会局部读取"
+lark-cli docs +fetch --doc "文档URL或token"
 lark-cli docs +create --content '<title>标题</title><p>内容</p>'
 lark-cli docs +update --doc "文档URL或token" --command append --content '<p>内容</p>'
 ```

skills/lark-doc/references/lark-doc-fetch.md

@@ -17,10 +17,8 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --detail with-ids
 lark-cli docs +fetch --doc Z1Fj...tnAc --scope outline --max-depth 3
 
 # 按 block id 区间精读
-lark-cli docs +fetch --doc Z1Fj...tnAc --scope range --start-block-id blkA --end-block-id blkB --detail with-ids
-
-# URL 带 #share 选区锚点时自动局部读取
-lark-cli docs +fetch --doc 'docURL#share-anchor'
+lark-cli docs +fetch --doc Z1Fj...tnAc \
+  --scope range --start-block-id blkA --end-block-id blkB --detail with-ids
 
 # 读整个章节（以标题 id 为锚点，自动展开到下一个同级/更高级标题前）
 lark-cli docs +fetch --doc Z1Fj...tnAc \

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

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

tests/cli_e2e/docs/docs_fetch_dryrun_test.go

@@ -43,35 +43,6 @@ func TestDocsFetchDryRunIgnoresAPIVersionCompatFlag(t *testing.T) {
 	}
 }
 
-func TestDocsFetchDryRunSelectionAnchorFragmentBecomesRangeStart(t *testing.T) {
-	setDocsDryRunEnv(t)
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"docs", "+fetch",
-			"--doc", "https://example.larksuite.com/wiki/wikcnDryRun#share-CUE3d6Ykno2fkexEvt8cGF8Wnse",
-			"--dry-run",
-		},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-
-	out := result.Stdout
-	if got := gjson.Get(out, "api.0.url").String(); got != "/open-apis/docs_ai/v1/documents/wikcnDryRun/fetch" {
-		t.Fatalf("url=%q, want docs fetch endpoint\nstdout:\n%s", got, out)
-	}
-	if got := gjson.Get(out, "api.0.body.read_option.read_mode").String(); got != "range" {
-		t.Fatalf("read_mode=%q, want range\nstdout:\n%s", got, out)
-	}
-	if got := gjson.Get(out, "api.0.body.read_option.start_block_id").String(); got != "share-CUE3d6Ykno2fkexEvt8cGF8Wnse" {
-		t.Fatalf("start_block_id=%q, want selection anchor\nstdout:\n%s", got, out)
-	}
-}
-
 func setDocsDryRunEnv(t *testing.T) {
 	t.Helper()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())