feat: align im feed shortcut commands with latest oapi

.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,30 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [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
@@ -1130,7 +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.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

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.
 )

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -18,7 +18,6 @@ var migratedCommonHelperPaths = []string{
 	"cmd/event/",
 	"events/",
 	"internal/event/consume/",
-	"shortcuts/apps/",
 	"shortcuts/base/",
 	"shortcuts/calendar/",
 	"shortcuts/contact/",

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -19,7 +19,6 @@ var migratedEnvelopePaths = []string{
 	"cmd/event/",
 	"events/",
 	"internal/event/consume/",
-	"shortcuts/apps/",
 	"shortcuts/base/",
 	"shortcuts/calendar/",
 	"shortcuts/contact/",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.52",
+  "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,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -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
 	},

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"
 )
@@ -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)
 	},
@@ -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,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -35,7 +36,7 @@ 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
 	},

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

@@ -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` 数组。
@@ -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
 	},
@@ -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"
 )
 
@@ -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
 	},

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"
 )
@@ -35,11 +35,11 @@ var AppsHTMLPublish = 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")
 		}
 		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("Miaoda uses index.html as 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"
 )
 
@@ -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).
+		// 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
 	},
@@ -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,20 +173,20 @@ 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
 }
@@ -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))
 }
 
@@ -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)
 }
@@ -562,7 +560,7 @@ func issueCredentials(ctx context.Context, rctx *common.RuntimeContext, appID st
 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,10 +609,10 @@ 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
 }

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"
@@ -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_release_create.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,7 +33,7 @@ var AppsReleaseCreate = 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
 	},

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"
 )
@@ -31,10 +32,10 @@ var AppsReleaseGet = 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("release-id")) == "" {
-			return appsValidationParamError("--release-id", "--release-id is required")
+			return output.ErrValidation("--release-id is required")
 		}
 		return nil
 	},

shortcuts/apps/apps_release_list.go

@@ -35,7 +35,7 @@ var AppsReleaseList = 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
 	},

shortcuts/apps/apps_session_create.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"
 )
@@ -30,7 +31,7 @@ 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
 	},

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

@@ -32,7 +32,7 @@ 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
 	},

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,6 +9,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -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
 	},

shortcuts/apps/common.go

@@ -4,9 +4,11 @@
 package apps
 
 import (
+	"errors"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
 )
 
 // appsService 是 CLI 命令的 service 前缀（lark-cli apps ...）。
@@ -21,11 +23,11 @@ const apiBasePath = "/open-apis/spark/v1"
 // 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"
@@ -53,12 +53,9 @@ var AppsGitCredentialInit = 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 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"))
@@ -132,12 +129,9 @@ var AppsGitCredentialRemove = 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 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"))
@@ -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 Miaoda 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 Miaoda 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 Miaoda 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 Miaoda 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)
 	}
@@ -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 Miaoda 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 Miaoda 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 Miaoda 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 Miaoda 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 Miaoda 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/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,18 +39,28 @@ 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)
+	return parseHTMLPublishResponse(apiResp.RawBody)
+}
+
+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"`
 	}
-	url, _ := data["url"].(string)
-	if url == "" {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"html-publish response is missing the published app url")
+	if err := json.Unmarshal(raw, &envelope); err != nil {
+		return nil, fmt.Errorf("decode html-publish response: %w", err)
 	}
-	return &htmlPublishResponse{URL: url}, nil
+	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
@@ -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 Miaoda 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/common/runner.go

@@ -298,14 +298,6 @@ func (ctx *RuntimeContext) CallAPITyped(method, url string, params map[string]in
 // carry fields a caller needs on failure (e.g. the file_token an overwrite
 // returned, for token-stability handling).
 func (ctx *RuntimeContext) ClassifyAPIResponse(resp *larkcore.ApiResp) (map[string]interface{}, error) {
-	return ClassifyAPIResponseWith(resp, ctx.APIClassifyContext())
-}
-
-// ClassifyAPIResponseWith is the RuntimeContext-free form of
-// ClassifyAPIResponse for callers that drive the request outside a running
-// shortcut (e.g. a cobra command holding only a factory) and supply their own
-// classification context.
-func ClassifyAPIResponseWith(resp *larkcore.ApiResp, cc errclass.ClassifyContext) (map[string]interface{}, error) {
 	logID, _ := logIDFromHeader(resp)["log_id"].(string)
 
 	result, parseErr := client.ParseJSONResponse(resp)
@@ -329,7 +321,7 @@ func ClassifyAPIResponseWith(resp *larkcore.ApiResp, cc errclass.ClassifyContext
 		}
 	}
 	out, _ := resultMap["data"].(map[string]interface{})
-	if apiErr := errclass.BuildAPIError(resultMap, cc); apiErr != nil {
+	if apiErr := errclass.BuildAPIError(resultMap, ctx.APIClassifyContext()); apiErr != nil {
 		return out, apiErr
 	}
 	if resp.StatusCode >= 400 {

shortcuts/im/helpers.go

@@ -1411,7 +1411,7 @@ const (
 )
 
 const (
-	feedShortcutBatchLimit = 10
+	feedShortcutBatchLimit = 30
 	feedShortcutWriteScope = "im:feed.shortcut:write"
 	feedShortcutReadScope  = "im:feed.shortcut:read"
 )
@@ -1423,7 +1423,8 @@ type shortcutItem struct {
 }
 
 // collectChatIDs reads --chat-id values (repeatable + comma-split) and
-// returns deduped, validated oc_ IDs. The server batch limit is 10.
+// returns deduped, validated oc_ IDs. This CLI enforces a local batch limit
+// of 30 even though the upstream API currently documents a higher ceiling.
 func collectChatIDs(rt *common.RuntimeContext) ([]string, error) {
 	raw := rt.StrSlice("chat-id")
 	if len(raw) == 0 {

shortcuts/im/im_feed_shortcut_create.go

@@ -17,7 +17,7 @@ import (
 var ImFeedShortcutCreate = common.Shortcut{
 	Service:     "im",
 	Command:     "+feed-shortcut-create",
-	Description: "Add chats to the user's feed shortcuts; user-only; batch up to 10 chat IDs per call; --head/--tail controls insertion order",
+	Description: "Add chats to the user's feed shortcuts; user-only; CHAT only; CLI enforces up to 30 chat IDs per call; --head/--tail controls insertion order",
 	Risk:        "write",
 	UserScopes:  []string{feedShortcutWriteScope},
 	AuthTypes:   []string{"user"},
@@ -28,7 +28,7 @@ var ImFeedShortcutCreate = common.Shortcut{
 		// reported through the structured validation envelope (exit 2)
 		// instead of cobra's plain-text error.
 		{Name: "chat-id", Type: "string_slice",
-			Desc: "open_chat_id to add as a feed shortcut (oc_xxx); required; repeat the flag or pass comma-separated; max 10 per call"},
+			Desc: "open_chat_id to add as a feed shortcut (oc_xxx); required; repeat the flag or pass comma-separated; CLI max 30 per call"},
 		{Name: "head", Type: "bool",
 			Desc: "insert at the top of the shortcut list (default); mutually exclusive with --tail"},
 		{Name: "tail", Type: "bool",

shortcuts/im/im_feed_shortcut_list.go

@@ -5,75 +5,31 @@ package im
 
 import (
 	"context"
-	"fmt"
 
 	"github.com/larksuite/cli/shortcuts/common"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
 
 // ImFeedShortcutList provides the +feed-shortcut-list shortcut for listing
-// the user's feed shortcuts. The server-controlled page size covers the full
-// list in practice, but pagination is version-locked: when the list changes
-// between calls the server rejects the stale token and the caller has to
-// restart by omitting --page-token.
-//
-// The shortcut is a thin one-page wrapper — there is no automatic walking.
-// Callers are expected to drive their own loop when they actually need to
-// paginate, because the version-lock means each page is a real checkpoint
-// that the caller must consciously decide what to do with on failure.
+// the current user's feed shortcuts. The latest OAPI contract returns the
+// full list directly, so the shortcut intentionally exposes no pagination or
+// detail-enrichment behavior.
 var ImFeedShortcutList = common.Shortcut{
-	Service:               "im",
-	Command:               "+feed-shortcut-list",
-	Description:           "List one page of the user's feed shortcuts; user-only; first call omits --page-token, subsequent calls pass the previous response's page_token; each entry is auto-enriched with the full per-type info object attached as `detail` (pass --no-detail to skip)",
-	Risk:                  "read",
-	UserScopes:            []string{feedShortcutReadScope},
-	ConditionalUserScopes: []string{chatBatchQueryScope},
-	AuthTypes:             []string{"user"},
-	HasFormat:             true,
-	Flags: []common.Flag{
-		{Name: "page-token",
-			Desc: "opaque pagination token from the previous response; omit for the first page. If a token is rejected because the list changed, restart by omitting it."},
-		{Name: "no-detail", Type: "bool",
-			Desc: "skip fetching the full info object for each shortcut (default: enrichment enabled — CHAT-type entries call im.chats.batch_query, require im:chat:read, and attach the object under the detail field)"},
-	},
+	Service:     "im",
+	Command:     "+feed-shortcut-list",
+	Description: "List the current user's feed shortcuts; user-only; returns the full CHAT shortcut list directly with no pagination or detail lookup",
+	Risk:        "read",
+	UserScopes:  []string{feedShortcutReadScope},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		d := common.NewDryRunAPI().
-			GET("/open-apis/im/v2/feed_shortcuts")
-		if token := runtime.Str("page-token"); token != "" {
-			d.Params(map[string]any{"page_token": token})
-		}
-		if !runtime.Bool("no-detail") {
-			d.Desc("conditional enrichment: if CHAT-type entries exist, execution also calls POST /open-apis/im/v1/chats/batch_query and requires scope im:chat:read; pass --no-detail to skip this extra call and extra scope")
-		}
-		return d
+		return common.NewDryRunAPI().GET("/open-apis/im/v2/feed_shortcuts")
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		data, err := runtime.DoAPIJSONTyped("GET", "/open-apis/im/v2/feed_shortcuts",
-			feedShortcutListQuery(runtime.Str("page-token")), nil)
+		data, err := runtime.DoAPIJSONTyped("GET", "/open-apis/im/v2/feed_shortcuts", nil, nil)
 		if err != nil {
 			return err
 		}
-		if !runtime.Bool("no-detail") {
-			if err := enrichFeedShortcutDetail(runtime, data); err != nil {
-				fmt.Fprintf(runtime.IO().ErrOut, "warning: detail enrichment failed: %v\n", err)
-				// Mirror the warning into the data payload so stdout-only
-				// consumers can tell "enrichment skipped" from "nothing to
-				// enrich" (same convention as mail's data-level _notice).
-				if data != nil {
-					data["_notice"] = fmt.Sprintf("detail enrichment skipped: %v", err)
-				}
-			}
-		}
 		runtime.Out(data, nil)
 		return nil
 	},
 }
-
-// feedShortcutListQuery omits the page_token key entirely when the token is
-// empty, so the server treats the call as a first-page request.
-func feedShortcutListQuery(token string) larkcore.QueryParams {
-	if token == "" {
-		return larkcore.QueryParams{}
-	}
-	return larkcore.QueryParams{"page_token": []string{token}}
-}

shortcuts/im/im_feed_shortcut_remove.go

@@ -15,7 +15,7 @@ import (
 var ImFeedShortcutRemove = common.Shortcut{
 	Service:     "im",
 	Command:     "+feed-shortcut-remove",
-	Description: "Remove chats from the user's feed shortcuts; user-only; batch up to 10 chat IDs per call; per-item failures return ok:false with failed_shortcuts",
+	Description: "Remove chats from the user's feed shortcuts; user-only; CHAT only; CLI enforces up to 30 chat IDs per call; per-item failures return ok:false with failed_shortcuts",
 	Risk:        "write",
 	UserScopes:  []string{feedShortcutWriteScope},
 	AuthTypes:   []string{"user"},
@@ -26,7 +26,7 @@ var ImFeedShortcutRemove = common.Shortcut{
 		// reported through the structured validation envelope (exit 2)
 		// instead of cobra's plain-text error.
 		{Name: "chat-id", Type: "string_slice",
-			Desc: "open_chat_id to remove from feed shortcuts (oc_xxx); required; repeat the flag or pass comma-separated; max 10 per call"},
+			Desc: "open_chat_id to remove from feed shortcuts (oc_xxx); required; repeat the flag or pass comma-separated; CLI max 30 per call"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		_, err := collectChatIDs(runtime)

shortcuts/im/im_feed_shortcut_test.go

@@ -6,7 +6,6 @@ package im
 import (
 	"bytes"
 	"context"
-	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -49,11 +48,6 @@ func newFeedShortcutRemoveCmd(t *testing.T) *cobra.Command {
 func newFeedShortcutListCmd(t *testing.T) *cobra.Command {
 	t.Helper()
 	cmd := &cobra.Command{Use: "test"}
-	cmd.Flags().String("page-token", "", "")
-	// Default true (skip enrichment) in tests so non-enrichment-focused tests
-	// don't trigger the batch_query path; tests that exercise detail
-	// enrichment flip this off.
-	cmd.Flags().Bool("no-detail", true, "")
 	if err := cmd.ParseFlags(nil); err != nil {
 		t.Fatalf("ParseFlags() error = %v", err)
 	}
@@ -76,11 +70,26 @@ func TestCollectChatIDs(t *testing.T) {
 		{name: "dedupes", input: []string{"oc_abc", "oc_abc", "oc_def"}, want: []string{"oc_abc", "oc_def"}},
 		{name: "rejects empty list", input: nil, wantErr: true, errSubstr: "--chat-id is required"},
 		{name: "rejects bad prefix", input: []string{"om_abc"}, wantErr: true, errSubstr: "must be an open_chat_id"},
+		{
+			name: "accepts limit boundary",
+			input: []string{
+				"oc_1", "oc_2", "oc_3", "oc_4", "oc_5", "oc_6", "oc_7", "oc_8", "oc_9", "oc_10",
+				"oc_11", "oc_12", "oc_13", "oc_14", "oc_15", "oc_16", "oc_17", "oc_18", "oc_19", "oc_20",
+				"oc_21", "oc_22", "oc_23", "oc_24", "oc_25", "oc_26", "oc_27", "oc_28", "oc_29", "oc_30",
+			},
+			want: []string{
+				"oc_1", "oc_2", "oc_3", "oc_4", "oc_5", "oc_6", "oc_7", "oc_8", "oc_9", "oc_10",
+				"oc_11", "oc_12", "oc_13", "oc_14", "oc_15", "oc_16", "oc_17", "oc_18", "oc_19", "oc_20",
+				"oc_21", "oc_22", "oc_23", "oc_24", "oc_25", "oc_26", "oc_27", "oc_28", "oc_29", "oc_30",
+			},
+		},
 		{
 			name: "rejects over limit",
 			input: []string{
-				"oc_1", "oc_2", "oc_3", "oc_4", "oc_5",
-				"oc_6", "oc_7", "oc_8", "oc_9", "oc_10", "oc_11",
+				"oc_1", "oc_2", "oc_3", "oc_4", "oc_5", "oc_6", "oc_7", "oc_8", "oc_9", "oc_10",
+				"oc_11", "oc_12", "oc_13", "oc_14", "oc_15", "oc_16", "oc_17", "oc_18", "oc_19", "oc_20",
+				"oc_21", "oc_22", "oc_23", "oc_24", "oc_25", "oc_26", "oc_27", "oc_28", "oc_29", "oc_30",
+				"oc_31",
 			},
 			wantErr:   true,
 			errSubstr: "too many --chat-id",
@@ -549,24 +558,15 @@ func TestImFeedShortcutListDryRunRendersGet(t *testing.T) {
 			t.Fatalf("DryRun output = %s, want %q", got, want)
 		}
 	}
-	if strings.Contains(got, "page_token") {
-		t.Fatalf("DryRun output = %s, should omit page_token on first-page request", got)
+}
+
+func TestImFeedShortcutListHasNoCustomFlags(t *testing.T) {
+	if len(ImFeedShortcutList.Flags) != 0 {
+		t.Fatalf("ImFeedShortcutList.Flags = %v, want no shortcut-specific flags", ImFeedShortcutList.Flags)
 	}
 }
 
-func TestImFeedShortcutListDryRunIncludesNonEmptyPageToken(t *testing.T) {
-	cmd := newFeedShortcutListCmd(t)
-	if err := cmd.Flags().Set("page-token", "tok1"); err != nil {
-		t.Fatalf("Set page-token error = %v", err)
-	}
-	rt := &common.RuntimeContext{Cmd: cmd}
-	got := ImFeedShortcutList.DryRun(context.Background(), rt).Format()
-	if !strings.Contains(got, "page_token=tok1") {
-		t.Fatalf("DryRun output = %s, want page_token=tok1", got)
-	}
-}
-
-func TestImFeedShortcutListHelpDoesNotTreatDetailAsArgName(t *testing.T) {
+func TestImFeedShortcutListHelpShowsNoLegacyFlags(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "app", AppSecret: "secret", Brand: core.BrandFeishu,
 	})
@@ -584,71 +584,13 @@ func TestImFeedShortcutListHelpDoesNotTreatDetailAsArgName(t *testing.T) {
 		t.Fatalf("Help() error = %v", err)
 	}
 	got := out.String()
-	if strings.Contains(got, "--no-detail detail") {
-		t.Fatalf("help output treats `detail` as a flag arg name:\n%s", got)
-	}
-	if !strings.Contains(got, "--no-detail") {
-		t.Fatalf("help output missing --no-detail:\n%s", got)
-	}
-}
-
-func TestImFeedShortcutListDryRunMentionsDetailScope(t *testing.T) {
-	cmd := newFeedShortcutListCmd(t)
-	if err := cmd.Flags().Set("no-detail", "false"); err != nil {
-		t.Fatalf("Set no-detail error = %v", err)
-	}
-	rt := &common.RuntimeContext{Cmd: cmd}
-	got := ImFeedShortcutList.DryRun(context.Background(), rt).Format()
-	for _, want := range []string{
-		"im:chat:read",
-		"--no-detail",
-		"batch_query",
-	} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("DryRun output = %s, want %q", got, want)
+	for _, banned := range []string{"--no-detail", "--page-token"} {
+		if strings.Contains(got, banned) {
+			t.Fatalf("help output should not mention legacy flag %s:\n%s", banned, got)
 		}
 	}
 }
 
-func TestImFeedShortcutListDoesNotExposeAutoPaginationFlags(t *testing.T) {
-	// Locks in the design decision: this shortcut is a one-page wrapper.
-	// If any of these reappear, callers/AI agents will assume auto-walking
-	// is supported and write code that silently double-fetches.
-	banned := map[string]bool{"page-all": true, "page-limit": true, "page-size": true}
-	for _, fl := range ImFeedShortcutList.Flags {
-		if banned[fl.Name] {
-			t.Fatalf("ImFeedShortcutList must not expose --%s", fl.Name)
-		}
-	}
-}
-
-func TestImFeedShortcutListPageTokenIsOptional(t *testing.T) {
-	// --page-token must NOT be Required: omitting it is the natural first-page
-	// signal (the server treats "missing" and "" the same). Forcing an empty
-	// string would just be noise.
-	for _, fl := range ImFeedShortcutList.Flags {
-		if fl.Name == "page-token" && fl.Required {
-			t.Fatalf("--page-token must be optional; omitting it should mean first page")
-		}
-	}
-}
-
-func TestImFeedShortcutListDetailOnByDefault(t *testing.T) {
-	// The real flag definition must keep detail enrichment on by default:
-	// --no-detail is an opt-out bool with a false zero-value default. The
-	// test-helper command flips it for isolation, so this definition-level
-	// check is what actually locks the shipped default against a flip.
-	for _, fl := range ImFeedShortcutList.Flags {
-		if fl.Name == "no-detail" {
-			if fl.Default != "" && fl.Default != "false" {
-				t.Fatalf("--no-detail default = %q, want unset/false (enrichment on by default)", fl.Default)
-			}
-			return
-		}
-	}
-	t.Fatalf("--no-detail flag not found on ImFeedShortcutList")
-}
-
 func TestFeedShortcutChatIDNotCobraRequired(t *testing.T) {
 	// --chat-id is mandatory, but must NOT be cobra-Required: cobra would
 	// intercept a missing flag before Validate runs and emit a plain-text
@@ -663,430 +605,46 @@ func TestFeedShortcutChatIDNotCobraRequired(t *testing.T) {
 	}
 }
 
-func TestFeedShortcutListQueryOmitsEmptyToken(t *testing.T) {
-	q := feedShortcutListQuery("")
-	if _, ok := q["page_token"]; ok {
-		t.Fatalf("feedShortcutListQuery(\"\") = %v, want no page_token key", q)
-	}
-	q = feedShortcutListQuery("next")
-	if v := q["page_token"]; len(v) != 1 || v[0] != "next" {
-		t.Fatalf("feedShortcutListQuery(\"next\") page_token = %v, want [next]", v)
-	}
-}
-
-func TestImFeedShortcutListExecuteForwardsToken(t *testing.T) {
-	tests := []struct {
-		name     string
-		token    string
-		wantSent string // value the server should see in ?page_token=
-		wantKey  bool   // whether ?page_token should appear at all
-	}{
-		{name: "first page omits param", token: "", wantSent: "", wantKey: false},
-		{name: "explicit token is forwarded", token: "tok1", wantSent: "tok1", wantKey: true},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			var calls int
-			var sawKey bool
-			var gotToken string
-			rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-				if !strings.Contains(req.URL.Path, "/open-apis/im/v2/feed_shortcuts") {
-					return nil, fmt.Errorf("unexpected request: %s", req.URL.Path)
-				}
-				calls++
-				_, sawKey = req.URL.Query()["page_token"]
-				gotToken = req.URL.Query().Get("page_token")
-				return shortcutJSONResponse(200, map[string]any{
-					"code": 0,
-					"data": map[string]any{
-						"shortcuts":  []any{map[string]any{"feed_card_id": "oc_a", "type": float64(1)}},
-						"has_more":   false,
-						"page_token": "end",
-					},
-				}), nil
-			}))
-
-			cmd := newFeedShortcutListCmd(t)
-			if err := cmd.Flags().Set("page-token", tt.token); err != nil {
-				t.Fatalf("Set page-token error = %v", err)
-			}
-			setRuntimeField(t, rt, "Cmd", cmd)
-
-			if err := ImFeedShortcutList.Execute(context.Background(), rt); err != nil {
-				t.Fatalf("Execute() error = %v", err)
-			}
-			if calls != 1 {
-				t.Fatalf("expected 1 API call, got %d", calls)
-			}
-			if sawKey != tt.wantKey {
-				t.Fatalf("page_token query key present = %v, want %v", sawKey, tt.wantKey)
-			}
-			if gotToken != tt.wantSent {
-				t.Fatalf("page_token sent = %q, want %q", gotToken, tt.wantSent)
-			}
-		})
-	}
-}
-
-func TestShortcutTypeFromValue(t *testing.T) {
-	tests := []struct {
-		name string
-		v    any
-		want ShortcutType
-	}{
-		{name: "float64 1 → chat", v: float64(1), want: ShortcutTypeChat},
-		{name: "int 1 → chat", v: 1, want: ShortcutTypeChat},
-		{name: "float64 0 → unknown", v: float64(0), want: ShortcutTypeUnknown},
-		{name: "unknown numeric → unknown ShortcutType(99)", v: float64(99), want: ShortcutType(99)},
-		{name: "string defaults to unknown", v: "1", want: ShortcutTypeUnknown},
-		{name: "nil defaults to unknown", v: nil, want: ShortcutTypeUnknown},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			if got := shortcutTypeFromValue(tt.v); got != tt.want {
-				t.Fatalf("shortcutTypeFromValue(%v) = %v, want %v", tt.v, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestResolveChatDetailBatchesAt50(t *testing.T) {
+func TestImFeedShortcutListExecuteRequestsFullList(t *testing.T) {
 	var calls int
+	var rawQuery string
 	rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-		if !strings.Contains(req.URL.Path, "/open-apis/im/v1/chats/batch_query") {
+		if !strings.Contains(req.URL.Path, "/open-apis/im/v2/feed_shortcuts") {
 			return nil, fmt.Errorf("unexpected request: %s", req.URL.Path)
 		}
 		calls++
-		// Echo each requested chat_id back with a synthetic name so we can
-		// confirm both that batching happened and that the response was
-		// parsed correctly.
-		body, _ := io.ReadAll(req.Body)
-		var parsed struct {
-			ChatIDs []string `json:"chat_ids"`
-		}
-		_ = json.Unmarshal(body, &parsed)
-		items := make([]any, 0, len(parsed.ChatIDs))
-		for _, id := range parsed.ChatIDs {
-			items = append(items, map[string]any{"chat_id": id, "name": "group-" + id})
-		}
-		return shortcutJSONResponse(200, map[string]any{
-			"code": 0,
-			"data": map[string]any{"items": items},
-		}), nil
-	}))
-	setRuntimeScopes(t, rt, chatBatchQueryScope)
-
-	ids := make([]string, 120) // 50 + 50 + 20 → 3 batches
-	for i := range ids {
-		ids[i] = fmt.Sprintf("oc_%d", i)
-	}
-	got, err := resolveChatDetail(rt, ids)
-	if err != nil {
-		t.Fatalf("resolveChatDetail() error = %v", err)
-	}
-	if calls != 3 {
-		t.Fatalf("calls = %d, want 3 (120 ids / 50 batch size)", calls)
-	}
-	if len(got) != 120 {
-		t.Fatalf("resolved size = %d, want 120", len(got))
-	}
-	first := got["oc_0"]
-	last := got["oc_119"]
-	if first == nil || last == nil {
-		t.Fatalf("Items missing boundary entries: first=%v last=%v", first, last)
-	}
-	if first["name"] != "group-oc_0" || last["name"] != "group-oc_119" {
-		t.Fatalf("expected name passthrough; got first=%v last=%v", first["name"], last["name"])
-	}
-}
-
-func TestResolveChatDetailIncludesP2PChats(t *testing.T) {
-	// Unlike the old title-only resolver, the detail resolver keeps p2p chats
-	// in the result map (their full object carries chat_mode/p2p_target_id);
-	// only `name` is empty. Locks in that the empty-name skip was removed
-	// when we switched from `title` (string) to `detail` (full object).
-	rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		rawQuery = req.URL.RawQuery
 		return shortcutJSONResponse(200, map[string]any{
 			"code": 0,
 			"data": map[string]any{
-				"items": []any{
-					map[string]any{"chat_id": "oc_group", "name": "Engineering", "chat_mode": "group"},
-					map[string]any{"chat_id": "oc_p2p", "name": "", "chat_mode": "p2p", "p2p_target_id": "ou_x"},
+				"shortcuts": []any{
+					map[string]any{"feed_card_id": "oc_a", "type": float64(1)},
 				},
 			},
 		}), nil
 	}))
-	setRuntimeScopes(t, rt, chatBatchQueryScope)
 
-	got, err := resolveChatDetail(rt, []string{"oc_group", "oc_p2p"})
-	if err != nil {
-		t.Fatalf("resolveChatDetail() error = %v", err)
-	}
-	if got["oc_group"]["name"] != "Engineering" {
-		t.Fatalf("oc_group name = %v, want Engineering", got["oc_group"]["name"])
-	}
-	p2p, ok := got["oc_p2p"]
-	if !ok {
-		t.Fatalf("oc_p2p must be in Items even though name is empty (caller decides what to show)")
-	}
-	if p2p["chat_mode"] != "p2p" || p2p["p2p_target_id"] != "ou_x" {
-		t.Fatalf("p2p detail = %v, want chat_mode=p2p with p2p_target_id passthrough", p2p)
-	}
-}
+	cmd := newFeedShortcutListCmd(t)
+	setRuntimeField(t, rt, "Cmd", cmd)
 
-func TestResolveChatDetailDropsItemsWithoutChatID(t *testing.T) {
-	// Defensive: the server should always echo chat_id back, but if it ever
-	// returns an item missing chat_id we must not write a "" → object entry
-	// into the map and end up attaching nonsense to entries.
-	rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-		return shortcutJSONResponse(200, map[string]any{
-			"code": 0,
-			"data": map[string]any{
-				"items": []any{
-					map[string]any{"chat_id": "oc_ok", "name": "ok"},
-					map[string]any{"name": "no chat_id"},
-				},
-			},
-		}), nil
-	}))
-	setRuntimeScopes(t, rt, chatBatchQueryScope)
-
-	got, err := resolveChatDetail(rt, []string{"oc_ok"})
-	if err != nil {
-		t.Fatalf("resolveChatDetail() error = %v", err)
-	}
-	if len(got) != 1 {
-		t.Fatalf("resolved size = %d, want 1 (entry without chat_id must be dropped)", len(got))
-	}
-	if _, ok := got[""]; ok {
-		t.Fatalf("got[\"\"] must not exist; got %v", got[""])
-	}
-}
-
-func TestResolveChatDetailPropagatesScopeError(t *testing.T) {
-	rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-		t.Fatalf("resolver should fail scope pre-flight before calling API: %s", req.URL.Path)
-		return nil, nil
-	}))
-	// Token resolves with a known-but-wrong scope set so the missing-scope
-	// branch (not the unknown-metadata warning branch) fires.
-	setRuntimeScopes(t, rt, "search:message")
-
-	_, err := resolveChatDetail(rt, []string{"oc_abc"})
-	if err == nil {
-		t.Fatalf("resolveChatDetail() expected scope error, got nil")
-	}
-	if !strings.Contains(err.Error(), chatBatchQueryScope) {
-		t.Fatalf("resolveChatDetail() error = %v, want mention of %s", err, chatBatchQueryScope)
-	}
-}
-
-func TestEnrichFeedShortcutDetailAttachesAndDedupes(t *testing.T) {
-	var calls int
-	var capturedIDs []string
-	rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-		if !strings.Contains(req.URL.Path, "/open-apis/im/v1/chats/batch_query") {
-			return nil, fmt.Errorf("unexpected request: %s", req.URL.Path)
-		}
-		calls++
-		body, _ := io.ReadAll(req.Body)
-		var parsed struct {
-			ChatIDs []string `json:"chat_ids"`
-		}
-		_ = json.Unmarshal(body, &parsed)
-		capturedIDs = append(capturedIDs, parsed.ChatIDs...)
-		items := make([]any, 0, len(parsed.ChatIDs))
-		for _, id := range parsed.ChatIDs {
-			items = append(items, map[string]any{
-				"chat_id":   id,
-				"name":      "name-of-" + id,
-				"chat_mode": "group",
-			})
-		}
-		return shortcutJSONResponse(200, map[string]any{
-			"code": 0,
-			"data": map[string]any{"items": items},
-		}), nil
-	}))
-	setRuntimeScopes(t, rt, chatBatchQueryScope)
-
-	data := map[string]any{
-		"shortcuts": []any{
-			map[string]any{"feed_card_id": "oc_a", "type": float64(1)},
-			map[string]any{"feed_card_id": "oc_b", "type": float64(1)},
-			map[string]any{"feed_card_id": "oc_a", "type": float64(1)}, // duplicate
-			// Unknown type — must be skipped without aborting the whole call.
-			map[string]any{"feed_card_id": "doc_xxx", "type": float64(3)},
-		},
-	}
-	if err := enrichFeedShortcutDetail(rt, data); err != nil {
-		t.Fatalf("enrichFeedShortcutDetail() error = %v", err)
+	if err := ImFeedShortcutList.Execute(context.Background(), rt); err != nil {
+		t.Fatalf("Execute() error = %v", err)
 	}
 	if calls != 1 {
-		t.Fatalf("calls = %d, want 1 (single batch covers all CHAT ids)", calls)
+		t.Fatalf("expected 1 API call, got %d", calls)
 	}
-	if len(capturedIDs) != 2 {
-		t.Fatalf("server saw chat_ids = %v, want 2 dedup'd ids", capturedIDs)
+	if rawQuery != "" {
+		t.Fatalf("request query = %q, want empty query string", rawQuery)
 	}
-
-	items := data["shortcuts"].([]any)
-	for _, ix := range []int{0, 1, 2} { // 2 is the duplicate of 0
-		detail, ok := items[ix].(map[string]any)["detail"].(map[string]any)
-		if !ok {
-			t.Fatalf("item[%d] missing detail field; got %v", ix, items[ix])
-		}
-		// The full chat object is passed through verbatim — not just a name.
-		if detail["chat_mode"] != "group" {
-			t.Fatalf("item[%d] detail.chat_mode = %v, want group (full object passthrough)", ix, detail["chat_mode"])
-		}
-		wantName := "name-of-" + items[ix].(map[string]any)["feed_card_id"].(string)
-		if detail["name"] != wantName {
-			t.Fatalf("item[%d] detail.name = %v, want %q", ix, detail["name"], wantName)
-		}
-	}
-	if _, ok := items[3].(map[string]any)["detail"]; ok {
-		t.Fatalf("item[3] (unknown type) should not have detail set")
-	}
-}
-
-func TestEnrichFeedShortcutDetailNoOpWhenEmpty(t *testing.T) {
-	rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-		t.Fatalf("must not call API for empty list: %s", req.URL.Path)
-		return nil, nil
-	}))
-	if err := enrichFeedShortcutDetail(rt, map[string]any{}); err != nil {
-		t.Fatalf("enrichFeedShortcutDetail(empty data) error = %v", err)
-	}
-	if err := enrichFeedShortcutDetail(rt, map[string]any{"shortcuts": []any{}}); err != nil {
-		t.Fatalf("enrichFeedShortcutDetail(empty shortcuts) error = %v", err)
-	}
-}
-
-func TestEnrichFeedShortcutDetailSkipsWhenNoSupportedType(t *testing.T) {
-	rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-		t.Fatalf("must not call batch_query when no resolvable types: %s", req.URL.Path)
-		return nil, nil
-	}))
-	data := map[string]any{
-		"shortcuts": []any{
-			map[string]any{"feed_card_id": "doc_1", "type": float64(3)},  // DOC, not exposed
-			map[string]any{"feed_card_id": "app_1", "type": float64(4)},  // OPENAPP, not exposed
-			map[string]any{"feed_card_id": "biz_1", "type": float64(13)}, // APP_FEED, not exposed
-		},
-	}
-	if err := enrichFeedShortcutDetail(rt, data); err != nil {
-		t.Fatalf("enrichFeedShortcutDetail() error = %v", err)
-	}
-	for i, it := range data["shortcuts"].([]any) {
-		if _, ok := it.(map[string]any)["detail"]; ok {
-			t.Fatalf("item[%d] should not have a detail (unknown type)", i)
-		}
-	}
-}
-
-func TestImFeedShortcutListExecuteEnrichesDetailByDefault(t *testing.T) {
-	rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-		switch {
-		case strings.Contains(req.URL.Path, "/open-apis/im/v2/feed_shortcuts"):
-			return shortcutJSONResponse(200, map[string]any{
-				"code": 0,
-				"data": map[string]any{
-					"shortcuts": []any{
-						map[string]any{"feed_card_id": "oc_a", "type": float64(1)},
-					},
-					"has_more":   false,
-					"page_token": "",
-				},
-			}), nil
-		case strings.Contains(req.URL.Path, "/open-apis/im/v1/chats/batch_query"):
-			return shortcutJSONResponse(200, map[string]any{
-				"code": 0,
-				"data": map[string]any{
-					"items": []any{
-						map[string]any{
-							"chat_id":   "oc_a",
-							"name":      "Team Alpha",
-							"chat_mode": "group",
-						},
-					},
-				},
-			}), nil
-		}
-		return nil, fmt.Errorf("unexpected request: %s", req.URL.Path)
-	}))
-	setRuntimeScopes(t, rt, feedShortcutReadScope+" "+chatBatchQueryScope)
-
-	cmd := newFeedShortcutListCmd(t)
-	if err := cmd.Flags().Set("no-detail", "false"); err != nil {
-		t.Fatalf("Set no-detail error = %v", err)
-	}
-	setRuntimeField(t, rt, "Cmd", cmd)
-
-	if err := ImFeedShortcutList.Execute(context.Background(), rt); err != nil {
-		t.Fatalf("Execute() error = %v", err)
-	}
-	out := rt.Factory.IOStreams.Out.(interface{ String() string }).String()
-	// Verify both the attach-field name and the full-object passthrough,
-	// so future regressions that drop fields (e.g. only keeping `name`)
-	// fail loudly here.
-	for _, want := range []string{
-		`"detail":`,
-		`"chat_mode": "group"`,
-		`"name": "Team Alpha"`,
-	} {
-		if !strings.Contains(out, want) {
-			t.Fatalf("stdout missing %q, got:\n%s", want, out)
-		}
-	}
-}
-
-func TestImFeedShortcutListExecuteWarnsOnEnrichFailure(t *testing.T) {
-	rt := newUserShortcutRuntime(t, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-		switch {
-		case strings.Contains(req.URL.Path, "/open-apis/im/v2/feed_shortcuts"):
-			return shortcutJSONResponse(200, map[string]any{
-				"code": 0,
-				"data": map[string]any{
-					"shortcuts": []any{
-						map[string]any{"feed_card_id": "oc_a", "type": float64(1)},
-					},
-					"has_more":   false,
-					"page_token": "",
-				},
-			}), nil
-		case strings.Contains(req.URL.Path, "/open-apis/im/v1/chats/batch_query"):
-			return nil, fmt.Errorf("batch_query network failure")
-		}
-		return nil, fmt.Errorf("unexpected request: %s", req.URL.Path)
-	}))
-	setRuntimeScopes(t, rt, feedShortcutReadScope+" "+chatBatchQueryScope)
-
-	cmd := newFeedShortcutListCmd(t)
-	if err := cmd.Flags().Set("no-detail", "false"); err != nil {
-		t.Fatalf("Set no-detail error = %v", err)
-	}
-	setRuntimeField(t, rt, "Cmd", cmd)
-
-	// Listing should still succeed even when enrichment can't reach the API —
-	// failure becomes a stderr warning, not a hard exit.
-	if err := ImFeedShortcutList.Execute(context.Background(), rt); err != nil {
-		t.Fatalf("Execute() error = %v", err)
-	}
-	stderr := rt.Factory.IOStreams.ErrOut.(interface{ String() string }).String()
-	if !strings.Contains(stderr, "detail enrichment failed") {
-		t.Fatalf("stderr = %q, want enrichment warning", stderr)
-	}
-	// And the shortcut itself still appears, just without `detail`.
 	stdout := rt.Factory.IOStreams.Out.(interface{ String() string }).String()
-	if !strings.Contains(stdout, `"feed_card_id": "oc_a"`) {
-		t.Fatalf("stdout should still contain the bare shortcut entry; got:\n%s", stdout)
+	for _, want := range []string{`"feed_card_id": "oc_a"`, `"type": 1`} {
+		if !strings.Contains(stdout, want) {
+			t.Fatalf("stdout = %s, want %q", stdout, want)
+		}
 	}
-	if strings.Contains(stdout, `"detail"`) {
-		t.Fatalf("stdout should NOT contain detail when enrichment failed; got:\n%s", stdout)
-	}
-	// The degradation is mirrored as a machine-readable data field so
-	// stdout-only consumers can tell "skipped" from "nothing to enrich".
-	if !strings.Contains(stdout, `"_notice": "detail enrichment skipped`) {
-		t.Fatalf("stdout should carry the _notice degradation marker; got:\n%s", stdout)
+	for _, banned := range []string{`"detail"`, `"_notice"`, `"page_token"`, `"has_more"`} {
+		if strings.Contains(stdout, banned) {
+			t.Fatalf("stdout should not contain legacy field %s; got:\n%s", banned, stdout)
+		}
 	}
 }

skills/lark-apps/references/lark-apps-db-execute.md

@@ -28,7 +28,7 @@ lark-cli apps +db-execute --app-id app_xxx --env dev --sql - --yes < /Users/.../
 
 - 成功默认 JSON 读取 `data.results[]`；每个元素对应一条 SQL，常见字段有 `sql_type`、`data`、`record_count`、`affected_rows`。
 - pretty 会按 SELECT/DML/DDL 自适应渲染；多语句会逐条显示 Statement 摘要。
-- 失败可能仍有前序语句已执行；此时 stdout 输出 `ok:false` 的 envelope（exit 非 0），从 `data` 读 `results[]`（全部逐条结果，失败语句 `sql_type` 为 `ERROR`）、`statement_index`、`error_code`、`error_message`、`rolled_back` 和 `note`，决定从哪条继续。
+- 失败可能仍有前序语句已执行；看 `error.detail.statement_index`、`completed`、`rolled_back` 和 `hint` 决定从哪条继续。
 
 ## Agent 规则
 

skills/lark-drive/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-drive
 version: 1.0.0
-description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
+description: "飞书云空间（云盘/云存储）：管理云空间（云盘/云存储）中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word/Markdown/Excel/CSV/PPTX 以及 Base 快照（.base）导入为飞书在线云文档（docx、sheet、bitable、slides）。当用户需要上传或下载文件、整理云空间（云盘/云存储）目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base/幻灯片 时使用。\"云空间\"、\"云盘\"和\"云存储\"是同一概念，用户说\"云盘\"、\"云存储\"、\"网盘\"、\"我的空间\"时均路由到本 skill。当用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是资源类型、URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -12,7 +12,7 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
-> **术语说明：** 飞书云空间也常被称为"云盘"、"云存储"、"网盘"或"我的空间"，这些说法通常指的是同一个产品，是飞书官方的云端文件存储与管理中心。
+> **术语说明：** 飞书云空间也常被称为"云盘"或"云存储"，三者指的是同一个产品，是飞书官方的云端文件存储与管理中心。
 
 > **导入分流规则：** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。
 
@@ -21,7 +21,6 @@ metadata:
 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--mine`，实为 owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
 - 用户要**根据文档评论定位正文位置**，例如 根据评论 review 文档、根据评论内容回看文档、区分多处相同引用文本时，对于 docx 类型（`file_type=docx`）的文档支持通过 `need_relation=true` 返回评论位置，其他类型暂不支持，具体用法需要先阅读 [`references/lark-drive-comment-location.md`](references/lark-drive-comment-location.md) 了解。
-- 用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，仍按资源类型、URL 路径和 token 路由到本 skill；不要因为域名不是飞书而回退到 WebFetch。
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
@@ -52,17 +51,88 @@ metadata:
 |----------|---------------------------------------------------------|-----------|----------|
 | `/docx/` | `https://example.larksuite.com/docx/doxcnxxxxxxxxx`    | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
 | `/doc/` | `https://example.larksuite.com/doc/doccnxxxxxxxxx`     | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
-| `/wiki/` | `https://example.larksuite.com/wiki/wikcnxxxxxxxxx`    | `wiki_token` | 不能直接当底层 `file_token`；优先用 `drive +inspect` 解包获取 `obj_token` |
+| `/wiki/` | `https://example.larksuite.com/wiki/wikcnxxxxxxxxx`    | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
 | `/sheets/` | `https://example.larksuite.com/sheets/shtcnxxxxxxxxx`  | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
 | `/drive/folder/` | `https://example.larksuite.com/drive/folder/fldcnxxxx` | `folder_token` | URL 路径中的 token 作为文件夹 token 使用 |
 
-### Wiki 链接特殊处理
+### Wiki 链接特殊处理（关键！）
+
+知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、多维表格等不同类型的文档。**不能直接假设 URL 中的 token 就是 file_token**，必须先查询实际类型和真实 token。
+
+#### 处理流程
+
+**推荐方式：使用 `drive +inspect` 自动解包**
 
 ```bash
 lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 ```
 
-知识库链接背后可能是 docx、sheet、bitable、slides、file 等不同对象。后续要做评论、下载、导出或内容读取时，优先用 `drive +inspect` 拿到 `type`、`token`、`title`、`url`；完整手动解析和跨 skill 路由见共享文档 [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md)。不要只根据 `/wiki/<token>` 猜底层类型。
+返回结果包含 `type`（底层文档类型）、`token`（真实 file_token）、`title`、`url` 等字段，直接用于后续操作。
+
+**手动方式：使用 `wiki.spaces.get_node` 查询节点信息**
+
+1. **使用 `wiki.spaces.get_node` 查询节点信息**
+   ```bash
+   lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
+   ```
+
+2. **从返回结果中提取关键信息**
+   - `node.obj_type`：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）
+   - `node.obj_token`：**真实的文档 token**（用于后续操作）
+   - `node.title`：文档标题
+
+3. **根据 `obj_type` 使用对应的 API**
+
+   | obj_type | 说明 | 使用的 API |
+   |----------|------|-----------|
+   | `docx` | 新版云文档 | `drive file.comments.*`、`docx.*` |
+   | `doc` | 旧版云文档 | `drive file.comments.*` |
+   | `sheet` | 电子表格 | `sheets.*` |
+   | `bitable` | 多维表格 | `bitable.*` |
+   | `slides` | 幻灯片 | `drive.*` |
+   | `file` | 文件 | `drive.*` |
+   | `mindnote` | 思维导图 | `drive.*` |
+
+#### 查询示例
+
+```bash
+# 查询 wiki 节点
+lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
+```
+
+返回结果示例：
+```json
+{
+  "node": {
+    "obj_type": "docx",
+    "obj_token": "xxxx",
+    "title": "标题",
+    "node_type": "origin",
+    "space_id": "12345678910"
+  }
+}
+```
+
+### 资源关系
+
+```
+Wiki Space (知识空间)
+└── Wiki Node (知识库节点)
+    ├── obj_type: docx (新版文档)
+    │   └── obj_token (真实文档 token)
+    ├── obj_type: doc (旧版文档)
+    │   └── obj_token (真实文档 token)
+    ├── obj_type: sheet (电子表格)
+    │   └── obj_token (真实文档 token)
+    ├── obj_type: bitable (多维表格)
+    │   └── obj_token (真实文档 token)
+    └── obj_type: file/slides/mindnote
+        └── obj_token (真实文档 token)
+
+Drive Folder (云空间/云盘/云存储文件夹)
+└── File (文件/文档)
+    └── file_token (直接使用)
+```
 
 ### 常见操作 Token 需求
 
@@ -75,12 +145,84 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 | 上传文件 | `folder_token` / `wiki_node_token` | 目标位置的 token |
 | 列出文档评论 | `file_token` | 同添加评论 |
 
-### 评论能力入口
+### 评论能力边界（关键！）
 
-- 添加评论优先使用 [`+add-comment`](references/lark-drive-add-comment.md)：review / 审阅 / 校对场景默认尽量创建局部评论，不要把多个可定位问题合并为一条全文评论。
-- 评论查询、统计、排序、回复限制，先读 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。
-- 需要根据评论定位正文位置时，先确认目标是 `file_type=docx`，再读 [`lark-drive-comment-location.md`](references/lark-drive-comment-location.md)；其他文档类型暂不支持返回定位字段。
-- reaction / 表情相关操作先读 [`lark-drive-reactions.md`](references/lark-drive-reactions.md)；只有用户明确需要 reaction 信息时才带 `need_reaction=true`。
+- `drive +add-comment` 支持两种模式。
+- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc`/`docx`/`file` 的 wiki URL。
+- 局部评论：传 `--block-id` 时启用；`docx` 支持文本定位或 block id，`sheet` 支持 `<sheetId>!<cell>`，`slides` 支持 `<slide-block-type>!<xml-id>`，wiki URL 解析到这些类型时也支持对应局部评论。Drive file 本次只支持全文评论，不支持局部评论。
+- Drive file 评论仅支持白名单扩展名：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件暂不支持，CLI 会直接报错提示当前还不支持这种类型的评论。
+- Review / 审阅 / 校对 / 逐条指出问题场景优先使用局部评论，不要把多个可定位问题汇总成一条全文评论；具体参数和定位方式见 [`drive +add-comment` 行为说明](references/lark-drive-add-comment.md#行为说明)。
+- `drive +add-comment` 的 `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。
+- `slides` 评论要求显式传 `--block-id <slide-block-type>!<xml-id>`；CLI 会将其拆分后写入 `anchor.block_id` 和 `anchor.slide_block_type`。其中 `<xml-id>` 是 PPT XML 协议中的元素 `id`；不支持 `--selection-with-ellipsis` 和 `--full-comment`。
+
+- 评论写入内容（添加评论、回复评论、编辑回复）里的文本不能直接出现 `<`、`>`；提交前必须先转义：`<` -> `&lt;`，`>` -> `&gt;`。
+- 使用 `drive +add-comment` 时，shortcut 会对 `type=text` 的文本元素自动做上述转义兜底；如果直接调用 `drive file.comments create_v2`、`drive file.comment.replys create`、`drive file.comment.replys update`，则需要在请求里自行传入已转义的内容。
+- 如果 wiki 解析后不是 `doc`/`docx`/`file`/`sheet`/`slides`，不要用 `+add-comment`。
+- 如果需要更底层地直接调用评论 V2 协议，再走原生 API：先执行 `lark-cli schema drive.file.comments.create_v2`，再执行 `lark-cli drive file.comments create_v2 ...`。全文评论省略 `anchor`，局部评论传 `anchor.block_id`。
+
+### 评论查询与统计口径（关键！）
+
+**强制规则**：`drive file.comments list` 默认必须传 `is_solved:false`，即仅查询未解决评论。即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确提到要包含已解决评论，仍然按默认口径查询未解决评论。仅当用户明确要求包含已解决评论时，才可省略 `is_solved` 参数。
+
+**正确示例：**
+
+```bash
+# 默认查询：仅未解决评论（推荐）
+lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'
+
+# 查询所有评论（用户未明确要求包含已解决评论）
+lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'
+
+# 包含已解决评论（需用户明确要求）
+lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'
+```
+
+**错误示例：**
+
+```bash
+# 不推荐：用户未明确要求但查询所有评论
+lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'
+```
+
+- 查询文档评论时，使用 `drive file.comments list`。
+- `drive file.comments list` 返回的 `items` 应理解为"评论卡片"列表，每个 `item` 对应用户界面里看到的一张评论卡片，而不是平铺的互动消息列表。
+- 服务端语义上，创建第一条评论时会同时创建该卡片里的第一条 reply；因此真正承载正文的是每个 `item.reply_list.replies`，其中第一条 reply 在用户视角下就是这张卡片里的"评论本身"。
+- 当用户要统计"评论数"或"评论卡片数"时，统计 `items` 的长度即可；如果是全量统计，则对所有评论分页返回的 `items` 长度累加。
+- 当用户要统计"回复数"时，按用户视角应排除每张评论卡片里的首条评论，统计口径是所有 `item.reply_list.replies` 的长度之和减去 `items` 的长度。
+- 当用户要统计"总互动数"时，统计所有 `item.reply_list.replies` 的长度之和即可；这个口径包含每张评论卡片里的首条评论。
+- 如果某个 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中；此时需要继续调用 `drive file.comment.replys list` 拉全后，再做全量回复数 / 总互动数统计。
+
+### 评论业务特性与引导（关键！）
+
+#### Review 场景评论落点
+- 默认策略是“能局部就局部”：用户说 review、审阅、检查文档、标注问题、给修改建议、逐条评论时，优先创建局部评论。
+- 多个独立问题应分别创建多条局部评论；不要为了省调用次数把 review 发现的问题合并到全文评论。
+- 只有在目标类型支持全文评论，且出现以下任一情况时，才退回全文评论：用户明确要求全文/总体评论、评论内容确实是文档级总结、目标类型不支持局部评论，或无法稳定定位到具体位置；否则应说明限制并请求用户提供可定位位置。
+- 具体参数、定位方式和不同文档类型的约束见 [`drive +add-comment` 行为说明](references/lark-drive-add-comment.md#行为说明)。
+
+#### 评论排序引导
+- 一个文档通常有多个评论，评论按 `create_time`（创建时间）排序。
+- **重要**：只有当用户明确提到"最新评论"、"最后评论"、"最早评论"时，才需要根据 `create_time` 进行排序：
+  - **必须先获取所有评论（处理分页拉完所有数据）**，不能只获取一页就排序
+  - "最新评论" / "最后评论"：按 `create_time` 降序排列，取第一条
+  - "最早评论"：按 `create_time` 升序排列，取第一条
+- 如果用户只说"第一条评论"，直接使用 `drive file.comments list` 返回的第一条即可，不需要额外排序。
+
+#### 评论回复限制
+- **添加评论回复前先检查是否存在以下限制**
+- **全文评论不支持回复**：`is_whole=true` 的评论（全文评论）无法添加回复，遇到此类评论应提示用户"全文评论不支持回复"。
+- **已解决评论不支持回复**：`is_solved=true` 的评论无法添加回复，遇到此类评论应提示用户"该评论已被解决，无法回复"。
+- **注意**：当用户要回复某条评论但该评论因上述限制不能回复时，只提示不能回复即可，**不要自动帮用户找其他可以回复的评论**，避免不符合用户预期。
+
+#### 批量查询与列表查询的选择
+- 使用 `drive file.comments batch_query` 是**已知评论 ID 后**的批量查询，需要传入具体的评论 ID 列表。
+- 使用 `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论，或获取"最新/最后 N 条评论"等场景。
+
+#### 评论定位字段
+- 需要根据评论定位到文档正文位置时（例如根据评论 review 文档、区分多处相同引用文本、把评论落点映射到 `docs +fetch` 的 block），先确认目标是 `file_type=docx`，再阅读 [评论定位字段说明](references/lark-drive-comment-location.md)，其他文档类型暂不支持返回定位字段。
+
+#### Reaction / 表情场景
+- 遇到评论 / 回复上的 reaction（表情、各表情数量、谁点了什么、添加/删除表情）相关问题时，**先阅读 [lark-drive-reactions.md](../../skills/lark-drive/references/lark-drive-reactions.md) 了解如何使用**。
 
 ### 典型错误与解决方案
 
@@ -90,52 +232,70 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
 | `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides） |
 
-### 权限能力入口
+#### `permission.public.patch` 错误码引导
 
-- 用户要管理 Drive 文档/文件协作者、公开权限、授权当前应用访问文档，或处理 `permission.public.patch` 的 `91009` / `91010` / `91011` / `91012` 错误时，先读 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。
-- 用户只是没有访问权限并希望向 owner 申请访问，优先使用 [`+apply-permission`](references/lark-drive-apply-permission.md)。
-- 普通 scope、身份或登录问题仍按 [`lark-shared`](../lark-shared/SKILL.md) 处理；不要把租户安全策略、对外分享、密级拦截简单归类为缺 scope。
+调用 `lark-cli drive permission.public patch` 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。
 
-## 不在本 skill 范围
+| 错误码 | 含义                     | 给用户的引导 |
+|--------|------------------------|--------------|
+| `91009` | 对外分享被租户安全策略管控，当前用户无法开启 | 提示用户：对外分享能力被租户安全策略统一管控，无法通过 API 或当前用户直接开启；需要联系租户管理员调整组织级对外分享策略。 |
+| `91010` | 文档对外分享未打开              | 提示用户：当前文档尚未打开对外分享，请先在文档权限设置中打开对外分享，再重试 `permission.public.patch`。 |
+| `91011` | 对外分享被文档密级管控            | 提示用户：对外分享被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
+| `91012` | 权限设置被文档密级管控            | 提示用户：该权限设置被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
 
-- 文档正文读取、总结、创建、编辑、图片/附件插入或下载：使用 [`lark-doc`](../lark-doc/SKILL.md)。
-- 电子表格单元格、筛选、公式、样式等表内操作：使用 [`lark-sheets`](../lark-sheets/SKILL.md)。
-- Base / 多维表格内部的表、字段、记录、视图、仪表盘等操作：使用 [`lark-base`](../lark-base/SKILL.md)。
-- 知识空间、Wiki 节点层级、空间成员管理：使用 [`lark-wiki`](../lark-wiki/SKILL.md)；上传本地文件到 wiki 节点仍用 `drive +upload --wiki-token`。
-- 原生 Markdown 文件读取、写入、patch、diff：使用 [`lark-markdown`](../lark-markdown/SKILL.md)；把 Markdown 导入成在线 docx 才用 `drive +import --type docx`。
+当用户最初提供的是文档 URL，遇到 `91011` 或 `91012` 时直接把该 URL 原样返回给用户作为操作入口；如果上下文只有 token，需要先尽量通过已有上下文、搜索结果或元数据恢复目标文档 URL，再给出可点击的文档 URL。
+
+### 授权当前应用访问文档
+
+当需要将文档权限授予**当前应用（bot）自身**时，先通过 bot info 接口获取应用的 open_id，再调用权限接口授权：
+
+```bash
+# 1. 获取当前应用的 open_id
+lark-cli api GET /open-apis/bot/v3/info --as bot
+# 从返回值中取 bot.open_id
+
+# 2. 授权当前应用访问文档
+lark-cli drive permission.members create \
+  --params '{"token":"<doc_token>","type":"<resource_type>"}' \
+  --data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'
+```
+
+> **注意**：此方式仅适用于需要授权给**当前应用**的场景。授权给其他用户时，直接使用对方的 open_id 即可，无需调用 bot info 接口。
+
+`<resource_type>` 可选值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`、`slides`。
 
 ## Shortcuts（推荐优先使用）
 
 Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）。有 Shortcut 的操作优先使用。
 
-| Shortcut | 说明 |
-|----------|----------|
-| [`+search`](references/lark-drive-search.md) | 搜索文档、Wiki、表格、文件夹等云空间对象；支持 `--edited-since`、`--mine`、`--doc-types` 等扁平 flag。 |
-| [`+upload`](references/lark-drive-upload.md) | 上传本地文件到 Drive 文件夹或 wiki 节点。 |
-| [`+create-folder`](references/lark-drive-create-folder.md) | 新建 Drive 文件夹，支持父文件夹与 bot 创建后自动授权。 |
-| [`+download`](references/lark-drive-download.md) | 下载 Drive 文件到本地。 |
-| [`+preview`](references/lark-drive-preview.md) | 查看或下载文件的 PDF / HTML / 文本 / 图片等预览产物。 |
-| [`+cover`](references/lark-drive-cover.md) | 查看或下载文件封面图规格。 |
-| [`+status`](references/lark-drive-status.md) | 比较本地目录与 Drive 文件夹差异；默认按 SHA-256 精确比较，`--quick` 使用修改时间近似比较。 |
-| [`+pull`](references/lark-drive-pull.md) | 从 Drive 拉取文件到本地目录，支持重复远端路径处理和增量模式。 |
-| `+sync` | 双向同步本地目录与 Drive 文件夹：拉取 `new_remote`、推送 `new_local`，`modified` 按 `--on-conflict=remote-wins\|local-wins\|keep-both\|ask` 处理；`--quick` 用修改时间近似比较；`--on-duplicate-remote` 支持 `fail` / `newest` / `oldest`；只同步 `type=file`，跳过在线文档和 shortcut，且不会删除两端多余文件。 |
-| [`+push`](references/lark-drive-push.md) | 将本地目录推送到 Drive 文件夹，支持 skip / smart / overwrite 与确认后删除远端。 |
-| [`+create-shortcut`](references/lark-drive-create-shortcut.md) | 在另一个文件夹里创建现有 Drive 文件的快捷方式。 |
-| [`+add-comment`](references/lark-drive-add-comment.md) | 给 doc/docx/file/sheet/slides 添加评论；评论统计、回复和 reaction 细则见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。 |
-| [`+export`](references/lark-drive-export.md) | 将 doc/docx/sheet/bitable/slides 导出为本地文件。 |
-| [`+export-download`](references/lark-drive-export-download.md) | 根据导出产物的 file_token 下载文件。 |
-| [`+import`](references/lark-drive-import.md) | 将本地文件导入为飞书在线文档、表格、多维表格或幻灯片。 |
-| [`+version-history`](references/lark-drive-version-history.md) | 查看文件历史版本。 |
-| [`+version-get`](references/lark-drive-version-get.md) | 下载指定历史版本。 |
-| [`+version-revert`](references/lark-drive-version-revert.md) | 回滚到指定历史版本。 |
-| [`+version-delete`](references/lark-drive-version-delete.md) | 删除指定历史版本。 |
-| [`+move`](references/lark-drive-move.md) | 移动 Drive 文件或文件夹；Wiki 层级移动走 `lark-wiki`。 |
-| [`+delete`](references/lark-drive-delete.md) | 删除 Drive 文件或文件夹，文件夹删除会轮询异步任务。 |
-| [`+task_result`](references/lark-drive-task-result.md) | 查询 import/export/move/delete 等异步任务结果。 |
-| [`+inspect`](references/lark-drive-inspect.md) | 检视 URL 的类型、标题和 canonical token；wiki URL 会自动解包到底层文档。 |
-| [`+apply-permission`](references/lark-drive-apply-permission.md) | 以 user 身份向文档 owner 申请访问权限。 |
-| [`+secure-label-list`](references/lark-drive-secure-label.md) | 列出当前用户可用的密级标签。 |
-| [`+secure-label-update`](references/lark-drive-secure-label.md) | 更新 Drive 文件或文档的密级标签。 |
+| Shortcut | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`+search`](references/lark-drive-search.md) | Search Lark docs, Wiki, and spreadsheet files with flat filter flags. Natural-language-friendly: `--edited-since`, `--mine`, `--doc-types`, etc.                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`+upload`](references/lark-drive-upload.md) | Upload a local file to a Drive folder or wiki node                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [`+create-folder`](references/lark-drive-create-folder.md) | Create a Drive folder, optionally under a parent folder, with bot auto-grant support                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| [`+download`](references/lark-drive-download.md) | Download a file from Drive to local                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`+preview`](references/lark-drive-preview.md) | List or download available preview artifacts for a Drive file; explicit `--type` required for downloads |
+| [`+cover`](references/lark-drive-cover.md) | List or download stable built-in cover presets for a Drive file; download-time HTTP 404 means the file has no artifact for that cover spec |
+| [`+status`](references/lark-drive-status.md) | Compare a local directory with a Drive folder by exact SHA-256 hash by default, or use `--quick` for a best-effort modified-time diff that skips remote downloads; reports `new_local` / `new_remote` / `modified` / `unchanged` plus `detection=exact` or `detection=quick`. Duplicate remote `rel_path` conflicts fail fast with `error.type=duplicate_remote_path` and list every conflicting entry; do not proceed as if one was chosen. `--local-dir` 必须是 cwd 内的相对路径，越界路径 CLI 会直接拒绝；目标在 cwd 外时引导用户切换 agent 工作目录，不要私自 `cd` 绕过。 |
+| [`+pull`](references/lark-drive-pull.md) | File-level Drive → local mirror. Duplicate remote `rel_path` conflicts fail by default; for duplicate files, `rename` downloads all copies with stable hashed suffixes, while `newest` / `oldest` pick one. `--if-exists` supports `overwrite` / `smart` / `skip` (`smart` is a best-effort modified-time incremental mode for repeat syncs). `--delete-local` requires `--yes`, only removes regular files, and is skipped after item failures. `--local-dir` must stay inside cwd.                                               |
+| `+sync` | Two-way local ↔ Drive sync. Reuses `+status` diff buckets, pulls `new_remote`, pushes `new_local`, and resolves `modified` via `--on-conflict=remote-wins|local-wins|keep-both|ask`. `--quick` enables best-effort modified-time diffing (timestamp mismatches can still trigger real pull/push actions), `--on-duplicate-remote` supports `fail|newest|oldest`, and the command is intentionally non-destructive (no delete on either side). |
+| [`+create-shortcut`](references/lark-drive-create-shortcut.md) | Create a shortcut to an existing Drive file in another folder                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`+add-comment`](references/lark-drive-add-comment.md) | Add a comment to doc/docx/file/sheet/slides, also supports wiki URL resolving to doc/docx/file/sheet/slides; file targets support selected extensions and full comments only                                                                                                                                                                                                                                                                                                                                                       |
+| [`+export`](references/lark-drive-export.md) | Export a doc/docx/sheet/bitable/slides to a local file with limited polling; supports `--file-name` for local naming                                                                                                                                                                                                                                                                                                                                                                                                               |
+| [`+export-download`](references/lark-drive-export-download.md) | Download an exported file by file_token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| [`+import`](references/lark-drive-import.md) | Import a local file to Drive as a cloud document (docx, sheet, bitable, slides)                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`+version-history`](references/lark-drive-version-history.md) | List historical versions of a file with only_tag=true and cursor-based pagination                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| [`+version-get`](references/lark-drive-version-get.md) | Download a specific historical version of a file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`+version-revert`](references/lark-drive-version-revert.md) | Revert a file to a specific historical version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| [`+version-delete`](references/lark-drive-version-delete.md) | Delete a specific historical version of a file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| [`+move`](references/lark-drive-move.md) | Move a file or folder to another location in Drive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [`+delete`](references/lark-drive-delete.md) | Delete a Drive file or folder with limited polling for folder deletes                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| [`+push`](references/lark-drive-push.md) | File-level local → Drive mirror. Duplicate remote `rel_path` conflicts fail by default; `newest` / `oldest` only apply to duplicate files when you explicitly want to target one remote file. `--if-exists` supports `skip` / `smart` / `overwrite` (`smart` skips files whose remote `modified_time` is already up to date, but falls through to the same overwrite path when the remote is older, so it inherits overwrite's rollout caveat). `--delete-remote` requires `--yes`. `--local-dir` must stay inside cwd.            |
+| [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| [`+inspect`](references/lark-drive-inspect.md) | Inspect a Lark document URL to get its type, title, and canonical token; auto-unwraps wiki URLs to the underlying document                                                                                                                                                                                                                                                                                                                                                                                                         |
+| [`+apply-permission`](references/lark-drive-apply-permission.md) | Apply to the document owner for view/edit access (user-only; 5/day per document)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`+secure-label-list`](references/lark-drive-secure-label.md) | List secure labels available to the current user |
+| [`+secure-label-update`](references/lark-drive-secure-label.md) | Update a Drive file/document secure label; downgrade approval errors require opening the document UI |
 
 ## API Resources
 
@@ -202,3 +362,35 @@ lark-cli drive <resource> <method> [flags] # 调用 API
   - `get` — 获取当前用户的容量信息，包含各业务使用量、租户配额是否超限、用户配额、所在部门配额
     - 仅支持 `--as user`，不要使用默认的 bot 身份
     - `quota_detail_id` 传当前用户的 `user_id`
+
+## 权限表
+
+| 方法                                             | 所需 scope                             |
+|------------------------------------------------|--------------------------------------|
+| `files.copy`                                   | `docs:document:copy`                 |
+| `files.create_folder`                          | `space:folder:create`                |
+| `files.list`                                   | `space:document:retrieve`            |
+| `files.patch`                                  | `docx:document:write_only`           |
+| `file.comments.batch_query`                    | `docs:document.comment:read`         |
+| `file.comments.create_v2`                      | `docs:document.comment:create`       |
+| `file.comments.list`                           | `docs:document.comment:read`         |
+| `file.comments.patch`                          | `docs:document.comment:update`       |
+| `file.comment.replys.create`                   | `docs:document.comment:create`       |
+| `file.comment.replys.delete`                   | `docs:document.comment:delete`       |
+| `file.comment.replys.list`                     | `docs:document.comment:read`         |
+| `file.comment.replys.update`                   | `docs:document.comment:update`       |
+| `permission.members.auth`                      | `docs:permission.member:auth`        |
+| `permission.members.create`                    | `docs:permission.member:create`      |
+| `permission.members.transfer_owner`            | `docs:permission.member:transfer`    |
+| `permission.public.get`                        | `docs:permission.setting:read`       |
+| `permission.public.patch`                      | `docs:permission.setting:write_only` |
+| `metas.batch_query`                            | `drive:drive.metadata:readonly`      |
+| `user.remove_subscription`                     | `docs:event:subscribe`               |
+| `user.subscription`                            | `docs:event:subscribe`               |
+| `user.subscription_status`                     | `docs:event:subscribe`               |
+| `file.statistics.get`                          | `drive:drive.metadata:readonly`      |
+| `file.view_records.list`                       | `drive:file:view_record:readonly`    |
+| `file.comment.reply.reactions.update_reaction` | `docs:document.comment:create`       |
+| `quota_details.get`                            | `drive:quota_detail:read_one`        |
+
+> `quota_details.get` 是 user-only OpenAPI：调用时必须显式传 `--as user`，且 `quota_detail_id` 应填写当前用户的 `user_id`。

skills/lark-drive/references/lark-drive-comments-guide.md

@@ -1,72 +0,0 @@
-# Drive 评论查询、统计与回复指南
-
-> 前置条件：先阅读 [`../SKILL.md`](../SKILL.md) 的“评论能力入口”，添加评论参数细节见 [`lark-drive-add-comment.md`](lark-drive-add-comment.md)，reaction 见 [`lark-drive-reactions.md`](lark-drive-reactions.md)。
-
-## 评论模式
-
-- `drive +add-comment` 支持全文评论和局部评论。
-- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc` / `docx` / `file` 的 wiki URL。
-- 局部评论：传 `--block-id` 时启用；`docx` 支持文本定位或 block id，`sheet` 支持 `<sheetId>!<cell>`，`slides` 支持 `<slide-block-type>!<xml-id>`，wiki URL 解析到这些类型时也支持对应局部评论。
-- Drive file 只支持全文评论，不支持局部评论。支持扩展名：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件暂不支持。
-- Review / 审阅 / 校对 / 逐条指出问题场景优先使用局部评论，不要把多个可定位问题汇总成一条全文评论。
-- `drive +add-comment` 的 `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。
-- `slides` 评论要求显式传 `--block-id <slide-block-type>!<xml-id>`；CLI 会将其拆分后写入 `anchor.block_id` 和 `anchor.slide_block_type`。其中 `<xml-id>` 是 PPT XML 协议中的元素 `id`；不支持 `--selection-with-ellipsis` 和 `--full-comment`。
-- 评论写入内容里的文本不能直接出现 `<`、`>`；提交前应转义为 `&lt;`、`&gt;`。`drive +add-comment` 会对 `type=text` 文本元素自动兜底转义；直接调用原生评论 API 时需要自行转义。
-- 如果 wiki 解析后不是 `doc` / `docx` / `file` / `sheet` / `slides`，不要用 `+add-comment`。
-
-## 查询默认口径
-
-`drive file.comments list` 默认必须传 `is_solved:false`，即仅查询未解决评论。即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确提到要包含已解决评论，仍然按默认口径查询未解决评论。仅当用户明确要求包含已解决评论时，才可省略 `is_solved` 参数。
-
-```bash
-# 默认查询：仅未解决评论
-lark-cli drive file.comments list --params '{"file_token":"xxx","file_type":"docx","is_solved":false}'
-
-# 包含已解决评论：仅当用户明确要求时使用
-lark-cli drive file.comments list --params '{"file_token":"xxx","file_type":"docx"}'
-```
-
-## 评论卡片与统计
-
-- `drive file.comments list` 返回的 `items` 是评论卡片列表，每个 `item` 对应用户界面中的一张评论卡片，不是平铺的互动消息列表。
-- 创建第一条评论时会同时创建该卡片里的第一条 reply；真正承载正文的是 `item.reply_list.replies`，其中第一条 reply 在用户视角下就是这张卡片里的“评论本身”。
-- 统计“评论数”或“评论卡片数”：统计 `items` 长度；全量统计时对所有分页返回的 `items` 长度累加。
-- 统计“回复数”：统计所有 `item.reply_list.replies` 长度之和，再减去 `items` 长度。
-- 统计“总互动数”：统计所有 `item.reply_list.replies` 长度之和，包含每张评论卡片里的首条评论。
-- 如果 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中；需要继续调用 `drive file.comment.replys list` 拉全后，再做全量回复数或总互动数统计。
-
-## 排序
-
-- 只有当用户明确提到“最新评论”“最后评论”“最早评论”时，才需要按 `create_time` 排序。
-- 排序前必须拉完所有评论分页，不能只取第一页。
-- “最新评论”/“最后评论”：按 `create_time` 降序取第一条。
-- “最早评论”：按 `create_time` 升序取第一条。
-- 用户只说“第一条评论”时，直接使用 `drive file.comments list` 返回的第一条，不需要额外排序。
-
-## 回复限制
-
-- 回复前先检查目标评论状态。
-- `is_whole=true` 的全文评论不支持回复；遇到时提示“全文评论不支持回复”。
-- `is_solved=true` 的已解决评论不支持回复；遇到时提示“该评论已被解决，无法回复”。
-- 当目标评论不能回复时，只提示限制，不要自动替用户寻找其他可回复评论。
-
-## batch_query 与 list
-
-- `drive file.comments batch_query` 用于已知评论 ID 后的批量查询，需要传入具体评论 ID 列表。
-- `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论、获取最新或最后 N 条评论等场景。
-
-## 评论定位字段
-
-- 需要根据评论定位到文档正文位置时（例如根据评论 review 文档、区分多处相同引用文本、把评论落点映射到 `docs +fetch` 的 block），先确认目标是 `file_type=docx`，再阅读 [`lark-drive-comment-location.md`](lark-drive-comment-location.md)。
-- 其他文档类型暂不支持返回定位字段。
-
-## 原生 API
-
-需要更底层地直接调用评论 V2 协议时，先查看 schema，再调用原生命令。全文评论省略 `anchor`，局部评论传 `anchor.block_id`。
-
-```bash
-lark-cli schema drive.file.comments.create_v2
-lark-cli drive file.comments create_v2 \
-  --params '{"file_token":"<DOC_TOKEN>"}' \
-  --data '{"file_type":"docx","reply_elements":[{"type":"text","text":"全文评论内容"}]}'
-```

skills/lark-drive/references/lark-drive-permission-guide.md

@@ -1,41 +0,0 @@
-# Drive 权限与授权指南
-
-> 前置条件：通用认证、scope 与 `--as` 规则见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
-
-## 何时读取
-
-- 用户要修改文档公开权限，尤其是 `drive permission.public patch` 返回 `91009` / `91010` / `91011` / `91012`。
-- 用户要给文档、文件、文件夹、Wiki 或 slides 增加协作者权限，或把访问权限授予当前应用（bot）自身。
-- 用户遇到 `permission denied`，但错误表现更像租户对外分享、安全策略或密级拦截，而不是普通 scope 缺失。
-
-如果用户只是想向文档 owner 申请访问权限，优先使用 [`lark-drive-apply-permission.md`](lark-drive-apply-permission.md)。
-
-## 公开权限错误码
-
-调用 `lark-cli drive permission.public patch` 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。
-
-| 错误码 | 含义 | 给用户的引导 |
-|--------|------|--------------|
-| `91009` | 对外分享被租户安全策略管控，当前用户无法开启 | 提示用户：对外分享能力被租户安全策略统一管控，无法通过 API 或当前用户直接开启；需要联系租户管理员调整组织级对外分享策略。 |
-| `91010` | 文档对外分享未打开 | 提示用户：当前文档尚未打开对外分享，请先在文档权限设置中打开对外分享，再重试 `permission.public.patch`。 |
-| `91011` | 对外分享被文档密级管控 | 提示用户：对外分享被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
-| `91012` | 权限设置被文档密级管控 | 提示用户：该权限设置被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
-
-当用户最初提供的是文档 URL，遇到 `91011` 或 `91012` 时直接把该 URL 原样返回给用户作为操作入口；如果上下文只有 token，需要先尽量通过已有上下文、搜索结果或元数据恢复目标文档 URL，再给出可点击的文档 URL。
-
-## 授权当前应用访问文档
-
-需要将文档权限授予当前应用（bot）自身时：
-
-1. 先执行 `lark-cli api GET /open-apis/bot/v3/info --as bot`，从返回值取 `bot.open_id`。
-2. 再调用 `lark-cli drive permission.members create`，用 `member_type=openid`、`member_id=<bot_open_id>` 授权。
-
-```bash
-lark-cli drive permission.members create \
-  --params '{"token":"<doc_token>","type":"<resource_type>"}' \
-  --data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'
-```
-
-此方式仅适用于授权给当前应用。授权给其他用户时，直接使用对方的 open_id，无需调用 bot info 接口。
-
-`<resource_type>` 可选值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`、`slides`。

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

@@ -1,6 +1,6 @@
 # drive reactions
 
-> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论入口，再阅读 [`lark-drive-comments-guide.md`](lark-drive-comments-guide.md) 了解评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；同时阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；再阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 处理文档评论 / 回复上的 reaction（点赞、表情、各表情数量、谁点了什么、添加/删除表情）。这个场景不常见，但规则比较集中：查询时只有在用户明确需要 reaction 信息时才带 `need_reaction=true`；写入时统一使用 `drive file.comment.reply.reactions update_reaction`，操作对象始终是 `reply_id`。
 

skills/lark-im/references/lark-im-feed-shortcut-create.md

@@ -9,7 +9,7 @@ This skill maps to shortcut: `lark-cli im +feed-shortcut-create`. Underlying API
 Adds one or more chats to the **current user's** feed shortcuts — equivalent to right-clicking a chat in the Feishu client and pinning it to the feed sidebar.
 
 - Only **CHAT-type** shortcuts are exposed by the OpenAPI gateway right now (`feed_card_id` must be an `oc_xxx` open_chat_id).
-- Batch up to **10 chat IDs per call**; pass more by issuing multiple calls.
+- The upstream OAPI currently documents up to 50 items per write call, but this CLI intentionally enforces a stricter **30 chat IDs per call** local limit; pass more by issuing multiple calls.
 - Currently only supports **user identity** (`--as user`); bot identity is not allowed by the server.
 - If you only know a group name, resolve its `oc_xxx` first with `im +chat-search` or `im +chat-list`.
 
@@ -34,7 +34,7 @@ lark-cli im +feed-shortcut-create --as user --chat-id oc_xxx --dry-run
 
 | Parameter | Default | Description |
 |------|------|------|
-| `--chat-id <oc_xxx>` | required | open_chat_id to add as a feed shortcut; repeatable or comma-separated; **max 10 per call** |
+| `--chat-id <oc_xxx>` | required | open_chat_id to add as a feed shortcut; repeatable or comma-separated; **CLI max 30 per call** |
 | `--head` | true (implied) | Insert at the top of the shortcut list; mutually exclusive with `--tail` |
 | `--tail` | false | Append at the bottom of the shortcut list |
 | `--as user` | required | Server only accepts user_access_token for this API |

skills/lark-im/references/lark-im-feed-shortcut-list.md

@@ -6,45 +6,32 @@ This skill maps to shortcut: `lark-cli im +feed-shortcut-list`. Underlying API:
 
 ## What it does
 
-Lists **one page** of the **current user's** feed shortcuts.
+Lists the **current user's full** feed shortcut list.
 
 - Only **CHAT-type** shortcuts are exposed via OpenAPI today (others in the IDL are not yet whitelisted).
-- The shortcut is a **thin one-page wrapper** — there is no built-in auto-pagination. Callers drive their own loop when they actually need to paginate.
-- Server-side page size is controlled by the service; in normal use one page usually covers the list.
-- Pagination tokens are opaque. If a token is rejected because the shortcut list changed, restart by omitting `--page-token`.
+- The latest OAPI contract returns the whole list directly, so this shortcut exposes **no pagination flags**.
+- The shortcut also does **not** perform any follow-up `im.chats.batch_query` detail enrichment.
 
 ## Commands
 
 ```bash
-# First page (the only call most users ever need — --page-token omitted)
+# List the current user's full shortcut list
 lark-cli im +feed-shortcut-list --as user
-
-# Continue from the previous response's page_token
-lark-cli im +feed-shortcut-list --as user --page-token <token-from-previous-response>
-
-# Skip detail enrichment when only IDs are needed; avoids the extra im:chat:read lookup
-lark-cli im +feed-shortcut-list --as user --no-detail -q '.data.shortcuts[].feed_card_id'
 ```
 
-> If you need to walk every page, write the loop yourself: read `data.page_token` from each response and pass it back in until `has_more=false`. The shortcut intentionally does not auto-walk because page-token errors require the caller to decide whether to restart from the first page.
-
 ## Parameters
 
 | Parameter | Required | Description |
 |------|------|------|
-| `--page-token <token>` | no | Opaque pagination token from the previous response. **Omit it for the first page.** |
-| `--no-detail` | no (default `false`) | Skip fetching each entry's full info object. By default enrichment is enabled: CHAT-type entries call `im.chats.batch_query`, need `im:chat:read`, and attach the object under the `detail` field. Pass `--no-detail` to skip the extra call and scope. |
 | `--as user` | yes | Server only accepts user_access_token for this API |
 
 ## Response Structure
 
 | Field | Type | Description |
 |------|------|------|
-| `shortcuts` | array | Feed shortcut entries; each has `feed_card_id` (oc_xxx) and `type` (1=CHAT). By default (without `--no-detail`), each entry also has a `detail` field with the full per-type info object. |
-| `has_more` | boolean | Whether more pages exist |
-| `page_token` | string | Opaque token to pass to the next call when continuing pagination |
+| `shortcuts` | array | Feed shortcut entries; each has `feed_card_id` (oc_xxx) and `type` (1=CHAT). |
 
-Example (with detail enrichment, CHAT type):
+Example:
 
 ```json
 {
@@ -52,52 +39,18 @@ Example (with detail enrichment, CHAT type):
     "shortcuts": [
       {
         "feed_card_id": "oc_092f0100fe59c35995727db1039777a8",
-        "type": 1,
-        "detail": {
-          "chat_id": "oc_092f0100fe59c35995727db1039777a8",
-          "chat_mode": "group",
-          "name": "Engineering",
-          "avatar": "https://...",
-          "description": "",
-          "external": false,
-          "owner_id": "ou_xxx",
-          "owner_id_type": "open_id",
-          "tenant_key": "..."
-        }
+        "type": 1
       },
       {
         "feed_card_id": "oc_c82061d126a06635aa3569587b134bb1",
-        "type": 1,
-        "detail": {
-          "chat_id": "oc_c82061d126a06635aa3569587b134bb1",
-          "chat_mode": "p2p",
-          "name": "",
-          "p2p_target_id": "ou_xxx",
-          "p2p_target_type": "user",
-          "avatar": "",
-          "description": "",
-          "external": false,
-          "tenant_key": "..."
-        }
+        "type": 1
       }
-    ],
-    "has_more": false,
-    "page_token": "v1.example-opaque-token"
+    ]
   }
 }
 ```
 
-## Detail Enrichment
-
-The `detail` payload is dispatched **per `type`**. Today only CHAT is wired in; future shortcut types can attach different object shapes. Callers should `switch` on `type` before parsing `detail`. For CHAT (`type=1`):
-
-- **Source**: `POST /open-apis/im/v1/chats/batch_query` (50 ids per call, server limit).
-- **Payload**: the **full chat object** is passed through verbatim — `chat_id`, `chat_mode` (`group` / `p2p` / `topic`), `name`, `avatar`, `description`, `external`, `tenant_key`, plus type-specific fields (`owner_id*` for groups, `p2p_target_*` for p2p).
-- **P2P chats** return an empty `name` because the Feishu client renders the partner's display name there. The rest of the object (especially `p2p_target_id`) still flows through, so callers can resolve the partner via `+contact-search` if a display title is needed.
-- **Lookup failure** (missing scope, network error) → the list still returns successfully; a warning is printed to stderr, the data payload carries a `_notice` field (`"detail enrichment skipped: ..."`), and affected entries simply lack the `detail` field. Check `_notice` to tell "enrichment skipped" from "nothing to enrich".
-
 ## Permissions
 
 - Required scope: `im:feed.shortcut:read`
-- Conditional scope (default detail path only): `im:chat:read`; pass `--no-detail` to avoid this extra scope and lookup.
 - Only available with user identity (`--as user`).

skills/lark-im/references/lark-im-feed-shortcut-remove.md

@@ -9,7 +9,7 @@ This skill maps to shortcut: `lark-cli im +feed-shortcut-remove`. Underlying API
 Removes one or more chats from the **current user's** feed shortcuts.
 
 - Only **CHAT-type** shortcuts are supported (`feed_card_id` must be an `oc_xxx`).
-- Batch up to **10 chat IDs per call**.
+- The upstream OAPI currently documents up to 50 items per write call, but this CLI intentionally enforces a stricter **30 chat IDs per call** local limit.
 - Currently only supports **user identity** (`--as user`).
 - Removing a chat that is not currently in the shortcut list is idempotent success: the call returns `ok:true`, `failure_count=0`, and no `failed_shortcuts` entry for that chat.
 
@@ -31,7 +31,7 @@ lark-cli im +feed-shortcut-remove --as user --chat-id oc_xxx --dry-run
 
 | Parameter | Required | Description |
 |------|------|------|
-| `--chat-id <oc_xxx>` | yes | open_chat_id to remove from feed shortcuts; repeatable or comma-separated; max 10 per call |
+| `--chat-id <oc_xxx>` | yes | open_chat_id to remove from feed shortcuts; repeatable or comma-separated; CLI max 30 per call |
 | `--as user` | yes | Server only accepts user_access_token for this API |
 
 ## Response
@@ -45,4 +45,4 @@ The response uses the same batch ledger as [`+feed-shortcut-create`](lark-im-fee
 
 ## Note
 
-- To see what is currently in the shortcut list before removing, run [`+feed-shortcut-list`](lark-im-feed-shortcut-list.md). Use `--no-detail` when you only need the `feed_card_id` values.
+- To see what is currently in the shortcut list before removing, run [`+feed-shortcut-list`](lark-im-feed-shortcut-list.md).

skills/lark-shared/references/lark-wiki-token-routing.md

@@ -1,42 +0,0 @@
-# Wiki token routing
-
-Wiki URL 中的 `/wiki/<token>` 是节点 token，不一定是底层文档、表格、Base、文件或幻灯片的对象 token。需要对底层对象做读取、评论、导出、下载、表内操作等动作时，先解包，再按底层类型路由。
-
-## 推荐方式
-
-优先使用 `lark-drive` 的 `drive +inspect`：
-
-```bash
-lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/<wiki_token>'
-```
-
-输出中的 `type` 是底层对象类型，`token` 是后续命令应使用的 canonical token。`wiki_node` 字段保留节点侧信息，如 `space_id`、`node_token`、`obj_token`、`obj_type`。
-
-## 手动方式
-
-如果不能使用 shortcut，再调用 Wiki 节点接口：
-
-```bash
-lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'
-```
-
-从返回值中读取：
-
-| 字段 | 含义 |
-|------|------|
-| `node.obj_type` | 底层对象类型，如 `docx`、`doc`、`sheet`、`bitable`、`slides`、`file`、`mindnote` |
-| `node.obj_token` | 底层对象 token，用于对应业务 skill 或原生 API |
-| `node.node_token` / `token` | Wiki 节点 token，用于 Wiki 节点层级操作 |
-| `node.space_id` | 所属知识空间 |
-
-## 路由
-
-| `obj_type` | 后续操作 |
-|------------|----------|
-| `docx` / `doc` | 文档内容走 `lark-doc`；评论、权限、导出等云空间能力走 `lark-drive` |
-| `sheet` | 表内数据走 `lark-sheets`；评论、权限、导出等云空间能力走 `lark-drive` |
-| `bitable` | 表内数据走 `lark-base`；评论、权限、导出等云空间能力走 `lark-drive` |
-| `slides` | 幻灯片内容编辑走 `lark-slides`；评论、权限、导出等云空间能力走 `lark-drive` |
-| `file` | 普通文件上传、下载、评论、权限等走 `lark-drive` |
-| `mindnote` | 思维笔记的移动、删除、快捷方式、权限、安全标签等云空间能力走 `lark-drive`；知识库节点层级操作走 `lark-wiki` |
-| wiki 节点层级 / 空间成员 | 走 `lark-wiki`，不要把底层对象 token 当节点 token |

tests/cli_e2e/im/feed_shortcut_workflow_test.go

@@ -55,7 +55,7 @@ func TestIM_FeedShortcutWorkflowAsUser(t *testing.T) {
 		}
 	})
 
-	t.Run("list feed shortcuts as user with detail enrichment", func(t *testing.T) {
+	t.Run("list feed shortcuts as user", func(t *testing.T) {
 		result, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
 			Args: []string{
 				"im", "+feed-shortcut-list",
@@ -85,43 +85,13 @@ func TestIM_FeedShortcutWorkflowAsUser(t *testing.T) {
 			}
 			found = true
 			require.Equal(t, int64(1), item.Get("type").Int(), "type should be 1 (CHAT)")
-			// detail enrichment is on by default — the chat we just created
-			// must come back with the chat info object attached.
-			require.True(t, item.Get("detail").Exists(),
-				"detail field should be attached when enrichment is enabled")
-			require.Equal(t, chatID, item.Get("detail.chat_id").String(),
-				"detail.chat_id should echo feed_card_id")
-			require.Equal(t, chatName, item.Get("detail.name").String(),
-				"detail.name should carry the chat's group name")
+			require.False(t, item.Get("detail").Exists(),
+				"detail field should not exist in the direct list contract")
 			break
 		}
 		require.True(t, found, "expected chat %s in feed shortcut list", chatID)
 	})
 
-	t.Run("list feed shortcuts with --no-detail skips lookup", func(t *testing.T) {
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{
-			Args: []string{
-				"im", "+feed-shortcut-list",
-				"--no-detail",
-			},
-			DefaultAs: "user",
-		})
-		require.NoError(t, err)
-		result.AssertExitCode(t, 0)
-		result.AssertStdoutStatus(t, true)
-
-		var foundEntry gjson.Result
-		for _, item := range gjson.Get(result.Stdout, "data.shortcuts").Array() {
-			if item.Get("feed_card_id").String() == chatID {
-				foundEntry = item
-				break
-			}
-		}
-		require.True(t, foundEntry.Exists(), "expected our chat in the bare list")
-		require.False(t, foundEntry.Get("detail").Exists(),
-			"detail field should NOT be present with --no-detail")
-	})
-
 	t.Run("unpin chat from feed as user", func(t *testing.T) {
 		result, err := clie2e.RunCmd(ctx, clie2e.Request{
 			Args: []string{
@@ -143,7 +113,6 @@ func TestIM_FeedShortcutWorkflowAsUser(t *testing.T) {
 		result, err := clie2e.RunCmdWithRetry(ctx, clie2e.Request{
 			Args: []string{
 				"im", "+feed-shortcut-list",
-				"--no-detail",
 			},
 			DefaultAs: "user",
 		}, clie2e.RetryOptions{
@@ -277,7 +246,7 @@ func cleanupFeedShortcuts(parentT *testing.T, defaultAs string, chatIDs ...strin
 	cleanupCtx, cancel := clie2e.CleanupContext()
 	defer cancel()
 	listResult, listErr := clie2e.RunCmd(cleanupCtx, clie2e.Request{
-		Args:      []string{"im", "+feed-shortcut-list", "--no-detail"},
+		Args:      []string{"im", "+feed-shortcut-list"},
 		DefaultAs: defaultAs,
 	})
 	clie2e.ReportCleanupFailure(parentT, "cleanup feed shortcuts list", listResult, listErr)
@@ -410,7 +379,7 @@ func TestIM_FeedShortcutDryRun(t *testing.T) {
 		require.NotContains(t, result.Stdout, "is_header", "remove must not send is_header")
 	})
 
-	t.Run("list dry-run mentions detail enrichment path", func(t *testing.T) {
+	t.Run("list dry-run hits feed_shortcuts endpoint directly", func(t *testing.T) {
 		result, err := clie2e.RunCmd(ctx, clie2e.Request{
 			Args: []string{
 				"im", "+feed-shortcut-list",
@@ -422,24 +391,7 @@ func TestIM_FeedShortcutDryRun(t *testing.T) {
 		result.AssertExitCode(t, 0)
 		require.Contains(t, result.Stdout, "GET")
 		require.Contains(t, result.Stdout, "/open-apis/im/v2/feed_shortcuts")
-		// Enrichment is on by default → DryRun adds a desc about the extra
-		// chats.batch_query call and the conditional scope.
-		require.Contains(t, result.Stdout, "im:chat:read")
-		require.Contains(t, result.Stdout, "batch_query")
-	})
-
-	t.Run("list dry-run with --no-detail omits the extra-scope note", func(t *testing.T) {
-		result, err := clie2e.RunCmd(ctx, clie2e.Request{
-			Args: []string{
-				"im", "+feed-shortcut-list",
-				"--no-detail",
-				"--dry-run",
-			},
-			DefaultAs: "user",
-		})
-		require.NoError(t, err)
-		result.AssertExitCode(t, 0)
-		require.NotContains(t, result.Stdout, "im:chat:read",
-			"with --no-detail, dry-run must not mention im:chat:read")
+		require.NotContains(t, result.Stdout, "im:chat:read")
+		require.NotContains(t, result.Stdout, "batch_query")
 	})
 }