feat(wiki): add exponential backoff retry for +node-create lock contention (#1012) (#1076)

When creating wiki nodes under the same parent concurrently, the API
returns error code 131009 (lock contention) ~5-15% of the time. This
adds automatic retry with exponential backoff (250ms, 500ms; max 2
retries) so callers no longer need to implement retry logic themselves.

- Retry loop in runWikiNodeCreate: only retries on code 131009, respects
  context cancellation, prints progress to stderr
- wrapWikiNodeCreateRetryError preserves Err/Raw/Detail.Code in ExitError
- 6 unit tests covering retry success, exhaustion, non-contention error,
  single-retry success, context cancellation, no-retry on success
- 8 dry-run E2E tests for wiki +node-create request shape and validation

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.39] - 2026-05-22
+
+### Features
+
+- **slides**: Add `+export` shortcut to export slides (#988)
+- **sidecar**: Support multi-client identity isolation in `server-demo` via per-client HMAC keys, preventing UAT cross-contamination when multiple CLI sandboxes share one sidecar (#934)
+- **im**: Support Markdown image rendering in post content (#893)
+
+### Bug Fixes
+
+- **scope**: Add 22 new scope entries to scope priorities (#1050)
+
+### Documentation
+
+- **base**: Update location `full_address` guidance (#754)
+- **apps**: Refine `lark-apps` skill description and surface, document `index.html` / `--path` hard constraints (#1040)
+
+## [v1.0.38] - 2026-05-22
+
+### Features
+
+- **apps**: Gate the Miaoda apps domain off on the Lark brand — the `apps` shortcut subtree returns a structured brand-restriction error, `auth login --domain apps` is rejected, `--domain all` skips it, and `spark:*` scopes are no longer requested (#1025)
+
 ## [v1.0.37] - 2026-05-21
 
 ### Features
@@ -817,6 +840,8 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.39]: https://github.com/larksuite/cli/releases/tag/v1.0.39
+[v1.0.38]: https://github.com/larksuite/cli/releases/tag/v1.0.38
 [v1.0.37]: https://github.com/larksuite/cli/releases/tag/v1.0.37
 [v1.0.36]: https://github.com/larksuite/cli/releases/tag/v1.0.36
 [v1.0.35]: https://github.com/larksuite/cli/releases/tag/v1.0.35

cmd/auth/auth.go

@@ -43,6 +43,7 @@ func NewCmdAuth(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(NewCmdAuthScopes(f, nil))
 	cmd.AddCommand(NewCmdAuthList(f, nil))
 	cmd.AddCommand(NewCmdAuthCheck(f, nil))
+	cmd.AddCommand(NewCmdAuthQRCode(f, nil))
 	return cmd
 }
 

cmd/auth/auth_test.go

@@ -61,7 +61,7 @@ func TestAuthLoginCmd_HelpGuidesNonStreamingAgentsToSplitFlow(t *testing.T) {
 	for _, want := range []string{
 		"only delivers final turn messages",
 		"--no-wait --json",
-		"send the verification URL to the user as your final message",
+		"send the verification URL (or QR code) to the user as your final message",
 		"run --device-code in a later step",
 	} {
 		if !strings.Contains(got, want) {

cmd/auth/login.go

@@ -47,9 +47,10 @@ func NewCmdAuthLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.
 		Long: `Device Flow authorization login.
 
 For AI agents: this command blocks until the user completes authorization in the
-browser. If your harness only delivers final turn messages, use --no-wait --json,
-send the verification URL to the user as your final message, end the turn, then
-run --device-code in a later step after the user confirms authorization.`,
+browser. If your harness or agent tool only delivers final turn messages, use --no-wait --json,
+send the verification URL (or QR code) to the user as your final message, end the turn, then
+run --device-code in a later step after the user confirms authorization. Use 'lark-cli auth qrcode'
+to generate QR codes (supports ASCII and PNG formats).`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if mode := f.ResolveStrictMode(cmd.Context()); mode == core.StrictModeBot {
 				return output.ErrWithHint(output.ExitValidation, "command_denied",
@@ -68,7 +69,13 @@ run --device-code in a later step after the user confirms authorization.`,
 
 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space- or comma-separated). Combines additively with --domain/--recommend")
 	cmd.Flags().BoolVar(&opts.Recommend, "recommend", false, "request only recommended (auto-approve) scopes")
-	available := sortedKnownDomains()
+	var helpBrand core.LarkBrand
+	if f != nil && f.Config != nil {
+		if cfg, err := f.Config(); err == nil && cfg != nil {
+			helpBrand = cfg.Brand
+		}
+	}
+	available := sortedKnownDomains(helpBrand)
 	cmd.Flags().StringSliceVar(&opts.Domains, "domain", nil,
 		fmt.Sprintf("domain (repeatable or comma-separated, e.g. --domain calendar,task)\navailable: %s, all", strings.Join(available, ", ")))
 	cmd.Flags().StringSliceVar(&opts.Exclude, "exclude", nil,
@@ -139,14 +146,14 @@ func authLoginRun(opts *LoginOptions) error {
 	// Expand --domain all to all available domains (from_meta projects + shortcut services)
 	for _, d := range selectedDomains {
 		if strings.EqualFold(d, "all") {
-			selectedDomains = sortedKnownDomains()
+			selectedDomains = sortedKnownDomains(config.Brand)
 			break
 		}
 	}
 
 	// Validate domain names and suggest corrections for unknown ones
 	if len(selectedDomains) > 0 {
-		knownDomains := allKnownDomains()
+		knownDomains := allKnownDomains(config.Brand)
 		for _, d := range selectedDomains {
 			if !knownDomains[d] {
 				if suggestion := suggestDomain(d, knownDomains); suggestion != "" {
@@ -170,7 +177,7 @@ func authLoginRun(opts *LoginOptions) error {
 
 	if !hasAnyOption {
 		if !opts.JSON && f.IOStreams.IsTerminal {
-			result, err := runInteractiveLogin(f.IOStreams, lang, msg)
+			result, err := runInteractiveLogin(f.IOStreams, lang, msg, config.Brand)
 			if err != nil {
 				return err
 			}
@@ -208,10 +215,10 @@ func authLoginRun(opts *LoginOptions) error {
 	if len(selectedDomains) > 0 || opts.Recommend {
 		var candidateScopes []string
 		if len(selectedDomains) > 0 {
-			candidateScopes = collectScopesForDomains(selectedDomains, "user")
+			candidateScopes = collectScopesForDomains(selectedDomains, "user", config.Brand)
 		} else {
 			// --recommend without --domain: all domains
-			candidateScopes = collectScopesForDomains(sortedKnownDomains(), "user")
+			candidateScopes = collectScopesForDomains(sortedKnownDomains(config.Brand), "user", config.Brand)
 		}
 
 		// Filter to auto-approve scopes if --recommend or interactive "common"
@@ -269,7 +276,7 @@ func authLoginRun(opts *LoginOptions) error {
 			"verification_url": authResp.VerificationUriComplete,
 			"device_code":      authResp.DeviceCode,
 			"expires_in":       authResp.ExpiresIn,
-			"hint":             fmt.Sprintf("Show verification_url to the user exactly as returned by the CLI and treat it as an opaque string. Do not URL-encode or decode it, do not normalize or rewrite it, do not add %%20, spaces, or punctuation, and do not wrap it as Markdown link text; prefer a fenced code block containing only the raw URL. For agent harnesses that only deliver final turn messages, make the URL the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s", authResp.DeviceCode),
+			"hint":             fmt.Sprintf("**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL so the user can either scan or copy the link.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation. Prefer a fenced code block containing only the raw URL. For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s", authResp.DeviceCode),
 		}
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)
@@ -452,6 +459,7 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 	return nil
 }
 
+// syncLoginUserToProfile persists the logged-in user info into the named profile.
 func syncLoginUserToProfile(profileName, appID, openID, userName string) error {
 	multi, err := core.LoadMultiAppConfig()
 	if err != nil {
@@ -477,6 +485,7 @@ func syncLoginUserToProfile(profileName, appID, openID, userName string) error {
 	return nil
 }
 
+// findProfileByName returns the AppConfig matching profileName, or nil.
 func findProfileByName(multi *core.MultiAppConfig, profileName string) *core.AppConfig {
 	for i := range multi.Apps {
 		if multi.Apps[i].ProfileName() == profileName {
@@ -490,7 +499,7 @@ func findProfileByName(multi *core.MultiAppConfig, profileName string) *core.App
 // shortcut scopes for the given domain names.
 // Domains with auth_domain children are automatically expanded to include
 // their children's scopes.
-func collectScopesForDomains(domains []string, identity string) []string {
+func collectScopesForDomains(domains []string, identity string, brand core.LarkBrand) []string {
 	scopeSet := make(map[string]bool)
 
 	// 1. API scopes from from_meta projects
@@ -509,6 +518,9 @@ func collectScopesForDomains(domains []string, identity string) []string {
 
 	// 3. Shortcut scopes matching by Service (only include shortcuts supporting the identity)
 	for _, sc := range shortcuts.AllShortcuts() {
+		if !shortcuts.IsShortcutServiceAvailable(sc.Service, brand) {
+			continue
+		}
 		if domainSet[sc.Service] && shortcutSupportsIdentity(sc, identity) {
 			for _, s := range sc.DeclaredScopesForIdentity(identity) {
 				scopeSet[s] = true
@@ -528,7 +540,7 @@ func collectScopesForDomains(domains []string, identity string) []string {
 // allKnownDomains returns all valid auth domain names (from_meta projects +
 // shortcut services), excluding domains that have auth_domain set (they are
 // folded into their parent domain).
-func allKnownDomains() map[string]bool {
+func allKnownDomains(brand core.LarkBrand) map[string]bool {
 	domains := make(map[string]bool)
 	for _, p := range registry.ListFromMetaProjects() {
 		if !registry.HasAuthDomain(p) {
@@ -536,6 +548,9 @@ func allKnownDomains() map[string]bool {
 		}
 	}
 	for _, sc := range shortcuts.AllShortcuts() {
+		if !shortcuts.IsShortcutServiceAvailable(sc.Service, brand) {
+			continue
+		}
 		if !registry.HasAuthDomain(sc.Service) {
 			domains[sc.Service] = true
 		}
@@ -544,8 +559,8 @@ func allKnownDomains() map[string]bool {
 }
 
 // sortedKnownDomains returns all valid domain names sorted alphabetically.
-func sortedKnownDomains() []string {
-	m := allKnownDomains()
+func sortedKnownDomains(brand core.LarkBrand) []string {
+	m := allKnownDomains(brand)
 	domains := make([]string, 0, len(m))
 	for d := range m {
 		domains = append(domains, d)

cmd/auth/login_brand_filter_test.go

@@ -0,0 +1,32 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"testing"
+
+	"github.com/larksuite/cli/internal/core"
+)
+
+func TestBrandFilter_AppsExcludedOnLark(t *testing.T) {
+	feishuDomains := allKnownDomains(core.BrandFeishu)
+	if !feishuDomains["apps"] {
+		t.Errorf("expected apps domain to be known on Feishu brand")
+	}
+
+	larkDomains := allKnownDomains(core.BrandLark)
+	if larkDomains["apps"] {
+		t.Errorf("expected apps domain to be EXCLUDED on Lark brand")
+	}
+
+	feishuScopes := collectScopesForDomains([]string{"apps"}, "user", core.BrandFeishu)
+	if len(feishuScopes) == 0 {
+		t.Errorf("expected non-empty scopes for apps on Feishu brand, got %d", len(feishuScopes))
+	}
+
+	larkScopes := collectScopesForDomains([]string{"apps"}, "user", core.BrandLark)
+	if len(larkScopes) != 0 {
+		t.Errorf("expected empty scopes for apps on Lark brand, got %d: %v", len(larkScopes), larkScopes)
+	}
+}

cmd/auth/login_interactive.go

@@ -11,6 +11,7 @@ import (
 	"github.com/charmbracelet/huh"
 
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
@@ -105,7 +106,7 @@ func buildDomainMeta(name, lang string) domainMeta {
 }
 
 // runInteractiveLogin shows an interactive TUI form for domain and permission selection.
-func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg) (*interactiveResult, error) {
+func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg, brand core.LarkBrand) (*interactiveResult, error) {
 	allDomains := getDomainMetadata(lang)
 
 	// Build multi-select options
@@ -165,7 +166,7 @@ func runInteractiveLogin(ios *cmdutil.IOStreams, lang string, msg *loginMsg) (*i
 	}
 
 	// Compute scope summary
-	scopes := collectScopesForDomains(selectedDomains, "user")
+	scopes := collectScopesForDomains(selectedDomains, "user", brand)
 	if permLevel == "common" {
 		scopes = registry.FilterAutoApproveScopes(scopes)
 	}

cmd/auth/login_messages.go

@@ -59,7 +59,7 @@ var loginMsgZh = &loginMsg{
 
 	OpenURL:            "在浏览器中打开以下链接进行认证:\n\n",
 	WaitingAuth:        "等待用户授权...",
-	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout >= 600s。若你的 harness 只会把最终回复发给用户，请改用 `lark-cli auth login --no-wait --json` 拿到 device_code 和 verification_url，把 verification_url 作为本轮最终消息原样发给用户并结束本轮；等用户回复已完成授权后，再在后续步骤运行 `lark-cli auth login --device-code <code>` 续上轮询。**不要在同一轮里展示 URL 后立刻阻塞执行 --device-code**，也不要短 timeout 反复重试；每次重启会作废上一轮的 device code，导致用户授权链接失效。向用户展示授权链接时，必须逐字原样转发 CLI 返回的 URL，把它视为不可修改的 opaque string；不要做 URL 编码或解码，不要补 `%20`、空格或标点，不要改写成 Markdown 链接，建议用只包含该 URL 的代码块单独输出。",
+	AgentTimeoutHint:   "[AI agent] 此命令最长阻塞约 10 分钟，等待用户在浏览器内完成授权。请确保 runner 的 timeout >= 600s。若你的 harness 或 agent 工具只会把最终回复发给用户，请改用 \"lark-cli auth login --no-wait --json\" 拿到 device_code 和 verification_url，把 verification_url 作为本轮最终消息发给用户并结束本轮；等用户回复已完成授权后，再在后续步骤运行 \"lark-cli auth login --device-code <code>\" 续上轮询。**不要在同一轮里展示 URL 后立刻阻塞执行 --device-code**，也不要短 timeout 反复重试；每次重启会作废上一轮的 device code，导致用户授权链接失效。**必须生成二维码并展示**: 你必须调用 lark-cli auth qrcode 将 verification_url 转为二维码，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。**关键：生成后必须在回复中展示图片**，仅生成文件不算完成，须用 image 标签或内联图片等方式将图片包含在回复中。**展示顺序**: 先输出 URL，再将二维码图片置于 URL 下方完整展示，确保用户可扫码或复制链接。**URL 输出规则**: 将 verification_url 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点），建议用仅包含该 URL 的代码块单独输出。",
 	AuthSuccess:        "已收到授权确认，正在获取用户信息并校验授权结果...",
 	LoginSuccess:       "授权成功! 用户: %s (%s)",
 	AuthorizedUser:     "当前授权账号: %s (%s)",
@@ -95,7 +95,7 @@ var loginMsgEn = &loginMsg{
 
 	OpenURL:            "Open this URL in your browser to authenticate:\n\n",
 	WaitingAuth:        "Waiting for user authorization...",
-	AgentTimeoutHint:   "[AI agent] This command blocks for up to ~10 minutes while waiting for the user to authorize in their browser. Make sure your runner's timeout is >= 600s. If your harness only delivers final turn messages, use `lark-cli auth login --no-wait --json` to get device_code and verification_url, present verification_url to the user exactly as the final message of this turn, then end the turn; after the user replies that they authorized, run `lark-cli auth login --device-code <code>` in a later step to resume polling. **Do NOT show the URL and then immediately block on --device-code in the same turn**, and do not retry with a short timeout; each restart invalidates the previous device code and makes the earlier authorization URL useless. When showing the authorization URL to the user, copy the CLI-returned URL exactly as-is and treat it as an opaque string. Do not URL-encode or decode it, do not add `%20`, spaces, or punctuation, do not rewrite it as Markdown link text, and prefer a fenced code block containing only the raw URL.",
+	AgentTimeoutHint:   "[AI agent] This command blocks for up to ~10 minutes while waiting for the user to authorize in their browser. Make sure your runner's timeout is >= 600s. If your harness or agent tool only delivers final turn messages, use \"lark-cli auth login --no-wait --json\" to get device_code and verification_url, present verification_url to the user exactly as the final message of this turn, then end the turn; after the user replies that they authorized, run \"lark-cli auth login --device-code <code>\" in a later step to resume polling. **Do NOT show the URL and then immediately block on --device-code in the same turn**, and do not retry with a short timeout; each restart invalidates the previous device code and makes the earlier authorization URL useless.**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL so the user can either scan or copy the link.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation. Prefer a fenced code block containing only the raw URL.",
 	AuthSuccess:        "Authorization confirmed, fetching user info and validating granted scopes...",
 	LoginSuccess:       "Authorization successful! User: %s (%s)",
 	AuthorizedUser:     "Authorized account: %s (%s)",
@@ -114,6 +114,7 @@ var loginMsgEn = &loginMsg{
 	HintFooter:  "  lark-cli auth login --help",
 }
 
+// getLoginMsg returns the login message bundle for the given language.
 func getLoginMsg(lang string) *loginMsg {
 	if lang == "en" {
 		return loginMsgEn

cmd/auth/login_test.go

@@ -171,7 +171,7 @@ func TestCompleteDomain_CommaSeparated(t *testing.T) {
 }
 
 func TestAllKnownDomains(t *testing.T) {
-	domains := allKnownDomains()
+	domains := allKnownDomains("")
 	if len(domains) == 0 {
 		t.Fatal("expected non-empty known domains")
 	}
@@ -185,7 +185,7 @@ func TestAllKnownDomains(t *testing.T) {
 }
 
 func TestSortedKnownDomains(t *testing.T) {
-	sorted := sortedKnownDomains()
+	sorted := sortedKnownDomains("")
 	if len(sorted) == 0 {
 		t.Fatal("expected non-empty sorted domains")
 	}
@@ -195,7 +195,7 @@ func TestSortedKnownDomains(t *testing.T) {
 	}
 
 	// Should match allKnownDomains
-	known := allKnownDomains()
+	known := allKnownDomains("")
 	if len(sorted) != len(known) {
 		t.Errorf("sorted (%d) and known (%d) length mismatch", len(sorted), len(known))
 	}
@@ -220,7 +220,7 @@ func TestCollectScopesForDomains(t *testing.T) {
 		t.Skip("no from_meta data available")
 	}
 
-	scopes := collectScopesForDomains([]string{"calendar"}, "user")
+	scopes := collectScopesForDomains([]string{"calendar"}, "user", "")
 	if len(scopes) == 0 {
 		t.Fatal("expected non-empty scopes for calendar domain")
 	}
@@ -247,7 +247,7 @@ func TestCollectScopesForDomains(t *testing.T) {
 }
 
 func TestCollectScopesForDomains_NonexistentDomain(t *testing.T) {
-	scopes := collectScopesForDomains([]string{"nonexistent_domain_xyz"}, "user")
+	scopes := collectScopesForDomains([]string{"nonexistent_domain_xyz"}, "user", "")
 	if len(scopes) != 0 {
 		t.Errorf("expected empty scopes for nonexistent domain, got %d", len(scopes))
 	}
@@ -945,12 +945,20 @@ func TestAuthLoginRun_NoWaitJSONHintIncludesRawURLGuidance(t *testing.T) {
 	}
 	hint, _ := data["hint"].(string)
 	for _, want := range []string{
-		"exactly as returned by the CLI",
+		"MUST generate QR code AND display it",
+		"lark-cli auth qrcode",
+		"Prefer PNG QR code (--output)",
+		"use ASCII (--ascii) only when the user explicitly requests it",
+		"This is a required step, do NOT skip it",
+		"CRITICAL",
+		"You MUST include the QR image in your response",
+		"Generating the file alone is NOT enough",
+		"image tags, inline images, or file attachments",
+		"Display order",
+		"place the QR code image below the URL",
 		"opaque string",
-		"Do not URL-encode or decode it",
-		"do not add %20, spaces, or punctuation",
-		"do not wrap it as Markdown link text",
-		"fenced code block containing only the raw URL",
+		"cannot be modified",
+		"Prefer a fenced code block",
 		"final message of the turn",
 		"return control to the user",
 		"do not block on --device-code in the same turn",
@@ -1054,12 +1062,18 @@ func TestAuthLoginRun_JSONDeviceAuthorizationAgentHintIncludesRawURLGuidance(t *
 		"结束本轮",
 		"用户回复已完成授权",
 		"不要在同一轮里展示 URL 后立刻阻塞执行 --device-code",
-		"逐字原样转发 CLI 返回的 URL",
+		"必须生成二维码并展示",
+		"lark-cli auth qrcode",
+		"优先生成 PNG 二维码（--output）",
+		"仅当用户明确要求时才使用 ASCII（--ascii）",
+		"生成后必须在回复中展示图片",
+		"仅生成文件不算完成",
+		"image 标签或内联图片",
+		"二维码图片置于 URL 下方完整展示",
+		"URL 输出规则",
 		"opaque string",
-		"不要做 URL 编码或解码",
-		"不要补 `%20`、空格或标点",
-		"不要改写成 Markdown 链接",
-		"只包含该 URL 的代码块单独输出",
+		"不要做任何修改",
+		"仅包含该 URL 的代码块",
 	} {
 		if !strings.Contains(hint, want) {
 			t.Fatalf("agent_hint missing %q, got:\n%s", want, hint)
@@ -1077,7 +1091,7 @@ func TestGetDomainMetadata_ExcludesEvent(t *testing.T) {
 }
 
 func TestAllKnownDomains_ExcludesAuthDomainChildren(t *testing.T) {
-	domains := allKnownDomains()
+	domains := allKnownDomains("")
 	if domains["whiteboard"] {
 		t.Error("whiteboard should not appear in known auth domains (it has auth_domain=docs)")
 	}
@@ -1087,7 +1101,7 @@ func TestAllKnownDomains_ExcludesAuthDomainChildren(t *testing.T) {
 }
 
 func TestCollectScopesForDomains_ExpandsAuthDomainChildren(t *testing.T) {
-	scopes := collectScopesForDomains([]string{"docs"}, "user")
+	scopes := collectScopesForDomains([]string{"docs"}, "user", "")
 	// docs domain should include whiteboard shortcut scopes (board:whiteboard:*)
 	found := false
 	for _, s := range scopes {

cmd/auth/qrcode.go

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/skip2/go-qrcode"
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// QRCodeOptions holds inputs for auth qrcode command.
+type QRCodeOptions struct {
+	Factory *cmdutil.Factory
+	Ctx     context.Context
+	URL     string
+	Size    int
+	ASCII   bool
+	Output  string
+}
+
+// NewCmdAuthQRCode creates the auth qrcode subcommand.
+func NewCmdAuthQRCode(f *cmdutil.Factory, runF func(*QRCodeOptions) error) *cobra.Command {
+	opts := &QRCodeOptions{Factory: f, Size: 256}
+
+	cmd := &cobra.Command{
+		Use:   "qrcode <url>",
+		Short: "Generate QR code for verification URL",
+		Long: `Generate a QR code image or ASCII representation for a verification URL.
+
+This command is designed for AI agents to generate QR codes for OAuth authorization URLs.
+
+For PNG output, the --output flag is required to specify the output file path (must be a relative path within the current directory).
+For ASCII output, the result is printed to stdout with fixed size.`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.URL = args[0]
+			opts.Ctx = cmd.Context()
+			if runF != nil {
+				return runF(opts)
+			}
+			return runQRCode(opts)
+		},
+	}
+
+	cmd.Flags().IntVar(&opts.Size, "size", 256, "Size of the QR code image in pixels (default: 256, for PNG mode only)")
+	cmd.Flags().BoolVar(&opts.ASCII, "ascii", false, "Output ASCII QR code to stdout")
+	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "Output file path for PNG image (relative path within current directory, required for non-ASCII mode)")
+
+	return cmd
+}
+
+// runQRCode executes the auth qrcode command.
+func runQRCode(opts *QRCodeOptions) error {
+	if opts.URL == "" {
+		return output.Errorf(output.ExitValidation, "missing_url", "url is required")
+	}
+
+	if opts.ASCII {
+		var out io.Writer = os.Stdout
+		if opts.Factory != nil {
+			out = opts.Factory.IOStreams.Out
+		}
+		return generateASCIIQRCode(opts.URL, out)
+	}
+
+	if opts.Output == "" {
+		return output.Errorf(output.ExitValidation, "missing_output", "output file path is required for PNG mode. Use --output or -o flag to specify the output file path.")
+	}
+
+	if opts.Size < 32 {
+		return output.Errorf(output.ExitValidation, "invalid_size", fmt.Sprintf("size must be at least 32, got %d", opts.Size))
+	}
+
+	if opts.Size > 1024 {
+		return output.Errorf(output.ExitValidation, "invalid_size", fmt.Sprintf("size must be at most 1024, got %d", opts.Size))
+	}
+
+	safePath, err := validate.SafeOutputPath(opts.Output)
+	if err != nil {
+		return output.ErrValidation("unsafe output path: %s", err)
+	}
+
+	if err := generateImageQRCode(opts.URL, opts.Size, safePath); err != nil {
+		return err
+	}
+
+	result := map[string]interface{}{
+		"ok":        true,
+		"file_path": safePath,
+		"hint":      "You MUST include the QR image in your response. Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.",
+	}
+
+	var out io.Writer = os.Stdout
+	if opts.Factory != nil {
+		out = opts.Factory.IOStreams.Out
+	}
+	encoder := json.NewEncoder(out)
+	encoder.SetEscapeHTML(false)
+	if err := encoder.Encode(result); err != nil {
+		return output.Errorf(output.ExitInternal, "internal", "failed to write output: %v", err)
+	}
+
+	return nil
+}
+
+// generateImageQRCode encodes the URL as a PNG QR code and writes it to outputPath.
+func generateImageQRCode(url string, size int, outputPath string) error {
+	png, err := qrcode.Encode(url, qrcode.Medium, size)
+	if err != nil {
+		return output.Errorf(output.ExitInternal, "encode_error", fmt.Sprintf("failed to encode QR code: %v", err))
+	}
+
+	err = vfs.WriteFile(outputPath, png, 0644)
+	if err != nil {
+		return output.Errorf(output.ExitInternal, "write_error", fmt.Sprintf("failed to write QR code to %s: %v", outputPath, err))
+	}
+
+	return nil
+}
+
+// generateASCIIQRCode encodes the URL as an ASCII QR code and prints it to stdout.
+func generateASCIIQRCode(url string, w io.Writer) error {
+	q, err := qrcode.New(url, qrcode.Medium)
+	if err != nil {
+		return output.Errorf(output.ExitInternal, "encode_error", fmt.Sprintf("failed to create QR code: %v", err))
+	}
+
+	fmt.Fprint(w, q.ToSmallString(false))
+
+	return nil
+}

cmd/auth/qrcode_test.go

@@ -0,0 +1,368 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+func TestNewCmdAuthQRCode_FlagParsing(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *QRCodeOptions
+	cmd := NewCmdAuthQRCode(f, func(opts *QRCodeOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"https://example.com", "--output", "qr.png", "--size", "128"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts.URL != "https://example.com" {
+		t.Errorf("URL = %q, want %q", gotOpts.URL, "https://example.com")
+	}
+	if gotOpts.Size != 128 {
+		t.Errorf("Size = %d, want %d", gotOpts.Size, 128)
+	}
+	if gotOpts.Output != "qr.png" {
+		t.Errorf("Output = %q, want %q", gotOpts.Output, "qr.png")
+	}
+	if gotOpts.ASCII {
+		t.Error("ASCII should be false by default")
+	}
+}
+
+func TestNewCmdAuthQRCode_ASCIIFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *QRCodeOptions
+	cmd := NewCmdAuthQRCode(f, func(opts *QRCodeOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"https://example.com", "--ascii"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !gotOpts.ASCII {
+		t.Error("ASCII should be true when --ascii is passed")
+	}
+}
+
+func TestNewCmdAuthQRCode_DefaultSize(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	var gotOpts *QRCodeOptions
+	cmd := NewCmdAuthQRCode(f, func(opts *QRCodeOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"https://example.com", "--ascii"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts.Size != 256 {
+		t.Errorf("default Size = %d, want 256", gotOpts.Size)
+	}
+}
+
+func TestNewCmdAuthQRCode_ExactOneArg(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdAuthQRCode(f, nil)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs([]string{})
+	if err := cmd.Execute(); err == nil {
+		t.Fatal("expected error when no URL argument provided")
+	}
+}
+
+func TestNewCmdAuthQRCode_RunE_PNGEndToEnd(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	tmpDir := t.TempDir()
+	oldWd, _ := os.Getwd()
+	if err := os.Chdir(tmpDir); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+	t.Cleanup(func() { os.Chdir(oldWd) })
+
+	cmd := NewCmdAuthQRCode(f, nil)
+	cmd.SetArgs([]string{"https://example.com", "--output", "qr.png"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data, err := os.ReadFile("qr.png")
+	if err != nil {
+		t.Fatalf("output file not created: %v", err)
+	}
+	if string(data[:4]) != "\x89PNG" {
+		t.Errorf("output does not start with PNG magic bytes, got %x", data[:4])
+	}
+
+	var result map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &result); err != nil {
+		t.Fatalf("stdout is not valid JSON: %v, got: %s", err, stdout.String())
+	}
+	if result["ok"] != true {
+		t.Errorf("ok = %v, want true", result["ok"])
+	}
+	hint, _ := result["hint"].(string)
+	if hint == "" {
+		t.Error("hint is empty")
+	}
+	if !strings.Contains(hint, "MUST include") {
+		t.Errorf("hint missing 'MUST include', got: %s", hint)
+	}
+	if !strings.Contains(hint, "NOT enough") {
+		t.Errorf("hint missing 'NOT enough', got: %s", hint)
+	}
+}
+
+func TestNewCmdAuthQRCode_RunE_MissingOutput(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdAuthQRCode(f, nil)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs([]string{"https://example.com"})
+	if err := cmd.Execute(); err == nil {
+		t.Fatal("expected error when --output is missing in PNG mode")
+	}
+}
+
+func TestNewCmdAuthQRCode_HelpText(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdAuthQRCode(f, nil)
+	cmd.SetOut(stdout)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs([]string{"--help"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{
+		"qrcode <url>",
+		"QR code",
+		"--output",
+		"--ascii",
+		"relative path",
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("help missing %q", want)
+		}
+	}
+}
+
+func TestRunQRCode_MissingURL(t *testing.T) {
+	err := runQRCode(&QRCodeOptions{URL: ""})
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail.Type != "missing_url" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "missing_url")
+	}
+}
+
+func TestRunQRCode_MissingOutput(t *testing.T) {
+	err := runQRCode(&QRCodeOptions{URL: "https://example.com", Size: 256})
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail.Type != "missing_output" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "missing_output")
+	}
+}
+
+func TestRunQRCode_InvalidSize(t *testing.T) {
+	err := runQRCode(&QRCodeOptions{
+		URL:    "https://example.com",
+		Size:   16,
+		Output: "qr.png",
+	})
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail.Type != "invalid_size" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "invalid_size")
+	}
+}
+
+func TestRunQRCode_SizeTooLarge(t *testing.T) {
+	err := runQRCode(&QRCodeOptions{
+		URL:    "https://example.com",
+		Size:   2048,
+		Output: "qr.png",
+	})
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+	if exitErr.Detail.Type != "invalid_size" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "invalid_size")
+	}
+}
+
+func TestRunQRCode_UnsafeOutputPath(t *testing.T) {
+	err := runQRCode(&QRCodeOptions{
+		URL:    "https://example.com",
+		Size:   256,
+		Output: "/etc/passwd",
+	})
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitValidation)
+	}
+}
+
+func TestRunQRCode_PNGWritesFile(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	tmpDir := t.TempDir()
+	oldWd, _ := os.Getwd()
+	if err := os.Chdir(tmpDir); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+	t.Cleanup(func() { os.Chdir(oldWd) })
+
+	err := runQRCode(&QRCodeOptions{
+		URL:     "https://example.com",
+		Size:    256,
+		Output:  "qr.png",
+		Factory: f,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	info, err := os.Stat("qr.png")
+	if err != nil {
+		t.Fatalf("output file not created: %v", err)
+	}
+	if info.Size() == 0 {
+		t.Error("output file is empty")
+	}
+
+	var result map[string]interface{}
+	if jsonErr := json.Unmarshal(stdout.Bytes(), &result); jsonErr != nil {
+		t.Fatalf("stdout is not valid JSON: %v, got: %s", jsonErr, stdout.String())
+	}
+	if result["ok"] != true {
+		t.Errorf("ok = %v, want true", result["ok"])
+	}
+}
+
+func TestRunQRCode_ASCIIOutputsToStdout(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	err := runQRCode(&QRCodeOptions{
+		URL:     "https://example.com",
+		ASCII:   true,
+		Factory: f,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if stdout.Len() == 0 {
+		t.Error("ASCII QR code produced no output")
+	}
+}
+
+func TestGenerateImageQRCode_Success(t *testing.T) {
+	tmpDir := t.TempDir()
+	outputPath := filepath.Join(tmpDir, "test-qr.png")
+
+	if err := generateImageQRCode("https://example.com", 256, outputPath); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data, err := os.ReadFile(outputPath)
+	if err != nil {
+		t.Fatalf("failed to read output file: %v", err)
+	}
+	if len(data) == 0 {
+		t.Error("output file is empty")
+	}
+	if len(data) < 8 {
+		t.Error("output too small to be a valid PNG")
+	}
+	if string(data[:4]) != "\x89PNG" {
+		t.Errorf("output does not start with PNG magic bytes, got %x", data[:4])
+	}
+}
+
+func TestGenerateImageQRCode_WriteError(t *testing.T) {
+	err := generateImageQRCode("https://example.com", 256, "/nonexistent/deep/nested/dir/qr.png")
+	if err == nil {
+		t.Fatal("expected error writing to nonexistent directory")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitInternal {
+		t.Errorf("exit code = %d, want %d", exitErr.Code, output.ExitInternal)
+	}
+	if exitErr.Detail.Type != "write_error" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "write_error")
+	}
+}
+
+func TestGenerateASCIIQRCode_Success(t *testing.T) {
+	var buf strings.Builder
+	err := generateASCIIQRCode("https://example.com", &buf)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if buf.Len() == 0 {
+		t.Error("ASCII QR code produced no output")
+	}
+}
+
+func TestGenerateASCIIQRCode_EmptyString(t *testing.T) {
+	var buf strings.Builder
+	err := generateASCIIQRCode("", &buf)
+	if err == nil {
+		t.Fatal("expected error for empty string")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Detail.Type != "encode_error" {
+		t.Errorf("error type = %q, want %q", exitErr.Detail.Type, "encode_error")
+	}
+}

cmd/root.go

@@ -10,7 +10,6 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"net/url"
 	"os"
 	"sort"
 	"strconv"
@@ -389,8 +388,8 @@ func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	if exitErr.Detail == nil || exitErr.Detail.Type != "permission" {
 		return
 	}
-	// Extract required scopes from API error detail
-	scopes := extractRequiredScopes(exitErr.Detail.Detail)
+	// Extract required scopes from API error detail (shared helper)
+	scopes := registry.ExtractRequiredScopes(exitErr.Detail.Detail)
 	if len(scopes) == 0 {
 		return
 	}
@@ -401,21 +400,10 @@ func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
 	}
 
 	// Select the recommended (least-privilege) scope
-	scopeIfaces := make([]interface{}, len(scopes))
-	for i, s := range scopes {
-		scopeIfaces[i] = s
-	}
-	recommended := registry.SelectRecommendedScope(scopeIfaces, "tenant")
-	if recommended == "" {
-		recommended = scopes[0]
-	}
+	recommended := registry.SelectRecommendedScopeFromStrings(scopes, "tenant")
 
 	// Build admin console URL with the recommended scope
-	host := "open.feishu.cn"
-	if cfg.Brand == "lark" {
-		host = "open.larksuite.com"
-	}
-	consoleURL := fmt.Sprintf("https://%s/page/scope-apply?clientID=%s&scopes=%s", host, url.QueryEscape(cfg.AppID), url.QueryEscape(recommended))
+	consoleURL := registry.BuildConsoleScopeURL(cfg.Brand, cfg.AppID, recommended)
 
 	// Clear raw API detail — useful info is now in message/hint/console_url
 	exitErr.Detail.Detail = nil
@@ -452,26 +440,3 @@ func enrichPermissionError(f *cmdutil.Factory, exitErr *output.ExitError) {
 		exitErr.Detail.ConsoleURL = consoleURL
 	}
 }
-
-// extractRequiredScopes extracts scope names from the API error's permission_violations field.
-func extractRequiredScopes(detail interface{}) []string {
-	m, ok := detail.(map[string]interface{})
-	if !ok {
-		return nil
-	}
-	violations, ok := m["permission_violations"].([]interface{})
-	if !ok {
-		return nil
-	}
-	var scopes []string
-	for _, v := range violations {
-		vm, ok := v.(map[string]interface{})
-		if !ok {
-			continue
-		}
-		if subject, ok := vm["subject"].(string); ok {
-			scopes = append(scopes, subject)
-		}
-	}
-	return scopes
-}

internal/output/lark_errors.go

@@ -39,6 +39,10 @@ const (
 	LarkErrDriveCrossTenantUnit    = 1064510 // cross tenant and unit not support
 	LarkErrDriveCrossBrand         = 1064511 // cross brand not support
 
+	// Wiki write-path lock contention (e.g. concurrent wiki +node-create under the
+	// same parent). Server-side write lock; transient, safe to retry with backoff.
+	LarkErrWikiLockContention = 131009
+
 	// Sheets float image: width/height/offset out of range or invalid.
 	LarkErrSheetsFloatImageInvalidDims = 1310246
 
@@ -83,6 +87,8 @@ func ClassifyLarkError(code int, msg string) (int, string, string) {
 	// drive-specific constraints that benefit from actionable hints
 	case LarkErrDriveResourceContention:
 		return ExitAPI, "conflict", "please retry later and avoid concurrent duplicate requests"
+	case LarkErrWikiLockContention:
+		return ExitAPI, "conflict", "wiki write lock contention on this parent node; retry with exponential backoff or serialize sibling-node writes"
 	case LarkErrDriveCrossTenantUnit:
 		return ExitAPI, "cross_tenant_unit", "operate on source and target within the same tenant and region/unit"
 	case LarkErrDriveCrossBrand:

internal/output/lark_errors_test.go

@@ -90,3 +90,24 @@ func TestClassifyLarkError_DriveCreateShortcutConstraints(t *testing.T) {
 		})
 	}
 }
+
+// TestClassifyLarkError_WikiLockContention verifies the wiki write-lock
+// contention error (131009) maps to an actionable retry hint instead of
+// a generic "api_error". Surfaces during concurrent wiki +node-create
+// against the same parent (see larksuite/cli#1012).
+func TestClassifyLarkError_WikiLockContention(t *testing.T) {
+	t.Parallel()
+	gotExitCode, gotType, gotHint := ClassifyLarkError(LarkErrWikiLockContention, "raw msg")
+	if gotExitCode != ExitAPI {
+		t.Fatalf("exitCode=%d, want %d", gotExitCode, ExitAPI)
+	}
+	if gotType != "conflict" {
+		t.Fatalf("type=%q, want %q", gotType, "conflict")
+	}
+	if !strings.Contains(gotHint, "wiki write lock") {
+		t.Fatalf("hint=%q, want substring %q", gotHint, "wiki write lock")
+	}
+	if !strings.Contains(gotHint, "backoff") {
+		t.Fatalf("hint=%q, want substring %q", gotHint, "backoff")
+	}
+}

internal/registry/scope_hint.go

@@ -0,0 +1,82 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package registry
+
+import (
+	"fmt"
+	"net/url"
+
+	"github.com/larksuite/cli/internal/core"
+)
+
+// ExtractRequiredScopes pulls scope names out of the API error's
+// permission_violations field. The detail argument is the raw `error` block
+// that the platform returns alongside lark code 99991672 / 99991679 — typically
+// shaped as:
+//
+//	{ "permission_violations": [ {"subject": "<scope>"}, ... ] }
+//
+// Returns nil when the structure does not match or no non-empty subjects are
+// present, so callers can branch on a simple len() == 0 check.
+func ExtractRequiredScopes(detail interface{}) []string {
+	m, ok := detail.(map[string]interface{})
+	if !ok {
+		return nil
+	}
+	violations, ok := m["permission_violations"].([]interface{})
+	if !ok {
+		return nil
+	}
+	scopes := make([]string, 0, len(violations))
+	for _, v := range violations {
+		vm, ok := v.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if subject, ok := vm["subject"].(string); ok && subject != "" {
+			scopes = append(scopes, subject)
+		}
+	}
+	if len(scopes) == 0 {
+		return nil
+	}
+	return scopes
+}
+
+// SelectRecommendedScopeFromStrings is a string-typed convenience wrapper
+// around SelectRecommendedScope. When no scope is recognized by the priority
+// table, it falls back to the first input scope so callers always have
+// something to surface to users.
+func SelectRecommendedScopeFromStrings(scopes []string, identity string) string {
+	if len(scopes) == 0 {
+		return ""
+	}
+	ifaces := make([]interface{}, len(scopes))
+	for i, s := range scopes {
+		ifaces[i] = s
+	}
+	if recommended := SelectRecommendedScope(ifaces, identity); recommended != "" {
+		return recommended
+	}
+	return scopes[0]
+}
+
+// BuildConsoleScopeURL returns the developer-console "apply scope" URL for the
+// given app and scope, branded for feishu / lark. Returns "" when appID or
+// scope is empty so callers can omit the field cleanly.
+func BuildConsoleScopeURL(brand core.LarkBrand, appID, scope string) string {
+	if appID == "" || scope == "" {
+		return ""
+	}
+	host := "open.feishu.cn"
+	if brand == core.BrandLark {
+		host = "open.larksuite.com"
+	}
+	return fmt.Sprintf(
+		"https://%s/page/scope-apply?clientID=%s&scopes=%s",
+		host,
+		url.QueryEscape(appID),
+		url.QueryEscape(scope),
+	)
+}

internal/registry/scope_hint_test.go

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package registry
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/core"
+)
+
+func TestExtractRequiredScopes_HappyPath(t *testing.T) {
+	detail := map[string]interface{}{
+		"permission_violations": []interface{}{
+			map[string]interface{}{"subject": "docs:permission.member:create"},
+			map[string]interface{}{"subject": "docs:doc"},
+			map[string]interface{}{"subject": ""}, // empty subject filtered
+			"not-a-map",                           // ignored
+		},
+	}
+	got := ExtractRequiredScopes(detail)
+	want := []string{"docs:permission.member:create", "docs:doc"}
+	if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+		t.Fatalf("ExtractRequiredScopes mismatch: got %v, want %v", got, want)
+	}
+}
+
+func TestExtractRequiredScopes_NilOrMalformed(t *testing.T) {
+	cases := []interface{}{
+		nil,
+		"plain string",
+		map[string]interface{}{},
+		map[string]interface{}{"permission_violations": "not-a-list"},
+		map[string]interface{}{"permission_violations": []interface{}{}},
+		map[string]interface{}{"permission_violations": []interface{}{
+			map[string]interface{}{"subject": ""},
+		}},
+	}
+	for i, in := range cases {
+		if got := ExtractRequiredScopes(in); got != nil {
+			t.Errorf("case %d: expected nil, got %v", i, got)
+		}
+	}
+}
+
+func TestBuildConsoleScopeURL_BrandSpecificHost(t *testing.T) {
+	got := BuildConsoleScopeURL(core.BrandFeishu, "cli_xxx", "docs:permission.member:create")
+	if !strings.Contains(got, "open.feishu.cn") {
+		t.Errorf("feishu brand should use open.feishu.cn host, got %s", got)
+	}
+	if !strings.Contains(got, "clientID=cli_xxx") {
+		t.Errorf("missing app id in url: %s", got)
+	}
+	if !strings.Contains(got, "scopes=docs%3Apermission.member%3Acreate") {
+		t.Errorf("scope not URL-escaped: %s", got)
+	}
+
+	got = BuildConsoleScopeURL(core.BrandLark, "cli_yyy", "drive:drive")
+	if !strings.Contains(got, "open.larksuite.com") {
+		t.Errorf("lark brand should use open.larksuite.com host, got %s", got)
+	}
+}
+
+func TestBuildConsoleScopeURL_EmptyInput(t *testing.T) {
+	if got := BuildConsoleScopeURL(core.BrandFeishu, "", "docs:doc"); got != "" {
+		t.Errorf("empty appID should yield empty url, got %s", got)
+	}
+	if got := BuildConsoleScopeURL(core.BrandFeishu, "cli_xxx", ""); got != "" {
+		t.Errorf("empty scope should yield empty url, got %s", got)
+	}
+}
+
+func TestSelectRecommendedScopeFromStrings_FallsBackToFirst(t *testing.T) {
+	ensureFreshRegistry(t)
+	// Unknown scopes (not in priority table) → fallback to first
+	got := SelectRecommendedScopeFromStrings([]string{"unknown:foo", "unknown:bar"}, "tenant")
+	if got != "unknown:foo" {
+		t.Errorf("expected fallback to first, got %s", got)
+	}
+}
+
+// When at least one scope is recognized by the priority table, the
+// recommended scope wins over the fallback (first input).
+func TestSelectRecommendedScopeFromStrings_PicksKnownScopeOverFallback(t *testing.T) {
+	ensureFreshRegistry(t)
+	// docs:permission.member:create is recommended (recommend=true) in
+	// scope_priorities.json. Putting an unknown scope first would otherwise
+	// win via the fallback path; this ensures the priority table is consulted
+	// before falling back.
+	got := SelectRecommendedScopeFromStrings([]string{"unknown:foo", "docs:permission.member:create"}, "tenant")
+	if got != "docs:permission.member:create" {
+		t.Errorf("expected priority-table winner, got %s", got)
+	}
+}
+
+func TestSelectRecommendedScopeFromStrings_Empty(t *testing.T) {
+	if got := SelectRecommendedScopeFromStrings(nil, "tenant"); got != "" {
+		t.Errorf("nil slice should return empty, got %s", got)
+	}
+	if got := SelectRecommendedScopeFromStrings([]string{}, "tenant"); got != "" {
+		t.Errorf("empty slice should return empty, got %s", got)
+	}
+}

internal/registry/scope_priorities.json

@@ -5568,5 +5568,115 @@
     "scope_name": "speech_to_text:speech",
     "final_score": "70.8755",
     "recommend": "true"
+  },
+  {
+    "scope_name": "spark:app:publish",
+    "final_score": "75.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "spark:app.access_scope:read",
+    "final_score": "88.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "spark:app.access_scope:write",
+    "final_score": "83.6587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "spark:app:read",
+    "final_score": "88.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "spark:app:write",
+    "final_score": "76.7173",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "docs:secure_label:write_only",
+    "final_score": "75.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "corehr:job_change_v2:read",
+    "final_score": "75.9982",
+    "recommend": "false"
+  },
+  {
+    "scope_name": "corehr:pre_hire.contract_file_id:read",
+    "final_score": "80.0587",
+    "recommend": "false"
+  },
+  {
+    "scope_name": "im:chat.user_setting:read",
+    "final_score": "88.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "minutes:minutes.upload:write",
+    "final_score": "83.6587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "im:feed.flag:write",
+    "final_score": "79.5982",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "im:feed.flag:read",
+    "final_score": "88.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "search:bot",
+    "final_score": "67.0587",
+    "recommend": "false"
+  },
+  {
+    "scope_name": "application:bot.basic_info:read",
+    "final_score": "88.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "drive:quota_detail:read_one",
+    "final_score": "75.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "docs:permission.member:apply",
+    "final_score": "83.6587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "corehr:employment.custom_field:write",
+    "final_score": "75.6587",
+    "recommend": "false"
+  },
+  {
+    "scope_name": "im:message.group_at_msg.include_bot:readonly",
+    "final_score": "88.9982",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "okr:okr.setting:read",
+    "final_score": "80.0587",
+    "recommend": "false"
+  },
+  {
+    "scope_name": "directory:employee.base.leader_id:read",
+    "final_score": "88.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "directory:employee.base.dotted_line_leaders:read",
+    "final_score": "88.0587",
+    "recommend": "true"
+  },
+  {
+    "scope_name": "directory:employee.base.active_status:read",
+    "final_score": "80.0587",
+    "recommend": "false"
   }
 ]

package.json

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

shortcuts/common/permission_grant.go

@@ -4,9 +4,12 @@
 package common
 
 import (
+	"errors"
 	"fmt"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/internal/validate"
 )
 
@@ -81,6 +84,12 @@ func autoGrantCurrentUserDrivePermission(runtime *RuntimeContext, token, resourc
 			fmt.Sprintf("Resource was created, but granting current user %s failed: %s. You can retry later or continue using bot identity.", permissionGrantPermMessage(), errMsg),
 			fmt.Sprintf("Auto-grant failed: %s. The app may lack the required scope or the resource restricts permission changes.", errMsg),
 		)
+		// Best-effort: when the underlying error is a structured permission
+		// ExitError (lark code 99991672/99991679), surface lark_code,
+		// required_scope and console_url so agents can guide users straight
+		// to the dev console. Overrides the generic hint with a more
+		// actionable one when console_url is available.
+		annotateGrantPermissionError(runtime, result, err)
 		fmt.Fprintf(runtime.IO().ErrOut, "Warning: resource was created, but auto-grant failed: %s. Retry later or grant permission manually.\n", errMsg)
 		return result
 	}
@@ -151,3 +160,54 @@ func compactPermissionGrantError(err error) string {
 	}
 	return strings.Join(strings.Fields(err.Error()), " ")
 }
+
+// annotateGrantPermissionError enriches a failed permission_grant result with
+// structured fields (lark_code / required_scope / console_url) when the
+// underlying error is a permission-class *output.ExitError. The CLI's main
+// permission-error path (cmd/root.go::enrichPermissionError) handles the same
+// case for top-level failures; this helper covers best-effort sub-calls whose
+// error is folded into a result map instead of propagated as ExitError.
+//
+// When console_url is available, the existing generic hint is overridden with
+// a more actionable one pointing at the developer console — that's the
+// concrete next step a user can take.
+func annotateGrantPermissionError(runtime *RuntimeContext, result map[string]interface{}, err error) {
+	if runtime == nil || result == nil || err == nil {
+		return
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		return
+	}
+	if exitErr.Detail.Type != "permission" {
+		return
+	}
+	if exitErr.Detail.Code != 0 {
+		result["lark_code"] = exitErr.Detail.Code
+	}
+
+	scopes := registry.ExtractRequiredScopes(exitErr.Detail.Detail)
+	if len(scopes) == 0 {
+		return
+	}
+	recommended := registry.SelectRecommendedScopeFromStrings(scopes, "tenant")
+	if recommended == "" {
+		return
+	}
+	result["required_scope"] = recommended
+
+	if runtime.Config == nil || runtime.Config.AppID == "" {
+		return
+	}
+	consoleURL := registry.BuildConsoleScopeURL(runtime.Config.Brand, runtime.Config.AppID, recommended)
+	if consoleURL == "" {
+		return
+	}
+	result["console_url"] = consoleURL
+	// Override the generic hint: pointing at the dev console is more actionable
+	// than the generic "retry later" fallback set by buildPermissionGrantResult.
+	result["hint"] = fmt.Sprintf(
+		"App is missing the %q scope; enable it in the developer console (see console_url), then retry.",
+		recommended,
+	)
+}

shortcuts/common/permission_grant_test.go

@@ -5,12 +5,14 @@ package common
 
 import (
 	"context"
+	"errors"
 	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 )
 
 func TestAutoGrantStderrWarning_SkippedNoUser(t *testing.T) {
@@ -94,3 +96,216 @@ func TestAutoGrantStderrWarning_GrantFailed(t *testing.T) {
 		t.Fatalf("hint = %#v, want string containing 'permission changes'", result["hint"])
 	}
 }
+
+// ── annotateGrantPermissionError unit tests ────────────────────────────────
+
+func newAnnotateRuntime(brand core.LarkBrand, appID string) *RuntimeContext {
+	return &RuntimeContext{
+		Config: &core.CliConfig{
+			AppID: appID,
+			Brand: brand,
+		},
+	}
+}
+
+// permission_violations subjects must surface as required_scope, and the
+// console_url must be brand-specific. The hint should be overridden to point
+// at the developer console.
+func TestAnnotateGrantPermissionError_AppScopeNotEnabled(t *testing.T) {
+	rt := newAnnotateRuntime(core.BrandFeishu, "cli_demo")
+	result := map[string]interface{}{
+		"hint": "generic fallback hint",
+	}
+
+	err := output.ErrAPI(99991672, "Permission denied [99991672]", map[string]interface{}{
+		"permission_violations": []interface{}{
+			map[string]interface{}{"subject": "docs:permission.member:create"},
+		},
+	})
+
+	annotateGrantPermissionError(rt, result, err)
+
+	if got := result["lark_code"]; got != 99991672 {
+		t.Errorf("expected lark_code=99991672, got %v", got)
+	}
+	if got, _ := result["required_scope"].(string); got != "docs:permission.member:create" {
+		t.Errorf("required_scope mismatch: got %v", got)
+	}
+	consoleURL, _ := result["console_url"].(string)
+	if !strings.HasPrefix(consoleURL, "https://open.feishu.cn/page/scope-apply") {
+		t.Errorf("console_url should target open.feishu.cn, got %s", consoleURL)
+	}
+	if !strings.Contains(consoleURL, "clientID=cli_demo") {
+		t.Errorf("console_url missing clientID, got %s", consoleURL)
+	}
+	hint, _ := result["hint"].(string)
+	if !strings.Contains(hint, "console_url") {
+		t.Errorf("hint should reference console_url, got %s", hint)
+	}
+	if !strings.Contains(hint, "docs:permission.member:create") {
+		t.Errorf("hint should mention required scope, got %s", hint)
+	}
+}
+
+func TestAnnotateGrantPermissionError_LarkBrand(t *testing.T) {
+	rt := newAnnotateRuntime(core.BrandLark, "cli_demo")
+	result := map[string]interface{}{}
+	err := output.ErrAPI(99991679, "Permission denied [99991679]", map[string]interface{}{
+		"permission_violations": []interface{}{
+			map[string]interface{}{"subject": "docs:permission.member:create"},
+		},
+	})
+
+	annotateGrantPermissionError(rt, result, err)
+
+	if u, _ := result["console_url"].(string); !strings.Contains(u, "open.larksuite.com") {
+		t.Errorf("lark brand should yield larksuite host, got %s", u)
+	}
+}
+
+// Non-permission errors (network, validation, plain errors) must not be
+// annotated — keep the existing generic hint untouched.
+func TestAnnotateGrantPermissionError_NonPermissionErrorNoOp(t *testing.T) {
+	rt := newAnnotateRuntime(core.BrandFeishu, "cli_demo")
+
+	cases := []error{
+		errors.New("plain error"),
+		output.ErrNetwork("connection reset"),
+		output.ErrValidation("bad request"),
+		// Non-permission API errors (e.g. 230001) — type is "api_error" not "permission"
+		output.ErrAPI(230001, "no permission", map[string]interface{}{
+			"permission_violations": []interface{}{
+				map[string]interface{}{"subject": "docs:doc"},
+			},
+		}),
+	}
+	for i, e := range cases {
+		result := map[string]interface{}{
+			"hint": "untouched hint",
+		}
+		annotateGrantPermissionError(rt, result, e)
+		if _, ok := result["lark_code"]; ok {
+			t.Errorf("case %d: expected no lark_code, got %v", i, result["lark_code"])
+		}
+		if _, ok := result["console_url"]; ok {
+			t.Errorf("case %d: expected no console_url, got %v", i, result["console_url"])
+		}
+		if got, _ := result["hint"].(string); got != "untouched hint" {
+			t.Errorf("case %d: hint should be unchanged, got %s", i, got)
+		}
+	}
+}
+
+// permission_violations missing → only lark_code is annotated; no console_url
+// and the existing hint stays as-is (caller's generic fallback wins).
+func TestAnnotateGrantPermissionError_NoViolations(t *testing.T) {
+	rt := newAnnotateRuntime(core.BrandFeishu, "cli_demo")
+	result := map[string]interface{}{
+		"hint": "untouched fallback",
+	}
+	err := output.ErrAPI(99991672, "Permission denied [99991672]", nil)
+
+	annotateGrantPermissionError(rt, result, err)
+
+	if got := result["lark_code"]; got != 99991672 {
+		t.Errorf("expected lark_code captured, got %v", got)
+	}
+	if _, ok := result["console_url"]; ok {
+		t.Errorf("console_url must not be set when violations are absent")
+	}
+	if got, _ := result["hint"].(string); got != "untouched fallback" {
+		t.Errorf("hint should remain fallback when no console_url, got %s", got)
+	}
+}
+
+// AppID empty → no console_url even when violations exist.
+func TestAnnotateGrantPermissionError_EmptyAppID(t *testing.T) {
+	rt := newAnnotateRuntime(core.BrandFeishu, "")
+	result := map[string]interface{}{}
+	err := output.ErrAPI(99991672, "Permission denied", map[string]interface{}{
+		"permission_violations": []interface{}{
+			map[string]interface{}{"subject": "docs:doc"},
+		},
+	})
+
+	annotateGrantPermissionError(rt, result, err)
+	if _, ok := result["console_url"]; ok {
+		t.Errorf("console_url must not be set when appID is empty")
+	}
+	if got, _ := result["required_scope"].(string); got != "docs:doc" {
+		t.Errorf("required_scope should still be set when appID is empty, got %s", got)
+	}
+}
+
+// Defensive: nil/empty arguments must be safe no-ops.
+func TestAnnotateGrantPermissionError_NilArgsSafe(t *testing.T) {
+	rt := newAnnotateRuntime(core.BrandFeishu, "cli_demo")
+
+	annotateGrantPermissionError(nil, map[string]interface{}{}, nil)
+	annotateGrantPermissionError(rt, nil, nil)
+	annotateGrantPermissionError(rt, map[string]interface{}{}, nil)
+	annotateGrantPermissionError(rt, map[string]interface{}{}, errors.New(""))
+}
+
+// Integration-style: end-to-end through AutoGrantCurrentUserDrivePermission
+// with a mocked 99991672 response — verifies the annotated fields show up
+// in the JSON result that callers downstream consume.
+func TestAutoGrantStderrWarning_GrantFailed_AppScopeNotEnabled_Annotated(t *testing.T) {
+	config := &core.CliConfig{
+		AppID:      "cli_app_demo",
+		AppSecret:  "secret",
+		Brand:      core.BrandFeishu,
+		UserOpenId: "ou_test_user",
+	}
+	f, _, _, reg := cmdutil.TestFactory(t, config)
+
+	// Stub the permission member create endpoint with a 99991672 response that
+	// includes permission_violations — what the platform returns when the app
+	// has not enabled the API scope.
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/permissions/tkn_doc/members",
+		Body: map[string]interface{}{
+			"code": 99991672,
+			"msg":  "App scope not enabled",
+			"error": map[string]interface{}{
+				"permission_violations": []interface{}{
+					map[string]interface{}{"subject": "docs:permission.member:create"},
+				},
+			},
+		},
+	})
+
+	ctx := cmdutil.ContextWithShortcut(context.Background(), "test:shortcut", "exec-3")
+	runtime := &RuntimeContext{
+		ctx:        ctx,
+		Config:     config,
+		Factory:    f,
+		resolvedAs: core.AsBot,
+	}
+
+	result := AutoGrantCurrentUserDrivePermission(runtime, "tkn_doc", "docx")
+	if result == nil {
+		t.Fatal("expected non-nil result")
+	}
+	if result["status"] != PermissionGrantFailed {
+		t.Fatalf("status = %v, want failed", result["status"])
+	}
+	if result["lark_code"] != 99991672 {
+		t.Errorf("lark_code = %v, want 99991672", result["lark_code"])
+	}
+	if got, _ := result["required_scope"].(string); got != "docs:permission.member:create" {
+		t.Errorf("required_scope = %v, want docs:permission.member:create", got)
+	}
+	consoleURL, _ := result["console_url"].(string)
+	if !strings.Contains(consoleURL, "open.feishu.cn/page/scope-apply") {
+		t.Errorf("console_url missing or wrong host: %s", consoleURL)
+	}
+	if !strings.Contains(consoleURL, "scopes=docs%3Apermission.member%3Acreate") {
+		t.Errorf("console_url missing escaped scope: %s", consoleURL)
+	}
+	hint, _ := result["hint"].(string)
+	if !strings.Contains(hint, "console_url") {
+		t.Errorf("hint should be overridden to mention console_url, got %s", hint)
+	}
+}

shortcuts/contact/contact_search_user_fanout.go

@@ -176,7 +176,11 @@ func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutRespo
 		if firstErrCode != 0 {
 			return nil, output.ErrAPI(firstErrCode, msg, "")
 		}
-		return nil, output.ErrWithHint(output.ExitInternal, "fanout", msg, "")
+		// No structured API code — the failure was transport, parse, panic, or
+		// cancellation. Suggest the actionable next step rather than shipping
+		// an empty hint that would leave the calling agent with nothing to do.
+		return nil, output.ErrWithHint(output.ExitInternal, "fanout", msg,
+			"retry the command; if it persists, narrow --queries to a single term to isolate the failing input")
 	}
 	return out, nil
 }

shortcuts/contact/contact_search_user_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"strings"
@@ -18,6 +19,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
@@ -1133,6 +1135,33 @@ func TestFanoutAssemble_AllFailed_ReturnsError(t *testing.T) {
 	}
 }
 
+// When all queries fail with no structured Lark API code (transport, parse,
+// panic, ctx-canceled), the returned ExitError must carry an actionable
+// hint so the calling agent has a next step to try instead of giving up.
+func TestFanoutAssemble_AllFailed_NoCode_HasActionableHint(t *testing.T) {
+	results := []fanoutResult{
+		{Index: 0, Query: "alice", ErrMsg: "transport: connection refused"},
+		{Index: 1, Query: "bob", ErrMsg: "transport: timeout"},
+	}
+	_, err := buildFanoutResponse([]string{"alice", "bob"}, results)
+	if err == nil {
+		t.Fatalf("expected error when all queries failed")
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T", err)
+	}
+	if exitErr.Detail == nil {
+		t.Fatalf("expected Detail, got nil")
+	}
+	if exitErr.Detail.Hint == "" {
+		t.Errorf("expected non-empty Hint so agents have a next step; got empty")
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "retry") {
+		t.Errorf("hint should suggest retry as the first action; got %q", exitErr.Detail.Hint)
+	}
+}
+
 // Codes from the first failure must propagate through output.ErrAPI so the
 // CLI's exit-code classifier sees the real signal (e.g., 99991663 rate limit)
 // instead of 0, which would mean "success" in the Lark protocol.

shortcuts/drive/drive_export.go

@@ -21,7 +21,7 @@ import (
 var DriveExport = common.Shortcut{
 	Service:     "drive",
 	Command:     "+export",
-	Description: "Export a doc/docx/sheet/bitable to a local file with limited polling",
+	Description: "Export a doc/docx/sheet/bitable/slides to a local file with limited polling",
 	Risk:        "read",
 	Scopes: []string{
 		"docs:document.content:read",
@@ -32,8 +32,8 @@ var DriveExport = common.Shortcut{
 	AuthTypes: []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "token", Desc: "source document token", Required: true},
-		{Name: "doc-type", Desc: "source document type: doc | docx | sheet | bitable", Required: true, Enum: []string{"doc", "docx", "sheet", "bitable"}},
-		{Name: "file-extension", Desc: "export format: docx | pdf | xlsx | csv | markdown | base (bitable only)", Required: true, Enum: []string{"docx", "pdf", "xlsx", "csv", "markdown", "base"}},
+		{Name: "doc-type", Desc: "source document type: doc | docx | sheet | bitable | slides", Required: true, Enum: []string{"doc", "docx", "sheet", "bitable", "slides"}},
+		{Name: "file-extension", Desc: "export format: docx | pdf | xlsx | csv | markdown | base (bitable only) | pptx (slides only)", Required: true, Enum: []string{"docx", "pdf", "xlsx", "csv", "markdown", "base", "pptx"}},
 		{Name: "sub-id", Desc: "sub-table/sheet ID, required when exporting sheet/bitable as csv"},
 		{Name: "file-name", Desc: "preferred output filename (optional)"},
 		{Name: "output-dir", Default: ".", Desc: "local output directory (default: current directory)"},

shortcuts/drive/drive_export_common.go

@@ -131,15 +131,15 @@ func validateDriveExportSpec(spec driveExportSpec) error {
 	}
 
 	switch spec.DocType {
-	case "doc", "docx", "sheet", "bitable":
+	case "doc", "docx", "sheet", "bitable", "slides":
 	default:
-		return output.ErrValidation("invalid --doc-type %q: allowed values are doc, docx, sheet, bitable", spec.DocType)
+		return output.ErrValidation("invalid --doc-type %q: allowed values are doc, docx, sheet, bitable, slides", spec.DocType)
 	}
 
 	switch spec.FileExtension {
-	case "docx", "pdf", "xlsx", "csv", "markdown", "base":
+	case "docx", "pdf", "xlsx", "csv", "markdown", "base", "pptx":
 	default:
-		return output.ErrValidation("invalid --file-extension %q: allowed values are docx, pdf, xlsx, csv, markdown, base", spec.FileExtension)
+		return output.ErrValidation("invalid --file-extension %q: allowed values are docx, pdf, xlsx, csv, markdown, base, pptx", spec.FileExtension)
 	}
 
 	if spec.FileExtension == "markdown" && spec.DocType != "docx" {
@@ -150,6 +150,14 @@ func validateDriveExportSpec(spec driveExportSpec) error {
 		return output.ErrValidation("--file-extension base only supports --doc-type bitable")
 	}
 
+	if spec.FileExtension == "pptx" && spec.DocType != "slides" {
+		return output.ErrValidation("--file-extension pptx only supports --doc-type slides")
+	}
+
+	if spec.DocType == "slides" && spec.FileExtension != "pptx" && spec.FileExtension != "pdf" {
+		return output.ErrValidation("--doc-type slides only supports --file-extension pptx or pdf")
+	}
+
 	if strings.TrimSpace(spec.SubID) != "" {
 		if spec.FileExtension != "csv" || (spec.DocType != "sheet" && spec.DocType != "bitable") {
 			return output.ErrValidation("--sub-id is only used when exporting sheet/bitable as csv")
@@ -345,6 +353,8 @@ func exportFileSuffix(fileExtension string) string {
 		return ".csv"
 	case "base":
 		return ".base"
+	case "pptx":
+		return ".pptx"
 	default:
 		return ""
 	}

shortcuts/drive/drive_export_common_test.go

@@ -70,4 +70,10 @@ func TestSanitizeExportFileNameAndEnsureExtension(t *testing.T) {
 	if got := exportFileSuffix("base"); got != ".base" {
 		t.Fatalf("exportFileSuffix(base) = %q, want %q", got, ".base")
 	}
+	if got := ensureExportFileExtension("report", "pptx"); got != "report.pptx" {
+		t.Fatalf("ensureExportFileExtension() = %q, want %q", got, "report.pptx")
+	}
+	if got := ensureExportFileExtension("report.pptx", "pptx"); got != "report.pptx" {
+		t.Fatalf("ensureExportFileExtension() should preserve suffix, got %q", got)
+	}
 }

shortcuts/drive/drive_export_test.go

@@ -50,11 +50,34 @@ func TestValidateDriveExportSpec(t *testing.T) {
 			name: "base bitable ok",
 			spec: driveExportSpec{Token: "base123", DocType: "bitable", FileExtension: "base"},
 		},
+		{
+			name: "slides pptx ok",
+			spec: driveExportSpec{Token: "slides123", DocType: "slides", FileExtension: "pptx"},
+		},
+		{
+			name: "slides pdf ok",
+			spec: driveExportSpec{Token: "slides123", DocType: "slides", FileExtension: "pdf"},
+		},
 		{
 			name:    "base non bitable rejected",
 			spec:    driveExportSpec{Token: "sheet123", DocType: "sheet", FileExtension: "base"},
 			wantErr: "only supports --doc-type bitable",
 		},
+		{
+			name:    "pptx non slides rejected",
+			spec:    driveExportSpec{Token: "docx123", DocType: "docx", FileExtension: "pptx"},
+			wantErr: "only supports --doc-type slides",
+		},
+		{
+			name:    "slides csv rejected",
+			spec:    driveExportSpec{Token: "slides123", DocType: "slides", FileExtension: "csv"},
+			wantErr: "slides only supports",
+		},
+		{
+			name:    "unknown doc type rejected",
+			spec:    driveExportSpec{Token: "docx123", DocType: "unknown", FileExtension: "pdf"},
+			wantErr: "invalid --doc-type",
+		},
 		{
 			name:    "unknown file extension rejected",
 			spec:    driveExportSpec{Token: "docx123", DocType: "docx", FileExtension: "rtf"},

shortcuts/im/helpers.go

@@ -911,12 +911,16 @@ func marshalMarkdownPostContent(content [][]map[string]interface{}) string {
 			"content": content,
 		},
 	}
-	return marshalJSONNoEscape(payload)
+	data, _ := json.Marshal(payload)
+	return string(data)
 }
 
 func buildSingleMDPost(markdown string) string {
 	return marshalMarkdownPostContent([][]map[string]interface{}{
-		buildPostElementNodes(optimizeMarkdownStyle(markdown)),
+		{{
+			"tag":  "md",
+			"text": optimizeMarkdownStyle(markdown),
+		}},
 	})
 }
 
@@ -940,7 +944,10 @@ func buildSegmentedPost(markdown string) string {
 		if optimized == "" {
 			continue
 		}
-		content = append(content, buildPostElementNodes(optimized))
+		content = append(content, []map[string]interface{}{{
+			"tag":  "md",
+			"text": optimized,
+		}})
 	}
 	if len(content) == 0 {
 		return buildSingleMDPost(markdown)
@@ -955,186 +962,8 @@ func buildMarkdownPostContent(markdown string) string {
 	return buildSingleMDPost(markdown)
 }
 
-// buildPostElementNodes splits optimized markdown text into Feishu post inline
-// elements. It tokenizes markdown links/images and bare http(s) URLs:
-//   - markdown links are kept verbatim inside a {"tag":"md"} segment
-//   - bare URLs become {"tag":"a"} elements rendered natively by Feishu,
-//     avoiding the md renderer misinterpreting underscores as italic markers
-//
-// Fenced code blocks are protected before tokenization so their content remains
-// a single md segment, and bare URLs support balanced parentheses in the path.
-func buildPostElementNodes(text string) []map[string]interface{} {
-	protected, codeBlocks := protectMarkdownCodeBlocks(text)
-	if protected == "" {
-		return []map[string]interface{}{{
-			"tag":  "md",
-			"text": text,
-		}}
-	}
-	elems := make([]map[string]interface{}, 0, 4)
-	prev := 0
-	for i := 0; i < len(protected); {
-		end, kind, ok := scanPostToken(protected, i)
-		if !ok {
-			i++
-			continue
-		}
-		if i > prev {
-			elems = appendMDPostNode(elems, restoreMarkdownCodeBlocks(protected[prev:i], codeBlocks))
-		}
-
-		token := protected[i:end]
-		if kind == postTokenMarkdown {
-			elems = appendMDPostNode(elems, restoreMarkdownCodeBlocks(token, codeBlocks))
-		} else {
-			url := trimBareURLToken(token)
-			if url == "" {
-				url = token
-			}
-			elems = append(elems, map[string]interface{}{
-				"tag":  "a",
-				"text": url,
-				"href": url,
-			})
-			elems = appendMDPostNode(elems, restoreMarkdownCodeBlocks(token[len(url):], codeBlocks))
-		}
-		prev = end
-		i = end
-	}
-	if prev < len(protected) {
-		elems = appendMDPostNode(elems, restoreMarkdownCodeBlocks(protected[prev:], codeBlocks))
-	}
-	if len(elems) == 0 {
-		return []map[string]interface{}{{
-			"tag":  "md",
-			"text": text,
-		}}
-	}
-	return elems
-}
-
-func trimBareURLToken(token string) string {
-	trimmed := strings.TrimRight(token, ".,;:!?")
-	for strings.HasSuffix(trimmed, ")") && strings.Count(trimmed, "(") < strings.Count(trimmed, ")") {
-		trimmed = strings.TrimSuffix(trimmed, ")")
-	}
-	return trimmed
-}
-
-type postTokenKind int
-
-const (
-	postTokenMarkdown postTokenKind = iota
-	postTokenURL
-)
-
-func appendMDPostNode(elems []map[string]interface{}, text string) []map[string]interface{} {
-	if text == "" {
-		return elems
-	}
-	return append(elems, map[string]interface{}{
-		"tag":  "md",
-		"text": text,
-	})
-}
-
-func scanPostToken(text string, start int) (end int, kind postTokenKind, ok bool) {
-	if end, ok = scanMarkdownLinkToken(text, start); ok {
-		return end, postTokenMarkdown, true
-	}
-	if end, ok = scanBareURLToken(text, start); ok {
-		return end, postTokenURL, true
-	}
-	return 0, 0, false
-}
-
-func scanMarkdownLinkToken(text string, start int) (int, bool) {
-	openBracket := start
-	if text[start] == '!' {
-		if start+1 >= len(text) || text[start+1] != '[' {
-			return 0, false
-		}
-		openBracket = start + 1
-	} else if text[start] != '[' {
-		return 0, false
-	}
-
-	closeBracket := strings.IndexByte(text[openBracket+1:], ']')
-	if closeBracket < 0 {
-		return 0, false
-	}
-	closeBracket += openBracket + 1
-	if closeBracket+1 >= len(text) || text[closeBracket+1] != '(' {
-		return 0, false
-	}
-	return scanBalancedParenToken(text, closeBracket+1)
-}
-
-func scanBareURLToken(text string, start int) (int, bool) {
-	if !strings.HasPrefix(text[start:], "http://") && !strings.HasPrefix(text[start:], "https://") {
-		return 0, false
-	}
-
-	depth := 0
-	for i := start; i < len(text); i++ {
-		switch text[i] {
-		case ' ', '\t', '\n', '\r', '<', '>', '"', '[', ']':
-			return i, i > start
-		case '(':
-			depth++
-		case ')':
-			if depth == 0 {
-				return i, i > start
-			}
-			depth--
-		}
-	}
-	return len(text), true
-}
-
-func scanBalancedParenToken(text string, openParen int) (int, bool) {
-	if openParen >= len(text) || text[openParen] != '(' {
-		return 0, false
-	}
-
-	depth := 0
-	for i := openParen; i < len(text); i++ {
-		switch text[i] {
-		case '(':
-			depth++
-		case ')':
-			depth--
-			if depth == 0 {
-				return i + 1, true
-			}
-		}
-	}
-	return 0, false
-}
-
-func buildPostElements(text string) string {
-	return marshalJSONNoEscape(buildPostElementNodes(text))
-}
-
-func marshalJSONNoEscape(v interface{}) string {
-	var buf bytes.Buffer
-	enc := json.NewEncoder(&buf)
-	enc.SetEscapeHTML(false)
-	_ = enc.Encode(v)
-	return strings.TrimSuffix(buf.String(), "\n")
-}
-
-// marshalStringNoEscape serializes a string to JSON without HTML-escaping
-// special characters like &, <, >. Go's json.Marshal escapes them to \u0026
-// etc. by default, which breaks URLs containing & in Feishu's md renderer.
-func marshalStringNoEscape(s string) string {
-	return marshalJSONNoEscape(s)
-}
-
 // wrapMarkdownAsPost wraps markdown text into Feishu post format JSON (no network).
 // Used by DryRun. Output may include md/text paragraphs when blank-line separators are present.
-// Bare URLs are emitted as {"tag":"a"} elements to avoid Feishu's md renderer
-// misinterpreting underscores in URLs as italic markers.
 func wrapMarkdownAsPost(markdown string) string {
 	return buildMarkdownPostContent(markdown)
 }

shortcuts/im/helpers_test.go

@@ -373,171 +373,19 @@ func TestOptimizeMarkdownStyle(t *testing.T) {
 	}
 }
 
-func TestMarshalStringNoEscape(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		want  string
-	}{
-		{name: "ampersand not escaped", input: "a=1&b=2", want: `"a=1&b=2"`},
-		{name: "angle brackets not escaped", input: "<tag>", want: `"<tag>"`},
-		{name: "regular string", input: "hello world", want: `"hello world"`},
-		{name: "url with ampersand", input: "https://example.com?a=1&b=2", want: `"https://example.com?a=1&b=2"`},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := marshalStringNoEscape(tt.input)
-			if got != tt.want {
-				t.Errorf("marshalStringNoEscape(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestBuildPostElements(t *testing.T) {
-	tests := []struct {
-		name      string
-		input     string
-		wantSubs  []string // substrings that must appear
-		wantNsubs []string // substrings that must NOT appear
-	}{
-		{
-			name:     "plain text no URL",
-			input:    "hello **world**",
-			wantSubs: []string{`"tag":"md"`, `hello **world**`},
-		},
-		{
-			name:     "bare URL only",
-			input:    "https://example.com/path",
-			wantSubs: []string{`"tag":"a"`, `"text":"https://example.com/path"`, `"href":"https://example.com/path"`},
-		},
-		{
-			name:     "bare URL with underscores",
-			input:    "https://example.com/flow_id=abc_def",
-			wantSubs: []string{`"tag":"a"`, `flow_id=abc_def`},
-		},
-		{
-			name:     "bare URL with ampersand not escaped",
-			input:    "https://example.com?a=1&b=2",
-			wantSubs: []string{`"tag":"a"`, `a=1&b=2`},
-		},
-		{
-			name:     "text before and after URL",
-			input:    "click here: https://example.com/path ok?",
-			wantSubs: []string{`"tag":"md"`, `click here: `, `"tag":"a"`, `https://example.com/path`, ` ok?`},
-		},
-		{
-			name:     "markdown link kept in md segment",
-			input:    "[click here](https://example.com/path_with_underscore)",
-			wantSubs: []string{`"tag":"md"`, `[click here](https://example.com/path_with_underscore)`},
-		},
-		{
-			name:      "markdown link not promoted to a tag",
-			input:     "[text](https://example.com)",
-			wantSubs:  []string{`"tag":"md"`},
-			wantNsubs: []string{`"tag":"a"`},
-		},
-		{
-			name:  "multiple bare URLs",
-			input: "https://a.com/x_y and https://b.com/p_q",
-			wantSubs: []string{
-				`"tag":"a"`, `https://a.com/x_y`,
-				`https://b.com/p_q`,
-				`"tag":"md"`, ` and `,
-			},
-		},
-		{
-			name:     "mixed markdown and bare URL",
-			input:    "**bold** https://example.com/foo_bar [link](https://example.com) end",
-			wantSubs: []string{`"tag":"md"`, `**bold**`, `"tag":"a"`, `foo_bar`, `[link](https://example.com)`},
-		},
-		{
-			name:     "empty string",
-			input:    "",
-			wantSubs: []string{`"tag":"md"`, `"text":""`},
-		},
-		{
-			name:      "URL followed by comma",
-			input:     "visit https://example.com/path, then click",
-			wantSubs:  []string{`"tag":"a"`, `"href":"https://example.com/path"`},
-			wantNsubs: []string{`https://example.com/path,`},
-		},
-		{
-			name:      "URL followed by period",
-			input:     "see https://example.com/foo.",
-			wantSubs:  []string{`"tag":"a"`, `https://example.com/foo`},
-			wantNsubs: []string{`https://example.com/foo."`},
-		},
-		{
-			name:     "URL with no trailing punctuation unchanged",
-			input:    "https://example.com/foo_bar",
-			wantSubs: []string{`"href":"https://example.com/foo_bar"`},
-		},
-		{
-			name:      "URL with balanced parentheses preserved",
-			input:     "https://en.wikipedia.org/wiki/Foo_(bar)",
-			wantSubs:  []string{`"href":"https://en.wikipedia.org/wiki/Foo_(bar)"`},
-			wantNsubs: []string{`"href":"https://en.wikipedia.org/wiki/Foo_"`},
-		},
-		{
-			name:      "code block URL stays markdown",
-			input:     "```bash\ncurl https://example.com/foo_bar\n```",
-			wantSubs:  []string{`"tag":"md"`, "```bash\\ncurl https://example.com/foo_bar\\n```"},
-			wantNsubs: []string{`"tag":"a"`},
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := buildPostElements(tt.input)
-			for _, sub := range tt.wantSubs {
-				if !strings.Contains(got, sub) {
-					t.Errorf("buildPostElements(%q)\n got: %s\n missing: %q", tt.input, got, sub)
-				}
-			}
-			for _, sub := range tt.wantNsubs {
-				if strings.Contains(got, sub) {
-					t.Errorf("buildPostElements(%q)\n got: %s\n should not contain: %q", tt.input, got, sub)
-				}
-			}
-		})
-	}
-}
-
 func TestWrapMarkdownAsPost(t *testing.T) {
-	t.Run("plain markdown", func(t *testing.T) {
-		got := wrapMarkdownAsPost("hello **world**")
-		content := decodePostContentForTest(t, got)
-		if len(content) != 1 {
-			t.Fatalf("wrapMarkdownAsPost() content len = %d, want 1", len(content))
-		}
-		node := decodePostParagraphForTest(t, got, 0)
-		if node["tag"] != "md" {
-			t.Fatalf("wrapMarkdownAsPost() tag = %#v, want md", node["tag"])
-		}
-		if node["text"] != "hello **world**" {
-			t.Fatalf("wrapMarkdownAsPost() text = %#v, want %q", node["text"], "hello **world**")
-		}
-	})
-
-	t.Run("bare URL becomes a tag", func(t *testing.T) {
-		got := wrapMarkdownAsPost("see https://example.com/flow_id=abc_def done")
-		if !strings.Contains(got, `"tag":"a"`) {
-			t.Fatalf("wrapMarkdownAsPost() bare URL should produce a tag: %s", got)
-		}
-		if !strings.Contains(got, `flow_id=abc_def`) {
-			t.Fatalf("wrapMarkdownAsPost() URL content missing: %s", got)
-		}
-	})
-
-	t.Run("code block URL stays md", func(t *testing.T) {
-		got := wrapMarkdownAsPost("```bash\ncurl https://example.com/foo_bar\n```")
-		if strings.Contains(got, `"tag":"a"`) {
-			t.Fatalf("wrapMarkdownAsPost() code block URL should stay markdown: %s", got)
-		}
-		if !strings.Contains(got, "```bash\\ncurl https://example.com/foo_bar\\n```") {
-			t.Fatalf("wrapMarkdownAsPost() code block content missing: %s", got)
-		}
-	})
+	got := wrapMarkdownAsPost("hello **world**")
+	content := decodePostContentForTest(t, got)
+	if len(content) != 1 {
+		t.Fatalf("wrapMarkdownAsPost() content len = %d, want 1", len(content))
+	}
+	node := decodePostParagraphForTest(t, got, 0)
+	if node["tag"] != "md" {
+		t.Fatalf("wrapMarkdownAsPost() tag = %#v, want md", node["tag"])
+	}
+	if node["text"] != "hello **world**" {
+		t.Fatalf("wrapMarkdownAsPost() text = %#v, want %q", node["text"], "hello **world**")
+	}
 }
 
 func TestShouldUseSegmentedPost(t *testing.T) {

shortcuts/mail/helpers.go

@@ -2331,15 +2331,15 @@ func validateSendTime(runtime *common.RuntimeContext) error {
 		return nil
 	}
 	if !runtime.Bool("confirm-send") {
-		return fmt.Errorf("--send-time requires --confirm-send to be set")
+		return output.ErrValidation("--send-time requires --confirm-send to be set")
 	}
 	ts, err := strconv.ParseInt(sendTime, 10, 64)
 	if err != nil {
-		return fmt.Errorf("--send-time must be a valid Unix timestamp in seconds, got %q", sendTime)
+		return output.ErrValidation("--send-time must be a valid Unix timestamp in seconds, got %q", sendTime)
 	}
 	minTime := time.Now().Unix() + 5*60
 	if ts < minTime {
-		return fmt.Errorf("--send-time must be at least 5 minutes in the future (minimum: %d, got: %d)", minTime, ts)
+		return output.ErrValidation("--send-time must be at least 5 minutes in the future (minimum: %d, got: %d)", minTime, ts)
 	}
 	return nil
 }
@@ -2444,10 +2444,10 @@ func validateRecipientCount(to, cc, bcc string) error {
 func validateComposeInlineAndAttachments(fio fileio.FileIO, attachFlag, inlineFlag string, plainText bool, body string) error {
 	if strings.TrimSpace(inlineFlag) != "" {
 		if plainText {
-			return fmt.Errorf("--inline is not supported with --plain-text (inline images require HTML body)")
+			return output.ErrValidation("--inline is not supported with --plain-text (inline images require HTML body)")
 		}
 		if body != "" && !bodyIsHTML(body) {
-			return fmt.Errorf("--inline requires an HTML body (the provided body appears to be plain text; add HTML tags or remove --inline)")
+			return output.ErrValidation("--inline requires an HTML body (the provided body appears to be plain text; add HTML tags or remove --inline)")
 		}
 	}
 	inlineSpecs, err := parseInlineSpecs(inlineFlag)
@@ -2529,7 +2529,7 @@ func validateEventFlags(runtime *common.RuntimeContext) error {
 	hasAll := summary != "" && start != "" && end != ""
 
 	if hasAny && !hasAll {
-		return fmt.Errorf("--event-summary, --event-start, and --event-end must all be provided together")
+		return output.ErrValidation("--event-summary, --event-start, and --event-end must all be provided together")
 	}
 	if summary == "" {
 		return nil

shortcuts/mail/signature_compose.go

@@ -13,6 +13,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	draftpkg "github.com/larksuite/cli/shortcuts/mail/draft"
 	"github.com/larksuite/cli/shortcuts/mail/emlbuilder"
@@ -241,7 +242,7 @@ func signatureCIDs(sig *signatureResult) []string {
 // validateSignatureWithPlainText returns an error if both --plain-text and --signature-id are set.
 func validateSignatureWithPlainText(plainText bool, signatureID string) error {
 	if plainText && signatureID != "" {
-		return fmt.Errorf("--plain-text and --signature-id are mutually exclusive: signatures require HTML mode")
+		return output.ErrValidation("--plain-text and --signature-id are mutually exclusive: signatures require HTML mode")
 	}
 	return nil
 }

shortcuts/register.go

@@ -5,12 +5,16 @@ package shortcuts
 
 import (
 	"context"
+	"fmt"
+	"slices"
 
 	"github.com/larksuite/cli/shortcuts/okr"
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts/apps"
 	"github.com/larksuite/cli/shortcuts/base"
@@ -32,6 +36,23 @@ import (
 	"github.com/larksuite/cli/shortcuts/wiki"
 )
 
+// Empty brand (no config loaded) is treated as no-restriction so bootstrap
+// paths and tests without config still see the full service list.
+var brandRestrictedServices = map[string][]core.LarkBrand{
+	"apps": {core.BrandFeishu},
+}
+
+func IsShortcutServiceAvailable(service string, brand core.LarkBrand) bool {
+	allowed, ok := brandRestrictedServices[service]
+	if !ok {
+		return true
+	}
+	if brand == "" {
+		return true
+	}
+	return slices.Contains(allowed, brand)
+}
+
 // allShortcuts aggregates shortcuts from all domain packages.
 var allShortcuts []common.Shortcut
 
@@ -69,6 +90,14 @@ func RegisterShortcuts(program *cobra.Command, f *cmdutil.Factory) {
 }
 
 func RegisterShortcutsWithContext(ctx context.Context, program *cobra.Command, f *cmdutil.Factory) {
+	// Factory.Config may be nil in tests that pass a zero-value factory.
+	var brand core.LarkBrand
+	if f != nil && f.Config != nil {
+		if cfg, err := f.Config(); err == nil && cfg != nil {
+			brand = cfg.Brand
+		}
+	}
+
 	// Group by service
 	byService := make(map[string][]common.Shortcut)
 	for _, s := range allShortcuts {
@@ -117,5 +146,46 @@ func RegisterShortcutsWithContext(ctx context.Context, program *cobra.Command, f
 		if service == "mail" {
 			mail.InstallOnMail(svc)
 		}
+
+		if !IsShortcutServiceAvailable(service, brand) {
+			installBrandRestrictionGuard(svc, service, brand)
+		}
 	}
 }
+
+// Mirrors internal/cmdpolicy/apply.go::installDenyStub: DisableFlagParsing +
+// ArbitraryArgs keep cobra from short-circuiting with "missing required flag"
+// before our RunE runs; leaf-level PersistentPreRunE defeats cobra's "first
+// PreRunE wins" walk-up that would otherwise shadow the stub.
+func installBrandRestrictionGuard(svc *cobra.Command, service string, brand core.LarkBrand) {
+	stub := func(c *cobra.Command, _ []string) error {
+		c.SilenceUsage = true
+		return output.ErrValidation(
+			"the %q feature is not yet supported on the %s brand",
+			service, brand,
+		)
+	}
+	noopPreRun := func(c *cobra.Command, _ []string) error {
+		c.SilenceUsage = true
+		return nil
+	}
+	var walk func(c *cobra.Command)
+	walk = func(c *cobra.Command) {
+		c.Hidden = true
+		c.DisableFlagParsing = true
+		c.Args = cobra.ArbitraryArgs
+		c.PreRunE = nil
+		c.PreRun = nil
+		c.PersistentPreRunE = noopPreRun
+		c.PersistentPreRun = nil
+		c.RunE = stub
+		c.Run = nil
+		for _, child := range c.Commands() {
+			walk(child)
+		}
+	}
+	walk(svc)
+
+	// --help bypasses RunE, so surface the restriction in Long too.
+	svc.Long = fmt.Sprintf("The %q feature is not yet supported on the %s brand.", service, brand)
+}

shortcuts/register_brand_guard_test.go

@@ -0,0 +1,122 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package shortcuts
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+func newFactoryWithBrand(brand core.LarkBrand) *cmdutil.Factory {
+	return &cmdutil.Factory{
+		Config: func() (*core.CliConfig, error) {
+			return &core.CliConfig{Brand: brand}, nil
+		},
+	}
+}
+
+func findChild(root *cobra.Command, name string) *cobra.Command {
+	for _, c := range root.Commands() {
+		if c.Name() == name {
+			return c
+		}
+	}
+	return nil
+}
+
+func TestBrandGuard_AppsStaysRegisteredOnLark(t *testing.T) {
+	program := &cobra.Command{Use: "root"}
+	RegisterShortcuts(program, newFactoryWithBrand(core.BrandLark))
+
+	apps := findChild(program, "apps")
+	if apps == nil {
+		t.Fatal("apps service command should be registered on Lark brand (so users see a clear brand error, not 'unknown command')")
+	}
+	if !apps.Hidden {
+		t.Error("apps service command should be Hidden on Lark brand")
+	}
+	if len(apps.Commands()) == 0 {
+		t.Error("apps subcommands should still be mounted (so children also hit the brand-restriction stub)")
+	}
+	for _, child := range apps.Commands() {
+		if !child.Hidden {
+			t.Errorf("apps child %q should be Hidden on Lark brand", child.Name())
+		}
+	}
+}
+
+func TestBrandGuard_AppsExecuteReturnsBrandError(t *testing.T) {
+	program := &cobra.Command{Use: "root"}
+	RegisterShortcuts(program, newFactoryWithBrand(core.BrandLark))
+
+	apps := findChild(program, "apps")
+	if apps == nil {
+		t.Fatal("apps should be registered")
+	}
+	create := findChild(apps, "+create")
+	if create == nil {
+		t.Fatal("apps +create should be registered")
+	}
+
+	err := create.RunE(create, []string{"--name", "x"})
+	if err == nil {
+		t.Fatal("expected brand-restriction error, got nil")
+	}
+	exitErr, ok := err.(*output.ExitError)
+	if !ok {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Code != output.ExitValidation {
+		t.Errorf("expected ExitValidation (%d), got %d", output.ExitValidation, exitErr.Code)
+	}
+	if !strings.Contains(exitErr.Error(), "apps") || !strings.Contains(exitErr.Error(), "lark") {
+		t.Errorf("expected error to mention apps + lark, got: %s", exitErr.Error())
+	}
+}
+
+func TestBrandGuard_AppsExecutableOnFeishu(t *testing.T) {
+	program := &cobra.Command{Use: "root"}
+	RegisterShortcuts(program, newFactoryWithBrand(core.BrandFeishu))
+
+	apps := findChild(program, "apps")
+	if apps == nil {
+		t.Fatal("apps should be registered on Feishu brand")
+	}
+	if apps.Hidden {
+		t.Error("apps should NOT be Hidden on Feishu brand")
+	}
+	create := findChild(apps, "+create")
+	if create == nil {
+		t.Fatal("apps +create should be registered on Feishu brand")
+	}
+	if create.DisableFlagParsing {
+		t.Error("apps +create should not have DisableFlagParsing on Feishu (the guard must not have run)")
+	}
+}
+
+func TestBrandGuard_DispatchHitsStubViaCobra(t *testing.T) {
+	program := &cobra.Command{Use: "root"}
+	RegisterShortcuts(program, newFactoryWithBrand(core.BrandLark))
+
+	program.SetArgs([]string{"apps", "+create", "--name", "x", "--app-type", "HTML"})
+	program.SetContext(context.Background())
+	err := program.Execute()
+	if err == nil {
+		t.Fatal("expected error from dispatching apps +create on Lark brand")
+	}
+	exitErr, ok := err.(*output.ExitError)
+	if !ok {
+		t.Fatalf("expected *output.ExitError from cobra dispatch, got %T: %v", err, err)
+	}
+	if !strings.Contains(exitErr.Error(), "lark") {
+		t.Errorf("dispatched error should mention lark brand, got: %s", exitErr.Error())
+	}
+}

shortcuts/sheets/lark_sheets_filter_views.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -463,7 +464,7 @@ func validateExpectedFlag(s string) error {
 	}
 	var arr []interface{}
 	if err := json.Unmarshal([]byte(s), &arr); err != nil {
-		return fmt.Errorf("--expected must be a JSON array (e.g. [\"6\"]), got: %s", s)
+		return output.ErrValidation("--expected must be a JSON array (e.g. [\"6\"]), got: %s", s)
 	}
 	return nil
 }

shortcuts/task/task_upload_attachment.go

@@ -38,7 +38,7 @@ const defaultTaskAttachmentResourceType = "task"
 var UploadAttachmentTask = common.Shortcut{
 	Service:     "task",
 	Command:     "+upload-attachment",
-	Description: "upload a local file as an attachment to a task; use --resource-type=task_delivery when uploading to task agents",
+	Description: "upload a local file as an attachment to a task",
 	Risk:        "write",
 	Scopes:      []string{"task:attachment:write"},
 	AuthTypes:   []string{"user", "bot"},

shortcuts/wiki/wiki_node_create.go

@@ -5,8 +5,11 @@ package wiki
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io"
 	"strings"
+	"time"
 
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
@@ -24,6 +27,16 @@ const (
 	wikiResolvedByMyLibrary       = "my_library"
 )
 
+const (
+	// wikiNodeCreateMaxRetries is the maximum number of retry attempts after
+	// the initial request when the API returns lock contention (code 131009).
+	wikiNodeCreateMaxRetries = 2
+
+	// wikiNodeCreateRetryBaseDelay is the initial backoff delay for lock
+	// contention retries. Subsequent retries double the delay (250ms, 500ms).
+	wikiNodeCreateRetryBaseDelay = 250 * time.Millisecond
+)
+
 var wikiObjectTypes = []string{
 	"sheet",
 	"mindnote",
@@ -68,7 +81,7 @@ var WikiNodeCreate = common.Shortcut{
 		spec := readWikiNodeCreateSpec(runtime)
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Creating wiki node...\n")
-		execution, err := runWikiNodeCreate(ctx, wikiNodeCreateAPI{runtime: runtime}, runtime.As(), spec)
+		execution, err := runWikiNodeCreate(ctx, wikiNodeCreateAPI{runtime: runtime}, runtime.As(), spec, runtime.IO().ErrOut)
 		if err != nil {
 			return err
 		}
@@ -288,15 +301,37 @@ func needsMyLibraryLookup(spec wikiNodeCreateSpec) bool {
 	return spec.SpaceID == "" || spec.SpaceID == wikiMyLibrarySpaceID
 }
 
-func runWikiNodeCreate(ctx context.Context, client wikiNodeCreateClient, identity core.Identity, spec wikiNodeCreateSpec) (*wikiNodeCreateExecution, error) {
+func runWikiNodeCreate(ctx context.Context, client wikiNodeCreateClient, identity core.Identity, spec wikiNodeCreateSpec, errOut io.Writer) (*wikiNodeCreateExecution, error) {
 	resolvedSpace, err := resolveWikiNodeCreateSpace(ctx, client, identity, spec)
 	if err != nil {
 		return nil, err
 	}
 
-	node, err := client.CreateNode(ctx, resolvedSpace.SpaceID, spec)
-	if err != nil {
-		return nil, err
+	var (
+		node    *wikiNodeRecord
+		lastErr error
+	)
+	for attempt := 0; attempt <= wikiNodeCreateMaxRetries; attempt++ {
+		if attempt > 0 {
+			delay := wikiNodeCreateRetryBaseDelay << uint(attempt-1)
+			fmt.Fprintf(errOut, "Wiki node create encountered lock contention, retrying (attempt %d/%d) in %v...\n", attempt, wikiNodeCreateMaxRetries, delay)
+			select {
+			case <-ctx.Done():
+				return nil, ctx.Err()
+			case <-time.After(delay):
+			}
+		}
+
+		node, lastErr = client.CreateNode(ctx, resolvedSpace.SpaceID, spec)
+		if lastErr == nil {
+			break
+		}
+		if !isWikiNodeLockContention(lastErr) {
+			return nil, lastErr
+		}
+	}
+	if lastErr != nil {
+		return nil, wrapWikiNodeCreateRetryError(lastErr)
 	}
 	if node == nil {
 		return nil, output.Errorf(output.ExitAPI, "api_error", "wiki node create returned no node")
@@ -308,6 +343,50 @@ func runWikiNodeCreate(ctx context.Context, client wikiNodeCreateClient, identit
 	}, nil
 }
 
+// isWikiNodeLockContention returns true if the error is a Lark API error with
+// code 131009 (wiki node lock contention), which is retryable with backoff.
+func isWikiNodeLockContention(err error) bool {
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		return false
+	}
+	return exitErr.Detail.Code == output.LarkErrWikiLockContention
+}
+
+// wrapWikiNodeCreateRetryError appends a retry-exhaustion hint to the original
+// API error. It builds the ExitError by hand (instead of using ErrWithHint) so
+// the original Lark error code survives in the envelope.
+func wrapWikiNodeCreateRetryError(err error) error {
+	if err == nil {
+		return nil
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		return err
+	}
+	hint := fmt.Sprintf(
+		"wiki node create failed after %d retries due to lock contention; try again later or reduce concurrent node creations under the same parent",
+		wikiNodeCreateMaxRetries,
+	)
+	if existing := strings.TrimSpace(exitErr.Detail.Hint); existing != "" {
+		hint = existing + "\n" + hint
+	}
+	return &output.ExitError{
+		Code: exitErr.Code,
+		Detail: &output.ErrDetail{
+			Type:       exitErr.Detail.Type,
+			Code:       exitErr.Detail.Code,
+			Message:    exitErr.Detail.Message,
+			Hint:       hint,
+			ConsoleURL: exitErr.Detail.ConsoleURL,
+			Risk:       exitErr.Detail.Risk,
+			Detail:     exitErr.Detail.Detail,
+		},
+		Err: exitErr.Err,
+		Raw: exitErr.Raw,
+	}
+}
+
 // resolveWikiNodeCreateSpace applies the shortcut's precedence rules:
 // explicit space ID wins, then parent-node inference, then my_library fallback.
 func resolveWikiNodeCreateSpace(ctx context.Context, client wikiNodeCreateClient, identity core.Identity, spec wikiNodeCreateSpec) (wikiResolvedSpace, error) {

shortcuts/wiki/wiki_node_create_test.go

@@ -7,7 +7,9 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"io"
 	"strings"
 	"sync/atomic"
 	"testing"
@@ -17,6 +19,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -31,6 +34,7 @@ type fakeWikiNodeCreateClient struct {
 	createNode    *wikiNodeRecord
 	returnNilNode bool
 	createErr     error
+	createErrs    []error // consumed in order; takes precedence over createErr
 	getSpaceErr   error
 	getNodeErr    error
 	createInvoked []fakeWikiNodeCreateCall
@@ -63,6 +67,11 @@ func (fake *fakeWikiNodeCreateClient) CreateNode(ctx context.Context, spaceID st
 		SpaceID: spaceID,
 		Spec:    spec,
 	})
+	if len(fake.createErrs) > 0 {
+		err := fake.createErrs[0]
+		fake.createErrs = fake.createErrs[1:]
+		return nil, err
+	}
 	if fake.createErr != nil {
 		return nil, fake.createErr
 	}
@@ -248,7 +257,7 @@ func TestRunWikiNodeCreateCreatesNodeInResolvedSpace(t *testing.T) {
 		ObjType:  "docx",
 		Title:    "Roadmap",
 	}
-	execution, err := runWikiNodeCreate(context.Background(), client, core.AsUser, spec)
+	execution, err := runWikiNodeCreate(context.Background(), client, core.AsUser, spec, io.Discard)
 	if err != nil {
 		t.Fatalf("runWikiNodeCreate() error = %v", err)
 	}
@@ -280,7 +289,7 @@ func TestRunWikiNodeCreateRejectsNilCreatedNode(t *testing.T) {
 		NodeType: wikiNodeTypeOrigin,
 		ObjType:  "docx",
 		Title:    "Roadmap",
-	})
+	}, io.Discard)
 	if err == nil || !strings.Contains(err.Error(), "wiki node create returned no node") {
 		t.Fatalf("expected missing node error, got %v", err)
 	}
@@ -772,3 +781,237 @@ func TestWikiNodeURL(t *testing.T) {
 		})
 	}
 }
+
+func TestRunWikiNodeCreateRetriesOnLockContention(t *testing.T) {
+	t.Parallel()
+
+	lockErr := output.ErrAPI(output.LarkErrWikiLockContention, "lock contention", nil)
+
+	client := &fakeWikiNodeCreateClient{
+		spaces: map[string]*wikiSpaceRecord{
+			wikiMyLibrarySpaceID: {SpaceID: "space_my_library"},
+		},
+		createNode: &wikiNodeRecord{
+			SpaceID:   "space_my_library",
+			NodeToken: "wik_created",
+			NodeType:  wikiNodeTypeOrigin,
+			ObjType:   "docx",
+			Title:     "Roadmap",
+		},
+		createErrs: []error{lockErr, lockErr}, // fail twice, then succeed
+	}
+
+	var stderr bytes.Buffer
+	spec := wikiNodeCreateSpec{
+		NodeType: wikiNodeTypeOrigin,
+		ObjType:  "docx",
+		Title:    "Roadmap",
+	}
+	execution, err := runWikiNodeCreate(context.Background(), client, core.AsUser, spec, &stderr)
+	if err != nil {
+		t.Fatalf("runWikiNodeCreate() error = %v", err)
+	}
+	if len(client.createInvoked) != 3 {
+		t.Fatalf("create invoked %d times, want 3", len(client.createInvoked))
+	}
+	if execution.Node.NodeToken != "wik_created" {
+		t.Fatalf("node token = %q, want %q", execution.Node.NodeToken, "wik_created")
+	}
+	if !strings.Contains(stderr.String(), "lock contention") {
+		t.Fatalf("stderr = %q, want lock contention log", stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "retrying (attempt 1/") {
+		t.Fatalf("stderr = %q, want attempt 1 log", stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "retrying (attempt 2/") {
+		t.Fatalf("stderr = %q, want attempt 2 log", stderr.String())
+	}
+}
+
+func TestRunWikiNodeCreateRetriesExhausted(t *testing.T) {
+	t.Parallel()
+
+	lockErr := output.ErrAPI(output.LarkErrWikiLockContention, "lock contention", nil)
+
+	client := &fakeWikiNodeCreateClient{
+		spaces: map[string]*wikiSpaceRecord{
+			wikiMyLibrarySpaceID: {SpaceID: "space_my_library"},
+		},
+		createErrs: []error{lockErr, lockErr, lockErr}, // all 3 attempts fail
+	}
+
+	var stderr bytes.Buffer
+	spec := wikiNodeCreateSpec{
+		NodeType: wikiNodeTypeOrigin,
+		ObjType:  "docx",
+		Title:    "Roadmap",
+	}
+	_, err := runWikiNodeCreate(context.Background(), client, core.AsUser, spec, &stderr)
+	if err == nil {
+		t.Fatalf("expected error after retries exhausted")
+	}
+	if len(client.createInvoked) != 3 {
+		t.Fatalf("create invoked %d times, want 3", len(client.createInvoked))
+	}
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError, got %T: %v", err, err)
+	}
+	if exitErr.Detail.Code != output.LarkErrWikiLockContention {
+		t.Fatalf("error code = %d, want %d", exitErr.Detail.Code, output.LarkErrWikiLockContention)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "failed after 2 retries") {
+		t.Fatalf("hint = %q, want retry exhaustion message", exitErr.Detail.Hint)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "lock contention") {
+		t.Fatalf("hint = %q, want original classification hint preserved", exitErr.Detail.Hint)
+	}
+}
+
+func TestRunWikiNodeCreateNoRetryOnNonContentionError(t *testing.T) {
+	t.Parallel()
+
+	otherErr := output.ErrAPI(output.LarkErrRateLimit, "rate limit", nil) // rate limit, not lock contention
+
+	client := &fakeWikiNodeCreateClient{
+		spaces: map[string]*wikiSpaceRecord{
+			wikiMyLibrarySpaceID: {SpaceID: "space_my_library"},
+		},
+		createErrs: []error{otherErr},
+	}
+
+	var stderr bytes.Buffer
+	spec := wikiNodeCreateSpec{
+		NodeType: wikiNodeTypeOrigin,
+		ObjType:  "docx",
+		Title:    "Roadmap",
+	}
+	_, err := runWikiNodeCreate(context.Background(), client, core.AsUser, spec, &stderr)
+	if err == nil {
+		t.Fatalf("expected error")
+	}
+	if len(client.createInvoked) != 1 {
+		t.Fatalf("create invoked %d times, want 1 (no retry)", len(client.createInvoked))
+	}
+	if strings.Contains(stderr.String(), "retrying") {
+		t.Fatalf("stderr = %q, should not contain retry log for non-contention error", stderr.String())
+	}
+}
+
+func TestRunWikiNodeCreateRetriesOnFirstLockThenSucceeds(t *testing.T) {
+	t.Parallel()
+
+	lockErr := output.ErrAPI(output.LarkErrWikiLockContention, "lock contention", nil)
+
+	client := &fakeWikiNodeCreateClient{
+		spaces: map[string]*wikiSpaceRecord{
+			wikiMyLibrarySpaceID: {SpaceID: "space_my_library"},
+		},
+		createNode: &wikiNodeRecord{
+			SpaceID:   "space_my_library",
+			NodeToken: "wik_created",
+			NodeType:  wikiNodeTypeOrigin,
+			ObjType:   "docx",
+			Title:     "Roadmap",
+		},
+		createErrs: []error{lockErr}, // fail once, then succeed
+	}
+
+	var stderr bytes.Buffer
+	spec := wikiNodeCreateSpec{
+		NodeType: wikiNodeTypeOrigin,
+		ObjType:  "docx",
+		Title:    "Roadmap",
+	}
+	execution, err := runWikiNodeCreate(context.Background(), client, core.AsUser, spec, &stderr)
+	if err != nil {
+		t.Fatalf("runWikiNodeCreate() error = %v", err)
+	}
+	if len(client.createInvoked) != 2 {
+		t.Fatalf("create invoked %d times, want 2", len(client.createInvoked))
+	}
+	if execution.Node.NodeToken != "wik_created" {
+		t.Fatalf("node token = %q, want %q", execution.Node.NodeToken, "wik_created")
+	}
+	if !strings.Contains(stderr.String(), "retrying (attempt 1/") {
+		t.Fatalf("stderr = %q, want attempt 1 log", stderr.String())
+	}
+	if strings.Contains(stderr.String(), "retrying (attempt 2/") {
+		t.Fatalf("stderr = %q, should not contain attempt 2 log", stderr.String())
+	}
+}
+
+func TestRunWikiNodeCreateRetryContextCancelled(t *testing.T) {
+	t.Parallel()
+
+	lockErr := output.ErrAPI(output.LarkErrWikiLockContention, "lock contention", nil)
+
+	client := &fakeWikiNodeCreateClient{
+		spaces: map[string]*wikiSpaceRecord{
+			wikiMyLibrarySpaceID: {SpaceID: "space_my_library"},
+		},
+		createErrs: []error{lockErr, lockErr, lockErr}, // always fail
+	}
+
+	var stderr bytes.Buffer
+	spec := wikiNodeCreateSpec{
+		NodeType: wikiNodeTypeOrigin,
+		ObjType:  "docx",
+		Title:    "Roadmap",
+	}
+
+	// Pre-cancel the context so the retry loop's select picks up
+	// ctx.Done() immediately during the first backoff wait.
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := runWikiNodeCreate(ctx, client, core.AsUser, spec, &stderr)
+	if err == nil {
+		t.Fatalf("expected error due to context cancellation")
+	}
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("error = %v, want context.Canceled", err)
+	}
+	// The initial attempt runs (context is checked only during backoff
+	// wait), but no retries should complete.
+	if len(client.createInvoked) != 1 {
+		t.Fatalf("create invoked %d times, want 1 (no retries after cancel)", len(client.createInvoked))
+	}
+}
+
+func TestRunWikiNodeCreateNoRetryOnSuccess(t *testing.T) {
+	t.Parallel()
+
+	client := &fakeWikiNodeCreateClient{
+		spaces: map[string]*wikiSpaceRecord{
+			wikiMyLibrarySpaceID: {SpaceID: "space_my_library"},
+		},
+		createNode: &wikiNodeRecord{
+			SpaceID:   "space_my_library",
+			NodeToken: "wik_created",
+			NodeType:  wikiNodeTypeOrigin,
+			ObjType:   "docx",
+			Title:     "Roadmap",
+		},
+	}
+
+	var stderr bytes.Buffer
+	spec := wikiNodeCreateSpec{
+		NodeType: wikiNodeTypeOrigin,
+		ObjType:  "docx",
+		Title:    "Roadmap",
+	}
+	execution, err := runWikiNodeCreate(context.Background(), client, core.AsUser, spec, &stderr)
+	if err != nil {
+		t.Fatalf("runWikiNodeCreate() error = %v", err)
+	}
+	if len(client.createInvoked) != 1 {
+		t.Fatalf("create invoked %d times, want 1", len(client.createInvoked))
+	}
+	if execution.Node.NodeToken != "wik_created" {
+		t.Fatalf("node token = %q, want %q", execution.Node.NodeToken, "wik_created")
+	}
+	if strings.Contains(stderr.String(), "retrying") {
+		t.Fatalf("stderr = %q, should not contain retry log on success", stderr.String())
+	}
+}

shortcuts/wiki/wiki_node_get.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
 )
 
 // wikiNodeGetURLObjTypes maps a Lark URL path prefix (slash-bounded) to the
@@ -57,14 +58,26 @@ var WikiNodeGet = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags: []common.Flag{
-		{Name: "token", Desc: "wiki node_token, obj_token, or a Lark URL embedding one of them", Required: true},
-		{Name: "obj-type", Desc: "obj_type when --token is an obj_token; auto-inferred from URL path when omitted", Enum: wikiNodeGetObjTypeEnum},
+		// --node-token is the canonical flag, matching sibling wiki commands
+		// (+node-delete / +node-copy / +move). --token is the original name
+		// and is kept as a hidden deprecated alias for backward compatibility;
+		// MarkDeprecated (registered in PostMount) prints a stderr warning
+		// when --token is used.
+		{Name: "node-token", Desc: "wiki node_token, obj_token, or a Lark URL embedding one of them"},
+		{Name: "token", Desc: "DEPRECATED: use --node-token", Hidden: true},
+		{Name: "obj-type", Desc: "obj_type when --node-token is an obj_token; auto-inferred from URL path when omitted", Enum: wikiNodeGetObjTypeEnum},
 		{Name: "space-id", Desc: "optional: assert the resolved node lives in this space"},
 	},
 	Tips: []string{
-		"--token accepts a raw token (wikcnXXX, docxXXX, ...) or a Lark URL like https://feishu.cn/wiki/<token> or https://feishu.cn/docx/<token>.",
+		"--node-token accepts a raw token (wikcnXXX, docxXXX, ...) or a Lark URL like https://feishu.cn/wiki/<token> or https://feishu.cn/docx/<token>.",
 		"For raw obj_tokens (not starting with wik), pass --obj-type so the API knows how to resolve them; URL inputs infer it from the path.",
 		"Pair with +move / +node-copy / +delete-space to confirm space_id, obj_type, and parent before mutating.",
+		"--token is the deprecated original name and still works for backward compatibility; new scripts should use --node-token.",
+	},
+	PostMount: func(cmd *cobra.Command) {
+		// cobra's MarkDeprecated prints "Flag --token has been deprecated, use --node-token instead"
+		// to stderr on use, and hides the flag from --help (matching the Hidden: true marker above).
+		_ = cmd.Flags().MarkDeprecated("token", "use --node-token instead")
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		_, err := readWikiNodeGetSpec(runtime)
@@ -142,20 +155,45 @@ func (spec wikiNodeGetSpec) RequestParams() map[string]interface{} {
 }
 
 func readWikiNodeGetSpec(runtime *common.RuntimeContext) (wikiNodeGetSpec, error) {
-	return parseWikiNodeGetSpec(
+	rawToken, err := resolveWikiNodeGetRawToken(
+		runtime.Str("node-token"),
 		runtime.Str("token"),
+	)
+	if err != nil {
+		return wikiNodeGetSpec{}, err
+	}
+	return parseWikiNodeGetSpec(
+		rawToken,
 		runtime.Str("obj-type"),
 		runtime.Str("space-id"),
 	)
 }
 
+// resolveWikiNodeGetRawToken picks between the canonical --node-token and the
+// deprecated --token alias. Both empty is fine (parseWikiNodeGetSpec will
+// surface the required-flag error). Both set with different values is rejected
+// upfront so callers fix the obvious bug rather than silently picking one.
+func resolveWikiNodeGetRawToken(nodeToken, legacyToken string) (string, error) {
+	canonical := strings.TrimSpace(nodeToken)
+	legacy := strings.TrimSpace(legacyToken)
+	switch {
+	case canonical != "" && legacy != "" && canonical != legacy:
+		return "", output.ErrValidation(
+			"--node-token and --token are both set with different values; pass --node-token only (--token is deprecated)")
+	case canonical != "":
+		return nodeToken, nil
+	default:
+		return legacyToken, nil
+	}
+}
+
 // parseWikiNodeGetSpec normalizes the raw flag values: extracts a token from a
 // URL when needed, picks the obj_type (URL path > explicit flag > none for
 // node_tokens), and validates the token shape.
 func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetSpec, error) {
 	tokenInput := strings.TrimSpace(rawToken)
 	if tokenInput == "" {
-		return wikiNodeGetSpec{}, output.ErrValidation("--token is required")
+		return wikiNodeGetSpec{}, output.ErrValidation("--node-token is required")
 	}
 
 	spec := wikiNodeGetSpec{
@@ -166,12 +204,12 @@ func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetS
 	if strings.Contains(tokenInput, "://") {
 		u, err := url.Parse(tokenInput)
 		if err != nil || u.Path == "" {
-			return wikiNodeGetSpec{}, output.ErrValidation("--token URL is malformed: %q", tokenInput)
+			return wikiNodeGetSpec{}, output.ErrValidation("--node-token URL is malformed: %q", tokenInput)
 		}
 		token, urlObjType, ok := tokenAndObjTypeFromWikiURL(u.Path)
 		if !ok {
 			return wikiNodeGetSpec{}, output.ErrValidation(
-				"unsupported --token URL path %q: expected /wiki/, /docx/, /doc/, /sheets/, /base/, /mindnote/, /slides/, or /file/ followed by a token",
+				"unsupported --node-token URL path %q: expected /wiki/, /docx/, /doc/, /sheets/, /base/, /mindnote/, /slides/, or /file/ followed by a token",
 				u.Path,
 			)
 		}
@@ -192,7 +230,7 @@ func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetS
 		}
 	} else if strings.ContainsAny(tokenInput, "/?#") {
 		return wikiNodeGetSpec{}, output.ErrValidation(
-			"--token must be a raw token or a full URL; partial paths are not accepted: %q",
+			"--node-token must be a raw token or a full URL; partial paths are not accepted: %q",
 			tokenInput,
 		)
 	} else {
@@ -223,7 +261,7 @@ func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetS
 		}
 	}
 
-	if err := validateOptionalResourceName(spec.Token, "--token"); err != nil {
+	if err := validateOptionalResourceName(spec.Token, "--node-token"); err != nil {
 		return wikiNodeGetSpec{}, err
 	}
 	if err := validateOptionalResourceName(spec.SpaceID, "--space-id"); err != nil {

shortcuts/wiki/wiki_node_get_test.go

@@ -4,6 +4,7 @@
 package wiki
 
 import (
+	"bytes"
 	"encoding/json"
 	"net/http"
 	"reflect"
@@ -12,6 +13,7 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/spf13/cobra"
 )
 
 func TestParseWikiNodeGetSpecRawNodeToken(t *testing.T) {
@@ -98,7 +100,7 @@ func TestParseWikiNodeGetSpecRejectsUnsupportedURLPath(t *testing.T) {
 	t.Parallel()
 
 	_, err := parseWikiNodeGetSpec("https://feishu.cn/im/chat/oc_123", "", "")
-	if err == nil || !strings.Contains(err.Error(), "unsupported --token URL path") {
+	if err == nil || !strings.Contains(err.Error(), "unsupported --node-token URL path") {
 		t.Fatalf("expected unsupported URL path error, got %v", err)
 	}
 }
@@ -115,11 +117,61 @@ func TestParseWikiNodeGetSpecRejectsPartialPath(t *testing.T) {
 func TestParseWikiNodeGetSpecRejectsEmptyToken(t *testing.T) {
 	t.Parallel()
 
-	if _, err := parseWikiNodeGetSpec("   ", "", ""); err == nil || !strings.Contains(err.Error(), "--token is required") {
+	if _, err := parseWikiNodeGetSpec("   ", "", ""); err == nil || !strings.Contains(err.Error(), "--node-token is required") {
 		t.Fatalf("expected required-token error, got %v", err)
 	}
 }
 
+func TestResolveWikiNodeGetRawTokenPrefersNodeToken(t *testing.T) {
+	t.Parallel()
+
+	got, err := resolveWikiNodeGetRawToken("wikcnNEW", "")
+	if err != nil || got != "wikcnNEW" {
+		t.Fatalf("resolve(node-token only) = (%q, %v), want (wikcnNEW, nil)", got, err)
+	}
+}
+
+func TestResolveWikiNodeGetRawTokenAcceptsLegacyToken(t *testing.T) {
+	t.Parallel()
+
+	got, err := resolveWikiNodeGetRawToken("", "wikcnLEGACY")
+	if err != nil || got != "wikcnLEGACY" {
+		t.Fatalf("resolve(legacy only) = (%q, %v), want (wikcnLEGACY, nil)", got, err)
+	}
+}
+
+func TestResolveWikiNodeGetRawTokenAcceptsBothWhenEqual(t *testing.T) {
+	t.Parallel()
+
+	// Same value on both flags is harmless (e.g. a script doubled the input
+	// while migrating to --node-token) — prefer the canonical one and don't
+	// surface a conflict error.
+	got, err := resolveWikiNodeGetRawToken("wikcnSAME", "wikcnSAME")
+	if err != nil || got != "wikcnSAME" {
+		t.Fatalf("resolve(both same) = (%q, %v), want (wikcnSAME, nil)", got, err)
+	}
+}
+
+func TestResolveWikiNodeGetRawTokenRejectsConflict(t *testing.T) {
+	t.Parallel()
+
+	_, err := resolveWikiNodeGetRawToken("wikcnNEW", "wikcnOLD")
+	if err == nil || !strings.Contains(err.Error(), "both set with different values") {
+		t.Fatalf("expected conflict error, got %v", err)
+	}
+}
+
+func TestResolveWikiNodeGetRawTokenEmptyDefersToParser(t *testing.T) {
+	t.Parallel()
+
+	// Both empty is not an error here — the caller (parseWikiNodeGetSpec) is
+	// where the required-flag check lives and produces the user-facing message.
+	got, err := resolveWikiNodeGetRawToken("", "")
+	if err != nil || got != "" {
+		t.Fatalf("resolve(empty) = (%q, %v), want ('', nil)", got, err)
+	}
+}
+
 func TestBuildWikiNodeGetDryRunSendsObjType(t *testing.T) {
 	t.Parallel()
 
@@ -204,7 +256,7 @@ func TestWikiNodeGetMountedExecuteParsesURLAndFormatsOutput(t *testing.T) {
 
 	err := mountAndRunWiki(t, WikiNodeGet, []string{
 		"+node-get",
-		"--token", "https://feishu.cn/docx/docxXYZ",
+		"--node-token", "https://feishu.cn/docx/docxXYZ",
 		"--as", "bot",
 	}, factory, stdout)
 	if err != nil {
@@ -245,6 +297,150 @@ func TestWikiNodeGetMountedExecuteParsesURLAndFormatsOutput(t *testing.T) {
 	}
 }
 
+func TestWikiNodeGetMountedAcceptsNodeTokenFlag(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+
+	stub := &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"space_id":   "space_123",
+					"node_token": "wikcnABC",
+					"obj_token":  "docxXYZ",
+					"obj_type":   "docx",
+					"node_type":  "origin",
+					"title":      "Via Node-Token",
+				},
+			},
+			"msg": "success",
+		},
+	}
+	var capturedQuery string
+	stub.OnMatch = func(req *http.Request) {
+		capturedQuery = req.URL.RawQuery
+	}
+	reg.Register(stub)
+
+	// Mount inline (rather than using mountAndRunWiki) so we can redirect the
+	// subcommand's pflag output and assert that no deprecation warning leaks
+	// when the canonical --node-token is used. The deprecation message comes
+	// from pflag, not cobra, so SetErr on the cobra root is NOT enough — pflag
+	// writes to FlagSet.Output(), which we redirect via Flags().SetOutput.
+	var flagOut bytes.Buffer
+	parent := mountWikiNodeGetWithFlagOut(t, factory, &flagOut)
+	parent.SetArgs([]string{
+		"+node-get",
+		"--node-token", "https://feishu.cn/docx/docxXYZ",
+		"--as", "bot",
+	})
+	stdout.Reset()
+	if err := parent.Execute(); err != nil {
+		t.Fatalf("parent.Execute() error = %v", err)
+	}
+
+	if !strings.Contains(capturedQuery, "token=docxXYZ") || !strings.Contains(capturedQuery, "obj_type=docx") {
+		t.Fatalf("captured query = %q, want token=docxXYZ and obj_type=docx", capturedQuery)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	if data["title"] != "Via Node-Token" {
+		t.Fatalf("title = %#v, want Via Node-Token", data["title"])
+	}
+	if got := flagOut.String(); strings.Contains(got, "deprecated") {
+		t.Fatalf("pflag output unexpectedly contains deprecation warning when using --node-token: %q", got)
+	}
+}
+
+// mountWikiNodeGetWithFlagOut mounts +node-get on a fresh parent and redirects
+// the subcommand's pflag output to w so tests can capture cobra/pflag-level
+// deprecation messages (which bypass the runtime IO stderr exposed by
+// TestFactory).
+func mountWikiNodeGetWithFlagOut(t *testing.T, factory *cmdutil.Factory, w *bytes.Buffer) *cobra.Command {
+	t.Helper()
+	parent := &cobra.Command{Use: "wiki"}
+	WikiNodeGet.Mount(parent, factory)
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	parent.SetErr(w)
+	for _, child := range parent.Commands() {
+		if child.Use == WikiNodeGet.Command {
+			child.Flags().SetOutput(w)
+			return parent
+		}
+	}
+	t.Fatalf("mountWikiNodeGetWithFlagOut: subcommand %q not registered on parent", WikiNodeGet.Command)
+	return nil
+}
+
+func TestWikiNodeGetMountedLegacyTokenFlagWarnsButWorks(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"space_id":   "space_123",
+					"node_token": "wikcnABC",
+					"obj_token":  "docxXYZ",
+					"obj_type":   "docx",
+					"node_type":  "origin",
+					"title":      "Legacy Token Path",
+				},
+			},
+			"msg": "success",
+		},
+	})
+
+	var flagOut bytes.Buffer
+	parent := mountWikiNodeGetWithFlagOut(t, factory, &flagOut)
+	parent.SetArgs([]string{
+		"+node-get",
+		"--token", "wikcnABC",
+		"--as", "bot",
+	})
+	stdout.Reset()
+	if err := parent.Execute(); err != nil {
+		t.Fatalf("parent.Execute() error = %v", err)
+	}
+
+	data := decodeWikiEnvelope(t, stdout)
+	if data["title"] != "Legacy Token Path" {
+		t.Fatalf("title = %#v, want Legacy Token Path", data["title"])
+	}
+	// pflag MarkDeprecated prints "Flag --token has been deprecated, use --node-token instead".
+	got := flagOut.String()
+	if !strings.Contains(got, "deprecated") || !strings.Contains(got, "--node-token") {
+		t.Fatalf("pflag output = %q, want a deprecation warning pointing to --node-token", got)
+	}
+}
+
+func TestWikiNodeGetMountedRejectsConflictingTokenFlags(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	// reg is unused: conflict is caught in Validate before any HTTP call.
+	factory, stdout, _, _ := cmdutil.TestFactory(t, wikiTestConfig())
+
+	err := mountAndRunWiki(t, WikiNodeGet, []string{
+		"+node-get",
+		"--node-token", "wikcnNEW",
+		"--token", "wikcnOLD",
+		"--as", "bot",
+	}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "both set with different values") {
+		t.Fatalf("expected conflict error, got %v", err)
+	}
+}
+
 func TestWikiNodeGetFallsBackToCreatorWhenNodeCreatorMissing(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
@@ -272,7 +468,7 @@ func TestWikiNodeGetFallsBackToCreatorWhenNodeCreatorMissing(t *testing.T) {
 
 	err := mountAndRunWiki(t, WikiNodeGet, []string{
 		"+node-get",
-		"--token", "wikcnABC",
+		"--node-token", "wikcnABC",
 		"--as", "bot",
 	}, factory, stdout)
 	if err != nil {
@@ -311,7 +507,7 @@ func TestWikiNodeGetRejectsSpaceIDMismatch(t *testing.T) {
 
 	err := mountAndRunWiki(t, WikiNodeGet, []string{
 		"+node-get",
-		"--token", "wikcnABC",
+		"--node-token", "wikcnABC",
 		"--space-id", "space_expected",
 		"--as", "bot",
 	}, factory, stdout)

sidecar/server-demo/README.md

@@ -195,3 +195,9 @@ its identity flipped (bot↔user) or its auth-header redirected (e.g. into
 | `allowlist.go` | Target host / identity allowlists |
 | `audit.go` | Log path/error sanitization |
 | `handler_test.go` | Unit tests for all of the above |
+
+## See also
+
+- [server-multi-tenant-demo](../server-multi-tenant-demo/) — extends this demo
+  with per-client HMAC key isolation, OAuth device-flow login, and persistent
+  client → user mapping for multi-tenant deployments

sidecar/server-multi-tenant-demo/README.md

@@ -0,0 +1,281 @@
+# Multi-Tenant Sidecar Server Demo
+
+> ⚠️ **This is a demo.** For production deployment, implement your own sidecar
+> server conforming to the wire protocol in `github.com/larksuite/cli/sidecar`.
+
+## Problem
+
+Organizations often manage **multiple Lark/Feishu apps** (e.g. one per
+department, one per product line), each with its own `app_id` and `app_secret`.
+These credentials must never be exposed to end-user environments (CI runners,
+developer sandboxes, containerized workspaces). At the same time, when multiple
+users share the same sidecar infrastructure, their Feishu identities must be
+strictly isolated — user A must never accidentally operate as user B.
+
+The single-tenant [server-demo](../server-demo/) solves the credential-hiding
+problem for **one app with one user**. This multi-tenant demo extends it to
+support:
+
+1. **Multiple apps** — run one sidecar instance per app; each instance holds
+   its own `app_id` / `app_secret` and listens on a separate port. Clients
+   choose which app to use by pointing `LARKSUITE_CLI_AUTH_PROXY` to the
+   corresponding port.
+2. **Per-client identity isolation** — each client environment gets a unique
+   HMAC key. The sidecar identifies request origin by matching the HMAC
+   signature and injects the correct user's token. No fallback to other
+   users' tokens.
+3. **Self-service user login** — management endpoints let each client initiate
+   an OAuth device-flow login to bind their own Feishu identity, without
+   exposing `app_secret` to the client.
+
+## Typical deployment
+
+```text
+                    Trusted Host
+    ┌──────────────────────────────────────────────┐
+    │  sidecar instance A (port 16384)             │
+    │    app_id=cli_aaa  app_secret=***            │
+    │    keys/proxy.key  keys/alice.key  keys/bob… │
+    │                                              │
+    │  sidecar instance B (port 16385)             │
+    │    app_id=cli_bbb  app_secret=***            │
+    │    keys/proxy.key  keys/charlie.key  ...     │
+    └─────────────┬────────────────────────────────┘
+                  │ same machine (loopback / docker bridge)
+    ┌─────────────┴────────────────────────────────┐
+    │  Client sandbox (container / CI runner)       │
+    │                                              │
+    │  LARKSUITE_CLI_AUTH_PROXY=http://host:16384   │
+    │  LARKSUITE_CLI_PROXY_KEY=<contents of         │
+    │                           alice.key>          │
+    │  LARKSUITE_CLI_APP_ID=cli_aaa                │
+    │  LARKSUITE_CLI_BRAND=feishu                  │
+    │                                              │
+    │  $ lark api GET /open-apis/... --as user     │
+    │    → sidecar matches alice.key               │
+    │    → injects alice's Feishu user token       │
+    └──────────────────────────────────────────────┘
+```
+
+**Key points:**
+
+- `app_id` and `app_secret` live only on the trusted host — clients only
+  know `app_id` (needed for the CLI's credential pipeline) and their own
+  HMAC key.
+- Each sidecar instance binds one app. Multiple apps = multiple instances
+  on different ports.
+- Clients select which app to use by choosing which sidecar port to connect
+  to (via `LARKSUITE_CLI_AUTH_PROXY`).
+
+## Architecture
+
+```text
+┌──────────────────────────────────────────────────────┐
+│                    Sidecar Server                     │
+│                                                      │
+│  ┌─────────────┐  ┌──────────────────────────────┐  │
+│  │ Shared Key   │  │ Per-Client Keys              │  │
+│  │ (proxy.key)  │  │ alice.key, bob.key, ...      │  │
+│  └──────┬──────┘  └──────────────┬───────────────┘  │
+│         │ management plane       │ data plane        │
+│         ▼                        ▼                   │
+│  ┌─────────────┐  ┌──────────────────────────────┐  │
+│  │ Auth Bridge  │  │ Proxy Handler                │  │
+│  │ login/poll/  │  │ HMAC verify → identify       │  │
+│  │ status       │  │ client → inject user token   │  │
+│  └─────────────┘  └──────────────────────────────┘  │
+└──────────────────────────────────────────────────────┘
+```
+
+**Dual-key design:**
+- **Management plane** (login flow): all clients use the shared `proxy.key`.
+  This allows any client to initiate login and query status without needing
+  individual key files pre-provisioned.
+- **Data plane** (API proxy): each client uses its own `{name}.key` for HMAC
+  signing. The sidecar identifies the client by matching which key verifies
+  the request signature, then injects that client's bound user token.
+
+## Build
+
+```bash
+go build -tags authsidecar_multi_tenant_demo \
+  -o sidecar-multi-tenant-demo \
+  ./sidecar/server-multi-tenant-demo/
+```
+
+## Server setup
+
+### 1. Configure the Lark app (trusted side only)
+
+```bash
+lark-cli config init --new   # set app_id / app_secret
+```
+
+### 2. Prepare the keys directory
+
+```text
+keys/
+├── proxy.key          # shared key (auto-generated on first run)
+├── alice.key          # client "alice" — generate with: openssl rand -hex 32 > alice.key
+├── bob.key            # client "bob"
+└── charlie.key        # client "charlie"
+```
+
+- Each file contains a 64-character hex string (32 bytes).
+- Filename stem (without `.key`) becomes the client identity.
+- `proxy.key` is excluded from client key scanning.
+- Keys are auto-rescanned on cache miss — add a new `.key` file and the next
+  unrecognized request will trigger a rescan; no restart needed.
+- Duplicate key values and shared-key collisions are rejected with a warning.
+
+### 3. Start the server
+
+```bash
+./sidecar-multi-tenant-demo \
+  --listen 127.0.0.1:16384 \
+  --key-file /path/to/keys/proxy.key \
+  --keys-dir /path/to/keys/ \
+  --log-file /path/to/audit.log
+```
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--listen` | `127.0.0.1:16384` | Address to bind the HTTP listener |
+| `--key-file` | `~/.lark-sidecar/proxy.key` | Shared HMAC key path (created if absent) |
+| `--keys-dir` | *(parent of `--key-file`)* | Directory containing per-client `*.key` files |
+| `--log-file` | *(stderr)* | Audit log output path |
+| `--profile` | *(active profile)* | lark-cli profile name for credential lookup |
+
+## Client setup
+
+**No changes to `lark-cli` itself are required.** The standard sidecar env
+vars are all that's needed — the multi-tenant isolation is entirely
+server-side.
+
+### Required environment variables
+
+```bash
+# Point to the sidecar instance for the desired app
+export LARKSUITE_CLI_AUTH_PROXY="http://127.0.0.1:16384"
+
+# Client-specific HMAC key (data-plane identity)
+export LARKSUITE_CLI_PROXY_KEY="$(cat /path/to/keys/alice.key)"
+
+# Must match the app configured on the sidecar instance
+export LARKSUITE_CLI_APP_ID="cli_xxx"
+
+# feishu or lark
+export LARKSUITE_CLI_BRAND="feishu"
+```
+
+### Multi-app switching (multiple sidecar instances)
+
+When the server operator runs multiple sidecar instances (one per app), clients
+switch between apps by changing `LARKSUITE_CLI_AUTH_PROXY` to point to the
+appropriate port:
+
+```bash
+# App A (e.g. "Marketing" app)
+export LARKSUITE_CLI_AUTH_PROXY="http://127.0.0.1:16384"
+export LARKSUITE_CLI_APP_ID="cli_marketing_app"
+
+# App B (e.g. "Engineering" app)
+export LARKSUITE_CLI_AUTH_PROXY="http://127.0.0.1:16385"
+export LARKSUITE_CLI_APP_ID="cli_engineering_app"
+```
+
+A client-side helper script can present these as a menu (e.g. "Select
+company"), reading from a local config file that maps app names to ports.
+The sidecar itself does not implement app selection — it is one instance per
+app by design.
+
+### User login flow
+
+Once the env vars are set, the client authenticates via the management
+endpoints. A helper script (or manual `curl`) calls:
+
+1. **Login**: `POST /_sidecar/auth/login` with `{"client_id": "alice"}` →
+   returns a device code and verification URL.
+2. **User opens the URL in a browser** and authorizes the app.
+3. **Poll**: `POST /_sidecar/auth/poll` with `{"device_code": "...", "client_id": "alice"}` →
+   blocks until authorization completes.
+4. **Status**: `POST /_sidecar/auth/status` with `{"client_id": "alice"}` →
+   returns the bound user name and token status.
+
+All management requests are signed with the **shared `proxy.key`** (not the
+client-specific key). The `client_id` in the body tells the sidecar which
+client→user mapping to update.
+
+After login, `lark-cli` commands (`lark api ...`, `lark doc ...`, etc.) work
+immediately — the sidecar injects the correct user token based on the
+client's HMAC key, with no additional configuration needed.
+
+### Example: end-to-end workflow
+
+```bash
+# 1. Server operator generates a key for a new client
+openssl rand -hex 32 > /path/to/keys/alice.key
+
+# 2. Client environment is configured (e.g. in .bashrc or container init)
+export LARKSUITE_CLI_AUTH_PROXY="http://host.docker.internal:16384"
+export LARKSUITE_CLI_PROXY_KEY="$(cat /path/to/keys/alice.key)"
+export LARKSUITE_CLI_APP_ID="cli_xxx"
+export LARKSUITE_CLI_BRAND="feishu"
+
+# 3. Client logs in (one-time)
+#    (using a helper script that calls the management endpoints)
+lark-auth login
+
+# 4. Client uses lark-cli as normal — identity is automatically resolved
+lark api GET /open-apis/authen/v1/user_info --as user
+# → returns alice's Feishu identity, not another user's
+```
+
+## Management endpoints
+
+| Endpoint | Method | Body | Purpose |
+| --- | --- | --- | --- |
+| `/_sidecar/auth/login` | POST | `{"client_id": "...", "domains": [...]}` | Start OAuth device-flow |
+| `/_sidecar/auth/poll` | POST | `{"device_code": "...", "client_id": "..."}` | Poll for completion |
+| `/_sidecar/auth/status` | POST | `{"client_id": "..."}` | Query status and mapping |
+
+All management requests require HMAC signing with the shared `proxy.key`.
+The HMAC covers method, path, timestamp, and body SHA-256 — see
+`verifyManagementHMAC` in `auth_bridge.go` for the canonical string format.
+
+## Design decisions
+
+1. **HMAC key as client identity** — the key is the existing trust anchor.
+   Using it for identification introduces no new trust assumptions and
+   prevents a malicious client from spoofing another client's identity
+   (unlike a header-based approach).
+
+2. **No fallback on unmapped clients** — this is authentication. Silently
+   falling back to another user's token is a security violation. Unmapped
+   clients receive an explicit error prompting them to log in.
+
+3. **One sidecar instance per app** — keeps `app_secret` scoping simple and
+   avoids cross-app token confusion. Multi-app support is achieved by running
+   multiple instances on different ports.
+
+4. **Proxy.key reuse across restarts** — when multiple sidecar instances start
+   concurrently, they all write to the same key file. The last writer wins,
+   leaving other instances with stale in-memory keys. Reusing the existing
+   key eliminates this race.
+
+## Source layout
+
+| File | Purpose |
+| --- | --- |
+| `main.go` | Entry point: flag parsing, key loading, server lifecycle |
+| `handler.go` | `proxyHandler.ServeHTTP` — multi-key HMAC verification and request forwarding |
+| `auth_bridge.go` | Management endpoints: login, poll, status, user mapping persistence |
+| `forward.go` | Forwarding HTTP client + proxy-header filter |
+| `allowlist.go` | Target host / identity allowlists |
+| `audit.go` | Log path/error sanitization |
+| `handler_test.go` | Unit tests |
+
+## See also
+
+- [server-demo](../server-demo/) — single-tenant minimal implementation
+- [`sidecar` package](https://pkg.go.dev/github.com/larksuite/cli/sidecar) — wire protocol

sidecar/server-multi-tenant-demo/allowlist.go

@@ -0,0 +1,44 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar_multi_tenant_demo
+
+package main
+
+import (
+	"strings"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/sidecar"
+)
+
+// buildAllowedHosts extracts the set of allowed target hostnames from
+// multiple brand endpoints so the sidecar can serve both feishu and lark clients.
+func buildAllowedHosts(endpoints ...core.Endpoints) map[string]bool {
+	hosts := make(map[string]bool)
+	for _, ep := range endpoints {
+		for _, u := range []string{ep.Open, ep.Accounts, ep.MCP} {
+			if idx := strings.Index(u, "://"); idx >= 0 {
+				hosts[u[idx+3:]] = true
+			}
+		}
+	}
+	return hosts
+}
+
+// buildAllowedIdentities returns the set of identities the sidecar is allowed to serve,
+// based on the trusted-side strict mode / SupportedIdentities configuration.
+func buildAllowedIdentities(cfg *core.CliConfig) map[string]bool {
+	ids := make(map[string]bool)
+	switch {
+	case cfg.SupportedIdentities == 0: // unknown/unset → allow both
+		ids[sidecar.IdentityUser] = true
+		ids[sidecar.IdentityBot] = true
+	case cfg.SupportedIdentities&1 != 0: // SupportsUser bit
+		ids[sidecar.IdentityUser] = true
+	}
+	if cfg.SupportedIdentities == 0 || cfg.SupportedIdentities&2 != 0 { // SupportsBot bit
+		ids[sidecar.IdentityBot] = true
+	}
+	return ids
+}

sidecar/server-multi-tenant-demo/audit.go

@@ -0,0 +1,51 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar_multi_tenant_demo
+
+package main
+
+import "strings"
+
+// sanitizePath strips query parameters and replaces ID-like path segments
+// with ":id" to prevent document tokens, chat IDs, etc. from leaking into logs.
+// Example: /open-apis/docx/v1/documents/doxcnXXXX/blocks → /open-apis/docx/v1/documents/:id/blocks
+func sanitizePath(pathAndQuery string) string {
+	// Strip query
+	path := pathAndQuery
+	if i := strings.IndexByte(path, '?'); i >= 0 {
+		path = path[:i]
+	}
+	// Replace ID-like segments (8+ chars, not a pure API keyword)
+	parts := strings.Split(path, "/")
+	for i, p := range parts {
+		if looksLikeID(p) {
+			parts[i] = ":id"
+		}
+	}
+	return strings.Join(parts, "/")
+}
+
+// looksLikeID returns true if a path segment appears to be a resource identifier
+// rather than an API route keyword. Heuristic: 8+ chars and contains a digit.
+func looksLikeID(seg string) bool {
+	if len(seg) < 8 {
+		return false
+	}
+	for _, c := range seg {
+		if c >= '0' && c <= '9' {
+			return true
+		}
+	}
+	return false
+}
+
+// sanitizeError returns a safe error string for logging, capped at 200 bytes
+// to avoid dumping upstream response bodies into audit logs.
+func sanitizeError(err error) string {
+	s := err.Error()
+	if len(s) > 200 {
+		return s[:200] + "..."
+	}
+	return s
+}

sidecar/server-multi-tenant-demo/auth_bridge.go

@@ -0,0 +1,530 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar_multi_tenant_demo
+
+package main
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"math"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// authBridge handles /_sidecar/auth/* management endpoints.
+// Supports multi-user token isolation: each client environment gets its own
+// Feishu identity via a clientName → feishuOpenId mapping.
+//
+// Identity chain:  PROXY_KEY → clientName → feishuOpenId → keychain token
+type authBridge struct {
+	key       []byte
+	appID     string
+	appSecret string
+	brand     core.LarkBrand
+	cred      *credential.CredentialProvider
+	logger    *log.Logger
+	httpCl    *http.Client
+
+	mu           sync.Mutex
+	pendingPolls map[string]context.CancelFunc
+
+	// clientName → feishuOpenId (protected by mu)
+	userMap map[string]string
+	mapFile string
+}
+
+func newAuthBridge(key []byte, appID, appSecret string, brand core.LarkBrand, cred *credential.CredentialProvider, logger *log.Logger) *authBridge {
+	configDir := os.Getenv("LARKSUITE_CLI_CONFIG_DIR")
+	mapFile := ""
+	if configDir != "" {
+		mapFile = filepath.Join(configDir, "client_user_map.json")
+	}
+
+	ab := &authBridge{
+		key:          key,
+		appID:        appID,
+		appSecret:    appSecret,
+		brand:        brand,
+		cred:         cred,
+		logger:       logger,
+		httpCl:       &http.Client{Timeout: 30 * time.Second},
+		pendingPolls: make(map[string]context.CancelFunc),
+		userMap:      make(map[string]string),
+		mapFile:      mapFile,
+	}
+	ab.loadUserMap()
+	return ab
+}
+
+func (ab *authBridge) loadUserMap() {
+	if ab.mapFile == "" {
+		return
+	}
+	data, err := vfs.ReadFile(ab.mapFile)
+	if err != nil {
+		return
+	}
+	var m map[string]string
+	if json.Unmarshal(data, &m) == nil && m != nil {
+		ab.userMap = m
+	}
+}
+
+func (ab *authBridge) saveUserMap() {
+	if ab.mapFile == "" {
+		return
+	}
+	data, err := json.MarshalIndent(ab.userMap, "", "  ")
+	if err != nil {
+		ab.logger.Printf("AUTH_BRIDGE_ERROR action=save_user_map error=%q", err.Error())
+		return
+	}
+	if err := vfs.WriteFile(ab.mapFile, data, 0600); err != nil {
+		ab.logger.Printf("AUTH_BRIDGE_ERROR action=save_user_map error=%q", err.Error())
+	}
+}
+
+// verifyManagementHMAC checks a simplified HMAC for management endpoints.
+// Canonical string: "sidecar-mgmt\n<method>\n<path>\n<timestamp>\n<body_sha256>"
+func (ab *authBridge) verifyManagementHMAC(r *http.Request, body []byte) error {
+	ts := r.Header.Get("X-Sidecar-Timestamp")
+	sig := r.Header.Get("X-Sidecar-Signature")
+	bodySha := r.Header.Get("X-Sidecar-Body-SHA256")
+
+	if ts == "" || sig == "" || bodySha == "" {
+		return fmt.Errorf("missing required headers")
+	}
+
+	tsVal, err := strconv.ParseInt(ts, 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid timestamp")
+	}
+	drift := math.Abs(float64(time.Now().Unix() - tsVal))
+	if drift > 60 {
+		return fmt.Errorf("timestamp drift %.0fs exceeds limit", drift)
+	}
+
+	actualSha := sha256Hex(body)
+	if bodySha != actualSha {
+		return fmt.Errorf("body SHA256 mismatch")
+	}
+
+	canonical := "sidecar-mgmt\n" + r.Method + "\n" + r.URL.Path + "\n" + ts + "\n" + bodySha
+	mac := hmac.New(sha256.New, ab.key)
+	mac.Write([]byte(canonical))
+	expected := hex.EncodeToString(mac.Sum(nil))
+
+	if !hmac.Equal([]byte(expected), []byte(sig)) {
+		return fmt.Errorf("HMAC signature mismatch")
+	}
+	return nil
+}
+
+func sha256Hex(data []byte) string {
+	h := sha256.Sum256(data)
+	return hex.EncodeToString(h[:])
+}
+
+// ServeHTTP routes management API requests.
+func (ab *authBridge) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 64*1024))
+	if err != nil {
+		jsonError(w, http.StatusBadRequest, "failed to read body")
+		return
+	}
+	r.Body.Close()
+
+	if err := ab.verifyManagementHMAC(r, body); err != nil {
+		jsonError(w, http.StatusUnauthorized, "HMAC verification failed: "+err.Error())
+		ab.logger.Printf("AUTH_BRIDGE_REJECT path=%s reason=%q", r.URL.Path, err.Error())
+		return
+	}
+
+	switch r.URL.Path {
+	case "/_sidecar/auth/login":
+		ab.handleLogin(w, r, body)
+	case "/_sidecar/auth/poll":
+		ab.handlePoll(w, r, body)
+	case "/_sidecar/auth/status":
+		ab.handleStatus(w, r, body)
+	default:
+		jsonError(w, http.StatusNotFound, "unknown management endpoint")
+	}
+}
+
+// parseClientID extracts the client identifier from a JSON body.
+func parseClientID(body []byte) string {
+	var raw struct {
+		ClientID string `json:"client_id"`
+	}
+	if len(body) > 0 {
+		_ = json.Unmarshal(body, &raw)
+	}
+	return raw.ClientID
+}
+
+// handleLogin initiates a device-flow OAuth login.
+func (ab *authBridge) handleLogin(w http.ResponseWriter, _ *http.Request, body []byte) {
+	var req struct {
+		Scope   string   `json:"scope"`
+		Domains []string `json:"domains"`
+	}
+	if len(body) > 0 {
+		_ = json.Unmarshal(body, &req)
+	}
+	clientID := parseClientID(body)
+
+	scope := req.Scope
+	if scope == "" {
+		scope = loadCachedScopes()
+	}
+	if scope == "" {
+		scope = "offline_access"
+	}
+
+	ab.logger.Printf("AUTH_BRIDGE_LOGIN_SCOPE scope_count=%d domains=%v client=%s",
+		len(strings.Fields(scope)), req.Domains, clientID)
+
+	authResp, err := larkauth.RequestDeviceAuthorization(
+		ab.httpCl, ab.appID, ab.appSecret, ab.brand, scope, io.Discard,
+	)
+	if err != nil {
+		jsonError(w, http.StatusBadGateway, "device authorization failed: "+err.Error())
+		ab.logger.Printf("AUTH_BRIDGE_ERROR action=login error=%q", err.Error())
+		return
+	}
+
+	ab.logger.Printf("AUTH_BRIDGE_LOGIN device_code_prefix=%s expires_in=%d",
+		truncate(authResp.DeviceCode, 12), authResp.ExpiresIn)
+
+	resp := map[string]interface{}{
+		"ok":               true,
+		"verification_url": authResp.VerificationUriComplete,
+		"user_code":        authResp.UserCode,
+		"device_code":      authResp.DeviceCode,
+		"expires_in":       authResp.ExpiresIn,
+		"interval":         authResp.Interval,
+	}
+	jsonOK(w, resp)
+}
+
+// handlePoll polls the device-flow token endpoint.
+// Binds the resulting feishu identity to the client on success.
+func (ab *authBridge) handlePoll(w http.ResponseWriter, r *http.Request, body []byte) {
+	var req struct {
+		DeviceCode string `json:"device_code"`
+	}
+	if err := json.Unmarshal(body, &req); err != nil || req.DeviceCode == "" {
+		jsonError(w, http.StatusBadRequest, "device_code is required")
+		return
+	}
+	clientID := parseClientID(body)
+
+	ctx, cancel := context.WithTimeout(r.Context(), 10*time.Minute)
+	defer cancel()
+
+	ab.mu.Lock()
+	if oldCancel, ok := ab.pendingPolls[req.DeviceCode]; ok {
+		oldCancel()
+	}
+	ab.pendingPolls[req.DeviceCode] = cancel
+	ab.mu.Unlock()
+
+	defer func() {
+		ab.mu.Lock()
+		delete(ab.pendingPolls, req.DeviceCode)
+		ab.mu.Unlock()
+	}()
+
+	result := larkauth.PollDeviceToken(
+		ctx, ab.httpCl, ab.appID, ab.appSecret, ab.brand,
+		req.DeviceCode, 5, 600, io.Discard,
+	)
+
+	if !result.OK {
+		resp := map[string]interface{}{
+			"ok":    false,
+			"error": result.Error,
+			"msg":   result.Message,
+		}
+		jsonOK(w, resp)
+		ab.logger.Printf("AUTH_BRIDGE_POLL_FAIL device_code_prefix=%s error=%q",
+			truncate(req.DeviceCode, 12), result.Message)
+		return
+	}
+
+	if result.Token == nil {
+		jsonError(w, http.StatusInternalServerError, "token response was nil")
+		return
+	}
+
+	now := time.Now().UnixMilli()
+	storedToken := &larkauth.StoredUAToken{
+		AppId:            ab.appID,
+		AccessToken:      result.Token.AccessToken,
+		RefreshToken:     result.Token.RefreshToken,
+		ExpiresAt:        now + int64(result.Token.ExpiresIn)*1000,
+		RefreshExpiresAt: now + int64(result.Token.RefreshExpiresIn)*1000,
+		Scope:            result.Token.Scope,
+		GrantedAt:        now,
+	}
+
+	ep := core.ResolveEndpoints(ab.brand)
+	openID, userName, err := fetchUserInfoDirect(ab.httpCl, ep.Open, result.Token.AccessToken)
+	if err != nil {
+		ab.logger.Printf("AUTH_BRIDGE_WARN action=user_info error=%q", err.Error())
+		jsonError(w, http.StatusBadGateway, "login succeeded but failed to get user info: "+err.Error())
+		return
+	}
+	storedToken.UserOpenId = openID
+
+	if err := larkauth.SetStoredToken(storedToken); err != nil {
+		jsonError(w, http.StatusInternalServerError, "failed to store token: "+err.Error())
+		return
+	}
+
+	if err := addUserToConfig(ab.appID, openID, userName); err != nil {
+		ab.logger.Printf("AUTH_BRIDGE_WARN action=sync_config error=%q", err.Error())
+	}
+
+	if clientID != "" {
+		ab.mu.Lock()
+		ab.userMap[clientID] = openID
+		ab.saveUserMap()
+		ab.mu.Unlock()
+		ab.logger.Printf("AUTH_BRIDGE_MAP client=%s -> feishu=%s (%s)",
+			clientID, openID, userName)
+	}
+
+	ab.logger.Printf("AUTH_BRIDGE_LOGIN_OK user=%s open_id=%s scope_count=%d client=%s",
+		userName, openID, len(strings.Fields(result.Token.Scope)), clientID)
+
+	resp := map[string]interface{}{
+		"ok":        true,
+		"user_name": userName,
+		"open_id":   openID,
+	}
+	jsonOK(w, resp)
+}
+
+// handleStatus returns current auth status.
+// Accepts client_id in body for client-specific mapping.
+func (ab *authBridge) handleStatus(w http.ResponseWriter, _ *http.Request, body []byte) {
+	clientID := parseClientID(body)
+
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		jsonError(w, http.StatusInternalServerError, "failed to load config: "+err.Error())
+		return
+	}
+
+	var users []map[string]interface{}
+	for _, app := range multi.Apps {
+		if app.AppId != ab.appID {
+			continue
+		}
+		for _, u := range app.Users {
+			stored := larkauth.GetStoredToken(ab.appID, u.UserOpenId)
+			status := "unknown"
+			if stored != nil {
+				status = larkauth.TokenStatus(stored)
+			}
+			users = append(users, map[string]interface{}{
+				"user_name":    u.UserName,
+				"user_open_id": u.UserOpenId,
+				"token_status": status,
+			})
+		}
+	}
+
+	resp := map[string]interface{}{
+		"ok":    true,
+		"users": users,
+	}
+
+	if clientID != "" {
+		ab.mu.Lock()
+		mappedOpenID := ab.userMap[clientID]
+		ab.mu.Unlock()
+
+		resp["client_id"] = clientID
+		resp["mapped_open_id"] = mappedOpenID
+		if mappedOpenID != "" {
+			stored := larkauth.GetStoredToken(ab.appID, mappedOpenID)
+			if stored != nil {
+				resp["mapped_status"] = larkauth.TokenStatus(stored)
+				for _, u := range users {
+					if u["user_open_id"] == mappedOpenID {
+						resp["mapped_user_name"] = u["user_name"]
+						break
+					}
+				}
+			} else {
+				resp["mapped_status"] = "no_token"
+			}
+		} else {
+			resp["mapped_status"] = "not_mapped"
+		}
+	}
+
+	jsonOK(w, resp)
+}
+
+// resolveUserTokenByClient resolves a UAT for a specific client environment.
+// Returns an error if the client has no user mapping — the user must
+// run the login flow first. No fallback to other users' tokens.
+func (ab *authBridge) resolveUserTokenByClient(clientName string) (string, error) {
+	ab.mu.Lock()
+	openID := ab.userMap[clientName]
+	ab.mu.Unlock()
+
+	if openID == "" {
+		ab.logger.Printf("AUTH_BRIDGE_REJECT_NO_MAPPING client=%s", clientName)
+		return "", fmt.Errorf("client %q has no user mapping; run the login flow to authorize", clientName)
+	}
+
+	ab.logger.Printf("AUTH_BRIDGE_RESOLVE client=%s feishu=%s", clientName, openID)
+
+	opts := larkauth.UATCallOptions{
+		UserOpenId: openID,
+		AppId:      ab.appID,
+		AppSecret:  ab.appSecret,
+		Domain:     ab.brand,
+	}
+	token, err := larkauth.GetValidAccessToken(ab.httpCl, opts)
+	if err != nil {
+		return "", fmt.Errorf("failed to resolve token for user %s: %v", openID, err)
+	}
+	return token, nil
+}
+
+func addUserToConfig(appID, openID, userName string) error {
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		return err
+	}
+	for i := range multi.Apps {
+		if multi.Apps[i].AppId != appID {
+			continue
+		}
+		found := false
+		for j := range multi.Apps[i].Users {
+			if multi.Apps[i].Users[j].UserOpenId == openID {
+				multi.Apps[i].Users[j].UserName = userName
+				found = true
+				break
+			}
+		}
+		if !found {
+			multi.Apps[i].Users = append(multi.Apps[i].Users, core.AppUser{
+				UserOpenId: openID,
+				UserName:   userName,
+			})
+		}
+		return core.SaveMultiAppConfig(multi)
+	}
+	return fmt.Errorf("app %s not found in config", appID)
+}
+
+func fetchUserInfoDirect(client *http.Client, openBase, accessToken string) (openID, name string, err error) {
+	u := openBase + "/open-apis/authen/v1/user_info"
+	req, err := http.NewRequest("GET", u, nil)
+	if err != nil {
+		return "", "", err
+	}
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", "", err
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", "", err
+	}
+
+	var result struct {
+		Code int `json:"code"`
+		Data struct {
+			OpenID string `json:"open_id"`
+			Name   string `json:"name"`
+		} `json:"data"`
+		Msg string `json:"msg"`
+	}
+	if err := json.Unmarshal(respBody, &result); err != nil {
+		return "", "", fmt.Errorf("parse user_info response: %w", err)
+	}
+	if result.Code != 0 {
+		return "", "", fmt.Errorf("user_info API error: [%d] %s", result.Code, result.Msg)
+	}
+	return result.Data.OpenID, result.Data.Name, nil
+}
+
+func jsonOK(w http.ResponseWriter, data interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(data)
+}
+
+func jsonError(w http.ResponseWriter, code int, msg string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(code)
+	json.NewEncoder(w).Encode(map[string]interface{}{
+		"ok":    false,
+		"error": msg,
+	})
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "..."
+}
+
+func loadCachedScopes() string {
+	configDir := os.Getenv("LARKSUITE_CLI_CONFIG_DIR")
+	if configDir == "" {
+		return ""
+	}
+	dir := filepath.Join(configDir, "cache", "auth_login_scopes")
+	entries, err := vfs.ReadDir(dir)
+	if err != nil {
+		return ""
+	}
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".json") {
+			continue
+		}
+		data, err := vfs.ReadFile(filepath.Join(dir, e.Name()))
+		if err != nil {
+			continue
+		}
+		var doc struct {
+			RequestedScope string `json:"requested_scope"`
+		}
+		if json.Unmarshal(data, &doc) == nil && doc.RequestedScope != "" {
+			return doc.RequestedScope
+		}
+	}
+	return ""
+}

sidecar/server-multi-tenant-demo/forward.go

@@ -0,0 +1,51 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar_multi_tenant_demo
+
+package main
+
+import (
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/larksuite/cli/sidecar"
+)
+
+// newForwardClient creates an HTTP client for forwarding requests to the
+// Lark API. It strips Authorization on cross-host redirects and disables
+// proxy to prevent real tokens from leaking through environment proxies.
+func newForwardClient() *http.Client {
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+	transport.Proxy = nil // never proxy the trusted hop
+	return &http.Client{
+		Transport: transport,
+		Timeout:   30 * time.Second,
+		CheckRedirect: func(req *http.Request, via []*http.Request) error {
+			if len(via) >= 10 {
+				return fmt.Errorf("too many redirects")
+			}
+			if len(via) > 0 && req.URL.Host != via[0].URL.Host {
+				req.Header.Del("Authorization")
+				req.Header.Del(sidecar.HeaderMCPUAT)
+				req.Header.Del(sidecar.HeaderMCPTAT)
+			}
+			return nil
+		},
+	}
+}
+
+// isProxyHeader returns true for headers specific to the sidecar protocol.
+func isProxyHeader(key string) bool {
+	switch http.CanonicalHeaderKey(key) {
+	case http.CanonicalHeaderKey(sidecar.HeaderProxyTarget),
+		http.CanonicalHeaderKey(sidecar.HeaderProxyIdentity),
+		http.CanonicalHeaderKey(sidecar.HeaderProxySignature),
+		http.CanonicalHeaderKey(sidecar.HeaderProxyTimestamp),
+		http.CanonicalHeaderKey(sidecar.HeaderBodySHA256),
+		http.CanonicalHeaderKey(sidecar.HeaderProxyAuthHeader):
+		return true
+	}
+	return false
+}

sidecar/server-multi-tenant-demo/handler.go

@@ -0,0 +1,372 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar_multi_tenant_demo
+
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"net/url"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/vfs"
+	"github.com/larksuite/cli/sidecar"
+)
+
+// proxyHandler handles HTTP requests from sandbox CLI instances.
+type proxyHandler struct {
+	key          []byte
+	cred         *credential.CredentialProvider
+	appID        string
+	brand        core.LarkBrand
+	logger       *log.Logger
+	forwardCl    *http.Client
+	allowedHosts map[string]bool // target host allowlist derived from brand
+	allowedIDs   map[string]bool // identity allowlist derived from strict mode
+	authBridge   *authBridge
+
+	// Per-client key isolation: keyHex → clientName.
+	// Data-plane requests are signed with a client-specific key;
+	// the matched key determines which client (and thus which user
+	// token) to use. Protected by ckMu.
+	ckMu       sync.RWMutex
+	clientKeys map[string]clientKeyEntry
+	keysDir    string // directory to scan for *.key files (excluding proxy.key)
+}
+
+type clientKeyEntry struct {
+	key        []byte
+	clientName string
+}
+
+// loadClientKeys scans keysDir for *.key files (excluding the shared
+// proxy.key) and populates the clientKeys map. The filename stem (without
+// .key) becomes the client identity. No naming convention is enforced.
+// Safe to call multiple times (e.g. on cache miss).
+func (h *proxyHandler) loadClientKeys() {
+	if h.keysDir == "" {
+		return
+	}
+	entries, err := vfs.ReadDir(h.keysDir)
+	if err != nil {
+		h.logger.Printf("KEYS_SCAN_ERROR dir=%s error=%q", h.keysDir, err.Error())
+		return
+	}
+
+	sharedKeyHex := string(h.key)
+
+	newKeys := make(map[string]clientKeyEntry)
+	for _, e := range entries {
+		name := e.Name()
+		if e.IsDir() || !strings.HasSuffix(name, ".key") {
+			continue
+		}
+		clientName := strings.TrimSuffix(name, ".key")
+		if clientName == "" || clientName == "proxy" {
+			continue
+		}
+		data, err := vfs.ReadFile(filepath.Join(h.keysDir, name))
+		if err != nil {
+			continue
+		}
+		keyHex := strings.TrimSpace(string(data))
+		if len(keyHex) != 64 {
+			h.logger.Printf("KEYS_SCAN_SKIP file=%s reason=\"key length %d, expected 64\"", name, len(keyHex))
+			continue
+		}
+		if keyHex == sharedKeyHex {
+			h.logger.Printf("KEYS_SCAN_SKIP file=%s reason=\"collides with shared proxy key\"", name)
+			continue
+		}
+		if existing, ok := newKeys[keyHex]; ok {
+			h.logger.Printf("KEYS_SCAN_SKIP file=%s reason=\"duplicate key, already loaded for client %s\"", name, existing.clientName)
+			continue
+		}
+		newKeys[keyHex] = clientKeyEntry{key: []byte(keyHex), clientName: clientName}
+	}
+
+	h.ckMu.Lock()
+	h.clientKeys = newKeys
+	h.ckMu.Unlock()
+
+	if len(newKeys) > 0 {
+		names := make([]string, 0, len(newKeys))
+		for _, e := range newKeys {
+			names = append(names, e.clientName)
+		}
+		h.logger.Printf("KEYS_LOADED count=%d clients=%v", len(newKeys), names)
+	}
+}
+
+// verifyWithClientKeys tries each client key to verify the HMAC.
+// Returns the client name on success, or empty string + error if none match.
+func (h *proxyHandler) verifyWithClientKeys(cr sidecar.CanonicalRequest, signature string) (string, error) {
+	h.ckMu.RLock()
+	keys := h.clientKeys
+	h.ckMu.RUnlock()
+
+	for _, entry := range keys {
+		if err := sidecar.Verify(entry.key, cr, signature); err == nil {
+			return entry.clientName, nil
+		}
+	}
+
+	// Cache miss: rescan keys directory and retry once
+	h.loadClientKeys()
+
+	h.ckMu.RLock()
+	keys = h.clientKeys
+	h.ckMu.RUnlock()
+
+	for _, entry := range keys {
+		if err := sidecar.Verify(entry.key, cr, signature); err == nil {
+			return entry.clientName, nil
+		}
+	}
+
+	return "", fmt.Errorf("no client key matched")
+}
+
+// allowedAuthHeaders lists the only header names the sidecar will inject real
+// tokens into.
+var allowedAuthHeaders = map[string]bool{
+	"Authorization":      true,
+	sidecar.HeaderMCPUAT: true,
+	sidecar.HeaderMCPTAT: true,
+}
+
+func (h *proxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	// Route management endpoints to authBridge (different HMAC scheme)
+	if len(r.URL.Path) > 10 && r.URL.Path[:10] == "/_sidecar/" {
+		if h.authBridge != nil {
+			h.authBridge.ServeHTTP(w, r)
+		} else {
+			http.Error(w, "auth bridge not configured", http.StatusNotImplemented)
+		}
+		return
+	}
+
+	start := time.Now()
+
+	// 0. Check protocol version
+	version := r.Header.Get(sidecar.HeaderProxyVersion)
+	if version != sidecar.ProtocolV1 {
+		http.Error(w, "unsupported "+sidecar.HeaderProxyVersion+": "+version, http.StatusBadRequest)
+		return
+	}
+
+	// 1. Verify timestamp
+	ts := r.Header.Get(sidecar.HeaderProxyTimestamp)
+	if ts == "" {
+		http.Error(w, "missing "+sidecar.HeaderProxyTimestamp, http.StatusBadRequest)
+		return
+	}
+
+	// 2. Read body and verify SHA256
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, "failed to read request body", http.StatusBadRequest)
+		return
+	}
+	r.Body.Close()
+
+	claimedSHA := r.Header.Get(sidecar.HeaderBodySHA256)
+	if claimedSHA == "" {
+		http.Error(w, "missing "+sidecar.HeaderBodySHA256, http.StatusBadRequest)
+		return
+	}
+	actualSHA := sidecar.BodySHA256(body)
+	if claimedSHA != actualSHA {
+		http.Error(w, "body SHA256 mismatch", http.StatusBadRequest)
+		return
+	}
+
+	// 3. Verify HMAC signature
+	target := r.Header.Get(sidecar.HeaderProxyTarget)
+	if target == "" {
+		http.Error(w, "missing "+sidecar.HeaderProxyTarget, http.StatusBadRequest)
+		return
+	}
+
+	pathAndQuery := r.URL.RequestURI()
+	targetHost, err := parseTarget(target)
+	if err != nil {
+		http.Error(w, "invalid "+sidecar.HeaderProxyTarget+": "+err.Error(), http.StatusForbidden)
+		h.logger.Printf("REJECT method=%s path=%s reason=%q", r.Method, sanitizePath(pathAndQuery), sanitizeError(err))
+		return
+	}
+
+	identity := r.Header.Get(sidecar.HeaderProxyIdentity)
+	if identity == "" {
+		http.Error(w, "missing "+sidecar.HeaderProxyIdentity, http.StatusBadRequest)
+		return
+	}
+	authHeader := r.Header.Get(sidecar.HeaderProxyAuthHeader)
+	if authHeader == "" {
+		http.Error(w, "missing "+sidecar.HeaderProxyAuthHeader, http.StatusBadRequest)
+		return
+	}
+
+	signature := r.Header.Get(sidecar.HeaderProxySignature)
+	cr := sidecar.CanonicalRequest{
+		Version:      version,
+		Method:       r.Method,
+		Host:         targetHost,
+		PathAndQuery: pathAndQuery,
+		BodySHA256:   claimedSHA,
+		Timestamp:    ts,
+		Identity:     identity,
+		AuthHeader:   authHeader,
+	}
+
+	// Try the primary (shared) key first, then per-client keys.
+	// matchedClient is empty when using the shared key.
+	var matchedClient string
+	if err := sidecar.Verify(h.key, cr, signature); err != nil {
+		client, clientErr := h.verifyWithClientKeys(cr, signature)
+		if clientErr != nil {
+			http.Error(w, "HMAC verification failed: "+err.Error(), http.StatusUnauthorized)
+			h.logger.Printf("REJECT method=%s path=%s reason=%q", r.Method, sanitizePath(pathAndQuery), "no key matched")
+			return
+		}
+		matchedClient = client
+	}
+
+	// 4. Validate target host against allowlist
+	if !h.allowedHosts[targetHost] {
+		http.Error(w, "target host not allowed: "+targetHost, http.StatusForbidden)
+		h.logger.Printf("REJECT method=%s path=%s reason=\"target host %s not in allowlist\"", r.Method, sanitizePath(pathAndQuery), targetHost)
+		return
+	}
+
+	// 5. Validate identity
+	if !h.allowedIDs[identity] {
+		http.Error(w, "identity not allowed: "+identity, http.StatusForbidden)
+		h.logger.Printf("REJECT method=%s path=%s reason=\"identity %s not allowed by strict mode\"", r.Method, sanitizePath(pathAndQuery), identity)
+		return
+	}
+
+	// 5.5 Validate auth-header
+	if !allowedAuthHeaders[authHeader] {
+		http.Error(w, "auth-header not allowed: "+authHeader, http.StatusForbidden)
+		h.logger.Printf("REJECT method=%s path=%s reason=\"auth-header %s not in allowlist\"", r.Method, sanitizePath(pathAndQuery), authHeader)
+		return
+	}
+
+	// 6. Resolve real token
+	// UAT (user identity): per-client isolation via matched PROXY_KEY.
+	// TAT (bot identity): shared credential provider (app-level).
+	var resolvedToken string
+	if identity == sidecar.IdentityUser && h.authBridge != nil {
+		token, err := h.authBridge.resolveUserTokenByClient(matchedClient)
+		if err != nil {
+			http.Error(w, "failed to resolve user token: "+err.Error(), http.StatusInternalServerError)
+			h.logger.Printf("TOKEN_ERROR method=%s path=%s identity=%s client=%s error=%q",
+				r.Method, sanitizePath(pathAndQuery), identity, matchedClient, sanitizeError(err))
+			return
+		}
+		resolvedToken = token
+	} else {
+		tokenResult, err := h.cred.ResolveToken(r.Context(), credential.TokenSpec{
+			Type:  credential.TokenTypeTAT,
+			AppID: h.appID,
+		})
+		if err != nil {
+			http.Error(w, "failed to resolve token: "+err.Error(), http.StatusInternalServerError)
+			h.logger.Printf("TOKEN_ERROR method=%s path=%s identity=%s error=%q", r.Method, sanitizePath(pathAndQuery), identity, sanitizeError(err))
+			return
+		}
+		resolvedToken = tokenResult.Token
+	}
+
+	// 7. Build forwarding request
+	forwardURL := "https://" + targetHost + pathAndQuery
+	forwardReq, err := http.NewRequestWithContext(r.Context(), r.Method, forwardURL, bytes.NewReader(body))
+	if err != nil {
+		http.Error(w, "failed to create forward request", http.StatusInternalServerError)
+		return
+	}
+
+	for k, vs := range r.Header {
+		if isProxyHeader(k) {
+			continue
+		}
+		for _, v := range vs {
+			forwardReq.Header.Add(k, v)
+		}
+	}
+
+	forwardReq.Header.Del("Authorization")
+	forwardReq.Header.Del(sidecar.HeaderMCPUAT)
+	forwardReq.Header.Del(sidecar.HeaderMCPTAT)
+
+	// 8. Inject real token
+	if authHeader == "Authorization" {
+		forwardReq.Header.Set("Authorization", "Bearer "+resolvedToken)
+	} else {
+		forwardReq.Header.Set(authHeader, resolvedToken)
+	}
+
+	// 9. Forward request
+	resp, err := h.forwardCl.Do(forwardReq)
+	if err != nil {
+		http.Error(w, "forward request failed: "+err.Error(), http.StatusBadGateway)
+		h.logger.Printf("FORWARD_ERROR method=%s path=%s error=%q", r.Method, sanitizePath(pathAndQuery), sanitizeError(err))
+		return
+	}
+	defer resp.Body.Close()
+
+	// 10. Copy response back
+	for k, vs := range resp.Header {
+		for _, v := range vs {
+			w.Header().Add(k, v)
+		}
+	}
+	w.WriteHeader(resp.StatusCode)
+	io.Copy(w, resp.Body)
+
+	// 11. Audit log
+	clientTag := ""
+	if matchedClient != "" {
+		clientTag = " client=" + matchedClient
+	}
+	h.logger.Printf("FORWARD method=%s path=%s identity=%s status=%d duration=%s%s",
+		r.Method, sanitizePath(pathAndQuery), identity, resp.StatusCode, time.Since(start).Round(time.Millisecond), clientTag)
+}
+
+// parseTarget validates X-Lark-Proxy-Target and returns the host portion.
+func parseTarget(target string) (host string, err error) {
+	u, perr := url.Parse(target)
+	if perr != nil {
+		return "", fmt.Errorf("parse: %w", perr)
+	}
+	if u.Scheme != "https" {
+		return "", fmt.Errorf("scheme must be https, got %q", u.Scheme)
+	}
+	if u.Host == "" {
+		return "", fmt.Errorf("missing host")
+	}
+	if u.User != nil {
+		return "", fmt.Errorf("userinfo not allowed")
+	}
+	if u.Path != "" && u.Path != "/" {
+		return "", fmt.Errorf("path not allowed (got %q)", u.Path)
+	}
+	if u.RawQuery != "" {
+		return "", fmt.Errorf("query not allowed")
+	}
+	if u.Fragment != "" {
+		return "", fmt.Errorf("fragment not allowed")
+	}
+	return u.Host, nil
+}

sidecar/server-multi-tenant-demo/handler_test.go

@@ -0,0 +1,878 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar_multi_tenant_demo
+
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/sidecar"
+)
+
+// fakeExtProvider is a stub extcred.Provider for tests that returns a fixed token.
+type fakeExtProvider struct {
+	token string
+}
+
+func (f *fakeExtProvider) Name() string { return "fake" }
+func (f *fakeExtProvider) ResolveAccount(ctx context.Context) (*extcred.Account, error) {
+	return nil, nil
+}
+func (f *fakeExtProvider) ResolveToken(ctx context.Context, req extcred.TokenSpec) (*extcred.Token, error) {
+	return &extcred.Token{Value: f.token, Source: "fake"}, nil
+}
+
+func discardLogger() *log.Logger {
+	return log.New(io.Discard, "", 0)
+}
+
+func newTestHandler(key []byte) *proxyHandler {
+	return &proxyHandler{
+		key:       key,
+		logger:    discardLogger(),
+		forwardCl: &http.Client{},
+		allowedHosts: map[string]bool{
+			"open.feishu.cn":     true,
+			"accounts.feishu.cn": true,
+			"mcp.feishu.cn":      true,
+		},
+		allowedIDs: map[string]bool{
+			sidecar.IdentityUser: true,
+			sidecar.IdentityBot:  true,
+		},
+	}
+}
+
+// signedReq creates a properly signed request for testing handler logic past
+// HMAC verification. Identity defaults to bot and auth-header to
+// "Authorization"; callers can override by mutating the returned request
+// before calling ServeHTTP (and re-signing if they need the signature to
+// remain valid after the mutation).
+func signedReq(t *testing.T, key []byte, method, target, path string, body []byte) *http.Request {
+	t.Helper()
+	targetHost := target
+	if idx := strings.Index(target, "://"); idx >= 0 {
+		targetHost = target[idx+3:]
+	}
+	bodySHA := sidecar.BodySHA256(body)
+	ts := sidecar.Timestamp()
+	identity := sidecar.IdentityBot
+	authHeader := "Authorization"
+	sig := sidecar.Sign(key, sidecar.CanonicalRequest{
+		Version:      sidecar.ProtocolV1,
+		Method:       method,
+		Host:         targetHost,
+		PathAndQuery: path,
+		BodySHA256:   bodySHA,
+		Timestamp:    ts,
+		Identity:     identity,
+		AuthHeader:   authHeader,
+	})
+
+	var bodyReader io.Reader
+	if body != nil {
+		bodyReader = bytes.NewReader(body)
+	}
+	req := httptest.NewRequest(method, path, bodyReader)
+	req.Header.Set(sidecar.HeaderProxyVersion, sidecar.ProtocolV1)
+	req.Header.Set(sidecar.HeaderProxyTarget, target)
+	req.Header.Set(sidecar.HeaderProxyIdentity, identity)
+	req.Header.Set(sidecar.HeaderProxyAuthHeader, authHeader)
+	req.Header.Set(sidecar.HeaderBodySHA256, bodySHA)
+	req.Header.Set(sidecar.HeaderProxyTimestamp, ts)
+	req.Header.Set(sidecar.HeaderProxySignature, sig)
+	return req
+}
+
+// resign recomputes the HMAC signature over the request's current proxy
+// headers. Use this in tests that mutate a signed field (Identity,
+// AuthHeader, Target host, etc.) after calling signedReq.
+func resign(t *testing.T, key []byte, req *http.Request, body []byte) {
+	t.Helper()
+	target := req.Header.Get(sidecar.HeaderProxyTarget)
+	targetHost := target
+	if idx := strings.Index(target, "://"); idx >= 0 {
+		targetHost = target[idx+3:]
+	}
+	sig := sidecar.Sign(key, sidecar.CanonicalRequest{
+		Version:      req.Header.Get(sidecar.HeaderProxyVersion),
+		Method:       req.Method,
+		Host:         targetHost,
+		PathAndQuery: req.URL.RequestURI(),
+		BodySHA256:   sidecar.BodySHA256(body),
+		Timestamp:    req.Header.Get(sidecar.HeaderProxyTimestamp),
+		Identity:     req.Header.Get(sidecar.HeaderProxyIdentity),
+		AuthHeader:   req.Header.Get(sidecar.HeaderProxyAuthHeader),
+	})
+	req.Header.Set(sidecar.HeaderProxySignature, sig)
+}
+
+// TestProxyHandler_UnsupportedVersion verifies the handler rejects requests
+// whose HeaderProxyVersion is absent or set to an unknown value. Kept in
+// front so an old client paired with a newer server (or vice versa) surfaces
+// a clear 400 instead of a misleading HMAC mismatch downstream.
+func TestProxyHandler_UnsupportedVersion(t *testing.T) {
+	h := newTestHandler([]byte("key"))
+	for _, v := range []string{"", "v0", "v2"} {
+		req := httptest.NewRequest("GET", "/path", nil)
+		if v != "" {
+			req.Header.Set(sidecar.HeaderProxyVersion, v)
+		}
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, req)
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("version=%q: expected 400, got %d", v, w.Code)
+		}
+	}
+}
+
+func TestProxyHandler_MissingTimestamp(t *testing.T) {
+	h := newTestHandler([]byte("key"))
+	req := httptest.NewRequest("GET", "/path", nil)
+	req.Header.Set(sidecar.HeaderProxyVersion, sidecar.ProtocolV1)
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestProxyHandler_MissingBodySHA(t *testing.T) {
+	h := newTestHandler([]byte("key"))
+	req := httptest.NewRequest("GET", "/path", nil)
+	req.Header.Set(sidecar.HeaderProxyVersion, sidecar.ProtocolV1)
+	req.Header.Set(sidecar.HeaderProxyTimestamp, sidecar.Timestamp())
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestProxyHandler_BadHMAC(t *testing.T) {
+	h := newTestHandler([]byte("real-key"))
+
+	bodySHA := sidecar.BodySHA256(nil)
+	ts := sidecar.Timestamp()
+
+	req := httptest.NewRequest("GET", "/path", nil)
+	req.Header.Set(sidecar.HeaderProxyVersion, sidecar.ProtocolV1)
+	req.Header.Set(sidecar.HeaderProxyTarget, "https://open.feishu.cn")
+	req.Header.Set(sidecar.HeaderProxyIdentity, sidecar.IdentityBot)
+	req.Header.Set(sidecar.HeaderProxyAuthHeader, "Authorization")
+	req.Header.Set(sidecar.HeaderProxyTimestamp, ts)
+	req.Header.Set(sidecar.HeaderBodySHA256, bodySHA)
+	req.Header.Set(sidecar.HeaderProxySignature, "bad-signature")
+
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("expected 401, got %d", w.Code)
+	}
+}
+
+func TestProxyHandler_BodySHA256Mismatch(t *testing.T) {
+	h := newTestHandler([]byte("key"))
+
+	req := httptest.NewRequest("POST", "/path", bytes.NewReader([]byte("real body")))
+	req.Header.Set(sidecar.HeaderProxyVersion, sidecar.ProtocolV1)
+	req.Header.Set(sidecar.HeaderProxyTarget, "https://open.feishu.cn")
+	req.Header.Set(sidecar.HeaderProxyTimestamp, sidecar.Timestamp())
+	req.Header.Set(sidecar.HeaderBodySHA256, sidecar.BodySHA256([]byte("different body")))
+	req.Header.Set(sidecar.HeaderProxySignature, "whatever")
+
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestProxyHandler_TargetNotAllowed(t *testing.T) {
+	key := []byte("test-key")
+	h := newTestHandler(key)
+
+	req := signedReq(t, key, "GET", "https://evil.com", "/steal", nil)
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if w.Code != http.StatusForbidden {
+		t.Errorf("expected 403 for disallowed host, got %d", w.Code)
+	}
+}
+
+func TestProxyHandler_IdentityNotAllowed(t *testing.T) {
+	key := []byte("test-key")
+	h := newTestHandler(key)
+	// Restrict to bot only
+	h.allowedIDs = map[string]bool{sidecar.IdentityBot: true}
+
+	req := signedReq(t, key, "GET", "https://open.feishu.cn", "/open-apis/test", nil)
+	req.Header.Set(sidecar.HeaderProxyIdentity, sidecar.IdentityUser)
+	resign(t, key, req, nil) // identity is signed; must re-sign after mutation
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if w.Code != http.StatusForbidden {
+		t.Errorf("expected 403 for disallowed identity, got %d", w.Code)
+	}
+}
+
+// TestParseTarget covers the per-shape rejections directly, without the
+// surrounding HTTP plumbing.
+func TestParseTarget(t *testing.T) {
+	cases := []struct {
+		name    string
+		target  string
+		wantErr bool
+		wantSub string // expected fragment of the error message
+	}{
+		{name: "valid https", target: "https://open.feishu.cn", wantErr: false},
+		{name: "valid https trailing slash", target: "https://open.feishu.cn/", wantErr: false},
+		{name: "http downgrade", target: "http://open.feishu.cn", wantErr: true, wantSub: "scheme must be https"},
+		{name: "missing scheme", target: "open.feishu.cn", wantErr: true, wantSub: "scheme must be https"},
+		{name: "ftp scheme", target: "ftp://open.feishu.cn", wantErr: true, wantSub: "scheme must be https"},
+		{name: "empty", target: "", wantErr: true, wantSub: "scheme must be https"},
+		{name: "empty host", target: "https://", wantErr: true, wantSub: "missing host"},
+		{name: "with path", target: "https://open.feishu.cn/open-apis", wantErr: true, wantSub: "path not allowed"},
+		{name: "with query", target: "https://open.feishu.cn?a=1", wantErr: true, wantSub: "query not allowed"},
+		{name: "with fragment", target: "https://open.feishu.cn#frag", wantErr: true, wantSub: "fragment not allowed"},
+		{name: "with userinfo", target: "https://attacker:pw@open.feishu.cn", wantErr: true, wantSub: "userinfo not allowed"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			host, err := parseTarget(tc.target)
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got host=%q", host)
+				}
+				if tc.wantSub != "" && !strings.Contains(err.Error(), tc.wantSub) {
+					t.Errorf("error %q should contain %q", err.Error(), tc.wantSub)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if host != "open.feishu.cn" {
+				t.Errorf("host = %q, want %q", host, "open.feishu.cn")
+			}
+		})
+	}
+}
+
+// TestProxyHandler_RejectsNonHTTPSTarget verifies end-to-end that a
+// compromised sandbox holding a valid PROXY_KEY cannot coerce the sidecar
+// into forwarding real tokens over cleartext HTTP or to an unexpected path.
+// The check must fire before HMAC verification so that the request is
+// rejected even when the signature is technically valid.
+func TestProxyHandler_RejectsNonHTTPSTarget(t *testing.T) {
+	key := []byte("test-key")
+	h := newTestHandler(key)
+
+	cases := []struct {
+		name   string
+		target string
+	}{
+		{"http downgrade", "http://open.feishu.cn"},
+		{"bare hostname", "open.feishu.cn"},
+		{"ftp scheme", "ftp://open.feishu.cn"},
+		{"target with path", "https://open.feishu.cn/open-apis/evil"},
+		{"target with query", "https://open.feishu.cn?steal=1"},
+		{"target with userinfo", "https://attacker:pw@open.feishu.cn"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			// Sign with a valid key against the malicious target — proves the
+			// scheme/shape check is not bypassed by signature legitimacy.
+			req := signedReq(t, key, "GET", tc.target, "/open-apis/im/v1/chats", nil)
+			w := httptest.NewRecorder()
+			h.ServeHTTP(w, req)
+			if w.Code != http.StatusForbidden {
+				t.Errorf("expected 403 for target %q, got %d (body: %s)", tc.target, w.Code, w.Body.String())
+			}
+		})
+	}
+}
+
+// TestProxyHandler_RejectsIdentityReplay locks in C1 end-to-end: a captured
+// bot-signed request whose identity header is flipped to user (or vice versa)
+// must be rejected at HMAC verification, not silently served with the wrong
+// token type. Without identity in the canonical string this returns 200.
+func TestProxyHandler_RejectsIdentityReplay(t *testing.T) {
+	key := []byte("test-key")
+	h := newTestHandler(key)
+
+	req := signedReq(t, key, "GET", "https://open.feishu.cn", "/open-apis/test", nil)
+	// Attacker flips identity without touching signature.
+	req.Header.Set(sidecar.HeaderProxyIdentity, sidecar.IdentityUser)
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("identity replay must fail signature verify (got %d, want 401): %s",
+			w.Code, w.Body.String())
+	}
+}
+
+// TestProxyHandler_RejectsAuthHeaderReplay is the companion: flipping
+// X-Lark-Proxy-Auth-Header post-signature must invalidate the signature so
+// an attacker cannot redirect the injected token into an unintended header.
+func TestProxyHandler_RejectsAuthHeaderReplay(t *testing.T) {
+	key := []byte("test-key")
+	h := newTestHandler(key)
+
+	req := signedReq(t, key, "GET", "https://open.feishu.cn", "/open-apis/test", nil)
+	req.Header.Set(sidecar.HeaderProxyAuthHeader, "Cookie")
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Errorf("auth-header replay must fail signature verify (got %d, want 401): %s",
+			w.Code, w.Body.String())
+	}
+}
+
+// TestProxyHandler_RejectsAuthHeaderNotInAllowlist pins the auth-header
+// allowlist: even a correctly-signed request must be rejected if it asks
+// the sidecar to inject the real token into an unintended header (e.g.
+// Cookie / User-Agent / X-Forwarded-For). This closes the sidechannel
+// where the real token ends up in headers that Lark ignores for auth but
+// intermediate logs may capture.
+func TestProxyHandler_RejectsAuthHeaderNotInAllowlist(t *testing.T) {
+	key := []byte("test-key")
+	h := newTestHandler(key)
+
+	for _, bad := range []string{"Cookie", "User-Agent", "X-Forwarded-For", "X-Real-IP", "Set-Cookie"} {
+		t.Run(bad, func(t *testing.T) {
+			req := signedReq(t, key, "GET", "https://open.feishu.cn", "/open-apis/test", nil)
+			req.Header.Set(sidecar.HeaderProxyAuthHeader, bad)
+			resign(t, key, req, nil) // auth-header is signed; must re-sign after override
+			w := httptest.NewRecorder()
+			h.ServeHTTP(w, req)
+			if w.Code != http.StatusForbidden {
+				t.Errorf("authHeader=%q: expected 403, got %d (body: %s)",
+					bad, w.Code, w.Body.String())
+			}
+		})
+	}
+}
+
+// TestProxyHandler_AcceptsAllowedAuthHeaders confirms the three protocol
+// header names remain accepted after the allowlist is enforced. A local
+// TLS test server stands in for the upstream so the test is fully offline.
+func TestProxyHandler_AcceptsAllowedAuthHeaders(t *testing.T) {
+	key := []byte("test-key")
+
+	upstream := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer upstream.Close()
+	upstreamHost := strings.TrimPrefix(upstream.URL, "https://")
+
+	for _, good := range []string{"Authorization", sidecar.HeaderMCPUAT, sidecar.HeaderMCPTAT} {
+		t.Run(good, func(t *testing.T) {
+			cred := credential.NewCredentialProvider(
+				[]extcred.Provider{&fakeExtProvider{token: "real-token"}},
+				nil, nil, nil,
+			)
+			h := &proxyHandler{
+				key:          key,
+				cred:         cred,
+				appID:        "cli_test",
+				logger:       discardLogger(),
+				forwardCl:    upstream.Client(),
+				allowedHosts: map[string]bool{upstreamHost: true},
+				allowedIDs:   map[string]bool{sidecar.IdentityUser: true, sidecar.IdentityBot: true},
+			}
+
+			req := signedReq(t, key, "GET", "https://"+upstreamHost, "/open-apis/test", nil)
+			req.Header.Set(sidecar.HeaderProxyAuthHeader, good)
+			resign(t, key, req, nil)
+			w := httptest.NewRecorder()
+			h.ServeHTTP(w, req)
+			if w.Code != http.StatusOK {
+				t.Fatalf("authHeader=%q: expected 200, got %d body=%s", good, w.Code, w.Body.String())
+			}
+		})
+	}
+}
+
+func TestRun_RejectsSelfProxy(t *testing.T) {
+	t.Setenv(envvars.CliAuthProxy, "http://127.0.0.1:16384")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	keyPath := filepath.Join(t.TempDir(), "proxy.key")
+
+	err := run(context.Background(), "127.0.0.1:0", keyPath, "", "", "")
+	if err == nil {
+		t.Fatal("expected error when AUTH_PROXY is set")
+	}
+	if !strings.Contains(err.Error(), envvars.CliAuthProxy) {
+		t.Errorf("error should mention %s, got: %v", envvars.CliAuthProxy, err)
+	}
+}
+
+func TestForwardClient_RedirectStripsAuth(t *testing.T) {
+	redirectTarget := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if auth := r.Header.Get("Authorization"); auth != "" {
+			t.Errorf("Authorization leaked to redirect target: %s", auth)
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer redirectTarget.Close()
+
+	origin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, redirectTarget.URL+"/redirected", http.StatusFound)
+	}))
+	defer origin.Close()
+
+	client := newForwardClient()
+	req, _ := http.NewRequest("GET", origin.URL+"/start", nil)
+	req.Header.Set("Authorization", "Bearer real-token")
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp.Body.Close()
+}
+
+func TestForwardClient_RedirectStripsMCPHeaders(t *testing.T) {
+	redirectTarget := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if v := r.Header.Get(sidecar.HeaderMCPUAT); v != "" {
+			t.Errorf("X-Lark-MCP-UAT leaked to redirect target: %s", v)
+		}
+		if v := r.Header.Get(sidecar.HeaderMCPTAT); v != "" {
+			t.Errorf("X-Lark-MCP-TAT leaked to redirect target: %s", v)
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer redirectTarget.Close()
+
+	origin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, redirectTarget.URL+"/redirected", http.StatusFound)
+	}))
+	defer origin.Close()
+
+	client := newForwardClient()
+	req, _ := http.NewRequest("POST", origin.URL+"/mcp", nil)
+	req.Header.Set(sidecar.HeaderMCPUAT, "real-uat-token")
+	req.Header.Set(sidecar.HeaderMCPTAT, "real-tat-token")
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	resp.Body.Close()
+}
+
+// TestProxyHandler_StripsClientSuppliedAuthHeaders verifies that the sidecar
+// is the sole source of auth headers on the forwarded request. A malicious
+// sandbox client must not be able to smuggle an Authorization/MCP header that
+// rides along with the sidecar-injected real token.
+func TestProxyHandler_StripsClientSuppliedAuthHeaders(t *testing.T) {
+	const realToken = "real-tenant-access-token"
+
+	// Capture what the upstream receives after sidecar forwarding.
+	// TLS is required because parseTarget rejects non-https targets.
+	var captured http.Header
+	upstream := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		captured = r.Header.Clone()
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer upstream.Close()
+
+	// Strip "https://" prefix to get host:port (matches what the handler sees).
+	upstreamHost := strings.TrimPrefix(upstream.URL, "https://")
+
+	cred := credential.NewCredentialProvider(
+		[]extcred.Provider{&fakeExtProvider{token: realToken}},
+		nil, nil, nil,
+	)
+
+	key := []byte("test-key")
+	h := &proxyHandler{
+		key:          key,
+		cred:         cred,
+		appID:        "cli_test",
+		logger:       discardLogger(),
+		forwardCl:    upstream.Client(), // trusts the httptest CA
+		allowedHosts: map[string]bool{upstreamHost: true},
+		allowedIDs:   map[string]bool{sidecar.IdentityUser: true, sidecar.IdentityBot: true},
+	}
+
+	cases := []struct {
+		name                string
+		proxyAuthHeader     string // which header sidecar should inject into
+		wantInjectedHeader  string // the header the real token ends up in
+		wantInjectedValue   string
+		wantStrippedHeaders []string
+	}{
+		{
+			name:                "inject Authorization, strip MCP attacker headers",
+			proxyAuthHeader:     "Authorization",
+			wantInjectedHeader:  "Authorization",
+			wantInjectedValue:   "Bearer " + realToken,
+			wantStrippedHeaders: []string{sidecar.HeaderMCPUAT, sidecar.HeaderMCPTAT},
+		},
+		{
+			name:                "inject MCP UAT, strip Authorization attacker header",
+			proxyAuthHeader:     sidecar.HeaderMCPUAT,
+			wantInjectedHeader:  sidecar.HeaderMCPUAT,
+			wantInjectedValue:   realToken,
+			wantStrippedHeaders: []string{"Authorization", sidecar.HeaderMCPTAT},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			captured = nil
+
+			req := signedReq(t, key, "GET", "https://"+upstreamHost, "/open-apis/test", nil)
+			req.Header.Set(sidecar.HeaderProxyAuthHeader, tc.proxyAuthHeader)
+			resign(t, key, req, nil) // auth-header is signed; re-sign after override
+
+			// Attacker smuggles all three possible auth headers with bogus values.
+			req.Header.Set("Authorization", "Bearer attacker-token")
+			req.Header.Set(sidecar.HeaderMCPUAT, "attacker-uat")
+			req.Header.Set(sidecar.HeaderMCPTAT, "attacker-tat")
+
+			// Non-auth headers should still pass through.
+			req.Header.Set("X-Custom-Header", "keep-me")
+
+			w := httptest.NewRecorder()
+			h.ServeHTTP(w, req)
+
+			if w.Code != http.StatusOK {
+				t.Fatalf("expected 200 from upstream, got %d; body=%s", w.Code, w.Body.String())
+			}
+			if captured == nil {
+				t.Fatal("upstream handler was not invoked")
+			}
+
+			// Injected header contains the real token (not the attacker value).
+			if got := captured.Get(tc.wantInjectedHeader); got != tc.wantInjectedValue {
+				t.Errorf("%s = %q, want %q", tc.wantInjectedHeader, got, tc.wantInjectedValue)
+			}
+
+			// All other auth headers must be stripped.
+			for _, h := range tc.wantStrippedHeaders {
+				if got := captured.Get(h); got != "" {
+					t.Errorf("%s should be stripped, got %q", h, got)
+				}
+			}
+
+			// Non-auth headers still forwarded.
+			if got := captured.Get("X-Custom-Header"); got != "keep-me" {
+				t.Errorf("X-Custom-Header = %q, want %q", got, "keep-me")
+			}
+		})
+	}
+}
+
+func TestBuildAllowedHosts(t *testing.T) {
+	feishu := core.Endpoints{
+		Open: "https://open.feishu.cn", Accounts: "https://accounts.feishu.cn", MCP: "https://mcp.feishu.cn",
+	}
+	lark := core.Endpoints{
+		Open: "https://open.larksuite.com", Accounts: "https://accounts.larksuite.com", MCP: "https://mcp.larksuite.com",
+	}
+	hosts := buildAllowedHosts(feishu, lark)
+	// feishu hosts
+	if !hosts["open.feishu.cn"] {
+		t.Error("expected open.feishu.cn in allowlist")
+	}
+	if !hosts["mcp.feishu.cn"] {
+		t.Error("expected mcp.feishu.cn in allowlist")
+	}
+	// lark hosts
+	if !hosts["open.larksuite.com"] {
+		t.Error("expected open.larksuite.com in allowlist")
+	}
+	if !hosts["mcp.larksuite.com"] {
+		t.Error("expected mcp.larksuite.com in allowlist")
+	}
+	// evil host
+	if hosts["evil.com"] {
+		t.Error("evil.com should not be in allowlist")
+	}
+}
+
+func TestSanitizePath(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"/open-apis/im/v1/messages?receive_id_type=chat_id", "/open-apis/im/v1/messages"},
+		{"/open-apis/calendar/v4/events", "/open-apis/calendar/v4/events"},
+		{"/open-apis/docx/v1/documents/doxcnABCD1234/blocks", "/open-apis/docx/v1/documents/:id/blocks"},
+		{"/open-apis/im/v1/chats/oc_abcdef12345678/members", "/open-apis/im/v1/chats/:id/members"},
+		{"/path?secret=abc", "/path"},
+	}
+	for _, tt := range tests {
+		if got := sanitizePath(tt.input); got != tt.want {
+			t.Errorf("sanitizePath(%q) = %q, want %q", tt.input, got, tt.want)
+		}
+	}
+}
+
+func TestLooksLikeID(t *testing.T) {
+	tests := []struct {
+		seg  string
+		want bool
+	}{
+		{"doxcnABCD1234", true},     // doc token
+		{"oc_abcdef12345678", true}, // chat ID
+		{"v1", false},               // API version
+		{"messages", false},         // route keyword
+		{"open-apis", false},        // route prefix
+		{"ab1", false},              // too short
+	}
+	for _, tt := range tests {
+		if got := looksLikeID(tt.seg); got != tt.want {
+			t.Errorf("looksLikeID(%q) = %v, want %v", tt.seg, got, tt.want)
+		}
+	}
+}
+
+func TestSanitizeError(t *testing.T) {
+	short := fmt.Errorf("short error")
+	if got := sanitizeError(short); got != "short error" {
+		t.Errorf("got %q", got)
+	}
+
+	longMsg := make([]byte, 300)
+	for i := range longMsg {
+		longMsg[i] = 'x'
+	}
+	long := fmt.Errorf("%s", string(longMsg))
+	got := sanitizeError(long)
+	if len(got) > 210 {
+		t.Errorf("expected truncation, got %d chars", len(got))
+	}
+	if !bytes.HasSuffix([]byte(got), []byte("...")) {
+		t.Errorf("expected '...' suffix, got %q", got[len(got)-10:])
+	}
+}
+
+// ---------- Multi-tenant tests ----------
+
+func writeKeyFile(t *testing.T, dir, name, content string) {
+	t.Helper()
+	if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestLoadClientKeys_SkipsSharedKeyCollision(t *testing.T) {
+	dir := t.TempDir()
+	sharedKey := strings.Repeat("aa", 32) // 64 hex chars
+	aliceKey := strings.Repeat("bb", 32)
+
+	writeKeyFile(t, dir, "proxy.key", sharedKey)
+	writeKeyFile(t, dir, "alice.key", aliceKey)
+	writeKeyFile(t, dir, "evil.key", sharedKey) // same as shared key
+
+	var logBuf bytes.Buffer
+	h := &proxyHandler{
+		key:        []byte(sharedKey),
+		keysDir:    dir,
+		clientKeys: make(map[string]clientKeyEntry),
+		logger:     log.New(&logBuf, "", 0),
+	}
+	h.loadClientKeys()
+
+	h.ckMu.RLock()
+	defer h.ckMu.RUnlock()
+
+	if len(h.clientKeys) != 1 {
+		t.Fatalf("expected 1 client key (alice), got %d", len(h.clientKeys))
+	}
+	for _, entry := range h.clientKeys {
+		if entry.clientName != "alice" {
+			t.Errorf("expected client alice, got %s", entry.clientName)
+		}
+	}
+	if !strings.Contains(logBuf.String(), "KEYS_SCAN_SKIP") || !strings.Contains(logBuf.String(), "collides with shared proxy key") {
+		t.Errorf("expected KEYS_SCAN_SKIP log for shared key collision, got: %s", logBuf.String())
+	}
+}
+
+func TestLoadClientKeys_SkipsDuplicateKeyHex(t *testing.T) {
+	dir := t.TempDir()
+	sharedKey := strings.Repeat("aa", 32)
+	dupeKey := strings.Repeat("cc", 32)
+
+	writeKeyFile(t, dir, "proxy.key", sharedKey)
+	writeKeyFile(t, dir, "alice.key", dupeKey)
+	writeKeyFile(t, dir, "bob.key", dupeKey) // duplicate of alice
+
+	var logBuf bytes.Buffer
+	h := &proxyHandler{
+		key:        []byte(sharedKey),
+		keysDir:    dir,
+		clientKeys: make(map[string]clientKeyEntry),
+		logger:     log.New(&logBuf, "", 0),
+	}
+	h.loadClientKeys()
+
+	h.ckMu.RLock()
+	defer h.ckMu.RUnlock()
+
+	if len(h.clientKeys) != 1 {
+		t.Fatalf("expected 1 client key (first loaded), got %d", len(h.clientKeys))
+	}
+	if !strings.Contains(logBuf.String(), "KEYS_SCAN_SKIP") || !strings.Contains(logBuf.String(), "duplicate key") {
+		t.Errorf("expected KEYS_SCAN_SKIP log for duplicate key, got: %s", logBuf.String())
+	}
+}
+
+func TestLoadClientKeys_SkipsProxyAndNonKeyFiles(t *testing.T) {
+	dir := t.TempDir()
+	sharedKey := strings.Repeat("aa", 32)
+
+	writeKeyFile(t, dir, "proxy.key", sharedKey)
+	writeKeyFile(t, dir, "alice.key", strings.Repeat("bb", 32))
+	writeKeyFile(t, dir, "notes.txt", "not a key")
+	if err := os.MkdirAll(filepath.Join(dir, "subdir.key"), 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	var logBuf bytes.Buffer
+	h := &proxyHandler{
+		key:        []byte(sharedKey),
+		keysDir:    dir,
+		clientKeys: make(map[string]clientKeyEntry),
+		logger:     log.New(&logBuf, "", 0),
+	}
+	h.loadClientKeys()
+
+	h.ckMu.RLock()
+	defer h.ckMu.RUnlock()
+
+	if len(h.clientKeys) != 1 {
+		t.Fatalf("expected 1 client key (alice), got %d", len(h.clientKeys))
+	}
+}
+
+func TestVerifyWithClientKeys_MatchesCorrectClient(t *testing.T) {
+	dir := t.TempDir()
+	sharedKey := strings.Repeat("aa", 32)
+	aliceKey := strings.Repeat("bb", 32)
+	bobKey := strings.Repeat("cc", 32)
+
+	writeKeyFile(t, dir, "proxy.key", sharedKey)
+	writeKeyFile(t, dir, "alice.key", aliceKey)
+	writeKeyFile(t, dir, "bob.key", bobKey)
+
+	h := &proxyHandler{
+		key:        []byte(sharedKey),
+		keysDir:    dir,
+		clientKeys: make(map[string]clientKeyEntry),
+		logger:     discardLogger(),
+	}
+	h.loadClientKeys()
+
+	cr := sidecar.CanonicalRequest{
+		Version:      sidecar.ProtocolV1,
+		Method:       "GET",
+		Host:         "open.feishu.cn",
+		PathAndQuery: "/test",
+		BodySHA256:   sidecar.BodySHA256(nil),
+		Timestamp:    sidecar.Timestamp(),
+		Identity:     sidecar.IdentityBot,
+		AuthHeader:   "Authorization",
+	}
+
+	// Sign with alice's key
+	aliceSig := sidecar.Sign([]byte(aliceKey), cr)
+	client, err := h.verifyWithClientKeys(cr, aliceSig)
+	if err != nil {
+		t.Fatalf("expected alice key to verify, got error: %v", err)
+	}
+	if client != "alice" {
+		t.Errorf("expected client=alice, got %q", client)
+	}
+
+	// Sign with bob's key
+	bobSig := sidecar.Sign([]byte(bobKey), cr)
+	client, err = h.verifyWithClientKeys(cr, bobSig)
+	if err != nil {
+		t.Fatalf("expected bob key to verify, got error: %v", err)
+	}
+	if client != "bob" {
+		t.Errorf("expected client=bob, got %q", client)
+	}
+
+	// Sign with unknown key
+	unknownKey := strings.Repeat("dd", 32)
+	unknownSig := sidecar.Sign([]byte(unknownKey), cr)
+	client, err = h.verifyWithClientKeys(cr, unknownSig)
+	if err == nil {
+		t.Errorf("expected error for unknown key, got client=%q", client)
+	}
+	if client != "" {
+		t.Errorf("expected empty client for unknown key, got %q", client)
+	}
+}
+
+func TestUserMap_RoundTripPersistence(t *testing.T) {
+	dir := t.TempDir()
+	mapFile := filepath.Join(dir, "client_user_map.json")
+
+	ab := &authBridge{
+		userMap: make(map[string]string),
+		mapFile: mapFile,
+		logger:  discardLogger(),
+	}
+
+	// Initially empty
+	ab.loadUserMap()
+	if len(ab.userMap) != 0 {
+		t.Fatalf("expected empty map, got %v", ab.userMap)
+	}
+
+	// Populate and save
+	ab.userMap["alice"] = "ou_alice_open_id_123"
+	ab.userMap["bob"] = "ou_bob_open_id_456"
+	ab.saveUserMap()
+
+	// Verify file contents
+	data, err := os.ReadFile(mapFile)
+	if err != nil {
+		t.Fatalf("failed to read map file: %v", err)
+	}
+	var saved map[string]string
+	if err := json.Unmarshal(data, &saved); err != nil {
+		t.Fatalf("failed to parse saved map: %v", err)
+	}
+	if saved["alice"] != "ou_alice_open_id_123" || saved["bob"] != "ou_bob_open_id_456" {
+		t.Errorf("saved map mismatch: %v", saved)
+	}
+
+	// Create new instance and load — simulates restart
+	ab2 := &authBridge{
+		userMap: make(map[string]string),
+		mapFile: mapFile,
+		logger:  discardLogger(),
+	}
+	ab2.loadUserMap()
+
+	if ab2.userMap["alice"] != "ou_alice_open_id_123" {
+		t.Errorf("after reload, alice=%q, want ou_alice_open_id_123", ab2.userMap["alice"])
+	}
+	if ab2.userMap["bob"] != "ou_bob_open_id_456" {
+		t.Errorf("after reload, bob=%q, want ou_bob_open_id_456", ab2.userMap["bob"])
+	}
+}

sidecar/server-multi-tenant-demo/main.go

@@ -0,0 +1,195 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build authsidecar_multi_tenant_demo
+
+// Command sidecar-server-demo is a reference implementation of a sidecar
+// auth proxy server. It is NOT production-ready — integrators should
+// implement their own server conforming to the wire protocol defined in
+// github.com/larksuite/cli/sidecar.
+//
+// The demo reuses the lark-cli credential pipeline (keychain + config) to
+// resolve real tokens, so it only works on a machine that has been
+// configured with `lark-cli auth login`.
+package main
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"flag"
+	"fmt"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/internal/vfs"
+	"github.com/larksuite/cli/sidecar"
+)
+
+func main() {
+	listen := flag.String("listen", sidecar.DefaultListenAddr, "listen address (host:port)")
+	keyFile := flag.String("key-file", defaultKeyFile(), "path to write the HMAC key")
+	keysDir := flag.String("keys-dir", "", "directory containing per-client *.key files for identity isolation (defaults to key-file's parent dir)")
+	logFile := flag.String("log-file", "", "audit log file (stderr if empty)")
+	profile := flag.String("profile", "", "lark-cli profile name (empty = active profile)")
+	flag.Parse()
+
+	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer cancel()
+
+	if err := run(ctx, *listen, *keyFile, *keysDir, *logFile, *profile); err != nil {
+		fmt.Fprintln(os.Stderr, "error:", err)
+		os.Exit(1)
+	}
+}
+
+func defaultKeyFile() string {
+	if home, err := os.UserHomeDir(); err == nil {
+		return filepath.Join(home, ".lark-sidecar", "proxy.key")
+	}
+	return "/tmp/lark-sidecar/proxy.key"
+}
+
+func run(ctx context.Context, listen, keyFile, keysDir, logFile, profile string) error {
+	if v := os.Getenv(envvars.CliAuthProxy); v != "" {
+		return fmt.Errorf("%s is set in this environment (%s); unset it before starting the sidecar server", envvars.CliAuthProxy, v)
+	}
+	if listen == "" {
+		return fmt.Errorf("invalid --listen address: empty")
+	}
+
+	if _, err := validate.SafeInputPath(keyFile); err != nil {
+		return fmt.Errorf("invalid --key-file path: %w", err)
+	}
+	if logFile != "" {
+		if _, err := validate.SafeInputPath(logFile); err != nil {
+			return fmt.Errorf("invalid --log-file path: %w", err)
+		}
+	}
+	if keysDir != "" {
+		if _, err := validate.SafeInputPath(keysDir); err != nil {
+			return fmt.Errorf("invalid --keys-dir path: %w", err)
+		}
+	}
+
+	// Reuse existing key if present; generate a new one only on first run.
+	keyDir := filepath.Dir(keyFile)
+	if err := vfs.MkdirAll(keyDir, 0700); err != nil {
+		return fmt.Errorf("failed to create key directory: %v", err)
+	}
+
+	var keyHex string
+	if existing, err := vfs.ReadFile(keyFile); err == nil && len(strings.TrimSpace(string(existing))) == 64 {
+		keyHex = strings.TrimSpace(string(existing))
+	} else {
+		keyBytes := make([]byte, 32)
+		if _, err := rand.Read(keyBytes); err != nil {
+			return fmt.Errorf("failed to generate HMAC key: %v", err)
+		}
+		keyHex = hex.EncodeToString(keyBytes)
+		if err := vfs.WriteFile(keyFile, []byte(keyHex), 0600); err != nil {
+			return fmt.Errorf("failed to write key file: %v", err)
+		}
+	}
+
+	// Default keysDir to the parent directory of keyFile
+	if keysDir == "" {
+		keysDir = keyDir
+	}
+
+	// Audit logger
+	var auditLogger *log.Logger
+	if logFile != "" {
+		f, err := vfs.OpenFile(logFile, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0600)
+		if err != nil {
+			return fmt.Errorf("failed to open log file: %v", err)
+		}
+		defer f.Close()
+		auditLogger = log.New(f, "", log.LstdFlags)
+	} else {
+		auditLogger = log.New(os.Stderr, "[audit] ", log.LstdFlags)
+	}
+
+	factory := cmdutil.NewDefault(nil, cmdutil.InvocationContext{Profile: profile})
+	cfg, err := factory.Config()
+	if err != nil {
+		return fmt.Errorf("failed to load config: %v", err)
+	}
+
+	listener, err := net.Listen("tcp", listen)
+	if err != nil {
+		return fmt.Errorf("failed to listen on %s: %v", listen, err)
+	}
+	defer listener.Close()
+
+	allowedHosts := buildAllowedHosts(
+		core.ResolveEndpoints(core.BrandFeishu),
+		core.ResolveEndpoints(core.BrandLark),
+	)
+	allowedIDs := buildAllowedIdentities(cfg)
+
+	ab := newAuthBridge([]byte(keyHex), cfg.AppID, cfg.AppSecret, cfg.Brand, factory.Credential, auditLogger)
+
+	handler := &proxyHandler{
+		key:          []byte(keyHex),
+		cred:         factory.Credential,
+		appID:        cfg.AppID,
+		brand:        cfg.Brand,
+		logger:       auditLogger,
+		forwardCl:    newForwardClient(),
+		allowedHosts: allowedHosts,
+		allowedIDs:   allowedIDs,
+		authBridge:   ab,
+		keysDir:      keysDir,
+	}
+	handler.loadClientKeys()
+
+	server := &http.Server{
+		Handler:           handler,
+		ReadHeaderTimeout: 10 * time.Second,
+		ReadTimeout:       60 * time.Second,
+		IdleTimeout:       120 * time.Second,
+		MaxHeaderBytes:    1 << 20,
+	}
+
+	go func() {
+		<-ctx.Done()
+		auditLogger.Println("shutting down...")
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		if err := server.Shutdown(shutdownCtx); err != nil {
+			auditLogger.Printf("shutdown error: %v", err)
+		}
+	}()
+
+	keyPrefix := keyHex
+	if len(keyPrefix) > 8 {
+		keyPrefix = keyPrefix[:8]
+	}
+	proxyURL := "http://" + listen
+	fmt.Fprintf(os.Stderr, "Auth sidecar listening on %s\n", proxyURL)
+	fmt.Fprintf(os.Stderr, "HMAC key prefix: %s\n", keyPrefix)
+	fmt.Fprintf(os.Stderr, "Full key written to %s (mode 0600)\n", keyFile)
+	fmt.Fprintf(os.Stderr, "Client keys dir: %s\n", keysDir)
+	fmt.Fprintf(os.Stderr, "\nSet in sandbox:\n")
+	fmt.Fprintf(os.Stderr, "  export %s=%q\n", envvars.CliAuthProxy, proxyURL)
+	fmt.Fprintf(os.Stderr, "  export %s=\"<read from %s>\"\n", envvars.CliProxyKey, keyFile)
+	fmt.Fprintf(os.Stderr, "  export %s=%q\n", envvars.CliAppID, cfg.AppID)
+	fmt.Fprintf(os.Stderr, "  export %s=%q\n", envvars.CliBrand, string(cfg.Brand))
+
+	if err := server.Serve(listener); err != nil && err != http.ErrServerClosed {
+		return fmt.Errorf("sidecar server exited unexpectedly: %v", err)
+	}
+	return nil
+}

skill-template/domains/base.md

@@ -34,6 +34,7 @@
 
 - **Base token 口径统一**：无论 Shortcut 还是原生 API，都统一使用 `base_token`
 - **附件字段**：上传本地文件时只能走 `lark-cli base +record-upload-attachment`
+- **地理位置字段**：写入必须使用 `{lng,lat}`；读取、筛选和转文本等场景使用 `full_address` 字符串，筛选优先用包含匹配；只有公式能访问坐标
 - **能力边界**：当前 `base/v3` 原生 spec 以单表 / 单记录 / 视图筛选配置为主，批量写入和旧 `search` 场景优先走 unified Shortcut 组合能力
 - **视图重命名确认规则**：用户已经明确“把哪个视图改成什么名字”时，执行 `table.views patch` / 对应 shortcut 直接改名即可，不需要再补一句确认
 - **删除确认规则（记录 / 字段 / 表）**：执行 `table.records delete / table.fields delete / tables delete` 或对应 shortcut 时，如果用户已经明确要求删除且目标明确，可以直接执行；只有目标不明确时才先追问

skills/lark-apps/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: lark-apps
-description: "飞书妙搭应用（lark-cli apps）：把本地 HTML 文件或目录部署为可访问、可分享的妙搭应用（静态网站 / Web 页面），返回访问 URL；并提供应用创建、更新、列出、设置可用范围（specific 指定可见 / public 互联网公开 / tenant 企业全员）等管理能力。当用户说『用 HTML / 网页开发 PPT / 幻灯片 / 演示文稿 / 可演示的 demo』、『部署 / 发布 HTML / 静态网站 / 网页 / dist 目录』、『把 /xxx 中的 HTML 文件用 lark-cli 部署 / 发到妙搭』、『开发一个 xxx 并部署成可以分享的网站 / 可访问的链接 / 可分享 URL』、『生成一个可以发给别人看的 PPT / 页面 / demo』，或提到 妙搭 / miaoda / apps / app_id / 可用范围 / open-to-tenant / open-to-public 等关键词时使用。**部署策略：用户明示『部署 / 发布 / 分享 / 可访问 / 可分享 URL』时直接走 `apps +html-publish` 自动部署并返回 URL；用户只说『可演示 / 写一个 PPT / 做个 demo』等模糊意图时，HTML 写完后先询问『要部署到妙搭以便分享吗？』再决定。**"
+description: "把本地 HTML 文件或目录部署到飞书妙搭（Miaoda），生成一个公网可访问的应用及其链接（URL）。当用户要创建 HTML 或要把 HTML、静态网站或 Web demo 发布成公网可访问的链接 / 可分享链接、设置应用共享范围，或提到妙搭 / Miaoda 时使用。凡产出可独立访问的 HTML 产物都属本 skill 的潜在归宿，是否真要部署由 skill 内部协议判断。不用于：上传普通文件到云空间/云盘/云存储（用 lark-drive）、编辑飞书云文档内容（用 lark-doc）、创建飞书原生幻灯片 / 演示文稿（用 lark-slides）。"
 metadata:
   requires:
     bins: ["lark-cli"]
-  cliHelp: "lark-cli apps --help; lark-cli apps +create --help; lark-cli apps +html-publish --help; lark-cli apps +access-scope-set --help; lark-cli apps +update --help"
+  cliHelp: "lark-cli apps --help"
 ---
 
 # apps (v1)
@@ -16,6 +16,10 @@ lark-cli apps +html-publish     --app-id app_xxx --path ./dist
 lark-cli apps +access-scope-set --app-id app_xxx --scope tenant
 ```
 
+## 品牌可用性（先做）
+
+跑 `lark-cli apps --help`；若提示暂未支持，告诉用户敬请期待并停止。
+
 ## 前置条件 — 执行操作前必读
 
 **CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
@@ -24,6 +28,7 @@ lark-cli apps +access-scope-set --app-id app_xxx --scope tenant
 3. **更新应用元信息（`apps +update`）** → 必读 [`lark-apps-update.md`](references/lark-apps-update.md)（部分更新，未传字段不变）
 4. **发布 HTML / PPT / 静态网站（`apps +html-publish`）** → 必读 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)（`--path` 文件 vs 目录、tar.gz 打包不做过滤）
 5. **设置可用范围（`apps +access-scope-set`）** → 必读 [`lark-apps-access-scope-set.md`](references/lark-apps-access-scope-set.md)（specific / public / tenant 三态互斥校验、targets JSON 结构）
+6. **查看当前可用范围（`apps +access-scope-get`）** → 必读 [`lark-apps-access-scope-get.md`](references/lark-apps-access-scope-get.md)（响应 scope 枚举 `All` / `Tenant` / `Range` 与 CLI 的 `public` / `tenant` / `specific` 映射；含 jq 复制 scope 配置示例）
 
 **未读完以上文件就执行相应操作会导致参数选择错误、互斥违反或文件被错误打包。**
 
@@ -37,6 +42,11 @@ lark-cli apps +access-scope-set --app-id app_xxx --scope tenant
 lark-cli auth login --domain apps
 ```
 
+## 写 HTML 前的硬约束（避免 publish 阶段被拒）
+
+- **入口文件必须叫 `index.html`** — 妙搭以 `index.html` 作为应用入口；目录形态时根目录下要有 `index.html`，单文件形态时文件名就是 `index.html`。命名成 `app.html` / `demo.html` 等会被 `+html-publish` 直接拒绝
+- **`--path` 不能等于当前工作目录（`.` / cwd）** — 源码硬拒，避免误把 `.git` / `.env` / `node_modules` 一并打包并通过 share URL 公开。HTML 产物放进具体子目录（如 `./dist`、`./public`、`./<page-name>/`）或单文件路径
+
 ## 端到端流程（HTML / PPT / 静态网站发布）
 
 **第一步：判断用户意图是「明示部署」还是「仅演示」**：
@@ -85,4 +95,5 @@ Shortcut 是对常用操作的高级封装（`lark-cli apps +<verb> [flags]`）
 | [`+create`](references/lark-apps-create.md) | 创建妙搭应用（name / description / icon-url） |
 | [`+update`](references/lark-apps-update.md) | 部分更新应用名 / 描述（只发传入字段） |
 | [`+access-scope-set`](references/lark-apps-access-scope-set.md) | 设置应用可用范围（specific / public / tenant，三态互斥校验） |
+| [`+access-scope-get`](references/lark-apps-access-scope-get.md) | 查看应用当前可用范围（响应 scope 枚举 `All` / `Tenant` / `Range`；可作"备份 / 复制 scope 配置"前置读） |
 | [`+html-publish`](references/lark-apps-html-publish.md) | **把本地 HTML 文件 / 目录 / PPT / 静态网站部署为可分享的妙搭应用，返回访问 URL**（用户明示部署 / 分享时直接调；仅说"可演示"时先问用户是否要部署再调） |

skills/lark-base/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-base
-version: 1.2.0
+version: 1.2.1
 description: "当需要用 lark-cli 操作飞书多维表格（Base）时调用：搜索 Base、建表、字段管理、记录读写、记录分享链接、视图配置、历史查询，以及角色/表单/仪表盘管理/工作流；也适用于把旧的 +table / +field / +record 写法改成当前命令写法。涉及字段设计、公式字段、查找引用、跨表计算、行级派生指标、数据分析需求时也必须使用本 skill。"
 metadata:
   requires:
@@ -40,7 +40,7 @@ metadata:
 
 1. 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。
 2. Base 业务命令仅使用 `lark-cli base +...` 形式的 shortcut 命令。
-3. 如果输入是 Wiki 链接或 Wiki token，并且用户想读取/操作其中的 Base，先执行 `lark-cli wiki +node-get --token <wiki_url_or_token>`；当返回 `data.obj_type=bitable` 时，把 `data.obj_token` 当作 `--base-token`。不要把 URL 里的 `/wiki/{token}` 当成 Base token。
+3. 如果输入是 Wiki 链接或 Wiki token，并且用户想读取/操作其中的 Base，先执行 `lark-cli wiki +node-get --node-token <wiki_url_or_token>`；当返回 `data.obj_type=bitable` 时，把 `data.obj_token` 当作 `--base-token`。不要把 URL 里的 `/wiki/{token}` 当成 Base token。（旧的 `--token` flag 仍可用，但已 deprecated，会在 stderr 打印迁移提示。）
 4. 定位到命令后，先读该命令对应的 reference，再执行命令。
 5. 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，第一步不是 `base`，而是 `lark-cli drive +import --type bitable`；导入完成后再回到 `lark-cli base +...` 做表内操作。
 6. 不要在 Base 场景改走 `lark-cli api /open-apis/bitable/v1/...`。
@@ -216,6 +216,7 @@ metadata:
 |----------|------|-----------------------------------------------------------|------|
 | 存储字段 | 真实存用户输入的数据 | 可以 | 常见如文本、数字、日期、单选、多选、人员、关联 |
 | 附件字段 | 存储文件附件 | 不应直接按普通字段写 | 上传附件走 `+record-upload-attachment`；下载附件走 `+record-download-attachment`；删除附件走 `+record-remove-attachment` |
+| 地理位置字段 | 存储坐标并由平台解析地址 | 可以 | 写入必须使用 `{lng,lat}`；读取、筛选和转文本等场景使用 `full_address` 字符串；只有公式能访问坐标 |
 | 系统字段 | 平台自动维护 | 不可以 | 常见如创建时间、更新时间、创建人、修改人、自动编号 |
 | `formula` 字段 | 通过表达式计算 | 不可以 | 只读字段 |
 | `lookup` 字段 | 通过跨表规则查找引用 | 不可以 | 只读字段 |
@@ -230,6 +231,7 @@ metadata:
 | 读取原始记录明细 / 关键词检索 / 导出 | `+record-search / +record-list / +record-get` | 不要拿 `+data-query` 当取数命令 |
 | 上传附件到记录 | `+record-upload-attachment` | 不要用 `+record-upsert` / `+record-batch-*` 伪造附件值 |
 | 下载记录里的附件文件 | `+record-download-attachment --record-id <record_id> --output <dir>`，可加 `--file-token <file_token>` 只下指定附件 | Base 附件必须用这个命令下载；用其他下载入口可能失败 |
+| 写入地理位置 | `+record-upsert` / `+record-batch-*` 传 `{lng,lat}` | 不要把纯地址文本当成 CellValue |
 | 基于视图做筛选读取 | `+view-set-filter` + `+record-list` | 不要跳过视图筛选直接猜条件 |
 | 本地 Excel / CSV / `.base` 导入为 Base | `lark-cli drive +import --type bitable` | 不要误走 `+base-create`、`+table-create` 或 `+record-upsert` |
 
@@ -264,7 +266,7 @@ metadata:
 Wiki Base fast path:
 
 ```bash
-BASE_TOKEN="$(lark-cli wiki +node-get --as user --token "<wiki_url_or_token>" --jq '.data | select(.obj_type == "bitable") | .obj_token')"
+BASE_TOKEN="$(lark-cli wiki +node-get --as user --node-token "<wiki_url_or_token>" --jq '.data | select(.obj_type == "bitable") | .obj_token')"
 ```
 
 | `lark-cli wiki +node-get` 返回的 `data.obj_type` | 后续路线 | 说明 |
@@ -350,7 +352,7 @@ lark-cli auth login --domain base
 | `1254066` | 人员字段错误 | `[{ "id": "ou_xxx" }]` |
 | `1254045` | 字段名不存在 | 检查字段名（含空格、大小写） |
 | `1254015` | 字段值类型不匹配 | 先 `+field-list`，再按类型构造 |
-| `param baseToken is invalid` / `base_token invalid` | 把 wiki token、workspace token 或其他 token 当成了 `base_token` | 如果输入来自 `/wiki/...`，先用 `lark-cli wiki +node-get --token <wiki_url_or_token>` 取真实 `data.obj_token`；当 `data.obj_type=bitable` 时，用 `data.obj_token` 作为 `--base-token` 重试，不要改走 `bitable/v1` |
+| `param baseToken is invalid` / `base_token invalid` | 把 wiki token、workspace token 或其他 token 当成了 `base_token` | 如果输入来自 `/wiki/...`，先用 `lark-cli wiki +node-get --node-token <wiki_url_or_token>` 取真实 `data.obj_token`；当 `data.obj_type=bitable` 时，用 `data.obj_token` 作为 `--base-token` 重试，不要改走 `bitable/v1` |
 | `not found` 且用户给的是 wiki 链接 | 常见于把 wiki token 当成 base token | 优先回退检查 wiki 解析，而不是改走 `bitable/v1` |
 | formula / lookup 创建失败 | 指南未读或结构不合法 | 先读 `formula-field-guide.md` / `lookup-field-guide.md`，再按 guide 重建请求 |
 | `ignored_fields` / `READONLY` | 只读字段被当成可写字段，常见于系统字段、formula、lookup | 移除只读字段，只写存储字段；计算结果交给 formula / lookup / 系统字段自动产出 |

skills/lark-base/references/lark-base-cell-value.md

@@ -106,7 +106,7 @@
 
 ### 2.8 location
 
-用对象 `{lng, lat}`，两者都是数字；`lng` 是经度，`lat` 是纬度。
+写入对象必须使用 `{lng, lat}`，两者都是数字；`lng` 是经度，`lat` 是纬度。不需要手动传 `full_address`，平台会根据坐标解析地址。
 
 ```json
 {
@@ -117,6 +117,8 @@
 }
 ```
 
+读取、筛选、转文本等场景使用 `full_address` 字符串；只有公式能访问坐标。如果用户只给地址文本，先获取或确认坐标后再写入；不要把仅有地址文本直接当作 location CellValue。
+
 ### 2.9 attachment（不作为普通 CellValue 写入）
 
 - 追加附件：使用 `lark-cli base +record-upload-attachment --record-id <record_id> --field-id <field_id> --file <path>`；可重复 `--file` 一次追加多个附件，不能用普通记录操作接口写附件值。

skills/lark-base/references/lark-base-data-query.md

@@ -277,6 +277,7 @@ POST /open-apis/base/v3/bases/:base_token/data/query
 | `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
 
 > **不支持** `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual`：地理位置无自然顺序。
+> location 按 `full_address` 字符串筛选，不支持经纬度空间筛选；查城市/片区时优先用 `contains`，避免用 `is` 匹配短地址词。
 
 *`checkbox`*
 

skills/lark-base/references/lark-base-field-update.md

@@ -101,7 +101,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
 
 | 目标类型 | 允许的源类型 | 说明 |
 |------|------|------|
-| `text` | `number`、`select`、`datetime`、`created_at`、`updated_at`、`location`、`auto_number`、`checkbox` | 保留字符串表示；丢失原类型语义和结构化能力 |
+| `text` | `number`、`select`、`datetime`、`created_at`、`updated_at`、`location`（只保留 `full_address`）、`auto_number`、`checkbox` | 保留字符串表示；丢失原类型语义和结构化能力 |
 | `number` | `text`、`number`、`datetime`、`created_at`、`updated_at`、`checkbox` | 保留可解析的数字值；无法解析的值会变空，原文本格式会丢失 |
 | `datetime` | `text`、`number`、`datetime`、`created_at`、`updated_at` | 保留可解析的时间字符串和时间戳；无法解析的值会变空，原文本格式会丢失 |
 | `select` | `text -> select`、`number -> select`、`single select -> multi select` | 只有完全匹配目标选项名的值会转成对应选项；没匹配上的值会被丢弃 |

skills/lark-base/references/lark-base-shortcut-field-properties.md

@@ -464,6 +464,8 @@
 { "type": "location", "name": "位置" }
 ```
 
+写入必须使用 `{lng,lat}`。location 读回会包含 `full_address`；筛选和 `location -> text` 类型转换按 `full_address` 字符串处理，只有公式能访问坐标。
+
 ```json
 { "type": "checkbox", "name": "完成" }
 ```

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

@@ -30,7 +30,7 @@
 
 ## 3. value 写法
 
-### `text` / `location`
+### `text`
 
 用字符串：
 
@@ -38,6 +38,16 @@
 ["标题", "intersects", "发布"]
 ```
 
+### `location`
+
+location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度筛选；优先使用 `intersects` 做包含匹配，例如查深圳：
+
+```json
+["位置", "intersects", "深圳"]
+```
+
+不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
+
 ### `number` / `auto_number`
 
 用数字：

skills/lark-drive/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-drive
 version: 1.0.0
-description: "飞书云空间：管理云空间中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word/Markdown/Excel/CSV 以及 Base 快照（.base）导入为飞书在线云文档（docx、sheet、bitable）。当用户需要上传或下载文件、整理云空间目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base 时使用。"
+description: "飞书云空间（云盘/云存储）：管理云空间（云盘/云存储）中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word/Markdown/Excel/CSV 以及 Base 快照（.base）导入为飞书在线云文档（docx、sheet、bitable）。当用户需要上传或下载文件、整理云空间（云盘/云存储）目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base 时使用。\"云空间\"、\"云盘\"和\"云存储\"是同一概念，用户说\"云盘\"、\"云存储\"、\"网盘\"、\"我的空间\"时均路由到本 skill。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -12,18 +12,20 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
+> **术语说明：** 飞书云空间也常被称为"云盘"或"云存储"，三者指的是同一个产品，是飞书官方的云端文件存储与管理中心。
+
 > **导入分流规则：** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。
 
 ## 快速决策
 
-- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--mine`，实为 owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
+- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--mine`，实为 owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
 - 用户要比较原生 `.md` 文件的**历史版本差异**，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
 - 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
-- 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
+- 用户要在云空间（云盘/云存储）里新建文件夹，优先使用 `lark-cli drive +create-folder`。
 - 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 
@@ -120,7 +122,7 @@ Wiki Space (知识空间)
     └── obj_type: file/slides/mindnote
         └── obj_token (真实文档 token)
 
-Drive Folder (云空间文件夹)
+Drive Folder (云空间/云盘/云存储文件夹)
 └── File (文件/文档)
     └── file_token (直接使用)
 ```
@@ -256,30 +258,30 @@ lark-cli drive permission.members create \
 
 Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）。有 Shortcut 的操作优先使用。
 
-| Shortcut | 说明 |
-|----------|------|
-| [`+search`](references/lark-drive-search.md) | Search Lark docs, Wiki, and spreadsheet files with flat filter flags. Natural-language-friendly: `--edited-since`, `--mine`, `--doc-types`, etc. |
-| [`+upload`](references/lark-drive-upload.md) | Upload a local file to a Drive folder or wiki node |
-| [`+create-folder`](references/lark-drive-create-folder.md) | Create a Drive folder, optionally under a parent folder, with bot auto-grant support |
-| [`+download`](references/lark-drive-download.md) | Download a file from Drive to local |
+| Shortcut | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`+search`](references/lark-drive-search.md) | Search Lark docs, Wiki, and spreadsheet files with flat filter flags. Natural-language-friendly: `--edited-since`, `--mine`, `--doc-types`, etc.                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`+upload`](references/lark-drive-upload.md) | Upload a local file to a Drive folder or wiki node                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [`+create-folder`](references/lark-drive-create-folder.md) | Create a Drive folder, optionally under a parent folder, with bot auto-grant support                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| [`+download`](references/lark-drive-download.md) | Download a file from Drive to local                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | [`+status`](references/lark-drive-status.md) | Compare a local directory with a Drive folder by exact SHA-256 hash by default, or use `--quick` for a best-effort modified-time diff that skips remote downloads; reports `new_local` / `new_remote` / `modified` / `unchanged` plus `detection=exact` or `detection=quick`. Duplicate remote `rel_path` conflicts fail fast with `error.type=duplicate_remote_path` and list every conflicting entry; do not proceed as if one was chosen. `--local-dir` 必须是 cwd 内的相对路径，越界路径 CLI 会直接拒绝；目标在 cwd 外时引导用户切换 agent 工作目录，不要私自 `cd` 绕过。 |
-| [`+pull`](references/lark-drive-pull.md) | File-level Drive → local mirror. Duplicate remote `rel_path` conflicts fail by default; for duplicate files, `rename` downloads all copies with stable hashed suffixes, while `newest` / `oldest` pick one. `--if-exists` supports `overwrite` / `smart` / `skip` (`smart` is a best-effort modified-time incremental mode for repeat syncs). `--delete-local` requires `--yes`, only removes regular files, and is skipped after item failures. `--local-dir` must stay inside cwd. |
+| [`+pull`](references/lark-drive-pull.md) | File-level Drive → local mirror. Duplicate remote `rel_path` conflicts fail by default; for duplicate files, `rename` downloads all copies with stable hashed suffixes, while `newest` / `oldest` pick one. `--if-exists` supports `overwrite` / `smart` / `skip` (`smart` is a best-effort modified-time incremental mode for repeat syncs). `--delete-local` requires `--yes`, only removes regular files, and is skipped after item failures. `--local-dir` must stay inside cwd.                                               |
 | `+sync` | Two-way local ↔ Drive sync. Reuses `+status` diff buckets, pulls `new_remote`, pushes `new_local`, and resolves `modified` via `--on-conflict=remote-wins|local-wins|keep-both|ask`. `--quick` enables best-effort modified-time diffing (timestamp mismatches can still trigger real pull/push actions), `--on-duplicate-remote` supports `fail|newest|oldest`, and the command is intentionally non-destructive (no delete on either side). |
-| [`+create-shortcut`](references/lark-drive-create-shortcut.md) | Create a shortcut to an existing Drive file in another folder |
-| [`+add-comment`](references/lark-drive-add-comment.md) | Add a comment to doc/docx/file/sheet/slides, also supports wiki URL resolving to doc/docx/file/sheet/slides; file targets support selected extensions and full comments only |
-| [`+export`](references/lark-drive-export.md) | Export a doc/docx/sheet/bitable to a local file with limited polling; supports `--file-name` for local naming |
-| [`+export-download`](references/lark-drive-export-download.md) | Download an exported file by file_token |
-| [`+import`](references/lark-drive-import.md) | Import a local file to Drive as a cloud document (docx, sheet, bitable) |
-| [`+version-history`](references/lark-drive-version-history.md) | List historical versions of a file with only_tag=true and cursor-based pagination |
-| [`+version-get`](references/lark-drive-version-get.md) | Download a specific historical version of a file |
-| [`+version-revert`](references/lark-drive-version-revert.md) | Revert a file to a specific historical version |
-| [`+version-delete`](references/lark-drive-version-delete.md) | Delete a specific historical version of a file |
-| [`+move`](references/lark-drive-move.md) | Move a file or folder to another location in Drive |
-| [`+delete`](references/lark-drive-delete.md) | Delete a Drive file or folder with limited polling for folder deletes |
-| [`+push`](references/lark-drive-push.md) | File-level local → Drive mirror. Duplicate remote `rel_path` conflicts fail by default; `newest` / `oldest` only apply to duplicate files when you explicitly want to target one remote file. `--if-exists` supports `skip` / `smart` / `overwrite` (`smart` skips files whose remote `modified_time` is already up to date, but falls through to the same overwrite path when the remote is older, so it inherits overwrite's rollout caveat). `--delete-remote` requires `--yes`. `--local-dir` must stay inside cwd. |
-| [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations |
-| [`+inspect`](references/lark-drive-inspect.md) | Inspect a Lark document URL to get its type, title, and canonical token; auto-unwraps wiki URLs to the underlying document |
-| [`+apply-permission`](references/lark-drive-apply-permission.md) | Apply to the document owner for view/edit access (user-only; 5/day per document) |
+| [`+create-shortcut`](references/lark-drive-create-shortcut.md) | Create a shortcut to an existing Drive file in another folder                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`+add-comment`](references/lark-drive-add-comment.md) | Add a comment to doc/docx/file/sheet/slides, also supports wiki URL resolving to doc/docx/file/sheet/slides; file targets support selected extensions and full comments only                                                                                                                                                                                                                                                                                                                                                       |
+| [`+export`](references/lark-drive-export.md) | Export a doc/docx/sheet/bitable/slides to a local file with limited polling; supports `--file-name` for local naming                                                                                                                                                                                                                                                                                                                                                                                                               |
+| [`+export-download`](references/lark-drive-export-download.md) | Download an exported file by file_token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| [`+import`](references/lark-drive-import.md) | Import a local file to Drive as a cloud document (docx, sheet, bitable)                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| [`+version-history`](references/lark-drive-version-history.md) | List historical versions of a file with only_tag=true and cursor-based pagination                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| [`+version-get`](references/lark-drive-version-get.md) | Download a specific historical version of a file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`+version-revert`](references/lark-drive-version-revert.md) | Revert a file to a specific historical version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| [`+version-delete`](references/lark-drive-version-delete.md) | Delete a specific historical version of a file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| [`+move`](references/lark-drive-move.md) | Move a file or folder to another location in Drive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [`+delete`](references/lark-drive-delete.md) | Delete a Drive file or folder with limited polling for folder deletes                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| [`+push`](references/lark-drive-push.md) | File-level local → Drive mirror. Duplicate remote `rel_path` conflicts fail by default; `newest` / `oldest` only apply to duplicate files when you explicitly want to target one remote file. `--if-exists` supports `skip` / `smart` / `overwrite` (`smart` skips files whose remote `modified_time` is already up to date, but falls through to the same overwrite path when the remote is older, so it inherits overwrite's rollout caveat). `--delete-remote` requires `--yes`. `--local-dir` must stay inside cwd.            |
+| [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| [`+inspect`](references/lark-drive-inspect.md) | Inspect a Lark document URL to get its type, title, and canonical token; auto-unwraps wiki URLs to the underlying document                                                                                                                                                                                                                                                                                                                                                                                                         |
+| [`+apply-permission`](references/lark-drive-apply-permission.md) | Apply to the document owner for view/edit access (user-only; 5/day per document)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 ## API Resources
 

skills/lark-drive/references/lark-drive-add-comment.md

@@ -178,5 +178,5 @@ lark-cli drive +add-comment \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-create-folder.md

@@ -1,8 +1,8 @@
-# drive +create-folder（创建云空间文件夹）
+# drive +create-folder（创建云空间/云盘/云存储文件夹）
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-在飞书云空间中创建一个新文件夹。该 shortcut 对原生 `drive files create_folder` 做了一层更适合日常使用的封装：`--folder-token` 可省略，此时会在调用者根目录创建；如果使用 `--as bot`，创建成功后 CLI 会尝试把新文件夹的可管理权限自动授予当前 CLI 用户。
+在飞书云空间（云盘/云存储）中创建一个新文件夹。该 shortcut 对原生 `drive files create_folder` 做了一层更适合日常使用的封装：`--folder-token` 可省略，此时会在调用者根目录创建；如果使用 `--as bot`，创建成功后 CLI 会尝试把新文件夹的可管理权限自动授予当前 CLI 用户。
 
 ## 命令
 
@@ -60,7 +60,7 @@ lark-cli drive +create-folder \
 
 ## 推荐场景
 
-- 用户说“在云空间新建一个文件夹 / 目录”时，优先使用 `drive +create-folder`
+- 用户说“在云空间（云盘/云存储）新建一个文件夹 / 目录”时，优先使用 `drive +create-folder`
 - 用户给了父文件夹链接或 token，需要在其下继续分层建目录时，传 `--folder-token`
 - 如果后续还要上传文件、移动文件、建子目录，优先复用返回值里的 `folder_token`
 
@@ -69,5 +69,5 @@ lark-cli drive +create-folder \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-create-shortcut.md

@@ -48,7 +48,7 @@ lark-cli drive +create-shortcut \
 - CLI 层会把 `--file-token` 和 `--type` 组装为底层 API 所需的 `refer_entity`
 - `--file-token` 必须是 Drive 文件 token，不要直接传 wiki 节点 token
 - 如果来源是 `/wiki/...` 链接，必须先按 [`lark-drive`](../SKILL.md) 中的 wiki 解析流程拿到真实 `obj_token`，再创建快捷方式
-- 目标位置必须是云空间文件夹；这个 shortcut 不是“复制文件内容”，而是“在另一个文件夹里挂一个引用入口”
+- 目标位置必须是云空间（云盘/云存储）文件夹；这个 shortcut 不是“复制文件内容”，而是“在另一个文件夹里挂一个引用入口”
 
 ## 类型说明
 
@@ -99,5 +99,5 @@ lark-cli drive +create-shortcut \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-delete.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-删除云空间内的文件或文件夹。删除后资源会进入回收站。
+删除云空间（云盘/云存储）内的文件或文件夹。删除后资源会进入回收站。
 
 > [!CAUTION]
 > 这是**高风险写操作**。CLI 层要求显式传 `--yes`；如果用户已经明确要求删除且目标明确，直接执行并带上 `--yes`。
@@ -63,7 +63,7 @@ lark-cli drive +task_result \
 
 ## 限制
 
-- 该 shortcut 仅支持云空间文件或文件夹，不支持 wiki 文档
+- 该 shortcut 仅支持云空间（云盘/云存储）文件或文件夹，不支持 wiki 文档
 - 该接口不支持并发调用
 - 调用频率上限为 5 QPS 且 10000 次/天
 
@@ -75,5 +75,5 @@ lark-cli drive +task_result \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-download.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-从飞书云空间下载文件到本地。
+从飞书云空间（云盘/云存储）下载文件到本地。
 
 ## 命令
 
@@ -27,5 +27,5 @@ https://xxx.feishu.cn/drive/file/boxbc_xxx
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-export-download.md

@@ -46,5 +46,5 @@ lark-cli drive +export-download \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-export.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-把 `doc` / `docx` / `sheet` / `bitable` 导出到本地文件。这个 shortcut 内置有限轮询：
+把 `doc` / `docx` / `sheet` / `bitable` / `slides` 导出到本地文件。这个 shortcut 内置有限轮询：
 
 - 如果导出任务在轮询窗口内完成，会直接下载到本地目录
 - 如果轮询结束仍未完成，会返回 `ticket`、`ready=false`、`timed_out=true` 和 `next_command`
@@ -39,6 +39,20 @@ lark-cli drive +export \
   --file-extension xlsx \
   --output-dir ./exports
 
+# 导出幻灯片为 pptx
+lark-cli drive +export \
+  --token "<SLIDES_TOKEN>" \
+  --doc-type slides \
+  --file-extension pptx \
+  --output-dir ./exports
+
+# 导出幻灯片为 pdf
+lark-cli drive +export \
+  --token "<SLIDES_TOKEN>" \
+  --doc-type slides \
+  --file-extension pdf \
+  --output-dir ./exports
+
 # 指定本地文件名（会按导出格式自动补扩展名）
 lark-cli drive +export \
   --token "<DOCX_TOKEN>" \
@@ -75,8 +89,8 @@ lark-cli drive +export \
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--token` | 是 | 源文档 token |
-| `--doc-type` | 是 | 源文档类型：`doc` / `docx` / `sheet` / `bitable` |
-| `--file-extension` | 是 | 导出格式：`docx` / `pdf` / `xlsx` / `csv` / `markdown` / `base` |
+| `--doc-type` | 是 | 源文档类型：`doc` / `docx` / `sheet` / `bitable` / `slides` |
+| `--file-extension` | 是 | 导出格式：`docx` / `pdf` / `xlsx` / `csv` / `markdown` / `base` / `pptx` |
 | `--sub-id` | 条件必填 | 当 `sheet` / `bitable` 导出为 `csv` 时必填 |
 | `--file-name` | 否 | 覆盖默认本地文件名；如未带扩展名，会按 `--file-extension` 自动补齐 |
 | `--output-dir` | 否 | 本地输出目录，默认当前目录 |
@@ -86,6 +100,8 @@ lark-cli drive +export \
 
 - `markdown` 只支持 `docx`
 - `base` 只支持 `bitable`
+- `pptx` 只支持 `slides`
+- `slides` 支持导出为 `pptx` / `pdf`
 - `sheet` / `bitable` 导出为 `csv` 时必须带 `--sub-id`
 - shortcut 内部固定有限轮询：最多 10 次，每次间隔 5 秒
 - 轮询超时不是失败；会返回 `ticket`、`timed_out=true` 和 `next_command`，供后续继续查询
@@ -115,5 +131,5 @@ lark-cli drive +export-download \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-import.md

@@ -56,7 +56,7 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
 |------|------|------|
 | `--file` | 是 | 本地文件路径，根据文件后缀名自动推断 `file_extension`；文件需满足对应格式的导入大小限制，超过 20MB 且仍在允许范围内时会自动切换分片上传 |
 | `--type` | 是 | 导入目标云文档格式。可选值：`docx` (新版文档)、`sheet` (电子表格)、`bitable` (多维表格) |
-| `--folder-token` | 否 | 目标文件夹 token，不传则请求中的 `point.mount_key` 为空字符串，Import API 会将其解释为导入到云空间根目录 |
+| `--folder-token` | 否 | 目标文件夹 token，不传则请求中的 `point.mount_key` 为空字符串，Import API 会将其解释为导入到云空间（云盘/云存储）根目录 |
 | `--name` | 否 | 导入后的在线云文档名称，不传默认使用本地文件名去掉扩展名后的结果 |
 | `--target-token` | 否 | 已有的多维表格 token，将数据导入到该多维表格中（**仅支持 `--type bitable`**）；传入后数据会挂载到目标多维表格而非新建一个 |
 
@@ -155,5 +155,5 @@ lark-cli drive +task_result --scenario import --ticket <TICKET>
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-move.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-将文件或文件夹移动到用户云空间的其他位置。
+将文件或文件夹移动到用户云空间（云盘/云存储）的其他位置。
 
 ## 与 `wiki +move` 的区别
 
@@ -116,5 +116,5 @@ lark-cli drive +task_result \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-pull.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-把飞书云空间的某个文件夹**单向、文件级**镜像到本地目录（Drive → 本地）。命令递归列出 `--folder-token` 下所有 `type=file` 的文件，逐一下载到 `--local-dir` 对应的相对路径，子文件夹自动复刻为本地目录。
+把飞书云空间（云盘/云存储）的某个文件夹**单向、文件级**镜像到本地目录（Drive → 本地）。命令递归列出 `--folder-token` 下所有 `type=file` 的文件，逐一下载到 `--local-dir` 对应的相对路径，子文件夹自动复刻为本地目录。
 
 > ⚠️ **不是 directory-level mirror**：`--delete-local` 只删除本地"多余"的常规文件，不删除空目录。如果云端把整个子文件夹删了，对应的本地子目录会留空（里面的文件被清掉，目录本身保留）；想精确同步目录结构请自己 `rmdir` 处理空壳。
 
@@ -131,7 +131,7 @@ lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) —— 云空间全部命令
+- [lark-drive](../SKILL.md) —— 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) —— 认证和全局参数
 - [lark-drive-status](lark-drive-status.md) —— 下载前先看差异
 - [lark-drive-download](lark-drive-download.md) —— 单文件按需拉取

skills/lark-drive/references/lark-drive-push.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-把本地目录**单向、文件级**镜像到飞书云空间的某个文件夹（本地 → Drive）。命令递归列出 `--folder-token` 下的远端清单，遍历 `--local-dir` 的所有常规文件，按相对路径在 Drive 上新建、覆盖或跳过；可选地（`--delete-remote --yes`）删除云端"本地没有"的 `type=file`。
+把本地目录**单向、文件级**镜像到飞书云空间（云盘/云存储）的某个文件夹（本地 → Drive）。命令递归列出 `--folder-token` 下的远端清单，遍历 `--local-dir` 的所有常规文件，按相对路径在 Drive 上新建、覆盖或跳过；可选地（`--delete-remote --yes`）删除云端"本地没有"的 `type=file`。
 
 > **"文件级镜像"≠"目录镜像"。** 命令只在文件维度收敛差异：本地多了文件就上传，本地少了文件且开了 `--delete-remote --yes` 就删远端文件。**远端只有的空目录、本地已删除的目录**都不会被收敛，云端目录树的多余结构不会被清理。如果需要"目录也要保持完全一致"，得自行先 `+status` 找差异、再手动处理多余目录。
 
@@ -155,7 +155,7 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) —— 云空间全部命令
+- [lark-drive](../SKILL.md) —— 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) —— 认证和全局参数
 - [lark-drive-status](lark-drive-status.md) —— 上传前先看差异（避免全量回写）
 - [lark-drive-pull](lark-drive-pull.md) —— Drive → 本地的对称命令

skills/lark-drive/references/lark-drive-reactions.md

@@ -109,5 +109,5 @@ Music, Typing, Pepper, CheckMark, CrossMark
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-search.md

@@ -1,9 +1,9 @@
 
-# drive +search（云空间搜索：扁平 flag，面向自然语言场景）
+# drive +search（云空间/云盘/云存储搜索：扁平 flag，面向自然语言场景）
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-基于 Search v2 接口 `POST /open-apis/search/v2/doc_wiki/search`，以**用户身份**统一搜索云空间对象。
+基于 Search v2 接口 `POST /open-apis/search/v2/doc_wiki/search`，以**用户身份**统一搜索云空间（云盘/云存储）对象。
 
 核心特性：
 
@@ -12,7 +12,7 @@
 - 自动处理 `my_edit_time` / `my_comment_time` 的小时级聚合（服务端存储粒度）：亚小时输入会向整点 snap，并在 stderr 打出提示
 - `--mine` 一键从当前登录用户的 open_id 填 `creator_ids`，不必再先去查 contact（注意 `creator_ids` 服务端按 **owner / 文档归属人** 语义匹配，不是“最初创建人”，详见下文「身份维度」）
 
-> **资源发现入口统一**：`drive +search` 同样返回 `SHEET` / `Base` / `FOLDER` 等全部云空间对象，不只是文档 / Wiki。用户说"找一个表格"、"找报表"、"最近打开的表格"时，也从这里开始；定位后再切到对应业务 skill（如 `lark-sheets`）做对象内部操作。
+> **资源发现入口统一**：`drive +search` 同样返回 `SHEET` / `Base` / `FOLDER` 等全部云空间（云盘/云存储）对象，不只是文档 / Wiki。用户说"找一个表格"、"找报表"、"最近打开的表格"时，也从这里开始；定位后再切到对应业务 skill（如 `lark-sheets`）做对象内部操作。
 
 ## 命令
 
@@ -216,7 +216,7 @@ stdout 的 JSON 输出不受影响。`open_time` / `create_time` 不做 snap。
 
 | 操作 | 所需 scope |
 |---|---|
-| 搜索云空间对象（文档 / Wiki / 表格等资源发现） | `search:docs:read` |
+| 搜索云空间（云盘/云存储）对象（文档 / Wiki / 表格等资源发现） | `search:docs:read` |
 
 ## 常见错误
 

skills/lark-drive/references/lark-drive-status.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-按 **精确 SHA-256**（默认）或 **快速 modified_time**（`--quick`）比较本地目录与飞书云空间文件夹，输出四类差异：
+按 **精确 SHA-256**（默认）或 **快速 modified_time**（`--quick`）比较本地目录与飞书云空间（云盘/云存储）文件夹，输出四类差异：
 
 | 字段 | 含义 |
 |------|------|
@@ -132,6 +132,6 @@ lark-cli drive +status \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) —— 云空间全部命令
+- [lark-drive](../SKILL.md) —— 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) —— 认证和全局参数
 - [lark-drive-upload](lark-drive-upload.md) / [lark-drive-download](lark-drive-download.md) —— 把 +status 输出接到推/拉动作上

skills/lark-drive/references/lark-drive-task-result.md

@@ -298,5 +298,5 @@ lark-cli drive +export-download --file-token <EXPORTED_FILE_TOKEN>
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-upload.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-上传本地文件到飞书云空间。目标位置可以是 Drive 文件夹，也可以是 wiki 节点。
+上传本地文件到飞书云空间（云盘/云存储）。目标位置可以是 Drive 文件夹，也可以是 wiki 节点。
 
 ## 快速决策
 - 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../../lark-markdown/SKILL.md)。
@@ -97,5 +97,5 @@ Shortcut 参数：
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-version-delete.md

@@ -34,5 +34,5 @@ lark-cli drive +version-delete \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-version-get.md

@@ -67,5 +67,5 @@ lark-cli drive +version-get \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-version-history.md

@@ -69,5 +69,5 @@ lark-cli drive +version-history \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-drive/references/lark-drive-version-revert.md

@@ -31,5 +31,5 @@ lark-cli drive +version-revert \
 
 ## 参考
 
-- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-im/references/lark-im-messages-reply.md

@@ -64,12 +64,27 @@ So `--markdown` is a convenience mode, not a full Markdown compatibility layer.
 - Block spacing and line breaks may be normalized during conversion.
 - Code blocks are preserved as code blocks.
 - Excess blank lines are compressed.
-- Only remote `http://...`, `https://...`, or already-uploaded `img_xxx` Markdown images are kept reliably.
-- Local paths in Markdown image syntax like `![x](./a.png)` are **not** auto-uploaded by `--markdown`.
-- If remote Markdown image handling fails, that image is removed with a warning.
+- Already-uploaded `img_xxx` image keys are the most reliable Markdown image input.
+- Local paths (e.g. `![x](./a.png)`) are **not** supported directly in `--markdown` and will not be auto-uploaded.
+- Remote URLs (`https://...`) will be auto-downloaded and uploaded at runtime; if the download or upload fails, the image is removed with a warning.
 
 If you need exact output, use `--msg-type post --content ...` instead of `--markdown`.
 
+### Image Constraint for `--markdown`
+
+When using `--markdown` with images, prefer pre-uploading via `images.create` and referencing `![alt](img_xxx)` for predictable results. Remote URLs may work but are not guaranteed.
+
+**Steps:**
+
+```bash
+# 1. Upload image to get image_key
+lark-cli im images create --data '{"image_type":"message"}' --file ./diagram.png
+# Returns: {"image_key":"img_v3_xxxx"}
+
+# 2. Use image_key in --markdown reply
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Result\n\n![diagram](img_v3_xxxx)\n\nSee above for details.'
+```
+
 ## Preserving Formatting
 
 If the reply contains multiple lines, code blocks, indentation, tabs, or a lot of escaping, prefer `$'...'`.
@@ -119,6 +134,11 @@ lark-cli im +messages-reply --message-id om_xxx --text "Let's discuss this" --re
 # Reply with basic Markdown (will be converted to post JSON)
 lark-cli im +messages-reply --message-id om_xxx --markdown $'## Reply\n\n- item 1\n- item 2'
 
+# Reply with Markdown containing an image (must pre-upload via images.create)
+lark-cli im images create --data '{"image_type":"message"}' --file ./screenshot.png
+# Use the returned image_key
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Screenshot\n\n![screenshot](img_v3_xxxx)\n\nConfirmed.'
+
 # If you need exact post structure, send JSON directly
 lark-cli im +messages-reply --message-id om_xxx --msg-type post --content '{"zh_cn":{"title":"Reply","content":[[{"tag":"text","text":"Detailed content"}]]}}'
 
@@ -172,6 +192,7 @@ lark-cli im +messages-reply --message-id om_xxx --markdown $'## Test\n\nhello' -
 - Choosing `--markdown` when you actually need exact plain text. If exact line breaks and spacing matter, use `--text`, usually with `$'...'`.
 - Assuming `--markdown` supports all Markdown features. It does not; it is converted into a Feishu `post` payload and rewritten first.
 - Putting local image paths inside Markdown like `![x](./a.png)`. `--markdown` does not auto-upload those paths.
+- **Using local file paths inside Markdown image syntax** (e.g. `![x](./a.png)`) with `--markdown`. Local paths are not auto-uploaded and will not render as an image. Pre-upload via `images.create` to get an `image_key` instead.
 - Using `--content` without making the JSON match the effective `--msg-type`.
 - Explicitly setting `--msg-type` to something that conflicts with `--text`, `--markdown`, or media flags.
 - Mixing `--text`, `--markdown`, or `--content` with media flags in one command.
@@ -226,3 +247,4 @@ The reply appears in the target message's thread and does not show up in the mai
 - Failures return error codes and messages
 - `--as user` uses a user access token (UAT) and requires the `im:message.send_as_user` and `im:message` scopes; the reply is sent as the authorized end user
 - `--as bot` uses a tenant access token (TAT), and requires the `im:message:send_as_bot` scope
+- When using `--markdown` with images, pre-uploading via `images.create` to obtain an `image_key` is recommended for reliability; remote URLs may be auto-resolved at runtime, but if download/upload fails the image is removed with a warning; local paths are not supported

skills/lark-im/references/lark-im-messages-send.md

@@ -64,12 +64,27 @@ This means `--markdown` is convenient, but it is not a full-fidelity Markdown tr
 - Block spacing and line breaks may be normalized during conversion.
 - Code blocks are preserved as code blocks.
 - Excess blank lines are compressed.
-- Only `http://...`, `https://...`, or already-uploaded `img_xxx` Markdown images are kept reliably.
-- Local paths in Markdown image syntax like `![x](./a.png)` are **not** auto-uploaded by `--markdown`; they may be stripped during optimization.
-- If remote Markdown image download/upload fails, that image is removed with a warning.
+- Already-uploaded `img_xxx` image keys are the most reliable Markdown image input.
+- Local paths in Markdown image syntax like `![x](./a.png)` are **not** supported and will not be auto-uploaded.
+- Remote URLs (`https://...`) will be auto-downloaded and uploaded at runtime; if the download or upload fails, the image is removed with a warning.
 
 If any of the above is unacceptable, do **not** use `--markdown`; use `--content` and provide the final JSON yourself.
 
+### Image Constraint for `--markdown`
+
+When using `--markdown` with images, prefer pre-uploading via `images.create` and referencing `![alt](img_xxx)` for predictable results. Remote URLs may work but are not guaranteed.
+
+**Steps:**
+
+```bash
+# 1. Upload image to get image_key
+lark-cli im images create --data '{"image_type":"message"}' --file ./diagram.png
+# Returns: {"image_key":"img_v3_xxxx"}
+
+# 2. Use image_key in --markdown
+lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Report\n\n![diagram](img_v3_xxxx)\n\nSee above for details.'
+```
+
 ## Preserving Formatting
 
 If the message has multiple lines, indentation, code blocks, tabs, or many quotes/backslashes, prefer shell ANSI-C quoting with `$'...'`.
@@ -118,6 +133,11 @@ lark-cli im +messages-send --chat-id oc_xxx --text $'Line 1\nLine 2\n  indented
 # Send basic Markdown (will be converted to post JSON)
 lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Update\n\n- item 1\n- item 2'
 
+# Send Markdown with an image (must pre-upload via images.create)
+lark-cli im images create --data '{"image_type":"message"}' --file ./screenshot.png
+# Use the returned image_key in the markdown content
+lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Status\n\n![screenshot](img_v3_xxxx)\n\nDone.'
+
 # If you need exact post structure, send JSON directly
 lark-cli im +messages-send --chat-id oc_xxx --msg-type post --content '{"zh_cn":{"title":"Title","content":[[{"tag":"text","text":"Body"}]]}}'
 
@@ -178,6 +198,7 @@ lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Test\n\nhello' --dry
 - Choosing `--markdown` when you actually need exact plain text. If exact line breaks and spacing matter, use `--text`, usually with `$'...'`.
 - Assuming `--markdown` supports all Markdown features. It does not; it is converted into a Feishu `post` payload and rewritten first.
 - Putting local image paths inside Markdown like `![x](./a.png)`. `--markdown` does not auto-upload those paths.
+- **Using local file paths inside Markdown image syntax** (e.g. `![x](./a.png)`) with `--markdown`. Local paths are not auto-uploaded and will not render as an image. Pre-upload via `images.create` to get an `image_key` instead.
 - Using `--content` without making the JSON match the effective `--msg-type`.
 - Explicitly setting `--msg-type` to something that conflicts with `--text`, `--markdown`, or media flags.
 - Mixing `--text`, `--markdown`, or `--content` with media flags in one command.
@@ -227,3 +248,4 @@ lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Test\n\nhello' --dry
 - `--as user` uses a user access token (UAT) and requires the `im:message.send_as_user` and `im:message` scopes; the message is sent as the authorized end user
 - `--as bot` uses a tenant access token (TAT) and requires the `im:message:send_as_bot` scope
 - When sending as a bot, the app must already be in the target group or already have a direct-message relationship with the target user
+- When using `--markdown` with images, pre-uploading via `images.create` to obtain an `image_key` is recommended for reliability; remote URLs may be auto-resolved at runtime, but if download/upload fails the image is removed with a warning; local paths are not supported

skills/lark-markdown/SKILL.md

@@ -21,7 +21,7 @@ metadata:
 - 用户要**覆盖更新 Drive 里某个 `.md` 文件内容**，使用 `lark-cli markdown +overwrite`
 - 用户要先拿 Markdown 文件的历史版本号，再做比较/下载/回滚，先用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +version-history`
 - 用户要把本地 Markdown **导入成在线新版文档（docx）**，不要用本 skill，改用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +import --type docx`
-- 用户要对 Markdown 文件做**rename / move / delete / 搜索 / 权限 / 评论**等云空间操作，不要留在本 skill，切到 [`lark-drive`](../lark-drive/SKILL.md)
+- 用户要对 Markdown 文件做**rename / move / delete / 搜索 / 权限 / 评论**等云空间（云盘/云存储）操作，不要留在本 skill，切到 [`lark-drive`](../lark-drive/SKILL.md)
 
 ## 核心边界
 

skills/lark-minutes/SKILL.md

@@ -66,11 +66,11 @@ lark-cli vc +notes --minute-tokens <minute_token>
 1. 当用户需要通过上传本地音视频文件来生成妙记时使用。
 2. 当用户说"把音视频文件转成纪要""把录音转成逐字稿/文字稿/撰写文字""把 mp4/mp3 转成总结/待办/章节"时，也先走这个入口。
 3. **处理流程**：
-   - **上传音视频获取 `file_token`**：使用 [`lark-cli drive +upload`](../lark-drive/references/lark-drive-upload.md) 上传本地文件到云空间并获取 `file_token`。
+   - **上传音视频获取 `file_token`**：使用 [`lark-cli drive +upload`](../lark-drive/references/lark-drive-upload.md) 上传本地文件到云空间（云盘/云存储）并获取 `file_token`。
    - **生成妙记**：获取到 `file_token` 后，调用 [`lark-cli minutes +upload`](references/lark-minutes-upload.md) 将文件转换为妙记并获取 `minute_url` 链接。
    - **继续获取纪要 / 逐字稿（按需）**：如果用户目标不是只要妙记链接，而是要纪要、逐字稿、总结、待办或章节，则从 `minute_url` 中提取 `minute_token`，再调用 [`lark-cli vc +notes --minute-tokens`](../lark-vc/references/lark-vc-notes.md) 获取对应产物。
 
-> **注意**：必须先获取飞书云空间的 `file_token` 才能进行转换。
+> **注意**：必须先获取飞书云空间（云盘/云存储）的 `file_token` 才能进行转换。
 >
 > **不要误走本地转写工具**：当用户目标是把本地音视频文件转成纪要、逐字稿、文字稿、撰写文字时，不要改用 `ffmpeg`、`whisper` 或其他本地 ASR/转码命令；标准路径就是 `drive +upload -> minutes +upload -> vc +notes --minute-tokens`。
 

skills/lark-minutes/references/lark-minutes-upload.md

@@ -17,8 +17,8 @@
 
 当用户要求将音视频文件转换为妙记，或进一步要纪要/逐字稿/文字稿/撰写文字时，必须按照以下步骤执行：
 
-1. **上传文件至云空间获取 file_token**
-   - 使用 `lark-cli drive +upload` 命令上传本地文件到云空间（Drive）：
+1. **上传文件至云空间（云盘/云存储）获取 file_token**
+   - 使用 `lark-cli drive +upload` 命令上传本地文件到云空间/云盘/云存储（Drive）：
      ```bash
      lark-cli drive +upload --file <path/to/media/file>
      ```
@@ -44,7 +44,7 @@
 ## 命令示例
 
 ```bash
-# 通过已上传到云空间的 file_token 生成妙记
+# 通过已上传到云空间（云盘/云存储）的 file_token 生成妙记
 lark-cli minutes +upload --file-token boxcnxxxxxxxxxxxxxxxx
 
 # 通过 minute_token 继续获取纪要 / 逐字稿 / 文字稿 / AI 产物
@@ -55,7 +55,7 @@ lark-cli vc +notes --minute-tokens obcnxxxxxxxxxxxxxxxx
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--file-token <token>` | 是 | 已经上传到飞书云空间的音视频文件的 file_token |
+| `--file-token <token>` | 是 | 已经上传到飞书云空间（云盘/云存储）的音视频文件的 file_token |
 
 ## 支持的格式与限制
 
@@ -72,13 +72,13 @@ lark-cli vc +notes --minute-tokens obcnxxxxxxxxxxxxxxxx
 
 ### 1. 必须提供 file_token
 
-本接口不直接处理本地文件的上传，必须先使用 `drive +upload` 将文件上传到云空间获取 `file_token`，然后再调用本接口。
+本接口不直接处理本地文件的上传，必须先使用 `drive +upload` 将文件上传到云空间（云盘/云存储）获取 `file_token`，然后再调用本接口。
 
 ### 2. 先上传，再生成妙记
 
 推荐流程如下：
 
-1. 使用 `lark-cli drive +upload --file <path>` 上传本地音视频文件到云空间
+1. 使用 `lark-cli drive +upload --file <path>` 上传本地音视频文件到云空间（云盘/云存储）
 2. 从返回结果中取出 `file_token`
 3. 调用 `lark-cli minutes +upload --file-token <file_token>` 生成妙记
 4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，再从 `minute_url` 提取 `minute_token`，继续调用 `lark-cli vc +notes --minute-tokens <minute_token>`
@@ -100,5 +100,5 @@ lark-cli vc +notes --minute-tokens obcnxxxxxxxxxxxxxxxx
 ## 参考
 
 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明
-- [drive +upload](../../lark-drive/references/lark-drive-upload.md) -- 上传文件到云空间
+- [drive +upload](../../lark-drive/references/lark-drive-upload.md) -- 上传文件到云空间（云盘/云存储）
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-shared/SKILL.md

@@ -14,7 +14,7 @@ description: "Use when first setting up lark-cli, running auth login, switching
 
 当你帮用户初始化配置时，使用background方式使用下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户。
 
-**URL 转发规则**：当命令输出 `verification_url`、`verification_uri_complete`、`console_url` 等 URL 字段时，必须将 URL exactly as returned by the CLI 转发给用户，并把它视为不可修改的 opaque string；不要做 URL encode/decode，不要补 `%20`、空格或标点，不要重新拼接 query，不要改写成 Markdown link text，建议用只包含原始 URL 的代码块单独输出。
+**URL 转发规则**：当命令输出 `verification_url`、`verification_uri_complete`、`console_url` 等 URL 字段时：**必须生成二维码**：你必须调用 `lark-cli auth qrcode` 将 URL 转为二维码并展示给用户，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。**URL 输出规则**：将 URL 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点、重新拼接 query），建议用仅包含原始 URL 的代码块单独输出，二维码和链接请一起展示给用户。
 
 ```bash
 # 发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）
@@ -29,14 +29,14 @@ lark-cli config init --new
 
 | 身份 | 标识 | 获取方式 | 适用场景 |
 |------|------|---------|---------|
-| user 用户身份 | `--as user` | `lark-cli auth login` 等 | 访问用户自己的资源（日历、云空间等） |
+| user 用户身份 | `--as user` | `lark-cli auth login` 等 | 访问用户自己的资源（日历、云空间/云盘/云存储等） |
 | bot 应用身份 | `--as bot` | 自动，只需 appId + appSecret | 应用级操作,访问bot自己的资源 |
 
 ### 身份选择原则
 
 输出的 `[identity: bot/user]` 代表当前身份。bot 与 user 表现差异很大，需确认身份符合目标需求：
 
-- **Bot 看不到用户资源**：无法访问用户的日历、云空间文档、邮箱等个人资源。例如 `--as bot` 查日程返回 bot 自己的（空）日历
+- **Bot 看不到用户资源**：无法访问用户的日历、云空间（云盘/云存储）文档、邮箱等个人资源。例如 `--as bot` 查日程返回 bot 自己的（空）日历
 - **Bot 无法代表用户操作**：发消息以应用名义发送，创建文档归属 bot
 - **Bot 权限**：只需在飞书开发者后台开通 scope，无需 `auth login`
 - **User 权限**：后台开通 scope + 用户通过 `auth login` 授权，两层都要满足

skills/lark-sheets/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-sheets
 version: 1.2.0
-description: "飞书电子表格：创建和操作电子表格。支持创建表格、创建/复制/删除/更新工作表、读写单元格、追加行数据、查找内容、导出文件。当用户需要创建电子表格、管理工作表、批量读写数据、在已知表格中查找内容、导出或下载表格时使用。若用户是想按名称或关键词搜索云空间里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。"
+description: "飞书电子表格：创建和操作电子表格。支持创建表格、创建/复制/删除/更新工作表、读写单元格、追加行数据、查找内容、导出文件。当用户需要创建电子表格、管理工作表、批量读写数据、在已知表格中查找内容、导出或下载表格时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -95,7 +95,7 @@ Wiki Space (知识空间)
     └── obj_type: file/slides/mindnote
         └── obj_token (真实文档 token)
 
-Drive Folder (云空间文件夹)
+Drive Folder (云空间/云盘/云存储文件夹)
 └── File (文件/文档)
     └── file_token (直接使用)
 ```

skills/lark-sheets/references/lark-sheets-cell-data.md

@@ -121,7 +121,7 @@ lark-cli sheets +append --spreadsheet-token "shtxxxxxxxx" \
 
 对应命令：`lark-cli sheets +find`
 
-只在一个已知 spreadsheet 内查找单元格内容，不是云空间搜索。
+只在一个已知 spreadsheet 内查找单元格内容，不是云空间（云盘/云存储）搜索。
 
 ```bash
 lark-cli sheets +find --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \

skills/lark-task/SKILL.md

@@ -33,26 +33,26 @@ metadata:
 > Task OpenAPI 中用于更新/操作任务的 `guid` 是任务的全局唯一标识（GUID），不是客户端展示的任务编号（例如 `t104121` / `suite_entity_num`）。
 > 对于 Feishu 的任务 applink（例如 `.../client/todo/task?guid=...`），必须使用 URL query 里的 `guid` 参数作为 task guid。
 
-## Shortcuts
-
-- [`+create`](./references/lark-task-create.md) — Create a task
-- [`+update`](./references/lark-task-update.md) — Update a task
-- [`+comment`](./references/lark-task-comment.md) — Add a comment to a task
-- [`+complete`](./references/lark-task-complete.md) — Complete a task
-- [`+reopen`](./references/lark-task-reopen.md) — Reopen a task
-- [`+assign`](./references/lark-task-assign.md) — Assign or remove members from a task
-- [`+followers`](./references/lark-task-followers.md) — Manage task followers
-- [`+reminder`](./references/lark-task-reminder.md) — Manage task reminders
-- [`+get-my-tasks`](./references/lark-task-get-my-tasks.md) — List tasks assigned to me
-- [`+get-related-tasks`](./references/lark-task-get-related-tasks.md) — List tasks related to me
-- [`+search`](./references/lark-task-search.md) — Search tasks
-- [`+subscribe-event`](./references/lark-task-subscribe-event.md) — Subscribe to task events
-- [`+set-ancestor`](./references/lark-task-set-ancestor.md) — Set or clear a task ancestor
-- [`+tasklist-create`](./references/lark-task-tasklist-create.md) — Create a tasklist and batch add tasks
-- [`+tasklist-search`](./references/lark-task-tasklist-search.md) — Search tasklists
-- [`+tasklist-task-add`](./references/lark-task-tasklist-task-add.md) — Add existing tasks to a tasklist
-- [`+tasklist-members`](./references/lark-task-tasklist-members.md) — Manage tasklist members
-- [`+upload-attachment`](./references/lark-task-upload-attachment.md) — Upload a file as a task attachment
+| Shortcut | 说明 |
+|----------|------|
+| [`+create`](references/lark-task-create.md) | create a task |
+| [`+update`](references/lark-task-update.md) | update task attributes |
+| [`+set-ancestor`](references/lark-task-set-ancestor.md) | set or clear a task ancestor |
+| [`+comment`](references/lark-task-comment.md) | add a comment to a task |
+| [`+complete`](references/lark-task-complete.md) | mark a task as complete |
+| [`+reopen`](references/lark-task-reopen.md) | reopen a completed task |
+| [`+assign`](references/lark-task-assign.md) | assign or remove task members |
+| [`+followers`](references/lark-task-followers.md) | manage task followers |
+| [`+reminder`](references/lark-task-reminder.md) | manage task reminders |
+| [`+get-my-tasks`](references/lark-task-get-my-tasks.md) | List tasks assigned to me |
+| [`+get-related-tasks`](references/lark-task-get-related-tasks.md) | list tasks related to me |
+| [`+search`](references/lark-task-search.md) | search tasks |
+| [`+subscribe-event`](references/lark-task-subscribe-event.md) | subscribe to task events |
+| [`+upload-attachment`](references/lark-task-upload-attachment.md) | upload a local file as an attachment to a task |
+| [`+tasklist-create`](references/lark-task-tasklist-create.md) | create a tasklist and optionally add tasks |
+| [`+tasklist-search`](references/lark-task-tasklist-search.md) | search tasklists |
+| [`+tasklist-task-add`](references/lark-task-tasklist-task-add.md) | add tasks to a tasklist |
+| [`+tasklist-members`](references/lark-task-tasklist-members.md) | manage tasklist members |
 
 ## API Resources
 
@@ -162,4 +162,3 @@ lark-cli task <resource> <method> [flags] # 调用 API
 | `agent.update_agent_profile` | `task:task:write` |
 | `agent.register_agent` | `task:task:write` |
 | `agent_task_step_info.append_task_steps` | `task:task:write` |
-| `+upload-attachment` | `task:attachment:write` |

skills/lark-wiki/SKILL.md

@@ -52,7 +52,7 @@ metadata:
 - `我的文档库` / `My Document Library` / `我的知识库` / `个人知识库` / `my_library` 都应视为 **Wiki personal library**，不是 Drive 根目录
 - 处理这类目标时，先解析 `my_library` 对应的真实 `space_id`，再执行 `wiki +move`、`wiki +node-create` 或其他 Wiki 写操作
 - 不要因为缺少显式 `space_id` 就退化成 `drive +move`
-- 如果用户明确说的是 Drive 文件夹、云空间根目录、`我的空间`，才进入 Drive 域处理
+- 如果用户明确说的是 Drive 文件夹、云空间（云盘/云存储）根目录、`我的空间`，才进入 Drive 域处理
 
 ## Shortcuts（推荐优先使用）
 

skills/lark-wiki/references/lark-wiki-move.md

@@ -15,12 +15,12 @@
 - `drive +move` 的目标是 **Drive 文件夹**，使用 `--folder-token`
 - 如果源对象已经是 Wiki 节点，必须使用 `wiki +move`，而不是 `drive +move`
 - 如果源对象还是 Drive 文档，但用户要“迁入知识库”“挂到某个 Wiki 页面下”，也应使用 `wiki +move`
-- 如果用户只是想整理云空间文件夹，把文件/文件夹挪到另一个 Drive 文件夹，应使用 `drive +move`
+- 如果用户只是想整理云空间（云盘/云存储）文件夹，把文件/文件夹挪到另一个 Drive 文件夹，应使用 `drive +move`
 
 ## 口语目标识别
 
 - 当用户说“移动到某个知识库”“挂到某个页面下”“迁入 Wiki”时，按 **Wiki 目标** 处理，优先使用 `wiki +move`
-- 当用户说“移动到某个文件夹”“移动到云空间根目录”时，按 **Drive 文件夹目标** 处理，优先使用 `drive +move`
+- 当用户说“移动到某个文件夹”“移动到云空间（云盘/云存储）根目录”时，按 **Drive 文件夹目标** 处理，优先使用 `drive +move`
 - 当用户说“移动到我的文档库”“移动到我的知识库”“放到个人知识库”时，应先按 **Wiki 个人知识库目标** 理解，而不是直接退化成 `drive +move`
 - 遇到“我的文档库”这类表述时，可以把它理解成：先用 `my_library` 去查询用户个人知识库，再拿到真实 `space_id`
 - 推荐做法是先执行 `lark-cli wiki spaces get --params '{"space_id":"my_library"}'`，取回真实知识库 `space_id`，再把这个 `space_id` 用到 `wiki +move`

skills/lark-wiki/references/lark-wiki-node-get.md

@@ -6,7 +6,7 @@ Get a wiki node's details by `node_token`, `obj_token`, or a Lark URL. Use this
 
 ```bash
 lark-cli wiki +node-get \
-  --token <node_token | obj_token | Lark URL> \
+  --node-token <node_token | obj_token | Lark URL> \
   [--obj-type <doc|docx|sheet|bitable|mindnote|slides|file>] \
   [--space-id <space_id>] \
   [--format json|pretty|table|csv|ndjson] \
@@ -17,8 +17,9 @@ lark-cli wiki +node-get \
 
 | Flag | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
-| `--token` | string | **Yes** | — | `node_token`, cloud-doc `obj_token`, or a Lark URL embedding one (e.g. `https://feishu.cn/wiki/<token>` or `https://feishu.cn/docx/<token>`) |
-| `--obj-type` | enum | No | — | Needed when `--token` is a raw `obj_token`; auto-inferred from the URL path. Not allowed when the token looks like a `node_token` (`wik...`) |
+| `--node-token` | string | **Yes** | — | `node_token`, cloud-doc `obj_token`, or a Lark URL embedding one (e.g. `https://feishu.cn/wiki/<token>` or `https://feishu.cn/docx/<token>`). Matches the `--node-token` naming used by sibling `+node-delete` / `+node-copy` / `+move`. |
+| `--token` | string | — (deprecated) | — | Deprecated original name; still accepted for backward compatibility but emits a `Flag --token has been deprecated, use --node-token instead` warning on stderr. New scripts should use `--node-token`. |
+| `--obj-type` | enum | No | — | Needed when `--node-token` is a raw `obj_token`; auto-inferred from the URL path. Not allowed when the token looks like a `node_token` (`wik...`) |
 | `--space-id` | string | No | — | Optional cross-check: fail if the resolved node does not live in this space |
 | `--format` | enum | No | `json` | `json` / `pretty` / `table` / `csv` / `ndjson` |
 | `--as` | enum | No | `auto` | Identity `user`/`bot`; wiki is user-centric → pass `--as user` |

tests/cli_e2e/wiki/wiki_node_create_dryrun_test.go

@@ -0,0 +1,207 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package wiki
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+func setWikiNodeCreateDryRunEnv(t *testing.T) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_APP_ID", "wiki_dryrun_test")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "wiki_dryrun_secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+}
+
+// TestWikiNodeCreateDryRun pins the request shape and Validate behavior for
+// `wiki +node-create`.
+func TestWikiNodeCreateDryRun(t *testing.T) {
+	setWikiNodeCreateDryRunEnv(t)
+
+	t.Run("HappyPath_ExplicitSpaceID", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		t.Cleanup(cancel)
+
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"wiki", "+node-create",
+				"--space-id", "123456",
+				"--title", "TestDoc",
+				"--obj-type", "docx",
+				"--dry-run",
+			},
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+
+		assert.Equal(t, "POST", gjson.Get(result.Stdout, "api.0.method").String())
+		assert.Equal(t, "/open-apis/wiki/v2/spaces/123456/nodes", gjson.Get(result.Stdout, "api.0.url").String())
+		assert.Equal(t, "origin", gjson.Get(result.Stdout, "api.0.body.node_type").String())
+		assert.Equal(t, "docx", gjson.Get(result.Stdout, "api.0.body.obj_type").String())
+		assert.Equal(t, "TestDoc", gjson.Get(result.Stdout, "api.0.body.title").String())
+	})
+
+	t.Run("HappyPath_WithParentNodeToken", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		t.Cleanup(cancel)
+
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"wiki", "+node-create",
+				"--space-id", "123456",
+				"--parent-node-token", "wikcnABC123",
+				"--title", "ChildDoc",
+				"--obj-type", "docx",
+				"--dry-run",
+			},
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+
+		// 2-step: resolve parent node -> create node
+		assert.Equal(t, "GET", gjson.Get(result.Stdout, "api.0.method").String())
+		assert.Equal(t, "/open-apis/wiki/v2/spaces/get_node", gjson.Get(result.Stdout, "api.0.url").String())
+		assert.Equal(t, "wikcnABC123", gjson.Get(result.Stdout, "api.0.params.token").String())
+
+		assert.Equal(t, "POST", gjson.Get(result.Stdout, "api.1.method").String())
+		assert.Equal(t, "/open-apis/wiki/v2/spaces/123456/nodes", gjson.Get(result.Stdout, "api.1.url").String())
+		assert.Equal(t, "wikcnABC123", gjson.Get(result.Stdout, "api.1.body.parent_node_token").String())
+	})
+
+	t.Run("HappyPath_ShortcutNodeType", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		t.Cleanup(cancel)
+
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"wiki", "+node-create",
+				"--space-id", "123456",
+				"--node-type", "shortcut",
+				"--origin-node-token", "wikcnORIG",
+				"--title", "ShortcutDoc",
+				"--obj-type", "docx",
+				"--dry-run",
+			},
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+
+		assert.Equal(t, "shortcut", gjson.Get(result.Stdout, "api.0.body.node_type").String())
+		assert.Equal(t, "wikcnORIG", gjson.Get(result.Stdout, "api.0.body.origin_node_token").String())
+	})
+
+	t.Run("RejectsShortcutWithoutOriginNodeToken", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		t.Cleanup(cancel)
+
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"wiki", "+node-create",
+				"--space-id", "123456",
+				"--node-type", "shortcut",
+				"--dry-run",
+			},
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 2)
+		msg := validateWikiErrorMessage(result)
+		assert.Contains(t, msg, "--origin-node-token is required")
+	})
+
+	t.Run("RejectsOriginNodeTokenWithoutShortcutType", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		t.Cleanup(cancel)
+
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"wiki", "+node-create",
+				"--space-id", "123456",
+				"--origin-node-token", "wikcnORIG",
+				"--dry-run",
+			},
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 2)
+		msg := validateWikiErrorMessage(result)
+		assert.Contains(t, msg, "--origin-node-token can only be used when --node-type=shortcut")
+	})
+
+	t.Run("RejectsBotWithoutSpaceIDOrParentNodeToken", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		t.Cleanup(cancel)
+
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"wiki", "+node-create",
+				"--dry-run",
+			},
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 2)
+		msg := validateWikiErrorMessage(result)
+		assert.Contains(t, msg, "bot identity requires --space-id or --parent-node-token")
+	})
+
+	t.Run("RejectsBotWithMyLibrarySpaceID", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		t.Cleanup(cancel)
+
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"wiki", "+node-create",
+				"--space-id", "my_library",
+				"--dry-run",
+			},
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 2)
+		msg := validateWikiErrorMessage(result)
+		assert.Contains(t, msg, "bot identity does not support --space-id my_library")
+	})
+
+	t.Run("RejectsInvalidObjType", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		t.Cleanup(cancel)
+
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"wiki", "+node-create",
+				"--space-id", "123456",
+				"--obj-type", "pdf",
+				"--dry-run",
+			},
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 2)
+		msg := validateWikiErrorMessage(result)
+		assert.Contains(t, msg, `"pdf"`)
+		assert.Contains(t, msg, "invalid value")
+	})
+}
+
+func validateWikiErrorMessage(r *clie2e.Result) string {
+	if msg := gjson.Get(r.Stdout, "error.message").String(); msg != "" {
+		return msg
+	}
+	if msg := gjson.Get(r.Stderr, "error.message").String(); msg != "" {
+		return msg
+	}
+	return r.Stdout + r.Stderr
+}