refactor(sheets): drop +recover flag/shortcut registration (split to PR #1414)

+recover (方案B) moved to its own PR (#1414). This PR (方案A) keeps +undo and
the read/write transaction_id split. The recover_to_revision server impl lives
in the facade recover MR.

.github/CODEOWNERS

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

.gitignore

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

.golangci.yml

@@ -73,20 +73,20 @@ linters:
           - forbidigo
       # errs-typed-only enforced on paths already migrated to errs.NewXxxError.
       # Add a path when its migration is complete.
-      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/apps/|shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/|internal/event/consume/|cmd/event/|events/|shortcuts/event/)
+      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/calendar/helpers\.go|shortcuts/drive/)
         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/drive/|shortcuts/calendar/helpers\.go|shortcuts/common/mcp_client\.go)
         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/)
+      # errs-no-legacy-helper is drive-only: the shared helpers it bans are
+      # still used by other domains until their later migration phase.
+      - path-except: (shortcuts/drive/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo
@@ -115,15 +115,17 @@ linters:
           msg: >-
             [errs-typed-only] use errs.NewXxxError(...) builder
             (see errs/types.go).
-        # ── legacy shared error helpers banned on migrated domains ──
-        # These helpers emit legacy output.Err* / bare error shapes or drop
-        # typed metadata such as Param/Cause. Migrated domains must use typed
-        # common replacements or local typed helpers instead.
-        - pattern: (common\.FlagErrorf|common\.RejectDangerousChars|common\.WrapInputStatError|common\.WrapSaveErrorByCategory)\b
+        # ── legacy shared error helpers banned on drive ──
+        # These helpers internally produce legacy output.Err* shapes, so they
+        # are invisible to the errs-typed-only ban above. Drive has migrated its
+        # calls to typed errs.* (drive-local driveInputStatError / driveSaveError);
+        # this prevents reintroduction. Other domains still use the shared
+        # helpers (migrated globally in a later phase), so this is drive-scoped.
+        - pattern: (common\.FlagErrorf|common\.WrapInputStatError|common\.WrapSaveErrorByCategory)\b
           msg: >-
-            [errs-no-legacy-helper] these shared helpers emit legacy or
-            metadata-poor error shapes. Use typed common replacements, typed
-            errs.NewXxxError builders, or domain-local typed helpers.
+            [errs-no-legacy-helper] these shared helpers emit legacy output.Err*
+            shapes. Use the typed errs.NewXxxError builders or the drive-local
+            driveInputStatError / driveSaveError helpers (shortcuts/drive/drive_errors.go).
         # ── bare error wraps banned on fully-typed paths ──
         - pattern: (fmt\.Errorf|errors\.New)\b
           msg: >-

.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
 ```
 
@@ -75,31 +75,7 @@ The one rule to internalize: **every error message you write will be parsed by a
 
 ### Structured errors in commands
 
-Command-facing failures must be typed `errs.*` errors — never the legacy `output.Err*` helpers and never a final bare `fmt.Errorf`. AI agents parse the stderr envelope's `type` / `subtype` / `param` / `hint` fields to decide their next action; the full taxonomy lives in `errs/ERROR_CONTRACT.md`.
-
-Picking a constructor:
-
-| Failure | Constructor |
-|---------|-------------|
-| User flag/arg fails validation | `errs.NewValidationError(errs.SubtypeInvalidArgument, ...).WithParam("--flag")` |
-| Valid request, wrong system state | `errs.NewValidationError(errs.SubtypeFailedPrecondition, ...).WithHint(...)` |
-| Lark API returned `code != 0` | `runtime.CallAPITyped` (shortcuts) / `errclass.BuildAPIError` (raw responses) — never hand-build |
-| Network / transport failure | `errs.NewNetworkError(errs.SubtypeNetworkTransport, ...)` |
-| Local file I/O failure | `errs.NewInternalError(errs.SubtypeFileIO, ...)` — validate the path first (`validate.SafeInputPath` / `SafeOutputPath`) and use `vfs.*` |
-| Unclassified lower-layer error as final | `errs.NewInternalError(errs.SubtypeUnknown, ...).WithCause(err)` |
-| Lower layer already returned a typed error | pass it through unchanged — re-wrapping downgrades its classification |
-
-Signatures that are easy to guess wrong:
-
-- `runtime.CallAPITyped(method, url string, params map[string]interface{}, data interface{}) (map[string]interface{}, error)` — it performs the HTTP request itself and classifies `code != 0` into a typed error; just return the error it gives you.
-- Typed pass-through check: `if _, ok := errs.ProblemOf(err); ok { return err }` — `ProblemOf` returns `(*errs.Problem, bool)`, not a nilable pointer.
-- `.WithParam` exists only on `*errs.ValidationError`. `InternalError` / `NetworkError` have no param field — file or endpoint context goes in the message or `.WithHint(...)`.
-
-`forbidigo` + `lint/errscontract` reject the legacy `output.Err*` helpers, bare final `fmt.Errorf` / `errors.New`, and legacy envelope literals on migrated paths. Beyond what lint catches, three authoring conventions apply:
-
-- Preserve the underlying error with `.WithCause(err)` so `errors.Is` / `errors.Unwrap` keep working.
-- `param` names only the user input that actually failed. Recovery guidance goes in `.WithHint(...)`; machine-readable recovery fields (`missing_scopes`, `log_id`) carry server/system ground truth only — never caller-side guesses.
-- Error-path tests assert typed metadata via `errs.ProblemOf` (`category` / `subtype` / `param`) and cause preservation, not message substrings alone.
+`RunE` functions must return `output.Errorf` / `output.ErrWithHint` — never bare `fmt.Errorf`. AI agents parse stderr as JSON; bare errors break this contract.
 
 ### stdout is data, stderr is everything else
 

CHANGELOG.md

@@ -2,127 +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
-
-- **apps**: Support multi dev modes (#1175)
-- **im**: Complete audio/post rendering and add opt-in `--download-resources` (#1245)
-- **base**: Configure initial base table schema (#1377)
-- **vc**: Add recording event support (#1369)
-- **minutes**: Replace words for transcript (#1372)
-- **markdown**: Emit typed error envelopes across the markdown domain (#1347)
-- **sheets**: Emit typed error envelopes across the sheets domain (#1348)
-- **slides**: Emit typed error envelopes across the slides domain (#1349)
-
-### Documentation
-
-- **skills**: Warn about `@file` absolute path restriction in lark-doc skills (#1375)
-- **skills**: Remove unsupported ⚠️ from callout emoji list (#1374)
-
-## [v1.0.50] - 2026-06-09
-
-### Features
-
-- **doc**: Emit typed error envelopes across the doc domain (#1346)
-- **event**: Emit typed error envelopes across the event domain (#1289)
-- **contact**: Emit typed error envelopes across the contact domain (#1287)
-- **sheets**: Guard `+csv-put --csv` against a path passed without `@` (#1337)
-- **cli**: Adjust agent timeout hint output conditions (#1328)
-
-### Bug Fixes
-
-- **drive**: Add `@file`/stdin support to `+add-comment --content` (#1343)
-- **slides**: Build create URL locally instead of drive metas call (#1329)
-- **cli**: Clarify `--block-id` supports comma-separated batch delete in help text (#1336)
-
-### Documentation
-
-- **doc**: Replace append with `block_insert_after` in skeleton workflow guidance (#1340)
-- **doc**: Document `<folder-manager>` resource block (#1168)
-- **drive**: Add drive comment location guidance (#1258)
-
-## [v1.0.49] - 2026-06-08
-
-### Features
-
-- **events**: Add whiteboard event domain with per-board subscription (#1265)
-- **im**: Support feed group (#1102)
-- **im**: Add feed shortcut create, list, and remove shortcuts (#1273)
-- **im**: Format feed group error handling (#1308)
-- **im**: Return typed error envelopes across the im domain (#1230)
-- **base**: Emit typed error envelopes across the base domain (#1248)
-- **calendar**: Emit typed error envelopes across the calendar domain (#1232)
-- **task**: Emit typed error envelopes across the task domain (#1231)
-- **okr,whiteboard**: Emit typed error envelopes across both domains (#1236)
-- **minutes,vc**: Emit typed error envelopes across both domains (#1234)
-- **markdown**: Harden create upload failures (#1325)
-- **drive**: Harden inspect shortcut failures (#1324)
-- **slides**: Add IconPark lookup for Lark slides (#1123)
-- **doc**: Remove docs v1 API (#1291)
-- **cli**: Add `skills` command to read embedded skill content (#1318)
-- **cli**: Fetch official skills index (#1301)
-- **shared**: Document relative-path-only file arguments (#1319)
-- **scopes**: Clear `recommend.allow` scope auto-approve overrides (#1272)
-- **shortcuts**: Check shortcut example commands against the live CLI tree (#1244)
-
-### Bug Fixes
-
-- **events**: Keep bounded event consume runs alive after stdin EOF (#1285)
-- **drive**: Use docs secure label read scope (#1281)
-
-### Documentation
-
-- **approval**: Restructure skill with intent table and scope boundaries (#1307)
-- **skills**: Tighten drive and markdown guardrails (#1326)
-- **skills**: Optimize calendar, vc, and minutes skill guidance (#1269)
-- **markdown**: Add markdown domain template (#1293)
-- **markdown**: Improve lark-markdown skill guidance (#1279)
-- **doc**: Improve lark-doc skill guidance (#1283)
-- **wiki**: Optimize skill guidance and routing boundaries (#1275)
-- **slides**: Tighten routing/boundary and reconcile in-slide whiteboard (#1169)
-
-## [v1.0.48] - 2026-06-04
-
-### Features
-
-- **mail**: Preserve mailbox context in `+triage` output for public mailboxes (#1238)
-- **contact**: Add contact skill domain guidance (#1144)
-
-### Bug Fixes
-
-- **skills**: Use JSON skills list during update (#1251)
-
-### Documentation
-
-- **drive**: Refine lark-drive knowledge organize workflow (#1253)
-- **vc-agent**: Require explicit leave request (#1260)
-- **slides**: Add whiteboard element documentation and improve slide guidance (#1029)
-
 ## [v1.0.47] - 2026-06-03
 
 ### Features
@@ -1130,11 +1009,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
-[v1.0.48]: https://github.com/larksuite/cli/releases/tag/v1.0.48
 [v1.0.47]: https://github.com/larksuite/cli/releases/tag/v1.0.47
 [v1.0.46]: https://github.com/larksuite/cli/releases/tag/v1.0.46
 [v1.0.45]: https://github.com/larksuite/cli/releases/tag/v1.0.45

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

README.md

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

README.zh.md

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

cmd/auth/auth_test.go

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

cmd/auth/check.go

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

cmd/auth/list.go

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

cmd/auth/list_test.go

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

cmd/auth/login.go

@@ -296,11 +296,10 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 
 	// Step 2: Show user code and verification URL.
-	// JSON mode embeds AgentTimeoutHint as a structured field so agents that
-	// capture stdout into a JSON parser see it without stream-mixing surprises.
-	// Text mode prints the hint to stderr only when running under a non-TTY
-	// (i.e. piped / agent harness), since humans reading a terminal don't need
-	// the agent-oriented instructions.
+	// Both branches surface AgentTimeoutHint, but on different channels:
+	// JSON mode embeds it as a structured field (so an agent that captures
+	// stdout into a JSON parser sees it without stream-mixing surprises),
+	// text mode prints to stderr (alongside the URL prompt).
 	if opts.JSON {
 		data := map[string]interface{}{
 			"event":                     "device_authorization",
@@ -318,9 +317,7 @@ func authLoginRun(opts *LoginOptions) error {
 	} else {
 		fmt.Fprintf(f.IOStreams.ErrOut, msg.OpenURL)
 		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", authResp.VerificationUriComplete)
-		if f.IOStreams != nil && !f.IOStreams.IsTerminal {
-			fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
-		}
+		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 
 	// Step 3: Poll for token
@@ -407,11 +404,10 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 			fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] [WARN] auth login: failed to remove cached requested scopes: %v\n", err)
 		}
 	}
-	// Skip the stderr hint in JSON mode (the --no-wait call that issued
-	// the device_code already surfaced it as a JSON field), and also skip it
-	// when running on an interactive terminal — the agent-oriented
-	// instructions only matter for piped / harness environments.
-	if !opts.JSON && f.IOStreams != nil && !f.IOStreams.IsTerminal {
+	// Skip the stderr hint in JSON mode — the --no-wait call that issued the
+	// device_code already returned the hint as a JSON field, and writing
+	// text to stderr would pollute consumers that combine streams via 2>&1.
+	if !opts.JSON {
 		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 	log(msg.WaitingAuth)

cmd/auth/logout.go

@@ -18,7 +18,6 @@ import (
 // LogoutOptions holds all inputs for auth logout.
 type LogoutOptions struct {
 	Factory *cmdutil.Factory
-	JSON    bool
 }
 
 // NewCmdAuthLogout creates the auth logout subcommand.
@@ -35,7 +34,6 @@ func NewCmdAuthLogout(f *cmdutil.Factory, runF func(*LogoutOptions) error) *cobr
 			return authLogoutRun(opts)
 		},
 	}
-	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
 	cmdutil.SetRisk(cmd, "write")
 
 	return cmd
@@ -46,28 +44,12 @@ func authLogoutRun(opts *LogoutOptions) error {
 
 	multi, _ := core.LoadMultiAppConfig()
 	if multi == nil || len(multi.Apps) == 0 {
-		if opts.JSON {
-			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
-				"ok":        true,
-				"loggedOut": false,
-				"reason":    "not_configured",
-			})
-			return nil
-		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "No configuration found.")
 		return nil
 	}
 
 	app := multi.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil || len(app.Users) == 0 {
-		if opts.JSON {
-			output.PrintJson(f.IOStreams.Out, map[string]interface{}{
-				"ok":        true,
-				"loggedOut": false,
-				"reason":    "not_logged_in",
-			})
-			return nil
-		}
 		fmt.Fprintln(f.IOStreams.ErrOut, "Not logged in.")
 		return nil
 	}
@@ -81,13 +63,6 @@ func authLogoutRun(opts *LogoutOptions) error {
 	if err := core.SaveMultiAppConfig(multi); err != nil {
 		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
 	}
-	if opts.JSON {
-		output.PrintJson(f.IOStreams.Out, map[string]interface{}{
-			"ok":        true,
-			"loggedOut": true,
-		})
-		return nil
-	}
 	output.PrintSuccess(f.IOStreams.ErrOut, "Logged out")
 	return nil
 }

cmd/auth/logout_test.go

@@ -1,147 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package auth
-
-import (
-	"encoding/json"
-	"strings"
-	"testing"
-
-	larkauth "github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/zalando/go-keyring"
-)
-
-func writeLogoutConfig(t *testing.T, users []core.AppUser) {
-	t.Helper()
-	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
-		CurrentApp: "test-app",
-		Apps: []core.AppConfig{
-			{
-				AppId:     "test-app",
-				AppSecret: core.PlainSecret("test-secret"),
-				Brand:     core.BrandFeishu,
-				Users:     users,
-			},
-		},
-	}); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-}
-
-func TestAuthLogoutRun_JSONMode_NotConfigured_WritesStdoutOnly(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	if payload["loggedOut"] != false {
-		t.Errorf("stdout.loggedOut = %v, want false", payload["loggedOut"])
-	}
-	if payload["reason"] != "not_configured" {
-		t.Errorf("stdout.reason = %v, want not_configured", payload["reason"])
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
-	}
-}
-
-func TestAuthLogoutRun_JSONMode_NotLoggedIn_WritesStdoutOnly(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	writeLogoutConfig(t, nil)
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	if payload["loggedOut"] != false {
-		t.Errorf("stdout.loggedOut = %v, want false", payload["loggedOut"])
-	}
-	if payload["reason"] != "not_logged_in" {
-		t.Errorf("stdout.reason = %v, want not_logged_in", payload["reason"])
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
-	}
-}
-
-func TestAuthLogoutRun_JSONMode_Success_WritesStdoutOnly(t *testing.T) {
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	writeLogoutConfig(t, []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}})
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:      "test-app",
-		UserOpenId: "ou_user",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authLogoutRun(&LogoutOptions{Factory: f, JSON: true}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if payload["ok"] != true {
-		t.Errorf("stdout.ok = %v, want true", payload["ok"])
-	}
-	if payload["loggedOut"] != true {
-		t.Errorf("stdout.loggedOut = %v, want true", payload["loggedOut"])
-	}
-	if _, hasReason := payload["reason"]; hasReason {
-		t.Errorf("stdout.reason must be absent on success, got %v", payload["reason"])
-	}
-	if stderr.Len() != 0 {
-		t.Errorf("stderr must stay empty in JSON mode, got:\n%s", stderr.String())
-	}
-}
-
-func TestAuthLogoutRun_DefaultMode_KeepsTextOutput(t *testing.T) {
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	writeLogoutConfig(t, []core.AppUser{{UserOpenId: "ou_user", UserName: "tester"}})
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:      "test-app",
-		UserOpenId: "ou_user",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	if err := authLogoutRun(&LogoutOptions{Factory: f}); err != nil {
-		t.Fatalf("authLogoutRun() error = %v", err)
-	}
-
-	if stdout.Len() != 0 {
-		t.Errorf("stdout must stay empty in default mode, got:\n%s", stdout.String())
-	}
-	if !strings.Contains(stderr.String(), "Logged out") {
-		t.Errorf("stderr = %q, want success text", stderr.String())
-	}
-}

cmd/auth/scopes.go

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

cmd/auth/status.go

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

cmd/build.go

@@ -6,7 +6,6 @@ package cmd
 import (
 	"context"
 	"io"
-	"io/fs"
 
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
@@ -17,7 +16,6 @@ import (
 	"github.com/larksuite/cli/cmd/profile"
 	"github.com/larksuite/cli/cmd/schema"
 	"github.com/larksuite/cli/cmd/service"
-	"github.com/larksuite/cli/cmd/skill"
 	cmdupdate "github.com/larksuite/cli/cmd/update"
 	_ "github.com/larksuite/cli/events"
 	"github.com/larksuite/cli/internal/build"
@@ -53,18 +51,6 @@ func WithKeychain(kc keychain.KeychainAccess) BuildOption {
 	}
 }
 
-// embeddedSkillContent is the skill tree wired into cmdutil.Factory.SkillContent
-// at build time. It is registered by the repo-root package main's init via
-// SetEmbeddedSkillContent — it cannot be threaded through main.go without
-// breaking the single-file preview build (see skills_embed.go). nil in builds
-// that embed no skills; the `skills` commands then return a typed internal error.
-var embeddedSkillContent fs.FS
-
-// SetEmbeddedSkillContent registers the embedded skill tree. Called from the
-// repo-root package main's init; a wrapper main can call it before Execute to
-// supply its own skill content.
-func SetEmbeddedSkillContent(fsys fs.FS) { embeddedSkillContent = fsys }
-
 // HideProfile sets the visibility policy for the root-level --profile flag.
 // When hide is true the flag stays registered (so existing invocations still
 // parse) but is omitted from help and shell completion. Typically called as
@@ -117,7 +103,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	if cfg.keychain != nil {
 		f.Keychain = cfg.keychain
 	}
-	f.SkillContent = embeddedSkillContent
 	rootCmd := &cobra.Command{
 		Use:     "lark-cli",
 		Short:   "Lark/Feishu CLI — OAuth authorization, UAT management, API calls",
@@ -155,7 +140,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.AddCommand(completion.NewCmdCompletion(f))
 	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
 	rootCmd.AddCommand(cmdevent.NewCmdEvents(f))
-	rootCmd.AddCommand(skill.NewCmdSkill(f))
 	service.RegisterServiceCommandsWithContext(ctx, rootCmd, f)
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)
 

cmd/cmdexample_catalog_test.go

@@ -1,160 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd_test
-
-import (
-	"sort"
-	"strings"
-)
-
-// universalFlags are accepted by every command (cobra auto-injects help; the
-// root injects version). They are never reported as unknown.
-var universalFlags = map[string]bool{"--help": true, "-h": true, "--version": true}
-
-// catalog is the source-of-truth command catalog: command path -> accepted flag
-// tokens. A path is the command words WITHOUT the "lark-cli" root prefix, e.g.
-// "contact +search-user". The root command is the empty path "".
-type catalog struct {
-	flagsByPath map[string]map[string]bool
-	group       map[string]bool // paths that are parent groups (have subcommands)
-	sorted      []string        // cached sorted paths for suggestCommand; invalidated on addCommand
-}
-
-func newCatalog() *catalog {
-	return &catalog{
-		flagsByPath: map[string]map[string]bool{},
-		group:       map[string]bool{},
-	}
-}
-
-// setGroup records whether path is a parent group (has subcommands). Leftover
-// words after a group node are unknown subcommands; after a leaf they are
-// positionals (e.g. "api GET /path").
-func (c *catalog) setGroup(path string, isGroup bool) {
-	if isGroup {
-		c.group[path] = true
-	}
-}
-
-func (c *catalog) isGroup(path string) bool { return c.group[path] }
-
-// addCommand registers a command path and the flags it accepts. Repeated calls
-// for the same path union the flag sets. flags are full tokens ("--query", "-q").
-func (c *catalog) addCommand(path string, flags []string) {
-	set := c.flagsByPath[path]
-	if set == nil {
-		set = map[string]bool{}
-		c.flagsByPath[path] = set
-	}
-	for _, f := range flags {
-		set[f] = true
-	}
-	c.sorted = nil // invalidate cached suggestion list
-}
-
-func (c *catalog) hasCommand(path string) bool {
-	_, ok := c.flagsByPath[path]
-	return ok
-}
-
-// hasFlag reports whether flag is accepted by command path (universal flags
-// always pass).
-func (c *catalog) hasFlag(path, flag string) bool {
-	if universalFlags[flag] {
-		return true
-	}
-	set := c.flagsByPath[path]
-	return set[flag]
-}
-
-// longestPrefix returns the longest known command path that is a prefix of
-// words, plus how many words it consumed. This separates real subcommands from
-// trailing positionals (e.g. "api GET /path" resolves to "api"). When words is
-// empty it falls back to the root command. ok=false means not even the first
-// word names a command.
-func (c *catalog) longestPrefix(words []string) (path string, n int, ok bool) {
-	if len(words) == 0 {
-		if c.hasCommand("") {
-			return "", 0, true
-		}
-		return "", 0, false
-	}
-	for i := len(words); i >= 1; i-- {
-		cand := strings.Join(words[:i], " ")
-		if c.hasCommand(cand) {
-			return cand, i, true
-		}
-	}
-	return "", 0, false
-}
-
-// paths returns all known command paths, sorted.
-func (c *catalog) paths() []string {
-	out := make([]string, 0, len(c.flagsByPath))
-	for p := range c.flagsByPath {
-		out = append(out, p)
-	}
-	sort.Strings(out)
-	return out
-}
-
-// suggestCommand returns the known command path closest to want (small edit
-// distance), for error hints. Returns "" when nothing is reasonably close.
-func (c *catalog) suggestCommand(want string) string {
-	if c.sorted == nil {
-		c.sorted = c.paths() // built once after the catalog is fully populated
-	}
-	return closest(want, c.sorted)
-}
-
-// suggestFlag returns the flag of path closest to flag, for error hints.
-func (c *catalog) suggestFlag(path, flag string) string {
-	set := c.flagsByPath[path]
-	cands := make([]string, 0, len(set))
-	for f := range set {
-		cands = append(cands, f)
-	}
-	sort.Strings(cands)
-	return closest(flag, cands)
-}
-
-// closest returns the candidate with the smallest Levenshtein distance to want,
-// but only if that distance is within a tolerance scaled to want's length
-// (avoids absurd suggestions).
-func closest(want string, cands []string) string {
-	best := ""
-	bestD := 1 << 30
-	for _, cand := range cands {
-		d := levenshtein(want, cand)
-		if d < bestD {
-			bestD, best = d, cand
-		}
-	}
-	tol := len(want)/2 + 1
-	if bestD > tol {
-		return ""
-	}
-	return best
-}
-
-func levenshtein(a, b string) int {
-	ra, rb := []rune(a), []rune(b)
-	prev := make([]int, len(rb)+1)
-	for j := range prev {
-		prev[j] = j
-	}
-	for i := 1; i <= len(ra); i++ {
-		cur := make([]int, len(rb)+1)
-		cur[0] = i
-		for j := 1; j <= len(rb); j++ {
-			cost := 1
-			if ra[i-1] == rb[j-1] {
-				cost = 0
-			}
-			cur[j] = min(prev[j]+1, cur[j-1]+1, prev[j-1]+cost)
-		}
-		prev = cur
-	}
-	return prev[len(rb)]
-}

cmd/cmdexample_check_test.go

@@ -1,60 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd_test
-
-import "strings"
-
-// Finding kinds.
-const (
-	unknownCommand = "unknown_command"
-	unknownFlag    = "unknown_flag"
-)
-
-// finding is a single mismatch between an example command reference and the
-// catalog.
-type finding struct {
-	line    int
-	raw     string
-	kind    string // unknownCommand | unknownFlag
-	path    string // resolved command path (unknownFlag) or attempted path (unknownCommand)
-	flag    string // offending flag (unknownFlag only)
-	suggest string // nearest known command/flag, "" if none close
-}
-
-// checkRefs validates refs against cat and returns all mismatches in order.
-func checkRefs(cat *catalog, refs []ref) []finding {
-	var out []finding
-	for _, r := range refs {
-		path, n, ok := cat.longestPrefix(r.words)
-		if !ok {
-			attempted := strings.Join(r.words, " ")
-			out = append(out, finding{
-				line: r.line, raw: r.raw, kind: unknownCommand,
-				path: attempted, suggest: cat.suggestCommand(attempted),
-			})
-			continue
-		}
-		// Leftover words after a group node are an unknown subcommand (e.g. a
-		// mistyped method like "batch_modify_message"). After a leaf they are
-		// positionals (e.g. "api GET /path"), so only groups trigger this.
-		if n < len(r.words) && cat.isGroup(path) {
-			attempted := strings.Join(r.words, " ")
-			out = append(out, finding{
-				line: r.line, raw: r.raw, kind: unknownCommand,
-				path: attempted, suggest: cat.suggestCommand(attempted),
-			})
-			continue
-		}
-		for _, f := range r.flags {
-			if cat.hasFlag(path, f) {
-				continue
-			}
-			out = append(out, finding{
-				line: r.line, raw: r.raw, kind: unknownFlag,
-				path: path, flag: f, suggest: cat.suggestFlag(path, f),
-			})
-		}
-	}
-	return out
-}

cmd/cmdexample_parse_test.go

@@ -1,222 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd_test
-
-import (
-	"regexp"
-	"strings"
-)
-
-// ref is one lark-cli command reference extracted from a shortcut example.
-type ref struct {
-	line  int      // 1-based line number (the line where the command starts)
-	raw   string   // reconstructed command text, for error display
-	words []string // command words before the first flag (subcommand candidates)
-	flags []string // flag tokens used, e.g. "--query", "-q"
-}
-
-const cliToken = "lark-cli"
-
-// subcommandStart guards against false positives from prose: a real command's
-// first word is ASCII (a service name or a +shortcut). A token starting with
-// CJK / punctuation is treated as narration, not a command.
-var subcommandStart = regexp.MustCompile(`^[A-Za-z+]`)
-
-// shellStops are standalone tokens that terminate a command (pipes, redirects,
-// separators). Separators glued to a token (`get;`, `foo|`) are handled inline.
-var shellStops = map[string]bool{
-	"|": true, "||": true, "&&": true, "&": true, ";": true,
-	">": true, ">>": true, "<": true, "2>": true, "2>&1": true,
-}
-
-// wordTrailPunct is sentence / CJK punctuation that can cling to a command word
-// in prose ("auth login." / "auth login，"); stripped so the word still resolves
-// instead of being dropped as an unknown command or non-ASCII narration.
-const wordTrailPunct = `.,;:!?"')]}，。、；：！？）】」』`
-
-// parseRefs extracts every lark-cli command reference from text (a shortcut's
-// Tips line, which may embed an "Example: lark-cli ..." command). It is
-// deliberately format-agnostic: it keys on the "lark-cli" token whether it sits
-// in a ```bash fence, an inline `code` span, or bare prose. Backslash
-// line-continuations are joined first so a multi-line invocation is parsed as
-// one command; inline-code backticks and trailing # comments terminate it.
-func parseRefs(content string) []ref {
-	var refs []ref
-	lines := strings.Split(content, "\n")
-	for i := 0; i < len(lines); i++ {
-		lineNo := i + 1
-		logical := lines[i]
-		// Shell line continuation: a trailing backslash joins the next physical
-		// line. Without this, flags on the continuation lines of a multi-line
-		// `lark-cli ... \` example are never seen by the checker.
-		for endsWithBackslash(logical) && i+1 < len(lines) {
-			logical = strings.TrimRight(logical, " \t")
-			logical = logical[:len(logical)-1] // drop the trailing backslash
-			i++
-			logical += " " + lines[i]
-		}
-		refs = append(refs, parseLine(logical, lineNo)...)
-	}
-	return refs
-}
-
-func endsWithBackslash(s string) bool {
-	return strings.HasSuffix(strings.TrimRight(s, " \t"), `\`)
-}
-
-func parseLine(line string, lineNo int) []ref {
-	var refs []ref
-	rest := line
-	for {
-		idx := strings.Index(rest, cliToken)
-		if idx < 0 {
-			break
-		}
-		after := rest[idx+len(cliToken):]
-		beforeOK := idx == 0 || isBoundary(rest[idx-1])
-		afterOK := after == "" || isBoundary(after[0])
-		if beforeOK && afterOK {
-			if words, flags, raw, ok := parseCmd(after); ok {
-				refs = append(refs, ref{line: lineNo, raw: cliToken + raw, words: words, flags: flags})
-			}
-		}
-		rest = after
-	}
-	return refs
-}
-
-// parseCmd tokenizes the text following "lark-cli" into leading command words
-// (the subcommand path, up to the first flag) and flag tokens. It stops at a
-// shell separator (standalone or glued), an inline-code backtick, a comment, or
-// a placeholder/prose word. ok=false filters out non-commands.
-func parseCmd(after string) (words, flags []string, raw string, ok bool) {
-	// An inline code span ends at the next backtick; a command never spans one.
-	if i := strings.IndexByte(after, '`'); i >= 0 {
-		after = after[:i]
-	}
-	// Drop $(...) command substitutions so flags belonging to the inner command
-	// (e.g. `--data "$(jq -n --arg x ...)"`) are not mistaken for lark-cli flags.
-	after = stripCmdSubst(after)
-
-	var kept []string
-	inFlags := false
-	for _, orig := range strings.Fields(after) {
-		tok := orig
-		if shellStops[tok] || strings.HasPrefix(tok, "#") {
-			break
-		}
-		// A shell separator glued to a token ends the command mid-token
-		// ("get;", "foo|next"): keep the part before it, handle it, then stop.
-		stop := false
-		if i := strings.IndexAny(tok, ";|"); i >= 0 {
-			tok, stop = tok[:i], true
-		}
-		switch {
-		case tok == "" || tok == "-":
-			// empty (after a glued separator) or a bare stdin marker — skip
-		case strings.HasPrefix(tok, "-"):
-			if f := normalizeFlag(tok); f != "" {
-				inFlags = true
-				flags = append(flags, f)
-				kept = append(kept, tok)
-			}
-		case inFlags:
-			// positional / flag value after the first flag — not a command word
-			kept = append(kept, tok)
-		default:
-			// Command-path word. ASCII placeholder markers (<x>, [x], {x|y},
-			// +<verb>, ...) end the command — checked on the RAW token so the
-			// trailing-punct stripping below cannot erase a "..." ellipsis
-			// ("base +..." must stay a placeholder, not become "+").
-			if strings.ContainsAny(tok, "<>[]{}|") || strings.Contains(tok, "...") {
-				stop = true
-				break
-			}
-			// Strip trailing sentence/CJK punctuation so "login." / "login，"
-			// resolve to "login"; non-ASCII narration ends the command.
-			w := strings.TrimRight(tok, wordTrailPunct)
-			if w == "" || hasNonASCII(w) {
-				stop = true
-				break
-			}
-			words = append(words, w)
-			kept = append(kept, tok)
-		}
-		if stop {
-			break
-		}
-	}
-	if len(kept) > 0 {
-		raw = " " + strings.Join(kept, " ")
-	}
-	// Keep root-only refs ("lark-cli --help") and refs whose first word looks
-	// like a subcommand; drop prose ("lark-cli 就能搞定 ...").
-	if len(words) == 0 {
-		return words, flags, raw, len(flags) > 0
-	}
-	if !subcommandStart.MatchString(words[0]) {
-		return nil, nil, "", false
-	}
-	return words, flags, raw, true
-}
-
-// stripCmdSubst removes $(...) command substitutions (including nested ones)
-// from s, leaving the surrounding text intact. Backtick substitutions are
-// already handled upstream (a command never spans a backtick).
-func stripCmdSubst(s string) string {
-	var b strings.Builder
-	depth := 0
-	for i := 0; i < len(s); i++ {
-		if depth == 0 && i+1 < len(s) && s[i] == '$' && s[i+1] == '(' {
-			depth = 1
-			i++ // skip '('
-			continue
-		}
-		if depth > 0 {
-			switch s[i] {
-			case '(':
-				depth++
-			case ')':
-				depth--
-			}
-			continue
-		}
-		b.WriteByte(s[i])
-	}
-	return b.String()
-}
-
-// isPlaceholderOrProse reports whether a command word is a doc placeholder
-// (<resource>, [flags], {a|b}, +<verb>, ...) or narration (CJK / other
-// non-ASCII), rather than a literal command token.
-func isPlaceholderOrProse(w string) bool {
-	if hasNonASCII(w) {
-		return true
-	}
-	return strings.ContainsAny(w, "<>[]{}|") || strings.Contains(w, "...")
-}
-
-func hasNonASCII(s string) bool {
-	return strings.IndexFunc(s, func(r rune) bool { return r > 127 }) >= 0
-}
-
-// flagShape matches the leading flag token, stripping any trailing junk such as
-// a "=value" suffix or punctuation that bled in from the surrounding markdown
-// ("--help\"", "--help;", "--params={}"). The underscore is allowed because
-// real flags use it ("--input_format", "--output_as"). Returns "" for non-flags.
-var flagShape = regexp.MustCompile(`^--?[A-Za-z][A-Za-z0-9_-]*`)
-
-// normalizeFlag extracts the canonical flag token from tok, or "" if tok is not
-// a real flag (e.g. a shell-string fragment like "-草稿'").
-func normalizeFlag(tok string) string {
-	return flagShape.FindString(tok)
-}
-
-func isBoundary(b byte) bool {
-	switch b {
-	case ' ', '\t', '`', '(', ')', '\'', '"', '*':
-		return true
-	}
-	return false
-}

cmd/cmdexample_test.go

@@ -1,113 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// This file and its cmdexample_*_test.go siblings implement a test-only check:
-// the example commands embedded in shortcut definitions (the "Example: lark-cli
-// ..." lines in each shortcut's Tips, shown in --help) must match the real
-// command tree. It lives entirely in _test.go files (package cmd_test) so it
-// ships in no binary and is not importable by product code; the truth source is
-// cmd.Build, the same tree the binary uses, so the check cannot drift.
-//
-// It runs in the standard unit-test CI job (go test ./cmd/...). A mismatch — an
-// example using a renamed command or an unaccepted flag — fails that job.
-
-package cmd_test
-
-import (
-	"context"
-	"sort"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/cmd"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/shortcuts"
-	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
-)
-
-// TestShortcutExampleCommands checks the example commands embedded in every
-// shortcut's Tips against the live command tree. A shortcut that defines no
-// example is simply skipped.
-//
-// Because the examples and the command definitions live in the same Go code,
-// this is a self-consistency check: any mismatch (an example using a renamed
-// command or a flag the command doesn't accept) is a bug to fix at the source.
-// It runs over all shortcuts — no baseline, no diff — since a wrong example is
-// always a defect, never acceptable "pre-existing drift".
-func TestShortcutExampleCommands(t *testing.T) {
-	// Reproducibility: use the embedded API metadata (not a developer's stale
-	// ~/.lark-cli remote cache, which can miss commands) and an empty config
-	// dir so local strict mode / plugins / policy cannot reshape the tree.
-	// t.Setenv auto-restores after the test, so other cmd tests are unaffected.
-	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	cat := buildCmdExampleCatalog()
-
-	type located struct {
-		shortcut string
-		f        finding
-	}
-	var findings []located
-	for _, sc := range shortcuts.AllShortcuts() {
-		var refs []ref
-		for _, tip := range sc.Tips {
-			refs = append(refs, parseRefs(tip)...)
-		}
-		label := strings.TrimSpace(sc.Service + " " + sc.Command)
-		for _, f := range checkRefs(cat, refs) {
-			findings = append(findings, located{shortcut: label, f: f})
-		}
-	}
-
-	if len(findings) == 0 {
-		return
-	}
-	sort.Slice(findings, func(i, j int) bool { return findings[i].shortcut < findings[j].shortcut })
-	for _, lf := range findings {
-		hint := ""
-		if lf.f.suggest != "" {
-			hint = "  (did you mean " + lf.f.suggest + "?)"
-		}
-		if lf.f.kind == unknownFlag {
-			t.Errorf("shortcut %q example uses unknown flag %s on %q%s\n      %s",
-				lf.shortcut, lf.f.flag, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
-		} else {
-			t.Errorf("shortcut %q example uses unknown command %q%s\n      %s",
-				lf.shortcut, lf.f.path, hint, strings.TrimSpace(lf.f.raw))
-		}
-	}
-	t.Fatalf("%d shortcut example command(s) don't match the real CLI — "+
-		"fix the Example in the shortcut definition.", len(findings))
-}
-
-// buildCmdExampleCatalog walks the live cobra command tree and records every
-// command path (minus the "lark-cli" root prefix) with its accepted flags and
-// whether it is a parent group. This is the same Build() the binary uses, so
-// the catalog can never drift from the real commands.
-func buildCmdExampleCatalog() *catalog {
-	root := cmd.Build(context.Background(), cmdutil.InvocationContext{})
-	cat := newCatalog()
-	var walk func(c *cobra.Command)
-	walk = func(c *cobra.Command) {
-		path := strings.TrimSpace(strings.TrimPrefix(c.CommandPath(), "lark-cli"))
-		var flags []string
-		add := func(fl *pflag.Flag) {
-			flags = append(flags, "--"+fl.Name)
-			if fl.Shorthand != "" {
-				flags = append(flags, "-"+fl.Shorthand)
-			}
-		}
-		c.Flags().VisitAll(add)
-		c.InheritedFlags().VisitAll(add)
-		c.PersistentFlags().VisitAll(add) // root's own persistent flags (e.g. --profile)
-		cat.addCommand(path, flags)
-		cat.setGroup(path, c.HasSubCommands())
-		for _, sub := range c.Commands() {
-			walk(sub)
-		}
-	}
-	walk(root)
-	return cat
-}

cmd/cmdexample_units_test.go

@@ -1,233 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd_test
-
-import (
-	"strings"
-	"testing"
-)
-
-func testCatalog() *catalog {
-	c := newCatalog()
-	c.addCommand("", []string{"--profile"}) // root
-	c.setGroup("", true)
-	c.addCommand("contact", []string{"--profile"})
-	c.setGroup("contact", true)
-	c.addCommand("contact +search-user", []string{"--query", "--as", "--format", "-q"})
-	c.addCommand("api", []string{"--params", "--data", "--as"}) // leaf (no subcommands)
-	c.addCommand("mail", nil)
-	c.setGroup("mail", true)
-	c.addCommand("mail user_mailbox.messages", []string{"--profile"})
-	c.setGroup("mail user_mailbox.messages", true)
-	c.addCommand("mail user_mailbox.messages batch_modify", []string{"--params", "--data"})
-	return c
-}
-
-func TestCmdExampleCatalogHasCommandAndFlag(t *testing.T) {
-	c := testCatalog()
-	if !c.hasCommand("contact +search-user") {
-		t.Fatal("expected contact +search-user to exist")
-	}
-	if c.hasCommand("contact +nope") {
-		t.Fatal("did not expect contact +nope")
-	}
-	if !c.hasFlag("contact +search-user", "--query") {
-		t.Fatal("--query should be valid")
-	}
-	if c.hasFlag("contact +search-user", "--nope") {
-		t.Fatal("--nope should be invalid")
-	}
-	// universal flags pass on any command
-	for _, f := range []string{"--help", "-h", "--version"} {
-		if !c.hasFlag("contact +search-user", f) {
-			t.Fatalf("universal flag %s should pass", f)
-		}
-	}
-}
-
-func TestCmdExampleLongestPrefix(t *testing.T) {
-	c := testCatalog()
-	tests := []struct {
-		words  []string
-		want   string
-		wantN  int
-		wantOK bool
-	}{
-		{[]string{"contact", "+search-user"}, "contact +search-user", 2, true},
-		{[]string{"api", "GET", "/open-apis/x"}, "api", 1, true}, // trailing positionals
-		{[]string{"nope"}, "", 0, false},
-		{nil, "", 0, true}, // empty -> root
-	}
-	for _, tt := range tests {
-		got, n, ok := c.longestPrefix(tt.words)
-		if got != tt.want || n != tt.wantN || ok != tt.wantOK {
-			t.Errorf("longestPrefix(%v) = (%q,%d,%v), want (%q,%d,%v)",
-				tt.words, got, n, ok, tt.want, tt.wantN, tt.wantOK)
-		}
-	}
-}
-
-func refWordsOf(refs []ref) [][]string {
-	var out [][]string
-	for _, r := range refs {
-		out = append(out, r.words)
-	}
-	return out
-}
-
-func TestCmdExampleParseRefsExtractsCommands(t *testing.T) {
-	content := strings.Join([]string{
-		"运行 `lark-cli contact +search-user --query 张三` 搜索", // inline code
-		"```bash",
-		"lark-cli api GET /open-apis/x --params '{}'", // bash block
-		"```",
-		"用 lark-cli mail user_mailbox.messages batch_modify 即可", // bare prose command
-		"npx foo | lark-cli api GET /y",                         // after a pipe
-	}, "\n")
-	refs := parseRefs(content)
-	if len(refs) != 4 {
-		t.Fatalf("expected 4 refs, got %d: %v", len(refs), refWordsOf(refs))
-	}
-	if got := refs[0]; strings.Join(got.words, " ") != "contact +search-user" ||
-		len(got.flags) != 1 || got.flags[0] != "--query" {
-		t.Errorf("ref0 = %+v", got)
-	}
-	if got := refs[1]; strings.Join(got.words, " ") != "api GET /open-apis/x" {
-		t.Errorf("ref1 words = %v", got.words)
-	}
-}
-
-func TestCmdExampleParseRefsFiltersPlaceholdersAndProse(t *testing.T) {
-	// A line whose first word is prose yields no command at all.
-	if refs := parseRefs("lark-cli 就能搞定这件事"); len(refs) != 0 {
-		t.Errorf("prose-first line should yield 0 refs, got %v", refWordsOf(refs))
-	}
-	// Syntax templates / trailing prose may leave a real leading word ("mail"),
-	// but no placeholder or CJK token may leak into the command words — that is
-	// what prevents false positives like an "<resource>" unknown-command report.
-	for _, line := range []string{
-		"lark-cli mail <resource> <method> [flags]",
-		"lark-cli apps +<verb> [flags]",
-		"lark-cli base +...",
-		"lark-cli mail 写信场景下的格式说明",
-	} {
-		for _, r := range parseRefs(line) {
-			for _, w := range r.words {
-				if isPlaceholderOrProse(w) {
-					t.Errorf("%q: placeholder/prose token %q leaked into words %v", line, w, r.words)
-				}
-			}
-		}
-	}
-}
-
-func TestCmdExampleParseRefsStripsTrailingJunk(t *testing.T) {
-	// frontmatter-style quoted value: the trailing quote must not bleed into the flag
-	refs := parseRefs(`cliHelp: "lark-cli contact --help"`)
-	if len(refs) != 1 {
-		t.Fatalf("expected 1 ref, got %d", len(refs))
-	}
-	if len(refs[0].flags) != 1 || refs[0].flags[0] != "--help" {
-		t.Errorf("expected flag --help, got %v", refs[0].flags)
-	}
-	// bare "-" (stdin marker) and "=value" suffix
-	refs = parseRefs("lark-cli api GET /x --params={} --data -")
-	if len(refs) != 1 {
-		t.Fatalf("expected 1 ref, got %d", len(refs))
-	}
-	flags := strings.Join(refs[0].flags, " ")
-	if flags != "--params --data" {
-		t.Errorf("expected '--params --data', got %q", flags)
-	}
-}
-
-func TestCmdExampleCheck(t *testing.T) {
-	c := testCatalog()
-	tests := []struct {
-		name     string
-		r        ref
-		wantKind string // "" = no finding
-		wantPath string
-	}{
-		{"valid shortcut", ref{words: []string{"contact", "+search-user"}, flags: []string{"--query"}}, "", ""},
-		{"valid leaf positional", ref{words: []string{"api", "GET", "/x"}}, "", ""},
-		{"unknown top command", ref{words: []string{"nope"}}, unknownCommand, "nope"},
-		{"group leftover = unknown subcommand",
-			ref{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}},
-			unknownCommand, "mail user_mailbox.messages batch_modify_message"},
-		{"unknown flag", ref{words: []string{"contact", "+search-user"}, flags: []string{"--nope"}}, unknownFlag, "contact +search-user"},
-		{"universal flag ok", ref{words: []string{"contact", "+search-user"}, flags: []string{"--help"}}, "", ""},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			fs := checkRefs(c, []ref{tt.r})
-			if tt.wantKind == "" {
-				if len(fs) != 0 {
-					t.Fatalf("expected no finding, got %+v", fs)
-				}
-				return
-			}
-			if len(fs) != 1 {
-				t.Fatalf("expected 1 finding, got %d: %+v", len(fs), fs)
-			}
-			if fs[0].kind != tt.wantKind || fs[0].path != tt.wantPath {
-				t.Errorf("got kind=%s path=%q, want kind=%s path=%q", fs[0].kind, fs[0].path, tt.wantKind, tt.wantPath)
-			}
-		})
-	}
-}
-
-func TestCmdExampleCheckSuggestsNearest(t *testing.T) {
-	c := testCatalog()
-	fs := checkRefs(c, []ref{{words: []string{"mail", "user_mailbox.messages", "batch_modify_message"}}})
-	if len(fs) != 1 || fs[0].suggest != "mail user_mailbox.messages batch_modify" {
-		t.Fatalf("expected suggestion 'mail user_mailbox.messages batch_modify', got %+v", fs)
-	}
-}
-
-// TestCmdExampleParseRefsRobustness covers the parser edge cases hardened after
-// review: backslash continuation, underscore flags, $(...) substitution, glued
-// separators, trailing punctuation, and the "..." placeholder.
-func TestCmdExampleParseRefsRobustness(t *testing.T) {
-	cases := []struct {
-		name, content, wantWords, wantFlags string
-		wantRefs                            int
-	}{
-		{"backslash continuation joins flags",
-			"lark-cli contact +search-user \\\n  --query foo \\\n  --as user",
-			"contact +search-user", "--query --as", 1},
-		{"underscore flag not truncated",
-			"lark-cli whiteboard +update --input_format mermaid",
-			"whiteboard +update", "--input_format", 1},
-		{"command-substitution flags ignored",
-			`lark-cli slides x create --data "$(jq -n --arg c '{}')" --as user`,
-			"slides x create", "--data --as", 1},
-		{"glued separator truncates",
-			"lark-cli auth login; echo done",
-			"auth login", "", 1},
-		{"trailing CJK punctuation stripped",
-			"用 lark-cli auth login。",
-			"auth login", "", 1},
-		{"ellipsis placeholder stays placeholder",
-			"lark-cli base +...",
-			"base", "", 1},
-	}
-	for _, tt := range cases {
-		t.Run(tt.name, func(t *testing.T) {
-			refs := parseRefs(tt.content)
-			if len(refs) != tt.wantRefs {
-				t.Fatalf("refs=%d want %d: %v", len(refs), tt.wantRefs, refWordsOf(refs))
-			}
-			if tt.wantRefs == 0 {
-				return
-			}
-			if got := strings.Join(refs[0].words, " "); got != tt.wantWords {
-				t.Errorf("words=%q want %q", got, tt.wantWords)
-			}
-			if got := strings.Join(refs[0].flags, " "); got != tt.wantFlags {
-				t.Errorf("flags=%q want %q", got, tt.wantFlags)
-			}
-		})
-	}
-}

cmd/event/bus.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/event"
@@ -39,8 +38,7 @@ func NewCmdBus(f *cmdutil.Factory) *cobra.Command {
 
 			logger, err := bus.SetupBusLogger(eventsDir)
 			if err != nil {
-				return errs.NewInternalError(errs.SubtypeFileIO,
-					"set up bus logger: %s", err).WithCause(err)
+				return err
 			}
 
 			tr := transport.New()
@@ -60,14 +58,7 @@ func NewCmdBus(f *cmdutil.Factory) *cobra.Command {
 				}
 			}()
 
-			if err := b.Run(ctx); err != nil {
-				if _, ok := errs.ProblemOf(err); ok {
-					return err
-				}
-				return errs.NewInternalError(errs.SubtypeUnknown,
-					"event bus daemon exited: %s", err).WithCause(err)
-			}
-			return nil
+			return b.Run(ctx)
 		},
 	}
 

cmd/event/bus_test.go

@@ -1,45 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package event
-
-import (
-	"os"
-	"path/filepath"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// The hidden `event _bus` daemon command must exit with a typed file_io error
-// when its log directory cannot be created (the error is only visible in the
-// forked process's captured stderr / bus.log).
-func TestBusCommandLoggerSetupFailureIsTypedFileIO(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	// Block the events/ root with a regular file so MkdirAll fails.
-	if err := os.WriteFile(filepath.Join(dir, "events"), []byte("x"), 0600); err != nil {
-		t.Fatal(err)
-	}
-
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "cli_bus_test", AppSecret: "secret", Brand: core.BrandFeishu,
-	})
-	cmd := NewCmdBus(f)
-	cmd.SetArgs([]string{})
-
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected logger setup error")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeFileIO {
-		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
-			errs.CategoryInternal, errs.SubtypeFileIO)
-	}
-}

cmd/event/consume.go

@@ -16,7 +16,6 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/appmeta"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -65,8 +64,8 @@ Use 'event schema <EventKey>' for parameter details.`,
 	cmd.Flags().StringVar(&o.jqExpr, "jq", "", "JQ expression to filter output")
 	cmd.Flags().BoolVar(&o.quiet, "quiet", false, "Suppress informational messages on stderr")
 	cmd.Flags().StringVar(&o.outputDir, "output-dir", "", "Write each event as a file in this directory (relative paths only; absolute paths and ~ are rejected to prevent path traversal)")
-	cmd.Flags().IntVar(&o.maxEvents, "max-events", 0, "Exit after N successful emits (0 = unlimited). Multi-worker EventKeys may emit up to workers-1 past N before all workers stop. Bounded runs ignore stdin EOF.")
-	cmd.Flags().DurationVar(&o.timeout, "timeout", 0, "Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout'). Bounded runs ignore stdin EOF.")
+	cmd.Flags().IntVar(&o.maxEvents, "max-events", 0, "Exit after N successful emits (0 = unlimited). Multi-worker EventKeys may emit up to workers-1 past N before all workers stop.")
+	cmd.Flags().DurationVar(&o.timeout, "timeout", 0, "Exit after DURATION (e.g. 30s, 2m). 0 = no timeout. Timeout is a normal exit (code 0; stderr 'reason: timeout').")
 	cmd.Flags().String("as", "auto", "identity type: user | bot | auto (must match EventKey's declared AuthTypes)")
 	_ = cmd.RegisterFlagCompletionFunc("as", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 		return []string{"user", "bot", "auto"}, cobra.ShellCompDirectiveNoFileComp
@@ -102,10 +101,11 @@ func runConsume(cmd *cobra.Command, f *cmdutil.Factory, eventKey string, o consu
 
 	if o.jqExpr != "" {
 		if err := output.ValidateJqExpression(o.jqExpr); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).
-				WithParam("--jq").
-				WithCause(err).
-				WithHint("see `lark-cli event consume --help` EXAMPLES for common patterns, or `lark-cli event schema %s` for valid field paths", eventKey)
+			return output.ErrWithHint(
+				output.ExitValidation, "validation",
+				err.Error(),
+				fmt.Sprintf("see `lark-cli event consume --help` EXAMPLES for common patterns, or `lark-cli event schema %s` for valid field paths", eventKey),
+			)
 		}
 	}
 
@@ -184,9 +184,8 @@ func runConsume(cmd *cobra.Command, f *cmdutil.Factory, eventKey string, o consu
 		errOut = io.Discard
 	}
 
-	// Non-TTY unbounded consumers use stdin EOF as shutdown for subprocess callers.
-	// Bounded runs already have --max-events/--timeout as their lifecycle control.
-	if shouldWatchStdinEOF(f.IOStreams.IsTerminal, o.maxEvents, o.timeout) {
+	// Non-TTY only: stdin EOF is shutdown for subprocess callers; in TTY Ctrl-D must not exit.
+	if !f.IOStreams.IsTerminal {
 		watchStdinEOF(os.Stdin, cancel, errOut)
 	}
 
@@ -261,12 +260,12 @@ func preflightScopes(ctx context.Context, pf *preflightCtx) error {
 	if len(missing) == 0 {
 		return nil
 	}
-	return errs.NewPermissionError(errs.SubtypeMissingScope,
-		"missing required scopes for EventKey %s (as %s): %s",
-		pf.eventKey, pf.identity, strings.Join(missing, ", ")).
-		WithIdentity(string(pf.identity)).
-		WithMissingScopes(missing...).
-		WithHint("%s", scopeRemediationHint(pf.identity, missing, pf.appID, pf.brand))
+	return output.ErrWithHint(
+		output.ExitAuth, "auth",
+		fmt.Sprintf("missing required scopes for EventKey %s (as %s): %s",
+			pf.eventKey, pf.identity, strings.Join(missing, ", ")),
+		scopeRemediationHint(pf.identity, missing, pf.appID, pf.brand),
+	)
 }
 
 // scopeRemediationHint returns an identity-appropriate fix for missing scopes.
@@ -301,27 +300,23 @@ func preflightEventTypes(pf *preflightCtx) error {
 	if len(missing) == 0 {
 		return nil
 	}
-	return errs.NewValidationError(errs.SubtypeFailedPrecondition,
-		"EventKey %s requires event types not subscribed in console: %s",
-		pf.keyDef.Key, strings.Join(missing, ", ")).
-		WithHint("subscribe these events and publish a new app version at: %s",
-			consoleEventSubscriptionURL(pf.brand, pf.appID))
+	return output.ErrWithHint(
+		output.ExitValidation, "validation",
+		fmt.Sprintf("EventKey %s requires event types not subscribed in console: %s",
+			pf.keyDef.Key, strings.Join(missing, ", ")),
+		fmt.Sprintf("subscribe these events and publish a new app version at: %s",
+			consoleEventSubscriptionURL(pf.brand, pf.appID)),
+	)
 }
 
 // sanitizeOutputDir rejects absolute/parent-escaping paths and ~ (SafeOutputPath treats it as a literal dir name).
 func sanitizeOutputDir(dir string) (string, error) {
 	if strings.HasPrefix(dir, "~") {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"%s; use a relative path like ./output instead", errOutputDirTilde).
-			WithParam("--output-dir").
-			WithCause(errOutputDirTilde)
+		return "", output.ErrValidation("%s; use a relative path like ./output instead", errOutputDirTilde)
 	}
 	safe, err := validate.SafeOutputPath(dir)
 	if err != nil {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"%s %q: %s", errOutputDirUnsafe, dir, err).
-			WithParam("--output-dir").
-			WithCause(errOutputDirUnsafe)
+		return "", output.ErrValidation("%s %q: %s", errOutputDirUnsafe, dir, err)
 	}
 	return safe, nil
 }
@@ -333,21 +328,18 @@ func resolveTenantToken(ctx context.Context, f *cmdutil.Factory, appID string) (
 	}
 	result, err := f.Credential.ResolveToken(ctx, credential.NewTokenSpec(core.AsBot, appID))
 	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return "", err
-		}
-		return "", errs.NewAuthenticationError(errs.SubtypeTokenMissing,
-			"resolve tenant access token: %s", err).WithCause(err)
+		return "", output.ErrAuth("resolve tenant access token: %s", err)
 	}
 	if result == nil || result.Token == "" {
-		return "", errs.NewAuthenticationError(errs.SubtypeTokenMissing,
-			"no tenant access token available for app %s", appID).
-			WithHint("Check that app_secret is configured (lark-cli config show) and try 'lark-cli auth login'.")
+		return "", output.ErrWithHint(
+			output.ExitAuth, "auth",
+			fmt.Sprintf("no tenant access token available for app %s", appID),
+			"Check that app_secret is configured (lark-cli config show) and try 'lark-cli auth login'.",
+		)
 	}
 	return result.Token, nil
 }
 
-// Sentinels for errors.Is checks; call sites wrap them as typed ValidationError causes.
 var (
 	errInvalidParamFormat = errors.New("invalid --param format")
 	errOutputDirTilde     = errors.New("--output-dir does not support ~ expansion")
@@ -359,10 +351,7 @@ func parseParams(raw []string) (map[string]string, error) {
 	for _, kv := range raw {
 		k, v, ok := strings.Cut(kv, "=")
 		if !ok || k == "" {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"%s %q: expected key=value", errInvalidParamFormat, kv).
-				WithParam("--param").
-				WithCause(errInvalidParamFormat)
+			return nil, output.ErrValidation("%s %q: expected key=value", errInvalidParamFormat, kv)
 		}
 		m[k] = v
 	}
@@ -381,8 +370,3 @@ func watchStdinEOF(r io.Reader, cancel context.CancelFunc, errOut io.Writer) {
 		cancel()
 	}()
 }
-
-// shouldWatchStdinEOF gates the stdin-EOF shutdown watcher: non-TTY unbounded runs only (<= 0 mirrors downstream's >0-is-bounded semantics, so negative bounds stay unbounded).
-func shouldWatchStdinEOF(isTerminal bool, maxEvents int, timeout time.Duration) bool {
-	return !isTerminal && maxEvents <= 0 && timeout <= 0
-}

cmd/event/consume_stdin_test.go

@@ -61,70 +61,3 @@ func TestWatchStdinEOF_DiagnosticMessage(t *testing.T) {
 		t.Fatal("watchStdinEOF did not cancel within 1s of EOF")
 	}
 }
-
-func TestShouldWatchStdinEOF(t *testing.T) {
-	tests := []struct {
-		name       string
-		isTerminal bool
-		maxEvents  int
-		timeout    time.Duration
-		want       bool
-	}{
-		{
-			name:       "terminal",
-			isTerminal: true,
-			want:       false,
-		},
-		{
-			name: "non terminal unbounded",
-			want: true,
-		},
-		{
-			name:      "non terminal negative max events is unbounded",
-			maxEvents: -1,
-			want:      true,
-		},
-		{
-			name:    "non terminal negative timeout is unbounded",
-			timeout: -1 * time.Second,
-			want:    true,
-		},
-		{
-			name:      "non terminal max events bounded",
-			maxEvents: 1,
-			want:      false,
-		},
-		{
-			name:    "non terminal timeout bounded",
-			timeout: 10 * time.Minute,
-			want:    false,
-		},
-		{
-			name:      "non terminal both bounds positive",
-			maxEvents: 1,
-			timeout:   10 * time.Minute,
-			want:      false,
-		},
-		{
-			name:      "non terminal bounded max events with negative timeout",
-			maxEvents: 1,
-			timeout:   -1 * time.Second,
-			want:      false,
-		},
-		{
-			name:      "non terminal bounded timeout with negative max events",
-			maxEvents: -1,
-			timeout:   10 * time.Minute,
-			want:      false,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := shouldWatchStdinEOF(tt.isTerminal, tt.maxEvents, tt.timeout)
-			if got != tt.want {
-				t.Fatalf("shouldWatchStdinEOF() = %v, want %v", got, tt.want)
-			}
-		})
-	}
-}

cmd/event/consume_test.go

@@ -4,14 +4,9 @@
 package event
 
 import (
-	"context"
 	"errors"
 	"strings"
 	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/credential"
 )
 
 func TestParseParams(t *testing.T) {
@@ -78,7 +73,6 @@ func TestParseParams(t *testing.T) {
 				if tc.wantEcho != "" && !strings.Contains(err.Error(), tc.wantEcho) {
 					t.Errorf("err %q should echo %q so user sees the bad input", err.Error(), tc.wantEcho)
 				}
-				assertInvalidArgumentParam(t, err, "--param")
 				return
 			}
 			if err != nil {
@@ -96,77 +90,6 @@ func TestParseParams(t *testing.T) {
 	}
 }
 
-// emptyTokenResolver resolves to a result that carries no token.
-type emptyTokenResolver struct{}
-
-func (emptyTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
-	return &credential.TokenResult{}, nil
-}
-
-// failingTokenResolver fails outright with an untyped error.
-type failingTokenResolver struct{}
-
-func (failingTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
-	return nil, errors.New("backend unavailable")
-}
-
-func factoryWithResolver(r credential.DefaultTokenResolver) *cmdutil.Factory {
-	return &cmdutil.Factory{Credential: credential.NewCredentialProvider(nil, nil, r, nil)}
-}
-
-func TestResolveTenantToken_EmptyTokenResult(t *testing.T) {
-	_, err := resolveTenantToken(context.Background(), factoryWithResolver(emptyTokenResolver{}), "cli_x")
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryAuthentication || p.Subtype != errs.SubtypeTokenMissing {
-		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
-			errs.CategoryAuthentication, errs.SubtypeTokenMissing)
-	}
-	var malformed *credential.MalformedTokenResultError
-	if !errors.As(err, &malformed) {
-		t.Error("empty-token failure should preserve the credential-layer cause")
-	}
-}
-
-func TestResolveTenantToken_ResolverFailure(t *testing.T) {
-	_, err := resolveTenantToken(context.Background(), factoryWithResolver(failingTokenResolver{}), "cli_x")
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryAuthentication || p.Subtype != errs.SubtypeTokenMissing {
-		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
-			errs.CategoryAuthentication, errs.SubtypeTokenMissing)
-	}
-	if errors.Unwrap(err) == nil {
-		t.Error("resolver failure should preserve its cause")
-	}
-}
-
-// assertInvalidArgumentParam verifies err is a typed validation error with
-// subtype invalid_argument naming the given flag in its param field.
-func assertInvalidArgumentParam(t *testing.T, err error, param string) {
-	t.Helper()
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype = %s, want %s", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != param {
-		t.Errorf("param = %q, want %q", ve.Param, param)
-	}
-}
-
 func TestSanitizeOutputDir(t *testing.T) {
 	cases := []struct {
 		name       string
@@ -207,7 +130,6 @@ func TestSanitizeOutputDir(t *testing.T) {
 				if !errors.Is(err, tc.wantSentry) {
 					t.Fatalf("want errors.Is(err, %v), got %q", tc.wantSentry, err.Error())
 				}
-				assertInvalidArgumentParam(t, err, "--output-dir")
 				return
 			}
 			if err != nil {

cmd/event/format_helpers_test.go

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

cmd/event/preflight_test.go

@@ -8,10 +8,10 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/appmeta"
 	"github.com/larksuite/cli/internal/core"
 	eventlib "github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/output"
 )
 
 func newPreflightCtx(appID string, brand core.LarkBrand, identity core.Identity, keyDef *eventlib.KeyDefinition, appVer *appmeta.AppVersion) *preflightCtx {
@@ -89,17 +89,19 @@ func TestPreflightEventTypes_MissingBlocks(t *testing.T) {
 	if !strings.Contains(err.Error(), "mail.user_mailbox.event.message_read_v1") {
 		t.Errorf("error should name the missing event type, got: %v", err)
 	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
+	var exit *output.ExitError
+	if !errors.As(err, &exit) {
+		t.Fatalf("expected output.ExitError, got %T: %v", err, err)
 	}
-	if p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("problem = %s/%s, want %s/%s", p.Category, p.Subtype,
-			errs.CategoryValidation, errs.SubtypeFailedPrecondition)
+	if exit.Code != output.ExitValidation {
+		t.Errorf("ExitCode = %d, want ExitValidation (%d)", exit.Code, output.ExitValidation)
+	}
+	if exit.Detail == nil {
+		t.Fatal("expected Detail with hint")
 	}
 	wantURL := "https://open.feishu.cn/app/cli_XXXXXXXXXXXXXXXX/event"
-	if !strings.Contains(p.Hint, wantURL) {
-		t.Errorf("hint missing subscription URL %q\ngot: %s", wantURL, p.Hint)
+	if !strings.Contains(exit.Detail.Hint, wantURL) {
+		t.Errorf("hint missing subscription URL %q\ngot: %s", wantURL, exit.Detail.Hint)
 	}
 }
 
@@ -143,19 +145,17 @@ func TestPreflightScopes_Bot_MissingBlocks(t *testing.T) {
 	if !strings.Contains(err.Error(), "im:message.group_at_msg") {
 		t.Errorf("error should name missing scope, got: %v", err)
 	}
-	var permErr *errs.PermissionError
-	if !errors.As(err, &permErr) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
+	var exit *output.ExitError
+	if !errors.As(err, &exit) {
+		t.Fatalf("expected output.ExitError, got %T: %v", err, err)
 	}
-	if permErr.Category != errs.CategoryAuthorization || permErr.Subtype != errs.SubtypeMissingScope {
-		t.Errorf("problem = %s/%s, want %s/%s", permErr.Category, permErr.Subtype,
-			errs.CategoryAuthorization, errs.SubtypeMissingScope)
+	if exit.Code != output.ExitAuth {
+		t.Errorf("ExitCode = %d, want ExitAuth (%d)", exit.Code, output.ExitAuth)
 	}
-	wantMissing := []string{"im:message.group_at_msg"}
-	if len(permErr.MissingScopes) != 1 || permErr.MissingScopes[0] != wantMissing[0] {
-		t.Errorf("MissingScopes = %v, want %v", permErr.MissingScopes, wantMissing)
+	if exit.Detail == nil {
+		t.Fatal("expected Detail with hint, got nil Detail")
 	}
-	hint := permErr.Hint
+	hint := exit.Detail.Hint
 	wantSubstrings := []string{
 		"https://open.feishu.cn/app/cli_x/auth?q=",
 		"im:message.group_at_msg",

cmd/event/runtime.go

@@ -6,8 +6,8 @@ package event
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/core"
 )
@@ -26,11 +26,7 @@ func (r *consumeRuntime) CallAPI(ctx context.Context, method, path string, body
 		As:     r.accessIdentity,
 	})
 	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport,
-			"api %s %s: %s", method, path, err).WithCause(err)
+		return nil, err
 	}
 	// Non-JSON HTTP errors (gateway text/plain 404 etc.) skip OAPI envelope parsing.
 	ct := resp.Header.Get("Content-Type")
@@ -40,20 +36,11 @@ func (r *consumeRuntime) CallAPI(ctx context.Context, method, path string, body
 		if len(body) > maxBodyEcho {
 			body = body[:maxBodyEcho] + "…(truncated)"
 		}
-		if resp.StatusCode >= 500 {
-			return nil, errs.NewNetworkError(errs.SubtypeNetworkServer,
-				"api %s %s returned %d: %s", method, path, resp.StatusCode, body).WithRetryable()
-		}
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"api %s %s returned %d: %s", method, path, resp.StatusCode, body)
+		return nil, fmt.Errorf("api %s %s returned %d: %s", method, path, resp.StatusCode, body)
 	}
 	result, err := client.ParseJSONResponse(resp)
 	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"api %s %s: %s", method, path, err).WithCause(err)
+		return nil, err
 	}
 	if apiErr := r.client.CheckResponse(result, r.accessIdentity); apiErr != nil {
 		return json.RawMessage(resp.RawBody), apiErr

cmd/event/runtime_test.go

@@ -1,147 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package event
-
-import (
-	"context"
-	"errors"
-	"io"
-	"net/http"
-	"strings"
-	"testing"
-
-	lark "github.com/larksuite/oapi-sdk-go/v3"
-	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/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-// staticTokenResolver always returns a fixed token without any HTTP calls.
-type staticTokenResolver struct{}
-
-func (s *staticTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
-	return &credential.TokenResult{Token: "test-token"}, nil
-}
-
-// stubRoundTripper intercepts every outgoing request with a canned response.
-type stubRoundTripper struct {
-	respond func(*http.Request) (*http.Response, error)
-}
-
-func (s stubRoundTripper) RoundTrip(r *http.Request) (*http.Response, error) { return s.respond(r) }
-
-func newTestConsumeRuntime(rt http.RoundTripper) *consumeRuntime {
-	sdk := lark.NewClient("test-app", "test-secret",
-		lark.WithEnableTokenCache(false),
-		lark.WithLogLevel(larkcore.LogLevelError),
-		lark.WithHttpClient(&http.Client{Transport: rt}),
-	)
-	return &consumeRuntime{
-		client: &client.APIClient{
-			SDK:        sdk,
-			ErrOut:     io.Discard,
-			Credential: credential.NewCredentialProvider(nil, nil, &staticTokenResolver{}, nil),
-			Config:     &core.CliConfig{AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu},
-		},
-		accessIdentity: core.AsBot,
-	}
-}
-
-func stubResponse(status int, contentType, body string) func(*http.Request) (*http.Response, error) {
-	return func(r *http.Request) (*http.Response, error) {
-		return &http.Response{
-			StatusCode: status,
-			Header:     http.Header{"Content-Type": []string{contentType}},
-			Body:       io.NopCloser(strings.NewReader(body)),
-			Request:    r,
-		}, nil
-	}
-}
-
-func requireCallAPIProblem(t *testing.T, err error, category errs.Category, subtype errs.Subtype) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != category || p.Subtype != subtype {
-		t.Fatalf("problem = %s/%s, want %s/%s", p.Category, p.Subtype, category, subtype)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_NonJSONHTTPError(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusNotFound, "text/plain", "gone")})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	requireCallAPIProblem(t, err, errs.CategoryInternal, errs.SubtypeInvalidResponse)
-	if !strings.Contains(err.Error(), "returned 404") {
-		t.Errorf("error should echo the HTTP status, got: %v", err)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_NonJSONHTTPErrorTruncatesLongBody(t *testing.T) {
-	long := strings.Repeat("x", 300)
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusBadGateway, "text/html", long)})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	requireCallAPIProblem(t, err, errs.CategoryNetwork, errs.SubtypeNetworkServer)
-	p, _ := errs.ProblemOf(err)
-	if !p.Retryable {
-		t.Fatal("5xx non-JSON response should be marked retryable")
-	}
-	if !strings.Contains(err.Error(), "…(truncated)") {
-		t.Errorf("long body should be truncated in the message, got: %v", err)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_UnparsableJSONBody(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusOK, "application/json", "{not json")})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	requireCallAPIProblem(t, err, errs.CategoryInternal, errs.SubtypeInvalidResponse)
-}
-
-func TestConsumeRuntimeCallAPI_TransportFailure(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: func(*http.Request) (*http.Response, error) {
-		return nil, errors.New("connection refused")
-	}})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryNetwork {
-		t.Fatalf("category = %s, want %s", p.Category, errs.CategoryNetwork)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_EnvelopeErrorIsTyped(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusOK, "application/json",
-		`{"code":99991663,"msg":"app not found"}`)})
-	_, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	if _, ok := errs.ProblemOf(err); !ok {
-		t.Fatalf("envelope error should be typed via BuildAPIError, got %T: %v", err, err)
-	}
-}
-
-func TestConsumeRuntimeCallAPI_Success(t *testing.T) {
-	r := newTestConsumeRuntime(stubRoundTripper{respond: stubResponse(http.StatusOK, "application/json",
-		`{"code":0,"data":{"ok":true}}`)})
-	raw, err := r.CallAPI(context.Background(), "GET", "/open-apis/event/v1/connection", nil)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if !strings.Contains(string(raw), `"code":0`) {
-		t.Errorf("raw body should pass through, got: %s", raw)
-	}
-}

cmd/event/schema.go

@@ -11,7 +11,6 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	eventlib "github.com/larksuite/cli/internal/event"
 	"github.com/larksuite/cli/internal/event/schemas"
@@ -40,14 +39,12 @@ func resolveSchemaJSON(def *eventlib.KeyDefinition) (json.RawMessage, []string,
 	if len(def.Schema.FieldOverrides) > 0 {
 		var parsed map[string]interface{}
 		if err := json.Unmarshal(base, &parsed); err != nil {
-			return nil, nil, errs.NewInternalError(errs.SubtypeUnknown,
-				"parse base schema for field overrides: %s", err).WithCause(err)
+			return nil, nil, err
 		}
 		orphans := schemas.ApplyFieldOverrides(parsed, def.Schema.FieldOverrides)
 		out, err := json.Marshal(parsed)
 		if err != nil {
-			return nil, nil, errs.NewInternalError(errs.SubtypeUnknown,
-				"serialize schema with field overrides: %s", err).WithCause(err)
+			return nil, nil, err
 		}
 		return out, orphans, nil
 	}
@@ -76,7 +73,7 @@ func renderSpec(s *eventlib.SchemaSpec) (json.RawMessage, error) {
 		copy(buf, s.Raw)
 		return buf, nil
 	}
-	return nil, errs.NewInternalError(errs.SubtypeUnknown, "schemaSpec has neither Type nor Raw")
+	return nil, fmt.Errorf("schemaSpec has neither Type nor Raw")
 }
 
 func NewCmdSchema(f *cmdutil.Factory) *cobra.Command {
@@ -134,16 +131,12 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 	if len(def.Params) > 0 {
 		fmt.Fprintf(out, "\nParameters:\n")
 		w := tabwriter.NewWriter(out, 0, 4, 2, ' ', 0)
-		fmt.Fprintf(w, "  NAME\tTYPE\tREQUIRED\tSUB-KEY\tDEFAULT\tDESCRIPTION\n")
+		fmt.Fprintf(w, "  NAME\tTYPE\tREQUIRED\tDEFAULT\tDESCRIPTION\n")
 		for _, p := range def.Params {
 			required := "no"
 			if p.Required {
 				required = "yes"
 			}
-			subKey := "no"
-			if p.SubscriptionKey {
-				subKey = "yes"
-			}
 			defaultVal := p.Default
 			if defaultVal == "" {
 				defaultVal = "-"
@@ -152,7 +145,7 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 			if desc == "" {
 				desc = "-"
 			}
-			fmt.Fprintf(w, "  %s\t%s\t%s\t%s\t%s\t%s\n", p.Name, p.Type, required, subKey, defaultVal, desc)
+			fmt.Fprintf(w, "  %s\t%s\t%s\t%s\t%s\n", p.Name, p.Type, required, defaultVal, desc)
 		}
 		w.Flush()
 
@@ -172,7 +165,7 @@ func runSchema(f *cmdutil.Factory, key string, asJSON bool) error {
 
 	resolved, _, err := resolveSchemaJSON(def)
 	if err != nil {
-		return err
+		return output.Errorf(output.ExitInternal, "internal", "resolve schema: %v", err)
 	}
 	if resolved != nil {
 		fmt.Fprintf(out, "\nOutput Schema:\n")

cmd/event/schema_test.go

@@ -10,7 +10,6 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	eventlib "github.com/larksuite/cli/internal/event"
@@ -96,79 +95,6 @@ func TestRunSchema_JSONOutput(t *testing.T) {
 	}
 }
 
-func TestSchema_RendersSubscriptionKeyMarker(t *testing.T) {
-	const syntheticKey = "test.evt_sub"
-	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })
-
-	eventlib.RegisterKey(eventlib.KeyDefinition{
-		Key:       syntheticKey,
-		EventType: syntheticKey,
-		Params: []eventlib.ParamDef{
-			{Name: "mailbox", SubscriptionKey: true, Description: "subscription id source"},
-			{Name: "folders", Description: "filter only"},
-		},
-		Schema: eventlib.SchemaDef{Native: &eventlib.SchemaSpec{Type: reflect.TypeOf(struct{ X string }{})}},
-	})
-
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
-	if err := runSchema(f, syntheticKey, false); err != nil {
-		t.Fatalf("runSchema: %v", err)
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, "SUB-KEY") {
-		t.Errorf("missing SUB-KEY column header in:\n%s", out)
-	}
-
-	// Find the mailbox row and verify "yes" is present
-	var mailboxRow string
-	for _, ln := range strings.Split(out, "\n") {
-		if strings.Contains(ln, "mailbox") && !strings.Contains(ln, "NAME") {
-			mailboxRow = ln
-			break
-		}
-	}
-	if !strings.Contains(mailboxRow, "yes") {
-		t.Errorf("mailbox row missing yes SUB-KEY marker: %q", mailboxRow)
-	}
-
-	// Find the folders row and verify "no" is present
-	var foldersRow string
-	for _, ln := range strings.Split(out, "\n") {
-		if strings.Contains(ln, "folders") && !strings.Contains(ln, "NAME") {
-			foldersRow = ln
-			break
-		}
-	}
-	if !strings.Contains(foldersRow, "no") {
-		t.Errorf("folders row missing no SUB-KEY marker: %q", foldersRow)
-	}
-}
-
-func TestSchema_JSON_IncludesSubscriptionKey(t *testing.T) {
-	const syntheticKey = "test.evt_json"
-	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })
-
-	eventlib.RegisterKey(eventlib.KeyDefinition{
-		Key:       syntheticKey,
-		EventType: syntheticKey,
-		Params:    []eventlib.ParamDef{{Name: "mailbox", SubscriptionKey: true}},
-		Schema:    eventlib.SchemaDef{Native: &eventlib.SchemaSpec{Type: reflect.TypeOf(struct{ X string }{})}},
-	})
-
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
-	if err := runSchema(f, syntheticKey, true); err != nil {
-		t.Fatalf("runSchema json: %v", err)
-	}
-
-	if !strings.Contains(stdout.String(), `"subscription_key"`) {
-		t.Errorf("JSON output missing subscription_key field: %s", stdout.String())
-	}
-	if !strings.Contains(stdout.String(), `true`) {
-		t.Errorf("JSON output missing subscription_key: true value: %s", stdout.String())
-	}
-}
-
 func TestResolveSchemaJSON_CustomWithOverlay(t *testing.T) {
 	const syntheticKey = "t.custom.overlay"
 	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })
@@ -203,38 +129,3 @@ func TestResolveSchemaJSON_CustomWithOverlay(t *testing.T) {
 		t.Errorf("overlay format = %v, want open_id", got)
 	}
 }
-
-func TestRenderSpec_EmptySpecIsTypedInternalError(t *testing.T) {
-	_, err := renderSpec(&eventlib.SchemaSpec{})
-	if err == nil {
-		t.Fatal("expected error for spec with neither Type nor Raw")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryInternal {
-		t.Errorf("category = %s, want %s", p.Category, errs.CategoryInternal)
-	}
-}
-
-func TestResolveSchemaJSON_InvalidBaseWithOverridesIsTypedInternalError(t *testing.T) {
-	def := &eventlib.KeyDefinition{
-		Key: "synthetic.invalid.base",
-		Schema: eventlib.SchemaDef{
-			Custom:         &eventlib.SchemaSpec{Raw: json.RawMessage("{not json")},
-			FieldOverrides: map[string]schemas.FieldMeta{"x": {}},
-		},
-	}
-	_, _, err := resolveSchemaJSON(def)
-	if err == nil {
-		t.Fatal("expected error for unparsable base schema")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed errs error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryInternal {
-		t.Errorf("category = %s, want %s", p.Category, errs.CategoryInternal)
-	}
-}

cmd/event/status.go

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

cmd/event/suggestions.go

@@ -8,8 +8,8 @@ import (
 	"sort"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	eventlib "github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/suggest"
 )
 
@@ -64,6 +64,9 @@ func unknownEventKeyErr(key string) error {
 	if guesses := suggestEventKeys(key); len(guesses) > 0 {
 		msg += " — did you mean " + formatSuggestions(guesses) + "?"
 	}
-	return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", msg).
-		WithHint("Run 'lark-cli event list' to see available keys.")
+	return output.ErrWithHint(
+		output.ExitValidation, "validation",
+		msg,
+		"Run 'lark-cli event list' to see available keys.",
+	)
 }

cmd/root_integration_test.go

@@ -377,9 +377,9 @@ func TestIntegration_Shortcut_BusinessError_OutputsEnvelope(t *testing.T) {
 		OK:       false,
 		Identity: "bot",
 		Error: &output.ErrDetail{
-			Type:    "api",
+			Type:    "api_error",
 			Code:    230002,
-			Message: "Bot/User can NOT be out of the chat.",
+			Message: "HTTP 400: Bot/User can NOT be out of the chat.",
 		},
 	})
 }

cmd/skill/skill.go

@@ -1,183 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package skill implements the `lark-cli skills` command group, which serves
-// binary-embedded skill content to AI agents. The package is "skill"; the
-// user-facing verb is "skills".
-package skill
-
-import (
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/skillcontent"
-	"github.com/spf13/cobra"
-)
-
-func newReader(f *cmdutil.Factory) (*skillcontent.Reader, error) {
-	if f.SkillContent == nil {
-		return nil, errs.NewInternalError(errs.SubtypeFileIO,
-			"skill content not embedded in this build")
-	}
-	return skillcontent.New(f.SkillContent), nil
-}
-
-type readEnvelope struct {
-	Skill    string `json:"skill"`
-	Path     string `json:"path"`
-	Content  string `json:"content"`
-	Guidance string `json:"guidance,omitempty"`
-}
-
-type listEnvelope struct {
-	OK     bool                     `json:"ok"`
-	Skills []skillcontent.SkillInfo `json:"skills"`
-	Count  int                      `json:"count"`
-}
-
-type listPathEnvelope struct {
-	OK      bool                    `json:"ok"`
-	Path    string                  `json:"path"`
-	Entries []skillcontent.DirEntry `json:"entries"`
-	Count   int                     `json:"count"`
-}
-
-func NewCmdSkill(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "skills",
-		Short: "Read embedded skill content (list / read)",
-		Long: "Read agent-readable skill content (SKILL.md and reference files) embedded in " +
-			"the CLI binary at build time, so it stays in sync with the CLI version. " +
-			"Machine resources such as assets/ and scripts/ are not embedded.",
-	}
-	// Risk is set on each leaf (GetRisk does not walk parents); the group has none.
-	cmdutil.DisableAuthCheck(cmd)
-	cmd.AddCommand(newListCmd(f), newReadCmd(f))
-	return cmd
-}
-
-func newListCmd(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "list [name[/path]]",
-		Short: "List skills, or list one layer under a skill path (like ls)",
-		Example: `  lark-cli skills list                      # all skills: name, description, version
-  lark-cli skills list lark-doc             # one layer under a skill (like ls)
-  lark-cli skills list lark-doc/references  # one layer under a subdirectory`,
-		Args: cobra.ArbitraryArgs,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if len(args) > 1 {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"list takes at most 1 argument: [name[/path]]").
-					WithHint("run 'lark-cli skills list --help'")
-			}
-			r, err := newReader(f)
-			if err != nil {
-				return err
-			}
-			if len(args) == 0 {
-				skills, err := r.List()
-				if err != nil {
-					return err
-				}
-				output.PrintJson(f.IOStreams.Out, listEnvelope{OK: true, Skills: skills, Count: len(skills)})
-				return nil
-			}
-			entries, listed, err := r.ListPath(args[0])
-			if err != nil {
-				return err
-			}
-			output.PrintJson(f.IOStreams.Out, listPathEnvelope{OK: true, Path: listed, Entries: entries, Count: len(entries)})
-			return nil
-		},
-	}
-	// --json is a no-op (list is always JSON), accepted only to stay symmetric with read.
-	cmd.Flags().Bool("json", false, "no-op (list output is always JSON)")
-	cmdutil.SetRisk(cmd, "read")
-	cmdutil.DisableAuthCheck(cmd)
-	return cmd
-}
-
-func newReadCmd(f *cmdutil.Factory) *cobra.Command {
-	var asJSON bool
-	cmd := &cobra.Command{
-		Use:   "read <name>[/<path>] [path]",
-		Short: "Print a skill's SKILL.md, or a file under the skill (raw markdown by default)",
-		Example: `  lark-cli skills read lark-doc                             # the skill's SKILL.md
-  lark-cli skills read lark-doc references/lark-doc-fetch.md  # a file under the skill
-  lark-cli skills read lark-doc/references/lark-doc-fetch.md  # same, slash form
-  lark-cli skills read lark-doc --json                      # JSON envelope`,
-		Args: cobra.ArbitraryArgs,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			name, relpath, err := parseReadTarget(args)
-			if err != nil {
-				return err
-			}
-			r, err := newReader(f)
-			if err != nil {
-				return err
-			}
-
-			var content []byte
-			var pathOut string
-			if relpath == "" {
-				content, err = r.ReadSkill(name)
-				pathOut = "SKILL.md"
-			} else {
-				content, pathOut, err = r.ReadReference(name, relpath)
-			}
-			if err != nil {
-				return err
-			}
-
-			isMain := pathOut == "SKILL.md"
-			if asJSON {
-				env := readEnvelope{Skill: name, Path: pathOut, Content: string(content)}
-				if isMain {
-					env.Guidance = readGuidance(name)
-				}
-				output.PrintJson(f.IOStreams.Out, env)
-				return nil
-			}
-			// Raw stdout stays byte-identical to the file; guidance goes to stderr.
-			if _, err := f.IOStreams.Out.Write(content); err != nil {
-				return errs.NewInternalError(errs.SubtypeFileIO, "failed to write output: %v", err)
-			}
-			if isMain {
-				fmt.Fprintln(f.IOStreams.ErrOut, readGuidance(name))
-			}
-			return nil
-		},
-	}
-	cmd.Flags().BoolVar(&asJSON, "json", false, "output as a JSON envelope instead of raw markdown")
-	cmdutil.SetRisk(cmd, "read")
-	cmdutil.DisableAuthCheck(cmd)
-	return cmd
-}
-
-// parseReadTarget maps 1-or-2 positional args to (name, relpath); a lone
-// "<a>/<b>" splits on the first '/', and relpath "" reads the main SKILL.md.
-func parseReadTarget(args []string) (name, relpath string, err error) {
-	switch len(args) {
-	case 1:
-		name, relpath = skillcontent.SplitArg(args[0])
-		return name, relpath, nil
-	case 2:
-		return args[0], args[1], nil
-	default:
-		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"read requires 1 or 2 arguments: <name>[/<path>] [path]").
-			WithHint("run 'lark-cli skills read --help'")
-	}
-}
-
-// readGuidance routes cross-skill "../lark-foo/..." references back through
-// `skills read lark-foo/...`: the path guard rejects a literal "../", so the
-// relative form must be rewritten.
-func readGuidance(name string) string {
-	return fmt.Sprintf("> Tip: read this skill's own files (e.g. `references/...`) with "+
-		"`lark-cli skills read %s <relative-path>` to keep them in sync with this CLI version. "+
-		"A reference to another skill (`../lark-foo/...`) uses the same command with the "+
-		"leading `../` removed: `lark-cli skills read lark-foo/...`.", name)
-}

cmd/skill/skill_test.go

@@ -1,306 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package skill
-
-import (
-	"encoding/json"
-	"io"
-	"io/fs"
-	"strings"
-	"testing"
-	"testing/fstest"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-// calFS is the default single-skill content tree for these tests. The embedded
-// FS is now injected through the Factory (no package global), so tests pass it
-// explicitly to run() — nothing is shared, so they are safe under -parallel.
-func calFS() fstest.MapFS {
-	return fstest.MapFS{
-		"lark-calendar/SKILL.md":             {Data: []byte("---\nname: lark-calendar\nversion: 1.0.0\ndescription: \"Cal\"\nmetadata:\n  cliHelp: \"lark-cli calendar --help\"\n---\nbody")},
-		"lark-calendar/references/agenda.md": {Data: []byte("# Agenda")},
-	}
-}
-
-// run executes the skills command tree against the given content FS (may be nil
-// to exercise the not-embedded path) and returns stdout/stderr/err.
-func run(t *testing.T, fsys fs.FS, args ...string) (stdout, stderr string, err error) {
-	t.Helper()
-	// Isolate CLI config state so tests never read/write the real config dir
-	// (repo convention).
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, out, errOut, _ := cmdutil.TestFactory(t, nil)
-	f.SkillContent = fsys
-	cmd := NewCmdSkill(f)
-	cmd.SetOut(io.Discard)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs(args)
-	err = cmd.Execute()
-	return out.String(), errOut.String(), err
-}
-
-func TestSkillList(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "list")
-	if err != nil {
-		t.Fatalf("list error: %v", err)
-	}
-	var got struct {
-		OK     bool             `json:"ok"`
-		Skills []map[string]any `json:"skills"`
-		Count  int              `json:"count"`
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	// "ok" is an explicit success marker (the list envelope is a typed struct;
-	// no automatic _notice attaches).
-	if !got.OK {
-		t.Error("expected ok=true in list envelope")
-	}
-	if got.Count != 1 || len(got.Skills) != 1 {
-		t.Fatalf("count: got %d", got.Count)
-	}
-	if got.Skills[0]["name"] != "lark-calendar" {
-		t.Errorf("name: got %v", got.Skills[0]["name"])
-	}
-	// Top-level list carries version + metadata, not a references list.
-	if _, ok := got.Skills[0]["references"]; ok {
-		t.Error("top-level list must not include references")
-	}
-	if got.Skills[0]["version"] != "1.0.0" {
-		t.Errorf("version: got %v, want 1.0.0", got.Skills[0]["version"])
-	}
-	if _, ok := got.Skills[0]["metadata"]; !ok {
-		t.Error("expected metadata in list entry")
-	}
-}
-
-func TestSkillListJSONFlagAccepted(t *testing.T) {
-	// `list --json` must be accepted (no-op), not rejected as an unknown flag,
-	// so it stays symmetric with read --json.
-	stdout, _, err := run(t, calFS(), "list", "--json")
-	if err != nil {
-		t.Fatalf("list --json error: %v", err)
-	}
-	var got struct {
-		OK    bool `json:"ok"`
-		Count int  `json:"count"`
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	if !got.OK || got.Count != 1 {
-		t.Errorf("envelope: %+v", got)
-	}
-}
-
-func TestSkillListPath(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "list", "lark-calendar")
-	if err != nil {
-		t.Fatalf("list <name> error: %v", err)
-	}
-	var got struct {
-		OK      bool   `json:"ok"`
-		Path    string `json:"path"`
-		Entries []struct {
-			Path  string `json:"path"`
-			IsDir bool   `json:"is_dir"`
-		} `json:"entries"`
-		Count int `json:"count"`
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	if !got.OK || got.Path != "lark-calendar" {
-		t.Errorf("envelope: %+v", got)
-	}
-	// One layer under the skill root: SKILL.md (file) + references (dir).
-	if got.Count != 2 || len(got.Entries) != 2 {
-		t.Fatalf("entries: got %+v", got.Entries)
-	}
-	if got.Entries[0].Path != "lark-calendar/SKILL.md" || got.Entries[0].IsDir {
-		t.Errorf("entry[0]: got %+v", got.Entries[0])
-	}
-	if got.Entries[1].Path != "lark-calendar/references" || !got.Entries[1].IsDir {
-		t.Errorf("entry[1]: got %+v", got.Entries[1])
-	}
-}
-
-func TestSkillListPathUnknown(t *testing.T) {
-	_, _, err := run(t, calFS(), "list", "no-such-skill")
-	if err == nil || !strings.Contains(err.Error(), "unknown skill") {
-		t.Fatalf("expected 'unknown skill' error, got %v", err)
-	}
-}
-
-func TestSkillListPathTraversal(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "list", "lark-calendar/../../etc")
-	if err == nil || !strings.Contains(err.Error(), "invalid path") {
-		t.Fatalf("expected 'invalid path' error, got %v", err)
-	}
-	if stdout != "" {
-		t.Errorf("stdout must be empty on rejection, got %q", stdout)
-	}
-}
-
-func TestSkillListTooManyArgs(t *testing.T) {
-	_, _, err := run(t, calFS(), "list", "a", "b")
-	if err == nil || !strings.Contains(err.Error(), "at most 1 argument") {
-		t.Fatalf("expected 'at most 1 argument' error, got %v", err)
-	}
-}
-
-// TestSkillListSkipsDirWithoutSKILLmd proves a top-level dir lacking SKILL.md is
-// omitted from the catalog (no blank entry).
-func TestSkillListSkipsDirWithoutSKILLmd(t *testing.T) {
-	fsys := fstest.MapFS{
-		"lark-calendar/SKILL.md": {Data: []byte("---\nname: lark-calendar\ndescription: \"Cal\"\n---\nb")},
-		"not-a-skill/readme.txt": {Data: []byte("junk")}, // dir without SKILL.md
-	}
-	stdout, _, err := run(t, fsys, "list")
-	if err != nil {
-		t.Fatalf("list error: %v", err)
-	}
-	var got struct {
-		Skills []map[string]any `json:"skills"`
-		Count  int              `json:"count"`
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	if got.Count != 1 || got.Skills[0]["name"] != "lark-calendar" {
-		t.Fatalf("expected only lark-calendar, got %+v", got.Skills)
-	}
-}
-
-func TestSkillReadRaw(t *testing.T) {
-	stdout, stderr, err := run(t, calFS(), "read", "lark-calendar")
-	if err != nil {
-		t.Fatalf("read error: %v", err)
-	}
-	if !strings.HasPrefix(stdout, "---\nname: lark-calendar") {
-		t.Errorf("raw output: got %q", stdout)
-	}
-	// Raw stdout is byte-pure SKILL.md — the guidance tip must NOT be appended.
-	if strings.Contains(stdout, "Tip:") {
-		t.Errorf("raw stdout must not carry the guidance tip: got %q", stdout)
-	}
-	// Guidance goes to stderr: own files via `skills read <name> ...`, and
-	// cross-skill refs routed to `skills read <other-skill> ...` (version-
-	// consistent), not "read directly".
-	if !strings.Contains(stderr, "lark-cli skills read lark-calendar <relative-path>") {
-		t.Errorf("expected own-files guidance on stderr: got %q", stderr)
-	}
-	if !strings.Contains(stderr, "lark-cli skills read lark-foo/...") {
-		t.Errorf("expected cross-skill refs routed to skills read: got %q", stderr)
-	}
-	if strings.Contains(stderr, "instead of opening them directly") ||
-		strings.Contains(stderr, "read those directly") {
-		t.Errorf("guidance must not steer cross-skill refs to direct reads: got %q", stderr)
-	}
-}
-
-func TestSkillReadJSON(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "read", "lark-calendar", "--json")
-	if err != nil {
-		t.Fatalf("read --json error: %v", err)
-	}
-	var got struct {
-		Skill, Path, Content, Guidance string
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v", e)
-	}
-	if got.Skill != "lark-calendar" || got.Path != "SKILL.md" || got.Content == "" {
-		t.Errorf("envelope: %+v", got)
-	}
-	// Guidance is a separate field, not merged into content.
-	if got.Guidance == "" {
-		t.Error("expected guidance field for main SKILL.md")
-	}
-	if strings.Contains(got.Content, "Tip:") {
-		t.Error("guidance must not be merged into content")
-	}
-}
-
-func TestSkillReadFile(t *testing.T) {
-	// Both the 2-arg and slash forms read the same file, with no guidance tip.
-	for _, args := range [][]string{
-		{"read", "lark-calendar", "references/agenda.md"},
-		{"read", "lark-calendar/references/agenda.md"},
-	} {
-		stdout, stderr, err := run(t, calFS(), args...)
-		if err != nil {
-			t.Fatalf("read %v error: %v", args, err)
-		}
-		if stdout != "# Agenda" {
-			t.Errorf("read %v output: got %q", args, stdout)
-		}
-		// Reference reads carry no guidance on either stream.
-		if strings.Contains(stderr, "Tip:") {
-			t.Errorf("read %v must not emit guidance on stderr: got %q", args, stderr)
-		}
-	}
-}
-
-func TestSkillReadFileJSON(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "read", "lark-calendar", "references/agenda.md", "--json")
-	if err != nil {
-		t.Fatalf("read file --json error: %v", err)
-	}
-	var got struct {
-		Skill, Path, Content, Guidance string
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	if got.Skill != "lark-calendar" || got.Path != "references/agenda.md" || got.Content != "# Agenda" {
-		t.Errorf("envelope: %+v", got)
-	}
-	// Reference reads do not carry the guidance tip.
-	if got.Guidance != "" {
-		t.Errorf("reference read must not include guidance, got %q", got.Guidance)
-	}
-}
-
-func TestSkillReadUnknown(t *testing.T) {
-	_, _, err := run(t, calFS(), "read", "no-such")
-	if err == nil {
-		t.Fatal("expected error")
-	}
-	if !strings.Contains(err.Error(), "unknown skill") {
-		t.Errorf("err: %v", err)
-	}
-}
-
-func TestSkillReadMissingArg(t *testing.T) {
-	_, _, err := run(t, calFS(), "read")
-	if err == nil || !strings.Contains(err.Error(), "requires 1 or 2 arguments") {
-		t.Fatalf("expected arg error, got %v", err)
-	}
-}
-
-func TestSkillReadTraversal(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "read", "lark-calendar", "../../etc/passwd")
-	if err == nil {
-		t.Fatal("expected rejection")
-	}
-	if !strings.Contains(err.Error(), "invalid path") {
-		t.Errorf("err: %v", err)
-	}
-	if stdout != "" {
-		t.Errorf("stdout must be empty on rejection, got %q", stdout)
-	}
-}
-
-func TestSkillNilContentFS(t *testing.T) {
-	_, _, err := run(t, nil, "list")
-	if err == nil {
-		t.Fatal("expected error when SkillContent is nil")
-	}
-	if !strings.Contains(err.Error(), "not embedded") {
-		t.Errorf("err: %v", err)
-	}
-}

cmd/update/update_test.go

@@ -49,29 +49,18 @@ func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult, npmFn func(s
 		u.DetectOverride = func() selfupdate.DetectResult { return result }
 		u.NpmInstallOverride = npmFn
 		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsIndexFetchOverride = successfulSkillsIndexFetch()
 		u.SkillsCommandOverride = successfulSkillsCommand()
 		return u
 	}
 	t.Cleanup(func() { newUpdater = origNew })
 }
 
-func successfulSkillsIndexFetch() func() *selfupdate.NpmResult {
-	return func() *selfupdate.NpmResult {
-		r := &selfupdate.NpmResult{}
-		r.Stdout.WriteString(`{"skills":[{"name":"lark-calendar"},{"name":"lark-mail"}]}`)
-		return r
-	}
-}
-
 func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
 	return func(args ...string) *selfupdate.NpmResult {
 		r := &selfupdate.NpmResult{}
 		switch strings.Join(args, " ") {
 		case "-y skills add https://open.feishu.cn --list":
 			r.Stdout.WriteString("Available Skills\n │    lark-calendar\n │    lark-mail\n")
-		case "-y skills ls -g --json":
-			r.Stdout.WriteString(`[{"name":"lark-calendar","path":"/tmp/lark-calendar","scope":"global","agents":["Codex"]},{"name":"custom-skill","path":"/tmp/custom-skill","scope":"global","agents":["Codex"]}]`)
 		case "-y skills ls -g":
 			r.Stdout.WriteString("Global Skills\nlark-calendar /tmp/lark-calendar\ncustom-skill /tmp/custom-skill\n")
 		default:
@@ -487,10 +476,6 @@ func TestUpdateNpmVerifyFail_JSON_NoRestoreHintWhenBackupUnavailable(t *testing.
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return errors.New("bad binary") }
 		u.RestoreAvailableOverride = func() bool { return false }
-		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
-			t.Fatal("skills sync should not run when binary verification fails")
-			return nil
-		}
 		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			t.Fatal("skills sync should not run when binary verification fails")
 			return nil
@@ -823,11 +808,6 @@ func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
 		}
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
-			r := &selfupdate.NpmResult{}
-			r.Err = fmt.Errorf("index unavailable")
-			return r
-		}
 		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
@@ -880,11 +860,6 @@ func TestUpdateNpm_SkillsFail_Human(t *testing.T) {
 		}
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
-			r := &selfupdate.NpmResult{}
-			r.Err = fmt.Errorf("index unavailable")
-			return r
-		}
 		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
@@ -1029,7 +1004,6 @@ func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
 				return successfulSkillsCommand()(args...)
@@ -1068,7 +1042,6 @@ func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{
 					Method:       selfupdate.InstallManual,
@@ -1113,7 +1086,6 @@ func TestUpdateRun_Npm_RunsSkillsSync_WritesLatestState(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{
 					Method: selfupdate.InstallNpm, NpmAvailable: true,
@@ -1173,10 +1145,6 @@ func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{Method: selfupdate.InstallNpm, NpmAvailable: true}
 			},
-			SkillsIndexFetchOverride: func() *selfupdate.NpmResult {
-				skillsCalled = true
-				return successfulSkillsIndexFetch()()
-			},
 			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
 				return successfulSkillsCommand()(args...)
@@ -1226,10 +1194,6 @@ func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsIndexFetchOverride: func() *selfupdate.NpmResult {
-				skillsCalled = true
-				return successfulSkillsIndexFetch()()
-			},
 			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
 				return successfulSkillsCommand()(args...)

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

events/minutes/preconsume.go

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

events/register.go

@@ -8,7 +8,6 @@ import (
 	"github.com/larksuite/cli/events/im"
 	"github.com/larksuite/cli/events/minutes"
 	"github.com/larksuite/cli/events/vc"
-	"github.com/larksuite/cli/events/whiteboard"
 	"github.com/larksuite/cli/internal/event"
 )
 
@@ -18,7 +17,6 @@ func init() {
 		im.Keys(),
 		minutes.Keys(),
 		vc.Keys(),
-		whiteboard.Keys(),
 	}
 	for _, keys := range all {
 		for _, k := range keys {

events/vc/note_detail_retry_test.go

@@ -1,35 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package vc
-
-import (
-	"errors"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// isLarkCode must match the API code on typed errs.* errors — the consume
-// runtime classifies OAPI failures via errclass.BuildAPIError, so the
-// not-found retry in fillVCNoteGeneratedDetails depends on this reading
-// Problem.Code rather than the legacy envelope shape.
-func TestIsLarkCode_MatchesTypedAPIErrorCode(t *testing.T) {
-	typedNotFound := errs.NewAPIError(errs.SubtypeNotFound, "note not ready").
-		WithCode(vcNoteDetailNotFoundCode)
-	if !isLarkCode(typedNotFound, vcNoteDetailNotFoundCode) {
-		t.Fatal("typed API error carrying the not-found code must match (retry path)")
-	}
-	if isLarkCode(typedNotFound, 99999) {
-		t.Error("a different expected code must not match")
-	}
-
-	otherTyped := errs.NewAPIError(errs.SubtypeServerError, "boom").WithCode(500)
-	if isLarkCode(otherTyped, vcNoteDetailNotFoundCode) {
-		t.Error("typed error with another code must not match")
-	}
-
-	if isLarkCode(errors.New("plain failure"), vcNoteDetailNotFoundCode) {
-		t.Error("untyped error must not match")
-	}
-}

events/vc/note_generated.go

@@ -6,11 +6,12 @@ package vc
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 )
 
@@ -147,8 +148,9 @@ func fillVCNoteGeneratedDetails(ctx context.Context, rt event.APIClient, out *VC
 }
 
 func isLarkCode(err error, code int) bool {
-	if p, ok := errs.ProblemOf(err); ok {
-		return p.Code == code
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) && exitErr.Detail != nil {
+		return exitErr.Detail.Code == code
 	}
 	return false
 }

events/vc/preconsume.go

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

events/vc/recording_ended.go

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

events/vc/recording_started.go

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

events/vc/recording_test.go

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

events/vc/recording_transcript_generated.go

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

events/vc/register.go

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

events/whiteboard/native.go

@@ -1,23 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package whiteboard
-
-// BoardWhiteboardUpdatedV1Data is the flattened whiteboard updated source payload.
-type BoardWhiteboardUpdatedV1Data struct {
-	// WhiteboardID is the id of the whiteboard whose content was updated.
-	WhiteboardID string `json:"whiteboard_id"`
-	// OperatorIDs lists the operators that produced this update batch.
-	OperatorIDs []OperatorID `json:"operator_ids"`
-}
-
-// OperatorID identifies an operator that produced the whiteboard update,
-// expressed in the three Lark identity formats.
-type OperatorID struct {
-	// OpenID is the operator's open_id within the current app.
-	OpenID string `json:"open_id"`
-	// UnionID is the operator's union_id across apps under the same ISV.
-	UnionID string `json:"union_id"`
-	// UserID is the operator's user_id within the tenant.
-	UserID string `json:"user_id"`
-}

events/whiteboard/preconsume.go

@@ -1,56 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package whiteboard
-
-import (
-	"context"
-	"fmt"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/event"
-	"github.com/larksuite/cli/internal/validate"
-)
-
-// cleanupTimeout bounds how long the unsubscribe call has to finish during
-// PreConsume cleanup so a stuck OAPI cannot block process shutdown.
-const cleanupTimeout = 5 * time.Second
-
-// whiteboardSubscriptionPreConsume calls the whiteboard event subscribe OAPI
-// and returns a cleanup that invokes the matching unsubscribe.
-//
-// board.whiteboard.updated_v1 is subscribed per-whiteboard (by whiteboard_id),
-// so the path contains a :whiteboard_id placeholder that must be supplied via params.
-func whiteboardSubscriptionPreConsume(eventType string) func(context.Context, event.APIClient, map[string]string) (func() error, error) {
-	return func(ctx context.Context, rt event.APIClient, params map[string]string) (func() error, error) {
-		if rt == nil {
-			return nil, errs.NewInternalError(errs.SubtypeUnknown,
-				"runtime API client is required for pre-consume subscription")
-		}
-		whiteboardID := params["whiteboard_id"]
-		if whiteboardID == "" {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"param whiteboard_id is required for %s", eventType).
-				WithParam("--param").
-				WithHint("pass it as --param whiteboard_id=<id>; run `lark-cli event schema %s` for details", eventType)
-		}
-		encoded := validate.EncodePathSegment(whiteboardID)
-		subscribePath := fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/subscribe", encoded)
-		unsubscribePath := fmt.Sprintf("/open-apis/board/v1/whiteboards/%s/unsubscribe", encoded)
-
-		body := map[string]string{"event_type": eventType}
-		if _, err := rt.CallAPI(ctx, "POST", subscribePath, body); err != nil {
-			return nil, err
-		}
-
-		return func() error {
-			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
-			defer cancel()
-			if _, err := rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body); err != nil {
-				return err
-			}
-			return nil
-		}, nil
-	}
-}

events/whiteboard/preconsume_test.go

@@ -1,212 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package whiteboard
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"strings"
-	"sync"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/event"
-)
-
-// recordedCall captures a single APIClient invocation for assertion.
-type recordedCall struct {
-	method string
-	path   string
-	body   interface{}
-}
-
-// fakeAPIClient is a minimal event.APIClient stub that records calls and
-// can be configured to fail when the request path matches errOnPath.
-type fakeAPIClient struct {
-	mu        sync.Mutex
-	calls     []recordedCall
-	errOnPath string
-}
-
-// CallAPI records the invocation and optionally returns a simulated error
-// when the path contains the configured errOnPath substring.
-func (f *fakeAPIClient) CallAPI(_ context.Context, method, path string, body interface{}) (json.RawMessage, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.calls = append(f.calls, recordedCall{method: method, path: path, body: body})
-	if f.errOnPath != "" && strings.Contains(path, f.errOnPath) {
-		return nil, errors.New("simulated subscribe failure")
-	}
-	return json.RawMessage(`{}`), nil
-}
-
-// TestWhiteboardSubscriptionPreConsume_MissingWhiteboardID verifies that the
-// PreConsume hook fails fast with an actionable error when whiteboard_id
-// is absent from the params map.
-func TestWhiteboardSubscriptionPreConsume_MissingWhiteboardID(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
-	cleanup, err := pc(context.Background(), &fakeAPIClient{}, map[string]string{})
-	if err == nil {
-		t.Fatalf("expected error when whiteboard_id missing")
-	}
-	if cleanup != nil {
-		t.Fatalf("expected nil cleanup on error")
-	}
-	if !strings.Contains(err.Error(), "whiteboard_id") {
-		t.Fatalf("error should mention whiteboard_id, got: %v", err)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument || ve.Param != "--param" {
-		t.Errorf("subtype/param = %s/%q, want %s/%q", ve.Subtype, ve.Param, errs.SubtypeInvalidArgument, "--param")
-	}
-	if ve.Hint == "" {
-		t.Error("missing whiteboard_id should carry a hint")
-	}
-}
-
-// TestWhiteboardSubscriptionPreConsume_NilRuntime verifies that PreConsume
-// returns an error when the runtime APIClient dependency is missing.
-func TestWhiteboardSubscriptionPreConsume_NilRuntime(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
-	_, err := pc(context.Background(), nil, map[string]string{"whiteboard_id": "wb1"})
-	if err == nil {
-		t.Fatalf("expected error when runtime client is nil")
-	}
-	if p, ok := errs.ProblemOf(err); !ok || p.Category != errs.CategoryInternal {
-		t.Errorf("nil-runtime invariant should be a typed internal error, got %T: %v", err, err)
-	}
-}
-
-// TestWhiteboardSubscriptionPreConsume_SubscribeError verifies that a
-// failed subscribe call surfaces the error and skips registering a cleanup,
-// so no spurious unsubscribe is invoked.
-func TestWhiteboardSubscriptionPreConsume_SubscribeError(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
-	rt := &fakeAPIClient{errOnPath: "/subscribe"}
-	cleanup, err := pc(context.Background(), rt, map[string]string{"whiteboard_id": "wb1"})
-	if err == nil {
-		t.Fatalf("expected error from subscribe call")
-	}
-	if cleanup != nil {
-		t.Fatalf("expected nil cleanup when subscribe fails")
-	}
-	// only the failed subscribe call should have been made; no unsubscribe.
-	if len(rt.calls) != 1 {
-		t.Fatalf("expected exactly 1 call (subscribe), got %d", len(rt.calls))
-	}
-}
-
-// TestWhiteboardSubscriptionPreConsume_SubscribeAndCleanup verifies the full
-// happy-path: subscribe is called once with the correct method/path/body,
-// and the returned cleanup invokes the matching unsubscribe.
-func TestWhiteboardSubscriptionPreConsume_SubscribeAndCleanup(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
-	rt := &fakeAPIClient{}
-	cleanup, err := pc(context.Background(), rt, map[string]string{"whiteboard_id": "wb1"})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if cleanup == nil {
-		t.Fatalf("expected non-nil cleanup")
-	}
-
-	if len(rt.calls) != 1 {
-		t.Fatalf("expected 1 call after subscribe, got %d", len(rt.calls))
-	}
-	got := rt.calls[0]
-	if got.method != "POST" {
-		t.Errorf("subscribe method: got %q, want POST", got.method)
-	}
-	wantSubPath := "/open-apis/board/v1/whiteboards/wb1/subscribe"
-	if got.path != wantSubPath {
-		t.Errorf("subscribe path: got %q, want %q", got.path, wantSubPath)
-	}
-	body, _ := got.body.(map[string]string)
-	if body["event_type"] != eventTypeWhiteboardUpdated {
-		t.Errorf("subscribe body event_type: got %q, want %q", body["event_type"], eventTypeWhiteboardUpdated)
-	}
-
-	cleanup()
-	if len(rt.calls) != 2 {
-		t.Fatalf("expected 2 calls after cleanup, got %d", len(rt.calls))
-	}
-	got2 := rt.calls[1]
-	if got2.method != "POST" {
-		t.Errorf("unsubscribe method: got %q, want POST", got2.method)
-	}
-	wantUnsubPath := "/open-apis/board/v1/whiteboards/wb1/unsubscribe"
-	if got2.path != wantUnsubPath {
-		t.Errorf("unsubscribe path: got %q, want %q", got2.path, wantUnsubPath)
-	}
-	body2, _ := got2.body.(map[string]string)
-	if body2["event_type"] != eventTypeWhiteboardUpdated {
-		t.Errorf("unsubscribe body event_type: got %q, want %q", body2["event_type"], eventTypeWhiteboardUpdated)
-	}
-}
-
-// TestWhiteboardSubscriptionPreConsume_PathSegmentEncoded verifies that
-// whiteboard_id values containing reserved URL characters are properly
-// path-segment encoded so they cannot escape into adjacent path segments.
-func TestWhiteboardSubscriptionPreConsume_PathSegmentEncoded(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	pc := whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated)
-	rt := &fakeAPIClient{}
-	// 含特殊字符的 whiteboard_id 应被 path-segment 编码，避免越界到其他 path 段。
-	_, err := pc(context.Background(), rt, map[string]string{"whiteboard_id": "wb/1?evil"})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if len(rt.calls) != 1 {
-		t.Fatalf("expected 1 call, got %d", len(rt.calls))
-	}
-	if strings.Contains(rt.calls[0].path, "wb/1?evil") {
-		t.Errorf("whiteboard_id was not encoded; path: %s", rt.calls[0].path)
-	}
-}
-
-// TestWhiteboardUpdatedV1HasPreConsume ensures the registered EventKey for
-// board.whiteboard.updated_v1 wires the PreConsume hook and declares the
-// required whiteboard_id parameter.
-func TestWhiteboardUpdatedV1HasPreConsume(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	keys := Keys()
-	for _, k := range keys {
-		if k.Key == eventTypeWhiteboardUpdated {
-			if k.PreConsume == nil {
-				t.Fatalf("EventKey %s should have PreConsume hook", eventTypeWhiteboardUpdated)
-			}
-			if len(k.Params) == 0 {
-				t.Fatalf("EventKey %s should declare whiteboard_id param", eventTypeWhiteboardUpdated)
-			}
-			var found bool
-			for _, p := range k.Params {
-				if p.Name == "whiteboard_id" && p.Required {
-					found = true
-				}
-			}
-			if !found {
-				t.Fatalf("EventKey %s must declare required whiteboard_id param", eventTypeWhiteboardUpdated)
-			}
-			return
-		}
-	}
-	t.Fatalf("EventKey %s not registered", eventTypeWhiteboardUpdated)
-}
-
-// 确保 event.APIClient 接口与本测试 mock 一致。
-var _ event.APIClient = (*fakeAPIClient)(nil)

events/whiteboard/register.go

@@ -1,48 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package whiteboard registers Board-domain EventKeys.
-package whiteboard
-
-import (
-	"reflect"
-
-	"github.com/larksuite/cli/internal/event"
-	"github.com/larksuite/cli/internal/event/schemas"
-)
-
-// eventTypeWhiteboardUpdated is the OAPI event type for whiteboard content updates.
-const eventTypeWhiteboardUpdated = "board.whiteboard.updated_v1"
-
-// Keys returns all Board-domain EventKey definitions.
-func Keys() []event.KeyDefinition {
-	return []event.KeyDefinition{
-		{
-			Key:         eventTypeWhiteboardUpdated,
-			DisplayName: "Whiteboard updated",
-			Description: "Pushed when the whiteboard content is updated.",
-			EventType:   eventTypeWhiteboardUpdated,
-			Params: []event.ParamDef{
-				{
-					Name:        "whiteboard_id",
-					Type:        event.ParamString,
-					Required:    true,
-					Description: "Whiteboard id to subscribe; subscription is per-whiteboard.",
-				},
-			},
-			Schema: event.SchemaDef{
-				Native: &event.SchemaSpec{Type: reflect.TypeOf(BoardWhiteboardUpdatedV1Data{})},
-				FieldOverrides: map[string]schemas.FieldMeta{
-					"/event/whiteboard_id":           {Kind: "whiteboard_id", Description: "whiteboard id to subscribe"},
-					"/event/operator_ids/*/open_id":  {Kind: "open_id"},
-					"/event/operator_ids/*/union_id": {Kind: "union_id"},
-					"/event/operator_ids/*/user_id":  {Kind: "user_id"},
-				},
-			},
-			PreConsume:            whiteboardSubscriptionPreConsume(eventTypeWhiteboardUpdated),
-			Scopes:                []string{"board:whiteboard:node:read"},
-			AuthTypes:             []string{"user", "bot"},
-			RequiredConsoleEvents: []string{eventTypeWhiteboardUpdated},
-		},
-	}
-}

internal/cmdutil/factory.go

@@ -6,7 +6,6 @@ package cmdutil
 import (
 	"context"
 	"io"
-	"io/fs"
 	"net/http"
 	"strings"
 
@@ -44,8 +43,6 @@ type Factory struct {
 	Credential *credential.CredentialProvider
 
 	FileIOProvider fileio.Provider // file transfer provider (default: local filesystem)
-
-	SkillContent fs.FS // embedded skill tree (rooted at the skill list); nil when the build embeds no skills
 }
 
 // ResolveFileIO resolves a FileIO instance using the current execution context.

internal/errclass/classify.go

@@ -92,18 +92,6 @@ func BuildAPIError(resp map[string]any, cc ClassifyContext) error {
 			base.Troubleshooter = ts
 		}
 	}
-	// Upstream-provided field-level reasons (resp.error.details[].value). Lark
-	// returns these as free-text reason strings with no machine-readable field
-	// name (verified for code 190014:
-	// {"error":{"details":[{"value":"end_time should be later than start_time"}]}}),
-	// so they are lifted into Problem.Hint — the sanctioned free-text recovery
-	// prompt — rather than fabricated structured params. Lifted before the
-	// category switch so any classified arm inherits it; the CategoryAPI arm
-	// below prefers this server detail over the context-free APIHint default.
-	detailHint := liftErrorDetailValues(resp)
-	if detailHint != "" {
-		base.Hint = detailHint
-	}
 
 	switch meta.Category {
 	case errs.CategoryAuthorization:
@@ -141,11 +129,7 @@ func BuildAPIError(resp map[string]any, cc ClassifyContext) error {
 			Action:  action,
 		}
 	case errs.CategoryAPI:
-		// A server-supplied detail (lifted into base.Hint above) wins over the
-		// context-free APIHint default; only fall back to APIHint when absent.
-		if base.Hint == "" {
-			base.Hint = APIHint(base.Subtype) // "" for subtypes without a context-free default
-		}
+		base.Hint = APIHint(base.Subtype) // "" for subtypes without a context-free default
 		return &errs.APIError{Problem: base}
 	default:
 		// Fail closed: an unrecognized Category routes to InternalError
@@ -230,10 +214,6 @@ func stringFromAny(v any) string {
 // per-subtype recovery hint before returning it, so the wire envelope
 // emitted via BuildAPIError always carries a hint for known config subtypes.
 func buildConfigError(p errs.Problem) *errs.ConfigError {
-	// Config categories have authoritative recovery guidance, so the curated
-	// ConfigHint deliberately overrides any server detail lifted into p.Hint
-	// (the opposite precedence from the CategoryAPI arm, where the lifted
-	// detail wins).
 	p.Hint = ConfigHint(p.Subtype)
 	return &errs.ConfigError{Problem: p}
 }
@@ -264,8 +244,6 @@ func APIHint(subtype errs.Subtype) string {
 		return "operate on source and target within the same tenant and region/unit"
 	case errs.SubtypeCrossBrand:
 		return "operate on source and target within the same brand environment"
-	case errs.SubtypeQuotaExceeded:
-		return "reduce the request volume or free quota, then retry after the relevant quota resets"
 	}
 	return ""
 }
@@ -278,10 +256,6 @@ func buildPermissionError(p errs.Problem, resp map[string]any, cc ClassifyContex
 	}
 	consoleURL := ConsoleURL(cc.Brand, cc.AppID, missing)
 	p.Message = CanonicalPermissionMessage(p.Subtype, cc.AppID, missing, p.Message)
-	// Permission categories have authoritative recovery guidance (scopes to
-	// grant, console URL), so the curated PermissionHint deliberately overrides
-	// any server detail lifted into p.Hint (the opposite precedence from the
-	// CategoryAPI arm, where the lifted detail wins).
 	p.Hint = PermissionHint(missing, identity, p.Subtype, consoleURL)
 	permErr := &errs.PermissionError{
 		Problem:       p,
@@ -390,32 +364,6 @@ func PermissionHint(missing []string, identity string, subtype errs.Subtype, con
 	return "check the calling identity has the required scope"
 }
 
-// liftErrorDetailValues collects the non-empty resp.error.details[].value reason
-// strings and joins them with "; ". Returns "" when the structure is absent or
-// carries no non-empty value. The shape (verified for code 190014) is
-// {"error":{"details":[{"value":"<reason>"}]}}.
-func liftErrorDetailValues(resp map[string]any) string {
-	errBlock, ok := resp["error"].(map[string]any)
-	if !ok {
-		return ""
-	}
-	details, ok := errBlock["details"].([]any)
-	if !ok || len(details) == 0 {
-		return ""
-	}
-	var values []string
-	for _, d := range details {
-		m, ok := d.(map[string]any)
-		if !ok {
-			continue
-		}
-		if v, _ := m["value"].(string); v != "" {
-			values = append(values, v)
-		}
-	}
-	return strings.Join(values, "; ")
-}
-
 // extractMissingScopes walks resp["error"]["permission_violations"][].subject.
 // Returns nil when the structure is absent.
 func extractMissingScopes(resp map[string]any) []string {

internal/errclass/classify_test.go

@@ -220,111 +220,6 @@ func TestBuildAPIError_TroubleshooterLiftedOnPermissionArm(t *testing.T) {
 	}
 }
 
-// TestBuildAPIError_DetailsLiftedToHintOnAPIArm pins that BuildAPIError lifts
-// resp.error.details[].value into Problem.Hint when the response routes to the
-// catch-all CategoryAPI arm. The real Lark shape (verified for code 190014) is
-// {"error":{"details":[{"value":"end_time should be later than start_time"}]}}
-// — only a human-readable reason string, no machine-readable field name. It is
-// lifted into Hint (sanctioned free-text recovery prompt) rather than fabricated
-// structured params.
-func TestBuildAPIError_DetailsLiftedToHintOnAPIArm(t *testing.T) {
-	resp := map[string]any{
-		"code": 190014,
-		"msg":  "invalid params",
-		"error": map[string]any{
-			"details": []any{
-				map[string]any{"value": "end_time should be later than start_time"},
-			},
-		},
-	}
-	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatal("ProblemOf returned !ok")
-	}
-	if !strings.Contains(p.Hint, "end_time should be later than start_time") {
-		t.Errorf("Hint = %q, want it to contain the server detail value", p.Hint)
-	}
-}
-
-// TestBuildAPIError_MultipleDetailsJoinedIntoHint pins that multiple non-empty
-// detail values are joined with "; " into a single Hint, and empty values are
-// skipped.
-func TestBuildAPIError_MultipleDetailsJoinedIntoHint(t *testing.T) {
-	resp := map[string]any{
-		"code": 190014,
-		"msg":  "invalid params",
-		"error": map[string]any{
-			"details": []any{
-				map[string]any{"value": "first reason"},
-				map[string]any{"value": ""},
-				map[string]any{"value": "second reason"},
-			},
-		},
-	}
-	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatal("ProblemOf returned !ok")
-	}
-	if p.Hint != "first reason; second reason" {
-		t.Errorf("Hint = %q, want %q", p.Hint, "first reason; second reason")
-	}
-}
-
-// TestBuildAPIError_DetailsSkipsNonMapEntries pins that malformed entries in
-// the details array (not a JSON object) are skipped rather than panicking, and
-// well-formed siblings still surface in the Hint.
-func TestBuildAPIError_DetailsSkipsNonMapEntries(t *testing.T) {
-	resp := map[string]any{
-		"code": 190014,
-		"msg":  "invalid params",
-		"error": map[string]any{
-			"details": []any{
-				"i am a bare string, not an object",
-				map[string]any{"value": "the real reason"},
-				42,
-			},
-		},
-	}
-	err := errclass.BuildAPIError(resp, errclass.ClassifyContext{})
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatal("ProblemOf returned !ok")
-	}
-	if p.Hint != "the real reason" {
-		t.Errorf("Hint = %q, want %q", p.Hint, "the real reason")
-	}
-}
-
-// TestBuildAPIError_DetailsMalformedShapesNoHint pins that a missing error
-// block, a non-array details field, and an empty details array all leave the
-// Hint untouched (no lifted detail) instead of erroring.
-func TestBuildAPIError_DetailsMalformedShapesNoHint(t *testing.T) {
-	cases := []struct {
-		name string
-		resp map[string]any
-	}{
-		{"no error block", map[string]any{"code": 190014, "msg": "invalid params"}},
-		{"details not array", map[string]any{"code": 190014, "msg": "invalid params", "error": map[string]any{"details": "nope"}}},
-		{"empty details", map[string]any{"code": 190014, "msg": "invalid params", "error": map[string]any{"details": []any{}}}},
-		{"detail values all empty", map[string]any{"code": 190014, "msg": "invalid params", "error": map[string]any{"details": []any{map[string]any{"value": ""}}}}},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			err := errclass.BuildAPIError(tc.resp, errclass.ClassifyContext{})
-			p, ok := errs.ProblemOf(err)
-			if !ok {
-				t.Fatal("ProblemOf returned !ok")
-			}
-			// With no liftable detail, the Hint must not echo a server detail.
-			if strings.Contains(p.Hint, "nope") {
-				t.Errorf("Hint should not lift a non-array details field, got %q", p.Hint)
-			}
-		})
-	}
-}
-
 // TestBuildAPIError_TroubleshooterAbsent pins that Troubleshooter stays empty
 // when the upstream response omits it — wire envelope must omit the field.
 func TestBuildAPIError_TroubleshooterAbsent(t *testing.T) {

internal/errclass/codemeta_calendar.go

@@ -1,16 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import "github.com/larksuite/cli/errs"
-
-// calendarCodeMeta holds calendar-service Lark code → CodeMeta mappings.
-// Only codes whose meaning is verifiable from repo evidence are registered;
-// ambiguous codes fall back to CategoryAPI via BuildAPIError.
-// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
-var calendarCodeMeta = map[int]CodeMeta{
-	190014: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // invalid params (carries a field-level detail lifted into Hint)
-}
-
-func init() { mergeCodeMeta(calendarCodeMeta, "calendar") }

internal/errclass/codemeta_calendar_test.go

@@ -1,39 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import (
-	"fmt"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// TestLookupCodeMeta_CalendarCodes pins each calendar-service code registered
-// via the codemeta_calendar.go init() merge to its expected
-// Category/Subtype/Retryable.
-func TestLookupCodeMeta_CalendarCodes(t *testing.T) {
-	cases := []struct {
-		code        int
-		wantCat     errs.Category
-		wantSubtype errs.Subtype
-		wantRetry   bool
-	}{
-		// 190014: calendar "invalid params" with a field-level detail
-		// (error.details[].value) lifted into Hint by BuildAPIError.
-		{190014, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
-	}
-	for _, tc := range cases {
-		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {
-			meta, ok := LookupCodeMeta(tc.code)
-			if !ok {
-				t.Fatalf("code %d not registered in codeMeta", tc.code)
-			}
-			if meta.Category != tc.wantCat || meta.Subtype != tc.wantSubtype || meta.Retryable != tc.wantRetry {
-				t.Errorf("code %d: got %+v, want Category=%v Subtype=%v Retryable=%v",
-					tc.code, meta, tc.wantCat, tc.wantSubtype, tc.wantRetry)
-			}
-		})
-	}
-}

internal/errclass/codemeta_mail.go

@@ -1,20 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import "github.com/larksuite/cli/errs"
-
-// mailCodeMeta holds mail-service Lark code -> CodeMeta mappings.
-// Only codes whose meaning is verifiable from repo evidence are registered;
-// ambiguous codes fall back to CategoryAPI via BuildAPIError.
-var mailCodeMeta = map[int]CodeMeta{
-	1234013: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},      // mailbox not found or not active
-	1236007: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // user daily send count exceeded
-	1236008: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // user daily external recipient count exceeded
-	1236009: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // tenant daily external recipient count exceeded
-	1236010: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // mail quota limit
-	1236013: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded}, // tenant storage limit exceeded
-}
-
-func init() { mergeCodeMeta(mailCodeMeta, "mail") }

internal/errclass/codemeta_minutes.go

@@ -1,18 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import "github.com/larksuite/cli/errs"
-
-// minutesCodeMeta holds minutes-service Lark code → CodeMeta mappings.
-// Only codes whose meaning is stable across minutes endpoints are registered;
-// endpoint-specific codes fall back to CategoryAPI via BuildAPIError.
-// Command-specific messages, hints, and subtypes are layered on top via
-// per-command enrichment.
-// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
-var minutesCodeMeta = map[int]CodeMeta{
-	2091005: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // caller lacks edit/read permission for the minute
-}
-
-func init() { mergeCodeMeta(minutesCodeMeta, "minutes") }

internal/errclass/codemeta_test.go

@@ -70,12 +70,6 @@ func TestLookupCodeMeta_TaskPermissionDenied_MergedViaInit(t *testing.T) {
 	}
 }
 
-func TestLookupCodeMeta_MinutesEndpointSpecificCode_NotGlobal(t *testing.T) {
-	if got, ok := LookupCodeMeta(2091001); ok {
-		t.Fatalf("LookupCodeMeta(2091001) = %+v, want unregistered; minutes endpoints use this code for different failures", got)
-	}
-}
-
 func TestLookupCodeMeta_RetryableAuthCode(t *testing.T) {
 	got, ok := LookupCodeMeta(20050)
 	if !ok {

internal/errclass/codemeta_vc.go

@@ -1,19 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import "github.com/larksuite/cli/errs"
-
-// vcCodeMeta holds vc-service Lark code → CodeMeta mappings.
-// Only codes whose meaning is verifiable from repo evidence are registered;
-// ambiguous codes (e.g. 124002 "recording still generating", which has no
-// precise taxonomy fit) fall back to CategoryAPI via BuildAPIError and rely on
-// per-command enrichment for a retry hint.
-// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
-var vcCodeMeta = map[int]CodeMeta{
-	121004: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                   // meeting has no minute file
-	121005: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // caller is not a participant / lacks view permission
-}
-
-func init() { mergeCodeMeta(vcCodeMeta, "vc") }

internal/event/bus/bus.go

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

internal/event/bus/bus_shutdown_test.go

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

internal/event/bus/conn.go

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

internal/event/bus/conn_test.go

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

internal/event/bus/handle_hello_test.go

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

internal/event/bus/hub.go

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

internal/event/bus/hub_observability_test.go

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

internal/event/bus/hub_publish_race_test.go

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

internal/event/bus/hub_test.go

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

internal/event/consume/consume.go

@@ -14,7 +14,6 @@ import (
 	"sync/atomic"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/event"
 	"github.com/larksuite/cli/internal/event/transport"
 )
@@ -45,9 +44,7 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 
 	keyDef, ok := event.Lookup(opts.EventKey)
 	if !ok {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"unknown EventKey: %s", opts.EventKey).
-			WithHint("run `lark-cli event list` to see available keys")
+		return fmt.Errorf("unknown EventKey: %s\nRun 'lark-cli event list' to see available keys", opts.EventKey)
 	}
 
 	if err := validateParams(keyDef, opts.Params); err != nil {
@@ -61,22 +58,6 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 		}
 	}
 
-	// Normalize params (resolve aliases like "me" -> real email) before fingerprint
-	// compute, PreConsume, Match, Process. Must happen BEFORE doHello so the
-	// SubscriptionID we send to bus reflects canonical values.
-	if keyDef.NormalizeParams != nil {
-		if err := keyDef.NormalizeParams(ctx, opts.Runtime, opts.Params); err != nil {
-			if _, ok := errs.ProblemOf(err); ok {
-				return err
-			}
-			return errs.NewInternalError(errs.SubtypeUnknown,
-				"normalize params for %s: %s", opts.EventKey, err).WithCause(err)
-		}
-	}
-
-	// Compute subscription identity from normalized params + SubscriptionKey flags.
-	subscriptionID := ComputeSubscriptionID(keyDef, opts.Params)
-
 	if opts.Timeout > 0 {
 		var cancel context.CancelFunc
 		ctx, cancel = context.WithTimeout(ctx, opts.Timeout)
@@ -97,24 +78,19 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 	}
 	defer conn.Close()
 
-	ack, br, err := doHello(conn, opts.EventKey, []string{keyDef.EventType}, subscriptionID)
+	ack, br, err := doHello(conn, opts.EventKey, []string{keyDef.EventType})
 	if err != nil {
-		return errs.NewInternalError(errs.SubtypeUnknown,
-			"event bus handshake failed: %s", err).WithCause(err)
+		return fmt.Errorf("handshake failed: %w", err)
 	}
 
-	var cleanup func() error
+	var cleanup func()
 	if ack.FirstForKey && keyDef.PreConsume != nil {
 		if !opts.Quiet {
 			fmt.Fprintf(errOut, "[event] running pre-consume setup...\n")
 		}
 		cleanup, err = keyDef.PreConsume(ctx, opts.Runtime, opts.Params)
 		if err != nil {
-			if _, ok := errs.ProblemOf(err); ok {
-				return err
-			}
-			return errs.NewInternalError(errs.SubtypeUnknown,
-				"pre-consume failed: %s", err).WithCause(err)
+			return fmt.Errorf("pre-consume failed: %w", err)
 		}
 	}
 
@@ -129,22 +105,14 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 		if cleanup != nil {
 			switch {
 			case r != nil:
-				fmt.Fprintf(errOut,
-					"WARN: panic recovered; running cleanup unconditionally (may affect other consumers of %s)\n",
-					opts.EventKey)
-				if cleanupErr := cleanup(); cleanupErr != nil {
-					fmt.Fprintf(errOut,
-						"WARN: cleanup also failed during panic recovery: %v\n", cleanupErr)
-				}
+				fmt.Fprintf(errOut, "WARN: panic recovered; running cleanup unconditionally (may affect other consumers of %s)\n", opts.EventKey)
+				cleanup()
 			case lastForKey:
 				if !opts.Quiet {
 					fmt.Fprintf(errOut, "[event] running cleanup...\n")
 				}
-				if cleanupErr := cleanup(); cleanupErr != nil {
-					fmt.Fprintf(errOut,
-						"WARN: cleanup failed: %v (server-side subscribe is idempotent — residual record will be overwritten on next subscribe)\n",
-						cleanupErr)
-				} else if !opts.Quiet {
+				cleanup()
+				if !opts.Quiet {
 					fmt.Fprintf(errOut, "[event] cleanup done.\n")
 				}
 			}
@@ -162,13 +130,13 @@ func Run(ctx context.Context, tr transport.IPC, appID, profileName, domain strin
 	if !opts.Quiet {
 		fmt.Fprintln(errOut, listeningText(opts))
 		if !opts.IsTTY {
-			fmt.Fprintln(errOut, stopHintText(opts))
+			fmt.Fprintln(errOut, stopHintText())
 		}
 	}
 
 	writeReadyMarker(errOut, opts)
 
-	return consumeLoop(ctx, conn, br, keyDef, opts, subscriptionID, &lastForKey, &emitted)
+	return consumeLoop(ctx, conn, br, keyDef, opts, &lastForKey, &emitted)
 }
 
 func truncateDuration(d time.Duration) time.Duration {
@@ -184,10 +152,8 @@ func validateParams(def *event.KeyDefinition, params map[string]string) error {
 	for _, p := range def.Params {
 		if p.Required {
 			if _, ok := params[p.Name]; !ok {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"required param %q missing for EventKey %s", p.Name, def.Key).
-					WithParam("--param").
-					WithHint("pass it as --param %s=<value>; run `lark-cli event schema %s` for details", p.Name, def.Key)
+				return fmt.Errorf("required param %q missing for EventKey %s. Run 'lark-cli event schema %s' for details",
+					p.Name, def.Key, def.Key)
 			}
 		}
 	}
@@ -203,15 +169,11 @@ func validateParams(def *event.KeyDefinition, params map[string]string) error {
 			continue
 		}
 		if len(validNames) == 0 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"unknown param %q: EventKey %s accepts no params", k, def.Key).
-				WithParam("--param").
-				WithHint("run `lark-cli event schema %s` for details", def.Key)
+			return fmt.Errorf("unknown param %q: EventKey %s accepts no params. Run 'lark-cli event schema %s' for details",
+				k, def.Key, def.Key)
 		}
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"unknown param %q for EventKey %s. valid params: %s", k, def.Key, strings.Join(validNames, ", ")).
-			WithParam("--param").
-			WithHint("run `lark-cli event schema %s` for details", def.Key)
+		return fmt.Errorf("unknown param %q for EventKey %s. valid params: %s. Run 'lark-cli event schema %s' for details",
+			k, def.Key, strings.Join(validNames, ", "), def.Key)
 	}
 	return nil
 }
@@ -251,11 +213,7 @@ func exitReason(ctx context.Context, emitted int64, opts Options) string {
 	return "signal"
 }
 
-func stopHintText(opts Options) string {
-	if opts.MaxEvents > 0 || opts.Timeout > 0 {
-		return "[event] to stop gracefully: send SIGTERM (kill <pid>). " +
-			"Avoid kill -9 — it skips cleanup and may leak server-side subscriptions."
-	}
+func stopHintText() string {
 	return "[event] to stop gracefully: send SIGTERM (kill <pid>) or close stdin. " +
 		"Avoid kill -9 — it skips cleanup and may leak server-side subscriptions."
 }

internal/event/consume/consume_test.go

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

internal/event/consume/fingerprint.go

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

internal/event/consume/fingerprint_test.go

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

internal/event/consume/handshake.go

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

internal/event/consume/handshake_test.go

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

internal/event/consume/jq.go

@@ -8,21 +8,17 @@ import (
 	"fmt"
 
 	"github.com/itchyny/gojq"
-
-	"github.com/larksuite/cli/errs"
 )
 
 // CompileJQ compiles once for hot-path reuse; exported so callers can preflight before side effects.
 func CompileJQ(expr string) (*gojq.Code, error) {
 	query, err := gojq.Parse(expr)
 	if err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"invalid jq expression: %s", err).WithParam("--jq").WithCause(err)
+		return nil, fmt.Errorf("invalid jq expression: %w", err)
 	}
 	code, err := gojq.Compile(query)
 	if err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"jq compile error: %s", err).WithParam("--jq").WithCause(err)
+		return nil, fmt.Errorf("jq compile error: %w", err)
 	}
 	return code, nil
 }

internal/event/consume/listening_text_test.go

@@ -50,32 +50,12 @@ func TestListeningText_NonTTY_MaxEventsAndTimeout(t *testing.T) {
 }
 
 // AI-facing contract: must name "kill -9" + "cleanup" so agents parsing stderr are steered away from SIGKILL.
-func TestStopHintText_Unbounded(t *testing.T) {
-	got := stopHintText(Options{})
-	mustContain := []string{"SIGTERM", "kill -9", "cleanup", "close stdin"}
+func TestStopHintText_Content(t *testing.T) {
+	got := stopHintText()
+	mustContain := []string{"SIGTERM", "kill -9", "cleanup"}
 	for _, s := range mustContain {
 		if !bytes.Contains([]byte(got), []byte(s)) {
-			t.Errorf("stopHintText(unbounded) missing %q; got %q", s, got)
-		}
-	}
-}
-
-// AI-facing contract: must name "kill -9" + "cleanup" so agents parsing stderr are steered away from SIGKILL.
-func TestStopHintText_Bounded(t *testing.T) {
-	cases := []Options{
-		{MaxEvents: 1},
-		{Timeout: 30 * time.Second},
-	}
-	for _, opts := range cases {
-		got := stopHintText(opts)
-		mustContain := []string{"SIGTERM", "kill -9", "cleanup"}
-		for _, s := range mustContain {
-			if !bytes.Contains([]byte(got), []byte(s)) {
-				t.Errorf("stopHintText(bounded) missing %q; got %q", s, got)
-			}
-		}
-		if bytes.Contains([]byte(got), []byte("close stdin")) {
-			t.Errorf("stopHintText(bounded) must not contain \"close stdin\"; got %q", got)
+			t.Errorf("stopHintText missing %q; got %q", s, got)
 		}
 	}
 }

internal/event/consume/loop.go

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

internal/event/consume/loop_jq_test.go

@@ -5,13 +5,10 @@ package consume
 
 import (
 	"encoding/json"
-	"errors"
 	"fmt"
 	"strings"
 	"sync"
 	"testing"
-
-	"github.com/larksuite/cli/errs"
 )
 
 func TestCompileJQReportsErrorEarly(t *testing.T) {
@@ -23,16 +20,6 @@ func TestCompileJQReportsErrorEarly(t *testing.T) {
 	if !strings.Contains(msg, "compile") && !strings.Contains(msg, "parse") && !strings.Contains(msg, "invalid") {
 		t.Errorf("error should mention compile/parse/invalid, got: %v", err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument || ve.Param != "--jq" {
-		t.Errorf("subtype/param = %s/%q, want %s/%q", ve.Subtype, ve.Param, errs.SubtypeInvalidArgument, "--jq")
-	}
-	if errors.Unwrap(err) == nil {
-		t.Error("compile error should preserve its cause")
-	}
 }
 
 func TestCompileJQReturnsUsableCode(t *testing.T) {

internal/event/consume/loop_test.go

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

internal/event/consume/shutdown.go

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

internal/event/consume/shutdown_test.go

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

internal/event/consume/sink.go

@@ -13,7 +13,6 @@ import (
 	"sync/atomic"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -24,8 +23,7 @@ type Sink interface {
 func newSink(opts Options) (Sink, error) {
 	if opts.OutputDir != "" {
 		if err := vfs.MkdirAll(opts.OutputDir, 0755); err != nil {
-			return nil, errs.NewInternalError(errs.SubtypeFileIO,
-				"create output dir: %s", err).WithCause(err)
+			return nil, fmt.Errorf("create output dir: %w", err)
 		}
 		// PID disambiguates filenames across processes sharing a Dir.
 		return &DirSink{Dir: opts.OutputDir, pid: os.Getpid()}, nil

internal/event/consume/startup.go

@@ -16,7 +16,6 @@ import (
 	"path/filepath"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/event"
 	"github.com/larksuite/cli/internal/event/protocol"
@@ -52,9 +51,10 @@ func EnsureBus(ctx context.Context, tr transport.IPC, appID, profileName, domain
 		} else {
 			fmt.Fprintf(errOut, "[event] remote connection check: online_instance_cnt=%d\n", count)
 			if count > 0 {
-				return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition,
-					"another event bus is already connected to this app (%d active connection(s) detected via API); only one bus should run globally to avoid duplicate event delivery", count).
-					WithHint("use `lark-cli event status` to check, or `lark-cli event stop` on the other machine first")
+				return nil, fmt.Errorf("another event bus is already connected to this app "+
+					"(%d active connection(s) detected via API).\n"+
+					"Only one bus should run globally to avoid duplicate event delivery.\n"+
+					"Use 'lark-cli event status' to check, or 'lark-cli event stop' on the other machine first", count)
 			}
 		}
 	} else {
@@ -65,10 +65,8 @@ func EnsureBus(ctx context.Context, tr transport.IPC, appID, profileName, domain
 	pid, forkErr := forkBus(tr, appID, profileName, domain)
 	if forkErr != nil && !errors.Is(forkErr, lockfile.ErrHeld) {
 		eventsRoot := filepath.Join(core.GetConfigDir(), "events")
-		return nil, errs.NewInternalError(errs.SubtypeUnknown,
-			"failed to start event bus daemon: %s", forkErr).
-			WithCause(forkErr).
-			WithHint("check disk space, permissions on %s, and `lark-cli doctor`", eventsRoot)
+		return nil, fmt.Errorf("failed to start event bus daemon: %w\n"+
+			"Check: disk space, permissions on %s, and 'lark-cli doctor'", forkErr, eventsRoot)
 	}
 	if pid > 0 {
 		announceForkedBus(errOut, pid)
@@ -90,9 +88,7 @@ func EnsureBus(ctx context.Context, tr transport.IPC, appID, profileName, domain
 	fmt.Fprintln(errOut, "[event] event bus exited unexpectedly.")
 	fmt.Fprintln(errOut, "[event] please check app credentials (lark-cli config show) and retry.")
 	fmt.Fprintf(errOut, "[event] logs: %s\n", logPath)
-	return nil, errs.NewInternalError(errs.SubtypeUnknown,
-		"failed to connect to event bus within %v (app=%s)", dialTimeout, appID).
-		WithHint("check app credentials (`lark-cli config show`) and retry; bus logs: %s", logPath)
+	return nil, fmt.Errorf("failed to connect to event bus within %v (app=%s)", dialTimeout, appID)
 }
 
 // probeAndDialBus distinguishes a healthy bus from a mid-shutdown listener via StatusQuery first.

internal/event/consume/startup_guard_test.go

@@ -1,99 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package consume
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"io"
-	"net"
-	"strconv"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/event"
-)
-
-// failDialTransport refuses every dial so EnsureBus falls through to the
-// remote-connection check without a local bus.
-type failDialTransport struct{}
-
-func (failDialTransport) Listen(string) (net.Listener, error) { return nil, errors.New("no listen") }
-func (failDialTransport) Dial(string) (net.Conn, error)       { return nil, errors.New("refused") }
-func (failDialTransport) Address(string) string               { return "guard-test-addr" }
-func (failDialTransport) Cleanup(string)                      {}
-
-// remoteBusyAPIClient reports active remote WebSocket connections.
-type remoteBusyAPIClient struct{ count int }
-
-func (c remoteBusyAPIClient) CallAPI(context.Context, string, string, interface{}) (json.RawMessage, error) {
-	return json.RawMessage(`{"code":0,"msg":"ok","data":{"online_instance_cnt":` +
-		strconv.Itoa(c.count) + `}}`), nil
-}
-
-func TestEnsureBus_RemoteBusAlreadyConnectedIsFailedPrecondition(t *testing.T) {
-	conn, err := EnsureBus(context.Background(), failDialTransport{},
-		"cli_guard_test", "", "", remoteBusyAPIClient{count: 2}, io.Discard)
-	if conn != nil {
-		t.Fatal("expected nil conn when a remote bus is already connected")
-	}
-	if err == nil {
-		t.Fatal("expected single-bus guard error")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("subtype = %s, want %s", ve.Subtype, errs.SubtypeFailedPrecondition)
-	}
-	if !strings.Contains(ve.Hint, "event stop") {
-		t.Errorf("hint should point at `event stop`, got: %q", ve.Hint)
-	}
-}
-
-func TestRun_UnknownEventKeyIsTypedValidation(t *testing.T) {
-	err := Run(context.Background(), failDialTransport{}, "cli_x", "", "", Options{
-		EventKey: "bogus.run.key",
-		ErrOut:   io.Discard,
-	})
-	if err == nil {
-		t.Fatal("expected unknown EventKey error")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype = %s, want %s", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if !strings.Contains(ve.Hint, "event list") {
-		t.Errorf("hint should point at `event list`, got: %q", ve.Hint)
-	}
-}
-
-func TestRun_InvalidJQFailsBeforeAnySideEffect(t *testing.T) {
-	event.RegisterKey(event.KeyDefinition{
-		Key:       "consume.runtest.jq",
-		EventType: "consume.runtest.jq_v1",
-		Schema:    event.SchemaDef{Custom: &event.SchemaSpec{Raw: json.RawMessage(`{}`)}},
-	})
-	err := Run(context.Background(), failDialTransport{}, "cli_x", "", "", Options{
-		EventKey: "consume.runtest.jq",
-		JQExpr:   "[invalid{{{",
-		ErrOut:   io.Discard,
-	})
-	if err == nil {
-		t.Fatal("expected jq validation error")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Param != "--jq" {
-		t.Errorf("param = %q, want %q", ve.Param, "--jq")
-	}
-}

internal/event/consume/validate_params_test.go

@@ -1,64 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package consume
-
-import (
-	"errors"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/event"
-)
-
-func requireParamValidationError(t *testing.T, err error) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected validation error, got nil")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument || ve.Param != "--param" {
-		t.Errorf("subtype/param = %s/%q, want %s/%q", ve.Subtype, ve.Param, errs.SubtypeInvalidArgument, "--param")
-	}
-	if ve.Hint == "" {
-		t.Error("param validation error should hint at `lark-cli event schema`")
-	}
-}
-
-func TestValidateParams_RequiredMissing(t *testing.T) {
-	def := &event.KeyDefinition{
-		Key:    "x.test",
-		Params: []event.ParamDef{{Name: "chat_id", Required: true}},
-	}
-	requireParamValidationError(t, validateParams(def, map[string]string{}))
-}
-
-func TestValidateParams_UnknownParam(t *testing.T) {
-	def := &event.KeyDefinition{
-		Key:    "x.test",
-		Params: []event.ParamDef{{Name: "chat_id"}},
-	}
-	requireParamValidationError(t, validateParams(def, map[string]string{"nope": "1"}))
-}
-
-func TestValidateParams_UnknownParamNoParamsAccepted(t *testing.T) {
-	def := &event.KeyDefinition{Key: "x.test"}
-	requireParamValidationError(t, validateParams(def, map[string]string{"nope": "1"}))
-}
-
-func TestValidateParams_DefaultAppliedAndValidPasses(t *testing.T) {
-	def := &event.KeyDefinition{
-		Key:    "x.test",
-		Params: []event.ParamDef{{Name: "mode", Required: true, Default: "all"}},
-	}
-	params := map[string]string{}
-	if err := validateParams(def, params); err != nil {
-		t.Fatalf("default should satisfy required param, got: %v", err)
-	}
-	if params["mode"] != "all" {
-		t.Errorf("default not applied, params=%v", params)
-	}
-}

internal/event/protocol/codec_test.go

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

internal/event/protocol/messages.go

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

internal/event/protocol/messages_test.go

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

internal/event/types.go

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

internal/registry/registry_test.go

@@ -231,9 +231,14 @@ func TestLoadAutoApproveSet(t *testing.T) {
 		t.Fatal("expected non-empty auto-approve set")
 	}
 
-	// From scope_priorities.json recommend=="true"
+	// From scope_overrides.json allow list
+	if !aaSet["calendar:calendar.event:create"] {
+		t.Error("expected calendar:calendar.event:create in auto-approve set (from allow list)")
+	}
+
+	// Verify allow list entries are present
 	if !aaSet["sheets:spreadsheet:read"] {
-		t.Error("expected sheets:spreadsheet:read in auto-approve set (recommend=true in priorities)")
+		t.Error("expected sheets:spreadsheet:read in auto-approve set (from allow list)")
 	}
 
 	t.Logf("Auto-approve set has %d scopes", len(aaSet))
@@ -252,10 +257,16 @@ func TestLoadPlatformAutoApproveSet(t *testing.T) {
 
 func TestLoadOverrideAutoApproveAllow(t *testing.T) {
 	allowSet := LoadOverrideAutoApproveAllow()
-	// recommend.allow in scope_overrides.json is intentionally empty:
-	// no scopes are special-cased into the auto-approve set anymore.
-	if len(allowSet) != 0 {
-		t.Errorf("expected empty override allow set, got %d entries", len(allowSet))
+	if len(allowSet) == 0 {
+		t.Fatal("expected non-empty override allow set")
+	}
+
+	// Known entries from scope_overrides.json
+	if !allowSet["calendar:calendar.event:create"] {
+		t.Error("expected calendar:calendar.event:create in allow set")
+	}
+	if !allowSet["mail:event"] {
+		t.Error("expected mail:event in allow set")
 	}
 }
 
@@ -266,9 +277,9 @@ func TestLoadOverrideAutoApproveDeny(t *testing.T) {
 }
 
 func TestIsAutoApproveScope(t *testing.T) {
-	// Known auto-approve scope (recommend=true in scope_priorities.json)
-	if !IsAutoApproveScope("sheets:spreadsheet:read") {
-		t.Error("expected sheets:spreadsheet:read to be auto-approve")
+	// Known auto-approve scope (in allow list)
+	if !IsAutoApproveScope("calendar:calendar.event:create") {
+		t.Error("expected calendar:calendar.event:create to be auto-approve")
 	}
 
 	// Completely unknown scope
@@ -279,8 +290,9 @@ func TestIsAutoApproveScope(t *testing.T) {
 
 func TestFilterAutoApproveScopes(t *testing.T) {
 	scopes := []string{
-		"sheets:spreadsheet:read", // auto-approve (recommend=true in priorities)
-		"zzz:unknown:scope",       // not in auto-approve
+		"calendar:calendar.event:create", // auto-approve (in allow list)
+		"zzz:unknown:scope",              // not in auto-approve
+		"sheets:spreadsheet:read",        // auto-approve (in allow list)
 	}
 
 	result := FilterAutoApproveScopes(scopes)
@@ -288,10 +300,10 @@ func TestFilterAutoApproveScopes(t *testing.T) {
 		t.Fatal("expected at least 1 auto-approve scope in result")
 	}
 
-	// Check that sheets:spreadsheet:read is included
+	// Check that calendar:calendar.event:create is included
 	found := false
 	for _, s := range result {
-		if s == "sheets:spreadsheet:read" {
+		if s == "calendar:calendar.event:create" {
 			found = true
 		}
 		// Ensure unknown scopes are not included
@@ -300,7 +312,7 @@ func TestFilterAutoApproveScopes(t *testing.T) {
 		}
 	}
 	if !found {
-		t.Error("expected sheets:spreadsheet:read in result")
+		t.Error("expected calendar:calendar.event:create in result")
 	}
 }
 

internal/registry/scope_overrides.json

@@ -12,7 +12,25 @@
     "vc:meeting.meetingevent:read": 75
   },
   "recommend": {
-    "allow": [],
+    "allow": [
+      "calendar:calendar.event:create",
+      "calendar:calendar.event:delete",
+      "calendar:calendar.event:read",
+      "calendar:calendar.event:update",
+      "calendar:calendar.free_busy:read",
+      "calendar:calendar:create",
+      "calendar:calendar:delete",
+      "calendar:calendar:read",
+      "calendar:calendar:update",
+      "contact:user.basic_profile:readonly",
+      "mail:event",
+      "mail:user_mailbox.mail_contact:read",
+      "mail:user_mailbox.mail_contact:write",
+      "mail:user_mailbox.message.address:read",
+      "mail:user_mailbox.message.body:read",
+      "mail:user_mailbox.message.subject:read",
+      "mail:user_mailbox.message:readonly"
+    ],
     "deny": [
       "im:chat",
       "im:message.send_as_user"

internal/selfupdate/updater.go

@@ -10,13 +10,10 @@ import (
 	"bytes"
 	"context"
 	"fmt"
-	"io"
-	"net/http"
 	"os/exec"
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -40,15 +37,9 @@ const (
 )
 
 const (
-	npmInstallTimeout      = 10 * time.Minute
-	skillsUpdateTimeout    = 2 * time.Minute
-	skillsIndexMaxBodySize = 1 << 20
-	verifyTimeout          = 10 * time.Second
-)
-
-var (
-	skillsIndexFetchTimeout = 10 * time.Second
-	officialSkillsIndexURL  = "https://open.feishu.cn/.well-known/skills/index.json"
+	npmInstallTimeout   = 10 * time.Minute
+	skillsUpdateTimeout = 2 * time.Minute
+	verifyTimeout       = 10 * time.Second
 )
 
 // DetectResult holds installation detection results.
@@ -92,7 +83,6 @@ func (r *NpmResult) CombinedOutput() string {
 type Updater struct {
 	DetectOverride           func() DetectResult
 	NpmInstallOverride       func(version string) *NpmResult
-	SkillsIndexFetchOverride func() *NpmResult
 	SkillsCommandOverride    func(args ...string) *NpmResult
 	VerifyOverride           func(expectedVersion string) error
 	RestoreAvailableOverride func() bool
@@ -163,53 +153,6 @@ func (u *Updater) RunNpmInstall(version string) *NpmResult {
 	return r
 }
 
-func (u *Updater) ListOfficialSkillsIndex() *NpmResult {
-	if u.SkillsIndexFetchOverride != nil {
-		return u.SkillsIndexFetchOverride()
-	}
-
-	r := &NpmResult{}
-	ctx, cancel := context.WithTimeout(context.Background(), skillsIndexFetchTimeout)
-	defer cancel()
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, officialSkillsIndexURL, nil)
-	if err != nil {
-		r.Err = err
-		return r
-	}
-
-	client := transport.NewHTTPClient(0)
-	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
-		if req.URL.Scheme != "https" {
-			return fmt.Errorf("official skills index redirected to non-HTTPS URL: %s", req.URL.Redacted())
-		}
-		return nil
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		r.Err = err
-		return r
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
-		r.Err = fmt.Errorf("official skills index returned HTTP %d", resp.StatusCode)
-		return r
-	}
-
-	limited := io.LimitReader(resp.Body, skillsIndexMaxBodySize+1)
-	if _, err := io.Copy(&r.Stdout, limited); err != nil {
-		r.Err = err
-		return r
-	}
-	if r.Stdout.Len() > skillsIndexMaxBodySize {
-		r.Stdout.Reset()
-		r.Err = fmt.Errorf("official skills index exceeds %d bytes", skillsIndexMaxBodySize)
-		return r
-	}
-	return r
-}
-
 func (u *Updater) ListOfficialSkills() *NpmResult {
 	r := u.runSkillsListOfficial("https://open.feishu.cn")
 	if r.Err != nil {
@@ -222,10 +165,6 @@ func (u *Updater) ListGlobalSkills() *NpmResult {
 	return u.runSkillsListGlobal()
 }
 
-func (u *Updater) ListGlobalSkillsJSON() *NpmResult {
-	return u.runSkillsCommand("-y", "skills", "ls", "-g", "--json")
-}
-
 func (u *Updater) InstallSkill(nameList []string) *NpmResult {
 	r := u.runSkillsInstall("https://open.feishu.cn", nameList)
 	if r.Err != nil {

internal/selfupdate/updater_test.go

@@ -4,18 +4,12 @@
 package selfupdate
 
 import (
-	"context"
-	"errors"
 	"fmt"
-	"net"
-	"net/http"
-	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"runtime"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -194,13 +188,6 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 			},
 			want: "-y skills ls -g",
 		},
-		{
-			name: "list global json",
-			run: func(u *Updater) *NpmResult {
-				return u.ListGlobalSkillsJSON()
-			},
-			want: "-y skills ls -g --json",
-		},
 		{
 			name: "install skill primary",
 			run: func(u *Updater) *NpmResult {
@@ -238,113 +225,6 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 	}
 }
 
-func TestListOfficialSkillsIndexSuccess(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		fmt.Fprint(w, `{"skills":[{"name":"lark-calendar"}]}`)
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	officialSkillsIndexURL = server.URL
-	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
-
-	result := New().ListOfficialSkillsIndex()
-	if result.Err != nil {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want nil", result.Err)
-	}
-	if got := result.Stdout.String(); !strings.Contains(got, "lark-calendar") {
-		t.Fatalf("ListOfficialSkillsIndex() stdout = %q, want skill JSON", got)
-	}
-}
-
-func TestListOfficialSkillsIndexHTTPError(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		http.Error(w, "not found", http.StatusNotFound)
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	officialSkillsIndexURL = server.URL
-	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
-
-	result := New().ListOfficialSkillsIndex()
-	if result.Err == nil || !strings.Contains(result.Err.Error(), "HTTP 404") {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want HTTP 404", result.Err)
-	}
-}
-
-func TestListOfficialSkillsIndexBodyTooLarge(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		fmt.Fprint(w, strings.Repeat("x", skillsIndexMaxBodySize+1))
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	officialSkillsIndexURL = server.URL
-	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
-
-	result := New().ListOfficialSkillsIndex()
-	if result.Err == nil || !strings.Contains(result.Err.Error(), "exceeds") {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want exceeds", result.Err)
-	}
-	if result.Stdout.Len() != 0 {
-		t.Fatalf("ListOfficialSkillsIndex() stdout len = %d, want 0", result.Stdout.Len())
-	}
-}
-
-func TestListOfficialSkillsIndexTimeout(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		time.Sleep(200 * time.Millisecond)
-		fmt.Fprint(w, `{"skills":[{"name":"lark-calendar"}]}`)
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	oldTimeout := skillsIndexFetchTimeout
-	officialSkillsIndexURL = server.URL
-	skillsIndexFetchTimeout = 50 * time.Millisecond
-	t.Cleanup(func() {
-		officialSkillsIndexURL = oldURL
-		skillsIndexFetchTimeout = oldTimeout
-	})
-
-	result := New().ListOfficialSkillsIndex()
-	var netErr net.Error
-	if result.Err == nil || (!errors.Is(result.Err, context.DeadlineExceeded) && !(errors.As(result.Err, &netErr) && netErr.Timeout())) {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want timeout error", result.Err)
-	}
-}
-
-func TestListOfficialSkillsIndexRejectsNonHTTPSRedirect(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		http.Redirect(w, r, "http://example.com/skills.json", http.StatusFound)
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	officialSkillsIndexURL = server.URL
-	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
-
-	result := New().ListOfficialSkillsIndex()
-	if result.Err == nil || !strings.Contains(result.Err.Error(), "non-HTTPS") {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want non-HTTPS redirect", result.Err)
-	}
-}
-
-func TestListOfficialSkillsIndexUsesOverride(t *testing.T) {
-	result := (&Updater{SkillsIndexFetchOverride: func() *NpmResult {
-		r := &NpmResult{}
-		r.Stdout.WriteString(`{"skills":[{"name":"override-skill"}]}`)
-		return r
-	}}).ListOfficialSkillsIndex()
-	if result.Err != nil {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want nil", result.Err)
-	}
-	if !strings.Contains(result.Stdout.String(), "override-skill") {
-		t.Fatalf("ListOfficialSkillsIndex() stdout = %q, want override result", result.Stdout.String())
-	}
-}
-
 func TestListOfficialSkillsFallsBack(t *testing.T) {
 	called := []string{}
 	updater := &Updater{

internal/skillcontent/reader.go

@@ -1,209 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package skillcontent reads embedded skill content from an injected fs.FS
-// rooted at the skill list (entries like "lark-calendar/SKILL.md").
-package skillcontent
-
-import (
-	"io/fs"
-	"path"
-	"sort"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	"gopkg.in/yaml.v3"
-)
-
-type Reader struct {
-	fsys fs.FS
-}
-
-func New(fsys fs.FS) *Reader { return &Reader{fsys: fsys} }
-
-type SkillInfo struct {
-	Name        string         `json:"name"`
-	Description string         `json:"description"`
-	Version     string         `json:"version,omitempty"`
-	Metadata    map[string]any `json:"metadata,omitempty"`
-}
-
-// DirEntry.Path is skill-prefixed (e.g. "lark-doc/references/x.md") so it can be
-// fed straight back into `read`.
-type DirEntry struct {
-	Path  string `json:"path"`
-	IsDir bool   `json:"is_dir"`
-}
-
-func (r *Reader) List() ([]SkillInfo, error) {
-	entries, err := fs.ReadDir(r.fsys, ".")
-	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeFileIO, "failed to read embedded skills: %v", err)
-	}
-	out := make([]SkillInfo, 0, len(entries))
-	for _, e := range entries {
-		if !e.IsDir() {
-			continue
-		}
-		// Skip dirs that aren't real skills (no SKILL.md).
-		if info, ok := r.skillInfo(e.Name()); ok {
-			out = append(out, info)
-		}
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
-	return out, nil
-}
-
-func (r *Reader) skillInfo(name string) (SkillInfo, bool) {
-	data, err := fs.ReadFile(r.fsys, name+"/SKILL.md")
-	if err != nil {
-		return SkillInfo{}, false
-	}
-	desc, version, metadata := parseFrontmatter(data)
-	return SkillInfo{Name: name, Description: desc, Version: version, Metadata: metadata}, true
-}
-
-// ListPath lists one directory layer (no recursion) under "<name>" or
-// "<name>/<sub>", returning the entries and the cleaned path listed.
-func (r *Reader) ListPath(arg string) ([]DirEntry, string, error) {
-	name, sub := SplitArg(arg)
-	if err := r.ensureSkill(name); err != nil {
-		return nil, "", err
-	}
-	dir := name
-	if sub != "" {
-		cleaned, err := cleanSubPath(sub)
-		if err != nil {
-			return nil, "", err
-		}
-		dir = name + "/" + cleaned
-		info, err := fs.Stat(r.fsys, dir)
-		if err != nil {
-			return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"path %q not found in skill %q", sub, name).
-				WithHint("run 'lark-cli skills list " + name + "' to see files in this skill")
-		}
-		if !info.IsDir() {
-			return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"path %q is a file, not a directory; use 'lark-cli skills read %s/%s' to read it", sub, name, cleaned)
-		}
-	}
-	entries, err := fs.ReadDir(r.fsys, dir)
-	if err != nil {
-		return nil, "", errs.NewInternalError(errs.SubtypeFileIO,
-			"failed to read embedded skill content: %v", err)
-	}
-	out := make([]DirEntry, 0, len(entries))
-	for _, e := range entries {
-		out = append(out, DirEntry{Path: dir + "/" + e.Name(), IsDir: e.IsDir()})
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].Path < out[j].Path })
-	return out, dir, nil
-}
-
-// SplitArg splits "<name>/<rest>" at the first separator; an argument with no
-// separator is a bare skill name (rest "").
-func SplitArg(arg string) (name, rest string) {
-	name, rest, _ = strings.Cut(arg, "/")
-	return name, rest
-}
-
-// parseFrontmatter best-effort-extracts the frontmatter fields; missing or
-// unparseable frontmatter yields ("", "", nil), never an error.
-func parseFrontmatter(skillMD []byte) (description, version string, metadata map[string]any) {
-	lines := strings.Split(string(skillMD), "\n")
-	if strings.TrimRight(lines[0], "\r") != "---" {
-		return "", "", nil
-	}
-	block := make([]string, 0, len(lines))
-	closed := false
-	for _, ln := range lines[1:] {
-		if strings.TrimRight(ln, "\r") == "---" {
-			closed = true
-			break
-		}
-		block = append(block, ln)
-	}
-	if !closed {
-		return "", "", nil
-	}
-	var fm struct {
-		Description string         `yaml:"description"`
-		Version     string         `yaml:"version"`
-		Metadata    map[string]any `yaml:"metadata"`
-	}
-	if err := yaml.Unmarshal([]byte(strings.Join(block, "\n")), &fm); err != nil {
-		return "", "", nil
-	}
-	return fm.Description, fm.Version, fm.Metadata
-}
-
-func (r *Reader) ReadSkill(name string) ([]byte, error) {
-	if err := r.ensureSkill(name); err != nil {
-		return nil, err
-	}
-	data, err := fs.ReadFile(r.fsys, name+"/SKILL.md")
-	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeFileIO,
-			"failed to read embedded skill content: %v", err)
-	}
-	return data, nil
-}
-
-func (r *Reader) ensureSkill(name string) error {
-	if name == "" || strings.ContainsAny(name, `/\`) || name == "." || name == ".." {
-		return unknownSkill(name)
-	}
-	info, err := fs.Stat(r.fsys, name)
-	if err != nil || !info.IsDir() {
-		return unknownSkill(name)
-	}
-	return nil
-}
-
-func unknownSkill(name string) error {
-	return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown skill %q", name).
-		WithHint("run 'lark-cli skills list' to see available skills")
-}
-
-// cleanSubPath returns the cleaned form of relpath, rejecting absolute paths and
-// ".." escapes. relpath must be non-empty (callers handle the skill-root case).
-func cleanSubPath(relpath string) (string, error) {
-	cleaned := path.Clean(relpath)
-	// path.Clean only treats '/' as a separator, so a Windows-style "..\" prefix
-	// survives; reject it explicitly alongside "../".
-	if relpath == "" || path.IsAbs(relpath) || cleaned == "." ||
-		cleaned == ".." || strings.HasPrefix(cleaned, "../") || strings.HasPrefix(cleaned, `..\`) {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"invalid path %q: must be a relative path without '..'", relpath)
-	}
-	return cleaned, nil
-}
-
-// ReadReference returns the bytes of <name>/<relpath> and the cleaned path.
-func (r *Reader) ReadReference(name, relpath string) ([]byte, string, error) {
-	if err := r.ensureSkill(name); err != nil {
-		return nil, "", err
-	}
-	cleaned, err := cleanSubPath(relpath)
-	if err != nil {
-		return nil, "", err
-	}
-	full := name + "/" + cleaned
-	info, err := fs.Stat(r.fsys, full)
-	if err != nil {
-		return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"reference %q not found in skill %q", relpath, name).
-			WithHint("run 'lark-cli skills list " + name + "' to see files in this skill")
-	}
-	if info.IsDir() {
-		return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"reference %q is a directory, not a file", relpath)
-	}
-	data, err := fs.ReadFile(r.fsys, full)
-	if err != nil {
-		return nil, "", errs.NewInternalError(errs.SubtypeFileIO,
-			"failed to read embedded skill content: %v", err)
-	}
-	return data, cleaned, nil
-}