chore: release v1.0.53 (#1443)

]

.github/CODEOWNERS

@@ -0,0 +1,30 @@
+/internal/ @liangshuo-1
+
+# Last match wins: existing domains below are exempt, only new skills/ entries need review.
+/skills/ @liangshuo-1
+/skills/lark-approval/
+/skills/lark-apps/
+/skills/lark-attendance/
+/skills/lark-base/
+/skills/lark-calendar/
+/skills/lark-contact/
+/skills/lark-doc/
+/skills/lark-drive/
+/skills/lark-event/
+/skills/lark-im/
+/skills/lark-mail/
+/skills/lark-markdown/
+/skills/lark-minutes/
+/skills/lark-okr/
+/skills/lark-openapi-explorer/
+/skills/lark-shared/
+/skills/lark-sheets/
+/skills/lark-skill-maker/
+/skills/lark-slides/
+/skills/lark-task/
+/skills/lark-vc/
+/skills/lark-vc-agent/
+/skills/lark-whiteboard/
+/skills/lark-wiki/
+/skills/lark-workflow-meeting-summary/
+/skills/lark-workflow-standup-report/

.gitignore

@@ -35,6 +35,8 @@ tests/mail/reports/
 # Generated / test artifacts
 .hammer/
 .lark-slides/
+/notes/
+/minutes/
 internal/registry/meta_data.json
 cmd/api/download.bin
 app.log

.golangci.yml

@@ -73,20 +73,20 @@ linters:
           - forbidigo
       # errs-typed-only enforced on paths already migrated to errs.NewXxxError.
       # Add a path when its migration is complete.
-      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|internal/event/consume/|cmd/event/|events/|shortcuts/event/)
+      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/apps/|shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/|internal/event/consume/|cmd/event/|events/|shortcuts/event/)
         text: errs-typed-only
         linters:
           - forbidigo
       # errs-no-bare-wrap enforced on paths fully migrated to typed final
       # errors. Scoped separately from errs-typed-only because cmd/auth/,
       # cmd/config/ still have residual fmt.Errorf and must not be caught.
-      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/common/mcp_client\.go|cmd/event/|events/|shortcuts/event/)
+      - path-except: (shortcuts/apps/|shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/|shortcuts/common/mcp_client\.go|cmd/event/|events/|shortcuts/event/)
         text: errs-no-bare-wrap
         linters:
           - forbidigo
       # errs-no-legacy-helper enforced on domains whose shared validation/save
       # helpers have migrated to typed final errors.
-      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|cmd/event/|events/|shortcuts/event/)
+      - path-except: (shortcuts/apps/|shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/|cmd/event/|events/|shortcuts/event/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo

.goreleaser.yml

@@ -17,6 +17,7 @@ builds:
     goarch:
       - amd64
       - arm64
+      - riscv64
 
 archives:
   - name_template: "lark-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"

AGENTS.md

@@ -11,7 +11,7 @@
 
 ```bash
 make build          # Build (runs fetch_meta first)
-make unit-test      # Required before PR (runs with -race)
+make unit-test      # Required before PR (runs with -race where supported, e.g. amd64/arm64)
 make test           # Full: vet + unit + integration
 ```
 

CHANGELOG.md

@@ -2,6 +2,89 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.53] - 2026-06-12
+
+### Features
+
+- **auth**: Revoke user tokens server-side on `auth logout` (#1434)
+- **auth**: Add `--json` flag support to auth subcommands (#1431)
+- **token**: Mint TAT via unified OAuth v3 Token Endpoint (#1408)
+- **note**: Split note into a dedicated domain with `+detail` and `+transcript` flows (#1345, #1417, #1435)
+- **im**: Unify sort flags into `--sort` field and `--order` direction (#1302)
+
+### Bug Fixes
+
+- **apps**: Read release error_logs from `data.error_logs` in `+release-get` (#1436)
+
+### Documentation
+
+- **skills**: Optimize whiteboard skill (#1371)
+- **skills**: Optimize okr skill (#1368)
+
+## [v1.0.52] - 2026-06-11
+
+### Features
+
+- **events**: Per-resource subscription identity + Match hook (#1185)
+- **apps**: Emit typed error envelopes across the apps domain (#1288)
+- **wiki**: Emit typed error envelopes across the wiki domain (#1350)
+- **im**: Add `--chat-modes` filter to chat search (#1317)
+- **apps**: Exclude `.git` directory from `+html-publish` package (#1396)
+- **build**: Support riscv64 prebuilt binaries in release and install pipeline
+
+### Bug Fixes
+
+- **apps**: Support git credential dry-run (#1390)
+- **whiteboard**: Fix parsing empty whiteboard content (#1391)
+- **build**: Make `-race` flag arch-conditional to support riscv64
+
+### Documentation
+
+- **im**: Document `chat.user_setting` batch_query/batch_update (#1339)
+- **im**: Document `chat.managers` and `chat.moderation` API resources (#1294)
+- **skills**: Optimize lark-drive skill routing (#1284)
+- **skills**: Expand cite user guidance and fix typos (#1394)
+
+## [v1.0.51] - 2026-06-10
+
+### Features
+
+- **apps**: Support multi dev modes (#1175)
+- **im**: Complete audio/post rendering and add opt-in `--download-resources` (#1245)
+- **base**: Configure initial base table schema (#1377)
+- **vc**: Add recording event support (#1369)
+- **minutes**: Replace words for transcript (#1372)
+- **markdown**: Emit typed error envelopes across the markdown domain (#1347)
+- **sheets**: Emit typed error envelopes across the sheets domain (#1348)
+- **slides**: Emit typed error envelopes across the slides domain (#1349)
+
+### Documentation
+
+- **skills**: Warn about `@file` absolute path restriction in lark-doc skills (#1375)
+- **skills**: Remove unsupported ⚠️ from callout emoji list (#1374)
+
+## [v1.0.50] - 2026-06-09
+
+### Features
+
+- **doc**: Emit typed error envelopes across the doc domain (#1346)
+- **event**: Emit typed error envelopes across the event domain (#1289)
+- **contact**: Emit typed error envelopes across the contact domain (#1287)
+- **sheets**: Guard `+csv-put --csv` against a path passed without `@` (#1337)
+- **cli**: Adjust agent timeout hint output conditions (#1328)
+
+### Bug Fixes
+
+- **drive**: Add `@file`/stdin support to `+add-comment --content` (#1343)
+- **slides**: Build create URL locally instead of drive metas call (#1329)
+- **cli**: Clarify `--block-id` supports comma-separated batch delete in help text (#1336)
+
+### Documentation
+
+- **doc**: Replace append with `block_insert_after` in skeleton workflow guidance (#1340)
+- **doc**: Document `<folder-manager>` resource block (#1168)
+- **drive**: Add drive comment location guidance (#1258)
+
 ## [v1.0.49] - 2026-06-08
 
 ### Features
@@ -1066,6 +1149,10 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.53]: https://github.com/larksuite/cli/releases/tag/v1.0.53
+[v1.0.52]: https://github.com/larksuite/cli/releases/tag/v1.0.52
+[v1.0.51]: https://github.com/larksuite/cli/releases/tag/v1.0.51
+[v1.0.50]: https://github.com/larksuite/cli/releases/tag/v1.0.50
 [v1.0.49]: https://github.com/larksuite/cli/releases/tag/v1.0.49
 [v1.0.48]: https://github.com/larksuite/cli/releases/tag/v1.0.48
 [v1.0.47]: https://github.com/larksuite/cli/releases/tag/v1.0.47

Makefile

@@ -8,6 +8,13 @@ DATE     := $(shell date +%Y-%m-%d)
 LDFLAGS  := -s -w -X $(MODULE)/internal/build.Version=$(VERSION) -X $(MODULE)/internal/build.Date=$(DATE)
 PREFIX   ?= /usr/local
 
+# The repository's Go 1.23 CI toolchain does not support -race on riscv64.
+# Prefer GOARCH passed to make (for example, `make GOARCH=riscv64 unit-test`)
+# over `go env GOARCH`, because command-line make variables are not visible to
+# $(shell ...).
+TEST_GOARCH := $(or $(GOARCH),$(shell go env GOARCH))
+RACE_FLAG := $(if $(filter riscv64,$(TEST_GOARCH)),,-race)
+
 .PHONY: all build vet fmt-check test unit-test integration-test examples-build install uninstall clean fetch_meta gitleaks
 
 all: test
@@ -34,7 +41,7 @@ fmt-check:
 
 # ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta
-	go test -race -gcflags="all=-N -l" -count=1 \
+	go test $(RACE_FLAG) -gcflags="all=-N -l" -count=1 \
 		./cmd/... ./internal/... ./shortcuts/... ./extension/...
 
 # examples-build keeps the shipped plugin-SDK examples compilable. If this

README.md

@@ -41,7 +41,7 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
 | ✍️ Approval   | Query approval tasks, approve/reject/transfer tasks, cancel and CC instances                                                      |
 | 🎯 OKR        | Query, create, update OKRs; manage objective & key results, alignments, indicators and progress.                                  |
 | 📋 Project    | Meegle — manage work items, schedules, and data via the standalone [meegle-cli](https://github.com/larksuite/meegle-cli) (install separately) |
-| 🔗 Apps       | Develop, deploy HTML, web pages and applications                                                                                  |
+| 🔗 Apps       | Create Spark/Miaoda apps, publish HTML/static sites, run cloud generation, and manage access scope                                 |
 
 ## Installation & Quick Start
 

README.zh.md

@@ -41,7 +41,7 @@
 | ✍️ 审批     | 查询审批任务、同意/拒绝/转交审批任务、撤回与抄送审批实例              |
 | 🎯 OKR  | 查询、创建、更新 OKR，管理目标、关键结果、对齐、指标和进展记录        |
 | 📋 飞书项目 | 管理工作项、排期与数据 — 由独立的 [meegle-cli](https://github.com/larksuite/meegle-cli) 提供（需单独安装） |
-| 🔗 应用     | 开发、部署 HTML、Web 页面和应用                                                                                                          |
+| 🔗 应用     | 创建妙搭（Spark/Miaoda）应用、发布 HTML/静态站点、云端生成迭代、管理可用范围                                                                                                   |
 
 ## 安装与快速开始
 

cmd/auth/auth_test.go

@@ -91,6 +91,29 @@ func TestAuthCheckCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthCheckCmd_AcceptsJSONFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *CheckOptions
+	cmd := NewCmdAuthCheck(f, func(opts *CheckOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--scope", "calendar:calendar:read", "--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Fatal("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+}
+
 func TestAuthLogoutCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 
@@ -109,6 +132,27 @@ func TestAuthLogoutCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthLogoutCmd_AcceptsJSONFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	var gotOpts *LogoutOptions
+	cmd := NewCmdAuthLogout(f, func(opts *LogoutOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Fatal("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+}
+
 func TestAuthListCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, nil)
 
@@ -126,6 +170,27 @@ func TestAuthListCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthListCmd_AcceptsJSONFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	var gotOpts *ListOptions
+	cmd := NewCmdAuthList(f, func(opts *ListOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Error("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+}
+
 func TestAuthStatusCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -145,6 +210,29 @@ func TestAuthStatusCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthStatusCmd_AcceptsJSONFlag(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *StatusOptions
+	cmd := NewCmdAuthStatus(f, func(opts *StatusOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Error("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+}
+
 func TestAuthStatusCmd_VerifyFlag(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
@@ -267,6 +355,32 @@ func TestAuthScopesCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestAuthScopesCmd_JSONFlagForcesJSONFormat(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	var gotOpts *ScopesOptions
+	cmd := NewCmdAuthScopes(f, func(opts *ScopesOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--format", "pretty", "--json"})
+	err := cmd.Execute()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotOpts == nil {
+		t.Fatal("expected opts to be set")
+	}
+	if !gotOpts.JSON {
+		t.Error("expected JSON=true")
+	}
+	if gotOpts.Format != "json" {
+		t.Errorf("expected format json, got %s", gotOpts.Format)
+	}
+}
+
 func TestAuthScopesRun_UsesTenantAccessTokenFromCredentialProvider(t *testing.T) {
 	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "", Brand: core.BrandFeishu,

cmd/auth/check.go

@@ -19,6 +19,7 @@ import (
 type CheckOptions struct {
 	Factory *cmdutil.Factory
 	Scope   string
+	JSON    bool
 }
 
 // NewCmdAuthCheck creates the auth check subcommand.
@@ -37,6 +38,7 @@ func NewCmdAuthCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.
 	}
 
 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to check (space-separated)")
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmd.MarkFlagRequired("scope")
 	cmdutil.SetRisk(cmd, "read")
 

cmd/auth/list.go

@@ -18,6 +18,7 @@ import (
 // ListOptions holds all inputs for auth list.
 type ListOptions struct {
 	Factory *cmdutil.Factory
+	JSON    bool
 }
 
 // NewCmdAuthList creates the auth list subcommand.
@@ -34,6 +35,7 @@ func NewCmdAuthList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Co
 			return authListRun(opts)
 		},
 	}
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")
 
 	return cmd
@@ -44,6 +46,14 @@ func authListRun(opts *ListOptions) error {
 
 	multi, _ := core.LoadMultiAppConfig()
 	if multi == nil || len(multi.Apps) == 0 {
+		if opts.JSON {
+			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+				"ok":     true,
+				"users":  []map[string]interface{}{},
+				"reason": "not_configured",
+			})
+			return nil
+		}
 		// auth list is a read-only probe; the "configured but no users"
 		// branch below already returns exit 0 with a stderr hint, so we
 		// keep the same contract here. We still want the hint to be
@@ -61,6 +71,14 @@ func authListRun(opts *ListOptions) error {
 
 	app := multi.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil || len(app.Users) == 0 {
+		if opts.JSON {
+			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+				"ok":     true,
+				"users":  []map[string]interface{}{},
+				"reason": "not_logged_in",
+			})
+			return nil
+		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "No logged-in users. Run `lark-cli auth login` to log in.")
 		return nil
 	}

cmd/auth/list_test.go

@@ -4,6 +4,7 @@
 package auth
 
 import (
+	"encoding/json"
 	"strings"
 	"testing"
 
@@ -34,6 +35,33 @@ func TestAuthListRun_NotConfigured_ReturnsExitZero(t *testing.T) {
 	}
 }
 
+func TestAuthListRun_JSONMode_NotConfigured_WritesStdoutOnly(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authListRun(&ListOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("auth list should succeed when not configured (exit 0); got: %v", err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
+	}
+	if payload["ok"] != true {
+		t.Errorf("stdout.ok = %v, want true", payload["ok"])
+	}
+	users, ok := payload["users"].([]any)
+	if !ok || len(users) != 0 {
+		t.Errorf("stdout.users = %v, want empty array", payload["users"])
+	}
+	if payload["reason"] != "not_configured" {
+		t.Errorf("stdout.reason = %v, want not_configured", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
 // TestAuthListRun_NotConfigured_AgentWorkspace_RoutesToBindHelp covers the
 // reason this hint exists workspace-aware in the first place: an AI agent
 // in OpenClaw / Hermes that probes auth list before binding gets routed to
@@ -57,3 +85,48 @@ func TestAuthListRun_NotConfigured_AgentWorkspace_RoutesToBindHelp(t *testing.T)
 		t.Errorf("agent hint must not mention config init: %s", out)
 	}
 }
+
+func TestAuthListRun_JSONMode_NoLoggedInUsers_WritesStdoutOnly(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, nil)
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authListRun(&ListOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("auth list should succeed when no users exist (exit 0); got: %v", err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
+	}
+	if payload["ok"] != true {
+		t.Errorf("stdout.ok = %v, want true", payload["ok"])
+	}
+	users, ok := payload["users"].([]any)
+	if !ok || len(users) != 0 {
+		t.Errorf("stdout.users = %v, want empty array", payload["users"])
+	}
+	if payload["reason"] != "not_logged_in" {
+		t.Errorf("stdout.reason = %v, want not_logged_in", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
+func TestAuthListRun_DefaultMode_NoLoggedInUsers_KeepsTextOutput(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, nil)
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authListRun(&ListOptions{Factory: f}); err != nil {
+		t.Fatalf("auth list should succeed when no users exist (exit 0); got: %v", err)
+	}
+
+	if stdout.Len() != 0 {
+		t.Errorf("stdout must stay empty in default mode, got:\n%s", stdout.String())
+	}
+	if !strings.Contains(stderr.String(), "No logged-in users") {
+		t.Errorf("stderr = %q, want no-users hint", stderr.String())
+	}
+}

cmd/auth/login_messages.go

@@ -128,5 +128,5 @@ func getLoginMsg(lang i18n.Lang) *loginMsg {
 // (not backed by from_meta service specs). Descriptions are now centralized in
 // service_descriptions.json.
 func getShortcutOnlyDomainNames() []string {
-	return []string{"base", "contact", "docs", "markdown", "apps"}
+	return []string{"base", "contact", "docs", "markdown", "apps", "note"}
 }

cmd/auth/login_test.go

@@ -9,6 +9,7 @@ import (
 	"errors"
 	"io"
 	"net/http"
+	"slices"
 	"sort"
 	"strings"
 	"testing"
@@ -214,6 +215,12 @@ func TestGetShortcutOnlyDomainNames_HaveDescriptions(t *testing.T) {
 	}
 }
 
+func TestGetShortcutOnlyDomainNames_IncludesNote(t *testing.T) {
+	if !slices.Contains(getShortcutOnlyDomainNames(), "note") {
+		t.Fatal("shortcut-only domains must include note so auth login can select vc:note:read")
+	}
+}
+
 func TestCollectScopesForDomains(t *testing.T) {
 	projects := registry.ListFromMetaProjects()
 	if len(projects) == 0 {

cmd/auth/logout.go

@@ -18,6 +18,7 @@ import (
 // LogoutOptions holds all inputs for auth logout.
 type LogoutOptions struct {
 	Factory *cmdutil.Factory
+	JSON    bool
 }
 
 // NewCmdAuthLogout creates the auth logout subcommand.
@@ -34,6 +35,7 @@ func NewCmdAuthLogout(f *cmdutil.Factory, runF func(*LogoutOptions) error) *cobr
 			return authLogoutRun(opts)
 		},
 	}
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "write")
 
 	return cmd
@@ -44,25 +46,65 @@ func authLogoutRun(opts *LogoutOptions) error {
 
 	multi, _ := core.LoadMultiAppConfig()
 	if multi == nil || len(multi.Apps) == 0 {
+		if opts.JSON {
+			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+				"ok":        true,
+				"loggedOut": false,
+				"reason":    "not_configured",
+			})
+			return nil
+		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "No configuration found.")
 		return nil
 	}
 
 	app := multi.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil || len(app.Users) == 0 {
+		if opts.JSON {
+			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+				"ok":        true,
+				"loggedOut": false,
+				"reason":    "not_logged_in",
+			})
+			return nil
+		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "Not logged in.")
 		return nil
 	}
 
+	httpClient, httpErr := f.HttpClient()
+	appSecret, secretErr := core.ResolveSecretInput(app.AppSecret, f.Keychain)
+
 	for _, user := range app.Users {
+		if httpErr == nil && secretErr == nil {
+			if token := larkauth.GetStoredToken(app.AppId, user.UserOpenId); token != nil {
+				revokeToken := token.RefreshToken
+				tokenTypeHint := "refresh_token"
+				if revokeToken == "" {
+					revokeToken = token.AccessToken
+					tokenTypeHint = "access_token"
+				}
+				if revokeToken != "" {
+					_ = larkauth.RevokeToken(httpClient, app.AppId, appSecret, app.Brand, revokeToken, tokenTypeHint)
+				}
+			}
+		}
 		if err := larkauth.RemoveStoredToken(app.AppId, user.UserOpenId); err != nil {
 			fmt.Fprintf(f.IOStreams.ErrOut, "Warning: failed to remove token for %s: %v\n", user.UserOpenId, err)
 		}
 	}
+
 	app.Users = []core.AppUser{}
 	if err := core.SaveMultiAppConfig(multi); err != nil {
 		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
 	}
+	if opts.JSON {
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+			"ok":        true,
+			"loggedOut": true,
+		})
+		return nil
+	}
 	output.PrintSuccess(f.IOStreams.ErrOut, "Logged out")
 	return nil
 }

cmd/auth/logout_test.go

@@ -0,0 +1,356 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"encoding/json"
+	"net/url"
+	"strings"
+	"testing"
+
+	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/zalando/go-keyring"
+)
+
+func writeLogoutConfig(t *testing.T, users []core.AppUser) {
+	t.Helper()
+	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
+		CurrentApp: "test-app",
+		Apps: []core.AppConfig{
+			{
+				AppId:     "test-app",
+				AppSecret: core.PlainSecret("test-secret"),
+				Brand:     core.BrandFeishu,
+				Users:     users,
+			},
+		},
+	}); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+}
+
+func TestAuthLogoutRun_JSONMode_NotConfigured_WritesStdoutOnly(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
+	}
+	if payload["ok"] != true {
+		t.Errorf("stdout.ok = %v, want true", payload["ok"])
+	}
+	if payload["loggedOut"] != false {
+		t.Errorf("stdout.loggedOut = %v, want false", payload["loggedOut"])
+	}
+	if payload["reason"] != "not_configured" {
+		t.Errorf("stdout.reason = %v, want not_configured", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
+func TestAuthLogoutRun_JSONMode_NotLoggedIn_WritesStdoutOnly(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, nil)
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
+	}
+	if payload["ok"] != true {
+		t.Errorf("stdout.ok = %v, want true", payload["ok"])
+	}
+	if payload["loggedOut"] != false {
+		t.Errorf("stdout.loggedOut = %v, want false", payload["loggedOut"])
+	}
+	if payload["reason"] != "not_logged_in" {
+		t.Errorf("stdout.reason = %v, want not_logged_in", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
+func TestAuthLogoutRun_JSONMode_Success_WritesStdoutOnly(t *testing.T) {
+	keyring.MockInit()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}})
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:      "test-app",
+		UserOpenId: "ou_user",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
+	}
+	if payload["ok"] != true {
+		t.Errorf("stdout.ok = %v, want true", payload["ok"])
+	}
+	if payload["loggedOut"] != true {
+		t.Errorf("stdout.loggedOut = %v, want true", payload["loggedOut"])
+	}
+	if _, hasReason := payload["reason"]; hasReason {
+		t.Errorf("stdout.reason must be absent on success, got %v", payload["reason"])
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
+	}
+}
+
+func TestAuthLogoutRun_DefaultMode_KeepsTextOutput(t *testing.T) {
+	keyring.MockInit()
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	writeLogoutConfig(t, []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}})
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:      "test-app",
+		UserOpenId: "ou_user",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	if stdout.Len() != 0 {
+		t.Errorf("stdout must stay empty in default mode, got:\n%s", stdout.String())
+	}
+	if !strings.Contains(stderr.String(), "Logged out") {
+		t.Errorf("stderr = %q, want success text", stderr.String())
+	}
+}
+
+func TestAuthLogoutRun_RevokesTokenAndClearsLocalState(t *testing.T) {
+	keyring.MockInit()
+	setupLoginConfigDir(t)
+	t.Setenv("HOME", t.TempDir())
+
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{
+				Name:      "default",
+				AppId:     "cli_test",
+				AppSecret: core.PlainSecret("secret"),
+				Brand:     core.BrandFeishu,
+				Users:     []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}},
+			},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:        "cli_test",
+		UserOpenId:   "ou_user",
+		AccessToken:  "user-access-token",
+		RefreshToken: "user-refresh-token",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		ProfileName: "default",
+		AppID:       "cli_test",
+		AppSecret:   "secret",
+		Brand:       core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    larkauth.PathOAuthRevoke,
+		Body:   map[string]interface{}{"code": 0},
+		BodyFilter: func(body []byte) bool {
+			values, err := url.ParseQuery(string(body))
+			if err != nil {
+				return false
+			}
+			return values.Get("client_id") == "cli_test" &&
+				values.Get("client_secret") == "secret" &&
+				values.Get("token") == "user-refresh-token" &&
+				values.Get("token_type_hint") == "refresh_token"
+		},
+	})
+
+	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	if got := stderr.String(); !strings.Contains(got, "Logged out") {
+		t.Fatalf("stderr = %q, want Logged out", got)
+	}
+	if got := larkauth.GetStoredToken("cli_test", "ou_user"); got != nil {
+		t.Fatalf("expected stored token removed, got %#v", got)
+	}
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if len(saved.Apps) != 1 || len(saved.Apps[0].Users) != 0 {
+		t.Fatalf("expected users cleared, got %#v", saved.Apps)
+	}
+}
+
+func TestAuthLogoutRun_FallsBackToAccessTokenWhenRefreshTokenMissing(t *testing.T) {
+	keyring.MockInit()
+	setupLoginConfigDir(t)
+	t.Setenv("HOME", t.TempDir())
+
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{
+				Name:      "default",
+				AppId:     "cli_test",
+				AppSecret: core.PlainSecret("secret"),
+				Brand:     core.BrandFeishu,
+				Users:     []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}},
+			},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:       "cli_test",
+		UserOpenId:  "ou_user",
+		AccessToken: "user-access-token",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		ProfileName: "default",
+		AppID:       "cli_test",
+		AppSecret:   "secret",
+		Brand:       core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    larkauth.PathOAuthRevoke,
+		Body:   map[string]interface{}{"code": 0},
+		BodyFilter: func(body []byte) bool {
+			values, err := url.ParseQuery(string(body))
+			if err != nil {
+				return false
+			}
+			return values.Get("client_id") == "cli_test" &&
+				values.Get("client_secret") == "secret" &&
+				values.Get("token") == "user-access-token" &&
+				values.Get("token_type_hint") == "access_token"
+		},
+	})
+
+	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	if got := stderr.String(); !strings.Contains(got, "Logged out") {
+		t.Fatalf("stderr = %q, want Logged out", got)
+	}
+	if got := larkauth.GetStoredToken("cli_test", "ou_user"); got != nil {
+		t.Fatalf("expected stored token removed, got %#v", got)
+	}
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if len(saved.Apps) != 1 || len(saved.Apps[0].Users) != 0 {
+		t.Fatalf("expected users cleared, got %#v", saved.Apps)
+	}
+}
+
+func TestAuthLogoutRun_RevokeFailureStillClearsLocalState(t *testing.T) {
+	keyring.MockInit()
+	setupLoginConfigDir(t)
+	t.Setenv("HOME", t.TempDir())
+
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{
+				Name:      "default",
+				AppId:     "cli_test",
+				AppSecret: core.PlainSecret("secret"),
+				Brand:     core.BrandFeishu,
+				Users:     []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}},
+			},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
+		AppId:        "cli_test",
+		UserOpenId:   "ou_user",
+		AccessToken:  "user-access-token",
+		RefreshToken: "user-refresh-token",
+	}); err != nil {
+		t.Fatalf("SetStoredToken() error = %v", err)
+	}
+
+	f, _, stderr, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		ProfileName: "default",
+		AppID:       "cli_test",
+		AppSecret:   "secret",
+		Brand:       core.BrandFeishu,
+	})
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    larkauth.PathOAuthRevoke,
+		Status: 500,
+		Body:   map[string]interface{}{"error": "server_error"},
+	})
+
+	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
+		t.Fatalf("authLogoutRun() error = %v", err)
+	}
+
+	gotErr := stderr.String()
+	if strings.Contains(gotErr, "failed to revoke token for ou_user") {
+		t.Fatalf("stderr = %q, want no revoke warning", gotErr)
+	}
+	if !strings.Contains(gotErr, "Logged out") {
+		t.Fatalf("stderr = %q, want Logged out", gotErr)
+	}
+	if got := larkauth.GetStoredToken("cli_test", "ou_user"); got != nil {
+		t.Fatalf("expected stored token removed, got %#v", got)
+	}
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if len(saved.Apps) != 1 || len(saved.Apps[0].Users) != 0 {
+		t.Fatalf("expected users cleared, got %#v", saved.Apps)
+	}
+}

cmd/auth/scopes.go

@@ -19,6 +19,7 @@ type ScopesOptions struct {
 	Factory *cmdutil.Factory
 	Ctx     context.Context
 	Format  string
+	JSON    bool
 }
 
 // NewCmdAuthScopes creates the auth scopes subcommand.
@@ -30,6 +31,9 @@ func NewCmdAuthScopes(f *cmdutil.Factory, runF func(*ScopesOptions) error) *cobr
 		Short: "Query scopes enabled for the app",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
+			if opts.JSON {
+				opts.Format = "json"
+			}
 			if runF != nil {
 				return runF(opts)
 			}
@@ -38,6 +42,7 @@ func NewCmdAuthScopes(f *cmdutil.Factory, runF func(*ScopesOptions) error) *cobr
 	}
 
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json (default) | pretty")
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")
 
 	return cmd

cmd/auth/status.go

@@ -17,6 +17,7 @@ import (
 type StatusOptions struct {
 	Factory *cmdutil.Factory
 	Verify  bool
+	JSON    bool
 }
 
 // NewCmdAuthStatus creates the auth status subcommand.
@@ -35,6 +36,7 @@ func NewCmdAuthStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobr
 	}
 
 	cmd.Flags().BoolVar(&opts.Verify, "verify", false, "verify token against server (requires network)")
+	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "read")
 
 	return cmd

cmd/config/init_probe.go

@@ -33,15 +33,16 @@ const probeTimeout = 3 * time.Second
 //
 //  1. A TAT request using the just-saved credentials. credential.FetchTAT
 //     returns a typed errs.* error (via the shared classifyTATResponseCode)
-//     only when the server deterministically rejected the credentials — a
-//     non-zero TAT body code, classified as CategoryConfig / SubtypeInvalidClient
-//     (10003 / 10014) or whatever codemeta maps. That typed error is propagated
-//     so the root dispatcher renders the canonical envelope and `config init`
-//     exits non-zero — identical to how every other token-resolving command
-//     reports the same bad credentials. Ambiguous failures (transport errors,
-//     HTTP non-200, JSON parse errors, timeouts) come back as raw untyped
-//     errors and are swallowed (return nil), so valid configurations are never
-//     disturbed by upstream noise. errs.IsTyped is the discriminator.
+//     only when the unified Token Endpoint deterministically rejected the
+//     credentials — an OAuth2 invalid_client / unauthorized_client classified as
+//     CategoryConfig / SubtypeInvalidClient, or whatever codemeta maps. That
+//     typed error is propagated so the root dispatcher renders the canonical
+//     envelope and `config init` exits non-zero — identical to how every other
+//     token-resolving command reports the same bad credentials. Ambiguous
+//     failures (transport errors, transient 5xx/server_error, JSON parse errors,
+//     timeouts) come back as raw untyped errors and are swallowed (return nil),
+//     so valid configurations are never disturbed by upstream noise.
+//     errs.IsTyped is the discriminator.
 //
 //  2. If TAT succeeded, a POST to the probe endpoint is fired. The outcome of
 //     that call (success, server error, timeout, parse failure) is always

cmd/config/init_probe_test.go

@@ -31,10 +31,10 @@ type fakeRT struct {
 
 func (f *fakeRT) RoundTrip(req *http.Request) (*http.Response, error) {
 	switch {
-	case strings.HasSuffix(req.URL.Path, "/auth/v3/tenant_access_token/internal"):
+	case strings.HasSuffix(req.URL.Path, "/oauth/v3/token"):
 		f.tatCalls++
 		if f.tatHandler == nil {
-			return jsonResp(200, `{"code":0,"tenant_access_token":"t-ok"}`), nil
+			return jsonResp(200, `{"code":0,"access_token":"t-ok","token_type":"Bearer"}`), nil
 		}
 		return f.tatHandler(req)
 	case strings.HasSuffix(req.URL.Path, "/application/v6/larksuite_cli_app/probe"):
@@ -84,14 +84,15 @@ func fakeFactory(t *testing.T, rt http.RoundTripper) (*cmdutil.Factory, *bytes.B
 }
 
 // assertConfigRejection asserts runProbe propagated a deterministic credential
-// rejection: a *errs.ConfigError (CategoryConfig / SubtypeInvalidClient) with
-// the expected upstream code. This is the same typed error every other
-// token-resolving command returns for the same bad credentials, and nothing is
-// written to stderr (the root dispatcher renders the envelope).
-func assertConfigRejection(t *testing.T, err error, errBuf *bytes.Buffer, wantCode int) {
+// rejection: a *errs.ConfigError (CategoryConfig / SubtypeInvalidClient). This
+// is the same typed error every other token-resolving command returns for the
+// same bad credentials, and nothing is written to stderr (the root dispatcher
+// renders the envelope). The numeric code is not asserted: the unified v3 Token
+// Endpoint reports invalid_client via the OAuth2 error string, not a Lark code.
+func assertConfigRejection(t *testing.T, err error, errBuf *bytes.Buffer) {
 	t.Helper()
 	if err == nil {
-		t.Fatalf("expected *errs.ConfigError (code %d), got nil", wantCode)
+		t.Fatal("expected *errs.ConfigError, got nil")
 	}
 	var cfgErr *errs.ConfigError
 	if !errors.As(err, &cfgErr) {
@@ -103,9 +104,6 @@ func assertConfigRejection(t *testing.T, err error, errBuf *bytes.Buffer, wantCo
 	if cfgErr.Subtype != errs.SubtypeInvalidClient {
 		t.Errorf("Subtype = %q, want %q", cfgErr.Subtype, errs.SubtypeInvalidClient)
 	}
-	if cfgErr.Code != wantCode {
-		t.Errorf("Code = %d, want %d", cfgErr.Code, wantCode)
-	}
 	if errBuf.Len() != 0 {
 		t.Errorf("runProbe must not write to stderr, got: %q", errBuf.String())
 	}
@@ -123,11 +121,13 @@ func assertSilent(t *testing.T, err error, errBuf *bytes.Buffer) {
 	}
 }
 
-// 10003 (bad / non-existent app_id) → ConfigError/InvalidClient, propagated.
-func TestRunProbe_TATCode10003_ReturnsConfigError(t *testing.T) {
+// invalid_client (bad / non-existent app_id or wrong secret) → the v3 Token
+// Endpoint returns HTTP 400 with the OAuth2 error → ConfigError/InvalidClient,
+// propagated. The probe endpoint must not be called when TAT fails.
+func TestRunProbe_TATInvalidClient_ReturnsConfigError(t *testing.T) {
 	rt := &fakeRT{
 		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(200, `{"code":10003,"msg":"invalid param"}`), nil
+			return jsonResp(400, `{"error":"invalid_client","error_description":"The client secret is invalid.","code":20002}`), nil
 		},
 	}
 	f, errBuf := fakeFactory(t, rt)
@@ -137,28 +137,27 @@ func TestRunProbe_TATCode10003_ReturnsConfigError(t *testing.T) {
 	if rt.probeCalls != 0 {
 		t.Error("probe endpoint must not be called when TAT fails")
 	}
-	assertConfigRejection(t, err, errBuf, 10003)
+	assertConfigRejection(t, err, errBuf)
 }
 
-// 10014 (real app_id + wrong secret) → ConfigError/InvalidClient via codemeta —
-// the most common real-world rejection, propagated.
-func TestRunProbe_TATCode10014_ReturnsConfigError(t *testing.T) {
+// unauthorized_client is treated as the same credential rejection, propagated.
+func TestRunProbe_TATUnauthorizedClient_ReturnsConfigError(t *testing.T) {
 	rt := &fakeRT{
 		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(200, `{"code":10014,"msg":"app secret invalid"}`), nil
+			return jsonResp(401, `{"error":"unauthorized_client","error_description":"client not authorized"}`), nil
 		},
 	}
 	f, errBuf := fakeFactory(t, rt)
-	assertConfigRejection(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf, 10014)
+	assertConfigRejection(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
 }
 
-// Any non-zero body code is a deterministic rejection and propagates (typed).
-// An unrecognized code falls back to *errs.APIError via BuildAPIError — still
-// typed, so the probe still surfaces it rather than swallowing.
-func TestRunProbe_TATUnknownBodyCode_Propagates(t *testing.T) {
+// Any other deterministic client-side OAuth error (e.g. invalid_scope) falls
+// back to *errs.APIError via BuildAPIError — still typed, so the probe surfaces
+// it rather than swallowing — but is not a credential (ConfigError) rejection.
+func TestRunProbe_TATOtherClientError_Propagates(t *testing.T) {
 	rt := &fakeRT{
 		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(200, `{"code":99999,"msg":"future-unknown"}`), nil
+			return jsonResp(400, `{"code":20068,"error":"invalid_scope","error_description":"unauthorized scope"}`), nil
 		},
 	}
 	f, errBuf := fakeFactory(t, rt)

cmd/event/format_helpers_test.go

@@ -143,6 +143,79 @@ func TestWriteStatusText_CoversAllStates(t *testing.T) {
 	}
 }
 
+func TestWriteStatusText_ShowsSubColumn(t *testing.T) {
+	var buf bytes.Buffer
+	writeStatusText(&buf, []appStatus{
+		{
+			AppID:     "cli_RUNNINGXXXXXXXXX",
+			State:     stateRunning,
+			PID:       1234,
+			UptimeSec: 60,
+			Active:    2,
+			Consumers: []protocol.ConsumerInfo{
+				{PID: 1001, EventKey: "mail.x", SubscriptionID: "mail.x:alice", Received: 5, Dropped: 0},
+				{PID: 1002, EventKey: "mail.x", SubscriptionID: "mail.x:bob", Received: 3, Dropped: 0},
+			},
+		},
+	})
+	out := buf.String()
+	if !strings.Contains(out, "SUB") {
+		t.Errorf("missing SUB column header: %s", out)
+	}
+	if !strings.Contains(out, "alice") {
+		t.Errorf("missing alice suffix in SUB column: %s", out)
+	}
+	if !strings.Contains(out, "bob") {
+		t.Errorf("missing bob suffix in SUB column: %s", out)
+	}
+}
+
+func TestWriteStatusText_LegacySubscriptionID_RendersDash(t *testing.T) {
+	var buf bytes.Buffer
+	writeStatusText(&buf, []appStatus{
+		{
+			AppID:     "cli_RUNNINGXXXXXXXXX",
+			State:     stateRunning,
+			PID:       1234,
+			UptimeSec: 60,
+			Active:    1,
+			Consumers: []protocol.ConsumerInfo{
+				{PID: 1001, EventKey: "im.x", SubscriptionID: "", Received: 5},
+			},
+		},
+	})
+	out := buf.String()
+	if !strings.Contains(out, "SUB") {
+		t.Errorf("missing SUB header: %s", out)
+	}
+	if !strings.Contains(out, "-") {
+		t.Errorf("missing dash placeholder for empty SubscriptionID: %s", out)
+	}
+}
+
+func TestWriteStatusText_EventKeyEqualSubscriptionID_RendersDash(t *testing.T) {
+	var buf bytes.Buffer
+	writeStatusText(&buf, []appStatus{
+		{
+			AppID:     "cli_RUNNINGXXXXXXXXX",
+			State:     stateRunning,
+			PID:       1234,
+			UptimeSec: 60,
+			Active:    1,
+			Consumers: []protocol.ConsumerInfo{
+				{PID: 1001, EventKey: "im.x", SubscriptionID: "im.x", Received: 5},
+			},
+		},
+	})
+	out := buf.String()
+	if !strings.Contains(out, "SUB") {
+		t.Errorf("missing SUB header: %s", out)
+	}
+	if !strings.Contains(out, "-") {
+		t.Errorf("missing dash placeholder when SubscriptionID==EventKey: %s", out)
+	}
+}
+
 func TestWriteStatusJSON_OrphanHint(t *testing.T) {
 	var buf bytes.Buffer
 	if err := writeStatusJSON(&buf, []appStatus{

cmd/event/schema.go

@@ -134,12 +134,16 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 	if len(def.Params) > 0 {
 		fmt.Fprintf(out, "\nParameters:\n")
 		w := tabwriter.NewWriter(out, 0, 4, 2, ' ', 0)
-		fmt.Fprintf(w, "  NAME\tTYPE\tREQUIRED\tDEFAULT\tDESCRIPTION\n")
+		fmt.Fprintf(w, "  NAME\tTYPE\tREQUIRED\tSUB-KEY\tDEFAULT\tDESCRIPTION\n")
 		for _, p := range def.Params {
 			required := "no"
 			if p.Required {
 				required = "yes"
 			}
+			subKey := "no"
+			if p.SubscriptionKey {
+				subKey = "yes"
+			}
 			defaultVal := p.Default
 			if defaultVal == "" {
 				defaultVal = "-"
@@ -148,7 +152,7 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 			if desc == "" {
 				desc = "-"
 			}
-			fmt.Fprintf(w, "  %s\t%s\t%s\t%s\t%s\n", p.Name, p.Type, required, defaultVal, desc)
+			fmt.Fprintf(w, "  %s\t%s\t%s\t%s\t%s\t%s\n", p.Name, p.Type, required, subKey, defaultVal, desc)
 		}
 		w.Flush()
 

cmd/event/schema_test.go

@@ -96,6 +96,79 @@ func TestRunSchema_JSONOutput(t *testing.T) {
 	}
 }
 
+func TestSchema_RendersSubscriptionKeyMarker(t *testing.T) {
+	const syntheticKey = "test.evt_sub"
+	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })
+
+	eventlib.RegisterKey(eventlib.KeyDefinition{
+		Key:       syntheticKey,
+		EventType: syntheticKey,
+		Params: []eventlib.ParamDef{
+			{Name: "mailbox", SubscriptionKey: true, Description: "subscription id source"},
+			{Name: "folders", Description: "filter only"},
+		},
+		Schema: eventlib.SchemaDef{Native: &eventlib.SchemaSpec{Type: reflect.TypeOf(struct{ X string }{})}},
+	})
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
+	if err := runSchema(f, syntheticKey, false); err != nil {
+		t.Fatalf("runSchema: %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, "SUB-KEY") {
+		t.Errorf("missing SUB-KEY column header in:\n%s", out)
+	}
+
+	// Find the mailbox row and verify "yes" is present
+	var mailboxRow string
+	for _, ln := range strings.Split(out, "\n") {
+		if strings.Contains(ln, "mailbox") && !strings.Contains(ln, "NAME") {
+			mailboxRow = ln
+			break
+		}
+	}
+	if !strings.Contains(mailboxRow, "yes") {
+		t.Errorf("mailbox row missing yes SUB-KEY marker: %q", mailboxRow)
+	}
+
+	// Find the folders row and verify "no" is present
+	var foldersRow string
+	for _, ln := range strings.Split(out, "\n") {
+		if strings.Contains(ln, "folders") && !strings.Contains(ln, "NAME") {
+			foldersRow = ln
+			break
+		}
+	}
+	if !strings.Contains(foldersRow, "no") {
+		t.Errorf("folders row missing no SUB-KEY marker: %q", foldersRow)
+	}
+}
+
+func TestSchema_JSON_IncludesSubscriptionKey(t *testing.T) {
+	const syntheticKey = "test.evt_json"
+	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })
+
+	eventlib.RegisterKey(eventlib.KeyDefinition{
+		Key:       syntheticKey,
+		EventType: syntheticKey,
+		Params:    []eventlib.ParamDef{{Name: "mailbox", SubscriptionKey: true}},
+		Schema:    eventlib.SchemaDef{Native: &eventlib.SchemaSpec{Type: reflect.TypeOf(struct{ X string }{})}},
+	})
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
+	if err := runSchema(f, syntheticKey, true); err != nil {
+		t.Fatalf("runSchema json: %v", err)
+	}
+
+	if !strings.Contains(stdout.String(), `"subscription_key"`) {
+		t.Errorf("JSON output missing subscription_key field: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `true`) {
+		t.Errorf("JSON output missing subscription_key: true value: %s", stdout.String())
+	}
+}
+
 func TestResolveSchemaJSON_CustomWithOverlay(t *testing.T) {
 	const syntheticKey = "t.custom.overlay"
 	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })

cmd/event/status.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"sort"
+	"strings"
 	"sync"
 	"time"
 
@@ -242,12 +243,17 @@ func writeStatusText(out io.Writer, statuses []appStatus) {
 				s.PID, (time.Duration(s.UptimeSec) * time.Second).String())
 			fmt.Fprintf(out, "  Active consumers: %d\n", s.Active)
 			if len(s.Consumers) > 0 {
-				headers := []string{"CONSUMER", "EVENT KEY", "RECEIVED", "DROPPED"}
+				headers := []string{"CONSUMER", "EVENT KEY", "SUB", "RECEIVED", "DROPPED"}
 				rows := make([][]string, 0, len(s.Consumers))
 				for _, c := range s.Consumers {
+					subDisplay := "-"
+					if c.SubscriptionID != "" && c.SubscriptionID != c.EventKey {
+						subDisplay = strings.TrimPrefix(c.SubscriptionID, c.EventKey+":")
+					}
 					rows = append(rows, []string{
 						fmt.Sprintf("pid=%d", c.PID),
 						c.EventKey,
+						subDisplay,
 						fmt.Sprintf("%d", c.Received),
 						fmt.Sprintf("%d", c.Dropped),
 					})

errs/subtypes.go

@@ -80,6 +80,7 @@ const (
 	SubtypeSDKError        Subtype = "sdk_error"        // lark SDK Do() returned an unexpected error
 	SubtypeInvalidResponse Subtype = "invalid_response" // SDK response body not parsable as JSON
 	SubtypeFileIO          Subtype = "file_io"          // local file I/O failure (mkdir / write / read)
+	SubtypeExternalTool    Subtype = "external_tool"    // an external tool the CLI shells out to (git, npx) failed at runtime; the tool output is in the message
 	SubtypeStorage         Subtype = "storage"          // local persistence failure (e.g. config file save)
 	// Generic untyped error lifted to InternalError uses SubtypeUnknown.
 )

events/minutes/preconsume.go

@@ -13,8 +13,8 @@ import (
 
 const cleanupTimeout = 5 * time.Second
 
-func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
-	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) {
+func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func() error, error) {
+	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func() error, error) {
 		if rt == nil {
 			return nil, errs.NewInternalError(errs.SubtypeUnknown,
 				"runtime API client is required for pre-consume subscription")
@@ -25,10 +25,13 @@ func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) fu
 			return nil, err
 		}
 
-		return func() {
+		return func() error {
 			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
 			defer cancel()
-			_, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body)
+			if _, err := rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body); err != nil {
+				return err
+			}
+			return nil
 		}, nil
 	}
 }

events/vc/preconsume.go

@@ -13,8 +13,8 @@ import (
 
 const cleanupTimeout = 5 * time.Second
 
-func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
-	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) {
+func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func() error, error) {
+	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func() error, error) {
 		if rt == nil {
 			return nil, errs.NewInternalError(errs.SubtypeUnknown,
 				"runtime API client is required for pre-consume subscription")
@@ -25,10 +25,13 @@ func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) fu
 			return nil, err
 		}
 
-		return func() {
+		return func() error {
 			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
 			defer cancel()
-			_, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body)
+			if _, err := rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body); err != nil {
+				return err
+			}
+			return nil
 		}, nil
 	}
 }

events/vc/recording_ended.go

@@ -0,0 +1,84 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"strconv"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// VCRecordingEndedOutput is the flattened shape for vc.recording.recording_ended_v1.
+type VCRecordingEndedOutput struct {
+	Type      string `json:"type"                 desc:"Event type; always vc.recording.recording_ended_v1"`
+	EventID   string `json:"event_id,omitempty"   desc:"Globally unique event ID; safe for deduplication"`
+	EventTime string `json:"event_time,omitempty" desc:"Time when the recording ended and uploaded successfully, in RFC3339 / ISO 8601 with the current system timezone"`
+	UniqueKey string `json:"unique_key,omitempty" desc:"Unique key generated for one recording_bean recording session"`
+	Source    string `json:"source,omitempty"     desc:"Recording source; always recording_bean"`
+}
+
+type recordingEndedEnvelope struct {
+	Header struct {
+		EventID    string `json:"event_id"`
+		EventType  string `json:"event_type"`
+		CreateTime string `json:"create_time"`
+	} `json:"header"`
+	Event recordingEndedEvent `json:"event"`
+}
+
+type recordingEndedEvent struct {
+	UniqueKey string `json:"unique_key"`
+	Source    string `json:"source"`
+}
+
+func processVCRecordingEnded(_ context.Context, _ event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	envelope, ok := parseRecordingEndedEnvelope(raw)
+	if !ok {
+		return raw.Payload, nil
+	}
+	if !isRecordingEndedBeanEvent(envelope) {
+		return nil, nil
+	}
+	out := &VCRecordingEndedOutput{
+		Type:      recordingEndedEventType(envelope, raw),
+		EventID:   envelope.Header.EventID,
+		EventTime: recordingEndedEventTime(envelope.Header.CreateTime),
+		UniqueKey: envelope.Event.UniqueKey,
+		Source:    envelope.Event.Source,
+	}
+	return json.Marshal(out)
+}
+
+func parseRecordingEndedEnvelope(raw *event.RawEvent) (*recordingEndedEnvelope, bool) {
+	var envelope recordingEndedEnvelope
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return nil, false
+	}
+	return &envelope, true
+}
+
+func isRecordingEndedBeanEvent(envelope *recordingEndedEnvelope) bool {
+	return envelope != nil && envelope.Event.Source == "recording_bean"
+}
+
+func recordingEndedEventType(envelope *recordingEndedEnvelope, raw *event.RawEvent) string {
+	if envelope != nil && envelope.Header.EventType != "" {
+		return envelope.Header.EventType
+	}
+	return raw.EventType
+}
+
+func recordingEndedEventTime(raw string) string {
+	if raw == "" {
+		return ""
+	}
+	millis, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil {
+		return ""
+	}
+	return time.UnixMilli(millis).Local().Format(time.RFC3339)
+}

events/vc/recording_started.go

@@ -0,0 +1,84 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"strconv"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// VCRecordingStartedOutput is the flattened shape for vc.recording.recording_started_v1.
+type VCRecordingStartedOutput struct {
+	Type      string `json:"type"                 desc:"Event type; always vc.recording.recording_started_v1"`
+	EventID   string `json:"event_id,omitempty"   desc:"Globally unique event ID; safe for deduplication"`
+	EventTime string `json:"event_time,omitempty" desc:"Recording start time in RFC3339 / ISO 8601 with the current system timezone"`
+	UniqueKey string `json:"unique_key,omitempty" desc:"Unique key generated for one recording_bean recording session"`
+	Source    string `json:"source,omitempty"     desc:"Recording source; always recording_bean"`
+}
+
+type recordingStartedEnvelope struct {
+	Header struct {
+		EventID    string `json:"event_id"`
+		EventType  string `json:"event_type"`
+		CreateTime string `json:"create_time"`
+	} `json:"header"`
+	Event recordingStartedEvent `json:"event"`
+}
+
+type recordingStartedEvent struct {
+	UniqueKey string `json:"unique_key"`
+	Source    string `json:"source"`
+}
+
+func processVCRecordingStarted(_ context.Context, _ event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	envelope, ok := parseRecordingStartedEnvelope(raw)
+	if !ok {
+		return raw.Payload, nil
+	}
+	if !isRecordingStartedBeanEvent(envelope) {
+		return nil, nil
+	}
+	out := &VCRecordingStartedOutput{
+		Type:      recordingStartedEventType(envelope, raw),
+		EventID:   envelope.Header.EventID,
+		EventTime: recordingStartedEventTime(envelope.Header.CreateTime),
+		UniqueKey: envelope.Event.UniqueKey,
+		Source:    envelope.Event.Source,
+	}
+	return json.Marshal(out)
+}
+
+func parseRecordingStartedEnvelope(raw *event.RawEvent) (*recordingStartedEnvelope, bool) {
+	var envelope recordingStartedEnvelope
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return nil, false
+	}
+	return &envelope, true
+}
+
+func isRecordingStartedBeanEvent(envelope *recordingStartedEnvelope) bool {
+	return envelope != nil && envelope.Event.Source == "recording_bean"
+}
+
+func recordingStartedEventType(envelope *recordingStartedEnvelope, raw *event.RawEvent) string {
+	if envelope != nil && envelope.Header.EventType != "" {
+		return envelope.Header.EventType
+	}
+	return raw.EventType
+}
+
+func recordingStartedEventTime(raw string) string {
+	if raw == "" {
+		return ""
+	}
+	millis, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil {
+		return ""
+	}
+	return time.UnixMilli(millis).Local().Format(time.RFC3339)
+}

events/vc/recording_test.go

@@ -0,0 +1,468 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+func TestVCKeys_RecordingEventsRegistered(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	for _, tc := range []struct {
+		eventType string
+	}{
+		{eventTypeRecordingStarted},
+		{eventTypeRecordingTranscriptGenerated},
+		{eventTypeRecordingEnded},
+	} {
+		t.Run(tc.eventType, func(t *testing.T) {
+			def, ok := event.Lookup(tc.eventType)
+			if !ok {
+				t.Fatalf("%s should be registered via Keys()", tc.eventType)
+			}
+			if def.Schema.Custom == nil {
+				t.Error("Processed key must set Schema.Custom")
+			}
+			if def.Schema.Native != nil {
+				t.Error("Processed key must not set Schema.Native")
+			}
+			if def.Process == nil {
+				t.Error("Process must not be nil for processed key")
+			}
+			if def.PreConsume == nil {
+				t.Error("PreConsume must not be nil for processed key")
+			}
+			if len(def.Scopes) != 1 || def.Scopes[0] != "vc:recording:read" {
+				t.Errorf("Scopes = %v", def.Scopes)
+			}
+			if len(def.AuthTypes) != 1 || def.AuthTypes[0] != "user" {
+				t.Errorf("AuthTypes = %v", def.AuthTypes)
+			}
+			if len(def.RequiredConsoleEvents) != 1 || def.RequiredConsoleEvents[0] != tc.eventType {
+				t.Errorf("RequiredConsoleEvents = %v", def.RequiredConsoleEvents)
+			}
+			if !strings.Contains(def.Description, "recording_bean") {
+				t.Errorf("Description should document recording_bean source, got %q", def.Description)
+			}
+			if !strings.Contains(def.Description, "connected to Feishu software") {
+				t.Errorf("Description should document Feishu software connection requirement, got %q", def.Description)
+			}
+			if strings.Contains(def.Description, "future") || strings.Contains(def.Description, "software_recording") {
+				t.Errorf("Description should not mention future sources, got %q", def.Description)
+			}
+			if tc.eventType == eventTypeRecordingEnded && (strings.Contains(def.Description, "object_type") || strings.Contains(def.Description, "object_id")) {
+				t.Errorf("ended Description should not document object metadata, got %q", def.Description)
+			}
+			wantSchemaType := reflect.TypeOf(VCRecordingStartedOutput{})
+			switch tc.eventType {
+			case eventTypeRecordingTranscriptGenerated:
+				wantSchemaType = reflect.TypeOf(VCRecordingTranscriptGeneratedOutput{})
+			case eventTypeRecordingEnded:
+				wantSchemaType = reflect.TypeOf(VCRecordingEndedOutput{})
+			}
+			if def.Schema.Custom.Type != wantSchemaType {
+				t.Errorf("Custom schema Type = %v, want %v", def.Schema.Custom.Type, wantSchemaType)
+			}
+		})
+	}
+}
+
+func TestProcessVCRecordingStarted(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	out := runRecordingProcess[VCRecordingStartedOutput](t, eventTypeRecordingStarted, processVCRecordingStarted, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_rec_start_001",
+			"event_type": "vc.recording.recording_started_v1",
+			"create_time": "1761782400000"
+		},
+		"event": {
+			"unique_key": "recording_001",
+			"source": "recording_bean"
+		}
+	}`)
+
+	if out.Type != eventTypeRecordingStarted {
+		t.Errorf("Type = %q", out.Type)
+	}
+	if out.EventID != "ev_rec_start_001" || out.EventTime != recordingTestEventTime(1761782400000) {
+		t.Errorf("EventID/EventTime = %q/%q", out.EventID, out.EventTime)
+	}
+	if out.UniqueKey != "recording_001" || out.Source != "recording_bean" {
+		t.Errorf("UniqueKey/Source = %q/%q", out.UniqueKey, out.Source)
+	}
+}
+
+func TestProcessVCRecordingTranscriptGenerated(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	got := runRecordingProcessRaw(t, eventTypeRecordingTranscriptGenerated, processVCRecordingTranscriptGenerated, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_rec_transcript_001",
+			"event_type": "vc.recording.recording_transcript_generated_v1",
+			"create_time": "1761782400100"
+		},
+		"event": {
+			"unique_key": "recording_001",
+			"source": "recording_bean",
+			"transcript_items": [
+				{
+					"speaker": {
+						"id": {
+							"open_id": "ou_0f8bf7acdf2ae69553ecbdbfbbd10a53",
+							"union_id": "on_bc03f16d781bff4178a5d11e48eb1867",
+							"user_id": null
+						},
+						"user_type": 100,
+						"user_role": 1,
+						"user_name": "Alice"
+					},
+					"text": "hello world",
+					"language": "en_us",
+					"start_time_ms": "1761782399000",
+					"end_time_ms": "1761782400000",
+					"sentence_id": "987654321"
+				},
+				{
+					"speaker": {
+						"user_name": "Bob"
+					},
+					"text": "second sentence",
+					"language": "en_us",
+					"start_time_ms": "1761782401000",
+					"end_time_ms": "1761782402000",
+					"sentence_id": "987654322"
+				}
+			]
+		}
+	}`)
+	if got == nil {
+		t.Fatal("Process output is nil")
+	}
+	var out VCRecordingTranscriptGeneratedOutput
+	if err := json.Unmarshal(got, &out); err != nil {
+		t.Fatalf("Process output is not valid JSON: %v\nraw=%s", err, string(got))
+	}
+
+	if out.Type != eventTypeRecordingTranscriptGenerated {
+		t.Errorf("Type = %q", out.Type)
+	}
+	if out.UniqueKey != "recording_001" || out.Source != "recording_bean" {
+		t.Errorf("UniqueKey/Source = %q/%q", out.UniqueKey, out.Source)
+	}
+	if out.EventTime != recordingTestEventTime(1761782400100) {
+		t.Errorf("EventTime = %q", out.EventTime)
+	}
+	if len(out.TranscriptItems) != 2 {
+		t.Fatalf("TranscriptItems len = %d, want 2", len(out.TranscriptItems))
+	}
+	item := out.TranscriptItems[0]
+	if item.SpeakerName != "Alice" || item.Text != "hello world" {
+		t.Errorf("Transcript speaker/text = %q/%q", item.SpeakerName, item.Text)
+	}
+	if item.StartTime != recordingTestEventTime(1761782399000) || item.EndTime != recordingTestEventTime(1761782400000) {
+		t.Errorf("Transcript timing = %q/%q", item.StartTime, item.EndTime)
+	}
+	if item.SentenceID != "987654321" {
+		t.Errorf("SentenceID = %q, want 987654321", item.SentenceID)
+	}
+	if out.TranscriptItems[1].SpeakerName != "Bob" || out.TranscriptItems[1].SentenceID != "987654322" {
+		t.Errorf("second transcript item = %+v", out.TranscriptItems[1])
+	}
+	itemJSON, err := json.Marshal(item)
+	if err != nil {
+		t.Fatalf("marshal transcript item: %v", err)
+	}
+	var itemFields map[string]any
+	if err := json.Unmarshal(itemJSON, &itemFields); err != nil {
+		t.Fatalf("unmarshal transcript item JSON: %v", err)
+	}
+	wantItemFields := map[string]bool{
+		"speaker_name": true,
+		"text":         true,
+		"start_time":   true,
+		"end_time":     true,
+		"sentence_id":  true,
+	}
+	for gotField := range itemFields {
+		if !wantItemFields[gotField] {
+			t.Errorf("Transcript item should not contain field %q, got %s", gotField, string(itemJSON))
+		}
+	}
+	for wantField := range wantItemFields {
+		if _, ok := itemFields[wantField]; !ok {
+			t.Errorf("Transcript item missing field %q, got %s", wantField, string(itemJSON))
+		}
+	}
+	for _, unexpected := range []string{
+		`"seq_id"`,
+		`"speaker"`,
+		`"user_open_id"`,
+		`"user_type"`,
+		`"user_role"`,
+		`"language"`,
+		`"start_time_ms"`,
+		`"end_time_ms"`,
+		`"sequence_id"`,
+		`"transcript_item"`,
+	} {
+		if strings.Contains(string(got), unexpected) {
+			t.Errorf("Transcript output should not contain %s, got %s", unexpected, string(got))
+		}
+	}
+	if !strings.Contains(string(got), `"sentence_id":"987654321"`) {
+		t.Errorf("Transcript output should contain sentence_id, got %s", string(got))
+	}
+}
+
+func TestProcessVCRecordingEnded(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	out := runRecordingProcess[VCRecordingEndedOutput](t, eventTypeRecordingEnded, processVCRecordingEnded, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_rec_end_001",
+			"event_type": "vc.recording.recording_ended_v1",
+			"create_time": "1761782400200"
+		},
+		"event": {
+			"unique_key": "recording_001",
+			"source": "recording_bean",
+			"object_type": "minutes",
+			"object_id": "minute_token_001"
+		}
+	}`)
+
+	if out.Type != eventTypeRecordingEnded {
+		t.Errorf("Type = %q", out.Type)
+	}
+	if out.UniqueKey != "recording_001" || out.Source != "recording_bean" {
+		t.Errorf("UniqueKey/Source = %q/%q", out.UniqueKey, out.Source)
+	}
+	if out.EventTime != recordingTestEventTime(1761782400200) {
+		t.Errorf("EventTime = %q", out.EventTime)
+	}
+}
+
+func TestProcessVCRecordingEnded_DropsObjectMetadata(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	got := runRecordingProcessRaw(t, eventTypeRecordingEnded, processVCRecordingEnded, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_rec_end_001",
+			"event_type": "vc.recording.recording_ended_v1",
+			"create_time": "1761782400200"
+		},
+		"event": {
+			"unique_key": "recording_001",
+			"source": "recording_bean",
+			"object_type": "minutes",
+			"object_id": "minute_token_001"
+		}
+	}`)
+
+	if strings.Contains(string(got), "object_type") || strings.Contains(string(got), "object_id") {
+		t.Fatalf("ended output should drop object metadata, got %s", string(got))
+	}
+}
+
+func TestProcessVCRecording_DropsTimestampField(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	got := runRecordingProcessRaw(t, eventTypeRecordingStarted, processVCRecordingStarted, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_rec_start_001",
+			"event_type": "vc.recording.recording_started_v1",
+			"create_time": "1761782400000"
+		},
+		"event": {
+			"unique_key": "recording_001",
+			"source": "recording_bean"
+		}
+	}`)
+
+	if strings.Contains(string(got), `"timestamp"`) {
+		t.Fatalf("recording output should use event_time instead of timestamp, got %s", string(got))
+	}
+	if !strings.Contains(string(got), `"event_time":"`+recordingTestEventTime(1761782400000)+`"`) {
+		t.Fatalf("recording output should include ISO 8601 event_time, got %s", string(got))
+	}
+}
+
+func TestProcessVCRecording_NonRecordingBeanFiltered(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	for _, tc := range []struct {
+		name      string
+		eventType string
+		process   event.ProcessFunc
+		payload   string
+	}{
+		{
+			name:      "started",
+			eventType: eventTypeRecordingStarted,
+			process:   processVCRecordingStarted,
+			payload: `{
+				"schema": "2.0",
+				"header": {"event_id": "ev_rec_start_001", "event_type": "vc.recording.recording_started_v1"},
+				"event": {"unique_key": "recording_001", "source": "software_recording"}
+			}`,
+		},
+		{
+			name:      "transcript",
+			eventType: eventTypeRecordingTranscriptGenerated,
+			process:   processVCRecordingTranscriptGenerated,
+			payload: `{
+				"schema": "2.0",
+				"header": {"event_id": "ev_rec_transcript_001", "event_type": "vc.recording.recording_transcript_generated_v1"},
+				"event": {"unique_key": "recording_001", "source": "software_recording", "transcript_items": []}
+			}`,
+		},
+		{
+			name:      "ended",
+			eventType: eventTypeRecordingEnded,
+			process:   processVCRecordingEnded,
+			payload: `{
+				"schema": "2.0",
+				"header": {"event_id": "ev_rec_end_001", "event_type": "vc.recording.recording_ended_v1"},
+				"event": {"unique_key": "recording_001", "source": "software_recording"}
+			}`,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got := runRecordingProcessRaw(t, tc.eventType, tc.process, tc.payload)
+			if got != nil {
+				t.Fatalf("non-recording_bean event should be filtered, got %s", string(got))
+			}
+		})
+	}
+}
+
+func TestProcessVCRecording_MalformedPayloadPassthrough(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	for _, tc := range []struct {
+		name      string
+		eventType string
+		process   event.ProcessFunc
+	}{
+		{name: "started", eventType: eventTypeRecordingStarted, process: processVCRecordingStarted},
+		{name: "transcript", eventType: eventTypeRecordingTranscriptGenerated, process: processVCRecordingTranscriptGenerated},
+		{name: "ended", eventType: eventTypeRecordingEnded, process: processVCRecordingEnded},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			raw := &event.RawEvent{
+				EventType: tc.eventType,
+				Payload:   json.RawMessage(`not json`),
+				Timestamp: time.Now(),
+			}
+			got, err := tc.process(context.Background(), nil, raw, nil)
+			if err != nil {
+				t.Fatalf("Process should swallow parse errors, got %v", err)
+			}
+			if string(got) != "not json" {
+				t.Errorf("malformed fallback output = %q, want original bytes", string(got))
+			}
+		})
+	}
+}
+
+func TestVCRecording_PreConsumeSubscriptionLifecycle(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	for _, tc := range []struct {
+		eventType string
+	}{
+		{eventTypeRecordingStarted},
+		{eventTypeRecordingTranscriptGenerated},
+		{eventTypeRecordingEnded},
+	} {
+		t.Run(tc.eventType, func(t *testing.T) {
+			def, ok := event.Lookup(tc.eventType)
+			if !ok {
+				t.Fatalf("%s should be registered via Keys()", tc.eventType)
+			}
+
+			type call struct {
+				method string
+				path   string
+				body   any
+			}
+			var calls []call
+			rt := &stubAPIClient{
+				callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+					calls = append(calls, call{method: method, path: path, body: body})
+					return json.RawMessage(`{"code":0,"msg":"success","data":{}}`), nil
+				},
+			}
+
+			cleanup, err := def.PreConsume(context.Background(), rt, nil)
+			if err != nil {
+				t.Fatalf("PreConsume error: %v", err)
+			}
+			if cleanup == nil {
+				t.Fatal("cleanup must not be nil")
+			}
+			if len(calls) != 1 {
+				t.Fatalf("calls after subscribe = %d, want 1", len(calls))
+			}
+			if calls[0].method != "POST" || calls[0].path != pathRecordingSubscribe {
+				t.Fatalf("subscribe call = %+v", calls[0])
+			}
+			assertSubscriptionRequest(t, calls[0].body, tc.eventType)
+
+			cleanup()
+			if len(calls) != 2 {
+				t.Fatalf("calls after cleanup = %d, want 2", len(calls))
+			}
+			if calls[1].method != "POST" || calls[1].path != pathRecordingUnsubscribe {
+				t.Fatalf("unsubscribe call = %+v", calls[1])
+			}
+			assertSubscriptionRequest(t, calls[1].body, tc.eventType)
+		})
+	}
+}
+
+func runRecordingProcess[T any](t *testing.T, eventType string, process event.ProcessFunc, payload string) T {
+	t.Helper()
+	got := runRecordingProcessRaw(t, eventType, process, payload)
+	if got == nil {
+		t.Fatal("Process output is nil")
+	}
+	var out T
+	if err := json.Unmarshal(got, &out); err != nil {
+		t.Fatalf("Process output is not valid JSON: %v\nraw=%s", err, string(got))
+	}
+	return out
+}
+
+func runRecordingProcessRaw(t *testing.T, eventType string, process event.ProcessFunc, payload string) json.RawMessage {
+	t.Helper()
+	raw := &event.RawEvent{
+		EventType: eventType,
+		Payload:   json.RawMessage(payload),
+		Timestamp: time.Now(),
+	}
+	got, err := process(context.Background(), nil, raw, nil)
+	if err != nil {
+		t.Fatalf("Process error: %v", err)
+	}
+	return got
+}
+
+func recordingTestEventTime(millis int64) string {
+	return time.UnixMilli(millis).Local().Format(time.RFC3339)
+}

events/vc/recording_transcript_generated.go

@@ -0,0 +1,163 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"strconv"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// VCRecordingTranscriptItemOutput is one flattened transcript item for recording events.
+type VCRecordingTranscriptItemOutput struct {
+	SpeakerName string `json:"speaker_name,omitempty" desc:"Speaker display name"`
+	Text        string `json:"text,omitempty"         desc:"Transcript text"`
+	StartTime   string `json:"start_time,omitempty"   desc:"Transcript item start time in RFC3339 / ISO 8601 with the current system timezone"`
+	EndTime     string `json:"end_time,omitempty"     desc:"Transcript item end time in RFC3339 / ISO 8601 with the current system timezone"`
+	SentenceID  string `json:"sentence_id,omitempty"  desc:"Transcript sentence ID"`
+}
+
+// VCRecordingTranscriptGeneratedOutput is the flattened shape for vc.recording.recording_transcript_generated_v1.
+type VCRecordingTranscriptGeneratedOutput struct {
+	Type            string                            `json:"type"                       desc:"Event type; always vc.recording.recording_transcript_generated_v1"`
+	EventID         string                            `json:"event_id,omitempty"         desc:"Globally unique event ID; safe for deduplication"`
+	EventTime       string                            `json:"event_time,omitempty"       desc:"Time when this batch of transcript items was generated, in RFC3339 / ISO 8601 with the current system timezone"`
+	UniqueKey       string                            `json:"unique_key,omitempty"       desc:"Unique key generated for one recording_bean recording session"`
+	Source          string                            `json:"source,omitempty"           desc:"Recording source; always recording_bean"`
+	TranscriptItems []VCRecordingTranscriptItemOutput `json:"transcript_items,omitempty" desc:"Generated transcript items"`
+}
+
+type recordingTranscriptGeneratedEnvelope struct {
+	Header struct {
+		EventID    string `json:"event_id"`
+		EventType  string `json:"event_type"`
+		CreateTime string `json:"create_time"`
+	} `json:"header"`
+	Event recordingTranscriptGeneratedEvent `json:"event"`
+}
+
+type recordingTranscriptGeneratedEvent struct {
+	UniqueKey       string                               `json:"unique_key"`
+	Source          string                               `json:"source"`
+	TranscriptItems []recordingTranscriptGeneratedItemIn `json:"transcript_items"`
+}
+
+type recordingTranscriptGeneratedItemIn struct {
+	Speaker     *recordingTranscriptGeneratedSpeakerIn `json:"speaker"`
+	Text        string                                 `json:"text"`
+	StartTimeMs recordingTranscriptGeneratedString     `json:"start_time_ms"`
+	EndTimeMs   recordingTranscriptGeneratedString     `json:"end_time_ms"`
+	SentenceID  string                                 `json:"sentence_id"`
+}
+
+type recordingTranscriptGeneratedSpeakerIn struct {
+	UserName string `json:"user_name"`
+}
+
+type recordingTranscriptGeneratedString string
+
+func processVCRecordingTranscriptGenerated(_ context.Context, _ event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	envelope, ok := parseRecordingTranscriptGeneratedEnvelope(raw)
+	if !ok {
+		return raw.Payload, nil
+	}
+	if !isRecordingTranscriptGeneratedBeanEvent(envelope) {
+		return nil, nil
+	}
+	out := &VCRecordingTranscriptGeneratedOutput{
+		Type:            recordingTranscriptGeneratedEventType(envelope, raw),
+		EventID:         envelope.Header.EventID,
+		EventTime:       recordingTranscriptGeneratedEventTime(envelope.Header.CreateTime),
+		UniqueKey:       envelope.Event.UniqueKey,
+		Source:          envelope.Event.Source,
+		TranscriptItems: recordingTranscriptItems(envelope.Event.TranscriptItems),
+	}
+	return json.Marshal(out)
+}
+
+func parseRecordingTranscriptGeneratedEnvelope(raw *event.RawEvent) (*recordingTranscriptGeneratedEnvelope, bool) {
+	var envelope recordingTranscriptGeneratedEnvelope
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return nil, false
+	}
+	return &envelope, true
+}
+
+func isRecordingTranscriptGeneratedBeanEvent(envelope *recordingTranscriptGeneratedEnvelope) bool {
+	return envelope != nil && envelope.Event.Source == "recording_bean"
+}
+
+func recordingTranscriptGeneratedEventType(envelope *recordingTranscriptGeneratedEnvelope, raw *event.RawEvent) string {
+	if envelope != nil && envelope.Header.EventType != "" {
+		return envelope.Header.EventType
+	}
+	return raw.EventType
+}
+
+func recordingTranscriptGeneratedEventTime(raw string) string {
+	return recordingTranscriptGeneratedMillisToLocalRFC3339(raw)
+}
+
+func recordingTranscriptGeneratedMillisToLocalRFC3339(raw string) string {
+	if raw == "" {
+		return ""
+	}
+	millis, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil {
+		return ""
+	}
+	return time.UnixMilli(millis).Local().Format(time.RFC3339)
+}
+
+func recordingTranscriptItems(items []recordingTranscriptGeneratedItemIn) []VCRecordingTranscriptItemOutput {
+	if len(items) == 0 {
+		return nil
+	}
+	out := make([]VCRecordingTranscriptItemOutput, 0, len(items))
+	for _, item := range items {
+		out = append(out, recordingTranscriptItem(item))
+	}
+	return out
+}
+
+func recordingTranscriptItem(item recordingTranscriptGeneratedItemIn) VCRecordingTranscriptItemOutput {
+	return VCRecordingTranscriptItemOutput{
+		SpeakerName: recordingSpeakerName(item.Speaker),
+		Text:        item.Text,
+		StartTime:   recordingTranscriptGeneratedMillisToLocalRFC3339(item.StartTimeMs.String()),
+		EndTime:     recordingTranscriptGeneratedMillisToLocalRFC3339(item.EndTimeMs.String()),
+		SentenceID:  item.SentenceID,
+	}
+}
+
+func recordingSpeakerName(speaker *recordingTranscriptGeneratedSpeakerIn) string {
+	if speaker == nil {
+		return ""
+	}
+	return speaker.UserName
+}
+
+func (s *recordingTranscriptGeneratedString) UnmarshalJSON(data []byte) error {
+	if string(data) == "null" {
+		return nil
+	}
+	var str string
+	if err := json.Unmarshal(data, &str); err == nil {
+		*s = recordingTranscriptGeneratedString(str)
+		return nil
+	}
+	var num json.Number
+	if err := json.Unmarshal(data, &num); err != nil {
+		return err
+	}
+	*s = recordingTranscriptGeneratedString(num.String())
+	return nil
+}
+
+func (s recordingTranscriptGeneratedString) String() string {
+	return string(s)
+}

events/vc/register.go

@@ -11,13 +11,18 @@ import (
 )
 
 const (
-	eventTypeMeetingEnded  = "vc.meeting.participant_meeting_ended_v1"
-	eventTypeNoteGenerated = "vc.note.generated_v1"
+	eventTypeMeetingEnded                 = "vc.meeting.participant_meeting_ended_v1"
+	eventTypeNoteGenerated                = "vc.note.generated_v1"
+	eventTypeRecordingStarted             = "vc.recording.recording_started_v1"
+	eventTypeRecordingTranscriptGenerated = "vc.recording.recording_transcript_generated_v1"
+	eventTypeRecordingEnded               = "vc.recording.recording_ended_v1"
 
-	pathMeetingSubscribe   = "/open-apis/vc/v1/meetings/subscription"
-	pathMeetingUnsubscribe = "/open-apis/vc/v1/meetings/unsubscription"
-	pathNoteSubscribe      = "/open-apis/vc/v1/notes/subscription"
-	pathNoteUnsubscribe    = "/open-apis/vc/v1/notes/unsubscription"
+	pathMeetingSubscribe     = "/open-apis/vc/v1/meetings/subscription"
+	pathMeetingUnsubscribe   = "/open-apis/vc/v1/meetings/unsubscription"
+	pathNoteSubscribe        = "/open-apis/vc/v1/notes/subscription"
+	pathNoteUnsubscribe      = "/open-apis/vc/v1/notes/unsubscription"
+	pathRecordingSubscribe   = "/open-apis/vc/v1/recordings/subscription"
+	pathRecordingUnsubscribe = "/open-apis/vc/v1/recordings/unsubscription"
 
 	pathNoteDetailFmt = "/open-apis/vc/v1/notes/%s"
 )
@@ -57,5 +62,53 @@ func Keys() []event.KeyDefinition {
 			},
 			RequiredConsoleEvents: []string{eventTypeNoteGenerated},
 		},
+		{
+			Key:         eventTypeRecordingStarted,
+			DisplayName: "Recording started",
+			Description: "Triggered when a recording_bean recording starts; only generated when connected to Feishu software.",
+			EventType:   eventTypeRecordingStarted,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCRecordingStartedOutput{})},
+			},
+			Process:    processVCRecordingStarted,
+			PreConsume: subscriptionPreConsume(eventTypeRecordingStarted, pathRecordingSubscribe, pathRecordingUnsubscribe),
+			Scopes:     []string{"vc:recording:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeRecordingStarted},
+		},
+		{
+			Key:         eventTypeRecordingTranscriptGenerated,
+			DisplayName: "Recording transcript generated",
+			Description: "Triggered when recording_bean transcript items are generated; only generated when connected to Feishu software.",
+			EventType:   eventTypeRecordingTranscriptGenerated,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCRecordingTranscriptGeneratedOutput{})},
+			},
+			Process:    processVCRecordingTranscriptGenerated,
+			PreConsume: subscriptionPreConsume(eventTypeRecordingTranscriptGenerated, pathRecordingSubscribe, pathRecordingUnsubscribe),
+			Scopes:     []string{"vc:recording:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeRecordingTranscriptGenerated},
+		},
+		{
+			Key:         eventTypeRecordingEnded,
+			DisplayName: "Recording ended",
+			Description: "Triggered when a recording_bean recording ends and uploads successfully; only generated when connected to Feishu software.",
+			EventType:   eventTypeRecordingEnded,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCRecordingEndedOutput{})},
+			},
+			Process:    processVCRecordingEnded,
+			PreConsume: subscriptionPreConsume(eventTypeRecordingEnded, pathRecordingSubscribe, pathRecordingUnsubscribe),
+			Scopes:     []string{"vc:recording:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeRecordingEnded},
+		},
 	}
 }

events/whiteboard/preconsume.go

@@ -22,8 +22,8 @@ const cleanupTimeout = 5 * time.Second
 //
 // board.whiteboard.updated_v1 is subscribed per-whiteboard (by whiteboard_id),
 // so the path contains a :whiteboard_id placeholder that must be supplied via params.
-func whiteboardSubscriptionPreConsume(eventType string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
-	return func(ctx context.Context, rt event.APIClient, params map[string]string) (func(), error) {
+func whiteboardSubscriptionPreConsume(eventType string) func(context.Context, event.APIClient, map[string]string) (func() error, error) {
+	return func(ctx context.Context, rt event.APIClient, params map[string]string) (func() error, error) {
 		if rt == nil {
 			return nil, errs.NewInternalError(errs.SubtypeUnknown,
 				"runtime API client is required for pre-consume subscription")
@@ -44,10 +44,13 @@ func whiteboardSubscriptionPreConsume(eventType string) func(context.Context, ev
 			return nil, err
 		}
 
-		return func() {
+		return func() error {
 			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
 			defer cancel()
-			_, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body)
+			if _, err := rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body); err != nil {
+				return err
+			}
+			return nil
 		}, nil
 	}
 }

internal/auth/device_flow.go

@@ -47,6 +47,7 @@ type DeviceFlowResult struct {
 // OAuthEndpoints contains the OAuth endpoint URLs.
 type OAuthEndpoints struct {
 	DeviceAuthorization string
+	Revoke              string
 	Token               string
 }
 
@@ -55,6 +56,7 @@ func ResolveOAuthEndpoints(brand core.LarkBrand) OAuthEndpoints {
 	ep := core.ResolveEndpoints(brand)
 	return OAuthEndpoints{
 		DeviceAuthorization: ep.Accounts + PathDeviceAuthorization,
+		Revoke:              ep.Accounts + PathOAuthRevoke,
 		Token:               ep.Open + PathOAuthTokenV2,
 	}
 }

internal/auth/device_flow_test.go

@@ -31,6 +31,9 @@ func TestResolveOAuthEndpoints_Feishu(t *testing.T) {
 	if ep.DeviceAuthorization != "https://accounts.feishu.cn/oauth/v1/device_authorization" {
 		t.Errorf("DeviceAuthorization = %q", ep.DeviceAuthorization)
 	}
+	if ep.Revoke != "https://accounts.feishu.cn/oauth/v1/revoke" {
+		t.Errorf("Revoke = %q", ep.Revoke)
+	}
 	if ep.Token != "https://open.feishu.cn/open-apis/authen/v2/oauth/token" {
 		t.Errorf("Token = %q", ep.Token)
 	}
@@ -42,6 +45,9 @@ func TestResolveOAuthEndpoints_Lark(t *testing.T) {
 	if ep.DeviceAuthorization != "https://accounts.larksuite.com/oauth/v1/device_authorization" {
 		t.Errorf("DeviceAuthorization = %q", ep.DeviceAuthorization)
 	}
+	if ep.Revoke != "https://accounts.larksuite.com/oauth/v1/revoke" {
+		t.Errorf("Revoke = %q", ep.Revoke)
+	}
 	if ep.Token != "https://open.larksuite.com/open-apis/authen/v2/oauth/token" {
 		t.Errorf("Token = %q", ep.Token)
 	}

internal/auth/paths.go

@@ -7,6 +7,8 @@ package auth
 const (
 	// PathDeviceAuthorization is the endpoint for device authorization.
 	PathDeviceAuthorization = "/oauth/v1/device_authorization"
+	// PathOAuthRevoke is the endpoint for revoking an OAuth token.
+	PathOAuthRevoke = "/oauth/v1/revoke"
 	// PathAppRegistration is the endpoint for application registration.
 	PathAppRegistration = "/oauth/v1/app/registration"
 	// PathOAuthTokenV2 is the endpoint for requesting an OAuth token (v2).

internal/auth/revoke.go

@@ -0,0 +1,131 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
+)
+
+// RevokeToken revokes a previously issued OAuth token.
+func RevokeToken(httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, token, tokenTypeHint string) error {
+	endpoints := ResolveOAuthEndpoints(brand)
+
+	form := url.Values{}
+	form.Set("client_id", appId)
+	form.Set("client_secret", appSecret)
+	form.Set("token", token)
+	if tokenTypeHint != "" {
+		form.Set("token_type_hint", tokenTypeHint)
+	}
+
+	req, err := http.NewRequest(http.MethodPost, endpoints.Revoke, strings.NewReader(form.Encode()))
+	if err != nil {
+		return errs.NewInternalError(errs.SubtypeUnknown, "token revoke request creation failed: %v", err).WithCause(err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return errs.NewNetworkError(errs.SubtypeNetworkTransport, "token revoke transport error: %v", err).WithCause(err)
+	}
+	defer resp.Body.Close()
+	logHTTPResponse(resp)
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "token revoke read error: %v", err).WithCause(err)
+	}
+
+	if resp.StatusCode >= 400 {
+		return revokeHTTPStatusError(resp.StatusCode, body)
+	}
+
+	if len(body) == 0 {
+		return nil
+	}
+
+	var data map[string]interface{}
+	if err := json.Unmarshal(body, &data); err != nil {
+		return nil
+	}
+
+	if code := getInt(data, "code", 0); code != 0 {
+		msg := getStr(data, "msg")
+		if msg == "" {
+			msg = getStr(data, "message")
+		}
+		if msg == "" {
+			msg = "unknown error"
+		}
+		return errs.NewAPIError(errs.SubtypeUnknown, "token revoke failed [%d]: %s", code, msg).
+			WithCode(code).
+			WithCause(errors.New(msg))
+	}
+
+	if errStr := getStr(data, "error"); errStr != "" {
+		msg := getStr(data, "error_description")
+		if msg == "" {
+			msg = errStr
+		}
+		return errs.NewAPIError(errs.SubtypeUnknown, "token revoke failed: %s", msg).
+			WithCause(errors.New(msg))
+	}
+
+	return nil
+}
+
+func revokeHTTPStatusError(status int, body []byte) error {
+	msg := formatOAuthErrorBody(body)
+	cause := errors.New(strings.TrimSpace(string(body)))
+	if strings.TrimSpace(string(body)) == "" {
+		cause = errors.New(msg)
+	}
+	if status >= http.StatusInternalServerError {
+		return errs.NewNetworkError(errs.SubtypeNetworkServer, "token revoke failed: HTTP %d: %s", status, msg).
+			WithCode(status).
+			WithRetryable().
+			WithCause(cause)
+	}
+	subtype := errs.SubtypeUnknown
+	if status == http.StatusNotFound {
+		subtype = errs.SubtypeNotFound
+	}
+	return errs.NewAPIError(subtype, "token revoke failed: HTTP %d: %s", status, msg).
+		WithCode(status).
+		WithCause(cause)
+}
+
+func formatOAuthErrorBody(body []byte) string {
+	trimmed := strings.TrimSpace(string(body))
+	if trimmed == "" {
+		return "empty response"
+	}
+
+	var data map[string]interface{}
+	if err := json.Unmarshal(body, &data); err != nil {
+		return trimmed
+	}
+
+	if msg := getStr(data, "error_description"); msg != "" {
+		return msg
+	}
+	if msg := getStr(data, "msg"); msg != "" {
+		return msg
+	}
+	if msg := getStr(data, "message"); msg != "" {
+		return msg
+	}
+	if msg := getStr(data, "error"); msg != "" {
+		return msg
+	}
+	return trimmed
+}

internal/auth/revoke_test.go

@@ -0,0 +1,207 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"errors"
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+type revokeRoundTripFunc func(*http.Request) (*http.Response, error)
+
+func (fn revokeRoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return fn(req)
+}
+
+type errReadCloser struct {
+	err error
+}
+
+func (r errReadCloser) Read(_ []byte) (int, error) {
+	return 0, r.err
+}
+
+func (r errReadCloser) Close() error {
+	return nil
+}
+
+func TestRevokeToken_PostsExpectedForm(t *testing.T) {
+	reg := &httpmock.Registry{}
+	t.Cleanup(func() { reg.Verify(t) })
+
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    PathOAuthRevoke,
+		Body:   map[string]interface{}{"code": 0},
+		BodyFilter: func(body []byte) bool {
+			values, err := url.ParseQuery(string(body))
+			if err != nil {
+				return false
+			}
+			return values.Get("client_id") == "cli_a" &&
+				values.Get("client_secret") == "secret_b" &&
+				values.Get("token") == "user-access-token" &&
+				values.Get("token_type_hint") == "access_token"
+		},
+	}
+	reg.Register(stub)
+
+	err := RevokeToken(httpmock.NewClient(reg), "cli_a", "secret_b", core.BrandFeishu, "user-access-token", "access_token")
+	if err != nil {
+		t.Fatalf("RevokeToken() error = %v", err)
+	}
+	if got := stub.CapturedHeaders.Get("Content-Type"); got != "application/x-www-form-urlencoded" {
+		t.Fatalf("Content-Type = %q", got)
+	}
+}
+
+func TestRevokeToken_DoFailureReturnsTypedNetworkError(t *testing.T) {
+	sentinel := errors.New("transport down")
+	httpClient := &http.Client{
+		Transport: revokeRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+			return nil, sentinel
+		}),
+	}
+
+	err := RevokeToken(httpClient, "cli_a", "secret_b", core.BrandFeishu, "user-access-token", "access_token")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T", err)
+	}
+	if p.Category != errs.CategoryNetwork || p.Subtype != errs.SubtypeNetworkTransport {
+		t.Fatalf("problem = %#v, want network/transport", p)
+	}
+	if !errors.Is(err, sentinel) {
+		t.Fatalf("expected cause %v to be preserved, got %v", sentinel, err)
+	}
+}
+
+func TestRevokeToken_ReportsHTTPError(t *testing.T) {
+	reg := &httpmock.Registry{}
+	t.Cleanup(func() { reg.Verify(t) })
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    PathOAuthRevoke,
+		Status: 400,
+		Body:   map[string]interface{}{"error": "invalid_token"},
+	})
+
+	err := RevokeToken(httpmock.NewClient(reg), "cli_a", "secret_b", core.BrandFeishu, "user-access-token", "access_token")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T", err)
+	}
+	if p.Category != errs.CategoryAPI || p.Code != 400 {
+		t.Fatalf("problem = %#v, want api error with HTTP 400", p)
+	}
+	if !strings.Contains(err.Error(), "invalid_token") {
+		t.Fatalf("expected invalid_token error, got %v", err)
+	}
+}
+
+func TestRevokeToken_ReportsOAuthCodeErrorAsTypedAPIError(t *testing.T) {
+	reg := &httpmock.Registry{}
+	t.Cleanup(func() { reg.Verify(t) })
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    PathOAuthRevoke,
+		Body: map[string]interface{}{
+			"code": 12345,
+			"msg":  "invalid revoke state",
+		},
+	})
+
+	err := RevokeToken(httpmock.NewClient(reg), "cli_a", "secret_b", core.BrandFeishu, "user-access-token", "access_token")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T", err)
+	}
+	if p.Category != errs.CategoryAPI || p.Code != 12345 {
+		t.Fatalf("problem = %#v, want api error with code 12345", p)
+	}
+	if !strings.Contains(err.Error(), "invalid revoke state") {
+		t.Fatalf("expected oauth error message, got %v", err)
+	}
+}
+
+func TestRevokeToken_ReportsOAuthErrorFieldAsTypedAPIError(t *testing.T) {
+	reg := &httpmock.Registry{}
+	t.Cleanup(func() { reg.Verify(t) })
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    PathOAuthRevoke,
+		Body: map[string]interface{}{
+			"error":             "invalid_token",
+			"error_description": "token already expired",
+		},
+	})
+
+	err := RevokeToken(httpmock.NewClient(reg), "cli_a", "secret_b", core.BrandFeishu, "user-access-token", "access_token")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T", err)
+	}
+	if p.Category != errs.CategoryAPI {
+		t.Fatalf("problem = %#v, want api error", p)
+	}
+	if !strings.Contains(err.Error(), "token already expired") {
+		t.Fatalf("expected oauth error_description, got %v", err)
+	}
+}
+
+func TestRevokeToken_ReadFailureReturnsTypedInternalError(t *testing.T) {
+	sentinel := errors.New("read failed")
+	httpClient := &http.Client{
+		Transport: revokeRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Body:       errReadCloser{err: sentinel},
+				Header:     make(http.Header),
+			}, nil
+		}),
+	}
+
+	err := RevokeToken(httpClient, "cli_a", "secret_b", core.BrandFeishu, "user-access-token", "access_token")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T", err)
+	}
+	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+		t.Fatalf("problem = %#v, want internal/invalid_response", p)
+	}
+	if !errors.Is(err, sentinel) {
+		t.Fatalf("expected cause %v to be preserved, got %v", sentinel, err)
+	}
+	if !strings.Contains(err.Error(), "token revoke read error") {
+		t.Fatalf("expected read error message, got %v", err)
+	}
+	if _, ok := err.(*errs.InternalError); !ok {
+		t.Fatalf("expected *errs.InternalError, got %T", err)
+	}
+}

internal/core/types.go

@@ -22,6 +22,12 @@ func ParseBrand(value string) LarkBrand {
 	return BrandFeishu
 }
 
+// OAuthTokenV3Path is the unified OAuth 2.0 Token Endpoint path on the accounts
+// domain. It serves every grant type (client_credentials for TAT,
+// authorization_code / device_code / refresh_token for UAT) and replaces the
+// legacy per-token endpoints (e.g. /open-apis/auth/v3/tenant_access_token/internal).
+const OAuthTokenV3Path = "/oauth/v3/token"
+
 // Endpoints holds resolved endpoint URLs for different Lark services.
 type Endpoints struct {
 	Open     string // e.g. "https://open.feishu.cn"

internal/core/types_test.go

@@ -42,6 +42,11 @@ func TestResolveEndpoints_EmptyDefaultsToFeishu(t *testing.T) {
 	if ep.Open != "https://open.feishu.cn" {
 		t.Errorf("Open = %q, want feishu.cn for empty brand", ep.Open)
 	}
+	// The unified OAuth v3 Token Endpoint mints TAT on the accounts domain;
+	// pin the default-brand host so a stray non-production domain revert is caught.
+	if ep.Accounts != "https://accounts.feishu.cn" {
+		t.Errorf("Accounts = %q, want accounts.feishu.cn for empty brand", ep.Accounts)
+	}
 }
 
 func TestResolveOpenBaseURL(t *testing.T) {

internal/credential/default_provider.go

@@ -19,33 +19,44 @@ import (
 	extcred "github.com/larksuite/cli/extension/credential"
 )
 
-// classifyTATResponseCode wraps a non-zero TAT endpoint response code into the
-// canonical typed error. The TAT mint endpoint reports invalid credentials
-// with two distinct codes:
+// classifyTATResponseCode wraps a deterministic (non-transient) failure from the
+// unified Token Endpoint into the canonical typed errs.* error. The v3 endpoint
+// reports failures using the OAuth 2.0 model — an `error` string plus an
+// optional numeric `code` — instead of the legacy `{code, msg}` shape.
 //
-//   - 10003: bad app_id format or non-existent app_id ("invalid param")
-//   - 10014: invalid app_secret ("app secret invalid")
-//
-// Both surface as CategoryConfig/InvalidClient from the user's perspective —
-// the configured credentials cannot mint a tenant access token. 10014 is
-// globally mapped in codemeta (TAT-mint-specific variant of OAuth 99991543).
-// 10003 is NOT globally mapped because in other Lark endpoints it carries
-// unrelated semantics (e.g. task API uses 10003 for permission denied), so
-// the override stays local to this TAT call site instead of leaking into the
-// shared codemeta table.
-func classifyTATResponseCode(code int, msg, brand, appID string) error {
-	if code == 10003 {
+// invalid_client / unauthorized_client mean the configured app_id/app_secret
+// cannot mint a token; from the user's perspective that is the same actionable
+// CategoryConfig/InvalidClient failure the legacy 10003/10014 codes produced.
+// Every other deterministic error falls through to BuildAPIError, which still
+// yields a typed error so probe callers (errs.IsTyped) surface it rather than
+// swallowing it. Transient/server-side failures (5xx / server_error) are
+// filtered out by FetchTAT before this is called, so they stay untyped.
+func classifyTATResponseCode(code int, oauthErr, errDesc, brand, appID string) error {
+	msg := errDesc
+	if msg == "" {
+		msg = oauthErr
+	}
+	switch oauthErr {
+	case "invalid_client", "unauthorized_client":
 		return errs.NewConfigError(errs.SubtypeInvalidClient, "%s", msg).
 			WithCode(code).
 			WithHint("%s", errclass.ConfigHint(errs.SubtypeInvalidClient))
 	}
-	return errclass.BuildAPIError(map[string]any{
+	if err := errclass.BuildAPIError(map[string]any{
 		"code": code,
 		"msg":  msg,
 	}, errclass.ClassifyContext{
 		Brand: brand,
 		AppID: appID,
-	})
+	}); err != nil {
+		return err
+	}
+	// BuildAPIError returns nil for code 0 (Feishu's success convention), but this
+	// function is only reached once FetchTAT has ruled out success — a non-credential
+	// OAuth error (e.g. invalid_scope) can arrive with code 0 and is still a
+	// deterministic rejection. Back it with a typed APIError so callers never receive
+	// the ("", nil) "empty token, no error" pair.
+	return errs.NewAPIError(errs.SubtypeUnknown, "%s", msg).WithCode(code)
 }
 
 // DefaultAccountProvider resolves account from config.json via keychain.
@@ -146,8 +157,8 @@ func (p *DefaultTokenProvider) resolveUAT(ctx context.Context) (*TokenResult, er
 	return &TokenResult{Token: token, Scopes: scopes}, nil
 }
 
-// resolveTAT resolves a tenant access token. Result is cached after first call.
-// NOTE: Uses sync.Once — only the context from the first call is used.
+// resolveTAT resolves a tenant access token. The result is cached after the first
+// call via sync.Once — only the context from the first call is used.
 func (p *DefaultTokenProvider) resolveTAT(ctx context.Context) (*TokenResult, error) {
 	p.tatOnce.Do(func() {
 		p.tatResult, p.tatErr = p.doResolveTAT(ctx)

internal/credential/default_provider_test.go

@@ -19,18 +19,16 @@ func TestDefaultAccountProvider_Implements(t *testing.T) {
 	var _ DefaultAccountResolver = &DefaultAccountProvider{}
 }
 
-// TestClassifyTATResponseCode_10003_MapsToInvalidClient pins that the TAT
-// endpoint's "invalid param" code surfaces as CategoryConfig/InvalidClient.
-// Reason: a bad or non-existent app_id triggers 10003 on the TAT mint endpoint,
-// which from the user's perspective is the same actionable failure as 10014
-// ("app secret invalid") — both mean the configured credentials cannot mint a
-// tenant access token. The global codemeta intentionally does not map 10003
-// because in other Lark endpoints 10003 carries unrelated semantics (e.g. task
-// API uses it for permission denied), so the override is local to this site.
-func TestClassifyTATResponseCode_10003_MapsToInvalidClient(t *testing.T) {
-	err := classifyTATResponseCode(10003, "invalid param", "feishu", "cli_app_x")
+// TestClassifyTATResponseCode_InvalidClient_MapsToInvalidClient pins that the
+// unified Token Endpoint's OAuth2 invalid_client error surfaces as
+// CategoryConfig/InvalidClient — the configured app_id/app_secret cannot mint a
+// tenant access token, the same actionable failure the legacy 10003/10014 codes
+// produced. The numeric code is intentionally not asserted: the v3 endpoint may
+// return invalid_client with no Lark code (code defaults to 0).
+func TestClassifyTATResponseCode_InvalidClient_MapsToInvalidClient(t *testing.T) {
+	err := classifyTATResponseCode(0, "invalid_client", "client authentication failed", "feishu", "cli_app_x")
 	if err == nil {
-		t.Fatal("expected non-nil error for code=10003")
+		t.Fatal("expected non-nil error for invalid_client")
 	}
 	var cfgErr *errs.ConfigError
 	if !errors.As(err, &cfgErr) {
@@ -42,22 +40,16 @@ func TestClassifyTATResponseCode_10003_MapsToInvalidClient(t *testing.T) {
 	if cfgErr.Subtype != errs.SubtypeInvalidClient {
 		t.Errorf("Subtype = %q, want %q", cfgErr.Subtype, errs.SubtypeInvalidClient)
 	}
-	if cfgErr.Code != 10003 {
-		t.Errorf("Code = %d, want 10003", cfgErr.Code)
-	}
 	if cfgErr.Hint == "" {
 		t.Error("Hint must be non-empty so the user gets a recovery action")
 	}
 }
 
-// TestClassifyTATResponseCode_10014_RoutesViaCodeMeta pins that 10014 still
-// goes through the global BuildAPIError path (codemeta entry) so the override
-// for 10003 does not regress the existing mapping.
-func TestClassifyTATResponseCode_10014_RoutesViaCodeMeta(t *testing.T) {
-	err := classifyTATResponseCode(10014, "app secret invalid", "feishu", "cli_app_x")
-	if err == nil {
-		t.Fatal("expected non-nil error for code=10014")
-	}
+// TestClassifyTATResponseCode_UnauthorizedClient_MapsToInvalidClient pins that
+// unauthorized_client is treated as the same credential failure as
+// invalid_client.
+func TestClassifyTATResponseCode_UnauthorizedClient_MapsToInvalidClient(t *testing.T) {
+	err := classifyTATResponseCode(0, "unauthorized_client", "client not authorized", "feishu", "cli_app_x")
 	var cfgErr *errs.ConfigError
 	if !errors.As(err, &cfgErr) {
 		t.Fatalf("expected *errs.ConfigError, got %T: %v", err, err)
@@ -65,21 +57,38 @@ func TestClassifyTATResponseCode_10014_RoutesViaCodeMeta(t *testing.T) {
 	if cfgErr.Subtype != errs.SubtypeInvalidClient {
 		t.Errorf("Subtype = %q, want %q", cfgErr.Subtype, errs.SubtypeInvalidClient)
 	}
-	if cfgErr.Code != 10014 {
-		t.Errorf("Code = %d, want 10014", cfgErr.Code)
-	}
 }
 
-// TestClassifyTATResponseCode_UnknownCodeFallsThrough pins that codes outside
-// the credential set fall through to the generic BuildAPIError fallback
-// (CategoryAPI/SubtypeUnknown) — the override is narrow and intentional.
-func TestClassifyTATResponseCode_UnknownCodeFallsThrough(t *testing.T) {
-	err := classifyTATResponseCode(99999999, "some unknown failure", "feishu", "cli_app_x")
+// TestClassifyTATResponseCode_OtherErrorFallsThrough pins that OAuth errors
+// outside the credential set fall through to the generic BuildAPIError fallback
+// — still typed, but not a ConfigError. The mapping is narrow and intentional.
+func TestClassifyTATResponseCode_OtherErrorFallsThrough(t *testing.T) {
+	err := classifyTATResponseCode(20068, "invalid_scope", "unauthorized scope", "feishu", "cli_app_x")
 	if err == nil {
-		t.Fatal("expected non-nil error for unmapped code")
+		t.Fatal("expected non-nil error for invalid_scope")
 	}
 	var cfgErr *errs.ConfigError
 	if errors.As(err, &cfgErr) {
-		t.Fatalf("unmapped code must not be classified as ConfigError, got %T", err)
+		t.Fatalf("invalid_scope must not be classified as ConfigError, got %T", err)
+	}
+}
+
+// TestClassifyTATResponseCode_CodeZeroOtherError_StillTyped pins the code-0
+// backstop: a non-credential OAuth error (e.g. invalid_scope) that arrives with no
+// numeric code (code 0) must still produce a non-nil typed error. BuildAPIError
+// returns nil for code 0 (Feishu's success convention); without the backstop,
+// FetchTAT would surface this deterministic rejection as ("", nil) — an empty token
+// with no error.
+func TestClassifyTATResponseCode_CodeZeroOtherError_StillTyped(t *testing.T) {
+	err := classifyTATResponseCode(0, "invalid_scope", "the requested scope is not granted", "feishu", "cli_app_x")
+	if err == nil {
+		t.Fatal("expected non-nil error for code-0 invalid_scope (must not be swallowed as success)")
+	}
+	if !errs.IsTyped(err) {
+		t.Fatalf("expected a typed errs.* error, got %T %v", err, err)
+	}
+	var cfgErr *errs.ConfigError
+	if errors.As(err, &cfgErr) {
+		t.Fatalf("code-0 invalid_scope must not be a ConfigError, got %T", err)
 	}
 }

internal/credential/tat_fetch.go

@@ -4,46 +4,47 @@
 package credential
 
 import (
-	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	"net/http"
+	"net/url"
+	"strings"
 
 	"github.com/larksuite/cli/internal/core"
 )
 
-// FetchTAT performs a single HTTP POST to mint a tenant access token with the
-// given credentials. It does not read configuration or keychain, so callers
-// that already hold plaintext credentials (e.g. the post-`config init` probe)
-// can validate them without a second keychain round-trip.
+// FetchTAT performs a single HTTP POST to mint a tenant access token via the
+// unified OAuth 2.0 Token Endpoint ({accounts}/oauth/v3/token) using the
+// client_credentials grant with client_secret_post authentication. It does not
+// read configuration or keychain, so callers that already hold plaintext
+// credentials (e.g. the post-`config init` probe) can validate them without a
+// second keychain round-trip.
 //
-// A non-zero TAT response code means the server inspected the payload and
-// rejected the credentials; FetchTAT returns the canonical typed error from
-// classifyTATResponseCode — the SAME classification doResolveTAT (and thus
-// every token-resolving command) produces, so callers see one consistent
-// envelope (CategoryConfig / SubtypeInvalidClient for 10003 / 10014, etc.).
-// Transport, HTTP-status and JSON-parse failures are returned raw (untyped),
-// leaving them ambiguous; a caller can use errs.IsTyped to tell a deterministic
-// credential rejection apart from upstream/transport noise.
+// A deterministic client-side rejection (e.g. invalid_client) returns the
+// canonical typed error from classifyTATResponseCode — the SAME classification
+// doResolveTAT (and thus every token-resolving command) produces, so callers
+// see one consistent envelope. Transport failures, unreadable/unparseable
+// bodies, and transient server-side failures (5xx / server_error) are returned
+// raw (untyped), leaving them ambiguous; a caller can use errs.IsTyped to tell a
+// deterministic credential rejection apart from upstream/transport noise.
 //
 // The caller owns the context timeout.
 func FetchTAT(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, appID, appSecret string) (string, error) {
 	ep := core.ResolveEndpoints(brand)
-	url := ep.Open + "/open-apis/auth/v3/tenant_access_token/internal"
+	endpoint := ep.Accounts + core.OAuthTokenV3Path
 
-	body, err := json.Marshal(map[string]string{
-		"app_id":     appID,
-		"app_secret": appSecret,
-	})
-	if err != nil {
-		return "", fmt.Errorf("failed to marshal TAT request: %w", err)
-	}
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
+	form := url.Values{}
+	form.Set("grant_type", "client_credentials")
+	form.Set("client_id", appID)
+	form.Set("client_secret", appSecret)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, strings.NewReader(form.Encode()))
 	if err != nil {
 		return "", err
 	}
-	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
 
 	resp, err := httpClient.Do(req)
 	if err != nil {
@@ -51,20 +52,51 @@ func FetchTAT(ctx context.Context, httpClient *http.Client, brand core.LarkBrand
 	}
 	defer resp.Body.Close()
 
-	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("TAT API returned HTTP %d", resp.StatusCode)
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return "", fmt.Errorf("failed to read TAT response: %w", err)
 	}
 
 	var result struct {
-		Code              int    `json:"code"`
-		Msg               string `json:"msg"`
-		TenantAccessToken string `json:"tenant_access_token"`
+		Code             int    `json:"code"`
+		AccessToken      string `json:"access_token"`
+		Error            string `json:"error"`
+		ErrorDescription string `json:"error_description"`
+		Msg              string `json:"msg"`
 	}
-	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-		return "", fmt.Errorf("failed to parse TAT response: %w", err)
+	if err := json.Unmarshal(body, &result); err != nil {
+		// An unparseable body is ambiguous (covers non-JSON error pages and
+		// truncated payloads); stay untyped so probe callers treat it as noise.
+		return "", fmt.Errorf("failed to parse TAT response (HTTP %d): %w", resp.StatusCode, err)
 	}
-	if result.Code != 0 {
-		return "", classifyTATResponseCode(result.Code, result.Msg, string(brand), appID)
+
+	if result.Code == 0 && result.AccessToken != "" {
+		return result.AccessToken, nil
 	}
-	return result.TenantAccessToken, nil
+
+	// Transient/server-side failures stay untyped so probe callers stay silent and
+	// retryers can back off; only deterministic client rejections are typed. Covers
+	// 5xx, HTTP 429 rate-limit, and the OAuth transient error strings (server_error,
+	// temporarily_unavailable, slow_down) — matching the legacy "non-2xx is noise"
+	// behavior so a rate-limited probe is not surfaced as a hard credential error.
+	if resp.StatusCode >= 500 || resp.StatusCode == http.StatusTooManyRequests ||
+		result.Error == "server_error" || result.Error == "temporarily_unavailable" ||
+		result.Error == "slow_down" {
+		return "", fmt.Errorf("TAT endpoint transient failure (HTTP %d, code=%d, error=%q): %s",
+			resp.StatusCode, result.Code, result.Error, result.ErrorDescription)
+	}
+
+	// A 2xx with neither token nor error is a malformed success — ambiguous, untyped.
+	if result.Code == 0 && result.Error == "" {
+		return "", fmt.Errorf("TAT response missing access_token (HTTP %d)", resp.StatusCode)
+	}
+
+	// Prefer the OAuth error_description; fall back to the legacy Lark `msg` so a
+	// gateway-level {code, msg} response (carrying no OAuth fields) still yields a
+	// non-empty typed message instead of a bare "API error: [code]".
+	desc := result.ErrorDescription
+	if desc == "" {
+		desc = result.Msg
+	}
+	return "", classifyTATResponseCode(result.Code, result.Error, desc, string(brand), appID)
 }

internal/credential/tat_fetch_test.go

@@ -44,7 +44,7 @@ func (s *stubRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
 func TestFetchTAT_Success(t *testing.T) {
 	rt := &stubRoundTripper{
 		respCode: 200,
-		respBody: `{"code":0,"tenant_access_token":"t-abc","msg":"ok"}`,
+		respBody: `{"code":0,"access_token":"t-abc","token_type":"Bearer","expires_in":7200}`,
 	}
 	hc := &http.Client{Transport: rt}
 
@@ -55,24 +55,33 @@ func TestFetchTAT_Success(t *testing.T) {
 	if token != "t-abc" {
 		t.Errorf("token = %q, want t-abc", token)
 	}
-	if rt.gotReq.URL.String() != "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" {
+	if rt.gotReq.URL.String() != "https://accounts.feishu.cn/oauth/v3/token" {
 		t.Errorf("url = %s", rt.gotReq.URL.String())
 	}
-	if !strings.Contains(rt.gotBody, `"app_id":"cli_app"`) || !strings.Contains(rt.gotBody, `"app_secret":"secret_x"`) {
-		t.Errorf("request body missing credentials: %s", rt.gotBody)
+	if ct := rt.gotReq.Header.Get("Content-Type"); ct != "application/x-www-form-urlencoded" {
+		t.Errorf("Content-Type = %q, want application/x-www-form-urlencoded", ct)
+	}
+	// client_secret_post: grant_type + client_id + client_secret in the form body.
+	for _, want := range []string{"grant_type=client_credentials", "client_id=cli_app", "client_secret=secret_x"} {
+		if !strings.Contains(rt.gotBody, want) {
+			t.Errorf("request body missing %q: %s", want, rt.gotBody)
+		}
 	}
 }
 
-// 10003 (bad / non-existent app_id, "invalid param") is classified locally by
+// invalid_client (wrong app_id/app_secret on the client_credentials grant) is a
+// deterministic client-side rejection that FetchTAT routes to
 // classifyTATResponseCode as CategoryConfig / SubtypeInvalidClient — the same
 // typed error doResolveTAT (and thus every token-resolving command) returns.
-func TestFetchTAT_Code10003_ConfigInvalidClient(t *testing.T) {
-	rt := &stubRoundTripper{respCode: 200, respBody: `{"code":10003,"msg":"invalid param"}`}
+// The v3 endpoint reports it as HTTP 400 with the OAuth2 error body (wrong
+// secret → code 20002, unknown app → code 20048).
+func TestFetchTAT_InvalidClient_ConfigInvalidClient(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 400, respBody: `{"error":"invalid_client","error_description":"The client secret is invalid.","code":20002}`}
 	hc := &http.Client{Transport: rt}
 
 	token, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
 	if err == nil {
-		t.Fatal("expected error for code 10003")
+		t.Fatal("expected error for invalid_client")
 	}
 	if token != "" {
 		t.Errorf("token = %q, want empty", token)
@@ -87,52 +96,115 @@ func TestFetchTAT_Code10003_ConfigInvalidClient(t *testing.T) {
 	if cfgErr.Subtype != errs.SubtypeInvalidClient {
 		t.Errorf("Subtype = %q, want %q", cfgErr.Subtype, errs.SubtypeInvalidClient)
 	}
-	if cfgErr.Code != 10003 {
-		t.Errorf("Code = %d, want 10003", cfgErr.Code)
-	}
 }
 
-// 10014 ("app secret invalid") — the most common real-world rejection (real
-// app_id + wrong secret) — is globally mapped in codemeta to
-// CategoryConfig / SubtypeInvalidClient via BuildAPIError.
-func TestFetchTAT_Code10014_ConfigInvalidClient(t *testing.T) {
-	rt := &stubRoundTripper{respCode: 200, respBody: `{"code":10014,"msg":"app secret invalid"}`}
-	hc := &http.Client{Transport: rt}
-
-	_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
-	var cfgErr *errs.ConfigError
-	if !errors.As(err, &cfgErr) {
-		t.Fatalf("error not *errs.ConfigError: %T %v", err, err)
-	}
-	if cfgErr.Subtype != errs.SubtypeInvalidClient || cfgErr.Code != 10014 {
-		t.Errorf("got Subtype=%q Code=%d, want invalid_client/10014", cfgErr.Subtype, cfgErr.Code)
-	}
-}
-
-// Any non-zero body code is a deterministic server-side rejection, so it
-// always yields a typed error (errs.IsTyped). An unrecognized code falls back
-// to CategoryAPI / SubtypeUnknown via BuildAPIError — still typed, so a probe
-// caller still surfaces it rather than silently swallowing.
-func TestFetchTAT_UnknownBodyCode_Typed(t *testing.T) {
-	rt := &stubRoundTripper{respCode: 200, respBody: `{"code":99999,"msg":"future-unknown"}`}
+// Any other deterministic client-side OAuth error (e.g. invalid_scope) still
+// yields a typed error (errs.IsTyped) via BuildAPIError — so a probe caller
+// surfaces it rather than silently swallowing it — but is NOT classified as a
+// credential (invalid_client) problem.
+func TestFetchTAT_OtherClientError_Typed(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 400, respBody: `{"code":20068,"error":"invalid_scope","error_description":"unauthorized scope"}`}
 	hc := &http.Client{Transport: rt}
 
 	_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
 	if err == nil {
-		t.Fatal("expected error for code 99999")
+		t.Fatal("expected error for invalid_scope")
 	}
 	if !errs.IsTyped(err) {
 		t.Fatalf("expected a typed errs.* error, got %T %v", err, err)
 	}
-	var apiErr *errs.APIError
-	if !errors.As(err, &apiErr) {
-		t.Errorf("unknown code should fall back to *errs.APIError, got %T", err)
+	var cfgErr *errs.ConfigError
+	if errors.As(err, &cfgErr) {
+		t.Errorf("invalid_scope must not be classified as ConfigError/InvalidClient, got %T", err)
 	}
 }
 
-// Non-2xx HTTP is ambiguous (not a payload-level credential rejection) — it
-// must stay UNTYPED so a probe caller treats it as upstream noise and stays
-// silent.
+// A deterministic OAuth error that arrives WITHOUT a numeric code (code defaults to
+// 0) must still surface as a non-nil typed error — never the ("", nil) success pair.
+// Guards the code-0 backstop in classifyTATResponseCode: BuildAPIError returns nil
+// for code 0, which would otherwise swallow this rejection into an empty-token success.
+func TestFetchTAT_OtherClientError_CodeZero_Typed(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 400, respBody: `{"error":"invalid_scope","error_description":"the requested scope is not granted"}`}
+	hc := &http.Client{Transport: rt}
+
+	tok, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+	if err == nil {
+		t.Fatal("expected non-nil error for code-0 invalid_scope (must not return empty token + nil error)")
+	}
+	if tok != "" {
+		t.Errorf("token = %q, want empty", tok)
+	}
+	if !errs.IsTyped(err) {
+		t.Fatalf("expected a typed errs.* error, got %T %v", err, err)
+	}
+}
+
+// A gateway-style {code, msg} error (no OAuth error / error_description fields)
+// must still surface its msg on the typed error, not degrade to a generic
+// "API error: [code]". Guards the legacy-msg fallback in FetchTAT.
+func TestFetchTAT_LarkStyleMsg_FallsBackOnTypedError(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 400, respBody: `{"code":99999,"msg":"app ticket invalid"}`}
+	hc := &http.Client{Transport: rt}
+
+	_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+	if err == nil {
+		t.Fatal("expected error for {code, msg} response")
+	}
+	if !errs.IsTyped(err) {
+		t.Fatalf("expected a typed errs.* error, got %T %v", err, err)
+	}
+	if !strings.Contains(err.Error(), "app ticket invalid") {
+		t.Errorf("typed error must carry the Lark msg, got: %v", err)
+	}
+}
+
+// Transient server-side failures (5xx / server_error) are NOT deterministic
+// credential rejections — they must stay UNTYPED so a probe caller treats them
+// as upstream noise and stays silent (and retryers can back off).
+func TestFetchTAT_ServerError_Untyped(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 500, respBody: `{"code":20050,"error":"server_error","error_description":"please retry"}`}
+	hc := &http.Client{Transport: rt}
+
+	_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+	if err == nil {
+		t.Fatal("expected error for server_error")
+	}
+	if errs.IsTyped(err) {
+		t.Errorf("server_error must be UNTYPED (transient), got typed %T %v", err, err)
+	}
+}
+
+// Rate-limiting is transient, not a deterministic credential rejection — an HTTP
+// 429 (even with a parseable OAuth body) and the OAuth slow_down error must both
+// stay UNTYPED so a rate-limited probe stays silent and retryers can back off.
+func TestFetchTAT_RateLimit_Untyped(t *testing.T) {
+	cases := []struct {
+		name string
+		code int
+		body string
+	}{
+		{"http 429", 429, `{"code":99991400,"error":"too_many_requests","error_description":"rate limit exceeded"}`},
+		{"oauth slow_down", 200, `{"error":"slow_down","error_description":"polling too fast"}`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			rt := &stubRoundTripper{respCode: tc.code, respBody: tc.body}
+			hc := &http.Client{Transport: rt}
+
+			_, err := FetchTAT(context.Background(), hc, core.BrandFeishu, "cli_app", "secret_x")
+			if err == nil {
+				t.Fatal("expected error for rate-limit")
+			}
+			if errs.IsTyped(err) {
+				t.Errorf("rate-limit must be UNTYPED (transient), got typed %T %v", err, err)
+			}
+		})
+	}
+}
+
+// Non-2xx HTTP with a non-JSON body is ambiguous (not a structured OAuth
+// rejection) — it must stay UNTYPED so a probe caller treats it as upstream
+// noise and stays silent.
 func TestFetchTAT_HTTPNon200_Untyped(t *testing.T) {
 	for _, code := range []int{401, 403, 500, 503} {
 		rt := &stubRoundTripper{respCode: code, respBody: `whatever`}
@@ -182,12 +254,12 @@ func TestFetchTAT_BrandRouting(t *testing.T) {
 		brand   core.LarkBrand
 		wantURL string
 	}{
-		{core.BrandFeishu, "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"},
-		{core.BrandLark, "https://open.larksuite.com/open-apis/auth/v3/tenant_access_token/internal"},
+		{core.BrandFeishu, "https://accounts.feishu.cn/oauth/v3/token"},
+		{core.BrandLark, "https://accounts.larksuite.com/oauth/v3/token"},
 	}
 	for _, tc := range tests {
 		t.Run(string(tc.brand), func(t *testing.T) {
-			rt := &stubRoundTripper{respCode: 200, respBody: `{"code":0,"tenant_access_token":"t"}`}
+			rt := &stubRoundTripper{respCode: 200, respBody: `{"code":0,"access_token":"t","token_type":"Bearer"}`}
 			hc := &http.Client{Transport: rt}
 			if _, err := FetchTAT(context.Background(), hc, tc.brand, "a", "b"); err != nil {
 				t.Fatal(err)

internal/errclass/codemeta.go

@@ -65,7 +65,7 @@ var codeMeta = map[int]CodeMeta{
 
 	// CategoryConfig
 	99991543: {Category: errs.CategoryConfig, Subtype: errs.SubtypeInvalidClient}, // RFC 6749 §5.2 — app_id / app_secret incorrect (Open API)
-	10014:    {Category: errs.CategoryConfig, Subtype: errs.SubtypeInvalidClient}, // TAT endpoint — "app secret invalid" (TAT-mint variant of 99991543)
+	10014:    {Category: errs.CategoryConfig, Subtype: errs.SubtypeInvalidClient}, // legacy TAT endpoint — "app secret invalid" (pre-v3 variant of 99991543; CLI now reports invalid_client)
 
 	// CategoryPolicy
 	21000: {Category: errs.CategoryPolicy, Subtype: errs.SubtypeChallengeRequired},

internal/event/bus/bus.go

@@ -262,19 +262,23 @@ func (b *Bus) handleConn(conn net.Conn) {
 
 // handleHello registers a consume connection with the hub; reader carries bytes already pulled off conn.
 func (b *Bus) handleHello(conn net.Conn, reader *bufio.Reader, hello *protocol.Hello) {
-	bc := NewConn(conn, reader, hello.EventKey, hello.EventTypes, hello.PID)
+	subID := hello.SubscriptionID
+	if subID == "" {
+		subID = hello.EventKey
+	}
+	bc := NewConn(conn, reader, hello.EventKey, hello.EventTypes, hello.PID, subID)
 	bc.SetLogger(b.logger)
 
 	// Register + isFirst under one lock; blocks on any in-progress cleanup lock for the same EventKey.
 	firstForKey := b.hub.RegisterAndIsFirst(bc)
 
-	bc.SetCheckLastForKey(func(eventKey string) bool {
-		return b.hub.AcquireCleanupLock(eventKey)
+	bc.SetCheckLastForKey(func(scope string) bool {
+		return b.hub.AcquireCleanupLock(scope)
 	})
 	bc.SetOnClose(func(c *Conn) {
 		b.hub.UnregisterAndIsLast(c)
 		// Release is idempotent and must fire on every disconnect path so waiters don't block forever.
-		b.hub.ReleaseCleanupLock(c.EventKey())
+		b.hub.ReleaseCleanupLock(c.SubscriptionID())
 		b.mu.Lock()
 		delete(b.conns, c)
 		remaining := len(b.conns)

internal/event/bus/bus_shutdown_test.go

@@ -33,7 +33,7 @@ func TestRunShutdownWithMultipleConns(t *testing.T) {
 		server, client := net.Pipe()
 		pipes = append(pipes, server, client)
 
-		bc := NewConn(server, nil, "im.msg", []string{"im.message.receive_v1"}, 1000+i)
+		bc := NewConn(server, nil, "im.msg", []string{"im.message.receive_v1"}, 1000+i, "")
 		bc.SetLogger(logger)
 		hub.RegisterAndIsFirst(bc)
 

internal/event/bus/conn.go

@@ -29,9 +29,10 @@ type Conn struct {
 	writeMu         sync.Mutex // serialises all net.Conn writes (Encode+SetWriteDeadline is a 2-call sequence)
 	eventKey        string
 	eventTypes      []string
+	subID           string
 	pid             int
 	onClose         func(*Conn)
-	checkLastForKey func(eventKey string) bool
+	checkLastForKey func(scope string) bool
 	logger          *log.Logger
 	closed          chan struct{}
 	closeOnce       sync.Once
@@ -41,7 +42,7 @@ type Conn struct {
 }
 
 // NewConn creates a Conn; pass a reader with pre-buffered bytes (handoff from Bus.handleConn) or nil for a fresh one.
-func NewConn(conn net.Conn, reader *bufio.Reader, eventKey string, eventTypes []string, pid int) *Conn {
+func NewConn(conn net.Conn, reader *bufio.Reader, eventKey string, eventTypes []string, pid int, subID string) *Conn {
 	if reader == nil {
 		reader = bufio.NewReader(conn)
 	}
@@ -52,10 +53,20 @@ func NewConn(conn net.Conn, reader *bufio.Reader, eventKey string, eventTypes []
 		eventKey:   eventKey,
 		eventTypes: eventTypes,
 		pid:        pid,
+		subID:      subID,
 		closed:     make(chan struct{}),
 	}
 }
 
+// SubscriptionID returns the subscription identity. Falls back to EventKey
+// when the stored subID is empty (legacy clients / no-SubscriptionKey EventKeys).
+func (c *Conn) SubscriptionID() string {
+	if c.subID == "" {
+		return c.eventKey
+	}
+	return c.subID
+}
+
 func (c *Conn) SetOnClose(fn func(*Conn)) { c.onClose = fn }
 
 // SetCheckLastForKey: returning true means "you are the last subscriber, run cleanup".
@@ -132,13 +143,19 @@ func (c *Conn) ReaderLoop() {
 }
 
 func (c *Conn) handleControlMessage(msg interface{}) {
-	switch m := msg.(type) {
+	switch msg.(type) {
 	case *protocol.Bye:
 		c.shutdown()
 	case *protocol.PreShutdownCheck:
+		// Use the connection's own authoritative subscription identity rather
+		// than recomputing from the incoming message: a stale or mismatched
+		// PreShutdownCheck must not ask about the wrong scope (which would
+		// suppress or mistrigger per-subscription cleanup). Conn.SubscriptionID()
+		// already falls back to EventKey when its stored subID is empty.
+		scope := c.SubscriptionID()
 		lastForKey := true
 		if c.checkLastForKey != nil {
-			lastForKey = c.checkLastForKey(m.EventKey)
+			lastForKey = c.checkLastForKey(scope)
 		}
 		ack := protocol.NewPreShutdownAck(lastForKey)
 		if err := c.writeFrame(ack); err != nil && c.logger != nil {

internal/event/bus/conn_test.go

@@ -21,7 +21,7 @@ func TestConn_SenderWritesEvents(t *testing.T) {
 	defer server.Close()
 	defer client.Close()
 
-	bc := NewConn(server, nil, "im.msg", []string{"im.message.receive_v1"}, 12345)
+	bc := NewConn(server, nil, "im.msg", []string{"im.message.receive_v1"}, 12345, "")
 	go bc.SenderLoop()
 
 	bc.SendCh() <- &protocol.Event{
@@ -62,7 +62,7 @@ func TestConn_ConcurrentWritesSerialised(t *testing.T) {
 	defer client.Close()
 
 	det := &serializingDetector{Conn: server}
-	bc := NewConn(det, nil, "im.msg", []string{"im.msg"}, 12345)
+	bc := NewConn(det, nil, "im.msg", []string{"im.msg"}, 12345, "")
 
 	go func() { _, _ = io.Copy(io.Discard, client) }()
 
@@ -106,7 +106,7 @@ func TestConn_TrySend_NonEvicting(t *testing.T) {
 	server, client := net.Pipe()
 	defer server.Close()
 	defer client.Close()
-	bc := NewConn(server, nil, "im.msg", []string{"im.msg"}, 12345)
+	bc := NewConn(server, nil, "im.msg", []string{"im.msg"}, 12345, "")
 
 	for i := 0; i < sendChCap; i++ {
 		if !bc.TrySend(i) {
@@ -126,7 +126,7 @@ func TestConn_ReaderDetectsEOF(t *testing.T) {
 	server, client := net.Pipe()
 	defer server.Close()
 
-	bc := NewConn(server, nil, "im.msg", []string{"im.msg"}, 12345)
+	bc := NewConn(server, nil, "im.msg", []string{"im.msg"}, 12345, "")
 
 	done := make(chan struct{})
 	go func() {
@@ -142,3 +142,23 @@ func TestConn_ReaderDetectsEOF(t *testing.T) {
 		t.Fatal("ReaderLoop did not exit on EOF")
 	}
 }
+
+func TestConn_SubscriptionID(t *testing.T) {
+	c1, c2 := net.Pipe()
+	defer c1.Close()
+	defer c2.Close()
+	conn := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 999, "mail.x:abc")
+	if got := conn.SubscriptionID(); got != "mail.x:abc" {
+		t.Errorf("SubscriptionID() = %q, want %q", got, "mail.x:abc")
+	}
+}
+
+func TestConn_SubscriptionID_EmptyFallsBackToEventKey(t *testing.T) {
+	c1, c2 := net.Pipe()
+	defer c1.Close()
+	defer c2.Close()
+	conn := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 999, "")
+	if got := conn.SubscriptionID(); got != "mail.x" {
+		t.Errorf("SubscriptionID() with empty input = %q, want fallback %q", got, "mail.x")
+	}
+}

internal/event/bus/handle_hello_test.go

@@ -63,3 +63,134 @@ func TestHandleHello_HelloAckWriteFailureUnregisters(t *testing.T) {
 		t.Errorf("b.conns after failed HelloAck = %d entries, want 0", remaining)
 	}
 }
+
+// TestHandleHello_LegacyClient_FallsBackToEventKey: a Hello with empty
+// subscription_id registers under EventKey (today's behavior preserved).
+func TestHandleHello_LegacyClient_FallsBackToEventKey(t *testing.T) {
+	logger := log.New(io.Discard, "", 0)
+	hub := NewHub()
+	b := &Bus{
+		hub:        hub,
+		logger:     logger,
+		conns:      make(map[*Conn]struct{}),
+		idleTimer:  time.NewTimer(30 * time.Second),
+		shutdownCh: make(chan struct{}, 1),
+	}
+
+	server, client := net.Pipe()
+	defer server.Close()
+	defer client.Close()
+
+	// Legacy client: no subscription_id field (empty string).
+	hello := &protocol.Hello{
+		PID:            9999,
+		EventKey:       "im.message",
+		EventTypes:     []string{"im.message.receive_v1"},
+		SubscriptionID: "", // legacy: empty, should fallback to EventKey
+	}
+
+	br := bufio.NewReader(server)
+
+	done := make(chan struct{})
+	go func() {
+		b.handleHello(server, br, hello)
+		close(done)
+	}()
+
+	// Read the HelloAck from client side to let handleHello complete.
+	clientReader := bufio.NewReader(client)
+	ackLine, err := clientReader.ReadString('\n')
+	if err != nil {
+		t.Fatalf("failed to read HelloAck: %v", err)
+	}
+
+	select {
+	case <-done:
+	case <-time.After(3 * time.Second):
+		t.Fatal("handleHello did not return within 3s")
+	}
+
+	// Assertions: registered under EventKey (not a qualified subscription ID).
+	if got := hub.ConnCount(); got != 1 {
+		t.Errorf("hub.ConnCount = %d, want 1", got)
+	}
+	if got := hub.EventKeyCount("im.message"); got != 1 {
+		t.Errorf("hub.EventKeyCount(im.message) = %d, want 1", got)
+	}
+	if got := hub.SubCount("im.message"); got != 1 {
+		t.Errorf("hub.SubCount(im.message) = %d, want 1 (legacy fallback to EventKey)", got)
+	}
+	if got := hub.SubCount("im.message:something"); got != 0 {
+		t.Errorf("hub.SubCount(im.message:something) = %d, want 0 (should not exist)", got)
+	}
+
+	if ackLine == "" {
+		t.Fatal("HelloAck was empty")
+	}
+}
+
+// TestHandleHello_ModernClient_UsesSubscriptionID: a Hello with
+// non-empty subscription_id registers under that ID, not EventKey.
+func TestHandleHello_ModernClient_UsesSubscriptionID(t *testing.T) {
+	logger := log.New(io.Discard, "", 0)
+	hub := NewHub()
+	b := &Bus{
+		hub:        hub,
+		logger:     logger,
+		conns:      make(map[*Conn]struct{}),
+		idleTimer:  time.NewTimer(30 * time.Second),
+		shutdownCh: make(chan struct{}, 1),
+	}
+
+	server, client := net.Pipe()
+	defer server.Close()
+	defer client.Close()
+
+	// Modern client: subscription_id explicitly set.
+	subscriptionID := "mail.message:alice@example.com"
+	hello := &protocol.Hello{
+		PID:            8888,
+		EventKey:       "mail.message",
+		EventTypes:     []string{"mail.message.receive_v1"},
+		SubscriptionID: subscriptionID, // modern: per-resource subscription
+	}
+
+	br := bufio.NewReader(server)
+
+	done := make(chan struct{})
+	go func() {
+		b.handleHello(server, br, hello)
+		close(done)
+	}()
+
+	// Read the HelloAck from client side to let handleHello complete.
+	clientReader := bufio.NewReader(client)
+	ackLine, err := clientReader.ReadString('\n')
+	if err != nil {
+		t.Fatalf("failed to read HelloAck: %v", err)
+	}
+
+	select {
+	case <-done:
+	case <-time.After(3 * time.Second):
+		t.Fatal("handleHello did not return within 3s")
+	}
+
+	// Assertions: registered under the subscription_id, not bare EventKey.
+	if got := hub.ConnCount(); got != 1 {
+		t.Errorf("hub.ConnCount = %d, want 1", got)
+	}
+	if got := hub.EventKeyCount("mail.message"); got != 1 {
+		t.Errorf("hub.EventKeyCount(mail.message) = %d, want 1", got)
+	}
+	if got := hub.SubCount(subscriptionID); got != 1 {
+		t.Errorf("hub.SubCount(%q) = %d, want 1 (modern: uses SubscriptionID)", subscriptionID, got)
+	}
+	if got := hub.SubCount("mail.message"); got != 0 {
+		t.Errorf("hub.SubCount(mail.message) = %d, want 0 (modern: NOT registered under bare EventKey)", got)
+	}
+
+	if ackLine == "" {
+		t.Fatal("HelloAck was empty")
+	}
+}

internal/event/bus/hub.go

@@ -16,6 +16,9 @@ import (
 // Subscriber is the interface a connection must satisfy for Hub registration.
 type Subscriber interface {
 	EventKey() string
+	// SubscriptionID identifies the per-resource subscription for dedup purposes.
+	// When no resource qualifier is needed it equals EventKey.
+	SubscriptionID() string
 	EventTypes() []string
 	SendCh() chan interface{}
 	PID() int
@@ -34,8 +37,11 @@ type Subscriber interface {
 type Hub struct {
 	mu          sync.RWMutex
 	subscribers map[Subscriber]struct{}
-	keyCounts   map[string]int
-	// cleanupInProgress[key] holds a channel closed on release; presence means a cleanup lock is held.
+	// subCounts is keyed by SubscriptionID (not EventKey) so that different
+	// per-resource subscriptions sharing the same EventKey are deduped independently.
+	subCounts map[string]int
+	// cleanupInProgress[subscriptionID] holds a channel closed on release;
+	// presence means a cleanup lock is held for that subscription.
 	cleanupInProgress map[string]chan struct{}
 	logger            atomic.Pointer[log.Logger]
 }
@@ -43,7 +49,7 @@ type Hub struct {
 func NewHub() *Hub {
 	return &Hub{
 		subscribers:       make(map[Subscriber]struct{}),
-		keyCounts:         make(map[string]int),
+		subCounts:         make(map[string]int),
 		cleanupInProgress: make(map[string]chan struct{}),
 	}
 }
@@ -51,7 +57,7 @@ func NewHub() *Hub {
 // SetLogger attaches a logger (nil tolerated).
 func (h *Hub) SetLogger(l *log.Logger) { h.logger.Store(l) }
 
-// UnregisterAndIsLast removes s and reports whether it was last for its EventKey; stale unregisters are no-ops.
+// UnregisterAndIsLast removes s and reports whether it was last for its SubscriptionID; stale unregisters are no-ops.
 func (h *Hub) UnregisterAndIsLast(s Subscriber) bool {
 	h.mu.Lock()
 	defer h.mu.Unlock()
@@ -59,34 +65,35 @@ func (h *Hub) UnregisterAndIsLast(s Subscriber) bool {
 		return false
 	}
 	delete(h.subscribers, s)
-	h.keyCounts[s.EventKey()]--
-	isLast := h.keyCounts[s.EventKey()] == 0
+	sid := s.SubscriptionID()
+	h.subCounts[sid]--
+	isLast := h.subCounts[sid] == 0
 	if isLast {
-		delete(h.keyCounts, s.EventKey())
+		delete(h.subCounts, sid)
 	}
 	return isLast
 }
 
-// AcquireCleanupLock reserves cleanup rights iff exactly one subscriber exists for eventKey and no lock is held.
+// AcquireCleanupLock reserves cleanup rights iff exactly one subscriber exists for subscriptionID and no lock is held.
 // Count==0 is rejected (would block future Register calls). On true return, caller MUST Release.
-func (h *Hub) AcquireCleanupLock(eventKey string) bool {
+func (h *Hub) AcquireCleanupLock(subscriptionID string) bool {
 	h.mu.Lock()
 	defer h.mu.Unlock()
-	if h.keyCounts[eventKey] != 1 {
+	if h.subCounts[subscriptionID] != 1 {
 		return false
 	}
-	if _, alreadyLocked := h.cleanupInProgress[eventKey]; alreadyLocked {
+	if _, alreadyLocked := h.cleanupInProgress[subscriptionID]; alreadyLocked {
 		return false
 	}
-	h.cleanupInProgress[eventKey] = make(chan struct{})
+	h.cleanupInProgress[subscriptionID] = make(chan struct{})
 	return true
 }
 
 // ReleaseCleanupLock is idempotent; OnClose calls unconditionally.
-func (h *Hub) ReleaseCleanupLock(eventKey string) {
+func (h *Hub) ReleaseCleanupLock(subscriptionID string) {
 	h.mu.Lock()
-	ch := h.cleanupInProgress[eventKey]
-	delete(h.cleanupInProgress, eventKey)
+	ch := h.cleanupInProgress[subscriptionID]
+	delete(h.cleanupInProgress, subscriptionID)
 	h.mu.Unlock()
 	if ch != nil {
 		close(ch)
@@ -94,23 +101,24 @@ func (h *Hub) ReleaseCleanupLock(eventKey string) {
 }
 
 // RegisterAndIsFirst adds s to the hub and reports whether it's the first
-// subscriber for its EventKey. If a cleanup is in progress for
-// s.EventKey() (another conn holds the cleanup lock), this waits until
+// subscriber for its SubscriptionID. If a cleanup is in progress for
+// s.SubscriptionID() (another conn holds the cleanup lock), this waits until
 // cleanup releases before registering — closing the PreShutdownCheck ×
 // Hello TOCTOU race. The wait releases h.mu before blocking on the
-// channel, so concurrent operations on other keys aren't stalled.
+// channel, so concurrent operations on other subscriptions aren't stalled.
 func (h *Hub) RegisterAndIsFirst(s Subscriber) bool {
+	sid := s.SubscriptionID()
 	for {
 		h.mu.Lock()
-		ch, locked := h.cleanupInProgress[s.EventKey()]
+		ch, locked := h.cleanupInProgress[sid]
 		if locked {
 			h.mu.Unlock()
 			<-ch // wait for release, then re-check (defensive against races)
 			continue
 		}
-		isFirst := h.keyCounts[s.EventKey()] == 0
+		isFirst := h.subCounts[sid] == 0
 		h.subscribers[s] = struct{}{}
-		h.keyCounts[s.EventKey()]++
+		h.subCounts[sid]++
 		h.mu.Unlock()
 		return isFirst
 	}
@@ -176,11 +184,25 @@ func (h *Hub) ConnCount() int {
 	return len(h.subscribers)
 }
 
-// EventKeyCount returns the number of subscribers registered for eventKey.
+// EventKeyCount returns total subscribers for the given EventKey, aggregating
+// across all SubscriptionIDs. For per-subscription counts use SubCount.
 func (h *Hub) EventKeyCount(eventKey string) int {
 	h.mu.RLock()
 	defer h.mu.RUnlock()
-	return h.keyCounts[eventKey]
+	count := 0
+	for s := range h.subscribers {
+		if s.EventKey() == eventKey {
+			count++
+		}
+	}
+	return count
+}
+
+// SubCount returns the count of subscribers for the given SubscriptionID.
+func (h *Hub) SubCount(subscriptionID string) int {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	return h.subCounts[subscriptionID]
 }
 
 // BroadcastSourceStatus fans out a source-level status change to every
@@ -205,10 +227,11 @@ func (h *Hub) Consumers() []protocol.ConsumerInfo {
 	result := make([]protocol.ConsumerInfo, 0, len(h.subscribers))
 	for s := range h.subscribers {
 		result = append(result, protocol.ConsumerInfo{
-			PID:      s.PID(),
-			EventKey: s.EventKey(),
-			Received: s.Received(),
-			Dropped:  s.DroppedCount(),
+			PID:            s.PID(),
+			EventKey:       s.EventKey(),
+			SubscriptionID: s.SubscriptionID(),
+			Received:       s.Received(),
+			Dropped:        s.DroppedCount(),
 		})
 	}
 	return result

internal/event/bus/hub_observability_test.go

@@ -17,7 +17,7 @@ func TestHubDroppedCountIncrements(t *testing.T) {
 	server, client := testNetPipe(t)
 	defer server.Close()
 	defer client.Close()
-	c := NewConn(server, nil, "k", []string{"t"}, 1)
+	c := NewConn(server, nil, "k", []string{"t"}, 1, "")
 	c.sendCh = make(chan interface{}, 1)
 	h.RegisterAndIsFirst(c)
 
@@ -35,7 +35,7 @@ func TestPublishAssignsIncrementalSeq(t *testing.T) {
 	server, client := testNetPipe(t)
 	defer server.Close()
 	defer client.Close()
-	c := NewConn(server, nil, "k", []string{"t"}, 1)
+	c := NewConn(server, nil, "k", []string{"t"}, 1, "")
 	c.sendCh = make(chan interface{}, 10)
 	h.RegisterAndIsFirst(c)
 
@@ -60,7 +60,7 @@ func TestPublishPopulatesEventIDAndSourceTime(t *testing.T) {
 	server, client := testNetPipe(t)
 	defer server.Close()
 	defer client.Close()
-	c := NewConn(server, nil, "k", []string{"t"}, 1)
+	c := NewConn(server, nil, "k", []string{"t"}, 1, "")
 	c.sendCh = make(chan interface{}, 1)
 	h.RegisterAndIsFirst(c)
 
@@ -87,7 +87,7 @@ func TestPublishSourceTimeTakesPrecedence(t *testing.T) {
 	server, client := testNetPipe(t)
 	defer server.Close()
 	defer client.Close()
-	c := NewConn(server, nil, "k", []string{"t"}, 1)
+	c := NewConn(server, nil, "k", []string{"t"}, 1, "")
 	c.sendCh = make(chan interface{}, 1)
 	h.RegisterAndIsFirst(c)
 
@@ -111,7 +111,7 @@ func TestPublishSourceTimeFallback(t *testing.T) {
 	server, client := testNetPipe(t)
 	defer server.Close()
 	defer client.Close()
-	c := NewConn(server, nil, "k", []string{"t"}, 1)
+	c := NewConn(server, nil, "k", []string{"t"}, 1, "")
 	c.sendCh = make(chan interface{}, 1)
 	h.RegisterAndIsFirst(c)
 

internal/event/bus/hub_publish_race_test.go

@@ -111,6 +111,7 @@ type alwaysFailSubscriber struct {
 }
 
 func (s *alwaysFailSubscriber) EventKey() string         { return s.eventKey }
+func (s *alwaysFailSubscriber) SubscriptionID() string   { return s.eventKey }
 func (s *alwaysFailSubscriber) EventTypes() []string     { return s.eventTypes }
 func (s *alwaysFailSubscriber) SendCh() chan interface{} { return s.sendCh }
 func (s *alwaysFailSubscriber) PID() int                 { return 0 }
@@ -153,6 +154,7 @@ func newRaceSubscriber(key string, types []string, capacity int) *raceSubscriber
 }
 
 func (s *raceSubscriber) EventKey() string         { return s.eventKey }
+func (s *raceSubscriber) SubscriptionID() string   { return s.eventKey }
 func (s *raceSubscriber) EventTypes() []string     { return s.eventTypes }
 func (s *raceSubscriber) SendCh() chan interface{} { return s.sendCh }
 func (s *raceSubscriber) PID() int                 { return s.pid }

internal/event/bus/hub_test.go

@@ -5,6 +5,7 @@ package bus
 
 import (
 	"encoding/json"
+	"net"
 	"sync"
 	"sync/atomic"
 	"testing"
@@ -235,7 +236,10 @@ func newTestConn(eventKey string, eventTypes []string) *testConn {
 	}
 }
 
-func (c *testConn) EventKey() string         { return c.eventKey }
+func (c *testConn) EventKey() string { return c.eventKey }
+
+// SubscriptionID falls back to EventKey for test mocks that don't set a separate subscription ID.
+func (c *testConn) SubscriptionID() string   { return c.eventKey }
 func (c *testConn) EventTypes() []string     { return c.eventTypes }
 func (c *testConn) SendCh() chan interface{} { return c.sendCh }
 func (c *testConn) PID() int                 { return c.pid }
@@ -275,3 +279,79 @@ func (c *testConn) TrySend(msg interface{}) bool {
 		return false
 	}
 }
+
+func TestHub_SubscriptionID_Isolation(t *testing.T) {
+	h := NewHub()
+	c1, _ := net.Pipe()
+	c2, _ := net.Pipe()
+	defer c1.Close()
+	defer c2.Close()
+	s1 := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 1, "mail.x:alice")
+	s2 := NewConn(c2, nil, "mail.x", []string{"mail.x"}, 2, "mail.x:bob")
+
+	if !h.RegisterAndIsFirst(s1) {
+		t.Error("s1 should be first for its subscription")
+	}
+	if !h.RegisterAndIsFirst(s2) {
+		t.Error("s2 should ALSO be first (different SubscriptionID)")
+	}
+	if !h.UnregisterAndIsLast(s1) {
+		t.Error("s1 should be last for mail.x:alice")
+	}
+	if !h.UnregisterAndIsLast(s2) {
+		t.Error("s2 should be last for mail.x:bob")
+	}
+}
+
+func TestHub_SameSubscriptionID_NotFirst(t *testing.T) {
+	h := NewHub()
+	c1, _ := net.Pipe()
+	c2, _ := net.Pipe()
+	defer c1.Close()
+	defer c2.Close()
+	s1 := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 1, "mail.x:alice")
+	s2 := NewConn(c2, nil, "mail.x", []string{"mail.x"}, 2, "mail.x:alice")
+
+	if !h.RegisterAndIsFirst(s1) {
+		t.Error("s1 first")
+	}
+	if h.RegisterAndIsFirst(s2) {
+		t.Error("s2 same SubscriptionID should NOT be first")
+	}
+}
+
+func TestHub_EventKeyCount_AggregatesAcrossSubscriptions(t *testing.T) {
+	h := NewHub()
+	c1, _ := net.Pipe()
+	c2, _ := net.Pipe()
+	defer c1.Close()
+	defer c2.Close()
+	s1 := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 1, "mail.x:alice")
+	s2 := NewConn(c2, nil, "mail.x", []string{"mail.x"}, 2, "mail.x:bob")
+	h.RegisterAndIsFirst(s1)
+	h.RegisterAndIsFirst(s2)
+	if got := h.EventKeyCount("mail.x"); got != 2 {
+		t.Errorf("EventKeyCount(mail.x) = %d, want 2 (aggregated across subscriptions)", got)
+	}
+	if got := h.SubCount("mail.x:alice"); got != 1 {
+		t.Errorf("SubCount(mail.x:alice) = %d, want 1", got)
+	}
+	if got := h.SubCount("mail.x:bob"); got != 1 {
+		t.Errorf("SubCount(mail.x:bob) = %d, want 1", got)
+	}
+}
+
+func TestHub_Consumers_PopulatesSubscriptionID(t *testing.T) {
+	h := NewHub()
+	c1, _ := net.Pipe()
+	defer c1.Close()
+	s1 := NewConn(c1, nil, "mail.x", []string{"mail.x"}, 1, "mail.x:alice")
+	h.RegisterAndIsFirst(s1)
+	consumers := h.Consumers()
+	if len(consumers) != 1 {
+		t.Fatalf("got %d consumers, want 1", len(consumers))
+	}
+	if consumers[0].SubscriptionID != "mail.x:alice" {
+		t.Errorf("Consumers()[0].SubscriptionID = %q, want %q", consumers[0].SubscriptionID, "mail.x:alice")
+	}
+}

internal/event/consume/consume.go

@@ -61,6 +61,22 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 		}
 	}
 
+	// Normalize params (resolve aliases like "me" -> real email) before fingerprint
+	// compute, PreConsume, Match, Process. Must happen BEFORE doHello so the
+	// SubscriptionID we send to bus reflects canonical values.
+	if keyDef.NormalizeParams != nil {
+		if err := keyDef.NormalizeParams(ctx, opts.Runtime, opts.Params); err != nil {
+			if _, ok := errs.ProblemOf(err); ok {
+				return err
+			}
+			return errs.NewInternalError(errs.SubtypeUnknown,
+				"normalize params for %s: %s", opts.EventKey, err).WithCause(err)
+		}
+	}
+
+	// Compute subscription identity from normalized params + SubscriptionKey flags.
+	subscriptionID := ComputeSubscriptionID(keyDef, opts.Params)
+
 	if opts.Timeout > 0 {
 		var cancel context.CancelFunc
 		ctx, cancel = context.WithTimeout(ctx, opts.Timeout)
@@ -81,13 +97,13 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 	}
 	defer conn.Close()
 
-	ack, br, err := doHello(conn, opts.EventKey, []string{keyDef.EventType})
+	ack, br, err := doHello(conn, opts.EventKey, []string{keyDef.EventType}, subscriptionID)
 	if err != nil {
 		return errs.NewInternalError(errs.SubtypeUnknown,
 			"event bus handshake failed: %s", err).WithCause(err)
 	}
 
-	var cleanup func()
+	var cleanup func() error
 	if ack.FirstForKey && keyDef.PreConsume != nil {
 		if !opts.Quiet {
 			fmt.Fprintf(errOut, "[event] running pre-consume setup...\n")
@@ -113,14 +129,22 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 		if cleanup != nil {
 			switch {
 			case r != nil:
-				fmt.Fprintf(errOut, "WARN: panic recovered; running cleanup unconditionally (may affect other consumers of %s)\n", opts.EventKey)
-				cleanup()
+				fmt.Fprintf(errOut,
+					"WARN: panic recovered; running cleanup unconditionally (may affect other consumers of %s)\n",
+					opts.EventKey)
+				if cleanupErr := cleanup(); cleanupErr != nil {
+					fmt.Fprintf(errOut,
+						"WARN: cleanup also failed during panic recovery: %v\n", cleanupErr)
+				}
 			case lastForKey:
 				if !opts.Quiet {
 					fmt.Fprintf(errOut, "[event] running cleanup...\n")
 				}
-				cleanup()
-				if !opts.Quiet {
+				if cleanupErr := cleanup(); cleanupErr != nil {
+					fmt.Fprintf(errOut,
+						"WARN: cleanup failed: %v (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)\n",
+						cleanupErr)
+				} else if !opts.Quiet {
 					fmt.Fprintf(errOut, "[event] cleanup done.\n")
 				}
 			}
@@ -144,7 +168,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 
 	writeReadyMarker(errOut, opts)
 
-	return consumeLoop(ctx, conn, br, keyDef, opts, &lastForKey, &emitted)
+	return consumeLoop(ctx, conn, br, keyDef, opts, subscriptionID, &lastForKey, &emitted)
 }
 
 func truncateDuration(d time.Duration) time.Duration {

internal/event/consume/consume_test.go

@@ -0,0 +1,101 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package consume
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"net"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/event/protocol"
+	"github.com/larksuite/cli/internal/event/transport"
+)
+
+// fakeRT is a minimal event.APIClient mock.
+type fakeRT struct {
+	err error
+}
+
+func (f *fakeRT) CallAPI(_ context.Context, _, _ string, _ interface{}) (json.RawMessage, error) {
+	return nil, f.err
+}
+
+func TestNormalizeParams_ErrorIsWrappedWithEventKey(t *testing.T) {
+	// Drives the real Run() path: NormalizeParams fails before EnsureBus, so no
+	// bus is contacted, yet the production error-wrapping is exercised — if Run()
+	// ever stops wrapping, this test fails.
+	const key = "test.evt_normalize_fail"
+	event.RegisterKey(event.KeyDefinition{
+		Key:       key,
+		EventType: key,
+		Schema:    event.SchemaDef{Custom: &event.SchemaSpec{Raw: json.RawMessage(`{"type":"object"}`)}},
+		NormalizeParams: func(_ context.Context, _ event.APIClient, _ map[string]string) error {
+			return errors.New("simulated normalize failure")
+		},
+	})
+	defer event.UnregisterKeyForTest(key)
+
+	err := Run(context.Background(), transport.New(), "app", "", "", Options{
+		EventKey: key,
+		Runtime:  &fakeRT{},
+		Quiet:    true,
+	})
+	if err == nil {
+		t.Fatal("expected Run to fail when NormalizeParams errors")
+	}
+	if !strings.Contains(err.Error(), "normalize params for "+key+":") {
+		t.Errorf("error not wrapped with EventKey prefix: %v", err)
+	}
+	if !strings.Contains(err.Error(), "simulated normalize failure") {
+		t.Errorf("underlying error not propagated: %v", err)
+	}
+}
+
+func TestDoHello_PassesSubscriptionIDToWire(t *testing.T) {
+	a, b := net.Pipe()
+	defer a.Close()
+	defer b.Close()
+
+	// Server-side: read Hello, decode, assert SubscriptionID, send ack
+	done := make(chan string, 1)
+	go func() {
+		br := bufio.NewReader(b)
+		line, err := protocol.ReadFrame(br)
+		if err != nil {
+			done <- "READ_ERR:" + err.Error()
+			return
+		}
+		msg, err := protocol.Decode(bytes.TrimRight(line, "\n"))
+		if err != nil {
+			done <- "DECODE_ERR:" + err.Error()
+			return
+		}
+		if hello, ok := msg.(*protocol.Hello); ok {
+			done <- hello.SubscriptionID
+			// send ack so client can return
+			ack := protocol.NewHelloAck("v1", true)
+			_ = protocol.EncodeWithDeadline(b, ack, protocol.WriteTimeout)
+		} else {
+			done <- "WRONG_TYPE"
+		}
+	}()
+
+	ack, _, err := doHello(a, "mail.x", []string{"mail.x"}, "mail.x:alice")
+	if err != nil {
+		t.Fatalf("doHello error: %v", err)
+	}
+	if ack == nil {
+		t.Fatal("got nil ack")
+	}
+	got := <-done
+	if got != "mail.x:alice" {
+		t.Errorf("Hello.SubscriptionID on wire = %q, want %q", got, "mail.x:alice")
+	}
+}

internal/event/consume/fingerprint.go

@@ -0,0 +1,41 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package consume
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"sort"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// ComputeSubscriptionID returns a stable identifier scoped to (EventKey, values
+// of the ParamDefs marked SubscriptionKey); the framework uses it to dedup
+// PreConsume/cleanup gates and key Hub counts per-subscription. No SubscriptionKey
+// params -> returns def.Key verbatim (legacy one-dimensional behavior).
+//
+// Stability contract: same EventKey + same normalized param values -> same ID
+// across CLI versions; changing the encoding requires a wire-format bump.
+func ComputeSubscriptionID(def *event.KeyDefinition, params map[string]string) string {
+	type kv struct {
+		Name  string `json:"name"`
+		Value string `json:"value"`
+	}
+	var subParams []kv
+	for _, p := range def.Params {
+		if !p.SubscriptionKey {
+			continue
+		}
+		subParams = append(subParams, kv{Name: p.Name, Value: params[p.Name]})
+	}
+	if len(subParams) == 0 {
+		return def.Key
+	}
+	sort.Slice(subParams, func(i, j int) bool { return subParams[i].Name < subParams[j].Name })
+	raw, _ := json.Marshal(subParams) // err impossible: kv has no unmarshalable fields
+	sum := sha256.Sum256(raw)
+	return def.Key + ":" + base64.RawURLEncoding.EncodeToString(sum[:12])
+}

internal/event/consume/fingerprint_test.go

@@ -0,0 +1,126 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package consume
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+func TestComputeSubscriptionID(t *testing.T) {
+	makeDef := func(subKeyNames ...string) *event.KeyDefinition {
+		def := &event.KeyDefinition{Key: "test.evt"}
+		marked := make(map[string]bool, len(subKeyNames))
+		for _, n := range subKeyNames {
+			marked[n] = true
+		}
+		for _, n := range []string{"alpha", "beta", "gamma"} {
+			def.Params = append(def.Params, event.ParamDef{Name: n, SubscriptionKey: marked[n]})
+		}
+		return def
+	}
+
+	t.Run("no SubscriptionKey params returns EventKey verbatim", func(t *testing.T) {
+		def := makeDef()
+		got := ComputeSubscriptionID(def, map[string]string{"alpha": "x", "beta": "y"})
+		if got != "test.evt" {
+			t.Errorf("got %q, want %q", got, "test.evt")
+		}
+	})
+
+	t.Run("single SubscriptionKey param: non-sub params do not leak into ID", func(t *testing.T) {
+		def := makeDef("alpha")
+		id1 := ComputeSubscriptionID(def, map[string]string{"alpha": "value1", "beta": "ignored"})
+		id2 := ComputeSubscriptionID(def, map[string]string{"alpha": "value1", "beta": "different"})
+		if id1 != id2 {
+			t.Errorf("non-SubscriptionKey param change leaked into ID: %q vs %q", id1, id2)
+		}
+	})
+
+	t.Run("different SubscriptionKey value produces different ID", func(t *testing.T) {
+		def := makeDef("alpha")
+		id1 := ComputeSubscriptionID(def, map[string]string{"alpha": "v1"})
+		id2 := ComputeSubscriptionID(def, map[string]string{"alpha": "v2"})
+		if id1 == id2 {
+			t.Errorf("different values produced same ID: %q", id1)
+		}
+	})
+}
+
+func TestComputeSubscriptionID_Stability(t *testing.T) {
+	// Param order in the ParamDef list must not affect the result (sorted by name internally).
+	def1 := &event.KeyDefinition{
+		Key: "test.evt",
+		Params: []event.ParamDef{
+			{Name: "b", SubscriptionKey: true},
+			{Name: "a", SubscriptionKey: true},
+		},
+	}
+	def2 := &event.KeyDefinition{
+		Key: "test.evt",
+		Params: []event.ParamDef{
+			{Name: "a", SubscriptionKey: true},
+			{Name: "b", SubscriptionKey: true},
+		},
+	}
+	id1 := ComputeSubscriptionID(def1, map[string]string{"a": "1", "b": "2"})
+	id2 := ComputeSubscriptionID(def2, map[string]string{"a": "1", "b": "2"})
+	if id1 != id2 {
+		t.Errorf("order-sensitive: id1=%q id2=%q", id1, id2)
+	}
+}
+
+func TestComputeSubscriptionID_Format(t *testing.T) {
+	def := &event.KeyDefinition{
+		Key:    "mail.user_mailbox.event.message_received_v1",
+		Params: []event.ParamDef{{Name: "mailbox", SubscriptionKey: true}},
+	}
+	id := ComputeSubscriptionID(def, map[string]string{"mailbox": "liuxinyang@example.com"})
+	prefix := "mail.user_mailbox.event.message_received_v1:"
+	if !strings.HasPrefix(id, prefix) {
+		t.Fatalf("missing prefix: %q", id)
+	}
+	suffix := strings.TrimPrefix(id, prefix)
+	if len(suffix) != 16 {
+		t.Errorf("fingerprint length = %d, want 16", len(suffix))
+	}
+	for _, c := range suffix {
+		isValid := (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-' || c == '_'
+		if !isValid {
+			t.Errorf("non-base64URL char in fingerprint: %q", suffix)
+			break
+		}
+	}
+}
+
+func TestComputeSubscriptionID_UnicodeAndSpecialChars(t *testing.T) {
+	def := &event.KeyDefinition{
+		Key:    "test.evt",
+		Params: []event.ParamDef{{Name: "value", SubscriptionKey: true}},
+	}
+	for _, val := range []string{"中文", "emoji🚀", "with spaces", "with:colons", "with\"quotes"} {
+		id := ComputeSubscriptionID(def, map[string]string{"value": val})
+		if !strings.HasPrefix(id, "test.evt:") || len(id) != len("test.evt:")+16 {
+			t.Errorf("ID malformed for value=%q: %q (len=%d)", val, id, len(id))
+		}
+	}
+}
+
+func TestComputeSubscriptionID_EmptyValue(t *testing.T) {
+	def := &event.KeyDefinition{
+		Key:    "test.evt",
+		Params: []event.ParamDef{{Name: "x", SubscriptionKey: true}},
+	}
+	id1 := ComputeSubscriptionID(def, map[string]string{"x": ""})
+	id2 := ComputeSubscriptionID(def, map[string]string{}) // missing entirely
+	if id1 != id2 {
+		t.Errorf("empty value should be indistinguishable from missing: %q vs %q", id1, id2)
+	}
+	id3 := ComputeSubscriptionID(def, map[string]string{"x": "nonempty"})
+	if id1 == id3 {
+		t.Errorf("empty and nonempty produced same ID: %q", id1)
+	}
+}

internal/event/consume/handshake.go

@@ -18,8 +18,8 @@ const helloAckTimeout = 5 * time.Second // symmetric with bus-side hello read de
 
 // doHello returns a bufio.Reader holding any bytes already pulled off conn so events
 // buffered with the ack in one TCP segment aren't dropped.
-func doHello(conn net.Conn, eventKey string, eventTypes []string) (*protocol.HelloAck, *bufio.Reader, error) {
-	hello := protocol.NewHello(os.Getpid(), eventKey, eventTypes, "v1")
+func doHello(conn net.Conn, eventKey string, eventTypes []string, subscriptionID string) (*protocol.HelloAck, *bufio.Reader, error) {
+	hello := protocol.NewHello(os.Getpid(), eventKey, eventTypes, "v1", subscriptionID)
 	if err := protocol.EncodeWithDeadline(conn, hello, protocol.WriteTimeout); err != nil {
 		return nil, nil, err
 	}

internal/event/consume/handshake_test.go

@@ -27,7 +27,7 @@ func TestDoHello_ReadDeadline(t *testing.T) {
 	start := time.Now()
 	done := make(chan error, 1)
 	go func() {
-		_, _, err := doHello(client, "im.msg", []string{"im.msg"})
+		_, _, err := doHello(client, "im.msg", []string{"im.msg"}, "")
 		done <- err
 	}()
 

internal/event/consume/loop.go

@@ -22,7 +22,7 @@ import (
 )
 
 // consumeLoop reads events and dispatches to workers; cancels on terminal sink errors.
-func consumeLoop(ctx context.Context, conn net.Conn, br *bufio.Reader, keyDef *event.KeyDefinition, opts Options, lastForKey *bool, emitted *atomic.Int64) error {
+func consumeLoop(ctx context.Context, conn net.Conn, br *bufio.Reader, keyDef *event.KeyDefinition, opts Options, subscriptionID string, lastForKey *bool, emitted *atomic.Int64) error {
 	ctx, cancel := context.WithCancel(ctx)
 	defer cancel()
 
@@ -185,7 +185,7 @@ func consumeLoop(ctx context.Context, conn net.Conn, br *bufio.Reader, keyDef *e
 		close(stopReader)
 		<-readerDone
 		conn.SetReadDeadline(time.Time{})
-		*lastForKey = checkLastForKey(conn, opts.EventKey)
+		*lastForKey = checkLastForKey(conn, opts.EventKey, subscriptionID)
 		conn.Close()
 	case <-allDone:
 		// bus-side close; can't query, assume last
@@ -199,13 +199,19 @@ func consumeLoop(ctx context.Context, conn net.Conn, br *bufio.Reader, keyDef *e
 
 // processAndOutput returns (wrote, err); err non-nil only for sink.Write failures.
 func processAndOutput(ctx context.Context, keyDef *event.KeyDefinition, evt *protocol.Event, opts Options, sink Sink, jqCode *gojq.Code) (bool, error) {
+	raw := &event.RawEvent{
+		EventType: evt.EventType,
+		Payload:   evt.Payload,
+	}
+
+	// Synchronous Match filter runs before any work (Process / sink write).
+	if keyDef.Match != nil && !keyDef.Match(raw, opts.Params) {
+		return false, nil
+	}
+
 	var result json.RawMessage
 
 	if keyDef.Process != nil {
-		raw := &event.RawEvent{
-			EventType: evt.EventType,
-			Payload:   evt.Payload,
-		}
 		var err error
 		result, err = keyDef.Process(ctx, opts.Runtime, raw, opts.Params)
 		if err != nil {

internal/event/consume/loop_test.go

@@ -89,7 +89,7 @@ func TestConsumeLoop_DeliversEventsAndExitsOnMaxEvents(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 
-	err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, &lastForKey, &emitted)
+	err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, "", &lastForKey, &emitted)
 	if err != nil {
 		t.Fatalf("consumeLoop: %v", err)
 	}
@@ -132,7 +132,7 @@ func TestConsumeLoop_SeqGapEmitsWarning(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 
-	if err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, &lastForKey, &emitted); err != nil {
+	if err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, "", &lastForKey, &emitted); err != nil {
 		t.Fatalf("consumeLoop: %v", err)
 	}
 	if got := emitted.Load(); got != 2 {
@@ -169,7 +169,7 @@ func TestConsumeLoop_JQFilterAppliedPerEvent(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 
-	if err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, &lastForKey, &emitted); err != nil {
+	if err := consumeLoop(ctx, client, bufio.NewReader(client), echoKeyDef("test.key"), opts, "", &lastForKey, &emitted); err != nil {
 		t.Fatalf("consumeLoop: %v", err)
 	}
 	if got := emitted.Load(); got != 1 {
@@ -196,12 +196,96 @@ func TestConsumeLoop_CompileJQFailsEarly(t *testing.T) {
 
 	var lastForKey bool
 	var emitted atomic.Int64
-	err := consumeLoop(context.Background(), client, bufio.NewReader(client), echoKeyDef("test.key"), opts, &lastForKey, &emitted)
+	err := consumeLoop(context.Background(), client, bufio.NewReader(client), echoKeyDef("test.key"), opts, "", &lastForKey, &emitted)
 	if err == nil {
 		t.Fatal("consumeLoop should fail immediately on bad jq expression")
 	}
 }
 
+// captureSink is a minimal Sink for unit-testing processAndOutput directly.
+type captureSink struct {
+	written []json.RawMessage
+}
+
+func (s *captureSink) Write(data json.RawMessage) error {
+	s.written = append(s.written, data)
+	return nil
+}
+
+func TestProcessAndOutput_Match_DropsEvent(t *testing.T) {
+	calledProcess := false
+	keyDef := &event.KeyDefinition{
+		Key: "test.evt",
+		Match: func(raw *event.RawEvent, params map[string]string) bool {
+			return false
+		},
+		Process: func(ctx context.Context, rt event.APIClient, raw *event.RawEvent, params map[string]string) (json.RawMessage, error) {
+			calledProcess = true
+			return json.RawMessage(`{}`), nil
+		},
+	}
+	sink := &captureSink{}
+	wrote, err := processAndOutput(context.Background(), keyDef,
+		&protocol.Event{Type: protocol.MsgTypeEvent, EventType: "test.evt", Payload: json.RawMessage(`{"x":1}`)},
+		Options{}, sink, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if wrote {
+		t.Error("Match returned false but event was written")
+	}
+	if calledProcess {
+		t.Error("Process was called even though Match returned false")
+	}
+	if len(sink.written) != 0 {
+		t.Errorf("sink received %d events, want 0", len(sink.written))
+	}
+}
+
+func TestProcessAndOutput_Match_NilAcceptsAll(t *testing.T) {
+	keyDef := &event.KeyDefinition{Key: "test.evt"} // no Match, no Process
+	sink := &captureSink{}
+	wrote, err := processAndOutput(context.Background(), keyDef,
+		&protocol.Event{Type: protocol.MsgTypeEvent, EventType: "test.evt", Payload: json.RawMessage(`{"x":1}`)},
+		Options{}, sink, nil)
+	if err != nil || !wrote {
+		t.Errorf("expected wrote=true err=nil; got wrote=%v err=%v", wrote, err)
+	}
+	if len(sink.written) != 1 {
+		t.Errorf("sink received %d events, want 1", len(sink.written))
+	}
+}
+
+func TestProcessAndOutput_Match_RunsBeforeProcess(t *testing.T) {
+	// Record the actual call sequence — a bare call-count check would still
+	// pass if Process ran before Match.
+	var order []string
+	keyDef := &event.KeyDefinition{
+		Key: "test.evt",
+		Match: func(raw *event.RawEvent, params map[string]string) bool {
+			order = append(order, "match")
+			return true
+		},
+		Process: func(ctx context.Context, rt event.APIClient, raw *event.RawEvent, params map[string]string) (json.RawMessage, error) {
+			order = append(order, "process")
+			return raw.Payload, nil
+		},
+	}
+	sink := &captureSink{}
+	wrote, err := processAndOutput(context.Background(), keyDef,
+		&protocol.Event{Type: protocol.MsgTypeEvent, EventType: "test.evt", Payload: json.RawMessage(`{}`)},
+		Options{}, sink, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !wrote {
+		t.Error("expected wrote=true")
+	}
+	if len(order) != 2 || order[0] != "match" || order[1] != "process" {
+		t.Errorf("call order = %v, want [match process]", order)
+	}
+}
+
 func TestIsTerminalSinkError(t *testing.T) {
 	for _, tc := range []struct {
 		name string

internal/event/consume/shutdown.go

@@ -16,8 +16,8 @@ const preShutdownAckTimeout = 2 * time.Second
 
 // checkLastForKey atomically reserves a cleanup lock; on any error defaults to true
 // (cleanup-on-error is safer than leaking server state). Discards non-ack frames in flight.
-func checkLastForKey(conn net.Conn, eventKey string) bool {
-	msg := protocol.NewPreShutdownCheck(eventKey)
+func checkLastForKey(conn net.Conn, eventKey string, subscriptionID string) bool {
+	msg := protocol.NewPreShutdownCheck(eventKey, subscriptionID)
 	if err := protocol.EncodeWithDeadline(conn, msg, protocol.WriteTimeout); err != nil {
 		return true
 	}

internal/event/consume/shutdown_test.go

@@ -4,6 +4,8 @@
 package consume
 
 import (
+	"bufio"
+	"bytes"
 	"encoding/json"
 	"io"
 	"net"
@@ -38,7 +40,7 @@ func TestCheckLastForKey_IgnoresNonAckFrames(t *testing.T) {
 		}
 	}()
 
-	got := checkLastForKey(client, "im.msg")
+	got := checkLastForKey(client, "im.msg", "")
 	if got != false {
 		t.Errorf("checkLastForKey = %v, want false", got)
 	}
@@ -62,7 +64,7 @@ func TestCheckLastForKey_ReturnsAckValue(t *testing.T) {
 		_ = protocol.Encode(server, ack)
 	}()
 
-	got := checkLastForKey(client, "im.msg")
+	got := checkLastForKey(client, "im.msg", "")
 	if got != true {
 		t.Errorf("checkLastForKey = %v, want true", got)
 	}
@@ -83,7 +85,7 @@ func TestCheckLastForKey_DefaultsToTrueOnTimeout(t *testing.T) {
 	}()
 
 	start := time.Now()
-	got := checkLastForKey(client, "im.msg")
+	got := checkLastForKey(client, "im.msg", "")
 	elapsed := time.Since(start)
 
 	if got != true {
@@ -93,3 +95,39 @@ func TestCheckLastForKey_DefaultsToTrueOnTimeout(t *testing.T) {
 		t.Errorf("elapsed = %v, expected ~%v (timeout-bounded)", elapsed, preShutdownAckTimeout)
 	}
 }
+
+func TestCheckLastForKey_SendsSubscriptionID(t *testing.T) {
+	a, b := net.Pipe()
+	defer a.Close()
+	defer b.Close()
+
+	done := make(chan string, 1)
+	go func() {
+		br := bufio.NewReader(b)
+		line, err := protocol.ReadFrame(br)
+		if err != nil {
+			done <- "READ_ERR"
+			return
+		}
+		msg, err := protocol.Decode(bytes.TrimRight(line, "\n"))
+		if err != nil {
+			done <- "DECODE_ERR"
+			return
+		}
+		check, ok := msg.(*protocol.PreShutdownCheck)
+		if !ok {
+			done <- "WRONG_TYPE"
+			return
+		}
+		done <- check.SubscriptionID
+		// Reply with ack so client returns
+		ack := protocol.NewPreShutdownAck(true)
+		_ = protocol.EncodeWithDeadline(b, ack, protocol.WriteTimeout)
+	}()
+
+	_ = checkLastForKey(a, "mail.x", "mail.x:alice")
+	got := <-done
+	if got != "mail.x:alice" {
+		t.Errorf("PreShutdownCheck.SubscriptionID on wire = %q, want %q", got, "mail.x:alice")
+	}
+}

internal/event/protocol/codec_test.go

@@ -77,3 +77,88 @@ func TestDecodeUnknownType(t *testing.T) {
 		t.Error("expected error for unknown type")
 	}
 }
+
+func TestEncodeDecodeHello_WithSubscriptionID(t *testing.T) {
+	msg := &Hello{
+		Type:           MsgTypeHello,
+		PID:            12345,
+		EventKey:       "mail.user_mailbox.event.message_received_v1",
+		EventTypes:     []string{"mail.user_mailbox.event.message_received_v1"},
+		Version:        "v1",
+		SubscriptionID: "mail.user_mailbox.event.message_received_v1:a7Bx9Kp2Lm3Qv4Rs",
+	}
+	buf := &bytes.Buffer{}
+	if err := Encode(buf, msg); err != nil {
+		t.Fatal(err)
+	}
+	line := buf.Bytes()
+	if !bytes.Contains(line, []byte(`"subscription_id":"mail.user_mailbox.event.message_received_v1:a7Bx9Kp2Lm3Qv4Rs"`)) {
+		t.Errorf("subscription_id not serialized: %s", string(line))
+	}
+	decoded, err := Decode(bytes.TrimRight(line, "\n"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	hello, ok := decoded.(*Hello)
+	if !ok {
+		t.Fatalf("expected *Hello, got %T", decoded)
+	}
+	if hello.SubscriptionID != msg.SubscriptionID {
+		t.Errorf("roundtrip subscription_id: got %q want %q", hello.SubscriptionID, msg.SubscriptionID)
+	}
+}
+
+func TestEncodeDecodeHello_EmptySubscriptionIDOmitted(t *testing.T) {
+	msg := &Hello{
+		Type:       MsgTypeHello,
+		PID:        1,
+		EventKey:   "k",
+		EventTypes: []string{"k"},
+		Version:    "v1",
+	}
+	buf := &bytes.Buffer{}
+	if err := Encode(buf, msg); err != nil {
+		t.Fatal(err)
+	}
+	if bytes.Contains(buf.Bytes(), []byte("subscription_id")) {
+		t.Errorf("empty subscription_id should be omitted: %s", buf.String())
+	}
+	decoded, _ := Decode(bytes.TrimRight(buf.Bytes(), "\n"))
+	hello := decoded.(*Hello)
+	if hello.SubscriptionID != "" {
+		t.Errorf("got %q, want empty", hello.SubscriptionID)
+	}
+}
+
+func TestEncodeDecodePreShutdownCheck_WithSubscriptionID(t *testing.T) {
+	msg := &PreShutdownCheck{
+		Type:           MsgTypePreShutdownCheck,
+		EventKey:       "mail.x",
+		SubscriptionID: "mail.x:abc",
+	}
+	buf := &bytes.Buffer{}
+	if err := Encode(buf, msg); err != nil {
+		t.Fatal(err)
+	}
+	decoded, err := Decode(bytes.TrimRight(buf.Bytes(), "\n"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := decoded.(*PreShutdownCheck)
+	if got.SubscriptionID != msg.SubscriptionID {
+		t.Errorf("roundtrip: got %q want %q", got.SubscriptionID, msg.SubscriptionID)
+	}
+}
+
+func TestStatusResponse_ConsumerInfo_SubscriptionID(t *testing.T) {
+	msg := NewStatusResponse(7, 120, 1, []ConsumerInfo{
+		{PID: 99, EventKey: "mail.x", SubscriptionID: "mail.x:abc", Received: 5, Dropped: 0},
+	})
+	buf := &bytes.Buffer{}
+	if err := Encode(buf, msg); err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Contains(buf.Bytes(), []byte(`"subscription_id":"mail.x:abc"`)) {
+		t.Errorf("ConsumerInfo.SubscriptionID missing from JSON: %s", buf.String())
+	}
+}

internal/event/protocol/messages.go

@@ -34,11 +34,12 @@ type SourceStatus struct {
 }
 
 type Hello struct {
-	Type       string   `json:"type"`
-	PID        int      `json:"pid"`
-	EventKey   string   `json:"event_key"`
-	EventTypes []string `json:"event_types"`
-	Version    string   `json:"version"`
+	Type           string   `json:"type"`
+	PID            int      `json:"pid"`
+	EventKey       string   `json:"event_key"`
+	EventTypes     []string `json:"event_types"`
+	Version        string   `json:"version"`
+	SubscriptionID string   `json:"subscription_id,omitempty"` // empty = fallback to EventKey on bus side
 }
 
 type HelloAck struct {
@@ -61,10 +62,11 @@ type Bye struct {
 	Type string `json:"type"`
 }
 
-// PreShutdownCheck atomically reserves the cleanup lock for EventKey.
+// PreShutdownCheck atomically reserves the cleanup lock for (EventKey, SubscriptionID).
 type PreShutdownCheck struct {
-	Type     string `json:"type"`
-	EventKey string `json:"event_key"`
+	Type           string `json:"type"`
+	EventKey       string `json:"event_key"`
+	SubscriptionID string `json:"subscription_id,omitempty"` // empty = fallback to EventKey
 }
 
 type PreShutdownAck struct {
@@ -77,10 +79,11 @@ type StatusQuery struct {
 }
 
 type ConsumerInfo struct {
-	PID      int    `json:"pid"`
-	EventKey string `json:"event_key"`
-	Received int64  `json:"received"`
-	Dropped  int64  `json:"dropped"`
+	PID            int    `json:"pid"`
+	EventKey       string `json:"event_key"`
+	SubscriptionID string `json:"subscription_id,omitempty"`
+	Received       int64  `json:"received"`
+	Dropped        int64  `json:"dropped"`
 }
 
 type StatusResponse struct {
@@ -95,13 +98,14 @@ type Shutdown struct {
 	Type string `json:"type"`
 }
 
-func NewHello(pid int, eventKey string, eventTypes []string, version string) *Hello {
+func NewHello(pid int, eventKey string, eventTypes []string, version string, subscriptionID string) *Hello {
 	return &Hello{
-		Type:       MsgTypeHello,
-		PID:        pid,
-		EventKey:   eventKey,
-		EventTypes: eventTypes,
-		Version:    version,
+		Type:           MsgTypeHello,
+		PID:            pid,
+		EventKey:       eventKey,
+		EventTypes:     eventTypes,
+		Version:        version,
+		SubscriptionID: subscriptionID,
 	}
 }
 
@@ -124,8 +128,8 @@ func NewEvent(eventType, eventID, sourceTime string, seq uint64, payload json.Ra
 	}
 }
 
-func NewPreShutdownCheck(eventKey string) *PreShutdownCheck {
-	return &PreShutdownCheck{Type: MsgTypePreShutdownCheck, EventKey: eventKey}
+func NewPreShutdownCheck(eventKey, subscriptionID string) *PreShutdownCheck {
+	return &PreShutdownCheck{Type: MsgTypePreShutdownCheck, EventKey: eventKey, SubscriptionID: subscriptionID}
 }
 
 func NewPreShutdownAck(lastForKey bool) *PreShutdownAck {

internal/event/protocol/messages_test.go

@@ -17,7 +17,7 @@ import (
 
 // Every NewXxx helper must set the Type discriminator (Decode rejects messages without it).
 func TestConstructors_PinTypeField(t *testing.T) {
-	if got := NewHello(1, "k", []string{"t"}, "v1"); got.Type != MsgTypeHello {
+	if got := NewHello(1, "k", []string{"t"}, "v1", ""); got.Type != MsgTypeHello {
 		t.Errorf("NewHello.Type = %q, want %q", got.Type, MsgTypeHello)
 	}
 	if got := NewHelloAck("v1", true); got.Type != MsgTypeHelloAck || !got.FirstForKey {
@@ -26,7 +26,7 @@ func TestConstructors_PinTypeField(t *testing.T) {
 	if got := NewEvent("im.msg", "e1", "", 7, json.RawMessage(`{}`)); got.Type != MsgTypeEvent || got.Seq != 7 {
 		t.Errorf("NewEvent mismatch: %+v", got)
 	}
-	if got := NewPreShutdownCheck("k"); got.Type != MsgTypePreShutdownCheck || got.EventKey != "k" {
+	if got := NewPreShutdownCheck("k", ""); got.Type != MsgTypePreShutdownCheck || got.EventKey != "k" {
 		t.Errorf("NewPreShutdownCheck mismatch: %+v", got)
 	}
 	if got := NewPreShutdownAck(true); got.Type != MsgTypePreShutdownAck || !got.LastForKey {
@@ -63,7 +63,7 @@ func TestEncode_DecodeRoundtripAllTypes(t *testing.T) {
 		}
 	}
 	roundtrip(t, NewHelloAck("v1", true), &HelloAck{})
-	roundtrip(t, NewPreShutdownCheck("im.msg"), &PreShutdownCheck{})
+	roundtrip(t, NewPreShutdownCheck("im.msg", ""), &PreShutdownCheck{})
 	roundtrip(t, NewPreShutdownAck(false), &PreShutdownAck{})
 	roundtrip(t, NewStatusQuery(), &StatusQuery{})
 	roundtrip(t, NewStatusResponse(7, 120, 1, []ConsumerInfo{{PID: 99, EventKey: "k"}}), &StatusResponse{})

internal/event/types.go

@@ -55,6 +55,23 @@ type ParamDef struct {
 	Default     string       `json:"default,omitempty"`
 	Description string       `json:"description"`
 	Values      []ParamValue `json:"values,omitempty"`
+
+	// SubscriptionKey marks this param as part of the subscription identity.
+	// Two consumers of the same EventKey but different values for any
+	// SubscriptionKey-marked param are treated as DISTINCT subscriptions:
+	// PreConsume runs once per (EventKey, SubscriptionID), cleanup runs once per
+	// (EventKey, SubscriptionID).
+	//
+	// CONTRACT: only mark a param SubscriptionKey if the EventKey's server-side
+	// subscribe/unsubscribe API is itself scoped to that resource. Lark keys the
+	// subscription record by (app, user, event_type) and overwrites it rather
+	// than reference-counting, so for a non-per-resource API the cleanup of one
+	// resource's last consumer unsubscribes the shared record and silently cuts
+	// off every other resource sharing that event_type.
+	//
+	// Default false = the param is a filter / formatting / metadata param
+	// and does not affect subscription identity.
+	SubscriptionKey bool `json:"subscription_key,omitempty"`
 }
 
 type ProcessFunc = func(ctx context.Context, rt APIClient, raw *RawEvent, params map[string]string) (json.RawMessage, error)
@@ -83,10 +100,44 @@ type KeyDefinition struct {
 
 	Schema SchemaDef `json:"schema"`
 
+	// NormalizeParams canonicalizes param values BEFORE fingerprint compute,
+	// PreConsume, Match, and Process. Mutates the params map in place.
+	// May call OAPI; runs once per consumer at startup.
+	//
+	// Use cases: resolve aliases ("me" -> real email, a name -> an ID),
+	// trim whitespace. On error, consume fails (no retry); caller gets the
+	// wrapped error.
+	//
+	// Default nil = no normalization, params pass through unchanged.
+	NormalizeParams func(ctx context.Context, rt APIClient, params map[string]string) error `json:"-"`
+
 	// Process required when Schema.Custom is Processed output; must be nil when Native is used.
+	//
+	// Convention: returning (nil, nil) signals "drop this event" — the
+	// consumer loop will skip writing it to sink and not advance the
+	// emitted counter. Useful for async filtering (e.g. fetch metadata,
+	// drop if folder doesn't match). For sync filters that don't need
+	// OAPI, use Match instead.
 	Process func(ctx context.Context, rt APIClient, raw *RawEvent, params map[string]string) (json.RawMessage, error) `json:"-"`
 
-	PreConsume func(ctx context.Context, rt APIClient, params map[string]string) (cleanup func(), err error) `json:"-"`
+	// Match is a synchronous payload filter run on every received event
+	// BEFORE Process. Return false to drop the event without further work.
+	//
+	// Signature deliberately omits ctx/rt to physically enforce "no OAPI
+	// calls in Match". For filters that need a metadata fetch first, use
+	// Process and return nil to drop.
+	//
+	// Default nil = accept all events.
+	Match func(raw *RawEvent, params map[string]string) bool `json:"-"`
+
+	// PreConsume runs once per (EventKey, SubscriptionID) when this consumer
+	// is first for that scope. Returns a cleanup function that the framework
+	// invokes when this consumer is the last for its scope.
+	//
+	// The cleanup's error return is honored: on nil the framework prints
+	// "[event] cleanup done."; on non-nil it prints a WARN with an
+	// idempotency note.
+	PreConsume func(ctx context.Context, rt APIClient, params map[string]string) (cleanup func() error, err error) `json:"-"`
 
 	Scopes []string `json:"scopes,omitempty"`
 

internal/output/lark_errors.go

@@ -35,9 +35,12 @@ const (
 	LarkErrAppNotInUse     = 99991662 // app is disabled in this tenant
 	LarkErrAppUnauthorized = 99991673 // app status unavailable; check installation
 
-	// TAT-endpoint variant of the "wrong app credentials" condition.
-	// /open-apis/auth/v3/tenant_access_token/internal returns code 10014
-	// ("app secret invalid") instead of 99991543 when the secret is wrong.
+	// "Wrong app credentials" code from the LEGACY TAT endpoint
+	// (/open-apis/auth/v3/tenant_access_token/internal returns 10014, "app secret
+	// invalid", instead of 99991543). Since the OAuth v3 migration the CLI mints
+	// TAT via accounts/oauth/v3/token and reports this as the OAuth invalid_client
+	// error, so it no longer emits 10014 itself; the constant + codemeta mapping
+	// are retained as a defensive fallback should 10014 still arrive.
 	LarkErrTATInvalidSecret = 10014
 
 	// Rate limit.

internal/registry/service_descriptions.json

@@ -47,6 +47,10 @@
     "en": { "title": "Minutes", "description": "Minutes content and metadata retrieval" },
     "zh": { "title": "妙记", "description": "妙记信息获取、内容查询" }
   },
+  "note": {
+    "en": { "title": "Note", "description": "Meeting note detail and unified transcript retrieval" },
+    "zh": { "title": "会议纪要", "description": "会议纪要详情与 unified 逐字稿查询" }
+  },
   "sheets": {
     "en": { "title": "Sheets", "description": "Spreadsheet operations" },
     "zh": { "title": "电子表格", "description": "电子表格操作" }

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -18,17 +18,25 @@ var migratedCommonHelperPaths = []string{
 	"cmd/event/",
 	"events/",
 	"internal/event/consume/",
+	"shortcuts/apps/",
 	"shortcuts/base/",
 	"shortcuts/calendar/",
 	"shortcuts/contact/",
+	"shortcuts/doc/",
 	"shortcuts/drive/",
 	"shortcuts/event/",
+	"shortcuts/im/",
 	"shortcuts/mail/",
+	"shortcuts/markdown/",
 	"shortcuts/minutes/",
+	"shortcuts/note/",
 	"shortcuts/okr/",
+	"shortcuts/sheets/",
+	"shortcuts/slides/",
 	"shortcuts/task/",
 	"shortcuts/vc/",
 	"shortcuts/whiteboard/",
+	"shortcuts/wiki/",
 }
 
 const commonImportPath = "github.com/larksuite/cli/shortcuts/common"

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -19,18 +19,25 @@ var migratedEnvelopePaths = []string{
 	"cmd/event/",
 	"events/",
 	"internal/event/consume/",
+	"shortcuts/apps/",
 	"shortcuts/base/",
 	"shortcuts/calendar/",
 	"shortcuts/contact/",
+	"shortcuts/doc/",
 	"shortcuts/drive/",
 	"shortcuts/event/",
+	"shortcuts/im/",
 	"shortcuts/mail/",
+	"shortcuts/markdown/",
 	"shortcuts/minutes/",
+	"shortcuts/note/",
 	"shortcuts/okr/",
+	"shortcuts/sheets/",
+	"shortcuts/slides/",
 	"shortcuts/task/",
 	"shortcuts/vc/",
 	"shortcuts/whiteboard/",
-	"shortcuts/im/",
+	"shortcuts/wiki/",
 }
 
 // legacyOutputImportPath is the import path of the package that declares the

lint/errscontract/rules_test.go

@@ -620,6 +620,7 @@ func boom() error {
 
 func TestCheckNoLegacyEnvelopeLiteral_RejectsExitErrorLiteralOnMigratedShortcutPaths(t *testing.T) {
 	for _, path := range []string{
+		"shortcuts/markdown/markdown_fetch.go",
 		"shortcuts/okr/okr_image_upload.go",
 		"shortcuts/task/task_update.go",
 		"shortcuts/whiteboard/whiteboard_update.go",
@@ -950,11 +951,17 @@ func TestCheckNoLegacyCommonHelperCall_RejectsLegacyHelpersOnMigratedPath(t *tes
 		"HandleApiResult",
 	}
 	paths := []string{
+		"shortcuts/doc/docs_fetch_v2.go",
 		"shortcuts/drive/drive_search.go",
+		"shortcuts/im/im_messages_send.go",
 		"shortcuts/mail/mail_send.go",
+		"shortcuts/markdown/markdown_fetch.go",
 		"shortcuts/okr/okr_progress_create.go",
+		"shortcuts/sheets/helpers.go",
+		"shortcuts/slides/slides_create.go",
 		"shortcuts/task/task_update.go",
 		"shortcuts/whiteboard/whiteboard_query.go",
+		"shortcuts/wiki/wiki_node_get.go",
 	}
 	for _, path := range paths {
 		for _, helper := range helpers {
@@ -982,6 +989,18 @@ common.` + helper + `()
 	}
 }
 
+func TestMigratedCommonHelperPaths_CoverMigratedEnvelopePaths(t *testing.T) {
+	commonPaths := make(map[string]struct{}, len(migratedCommonHelperPaths))
+	for _, path := range migratedCommonHelperPaths {
+		commonPaths[path] = struct{}{}
+	}
+	for _, path := range migratedEnvelopePaths {
+		if _, ok := commonPaths[path]; !ok {
+			t.Fatalf("migratedEnvelopePaths contains %q but migratedCommonHelperPaths does not", path)
+		}
+	}
+}
+
 func TestCheckNoLegacyCommonHelperCall_RejectsDangerousCharsOnCalendarPath(t *testing.T) {
 	src := `package calendar
 
@@ -1003,6 +1022,91 @@ func boom() {
 	}
 }
 
+func TestCheckNoLegacyCommonHelperCall_CoversDocPathWithAliasAndFunctionValue(t *testing.T) {
+	src := `package migrated
+
+import c "github.com/larksuite/cli/shortcuts/common"
+
+func boom() {
+	f := c.FlagErrorf
+	_ = f
+	c.WrapInputStatError(nil)
+}
+`
+	v := CheckNoLegacyCommonHelperCall("shortcuts/doc/docs_fetch_v2.go", src)
+	if len(v) != 2 {
+		t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on doc path, got %d: %+v", len(v), v)
+	}
+}
+
+func TestCheckNoLegacyCommonHelperCall_CoversSheetsPathWithAliasAndFunctionValue(t *testing.T) {
+	src := `package migrated
+
+import c "github.com/larksuite/cli/shortcuts/common"
+
+func boom() {
+	f := c.FlagErrorf
+	_ = f
+	c.WrapInputStatError(nil)
+}
+`
+	v := CheckNoLegacyCommonHelperCall("shortcuts/sheets/helpers.go", src)
+	if len(v) != 2 {
+		t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on sheets path, got %d: %+v", len(v), v)
+	}
+}
+
+func TestCheckNoLegacyCommonHelperCall_CoversSlidesPathWithAliasAndFunctionValue(t *testing.T) {
+	src := `package migrated
+
+import c "github.com/larksuite/cli/shortcuts/common"
+
+func boom() {
+	f := c.FlagErrorf
+	_ = f
+	c.WrapInputStatError(nil)
+}
+`
+	v := CheckNoLegacyCommonHelperCall("shortcuts/slides/slides_create.go", src)
+	if len(v) != 2 {
+		t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on slides path, got %d: %+v", len(v), v)
+	}
+}
+
+func TestCheckNoLegacyCommonHelperCall_CoversMarkdownPathWithAliasAndFunctionValue(t *testing.T) {
+	src := `package migrated
+
+import c "github.com/larksuite/cli/shortcuts/common"
+
+func boom() {
+	f := c.FlagErrorf
+	_ = f
+	c.WrapInputStatError(nil)
+}
+`
+	v := CheckNoLegacyCommonHelperCall("shortcuts/markdown/markdown_fetch.go", src)
+	if len(v) != 2 {
+		t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on markdown path, got %d: %+v", len(v), v)
+	}
+}
+
+func TestCheckNoLegacyCommonHelperCall_CoversWikiPathWithAliasAndFunctionValue(t *testing.T) {
+	src := `package migrated
+
+import c "github.com/larksuite/cli/shortcuts/common"
+
+func boom() {
+	f := c.FlagErrorf
+	_ = f
+	c.WrapInputStatError(nil)
+}
+`
+	v := CheckNoLegacyCommonHelperCall("shortcuts/wiki/wiki_node_get.go", src)
+	if len(v) != 2 {
+		t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on wiki path, got %d: %+v", len(v), v)
+	}
+}
+
 func TestCheckNoLegacyCommonHelperCall_AllowsNonMigratedPath(t *testing.T) {
 	src := `package contact
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.49",
+  "version": "1.0.53",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"
@@ -15,7 +15,8 @@
   ],
   "cpu": [
     "x64",
-    "arm64"
+    "arm64",
+    "riscv64"
   ],
   "engines": {
     "node": ">=16"

scripts/build-pkg-pr-new.sh

@@ -33,6 +33,7 @@ build_target darwin arm64
 build_target linux amd64
 build_target darwin amd64
 build_target linux arm64
+build_target linux riscv64
 build_target windows amd64
 build_target windows arm64
 
@@ -55,6 +56,7 @@ const platformMap = {
 const archMap = {
   x64: "amd64",
   arm64: "arm64",
+  riscv64: "riscv64",
 };
 
 const platform = platformMap[process.platform];

scripts/install.js

@@ -30,6 +30,7 @@ const PLATFORM_MAP = {
 const ARCH_MAP = {
   x64: "amd64",
   arm64: "arm64",
+  riscv64: "riscv64",
 };
 
 const platform = PLATFORM_MAP[process.platform];

shortcuts/apps/apps_access_scope_get.go

@@ -9,7 +9,6 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -21,15 +20,18 @@ var AppsAccessScopeGet = common.Shortcut{
 	Command:     "+access-scope-get",
 	Description: "Get Miaoda app access scope configuration",
 	Risk:        "read",
-	Scopes:      []string{"spark:app:read"},
-	AuthTypes:   []string{"user"},
-	HasFormat:   true,
+	Tips: []string{
+		"Example: lark-cli apps +access-scope-get --app-id <app_id>",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
 	Flags: []common.Flag{
 		{Name: "app-id", Desc: "app ID", Required: true},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return output.ErrValidation("--app-id is required")
+			return appsValidationParamError("--app-id", "--app-id is required")
 		}
 		return nil
 	},
@@ -42,9 +44,9 @@ var AppsAccessScopeGet = common.Shortcut{
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		path := fmt.Sprintf("%s/apps/%s/access-scope", apiBasePath, validate.EncodePathSegment(appID))
-		data, err := rctx.CallAPI("GET", path, nil, nil)
+		data, err := rctx.CallAPITyped("GET", path, nil, nil)
 		if err != nil {
-			return err
+			return withAppsHint(err, "verify --app-id is correct and you have access to the app; list your apps with `lark-cli apps +list`")
 		}
 		// 原样透传 — 保留服务端字符串枚举 (All/Tenant/Range)，不合并 users/departments/chats。
 		rctx.OutFormat(data, nil, func(w io.Writer) {

shortcuts/apps/apps_access_scope_set.go

@@ -10,7 +10,6 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -27,9 +26,14 @@ var AppsAccessScopeSet = common.Shortcut{
 	Command:     "+access-scope-set",
 	Description: "Set Miaoda app access scope (specific / public / tenant)",
 	Risk:        "write",
-	Scopes:      []string{"spark:app:write"},
-	AuthTypes:   []string{"user"},
-	HasFormat:   true,
+	Tips: []string{
+		`Example: lark-cli apps +access-scope-set --app-id <app_id> --scope tenant`,
+		`Example: lark-cli apps +access-scope-set --app-id <app_id> --scope public --require-login`,
+		`Example: lark-cli apps +access-scope-set --app-id <app_id> --scope specific --targets '[{"type":"user","id":"<open_id>"}]'`,
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
 	Flags: []common.Flag{
 		{Name: "app-id", Desc: "app ID", Required: true},
 		{Name: "scope", Desc: "scope: specific | public | tenant", Required: true, Enum: []string{"specific", "public", "tenant"}},
@@ -40,7 +44,7 @@ var AppsAccessScopeSet = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return output.ErrValidation("--app-id is required")
+			return appsValidationParamError("--app-id", "--app-id is required")
 		}
 		return validateAccessScopeFlags(rctx)
 	},
@@ -64,9 +68,9 @@ var AppsAccessScopeSet = common.Shortcut{
 		}
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		path := fmt.Sprintf("%s/apps/%s/access-scope", apiBasePath, validate.EncodePathSegment(appID))
-		data, err := rctx.CallAPI("PUT", path, nil, body)
+		data, err := rctx.CallAPITyped("PUT", path, nil, body)
 		if err != nil {
-			return err
+			return withAppsHint(err, "verify --app-id is correct; for scope=specific, each --targets id must be a valid open_id/department_id/chat_id and --approver a valid open_id; review the current scope with `lark-cli apps +access-scope-get --app-id <app_id>`")
 		}
 		rctx.OutFormat(data, nil, func(w io.Writer) {
 			fmt.Fprintf(w, "access-scope set: %s\n", rctx.Str("scope"))
@@ -85,36 +89,42 @@ func validateAccessScopeFlags(rctx *common.RuntimeContext) error {
 	switch scope {
 	case "specific":
 		if targets == "" {
-			return output.ErrValidation("--targets is required when --scope=specific")
+			return appsValidationParamError("--targets", "--targets is required when --scope=specific")
 		}
 		if err := validateTargetsJSON(targets); err != nil {
 			return err
 		}
 		if approver != "" && !applyEnabled {
-			return output.ErrValidation("--approver requires --apply-enabled")
+			return appsValidationParamError("--approver", "--approver requires --apply-enabled")
 		}
 		if requireLogin {
-			return output.ErrValidation("--require-login is not allowed when --scope=specific")
+			return appsValidationParamError("--require-login", "--require-login is not allowed when --scope=specific")
 		}
 	case "public":
 		if targets != "" {
-			return output.ErrValidation("--targets is not allowed when --scope=public")
+			return appsValidationParamError("--targets", "--targets is not allowed when --scope=public")
 		}
 		if applyEnabled {
-			return output.ErrValidation("--apply-enabled is not allowed when --scope=public")
+			return appsValidationParamError("--apply-enabled", "--apply-enabled is not allowed when --scope=public")
 		}
 		if approver != "" {
-			return output.ErrValidation("--approver is not allowed when --scope=public")
+			return appsValidationParamError("--approver", "--approver is not allowed when --scope=public")
 		}
 		if !rctx.Cmd.Flags().Changed("require-login") {
-			return output.ErrValidation("--require-login is required when --scope=public (pass true or false explicitly; do not rely on the default)")
+			return appsValidationParamError("--require-login", "--require-login is required when --scope=public (pass true or false explicitly; do not rely on the default)")
 		}
 	case "tenant":
 		if targets != "" || applyEnabled || approver != "" || requireLogin {
-			return output.ErrValidation("no extra flags allowed when --scope=tenant")
+			return appsValidationError("no extra flags allowed when --scope=tenant").
+				WithParams(
+					appsInvalidParam("--targets", "not allowed when --scope=tenant"),
+					appsInvalidParam("--apply-enabled", "not allowed when --scope=tenant"),
+					appsInvalidParam("--approver", "not allowed when --scope=tenant"),
+					appsInvalidParam("--require-login", "not allowed when --scope=tenant"),
+				)
 		}
 	default:
-		return output.ErrValidation("--scope must be specific / public / tenant")
+		return appsValidationParamError("--scope", "--scope must be specific / public / tenant")
 	}
 	return nil
 }
@@ -122,18 +132,18 @@ func validateAccessScopeFlags(rctx *common.RuntimeContext) error {
 func validateTargetsJSON(targetsJSON string) error {
 	var items []map[string]interface{}
 	if err := json.Unmarshal([]byte(targetsJSON), &items); err != nil {
-		return output.ErrValidation("--targets is not valid JSON: %v", err)
+		return appsValidationParamError("--targets", "--targets is not valid JSON: %v", err).WithCause(err)
 	}
 	if len(items) == 0 {
-		return output.ErrValidation("--targets must contain at least one entry; specific scope requires concrete user/department/chat ids")
+		return appsValidationParamError("--targets", "--targets must contain at least one entry; specific scope requires concrete user/department/chat ids")
 	}
 	for i, t := range items {
 		typ, _ := t["type"].(string)
 		if !allowedAccessTargetTypes[typ] {
-			return output.ErrValidation("--targets[%d].type %q must be one of: user / department / chat", i, typ)
+			return appsValidationParamError("--targets", "--targets[%d].type %q must be one of: user / department / chat", i, typ)
 		}
 		if id, _ := t["id"].(string); strings.TrimSpace(id) == "" {
-			return output.ErrValidation("--targets[%d].id is empty", i)
+			return appsValidationParamError("--targets", "--targets[%d].id is empty", i)
 		}
 	}
 	return nil
@@ -152,7 +162,7 @@ func buildAccessScopeBody(rctx *common.RuntimeContext) (map[string]interface{},
 	scope := rctx.Str("scope")
 	enum, ok := scopeStringToServerEnum[scope]
 	if !ok {
-		return nil, output.ErrValidation("--scope must be specific / public / tenant, got %q", scope)
+		return nil, appsValidationParamError("--scope", "--scope must be specific / public / tenant, got %q", scope)
 	}
 	body := map[string]interface{}{"scope": enum}
 
@@ -161,7 +171,7 @@ func buildAccessScopeBody(rctx *common.RuntimeContext) (map[string]interface{},
 		// 用户传统一格式 [{type:user|department|chat, id:...}]，body 里拆 3 个并列数组发后端。
 		var targets []map[string]interface{}
 		if err := json.Unmarshal([]byte(rctx.Str("targets")), &targets); err != nil {
-			return nil, output.ErrValidation("--targets is not valid JSON: %v", err)
+			return nil, appsValidationParamError("--targets", "--targets is not valid JSON: %v", err).WithCause(err)
 		}
 		users, departments, chats := splitAccessScopeTargets(targets)
 		if len(users) > 0 {

shortcuts/apps/apps_access_scope_set_test.go

@@ -8,9 +8,62 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/spf13/cobra"
+
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
 )
 
+func testRuntimeAccessScope(t *testing.T, scope, targets, approver string, applyEnabled, requireLogin bool) *common.RuntimeContext {
+	t.Helper()
+	cmd := &cobra.Command{Use: "access-scope-set"}
+	cmd.Flags().String("scope", scope, "")
+	cmd.Flags().String("targets", targets, "")
+	cmd.Flags().String("approver", approver, "")
+	cmd.Flags().Bool("apply-enabled", applyEnabled, "")
+	cmd.Flags().Bool("require-login", requireLogin, "")
+	return common.TestNewRuntimeContext(cmd, nil)
+}
+
+func TestBuildAccessScopeBody_Branches(t *testing.T) {
+	t.Run("invalid scope", func(t *testing.T) {
+		if _, err := buildAccessScopeBody(testRuntimeAccessScope(t, "bogus", "", "", false, false)); err == nil {
+			t.Error("unknown scope must error")
+		}
+	})
+	t.Run("specific with all target kinds and approver", func(t *testing.T) {
+		body, err := buildAccessScopeBody(testRuntimeAccessScope(t,
+			"specific",
+			`[{"type":"user","id":"u1"},{"type":"department","id":"d1"},{"type":"chat","id":"c1"}]`,
+			"ou_appr", true, false))
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if body["scope"] != "Range" {
+			t.Errorf("scope=%v want Range", body["scope"])
+		}
+		for _, k := range []string{"users", "departments", "chats", "apply_config"} {
+			if _, ok := body[k]; !ok {
+				t.Errorf("missing %q in body=%v", k, body)
+			}
+		}
+	})
+	t.Run("specific with invalid targets JSON", func(t *testing.T) {
+		if _, err := buildAccessScopeBody(testRuntimeAccessScope(t, "specific", "{bad", "", false, false)); err == nil {
+			t.Error("invalid targets JSON must error")
+		}
+	})
+	t.Run("public sets require_login", func(t *testing.T) {
+		body, err := buildAccessScopeBody(testRuntimeAccessScope(t, "public", "", "", false, true))
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if body["scope"] != "All" || body["require_login"] != true {
+			t.Errorf("public body=%v", body)
+		}
+	})
+}
+
 func TestAppsAccessScopeSet_Specific(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
 	stub := &httpmock.Stub{
@@ -201,3 +254,44 @@ func TestAppsAccessScopeSet_TrimsAppIDInPath(t *testing.T) {
 		t.Fatalf("execute err=%v", err)
 	}
 }
+
+func TestSplitAccessScopeTargets_Partitions(t *testing.T) {
+	users, departments, chats := splitAccessScopeTargets([]map[string]interface{}{
+		{"type": "user", "id": "u1"},
+		{"type": "department", "id": "d1"},
+		{"type": "chat", "id": "c1"},
+		{"type": "user", "id": "  "},   // empty id skipped
+		{"type": "unknown", "id": "x"}, // unknown type skipped
+	})
+	if len(users) != 1 || users[0] != "u1" {
+		t.Errorf("users=%v want [u1]", users)
+	}
+	if len(departments) != 1 || departments[0] != "d1" {
+		t.Errorf("departments=%v want [d1]", departments)
+	}
+	if len(chats) != 1 || chats[0] != "c1" {
+		t.Errorf("chats=%v want [c1]", chats)
+	}
+}
+
+func TestValidateTargetsJSON_Cases(t *testing.T) {
+	cases := []struct {
+		name    string
+		in      string
+		wantErr bool
+	}{
+		{"invalid json", "{not json", true},
+		{"empty array", "[]", true},
+		{"bad type", `[{"type":"role","id":"r1"}]`, true},
+		{"empty id", `[{"type":"user","id":"  "}]`, true},
+		{"valid", `[{"type":"user","id":"u1"}]`, false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			err := validateTargetsJSON(c.in)
+			if (err != nil) != c.wantErr {
+				t.Errorf("validateTargetsJSON(%q) err=%v wantErr=%v", c.in, err, c.wantErr)
+			}
+		})
+	}
+}

shortcuts/apps/apps_callapi_typed_test.go

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+// TestAppsList_503IsRetryableTypedError pins the typed-error upgrade: a 5xx
+// response from the apps list endpoint must surface as a typed errs.Problem with
+// Retryable == true (via CallAPITyped → httpStatusError). The pre-migration
+// CallAPI path produced a legacy *output.ExitError with no Retryable field, so
+// this test fails until AppsList is migrated to CallAPITyped.
+func TestAppsList_503IsRetryableTypedError(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps",
+		Status: 503,
+		// A gateway-style non-JSON body (text/html) forces the status-based
+		// classifier (httpStatusError) rather than the API-envelope path.
+		Headers: http.Header{"Content-Type": []string{"text/html"}},
+		RawBody: []byte("<html><body>503 Service Unavailable</body></html>"),
+	})
+
+	err := runAppsShortcut(t, AppsList,
+		[]string{"+list", "--as", "user"}, factory, stdout)
+	if err == nil {
+		t.Fatalf("expected an error on 503, got nil; stdout:\n%s", stdout.String())
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected a typed errs.Problem on 503, got %T: %v", err, err)
+	}
+	if !p.Retryable {
+		t.Fatalf("expected Retryable == true on 503, got Problem=%+v", p)
+	}
+}
+
+// TestAppsList_SuccessShapeUnchanged pins that the success path is
+// output-shape-neutral after migration: a 200 envelope still yields a success
+// stdout envelope carrying the app_id.
+func TestAppsList_SuccessShapeUnchanged(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{"app_id": "a", "name": "n"},
+				},
+			},
+		},
+	})
+
+	if err := runAppsShortcut(t, AppsList,
+		[]string{"+list", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if got := stdout.String(); !strings.Contains(got, `"app_id": "a"`) {
+		t.Fatalf("stdout missing app_id: %s", got)
+	}
+}

shortcuts/apps/apps_chat.go

@@ -0,0 +1,82 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsChat sends a user message to a session, starting/continuing a conversation.
+// Async: the message is queued and the response carries no business payload (no
+// turn_id, no next_poll_after_ms — the turn is not generated yet). Poll
+// +session-get; it returns next_poll_after_ms, and once the turn runs its handle
+// is in latest_turn.turn_id.
+
+// Turn cost varies sharply by init state: the first +chat on a not-initialized
+// app runs a one-time design + first-generation pass server-side (~20-50 min);
+// chat on an already-initialized app is incremental and finishes in minutes.
+// The init-state check and matching polling cadence live in the lark-apps
+// skill reference (references/lark-apps-cloud-dev.md) — the canonical source.
+var AppsChat = common.Shortcut{
+	Service:     appsService,
+	Command:     "+chat",
+	Description: "Send a message to a session to start/continue a conversation",
+	Risk:        "write",
+	Tips: []string{
+		`Example: lark-cli apps +chat --app-id <app_id> --session-id <session_id> --message "做一个待办清单页面"`,
+		`Example: lark-cli apps +chat --app-id <app_id> --session-id <session_id> --message "把首页标题改为 我的待办"`,
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "session-id", Desc: "session ID", Required: true},
+		{Name: "message", Desc: "user message text", Required: true},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if strings.TrimSpace(rctx.Str("app-id")) == "" {
+			return appsValidationParamError("--app-id", "--app-id is required")
+		}
+		if strings.TrimSpace(rctx.Str("session-id")) == "" {
+			return appsValidationParamError("--session-id", "--session-id is required")
+		}
+		// Do not echo --message content in the error (spec §4 redaction).
+		if strings.TrimSpace(rctx.Str("message")) == "" {
+			return appsValidationParamError("--message", "--message is required")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		return common.NewDryRunAPI().
+			POST(chatPath(rctx.Str("app-id"), rctx.Str("session-id"))).
+			Desc("Send a message to a session").
+			Body(buildChatBody(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		data, err := rctx.CallAPITyped("POST", chatPath(rctx.Str("app-id"), rctx.Str("session-id")), nil, buildChatBody(rctx))
+		if err != nil {
+			return withAppsHint(err, "if the session_id is unknown or invalid, list this app's sessions with `lark-cli apps +session-list --app-id "+strings.TrimSpace(rctx.Str("app-id"))+"`")
+		}
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "message sent; poll +session-get for turn status\n")
+		})
+		return nil
+	},
+}
+
+func chatPath(appID, sessionID string) string {
+	return sessionPath(appID, sessionID) + "/chat"
+}
+
+func buildChatBody(rctx *common.RuntimeContext) map[string]interface{} {
+	return map[string]interface{}{
+		"message": strings.TrimSpace(rctx.Str("message")),
+	}
+}

shortcuts/apps/apps_chat_test.go

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestAppsChat_Success(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sessions/conv_x/chat",
+		Body: map[string]interface{}{
+			"code": 0,
+			// +chat is async and returns NO business payload (no turn_id, no
+			// next_poll_after_ms — the turn is not generated yet). turn_id and the
+			// poll interval are read later from +session-get.
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(stub)
+	if err := runAppsShortcut(t, AppsChat,
+		[]string{"+chat", "--app-id", "app_x", "--session-id", "conv_x", "--message", "把首页表头改成蓝色", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	var sent map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &sent); err != nil {
+		t.Fatalf("decode body: %v", err)
+	}
+	if sent["message"] != "把首页表头改成蓝色" {
+		t.Fatalf("body.message = %v", sent["message"])
+	}
+	if _, present := sent["attachment_ids"]; present {
+		t.Fatalf("attachment_ids must not be sent this iteration: %v", sent)
+	}
+	// +chat carries no next_poll_after_ms; the CLI must not fabricate one.
+	if got := stdout.String(); strings.Contains(got, "next_poll_after_ms") {
+		t.Fatalf("stdout must not reference next_poll_after_ms (chat returns none): %s", got)
+	}
+}
+
+func TestAppsChat_Pretty(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sessions/conv_x/chat",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{}},
+	})
+	if err := runAppsShortcut(t, AppsChat,
+		[]string{"+chat", "--app-id", "app_x", "--session-id", "conv_x", "--message", "hi", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if got := stdout.String(); !strings.Contains(got, "message sent") || !strings.Contains(got, "+session-get") {
+		t.Fatalf("pretty wrong: %q", got)
+	}
+}
+
+func TestAppsChat_RequiresMessage(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsChat,
+		[]string{"+chat", "--app-id", "app_x", "--session-id", "conv_x", "--message", "", "--as", "user"}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "message") {
+		t.Fatalf("expected --message required error, got %v", err)
+	}
+}
+
+// Security: a non-blank message that fails for another reason must never be echoed.
+// Here we assert the blank-message error names the field only (no content leak path).
+func TestAppsChat_ValidationDoesNotEchoMessage(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	// blank message triggers validation; the error must mention the flag, not any content.
+	err := runAppsShortcut(t, AppsChat,
+		[]string{"+chat", "--app-id", "", "--session-id", "conv_x", "--message", "secret-content-xyz", "--as", "user"}, factory, stdout)
+	if err == nil {
+		t.Fatalf("expected validation error")
+	}
+	if strings.Contains(err.Error(), "secret-content-xyz") {
+		t.Fatalf("validation error must not echo --message content: %v", err)
+	}
+}
+
+func TestAppsChat_DryRun(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsChat,
+		[]string{"+chat", "--app-id", "app_x", "--session-id", "conv_x", "--message", "hi", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "/open-apis/spark/v1/apps/app_x/sessions/conv_x/chat") {
+		t.Fatalf("dry-run missing endpoint: %s", got)
+	}
+	if !strings.Contains(got, `"message": "hi"`) {
+		t.Fatalf("dry-run missing message body: %s", got)
+	}
+}

shortcuts/apps/apps_create.go

@@ -9,35 +9,33 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+const createHint = "verify --app-type is html or full_stack and --name is non-empty; if this is a permission error, confirm your account can create Miaoda apps"
+
 // AppsCreate creates a new Miaoda app.
 var AppsCreate = common.Shortcut{
 	Service:     appsService,
 	Command:     "+create",
 	Description: "Create a new Miaoda app",
 	Risk:        "write",
-	Scopes:      []string{"spark:app:write"},
-	AuthTypes:   []string{"user"},
-	HasFormat:   true,
+	Tips: []string{
+		`Example: lark-cli apps +create --name "审批系统" --app-type full_stack`,
+		`Example: lark-cli apps +create --name "活动页" --app-type html --description "活动报名"`,
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
 	Flags: []common.Flag{
 		{Name: "name", Desc: "app display name", Required: true},
-		{Name: "app-type", Desc: "app type (currently only: HTML)", Required: true},
+		{Name: "app-type", Desc: "app type", Required: true, Enum: []string{"html", "full_stack"}},
 		{Name: "description", Desc: "app description"},
 		{Name: "icon-url", Desc: "app icon URL (server uses default if omitted)"},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("name")) == "" {
-			return output.ErrValidation("--name is required")
-		}
-		appType := strings.TrimSpace(rctx.Str("app-type"))
-		if appType == "" {
-			return output.ErrValidation("--app-type is required")
-		}
-		if !validAppTypes[appType] {
-			return output.ErrValidation(fmt.Sprintf("--app-type %q is not supported (allowed: HTML)", appType))
+			return appsValidationParamError("--name", "--name is required")
 		}
 		return nil
 	},
@@ -48,9 +46,9 @@ var AppsCreate = common.Shortcut{
 			Body(buildAppsCreateBody(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-		data, err := rctx.CallAPI("POST", apiBasePath+"/apps", nil, buildAppsCreateBody(rctx))
+		data, err := rctx.CallAPITyped("POST", apiBasePath+"/apps", nil, buildAppsCreateBody(rctx))
 		if err != nil {
-			return err
+			return withAppsHint(err, createHint)
 		}
 		rctx.OutFormat(data, nil, func(w io.Writer) {
 			fmt.Fprintf(w, "created: %s\n", common.GetString(data, "app", "app_id"))
@@ -59,15 +57,13 @@ var AppsCreate = common.Shortcut{
 	},
 }
 
-// 应用类型枚举。当前只有 HTML，未来会扩展（SPA、NATIVE、...）。
-var validAppTypes = map[string]bool{
-	"HTML": true,
-}
-
 func buildAppsCreateBody(rctx *common.RuntimeContext) map[string]interface{} {
+	// --app-type is constrained to the lowercase enum (html / full_stack) by the
+	// flag's Enum, so send it through verbatim. Legacy uppercase compatibility is
+	// a server concern and is intentionally not surfaced by the CLI.
 	body := map[string]interface{}{
 		"name":     strings.TrimSpace(rctx.Str("name")),
-		"app_type": strings.TrimSpace(rctx.Str("app-type")),
+		"app_type": rctx.Str("app-type"),
 	}
 	if desc := strings.TrimSpace(rctx.Str("description")); desc != "" {
 		body["description"] = desc

shortcuts/apps/apps_create_test.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -22,6 +23,7 @@ import (
 
 func newAppsExecuteFactory(t *testing.T) (*cmdutil.Factory, *bytes.Buffer, *httpmock.Registry) {
 	t.Helper()
+	t.Setenv("HOME", t.TempDir())
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	cfg := &core.CliConfig{
 		AppID:      "test-app-" + strings.ToLower(t.Name()),
@@ -46,6 +48,31 @@ func runAppsShortcut(t *testing.T, sc common.Shortcut, args []string, factory *c
 	return parent.ExecuteContext(context.Background())
 }
 
+func requireAppsProblem(t *testing.T, err error, category errs.Category) *errs.Problem {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("expected error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T: %v", err, err)
+	}
+	if p.Category != category {
+		t.Fatalf("error category = %q, want %q", p.Category, category)
+	}
+	return p
+}
+
+func requireAppsValidationProblem(t *testing.T, err error) *errs.Problem {
+	t.Helper()
+	return requireAppsProblem(t, err, errs.CategoryValidation)
+}
+
+func requireAppsAPIProblem(t *testing.T, err error) *errs.Problem {
+	t.Helper()
+	return requireAppsProblem(t, err, errs.CategoryAPI)
+}
+
 // +create 测试
 
 func TestAppsCreate_Success(t *testing.T) {
@@ -68,7 +95,7 @@ func TestAppsCreate_Success(t *testing.T) {
 	reg.Register(stub)
 
 	if err := runAppsShortcut(t, AppsCreate,
-		[]string{"+create", "--name", "Demo", "--app-type", "HTML", "--description", "d", "--as", "user"},
+		[]string{"+create", "--name", "Demo", "--app-type", "html", "--description", "d", "--as", "user"},
 		factory, stdout); err != nil {
 		t.Fatalf("execute err=%v", err)
 	}
@@ -83,8 +110,8 @@ func TestAppsCreate_Success(t *testing.T) {
 	if sent["name"] != "Demo" {
 		t.Fatalf("body.name = %v", sent["name"])
 	}
-	if sent["app_type"] != "HTML" {
-		t.Fatalf("body.app_type = %v (want HTML)", sent["app_type"])
+	if sent["app_type"] != "html" {
+		t.Fatalf("body.app_type = %v (want html)", sent["app_type"])
 	}
 	if sent["description"] != "d" {
 		t.Fatalf("body.description = %v", sent["description"])
@@ -108,7 +135,7 @@ func TestAppsCreate_WithIconURL(t *testing.T) {
 	})
 
 	if err := runAppsShortcut(t, AppsCreate,
-		[]string{"+create", "--name", "Demo", "--app-type", "HTML", "--icon-url", "https://example.com/icon.svg", "--as", "user"},
+		[]string{"+create", "--name", "Demo", "--app-type", "html", "--icon-url", "https://example.com/icon.svg", "--as", "user"},
 		factory, stdout); err != nil {
 		t.Fatalf("execute err=%v", err)
 	}
@@ -133,7 +160,7 @@ func TestAppsCreate_PrettyOutputReadsNestedAppID(t *testing.T) {
 	})
 
 	if err := runAppsShortcut(t, AppsCreate,
-		[]string{"+create", "--name", "Demo", "--app-type", "HTML", "--format", "pretty", "--as", "user"},
+		[]string{"+create", "--name", "Demo", "--app-type", "html", "--format", "pretty", "--as", "user"},
 		factory, stdout); err != nil {
 		t.Fatalf("execute err=%v", err)
 	}
@@ -144,7 +171,7 @@ func TestAppsCreate_PrettyOutputReadsNestedAppID(t *testing.T) {
 
 func TestAppsCreate_RequiresName(t *testing.T) {
 	factory, stdout, _ := newAppsExecuteFactory(t)
-	err := runAppsShortcut(t, AppsCreate, []string{"+create", "--app-type", "HTML", "--as", "user"}, factory, stdout)
+	err := runAppsShortcut(t, AppsCreate, []string{"+create", "--app-type", "html", "--as", "user"}, factory, stdout)
 	if err == nil || !strings.Contains(err.Error(), "name") {
 		t.Fatalf("expected name required error, got %v", err)
 	}
@@ -159,20 +186,31 @@ func TestAppsCreate_RequiresAppType(t *testing.T) {
 	}
 }
 
+// TestAppsCreate_RejectsInvalidAppType pins that --app-type is a strict
+// lowercase enum (html / full_stack). Unknown values and legacy uppercase are
+// both rejected by the flag's Enum — the CLI does not normalize case; legacy
+// uppercase compatibility is a server-side concern, not surfaced by the client.
 func TestAppsCreate_RejectsInvalidAppType(t *testing.T) {
-	factory, stdout, _ := newAppsExecuteFactory(t)
-	err := runAppsShortcut(t, AppsCreate,
-		[]string{"+create", "--name", "Demo", "--app-type", "spa", "--as", "user"},
-		factory, stdout)
-	if err == nil || !strings.Contains(err.Error(), "not supported") {
-		t.Fatalf("expected unsupported app-type error, got %v", err)
+	for _, appType := range []string{"spa", "HTML", "Full_Stack"} {
+		t.Run(appType, func(t *testing.T) {
+			factory, stdout, _ := newAppsExecuteFactory(t)
+			err := runAppsShortcut(t, AppsCreate,
+				[]string{"+create", "--name", "Demo", "--app-type", appType, "--as", "user"},
+				factory, stdout)
+			if err == nil || !strings.Contains(err.Error(), "invalid value") {
+				t.Fatalf("expected invalid-enum error for %q, got %v", appType, err)
+			}
+			if !strings.Contains(err.Error(), "full_stack") {
+				t.Fatalf("expected enum error to list allowed values, got %v", err)
+			}
+		})
 	}
 }
 
 func TestAppsCreate_DryRun(t *testing.T) {
 	factory, stdout, _ := newAppsExecuteFactory(t)
 	if err := runAppsShortcut(t, AppsCreate,
-		[]string{"+create", "--name", "Demo", "--app-type", "HTML", "--dry-run", "--as", "user"},
+		[]string{"+create", "--name", "Demo", "--app-type", "html", "--dry-run", "--as", "user"},
 		factory, stdout); err != nil {
 		t.Fatalf("dry-run err=%v", err)
 	}
@@ -183,7 +221,55 @@ func TestAppsCreate_DryRun(t *testing.T) {
 	if !strings.Contains(got, `"name": "Demo"`) {
 		t.Fatalf("dry-run missing body: %s", got)
 	}
-	if !strings.Contains(got, `"app_type": "HTML"`) {
+	if !strings.Contains(got, `"app_type": "html"`) {
 		t.Fatalf("dry-run missing app_type: %s", got)
 	}
 }
+
+func TestAppsCreate_FullstackSuccess(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"app": map[string]interface{}{"app_id": "app_fs", "name": "Demo"},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	if err := runAppsShortcut(t, AppsCreate,
+		[]string{"+create", "--name", "Demo", "--app-type", "full_stack", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+
+	var sent map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &sent); err != nil {
+		t.Fatalf("decode body: %v", err)
+	}
+	if sent["app_type"] != "full_stack" {
+		t.Fatalf("body.app_type = %v (want full_stack)", sent["app_type"])
+	}
+	if _, present := sent["message"]; present {
+		t.Fatalf("message should never be sent: %v", sent)
+	}
+}
+
+func TestAppsCreate_FullstackDryRun(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCreate,
+		[]string{"+create", "--name", "Demo", "--app-type", "full_stack", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, `"app_type": "full_stack"`) {
+		t.Fatalf("dry-run missing app_type full_stack: %s", got)
+	}
+	if strings.Contains(got, `"message"`) {
+		t.Fatalf("dry-run should not contain message: %s", got)
+	}
+}

shortcuts/apps/apps_db_env_create.go

@@ -0,0 +1,98 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const dbEnvCreateHint = "verify --app-id is correct; if the app is already multi-env this is a conflict — inspect current tables with `lark-cli apps +db-table-list --app-id <app_id> --env dev`"
+
+// AppsDBEnvCreate creates a DB environment for a Miaoda app（拆分单库为 dev/online 多环境）。
+//
+// 调 POST /apps/{app_id}/db_dev_init。--env 指定要创建的环境，由调用方传入，目前只支持 dev。
+// 不可逆：单库一旦拆成 dev/online 双库无法回退。Risk: high-risk-write 触发框架自动注入 --yes 确认关卡。
+var AppsDBEnvCreate = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-env-create",
+	Description: "Create a DB environment (split single-env DB into dev/online, irreversible)",
+	Risk:        "high-risk-write",
+	Tips: []string{
+		"Example: lark-cli apps +db-env-create --env dev --sync-data --app-id <app_id> --yes",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "env", Default: "dev", Enum: []string{"dev"}, Desc: "environment to create (only dev supported for now)"},
+		{Name: "sync-data", Type: "bool", Desc: "copy existing online data into the new environment (default off)"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(appDbEnvCreatePath(appID)).
+			Desc("Create Miaoda app DB environment").
+			Body(buildDBEnvCreateBody(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("POST", appDbEnvCreatePath(appID), nil, buildDBEnvCreateBody(rctx))
+		if err != nil {
+			return withAppsHint(err, dbEnvCreateHint)
+		}
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			renderEnvCreatePretty(w, data)
+		})
+		return nil
+	},
+}
+
+// buildDBEnvCreateBody 构造 db 环境创建 body：sync_data（bool）。
+// --env 目前只支持 dev、服务端接口本身即创建 dev 环境，故不下发 env 字段（仅做 CLI 入参校验/前向兼容）。
+func buildDBEnvCreateBody(rctx *common.RuntimeContext) map[string]interface{} {
+	return map[string]interface{}{
+		"sync_data": rctx.Bool("sync-data"),
+	}
+}
+
+// renderEnvCreatePretty 输出 4 行（pretty 模式）：
+//
+//	✓ Multi-env initialized
+//	Environments: dev, online
+//	Data synced: yes
+//	Note: structure changes in dev now need to be released to online.
+func renderEnvCreatePretty(w io.Writer, data map[string]interface{}) {
+	fmt.Fprintln(w, "✓ Multi-env initialized")
+
+	if envs, ok := data["environments"].([]interface{}); ok && len(envs) > 0 {
+		names := make([]string, 0, len(envs))
+		for _, e := range envs {
+			if s, ok := e.(string); ok {
+				names = append(names, s)
+			}
+		}
+		fmt.Fprintf(w, "Environments: %s\n", strings.Join(names, ", "))
+	}
+
+	synced := "no"
+	if ds, ok := data["data_synced"].(bool); ok && ds {
+		synced = "yes"
+	}
+	fmt.Fprintf(w, "Data synced: %s\n", synced)
+
+	fmt.Fprintln(w, "Note: structure changes in dev now need to be released to online.")
+}

shortcuts/apps/apps_db_env_create_test.go

@@ -0,0 +1,124 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestAppsDBEnvCreate_WithYesPostsSyncData(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/db_dev_init", // URL 仍走 db_dev_init，CLI 命令名 +db-env-create
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"status":       "initialized",
+				"environments": []interface{}{"dev", "online"},
+				"data_synced":  true,
+			},
+		},
+	}
+	reg.Register(stub)
+	if err := runAppsShortcut(t, AppsDBEnvCreate,
+		[]string{"+db-env-create", "--app-id", "app_x", "--env", "dev", "--sync-data", "--yes", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+
+	var sent map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &sent); err != nil {
+		t.Fatalf("decode body: %v", err)
+	}
+	if sent["sync_data"] != true {
+		t.Fatalf("body.sync_data = %v (want true)", sent["sync_data"])
+	}
+	if !strings.Contains(stdout.String(), "initialized") {
+		t.Fatalf("stdout should include status, got %s", stdout.String())
+	}
+}
+
+// 不传 --sync-data（默认）→ body.sync_data=false
+func TestAppsDBEnvCreate_SyncDataFalseByDefault(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/db_dev_init",
+		Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"status": "initialized"}},
+	}
+	reg.Register(stub)
+	if err := runAppsShortcut(t, AppsDBEnvCreate,
+		[]string{"+db-env-create", "--app-id", "app_x", "--env", "dev", "--yes", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	var sent map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &sent); err != nil {
+		t.Fatalf("decode body: %v", err)
+	}
+	if sent["sync_data"] != false {
+		t.Fatalf("body.sync_data = %v (want false by default)", sent["sync_data"])
+	}
+}
+
+func TestAppsDBEnvCreate_PrettyEmitsAllFourLines(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/db_dev_init",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"status":       "initialized",
+				"environments": []interface{}{"dev", "online"},
+				"data_synced":  true,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBEnvCreate,
+		[]string{"+db-env-create", "--app-id", "app_x", "--env", "dev", "--sync-data", "--yes", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	wantLines := []string{
+		"✓ Multi-env initialized",
+		"Environments: dev, online",
+		"Data synced: yes",
+		"Note: structure changes in dev now need to be released to online.",
+	}
+	for _, line := range wantLines {
+		if !strings.Contains(got, line) {
+			t.Errorf("pretty output missing line %q\ngot:\n%s", line, got)
+		}
+	}
+}
+
+func TestAppsDBEnvCreate_DryRunNoConfirm(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBEnvCreate,
+		[]string{"+db-env-create", "--app-id", "app_x", "--env", "dev", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	if got := stdout.String(); !strings.Contains(got, "/open-apis/spark/v1/apps/app_x/db_dev_init") {
+		t.Fatalf("dry-run missing endpoint: %s", got)
+	}
+}
+
+// --env 只接受 dev：传 online 应被 enum 校验拒绝。
+func TestAppsDBEnvCreate_RejectsNonDevEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBEnvCreate,
+		[]string{"+db-env-create", "--app-id", "app_x", "--env", "online", "--yes", "--as", "user"},
+		factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "env") {
+		t.Fatalf("expected env enum rejection, got %v", err)
+	}
+}

shortcuts/apps/apps_db_execute.go

@@ -0,0 +1,528 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsDBExecute executes SQL against a Miaoda app database.
+//
+// POST /apps/{app_id}/sql_commands，CLI 永远带 ?transactional=false 进入 DBA 模式
+// （不默认包事务、支持 DDL、result 字符串内嵌结构化 JSON）。
+//
+// pretty 渲染 6 种形态：
+//   - 单 SELECT：表格（列间两空格、列对齐填充）
+//   - 空 SELECT：`(0 rows)`
+//   - 单 DML：`✓ N row(s) <verb>`（verb 跟 sql_type：INSERT→inserted/UPDATE→updated/DELETE→deleted）
+//   - 单 DDL：`✓ DDL executed`
+//   - 多语句全部成功：逐条 `Statement K: ✓ <summary>` + 末尾 `✓ N statements executed`
+//   - 多语句部分失败：`Statement K: ✗ <message> [<code>]` + 末尾「前序语句已落地」提示
+//
+// 失败语义：server 多语句失败仍返 code:0，把失败语句标成 ERROR 哨兵塞进 result。Execute 检测到哨兵
+// 后按 partial failure 上报（exit 非 0）：stdout 输出 ok:false 数据，带 results /
+// statement_index / error_code / error_message / rolled_back / note，避免 agent 误判
+// ok:true 假成功。CLI 永远 DBA 模式（transactional=false），失败前的语句已 auto-commit
+// 落地，故 rolled_back=false（真机 boe 实证）。
+//
+// JSON envelope（成功路径）：CLI 把 server 返的 result 字符串解出来放进 `data.results` 数组。
+//
+// Risk: high-risk-write —— SQL 可含 DML/DDL，框架对所有执行强制 --yes 确认关卡（--dry-run 预览豁免）。
+//
+// SQL 来源二选一：--sql（内联文本，或 - 读 stdin）/ --file（.sql 文件路径，受 CLI 相对路径约束）。
+// --file 在 Validate 阶段读出内容、归一化到 --sql，下游统一从 rctx.Str("sql") 取。
+var AppsDBExecute = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-execute",
+	Description: "Execute SQL (SELECT / DML / DDL) against a Miaoda app database",
+	Risk:        "high-risk-write",
+	Tips: []string{
+		`Example: lark-cli apps +db-execute --app-id <app_id> --sql "SELECT * FROM orders LIMIT 10" --yes`,
+		`Example: lark-cli apps +db-execute --app-id <app_id> --env dev --file ./migration.sql --yes`,
+		"Tip: filter fields with --jq, e.g. -q '.data.results[].sql_type'",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "sql", Desc: "SQL text; use - to read stdin. Mutually exclusive with --file",
+			Input: []string{common.Stdin}},
+		{Name: "file", Desc: "path to a .sql file (relative to cwd). Mutually exclusive with --sql"},
+		{Name: "env", Default: "dev", Enum: []string{"dev", "online"}, Desc: "target db environment (default dev; use --env online for the online environment)"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		sql := strings.TrimSpace(rctx.Str("sql"))
+		file := strings.TrimSpace(rctx.Str("file"))
+		if sql != "" && file != "" {
+			return appsValidationError("--sql and --file are mutually exclusive").
+				WithParams(
+					appsInvalidParam("--sql", "mutually exclusive with --file"),
+					appsInvalidParam("--file", "mutually exclusive with --sql"),
+				)
+		}
+		if file != "" {
+			data, err := cmdutil.ReadInputFile(rctx.FileIO(), file)
+			if err != nil {
+				return appsValidationParamError("--file", "--file: %v", err).WithCause(err)
+			}
+			// 归一化：把文件内容写回 --sql，下游（DryRun/Execute）统一从 sql 取。
+			rctx.Cmd.Flags().Set("sql", string(data))
+			sql = strings.TrimSpace(string(data))
+		}
+		if sql == "" {
+			return appsValidationError("one of --sql or --file is required (use --sql - to read stdin)").
+				WithParams(
+					appsInvalidParam("--sql", "one of --sql or --file is required"),
+					appsInvalidParam("--file", "one of --sql or --file is required"),
+				)
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(appSQLPath(appID)).
+			Desc("Execute SQL on Miaoda app database").
+			Params(buildDBSQLParams(rctx)).
+			Body(buildDBSQLBody(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		raw, err := rctx.CallAPITyped("POST", appSQLPath(appID),
+			buildDBSQLParams(rctx),
+			buildDBSQLBody(rctx))
+		if err != nil {
+			return withAppsHint(err, "verify table/column names with `lark-cli apps +db-table-get --app-id "+appID+" --table <table>`; for day-to-day debugging target the dev database with `--env dev`")
+		}
+
+		// server `result: string` 内嵌结构化数组 —— CLI 解出来放进 envelope 的 data.results，
+		// 让 json/pretty 路径都基于同一份反序列化产物渲染。
+		stmts := parseSQLResult(common.GetString(raw, "result"))
+		// 注意：data.results 在 json（默认）路径下原样透出全部行，CLI 侧不再二次截断。
+		// 这不是无界 token 黑洞 —— server 对单条 SELECT 结果集有 1000 行硬上限，超出会直接
+		// 返报错（而非静默截断）。需要更大结果集时请在 SQL 里显式 LIMIT/分页，由调用方控制规模。
+		data := map[string]interface{}{"results": stmts}
+
+		// 多语句 / 单语句失败：server 仍返 code:0，把失败语句标成 ERROR 哨兵塞进 result。
+		// 已落地的前序语句 + 失败语句构成 partial failure：逐条结果作为 ok:false 数据
+		// 留在 stdout（机器可读）+ 非零退出信号，别让 agent 误判 ok:true 假成功。
+		// pretty 模式 stdout 只打逐条 ✓/✗ 摘要（不再叠一份 JSON envelope），仅返回退出信号。
+		if errIdx, errStmt, failed := findErrorSentinel(stmts); failed {
+			if rctx.Format == "pretty" {
+				renderSQLPretty(rctx.IO().Out, stmts)
+				return output.PartialFailure(output.ExitAPI)
+			}
+			return rctx.OutPartialFailure(sqlStatementFailurePayload(stmts, errIdx, errStmt), nil)
+		}
+
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			renderSQLPretty(w, stmts)
+		})
+		return nil
+	},
+}
+
+// findErrorSentinel 在 statements 里找 ERROR 哨兵（server 失败时追加在失败语句位置）。
+// 返回失败语句下标（0-based）、该 ERROR statement、是否命中。
+func findErrorSentinel(stmts []map[string]interface{}) (int, map[string]interface{}, bool) {
+	for i, s := range stmts {
+		if common.GetString(s, "sql_type") == "ERROR" {
+			return i, s, true
+		}
+	}
+	return 0, nil, false
+}
+
+// sqlStatementFailurePayload 把 ERROR 哨兵整理成 partial-failure 的 stdout 数据。
+//
+// CLI 永远 DBA 模式（transactional=false），真机 boe 实证：失败语句之前的语句已逐条 auto-commit
+// 落地，不存在外层事务回滚。因此 rolled_back=false、results 含全部逐条结果（ERROR 哨兵在
+// 失败位置），note 提示用户别整批重跑（否则会重复写入）。
+func sqlStatementFailurePayload(stmts []map[string]interface{}, errIdx int, errStmt map[string]interface{}) map[string]interface{} {
+	code, msg := parseErrorSentinel(common.GetString(errStmt, "data"))
+	stmtNo := errIdx + 1 // 1-based 给人看
+	note := "no statements were applied; fix the SQL and re-run."
+	if errIdx > 0 {
+		note = fmt.Sprintf(
+			"statements 1-%d were already applied (DBA mode auto-commits each statement); fix statement %d and re-run only the remaining statements.",
+			errIdx, stmtNo)
+	}
+	return map[string]interface{}{
+		"results":         stmts,
+		"statement_index": errIdx,
+		"error_code":      code,
+		"error_message":   fmt.Sprintf("%s (at statement %d of %d)", msg, stmtNo, len(stmts)),
+		"rolled_back":     false,
+		"note":            note,
+	}
+}
+
+// parseErrorSentinel 解析 ERROR 哨兵的 data（`{code,message}` JSON），返回数值 code 与 message。
+// code 兼容 int / "k_dl_1300002" / 数字字符串多形态（复用 codeString），解析失败回退 0 / 原文。
+func parseErrorSentinel(data string) (int, string) {
+	if data == "" {
+		return 0, "(unknown error)"
+	}
+	var e struct {
+		Code    interface{} `json:"code"`
+		Message string      `json:"message"`
+	}
+	if err := json.Unmarshal([]byte(data), &e); err != nil {
+		return 0, data
+	}
+	code := 0
+	if cs := codeString(e.Code); cs != "" {
+		if n, convErr := strconv.Atoi(cs); convErr == nil {
+			code = n
+		}
+	}
+	if e.Message == "" {
+		return code, "(unknown error)"
+	}
+	return code, e.Message
+}
+
+// buildDBSQLParams 构造 sql 接口的 query：env + 强制 transactional=false（DBA 模式）。
+//
+// CLI 永远走 DBA 模式，原子性由用户在 SQL 内显式 BEGIN/COMMIT 控制；不暴露 transactional flag 给用户。
+func buildDBSQLParams(rctx *common.RuntimeContext) map[string]interface{} {
+	return map[string]interface{}{
+		"env":           rctx.Str("env"),
+		"transactional": false,
+	}
+}
+
+// buildDBSQLBody 构造 sql 接口的 body：仅 sql（来源由 Validate 归一化到 --sql）。
+func buildDBSQLBody(rctx *common.RuntimeContext) map[string]interface{} {
+	return map[string]interface{}{
+		"sql": rctx.Str("sql"),
+	}
+}
+
+// parseSQLResult 从 server result 字符串反序列化出 statements 数组，兼容两种 wire 形态：
+//
+//  1. 结构化形态：`[{"sql_type":"SELECT","data":"[...]","record_count":N}, ...]`
+//     —— 每条 statement 含 sql_type / data / record_count / affected_rows 元数据。
+//
+//  2. 字符串数组形态：`["[{...rows...}]", "", ...]`
+//     —— 每条 statement 一个字符串：SELECT 是 rows JSON、DML/DDL 是空串；
+//     无 sql_type 元数据，CLI 端按内容形态推断（SELECT vs OK）。
+//
+// 解析失败时返回单元素 fallback `{sql_type:"RAW", data:resultStr}`，pretty 路径原样打。
+func parseSQLResult(resultStr string) []map[string]interface{} {
+	if resultStr == "" {
+		return nil
+	}
+
+	// 形态 1：结构化数组（每元素是 object）
+	var structured []map[string]interface{}
+	if err := json.Unmarshal([]byte(resultStr), &structured); err == nil && isStructuredResult(structured) {
+		return structured
+	}
+
+	// 形态 2：字符串数组（每元素是 rows JSON 或 ""）
+	var legacy []string
+	if err := json.Unmarshal([]byte(resultStr), &legacy); err == nil {
+		out := make([]map[string]interface{}, 0, len(legacy))
+		for _, rowsJSON := range legacy {
+			out = append(out, normalizeLegacyStatement(rowsJSON))
+		}
+		return out
+	}
+
+	return []map[string]interface{}{{"sql_type": "RAW", "data": resultStr}}
+}
+
+// isStructuredResult 判断反序列化出来的 []map 是不是新形态：第一条元素含 sql_type 字段。
+// 兼容场景：[]map 反序列化 legacy `[""]` 可能也能成（空 map），用 sql_type 存在性区分。
+func isStructuredResult(stmts []map[string]interface{}) bool {
+	if len(stmts) == 0 {
+		return false
+	}
+	_, ok := stmts[0]["sql_type"]
+	return ok
+}
+
+// normalizeLegacyStatement 把 legacy wire 一个字符串元素转成跟新形态一致的 map。
+// 推断规则：data 是非空 rows 数组 → sql_type=SELECT；空串 / 空数组 → sql_type=OK（DML/DDL 老 wire 不可分）。
+func normalizeLegacyStatement(rowsJSON string) map[string]interface{} {
+	stmt := map[string]interface{}{
+		"sql_type": "OK",
+		"data":     rowsJSON,
+	}
+	trimmed := strings.TrimSpace(rowsJSON)
+	if trimmed == "" || trimmed == "null" {
+		return stmt
+	}
+	var rows []interface{}
+	if err := json.Unmarshal([]byte(trimmed), &rows); err != nil {
+		// 非 JSON 数组（理论上 server 不会返这种），按原样保留 sql_type=OK
+		return stmt
+	}
+	// 是 JSON 数组 → 视作 SELECT，含 record_count
+	stmt["sql_type"] = "SELECT"
+	stmt["record_count"] = float64(len(rows))
+	return stmt
+}
+
+// renderSQLPretty 按 statements 数量分单条 / 多条两种渲染路径。
+func renderSQLPretty(w io.Writer, stmts []map[string]interface{}) {
+	if len(stmts) == 0 {
+		fmt.Fprintln(w, "(empty result)")
+		return
+	}
+	if len(stmts) == 1 {
+		renderSingleStatementPretty(w, stmts[0])
+		return
+	}
+	renderMultiStatementPretty(w, stmts)
+}
+
+// renderSingleStatementPretty 单条 statement pretty（无 Statement header）。
+func renderSingleStatementPretty(w io.Writer, s map[string]interface{}) {
+	sqlType := common.GetString(s, "sql_type")
+	switch {
+	case sqlType == "SELECT":
+		renderSelectRowsAsTable(w, common.GetString(s, "data"))
+	case sqlType == "ERROR":
+		// 单条就挂的极端场景：直接打 ERROR 行（跟多语句失败的最后一行格式一致）。
+		fmt.Fprintln(w, "✗ "+errorSummary(common.GetString(s, "data")))
+	case isDMLType(sqlType):
+		// 结构化 wire 下 INSERT / UPDATE / DELETE / MERGE：✓ N row(s) <verb>
+		fmt.Fprintln(w, "✓ "+dmlSummary(sqlType, s["affected_rows"]))
+	case sqlType == "OK":
+		// legacy wire 下 DML / DDL 都映射成 OK（老 wire 不带 sql_type 元数据，无法区分动词 / 行数）
+		fmt.Fprintln(w, "✓ ok")
+	default:
+		// 其余皆 DDL：真机 boe 返细粒度动词 CREATE_TABLE / DROP_TABLE / ALTER_TABLE / TRUNCATE 等。
+		fmt.Fprintln(w, "✓ DDL executed")
+	}
+}
+
+// renderMultiStatementPretty 多条 statement pretty：
+//   - 每条用 "Statement K: ✓ <summary>" / "Statement K: ✗ <error> [<code>]"
+//   - SELECT 用 "Statement K: SELECT (N row(s))" 头 + 紧跟表格
+//   - 末尾汇总：全部成功 "✓ N statements executed"；遇 ERROR 哨兵打「前序语句已落地」提示
+//     （DBA 模式不回滚），失败本身由 Execute 升级成 typed error（exit 非 0）
+func renderMultiStatementPretty(w io.Writer, stmts []map[string]interface{}) {
+	failedIdx := -1
+	successCount := 0
+	for i, s := range stmts {
+		sqlType := common.GetString(s, "sql_type")
+		idx := i + 1
+		switch {
+		case sqlType == "ERROR":
+			fmt.Fprintf(w, "Statement %d: ✗ %s\n", idx, errorSummary(common.GetString(s, "data")))
+			failedIdx = i
+		case sqlType == "SELECT":
+			rc := intOrZero(s["record_count"])
+			fmt.Fprintf(w, "Statement %d: SELECT (%d row%s)\n", idx, rc, plural(rc))
+			renderSelectRowsAsTable(w, common.GetString(s, "data"))
+			successCount++
+		case isDMLType(sqlType):
+			fmt.Fprintf(w, "Statement %d: ✓ %s\n", idx, dmlSummary(sqlType, s["affected_rows"]))
+			successCount++
+		case sqlType == "OK":
+			fmt.Fprintf(w, "Statement %d: ✓ ok\n", idx)
+			successCount++
+		default:
+			// DDL 族：CREATE_TABLE / DROP_TABLE / ALTER_TABLE / TRUNCATE / CREATE_INDEX ...
+			fmt.Fprintf(w, "Statement %d: ✓ DDL executed\n", idx)
+			successCount++
+		}
+		if i < len(stmts)-1 {
+			fmt.Fprintln(w) // statements 间留空行
+		}
+	}
+	fmt.Fprintln(w)
+	if failedIdx >= 0 {
+		// CLI 永远 DBA 模式（transactional=false），失败语句之前的语句已 auto-commit 落地，
+		// 不存在整批回滚 —— 如实告诉用户，避免整批重跑导致重复写入。
+		if successCount > 0 {
+			fmt.Fprintf(w, "(statement %d failed; %d statement%s before it already applied — DBA mode auto-commits each)\n",
+				failedIdx+1, successCount, plural(int64(successCount)))
+		} else {
+			fmt.Fprintf(w, "(statement %d failed; no statements applied)\n", failedIdx+1)
+		}
+	} else {
+		fmt.Fprintf(w, "✓ %d statements executed\n", successCount)
+	}
+}
+
+// renderSelectRowsAsTable 把 SELECT 的 data（rows JSON 数组字符串）解析并渲染成对齐表格。
+// 空结果输出 "(0 rows)"。
+func renderSelectRowsAsTable(w io.Writer, dataJSON string) {
+	if dataJSON == "" || dataJSON == "[]" {
+		fmt.Fprintln(w, "(0 rows)")
+		return
+	}
+	var rows []map[string]interface{}
+	if err := json.Unmarshal([]byte(dataJSON), &rows); err != nil {
+		// 数据不符合预期 schema —— 原样打 fallback。
+		fmt.Fprintln(w, dataJSON)
+		return
+	}
+	if len(rows) == 0 {
+		fmt.Fprintln(w, "(0 rows)")
+		return
+	}
+	headers := collectColumns(rows)
+	cells := make([][]string, 0, len(rows))
+	for _, row := range rows {
+		line := make([]string, 0, len(headers))
+		for _, h := range headers {
+			line = append(line, cellString(row[h]))
+		}
+		cells = append(cells, line)
+	}
+	renderAlignedTable(w, headers, cells)
+}
+
+// collectColumns 按首行字段顺序收集列名；首行 key 顺序由 encoding/json 反序列化决定（map 无序），
+// 排序后保证输出稳定。列顺序在示例里跟 SQL SELECT 顺序一致——但 Go encoding/json 反序列化丢列序，
+// 这里按字典序保证可重现，agent / 测试可稳定 assert。
+func collectColumns(rows []map[string]interface{}) []string {
+	set := map[string]struct{}{}
+	for _, r := range rows {
+		for k := range r {
+			set[k] = struct{}{}
+		}
+	}
+	cols := make([]string, 0, len(set))
+	for k := range set {
+		cols = append(cols, k)
+	}
+	sort.Strings(cols)
+	return cols
+}
+
+// cellString 把任意 JSON value 转字符串显示（null → 空串；非字符串/数字 → JSON 编码）。
+func cellString(v interface{}) string {
+	switch x := v.(type) {
+	case nil:
+		return ""
+	case string:
+		return x
+	case bool:
+		if x {
+			return "true"
+		}
+		return "false"
+	case float64:
+		// 整数值不输出小数（id=101 而不是 101.000000）。
+		if x == float64(int64(x)) {
+			return fmt.Sprintf("%d", int64(x))
+		}
+		return fmt.Sprintf("%g", x)
+	}
+	b, err := json.Marshal(v)
+	if err != nil {
+		return fmt.Sprintf("%v", v)
+	}
+	return string(b)
+}
+
+// dmlSummary 把 sql_type + affected_rows 渲染成 "N row(s) <verb>" 字符串。
+//
+// 动词映射：INSERT → inserted / UPDATE → updated / DELETE → deleted / MERGE → merged。
+// 未知 sql_type 默认 "affected"。
+func dmlSummary(sqlType string, affectedRows interface{}) string {
+	n := intOrZero(affectedRows)
+	verb := dmlVerb(sqlType)
+	return fmt.Sprintf("%d row%s %s", n, plural(n), verb)
+}
+
+// isDMLType 判断 sql_type 是否是行级 DML（带 affected_rows 语义）。
+// 真机 boe wire：SELECT 走表格、INSERT/UPDATE/DELETE/MERGE 走行数摘要、其余（CREATE_TABLE /
+// DROP_TABLE / ALTER_TABLE / TRUNCATE / CREATE_INDEX ...）一律按 DDL 处理。
+func isDMLType(sqlType string) bool {
+	switch strings.ToUpper(sqlType) {
+	case "INSERT", "UPDATE", "DELETE", "MERGE":
+		return true
+	}
+	return false
+}
+
+func dmlVerb(sqlType string) string {
+	switch strings.ToUpper(sqlType) {
+	case "INSERT":
+		return "inserted"
+	case "UPDATE":
+		return "updated"
+	case "DELETE":
+		return "deleted"
+	case "MERGE":
+		return "merged"
+	}
+	return "affected"
+}
+
+func plural(n int64) string {
+	if n == 1 {
+		return ""
+	}
+	return "s"
+}
+
+// errorSummary 从 ERROR 哨兵的 data 字段（{code, message} JSON）解析出 "message [code]" 形态。
+// 解析失败时回退到原文。
+func errorSummary(data string) string {
+	if data == "" {
+		return "(unknown error)"
+	}
+	var e struct {
+		Code    interface{} `json:"code"`
+		Message string      `json:"message"`
+	}
+	if err := json.Unmarshal([]byte(data), &e); err != nil {
+		return data
+	}
+	codeStr := codeString(e.Code)
+	if codeStr != "" {
+		return fmt.Sprintf("%s [%s]", e.Message, codeStr)
+	}
+	return e.Message
+}
+
+// codeString 处理 code 字段在 wire 上可能是 int / "k_dl_1300015" / 数字字符串等多形态。
+func codeString(c interface{}) string {
+	switch x := c.(type) {
+	case nil:
+		return ""
+	case string:
+		// "k_dl_1300015" → 抽 1300015；纯数字保持原样。
+		if strings.HasPrefix(x, "k_dl_") {
+			return strings.TrimPrefix(x, "k_dl_")
+		}
+		return x
+	case float64:
+		return fmt.Sprintf("%d", int64(x))
+	}
+	return ""
+}
+
+// intOrZero 把 JSON number 转 int64；nil / 类型不匹配返回 0。
+func intOrZero(raw interface{}) int64 {
+	if n, ok := numericAsFloat(raw); ok {
+		return int64(n)
+	}
+	return 0
+}

shortcuts/apps/apps_db_execute_test.go

@@ -0,0 +1,850 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+)
+
+func TestAppsDBExecute_SingleSELECTJSONEnvelopeWrapsResults(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				// DBA 模式 result：结构化数组 JSON 字符串
+				"result": `[{"sql_type":"SELECT","data":"[{\"id\":101,\"total_cents\":2500}]","record_count":1}]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "select 1", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	// JSON envelope 应该把 result 字符串 parse 之后放进 data.results
+	var env struct {
+		Data struct {
+			Results []map[string]interface{} `json:"results"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("decode envelope: %v\n%s", err, stdout.String())
+	}
+	if len(env.Data.Results) != 1 {
+		t.Fatalf("data.results = %d items (want 1)", len(env.Data.Results))
+	}
+	if env.Data.Results[0]["sql_type"] != "SELECT" {
+		t.Fatalf("results[0].sql_type = %v", env.Data.Results[0]["sql_type"])
+	}
+}
+
+func TestAppsDBExecute_DryRunSendsTransactionalFalse(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "select 1", "--env", "dev", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Body   map[string]interface{} `json:"body"`
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
+		t.Fatalf("decode: %v\n%s", err, stdout.String())
+	}
+	if env.API[0].Method != "POST" || env.API[0].URL != "/open-apis/spark/v1/apps/app_x/sql_commands" {
+		t.Fatalf("method/url = %s %s", env.API[0].Method, env.API[0].URL)
+	}
+	if env.API[0].Body["sql"] != "select 1" {
+		t.Fatalf("body.sql = %v", env.API[0].Body["sql"])
+	}
+	if env.API[0].Params["env"] != "dev" {
+		t.Fatalf("params.env = %v", env.API[0].Params["env"])
+	}
+	if env.API[0].Params["transactional"] != false {
+		t.Fatalf("params.transactional = %v (want false, CLI is DBA mode)", env.API[0].Params["transactional"])
+	}
+	if _, ok := env.API[0].Body["transactional"]; ok {
+		t.Fatalf("transactional should NOT be in body, got body=%v", env.API[0].Body)
+	}
+}
+
+func TestAppsDBExecute_RejectsEmptySQL(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "   ", "--as", "user"}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "--sql or --file") {
+		t.Fatalf("expected empty-sql error, got %v", err)
+	}
+}
+
+// --sql 与 --file 互斥
+func TestAppsDBExecute_RejectsSQLAndFileTogether(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "SELECT 1", "--file", "x.sql", "--as", "user"}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "mutually exclusive") {
+		t.Fatalf("expected mutual-exclusion error, got %v", err)
+	}
+}
+
+// --file 读取相对路径 .sql 文件 → 内容进 body.sql（dry-run 验证）
+func TestAppsDBExecute_FileReadsSQLIntoBody(t *testing.T) {
+	dir := t.TempDir()
+	sqlPath := filepath.Join(dir, "m.sql")
+	if err := os.WriteFile(sqlPath, []byte("SELECT 42 AS answer;\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	// 切到临时目录，使相对路径校验通过（CLI 仅接受 cwd 内相对路径）。
+	// 用 os.Chdir + 还原而非 t.Chdir：后者要 Go 1.24，本仓库 go.mod 为 1.23。
+	oldWD, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(oldWD) })
+
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--app-id", "app_x", "--env", "dev", "--file", "m.sql", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Body map[string]interface{} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
+		t.Fatalf("decode: %v\n%s", err, stdout.String())
+	}
+	if env.API[0].Body["sql"] != "SELECT 42 AS answer;\n" {
+		t.Fatalf("body.sql = %v, want file content", env.API[0].Body["sql"])
+	}
+}
+
+// ============================================================================
+// legacy wire 形态测试 —— BOE server 实测返这种 ["rows-json-string", ...]
+// 形态而非 spec 里的 [{sql_type, data, ...}]，CLI 端必须兼容。
+// 输入用 BOE 真实抓包数据（test_scripts/boe_e2e/run.log）。
+// ============================================================================
+
+func TestAppsDBExecute_LegacyWireSingleSelect(t *testing.T) {
+	// BOE 实测：SELECT 1 AS x  →  result: "[\"[{\\\"x\\\":1}]\"]"
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `["[{\"x\":1}]"]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "SELECT 1 AS x", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "x") {
+		t.Errorf("missing header 'x':\n%s", got)
+	}
+	if !strings.Contains(got, "1") {
+		t.Errorf("missing value row '1':\n%s", got)
+	}
+	// 不应回退到 RAW
+	if strings.Contains(got, "RAW") || strings.Contains(got, "[\\\"") {
+		t.Errorf("should not fall back to RAW or raw-string passthrough:\n%s", got)
+	}
+}
+
+func TestAppsDBExecute_LegacyWireSingleSelectJSONEnvelope(t *testing.T) {
+	// 验证 JSON envelope 也把 legacy result 正确归一化进 data.results
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `["[{\"x\":1}]"]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "SELECT 1 AS x", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	var env struct {
+		Data struct {
+			Results []map[string]interface{} `json:"results"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("decode: %v\n%s", err, stdout.String())
+	}
+	if len(env.Data.Results) != 1 {
+		t.Fatalf("results length = %d, want 1; got: %v", len(env.Data.Results), env.Data.Results)
+	}
+	if env.Data.Results[0]["sql_type"] != "SELECT" {
+		t.Fatalf("results[0].sql_type = %v, want SELECT", env.Data.Results[0]["sql_type"])
+	}
+	if env.Data.Results[0]["record_count"] != float64(1) {
+		t.Fatalf("results[0].record_count = %v, want 1", env.Data.Results[0]["record_count"])
+	}
+}
+
+func TestAppsDBExecute_LegacyWireMultiSelect(t *testing.T) {
+	// BOE 实测：SELECT 1; SELECT 2  →  result: "[\"[{\\\"?column?\\\":1}]\",\"[{\\\"?column?\\\":2}]\"]"
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `["[{\"?column?\":1}]","[{\"?column?\":2}]"]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "SELECT 1; SELECT 2;", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	// 多语句应有 Statement N: header
+	if !strings.Contains(got, "Statement 1: SELECT") || !strings.Contains(got, "Statement 2: SELECT") {
+		t.Errorf("missing Statement headers:\n%s", got)
+	}
+	// 末尾应有 ✓ N statements executed
+	if !strings.Contains(got, "✓ 2 statements executed") {
+		t.Errorf("missing summary line:\n%s", got)
+	}
+}
+
+func TestAppsDBExecute_LegacyWireDDLEmptyResult(t *testing.T) {
+	// BOE 实测：CREATE TABLE  →  result: "" （空字符串，无 rows）
+	// 老 wire 不区分 DDL/DML/无返回，统一标 "ok"
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": ``, // 空字符串
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "CREATE TABLE foo (id INT)", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	// result="" 触发 parseSQLResult 返 nil → renderSQLPretty 输出 "(empty result)"
+	if !strings.Contains(got, "(empty result)") {
+		t.Errorf("expected '(empty result)' for empty result string, got:\n%s", got)
+	}
+}
+
+func TestAppsDBExecute_LegacyWireMultiSelectWithRealTable(t *testing.T) {
+	// BOE 实测真实表抓包（course 表第一行）：复杂 JSON 含 CJK / timestamp / uuid 字段
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `["[{\"id\":\"abc-123\",\"title\":\"高效沟通\",\"capacity\":30}]"]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "SELECT id,title,capacity FROM course LIMIT 1", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	// 验证 CJK / uuid / int 都能正确显示在表格里
+	for _, want := range []string{"id", "title", "capacity", "abc-123", "高效沟通", "30"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing %q in pretty output:\n%s", want, got)
+		}
+	}
+}
+
+// pretty 单 SELECT：表格输出，列间两空格，无 Statement header。
+func TestAppsDBExecute_PrettySingleSelectTable(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[{"sql_type":"SELECT","data":"[{\"id\":101,\"total_cents\":2500},{\"id\":102,\"total_cents\":1800}]","record_count":2}]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "select", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if strings.Contains(got, "Statement 1:") {
+		t.Errorf("single statement pretty should NOT have Statement header\noutput:\n%s", got)
+	}
+	// 列按字典序排序：id / total_cents
+	if !strings.Contains(got, "id   total_cents") {
+		t.Errorf("missing header row\noutput:\n%s", got)
+	}
+	if !strings.Contains(got, "101  2500") || !strings.Contains(got, "102  1800") {
+		t.Errorf("missing data rows\noutput:\n%s", got)
+	}
+}
+
+func TestAppsDBExecute_PrettyEmptySelect(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[{"sql_type":"SELECT","data":"[]","record_count":0}]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "select", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "(0 rows)") {
+		t.Fatalf("empty SELECT should print (0 rows), got:\n%s", stdout.String())
+	}
+}
+
+func TestAppsDBExecute_PrettySingleDMLAndDDL(t *testing.T) {
+	cases := []struct {
+		name    string
+		result  string
+		wantStr string
+	}{
+		{"INSERT_1_row", `[{"sql_type":"INSERT","data":"","affected_rows":1}]`, "✓ 1 row inserted"},
+		{"UPDATE_5_rows", `[{"sql_type":"UPDATE","data":"","affected_rows":5}]`, "✓ 5 rows updated"},
+		{"DELETE_0_rows", `[{"sql_type":"DELETE","data":"","affected_rows":0}]`, "✓ 0 rows deleted"},
+		{"DDL", `[{"sql_type":"DDL","data":"","affected_rows":0}]`, "✓ DDL executed"},
+		// 真机 boe 实测：DDL 的 sql_type 是细粒度动词（CREATE_TABLE / DROP_TABLE / ALTER_TABLE...），
+		// data 是 "[]"、无 affected_rows。必须识别为 DDL，而不是落到 dmlSummary 渲染成 "0 rows affected"。
+		{"CREATE_TABLE", `[{"sql_type":"CREATE_TABLE","data":"[]"}]`, "✓ DDL executed"},
+		{"DROP_TABLE", `[{"sql_type":"DROP_TABLE","data":"[]"}]`, "✓ DDL executed"},
+		{"ALTER_TABLE", `[{"sql_type":"ALTER_TABLE","data":"[]"}]`, "✓ DDL executed"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			factory, stdout, reg := newAppsExecuteFactory(t)
+			reg.Register(&httpmock.Stub{
+				Method: "POST",
+				URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+				Body:   map[string]interface{}{"code": 0, "data": map[string]interface{}{"result": c.result}},
+			})
+			if err := runAppsShortcut(t, AppsDBExecute,
+				[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "x", "--format", "pretty", "--as", "user"},
+				factory, stdout); err != nil {
+				t.Fatalf("execute err=%v", err)
+			}
+			if !strings.Contains(stdout.String(), c.wantStr) {
+				t.Errorf("want %q\ngot:\n%s", c.wantStr, stdout.String())
+			}
+		})
+	}
+}
+
+func TestAppsDBExecute_PrettyMultiStatementsAllSuccess(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[` +
+					`{"sql_type":"INSERT","data":"","affected_rows":1},` +
+					`{"sql_type":"UPDATE","data":"","affected_rows":1},` +
+					`{"sql_type":"SELECT","data":"[{\"id\":999}]","record_count":1}` +
+					`]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "x", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, line := range []string{
+		"Statement 1: ✓ 1 row inserted",
+		"Statement 2: ✓ 1 row updated",
+		"Statement 3: SELECT (1 row)",
+		"✓ 3 statements executed",
+	} {
+		if !strings.Contains(got, line) {
+			t.Errorf("missing %q in pretty output\nfull:\n%s", line, got)
+		}
+	}
+}
+
+// TestAppsDBExecute_PrettyMultiStatementsDDL 钉住真机 boe 多语句 DDL 的 wire：
+// CREATE_TABLE / DROP_TABLE（data="[]"、无 affected_rows）须渲染成 "✓ DDL executed"，
+// 不能落到 dmlSummary 变成 "0 rows affected"。
+func TestAppsDBExecute_PrettyMultiStatementsDDL(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[{"sql_type":"CREATE_TABLE","data":"[]"},{"sql_type":"DROP_TABLE","data":"[]"}]`,
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "x", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, line := range []string{
+		"Statement 1: ✓ DDL executed",
+		"Statement 2: ✓ DDL executed",
+		"✓ 2 statements executed",
+	} {
+		if !strings.Contains(got, line) {
+			t.Errorf("missing %q in pretty output\nfull:\n%s", line, got)
+		}
+	}
+	if strings.Contains(got, "rows affected") {
+		t.Errorf("DDL must not render as 'rows affected'\nfull:\n%s", got)
+	}
+}
+
+func TestAppsDBExecute_PrettyMultiStatementsPartialFailureWithErrorSentinel(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[` +
+					`{"sql_type":"INSERT","data":"","affected_rows":1},` +
+					`{"sql_type":"ERROR","data":"{\"code\":1300015,\"message\":\"syntax error at or near 'SELEC'\"}"}` +
+					`]`,
+			},
+		},
+	})
+	// pretty 失败路径：逐条 ✓/✗ 摘要照打到 stdout（人看），同时返回 typed error（exit 非 0）。
+	err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "x", "--format", "pretty", "--as", "user"},
+		factory, stdout)
+	if err == nil {
+		t.Fatalf("pretty multi-statement failure must still return a typed error; stdout:\n%s", stdout.String())
+	}
+	got := stdout.String()
+	for _, line := range []string{
+		"Statement 1: ✓ 1 row inserted",
+		"Statement 2: ✗ syntax error at or near 'SELEC' [1300015]",
+	} {
+		if !strings.Contains(got, line) {
+			t.Errorf("missing %q in pretty output\nfull:\n%s", line, got)
+		}
+	}
+	// DBA 模式（transactional=false）前序语句已 auto-commit 落地，绝不能误报「rolled back」。
+	if strings.Contains(got, "rolled back") {
+		t.Errorf("DBA mode must NOT claim rollback (prior statements persisted); got:\n%s", got)
+	}
+	if strings.Contains(got, "statements executed") {
+		t.Errorf("failed run should NOT print success summary; got:\n%s", got)
+	}
+}
+
+// TestAppsDBExecute_MultiStatementFailureReturnsTypedError 钉死「多语句失败 → partial failure」：
+// 逐条结果 + statement_index / error_code / rolled_back / note 作为 ok:false 数据落 stdout，
+// 退出信号是 PartialFailureError（非零 exit）。rolled_back=false 因 CLI 永远 DBA 模式
+// （真机 boe 实证：失败前的语句已落地）。
+func TestAppsDBExecute_MultiStatementFailureReturnsTypedError(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[` +
+					`{"sql_type":"INSERT","data":"","affected_rows":1},` +
+					`{"sql_type":"ERROR","data":"{\"code\":\"k_dl_1300002\",\"message\":\"duplicate key value violates unique constraint\"}"}` +
+					`]`,
+			},
+		},
+	})
+	err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "x", "--as", "user"},
+		factory, stdout)
+	if err == nil {
+		t.Fatalf("multi-statement failure must return a partial-failure error; stdout:\n%s", stdout.String())
+	}
+	// json 失败路径不得打成功 envelope。
+	if strings.Contains(stdout.String(), `"ok": true`) {
+		t.Errorf("must not emit ok:true success envelope on failure; stdout:\n%s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("want *output.PartialFailureError, got %T: %v", err, err)
+	}
+	if pfErr.Code != output.ExitAPI {
+		t.Errorf("exit = %d, want %d (ExitAPI)", pfErr.Code, output.ExitAPI)
+	}
+	payload := decodePartialFailureData(t, stdout.String())
+	if got := payload["statement_index"]; got != float64(1) {
+		t.Errorf("statement_index = %v, want 1", got)
+	}
+	if got := payload["error_code"]; got != float64(1300002) {
+		t.Errorf("error_code = %v, want 1300002", got)
+	}
+	msg, _ := payload["error_message"].(string)
+	if !strings.Contains(msg, "(at statement 2 of 2)") {
+		t.Errorf("error_message missing statement locator: %q", msg)
+	}
+	if got := payload["rolled_back"]; got != false {
+		t.Errorf("rolled_back = %v, want false (DBA mode persists prior statements)", got)
+	}
+	results, _ := payload["results"].([]interface{})
+	if len(results) != 2 {
+		t.Errorf("results length = %d, want 2 (persisted statement + ERROR sentinel)", len(results))
+	}
+	note, _ := payload["note"].(string)
+	if !strings.Contains(note, "already applied") {
+		t.Errorf("note should warn prior statements persisted, got %q", note)
+	}
+}
+
+// decodePartialFailureData 解析 stdout 上 ok:false 的 partial-failure envelope，返回 data 块。
+func decodePartialFailureData(t *testing.T, stdoutStr string) map[string]interface{} {
+	t.Helper()
+	var envelope struct {
+		OK   bool                   `json:"ok"`
+		Data map[string]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(stdoutStr), &envelope); err != nil {
+		t.Fatalf("stdout is not a JSON envelope: %v\n%s", err, stdoutStr)
+	}
+	if envelope.OK {
+		t.Fatalf("envelope.ok = true, want false on partial failure")
+	}
+	if envelope.Data == nil {
+		t.Fatalf("envelope.data missing; stdout:\n%s", stdoutStr)
+	}
+	return envelope.Data
+}
+
+// TestAppsDBExecute_SingleErrorReturnsTypedError 单条语句失败（server 也返 code:0 + ERROR 哨兵）
+// 同样走 partial failure：statement_index=0、note 说明无语句落地、message 标注 (at statement 1 of 1)。
+func TestAppsDBExecute_SingleErrorReturnsTypedError(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[{"sql_type":"ERROR","data":"{\"code\":\"k_dl_000002\",\"message\":\"syntax error at or near 'SELEC'\"}"}]`,
+			},
+		},
+	})
+	err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "x", "--as", "user"},
+		factory, stdout)
+	if err == nil {
+		t.Fatalf("single ERROR sentinel must return a partial-failure error; stdout:\n%s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("want *output.PartialFailureError, got %T: %v", err, err)
+	}
+	payload := decodePartialFailureData(t, stdout.String())
+	msg, _ := payload["error_message"].(string)
+	if !strings.Contains(msg, "(at statement 1 of 1)") {
+		t.Errorf("error_message missing locator: %q", msg)
+	}
+	if got := payload["statement_index"]; got != float64(0) {
+		t.Errorf("statement_index = %v, want 0", got)
+	}
+	note, _ := payload["note"].(string)
+	if !strings.Contains(note, "no statements were applied") {
+		t.Errorf("note should say nothing was applied, got %q", note)
+	}
+}
+
+func TestCellString_AllKinds(t *testing.T) {
+	cases := []struct {
+		name string
+		in   interface{}
+		want string
+	}{
+		{"nil", nil, ""},
+		{"string", "hello", "hello"},
+		{"bool true", true, "true"},
+		{"bool false", false, "false"},
+		{"int float", float64(101), "101"},
+		{"fractional", float64(1.25), "1.25"},
+		{"object", map[string]interface{}{"a": float64(1)}, `{"a":1}`},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := cellString(c.in); got != c.want {
+				t.Errorf("cellString(%v)=%q want %q", c.in, got, c.want)
+			}
+		})
+	}
+}
+
+func TestCodeString_Forms(t *testing.T) {
+	cases := []struct {
+		name string
+		in   interface{}
+		want string
+	}{
+		{"nil", nil, ""},
+		{"k_dl prefix", "k_dl_1300015", "1300015"},
+		{"plain string", "1300015", "1300015"},
+		{"float64", float64(42), "42"},
+		{"unsupported", []int{1}, ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := codeString(c.in); got != c.want {
+				t.Errorf("codeString(%v)=%q want %q", c.in, got, c.want)
+			}
+		})
+	}
+}
+
+func TestDmlVerb_AllVerbs(t *testing.T) {
+	cases := map[string]string{
+		"INSERT":       "inserted",
+		"update":       "updated",
+		"DELETE":       "deleted",
+		"Merge":        "merged",
+		"CREATE_TABLE": "affected",
+	}
+	for in, want := range cases {
+		if got := dmlVerb(in); got != want {
+			t.Errorf("dmlVerb(%q)=%q want %q", in, got, want)
+		}
+	}
+}
+
+func TestIntOrZero_Cases(t *testing.T) {
+	if got := intOrZero(float64(5)); got != 5 {
+		t.Errorf("intOrZero(5)=%d want 5", got)
+	}
+	if got := intOrZero("x"); got != 0 {
+		t.Errorf("intOrZero(non-numeric)=%d want 0", got)
+	}
+	if got := intOrZero(nil); got != 0 {
+		t.Errorf("intOrZero(nil)=%d want 0", got)
+	}
+}
+
+func TestErrorSummary_Cases(t *testing.T) {
+	cases := []struct {
+		name, in, want string
+	}{
+		{"empty", "", "(unknown error)"},
+		{"malformed json", "not json", "not json"},
+		{"with code", `{"code":"k_dl_1300015","message":"boom"}`, "boom [1300015]"},
+		{"no code", `{"message":"plain"}`, "plain"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := errorSummary(c.in); got != c.want {
+				t.Errorf("errorSummary(%q)=%q want %q", c.in, got, c.want)
+			}
+		})
+	}
+}
+
+func TestParseErrorSentinel_Cases(t *testing.T) {
+	cases := []struct {
+		name, in string
+		wantCode int
+		wantMsg  string
+	}{
+		{"empty", "", 0, "(unknown error)"},
+		{"malformed", "xyz", 0, "xyz"},
+		{"code+msg", `{"code":"1300015","message":"boom"}`, 1300015, "boom"},
+		{"empty msg", `{"code":"1300015","message":""}`, 1300015, "(unknown error)"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			code, msg := parseErrorSentinel(c.in)
+			if code != c.wantCode || msg != c.wantMsg {
+				t.Errorf("parseErrorSentinel(%q)=%d,%q want %d,%q", c.in, code, msg, c.wantCode, c.wantMsg)
+			}
+		})
+	}
+}
+
+func TestIsStructuredResult_Cases(t *testing.T) {
+	if !isStructuredResult([]map[string]interface{}{{"sql_type": "SELECT"}}) {
+		t.Error("expected structured=true when sql_type present")
+	}
+	if isStructuredResult([]map[string]interface{}{{}}) {
+		t.Error("expected structured=false when sql_type absent")
+	}
+	if isStructuredResult(nil) {
+		t.Error("expected structured=false for empty")
+	}
+}
+
+func TestNormalizeLegacyStatement_Cases(t *testing.T) {
+	t.Run("empty -> OK", func(t *testing.T) {
+		got := normalizeLegacyStatement("")
+		if got["sql_type"] != "OK" {
+			t.Errorf("got sql_type=%v want OK", got["sql_type"])
+		}
+	})
+	t.Run("null -> OK", func(t *testing.T) {
+		got := normalizeLegacyStatement("null")
+		if got["sql_type"] != "OK" {
+			t.Errorf("got sql_type=%v want OK", got["sql_type"])
+		}
+	})
+	t.Run("rows -> SELECT", func(t *testing.T) {
+		got := normalizeLegacyStatement(`[{"id":1}]`)
+		if got["sql_type"] != "SELECT" {
+			t.Errorf("got sql_type=%v want SELECT", got["sql_type"])
+		}
+		if got["record_count"] != float64(1) {
+			t.Errorf("got record_count=%v want 1", got["record_count"])
+		}
+	})
+	t.Run("non-json kept as OK", func(t *testing.T) {
+		got := normalizeLegacyStatement(`notjson`)
+		if got["sql_type"] != "OK" {
+			t.Errorf("got sql_type=%v want OK", got["sql_type"])
+		}
+	})
+}
+
+func TestCellString_MarshalFallback(t *testing.T) {
+	// complex128 is not switch-handled and json.Marshal rejects it →
+	// falls back to fmt.Sprintf("%v", v), which is deterministic for complex.
+	if got := cellString(complex(1, 2)); got != "(1+2i)" {
+		t.Errorf("cellString(complex)=%q want (1+2i)", got)
+	}
+}
+
+func TestRenderSingleStatementPretty_Branches(t *testing.T) {
+	cases := []struct {
+		name   string
+		stmt   map[string]interface{}
+		substr string
+	}{
+		{"select empty", map[string]interface{}{"sql_type": "SELECT", "data": "[]"}, "(0 rows)"},
+		{"error", map[string]interface{}{"sql_type": "ERROR", "data": `{"message":"boom"}`}, "✗ boom"},
+		{"dml insert", map[string]interface{}{"sql_type": "INSERT", "affected_rows": float64(3)}, "✓ 3 rows inserted"},
+		{"legacy ok", map[string]interface{}{"sql_type": "OK"}, "✓ ok"},
+		{"ddl default", map[string]interface{}{"sql_type": "CREATE_TABLE"}, "✓ DDL executed"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			var b strings.Builder
+			renderSingleStatementPretty(&b, c.stmt)
+			if !strings.Contains(b.String(), c.substr) {
+				t.Errorf("output %q does not contain %q", b.String(), c.substr)
+			}
+		})
+	}
+}
+
+func TestRenderSelectRowsAsTable_Branches(t *testing.T) {
+	cases := []struct {
+		name   string
+		data   string
+		substr string
+	}{
+		{"empty string", "", "(0 rows)"},
+		{"empty array", "[]", "(0 rows)"},
+		{"malformed fallback", "{bad", "{bad"},
+		{"rows", `[{"id":1}]`, "id"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			var b strings.Builder
+			renderSelectRowsAsTable(&b, c.data)
+			if !strings.Contains(b.String(), c.substr) {
+				t.Errorf("output %q does not contain %q", b.String(), c.substr)
+			}
+		})
+	}
+}
+
+// TestAppsDBExecute_PrettyPartialFailureKeepsStdoutHumanOnly pins the pretty
+// contract on a statement failure: stdout carries only the per-statement
+// human summary (no JSON envelope stacked after it), and the command still
+// exits non-zero via the partial-failure signal.
+func TestAppsDBExecute_PrettyPartialFailureKeepsStdoutHumanOnly(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/spark/v1/apps/app_x/sql_commands",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"result": `[{"sql_type":"ERROR","data":"{\"code\":\"k_dl_000002\",\"message\":\"syntax error\"}"}]`,
+			},
+		},
+	})
+	err := runAppsShortcut(t, AppsDBExecute,
+		[]string{"+db-execute", "--yes", "--app-id", "app_x", "--sql", "x", "--format", "pretty", "--as", "user"},
+		factory, stdout)
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("want *output.PartialFailureError, got %T: %v", err, err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "✗") {
+		t.Fatalf("pretty summary missing failure marker; stdout:\n%s", out)
+	}
+	if strings.Contains(out, `"ok"`) {
+		t.Fatalf("pretty stdout must not stack a JSON envelope after the summary; stdout:\n%s", out)
+	}
+}

shortcuts/apps/apps_db_table_get.go

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const dbTableGetHint = "verify --app-id and --table are correct; list tables with `lark-cli apps +db-table-list --app-id <app_id>`; if targeting --env dev, create it first with `lark-cli apps +db-env-create --app-id <app_id> --env dev`"
+
+// AppsDBTableGet gets one table's structure (动词对齐 +db-table-list)。
+//
+// GET /apps/{app_id}/tables/{table_name}。
+//
+// `--format` 同时驱动 CLI 渲染和 server 请求形态：
+//   - `--format json`（默认）/ table / ndjson / csv：CLI 不传 format query，response 含结构化
+//     columns / indexes / constraints / stats，envelope 化输出。
+//   - `--format pretty`：CLI 给 server 带 ?format=ddl，response 含 ddl 字符串，stdout 直接打
+//     ddl 内容（无 envelope / 无表格包装）。
+var AppsDBTableGet = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-table-get",
+	Description: "Get a table's structure: columns, indexes and constraints",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +db-table-get --app-id <app_id> --table <table>",
+		"Tip: filter fields with --jq (json format), e.g. -q '.data.columns[].name'",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "table", Desc: "table name", Required: true},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
+			return err
+		}
+		if strings.TrimSpace(rctx.Str("table")) == "" {
+			return appsValidationParamError("--table", "--table is required")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appTablePath(appID, strings.TrimSpace(rctx.Str("table")))).
+			Desc("Get Miaoda app db table schema").
+			Params(buildDBTableGetParams(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		path := appTablePath(appID, strings.TrimSpace(rctx.Str("table")))
+		data, err := rctx.CallAPITyped("GET", path, buildDBTableGetParams(rctx), nil)
+		if err != nil {
+			return withAppsHint(err, dbTableGetHint)
+		}
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			// pretty 模式：stdout 直接打 ddl 文本（无 trailing newline，由 server 返回的字符串决定）。
+			io.WriteString(w, common.GetString(data, "ddl"))
+		})
+		return nil
+	},
+}
+
+// buildDBTableGetParams 构造 schema 接口的 query。
+//
+// CLI 检测 rctx.Format == "pretty" 时给 server 带 format=ddl，要求返 CREATE 语句文本；
+// 其他 format（含默认 json）不传该参数，让 server 返默认结构化字段。
+func buildDBTableGetParams(rctx *common.RuntimeContext) map[string]interface{} {
+	params := map[string]interface{}{"env": rctx.Str("env")}
+	if rctx.Format == "pretty" {
+		params["format"] = "ddl"
+	}
+	return params
+}

shortcuts/apps/apps_db_table_get_test.go

@@ -0,0 +1,131 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestAppsDBTableGet_DefaultJSONReturnsStructuredFields(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_x/tables/orders",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"name":        "orders",
+				"description": "订单表",
+				"columns": []interface{}{
+					map[string]interface{}{
+						"name": "id", "data_type": "int8",
+						"is_primary_key": true, "is_unique": true,
+						"is_allow_null": false, "default_value": "",
+					},
+				},
+				"indexes": []interface{}{
+					map[string]interface{}{"name": "orders_pkey", "type": "btree", "columns": []interface{}{"id"}, "definition": "..."},
+				},
+				"constraints": []interface{}{
+					map[string]interface{}{"type": "primary_key", "name": "orders_pkey", "columns": []interface{}{"id"}},
+				},
+				"estimated_row_count": 1200,
+				"size_bytes":          81920,
+			},
+		},
+	})
+
+	if err := runAppsShortcut(t, AppsDBTableGet,
+		[]string{"+db-table-get", "--app-id", "app_x", "--table", "orders", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if got := stdout.String(); !strings.Contains(got, `"name": "orders"`) {
+		t.Fatalf("stdout missing schema name: %s", got)
+	}
+}
+
+// --format pretty 是触发 DDL 模式的唯一开关。
+// 用 --format json + --dry-run 走 JSON envelope 路径方便 parse，但 query 形态由代码内部
+// 根据 rctx.Format 决定 —— 这里我们直接传 --format pretty + --dry-run，pretty 模式下 dry-run
+// 输出是 plain text 列表，用 substring 校验 format=ddl 出现在 URL query 中。
+func TestAppsDBTableGet_PrettyFormatSendsFormatDDLQuery(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBTableGet,
+		[]string{"+db-table-get", "--app-id", "app_x", "--table", "orders", "--format", "pretty", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "/open-apis/spark/v1/apps/app_x/tables/orders") {
+		t.Fatalf("missing URL in dry-run output:\n%s", got)
+	}
+	if !strings.Contains(got, "format=ddl") {
+		t.Fatalf("--format=pretty should trigger ?format=ddl, got:\n%s", got)
+	}
+}
+
+func TestAppsDBTableGet_NonPrettyFormatsOmitFormatQuery(t *testing.T) {
+	// 默认 json / table / ndjson / csv 都走 schema 路径 —— CLI 不传 format query。
+	for _, format := range []string{"json", "table", "ndjson", "csv"} {
+		t.Run(format, func(t *testing.T) {
+			factory, stdout, _ := newAppsExecuteFactory(t)
+			args := []string{"+db-table-get", "--app-id", "app_x", "--table", "orders", "--format", format, "--dry-run", "--as", "user"}
+			if err := runAppsShortcut(t, AppsDBTableGet, args, factory, stdout); err != nil {
+				t.Fatalf("dry-run err=%v", err)
+			}
+			var env struct {
+				API []struct {
+					Params map[string]interface{} `json:"params"`
+				} `json:"api"`
+			}
+			if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
+				t.Fatalf("decode: %v", err)
+			}
+			if _, ok := env.API[0].Params["format"]; ok {
+				t.Fatalf("--format=%s should omit format query, got %v", format, env.API[0].Params)
+			}
+		})
+	}
+}
+
+func TestAppsDBTableGet_PrettyOutputIsDDLTextOnly(t *testing.T) {
+	// pretty 模式 stdout 直接打 ddl 字段文本，无 envelope / 表格包装。
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	ddl := "CREATE TABLE orders (\n  id bigint NOT NULL,\n  PRIMARY KEY (id)\n);"
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_x/tables/orders",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"ddl": ddl},
+		},
+	})
+
+	if err := runAppsShortcut(t, AppsDBTableGet,
+		[]string{"+db-table-get", "--app-id", "app_x", "--table", "orders", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, "CREATE TABLE orders") {
+		t.Fatalf("pretty output should contain raw DDL, got:\n%s", got)
+	}
+	if strings.Contains(got, `"data":`) || strings.Contains(got, `"ddl":`) {
+		t.Fatalf("pretty output should not be JSON envelope, got:\n%s", got)
+	}
+}
+
+func TestAppsDBTableGet_RequiresTable(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBTableGet,
+		[]string{"+db-table-get", "--app-id", "app_x", "--as", "user"}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "table") {
+		t.Fatalf("expected table required error, got %v", err)
+	}
+}

shortcuts/apps/apps_db_table_list.go

@@ -0,0 +1,301 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const dbTableListHint = "verify --app-id is correct; if targeting --env dev, create it first with `lark-cli apps +db-env-create --app-id <app_id> --env dev`"
+
+// AppsDBTableList lists tables in a Miaoda app's database.
+//
+// GET /apps/{app_id}/tables（cursor 分页），response items[] 含 estimated_row_count /
+// size_bytes optional 字段，默认返回，不必额外传 query。
+//
+// 输出裁剪：server 给每张表回完整 columns[]（与 +db-table-get 同源、内容一致）。CLI 用白名单
+// 投影（dbTableListItem）只组装产品要求字段、把 columns[] 折算成 column_count，避免逐表重复列定义
+// 放大 token、并与 +db-table-get 职责区分。完整列定义 / 索引 / 约束 / DDL 用 +db-table-get。
+//
+// pretty 渲染 5 列：name / description / estimated_row_count / size / columns（即 column_count）；
+// 列间两空格、列对齐填充、空 description 用 "—" 占位、size 按 KB/MB/GB 友好格式化。
+var AppsDBTableList = common.Shortcut{
+	Service:     appsService,
+	Command:     "+db-table-list",
+	Description: "List tables in a Miaoda app database (cursor pagination)",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +db-table-list --app-id <app_id>",
+		"Tip: filter fields with --jq, e.g. -q '.data.items[].name'",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
+		{Name: "page-token", Desc: "pagination cursor from previous response"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appTablesPath(appID)).
+			Desc("List Miaoda app db tables").
+			Params(buildDBTableListParams(rctx))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("GET", appTablesPath(appID), buildDBTableListParams(rctx), nil)
+		if err != nil {
+			return withAppsHint(err, dbTableListHint)
+		}
+		// 白名单投影：只把产品要求的字段组装进 dbTableListItem，替换 server 原始 items[]。
+		// server 给每张表回完整 columns[]（与 +db-table-get 同源、逐字节一致），在 list 里逐表
+		// 重复既放大 token 又与 schema 职责重叠。这里用白名单而非 delete 黑名单 —— server 后续新增
+		// 字段不会自动泄漏进 CLI 输出。需要完整列定义 / 索引 / 约束 / DDL 用 +db-table-get。
+		items := projectTableListItems(data["items"])
+		data["items"] = items
+		rctx.OutFormat(data, nil, func(w io.Writer) {
+			renderTableListPretty(w, items)
+		})
+		return nil
+	},
+}
+
+// dbTableListItem 是 +db-table-list 对外输出的「产品要求字段」白名单。
+// 改字段在此处增删即可，无需在 Execute 里逐个 delete server 返回的多余字段。
+type dbTableListItem struct {
+	Name              string      `json:"name"`
+	Description       string      `json:"description"`
+	EstimatedRowCount interface{} `json:"estimated_row_count,omitempty"`
+	SizeBytes         interface{} `json:"size_bytes,omitempty"`
+	ColumnCount       int         `json:"column_count"`
+}
+
+// projectTableListItems 把 server 原始 items[]（map）投影成白名单 dbTableListItem 切片。
+// column_count 由 server 返回的 columns[] 长度派生（随后 columns[] 不再透出）。
+func projectTableListItems(raw interface{}) []dbTableListItem {
+	arr, _ := raw.([]interface{})
+	out := make([]dbTableListItem, 0, len(arr))
+	for _, it := range arr {
+		m, ok := it.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		out = append(out, dbTableListItem{
+			Name:              common.GetString(m, "name"),
+			Description:       common.GetString(m, "description"),
+			EstimatedRowCount: m["estimated_row_count"],
+			SizeBytes:         m["size_bytes"],
+			ColumnCount:       deriveColumnCount(m),
+		})
+	}
+	return out
+}
+
+func buildDBTableListParams(rctx *common.RuntimeContext) map[string]interface{} {
+	params := map[string]interface{}{
+		"env":       rctx.Str("env"),
+		"page_size": rctx.Int("page-size"),
+	}
+	if token := strings.TrimSpace(rctx.Str("page-token")); token != "" {
+		params["page_token"] = token
+	}
+	return params
+}
+
+// renderTableListPretty 5 列输出，列间两空格、列对齐填充。
+//
+// 列名：name / description / estimated_row_count / size / columns。
+// 空 description 用 "—" 占位；size 由 size_bytes 经 humanBytes 友好格式化；
+// columns 列取白名单投影的 column_count。
+func renderTableListPretty(w io.Writer, items []dbTableListItem) {
+	headers := []string{"name", "description", "estimated_row_count", "size", "columns"}
+	rows := make([][]string, 0, len(items))
+	for _, item := range items {
+		desc := item.Description
+		if desc == "" {
+			desc = "—"
+		}
+		rows = append(rows, []string{
+			item.Name,
+			desc,
+			intString(item.EstimatedRowCount),
+			humanBytes(item.SizeBytes),
+			fmt.Sprintf("%d", item.ColumnCount),
+		})
+	}
+	renderAlignedTable(w, headers, rows)
+}
+
+// renderAlignedTable 输出列对齐表格：列间两空格、列宽按每列最长 cell 填充、
+// 不画 `|` 和 `-` 分隔线、不依赖 TTY 着色。
+func renderAlignedTable(w io.Writer, headers []string, rows [][]string) {
+	if len(headers) == 0 {
+		return
+	}
+	widths := make([]int, len(headers))
+	for i, h := range headers {
+		widths[i] = displayWidth(h)
+	}
+	for _, row := range rows {
+		for i, cell := range row {
+			if i >= len(widths) {
+				break
+			}
+			if dw := displayWidth(cell); dw > widths[i] {
+				widths[i] = dw
+			}
+		}
+	}
+	writeRow := func(cells []string) {
+		for i, cell := range cells {
+			if i >= len(widths) {
+				continue
+			}
+			if i > 0 {
+				io.WriteString(w, "  ")
+			}
+			io.WriteString(w, cell)
+			if i < len(widths)-1 {
+				pad := widths[i] - displayWidth(cell)
+				if pad > 0 {
+					io.WriteString(w, strings.Repeat(" ", pad))
+				}
+			}
+		}
+		io.WriteString(w, "\n")
+	}
+	writeRow(headers)
+	for _, r := range rows {
+		writeRow(r)
+	}
+}
+
+// displayWidth 估算字符串在 monospace 终端下的显示宽度。
+// ASCII 占 1 列；CJK / 全角字符占 2 列；其他多字节字符按 rune 数算（保守）。
+func displayWidth(s string) int {
+	w := 0
+	for _, r := range s {
+		switch {
+		case r < 0x80:
+			w++
+		case isWide(r):
+			w += 2
+		default:
+			w++
+		}
+	}
+	return w
+}
+
+func isWide(r rune) bool {
+	switch {
+	case r >= 0x1100 && r <= 0x115F: // Hangul Jamo
+	case r >= 0x2E80 && r <= 0x303E: // CJK Radicals / Kangxi
+	case r >= 0x3041 && r <= 0x33FF: // Hiragana / Katakana / Bopomofo / CJK Symbols
+	case r >= 0x3400 && r <= 0x4DBF: // CJK Extension A
+	case r >= 0x4E00 && r <= 0x9FFF: // CJK Unified Ideographs
+	case r >= 0xA000 && r <= 0xA4CF: // Yi
+	case r >= 0xAC00 && r <= 0xD7A3: // Hangul Syllables
+	case r >= 0xF900 && r <= 0xFAFF: // CJK Compatibility Ideographs
+	case r >= 0xFE30 && r <= 0xFE4F: // CJK Compatibility Forms
+	case r >= 0xFF00 && r <= 0xFF60: // Fullwidth Forms
+	case r >= 0xFFE0 && r <= 0xFFE6: // Fullwidth Signs
+	case r >= 0x20000 && r <= 0x2FFFD: // CJK Extension B-F
+	case r >= 0x30000 && r <= 0x3FFFD: // CJK Extension G
+	default:
+		return false
+	}
+	return true
+}
+
+// humanBytes 把 size_bytes 数值转 KB / MB / GB 友好字符串。
+// 1 KiB = 1024 B；与 PG / 操作系统约定一致。
+func humanBytes(raw interface{}) string {
+	n, ok := numericAsFloat(raw)
+	if !ok {
+		return "—"
+	}
+	const unit = 1024.0
+	switch {
+	case n < unit:
+		return fmt.Sprintf("%d B", int64(n))
+	case n < unit*unit:
+		return fmt.Sprintf("%.0f KB", n/unit)
+	case n < unit*unit*unit:
+		return formatFloat(n/(unit*unit)) + " MB"
+	default:
+		return formatFloat(n/(unit*unit*unit)) + " GB"
+	}
+}
+
+// formatFloat 一位小数；整数值省略小数（24 KB 而不是 24.0 KB；1.5 MB 而不是 1 MB）。
+func formatFloat(f float64) string {
+	if f == float64(int64(f)) {
+		return fmt.Sprintf("%d", int64(f))
+	}
+	return fmt.Sprintf("%.1f", f)
+}
+
+// intString 把 JSON 反序列化进来的 number 转为整数字符串显示（estimated_row_count）。
+func intString(raw interface{}) string {
+	if n, ok := numericAsFloat(raw); ok {
+		return fmt.Sprintf("%d", int64(n))
+	}
+	return "—"
+}
+
+func numericAsFloat(raw interface{}) (float64, bool) {
+	switch v := raw.(type) {
+	case float64:
+		return v, true
+	case float32:
+		return float64(v), true
+	case int:
+		return float64(v), true
+	case int32:
+		return float64(v), true
+	case int64:
+		return float64(v), true
+	case uint:
+		return float64(v), true
+	case uint32:
+		return float64(v), true
+	case uint64:
+		return float64(v), true
+	case json.Number:
+		f, err := v.Float64()
+		if err != nil {
+			return 0, false
+		}
+		return f, true
+	case nil:
+		return 0, false
+	}
+	return 0, false
+}
+
+// deriveColumnCount 从 items[i].columns 数组长度派生 column_count。
+func deriveColumnCount(m map[string]interface{}) int {
+	cols, ok := m["columns"].([]interface{})
+	if !ok {
+		return 0
+	}
+	return len(cols)
+}

shortcuts/apps/apps_db_table_list_test.go

@@ -0,0 +1,309 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+// TestAppsDBTableList_BusinessErrorSurfacedAsTypedEnvelope 验证 server 业务错误
+// （code != 0，如单环境 app 查 env=dev 返 "Invalid DB Branch"）被 CLI 透出成
+// typed error —— 用 BOE 实测的错误码 / 文案做输入。
+//
+// 迁移到 runtime.CallAPITyped 后，非零 code 的业务错误由 errclass.BuildAPIError
+// 归类为 typed errs.* error（wire type 为 "api" 类别，不再是 legacy 的
+// *output.ExitError / "api_error"），但仍保留 code 与 message。与 drive/okr 等
+// 已迁移域一致：用 errs.ProblemOf 读 typed envelope，断言不弱化。
+func TestAppsDBTableList_BusinessErrorSurfacedAsTypedEnvelope(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_x/tables",
+		Body: map[string]interface{}{
+			"code": 500002511,
+			"msg":  "k_dl_1600000：Invalid DB Branch：dev",
+		},
+	})
+
+	err := runAppsShortcut(t, AppsDBTableList,
+		[]string{"+db-table-list", "--app-id", "app_x", "--env", "dev", "--as", "user"},
+		factory, stdout)
+	if err == nil {
+		t.Fatalf("expected business error to surface, got nil; stdout=%s", stdout.String())
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected a typed errs.Problem, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryAPI {
+		t.Fatalf("error.type = %q, want %q", p.Category, errs.CategoryAPI)
+	}
+	if p.Code != 500002511 {
+		t.Fatalf("error.code = %d, want 500002511", p.Code)
+	}
+	if !strings.Contains(p.Message, "Invalid DB Branch") {
+		t.Fatalf("error.message missing 'Invalid DB Branch': %q", p.Message)
+	}
+}
+
+func TestAppsDBTableList_SuccessReturnsItemsWithStats(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_x/tables",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"has_more":   false,
+				"page_token": "",
+				"items": []interface{}{
+					map[string]interface{}{
+						"name":                "orders",
+						"description":         "订单表",
+						"columns":             []interface{}{map[string]interface{}{"name": "id"}, map[string]interface{}{"name": "user_id"}},
+						"estimated_row_count": 1200,
+						"size_bytes":          81920,
+					},
+				},
+			},
+		},
+	})
+
+	if err := runAppsShortcut(t, AppsDBTableList,
+		[]string{"+db-table-list", "--app-id", "app_x", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	if !strings.Contains(got, `"name": "orders"`) {
+		t.Fatalf("stdout missing table name: %s", got)
+	}
+	if !strings.Contains(got, `"estimated_row_count": 1200`) {
+		t.Fatalf("stdout missing estimated_row_count: %s", got)
+	}
+	// CLI 裁剪：json 默认不透出每表 columns[]，折算成 column_count（mock 给了 2 列）。
+	if !strings.Contains(got, `"column_count": 2`) {
+		t.Fatalf("stdout missing column_count (should replace columns[]): %s", got)
+	}
+	if strings.Contains(got, `"columns"`) {
+		t.Fatalf("stdout should NOT contain raw columns[] (stripped to column_count): %s", got)
+	}
+}
+
+// pretty 5 列 + 列名 (size / columns，不是 size_bytes / column_count) + size 友好格式（KB） +
+// 空 description 用 "—" 占位。
+func TestAppsDBTableList_PrettyRendersFiveColumnsHumanReadable(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/spark/v1/apps/app_x/tables",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{
+						"name":                "orders",
+						"description":         "Order entries",
+						"columns":             []interface{}{map[string]interface{}{"name": "id"}, map[string]interface{}{"name": "user_id"}},
+						"estimated_row_count": 1200,
+						"size_bytes":          81920, // 80 KB
+					},
+					map[string]interface{}{
+						"name":                "customers",
+						"description":         "",
+						"columns":             []interface{}{map[string]interface{}{"name": "id"}},
+						"estimated_row_count": 350,
+						"size_bytes":          24576, // 24 KB
+					},
+				},
+			},
+		},
+	})
+	if err := runAppsShortcut(t, AppsDBTableList,
+		[]string{"+db-table-list", "--app-id", "app_x", "--format", "pretty", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	// Header 行 5 列命名。
+	wantHeader := "name       description    estimated_row_count  size   columns"
+	// rows
+	wantOrders := "orders     Order entries  1200                 80 KB  2"
+	wantCustomers := "customers  —              350                  24 KB  1"
+	for _, want := range []string{wantHeader, wantOrders, wantCustomers} {
+		if !strings.Contains(got, want) {
+			t.Errorf("missing line %q\nactual output:\n%s", want, got)
+		}
+	}
+	// 禁止出现旧列名 / 原始字节。
+	for _, banned := range []string{"size_bytes", "column_count", "81920", "24576"} {
+		if strings.Contains(got, banned) {
+			t.Errorf("pretty output contains %q (must be human-formatted)\noutput:\n%s", banned, got)
+		}
+	}
+}
+
+func TestAppsDBTableList_RequiresAppID(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBTableList,
+		[]string{"+db-table-list", "--app-id", "  ", "--as", "user"}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "app-id") {
+		t.Fatalf("expected app-id required error, got %v", err)
+	}
+}
+
+func TestAppsDBTableList_DryRunSendsPaginationAndEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBTableList,
+		[]string{"+db-table-list", "--app-id", "app_x", "--env", "dev",
+			"--page-size", "50", "--page-token", "cursor-abc",
+			"--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
+		t.Fatalf("decode dry-run: %v\n%s", err, stdout.String())
+	}
+	if env.API[0].Method != "GET" || env.API[0].URL != "/open-apis/spark/v1/apps/app_x/tables" {
+		t.Fatalf("dry-run method/url = %s %s", env.API[0].Method, env.API[0].URL)
+	}
+	if env.API[0].Params["env"] != "dev" {
+		t.Fatalf("dry-run params.env = %v (want dev)", env.API[0].Params["env"])
+	}
+	if pz, _ := env.API[0].Params["page_size"].(float64); int(pz) != 50 {
+		t.Fatalf("dry-run params.page_size = %v (want 50)", env.API[0].Params["page_size"])
+	}
+	if env.API[0].Params["page_token"] != "cursor-abc" {
+		t.Fatalf("dry-run params.page_token = %v (want cursor-abc)", env.API[0].Params["page_token"])
+	}
+}
+
+func TestAppsDBTableList_DoesNotSendIncludeStatsQuery(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsDBTableList,
+		[]string{"+db-table-list", "--app-id", "app_x", "--dry-run", "--as", "user"},
+		factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	var env struct {
+		API []struct {
+			Params map[string]interface{} `json:"params"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal([]byte(stdout.String()), &env); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if _, ok := env.API[0].Params["include_stats"]; ok {
+		t.Fatalf("CLI should not send include_stats query, but got params=%v", env.API[0].Params)
+	}
+}
+
+func TestAppsDBTableList_RejectsBadEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	err := runAppsShortcut(t, AppsDBTableList,
+		[]string{"+db-table-list", "--app-id", "app_x", "--env", "prod", "--as", "user"}, factory, stdout)
+	if err == nil || !strings.Contains(err.Error(), "env") {
+		t.Fatalf("expected env enum rejection, got %v", err)
+	}
+}
+
+func TestNumericAsFloat_AllTypes(t *testing.T) {
+	cases := []struct {
+		name string
+		in   interface{}
+		want float64
+		ok   bool
+	}{
+		{"float64", float64(3.5), 3.5, true},
+		{"float32", float32(2), 2, true},
+		{"int", int(7), 7, true},
+		{"int32", int32(8), 8, true},
+		{"int64", int64(9), 9, true},
+		{"uint", uint(10), 10, true},
+		{"uint32", uint32(11), 11, true},
+		{"uint64", uint64(12), 12, true},
+		{"json.Number valid", json.Number("13.5"), 13.5, true},
+		{"json.Number invalid", json.Number("abc"), 0, false},
+		{"nil", nil, 0, false},
+		{"unsupported string", "x", 0, false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got, ok := numericAsFloat(c.in)
+			if ok != c.ok || got != c.want {
+				t.Fatalf("numericAsFloat(%v) = %v,%v want %v,%v", c.in, got, ok, c.want, c.ok)
+			}
+		})
+	}
+}
+
+func TestFormatFloat_IntegerVsFractional(t *testing.T) {
+	cases := []struct {
+		in   float64
+		want string
+	}{
+		{24, "24"},
+		{1.5, "1.5"},
+		{2.04, "2.0"},
+		{0, "0"},
+	}
+	for _, c := range cases {
+		if got := formatFloat(c.in); got != c.want {
+			t.Errorf("formatFloat(%v)=%q want %q", c.in, got, c.want)
+		}
+	}
+}
+
+func TestHumanBytes_UnitBoundaries(t *testing.T) {
+	cases := []struct {
+		name string
+		in   interface{}
+		want string
+	}{
+		{"non-numeric", "x", "—"},
+		{"bytes", float64(512), "512 B"},
+		{"kb", float64(2048), "2 KB"},
+		{"mb fractional", float64(1572864), "1.5 MB"},
+		{"gb integer", float64(2 * 1024 * 1024 * 1024), "2 GB"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := humanBytes(c.in); got != c.want {
+				t.Errorf("humanBytes(%v)=%q want %q", c.in, got, c.want)
+			}
+		})
+	}
+}
+
+func TestIntString_Cases(t *testing.T) {
+	if got := intString(float64(42)); got != "42" {
+		t.Errorf("intString(42)=%q want 42", got)
+	}
+	if got := intString("x"); got != "—" {
+		t.Errorf("intString(non-numeric)=%q want —", got)
+	}
+}
+
+func TestDeriveColumnCount_Cases(t *testing.T) {
+	if got := deriveColumnCount(map[string]interface{}{"columns": []interface{}{1, 2, 3}}); got != 3 {
+		t.Errorf("deriveColumnCount=%d want 3", got)
+	}
+	if got := deriveColumnCount(map[string]interface{}{}); got != 0 {
+		t.Errorf("deriveColumnCount(missing)=%d want 0", got)
+	}
+	if got := deriveColumnCount(map[string]interface{}{"columns": "notarray"}); got != 0 {
+		t.Errorf("deriveColumnCount(wrongtype)=%d want 0", got)
+	}
+}

shortcuts/apps/apps_env_pull.go

@@ -0,0 +1,380 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// envKeyPattern matches valid environment variable names: [A-Za-z_][A-Za-z0-9_]*
+var envKeyPattern = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+
+type envPullDatabaseInfo struct {
+	Detected      bool
+	ExpiresAtRaw  string
+	ExpiresAtText string
+}
+
+// AppsEnvPull pulls startup env vars for an app into the local .env.local file.
+var AppsEnvPull = common.Shortcut{
+	Service:     appsService,
+	Command:     "+env-pull",
+	Description: "Pull app startup env vars into the local project .env.local",
+	Risk:        "write",
+	Tips: []string{
+		"Example: lark-cli apps +env-pull --app-id <app_id>",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "app ID"},
+		{Name: "project-path", Desc: "local project root path (defaults to current directory)"},
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		if strings.TrimSpace(rctx.Str("app-id")) == "" {
+			return appsValidationParamError("--app-id", "--app-id is required")
+		}
+		_, envFile, err := resolveEnvPullTarget(strings.TrimSpace(rctx.Str("project-path")))
+		if err != nil {
+			return appsValidationParamError("--project-path", "--project-path: %v", err).WithCause(err)
+		}
+		if err := checkEnvPullTarget(envFile); err != nil {
+			return err
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		projectPath, envFile, _ := resolveEnvPullTarget(strings.TrimSpace(rctx.Str("project-path")))
+		appID := strings.TrimSpace(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(fmt.Sprintf("%s/apps/%s/env_vars", apiBasePath, validate.EncodePathSegment(appID))).
+			Desc("Pull app startup env vars into the local .env.local file").
+			Set("project_path", projectPath).
+			Set("env_file", envFile)
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID := strings.TrimSpace(rctx.Str("app-id"))
+		_, envFile, err := resolveEnvPullTarget(strings.TrimSpace(rctx.Str("project-path")))
+		if err != nil {
+			return appsValidationParamError("--project-path", "--project-path: %v", err).WithCause(err)
+		}
+		if err := checkEnvPullTarget(envFile); err != nil {
+			return err
+		}
+		if err := rctx.EnsureScopes([]string{"spark:app:read"}); err != nil {
+			return err
+		}
+
+		path := fmt.Sprintf("%s/apps/%s/env_vars", apiBasePath, validate.EncodePathSegment(appID))
+		data, err := rctx.CallAPITyped("POST", path, nil, nil)
+		if err != nil {
+			return withAppsHint(err, "verify --app-id is correct and you have access to the app; list your apps with `lark-cli apps +list`")
+		}
+
+		envVars, databaseInfo, skippedKeys, err := extractEnvPullVars(data)
+		if err != nil {
+			return err
+		}
+		if envVars == nil {
+			envVars = map[string]string{}
+		}
+		envVars["FORCE_DB_BRANCH"] = "dev"
+		original, err := readEnvPullFile(envFile)
+		if err != nil {
+			return err
+		}
+		merged, updated, created := mergeEnvPullFileContent(original, envVars)
+		if err := ensureEnvPullParentDir(envFile); err != nil {
+			return err
+		}
+		if err := validate.AtomicWrite(envFile, []byte(merged), 0o600); err != nil {
+			return &errs.InternalError{Problem: errs.Problem{Category: errs.CategoryInternal, Subtype: errs.SubtypeUnknown, Message: fmt.Sprintf("cannot write %s: %v", envFile, err)}, Cause: err}
+		}
+
+		result := buildEnvPullSuccessData(appID, envFile, databaseInfo)
+		rctx.OutFormat(result, nil, func(w io.Writer) {
+			writeEnvPullPretty(w, appID, envFile, databaseInfo, skippedKeys)
+		})
+		_ = updated
+		_ = created
+		return nil
+	},
+}
+
+func resolveEnvPullTarget(projectPath string) (string, string, error) {
+	if strings.TrimSpace(projectPath) == "" {
+		cwd, err := os.Getwd() //nolint:forbidigo // shortcuts cannot import internal/vfs; cwd lookup is local-only and bounded.
+		if err != nil {
+			return "", "", errs.NewInternalError(errs.SubtypeUnknown, "cannot determine working directory: %v", err).WithCause(err)
+		}
+		projectPath = cwd
+	}
+	if err := validate.RejectControlChars(projectPath, "--project-path"); err != nil {
+		return "", "", err
+	}
+	projectPath = filepath.Clean(projectPath)
+	return projectPath, filepath.Join(projectPath, ".env.local"), nil
+}
+
+func checkEnvPullTarget(envFile string) error {
+	info, err := os.Lstat(envFile) //nolint:forbidigo // shortcuts cannot import internal/vfs; direct lstat is needed to reject symlinks before write.
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return appsValidationParamError("--project-path", "cannot inspect %s: %v", envFile, err).WithCause(err)
+	}
+	if info.Mode()&os.ModeSymlink != 0 {
+		return appsValidationParamError("--project-path", "target %s must be a regular file, not a symlink", envFile)
+	}
+	if !info.Mode().IsRegular() {
+		return appsValidationParamError("--project-path", "target %s must be a regular file", envFile)
+	}
+	return nil
+}
+
+func extractEnvPullVars(data map[string]interface{}) (map[string]string, envPullDatabaseInfo, []string, error) {
+	raw := data["env_vars"]
+	if raw == nil {
+		if nested, ok := data["data"].(map[string]interface{}); ok {
+			raw = nested["env_vars"]
+		}
+	}
+	if raw == nil {
+		return nil, envPullDatabaseInfo{}, nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "response field env_vars must be an object or array of key/value entries")
+	}
+
+	var skippedKeys []string
+	switch typed := raw.(type) {
+	case map[string]interface{}:
+		out := make(map[string]string, len(typed))
+		for key, value := range typed {
+			if !envKeyPattern.MatchString(key) {
+				skippedKeys = append(skippedKeys, key)
+				continue
+			}
+			s, ok := value.(string)
+			if !ok {
+				continue
+			}
+			out[key] = s
+		}
+		return out, envPullDatabaseInfo{Detected: hasEnvPullDatabase(out)}, skippedKeys, nil
+	case []interface{}:
+		out := make(map[string]string, len(typed))
+		info := envPullDatabaseInfo{}
+		for _, item := range typed {
+			entry, ok := item.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			key, ok := entry["key"].(string)
+			if !ok || strings.TrimSpace(key) == "" {
+				continue
+			}
+			if !envKeyPattern.MatchString(key) {
+				skippedKeys = append(skippedKeys, key)
+				continue
+			}
+			value, ok := entry["value"].(string)
+			if !ok {
+				continue
+			}
+			out[key] = value
+			if key == "SUDA_DATABASE_URL" {
+				info.Detected = true
+				info.ExpiresAtRaw, info.ExpiresAtText = extractEnvPullDatabaseExpiry(entry["extras"])
+			}
+		}
+		return out, info, skippedKeys, nil
+	default:
+		return nil, envPullDatabaseInfo{}, nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "response field env_vars must be an object or array of key/value entries")
+	}
+}
+
+func readEnvPullFile(envFile string) (string, error) {
+	data, err := os.ReadFile(envFile) //nolint:forbidigo // shortcuts cannot import internal/vfs; validated local file read for a single env file.
+	if err != nil {
+		if os.IsNotExist(err) {
+			return "", nil
+		}
+		return "", &errs.InternalError{Problem: errs.Problem{Category: errs.CategoryInternal, Subtype: errs.SubtypeUnknown, Message: fmt.Sprintf("cannot read %s: %v", envFile, err)}, Cause: err}
+	}
+	return string(data), nil
+}
+
+func ensureEnvPullParentDir(envFile string) error {
+	dir := filepath.Dir(envFile)
+	if err := os.MkdirAll(dir, 0o755); err != nil { //nolint:forbidigo // shortcuts cannot import internal/vfs; local mkdir for target env parent dir.
+		return &errs.InternalError{Problem: errs.Problem{Category: errs.CategoryInternal, Subtype: errs.SubtypeUnknown, Message: fmt.Sprintf("cannot create %s: %v", dir, err)}, Cause: err}
+	}
+	return nil
+}
+
+func mergeEnvPullFileContent(original string, envVars map[string]string) (string, []string, []string) {
+	if len(envVars) == 0 {
+		if original == "" {
+			return "", nil, nil
+		}
+		return ensureTrailingNewline(original), nil, nil
+	}
+
+	normalized := strings.ReplaceAll(original, "\r\n", "\n")
+	lines := []string{}
+	if normalized != "" {
+		lines = strings.Split(normalized, "\n")
+		if len(lines) > 0 && lines[len(lines)-1] == "" {
+			lines = lines[:len(lines)-1]
+		}
+	}
+
+	used := make(map[string]bool, len(envVars))
+	updated := make([]string, 0, len(envVars))
+	for i, line := range lines {
+		key, ok := parseEnvPullAssignmentLine(line)
+		if !ok {
+			continue
+		}
+		value, exists := envVars[key]
+		if !exists {
+			continue
+		}
+		lines[i] = formatEnvPullAssignment(key, value)
+		updated = append(updated, key)
+		used[key] = true
+	}
+
+	created := make([]string, 0, len(envVars))
+	pending := make([]string, 0, len(envVars))
+	for key := range envVars {
+		if used[key] {
+			continue
+		}
+		pending = append(pending, key)
+	}
+	sort.Strings(pending)
+	for _, key := range pending {
+		lines = append(lines, formatEnvPullAssignment(key, envVars[key]))
+		created = append(created, key)
+	}
+
+	sort.Strings(updated)
+	content := strings.Join(lines, "\n")
+	if content != "" {
+		content += "\n"
+	}
+	return content, updated, created
+}
+
+func parseEnvPullAssignmentLine(line string) (string, bool) {
+	trimmed := strings.TrimSpace(line)
+	if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+		return "", false
+	}
+	if strings.HasPrefix(trimmed, "export ") || strings.HasPrefix(trimmed, "export\t") {
+		remainder := strings.TrimSpace(strings.TrimPrefix(strings.TrimPrefix(trimmed, "export "), "export\t"))
+		if remainder == "" || strings.HasPrefix(remainder, "=") {
+			return "", false
+		}
+		trimmed = remainder
+	}
+	idx := strings.Index(trimmed, "=")
+	if idx <= 0 {
+		return "", false
+	}
+	key := strings.TrimSpace(trimmed[:idx])
+	if key == "" || strings.ContainsAny(key, " \t") {
+		return "", false
+	}
+	return key, true
+}
+
+func formatEnvPullAssignment(key, value string) string {
+	return fmt.Sprintf("%s=%s", key, strconv.Quote(value))
+}
+
+func buildEnvPullSuccessData(appID, envFile string, databaseInfo envPullDatabaseInfo) map[string]interface{} {
+	result := map[string]interface{}{
+		"app_id":   appID,
+		"env_file": envFile,
+	}
+	if databaseInfo.ExpiresAtRaw != "" {
+		result["database_url_expires_at"] = databaseInfo.ExpiresAtRaw
+	}
+	return result
+}
+
+func hasEnvPullDatabase(envVars map[string]string) bool {
+	_, ok := envVars["SUDA_DATABASE_URL"]
+	return ok
+}
+
+func extractEnvPullDatabaseExpiry(rawExtras interface{}) (string, string) {
+	extras, ok := rawExtras.([]interface{})
+	if !ok {
+		return "", ""
+	}
+	for _, raw := range extras {
+		entry, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		key, _ := entry["key"].(string)
+		if key != "expiresAt" {
+			continue
+		}
+		switch value := entry["value"].(type) {
+		case string:
+			rawValue := strings.TrimSpace(value)
+			ts, err := strconv.ParseInt(rawValue, 10, 64)
+			if err != nil {
+				return "", ""
+			}
+			return rawValue, time.Unix(ts, 0).Local().Format("2006-01-02 15:04:05 MST")
+		case float64:
+			ts := int64(value)
+			rawValue := strconv.FormatInt(ts, 10)
+			return rawValue, time.Unix(ts, 0).Local().Format("2006-01-02 15:04:05 MST")
+		}
+	}
+	return "", ""
+}
+
+func writeEnvPullPretty(w io.Writer, appID, envFile string, databaseInfo envPullDatabaseInfo, skippedKeys []string) {
+	fmt.Fprintf(w, "✓ App detected: %s\n", appID)
+	if databaseInfo.Detected {
+		fmt.Fprintln(w, "✓ Development database detected")
+	}
+	fmt.Fprintf(w, "✓ Local environment written to %s\n", envFile)
+	if databaseInfo.ExpiresAtText != "" {
+		fmt.Fprintln(w)
+		fmt.Fprintf(w, "DATABASE_URL is valid until %s.\n", databaseInfo.ExpiresAtText)
+	}
+	if len(skippedKeys) > 0 {
+		fmt.Fprintln(w)
+		fmt.Fprintf(w, "⚠ Skipped %d invalid key(s): %s (key names must match [A-Za-z_][A-Za-z0-9_]*)\n", len(skippedKeys), strings.Join(skippedKeys, ", "))
+	}
+	fmt.Fprintf(w, "Run `lark-cli apps +env-pull --app-id <app_id>` again to refresh it.\n")
+}
+
+func ensureTrailingNewline(s string) string {
+	if s == "" || strings.HasSuffix(s, "\n") {
+		return s
+	}
+	return s + "\n"
+}

shortcuts/apps/apps_errors.go

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"errors"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/client"
+)
+
+func appsValidationError(format string, args ...any) *errs.ValidationError {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...)
+}
+
+func appsValidationParamError(param, format string, args ...any) *errs.ValidationError {
+	return appsValidationError(format, args...).WithParam(param)
+}
+
+func appsInvalidParam(name, reason string) errs.InvalidParam {
+	return errs.InvalidParam{Name: name, Reason: reason}
+}
+
+func appsFailedPreconditionParamError(param, format string, args ...any) *errs.ValidationError {
+	return errs.NewValidationError(errs.SubtypeFailedPrecondition, format, args...).WithParam(param)
+}
+
+func appsFailedPreconditionError(format string, args ...any) *errs.ValidationError {
+	return errs.NewValidationError(errs.SubtypeFailedPrecondition, format, args...)
+}
+
+// appsStorageError classifies a local credential/state storage failure
+// (read, write, delete, list) as internal/storage.
+func appsStorageError(err error, format string, args ...any) *errs.InternalError {
+	return errs.NewInternalError(errs.SubtypeStorage, format, args...).WithCause(err)
+}
+
+// appsExternalToolError classifies a runtime failure of an external tool the
+// CLI shells out to (git, npx) as internal/external_tool. The tool output is
+// carried in the message; recovery guidance goes in the hint.
+func appsExternalToolError(err error, format string, args ...any) *errs.InternalError {
+	return errs.NewInternalError(errs.SubtypeExternalTool, format, args...).WithCause(err)
+}
+
+// appsSubprocessEnvelopeError classifies a malformed or failed envelope from a
+// lark-cli subprocess (+git-credential-init / +env-pull) as internal/invalid_response.
+func appsSubprocessEnvelopeError(format string, args ...any) *errs.InternalError {
+	return errs.NewInternalError(errs.SubtypeInvalidResponse, format, args...)
+}
+
+func appsInputPathError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, fileio.ErrPathValidation) {
+		return appsValidationParamError("--path", "unsafe --path: %s", err).WithCause(err)
+	}
+	return appsValidationParamError("--path", "cannot read --path: %s", err).WithCause(err)
+}
+
+func appsInputPathEntryError(path string, err error) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, fileio.ErrPathValidation) {
+		return appsValidationParamError("--path", "unsafe --path entry %s: %s", path, err).WithCause(err)
+	}
+	return appsValidationParamError("--path", "cannot read --path entry %s: %s", path, err).WithCause(err)
+}
+
+func appsFileIOError(err error, format string, args ...any) *errs.InternalError {
+	return errs.NewInternalError(errs.SubtypeFileIO, format, args...).WithCause(err)
+}
+
+// enrichHTMLPublishAPIError adapts a typed failure from the HTML publish
+// endpoint: refines endpoint-scoped business codes, prefixes the message with
+// command context, and attaches endpoint-specific recovery hints. A
+// still-untyped error is lifted at the SDK boundary instead.
+func enrichHTMLPublishAPIError(err error) error {
+	if err == nil {
+		return nil
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		return client.WrapDoAPIError(err)
+	}
+	// The HTML publish business codes (90001/90002) are scoped to this
+	// endpoint, not service-global, so their subtype classification lives
+	// here instead of the global errclass code table. Only an
+	// otherwise-unclassified API error is refined; a stronger upstream
+	// classification is never overridden.
+	if p.Category == errs.CategoryAPI && p.Subtype == errs.SubtypeUnknown && p.Code == errCodeAppNotFound {
+		p.Subtype = errs.SubtypeNotFound
+	}
+	if p.Message != "" {
+		p.Message = "html-publish failed: " + p.Message
+	}
+	if hint := buildHTMLPublishFailureHint(p.Code); hint != "" {
+		p.Hint = hint
+	}
+	return err
+}

shortcuts/apps/apps_errors_test.go

@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+)
+
+func TestAppsInputPathError_ClassifiesPathValidation(t *testing.T) {
+	cause := errors.New("path escapes working directory")
+	err := appsInputPathError(&fileio.PathValidationError{Err: cause})
+
+	problem := requireAppsValidationProblem(t, err)
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if !strings.Contains(problem.Message, "unsafe --path") {
+		t.Fatalf("message = %q, want unsafe --path context", problem.Message)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) || validationErr.Param != "--path" {
+		t.Fatalf("param = %q, want --path", validationErr.Param)
+	}
+	if !errors.Is(err, fileio.ErrPathValidation) || !errors.Is(err, cause) {
+		t.Fatalf("path validation cause chain not preserved: %v", err)
+	}
+}
+
+func TestAppsInputPathEntryError_ClassifiesReadFailure(t *testing.T) {
+	cause := errors.New("permission denied")
+	err := appsInputPathEntryError("dist/index.html", cause)
+
+	problem := requireAppsValidationProblem(t, err)
+	if !strings.Contains(problem.Message, "cannot read --path entry dist/index.html") {
+		t.Fatalf("message = %q, want entry read context", problem.Message)
+	}
+	if !errors.Is(err, cause) {
+		t.Fatalf("cause chain not preserved: %v", err)
+	}
+}
+
+func TestAppsFileIOError_ClassifiesInternalFileIO(t *testing.T) {
+	cause := errors.New("archive writer failed")
+	err := appsFileIOError(cause, "pack failed: %v", cause)
+
+	problem := requireAppsProblem(t, err, errs.CategoryInternal)
+	if problem.Subtype != errs.SubtypeFileIO {
+		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeFileIO)
+	}
+	if !errors.Is(err, cause) {
+		t.Fatalf("cause chain not preserved: %v", err)
+	}
+}
+
+func TestEnrichHTMLPublishAPIError_LiftsUntypedBoundaryError(t *testing.T) {
+	err := enrichHTMLPublishAPIError(errors.New("connection reset by peer"))
+
+	problem := requireAppsProblem(t, err, errs.CategoryNetwork)
+	if problem.Subtype != errs.SubtypeNetworkTransport {
+		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeNetworkTransport)
+	}
+}
+
+func TestEnrichHTMLPublishAPIError_PreservesClassificationAndAddsHint(t *testing.T) {
+	err := errs.NewAPIError(errs.SubtypeUnknown, "build failed").
+		WithCode(errCodeBuildFailed).
+		WithLogID("logid-build-failed")
+
+	got := enrichHTMLPublishAPIError(err)
+	if got != err {
+		t.Fatalf("typed error should be enriched in place")
+	}
+	problem := requireAppsAPIProblem(t, got)
+	if problem.Subtype != errs.SubtypeUnknown {
+		t.Fatalf("subtype = %q, want %q unchanged", problem.Subtype, errs.SubtypeUnknown)
+	}
+	if problem.Code != errCodeBuildFailed {
+		t.Fatalf("code = %d, want %d", problem.Code, errCodeBuildFailed)
+	}
+	if problem.LogID != "logid-build-failed" {
+		t.Fatalf("log_id = %q, want preserved", problem.LogID)
+	}
+	if !strings.Contains(problem.Message, "html-publish failed") {
+		t.Fatalf("message = %q, want html-publish context", problem.Message)
+	}
+	if problem.Hint == "" {
+		t.Fatalf("expected known-code recovery hint")
+	}
+}
+
+func TestEnrichHTMLPublishAPIError_ClassifiesAppNotFoundLocally(t *testing.T) {
+	err := errs.NewAPIError(errs.SubtypeUnknown, "app not found").WithCode(errCodeAppNotFound)
+
+	problem := requireAppsAPIProblem(t, enrichHTMLPublishAPIError(err))
+	if problem.Subtype != errs.SubtypeNotFound {
+		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeNotFound)
+	}
+}
+
+func TestEnrichHTMLPublishAPIError_KeepsStrongerClassification(t *testing.T) {
+	err := errs.NewAPIError(errs.SubtypeRateLimit, "throttled").WithCode(errCodeAppNotFound)
+
+	problem := requireAppsAPIProblem(t, enrichHTMLPublishAPIError(err))
+	if problem.Subtype != errs.SubtypeRateLimit {
+		t.Fatalf("subtype = %q, want %q unchanged", problem.Subtype, errs.SubtypeRateLimit)
+	}
+}

shortcuts/apps/apps_examples_test.go

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"regexp"
+	"strings"
+	"testing"
+)
+
+func TestAppsShortcutsHaveExamples(t *testing.T) {
+	realAppID := regexp.MustCompile(`app_[a-z0-9]{6,}`)
+	email := regexp.MustCompile(`[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}`)
+	phone := regexp.MustCompile(`\b1[3-9]\d{9}\b`)
+	for _, s := range Shortcuts() {
+		hasExample := false
+		for _, tip := range s.Tips {
+			if strings.HasPrefix(tip, "Example: lark-cli apps +") {
+				hasExample = true
+			}
+			if realAppID.MatchString(tip) {
+				t.Errorf("%s tip leaks real-looking app id (use <app_id>): %q", s.Command, tip)
+			}
+			if email.MatchString(tip) || phone.MatchString(tip) {
+				t.Errorf("%s tip leaks PII: %q", s.Command, tip)
+			}
+		}
+		if !hasExample {
+			t.Errorf("%s has no \"Example: lark-cli apps +...\" tip", s.Command)
+		}
+	}
+}
+
+func TestHighFreqCommandsHaveMultipleExamples(t *testing.T) {
+	want := map[string]int{"+chat": 2, "+access-scope-set": 2}
+	for _, s := range Shortcuts() {
+		min, ok := want[s.Command]
+		if !ok {
+			continue
+		}
+		n := 0
+		for _, tip := range s.Tips {
+			if strings.HasPrefix(tip, "Example: lark-cli apps +") {
+				n++
+			}
+		}
+		if n < min {
+			t.Errorf("%s has %d Example tips, want >= %d", s.Command, n, min)
+		}
+	}
+}

shortcuts/apps/apps_hint_leak_test.go

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"regexp"
+	"testing"
+)
+
+// TestAppsErrorHintsCarryNoSecretsOrPII guards the actionable error hints added
+// for the apps command-governance task. Those hints are inline string literals
+// spread across several files (apps_env_pull.go, apps_access_scope_set.go,
+// apps_access_scope_get.go, apps_init.go git-push path, and the
+// gitCredentialIssueHint const in git_credential.go). They are stable English
+// strings, so we assert the verbatim copies here: a real app_id, an email, or a
+// phone number must never appear in a hint. Placeholders like <app_id> are
+// expected and must NOT trip the real-app-id regex.
+func TestAppsErrorHintsCarryNoSecretsOrPII(t *testing.T) {
+	// These are copied verbatim from the source. If a hint changes, copy the new
+	// text here so this leak guard keeps tracking the real production string.
+	hints := []string{
+		// apps_env_pull.go:86 and apps_access_scope_get.go:50 (identical literals)
+		"verify --app-id is correct and you have access to the app; list your apps with `lark-cli apps +list`",
+		// apps_access_scope_set.go:74
+		"verify --app-id is correct; for scope=specific, each --targets id must be a valid open_id/department_id/chat_id and --approver a valid open_id; review the current scope with `lark-cli apps +access-scope-get --app-id <app_id>`",
+		// apps_init.go:483 (git push rejection)
+		"the push was rejected — the git output is in the message above; if it is a non-fast-forward (remote has new commits), sync the remote and retry; if it is an auth failure, make sure `lark-cli apps +git-credential-init` has succeeded",
+		// git_credential.go gitCredentialIssueHint const (referenced directly so a
+		// rename or text change breaks the build instead of silently drifting)
+		gitCredentialIssueHint,
+		// command-governance hints added for this task (referenced by const, no drift)
+		appIDListHint,
+		sessionStopHint,
+		createHint,
+		dbEnvCreateHint,
+		dbTableGetHint,
+		dbTableListHint,
+	}
+
+	realAppID := regexp.MustCompile(`app_[a-z0-9]{6,}`)
+	email := regexp.MustCompile(`[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}`)
+	phone := regexp.MustCompile(`\b1[3-9]\d{9}\b`)
+	// An obvious secret: a PAT-like token or a "secret=..." / "token=..." pair.
+	secret := regexp.MustCompile(`(?i)(pat-[a-z0-9]+|secret\s*[=:]\s*\S|token\s*[=:]\s*\S)`)
+
+	for _, h := range hints {
+		if realAppID.MatchString(h) {
+			t.Errorf("hint leaks a real-looking app id (use <app_id>): %q", h)
+		}
+		if email.MatchString(h) {
+			t.Errorf("hint leaks an email address: %q", h)
+		}
+		if phone.MatchString(h) {
+			t.Errorf("hint leaks a phone number: %q", h)
+		}
+		if secret.MatchString(h) {
+			t.Errorf("hint leaks an obvious secret/token: %q", h)
+		}
+	}
+
+	// Sanity: the placeholder <app_id> must NOT match the real-app-id regex,
+	// otherwise the guard above would be a false positive on legitimate hints.
+	if realAppID.MatchString("<app_id>") {
+		t.Fatal("realAppID regex incorrectly matches the <app_id> placeholder")
+	}
+}

shortcuts/apps/apps_hints_more_test.go

@@ -0,0 +1,129 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func assertHintContains(t *testing.T, sc common.Shortcut, args []string, stub *httpmock.Stub, want string) {
+	t.Helper()
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(stub)
+	err := runAppsShortcut(t, sc, args, factory, stdout)
+	if err == nil {
+		t.Fatalf("expected failure, got nil; stdout=%s", stdout.String())
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed errs.Problem, got %T: %v", err, err)
+	}
+	if !strings.Contains(p.Hint, want) {
+		t.Fatalf("hint %q does not contain %q", p.Hint, want)
+	}
+}
+
+func TestAppsSessionCreate_4xxFailureCarriesListHint(t *testing.T) {
+	assertHintContains(t, AppsSessionCreate,
+		[]string{"+session-create", "--app-id", "app_x", "--as", "user"},
+		&httpmock.Stub{Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/sessions",
+			Status: http.StatusNotFound, Body: map[string]interface{}{"msg": "app not found"}},
+		"apps +list")
+}
+
+func TestAppsSessionList_4xxFailureCarriesListHint(t *testing.T) {
+	assertHintContains(t, AppsSessionList,
+		[]string{"+session-list", "--app-id", "app_x", "--as", "user"},
+		&httpmock.Stub{Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/sessions",
+			Status: http.StatusForbidden, Body: map[string]interface{}{"msg": "permission denied"}},
+		"apps +list")
+}
+
+func TestAppsUpdate_4xxFailureCarriesListHint(t *testing.T) {
+	assertHintContains(t, AppsUpdate,
+		[]string{"+update", "--app-id", "app_x", "--name", "n", "--as", "user"},
+		&httpmock.Stub{Method: "PATCH", URL: "/open-apis/spark/v1/apps/app_x",
+			Status: http.StatusNotFound, Body: map[string]interface{}{"msg": "app not found"}},
+		"apps +list")
+}
+
+func TestAppsReleaseList_4xxFailureCarriesListHint(t *testing.T) {
+	assertHintContains(t, AppsReleaseList,
+		[]string{"+release-list", "--app-id", "app_x", "--as", "user"},
+		&httpmock.Stub{Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/releases",
+			Status: http.StatusForbidden, Body: map[string]interface{}{"msg": "permission denied"}},
+		"apps +list")
+}
+
+func TestAppsSessionStop_4xxFailureCarriesSessionHint(t *testing.T) {
+	assertHintContains(t, AppsSessionStop,
+		[]string{"+session-stop", "--app-id", "app_x", "--session-id", "s1", "--turn-id", "t1", "--as", "user"},
+		&httpmock.Stub{Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/sessions/s1/stop",
+			Status: http.StatusNotFound, Body: map[string]interface{}{"msg": "session not found"}},
+		"+session-list")
+}
+
+func TestAppsCreate_4xxFailureCarriesTypeHint(t *testing.T) {
+	assertHintContains(t, AppsCreate,
+		[]string{"+create", "--name", "n", "--app-type", "html", "--as", "user"},
+		&httpmock.Stub{Method: "POST", URL: "/open-apis/spark/v1/apps",
+			Status: http.StatusForbidden, Body: map[string]interface{}{"msg": "permission denied"}},
+		"full_stack")
+}
+
+func TestAppsDBEnvCreate_4xxFailureCarriesHint(t *testing.T) {
+	assertHintContains(t, AppsDBEnvCreate,
+		[]string{"+db-env-create", "--app-id", "app_x", "--env", "dev", "--yes", "--as", "user"},
+		&httpmock.Stub{Method: "POST", URL: "/open-apis/spark/v1/apps/app_x/db_dev_init",
+			Status: http.StatusConflict, Body: map[string]interface{}{"msg": "already multi-env"}},
+		"+db-table-list")
+}
+
+func TestAppsDBTableGet_4xxFailureCarriesHint(t *testing.T) {
+	assertHintContains(t, AppsDBTableGet,
+		[]string{"+db-table-get", "--app-id", "app_x", "--table", "users", "--as", "user"},
+		&httpmock.Stub{Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/tables/users",
+			Status: http.StatusNotFound, Body: map[string]interface{}{"msg": "table not found"}},
+		"+db-table-list")
+}
+
+func TestAppsDBTableList_4xxFailureCarriesHint(t *testing.T) {
+	assertHintContains(t, AppsDBTableList,
+		[]string{"+db-table-list", "--app-id", "app_x", "--env", "dev", "--as", "user"},
+		&httpmock.Stub{Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/tables",
+			Status: http.StatusNotFound, Body: map[string]interface{}{"msg": "dev env not found"}},
+		"+db-env-create")
+}
+
+// withAppsHint must only fill an EMPTY hint; an upstream-provided hint wins.
+func TestWithAppsHint_DoesNotOverrideUpstreamHint(t *testing.T) {
+	upstream := &errs.Problem{Message: "boom", Hint: "upstream specific hint"}
+	got := withAppsHint(upstream, appIDListHint)
+	p, ok := errs.ProblemOf(got)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", got)
+	}
+	if p.Hint != "upstream specific hint" {
+		t.Fatalf("upstream hint was overridden: %q", p.Hint)
+	}
+}
+
+// withAppsHint fills the hint when empty and leaves Message untouched.
+func TestWithAppsHint_FillsEmptyHintKeepsMessage(t *testing.T) {
+	p0 := &errs.Problem{Message: "boom"}
+	got := withAppsHint(p0, appIDListHint)
+	p, _ := errs.ProblemOf(got)
+	if p.Hint != appIDListHint {
+		t.Fatalf("hint not filled: %q", p.Hint)
+	}
+	if p.Message != "boom" {
+		t.Fatalf("message mutated: %q", p.Message)
+	}
+}