feat(credential): resolve the active app from the invocation context

Each lark-cli invocation can now carry its own app identity, so callers
bound to different apps no longer compete over a single stored default
profile.

.github/CODEOWNERS

@@ -1,30 +0,0 @@
-/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,8 +35,6 @@ 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/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/)
+      - 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/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/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/)
+      - path-except: (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/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/)
+      - path-except: (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,7 +17,6 @@ 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 where supported, e.g. amd64/arm64)
+make unit-test      # Required before PR (runs with -race)
 make test           # Full: vet + unit + integration
 ```
 

CHANGELOG.md

@@ -2,49 +2,6 @@
 
 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
@@ -1149,8 +1106,6 @@ 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

Makefile

@@ -8,13 +8,6 @@ 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
@@ -41,7 +34,7 @@ fmt-check:
 
 # ./extension/... keeps the public plugin SDK in the default test matrix.
 unit-test: fetch_meta
-	go test $(RACE_FLAG) -gcflags="all=-N -l" -count=1 \
+	go test -race -gcflags="all=-N -l" -count=1 \
 		./cmd/... ./internal/... ./shortcuts/... ./extension/...
 
 # examples-build keeps the shipped plugin-SDK examples compilable. If this

cmd/auth/auth_test.go

@@ -91,29 +91,6 @@ 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)
 
@@ -132,27 +109,6 @@ 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)
 
@@ -170,27 +126,6 @@ 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,
@@ -210,29 +145,6 @@ 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,
@@ -355,32 +267,6 @@ 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,7 +19,6 @@ import (
 type CheckOptions struct {
 	Factory *cmdutil.Factory
 	Scope   string
-	JSON    bool
 }
 
 // NewCmdAuthCheck creates the auth check subcommand.
@@ -38,7 +37,6 @@ 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,7 +18,6 @@ import (
 // ListOptions holds all inputs for auth list.
 type ListOptions struct {
 	Factory *cmdutil.Factory
-	JSON    bool
 }
 
 // NewCmdAuthList creates the auth list subcommand.
@@ -35,7 +34,6 @@ 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
@@ -46,14 +44,6 @@ 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
@@ -71,14 +61,6 @@ 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,7 +4,6 @@
 package auth
 
 import (
-	"encoding/json"
 	"strings"
 	"testing"
 
@@ -35,33 +34,6 @@ 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
@@ -85,48 +57,3 @@ 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", "note"}
+	return []string{"base", "contact", "docs", "markdown", "apps"}
 }

cmd/auth/login_test.go

@@ -9,7 +9,6 @@ import (
 	"errors"
 	"io"
 	"net/http"
-	"slices"
 	"sort"
 	"strings"
 	"testing"
@@ -215,12 +214,6 @@ 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,7 +18,6 @@ import (
 // LogoutOptions holds all inputs for auth logout.
 type LogoutOptions struct {
 	Factory *cmdutil.Factory
-	JSON    bool
 }
 
 // NewCmdAuthLogout creates the auth logout subcommand.
@@ -35,7 +34,6 @@ 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
@@ -46,65 +44,25 @@ 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

@@ -1,356 +0,0 @@
-// 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,7 +19,6 @@ type ScopesOptions struct {
 	Factory *cmdutil.Factory
 	Ctx     context.Context
 	Format  string
-	JSON    bool
 }
 
 // NewCmdAuthScopes creates the auth scopes subcommand.
@@ -31,9 +30,6 @@ 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)
 			}
@@ -42,7 +38,6 @@ 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,7 +17,6 @@ import (
 type StatusOptions struct {
 	Factory *cmdutil.Factory
 	Verify  bool
-	JSON    bool
 }
 
 // NewCmdAuthStatus creates the auth status subcommand.
@@ -36,7 +35,6 @@ 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/bootstrap.go

@@ -6,14 +6,21 @@ package cmd
 import (
 	"errors"
 	"io"
+	"os"
+	"strings"
 
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/envvars"
 	"github.com/spf13/pflag"
 )
 
 // BootstrapInvocationContext extracts global invocation options before
 // the real command tree is built, so provider-backed config resolution sees
 // the correct profile from the start.
+//
+// Profile resolution: --profile flag > CliRuntimeAppID env > "" (defers to
+// MultiAppConfig.CurrentApp). The env value flows through FindApp which
+// matches by Name first, then by AppId — so callers can pass either form.
 func BootstrapInvocationContext(args []string) (cmdutil.InvocationContext, error) {
 	var globals GlobalOptions
 
@@ -26,5 +33,9 @@ func BootstrapInvocationContext(args []string) (cmdutil.InvocationContext, error
 	if err := fs.Parse(args); err != nil && !errors.Is(err, pflag.ErrHelp) {
 		return cmdutil.InvocationContext{}, err
 	}
-	return cmdutil.InvocationContext{Profile: globals.Profile}, nil
+	profile := globals.Profile
+	if profile == "" {
+		profile = strings.TrimSpace(os.Getenv(envvars.CliRuntimeAppID))
+	}
+	return cmdutil.InvocationContext{Profile: profile}, nil
 }

cmd/bootstrap_test.go

@@ -3,7 +3,11 @@
 
 package cmd
 
-import "testing"
+import (
+	"testing"
+
+	"github.com/larksuite/cli/internal/envvars"
+)
 
 func TestBootstrapInvocationContext_ProfileFlag(t *testing.T) {
 	inv, err := BootstrapInvocationContext([]string{"--profile", "target", "auth", "status"})
@@ -70,3 +74,25 @@ func TestBootstrapInvocationContext_HelpWithProfile(t *testing.T) {
 		t.Fatalf("profile = %q, want %q", inv.Profile, "target")
 	}
 }
+
+func TestBootstrapInvocationContext_RuntimeAppIDEnv(t *testing.T) {
+	t.Setenv(envvars.CliRuntimeAppID, " env-app ")
+	inv, err := BootstrapInvocationContext([]string{"auth", "status"})
+	if err != nil {
+		t.Fatalf("BootstrapInvocationContext() error = %v", err)
+	}
+	if inv.Profile != "env-app" {
+		t.Fatalf("profile = %q, want %q (env value, trimmed)", inv.Profile, "env-app")
+	}
+}
+
+func TestBootstrapInvocationContext_ProfileFlagBeatsRuntimeAppIDEnv(t *testing.T) {
+	t.Setenv(envvars.CliRuntimeAppID, "env-app")
+	inv, err := BootstrapInvocationContext([]string{"--profile", "flag-app", "auth", "status"})
+	if err != nil {
+		t.Fatalf("BootstrapInvocationContext() error = %v", err)
+	}
+	if inv.Profile != "flag-app" {
+		t.Fatalf("profile = %q, want %q (--profile wins over env)", inv.Profile, "flag-app")
+	}
+}

cmd/config/bind.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"sort"
 	"strings"
 
 	"github.com/charmbracelet/huh"
@@ -55,6 +56,11 @@ type BindOptions struct {
 	// configBindRun; downstream branches read this instead of rechecking
 	// IOStreams.IsTerminal. Do not set from outside — it is overwritten.
 	IsTUI bool
+
+	// All binds every account exposed by the agent source as a multi-app
+	// config. Hidden flag, currently openclaw source only, mutually
+	// exclusive with --app-id.
+	All bool
 }
 
 // NewCmdConfigBind creates the config bind subcommand.
@@ -107,6 +113,8 @@ Interactive terminal use: run with no flags to enter the TUI form.`,
 	cmd.Flags().StringVar(&opts.Identity, "identity", "", "identity preset (bot-only|user-default); defaults to bot-only in flag mode (safer: no impersonation)")
 	cmd.Flags().BoolVar(&opts.Force, "force", false, "confirm a risky transition (currently: bot-only → user-default identity change in flag mode)")
 	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
+	cmd.Flags().BoolVar(&opts.All, "all", false, "bind every account from the agent source as a multi-app config (currently openclaw source only)")
+	_ = cmd.Flags().MarkHidden("all")
 	cmdutil.SetRisk(cmd, "write")
 
 	return cmd
@@ -124,6 +132,10 @@ func configBindRun(opts *BindOptions) error {
 	// opts.IsTUI instead of re-checking IOStreams.IsTerminal.
 	opts.IsTUI = opts.Source == "" && opts.Factory.IOStreams.IsTerminal
 
+	if opts.All {
+		return configBindAllRun(opts)
+	}
+
 	source, err := finalizeSource(opts)
 	if err != nil {
 		return err
@@ -632,6 +644,15 @@ func validateBindFlags(opts *BindOptions) error {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --identity %q; valid values: bot-only, user-default", opts.Identity).WithParam("--identity")
 		}
 	}
+	if opts.All {
+		if opts.AppID != "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--all is mutually exclusive with --app-id").WithParam("--all")
+		}
+		src := strings.TrimSpace(strings.ToLower(opts.Source))
+		if src != "" && src != "openclaw" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--all only supports --source openclaw").WithParam("--all")
+		}
+	}
 	lang, err := cmdutil.ParseLangFlag(opts.Lang)
 	if err != nil {
 		return err
@@ -677,3 +698,173 @@ func tuiSelectIdentity(opts *BindOptions) (string, error) {
 	}
 	return value, nil
 }
+
+// configBindAllRun binds every account exposed by the agent source as a
+// multi-app config. Flag-mode only; bot-only identity by default;
+// silently overwrites prior bindings.
+func configBindAllRun(opts *BindOptions) error {
+	// --all is flag-mode only: resolve the source through the same flag/env
+	// reconciliation as a single bind (including the explicit-vs-detected
+	// mismatch guard), but never prompt.
+	opts.IsTUI = false
+	source, err := finalizeSource(opts)
+	if err != nil {
+		return err
+	}
+	if source != "openclaw" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"--all only supports --source openclaw").WithParam("--all")
+	}
+	core.SetCurrentWorkspace(core.Workspace(source))
+	targetConfigPath := core.GetConfigPath()
+	previousConfigBytes, _ := vfs.ReadFile(targetConfigPath)
+
+	binder, err := newBinder(source, opts)
+	if err != nil {
+		return err
+	}
+	candidates, err := binder.ListCandidates()
+	if err != nil {
+		return err
+	}
+	if len(candidates) == 0 {
+		return errs.NewConfigError(errs.SubtypeNotConfigured,
+			"no Feishu accounts found in openclaw.json").
+			WithHint("configure channels.feishu.accounts first")
+	}
+
+	if opts.Identity == "" {
+		opts.Identity = "bot-only"
+	}
+	if err := warnIdentityEscalation(opts, previousConfigBytes); err != nil {
+		return err
+	}
+	noticeUserDefaultRisk(opts)
+	prior := priorLang(previousConfigBytes)
+
+	oc, ok := binder.(*openclawBinder)
+	if !ok {
+		return errs.NewInternalError(errs.SubtypeSDKError, "internal: --all requires openclawBinder, got %T", binder)
+	}
+	apps, err := oc.BuildAll()
+	if err != nil {
+		return err
+	}
+	for i := range apps {
+		applyPreferences(&apps[i], opts, prior)
+	}
+	sortAppsDefaultFirst(apps)
+	apps = dedupAndOrderApps(apps)
+
+	return commitMultiAppBinding(opts, apps, previousConfigBytes, source, targetConfigPath)
+}
+
+// sortAppsDefaultFirst orders the bound apps deterministically: the "default"
+// alias first, then named accounts alphabetically. Account enumeration
+// upstream follows Go map order, and CurrentApp is taken from the first
+// entry — without a stable order the selected default app would vary
+// between runs of the same bind.
+func sortAppsDefaultFirst(apps []core.AppConfig) {
+	sort.SliceStable(apps, func(i, j int) bool {
+		di, dj := strings.EqualFold(apps[i].Name, "default"), strings.EqualFold(apps[j].Name, "default")
+		if di != dj {
+			return di
+		}
+		return apps[i].Name < apps[j].Name
+	})
+}
+
+// dedupAndOrderApps collapses entries that share an AppId. Per OpenClaw
+// semantics, "default" is an implicit fallback alias that inherits the
+// top-level appId; when an explicit named account exposes the same appId,
+// "default" is redundant and discarded. Insertion order is preserved.
+func dedupAndOrderApps(apps []core.AppConfig) []core.AppConfig {
+	byID := make(map[string]int, len(apps))
+	out := make([]core.AppConfig, 0, len(apps))
+	for _, a := range apps {
+		if idx, seen := byID[a.AppId]; seen {
+			if strings.EqualFold(out[idx].Name, "default") && !strings.EqualFold(a.Name, "default") {
+				out[idx] = a
+			}
+			continue
+		}
+		byID[a.AppId] = len(out)
+		out = append(out, a)
+	}
+	return out
+}
+
+// commitMultiAppBinding writes a MultiAppConfig containing every bound
+// account. CurrentApp defaults to the first entry so existing single-app
+// callers keep their behaviour; callers select another profile with
+// --profile or LARKSUITE_CLI_RUNTIME_APP_ID.
+func commitMultiAppBinding(opts *BindOptions, apps []core.AppConfig, previousConfigBytes []byte, source, configPath string) error {
+	multi := &core.MultiAppConfig{
+		CurrentApp: apps[0].ProfileName(),
+		Apps:       apps,
+	}
+
+	if err := vfs.MkdirAll(core.GetConfigDir(), 0700); err != nil {
+		return errs.NewInternalError(errs.SubtypeFileIO, "failed to create workspace directory: %v", err).WithCause(err)
+	}
+	data, err := json.MarshalIndent(multi, "", "  ")
+	if err != nil {
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to marshal config: %v", err).WithCause(err)
+	}
+	if err := validate.AtomicWrite(configPath, append(data, '\n'), 0600); err != nil {
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to write config %s: %v", configPath, err).WithCause(err)
+	}
+
+	replaced := previousConfigBytes != nil
+	if replaced {
+		cleanupKeychainFromDataMulti(opts.Factory.Keychain, previousConfigBytes, apps)
+	}
+
+	appIDs := make([]string, len(apps))
+	for i := range apps {
+		appIDs[i] = apps[i].AppId
+	}
+
+	uiMsg := getBindMsg(opts.UILang)
+	display := sourceDisplayName(source)
+	fmt.Fprintln(opts.Factory.IOStreams.ErrOut,
+		fmt.Sprintf(uiMsg.BindSuccessHeader, display)+"\n"+
+			fmt.Sprintf("bound %d Feishu apps: %s", len(appIDs), strings.Join(appIDs, ", ")))
+
+	envelope := map[string]interface{}{
+		"ok":          true,
+		"workspace":   source,
+		"app_ids":     appIDs,
+		"config_path": configPath,
+		"replaced":    replaced,
+		"identity":    opts.Identity,
+		"all":         true,
+	}
+	resultJSON, _ := json.Marshal(envelope)
+	fmt.Fprintln(opts.Factory.IOStreams.Out, string(resultJSON))
+	return nil
+}
+
+// cleanupKeychainFromDataMulti is cleanupKeychainFromData with a keep set,
+// used when re-binding multiple apps in one pass.
+func cleanupKeychainFromDataMulti(kc keychain.KeychainAccess, data []byte, keep []core.AppConfig) {
+	var multi core.MultiAppConfig
+	if err := json.Unmarshal(data, &multi); err != nil {
+		return
+	}
+	keepIDs := make(map[string]struct{}, len(keep))
+	for i := range keep {
+		ref := keep[i].AppSecret.Ref
+		if ref != nil && ref.Source == "keychain" {
+			keepIDs[ref.ID] = struct{}{}
+		}
+	}
+	for _, app := range multi.Apps {
+		if app.AppSecret.Ref != nil && app.AppSecret.Ref.Source == "keychain" {
+			if _, ok := keepIDs[app.AppSecret.Ref.ID]; ok {
+				continue
+			}
+		}
+		core.RemoveSecretStore(app.AppSecret, kc)
+	}
+}

cmd/config/bind_test.go

@@ -1907,3 +1907,270 @@ func TestConfigBindRun_LangExplicit_PrintsConfirmation(t *testing.T) {
 		t.Errorf("stderr = %q, want it to contain confirmation %q", got, want)
 	}
 }
+
+// ── --all flag tests (hidden multi-account bind) ──
+
+func TestConfigBindCmd_AllFlagParsing(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	var gotOpts *BindOptions
+	cmd := NewCmdConfigBind(f, func(opts *BindOptions) error {
+		gotOpts = opts
+		return nil
+	})
+	cmd.SetArgs([]string{"--source", "openclaw", "--all"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !gotOpts.All {
+		t.Error("expected All=true")
+	}
+
+	// --all is hidden but still parseable.
+	flag := cmd.Flags().Lookup("all")
+	if flag == nil {
+		t.Fatal("--all flag must be registered")
+	}
+	if !flag.Hidden {
+		t.Error("--all must be hidden")
+	}
+}
+
+// requireAllValidationParam asserts err is a typed validation error of
+// subtype invalid_argument carrying the named param, locking the contract
+// beyond the prose message.
+func requireAllValidationParam(t *testing.T, err error, wantParam string) {
+	t.Helper()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T (%v)", err, err)
+	}
+	if ve.Category != errs.CategoryValidation || ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected validation/invalid_argument, got %s/%s", ve.Category, ve.Subtype)
+	}
+	if ve.Param != wantParam {
+		t.Fatalf("param = %q, want %q", ve.Param, wantParam)
+	}
+}
+
+func TestConfigBindRun_AllRejectsAppID(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{
+		Factory: f,
+		Source:  "openclaw",
+		AppID:   "cli_x",
+		All:     true,
+	})
+	if err == nil {
+		t.Fatal("expected validation error")
+	}
+	if !strings.Contains(err.Error(), "--all is mutually exclusive with --app-id") {
+		t.Errorf("unexpected error: %v", err)
+	}
+	requireAllValidationParam(t, err, "--all")
+}
+
+func TestDedupAndOrderApps_NamedWinsOverDefault(t *testing.T) {
+	// OpenClaw semantics: "default" is an implicit fallback alias; when a
+	// named account exposes the same appId, default is dropped.
+	apps := []core.AppConfig{
+		{Name: "acct-a", AppId: "cli_main"},
+		{Name: "acct-b", AppId: "cli_product"},
+		{Name: "default", AppId: "cli_main"},
+	}
+	got := dedupAndOrderApps(apps)
+	if len(got) != 2 {
+		t.Fatalf("len=%d, want 2", len(got))
+	}
+	if got[0].Name != "acct-a" || got[0].AppId != "cli_main" {
+		t.Errorf("apps[0]=%+v, want acct-a cli_main", got[0])
+	}
+	if got[1].Name != "acct-b" {
+		t.Errorf("apps[1]=%+v, want acct-b", got[1])
+	}
+}
+
+func TestDedupAndOrderApps_DefaultFirstThenNamedOverwrites(t *testing.T) {
+	// default arrives before its named alias — named still wins.
+	apps := []core.AppConfig{
+		{Name: "default", AppId: "cli_main"},
+		{Name: "acct-a", AppId: "cli_main"},
+	}
+	got := dedupAndOrderApps(apps)
+	if len(got) != 1 {
+		t.Fatalf("len=%d, want 1", len(got))
+	}
+	if got[0].Name != "acct-a" {
+		t.Errorf("apps[0]=%+v, want acct-a", got[0])
+	}
+}
+
+func TestDedupAndOrderApps_NoDuplicatesPreservesOrder(t *testing.T) {
+	apps := []core.AppConfig{
+		{Name: "acct-a", AppId: "cli_main"},
+		{Name: "acct-b", AppId: "cli_product"},
+		{Name: "acct-c", AppId: "cli_extra"},
+	}
+	got := dedupAndOrderApps(apps)
+	if len(got) != 3 {
+		t.Fatalf("len=%d, want 3", len(got))
+	}
+	want := []string{"acct-a", "acct-b", "acct-c"}
+	for i := range got {
+		if got[i].Name != want[i] {
+			t.Errorf("apps[%d]=%q, want %q", i, got[i].Name, want[i])
+		}
+	}
+}
+
+func TestDedupAndOrderApps_DefaultAlreadyFirst(t *testing.T) {
+	apps := []core.AppConfig{
+		{Name: "default", AppId: "cli_main"},
+		{Name: "acct-b", AppId: "cli_product"},
+	}
+	got := dedupAndOrderApps(apps)
+	if len(got) != 2 || got[0].Name != "default" {
+		t.Fatalf("got %+v, want default first", got)
+	}
+}
+
+func TestConfigBindRun_AllRejectsNonOpenClawSource(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{
+		Factory: f,
+		Source:  "hermes",
+		All:     true,
+	})
+	if err == nil {
+		t.Fatal("expected validation error")
+	}
+	if !strings.Contains(err.Error(), "--all only supports --source openclaw") {
+		t.Errorf("unexpected error: %v", err)
+	}
+	requireAllValidationParam(t, err, "--all")
+}
+
+func TestConfigBindRun_AllRejectsSourceEnvMismatch(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	clearAgentEnv(t)
+	t.Setenv("HERMES_HOME", t.TempDir()) // env says hermes, flag says openclaw
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{Factory: f, Source: "openclaw", All: true})
+	if err == nil {
+		t.Fatal("expected source/env mismatch error")
+	}
+	if !strings.Contains(err.Error(), "does not match detected Agent environment") {
+		t.Errorf("unexpected error: %v", err)
+	}
+	requireAllValidationParam(t, err, "--source")
+}
+
+func TestConfigBindRun_AllBindsEveryAccount(t *testing.T) {
+	saveWorkspace(t)
+	configDir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
+	clearAgentEnv(t)
+
+	openclawHome := t.TempDir()
+	t.Setenv("OPENCLAW_HOME", openclawHome)
+	openclawDir := filepath.Join(openclawHome, ".openclaw")
+	if err := os.MkdirAll(openclawDir, 0700); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	// Top-level credentials surface as a "default" candidate aliasing the
+	// "work" account; dedup must collapse them and keep the named entry.
+	cfg := `{"channels":{"feishu":{"appId":"cli_main","appSecret":"sec_main","domain":"feishu","accounts":{"work":{"appId":"cli_main","appSecret":"sec_main"},"personal":{"appId":"cli_personal","appSecret":"sec_personal"}}}}}`
+	if err := os.WriteFile(filepath.Join(openclawDir, "openclaw.json"), []byte(cfg), 0600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{Factory: f, All: true})
+	if err != nil {
+		t.Fatalf("expected success, got %v", err)
+	}
+
+	configPath := filepath.Join(configDir, "openclaw", "config.json")
+	assertEnvelope(t, stdout.Bytes(), map[string]any{
+		"ok":          true,
+		"workspace":   "openclaw",
+		"app_ids":     []any{"cli_main", "cli_personal"},
+		"config_path": configPath,
+		"replaced":    false,
+		"identity":    "bot-only",
+		"all":         true,
+	})
+
+	data, err := os.ReadFile(configPath)
+	if err != nil {
+		t.Fatalf("read written config: %v", err)
+	}
+	var multi core.MultiAppConfig
+	if err := json.Unmarshal(data, &multi); err != nil {
+		t.Fatalf("written config is not a MultiAppConfig: %v", err)
+	}
+	if len(multi.Apps) != 2 {
+		t.Fatalf("apps = %d, want 2", len(multi.Apps))
+	}
+	// The account aliased by top-level "default" stays first and becomes
+	// the initial CurrentApp.
+	if multi.CurrentApp != "work" {
+		t.Errorf("currentApp = %q, want %q", multi.CurrentApp, "work")
+	}
+	if multi.Apps[0].Name != "work" || multi.Apps[1].Name != "personal" {
+		t.Errorf("app order = [%q, %q], want [work, personal]", multi.Apps[0].Name, multi.Apps[1].Name)
+	}
+}
+
+func TestConfigBindRun_AllEscalationRequiresForce(t *testing.T) {
+	saveWorkspace(t)
+	configDir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
+	clearAgentEnv(t)
+
+	openclawHome := t.TempDir()
+	t.Setenv("OPENCLAW_HOME", openclawHome)
+	openclawDir := filepath.Join(openclawHome, ".openclaw")
+	if err := os.MkdirAll(openclawDir, 0700); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	cfg := `{"channels":{"feishu":{"appId":"cli_main","appSecret":"sec_main","domain":"feishu"}}}`
+	if err := os.WriteFile(filepath.Join(openclawDir, "openclaw.json"), []byte(cfg), 0600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	// Pre-existing binding locked to bot-only.
+	ocDir := filepath.Join(configDir, "openclaw")
+	if err := os.MkdirAll(ocDir, 0700); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	locked := `{"apps":[{"appId":"cli_old","strictMode":"bot"}]}`
+	if err := os.WriteFile(filepath.Join(ocDir, "config.json"), []byte(locked), 0600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := configBindRun(&BindOptions{Factory: f, All: true, Identity: "user-default"})
+	if err == nil {
+		t.Fatal("expected confirmation-required error without --force")
+	}
+	var ce *errs.ConfirmationRequiredError
+	if !errors.As(err, &ce) {
+		t.Fatalf("expected *errs.ConfirmationRequiredError, got %T (%v)", err, err)
+	}
+
+	// Same escalation with --force proceeds.
+	f2, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f2, All: true, Identity: "user-default", Force: true}); err != nil {
+		t.Fatalf("expected --force to allow escalation, got %v", err)
+	}
+	envelope := map[string]any{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("invalid JSON output: %v", err)
+	}
+	if envelope["replaced"] != true || envelope["identity"] != "user-default" {
+		t.Errorf("envelope = %v, want replaced=true identity=user-default", envelope)
+	}
+}

cmd/config/binder.go

@@ -172,40 +172,54 @@ func (b *openclawBinder) Build(appID string) (*core.AppConfig, error) {
 	if b.cfg == nil {
 		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: Build called before ListCandidates")
 	}
-
-	var selected *binding.CandidateApp
 	for i := range b.rawApps {
 		if b.rawApps[i].AppID == appID {
-			selected = &b.rawApps[i]
-			break
+			return b.buildFromCandidate(&b.rawApps[i])
 		}
 	}
-	if selected == nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q not in candidates", appID)
-	}
+	return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: appID %q not in candidates", appID)
+}
 
-	if selected.AppSecret.IsZero() {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "appSecret is empty for app %s in %s", selected.AppID, b.path).
+// BuildAll builds every candidate without appID lookup so duplicate-appID
+// entries (e.g. OpenClaw's "default" alias of a named account) keep their own
+// Label. --all callers must use this; Build(appID) collapses duplicates.
+func (b *openclawBinder) BuildAll() ([]core.AppConfig, error) {
+	if b.cfg == nil {
+		return nil, errs.NewInternalError(errs.SubtypeSDKError, "internal: BuildAll called before ListCandidates")
+	}
+	out := make([]core.AppConfig, 0, len(b.rawApps))
+	for i := range b.rawApps {
+		cfg, err := b.buildFromCandidate(&b.rawApps[i])
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, *cfg)
+	}
+	return out, nil
+}
+
+func (b *openclawBinder) buildFromCandidate(c *binding.CandidateApp) (*core.AppConfig, error) {
+	if c.AppSecret.IsZero() {
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "appSecret is empty for app %s in %s", c.AppID, b.path).
 			WithHint("configure channels.feishu.appSecret in openclaw.json")
 	}
-	secret, err := binding.ResolveSecretInput(selected.AppSecret, b.cfg.Secrets, os.Getenv)
+	secret, err := binding.ResolveSecretInput(c.AppSecret, b.cfg.Secrets, os.Getenv)
 	if err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "failed to resolve appSecret for %s: %v", selected.AppID, err).
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "failed to resolve appSecret for %s: %v", c.AppID, err).
 			WithHint("check appSecret configuration in %s", b.path).
 			WithCause(err)
 	}
-
-	stored, err := core.ForStorage(selected.AppID, core.PlainSecret(secret), b.opts.Factory.Keychain)
+	stored, err := core.ForStorage(c.AppID, core.PlainSecret(secret), b.opts.Factory.Keychain)
 	if err != nil {
 		return nil, errs.NewInternalError(errs.SubtypeStorage, "keychain unavailable: %v", err).
 			WithHint("use file: reference in config to bypass keychain").
 			WithCause(err)
 	}
-
 	return &core.AppConfig{
-		AppId:     selected.AppID,
+		Name:      c.Label,
+		AppId:     c.AppID,
 		AppSecret: stored,
-		Brand:     core.LarkBrand(normalizeBrand(selected.Brand)),
+		Brand:     core.LarkBrand(normalizeBrand(c.Brand)),
 	}, nil
 }
 

cmd/config/init_probe.go

@@ -33,16 +33,15 @@ 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 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.
+//     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.
 //
 //  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, "/oauth/v3/token"):
+	case strings.HasSuffix(req.URL.Path, "/auth/v3/tenant_access_token/internal"):
 		f.tatCalls++
 		if f.tatHandler == nil {
-			return jsonResp(200, `{"code":0,"access_token":"t-ok","token_type":"Bearer"}`), nil
+			return jsonResp(200, `{"code":0,"tenant_access_token":"t-ok"}`), nil
 		}
 		return f.tatHandler(req)
 	case strings.HasSuffix(req.URL.Path, "/application/v6/larksuite_cli_app/probe"):
@@ -84,15 +84,14 @@ 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). 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) {
+// 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) {
 	t.Helper()
 	if err == nil {
-		t.Fatal("expected *errs.ConfigError, got nil")
+		t.Fatalf("expected *errs.ConfigError (code %d), got nil", wantCode)
 	}
 	var cfgErr *errs.ConfigError
 	if !errors.As(err, &cfgErr) {
@@ -104,6 +103,9 @@ func assertConfigRejection(t *testing.T, err error, errBuf *bytes.Buffer) {
 	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())
 	}
@@ -121,13 +123,11 @@ func assertSilent(t *testing.T, err error, errBuf *bytes.Buffer) {
 	}
 }
 
-// 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) {
+// 10003 (bad / non-existent app_id) → ConfigError/InvalidClient, propagated.
+func TestRunProbe_TATCode10003_ReturnsConfigError(t *testing.T) {
 	rt := &fakeRT{
 		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(400, `{"error":"invalid_client","error_description":"The client secret is invalid.","code":20002}`), nil
+			return jsonResp(200, `{"code":10003,"msg":"invalid param"}`), nil
 		},
 	}
 	f, errBuf := fakeFactory(t, rt)
@@ -137,27 +137,28 @@ func TestRunProbe_TATInvalidClient_ReturnsConfigError(t *testing.T) {
 	if rt.probeCalls != 0 {
 		t.Error("probe endpoint must not be called when TAT fails")
 	}
-	assertConfigRejection(t, err, errBuf)
+	assertConfigRejection(t, err, errBuf, 10003)
 }
 
-// unauthorized_client is treated as the same credential rejection, propagated.
-func TestRunProbe_TATUnauthorizedClient_ReturnsConfigError(t *testing.T) {
+// 10014 (real app_id + wrong secret) → ConfigError/InvalidClient via codemeta —
+// the most common real-world rejection, propagated.
+func TestRunProbe_TATCode10014_ReturnsConfigError(t *testing.T) {
 	rt := &fakeRT{
 		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(401, `{"error":"unauthorized_client","error_description":"client not authorized"}`), nil
+			return jsonResp(200, `{"code":10014,"msg":"app secret invalid"}`), nil
 		},
 	}
 	f, errBuf := fakeFactory(t, rt)
-	assertConfigRejection(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf)
+	assertConfigRejection(t, runProbe(context.Background(), f, "cli_x", "secret_y", core.BrandFeishu), errBuf, 10014)
 }
 
-// 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) {
+// 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) {
 	rt := &fakeRT{
 		tatHandler: func(req *http.Request) (*http.Response, error) {
-			return jsonResp(400, `{"code":20068,"error":"invalid_scope","error_description":"unauthorized scope"}`), nil
+			return jsonResp(200, `{"code":99999,"msg":"future-unknown"}`), nil
 		},
 	}
 	f, errBuf := fakeFactory(t, rt)

errs/subtypes.go

@@ -80,7 +80,6 @@ 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.
 )

internal/auth/device_flow.go

@@ -47,7 +47,6 @@ type DeviceFlowResult struct {
 // OAuthEndpoints contains the OAuth endpoint URLs.
 type OAuthEndpoints struct {
 	DeviceAuthorization string
-	Revoke              string
 	Token               string
 }
 
@@ -56,7 +55,6 @@ 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,9 +31,6 @@ 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)
 	}
@@ -45,9 +42,6 @@ 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,8 +7,6 @@ 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

@@ -1,131 +0,0 @@
-// 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

@@ -1,207 +0,0 @@
-// 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,12 +22,6 @@ 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,11 +42,6 @@ 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,44 +19,33 @@ import (
 	extcred "github.com/larksuite/cli/extension/credential"
 )
 
-// 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.
+// 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:
 //
-// 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":
+//   - 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 {
 		return errs.NewConfigError(errs.SubtypeInvalidClient, "%s", msg).
 			WithCode(code).
 			WithHint("%s", errclass.ConfigHint(errs.SubtypeInvalidClient))
 	}
-	if err := errclass.BuildAPIError(map[string]any{
+	return 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.
@@ -79,6 +68,8 @@ func (p *DefaultAccountProvider) ResolveAccount(ctx context.Context) (*Account,
 		return nil, core.NotConfiguredError()
 	}
 
+	// p.profile already incorporates --profile / CliRuntimeAppID precedence
+	// (resolved in cmd/bootstrap.go before Factory construction).
 	cfg, err := core.ResolveConfigFromMulti(multi, p.keychain(), p.profile)
 	if err != nil {
 		return nil, err
@@ -157,8 +148,8 @@ func (p *DefaultTokenProvider) resolveUAT(ctx context.Context) (*TokenResult, er
 	return &TokenResult{Token: token, Scopes: scopes}, nil
 }
 
-// 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.
+// 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.
 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,16 +19,18 @@ func TestDefaultAccountProvider_Implements(t *testing.T) {
 	var _ DefaultAccountResolver = &DefaultAccountProvider{}
 }
 
-// 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")
+// 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")
 	if err == nil {
-		t.Fatal("expected non-nil error for invalid_client")
+		t.Fatal("expected non-nil error for code=10003")
 	}
 	var cfgErr *errs.ConfigError
 	if !errors.As(err, &cfgErr) {
@@ -40,16 +42,22 @@ func TestClassifyTATResponseCode_InvalidClient_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_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")
+// 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")
+	}
 	var cfgErr *errs.ConfigError
 	if !errors.As(err, &cfgErr) {
 		t.Fatalf("expected *errs.ConfigError, got %T: %v", err, err)
@@ -57,38 +65,21 @@ func TestClassifyTATResponseCode_UnauthorizedClient_MapsToInvalidClient(t *testi
 	if cfgErr.Subtype != errs.SubtypeInvalidClient {
 		t.Errorf("Subtype = %q, want %q", cfgErr.Subtype, errs.SubtypeInvalidClient)
 	}
-}
-
-// 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 invalid_scope")
-	}
-	var cfgErr *errs.ConfigError
-	if errors.As(err, &cfgErr) {
-		t.Fatalf("invalid_scope must not be classified as ConfigError, got %T", err)
+	if cfgErr.Code != 10014 {
+		t.Errorf("Code = %d, want 10014", cfgErr.Code)
 	}
 }
 
-// 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")
+// 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")
 	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)
+		t.Fatal("expected non-nil error for unmapped code")
 	}
 	var cfgErr *errs.ConfigError
 	if errors.As(err, &cfgErr) {
-		t.Fatalf("code-0 invalid_scope must not be a ConfigError, got %T", err)
+		t.Fatalf("unmapped code must not be classified as ConfigError, got %T", err)
 	}
 }

internal/credential/tat_fetch.go

@@ -4,47 +4,46 @@
 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 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.
+// 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.
 //
-// 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.
+// 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.
 //
 // 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)
-	endpoint := ep.Accounts + core.OAuthTokenV3Path
+	url := ep.Open + "/open-apis/auth/v3/tenant_access_token/internal"
 
-	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()))
+	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))
 	if err != nil {
 		return "", err
 	}
-	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Content-Type", "application/json")
 
 	resp, err := httpClient.Do(req)
 	if err != nil {
@@ -52,51 +51,20 @@ func FetchTAT(ctx context.Context, httpClient *http.Client, brand core.LarkBrand
 	}
 	defer resp.Body.Close()
 
-	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
-	if err != nil {
-		return "", fmt.Errorf("failed to read TAT response: %w", err)
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("TAT API returned HTTP %d", resp.StatusCode)
 	}
 
 	var result struct {
-		Code             int    `json:"code"`
-		AccessToken      string `json:"access_token"`
-		Error            string `json:"error"`
-		ErrorDescription string `json:"error_description"`
-		Msg              string `json:"msg"`
+		Code              int    `json:"code"`
+		Msg               string `json:"msg"`
+		TenantAccessToken string `json:"tenant_access_token"`
 	}
-	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 err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return "", fmt.Errorf("failed to parse TAT response: %w", err)
 	}
-
-	if result.Code == 0 && result.AccessToken != "" {
-		return result.AccessToken, nil
+	if result.Code != 0 {
+		return "", classifyTATResponseCode(result.Code, result.Msg, string(brand), appID)
 	}
-
-	// 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)
+	return result.TenantAccessToken, nil
 }

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,"access_token":"t-abc","token_type":"Bearer","expires_in":7200}`,
+		respBody: `{"code":0,"tenant_access_token":"t-abc","msg":"ok"}`,
 	}
 	hc := &http.Client{Transport: rt}
 
@@ -55,33 +55,24 @@ func TestFetchTAT_Success(t *testing.T) {
 	if token != "t-abc" {
 		t.Errorf("token = %q, want t-abc", token)
 	}
-	if rt.gotReq.URL.String() != "https://accounts.feishu.cn/oauth/v3/token" {
+	if rt.gotReq.URL.String() != "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" {
 		t.Errorf("url = %s", rt.gotReq.URL.String())
 	}
-	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)
-		}
+	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)
 	}
 }
 
-// invalid_client (wrong app_id/app_secret on the client_credentials grant) is a
-// deterministic client-side rejection that FetchTAT routes to
+// 10003 (bad / non-existent app_id, "invalid param") is classified locally by
 // classifyTATResponseCode as CategoryConfig / SubtypeInvalidClient — the same
 // typed error doResolveTAT (and thus every token-resolving command) returns.
-// 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}`}
+func TestFetchTAT_Code10003_ConfigInvalidClient(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 200, respBody: `{"code":10003,"msg":"invalid param"}`}
 	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 invalid_client")
+		t.Fatal("expected error for code 10003")
 	}
 	if token != "" {
 		t.Errorf("token = %q, want empty", token)
@@ -96,115 +87,52 @@ func TestFetchTAT_InvalidClient_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)
+	}
 }
 
-// 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"}`}
+// 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")
-	if err == nil {
-		t.Fatal("expected error for invalid_scope")
-	}
-	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.Errorf("invalid_scope must not be classified as ConfigError/InvalidClient, got %T", err)
+	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)
 	}
 }
 
-// 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"}`}
+// 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"}`}
 	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")
+		t.Fatal("expected error for code 99999")
 	}
 	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)
+	var apiErr *errs.APIError
+	if !errors.As(err, &apiErr) {
+		t.Errorf("unknown code should fall back to *errs.APIError, got %T", 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.
+// 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.
 func TestFetchTAT_HTTPNon200_Untyped(t *testing.T) {
 	for _, code := range []int{401, 403, 500, 503} {
 		rt := &stubRoundTripper{respCode: code, respBody: `whatever`}
@@ -254,12 +182,12 @@ func TestFetchTAT_BrandRouting(t *testing.T) {
 		brand   core.LarkBrand
 		wantURL string
 	}{
-		{core.BrandFeishu, "https://accounts.feishu.cn/oauth/v3/token"},
-		{core.BrandLark, "https://accounts.larksuite.com/oauth/v3/token"},
+		{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"},
 	}
 	for _, tc := range tests {
 		t.Run(string(tc.brand), func(t *testing.T) {
-			rt := &stubRoundTripper{respCode: 200, respBody: `{"code":0,"access_token":"t","token_type":"Bearer"}`}
+			rt := &stubRoundTripper{respCode: 200, respBody: `{"code":0,"tenant_access_token":"t"}`}
 			hc := &http.Client{Transport: rt}
 			if _, err := FetchTAT(context.Background(), hc, tc.brand, "a", "b"); err != nil {
 				t.Fatal(err)

internal/envvars/envvars.go

@@ -4,8 +4,11 @@
 package envvars
 
 const (
-	CliAppID             = "LARKSUITE_CLI_APP_ID"
-	CliAppSecret         = "LARKSUITE_CLI_APP_SECRET"
+	CliAppID     = "LARKSUITE_CLI_APP_ID"
+	CliAppSecret = "LARKSUITE_CLI_APP_SECRET"
+	// CliRuntimeAppID pins a profile by appId when --profile is unset.
+	// Selector only; credentials still come from config.json / keychain.
+	CliRuntimeAppID      = "LARKSUITE_CLI_RUNTIME_APP_ID"
 	CliBrand             = "LARKSUITE_CLI_BRAND"
 	CliUserAccessToken   = "LARKSUITE_CLI_USER_ACCESS_TOKEN"
 	CliTenantAccessToken = "LARKSUITE_CLI_TENANT_ACCESS_TOKEN"

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}, // legacy TAT endpoint — "app secret invalid" (pre-v3 variant of 99991543; CLI now reports invalid_client)
+	10014:    {Category: errs.CategoryConfig, Subtype: errs.SubtypeInvalidClient}, // TAT endpoint — "app secret invalid" (TAT-mint variant of 99991543)
 
 	// CategoryPolicy
 	21000: {Category: errs.CategoryPolicy, Subtype: errs.SubtypeChallengeRequired},

internal/output/lark_errors.go

@@ -35,12 +35,9 @@ const (
 	LarkErrAppNotInUse     = 99991662 // app is disabled in this tenant
 	LarkErrAppUnauthorized = 99991673 // app status unavailable; check installation
 
-	// "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.
+	// 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.
 	LarkErrTATInvalidSecret = 10014
 
 	// Rate limit.

internal/registry/service_descriptions.json

@@ -47,10 +47,6 @@
     "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": "电子表格操作" }

internal/suggest/suggest.go

@@ -7,10 +7,7 @@
 // carrying their own copy.
 package suggest
 
-import (
-	"sort"
-	"strings"
-)
+import "sort"
 
 // Levenshtein computes the classic edit distance between two strings. It is
 // rune-aware, so it is correct for multi-byte input.
@@ -54,29 +51,22 @@ func Levenshtein(a, b string) int {
 // signal of intent that raw edit distance misses.
 func Closest(typed string, candidates []string, maxN int) []string {
 	type scored struct {
-		name    string
-		contain bool
-		prefix  int
-		dist    int
+		name   string
+		prefix int
+		dist   int
 	}
 	limit := editLimit(typed)
 	ranked := make([]scored, 0, len(candidates))
 	for _, c := range candidates {
 		p := sharedPrefixLen(typed, c)
 		d := Levenshtein(typed, c)
-		ct := containsSegment(typed, c)
-		// Keep only plausible matches: a meaningful shared prefix, an edit
-		// distance within budget, or one name containing the other (a missing
-		// namespace prefix like "+block-list" vs "+base-block-list"). Drop
-		// everything else so the hint stays short.
-		if p >= 3 || d <= limit || ct {
-			ranked = append(ranked, scored{name: c, contain: ct, prefix: p, dist: d})
+		// Keep only plausible matches: a meaningful shared prefix, or an edit
+		// distance within budget. Drop everything else so the hint stays short.
+		if p >= 3 || d <= limit {
+			ranked = append(ranked, scored{name: c, prefix: p, dist: d})
 		}
 	}
 	sort.Slice(ranked, func(i, j int) bool {
-		if ranked[i].contain != ranked[j].contain {
-			return ranked[i].contain
-		}
 		if ranked[i].prefix != ranked[j].prefix {
 			return ranked[i].prefix > ranked[j].prefix
 		}
@@ -104,21 +94,6 @@ func editLimit(s string) int {
 	return 2
 }
 
-// containsSegment reports whether one name contains the other as a substring
-// after stripping the "+"/"--" sigils. It catches hallucinated names that drop
-// a namespace prefix (e.g. "+block-list" for "+base-block-list"), which share
-// almost no prefix and sit far beyond the edit-distance budget. The shorter
-// side must be at least 5 runes so generic fragments like "list" do not match
-// half the catalog.
-func containsSegment(a, b string) bool {
-	a = strings.TrimLeft(a, "+-")
-	b = strings.TrimLeft(b, "+-")
-	if len([]rune(a)) > len([]rune(b)) {
-		a, b = b, a
-	}
-	return len([]rune(a)) >= 5 && strings.Contains(b, a)
-}
-
 func sharedPrefixLen(a, b string) int {
 	ra, rb := []rune(a), []rune(b)
 	n := 0

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -18,18 +18,15 @@ 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/",

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -19,18 +19,15 @@ 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/",
@@ -38,6 +35,7 @@ var migratedEnvelopePaths = []string{
 	"shortcuts/vc/",
 	"shortcuts/whiteboard/",
 	"shortcuts/wiki/",
+	"shortcuts/im/",
 }
 
 // legacyOutputImportPath is the import path of the package that declares the

lint/errscontract/rules_test.go

@@ -953,7 +953,6 @@ func TestCheckNoLegacyCommonHelperCall_RejectsLegacyHelpersOnMigratedPath(t *tes
 	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",
@@ -989,18 +988,6 @@ 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
 

package.json

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

scripts/build-pkg-pr-new.sh

@@ -33,7 +33,6 @@ 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
 
@@ -56,7 +55,6 @@ const platformMap = {
 const archMap = {
   x64: "amd64",
   arm64: "arm64",
-  riscv64: "riscv64",
 };
 
 const platform = platformMap[process.platform];

scripts/install.js

@@ -30,7 +30,6 @@ 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,16 +9,17 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsAccessScopeGet reads the current access scope configuration of an app.
+// AppsAccessScopeGet reads the current access scope configuration of a Miaoda app.
 // 响应原样透传服务端契约（字符串 scope 枚举 All/Tenant/Range + 拆分的 users/departments/chats 数组）。
 var AppsAccessScopeGet = common.Shortcut{
 	Service:     appsService,
 	Command:     "+access-scope-get",
-	Description: "Get app access scope configuration",
+	Description: "Get Miaoda app access scope configuration",
 	Risk:        "read",
 	Tips: []string{
 		"Example: lark-cli apps +access-scope-get --app-id <app_id>",
@@ -31,7 +32,7 @@ var AppsAccessScopeGet = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		return nil
 	},
@@ -39,7 +40,7 @@ var AppsAccessScopeGet = common.Shortcut{
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			GET(fmt.Sprintf("%s/apps/%s/access-scope", apiBasePath, validate.EncodePathSegment(appID))).
-			Desc("Get app access scope")
+			Desc("Get Miaoda app access scope")
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		appID := strings.TrimSpace(rctx.Str("app-id"))

shortcuts/apps/apps_access_scope_set.go

@@ -10,6 +10,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -24,7 +25,7 @@ var allowedAccessTargetTypes = map[string]bool{
 var AppsAccessScopeSet = common.Shortcut{
 	Service:     appsService,
 	Command:     "+access-scope-set",
-	Description: "Set app access scope (specific / public / tenant)",
+	Description: "Set Miaoda app access scope (specific / public / tenant)",
 	Risk:        "write",
 	Tips: []string{
 		`Example: lark-cli apps +access-scope-set --app-id <app_id> --scope tenant`,
@@ -44,7 +45,7 @@ var AppsAccessScopeSet = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		return validateAccessScopeFlags(rctx)
 	},
@@ -52,7 +53,7 @@ var AppsAccessScopeSet = common.Shortcut{
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		dry := common.NewDryRunAPI().
 			PUT(fmt.Sprintf("%s/apps/%s/access-scope", apiBasePath, validate.EncodePathSegment(appID))).
-			Desc("Set app access scope")
+			Desc("Set Miaoda app access scope")
 		body, bodyErr := buildAccessScopeBody(rctx)
 		if bodyErr != nil {
 			dry.Set("body_error", bodyErr.Error())
@@ -89,42 +90,36 @@ func validateAccessScopeFlags(rctx *common.RuntimeContext) error {
 	switch scope {
 	case "specific":
 		if targets == "" {
-			return appsValidationParamError("--targets", "--targets is required when --scope=specific")
+			return output.ErrValidation("--targets is required when --scope=specific")
 		}
 		if err := validateTargetsJSON(targets); err != nil {
 			return err
 		}
 		if approver != "" && !applyEnabled {
-			return appsValidationParamError("--approver", "--approver requires --apply-enabled")
+			return output.ErrValidation("--approver requires --apply-enabled")
 		}
 		if requireLogin {
-			return appsValidationParamError("--require-login", "--require-login is not allowed when --scope=specific")
+			return output.ErrValidation("--require-login is not allowed when --scope=specific")
 		}
 	case "public":
 		if targets != "" {
-			return appsValidationParamError("--targets", "--targets is not allowed when --scope=public")
+			return output.ErrValidation("--targets is not allowed when --scope=public")
 		}
 		if applyEnabled {
-			return appsValidationParamError("--apply-enabled", "--apply-enabled is not allowed when --scope=public")
+			return output.ErrValidation("--apply-enabled is not allowed when --scope=public")
 		}
 		if approver != "" {
-			return appsValidationParamError("--approver", "--approver is not allowed when --scope=public")
+			return output.ErrValidation("--approver is not allowed when --scope=public")
 		}
 		if !rctx.Cmd.Flags().Changed("require-login") {
-			return appsValidationParamError("--require-login", "--require-login is required when --scope=public (pass true or false explicitly; do not rely on the default)")
+			return output.ErrValidation("--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 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"),
-				)
+			return output.ErrValidation("no extra flags allowed when --scope=tenant")
 		}
 	default:
-		return appsValidationParamError("--scope", "--scope must be specific / public / tenant")
+		return output.ErrValidation("--scope must be specific / public / tenant")
 	}
 	return nil
 }
@@ -132,18 +127,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 appsValidationParamError("--targets", "--targets is not valid JSON: %v", err).WithCause(err)
+		return output.ErrValidation("--targets is not valid JSON: %v", err)
 	}
 	if len(items) == 0 {
-		return appsValidationParamError("--targets", "--targets must contain at least one entry; specific scope requires concrete user/department/chat ids")
+		return output.ErrValidation("--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 appsValidationParamError("--targets", "--targets[%d].type %q must be one of: user / department / chat", i, typ)
+			return output.ErrValidation("--targets[%d].type %q must be one of: user / department / chat", i, typ)
 		}
 		if id, _ := t["id"].(string); strings.TrimSpace(id) == "" {
-			return appsValidationParamError("--targets", "--targets[%d].id is empty", i)
+			return output.ErrValidation("--targets[%d].id is empty", i)
 		}
 	}
 	return nil
@@ -162,7 +157,7 @@ func buildAccessScopeBody(rctx *common.RuntimeContext) (map[string]interface{},
 	scope := rctx.Str("scope")
 	enum, ok := scopeStringToServerEnum[scope]
 	if !ok {
-		return nil, appsValidationParamError("--scope", "--scope must be specific / public / tenant, got %q", scope)
+		return nil, output.ErrValidation("--scope must be specific / public / tenant, got %q", scope)
 	}
 	body := map[string]interface{}{"scope": enum}
 
@@ -171,7 +166,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, appsValidationParamError("--targets", "--targets is not valid JSON: %v", err).WithCause(err)
+			return nil, output.ErrValidation("--targets is not valid JSON: %v", err)
 		}
 		users, departments, chats := splitAccessScopeTargets(targets)
 		if len(users) > 0 {

shortcuts/apps/apps_chat.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -42,14 +43,14 @@ var AppsChat = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		if strings.TrimSpace(rctx.Str("session-id")) == "" {
-			return appsValidationParamError("--session-id", "--session-id is required")
+			return output.ErrValidation("--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 output.ErrValidation("--message is required")
 		}
 		return nil
 	},

shortcuts/apps/apps_create.go

@@ -9,16 +9,17 @@ 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 apps"
+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 app.
+// AppsCreate creates a new Miaoda app.
 var AppsCreate = common.Shortcut{
 	Service:     appsService,
 	Command:     "+create",
-	Description: "Create a new app",
+	Description: "Create a new Miaoda app",
 	Risk:        "write",
 	Tips: []string{
 		`Example: lark-cli apps +create --name "审批系统" --app-type full_stack`,
@@ -35,14 +36,14 @@ var AppsCreate = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("name")) == "" {
-			return appsValidationParamError("--name", "--name is required")
+			return output.ErrValidation("--name is required")
 		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			POST(apiBasePath + "/apps").
-			Desc("Create an app").
+			Desc("Create a Miaoda app").
 			Body(buildAppsCreateBody(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_create_test.go

@@ -12,7 +12,6 @@ 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"
@@ -48,31 +47,6 @@ 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) {

shortcuts/apps/apps_db_env_create.go

@@ -14,7 +14,7 @@ import (
 
 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 an app（拆分单库为 dev/online 多环境）。
+// 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 确认关卡。
@@ -30,7 +30,7 @@ var AppsDBEnvCreate = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app id", Required: true},
+		{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)"},
 	},
@@ -42,7 +42,7 @@ var AppsDBEnvCreate = common.Shortcut{
 		appID, _ := requireAppID(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			POST(appDbEnvCreatePath(appID)).
-			Desc("Create app DB environment").
+			Desc("Create Miaoda app DB environment").
 			Body(buildDBEnvCreateBody(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_db_execute.go

@@ -17,7 +17,7 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsDBExecute executes SQL against an app database.
+// AppsDBExecute executes SQL against a Miaoda app database.
 //
 // POST /apps/{app_id}/sql_commands，CLI 永远带 ?transactional=false 进入 DBA 模式
 // （不默认包事务、支持 DDL、result 字符串内嵌结构化 JSON）。
@@ -31,9 +31,8 @@ import (
 //   - 多语句部分失败：`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
+// 后升级成 typed api_error（exit 非 0、detail 带 statement_index / completed / rolled_back），
+// 避免 agent 误判 ok:true 假成功。CLI 永远 DBA 模式（transactional=false），失败前的语句已 auto-commit
 // 落地，故 rolled_back=false（真机 boe 实证）。
 //
 // JSON envelope（成功路径）：CLI 把 server 返的 result 字符串解出来放进 `data.results` 数组。
@@ -45,7 +44,7 @@ import (
 var AppsDBExecute = common.Shortcut{
 	Service:     appsService,
 	Command:     "+db-execute",
-	Description: "Execute SQL (SELECT / DML / DDL) against an app database",
+	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`,
@@ -56,7 +55,7 @@ var AppsDBExecute = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app id", Required: true},
+		{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"},
@@ -69,27 +68,19 @@ var AppsDBExecute = common.Shortcut{
 		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"),
-				)
+			return output.ErrValidation("--sql and --file are mutually exclusive")
 		}
 		if file != "" {
 			data, err := cmdutil.ReadInputFile(rctx.FileIO(), file)
 			if err != nil {
-				return appsValidationParamError("--file", "--file: %v", err).WithCause(err)
+				return output.ErrValidation("--file: %v", 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 output.ErrValidation("one of --sql or --file is required (use --sql - to read stdin)")
 		}
 		return nil
 	},
@@ -97,7 +88,7 @@ var AppsDBExecute = common.Shortcut{
 		appID, _ := requireAppID(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			POST(appSQLPath(appID)).
-			Desc("Execute SQL on app database").
+			Desc("Execute SQL on Miaoda app database").
 			Params(buildDBSQLParams(rctx)).
 			Body(buildDBSQLBody(rctx))
 	},
@@ -122,15 +113,13 @@ var AppsDBExecute = common.Shortcut{
 		data := map[string]interface{}{"results": stmts}
 
 		// 多语句 / 单语句失败：server 仍返 code:0，把失败语句标成 ERROR 哨兵塞进 result。
-		// 已落地的前序语句 + 失败语句构成 partial failure：逐条结果作为 ok:false 数据
-		// 留在 stdout（机器可读）+ 非零退出信号，别让 agent 误判 ok:true 假成功。
-		// pretty 模式 stdout 只打逐条 ✓/✗ 摘要（不再叠一份 JSON envelope），仅返回退出信号。
+		// 升级成 typed api_error（exit 非 0），别让 agent 误判 ok:true 假成功。
+		// pretty 模式仍把逐条 ✓/✗ 摘要打到 stdout（人看），再返回 error（envelope→stderr）。
 		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)
+			return sqlStatementError(stmts, errIdx, errStmt)
 		}
 
 		rctx.OutFormat(data, nil, func(w io.Writer) {
@@ -151,28 +140,31 @@ func findErrorSentinel(stmts []map[string]interface{}) (int, map[string]interfac
 	return 0, nil, false
 }
 
-// sqlStatementFailurePayload 把 ERROR 哨兵整理成 partial-failure 的 stdout 数据。
+// sqlStatementError 把 ERROR 哨兵升级成 typed api_error。
 //
 // 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{} {
+// 落地，不存在外层事务回滚。因此 rolled_back=false、completed 列出已落地的前序语句，hint 提示用户
+// 别整批重跑（否则会重复写入）。
+func sqlStatementError(stmts []map[string]interface{}, errIdx int, errStmt map[string]interface{}) error {
 	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,
+	fullMsg := fmt.Sprintf("%s (at statement %d of %d)", msg, stmtNo, len(stmts))
+
+	apiErr := output.ErrAPI(code, fullMsg, map[string]interface{}{
 		"statement_index": errIdx,
-		"error_code":      code,
-		"error_message":   fmt.Sprintf("%s (at statement %d of %d)", msg, stmtNo, len(stmts)),
+		"completed":       stmts[:errIdx],
 		"rolled_back":     false,
-		"note":            note,
+	})
+	if apiErr.Detail != nil {
+		if errIdx > 0 {
+			apiErr.Detail.Hint = 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)
+		} else {
+			apiErr.Detail.Hint = "no statements were applied; fix the SQL and re-run."
+		}
 	}
+	return apiErr
 }
 
 // parseErrorSentinel 解析 ERROR 哨兵的 data（`{code,message}` JSON），返回数值 code 与 message。

shortcuts/apps/apps_db_execute_test.go

@@ -495,9 +495,9 @@ func TestAppsDBExecute_PrettyMultiStatementsPartialFailureWithErrorSentinel(t *t
 	}
 }
 
-// TestAppsDBExecute_MultiStatementFailureReturnsTypedError 钉死「多语句失败 → partial failure」：
-// 逐条结果 + statement_index / error_code / rolled_back / note 作为 ok:false 数据落 stdout，
-// 退出信号是 PartialFailureError（非零 exit）。rolled_back=false 因 CLI 永远 DBA 模式
+// TestAppsDBExecute_MultiStatementFailureReturnsTypedError 钉死「多语句失败 → typed api_error」：
+// json 默认不再打 ok:true 假成功，而是返回 *output.ExitError（type=api_error、非零 exit），
+// detail 带 statement_index / completed / rolled_back。rolled_back=false 因 CLI 永远 DBA 模式
 // （真机 boe 实证：失败前的语句已落地）。
 func TestAppsDBExecute_MultiStatementFailureReturnsTypedError(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
@@ -518,64 +518,45 @@ func TestAppsDBExecute_MultiStatementFailureReturnsTypedError(t *testing.T) {
 		[]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())
+		t.Fatalf("multi-statement failure must return a typed 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)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("want *output.ExitError with detail, got %T: %v", err, err)
 	}
-	if pfErr.Code != output.ExitAPI {
-		t.Errorf("exit = %d, want %d (ExitAPI)", pfErr.Code, output.ExitAPI)
+	if exitErr.Detail.Type != "api_error" {
+		t.Errorf("error.type = %q, want api_error", exitErr.Detail.Type)
 	}
-	payload := decodePartialFailureData(t, stdout.String())
-	if got := payload["statement_index"]; got != float64(1) {
-		t.Errorf("statement_index = %v, want 1", got)
+	if exitErr.Detail.Code != 1300002 {
+		t.Errorf("error.code = %d, want 1300002", exitErr.Detail.Code)
 	}
-	if got := payload["error_code"]; got != float64(1300002) {
-		t.Errorf("error_code = %v, want 1300002", got)
+	if !strings.Contains(exitErr.Detail.Message, "(at statement 2 of 2)") {
+		t.Errorf("error.message missing statement locator: %q", exitErr.Detail.Message)
 	}
-	msg, _ := payload["error_message"].(string)
-	if !strings.Contains(msg, "(at statement 2 of 2)") {
-		t.Errorf("error_message missing statement locator: %q", msg)
+	if output.ExitCodeOf(err) != output.ExitAPI {
+		t.Errorf("exit = %d, want %d (ExitAPI)", output.ExitCodeOf(err), output.ExitAPI)
 	}
-	if got := payload["rolled_back"]; got != false {
-		t.Errorf("rolled_back = %v, want false (DBA mode persists prior statements)", got)
+	detail, ok := exitErr.Detail.Detail.(map[string]interface{})
+	if !ok {
+		t.Fatalf("error.detail not a map: %T", exitErr.Detail.Detail)
 	}
-	results, _ := payload["results"].([]interface{})
-	if len(results) != 2 {
-		t.Errorf("results length = %d, want 2 (persisted statement + ERROR sentinel)", len(results))
+	if detail["statement_index"] != 1 {
+		t.Errorf("statement_index = %v, want 1", detail["statement_index"])
 	}
-	note, _ := payload["note"].(string)
-	if !strings.Contains(note, "already applied") {
-		t.Errorf("note should warn prior statements persisted, got %q", note)
+	if detail["rolled_back"] != false {
+		t.Errorf("rolled_back = %v, want false (DBA mode persists prior statements)", detail["rolled_back"])
 	}
-}
-
-// 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 completed, ok := detail["completed"].([]map[string]interface{}); !ok || len(completed) != 1 {
+		t.Errorf("completed = %v, want 1 persisted statement", detail["completed"])
 	}
-	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)。
+// 同样升级成 typed error：statement_index=0、completed 空、message 标注 (at statement 1 of 1)。
 func TestAppsDBExecute_SingleErrorReturnsTypedError(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
 	reg.Register(&httpmock.Stub{
@@ -592,23 +573,21 @@ func TestAppsDBExecute_SingleErrorReturnsTypedError(t *testing.T) {
 		[]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())
+		t.Fatalf("single ERROR sentinel must return a typed 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)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("want *output.ExitError with detail, 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 !strings.Contains(exitErr.Detail.Message, "(at statement 1 of 1)") {
+		t.Errorf("error.message missing locator: %q", exitErr.Detail.Message)
 	}
-	if got := payload["statement_index"]; got != float64(0) {
-		t.Errorf("statement_index = %v, want 0", got)
+	detail, _ := exitErr.Detail.Detail.(map[string]interface{})
+	if detail["statement_index"] != 0 {
+		t.Errorf("statement_index = %v, want 0", detail["statement_index"])
 	}
-	note, _ := payload["note"].(string)
-	if !strings.Contains(note, "no statements were applied") {
-		t.Errorf("note should say nothing was applied, got %q", note)
+	if completed, ok := detail["completed"].([]map[string]interface{}); !ok || len(completed) != 0 {
+		t.Errorf("completed = %v, want empty", detail["completed"])
 	}
 }
 
@@ -816,35 +795,3 @@ func TestRenderSelectRowsAsTable_Branches(t *testing.T) {
 		})
 	}
 }
-
-// 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

@@ -8,6 +8,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -35,7 +36,7 @@ var AppsDBTableGet = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app id", Required: true},
+		{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"},
 	},
@@ -44,7 +45,7 @@ var AppsDBTableGet = common.Shortcut{
 			return err
 		}
 		if strings.TrimSpace(rctx.Str("table")) == "" {
-			return appsValidationParamError("--table", "--table is required")
+			return output.ErrValidation("--table is required")
 		}
 		return nil
 	},
@@ -52,7 +53,7 @@ var AppsDBTableGet = common.Shortcut{
 		appID, _ := requireAppID(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			GET(appTablePath(appID, strings.TrimSpace(rctx.Str("table")))).
-			Desc("Get app db table schema").
+			Desc("Get Miaoda app db table schema").
 			Params(buildDBTableGetParams(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_db_table_list.go

@@ -15,7 +15,7 @@ import (
 
 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 an app's database.
+// AppsDBTableList lists tables in a Miaoda app's database.
 //
 // GET /apps/{app_id}/tables（cursor 分页），response items[] 含 estimated_row_count /
 // size_bytes optional 字段，默认返回，不必额外传 query。
@@ -29,7 +29,7 @@ const dbTableListHint = "verify --app-id is correct; if targeting --env dev, cre
 var AppsDBTableList = common.Shortcut{
 	Service:     appsService,
 	Command:     "+db-table-list",
-	Description: "List tables in an app database (cursor pagination)",
+	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>",
@@ -39,7 +39,7 @@ var AppsDBTableList = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app id", Required: true},
+		{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"},
@@ -52,7 +52,7 @@ var AppsDBTableList = common.Shortcut{
 		appID, _ := requireAppID(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			GET(appTablesPath(appID)).
-			Desc("List app db tables").
+			Desc("List Miaoda app db tables").
 			Params(buildDBTableListParams(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_env_pull.go

@@ -47,11 +47,11 @@ var AppsEnvPull = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return &errs.ValidationError{Problem: errs.Problem{Category: errs.CategoryValidation, Subtype: errs.SubtypeInvalidArgument, Message: "--app-id is required"}, Param: "app-id"}
 		}
 		_, envFile, err := resolveEnvPullTarget(strings.TrimSpace(rctx.Str("project-path")))
 		if err != nil {
-			return appsValidationParamError("--project-path", "--project-path: %v", err).WithCause(err)
+			return &errs.ValidationError{Problem: errs.Problem{Category: errs.CategoryValidation, Subtype: errs.SubtypeInvalidArgument, Message: fmt.Sprintf("--project-path: %v", err)}, Param: "project-path", Cause: err}
 		}
 		if err := checkEnvPullTarget(envFile); err != nil {
 			return err
@@ -71,7 +71,7 @@ var AppsEnvPull = common.Shortcut{
 		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)
+			return &errs.ValidationError{Problem: errs.Problem{Category: errs.CategoryValidation, Subtype: errs.SubtypeInvalidArgument, Message: fmt.Sprintf("--project-path: %v", err)}, Param: "project-path", Cause: err}
 		}
 		if err := checkEnvPullTarget(envFile); err != nil {
 			return err
@@ -120,7 +120,7 @@ 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)
+			return "", "", fmt.Errorf("cannot determine working directory: %w", err)
 		}
 		projectPath = cwd
 	}
@@ -137,13 +137,13 @@ func checkEnvPullTarget(envFile string) error {
 		if os.IsNotExist(err) {
 			return nil
 		}
-		return appsValidationParamError("--project-path", "cannot inspect %s: %v", envFile, err).WithCause(err)
+		return &errs.ValidationError{Problem: errs.Problem{Category: errs.CategoryValidation, Subtype: errs.SubtypeInvalidArgument, Message: fmt.Sprintf("cannot inspect %s: %v", envFile, err)}, Param: "project-path", Cause: err}
 	}
 	if info.Mode()&os.ModeSymlink != 0 {
-		return appsValidationParamError("--project-path", "target %s must be a regular file, not a symlink", envFile)
+		return &errs.ValidationError{Problem: errs.Problem{Category: errs.CategoryValidation, Subtype: errs.SubtypeInvalidArgument, Message: fmt.Sprintf("target %s must be a regular file, not a symlink", envFile)}, Param: "project-path"}
 	}
 	if !info.Mode().IsRegular() {
-		return appsValidationParamError("--project-path", "target %s must be a regular file", envFile)
+		return &errs.ValidationError{Problem: errs.Problem{Category: errs.CategoryValidation, Subtype: errs.SubtypeInvalidArgument, Message: fmt.Sprintf("target %s must be a regular file", envFile)}, Param: "project-path"}
 	}
 	return nil
 }
@@ -156,7 +156,7 @@ func extractEnvPullVars(data map[string]interface{}) (map[string]string, envPull
 		}
 	}
 	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")
+		return nil, envPullDatabaseInfo{}, nil, &errs.ValidationError{Problem: errs.Problem{Category: errs.CategoryValidation, Subtype: errs.SubtypeInvalidResponse, Message: "response field env_vars must be an object or array of key/value entries"}}
 	}
 
 	var skippedKeys []string
@@ -203,7 +203,7 @@ func extractEnvPullVars(data map[string]interface{}) (map[string]string, envPull
 		}
 		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")
+		return nil, envPullDatabaseInfo{}, nil, &errs.ValidationError{Problem: errs.Problem{Category: errs.CategoryValidation, Subtype: errs.SubtypeInvalidResponse, Message: "response field env_vars must be an object or array of key/value entries"}}
 	}
 }
 

shortcuts/apps/apps_env_pull_test.go

@@ -1079,28 +1079,3 @@ func TestEnsureEnvPullParentDir_MkdirError(t *testing.T) {
 		t.Error("MkdirAll over a file component must surface an error")
 	}
 }
-
-// TestExtractEnvPullVars_MissingEnvVarsIsInternalInvalidResponse pins that a
-// response without a usable env_vars field classifies as
-// internal/invalid_response — a broken upstream payload, not a flag problem
-// the agent should retry with different arguments.
-func TestExtractEnvPullVars_MissingEnvVarsIsInternalInvalidResponse(t *testing.T) {
-	for name, data := range map[string]map[string]interface{}{
-		"missing":    {},
-		"wrong type": {"env_vars": "not-an-object"},
-	} {
-		t.Run(name, func(t *testing.T) {
-			_, _, _, err := extractEnvPullVars(data)
-			if err == nil {
-				t.Fatalf("expected error for %s env_vars", name)
-			}
-			p, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatalf("expected typed problem, got %T: %v", err, err)
-			}
-			if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
-				t.Fatalf("classification = %s/%s, want internal/invalid_response", p.Category, p.Subtype)
-			}
-		})
-	}
-}

shortcuts/apps/apps_errors.go

@@ -1,104 +0,0 @@
-// 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

@@ -1,113 +0,0 @@
-// 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_html_publish.go

@@ -10,7 +10,7 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/client"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -19,7 +19,7 @@ import (
 var AppsHTMLPublish = common.Shortcut{
 	Service:     appsService,
 	Command:     "+html-publish",
-	Description: "Publish HTML to an app (single multipart POST returns the access URL)",
+	Description: "Publish HTML to a Miaoda app (single multipart POST returns the access URL)",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +html-publish --app-id <app_id> --path ./dist",
@@ -29,17 +29,17 @@ var AppsHTMLPublish = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", Required: true},
 		{Name: "path", Desc: "path to HTML file or directory", Required: true},
 		{Name: "allow-sensitive", Type: "bool", Desc: "skip the credential-file scan (allow .env / .npmrc / .aws/credentials / etc. in the publish payload)"},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		path := strings.TrimSpace(rctx.Str("path"))
 		if path == "" {
-			return appsValidationParamError("--path", "--path is required")
+			return output.ErrValidation("--path is required")
 		}
 		// Block well-known credential files in the publish payload unless the
 		// caller explicitly opts in. Lives in Validate (not DryRun) so that
@@ -150,9 +150,9 @@ func sensitiveCandidatesError(hits []string) error {
 		sample = strings.Join(hits[:maxSensitiveListInError], ", ") +
 			fmt.Sprintf(" (and %d more)", len(hits)-maxSensitiveListInError)
 	}
-	return appsValidationParamError("--path",
-		"--path contains %d credential file(s) that should not be published: %s", len(hits), sample).
-		WithHint("remove these files from the publish payload, OR pass --allow-sensitive if shipping them is intentional (e.g. a docs site demoing credential-file formats)")
+	return output.ErrWithHint(output.ExitValidation, "validation",
+		fmt.Sprintf("--path contains %d credential file(s) that should not be published: %s", len(hits), sample),
+		"remove these files from the publish payload, OR pass --allow-sensitive if shipping them is intentional (e.g. a docs site demoing credential-file formats)")
 }
 
 // maxHTMLPublishTarballBytes 是 client 端 tar.gz 包体上限，对齐 OAPI 设计 20MB 约束。
@@ -178,14 +178,15 @@ func ensureIndexHTML(candidates []htmlPublishCandidate) error {
 			return nil
 		}
 	}
-	return appsFailedPreconditionParamError("--path", "--path is missing index.html").
-		WithHint("index.html is the app entrypoint; for a directory put index.html at the root, or pass a single file named index.html")
+	return output.ErrWithHint(output.ExitAPI, "validation",
+		"--path 中缺少 index.html",
+		"妙搭以 index.html 作为应用入口；目录形态把首页放在根目录命名 index.html，单文件形态把文件命名为 index.html")
 }
 
-func runHTMLPublish(ctx context.Context, fio fileio.FileIO, publisher appsHTMLPublishClient, spec appsHTMLPublishSpec) (map[string]interface{}, error) {
+func runHTMLPublish(ctx context.Context, fio fileio.FileIO, client appsHTMLPublishClient, spec appsHTMLPublishSpec) (map[string]interface{}, error) {
 	candidates, err := walkHTMLPublishCandidates(fio, spec.Path)
 	if err != nil {
-		return nil, err
+		return nil, output.Errorf(output.ExitAPI, "io", "scan --path %s: %v", spec.Path, err)
 	}
 	if err := ensureIndexHTML(candidates); err != nil {
 		return nil, err
@@ -195,24 +196,24 @@ func runHTMLPublish(ctx context.Context, fio fileio.FileIO, publisher appsHTMLPu
 		rawTotal += c.Size
 	}
 	if rawTotal > maxHTMLPublishRawBytes {
-		return nil, appsValidationParamError("--path",
-			"--path total raw bytes %d exceeds %d bytes limit (uncompressed pre-pack cap)", rawTotal, maxHTMLPublishRawBytes).
-			WithHint("reduce --path contents or choose a smaller subdirectory before packaging")
+		return nil, output.ErrWithHint(output.ExitAPI, "validation",
+			fmt.Sprintf("--path total raw bytes %d exceeds %d bytes limit (uncompressed pre-pack cap)", rawTotal, maxHTMLPublishRawBytes),
+			"在 tar+gzip 进入内存前拦截，避免 OOM；精简 --path 内容或选择更小的子目录")
 	}
 	tarball, err := buildHTMLPublishTarball(fio, candidates)
 	if err != nil {
-		return nil, err
+		return nil, output.Errorf(output.ExitAPI, "io", "pack: %v", err)
 	}
 
 	if tarball.Size > maxHTMLPublishTarballBytes {
-		return nil, appsValidationParamError("--path",
-			"packed tar.gz size %d bytes exceeds %d bytes limit", tarball.Size, maxHTMLPublishTarballBytes).
-			WithHint("reduce --path contents, remove unrelated large files, then retry")
+		return nil, output.ErrWithHint(output.ExitAPI, "validation",
+			fmt.Sprintf("packed tar.gz size %d bytes exceeds %d bytes limit", tarball.Size, maxHTMLPublishTarballBytes),
+			"请精简 --path 目录（去掉无关大文件 / 压缩资源）后重试；本期接口上限 20MB")
 	}
 
-	resp, err := publisher.HTMLPublish(ctx, spec.AppID, tarball)
+	resp, err := client.HTMLPublish(ctx, spec.AppID, tarball)
 	if err != nil {
-		return nil, client.WrapDoAPIError(err)
+		return nil, err
 	}
 
 	out := map[string]interface{}{}

shortcuts/apps/apps_html_publish_test.go

@@ -10,6 +10,8 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/larksuite/cli/internal/output"
 )
 
 type fakeAppsHTMLPublishClient struct {
@@ -103,11 +105,17 @@ func TestRunHTMLPublish_DirRequiresIndexHTML(t *testing.T) {
 	if err == nil {
 		t.Fatalf("expected error for missing index.html")
 	}
-	problem := requireAppsValidationProblem(t, err)
-	if !strings.Contains(problem.Message, "index.html") {
-		t.Fatalf("message missing 'index.html': %v", problem.Message)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError with detail, got %v", err)
 	}
-	if problem.Hint == "" {
+	if exitErr.Detail.Type != "validation" {
+		t.Fatalf("error.type = %q, want validation", exitErr.Detail.Type)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "index.html") {
+		t.Fatalf("message missing 'index.html': %v", exitErr.Detail.Message)
+	}
+	if exitErr.Detail.Hint == "" {
 		t.Fatalf("expected non-empty hint")
 	}
 	if len(fake.calls) != 0 {
@@ -145,7 +153,10 @@ func TestRunHTMLPublish_SingleFileRejectedIfNotNamedIndex(t *testing.T) {
 	if err == nil {
 		t.Fatalf("single-file path 'foo.html' should be rejected (not named index.html)")
 	}
-	requireAppsValidationProblem(t, err)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Type != "validation" {
+		t.Fatalf("expected ExitError type=validation, got %v", err)
+	}
 	if len(fake.calls) != 0 {
 		t.Fatalf("client must not be called when index.html missing")
 	}
@@ -188,11 +199,17 @@ func TestRunHTMLPublish_RejectsOversizeTarball(t *testing.T) {
 	if err == nil {
 		t.Fatalf("expected oversize error")
 	}
-	problem := requireAppsValidationProblem(t, err)
-	if !strings.Contains(problem.Message, "exceeds") {
-		t.Fatalf("message missing 'exceeds': %v", problem.Message)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError with detail, got %v", err)
 	}
-	if problem.Hint == "" {
+	if exitErr.Detail.Type != "validation" {
+		t.Fatalf("error.type = %q, want validation", exitErr.Detail.Type)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "exceeds") {
+		t.Fatalf("message missing 'exceeds': %v", exitErr.Detail.Message)
+	}
+	if exitErr.Detail.Hint == "" {
 		t.Fatalf("expected non-empty hint")
 	}
 	if len(fake.calls) != 0 {
@@ -320,12 +337,18 @@ func TestAppsHTMLPublish_SensitiveBlocksValidate(t *testing.T) {
 	if err == nil {
 		t.Fatalf("dry-run with sensitive file should fail")
 	}
-	problem := requireAppsValidationProblem(t, err)
-	if !strings.Contains(problem.Message, ".env") {
-		t.Fatalf("error message should list the offending file, got %q", problem.Message)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError with detail, got %v", err)
 	}
-	if !strings.Contains(problem.Hint, "--allow-sensitive") {
-		t.Fatalf("error hint should mention --allow-sensitive escape hatch, got %q", problem.Hint)
+	if exitErr.Detail.Type != "validation" {
+		t.Fatalf("error.type = %q, want validation", exitErr.Detail.Type)
+	}
+	if !strings.Contains(exitErr.Detail.Message, ".env") {
+		t.Fatalf("error message should list the offending file, got %q", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "--allow-sensitive") {
+		t.Fatalf("error hint should mention --allow-sensitive escape hatch, got %q", exitErr.Detail.Hint)
 	}
 }
 
@@ -415,9 +438,15 @@ func TestAppsHTMLPublish_SensitiveBlocksWhenPathIsCredentialParentDir(t *testing
 			if err == nil {
 				t.Fatalf("expected rejection when --path is %s/ (would leak %s), got success", tc.parent, tc.fileName)
 			}
-			problem := requireAppsValidationProblem(t, err)
-			if !strings.Contains(problem.Message, tc.wantSubstr) {
-				t.Fatalf("error message should name the leaked file, got %q", problem.Message)
+			var exitErr *output.ExitError
+			if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+				t.Fatalf("expected ExitError with detail, got %v", err)
+			}
+			if exitErr.Detail.Type != "validation" {
+				t.Fatalf("error.type = %q, want validation", exitErr.Detail.Type)
+			}
+			if !strings.Contains(exitErr.Detail.Message, tc.wantSubstr) {
+				t.Fatalf("error message should name the leaked file, got %q", exitErr.Detail.Message)
 			}
 		})
 	}
@@ -451,9 +480,15 @@ func TestAppsHTMLPublish_SensitiveBlocksWhenPathIsCredentialFileItself(t *testin
 	if err == nil {
 		t.Fatalf("expected rejection when --path points directly at .aws/credentials, got success")
 	}
-	problem := requireAppsValidationProblem(t, err)
-	if !strings.Contains(problem.Message, "credentials") {
-		t.Fatalf("error message should name the leaked file, got %q", problem.Message)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError with detail, got %v", err)
+	}
+	if exitErr.Detail.Type != "validation" {
+		t.Fatalf("error.type = %q, want validation", exitErr.Detail.Type)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "credentials") {
+		t.Fatalf("error message should name the leaked file, got %q", exitErr.Detail.Message)
 	}
 }
 
@@ -463,7 +498,11 @@ func TestAppsHTMLPublish_SensitiveBlocksWhenPathIsCredentialFileItself(t *testin
 func TestSensitiveCandidatesError_Truncation(t *testing.T) {
 	hits := []string{"a.env", "b.env", "c.env", "d.env", "e.env", "f.env", "g.env"}
 	err := sensitiveCandidatesError(hits)
-	msg := requireAppsValidationProblem(t, err).Message
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError with detail, got %v", err)
+	}
+	msg := exitErr.Detail.Message
 	if !strings.Contains(msg, "7 credential file(s)") {
 		t.Fatalf("message should report the full count, got %q", msg)
 	}
@@ -495,9 +534,15 @@ func TestRunHTMLPublish_RejectsOversizeRawCandidates(t *testing.T) {
 	if err == nil {
 		t.Fatalf("expected raw-size cap to fire")
 	}
-	problem := requireAppsValidationProblem(t, err)
-	if !strings.Contains(problem.Message, "raw") || !strings.Contains(problem.Message, "bytes") {
-		t.Fatalf("expected message to explain raw-byte cap, got %q", problem.Message)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError with detail, got %v", err)
+	}
+	if exitErr.Detail.Type != "validation" {
+		t.Fatalf("error.type = %q, want validation", exitErr.Detail.Type)
+	}
+	if !strings.Contains(exitErr.Detail.Message, "raw") || !strings.Contains(exitErr.Detail.Message, "bytes") {
+		t.Fatalf("expected message to explain raw-byte cap, got %q", exitErr.Detail.Message)
 	}
 	if len(fake.calls) != 0 {
 		t.Fatalf("client must not be called when raw cap hit")

shortcuts/apps/apps_init.go

@@ -14,8 +14,8 @@ import (
 	"strings"
 	"unicode"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/charcheck"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -27,8 +27,8 @@ const defaultInitBranch = "sprint/default"
 // the non-empty (`app sync`) path stays a single commit.
 const (
 	commitMsgAppCode   = "chore: initialize app project code"
-	commitMsgAppConfig = "chore: initialize app config"
-	commitMsgUpgrade   = "chore: initialize app repository"
+	commitMsgAppConfig = "chore: initialize miaoda app config"
+	commitMsgUpgrade   = "chore: initialize miaoda app repository"
 )
 
 // scaffold kinds returned by runScaffold and consumed by commitAndPushIfDirty.
@@ -49,11 +49,11 @@ const (
 // can swap in a fakeCommandRunner. Production uses execCommandRunner.
 var initRunner commandRunner = execCommandRunner{}
 
-// AppsInit initializes an app's code and local development environment.
+// AppsInit initializes a Miaoda app's code and local development environment.
 var AppsInit = common.Shortcut{
 	Service:     appsService,
 	Command:     "+init",
-	Description: "Initialize an app's code and local development environment",
+	Description: "Initialize a Miaoda app's code and local development environment",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +init --app-id <app_id> --dir <dir>",
@@ -72,14 +72,14 @@ var AppsInit = common.Shortcut{
 		// exit-1 (root.go handleRootError case 4), bypassing the structured
 		// envelope. The spec and the E2E assert exit-2 + a structured
 		// {"ok":false,"error":{...}} envelope for missing --app-id, so the empty
-		// check lives in Validate (typed validation error -> exit 2).
-		{Name: "app-id", Desc: "app ID"},
+		// check lives in Validate (output.ErrValidation -> ExitValidation=2).
+		{Name: "app-id", Desc: "Miaoda app ID"},
 		{Name: "dir", Desc: "clone target directory; absolute or relative path (default ./<app-id>)"},
 		{Name: "template", Desc: "code-init template for an empty repo; optional — if omitted, derived from the app's tech stack"},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		return nil
 	},
@@ -87,7 +87,7 @@ var AppsInit = common.Shortcut{
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		template := resolveTemplate(rctx, appID)
 		dry := common.NewDryRunAPI().
-			Desc("Initialize app code (credential-init, clone, checkout, npx code-init, optional commit/push)").
+			Desc("Initialize Miaoda app code (credential-init, clone, checkout, npx code-init, optional commit/push)").
 			Set("credential_init", fmt.Sprintf("apps +git-credential-init --app-id %s --format json", appID)).
 			Set("checkout", "git checkout "+defaultInitBranch).
 			Set("scaffold", fmt.Sprintf("empty repo: npx -y --prefer-online %s app init --template %s --app-id %s; non-empty: npx -y --prefer-online %s app sync + .spark/meta.json app_id patch + conditional skills sync --local", miaodaCLIPkg, template, appID, miaodaCLIPkg)).
@@ -152,14 +152,14 @@ func resolveTargetPath(rctx *common.RuntimeContext, appID string) (string, error
 	// path is a log-injection vector); charcheck additionally rejects dangerous
 	// Unicode (bidi overrides, zero-width) that IsControl does not.
 	if strings.IndexFunc(raw, unicode.IsControl) >= 0 {
-		return "", appsValidationParamError("--dir", "--dir must not contain control characters")
+		return "", output.ErrValidation("--dir must not contain control characters")
 	}
 	if err := charcheck.RejectControlChars(raw, "--dir"); err != nil {
-		return "", appsValidationParamError("--dir", "%v", err).WithCause(err)
+		return "", output.ErrValidation("%v", err)
 	}
 	abs, err := filepath.Abs(raw) //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); raw is control-char-validated above, and FileIO.ResolvePath cannot resolve a clone target (it rejects absolute paths).
 	if err != nil {
-		return "", appsValidationParamError("--dir", "--dir cannot be resolved: %v", err)
+		return "", output.ErrValidation("--dir cannot be resolved: %v", err)
 	}
 	return abs, nil
 }
@@ -173,25 +173,25 @@ func ensureEmptyDir(dir string) error {
 		return nil
 	}
 	if err != nil {
-		return appsValidationParamError("--dir", "--dir cannot be read: %v", err)
+		return output.ErrValidation("--dir cannot be read: %v", err)
 	}
 	if info.Mode()&os.ModeSymlink != 0 {
-		return appsValidationParamError("--dir", "--dir must not be a symlink: %q", dir)
+		return output.ErrValidation("--dir must not be a symlink: %q", dir)
 	}
 	if !info.IsDir() {
-		return appsValidationParamError("--dir", "--dir exists and is not a directory: %q", dir)
+		return output.ErrValidation("--dir exists and is not a directory: %q", dir)
 	}
 	entries, err := os.ReadDir(dir) //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); dir is the validated clone target, and FileIO has no ReadDir.
 	if err != nil {
-		return appsValidationParamError("--dir", "--dir cannot be read: %v", err)
+		return output.ErrValidation("--dir cannot be read: %v", err)
 	}
 	if len(entries) > 0 {
-		return appsValidationParamError("--dir", "target directory %q already exists and is not empty", dir)
+		return output.ErrValidation("target directory %q already exists and is not empty", dir)
 	}
 	return nil
 }
 
-// isAlreadyInitialized reports whether dir is an already-initialized app
+// isAlreadyInitialized reports whether dir is an already-initialized Miaoda app
 // repo, detected by the presence of <dir>/.spark/meta.json (regardless of its
 // app_id value). Used to short-circuit +init into a friendly no-op.
 func isAlreadyInitialized(dir string) bool {
@@ -209,11 +209,11 @@ func ensureMetaAppID(dir, appID string) error {
 		return nil
 	}
 	if err != nil {
-		return appsFileIOError(err, "read %s failed: %v", metaRelPath, err)
+		return output.Errorf(output.ExitAPI, "meta_write", "read %s failed: %v", metaRelPath, err)
 	}
 	var m map[string]interface{}
 	if err := json.Unmarshal(b, &m); err != nil {
-		return appsFileIOError(err, "parse %s failed: %v", metaRelPath, err)
+		return output.Errorf(output.ExitAPI, "meta_write", "parse %s failed: %v", metaRelPath, err)
 	}
 	if cur, _ := m["app_id"].(string); strings.TrimSpace(cur) != "" {
 		return nil
@@ -224,10 +224,10 @@ func ensureMetaAppID(dir, appID string) error {
 	m["app_id"] = appID
 	out, err := json.MarshalIndent(m, "", "  ")
 	if err != nil {
-		return appsFileIOError(err, "marshal %s failed: %v", metaRelPath, err)
+		return output.Errorf(output.ExitAPI, "meta_write", "marshal %s failed: %v", metaRelPath, err)
 	}
 	if err := os.WriteFile(path, append(out, '\n'), 0o644); err != nil { //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); path is under the validated clone dir, and FileIO.Save rejects absolute paths.
-		return appsFileIOError(err, "write %s failed: %v", metaRelPath, err)
+		return output.Errorf(output.ExitAPI, "meta_write", "write %s failed: %v", metaRelPath, err)
 	}
 	return nil
 }
@@ -244,7 +244,7 @@ func hasSteeringSkills(dir string) bool {
 func isEmptyRepo(ctx context.Context, dir string) (bool, error) {
 	stdout, stderr, err := initRunner.Run(ctx, dir, "git", "ls-files")
 	if err != nil {
-		return false, appsExternalToolError(err, "git ls-files failed: %s", gitErr(stderr, err))
+		return false, output.Errorf(output.ExitAPI, "git_ls_files", "git ls-files failed: %s", gitErr(stderr, err))
 	}
 	for _, line := range strings.Split(strings.TrimSpace(stdout), "\n") {
 		f := strings.TrimSpace(line)
@@ -274,19 +274,19 @@ func runScaffold(ctx context.Context, dir, appID, template string) (string, erro
 		// seed README.md — as empty. If other seed files (e.g. .gitignore) can
 		// appear, extend isEmptyRepo's allow-list accordingly.
 		if _, stderr, err := initRunner.Run(ctx, dir, "npx", "-y", "--prefer-online", miaodaCLIPkg, "app", "init", "--template", template, "--app-id", appID); err != nil {
-			return "", appsExternalToolError(err, "npx app init failed: %s", gitErr(stderr, err))
+			return "", output.Errorf(output.ExitAPI, "npx_app_init", "npx app init failed: %s", gitErr(stderr, err))
 		}
 		return scaffoldKindInit, nil
 	}
 	if _, stderr, err := initRunner.Run(ctx, dir, "npx", "-y", "--prefer-online", miaodaCLIPkg, "app", "sync"); err != nil {
-		return "", appsExternalToolError(err, "npx app sync failed: %s", gitErr(stderr, err))
+		return "", output.Errorf(output.ExitAPI, "npx_app_sync", "npx app sync failed: %s", gitErr(stderr, err))
 	}
 	if err := ensureMetaAppID(dir, appID); err != nil {
 		return "", err
 	}
 	if !hasSteeringSkills(dir) {
 		if _, stderr, err := initRunner.Run(ctx, dir, "npx", "-y", "--prefer-online", miaodaCLIPkg, "skills", "sync", "--local"); err != nil {
-			return "", appsExternalToolError(err, "npx skills sync failed: %s", gitErr(stderr, err))
+			return "", output.Errorf(output.ExitAPI, "npx_skills_sync", "npx skills sync failed: %s", gitErr(stderr, err))
 		}
 	}
 	return scaffoldKindUpgrade, nil
@@ -303,13 +303,13 @@ func parseRepoURLFromEnvelope(stdout string) (string, error) {
 		} `json:"data"`
 	}
 	if err := json.Unmarshal([]byte(stdout), &env); err != nil {
-		return "", appsSubprocessEnvelopeError("could not parse +git-credential-init output as JSON: %v", err)
+		return "", output.Errorf(output.ExitInternal, "credential_init", "could not parse +git-credential-init output as JSON: %v", err)
 	}
 	if !env.OK {
-		return "", appsSubprocessEnvelopeError("+git-credential-init reported failure")
+		return "", output.Errorf(output.ExitInternal, "credential_init", "+git-credential-init reported failure")
 	}
 	if strings.TrimSpace(env.Data.RepositoryURL) == "" {
-		return "", appsSubprocessEnvelopeError("+git-credential-init returned no repository_url")
+		return "", output.Errorf(output.ExitInternal, "credential_init", "+git-credential-init returned no repository_url")
 	}
 	return env.Data.RepositoryURL, nil
 }
@@ -324,13 +324,13 @@ func parseEnvFileFromEnvelope(stdout string) (string, error) {
 		} `json:"data"`
 	}
 	if err := json.Unmarshal([]byte(stdout), &env); err != nil {
-		return "", appsSubprocessEnvelopeError("could not parse +env-pull output as JSON: %v", err)
+		return "", output.Errorf(output.ExitInternal, "env_pull", "could not parse +env-pull output as JSON: %v", err)
 	}
 	if !env.OK {
-		return "", appsSubprocessEnvelopeError("+env-pull reported failure")
+		return "", output.Errorf(output.ExitInternal, "env_pull", "+env-pull reported failure")
 	}
 	if strings.TrimSpace(env.Data.EnvFile) == "" {
-		return "", appsSubprocessEnvelopeError("+env-pull returned no env_file")
+		return "", output.Errorf(output.ExitInternal, "env_pull", "+env-pull returned no env_file")
 	}
 	return env.Data.EnvFile, nil
 }
@@ -364,9 +364,7 @@ func validateRepoURLScheme(repoURL string) error {
 	if strings.HasPrefix(repoURL, "http://") || strings.HasPrefix(repoURL, "https://") {
 		return nil
 	}
-	// The URL comes from the +git-credential-init subprocess response, not user
-	// input, so a non-http(s) scheme is a broken upstream contract.
-	return appsSubprocessEnvelopeError(
+	return output.Errorf(output.ExitValidation, "validation",
 		"repository_url from +git-credential-init must be http(s); refusing %q", redactURLCredentials(repoURL))
 }
 
@@ -379,7 +377,7 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 	}
 
 	// Already-initialized short-circuit: a dir containing .spark/meta.json is an
-	// initialized app repo -> skip clone/scaffold/commit, but still refresh
+	// initialized Miaoda app repo -> skip clone/scaffold/commit, but still refresh
 	// the local env so a re-run picks up the latest startup env vars.
 	if isAlreadyInitialized(dir) {
 		initLogf(rctx, "Already initialized at %s — refreshing local environment", dir)
@@ -417,12 +415,12 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 	}
 
 	if _, err := exec.LookPath("git"); err != nil {
-		return appsFailedPreconditionError("git executable not found on PATH").
-			WithHint("install git and ensure it is on your PATH")
+		return output.ErrWithHint(output.ExitInternal, "dependency",
+			"git executable not found on PATH", "install git and ensure it is on your PATH")
 	}
 	if _, err := exec.LookPath("npx"); err != nil {
-		return appsFailedPreconditionError("npx executable not found on PATH").
-			WithHint("install Node.js (which provides npx) and ensure it is on your PATH")
+		return output.ErrWithHint(output.ExitInternal, "dependency",
+			"npx executable not found on PATH", "install Node.js (which provides npx) and ensure it is on your PATH")
 	}
 
 	if err := ensureEmptyDir(dir); err != nil {
@@ -440,11 +438,11 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 
 	initLogf(rctx, "Cloning into %s...", dir)
 	if _, stderr, err := initRunner.Run(ctx, "", "git", "clone", "--", repoURL, dir); err != nil {
-		return appsExternalToolError(err, "git clone failed: %s", gitErr(stderr, err))
+		return output.Errorf(output.ExitAPI, "git_clone", "git clone failed: %s", gitErr(stderr, err))
 	}
 	initLogf(rctx, "Checking out %s...", defaultInitBranch)
 	if _, stderr, err := initRunner.Run(ctx, dir, "git", "checkout", defaultInitBranch); err != nil {
-		return appsExternalToolError(err, "git checkout %s failed: %s", defaultInitBranch, gitErr(stderr, err))
+		return output.Errorf(output.ExitAPI, "git_checkout", "git checkout %s failed: %s", defaultInitBranch, gitErr(stderr, err))
 	}
 
 	initLogf(rctx, "Initializing app code (running miaoda-cli)...")
@@ -538,7 +536,7 @@ func pullEnv(ctx context.Context, rctx *common.RuntimeContext, appID, dir string
 func issueCredentials(ctx context.Context, rctx *common.RuntimeContext, appID string) (string, error) {
 	self, err := os.Executable()
 	if err != nil {
-		return "", errs.NewInternalError(errs.SubtypeUnknown, "cannot locate lark-cli executable: %v", err).WithCause(err)
+		return "", output.Errorf(output.ExitInternal, "internal", "cannot locate lark-cli executable: %v", err)
 	}
 	args := []string{"apps", "+git-credential-init", "--app-id", appID, "--format", "json"}
 	if as := strings.TrimSpace(rctx.Str("as")); as != "" {
@@ -546,9 +544,9 @@ func issueCredentials(ctx context.Context, rctx *common.RuntimeContext, appID st
 	}
 	stdout, stderr, err := initRunner.Run(ctx, "", self, args...)
 	if err != nil {
-		return "", appsExternalToolError(err, "apps +git-credential-init failed: %s", gitErr(stderr, err)).
-			WithHint("ensure apps +git-credential-init is available and you are logged in").
-			WithCause(err)
+		return "", output.ErrWithHint(output.ExitAPI, "credential_init",
+			fmt.Sprintf("apps +git-credential-init failed: %s", gitErr(stderr, err)),
+			"ensure apps +git-credential-init is available and you are logged in")
 	}
 	return parseRepoURLFromEnvelope(stdout)
 }
@@ -556,13 +554,13 @@ func issueCredentials(ctx context.Context, rctx *common.RuntimeContext, appID st
 // commitAndPushIfDirty commits and pushes only when the working tree has
 // changes; a clean tree is a no-op (returns false,false). For the empty-repo
 // init path (scaffoldKind == "init") it splits the scaffolded tree into two
-// commits — app project code, then app config (.spark/.agent) — skipping
+// commits — app project code, then Miaoda config (.spark/.agent) — skipping
 // either commit when that group has no changes (no empty commits). Other paths
 // commit once. Push is a single `git push origin <branch>` for all commits.
 func commitAndPushIfDirty(ctx context.Context, dir, scaffoldKind string) (committed, pushed bool, err error) {
 	status, stderr, runErr := initRunner.Run(ctx, dir, "git", "status", "--porcelain")
 	if runErr != nil {
-		return false, false, appsExternalToolError(runErr, "git status failed: %s", gitErr(stderr, runErr))
+		return false, false, output.Errorf(output.ExitAPI, "git_status", "git status failed: %s", gitErr(stderr, runErr))
 	}
 	if strings.TrimSpace(status) == "" {
 		return false, false, nil
@@ -597,7 +595,7 @@ func commitAndPushIfDirty(ctx context.Context, dir, scaffoldKind string) (commit
 
 	if _, se, e := initRunner.Run(ctx, dir, "git", "push", "origin", defaultInitBranch); e != nil {
 		return true, false, withAppsHint(
-			appsExternalToolError(e, "git push failed: %s", gitErr(se, e)),
+			output.Errorf(output.ExitAPI, "git_push", "git push failed: %s", gitErr(se, e)),
 			"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")
 	}
 	return true, true, nil
@@ -611,17 +609,17 @@ func commitAndPushIfDirty(ctx context.Context, dir, scaffoldKind string) (commit
 func stageAndCommit(ctx context.Context, dir, message string, pathspecs ...string) error {
 	addArgs := append([]string{"add", "-A", "--"}, pathspecs...)
 	if _, se, e := initRunner.Run(ctx, dir, "git", addArgs...); e != nil {
-		return appsExternalToolError(e, "git add failed: %s", gitErr(se, e))
+		return output.Errorf(output.ExitAPI, "git_add", "git add failed: %s", gitErr(se, e))
 	}
 	if _, se, e := initRunner.Run(ctx, dir, "git", "commit", "--no-verify", "-m", message); e != nil {
-		return appsExternalToolError(e, "git commit failed: %s", gitErr(se, e))
+		return output.Errorf(output.ExitAPI, "git_commit", "git commit failed: %s", gitErr(se, e))
 	}
 	return nil
 }
 
 // classifyPorcelain parses `git status --porcelain` output and partitions the
 // changed paths into the "app code" group (anything outside .spark/ and .agent/)
-// and the "app config" group (.spark/ and .agent/). It returns the exact
+// and the "Miaoda config" group (.spark/ and .agent/). It returns the exact
 // porcelain paths so callers can stage them verbatim: porcelain never lists
 // gitignored files, so `git add -- <these paths>` never trips git's ignored-path
 // error. (Naming an ignored dir explicitly — or combining a "." pathspec with
@@ -658,7 +656,7 @@ func porcelainPath(line string) string {
 	return p
 }
 
-// isConfigPath reports whether p is the app-config group: the .spark or
+// isConfigPath reports whether p is the Miaoda app-config group: the .spark or
 // .agent directory itself, or anything under them. ".sparkrc" is NOT config.
 func isConfigPath(p string) bool {
 	return p == ".spark" || p == ".agent" ||

shortcuts/apps/apps_init_test.go

@@ -17,7 +17,6 @@ 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/shortcuts/common"
@@ -835,7 +834,7 @@ func TestAppsInit_EmptyRepo_TwoCommits(t *testing.T) {
 		t.Fatalf("unexpected: %v", err)
 	}
 	msgs := commitMessages(f.calls)
-	want := []string{"chore: initialize app project code", "chore: initialize app config"}
+	want := []string{"chore: initialize app project code", "chore: initialize miaoda app config"}
 	if len(msgs) != 2 || msgs[0] != want[0] || msgs[1] != want[1] {
 		t.Fatalf("commit messages = %v, want %v", msgs, want)
 	}
@@ -896,7 +895,7 @@ func TestAppsInit_EmptyRepo_ConfigOnly_SingleCommit(t *testing.T) {
 		t.Fatalf("unexpected: %v", err)
 	}
 	msgs := commitMessages(f.calls)
-	if len(msgs) != 1 || msgs[0] != "chore: initialize app config" {
+	if len(msgs) != 1 || msgs[0] != "chore: initialize miaoda app config" {
 		t.Fatalf("commit messages = %v, want one config commit", msgs)
 	}
 }
@@ -916,7 +915,7 @@ func TestAppsInit_NonEmpty_SingleInitCommit(t *testing.T) {
 		t.Fatalf("unexpected: %v", err)
 	}
 	msgs := commitMessages(f.calls)
-	if len(msgs) != 1 || msgs[0] != "chore: initialize app repository" {
+	if len(msgs) != 1 || msgs[0] != "chore: initialize miaoda app repository" {
 		t.Fatalf("commit messages = %v, want one upgrade commit", msgs)
 	}
 	for _, c := range f.calls {
@@ -1467,28 +1466,3 @@ func TestAppsInit_Description_IsAboutCode(t *testing.T) {
 		t.Errorf("Description should mention app code: %q", AppsInit.Description)
 	}
 }
-
-// TestRunScaffold_SubprocessFailureIsExternalTool pins the typed
-// classification of an external-tool failure: a failing git subprocess
-// surfaces as internal/external_tool with the cause preserved.
-func TestRunScaffold_SubprocessFailureIsExternalTool(t *testing.T) {
-	cause := errors.New("exit status 128")
-	f := &fakeCommandRunner{results: map[string]fakeCallResult{
-		"git ls-files": {stderr: "fatal: not a git repository", err: cause},
-	}}
-	withFakeRunner(t, f)
-	_, err := runScaffold(context.Background(), t.TempDir(), "app_x", "nestjs-react-fullstack")
-	if err == nil {
-		t.Fatalf("expected error from failing git subprocess")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed problem, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeExternalTool {
-		t.Fatalf("classification = %s/%s, want internal/external_tool", p.Category, p.Subtype)
-	}
-	if !errors.Is(err, cause) {
-		t.Fatalf("cause chain not preserved: %v", err)
-	}
-}

shortcuts/apps/apps_list.go

@@ -12,7 +12,7 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsList lists apps visible to the calling user (cursor pagination).
+// AppsList lists Miaoda apps visible to the calling user (cursor pagination).
 //
 // Supports name fuzzy match (--keyword), ownership-dimension filter
 // (--ownership: all / mine / shared), and app-type filter (--app-type). See
@@ -22,7 +22,7 @@ import (
 var AppsList = common.Shortcut{
 	Service:     appsService,
 	Command:     "+list",
-	Description: "List apps visible to the calling user (cursor pagination)",
+	Description: "List Miaoda apps visible to the calling user (cursor pagination)",
 	Risk:        "read",
 	Tips: []string{
 		"Example: lark-cli apps +list",
@@ -42,7 +42,7 @@ var AppsList = common.Shortcut{
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			GET(apiBasePath + "/apps").
-			Desc("List apps").
+			Desc("List Miaoda apps").
 			Params(buildAppsListParams(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_release_create.go

@@ -9,15 +9,16 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsReleaseCreate creates a release for an app.
+// AppsReleaseCreate creates a release for a Miaoda app.
 var AppsReleaseCreate = common.Shortcut{
 	Service:     appsService,
 	Command:     "+release-create",
-	Description: "Create a release for an app (returns release_id for status polling)",
+	Description: "Create a release for a Miaoda app (returns release_id for status polling)",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +release-create --app-id <app_id>",
@@ -27,12 +28,12 @@ var AppsReleaseCreate = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", Required: true},
 		{Name: "branch", Desc: "release branch (server uses default if omitted)"},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		return nil
 	},

shortcuts/apps/apps_release_get.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -26,15 +27,15 @@ var AppsReleaseGet = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", Required: true},
 		{Name: "release-id", Desc: "release ID (the release_id returned by +release-create)", 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")
+			return output.ErrValidation("--app-id is required")
 		}
 		if strings.TrimSpace(rctx.Str("release-id")) == "" {
-			return appsValidationParamError("--release-id", "--release-id is required")
+			return output.ErrValidation("--release-id is required")
 		}
 		return nil
 	},
@@ -57,9 +58,6 @@ var AppsReleaseGet = common.Shortcut{
 		out := data
 		if release, ok := data["release"].(map[string]interface{}); ok {
 			out = release
-			if el, ok := data["error_logs"]; ok {
-				out["error_logs"] = el
-			}
 		}
 		rctx.OutFormat(out, nil, func(w io.Writer) {
 			fmt.Fprintf(w, "release_id: %v\nstatus: %v\ncreated_at: %v\nupdated_at: %v\n",

shortcuts/apps/apps_release_get_test.go

@@ -134,15 +134,13 @@ func TestAppsReleaseGetPrettyFailedErrorLogs(t *testing.T) {
 		URL:    "/open-apis/spark/v1/apps/app_x/releases/6",
 		Body: map[string]interface{}{
 			"code": 0, "msg": "",
-			"data": map[string]interface{}{
-				"release": map[string]interface{}{
-					"release_id": "6", "status": "failed",
-					"created_at": "1700000000000", "updated_at": "1700000000050",
-				},
+			"data": map[string]interface{}{"release": map[string]interface{}{
+				"release_id": "6", "status": "failed",
+				"created_at": "1700000000000", "updated_at": "1700000000050",
 				"error_logs": []interface{}{
 					map[string]interface{}{"step": "build", "error_log": "compile error"},
 				},
-			},
+			}},
 		},
 	})
 	if err := AppsReleaseGet.Execute(context.Background(), rctx); err != nil {
@@ -202,13 +200,11 @@ func TestAppsReleaseGetPrettyFailedEmptyLogs(t *testing.T) {
 	reg.Register(&httpmock.Stub{
 		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/releases/9",
 		Body: map[string]interface{}{"code": 0, "msg": "",
-			"data": map[string]interface{}{
-				"release": map[string]interface{}{
-					"release_id": "9", "status": "failed",
-					"created_at": "1700000000000", "updated_at": "1700000000050",
-				},
+			"data": map[string]interface{}{"release": map[string]interface{}{
+				"release_id": "9", "status": "failed",
+				"created_at": "1700000000000", "updated_at": "1700000000050",
 				"error_logs": []interface{}{},
-			}},
+			}}},
 	})
 	if err := AppsReleaseGet.Execute(context.Background(), rctx); err != nil {
 		t.Fatalf("Execute() = %v", err)
@@ -218,69 +214,6 @@ func TestAppsReleaseGetPrettyFailedEmptyLogs(t *testing.T) {
 	}
 }
 
-func TestAppsReleaseGetJSONErrorLogsPassthrough(t *testing.T) {
-	rctx, stdoutBuf, reg := newStatusRuntimeContext(t, "app_x", "6")
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/releases/6",
-		Body: map[string]interface{}{"code": 0, "msg": "",
-			"data": map[string]interface{}{
-				"release": map[string]interface{}{
-					"release_id": "6", "status": "failed",
-					"created_at": "1700000000000", "updated_at": "1700000000050",
-				},
-				"error_logs": []interface{}{
-					map[string]interface{}{"step": "build", "error_log": "compile error"},
-				},
-			}},
-	})
-	if err := AppsReleaseGet.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	var env struct {
-		OK   bool                   `json:"ok"`
-		Data map[string]interface{} `json:"data"`
-	}
-	if err := json.Unmarshal(stdoutBuf.Bytes(), &env); err != nil {
-		t.Fatalf("unmarshal: %v\nraw: %s", err, stdoutBuf.String())
-	}
-	logs, ok := env.Data["error_logs"].([]interface{})
-	if !ok || len(logs) != 1 {
-		t.Fatalf("JSON must passthrough data.error_logs, got: %v", env.Data["error_logs"])
-	}
-	first, _ := logs[0].(map[string]interface{})
-	if first["step"] != "build" || first["error_log"] != "compile error" {
-		t.Errorf("error_logs content mismatch: %v", logs[0])
-	}
-	// flattened release fields must still be present alongside error_logs
-	if env.Data["release_id"] != "6" || env.Data["status"] != "failed" {
-		t.Errorf("flattened release fields missing: %v", env.Data)
-	}
-}
-
-func TestAppsReleaseGetJSONNoErrorLogsKeyWhenAbsent(t *testing.T) {
-	rctx, stdoutBuf, reg := newStatusRuntimeContext(t, "app_x", "5")
-	reg.Register(&httpmock.Stub{
-		Method: "GET", URL: "/open-apis/spark/v1/apps/app_x/releases/5",
-		Body: map[string]interface{}{"code": 0, "msg": "",
-			"data": map[string]interface{}{"release": map[string]interface{}{
-				"release_id": "5", "status": "finished",
-				"created_at": "1700000000000", "updated_at": "1700000000001",
-			}}},
-	})
-	if err := AppsReleaseGet.Execute(context.Background(), rctx); err != nil {
-		t.Fatalf("Execute() = %v", err)
-	}
-	var env struct {
-		Data map[string]interface{} `json:"data"`
-	}
-	if err := json.Unmarshal(stdoutBuf.Bytes(), &env); err != nil {
-		t.Fatalf("unmarshal: %v\nraw: %s", err, stdoutBuf.String())
-	}
-	if _, present := env.Data["error_logs"]; present {
-		t.Errorf("error_logs key must be absent when API omits it, got: %v", env.Data)
-	}
-}
-
 func TestAppsReleaseGetPrettyCommitID(t *testing.T) {
 	rctx, stdoutBuf, reg := newStatusRuntimeContext(t, "app_x", "10")
 	rctx.Format = "pretty"

shortcuts/apps/apps_release_list.go

@@ -14,11 +14,11 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsReleaseList lists an app's release history (most recent first).
+// AppsReleaseList lists a Miaoda app's release history (most recent first).
 var AppsReleaseList = common.Shortcut{
 	Service:     appsService,
 	Command:     "+release-list",
-	Description: "List an app's release history (most recent first)",
+	Description: "List a Miaoda app's release history (most recent first)",
 	Risk:        "read",
 	Tips: []string{
 		"Example: lark-cli apps +release-list --app-id <app_id>",
@@ -28,14 +28,14 @@ var AppsReleaseList = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", Required: true},
 		{Name: "status", Enum: []string{"publishing", "finished", "failed"}, Desc: "filter by release status: publishing | finished | failed"},
 		{Name: "page-size", Type: "int", Default: "20", Desc: "page size (max 500)"},
 		{Name: "page-token", Desc: "pagination cursor from a previous response"},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		return nil
 	},

shortcuts/apps/apps_session_create.go

@@ -9,15 +9,16 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsSessionCreate creates a new session under an existing app.
+// AppsSessionCreate creates a new session under an existing Miaoda app.
 var AppsSessionCreate = common.Shortcut{
 	Service:     appsService,
 	Command:     "+session-create",
-	Description: "Create a session under an app",
+	Description: "Create a session under a Miaoda app",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +session-create --app-id <app_id>",
@@ -30,14 +31,14 @@ var AppsSessionCreate = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			POST(sessionsPath(rctx.Str("app-id"))).
-			Desc("Create a session under an app")
+			Desc("Create a session under a Miaoda app")
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		data, err := rctx.CallAPITyped("POST", sessionsPath(rctx.Str("app-id")), nil, nil)

shortcuts/apps/apps_session_get.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -32,10 +33,10 @@ var AppsSessionGet = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		if strings.TrimSpace(rctx.Str("session-id")) == "" {
-			return appsValidationParamError("--session-id", "--session-id is required")
+			return output.ErrValidation("--session-id is required")
 		}
 		return nil
 	},

shortcuts/apps/apps_session_list.go

@@ -12,11 +12,11 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsSessionList lists sessions under an app (cursor pagination, single page).
+// AppsSessionList lists sessions under a Miaoda app (cursor pagination, single page).
 var AppsSessionList = common.Shortcut{
 	Service:     appsService,
 	Command:     "+session-list",
-	Description: "List sessions under an app (cursor pagination)",
+	Description: "List sessions under a Miaoda app (cursor pagination)",
 	Risk:        "read",
 	Tips: []string{
 		"Example: lark-cli apps +session-list --app-id <app_id>",
@@ -32,14 +32,14 @@ var AppsSessionList = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			GET(sessionsPath(rctx.Str("app-id"))).
-			Desc("List sessions under an app").
+			Desc("List sessions under a Miaoda app").
 			Params(buildSessionListParams(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_session_stop.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -34,13 +35,13 @@ var AppsSessionStop = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		if strings.TrimSpace(rctx.Str("session-id")) == "" {
-			return appsValidationParamError("--session-id", "--session-id is required")
+			return output.ErrValidation("--session-id is required")
 		}
 		if strings.TrimSpace(rctx.Str("turn-id")) == "" {
-			return appsValidationParamError("--turn-id", "--turn-id is required")
+			return output.ErrValidation("--turn-id is required")
 		}
 		return nil
 	},

shortcuts/apps/apps_update.go

@@ -9,15 +9,16 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsUpdate partially updates an app's name / description.
+// AppsUpdate partially updates a Miaoda app's name / description.
 var AppsUpdate = common.Shortcut{
 	Service:     appsService,
 	Command:     "+update",
-	Description: "Partially update an app (only provided fields are sent)",
+	Description: "Partially update a Miaoda app (only provided fields are sent)",
 	Risk:        "write",
 	Tips: []string{
 		`Example: lark-cli apps +update --app-id <app_id> --name "新名称"`,
@@ -33,15 +34,11 @@ var AppsUpdate = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
-			return appsValidationParamError("--app-id", "--app-id is required")
+			return output.ErrValidation("--app-id is required")
 		}
 		body := buildAppsUpdateBody(rctx)
 		if len(body) == 0 {
-			return appsValidationError("provide at least one of --name or --description").
-				WithParams(
-					appsInvalidParam("--name", "provide at least one of --name or --description"),
-					appsInvalidParam("--description", "provide at least one of --name or --description"),
-				)
+			return output.ErrValidation("provide at least one of --name or --description")
 		}
 		return nil
 	},
@@ -49,7 +46,7 @@ var AppsUpdate = common.Shortcut{
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			PATCH(fmt.Sprintf("%s/apps/%s", apiBasePath, validate.EncodePathSegment(appID))).
-			Desc("Update an app").
+			Desc("Update a Miaoda app").
 			Body(buildAppsUpdateBody(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/common.go

@@ -4,28 +4,30 @@
 package apps
 
 import (
+	"errors"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
 )
 
 // appsService 是 CLI 命令的 service 前缀（lark-cli apps ...）。
 const appsService = "apps"
 
-// apiBasePath is the registered OAPI prefix for the apps domain.
+// apiBasePath is the registered OAPI prefix for the Miaoda apps domain.
 const apiBasePath = "/open-apis/spark/v1"
 
 // appIDListHint is the shared recovery hint for commands whose most likely
 // failure cause is a wrong/inaccessible --app-id. It points at +list to find
-// the correct app id. The app_/cli_ format rule is taught in
+// the correct Miaoda app id. The app_/cli_ format rule is taught in
 // lark-apps SKILL.md ("app_id 获取"); the hint stays lean and does not repeat it.
 const appIDListHint = "verify --app-id is correct and you have access to the app; list your apps with `lark-cli apps +list`"
 
-// withAppsHint attaches an actionable next-step hint to a typed failure,
-// preserving its original classification (subtype/code/log_id). A hint already
-// present on the error is kept (the upstream wording wins); only an empty hint
-// is filled in. Mirrors drive.appendDriveExportRecoveryHint. err==nil and
-// untyped errors pass through unchanged.
+// withAppsHint attaches an actionable next-step hint to a failure returned by
+// CallAPI, preserving its original classification (typed subtype/code/log_id or
+// legacy detail). A hint already present on the error is kept (the upstream
+// wording wins); only an empty hint is filled in. Mirrors
+// drive.appendDriveExportRecoveryHint. err==nil passes through.
 func withAppsHint(err error, hint string) error {
 	if err == nil {
 		return nil
@@ -37,5 +39,14 @@ func withAppsHint(err error, hint string) error {
 		}
 		return err
 	}
+	// Legacy *output.ExitError fallback: fill the hint in place, preserving the
+	// original class / exit code rather than downgrading the error.
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) && exitErr.Detail != nil {
+		if strings.TrimSpace(exitErr.Detail.Hint) == "" {
+			exitErr.Detail.Hint = hint
+		}
+		return err
+	}
 	return err
 }

shortcuts/apps/common_test.go

@@ -7,7 +7,7 @@ import (
 	"errors"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
 )
 
 func TestWithAppsHint(t *testing.T) {
@@ -17,40 +17,46 @@ func TestWithAppsHint(t *testing.T) {
 		}
 	})
 
-	t.Run("empty hint gets filled, classification preserved", func(t *testing.T) {
-		in := errs.NewAPIError(errs.SubtypeNotFound, "boom").WithCode(404)
+	t.Run("empty hint gets filled, code/type preserved", func(t *testing.T) {
+		in := &output.ExitError{Code: 1, Detail: &output.ErrDetail{Type: "api_error", Message: "boom"}}
 		out := withAppsHint(in, "run +release-list")
-		p, ok := errs.ProblemOf(out)
-		if !ok {
-			t.Fatalf("returned error is not typed: %T", out)
+		var exitErr *output.ExitError
+		if !errors.As(out, &exitErr) {
+			t.Fatalf("returned error is not *output.ExitError: %T", out)
 		}
-		if p.Hint != "run +release-list" {
-			t.Errorf("Hint = %q, want %q", p.Hint, "run +release-list")
+		if exitErr.Detail.Hint != "run +release-list" {
+			t.Errorf("Hint = %q, want %q", exitErr.Detail.Hint, "run +release-list")
 		}
-		if p.Subtype != errs.SubtypeNotFound || p.Code != 404 || p.Message != "boom" {
-			t.Errorf("subtype/code/message mutated: subtype=%q code=%d msg=%q", p.Subtype, p.Code, p.Message)
+		if exitErr.Code != 1 || exitErr.Detail.Type != "api_error" || exitErr.Detail.Message != "boom" {
+			t.Errorf("code/type/message mutated: code=%d type=%q msg=%q", exitErr.Code, exitErr.Detail.Type, exitErr.Detail.Message)
 		}
 	})
 
 	t.Run("existing hint is preserved, not clobbered", func(t *testing.T) {
-		in := errs.NewAPIError(errs.SubtypeUnknown, "boom").WithHint("original hint")
+		in := output.ErrWithHint(1, "api_error", "boom", "original hint")
 		out := withAppsHint(in, "new hint")
-		p, _ := errs.ProblemOf(out)
-		if p.Hint != "original hint" {
-			t.Errorf("Hint = %q, want preserved %q", p.Hint, "original hint")
+		var exitErr *output.ExitError
+		if !errors.As(out, &exitErr) {
+			t.Fatalf("returned error is not *output.ExitError: %T", out)
+		}
+		if exitErr.Detail.Hint != "original hint" {
+			t.Errorf("Hint = %q, want preserved %q", exitErr.Detail.Hint, "original hint")
 		}
 	})
 
 	t.Run("blank-whitespace hint is treated as empty and filled", func(t *testing.T) {
-		in := errs.NewAPIError(errs.SubtypeUnknown, "boom").WithHint("   ")
+		in := output.ErrWithHint(1, "api_error", "boom", "   ")
 		out := withAppsHint(in, "filled hint")
-		p, _ := errs.ProblemOf(out)
-		if p.Hint != "filled hint" {
-			t.Errorf("Hint = %q, want %q", p.Hint, "filled hint")
+		var exitErr *output.ExitError
+		if !errors.As(out, &exitErr) {
+			t.Fatalf("returned error is not *output.ExitError: %T", out)
+		}
+		if exitErr.Detail.Hint != "filled hint" {
+			t.Errorf("Hint = %q, want %q", exitErr.Detail.Hint, "filled hint")
 		}
 	})
 
-	t.Run("untyped error returned unchanged, no panic", func(t *testing.T) {
+	t.Run("unrecognized error type returned unchanged, no panic", func(t *testing.T) {
 		in := errors.New("plain")
 		out := withAppsHint(in, "ignored")
 		if out == nil || out.Error() != "plain" {

shortcuts/apps/db_common.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 )
 
@@ -36,7 +37,7 @@ func appDbEnvCreatePath(appID string) string {
 func requireAppID(raw string) (string, error) {
 	id := strings.TrimSpace(raw)
 	if id == "" {
-		return "", appsValidationParamError("--app-id", "--app-id is required")
+		return "", output.ErrValidation("--app-id is required")
 	}
 	return id, nil
 }

shortcuts/apps/git_credential.go

@@ -6,6 +6,7 @@ package apps
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -21,11 +22,10 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/keychain"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/apps/gitcred"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -35,12 +35,12 @@ const gitCredentialIssuePath = apiBasePath + "/apps/:app_id/git_info"
 
 // gitCredentialIssueHint is the actionable next-step attached to a failed
 // Git-credential issuance. A 5xx is flagged retryable separately at the call site.
-const gitCredentialIssueHint = "failed to issue the Git credential: verify --app-id is correct and you have developer access to this app; a 5xx is a transient server error and is safe to retry"
+const gitCredentialIssueHint = "failed to issue the Git credential: verify --app-id is correct and you have developer access to this Miaoda app; a 5xx is a transient server error and is safe to retry"
 
 var AppsGitCredentialInit = common.Shortcut{
 	Service:     appsService,
 	Command:     "+git-credential-init",
-	Description: "Initialize Git credentials and a URL-scoped Git helper for an app repository",
+	Description: "Initialize Git credentials and a URL-scoped Git helper for a Miaoda app repository",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +git-credential-init --app-id <app_id>",
@@ -49,22 +49,19 @@ var AppsGitCredentialInit = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", 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")
+			return output.ErrValidation("--app-id is required")
 		}
-		if err := validate.ResourceName(strings.TrimSpace(rctx.Str("app-id")), "--app-id"); err != nil {
-			return appsValidationParamError("--app-id", "%v", err).WithCause(err)
-		}
-		return nil
+		return validate.ResourceName(strings.TrimSpace(rctx.Str("app-id")), "--app-id")
 	},
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			GET(gitCredentialIssuePath).
-			Desc("Issue an app Git repository PAT").
+			Desc("Issue a Miaoda Git repository PAT").
 			Set("mode", "api-plus-local-setup").
 			Set("action", "initialize_local_git_credential").
 			Set("app_id", appID).
@@ -81,7 +78,7 @@ var AppsGitCredentialInit = common.Shortcut{
 		manager := newGitCredentialManager(appID, rctx.Factory.Keychain, runtimeIssuer{rctx: rctx})
 		result, err := manager.Init(ctx, profileFromConfig(rctx.Config), appID)
 		if err != nil {
-			return gitCredentialLocalError("Initialize local app Git credential", err)
+			return gitCredentialLocalError("Initialize local Miaoda Git credential", err)
 		}
 		payload := map[string]interface{}{
 			"app_id":         result.AppID,
@@ -119,7 +116,7 @@ var AppsGitCredentialInit = common.Shortcut{
 var AppsGitCredentialRemove = common.Shortcut{
 	Service:     appsService,
 	Command:     "+git-credential-remove",
-	Description: "Remove local Git credentials and the URL-scoped Git helper for an app repository",
+	Description: "Remove local Git credentials and the URL-scoped Git helper for a Miaoda app repository",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +git-credential-remove --app-id <app_id>",
@@ -128,16 +125,13 @@ var AppsGitCredentialRemove = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", 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")
+			return output.ErrValidation("--app-id is required")
 		}
-		if err := validate.ResourceName(strings.TrimSpace(rctx.Str("app-id")), "--app-id"); err != nil {
-			return appsValidationParamError("--app-id", "%v", err).WithCause(err)
-		}
-		return nil
+		return validate.ResourceName(strings.TrimSpace(rctx.Str("app-id")), "--app-id")
 	},
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		appID := strings.TrimSpace(rctx.Str("app-id"))
@@ -159,7 +153,7 @@ var AppsGitCredentialRemove = common.Shortcut{
 		manager := newGitCredentialManager(appID, rctx.Factory.Keychain, nil)
 		result, err := manager.Remove(ctx, profileFromConfig(rctx.Config), appID)
 		if err != nil {
-			return gitCredentialLocalError("Remove local app Git credential", err)
+			return gitCredentialLocalError("Remove local Miaoda Git credential", err)
 		}
 		payload := map[string]interface{}{
 			"app_id":  result.AppID,
@@ -193,7 +187,7 @@ var AppsGitCredentialRemove = common.Shortcut{
 var AppsGitCredentialList = common.Shortcut{
 	Service:     appsService,
 	Command:     "+git-credential-list",
-	Description: "List local Git credentials for app repositories",
+	Description: "List local Git credentials for Miaoda app repositories",
 	Risk:        "read",
 	Tips: []string{
 		"Example: lark-cli apps +git-credential-list",
@@ -215,7 +209,7 @@ var AppsGitCredentialList = common.Shortcut{
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		records, err := listGitCredentialRecords(rctx.Factory.Keychain, time.Now)
 		if err != nil {
-			return gitCredentialLocalError("List local app Git credentials", err)
+			return gitCredentialLocalError("List local Miaoda Git credentials", err)
 		}
 		payload := map[string]interface{}{
 			"count":       len(records),
@@ -252,7 +246,7 @@ func InstallOnApps(parent *cobra.Command, f *cmdutil.Factory) {
 func newGitCredentialHelperCommand(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:    "git-credential-helper get|store|erase",
-		Short:  "Git credential helper for app repositories",
+		Short:  "Git credential helper for Miaoda app repositories",
 		Hidden: true,
 		Args:   cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -260,7 +254,7 @@ func newGitCredentialHelperCommand(f *cmdutil.Factory) *cobra.Command {
 			return runGitCredentialHelper(cmd.Context(), f, strings.TrimSpace(appID), args[0])
 		},
 	}
-	cmd.Flags().String("app-id", "", "app ID")
+	cmd.Flags().String("app-id", "", "Miaoda app ID")
 	_ = cmd.Flags().MarkHidden("app-id")
 	return cmd
 }
@@ -274,7 +268,7 @@ func (i runtimeIssuer) Issue(ctx context.Context, appID string, profile gitcred.
 		HttpMethod: http.MethodGet,
 		ApiPath:    issuePath(appID),
 	})
-	data, err := parseIssueCredentialData(resp, err, i.rctx.APIClassifyContext())
+	data, err := parseIssueCredentialData(resp, err)
 	if err != nil {
 		return nil, err
 	}
@@ -291,8 +285,7 @@ func (i factoryIssuer) Issue(ctx context.Context, appID string, profile gitcred.
 		return nil, err
 	}
 	if cfg.UserOpenId == "" {
-		return nil, errs.NewAuthenticationError(errs.SubtypeTokenMissing, "not logged in").
-			WithHint("run `lark-cli auth login --scope \"spark:app:read\"`")
+		return nil, output.ErrAuth("not logged in: run `lark-cli auth login --scope \"spark:app:read\"`")
 	}
 	ac, err := i.f.NewAPIClientWithConfig(cfg)
 	if err != nil {
@@ -303,11 +296,7 @@ func (i factoryIssuer) Issue(ctx context.Context, appID string, profile gitcred.
 		ApiPath:    issuePath(appID),
 	}
 	resp, err := ac.DoSDKRequest(ctx, req, core.AsUser)
-	data, err := parseIssueCredentialData(resp, err, errclass.ClassifyContext{
-		Brand:    string(cfg.Brand),
-		AppID:    cfg.AppID,
-		Identity: string(core.AsUser),
-	})
+	data, err := parseIssueCredentialData(resp, err)
 	if err != nil {
 		return nil, err
 	}
@@ -425,11 +414,13 @@ func gitCredentialLocalError(action string, err error) error {
 	if err == nil {
 		return nil
 	}
-	// Typed errors pass through unchanged; everything the apps domain and the
-	// shared runtime produce is typed, so there is no legacy envelope to forward.
 	if _, ok := errs.UnwrapTypedError(err); ok {
 		return err
 	}
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) {
+		return err
+	}
 	return &errs.ConfigError{Problem: errs.Problem{
 		Category: errs.CategoryConfig,
 		Subtype:  errs.SubtypeInvalidConfig,
@@ -457,43 +448,64 @@ func issuedFromData(appID string, data map[string]interface{}) (*gitcred.IssuedC
 		issued.AppID = appID
 	}
 	if issued.GitHTTPURL == "" {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response missing gitURL")
+		return nil, output.Errorf(output.ExitAPI, "api_error", "Issue Miaoda Git credential: response missing gitURL")
 	}
 	if issued.PAT == "" {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response missing token")
+		return nil, output.Errorf(output.ExitAPI, "api_error", "Issue Miaoda Git credential: response missing token")
 	}
 	return issued, nil
 }
 
-// parseIssueCredentialData turns the git-credential issue response into the
-// credential data map. A standard Lark envelope (top-level "code") and any
-// HTTP error status route through the shared response classifier, so generic
-// codes (missing scope, app not authorized) and 5xx statuses keep their
-// canonical category/subtype/retryable classification. The endpoint's
-// non-standard success shapes — direct git info or a BaseResp wrapper — are
-// handled locally.
-func parseIssueCredentialData(resp *larkcore.ApiResp, err error, cc errclass.ClassifyContext) (map[string]any, error) {
+func parseIssueCredentialData(resp *larkcore.ApiResp, err error) (map[string]any, error) {
 	if err != nil {
-		return nil, client.WrapDoAPIError(err)
+		return nil, err
 	}
 	detail := logIDDetail(resp)
 	if resp == nil || len(resp.RawBody) == 0 {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"Issue app Git credential: empty response body")
+		return nil, &errs.InternalError{Problem: errs.Problem{
+			Category: errs.CategoryInternal,
+			Subtype:  errs.SubtypeUnknown,
+			Message:  "Issue Miaoda Git credential: empty response body",
+		}}
 	}
 	var result map[string]any
-	jsonErr := json.Unmarshal(resp.RawBody, &result)
-	_, hasCode := result["code"]
-	if jsonErr != nil || hasCode || resp.StatusCode >= http.StatusBadRequest {
-		data, cerr := common.ClassifyAPIResponseWith(resp, cc)
-		if cerr != nil {
-			return nil, withAppsHint(cerr, gitCredentialIssueHint)
+	if jsonErr := json.Unmarshal(resp.RawBody, &result); jsonErr != nil {
+		return nil, &errs.InternalError{Problem: errs.Problem{
+			Category: errs.CategoryInternal,
+			Subtype:  errs.SubtypeUnknown,
+			Message:  fmt.Sprintf("Issue Miaoda Git credential: unmarshal response: %s", jsonErr),
+		}, Cause: jsonErr}
+	}
+	if resp.StatusCode >= http.StatusBadRequest {
+		msg := firstString(result, "msg", "message")
+		if msg == "" {
+			msg = fmt.Sprintf("HTTP %d", resp.StatusCode)
 		}
-		if data != nil {
+		return nil, &errs.APIError{Problem: errs.Problem{
+			Category:  errs.CategoryAPI,
+			Subtype:   errs.SubtypeUnknown,
+			Code:      resp.StatusCode,
+			Message:   msg,
+			LogID:     logIDString(resp),
+			Hint:      gitCredentialIssueHint,
+			Retryable: resp.StatusCode >= http.StatusInternalServerError,
+		}}
+	}
+	if _, hasCode := result["code"]; hasCode {
+		code := firstInt64(result, "code")
+		if code != 0 {
+			return nil, &errs.APIError{Problem: errs.Problem{
+				Category: errs.CategoryAPI,
+				Subtype:  errs.SubtypeUnknown,
+				Code:     int(code),
+				Message:  firstString(result, "msg", "message"),
+				LogID:    logIDString(resp),
+				Hint:     gitCredentialIssueHint,
+			}}
+		}
+		if data, ok := result["data"].(map[string]any); ok {
 			result = data
 		}
-		// data == nil: a code==0 envelope whose fields sit beside "code" instead
-		// of under "data" — keep the locally-unmarshalled top-level object.
 	} else if err := checkGitInfoBaseResp(result, logIDString(resp)); err != nil {
 		return nil, err
 	}
@@ -522,11 +534,13 @@ func checkGitInfoBaseResp(result map[string]any, logID string) error {
 		if message == "" {
 			message = "Git credential API returned non-zero BaseResp status"
 		}
-		baseErr := errs.NewAPIError(errs.SubtypeUnknown, "Issue app Git credential: %s", message).WithCode(int(code))
-		if logID != "" {
-			baseErr = baseErr.WithLogID(logID)
-		}
-		return baseErr
+		return &errs.APIError{Problem: errs.Problem{
+			Category: errs.CategoryAPI,
+			Subtype:  errs.SubtypeUnknown,
+			Code:     int(code),
+			Message:  "Issue Miaoda Git credential: " + message,
+			LogID:    logID,
+		}}
 	}
 	return nil
 }
@@ -564,9 +578,6 @@ func firstInt64(data map[string]interface{}, keys ...string) int64 {
 			return int64(v)
 		case float64:
 			return int64(v)
-		case json.Number:
-			n, _ := v.Int64()
-			return n
 		case string:
 			n, _ := strconv.ParseInt(strings.TrimSpace(v), 10, 64)
 			return n

shortcuts/apps/git_credential_storage.go

@@ -5,6 +5,7 @@ package apps
 
 import (
 	"errors"
+	"fmt"
 	"net/url"
 	"os"
 	"path/filepath"
@@ -34,7 +35,7 @@ func (gitCredentialAppStorage) ListAppIDs() ([]string, error) {
 		if errors.Is(err, os.ErrNotExist) {
 			return []string{}, nil
 		}
-		return nil, appsStorageError(err, "apps storage: read root: %v", err)
+		return nil, fmt.Errorf("apps storage: read root: %w", err)
 	}
 	appIDs := make([]string, 0, len(entries))
 	for _, e := range entries {

shortcuts/apps/git_credential_test.go

@@ -25,8 +25,8 @@ import (
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/apps/gitcred"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -213,7 +213,7 @@ func TestParseIssueCredentialDataAcceptsDirectBaseRespShape(t *testing.T) {
 			"expiredTime":1780050600,
 			"BaseResp":{"StatusCode":0,"StatusMessage":"ok"}
 		}`),
-	}, nil, errclass.ClassifyContext{})
+	}, nil)
 	if err != nil {
 		t.Fatalf("parseIssueCredentialData returned error: %v", err)
 	}
@@ -699,7 +699,7 @@ func assertStringSliceEqual(t *testing.T, got, want []string) {
 
 func TestGitCredentialLocalErrorWrapsOnlyPlainErrors(t *testing.T) {
 	plain := errors.New("git config failed")
-	wrapped := gitCredentialLocalError("List local app Git credentials", plain)
+	wrapped := gitCredentialLocalError("List local Miaoda Git credentials", plain)
 	var configErr *errs.ConfigError
 	if !errors.As(wrapped, &configErr) {
 		t.Fatalf("plain local error wrapped as %T, want *errs.ConfigError", wrapped)
@@ -717,9 +717,9 @@ func TestGitCredentialLocalErrorWrapsOnlyPlainErrors(t *testing.T) {
 		t.Fatalf("typed error was rewrapped: %#v", got)
 	}
 
-	validationErr := errs.NewValidationError(errs.SubtypeInvalidArgument, "bad app")
-	if got := gitCredentialLocalError("action", validationErr); got != error(validationErr) {
-		t.Fatalf("typed validation error was rewrapped: %#v", got)
+	exitErr := output.ErrValidation("bad app")
+	if got := gitCredentialLocalError("action", exitErr); got != exitErr {
+		t.Fatalf("legacy output error was rewrapped: %#v", got)
 	}
 
 	if got := gitCredentialLocalError("action", nil); got != nil {
@@ -925,43 +925,43 @@ func TestGitCredentialHelpersAndParsers(t *testing.T) {
 }
 
 func TestParseIssueCredentialDataErrors(t *testing.T) {
-	if _, err := parseIssueCredentialData(nil, errors.New("transport failed"), errclass.ClassifyContext{}); err == nil {
+	if _, err := parseIssueCredentialData(nil, errors.New("transport failed")); err == nil {
 		t.Fatal("parseIssueCredentialData transport error returned nil")
 	}
-	if _, err := parseIssueCredentialData(nil, nil, errclass.ClassifyContext{}); err == nil {
+	if _, err := parseIssueCredentialData(nil, nil); err == nil {
 		t.Fatal("parseIssueCredentialData nil response returned nil")
 	}
-	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte("{bad json")}, nil, errclass.ClassifyContext{}); err == nil {
+	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte("{bad json")}, nil); err == nil {
 		t.Fatal("parseIssueCredentialData bad json returned nil")
 	}
 	header := http.Header{"X-Tt-Logid": []string{"log_x"}}
-	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusBadRequest, RawBody: []byte(`{"msg":"bad request"}`), Header: header}, nil, errclass.ClassifyContext{}); err == nil || !strings.Contains(err.Error(), "bad request") {
+	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusBadRequest, RawBody: []byte(`{"msg":"bad request"}`), Header: header}, nil); err == nil || !strings.Contains(err.Error(), "bad request") {
 		t.Fatalf("HTTP error = %v", err)
 	}
-	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusInternalServerError, RawBody: []byte(`{}`), Header: header}, nil, errclass.ClassifyContext{}); err == nil || !strings.Contains(err.Error(), "HTTP 500") {
+	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusInternalServerError, RawBody: []byte(`{}`), Header: header}, nil); err == nil || !strings.Contains(err.Error(), "HTTP 500") {
 		t.Fatalf("HTTP fallback error = %v", err)
 	}
-	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"code":999,"msg":"failed"}`), Header: header}, nil, errclass.ClassifyContext{}); err == nil || !strings.Contains(err.Error(), "failed") {
+	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"code":999,"msg":"failed"}`), Header: header}, nil); err == nil || !strings.Contains(err.Error(), "failed") {
 		t.Fatalf("code error = %v", err)
 	}
-	data, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"code":0}`), Header: header}, nil, errclass.ClassifyContext{})
+	data, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"code":0}`), Header: header}, nil)
 	if err != nil {
 		t.Fatalf("code zero without data returned error: %v", err)
 	}
 	if data["log_id"] != "log_x" {
 		t.Fatalf("log_id = %v", data["log_id"])
 	}
-	data, err = parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`null`), Header: header}, nil, errclass.ClassifyContext{})
+	data, err = parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`null`), Header: header}, nil)
 	if err != nil {
 		t.Fatalf("null response with log id returned error: %v", err)
 	}
 	if data["log_id"] != "log_x" {
 		t.Fatalf("null response log_id = %v", data["log_id"])
 	}
-	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"BaseResp":{"StatusCode":7,"StatusMessage":"denied"}}`), Header: header}, nil, errclass.ClassifyContext{}); err == nil || !strings.Contains(err.Error(), "denied") {
+	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"BaseResp":{"StatusCode":7,"StatusMessage":"denied"}}`), Header: header}, nil); err == nil || !strings.Contains(err.Error(), "denied") {
 		t.Fatalf("BaseResp error = %v", err)
 	}
-	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"baseResp":{"statusCode":7}}`)}, nil, errclass.ClassifyContext{}); err == nil || !strings.Contains(err.Error(), "non-zero BaseResp") {
+	if _, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"baseResp":{"statusCode":7}}`)}, nil); err == nil || !strings.Contains(err.Error(), "non-zero BaseResp") {
 		t.Fatalf("BaseResp fallback error = %v", err)
 	}
 }
@@ -970,7 +970,7 @@ func TestParseIssueCredentialDataErrors(t *testing.T) {
 // credential issuance failure is flagged retryable and carries the developer-access hint.
 func TestParseIssueCredentialData503IsRetryableWithHint(t *testing.T) {
 	header := http.Header{"X-Tt-Logid": []string{"log_x"}}
-	_, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusServiceUnavailable, RawBody: []byte(`{"msg":"upstream busy"}`), Header: header}, nil, errclass.ClassifyContext{})
+	_, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusServiceUnavailable, RawBody: []byte(`{"msg":"upstream busy"}`), Header: header}, nil)
 	if err == nil {
 		t.Fatal("expected 503 error, got nil")
 	}
@@ -990,7 +990,7 @@ func TestParseIssueCredentialData503IsRetryableWithHint(t *testing.T) {
 // non-zero business code (no HTTP status) carries the hint but is not retryable.
 func TestParseIssueCredentialDataBusinessCodeHasHintNotRetryable(t *testing.T) {
 	header := http.Header{"X-Tt-Logid": []string{"log_x"}}
-	_, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"code":999,"msg":"no developer access"}`), Header: header}, nil, errclass.ClassifyContext{})
+	_, err := parseIssueCredentialData(&larkcore.ApiResp{StatusCode: http.StatusOK, RawBody: []byte(`{"code":999,"msg":"no developer access"}`), Header: header}, nil)
 	if err == nil {
 		t.Fatal("expected business-code error, got nil")
 	}
@@ -1014,10 +1014,11 @@ func TestParseIssueCredentialDataBusinessCodeHasHintNotRetryable(t *testing.T) {
 // server msg and assert (a) Message equals that msg exactly, and (b) neither
 // Message nor Hint contains any token/secret-shaped string.
 //
-// Note: server msg passthrough is the shared classifier's responsibility;
-// apps adds only a static hint. There is no msg redaction in this path, so
-// this test does not assert a redaction that does not exist — it asserts
-// that apps injects nothing sensitive of its own.
+// Note: server msg passthrough is the framework's responsibility; apps adds
+// only a static hint. There is no msg redaction in this path (verbatim
+// passthrough is the existing behavior), so this test does not assert a
+// redaction that does not exist — it asserts that apps injects nothing
+// sensitive of its own.
 func TestParseIssueCredentialDataMessageAddsNoExtraSecret(t *testing.T) {
 	const serverMsg = "permission denied"
 	header := http.Header{"X-Tt-Logid": []string{"log_x"}}
@@ -1044,7 +1045,7 @@ func TestParseIssueCredentialDataMessageAddsNoExtraSecret(t *testing.T) {
 		},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
-			_, err := parseIssueCredentialData(tc.resp, nil, errclass.ClassifyContext{})
+			_, err := parseIssueCredentialData(tc.resp, nil)
 			if err == nil {
 				t.Fatal("expected an error, got nil")
 			}
@@ -1052,12 +1053,9 @@ func TestParseIssueCredentialDataMessageAddsNoExtraSecret(t *testing.T) {
 			if !ok {
 				t.Fatalf("expected typed errs.Problem, got %T: %v", err, err)
 			}
-			// (a) The server msg survives into the message. The business-code
-			// path passes it through verbatim; the HTTP-status path reports
-			// "HTTP <status>: <body>" via the shared classifier, so assert
-			// containment rather than equality.
-			if !strings.Contains(p.Message, serverMsg) {
-				t.Fatalf("Message = %q, want it to contain server msg %q", p.Message, serverMsg)
+			// (a) The server msg is passed through verbatim.
+			if p.Message != serverMsg {
+				t.Fatalf("Message = %q, want server msg %q (verbatim passthrough)", p.Message, serverMsg)
 			}
 			// apps adds only the static hint — assert that exact static text,
 			// proving apps injects no per-request secret into the hint either.
@@ -1140,45 +1138,3 @@ exit 0
 	}
 	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
 }
-
-// TestParseIssueCredentialData_SharedClassifierCoverage pins the canonical
-// classifications the shared classifier provides on the credential-issue
-// path: a generic missing-scope code becomes a typed permission error with
-// the missing scopes extracted, and an HTTP 503 becomes a retryable
-// network/server_error — neither collapses to api/unknown.
-func TestParseIssueCredentialData_SharedClassifierCoverage(t *testing.T) {
-	header := http.Header{"X-Tt-Logid": []string{"log_x"}}
-
-	t.Run("missing scope classifies as authorization with scopes", func(t *testing.T) {
-		body := `{"code":99991676,"msg":"token scope insufficient","error":{"permission_violations":[{"subject":"spark:app:read"}]}}`
-		_, err := parseIssueCredentialData(&larkcore.ApiResp{
-			StatusCode: http.StatusOK, RawBody: []byte(body), Header: header,
-		}, nil, errclass.ClassifyContext{})
-		var permErr *errs.PermissionError
-		if !errors.As(err, &permErr) {
-			t.Fatalf("want *errs.PermissionError, got %T: %v", err, err)
-		}
-		if permErr.Subtype != errs.SubtypeTokenScopeInsufficient {
-			t.Fatalf("subtype = %q, want %q", permErr.Subtype, errs.SubtypeTokenScopeInsufficient)
-		}
-		if len(permErr.MissingScopes) != 1 || permErr.MissingScopes[0] != "spark:app:read" {
-			t.Fatalf("MissingScopes = %v, want [spark:app:read]", permErr.MissingScopes)
-		}
-	})
-
-	t.Run("http 503 classifies as retryable network server_error", func(t *testing.T) {
-		_, err := parseIssueCredentialData(&larkcore.ApiResp{
-			StatusCode: http.StatusServiceUnavailable, RawBody: []byte(`{"msg":"upstream busy"}`), Header: header,
-		}, nil, errclass.ClassifyContext{})
-		p, ok := errs.ProblemOf(err)
-		if !ok {
-			t.Fatalf("want typed problem, got %T: %v", err, err)
-		}
-		if p.Category != errs.CategoryNetwork || p.Subtype != errs.SubtypeNetworkServer {
-			t.Fatalf("classification = %s/%s, want network/server_error", p.Category, p.Subtype)
-		}
-		if !p.Retryable {
-			t.Fatalf("retryable = false, want true for 5xx")
-		}
-	})
-}

shortcuts/apps/gitcred/gitconfig.go

@@ -5,10 +5,10 @@ package gitcred
 
 import (
 	"context"
+	"fmt"
 	"os/exec"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 )
 
@@ -38,7 +38,7 @@ func (g GlobalGitConfig) SetHelper(ctx context.Context, gitHTTPURL, appID string
 		return err
 	}
 	if hadHelper && previousHelper != helper && !g.isManagedHelper(previousHelper) {
-		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "git credential helper already configured for %s; refusing to overwrite non-lark helper", normalizedURL)
+		return fmt.Errorf("git credential helper already configured for %s; refusing to overwrite non-lark helper", normalizedURL)
 	}
 	if err := exec.CommandContext(ctx, "git", "config", "--global", helperKey, helper).Run(); err != nil {
 		return err
@@ -106,7 +106,7 @@ func gitConfigGet(ctx context.Context, key string) (string, bool, error) {
 	if isGitConfigGetMissing(err) {
 		return "", false, nil
 	}
-	return "", false, errs.NewInternalError(errs.SubtypeExternalTool, "git config get %s failed: %v", key, err).WithCause(err)
+	return "", false, fmt.Errorf("get %s: %w", key, err)
 }
 
 func gitConfigUnset(ctx context.Context, key string) error {
@@ -114,7 +114,7 @@ func gitConfigUnset(ctx context.Context, key string) error {
 		if isGitConfigUnsetMissing(err) {
 			return nil
 		}
-		return errs.NewInternalError(errs.SubtypeExternalTool, "git config unset %s failed: %v", key, err).WithCause(err)
+		return fmt.Errorf("unset %s: %w", key, err)
 	}
 	return nil
 }

shortcuts/apps/gitcred/helper.go

@@ -11,7 +11,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 )
 
@@ -40,21 +40,21 @@ func NewManager(store *Store, secrets *SecretStore, gitConfig GitConfig, issuer
 func (m *Manager) Init(ctx context.Context, profile ProfileContext, appID string) (*InitResult, error) {
 	appID = strings.TrimSpace(appID)
 	if appID == "" {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--app-id is required").WithParam("--app-id")
+		return nil, output.ErrValidation("--app-id is required")
 	}
 	if err := validate.ResourceName(appID, "--app-id"); err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%v", err).WithParam("--app-id").WithCause(err)
+		return nil, err
 	}
 	if profile.UserOpenID == "" {
-		return nil, errs.NewAuthenticationError(errs.SubtypeTokenMissing, "not logged in").WithHint("run `lark-cli auth login --scope \"spark:app:read\"`")
+		return nil, output.ErrAuth("not logged in: run `lark-cli auth login --scope \"spark:app:read\"`")
 	}
 	unlockApp, err := lockApp(appID)
 	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeStorage, "acquire Git credential lock for %s: %v", appID, err).WithCause(err)
+		return nil, fmt.Errorf("acquire Git credential lock for %s: %w", appID, err)
 	}
 	defer unlockApp()
 	if m.Issuer == nil {
-		return nil, errs.NewInternalError(errs.SubtypeUnknown, "git credential issuer is not configured")
+		return nil, output.Errorf(output.ExitAPI, "api_error", "git credential issuer is not configured")
 	}
 	issued, err := m.Issuer.Issue(ctx, appID, profile)
 	if err != nil {
@@ -125,14 +125,14 @@ func (m *Manager) Init(ctx context.Context, profile ProfileContext, appID string
 func (m *Manager) Remove(ctx context.Context, profile ProfileContext, appID string) (*RemoveResult, error) {
 	appID = strings.TrimSpace(appID)
 	if appID == "" {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--app-id is required").WithParam("--app-id")
+		return nil, output.ErrValidation("--app-id is required")
 	}
 	if err := validate.ResourceName(appID, "--app-id"); err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%v", err).WithParam("--app-id").WithCause(err)
+		return nil, err
 	}
 	unlockApp, err := lockApp(appID)
 	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeStorage, "acquire Git credential lock for %s: %v", appID, err).WithCause(err)
+		return nil, fmt.Errorf("acquire Git credential lock for %s: %w", appID, err)
 	}
 	defer unlockApp()
 	records, err := m.Store.FindByAppID(appID, ProfileContext{})
@@ -335,7 +335,7 @@ func (m *Manager) Erase(r io.Reader) error {
 	}
 	unlockApp, err := lockApp(record.AppID)
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "acquire Git credential lock for %s: %v", record.AppID, err).WithCause(err)
+		return fmt.Errorf("acquire Git credential lock for %s: %w", record.AppID, err)
 	}
 	defer unlockApp()
 	record, err = m.Store.FindByURL(url)
@@ -360,8 +360,7 @@ func (m *Manager) readConfirmed(url string, current ProfileContext) (CredentialR
 		return CredentialRecord{}, "", false, err
 	}
 	if record.ProfileAppID != current.ProfileAppID || record.UserOpenID != current.UserOpenID {
-		return CredentialRecord{}, "", false, errs.NewValidationError(errs.SubtypeFailedPrecondition, "current login does not match initialized credential").
-			WithHint(fmt.Sprintf("run `lark-cli apps +git-credential-init --app-id %s` with the current login or switch back to the original account", record.AppID))
+		return CredentialRecord{}, "", false, fmt.Errorf("current login does not match initialized credential; run `lark-cli apps +git-credential-init --app-id %s` with the current login or switch back to the original account", record.AppID)
 	}
 	pat, err := m.Secrets.Get(record.PATRef)
 	if err != nil {
@@ -424,7 +423,7 @@ func ParseCredentialInput(r io.Reader) (CredentialInput, error) {
 func parseNormalizedForInput(raw string) (CredentialInput, error) {
 	parts := strings.SplitN(raw, "://", 2)
 	if len(parts) != 2 {
-		return CredentialInput{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid credential URL")
+		return CredentialInput{}, output.ErrValidation("invalid credential URL")
 	}
 	hostPath := parts[1]
 	idx := strings.Index(hostPath, "/")
@@ -458,19 +457,19 @@ func defaultUsername(username string) string {
 
 func validateIssuedCredential(appID, normalizedURL string, issued *IssuedCredential, now int64) error {
 	if issued == nil {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: empty credential")
+		return output.Errorf(output.ExitAPI, "api_error", "Issue Miaoda Git credential: empty credential")
 	}
 	if issued.AppID != "" && issued.AppID != appID {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response app_id %q does not match requested app_id %q", issued.AppID, appID)
+		return output.Errorf(output.ExitAPI, "api_error", "Issue Miaoda Git credential: response app_id %q does not match requested app_id %q", issued.AppID, appID)
 	}
 	if normalizedURL == "" {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response missing gitURL")
+		return output.Errorf(output.ExitAPI, "api_error", "Issue Miaoda Git credential: response missing gitURL")
 	}
 	if strings.TrimSpace(issued.PAT) == "" {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response missing token")
+		return output.Errorf(output.ExitAPI, "api_error", "Issue Miaoda Git credential: response missing token")
 	}
 	if issued.ExpiresAt <= now {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response expiredTime must be in the future")
+		return output.Errorf(output.ExitAPI, "api_error", "Issue Miaoda Git credential: response expiredTime must be in the future")
 	}
 	return nil
 }

shortcuts/apps/gitcred/lock.go

@@ -5,12 +5,12 @@ package gitcred
 
 import (
 	"errors"
+	"fmt"
 	"path/filepath"
 	"regexp"
 	"sync"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/lockfile"
 	"github.com/larksuite/cli/internal/vfs" //nolint:depguard // git credential locks live under CLI config dir and are not user file I/O.
@@ -30,7 +30,7 @@ func lockURL(url string) func() {
 func lockApp(appID string) (func(), error) {
 	dir := filepath.Join(core.GetConfigDir(), "locks")
 	if err := vfs.MkdirAll(dir, 0700); err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeStorage, "create Git credential lock dir: %v", err).WithCause(err)
+		return nil, fmt.Errorf("create Git credential lock dir: %w", err)
 	}
 	name := "apps_git_credential_" + safeLockNameChars.ReplaceAllString(appID, "_") + ".lock"
 	lock := lockfile.New(filepath.Join(dir, filepath.Base(name)))

shortcuts/apps/gitcred/types.go

@@ -27,7 +27,7 @@ const (
 )
 
 // CredentialFile is the app-scoped non-secret metadata persisted under the
-// app storage directory.
+// Miaoda app storage directory.
 type CredentialFile struct {
 	Version int `json:"version"`
 	CredentialRecord

shortcuts/apps/gitcred/url.go

@@ -12,17 +12,17 @@ import (
 	"path"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
 )
 
 func NormalizeGitHTTPURL(raw string) (string, error) {
 	raw = strings.TrimSpace(raw)
 	if raw == "" {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "git_http_url is empty")
+		return "", output.ErrValidation("git_http_url is empty")
 	}
 	u, err := url.Parse(raw)
 	if err != nil {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid git_http_url %q: %s", raw, err).WithCause(err)
+		return "", output.ErrValidation("invalid git_http_url %q: %s", raw, err)
 	}
 	return normalizeParsedURL(u)
 }
@@ -31,7 +31,7 @@ func NormalizeCredentialInput(input CredentialInput) (string, error) {
 	protocol := strings.TrimSpace(input.Protocol)
 	host := strings.TrimSpace(input.Host)
 	if protocol == "" || host == "" {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "git credential input must include protocol and host")
+		return "", output.ErrValidation("git credential input must include protocol and host")
 	}
 	u := &url.URL{
 		Scheme: protocol,
@@ -44,11 +44,11 @@ func NormalizeCredentialInput(input CredentialInput) (string, error) {
 func normalizeParsedURL(u *url.URL) (string, error) {
 	scheme := strings.ToLower(strings.TrimSpace(u.Scheme))
 	if scheme != "http" && scheme != "https" {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "git credential only supports http/https URLs")
+		return "", output.ErrValidation("git credential only supports http/https URLs")
 	}
 	host := normalizeHost(scheme, u.Host)
 	if host == "" {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "git_http_url host is empty")
+		return "", output.ErrValidation("git_http_url host is empty")
 	}
 	cleanPath := cleanURLPath(u.EscapedPath())
 	normalized := (&url.URL{Scheme: scheme, Host: host, Path: cleanPath}).String()

shortcuts/apps/html_publish_client.go

@@ -6,13 +6,13 @@ package apps
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"fmt"
 	"net/http"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/client"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -39,21 +39,31 @@ func (api appsHTMLPublishAPI) HTMLPublish(ctx context.Context, appID string, tar
 		Body:       fd,
 	}, larkcore.WithFileUpload())
 	if err != nil {
-		return nil, client.WrapDoAPIError(err)
+		return nil, err
 	}
-	data, err := api.runtime.ClassifyAPIResponse(apiResp)
-	if err != nil {
-		return nil, enrichHTMLPublishAPIError(err)
-	}
-	url, _ := data["url"].(string)
-	if url == "" {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"html-publish response is missing the published app url")
-	}
-	return &htmlPublishResponse{URL: url}, nil
+	return parseHTMLPublishResponse(apiResp.RawBody)
 }
 
-// OAPI business error codes returned by the
+func parseHTMLPublishResponse(raw []byte) (*htmlPublishResponse, error) {
+	var envelope struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+		Data struct {
+			URL string `json:"url"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(raw, &envelope); err != nil {
+		return nil, fmt.Errorf("decode html-publish response: %w", err)
+	}
+	if envelope.Code != 0 {
+		return nil, output.ErrWithHint(output.ExitAPI, "api_error",
+			fmt.Sprintf("html-publish failed (code=%d): %s", envelope.Code, envelope.Msg),
+			buildHTMLPublishFailureHint(envelope.Code))
+	}
+	return &htmlPublishResponse{URL: envelope.Data.URL}, nil
+}
+
+// OAPI business error codes returned by the Miaoda
 // /apps/{id}/upload_and_release_html_code endpoint. Owned by the backend
 // service; update when new codes are documented in the OAPI spec.
 const (
@@ -64,9 +74,9 @@ const (
 func buildHTMLPublishFailureHint(code int) string {
 	switch code {
 	case errCodeBuildFailed:
-		return "server-side build failed: run `lark-cli apps +html-publish --app-id <your-app-id> --path <path> --dry-run` to inspect the packaged file list"
+		return "构建失败：用 `lark-cli apps +html-publish --app-id <your-app-id> --path <path> --dry-run` 检查打包文件清单"
 	case errCodeAppNotFound:
-		return "the app does not exist or the caller has no access; ask the user to confirm the app_id (extract it from the app URL https://miaoda.feishu.cn/app/app_xxx after /app/, or take the app_xxx string directly)"
+		return "应用不存在或无权访问；请用户确认 app_id（从妙搭应用链接 https://miaoda.feishu.cn/app/app_xxx 的 /app/ 后面提取，或直接给 app_xxx 字符串）"
 	default:
 		return ""
 	}

shortcuts/apps/html_publish_client_test.go

@@ -6,21 +6,21 @@ package apps
 import (
 	"bytes"
 	"context"
+	"errors"
 	"mime"
 	"mime/multipart"
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
 func newAppsClientRuntime(t *testing.T) (*common.RuntimeContext, *httpmock.Registry) {
 	t.Helper()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	cfg := &core.CliConfig{
 		AppID:      "test-app-" + strings.ToLower(t.Name()),
 		AppSecret:  "test-secret",
@@ -94,57 +94,15 @@ func TestAppsHTMLPublishAPI_BusinessErrorHasHint(t *testing.T) {
 	if err == nil {
 		t.Fatalf("expected error")
 	}
-	problem := requireAppsAPIProblem(t, err)
-	if problem.Code != errCodeBuildFailed {
-		t.Fatalf("code = %d, want %d", problem.Code, errCodeBuildFailed)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+		t.Fatalf("expected ExitError with detail, got %v", err)
 	}
-	if problem.Hint == "" {
+	if exitErr.Detail.Hint == "" {
 		t.Fatalf("expected non-empty hint on code 90001")
 	}
-	if !strings.Contains(problem.Message, "build failed") {
-		t.Fatalf("missing failure message: %v", problem.Message)
-	}
-}
-
-func TestAppsHTMLPublishAPI_AppNotFoundClassified(t *testing.T) {
-	rctx, reg := newAppsClientRuntime(t)
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/spark/v1/apps/app_missing/upload_and_release_html_code",
-		Body: map[string]interface{}{
-			"code": errCodeAppNotFound,
-			"msg":  "app not found",
-		},
-	})
-
-	api := appsHTMLPublishAPI{runtime: rctx}
-	_, err := api.HTMLPublish(context.Background(), "app_missing", &htmlPublishTarball{Body: []byte("fake")})
-	problem := requireAppsAPIProblem(t, err)
-	if problem.Subtype != errs.SubtypeNotFound {
-		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeNotFound)
-	}
-	if problem.Hint == "" {
-		t.Fatalf("expected app-not-found recovery hint")
-	}
-}
-
-func TestAppsHTMLPublishAPI_MissingURLIsInvalidResponse(t *testing.T) {
-	rctx, reg := newAppsClientRuntime(t)
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/spark/v1/apps/app_x/upload_and_release_html_code",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "success",
-			"data": map[string]interface{}{},
-		},
-	})
-
-	api := appsHTMLPublishAPI{runtime: rctx}
-	_, err := api.HTMLPublish(context.Background(), "app_x", &htmlPublishTarball{Body: []byte("fake")})
-	problem := requireAppsProblem(t, err, errs.CategoryInternal)
-	if problem.Subtype != errs.SubtypeInvalidResponse {
-		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeInvalidResponse)
+	if !strings.Contains(exitErr.Detail.Message, "build failed") {
+		t.Fatalf("missing failure message: %v", exitErr.Detail.Message)
 	}
 }
 
@@ -180,18 +138,8 @@ func TestBuildHTMLPublishFailureHint_NotFoundHintNoLongerMentionsList(t *testing
 	}
 }
 
-func TestAppsHTMLPublishAPI_MalformedResponseIsInvalidResponse(t *testing.T) {
-	rctx, reg := newAppsClientRuntime(t)
-	reg.Register(&httpmock.Stub{
-		Method:  "POST",
-		URL:     "/open-apis/spark/v1/apps/app_x/upload_and_release_html_code",
-		RawBody: []byte("{not json"),
-	})
-
-	api := appsHTMLPublishAPI{runtime: rctx}
-	_, err := api.HTMLPublish(context.Background(), "app_x", &htmlPublishTarball{Body: []byte("fake")})
-	problem := requireAppsProblem(t, err, errs.CategoryInternal)
-	if problem.Subtype != errs.SubtypeInvalidResponse {
-		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeInvalidResponse)
+func TestParseHTMLPublishResponse_InvalidJSON(t *testing.T) {
+	if _, err := parseHTMLPublishResponse([]byte("{not json")); err == nil {
+		t.Error("malformed html-publish response must surface a decode error")
 	}
 }

shortcuts/apps/html_publish_tarball.go

@@ -9,9 +9,10 @@ import (
 	"compress/gzip"
 	"crypto/sha256"
 	"encoding/hex"
+	"errors"
+	"fmt"
 	"io"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 )
 
@@ -25,7 +26,7 @@ type htmlPublishTarball struct {
 
 func buildHTMLPublishTarball(fio fileio.FileIO, candidates []htmlPublishCandidate) (*htmlPublishTarball, error) {
 	if len(candidates) == 0 {
-		return nil, appsValidationParamError("--path", "no files to pack")
+		return nil, errors.New("no files to pack")
 	}
 
 	var buf bytes.Buffer
@@ -44,10 +45,10 @@ func buildHTMLPublishTarball(fio fileio.FileIO, candidates []htmlPublishCandidat
 
 	if err := tw.Close(); err != nil {
 		_ = gz.Close()
-		return nil, appsFileIOError(err, "tar close: %v", err)
+		return nil, fmt.Errorf("tar close: %w", err)
 	}
 	if err := gz.Close(); err != nil {
-		return nil, appsFileIOError(err, "gzip close: %v", err)
+		return nil, fmt.Errorf("gzip close: %w", err)
 	}
 
 	return &htmlPublishTarball{
@@ -59,12 +60,12 @@ func buildHTMLPublishTarball(fio fileio.FileIO, candidates []htmlPublishCandidat
 
 func writeHTMLPublishTarEntry(fio fileio.FileIO, tw *tar.Writer, c htmlPublishCandidate) error {
 	if isUnsafeRelPath(c.RelPath) {
-		return errs.NewInternalError(errs.SubtypeUnknown, "invalid tar entry name %q", c.RelPath)
+		return fmt.Errorf("invalid tar entry name %q", c.RelPath)
 	}
 
 	src, err := fio.Open(c.AbsPath)
 	if err != nil {
-		return appsInputPathEntryError(c.AbsPath, err)
+		return fmt.Errorf("open %s: %w", c.AbsPath, err)
 	}
 	defer src.Close()
 
@@ -75,10 +76,10 @@ func writeHTMLPublishTarEntry(fio fileio.FileIO, tw *tar.Writer, c htmlPublishCa
 		Typeflag: tar.TypeReg,
 	}
 	if err := tw.WriteHeader(hdr); err != nil {
-		return appsFileIOError(err, "write header %s: %v", c.RelPath, err)
+		return fmt.Errorf("write header %s: %w", c.RelPath, err)
 	}
 	if _, err := io.Copy(tw, src); err != nil {
-		return appsFileIOError(err, "copy %s: %v", c.RelPath, err)
+		return fmt.Errorf("copy %s: %w", c.RelPath, err)
 	}
 	return nil
 }

shortcuts/apps/storage.go

@@ -5,11 +5,11 @@ package apps
 
 import (
 	"errors"
+	"fmt"
 	"net/url"
 	"os"
 	"path/filepath"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/internal/vfs" //nolint:depguard // existing apps storage persists CLI config-dir state; it is not user file I/O.
@@ -25,10 +25,10 @@ const storageRoot = "spark"
 // can traverse out of the storage directory.
 func checkSeg(name, what string) error {
 	if err := validate.ResourceName(name, what); err != nil {
-		return appsStorageError(err, "apps storage: %v", err)
+		return fmt.Errorf("apps storage: %w", err)
 	}
 	if name == "." {
-		return errs.NewInternalError(errs.SubtypeStorage, "apps storage: %s must not be \".\"", what)
+		return fmt.Errorf("apps storage: %s must not be \".\"", what)
 	}
 	return nil
 }
@@ -60,7 +60,7 @@ func Read(appID, key string) ([]byte, error) {
 		if errors.Is(err, os.ErrNotExist) {
 			return nil, nil
 		}
-		return nil, appsStorageError(err, "apps storage: read: %v", err)
+		return nil, fmt.Errorf("apps storage: read: %w", err)
 	}
 	return data, nil
 }
@@ -79,10 +79,10 @@ func Write(appID, key string, data []byte) error {
 		return err
 	}
 	if err := vfs.MkdirAll(appDir(appID), 0700); err != nil {
-		return appsStorageError(err, "apps storage: create dir: %v", err)
+		return fmt.Errorf("apps storage: create dir: %w", err)
 	}
 	if err := validate.AtomicWrite(appKeyPath(appID, key), data, 0600); err != nil {
-		return appsStorageError(err, "apps storage: write: %v", err)
+		return fmt.Errorf("apps storage: write: %w", err)
 	}
 	return nil
 }
@@ -96,7 +96,7 @@ func Delete(appID, key string) error {
 		return err
 	}
 	if err := vfs.Remove(appKeyPath(appID, key)); err != nil && !errors.Is(err, os.ErrNotExist) {
-		return appsStorageError(err, "apps storage: delete: %v", err)
+		return fmt.Errorf("apps storage: delete: %w", err)
 	}
 	return nil
 }
@@ -113,7 +113,7 @@ func List(appID string) ([]string, error) {
 		if errors.Is(err, os.ErrNotExist) {
 			return []string{}, nil
 		}
-		return nil, appsStorageError(err, "apps storage: read dir: %v", err)
+		return nil, fmt.Errorf("apps storage: read dir: %w", err)
 	}
 	keys := make([]string, 0, len(entries))
 	for _, e := range entries {

shortcuts/apps/walk_html_publish_candidates.go

@@ -4,11 +4,11 @@
 package apps
 
 import (
+	"fmt"
 	"io/fs"
 	"path/filepath"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 )
 
@@ -40,7 +40,7 @@ func isUnsafeRelPath(rel string) bool {
 func walkHTMLPublishCandidates(fio fileio.FileIO, rootPath string) ([]htmlPublishCandidate, error) {
 	stat, err := fio.Stat(rootPath)
 	if err != nil {
-		return nil, appsInputPathError(err)
+		return nil, fmt.Errorf("stat %s: %w", rootPath, err)
 	}
 	if !stat.IsDir() {
 		return []htmlPublishCandidate{{
@@ -54,7 +54,7 @@ func walkHTMLPublishCandidates(fio fileio.FileIO, rootPath string) ([]htmlPublis
 	//nolint:forbidigo // fileio has no WalkDir; rootPath is already validated above via fio.Stat -> SafeInputPath.
 	err = filepath.WalkDir(rootPath, func(path string, d fs.DirEntry, walkErr error) error {
 		if walkErr != nil {
-			return appsInputPathEntryError(path, walkErr)
+			return walkErr
 		}
 		// Skip a stray git repo: a directory named .git skips the whole subtree,
 		// and a .git file (the gitdir pointer used by submodules/worktrees) is
@@ -70,7 +70,7 @@ func walkHTMLPublishCandidates(fio fileio.FileIO, rootPath string) ([]htmlPublis
 		}
 		info, err := d.Info()
 		if err != nil {
-			return appsInputPathEntryError(path, err)
+			return err
 		}
 		// 只接受 regular file —— symlink / device / pipe / socket 都跳过。
 		// symlink 不跟随是设计决策（避免 loop + out-of-root 引用），且 fio.Open 也会拒非 regular。
@@ -79,7 +79,7 @@ func walkHTMLPublishCandidates(fio fileio.FileIO, rootPath string) ([]htmlPublis
 		}
 		rel, err := filepath.Rel(rootPath, path)
 		if err != nil {
-			return appsFileIOError(err, "resolve relative path for %s: %v", path, err)
+			return err
 		}
 		relSlash := filepath.ToSlash(rel)
 		// Defense in depth: WalkDir + Rel inside rootPath should never yield a
@@ -87,7 +87,7 @@ func walkHTMLPublishCandidates(fio fileio.FileIO, rootPath string) ([]htmlPublis
 		// filesystem layout shouldn't be able to inject one into RelPath.
 		// Mirrors the same guard at tar entry write time.
 		if isUnsafeRelPath(relSlash) {
-			return errs.NewInternalError(errs.SubtypeUnknown, "walker produced unsafe relative path %q for %s", relSlash, path)
+			return fmt.Errorf("walker produced unsafe relative path %q for %s", relSlash, path)
 		}
 		out = append(out, htmlPublishCandidate{
 			RelPath: relSlash,

shortcuts/base/base_data_query.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"strings"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -21,7 +20,6 @@ var BaseDataQuery = common.Shortcut{
 	AuthTypes:   authTypes(),
 	Flags: []common.Flag{
 		baseTokenFlag(true),
-		{Name: "table-id", Hidden: true},
 		{Name: "dsl", Desc: "query JSON DSL; read lark-base-data-query-guide.md first, then lark-base-data-query.md for the full DSL SSOT", Required: true},
 	},
 	Tips: []string{
@@ -30,9 +28,6 @@ var BaseDataQuery = common.Shortcut{
 		"`dimensions` and `measures` cannot both be empty.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if strings.TrimSpace(runtime.Str("table-id")) != "" {
-			return baseFlagErrorf("+data-query does not support --table-id; put table names/fields inside --dsl (read lark-base-data-query-guide.md)")
-		}
 		var dsl map[string]interface{}
 		dec := json.NewDecoder(bytes.NewReader([]byte(runtime.Str("dsl"))))
 		dec.UseNumber()

shortcuts/base/base_dryrun_ops_test.go

@@ -73,14 +73,6 @@ func TestDryRunFieldOps(t *testing.T) {
 	)
 	assertDryRunContains(t, dryRunFieldList(ctx, listRT), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/fields", "offset=0", "limit=200")
 
-	batchListRT := newBaseTestRuntimeWithArrays(
-		map[string]string{"base-token": "app_x"},
-		map[string][]string{"table-id": {"tbl_1", "tbl_2"}},
-		nil,
-		map[string]int{"offset": 0, "limit": 50},
-	)
-	assertDryRunContains(t, dryRunFieldListBatch(ctx, batchListRT), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/fields", "GET /open-apis/base/v3/bases/app_x/tables/tbl_2/fields", "limit=50")
-
 	rt := newBaseTestRuntime(
 		map[string]string{
 			"base-token": "app_x",

shortcuts/base/base_execute_test.go

@@ -1066,129 +1066,6 @@ func TestBaseFieldExecuteCRUD(t *testing.T) {
 		}
 	})
 
-	t.Run("list resolves table name", func(t *testing.T) {
-		factory, stdout, reg := newExecuteFactory(t)
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{"tables": []interface{}{
-					map[string]interface{}{"id": "tbl_orders", "name": "Orders"},
-				}, "total": 1},
-			},
-		})
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_orders/fields",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{"fields": []interface{}{
-					map[string]interface{}{"id": "fld_name", "name": "Name", "type": "text"},
-				}, "total": 1},
-			},
-		})
-		if err := runShortcut(t, BaseFieldList, []string{"+field-list", "--base-token", "app_x", "--table-id", "Orders"}, factory, stdout); err != nil {
-			t.Fatalf("err=%v", err)
-		}
-		if got := stdout.String(); !strings.Contains(got, `"fields"`) || !strings.Contains(got, `"name": "Name"`) {
-			t.Fatalf("stdout=%s", got)
-		}
-	})
-
-	t.Run("list batch multiple tables", func(t *testing.T) {
-		factory, stdout, reg := newExecuteFactory(t)
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_a/fields",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{"fields": []interface{}{
-					map[string]interface{}{"id": "fld_a", "name": "Name", "type": "text", "style": map[string]interface{}{"type": "plain"}},
-				}, "total": 1},
-			},
-		})
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_b/fields",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{"fields": []interface{}{
-					map[string]interface{}{"id": "fld_b", "name": "Status", "type": "select", "options": []interface{}{map[string]interface{}{"name": "Todo", "color": "red"}}},
-				}, "total": 1},
-			},
-		})
-		if err := runShortcut(t, BaseFieldListBatch, []string{"+field-list-batch", "--base-token", "app_x", "--table-id", "tbl_a", "--table-id", "tbl_b", "--compact"}, factory, stdout); err != nil {
-			t.Fatalf("err=%v", err)
-		}
-		got := stdout.String()
-		if !strings.Contains(got, `"tables"`) || !strings.Contains(got, `"table_id": "tbl_a"`) || !strings.Contains(got, `"table_id": "tbl_b"`) || !strings.Contains(got, `"options": [`) || !strings.Contains(got, `"Todo"`) || !strings.Contains(got, `"style"`) || strings.Contains(got, `"color"`) {
-			t.Fatalf("stdout=%s", got)
-		}
-	})
-
-	t.Run("list batch resolves table names", func(t *testing.T) {
-		factory, stdout, reg := newExecuteFactory(t)
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{"tables": []interface{}{
-					map[string]interface{}{"id": "tbl_orders", "name": "Orders"},
-				}, "total": 1},
-			},
-		})
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_a/fields",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{"fields": []interface{}{
-					map[string]interface{}{"id": "fld_a", "name": "Name", "type": "text"},
-				}, "total": 1},
-			},
-		})
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_orders/fields",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{"fields": []interface{}{
-					map[string]interface{}{"id": "fld_order", "name": "Status", "type": "select"},
-				}, "total": 1},
-			},
-		})
-		if err := runShortcut(t, BaseFieldListBatch, []string{"+field-list-batch", "--base-token", "app_x", "--table-id", "tbl_a", "--table-id", "Orders"}, factory, stdout); err != nil {
-			t.Fatalf("err=%v", err)
-		}
-		got := stdout.String()
-		if !strings.Contains(got, `"table_id": "tbl_a"`) || !strings.Contains(got, `"table_id": "tbl_orders"`) || !strings.Contains(got, `"table_ref": "Orders"`) || !strings.Contains(got, `"table_name": "Orders"`) {
-			t.Fatalf("stdout=%s", got)
-		}
-	})
-
-	t.Run("list batch default keeps full fields", func(t *testing.T) {
-		factory, stdout, reg := newExecuteFactory(t)
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_b/fields",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{"fields": []interface{}{
-					map[string]interface{}{"id": "fld_b", "name": "Status", "type": "select", "options": []interface{}{map[string]interface{}{"name": "Todo", "color": "red"}}},
-				}, "total": 1},
-			},
-		})
-		if err := runShortcut(t, BaseFieldListBatch, []string{"+field-list-batch", "--base-token", "app_x", "--table-id", "tbl_b"}, factory, stdout); err != nil {
-			t.Fatalf("err=%v", err)
-		}
-		got := stdout.String()
-		if !strings.Contains(got, `"table_id": "tbl_b"`) || !strings.Contains(got, `"color": "red"`) {
-			t.Fatalf("stdout=%s", got)
-		}
-	})
-
 	t.Run("get", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
@@ -1557,48 +1434,6 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
-	t.Run("search accepts query alias", func(t *testing.T) {
-		factory, stdout, reg := newExecuteFactory(t)
-		searchStub := &httpmock.Stub{
-			Method: "POST",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records/search",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{
-					"fields":         []interface{}{"Title"},
-					"field_id_list":  []interface{}{"fld_title"},
-					"record_id_list": []interface{}{"rec_1"},
-					"data":           []interface{}{[]interface{}{"Created by AI"}},
-					"has_more":       false,
-				},
-			},
-		}
-		reg.Register(searchStub)
-		if err := runShortcut(
-			t,
-			BaseRecordSearch,
-			[]string{
-				"+record-search",
-				"--base-token", "app_x",
-				"--table-id", "tbl_x",
-				"--query", "Created",
-				"--search-field", "Title",
-				"--format", "json",
-			},
-			factory,
-			stdout,
-		); err != nil {
-			t.Fatalf("err=%v", err)
-		}
-		var body map[string]interface{}
-		if err := json.Unmarshal(searchStub.CapturedBody, &body); err != nil {
-			t.Fatalf("captured body json err=%v body=%s", err, string(searchStub.CapturedBody))
-		}
-		if body["keyword"] != "Created" {
-			t.Fatalf("captured body=%#v", body)
-		}
-	})
-
 	t.Run("search with filter json file", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		tmp := t.TempDir()
@@ -1690,29 +1525,20 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
-	t.Run("list fields alias projects columns", func(t *testing.T) {
-		factory, stdout, reg := newExecuteFactory(t)
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/records?field_id=Name&limit=100&offset=0",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{"items": []interface{}{}, "has_more": false},
-			},
-		})
-		if err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--fields", "Name"}, factory, stdout); err != nil {
+	t.Run("list legacy fields flag rejected", func(t *testing.T) {
+		factory, stdout, _ := newExecuteFactory(t)
+		err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--fields", "Name"}, factory, stdout)
+		if err == nil || !strings.Contains(err.Error(), "unknown flag: --fields") {
 			t.Fatalf("err=%v", err)
 		}
 	})
 
-	t.Run("list fields alias works in dry-run", func(t *testing.T) {
+	t.Run("list legacy fields flag rejected in dry-run", func(t *testing.T) {
 		factory, stdout, _ := newExecuteFactory(t)
-		if err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--fields", "Name", "--dry-run"}, factory, stdout); err != nil {
+		err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--fields", "Name", "--dry-run"}, factory, stdout)
+		if err == nil || !strings.Contains(err.Error(), "unknown flag: --fields") {
 			t.Fatalf("err=%v", err)
 		}
-		if got := stdout.String(); !strings.Contains(got, "field_id=Name") {
-			t.Fatalf("stdout=%s", got)
-		}
 	})
 
 	t.Run("get", func(t *testing.T) {

shortcuts/base/base_shortcuts_test.go

@@ -59,23 +59,6 @@ func newBaseTestRuntimeWithArrays(stringFlags map[string]string, stringArrayFlag
 	return &common.RuntimeContext{Cmd: cmd, Config: &core.CliConfig{UserOpenId: "ou_test"}}
 }
 
-func TestFieldSearchOptionsAlias(t *testing.T) {
-	runtime := newBaseTestRuntime(map[string]string{"field-name": "Status"}, nil, nil)
-	if got := fieldSearchOptionsRef(runtime); got != "Status" {
-		t.Fatalf("field ref=%q", got)
-	}
-	if err := BaseFieldSearchOptions.Validate(context.Background(), runtime); err != nil {
-		t.Fatalf("err=%v", err)
-	}
-}
-
-func TestFieldSearchOptionsRequiresFieldRef(t *testing.T) {
-	err := BaseFieldSearchOptions.Validate(context.Background(), newBaseTestRuntime(map[string]string{}, nil, nil))
-	if err == nil || !strings.Contains(err.Error(), "--field-id is required") {
-		t.Fatalf("err=%v", err)
-	}
-}
-
 func TestBaseAction(t *testing.T) {
 	t.Run("missing action", func(t *testing.T) {
 		runtime := newBaseTestRuntime(map[string]string{"get": ""}, map[string]bool{"list": false}, nil)
@@ -152,7 +135,7 @@ func TestShortcutsCatalog(t *testing.T) {
 	want := []string{
 		"+base-block-list", "+base-block-create", "+base-block-move", "+base-block-rename", "+base-block-delete",
 		"+table-list", "+table-get", "+table-create", "+table-update", "+table-delete",
-		"+field-list", "+field-list-batch", "+field-get", "+field-create", "+field-update", "+field-delete", "+field-search-options",
+		"+field-list", "+field-get", "+field-create", "+field-update", "+field-delete", "+field-search-options",
 		"+view-list", "+view-get", "+view-create", "+view-delete", "+view-get-filter", "+view-set-filter", "+view-get-visible-fields", "+view-set-visible-fields", "+view-get-group", "+view-set-group", "+view-get-sort", "+view-set-sort", "+view-get-timebar", "+view-set-timebar", "+view-get-card", "+view-set-card", "+view-rename",
 		"+record-list", "+record-search", "+record-get", "+record-upsert", "+record-batch-create", "+record-batch-update", "+record-share-link-create", "+record-upload-attachment", "+record-download-attachment", "+record-remove-attachment", "+record-delete",
 		"+record-history-list",
@@ -1105,22 +1088,6 @@ func TestBaseRecordValidate(t *testing.T) {
 	)); err != nil {
 		t.Fatalf("record search flag validate err=%v", err)
 	}
-	if err := BaseRecordSearch.Validate(ctx, newBaseTestRuntimeWithArrays(
-		map[string]string{"base-token": "b", "table-id": "tbl_1", "query": "Alice"},
-		map[string][]string{"search-field": {"Name"}},
-		nil,
-		nil,
-	)); err != nil {
-		t.Fatalf("record search query alias validate err=%v", err)
-	}
-	if err := BaseRecordSearch.Validate(ctx, newBaseTestRuntimeWithArrays(
-		map[string]string{"base-token": "b", "table-id": "tbl_1", "keyword": "Alice", "query": "Bob"},
-		map[string][]string{"search-field": {"Name"}},
-		nil,
-		nil,
-	)); err == nil || !strings.Contains(err.Error(), "use only one") {
-		t.Fatalf("err=%v", err)
-	}
 	if err := BaseRecordSearch.Validate(ctx, newBaseTestRuntime(
 		map[string]string{
 			"base-token": "b",

shortcuts/base/dashboard_block_get_data.go

@@ -19,7 +19,6 @@ var BaseDashboardBlockGetData = common.Shortcut{
 	HasFormat:   true,
 	Flags: []common.Flag{
 		baseTokenFlag(true),
-		{Name: "dashboard-id", Hidden: true},
 		blockIDFlag(true),
 	},
 	Tips: []string{

shortcuts/base/field_list.go

@@ -21,7 +21,6 @@ var BaseFieldList = common.Shortcut{
 		tableRefFlag(true),
 		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
 		{Name: "limit", Type: "int", Default: "100", Desc: "pagination size, range 1-200"},
-		{Name: "compact", Type: "bool", Desc: "return compact field objects (id/name/type/style/options) for lower context cost; default returns full field objects"},
 	},
 	DryRun: dryRunFieldList,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/field_list_batch.go

@@ -1,30 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package base
-
-import (
-	"context"
-
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-var BaseFieldListBatch = common.Shortcut{
-	Service:     "base",
-	Command:     "+field-list-batch",
-	Description: "List fields for multiple tables in one call",
-	Risk:        "read",
-	Scopes:      []string{"base:field:read"},
-	AuthTypes:   authTypes(),
-	Flags: []common.Flag{
-		baseTokenFlag(true),
-		{Name: "table-id", Type: "string_array", Desc: tableRefFlag(true).Desc + "; repeat to list fields for multiple tables", Required: true},
-		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
-		{Name: "limit", Type: "int", Default: "100", Desc: "pagination size, range 1-200"},
-		{Name: "compact", Type: "bool", Desc: "return compact field objects (id/name/type/style/options) for lower context cost; default returns full field objects"},
-	},
-	DryRun: dryRunFieldListBatch,
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return executeFieldListBatch(runtime)
-	},
-}

shortcuts/base/field_ops.go

@@ -10,12 +10,6 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-type fieldListTableRef struct {
-	input string
-	id    string
-	name  string
-}
-
 func dryRunFieldList(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 	offset := runtime.Int("offset")
 	if offset < 0 {
@@ -29,22 +23,6 @@ func dryRunFieldList(_ context.Context, runtime *common.RuntimeContext) *common.
 		Set("table_id", baseTableID(runtime))
 }
 
-func dryRunFieldListBatch(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	offset := runtime.Int("offset")
-	if offset < 0 {
-		offset = 0
-	}
-	limit := common.ParseIntBounded(runtime, "limit", 1, 200)
-	dry := common.NewDryRunAPI()
-	for _, tableIDValue := range runtime.StrArray("table-id") {
-		dry.GET(baseV3Path("bases", runtime.Str("base-token"), "tables", tableIDValue, "fields")).
-			Params(map[string]interface{}{"offset": offset, "limit": limit}).
-			Set("base_token", runtime.Str("base-token")).
-			Set("table_id", tableIDValue)
-	}
-	return dry
-}
-
 func dryRunFieldGet(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 	return common.NewDryRunAPI().
 		GET("/open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id").
@@ -83,7 +61,6 @@ func dryRunFieldDelete(_ context.Context, runtime *common.RuntimeContext) *commo
 }
 
 func dryRunFieldSearchOptions(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	fieldRef := fieldSearchOptionsRef(runtime)
 	params := map[string]interface{}{
 		"offset": runtime.Int("offset"),
 		"limit":  runtime.Int("limit"),
@@ -91,15 +68,15 @@ func dryRunFieldSearchOptions(_ context.Context, runtime *common.RuntimeContext)
 	if params["limit"].(int) <= 0 {
 		params["limit"] = 30
 	}
-	if keyword := strings.TrimSpace(fieldSearchOptionsKeyword(runtime)); keyword != "" {
+	if keyword := strings.TrimSpace(runtime.Str("keyword")); keyword != "" {
 		params["query"] = keyword
 	}
 	return common.NewDryRunAPI().
-		GET(baseV3Path("bases", runtime.Str("base-token"), "tables", baseTableID(runtime), "fields", fieldRef, "options")).
+		GET("/open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id/options").
 		Params(params).
 		Set("base_token", runtime.Str("base-token")).
 		Set("table_id", baseTableID(runtime)).
-		Set("field_id", fieldRef)
+		Set("field_id", runtime.Str("field-id"))
 }
 
 func validateFieldJSON(runtime *common.RuntimeContext) (map[string]interface{}, error) {
@@ -141,142 +118,17 @@ func executeFieldList(runtime *common.RuntimeContext) error {
 		offset = 0
 	}
 	limit := common.ParseIntBounded(runtime, "limit", 1, 200)
-	baseToken := runtime.Str("base-token")
-	tableRef, err := resolveFieldListTableRefs(runtime, baseToken, []string{baseTableID(runtime)})
-	if err != nil {
-		return err
-	}
-	fields, total, err := listAllFields(runtime, baseToken, tableRef[0].id, offset, limit)
+	fields, total, err := listAllFields(runtime, runtime.Str("base-token"), baseTableID(runtime), offset, limit)
 	if err != nil {
 		return err
 	}
 	if total == 0 {
 		total = len(fields)
 	}
-	if runtime.Bool("compact") {
-		fields = compactFields(fields)
-	}
 	runtime.Out(map[string]interface{}{"fields": fields, "total": total}, nil)
 	return nil
 }
 
-func executeFieldListBatch(runtime *common.RuntimeContext) error {
-	offset := runtime.Int("offset")
-	if offset < 0 {
-		offset = 0
-	}
-	limit := common.ParseIntBounded(runtime, "limit", 1, 200)
-	baseToken := runtime.Str("base-token")
-	tableRefs, err := resolveFieldListTableRefs(runtime, baseToken, runtime.StrArray("table-id"))
-	if err != nil {
-		return err
-	}
-	results := make([]map[string]interface{}, 0, len(tableRefs))
-	for _, tableRef := range tableRefs {
-		fields, total, err := listAllFields(runtime, baseToken, tableRef.id, offset, limit)
-		if err != nil {
-			return err
-		}
-		if total == 0 {
-			total = len(fields)
-		}
-		if runtime.Bool("compact") {
-			fields = compactFields(fields)
-		}
-		result := map[string]interface{}{
-			"table_id": tableRef.id,
-			"fields":   fields,
-			"total":    total,
-		}
-		if tableRef.input != tableRef.id {
-			result["table_ref"] = tableRef.input
-		}
-		if tableRef.name != "" {
-			result["table_name"] = tableRef.name
-		}
-		results = append(results, result)
-	}
-	runtime.Out(map[string]interface{}{"tables": results, "total": len(results)}, nil)
-	return nil
-}
-
-func resolveFieldListTableRefs(runtime *common.RuntimeContext, baseToken string, refs []string) ([]fieldListTableRef, error) {
-	if len(refs) == 0 {
-		return nil, baseValidationErrorf("--table-id is required")
-	}
-	resolved := make([]fieldListTableRef, 0, len(refs))
-	needsTableList := false
-	for _, raw := range refs {
-		ref := strings.TrimSpace(raw)
-		if ref == "" {
-			return nil, baseValidationErrorf("--table-id must not be empty")
-		}
-		if !isBaseTableID(ref) {
-			needsTableList = true
-		}
-		resolved = append(resolved, fieldListTableRef{input: ref, id: ref})
-	}
-	if !needsTableList {
-		return resolved, nil
-	}
-	tables, err := listEveryTable(runtime, baseToken)
-	if err != nil {
-		return nil, err
-	}
-	for i, tableRef := range resolved {
-		if isBaseTableID(tableRef.input) {
-			continue
-		}
-		table, err := resolveTableRef(tables, tableRef.input)
-		if err != nil {
-			return nil, baseValidationErrorf("table %q not found; run +table-list to verify the table name or pass the tbl... ID", tableRef.input)
-		}
-		tableIDValue := tableID(table)
-		if tableIDValue == "" {
-			return nil, baseValidationErrorf("table %q resolved without a table ID; run +table-list and pass the tbl... ID", tableRef.input)
-		}
-		resolved[i].id = tableIDValue
-		resolved[i].name = tableNameFromMap(table)
-	}
-	return resolved, nil
-}
-
-func isBaseTableID(ref string) bool {
-	return strings.HasPrefix(strings.TrimSpace(ref), "tbl")
-}
-
-// compactFields projects each field to the keys an agent needs for selection
-// (id / name / type / style, plus select option names), dropping formula
-// expressions and lookup internals that bloat agent context. Opt-in via
-// `--compact`; the default output keeps full field objects.
-func compactFields(fields []map[string]interface{}) []map[string]interface{} {
-	keep := []string{"id", "name", "type", "is_primary", "ui_type", "description", "style"}
-	out := make([]map[string]interface{}, 0, len(fields))
-	for _, f := range fields {
-		c := map[string]interface{}{}
-		for _, k := range keep {
-			if v, ok := f[k]; ok {
-				c[k] = v
-			}
-		}
-		if opts, ok := f["options"].([]interface{}); ok && len(opts) > 0 {
-			names := make([]interface{}, 0, len(opts))
-			for _, o := range opts {
-				if om, ok := o.(map[string]interface{}); ok {
-					if name, ok := om["name"]; ok {
-						names = append(names, name)
-						continue
-					}
-				}
-				names = append(names, o)
-			}
-			c["options"] = names
-		}
-		out = append(out, c)
-	}
-	return out
-}
-
 func executeFieldGet(runtime *common.RuntimeContext) error {
 	baseToken := runtime.Str("base-token")
 	tableIDValue := baseTableID(runtime)
@@ -332,25 +184,10 @@ func executeFieldDelete(runtime *common.RuntimeContext) error {
 	return nil
 }
 
-func fieldSearchOptionsRef(runtime *common.RuntimeContext) string {
-	fieldRef := runtime.Str("field-id")
-	if strings.TrimSpace(fieldRef) == "" {
-		fieldRef = runtime.Str("field-name")
-	}
-	return fieldRef
-}
-
-func fieldSearchOptionsKeyword(runtime *common.RuntimeContext) string {
-	if keyword := strings.TrimSpace(runtime.Str("keyword")); keyword != "" {
-		return keyword
-	}
-	return strings.TrimSpace(runtime.Str("query"))
-}
-
 func executeFieldSearchOptions(runtime *common.RuntimeContext) error {
 	baseToken := runtime.Str("base-token")
 	tableIDValue := baseTableID(runtime)
-	fieldRef := fieldSearchOptionsRef(runtime)
+	fieldRef := runtime.Str("field-id")
 	params := map[string]interface{}{
 		"offset": runtime.Int("offset"),
 		"limit":  runtime.Int("limit"),
@@ -358,7 +195,7 @@ func executeFieldSearchOptions(runtime *common.RuntimeContext) error {
 	if params["limit"].(int) <= 0 {
 		params["limit"] = 30
 	}
-	if keyword := strings.TrimSpace(fieldSearchOptionsKeyword(runtime)); keyword != "" {
+	if keyword := strings.TrimSpace(runtime.Str("keyword")); keyword != "" {
 		params["query"] = keyword
 	}
 	data, err := baseV3Call(runtime, "GET", baseV3Path("bases", baseToken, "tables", tableIDValue, "fields", fieldRef, "options"), params, nil)
@@ -373,7 +210,7 @@ func executeFieldSearchOptions(runtime *common.RuntimeContext) error {
 	runtime.Out(map[string]interface{}{
 		"field_id":   fieldRef,
 		"field_name": fieldRef,
-		"keyword":    fieldSearchOptionsKeyword(runtime),
+		"keyword":    strings.TrimSpace(runtime.Str("keyword")),
 		"options":    options,
 		"total":      total,
 	}, nil)

shortcuts/base/field_search_options.go

@@ -5,7 +5,6 @@ package base
 
 import (
 	"context"
-	"strings"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -20,10 +19,8 @@ var BaseFieldSearchOptions = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		tableRefFlag(true),
-		fieldRefFlag(false),
-		{Name: "field-name", Hidden: true},
+		fieldRefFlag(true),
 		{Name: "keyword", Desc: "keyword for option query"},
-		{Name: "query", Hidden: true},
 		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
 		{Name: "limit", Type: "int", Default: "30", Desc: "pagination size, default 30"},
 	},
@@ -32,15 +29,6 @@ var BaseFieldSearchOptions = common.Shortcut{
 		"Use only for fields with options, such as select or multi-select fields.",
 	},
 	DryRun: dryRunFieldSearchOptions,
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if strings.TrimSpace(fieldSearchOptionsRef(runtime)) == "" {
-			return baseFlagErrorf("--field-id is required")
-		}
-		if strings.TrimSpace(runtime.Str("keyword")) != "" && strings.TrimSpace(runtime.Str("query")) != "" {
-			return baseFlagErrorf("--query is a deprecated alias for --keyword; use only one")
-		}
-		return nil
-	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeFieldSearchOptions(runtime)
 	},