fix: optimize skill

internal/suggest/suggest.go

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

shortcuts/apps/apps_access_scope_get.go

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

shortcuts/apps/apps_access_scope_set.go

@@ -24,7 +24,7 @@ var allowedAccessTargetTypes = map[string]bool{
 var AppsAccessScopeSet = common.Shortcut{
 	Service:     appsService,
 	Command:     "+access-scope-set",
-	Description: "Set app access scope (specific / public / tenant)",
+	Description: "Set Miaoda app access scope (specific / public / tenant)",
 	Risk:        "write",
 	Tips: []string{
 		`Example: lark-cli apps +access-scope-set --app-id <app_id> --scope tenant`,
@@ -52,7 +52,7 @@ var AppsAccessScopeSet = common.Shortcut{
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		dry := common.NewDryRunAPI().
 			PUT(fmt.Sprintf("%s/apps/%s/access-scope", apiBasePath, validate.EncodePathSegment(appID))).
-			Desc("Set app access scope")
+			Desc("Set Miaoda app access scope")
 		body, bodyErr := buildAccessScopeBody(rctx)
 		if bodyErr != nil {
 			dry.Set("body_error", bodyErr.Error())

shortcuts/apps/apps_create.go

@@ -12,13 +12,13 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-const createHint = "verify --app-type is html or full_stack and --name is non-empty; if this is a permission error, confirm your account can create apps"
+const createHint = "verify --app-type is html or full_stack and --name is non-empty; if this is a permission error, confirm your account can create Miaoda apps"
 
-// AppsCreate creates a new app.
+// AppsCreate creates a new Miaoda app.
 var AppsCreate = common.Shortcut{
 	Service:     appsService,
 	Command:     "+create",
-	Description: "Create a new app",
+	Description: "Create a new Miaoda app",
 	Risk:        "write",
 	Tips: []string{
 		`Example: lark-cli apps +create --name "审批系统" --app-type full_stack`,
@@ -42,7 +42,7 @@ var AppsCreate = common.Shortcut{
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			POST(apiBasePath + "/apps").
-			Desc("Create an app").
+			Desc("Create a Miaoda app").
 			Body(buildAppsCreateBody(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_db_env_create.go

@@ -14,7 +14,7 @@ import (
 
 const dbEnvCreateHint = "verify --app-id is correct; if the app is already multi-env this is a conflict — inspect current tables with `lark-cli apps +db-table-list --app-id <app_id> --env dev`"
 
-// AppsDBEnvCreate creates a DB environment for an app（拆分单库为 dev/online 多环境）。
+// AppsDBEnvCreate creates a DB environment for a Miaoda app（拆分单库为 dev/online 多环境）。
 //
 // 调 POST /apps/{app_id}/db_dev_init。--env 指定要创建的环境，由调用方传入，目前只支持 dev。
 // 不可逆：单库一旦拆成 dev/online 双库无法回退。Risk: high-risk-write 触发框架自动注入 --yes 确认关卡。
@@ -30,7 +30,7 @@ var AppsDBEnvCreate = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app id", Required: true},
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "env", Default: "dev", Enum: []string{"dev"}, Desc: "environment to create (only dev supported for now)"},
 		{Name: "sync-data", Type: "bool", Desc: "copy existing online data into the new environment (default off)"},
 	},
@@ -42,7 +42,7 @@ var AppsDBEnvCreate = common.Shortcut{
 		appID, _ := requireAppID(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			POST(appDbEnvCreatePath(appID)).
-			Desc("Create app DB environment").
+			Desc("Create Miaoda app DB environment").
 			Body(buildDBEnvCreateBody(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_db_execute.go

@@ -17,7 +17,7 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsDBExecute executes SQL against an app database.
+// AppsDBExecute executes SQL against a Miaoda app database.
 //
 // POST /apps/{app_id}/sql_commands，CLI 永远带 ?transactional=false 进入 DBA 模式
 // （不默认包事务、支持 DDL、result 字符串内嵌结构化 JSON）。
@@ -45,7 +45,7 @@ import (
 var AppsDBExecute = common.Shortcut{
 	Service:     appsService,
 	Command:     "+db-execute",
-	Description: "Execute SQL (SELECT / DML / DDL) against an app database",
+	Description: "Execute SQL (SELECT / DML / DDL) against a Miaoda app database",
 	Risk:        "high-risk-write",
 	Tips: []string{
 		`Example: lark-cli apps +db-execute --app-id <app_id> --sql "SELECT * FROM orders LIMIT 10" --yes`,
@@ -56,7 +56,7 @@ var AppsDBExecute = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app id", Required: true},
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "sql", Desc: "SQL text; use - to read stdin. Mutually exclusive with --file",
 			Input: []string{common.Stdin}},
 		{Name: "file", Desc: "path to a .sql file (relative to cwd). Mutually exclusive with --sql"},
@@ -97,7 +97,7 @@ var AppsDBExecute = common.Shortcut{
 		appID, _ := requireAppID(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			POST(appSQLPath(appID)).
-			Desc("Execute SQL on app database").
+			Desc("Execute SQL on Miaoda app database").
 			Params(buildDBSQLParams(rctx)).
 			Body(buildDBSQLBody(rctx))
 	},

shortcuts/apps/apps_db_table_get.go

@@ -35,7 +35,7 @@ var AppsDBTableGet = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app id", Required: true},
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "table", Desc: "table name", Required: true},
 		{Name: "env", Default: "online", Enum: []string{"dev", "online"}, Desc: "target db environment"},
 	},
@@ -52,7 +52,7 @@ var AppsDBTableGet = common.Shortcut{
 		appID, _ := requireAppID(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			GET(appTablePath(appID, strings.TrimSpace(rctx.Str("table")))).
-			Desc("Get app db table schema").
+			Desc("Get Miaoda app db table schema").
 			Params(buildDBTableGetParams(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_db_table_list.go

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

shortcuts/apps/apps_html_publish.go

@@ -19,7 +19,7 @@ import (
 var AppsHTMLPublish = common.Shortcut{
 	Service:     appsService,
 	Command:     "+html-publish",
-	Description: "Publish HTML to an app (single multipart POST returns the access URL)",
+	Description: "Publish HTML to a Miaoda app (single multipart POST returns the access URL)",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +html-publish --app-id <app_id> --path ./dist",
@@ -29,7 +29,7 @@ var AppsHTMLPublish = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", Required: true},
 		{Name: "path", Desc: "path to HTML file or directory", Required: true},
 		{Name: "allow-sensitive", Type: "bool", Desc: "skip the credential-file scan (allow .env / .npmrc / .aws/credentials / etc. in the publish payload)"},
 	},
@@ -179,7 +179,7 @@ func ensureIndexHTML(candidates []htmlPublishCandidate) error {
 		}
 	}
 	return appsFailedPreconditionParamError("--path", "--path is missing index.html").
-		WithHint("index.html is the app entrypoint; for a directory put index.html at the root, or pass a single file named index.html")
+		WithHint("Miaoda uses index.html as the app entrypoint; for a directory put index.html at the root, or pass a single file named index.html")
 }
 
 func runHTMLPublish(ctx context.Context, fio fileio.FileIO, publisher appsHTMLPublishClient, spec appsHTMLPublishSpec) (map[string]interface{}, error) {

shortcuts/apps/apps_init.go

@@ -27,8 +27,8 @@ const defaultInitBranch = "sprint/default"
 // the non-empty (`app sync`) path stays a single commit.
 const (
 	commitMsgAppCode   = "chore: initialize app project code"
-	commitMsgAppConfig = "chore: initialize app config"
-	commitMsgUpgrade   = "chore: initialize app repository"
+	commitMsgAppConfig = "chore: initialize miaoda app config"
+	commitMsgUpgrade   = "chore: initialize miaoda app repository"
 )
 
 // scaffold kinds returned by runScaffold and consumed by commitAndPushIfDirty.
@@ -49,11 +49,11 @@ const (
 // can swap in a fakeCommandRunner. Production uses execCommandRunner.
 var initRunner commandRunner = execCommandRunner{}
 
-// AppsInit initializes an app's code and local development environment.
+// AppsInit initializes a Miaoda app's code and local development environment.
 var AppsInit = common.Shortcut{
 	Service:     appsService,
 	Command:     "+init",
-	Description: "Initialize an app's code and local development environment",
+	Description: "Initialize a Miaoda app's code and local development environment",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +init --app-id <app_id> --dir <dir>",
@@ -73,7 +73,7 @@ var AppsInit = common.Shortcut{
 		// envelope. The spec and the E2E assert exit-2 + a structured
 		// {"ok":false,"error":{...}} envelope for missing --app-id, so the empty
 		// check lives in Validate (typed validation error -> exit 2).
-		{Name: "app-id", Desc: "app ID"},
+		{Name: "app-id", Desc: "Miaoda app ID"},
 		{Name: "dir", Desc: "clone target directory; absolute or relative path (default ./<app-id>)"},
 		{Name: "template", Desc: "code-init template for an empty repo; optional — if omitted, derived from the app's tech stack"},
 	},
@@ -87,7 +87,7 @@ var AppsInit = common.Shortcut{
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		template := resolveTemplate(rctx, appID)
 		dry := common.NewDryRunAPI().
-			Desc("Initialize app code (credential-init, clone, checkout, npx code-init, optional commit/push)").
+			Desc("Initialize Miaoda app code (credential-init, clone, checkout, npx code-init, optional commit/push)").
 			Set("credential_init", fmt.Sprintf("apps +git-credential-init --app-id %s --format json", appID)).
 			Set("checkout", "git checkout "+defaultInitBranch).
 			Set("scaffold", fmt.Sprintf("empty repo: npx -y --prefer-online %s app init --template %s --app-id %s; non-empty: npx -y --prefer-online %s app sync + .spark/meta.json app_id patch + conditional skills sync --local", miaodaCLIPkg, template, appID, miaodaCLIPkg)).
@@ -191,7 +191,7 @@ func ensureEmptyDir(dir string) error {
 	return nil
 }
 
-// isAlreadyInitialized reports whether dir is an already-initialized app
+// isAlreadyInitialized reports whether dir is an already-initialized Miaoda app
 // repo, detected by the presence of <dir>/.spark/meta.json (regardless of its
 // app_id value). Used to short-circuit +init into a friendly no-op.
 func isAlreadyInitialized(dir string) bool {
@@ -379,7 +379,7 @@ func appsInitExecute(ctx context.Context, rctx *common.RuntimeContext) error {
 	}
 
 	// Already-initialized short-circuit: a dir containing .spark/meta.json is an
-	// initialized app repo -> skip clone/scaffold/commit, but still refresh
+	// initialized Miaoda app repo -> skip clone/scaffold/commit, but still refresh
 	// the local env so a re-run picks up the latest startup env vars.
 	if isAlreadyInitialized(dir) {
 		initLogf(rctx, "Already initialized at %s — refreshing local environment", dir)
@@ -556,7 +556,7 @@ func issueCredentials(ctx context.Context, rctx *common.RuntimeContext, appID st
 // commitAndPushIfDirty commits and pushes only when the working tree has
 // changes; a clean tree is a no-op (returns false,false). For the empty-repo
 // init path (scaffoldKind == "init") it splits the scaffolded tree into two
-// commits — app project code, then app config (.spark/.agent) — skipping
+// commits — app project code, then Miaoda config (.spark/.agent) — skipping
 // either commit when that group has no changes (no empty commits). Other paths
 // commit once. Push is a single `git push origin <branch>` for all commits.
 func commitAndPushIfDirty(ctx context.Context, dir, scaffoldKind string) (committed, pushed bool, err error) {
@@ -621,7 +621,7 @@ func stageAndCommit(ctx context.Context, dir, message string, pathspecs ...strin
 
 // classifyPorcelain parses `git status --porcelain` output and partitions the
 // changed paths into the "app code" group (anything outside .spark/ and .agent/)
-// and the "app config" group (.spark/ and .agent/). It returns the exact
+// and the "Miaoda config" group (.spark/ and .agent/). It returns the exact
 // porcelain paths so callers can stage them verbatim: porcelain never lists
 // gitignored files, so `git add -- <these paths>` never trips git's ignored-path
 // error. (Naming an ignored dir explicitly — or combining a "." pathspec with
@@ -658,7 +658,7 @@ func porcelainPath(line string) string {
 	return p
 }
 
-// isConfigPath reports whether p is the app-config group: the .spark or
+// isConfigPath reports whether p is the Miaoda app-config group: the .spark or
 // .agent directory itself, or anything under them. ".sparkrc" is NOT config.
 func isConfigPath(p string) bool {
 	return p == ".spark" || p == ".agent" ||

shortcuts/apps/apps_init_test.go

@@ -835,7 +835,7 @@ func TestAppsInit_EmptyRepo_TwoCommits(t *testing.T) {
 		t.Fatalf("unexpected: %v", err)
 	}
 	msgs := commitMessages(f.calls)
-	want := []string{"chore: initialize app project code", "chore: initialize app config"}
+	want := []string{"chore: initialize app project code", "chore: initialize miaoda app config"}
 	if len(msgs) != 2 || msgs[0] != want[0] || msgs[1] != want[1] {
 		t.Fatalf("commit messages = %v, want %v", msgs, want)
 	}
@@ -896,7 +896,7 @@ func TestAppsInit_EmptyRepo_ConfigOnly_SingleCommit(t *testing.T) {
 		t.Fatalf("unexpected: %v", err)
 	}
 	msgs := commitMessages(f.calls)
-	if len(msgs) != 1 || msgs[0] != "chore: initialize app config" {
+	if len(msgs) != 1 || msgs[0] != "chore: initialize miaoda app config" {
 		t.Fatalf("commit messages = %v, want one config commit", msgs)
 	}
 }
@@ -916,7 +916,7 @@ func TestAppsInit_NonEmpty_SingleInitCommit(t *testing.T) {
 		t.Fatalf("unexpected: %v", err)
 	}
 	msgs := commitMessages(f.calls)
-	if len(msgs) != 1 || msgs[0] != "chore: initialize app repository" {
+	if len(msgs) != 1 || msgs[0] != "chore: initialize miaoda app repository" {
 		t.Fatalf("commit messages = %v, want one upgrade commit", msgs)
 	}
 	for _, c := range f.calls {

shortcuts/apps/apps_list.go

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

shortcuts/apps/apps_release_create.go

@@ -13,11 +13,11 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsReleaseCreate creates a release for an app.
+// AppsReleaseCreate creates a release for a Miaoda app.
 var AppsReleaseCreate = common.Shortcut{
 	Service:     appsService,
 	Command:     "+release-create",
-	Description: "Create a release for an app (returns release_id for status polling)",
+	Description: "Create a release for a Miaoda app (returns release_id for status polling)",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +release-create --app-id <app_id>",
@@ -27,7 +27,7 @@ var AppsReleaseCreate = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", Required: true},
 		{Name: "branch", Desc: "release branch (server uses default if omitted)"},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_release_get.go

@@ -26,7 +26,7 @@ var AppsReleaseGet = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", Required: true},
 		{Name: "release-id", Desc: "release ID (the release_id returned by +release-create)", Required: true},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/apps_release_list.go

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

shortcuts/apps/apps_session_create.go

@@ -13,11 +13,11 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsSessionCreate creates a new session under an existing app.
+// AppsSessionCreate creates a new session under an existing Miaoda app.
 var AppsSessionCreate = common.Shortcut{
 	Service:     appsService,
 	Command:     "+session-create",
-	Description: "Create a session under an app",
+	Description: "Create a session under a Miaoda app",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +session-create --app-id <app_id>",
@@ -37,7 +37,7 @@ var AppsSessionCreate = common.Shortcut{
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().
 			POST(sessionsPath(rctx.Str("app-id"))).
-			Desc("Create a session under an app")
+			Desc("Create a session under a Miaoda app")
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		data, err := rctx.CallAPITyped("POST", sessionsPath(rctx.Str("app-id")), nil, nil)

shortcuts/apps/apps_session_list.go

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

shortcuts/apps/apps_update.go

@@ -13,11 +13,11 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// AppsUpdate partially updates an app's name / description.
+// AppsUpdate partially updates a Miaoda app's name / description.
 var AppsUpdate = common.Shortcut{
 	Service:     appsService,
 	Command:     "+update",
-	Description: "Partially update an app (only provided fields are sent)",
+	Description: "Partially update a Miaoda app (only provided fields are sent)",
 	Risk:        "write",
 	Tips: []string{
 		`Example: lark-cli apps +update --app-id <app_id> --name "新名称"`,
@@ -49,7 +49,7 @@ var AppsUpdate = common.Shortcut{
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			PATCH(fmt.Sprintf("%s/apps/%s", apiBasePath, validate.EncodePathSegment(appID))).
-			Desc("Update an app").
+			Desc("Update a Miaoda app").
 			Body(buildAppsUpdateBody(rctx))
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {

shortcuts/apps/common.go

@@ -12,12 +12,12 @@ import (
 // appsService 是 CLI 命令的 service 前缀（lark-cli apps ...）。
 const appsService = "apps"
 
-// apiBasePath is the registered OAPI prefix for the apps domain.
+// apiBasePath is the registered OAPI prefix for the Miaoda apps domain.
 const apiBasePath = "/open-apis/spark/v1"
 
 // appIDListHint is the shared recovery hint for commands whose most likely
 // failure cause is a wrong/inaccessible --app-id. It points at +list to find
-// the correct app id. The app_/cli_ format rule is taught in
+// the correct Miaoda app id. The app_/cli_ format rule is taught in
 // lark-apps SKILL.md ("app_id 获取"); the hint stays lean and does not repeat it.
 const appIDListHint = "verify --app-id is correct and you have access to the app; list your apps with `lark-cli apps +list`"
 

shortcuts/apps/git_credential.go

@@ -35,12 +35,12 @@ const gitCredentialIssuePath = apiBasePath + "/apps/:app_id/git_info"
 
 // gitCredentialIssueHint is the actionable next-step attached to a failed
 // Git-credential issuance. A 5xx is flagged retryable separately at the call site.
-const gitCredentialIssueHint = "failed to issue the Git credential: verify --app-id is correct and you have developer access to this app; a 5xx is a transient server error and is safe to retry"
+const gitCredentialIssueHint = "failed to issue the Git credential: verify --app-id is correct and you have developer access to this Miaoda app; a 5xx is a transient server error and is safe to retry"
 
 var AppsGitCredentialInit = common.Shortcut{
 	Service:     appsService,
 	Command:     "+git-credential-init",
-	Description: "Initialize Git credentials and a URL-scoped Git helper for an app repository",
+	Description: "Initialize Git credentials and a URL-scoped Git helper for a Miaoda app repository",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +git-credential-init --app-id <app_id>",
@@ -49,7 +49,7 @@ var AppsGitCredentialInit = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", Required: true},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
@@ -64,7 +64,7 @@ var AppsGitCredentialInit = common.Shortcut{
 		appID := strings.TrimSpace(rctx.Str("app-id"))
 		return common.NewDryRunAPI().
 			GET(gitCredentialIssuePath).
-			Desc("Issue an app Git repository PAT").
+			Desc("Issue a Miaoda Git repository PAT").
 			Set("mode", "api-plus-local-setup").
 			Set("action", "initialize_local_git_credential").
 			Set("app_id", appID).
@@ -81,7 +81,7 @@ var AppsGitCredentialInit = common.Shortcut{
 		manager := newGitCredentialManager(appID, rctx.Factory.Keychain, runtimeIssuer{rctx: rctx})
 		result, err := manager.Init(ctx, profileFromConfig(rctx.Config), appID)
 		if err != nil {
-			return gitCredentialLocalError("Initialize local app Git credential", err)
+			return gitCredentialLocalError("Initialize local Miaoda Git credential", err)
 		}
 		payload := map[string]interface{}{
 			"app_id":         result.AppID,
@@ -119,7 +119,7 @@ var AppsGitCredentialInit = common.Shortcut{
 var AppsGitCredentialRemove = common.Shortcut{
 	Service:     appsService,
 	Command:     "+git-credential-remove",
-	Description: "Remove local Git credentials and the URL-scoped Git helper for an app repository",
+	Description: "Remove local Git credentials and the URL-scoped Git helper for a Miaoda app repository",
 	Risk:        "write",
 	Tips: []string{
 		"Example: lark-cli apps +git-credential-remove --app-id <app_id>",
@@ -128,7 +128,7 @@ var AppsGitCredentialRemove = common.Shortcut{
 	AuthTypes: []string{"user"},
 	HasFormat: true,
 	Flags: []common.Flag{
-		{Name: "app-id", Desc: "app ID", Required: true},
+		{Name: "app-id", Desc: "Miaoda app ID", Required: true},
 	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if strings.TrimSpace(rctx.Str("app-id")) == "" {
@@ -159,7 +159,7 @@ var AppsGitCredentialRemove = common.Shortcut{
 		manager := newGitCredentialManager(appID, rctx.Factory.Keychain, nil)
 		result, err := manager.Remove(ctx, profileFromConfig(rctx.Config), appID)
 		if err != nil {
-			return gitCredentialLocalError("Remove local app Git credential", err)
+			return gitCredentialLocalError("Remove local Miaoda Git credential", err)
 		}
 		payload := map[string]interface{}{
 			"app_id":  result.AppID,
@@ -193,7 +193,7 @@ var AppsGitCredentialRemove = common.Shortcut{
 var AppsGitCredentialList = common.Shortcut{
 	Service:     appsService,
 	Command:     "+git-credential-list",
-	Description: "List local Git credentials for app repositories",
+	Description: "List local Git credentials for Miaoda app repositories",
 	Risk:        "read",
 	Tips: []string{
 		"Example: lark-cli apps +git-credential-list",
@@ -215,7 +215,7 @@ var AppsGitCredentialList = common.Shortcut{
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		records, err := listGitCredentialRecords(rctx.Factory.Keychain, time.Now)
 		if err != nil {
-			return gitCredentialLocalError("List local app Git credentials", err)
+			return gitCredentialLocalError("List local Miaoda Git credentials", err)
 		}
 		payload := map[string]interface{}{
 			"count":       len(records),
@@ -252,7 +252,7 @@ func InstallOnApps(parent *cobra.Command, f *cmdutil.Factory) {
 func newGitCredentialHelperCommand(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:    "git-credential-helper get|store|erase",
-		Short:  "Git credential helper for app repositories",
+		Short:  "Git credential helper for Miaoda app repositories",
 		Hidden: true,
 		Args:   cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -260,7 +260,7 @@ func newGitCredentialHelperCommand(f *cmdutil.Factory) *cobra.Command {
 			return runGitCredentialHelper(cmd.Context(), f, strings.TrimSpace(appID), args[0])
 		},
 	}
-	cmd.Flags().String("app-id", "", "app ID")
+	cmd.Flags().String("app-id", "", "Miaoda app ID")
 	_ = cmd.Flags().MarkHidden("app-id")
 	return cmd
 }
@@ -457,10 +457,10 @@ func issuedFromData(appID string, data map[string]interface{}) (*gitcred.IssuedC
 		issued.AppID = appID
 	}
 	if issued.GitHTTPURL == "" {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response missing gitURL")
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue Miaoda Git credential: response missing gitURL")
 	}
 	if issued.PAT == "" {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response missing token")
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue Miaoda Git credential: response missing token")
 	}
 	return issued, nil
 }
@@ -479,7 +479,7 @@ func parseIssueCredentialData(resp *larkcore.ApiResp, err error, cc errclass.Cla
 	detail := logIDDetail(resp)
 	if resp == nil || len(resp.RawBody) == 0 {
 		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"Issue app Git credential: empty response body")
+			"Issue Miaoda Git credential: empty response body")
 	}
 	var result map[string]any
 	jsonErr := json.Unmarshal(resp.RawBody, &result)
@@ -522,7 +522,7 @@ func checkGitInfoBaseResp(result map[string]any, logID string) error {
 		if message == "" {
 			message = "Git credential API returned non-zero BaseResp status"
 		}
-		baseErr := errs.NewAPIError(errs.SubtypeUnknown, "Issue app Git credential: %s", message).WithCode(int(code))
+		baseErr := errs.NewAPIError(errs.SubtypeUnknown, "Issue Miaoda Git credential: %s", message).WithCode(int(code))
 		if logID != "" {
 			baseErr = baseErr.WithLogID(logID)
 		}

shortcuts/apps/git_credential_test.go

@@ -699,7 +699,7 @@ func assertStringSliceEqual(t *testing.T, got, want []string) {
 
 func TestGitCredentialLocalErrorWrapsOnlyPlainErrors(t *testing.T) {
 	plain := errors.New("git config failed")
-	wrapped := gitCredentialLocalError("List local app Git credentials", plain)
+	wrapped := gitCredentialLocalError("List local Miaoda Git credentials", plain)
 	var configErr *errs.ConfigError
 	if !errors.As(wrapped, &configErr) {
 		t.Fatalf("plain local error wrapped as %T, want *errs.ConfigError", wrapped)

shortcuts/apps/gitcred/helper.go

@@ -458,19 +458,19 @@ func defaultUsername(username string) string {
 
 func validateIssuedCredential(appID, normalizedURL string, issued *IssuedCredential, now int64) error {
 	if issued == nil {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: empty credential")
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue Miaoda Git credential: empty credential")
 	}
 	if issued.AppID != "" && issued.AppID != appID {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response app_id %q does not match requested app_id %q", issued.AppID, appID)
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue Miaoda Git credential: response app_id %q does not match requested app_id %q", issued.AppID, appID)
 	}
 	if normalizedURL == "" {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response missing gitURL")
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue Miaoda Git credential: response missing gitURL")
 	}
 	if strings.TrimSpace(issued.PAT) == "" {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response missing token")
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue Miaoda Git credential: response missing token")
 	}
 	if issued.ExpiresAt <= now {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue app Git credential: response expiredTime must be in the future")
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "Issue Miaoda Git credential: response expiredTime must be in the future")
 	}
 	return nil
 }

shortcuts/apps/gitcred/types.go

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

shortcuts/apps/html_publish_client.go

@@ -53,7 +53,7 @@ func (api appsHTMLPublishAPI) HTMLPublish(ctx context.Context, appID string, tar
 	return &htmlPublishResponse{URL: url}, nil
 }
 
-// OAPI business error codes returned by the
+// OAPI business error codes returned by the Miaoda
 // /apps/{id}/upload_and_release_html_code endpoint. Owned by the backend
 // service; update when new codes are documented in the OAPI spec.
 const (
@@ -66,7 +66,7 @@ func buildHTMLPublishFailureHint(code int) string {
 	case errCodeBuildFailed:
 		return "server-side build failed: run `lark-cli apps +html-publish --app-id <your-app-id> --path <path> --dry-run` to inspect the packaged file list"
 	case errCodeAppNotFound:
-		return "the app does not exist or the caller has no access; ask the user to confirm the app_id (extract it from the app URL https://miaoda.feishu.cn/app/app_xxx after /app/, or take the app_xxx string directly)"
+		return "the app does not exist or the caller has no access; ask the user to confirm the app_id (extract it from the Miaoda app URL https://miaoda.feishu.cn/app/app_xxx after /app/, or take the app_xxx string directly)"
 	default:
 		return ""
 	}

shortcuts/base/base_data_query.go

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

shortcuts/base/base_dryrun_ops_test.go

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

shortcuts/base/base_execute_test.go

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

shortcuts/base/base_shortcuts_test.go

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

shortcuts/base/dashboard_block_get_data.go

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

shortcuts/base/field_list.go

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

shortcuts/base/field_list_batch.go

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

shortcuts/base/field_ops.go

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

shortcuts/base/field_search_options.go

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

shortcuts/base/helpers_test.go

@@ -4,7 +4,6 @@
 package base
 
 import (
-	"context"
 	"encoding/json"
 	"os"
 	"reflect"
@@ -497,61 +496,3 @@ func TestCanonicalSelectAndCompareHelpers(t *testing.T) {
 		t.Fatalf("err=%v", err)
 	}
 }
-
-func TestNormalizePluralReferenceValues(t *testing.T) {
-	cases := []struct {
-		name string
-		in   []string
-		want []string
-	}{
-		{"repeated single values", []string{"fldA", "fldB"}, []string{"fldA", "fldB"}},
-		{"json array", []string{`["fldA","fldB"]`}, []string{"fldA", "fldB"}},
-		{"comma separated ids", []string{"fldA, fldB"}, []string{"fldA", "fldB"}},
-		{"comma separated names", []string{"商品名称,SKU,单价"}, []string{"商品名称", "SKU", "单价"}},
-		{"trailing comma ignored", []string{"recA,recB,"}, []string{"recA", "recB"}},
-		{"fullwidth comma kept whole", []string{"销售额，单价"}, []string{"销售额，单价"}},
-		{"mixed forms", []string{`["fldA"]`, "fldB,fldC", "Name"}, []string{"fldA", "fldB", "fldC", "Name"}},
-		{"invalid json kept literal", []string{`[fldA`}, []string{`[fldA`}},
-		{"blank dropped", []string{"  ", "fldA"}, []string{"fldA"}},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			if got := normalizePluralReferenceValues(tc.in); !reflect.DeepEqual(got, tc.want) {
-				t.Fatalf("got=%v want=%v", got, tc.want)
-			}
-		})
-	}
-}
-
-func TestRecordFlagAliasMergeAndDedupe(t *testing.T) {
-	fieldRT := newBaseTestRuntimeWithArrays(nil, map[string][]string{
-		"field-id": {"fldA"},
-		"fields":   {"fldA,fldB"},
-	}, nil, nil)
-	if got := recordFieldFlags(fieldRT); !reflect.DeepEqual(got, []string{"fldA", "fldB"}) {
-		t.Fatalf("field flags=%v", got)
-	}
-	recordRT := newBaseTestRuntimeWithArrays(nil, map[string][]string{
-		"record-id":  {"recA"},
-		"record-ids": {`["recA","recB"]`},
-	}, nil, nil)
-	if got := recordIDFlags(recordRT); !reflect.DeepEqual(got, []string{"recA", "recB"}) {
-		t.Fatalf("record flags=%v", got)
-	}
-}
-
-func TestFieldSearchOptionsKeywordQueryAlias(t *testing.T) {
-	ctx := context.Background()
-	if err := BaseFieldSearchOptions.Validate(ctx, newBaseTestRuntime(
-		map[string]string{"field-id": "Status", "keyword": "A", "query": "B"}, nil, nil,
-	)); err == nil || !strings.Contains(err.Error(), "use only one") {
-		t.Fatalf("err=%v", err)
-	}
-	queryOnly := newBaseTestRuntime(map[string]string{"field-id": "Status", "query": "Do"}, nil, nil)
-	if err := BaseFieldSearchOptions.Validate(ctx, queryOnly); err != nil {
-		t.Fatalf("err=%v", err)
-	}
-	if got := fieldSearchOptionsKeyword(queryOnly); got != "Do" {
-		t.Fatalf("keyword=%q", got)
-	}
-}

shortcuts/base/record_get.go

@@ -21,10 +21,7 @@ var BaseRecordGet = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		{Name: "record-id", Type: "string_array", Desc: "record ID (repeatable)"},
-		{Name: "record-ids", Type: "string_array", Hidden: true},
 		{Name: "field-id", Type: "string_array", Desc: "field ID or name to project; repeat to keep only needed columns"},
-		{Name: "field-names", Type: "string_array", Hidden: true},
-		{Name: "fields", Type: "string_array", Hidden: true},
 		{Name: "json", Desc: `JSON object with record_id_list, e.g. {"record_id_list":["rec_xxx"]}`},
 		recordReadFormatFlag(),
 	},

shortcuts/base/record_list.go

@@ -5,7 +5,6 @@ package base
 
 import (
 	"context"
-	"strings"
 
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
@@ -22,14 +21,9 @@ var BaseRecordList = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		recordListFieldRefFlag(),
-		{Name: "field-names", Type: "string_array", Hidden: true},
-		{Name: "fields", Type: "string_array", Hidden: true},
 		recordListViewRefFlag(),
 		recordFilterFlag(),
-		recordFilterAliasFlag(),
 		recordSortFlag(),
-		recordSortAliasFlag(),
-		{Name: "json", Hidden: true},
 		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
 		{Name: "limit", Type: "int", Default: "100", Desc: "pagination size, range 1-200"},
 		recordReadFormatFlag(),
@@ -51,9 +45,6 @@ var BaseRecordList = common.Shortcut{
 		if err := validateRecordReadFormat(runtime); err != nil {
 			return err
 		}
-		if strings.TrimSpace(runtime.Str("json")) != "" {
-			return baseFlagErrorf("+record-list does not support --json; use --filter-json for filters and --sort-json for sorting")
-		}
 		return validateRecordQueryOptions(runtime)
 	},
 	DryRun: dryRunRecordList,

shortcuts/base/record_ops.go

@@ -5,7 +5,6 @@ package base
 
 import (
 	"context"
-	"encoding/json"
 	"net/url"
 	"strconv"
 	"strings"
@@ -46,11 +45,11 @@ func validateRecordSelection(runtime *common.RuntimeContext) error {
 }
 
 func resolveRecordSelection(runtime *common.RuntimeContext) (recordSelection, error) {
-	recordIDs := recordIDFlags(runtime)
-	fieldIDs := recordFieldFlags(runtime)
+	recordIDs := runtime.StrArray("record-id")
+	fieldIDs := runtime.StrArray("field-id")
 	jsonRaw := strings.TrimSpace(runtime.Str("json"))
 	if len(recordIDs) > 0 && jsonRaw != "" {
-		return recordSelection{}, baseFlagErrorf("--record-id/--record-ids and --json are mutually exclusive")
+		return recordSelection{}, baseFlagErrorf("--record-id and --json are mutually exclusive")
 	}
 	if jsonRaw != "" {
 		pc := newParseCtx(runtime)
@@ -146,73 +145,6 @@ func normalizeRecordGetSelectFields(values interface{}) ([]string, error) {
 	})
 }
 
-func recordIDFlags(runtime *common.RuntimeContext) []string {
-	return mergeReferenceSources(
-		runtime.StrArray("record-id"),
-		normalizePluralReferenceValues(runtime.StrArray("record-ids")),
-	)
-}
-
-func recordFieldFlags(runtime *common.RuntimeContext) []string {
-	return mergeReferenceSources(
-		runtime.StrArray("field-id"),
-		normalizePluralReferenceValues(runtime.StrArray("field-names")),
-		normalizePluralReferenceValues(runtime.StrArray("fields")),
-	)
-}
-
-// mergeReferenceSources concatenates flag sources, dropping values from later
-// sources that an earlier source already provided — so the same reference
-// passed through both a canonical flag and its plural alias is sent only once.
-// Duplicates inside a single source are kept on purpose: repeating a value on
-// one flag is a user mistake that downstream validation should keep rejecting.
-func mergeReferenceSources(sources ...[]string) []string {
-	var out []string
-	seenBefore := map[string]struct{}{}
-	for _, source := range sources {
-		for _, value := range source {
-			if _, ok := seenBefore[value]; ok {
-				continue
-			}
-			out = append(out, value)
-		}
-		for _, value := range source {
-			seenBefore[value] = struct{}{}
-		}
-	}
-	return out
-}
-
-// normalizePluralReferenceValues expands each raw value of a plural alias flag
-// (--field-names / --fields / --record-ids) into individual references. Plural
-// flags carry list semantics, so an ASCII comma is always a separator (eval
-// traces show comma-joined values are exclusively lists, mostly field names);
-// a JSON string array is also accepted. Names that contain a literal ASCII
-// comma must use the singular flag (--field-id), which never splits. Fullwidth
-// "，" and "、" are untouched, so ordinary Chinese names are safe here too.
-func normalizePluralReferenceValues(values []string) []string {
-	var out []string
-	for _, value := range values {
-		value = strings.TrimSpace(value)
-		if value == "" {
-			continue
-		}
-		if strings.HasPrefix(value, "[") {
-			var parsed []string
-			if err := json.Unmarshal([]byte(value), &parsed); err == nil {
-				out = append(out, parsed...)
-				continue
-			}
-		}
-		for _, part := range strings.Split(value, ",") {
-			if part = strings.TrimSpace(part); part != "" {
-				out = append(out, part)
-			}
-		}
-	}
-	return out
-}
-
 func normalizeStringList(values interface{}, opts stringListNormalizeOptions) ([]string, error) {
 	var rawItems []interface{}
 	switch typed := values.(type) {
@@ -443,7 +375,7 @@ func validateRecordJSON(runtime *common.RuntimeContext) error {
 }
 
 func recordListFields(runtime *common.RuntimeContext) []string {
-	return recordFieldFlags(runtime)
+	return runtime.StrArray("field-id")
 }
 
 func executeRecordList(runtime *common.RuntimeContext) error {

shortcuts/base/record_query.go

@@ -26,10 +26,6 @@ func recordFilterFlag() common.Flag {
 	}
 }
 
-func recordFilterAliasFlag() common.Flag {
-	return common.Flag{Name: "filter", Hidden: true, Input: []string{common.File}}
-}
-
 func recordSortFlag() common.Flag {
 	return common.Flag{
 		Name:  recordSortJSONFlag,
@@ -38,10 +34,6 @@ func recordSortFlag() common.Flag {
 	}
 }
 
-func recordSortAliasFlag() common.Flag {
-	return common.Flag{Name: "sort", Hidden: true, Input: []string{common.File}}
-}
-
 func validateRecordQueryOptions(runtime *common.RuntimeContext) error {
 	if _, err := parseRecordFilterFlag(runtime); err != nil {
 		return err
@@ -51,10 +43,7 @@ func validateRecordQueryOptions(runtime *common.RuntimeContext) error {
 }
 
 func parseRecordFilterFlag(runtime *common.RuntimeContext) (interface{}, error) {
-	filterRaw, err := recordQueryFlagValue(runtime, recordFilterJSONFlag, "filter")
-	if err != nil {
-		return nil, err
-	}
+	filterRaw := strings.TrimSpace(runtime.Str(recordFilterJSONFlag))
 	if filterRaw == "" {
 		return nil, nil
 	}
@@ -63,10 +52,7 @@ func parseRecordFilterFlag(runtime *common.RuntimeContext) (interface{}, error)
 }
 
 func parseRecordSortFlag(runtime *common.RuntimeContext) ([]interface{}, error) {
-	sortRaw, err := recordQueryFlagValue(runtime, recordSortJSONFlag, "sort")
-	if err != nil {
-		return nil, err
-	}
+	sortRaw := strings.TrimSpace(runtime.Str(recordSortJSONFlag))
 	if sortRaw == "" {
 		return nil, nil
 	}
@@ -78,18 +64,6 @@ func parseRecordSortFlag(runtime *common.RuntimeContext) ([]interface{}, error)
 	return normalizeRecordSortValue(value, "--"+recordSortJSONFlag)
 }
 
-func recordQueryFlagValue(runtime *common.RuntimeContext, canonical string, alias string) (string, error) {
-	canonicalRaw := strings.TrimSpace(runtime.Str(canonical))
-	aliasRaw := strings.TrimSpace(runtime.Str(alias))
-	if canonicalRaw != "" && aliasRaw != "" {
-		return "", baseFlagErrorf("--%s is a deprecated alias for --%s; use only one", alias, canonical)
-	}
-	if canonicalRaw != "" {
-		return canonicalRaw, nil
-	}
-	return aliasRaw, nil
-}
-
 func normalizeRecordSortValue(value interface{}, label string) ([]interface{}, error) {
 	var sortConfig []interface{}
 	if parsed, ok := value.([]interface{}); ok {
@@ -193,7 +167,7 @@ func applyRecordQueryToBody(runtime *common.RuntimeContext, body map[string]inte
 
 func recordSearchFlagBody(runtime *common.RuntimeContext) (map[string]interface{}, error) {
 	body := map[string]interface{}{}
-	if keyword := recordSearchKeyword(runtime); keyword != "" {
+	if keyword := strings.TrimSpace(runtime.Str("keyword")); keyword != "" {
 		body["keyword"] = keyword
 	}
 	searchFields := runtime.StrArray("search-field")
@@ -243,9 +217,6 @@ func validateRecordSearchFlags(runtime *common.RuntimeContext) error {
 	if err := validateRecordReadFormat(runtime); err != nil {
 		return err
 	}
-	if strings.TrimSpace(runtime.Str("keyword")) != "" && strings.TrimSpace(runtime.Str("query")) != "" {
-		return baseFlagErrorf("--query is a deprecated alias for --keyword; use only one")
-	}
 	jsonRaw := strings.TrimSpace(runtime.Str("json"))
 	if jsonRaw != "" {
 		if recordSearchHasJSONExclusiveFlagInputs(runtime) {
@@ -254,7 +225,7 @@ func validateRecordSearchFlags(runtime *common.RuntimeContext) error {
 		_, err := recordSearchJSONBody(runtime)
 		return err
 	}
-	if recordSearchKeyword(runtime) == "" {
+	if strings.TrimSpace(runtime.Str("keyword")) == "" {
 		return baseFlagErrorf("--keyword is required unless --json is used")
 	}
 	if len(runtime.StrArray("search-field")) == 0 {
@@ -264,7 +235,7 @@ func validateRecordSearchFlags(runtime *common.RuntimeContext) error {
 }
 
 func recordSearchHasJSONExclusiveFlagInputs(runtime *common.RuntimeContext) bool {
-	return recordSearchKeyword(runtime) != "" ||
+	return strings.TrimSpace(runtime.Str("keyword")) != "" ||
 		len(runtime.StrArray("search-field")) > 0 ||
 		len(recordListFields(runtime)) > 0 ||
 		runtime.Str("view-id") != "" ||
@@ -272,13 +243,6 @@ func recordSearchHasJSONExclusiveFlagInputs(runtime *common.RuntimeContext) bool
 		runtime.Changed("limit")
 }
 
-func recordSearchKeyword(runtime *common.RuntimeContext) string {
-	if keyword := strings.TrimSpace(runtime.Str("keyword")); keyword != "" {
-		return keyword
-	}
-	return strings.TrimSpace(runtime.Str("query"))
-}
-
 func formatRecordQueryPriorityTip() string {
 	return fmt.Sprintf("Query priority: --%s overrides --view-id's view filter JSON; --%s overrides --view-id's view sort config.", recordFilterJSONFlag, recordSortJSONFlag)
 }

shortcuts/base/record_search.go

@@ -22,16 +22,11 @@ var BaseRecordSearch = common.Shortcut{
 		tableRefFlag(true),
 		{Name: "json", Desc: `record search JSON object for the full request body, e.g. {"keyword":"Alice","search_fields":["Name"],"select_fields":["Name","Status"],"filter":{"logic":"and","conditions":[]},"sort":[{"field":"Updated","desc":true}],"limit":50}; escape hatch for advanced cases`},
 		{Name: "keyword", Desc: "keyword for record search; required unless --json is used"},
-		{Name: "query", Desc: "deprecated alias for --keyword", Hidden: true},
 		{Name: "search-field", Type: "string_array", Desc: "field ID or name to search; repeat for multiple fields; required unless --json is used"},
 		recordListFieldRefFlag(),
-		{Name: "field-names", Type: "string_array", Hidden: true},
-		{Name: "fields", Type: "string_array", Hidden: true},
 		recordListViewRefFlag(),
 		recordFilterFlag(),
-		recordFilterAliasFlag(),
 		recordSortFlag(),
-		recordSortAliasFlag(),
 		{Name: "offset", Type: "int", Default: "0", Desc: "pagination offset"},
 		{Name: "limit", Type: "int", Default: "10", Desc: "pagination size, range 1-200"},
 		recordReadFormatFlag(),

shortcuts/base/shortcuts.go

@@ -19,7 +19,6 @@ func Shortcuts() []common.Shortcut {
 		BaseTableUpdate,
 		BaseTableDelete,
 		BaseFieldList,
-		BaseFieldListBatch,
 		BaseFieldGet,
 		BaseFieldCreate,
 		BaseFieldUpdate,

shortcuts/base/table_ops.go

@@ -63,8 +63,7 @@ func executeTableList(runtime *common.RuntimeContext) error {
 		offset = 0
 	}
 	limit := common.ParseIntBounded(runtime, "limit", 1, 100)
-	baseToken := runtime.Str("base-token")
-	tables, total, err := listAllTables(runtime, baseToken, offset, limit)
+	tables, total, err := listAllTables(runtime, runtime.Str("base-token"), offset, limit)
 	if err != nil {
 		return err
 	}
@@ -187,24 +186,6 @@ func listEveryField(runtime *common.RuntimeContext, baseToken, tableID string) (
 	return items, nil
 }
 
-func listEveryTable(runtime *common.RuntimeContext, baseToken string) ([]map[string]interface{}, error) {
-	const pageLimit = 100
-	offset := 0
-	items := []map[string]interface{}{}
-	for {
-		batch, total, err := listAllTables(runtime, baseToken, offset, pageLimit)
-		if err != nil {
-			return nil, err
-		}
-		items = append(items, batch...)
-		if len(batch) == 0 || len(batch) < pageLimit || (total > 0 && len(items) >= total) {
-			break
-		}
-		offset += len(batch)
-	}
-	return items, nil
-}
-
 func listEveryView(runtime *common.RuntimeContext, baseToken, tableID string) ([]map[string]interface{}, error) {
 	const pageLimit = 100
 	offset := 0

shortcuts/calendar/calendar_meeting.go

@@ -0,0 +1,235 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// calendar +meeting — get meeting info for calendar events via mget_instance_relation_info
+
+package calendar
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const meetingLogPrefix = "[calendar +meeting]"
+
+var scopesCalendarMeeting = []string{
+	"calendar:calendar:read",
+	"calendar:calendar.event:read",
+	"vc:meeting.meetingevent:read",
+}
+
+// mgetInstanceRelationRequestBody is the request body for mget_instance_relation_info API.
+type mgetInstanceRelationRequestBody struct {
+	InstanceIDs            []string `json:"instance_ids"`
+	NeedMeetingInstanceIDs bool     `json:"need_meeting_instance_ids"`
+	NeedMeetingNotes       bool     `json:"need_meeting_notes"`
+	NeedAIMeetingNotes     bool     `json:"need_ai_meeting_notes"`
+}
+
+// meetingInfoItem represents a single event's meeting info in the output.
+type meetingInfoItem struct {
+	EventID     string `json:"event_id"`
+	MeetingID   string `json:"meeting_id,omitempty"`
+	MeetingNote string `json:"meeting_note,omitempty"`
+	Error       string `json:"error,omitempty"`
+	Hint        string `json:"hint,omitempty"`
+}
+
+// translateFailMsg converts API fail_msg to a user-friendly error message.
+func translateFailMsg(failMsg string) string {
+	switch failMsg {
+	case "No Permission":
+		return "no read permission for this calendar event (not a participant of the event)"
+	case "Not Found":
+		return "event not found on the specified calendar (event ID may be incorrect or does not belong to this calendar)"
+	default:
+		return failMsg
+	}
+}
+
+// fetchEventMeetingInfo queries mget_instance_relation_info for a single event instance.
+func fetchEventMeetingInfo(ctx context.Context, runtime *common.RuntimeContext, instanceID, calendarID string) *meetingInfoItem {
+	body := &mgetInstanceRelationRequestBody{
+		InstanceIDs:            []string{instanceID},
+		NeedMeetingInstanceIDs: true,
+		NeedMeetingNotes:       true,
+		NeedAIMeetingNotes:     true,
+	}
+
+	data, err := runtime.CallAPITyped("POST",
+		fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/mget_instance_relation_info", validate.EncodePathSegment(calendarID)),
+		nil, body)
+	if err != nil {
+		return &meetingInfoItem{EventID: instanceID, Error: err.Error()}
+	}
+
+	// Check for failed instance IDs first
+	if failedIDs, _ := data["failed_instance_ids"].([]any); len(failedIDs) > 0 {
+		for _, raw := range failedIDs {
+			if failInfo, ok := raw.(map[string]any); ok {
+				if failID, _ := failInfo["instance_id"].(string); failID == instanceID {
+					failMsg, _ := failInfo["fail_msg"].(string)
+					return &meetingInfoItem{EventID: instanceID, Error: translateFailMsg(failMsg)}
+				}
+			}
+		}
+	}
+
+	infos, _ := data["instance_relation_infos"].([]any)
+	if len(infos) == 0 {
+		return &meetingInfoItem{EventID: instanceID, Error: "no event relation info found"}
+	}
+
+	info, _ := infos[0].(map[string]any)
+	result := &meetingInfoItem{EventID: instanceID}
+
+	// Extract meeting_id (return first if multiple) — API returns string
+	if rawIDs, _ := info["meeting_instance_ids"].([]any); len(rawIDs) > 0 {
+		if id, ok := rawIDs[0].(string); ok && id != "" {
+			result.MeetingID = id
+		}
+	}
+
+	// Extract meeting_note (return first if multiple)
+	if notes, _ := info["meeting_notes"].([]any); len(notes) > 0 {
+		if note, ok := notes[0].(string); ok && note != "" {
+			result.MeetingNote = note
+		}
+	}
+
+	// Add hints for empty resources (independent checks)
+	var emptyFields []string
+	if result.MeetingID == "" {
+		emptyFields = append(emptyFields, "meeting_id")
+	}
+	if result.MeetingNote == "" {
+		emptyFields = append(emptyFields, "meeting_note")
+	}
+	if len(emptyFields) > 0 {
+		result.Hint = fmt.Sprintf("%s not found for this event", strings.Join(emptyFields, ", "))
+	}
+
+	return result
+}
+
+// CalendarMeeting gets meeting info for calendar events.
+var CalendarMeeting = common.Shortcut{
+	Service:     "calendar",
+	Command:     "+meeting",
+	Description: "Get meeting info for calendar events (meeting_id, meeting_note)",
+	Risk:        "read",
+	Scopes:      []string{"calendar:calendar.event:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "event-ids", Desc: "calendar event instance IDs, comma-separated for batch", Required: true},
+		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
+		ids := common.SplitCSV(runtime.Str("event-ids"))
+		const maxBatchSize = 50
+		if len(ids) > maxBatchSize {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--event-ids: too many IDs (%d), maximum is %d", len(ids), maxBatchSize).WithParam("--event-ids")
+		}
+		// dynamic scope check
+		result, err := runtime.Factory.Credential.ResolveToken(ctx, credential.NewTokenSpec(runtime.As(), runtime.Config.AppID))
+		if err == nil && result != nil && result.Scopes != "" {
+			if missing := auth.MissingScopes(result.Scopes, scopesCalendarMeeting); len(missing) > 0 {
+				return errs.NewPermissionError(errs.SubtypeMissingScope,
+					"missing required scope(s): %s", strings.Join(missing, ", ")).
+					WithHint("run `lark-cli auth login --scope %q` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(missing, " ")).
+					WithMissingScopes(missing...).
+					WithIdentity(string(runtime.As()))
+			}
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		calendarID := runtime.Str("calendar-id")
+		if calendarID == "" {
+			calendarID = "<primary>"
+		}
+		return common.NewDryRunAPI().
+			POST(fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/mget_instance_relation_info", calendarID)).
+			Set("event_ids", common.SplitCSV(runtime.Str("event-ids"))).
+			Set("calendar_id", calendarID)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		errOut := runtime.IO().ErrOut
+		instanceIDs := common.SplitCSV(runtime.Str("event-ids"))
+		calendarID := strings.TrimSpace(runtime.Str("calendar-id"))
+		if calendarID == "" {
+			calendarID = PrimaryCalendarIDStr
+		}
+
+		results := make([]*meetingInfoItem, 0, len(instanceIDs))
+		const batchDelay = 100 * time.Millisecond
+		fmt.Fprintf(errOut, "%s querying %d event_id(s)\n", meetingLogPrefix, len(instanceIDs))
+		for i, id := range instanceIDs {
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+			if i > 0 {
+				time.Sleep(batchDelay)
+			}
+			fmt.Fprintf(errOut, "%s querying event_id=%s ...\n", meetingLogPrefix, id)
+			results = append(results, fetchEventMeetingInfo(ctx, runtime, id, calendarID))
+		}
+
+		successCount := 0
+		for _, r := range results {
+			if r.Error == "" {
+				successCount++
+			}
+		}
+		fmt.Fprintf(errOut, "%s done: %d total, %d succeeded, %d failed\n", meetingLogPrefix, len(results), successCount, len(results)-successCount)
+
+		if successCount == 0 && len(results) > 0 {
+			return runtime.OutPartialFailure(map[string]any{"meetings": results}, &output.Meta{Count: len(results)})
+		}
+
+		outData := map[string]any{"meetings": results}
+		runtime.OutFormat(outData, &output.Meta{Count: len(results)}, func(w io.Writer) {
+			if len(results) == 0 {
+				fmt.Fprintln(w, "No events.")
+				return
+			}
+			var rows []map[string]interface{}
+			for _, r := range results {
+				row := map[string]interface{}{"event_id": r.EventID}
+				if r.Error != "" {
+					row["status"] = "FAIL"
+					row["error"] = r.Error
+				} else {
+					row["status"] = "OK"
+					if r.MeetingID != "" {
+						row["meeting_id"] = r.MeetingID
+					}
+					if r.MeetingNote != "" {
+						row["meeting_note"] = r.MeetingNote
+					}
+					if r.Hint != "" {
+						row["hint"] = r.Hint
+					}
+				}
+				rows = append(rows, row)
+			}
+			output.PrintTable(w, rows)
+			fmt.Fprintf(w, "\n%d event(s), %d succeeded, %d failed\n", len(results), successCount, len(results)-successCount)
+		})
+		return nil
+	},
+}

shortcuts/calendar/calendar_meeting_test.go

@@ -0,0 +1,484 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+var calWarmOnce sync.Once
+
+func calWarmTokenCache(t *testing.T) {
+	t.Helper()
+	calWarmOnce.Do(func() {
+		f, _, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+		reg.Register(&httpmock.Stub{
+			URL:  "/open-apis/test/v1/warm",
+			Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{}},
+		})
+		s := common.Shortcut{
+			Service:   "test",
+			Command:   "+warm",
+			AuthTypes: []string{"bot"},
+			Execute: func(_ context.Context, rctx *common.RuntimeContext) error {
+				_, err := rctx.CallAPI("GET", "/open-apis/test/v1/warm", nil, nil)
+				return err
+			},
+		}
+		parent := &cobra.Command{Use: "test"}
+		s.Mount(parent, f)
+		parent.SetArgs([]string{"+warm"})
+		parent.SilenceErrors = true
+		parent.SilenceUsage = true
+		parent.Execute()
+	})
+}
+
+func calDefaultConfig() *core.CliConfig {
+	return &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+		UserOpenId: "ou_testuser",
+	}
+}
+
+func calMountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Factory, stdout *bytes.Buffer) error {
+	t.Helper()
+	calWarmTokenCache(t)
+	parent := &cobra.Command{Use: "calendar"}
+	s.Mount(parent, f)
+	parent.SetArgs(args)
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	if stdout != nil {
+		stdout.Reset()
+	}
+	return parent.Execute()
+}
+
+// ---------------------------------------------------------------------------
+// calendar +meeting tests
+// ---------------------------------------------------------------------------
+
+func mgetInstanceRelationStub(calendarID, instanceID string, meetingIDs []string, meetingNotes []string, aiMeetingNotes []string) *httpmock.Stub {
+	infos := map[string]interface{}{
+		"instance_id": instanceID,
+	}
+	mIDs := make([]interface{}, len(meetingIDs))
+	for i, id := range meetingIDs {
+		mIDs[i] = id
+	}
+	infos["meeting_instance_ids"] = mIDs
+	if len(meetingNotes) > 0 {
+		notes := make([]interface{}, len(meetingNotes))
+		for i, n := range meetingNotes {
+			notes[i] = n
+		}
+		infos["meeting_notes"] = notes
+	}
+	if len(aiMeetingNotes) > 0 {
+		notes := make([]interface{}, len(aiMeetingNotes))
+		for i, n := range aiMeetingNotes {
+			notes[i] = n
+		}
+		infos["ai_meeting_notes"] = notes
+	}
+	return &httpmock.Stub{
+		Method: "POST",
+		URL:    fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/mget_instance_relation_info", calendarID),
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"instance_relation_infos": []interface{}{infos},
+			},
+		},
+	}
+}
+
+func mgetInstanceRelationFailedStub(calendarID, instanceID, failMsg string) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "POST",
+		URL:    fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/mget_instance_relation_info", calendarID),
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"instance_relation_infos": []interface{}{},
+				"failed_instance_ids": []interface{}{
+					map[string]interface{}{
+						"instance_id": instanceID,
+						"fail_msg":    failMsg,
+					},
+				},
+			},
+		},
+	}
+}
+
+func TestMeeting_Validation_MissingEventIDs(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for missing --event-ids")
+	}
+}
+
+func TestMeeting_Validation_BatchLimit(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	ids := make([]string, 51)
+	for i := range ids {
+		ids[i] = fmt.Sprintf("evt%d", i)
+	}
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", strings.Join(ids, ","), "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected batch limit error")
+	}
+	if !strings.Contains(err.Error(), "too many IDs") {
+		t.Errorf("expected 'too many IDs' error, got: %v", err)
+	}
+}
+
+func TestMeeting_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", "evt001", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "mget_instance_relation_info") {
+		t.Errorf("dry-run should show mget API path, got: %s", stdout.String())
+	}
+}
+
+func TestMeeting_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(mgetInstanceRelationStub("primary", "evt_m1", []string{"123456"}, []string{"doc_note1"}, []string{"doc_ai1"}))
+
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", "evt_m1", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	if len(meetings) != 1 {
+		t.Fatalf("expected 1 meeting, got %d", len(meetings))
+	}
+	m, _ := meetings[0].(map[string]any)
+	if m["meeting_id"] != "123456" {
+		t.Errorf("meeting_id = %v, want 123456", m["meeting_id"])
+	}
+	if m["meeting_note"] != "doc_note1" {
+		t.Errorf("meeting_note = %v, want doc_note1", m["meeting_note"])
+	}
+	if _, hasAI := m["ai_meeting_note"]; hasAI {
+		t.Error("ai_meeting_note should not be present in output")
+	}
+}
+
+func TestMeeting_Execute_FailedInstance(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(mgetInstanceRelationFailedStub("primary", "evt_fail", "No Permission"))
+
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", "evt_fail", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	// Verify translated fail_msg appears in output
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err == nil {
+		data, _ := resp["data"].(map[string]any)
+		meetings, _ := data["meetings"].([]any)
+		if len(meetings) > 0 {
+			m, _ := meetings[0].(map[string]any)
+			if errMsg, _ := m["error"].(string); !strings.Contains(errMsg, "no read permission") {
+				t.Errorf("expected translated fail_msg, got: %v", errMsg)
+			}
+		}
+	}
+}
+
+func TestMeeting_Execute_NoMeeting(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(mgetInstanceRelationStub("primary", "evt_nomeet", []string{}, nil, nil))
+
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", "evt_nomeet", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	if len(meetings) != 1 {
+		t.Fatalf("expected 1 meeting, got %d", len(meetings))
+	}
+	m, _ := meetings[0].(map[string]any)
+	if hint, _ := m["hint"].(string); !strings.Contains(hint, "meeting_id") {
+		t.Errorf("expected hint about meeting_id, got: %v", hint)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// calendar +search-event tests
+// ---------------------------------------------------------------------------
+
+func TestSearchEvent_Validation_InvalidTimeRange(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--start", "bad-format", "--end", "2026-04-27", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for invalid --start")
+	}
+	if !strings.Contains(err.Error(), "--start") {
+		t.Errorf("unexpected error: %v", err)
+	}
+}
+
+func TestSearchEvent_Validation_TimeRangeStartAfterEnd(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--start", "2026-04-27", "--end", "2026-04-20", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for start after end")
+	}
+}
+
+func TestSearchEvent_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--query", "周会", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "search_event") {
+		t.Errorf("dry-run should show search_event API path, got: %s", stdout.String())
+	}
+}
+
+func TestSearchEvent_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/primary/events/search_event",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{
+						"display_info": "Q2 周会\n2026-04-23 15:00-16:00",
+						"meta_data": map[string]interface{}{
+							"event_id": "evt_search1",
+							"summary":  "Q2 周会",
+							"start": map[string]interface{}{
+								"date_time": "2026-04-23T15:00:00+08:00",
+								"timezone":  "Asia/Shanghai",
+							},
+							"end": map[string]interface{}{
+								"date_time": "2026-04-23T16:00:00+08:00",
+								"timezone":  "Asia/Shanghai",
+							},
+							"is_all_day": false,
+							"app_link":   "https://applink.feishu.cn/...",
+						},
+					},
+				},
+				"has_more":   false,
+				"page_token": "",
+			},
+		},
+	})
+
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--query", "周会", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	if data["calendar_id"] != "primary" {
+		t.Errorf("calendar_id = %v, want primary", data["calendar_id"])
+	}
+	items, _ := data["items"].([]any)
+	if len(items) != 1 {
+		t.Fatalf("expected 1 item, got %d", len(items))
+	}
+	item, _ := items[0].(map[string]any)
+	if item["event_id"] != "evt_search1" {
+		t.Errorf("event_id = %v, want evt_search1", item["event_id"])
+	}
+	if item["summary"] != "Q2 周会" {
+		t.Errorf("summary = %v, want 'Q2 周会'", item["summary"])
+	}
+}
+
+func TestSearchEvent_Execute_Empty(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/primary/events/search_event",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items":    []interface{}{},
+				"has_more": false,
+			},
+		},
+	})
+
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--query", "nonexistent", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Pure function tests
+// ---------------------------------------------------------------------------
+
+func TestParseSearchEventTimeRange(t *testing.T) {
+	tests := []struct {
+		name    string
+		start   string
+		end     string
+		wantErr bool
+	}{
+		{"empty", "", "", false},
+		{"valid", "2026-04-20", "2026-04-27", false},
+		{"start only defaults end", "2026-04-20", "", false},
+		{"end only defaults start", "", "2026-04-27", false},
+		{"invalid start format", "not-a-date", "2026-04-27", true},
+		{"start after end", "2026-04-27", "2026-04-20", true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("start", "", "")
+			cmd.Flags().String("end", "", "")
+			if tt.start != "" {
+				_ = cmd.Flags().Set("start", tt.start)
+			}
+			if tt.end != "" {
+				_ = cmd.Flags().Set("end", tt.end)
+			}
+			runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+			_, _, err := parseSearchEventTimeRange(runtime)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("parseSearchEventTimeRange() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+
+	t.Run("start only fills end with end-of-day", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "test"}
+		cmd.Flags().String("start", "", "")
+		cmd.Flags().String("end", "", "")
+		_ = cmd.Flags().Set("start", "2026-04-20")
+		runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+		startRFC, endRFC, err := parseSearchEventTimeRange(runtime)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !strings.HasPrefix(startRFC, "2026-04-20T00:00:00") {
+			t.Errorf("start = %s, want 2026-04-20T00:00:00...", startRFC)
+		}
+		if !strings.HasPrefix(endRFC, "2026-04-20T23:59:59") {
+			t.Errorf("end = %s, want 2026-04-20T23:59:59...", endRFC)
+		}
+	})
+
+	t.Run("end only fills start with start-of-day", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "test"}
+		cmd.Flags().String("start", "", "")
+		cmd.Flags().String("end", "", "")
+		_ = cmd.Flags().Set("end", "2026-04-27")
+		runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+		startRFC, endRFC, err := parseSearchEventTimeRange(runtime)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !strings.HasPrefix(startRFC, "2026-04-27T00:00:00") {
+			t.Errorf("start = %s, want 2026-04-27T00:00:00...", startRFC)
+		}
+		if !strings.HasPrefix(endRFC, "2026-04-27T23:59:59") {
+			t.Errorf("end = %s, want 2026-04-27T23:59:59...", endRFC)
+		}
+	})
+}
+
+func TestBuildSearchEventFilter(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("attendee-ids", "", "")
+	_ = cmd.Flags().Set("attendee-ids", "ou_user1,oc_chat1,omm_room1")
+	runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+
+	filter := buildSearchEventFilter(runtime, "", "")
+	if filter == nil {
+		t.Fatal("expected filter to be non-nil")
+	}
+	if len(filter.AttendeeUserIDs) != 1 || filter.AttendeeUserIDs[0] != "ou_user1" {
+		t.Errorf("attendee_user_ids = %v, want [ou_user1]", filter.AttendeeUserIDs)
+	}
+	if len(filter.AttendeeChatIDs) != 1 || filter.AttendeeChatIDs[0] != "oc_chat1" {
+		t.Errorf("attendee_chat_ids = %v, want [oc_chat1]", filter.AttendeeChatIDs)
+	}
+	if len(filter.MeetingRoomIDs) != 1 || filter.MeetingRoomIDs[0] != "omm_room1" {
+		t.Errorf("meeting_room_ids = %v, want [omm_room1]", filter.MeetingRoomIDs)
+	}
+}
+
+func TestBuildSearchEventFilter_Empty(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("attendee-ids", "", "")
+	runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+
+	filter := buildSearchEventFilter(runtime, "", "")
+	if filter != nil {
+		t.Errorf("expected nil for empty filter, got %v", filter)
+	}
+}
+
+func TestBuildSearchEventFilter_TimeRange(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("attendee-ids", "", "")
+	runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+
+	filter := buildSearchEventFilter(runtime, "2026-04-20T00:00:00+08:00", "2026-04-27T23:59:59+08:00")
+	if filter == nil {
+		t.Fatal("expected filter to be non-nil")
+	}
+	if filter.TimeRange == nil {
+		t.Fatal("expected time_range in filter")
+	}
+	if filter.TimeRange.StartTime != "2026-04-20T00:00:00+08:00" {
+		t.Errorf("start_time = %v, want 2026-04-20T00:00:00+08:00", filter.TimeRange.StartTime)
+	}
+}

shortcuts/calendar/calendar_room_find.go

@@ -66,7 +66,8 @@ type roomFindSlot struct {
 type roomFindTimeSlot struct {
 	Start        string                `json:"start,omitempty"`
 	End          string                `json:"end,omitempty"`
-	MeetingRooms []*roomFindSuggestion `json:"meeting_rooms,omitempty"`
+	MeetingRooms []*roomFindSuggestion `json:"meeting_rooms"`
+	Hint         string                `json:"hint,omitempty"`
 }
 
 type roomFindOutput struct {
@@ -103,11 +104,18 @@ func collectRoomFindResults(slots []roomFindSlot, limit int, fetch func(roomFind
 				}
 				return
 			}
-			out.TimeSlots = append(out.TimeSlots, &roomFindTimeSlot{
+			if suggestions == nil {
+				suggestions = []*roomFindSuggestion{}
+			}
+			ts := &roomFindTimeSlot{
 				Start:        slot.Start,
 				End:          slot.End,
 				MeetingRooms: suggestions,
-			})
+			}
+			if len(suggestions) == 0 {
+				ts.Hint = "no meeting room matches the current filters for this slot"
+			}
+			out.TimeSlots = append(out.TimeSlots, ts)
 		}(slot)
 	}
 	wg.Wait()
@@ -374,6 +382,10 @@ var CalendarRoomFind = common.Shortcut{
 			}
 			for _, slot := range out.TimeSlots {
 				fmt.Fprintf(w, "%s - %s\n", slot.Start, slot.End)
+				if len(slot.MeetingRooms) == 0 {
+					fmt.Fprintf(w, "0 meeting room(s) found: %s\n", slot.Hint)
+					continue
+				}
 				var rows []map[string]interface{}
 				for _, room := range slot.MeetingRooms {
 					rows = append(rows, map[string]interface{}{
@@ -384,6 +396,7 @@ var CalendarRoomFind = common.Shortcut{
 					})
 				}
 				output.PrintTable(w, rows)
+				fmt.Fprintf(w, "%d meeting room(s) found\n", len(slot.MeetingRooms))
 				fmt.Fprintln(w)
 			}
 		})

shortcuts/calendar/calendar_room_find_test.go

@@ -4,6 +4,8 @@
 package calendar
 
 import (
+	"encoding/json"
+	"strings"
 	"testing"
 	"time"
 )
@@ -82,3 +84,60 @@ func TestCollectRoomFindResults_LimitsConcurrency(t *testing.T) {
 		t.Fatalf("expected %d time slots, got %d", len(slots), len(out.TimeSlots))
 	}
 }
+
+func TestCollectRoomFindResults_EmptySlotEmitsHintAndArray(t *testing.T) {
+	slots := []roomFindSlot{
+		{Start: "2026-03-27T14:00:00+08:00", End: "2026-03-27T15:00:00+08:00"},
+		{Start: "2026-03-27T15:00:00+08:00", End: "2026-03-27T16:00:00+08:00"},
+	}
+
+	out, err := collectRoomFindResults(slots, 2, func(slot roomFindSlot) ([]*roomFindSuggestion, error) {
+		if strings.HasPrefix(slot.Start, "2026-03-27T14") {
+			return []*roomFindSuggestion{{RoomID: "rm_1", RoomName: "Room A"}}, nil
+		}
+		return nil, nil
+	})
+	if err != nil {
+		t.Fatalf("collectRoomFindResults returned error: %v", err)
+	}
+	if len(out.TimeSlots) != 2 {
+		t.Fatalf("expected 2 time slots, got %d", len(out.TimeSlots))
+	}
+
+	for _, ts := range out.TimeSlots {
+		if ts.MeetingRooms == nil {
+			t.Fatalf("meeting_rooms should be non-nil for slot %s", ts.Start)
+		}
+		switch {
+		case strings.HasPrefix(ts.Start, "2026-03-27T14"):
+			if len(ts.MeetingRooms) != 1 {
+				t.Fatalf("expected 1 room for first slot, got %d", len(ts.MeetingRooms))
+			}
+			if ts.Hint != "" {
+				t.Fatalf("non-empty slot should not carry hint, got %q", ts.Hint)
+			}
+		case strings.HasPrefix(ts.Start, "2026-03-27T15"):
+			if len(ts.MeetingRooms) != 0 {
+				t.Fatalf("expected 0 rooms for empty slot, got %d", len(ts.MeetingRooms))
+			}
+			if ts.Hint == "" {
+				t.Fatal("empty slot should carry a hint explaining the filters")
+			}
+		}
+	}
+
+	emptySlot := out.TimeSlots[0]
+	if !strings.HasPrefix(emptySlot.Start, "2026-03-27T15") {
+		emptySlot = out.TimeSlots[1]
+	}
+	raw, err := json.Marshal(emptySlot)
+	if err != nil {
+		t.Fatalf("marshal empty slot: %v", err)
+	}
+	if !strings.Contains(string(raw), `"meeting_rooms":[]`) {
+		t.Fatalf("expected meeting_rooms:[] in JSON, got %s", raw)
+	}
+	if !strings.Contains(string(raw), `"hint"`) {
+		t.Fatalf("expected hint field in JSON, got %s", raw)
+	}
+}

shortcuts/calendar/calendar_search_event.go

@@ -0,0 +1,351 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// calendar +search-event — search calendar events by keyword, time range, and attendees
+
+package calendar
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const searchEventLogPrefix = "[calendar +search-event]"
+
+const (
+	defaultSearchEventPageSize = 20
+	maxSearchEventPageSize     = 30
+)
+
+var scopesSearchEvent = []string{
+	"calendar:calendar:read",
+	"calendar:calendar.event:read",
+}
+
+// searchEventTimeRange represents the time range filter for search_event API.
+type searchEventTimeRange struct {
+	StartTime string `json:"start_time,omitempty"`
+	EndTime   string `json:"end_time,omitempty"`
+}
+
+// searchEventFilter represents the filter object for the search_event API request.
+type searchEventFilter struct {
+	AttendeeUserIDs []string              `json:"attendee_user_ids,omitempty"`
+	AttendeeChatIDs []string              `json:"attendee_chat_ids,omitempty"`
+	MeetingRoomIDs  []string              `json:"meeting_room_ids,omitempty"`
+	TimeRange       *searchEventTimeRange `json:"time_range,omitempty"`
+}
+
+// searchEventRequestBody is the request body for the search_event API.
+type searchEventRequestBody struct {
+	Query  string             `json:"query"`
+	Filter *searchEventFilter `json:"filter,omitempty"`
+}
+
+// searchEventTimeInfo represents start/end time info in the search result.
+type searchEventTimeInfo struct {
+	Date     string `json:"date,omitempty"`
+	DateTime string `json:"date_time,omitempty"`
+	Timezone string `json:"timezone,omitempty"`
+}
+
+// searchEventItem represents a single event in the search result output.
+type searchEventItem struct {
+	EventID  string               `json:"event_id"`
+	Summary  string               `json:"summary"`
+	Start    *searchEventTimeInfo `json:"start,omitempty"`
+	End      *searchEventTimeInfo `json:"end,omitempty"`
+	IsAllDay bool                 `json:"is_all_day,omitempty"`
+	AppLink  string               `json:"app_link,omitempty"`
+}
+
+// searchEventOutput is the structured output for +search-event.
+type searchEventOutput struct {
+	CalendarID string            `json:"calendar_id"`
+	Items      []searchEventItem `json:"items"`
+	HasMore    bool              `json:"has_more"`
+	PageToken  string            `json:"page_token"`
+}
+
+// parseSearchEventTimeRange parses --start / --end into RFC3339 strings.
+// When only one side is provided, the other defaults to the same day's
+// boundary (start → end-of-day, end → start-of-day).
+func parseSearchEventTimeRange(runtime *common.RuntimeContext) (string, string, error) {
+	startInput := strings.TrimSpace(runtime.Str("start"))
+	endInput := strings.TrimSpace(runtime.Str("end"))
+	if startInput == "" && endInput == "" {
+		return "", "", nil
+	}
+
+	var startSec, endSec int64
+
+	if startInput != "" {
+		ts, err := common.ParseTime(startInput)
+		if err != nil {
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
+		}
+		startSec, _ = strconv.ParseInt(ts, 10, 64)
+	}
+	if endInput != "" {
+		ts, err := common.ParseTime(endInput, "end")
+		if err != nil {
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
+		}
+		endSec, _ = strconv.ParseInt(ts, 10, 64)
+	}
+
+	if startInput == "" {
+		t := time.Unix(endSec, 0).In(time.Local)
+		startSec = time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, t.Location()).Unix()
+	}
+	if endInput == "" {
+		t := time.Unix(startSec, 0).In(time.Local)
+		endSec = time.Date(t.Year(), t.Month(), t.Day(), 23, 59, 59, 0, t.Location()).Unix()
+	}
+
+	if startSec > endSec {
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start must be before --end").WithParam("--start")
+	}
+
+	return time.Unix(startSec, 0).Format(time.RFC3339), time.Unix(endSec, 0).Format(time.RFC3339), nil
+}
+
+// buildSearchEventFilter builds the filter object for the search_event API.
+func buildSearchEventFilter(runtime *common.RuntimeContext, startTime, endTime string) *searchEventFilter {
+	attendeeIDs := common.SplitCSV(runtime.Str("attendee-ids"))
+
+	var userIDs, chatIDs, roomIDs []string
+	for _, id := range attendeeIDs {
+		switch {
+		case strings.HasPrefix(id, "ou_"):
+			userIDs = append(userIDs, id)
+		case strings.HasPrefix(id, "oc_"):
+			chatIDs = append(chatIDs, id)
+		case strings.HasPrefix(id, "omm_"):
+			roomIDs = append(roomIDs, id)
+		default:
+			userIDs = append(userIDs, id)
+		}
+	}
+
+	var tr *searchEventTimeRange
+	if startTime != "" || endTime != "" {
+		tr = &searchEventTimeRange{StartTime: startTime, EndTime: endTime}
+	}
+
+	if len(userIDs) == 0 && len(chatIDs) == 0 && len(roomIDs) == 0 && tr == nil {
+		return nil
+	}
+	return &searchEventFilter{
+		AttendeeUserIDs: userIDs,
+		AttendeeChatIDs: chatIDs,
+		MeetingRoomIDs:  roomIDs,
+		TimeRange:       tr,
+	}
+}
+
+// extractTimeInfo extracts time info from a meta_data start/end map.
+func extractTimeInfo(m map[string]any) *searchEventTimeInfo {
+	if m == nil {
+		return nil
+	}
+	info := &searchEventTimeInfo{}
+	if v, ok := m["date"].(string); ok && v != "" {
+		info.Date = v
+	}
+	if v, ok := m["date_time"].(string); ok && v != "" {
+		info.DateTime = v
+	}
+	if v, ok := m["timezone"].(string); ok && v != "" {
+		info.Timezone = v
+	}
+	if info.Date == "" && info.DateTime == "" {
+		return nil
+	}
+	return info
+}
+
+// CalendarSearchEvent searches calendar events by keyword, time range, and attendees.
+var CalendarSearchEvent = common.Shortcut{
+	Service:     "calendar",
+	Command:     "+search-event",
+	Description: "Search calendar events by keyword, time range, and attendees",
+	Risk:        "read",
+	Scopes:      []string{"calendar:calendar.event:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
+		{Name: "query", Desc: "search keyword"},
+		{Name: "attendee-ids", Desc: "attendee IDs, comma-separated (supports user ou_, chat oc_, room omm_)"},
+		{Name: "start", Desc: "search time range start (ISO 8601 or YYYY-MM-DD)"},
+		{Name: "end", Desc: "search time range end (ISO 8601 or YYYY-MM-DD)"},
+		{Name: "page-token", Desc: "page token for next page"},
+		{Name: "page-size", Default: "20", Desc: "page size, 1-30 (default 20)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
+		if _, _, err := parseSearchEventTimeRange(runtime); err != nil {
+			return err
+		}
+		if _, err := common.ValidatePageSizeTyped(runtime, "page-size", defaultSearchEventPageSize, 1, maxSearchEventPageSize); err != nil {
+			return err
+		}
+		// dynamic scope check
+		result, err := runtime.Factory.Credential.ResolveToken(ctx, credential.NewTokenSpec(runtime.As(), runtime.Config.AppID))
+		if err == nil && result != nil && result.Scopes != "" {
+			if missing := auth.MissingScopes(result.Scopes, scopesSearchEvent); len(missing) > 0 {
+				return errs.NewPermissionError(errs.SubtypeMissingScope,
+					"missing required scope(s): %s", strings.Join(missing, ", ")).
+					WithHint("run `lark-cli auth login --scope %q` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(missing, " ")).
+					WithMissingScopes(missing...).
+					WithIdentity(string(runtime.As()))
+			}
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		calendarID := runtime.Str("calendar-id")
+		if calendarID == "" {
+			calendarID = "<primary>"
+		}
+		return common.NewDryRunAPI().
+			POST(fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/search_event", calendarID)).
+			Set("calendar_id", calendarID)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		calendarID := strings.TrimSpace(runtime.Str("calendar-id"))
+		if calendarID == "" {
+			calendarID = PrimaryCalendarIDStr
+		}
+
+		startTime, endTime, err := parseSearchEventTimeRange(runtime)
+		if err != nil {
+			return err
+		}
+
+		// Build request body — always send query (even if empty)
+		body := &searchEventRequestBody{
+			Query: strings.TrimSpace(runtime.Str("query")),
+		}
+		if filter := buildSearchEventFilter(runtime, startTime, endTime); filter != nil {
+			body.Filter = filter
+		}
+
+		// Build query params
+		params := map[string]any{}
+		pageSize, _ := strconv.Atoi(strings.TrimSpace(runtime.Str("page-size")))
+		if pageSize <= 0 {
+			pageSize = defaultSearchEventPageSize
+		}
+		params["page_size"] = strconv.Itoa(pageSize)
+		if pt := strings.TrimSpace(runtime.Str("page-token")); pt != "" {
+			params["page_token"] = pt
+		}
+
+		data, err := runtime.CallAPITyped("POST",
+			fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/search_event", validate.EncodePathSegment(calendarID)),
+			params, body)
+		if err != nil {
+			return err
+		}
+		if data == nil {
+			data = map[string]any{}
+		}
+
+		items := common.GetSlice(data, "items")
+		hasMore, _ := data["has_more"].(bool)
+		pageToken, _ := data["page_token"].(string)
+
+		// Transform items to structured output
+		outItems := make([]searchEventItem, 0, len(items))
+		for _, raw := range items {
+			item, _ := raw.(map[string]any)
+			if item == nil {
+				continue
+			}
+			meta, _ := item["meta_data"].(map[string]any)
+			out := searchEventItem{}
+			if meta != nil {
+				if v, ok := meta["event_id"].(string); ok {
+					out.EventID = v
+				}
+				if v, ok := meta["summary"].(string); ok {
+					out.Summary = v
+				}
+				if v, ok := meta["is_all_day"].(bool); ok {
+					out.IsAllDay = v
+				}
+				if v, ok := meta["app_link"].(string); ok {
+					out.AppLink = v
+				}
+				if start, ok := meta["start"].(map[string]any); ok {
+					out.Start = extractTimeInfo(start)
+				}
+				if end, ok := meta["end"].(map[string]any); ok {
+					out.End = extractTimeInfo(end)
+				}
+			}
+			outItems = append(outItems, out)
+		}
+
+		outData := searchEventOutput{
+			CalendarID: calendarID,
+			Items:      outItems,
+			HasMore:    hasMore,
+			PageToken:  pageToken,
+		}
+
+		runtime.OutFormat(outData, &output.Meta{Count: len(outItems)}, func(w io.Writer) {
+			if len(outItems) == 0 {
+				fmt.Fprintln(w, "No events found.")
+				return
+			}
+			var rows []map[string]interface{}
+			for _, item := range outItems {
+				row := map[string]interface{}{
+					"event_id": item.EventID,
+					"summary":  common.TruncateStr(item.Summary, 40),
+				}
+				if item.Start != nil {
+					if item.Start.DateTime != "" {
+						row["start"] = item.Start.DateTime
+					} else if item.Start.Date != "" {
+						row["start"] = item.Start.Date
+					}
+				}
+				if item.End != nil {
+					if item.End.DateTime != "" {
+						row["end"] = item.End.DateTime
+					} else if item.End.Date != "" {
+						row["end"] = item.End.Date
+					}
+				}
+				if item.IsAllDay {
+					row["is_all_day"] = true
+				}
+				rows = append(rows, row)
+			}
+			output.PrintTable(w, rows)
+			fmt.Fprintf(w, "\n%d event(s) found\n", len(outItems))
+		})
+
+		if hasMore && runtime.Format != "json" && runtime.Format != "" {
+			fmt.Fprintf(runtime.IO().Out, "\n(more available, page_token: %s)\n", pageToken)
+		}
+		return nil
+	},
+}

shortcuts/calendar/calendar_test.go

@@ -2234,10 +2234,10 @@ func TestResolveStartEnd_ExplicitValues(t *testing.T) {
 // Shortcuts() registration test
 // ---------------------------------------------------------------------------
 
-func TestShortcuts_Returns7(t *testing.T) {
+func TestShortcuts_Returns9(t *testing.T) {
 	shortcuts := Shortcuts()
-	if len(shortcuts) != 7 {
-		t.Fatalf("expected 7 shortcuts, got %d", len(shortcuts))
+	if len(shortcuts) != 9 {
+		t.Fatalf("expected 9 shortcuts, got %d", len(shortcuts))
 	}
 
 	names := map[string]bool{}

shortcuts/calendar/shortcuts.go

@@ -15,5 +15,7 @@ func Shortcuts() []common.Shortcut {
 		CalendarRoomFind,
 		CalendarRsvp,
 		CalendarSuggestion,
+		CalendarMeeting,
+		CalendarSearchEvent,
 	}
 }

shortcuts/drive/drive_import.go

@@ -31,10 +31,7 @@ var DriveImport = common.Shortcut{
 		{Name: "type", Desc: "target document type (docx, sheet, bitable, slides)", Required: true},
 		{Name: "folder-token", Desc: "target folder token (omit for root folder; API accepts empty mount_key as root)"},
 		{Name: "name", Desc: "imported file name (default: local file name without extension)"},
-		{Name: "target-token", Desc: "existing token to import data into (only for type=bitable); verify the returned verification_token, not the import task token"},
-	},
-	Tips: []string{
-		"When --target-token is set, data is mounted into that existing Base; verify output.verification_token with lark-cli base +base-get.",
+		{Name: "target-token", Desc: "existing token to import data into (only for type=bitable); when set, data is mounted into this bitable instead of creating a new one"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateDriveImportSpec(driveImportSpec{
@@ -142,14 +139,6 @@ var DriveImport = common.Shortcut{
 		if status.Extra != nil {
 			out["extra"] = status.Extra
 		}
-		if spec.TargetToken != "" {
-			out["target_token"] = spec.TargetToken
-			out["verification_token"] = spec.TargetToken
-			if u := common.BuildResourceURL(runtime.Config.Brand, "bitable", spec.TargetToken); u != "" {
-				out["verification_url"] = u
-			}
-			out["verify_hint"] = fmt.Sprintf("because --target-token was used, verify the existing target Base with: lark-cli base +base-get --base-token %s", spec.TargetToken)
-		}
 		if !ready {
 			nextCommand := driveImportTaskResultCommand(ticket)
 			fmt.Fprintf(runtime.IO().ErrOut, "Import task is still in progress. Continue with: %s\n", nextCommand)

shortcuts/drive/drive_import_test.go

@@ -762,43 +762,3 @@ func TestDriveImportFallbackURLForSlides(t *testing.T) {
 		t.Fatalf("data.url = %#v, want %q (slides fallback)", got, want)
 	}
 }
-
-func TestDriveImportTargetTokenOutputsVerificationToken(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveImportTestConfig("target-token"))
-	driveImportMockEnv(t, reg, "ticket_target", map[string]interface{}{
-		"token":      "bascn_backend_result",
-		"type":       "bitable",
-		"job_status": float64(0),
-	})
-
-	tmpDir := t.TempDir()
-	origDir, _ := os.Getwd()
-	if err := os.Chdir(tmpDir); err != nil {
-		t.Fatalf("Chdir: %v", err)
-	}
-	defer os.Chdir(origDir)
-	if err := os.WriteFile("snapshot.base", []byte("fake-base"), 0o644); err != nil {
-		t.Fatalf("WriteFile: %v", err)
-	}
-
-	if err := mountAndRunDrive(t, DriveImport, []string{
-		"+import", "--file", "snapshot.base", "--type", "bitable", "--target-token", "bascn_target", "--as", "user",
-	}, f, stdout); err != nil {
-		t.Fatalf("import should succeed, got: %v", err)
-	}
-
-	data := decodeDriveEnvelope(t, stdout)
-	if got, want := data["token"], "bascn_backend_result"; got != want {
-		t.Fatalf("data.token = %#v, want backend result token %q", got, want)
-	}
-	if got, want := data["verification_token"], "bascn_target"; got != want {
-		t.Fatalf("data.verification_token = %#v, want target token %q", got, want)
-	}
-	if got, want := data["target_token"], "bascn_target"; got != want {
-		t.Fatalf("data.target_token = %#v, want target token %q", got, want)
-	}
-	hint, _ := data["verify_hint"].(string)
-	if !strings.Contains(hint, "lark-cli base +base-get --base-token bascn_target") {
-		t.Fatalf("verify_hint = %q, want target-token verification command", hint)
-	}
-}

shortcuts/minutes/minutes_detail.go

@@ -0,0 +1,285 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// minutes +detail — query minute details with selective artifact flags
+
+package minutes
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const minutesDetailLogPrefix = "[minutes +detail]"
+
+// Error codes from the minutes API.
+const minutesDetailNoReadPermissionCode = 2091005
+
+var validMinuteTokenDetail = regexp.MustCompile(`^[a-z0-9]+$`)
+
+var scopesDetailMinuteTokens = []string{
+	"minutes:minutes.basic:read",
+	"minutes:minutes.artifacts:read",
+}
+
+// minuteDetailItem represents a single minute detail result.
+type minuteDetailItem struct {
+	MinuteToken string         `json:"minute_token"`
+	Title       string         `json:"title"`
+	NoteID      string         `json:"note_id"`
+	Artifacts   map[string]any `json:"artifacts,omitempty"`
+	Error       string         `json:"error,omitempty"`
+}
+
+// fetchMinuteDetail queries a single minute's metadata and selected artifacts.
+func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minuteToken string) *minuteDetailItem {
+	data, err := runtime.CallAPITyped(http.MethodGet,
+		fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil)
+	if err != nil {
+		result := &minuteDetailItem{MinuteToken: minuteToken}
+		if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailNoReadPermissionCode {
+			result.Error = fmt.Sprintf("No read permission for minute %s. Ask the minute owner for minute file read permission", minuteToken)
+		} else {
+			result.Error = fmt.Sprintf("failed to query minute: %v", err)
+		}
+		return result
+	}
+
+	minute, _ := data["minute"].(map[string]any)
+	if minute == nil {
+		return &minuteDetailItem{MinuteToken: minuteToken, Error: "minute not found"}
+	}
+
+	result := &minuteDetailItem{MinuteToken: minuteToken}
+	if v, ok := minute["title"].(string); ok && v != "" {
+		result.Title = v
+	}
+	if v, ok := minute["note_id"].(string); ok && v != "" {
+		result.NoteID = v
+	}
+
+	// Fetch artifacts selectively based on flags
+	needSummary := runtime.Bool("summary")
+	needTodo := runtime.Bool("todo")
+	needChapter := runtime.Bool("chapter")
+	needTranscript := runtime.Bool("transcript")
+	needKeyword := runtime.Bool("keyword")
+
+	if needSummary || needTodo || needChapter || needTranscript || needKeyword {
+		artData, err := runtime.CallAPITyped(http.MethodGet,
+			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/artifacts", validate.EncodePathSegment(minuteToken)), nil, nil)
+		if err != nil {
+			fmt.Fprintf(runtime.IO().ErrOut, "%s failed to fetch artifacts for %s: %v\n", minutesDetailLogPrefix, minuteToken, err)
+		} else {
+			artifacts := make(map[string]any)
+			if needSummary {
+				if v, ok := artData["summary"].(string); ok && v != "" {
+					artifacts["summary"] = v
+				} else {
+					artifacts["summary"] = ""
+				}
+			}
+			if needTodo {
+				if v, ok := artData["minute_todos"].([]any); ok && len(v) > 0 {
+					artifacts["todos"] = v
+				} else {
+					artifacts["todos"] = []any{}
+				}
+			}
+			if needChapter {
+				if v, ok := artData["minute_chapters"].([]any); ok && len(v) > 0 {
+					artifacts["chapters"] = v
+				} else {
+					artifacts["chapters"] = []any{}
+				}
+			}
+			if needKeyword {
+				if v, ok := artData["keywords"].([]any); ok && len(v) > 0 {
+					artifacts["keywords"] = v
+				} else {
+					artifacts["keywords"] = []any{}
+				}
+			}
+			if needTranscript {
+				if v, ok := artData["transcript"].(string); ok && v != "" {
+					if path := saveDetailTranscript(runtime, minuteToken, result.Title, []byte(v)); path != "" {
+						artifacts["transcript_file"] = path
+					} else {
+						artifacts["transcript_file"] = ""
+					}
+				} else {
+					artifacts["transcript_file"] = ""
+				}
+			}
+			result.Artifacts = artifacts
+		}
+	}
+
+	return result
+}
+
+// saveDetailTranscript persists transcript bytes to the canonical artifact path.
+func saveDetailTranscript(runtime *common.RuntimeContext, minuteToken, title string, content []byte) string {
+	errOut := runtime.IO().ErrOut
+	dirName := common.DefaultMinuteArtifactDir(minuteToken)
+	transcriptPath := filepath.Join(dirName, common.DefaultTranscriptFileName)
+
+	if !runtime.Bool("overwrite") {
+		if _, statErr := runtime.FileIO().Stat(transcriptPath); statErr == nil {
+			fmt.Fprintf(errOut, "%s transcript already exists: %s (use --overwrite to replace)\n", minutesDetailLogPrefix, transcriptPath)
+			return transcriptPath
+		}
+	}
+
+	fmt.Fprintf(errOut, "%s writing transcript: %s\n", minutesDetailLogPrefix, transcriptPath)
+	if _, err := runtime.FileIO().Save(transcriptPath, fileio.SaveOptions{}, bytes.NewReader(content)); err != nil {
+		fmt.Fprintf(errOut, "%s failed to write transcript: %v\n", minutesDetailLogPrefix, err)
+		return ""
+	}
+	return transcriptPath
+}
+
+// MinutesDetail queries minute details with selective artifact flags.
+var MinutesDetail = common.Shortcut{
+	Service:     "minutes",
+	Command:     "+detail",
+	Description: "Query minute details with selective artifact flags (summary, todo, chapter, transcript, keyword)",
+	Risk:        "read",
+	Scopes:      []string{"minutes:minutes.basic:read", "minutes:minutes.artifacts:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "minute-tokens", Desc: "minute tokens, comma-separated for batch", Required: true},
+		{Name: "summary", Type: "bool", Desc: "include summary"},
+		{Name: "todo", Type: "bool", Desc: "include todos"},
+		{Name: "chapter", Type: "bool", Desc: "include chapters"},
+		{Name: "transcript", Type: "bool", Desc: "include transcript (saved to file)"},
+		{Name: "keyword", Type: "bool", Desc: "include keywords"},
+		{Name: "overwrite", Type: "bool", Desc: "overwrite existing transcript files"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		tokens := common.SplitCSV(runtime.Str("minute-tokens"))
+		const maxBatchSize = 50
+		if len(tokens) > maxBatchSize {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-tokens: too many tokens (%d), maximum is %d", len(tokens), maxBatchSize).WithParam("--minute-tokens")
+		}
+		for _, token := range tokens {
+			if !validMinuteTokenDetail.MatchString(token) {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid minute token %q: must contain only lowercase alphanumeric characters", token).WithParam("--minute-tokens")
+			}
+		}
+		// dynamic scope check
+		result, err := runtime.Factory.Credential.ResolveToken(ctx, credential.NewTokenSpec(runtime.As(), runtime.Config.AppID))
+		if err == nil && result != nil && result.Scopes != "" {
+			if missing := auth.MissingScopes(result.Scopes, scopesDetailMinuteTokens); len(missing) > 0 {
+				return errs.NewPermissionError(errs.SubtypeMissingScope,
+					"missing required scope(s): %s", strings.Join(missing, ", ")).
+					WithHint("run `lark-cli auth login --scope %q` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(missing, " ")).
+					WithMissingScopes(missing...).
+					WithIdentity(string(runtime.As()))
+			}
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		tokens := runtime.Str("minute-tokens")
+		d := common.NewDryRunAPI().
+			GET("/open-apis/minutes/v1/minutes/{minute_token}").
+			Set("minute_tokens", common.SplitCSV(tokens))
+
+		if runtime.Bool("summary") || runtime.Bool("todo") || runtime.Bool("chapter") || runtime.Bool("transcript") || runtime.Bool("keyword") {
+			d.GET("/open-apis/minutes/v1/minutes/{minute_token}/artifacts")
+		}
+		return d
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		errOut := runtime.IO().ErrOut
+		minuteTokens := common.SplitCSV(runtime.Str("minute-tokens"))
+		results := make([]*minuteDetailItem, 0, len(minuteTokens))
+
+		const batchDelay = 100 * time.Millisecond
+		fmt.Fprintf(errOut, "%s querying %d minute_token(s)\n", minutesDetailLogPrefix, len(minuteTokens))
+		for i, token := range minuteTokens {
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+			if i > 0 {
+				time.Sleep(batchDelay)
+			}
+			fmt.Fprintf(errOut, "%s querying minute_token=%s ...\n", minutesDetailLogPrefix, token)
+			results = append(results, fetchMinuteDetail(ctx, runtime, token))
+		}
+
+		successCount := 0
+		for _, r := range results {
+			if r.Error == "" {
+				successCount++
+			}
+		}
+		fmt.Fprintf(errOut, "%s done: %d total, %d succeeded, %d failed\n", minutesDetailLogPrefix, len(results), successCount, len(results)-successCount)
+
+		if successCount == 0 && len(results) > 0 {
+			return runtime.OutPartialFailure(map[string]any{"minutes": results}, &output.Meta{Count: len(results)})
+		}
+
+		outData := map[string]any{"minutes": results}
+		runtime.OutFormat(outData, &output.Meta{Count: len(results)}, func(w io.Writer) {
+			if len(results) == 0 {
+				fmt.Fprintln(w, "No minutes.")
+				return
+			}
+			var rows []map[string]interface{}
+			for _, r := range results {
+				row := map[string]interface{}{"minute_token": r.MinuteToken}
+				if r.Error != "" {
+					row["status"] = "FAIL"
+					row["error"] = r.Error
+				} else {
+					row["status"] = "OK"
+					row["title"] = r.Title
+					row["note_id"] = r.NoteID
+					if len(r.Artifacts) > 0 {
+						var parts []string
+						if _, ok := r.Artifacts["summary"]; ok {
+							parts = append(parts, "summary")
+						}
+						if _, ok := r.Artifacts["todos"]; ok {
+							parts = append(parts, "todo")
+						}
+						if _, ok := r.Artifacts["chapters"]; ok {
+							parts = append(parts, "chapter")
+						}
+						if _, ok := r.Artifacts["keywords"]; ok {
+							parts = append(parts, "keyword")
+						}
+						if _, ok := r.Artifacts["transcript_file"]; ok {
+							parts = append(parts, "transcript")
+						}
+						if len(parts) > 0 {
+							row["artifacts"] = strings.Join(parts, ", ")
+						}
+					}
+				}
+				rows = append(rows, row)
+			}
+			output.PrintTable(w, rows)
+			fmt.Fprintf(w, "\n%d minute(s), %d succeeded, %d failed\n", len(results), successCount, len(results)-successCount)
+		})
+		return nil
+	},
+}

shortcuts/minutes/minutes_detail_test.go

@@ -0,0 +1,372 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+var detailWarmOnce sync.Once
+
+func detailWarmTokenCache(t *testing.T) {
+	t.Helper()
+	detailWarmOnce.Do(func() {
+		f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+		reg.Register(&httpmock.Stub{
+			URL:  "/open-apis/test/v1/warm",
+			Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{}},
+		})
+		s := common.Shortcut{
+			Service:   "test",
+			Command:   "+warm",
+			AuthTypes: []string{"bot"},
+			Execute: func(_ context.Context, rctx *common.RuntimeContext) error {
+				_, err := rctx.CallAPI("GET", "/open-apis/test/v1/warm", nil, nil)
+				return err
+			},
+		}
+		parent := &cobra.Command{Use: "test"}
+		s.Mount(parent, f)
+		parent.SetArgs([]string{"+warm"})
+		parent.SilenceErrors = true
+		parent.SilenceUsage = true
+		parent.Execute()
+	})
+}
+
+func detailMountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Factory, stdout *bytes.Buffer) error {
+	t.Helper()
+	detailWarmTokenCache(t)
+	parent := &cobra.Command{Use: "minutes"}
+	s.Mount(parent, f)
+	parent.SetArgs(args)
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	if stdout != nil {
+		stdout.Reset()
+	}
+	return parent.Execute()
+}
+
+func detailBotExec(t *testing.T, name string, f *cmdutil.Factory, fn func(context.Context, *common.RuntimeContext) error) error {
+	t.Helper()
+	detailWarmTokenCache(t)
+	s := common.Shortcut{
+		Service:   "test",
+		Command:   "+" + name,
+		AuthTypes: []string{"bot"},
+		HasFormat: true,
+		Execute:   fn,
+	}
+	parent := &cobra.Command{Use: "minutes"}
+	s.Mount(parent, f)
+	parent.SetArgs([]string{"+" + name, "--format", "json"})
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	return parent.Execute()
+}
+
+// ---------------------------------------------------------------------------
+// Validation tests
+// ---------------------------------------------------------------------------
+
+func detailMinuteGetStub(token, noteID, title string) *httpmock.Stub {
+	minute := map[string]interface{}{"title": title}
+	if noteID != "" {
+		minute["note_id"] = noteID
+	}
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/minutes/v1/minutes/" + token,
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"minute": minute},
+		},
+	}
+}
+
+func detailArtifactsStub(token, transcript string) *httpmock.Stub {
+	data := map[string]interface{}{
+		"summary":         "Test summary content",
+		"minute_todos":    []interface{}{map[string]interface{}{"content": "Buy milk"}},
+		"minute_chapters": []interface{}{map[string]interface{}{"title": "Intro", "summary_content": "Opening"}},
+		"keywords":        []interface{}{"budget", "roadmap"},
+	}
+	if transcript != "" {
+		data["transcript"] = transcript
+	}
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/minutes/v1/minutes/" + token + "/artifacts",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": data,
+		},
+	}
+}
+
+func TestDetail_Validation_MissingMinuteTokens(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for missing --minute-tokens")
+	}
+}
+
+func TestDetail_Validation_InvalidToken(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "INVALID!", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for invalid token")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if ve.Param != "--minute-tokens" {
+		t.Errorf("Param = %q, want --minute-tokens", ve.Param)
+	}
+}
+
+func TestDetail_Validation_BatchLimit(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	tokens := make([]string, 51)
+	for i := range tokens {
+		tokens[i] = fmt.Sprintf("tok%d", i)
+	}
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", strings.Join(tokens, ","), "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected batch limit error")
+	}
+	if !strings.Contains(err.Error(), "too many tokens") {
+		t.Errorf("expected 'too many tokens' error, got: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// DryRun tests
+// ---------------------------------------------------------------------------
+
+func TestDetail_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tok001", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "/open-apis/minutes/v1/minutes/") {
+		t.Errorf("dry-run should show minutes API path, got: %s", stdout.String())
+	}
+}
+
+func TestDetail_DryRun_WithArtifactFlags(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tok001", "--summary", "--todo", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "artifacts") {
+		t.Errorf("dry-run should show artifacts API path when artifact flags are set, got: %s", stdout.String())
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execute tests with mocked HTTP
+// ---------------------------------------------------------------------------
+
+func TestDetail_Execute_BasicInfo(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("tokbasic", "", "Test Meeting"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokbasic", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	minutes, _ := data["minutes"].([]any)
+	if len(minutes) != 1 {
+		t.Fatalf("expected 1 minute, got %d", len(minutes))
+	}
+	m, _ := minutes[0].(map[string]any)
+	if m["minute_token"] != "tokbasic" {
+		t.Errorf("minute_token = %v, want tokbasic", m["minute_token"])
+	}
+	if m["title"] != "Test Meeting" {
+		t.Errorf("title = %v, want Test Meeting", m["title"])
+	}
+	if _, ok := m["note_id"]; ok {
+		t.Errorf("note_id should be omitted when minute has no note_id, got %v", m["note_id"])
+	}
+}
+
+func TestDetail_Execute_WithSummaryAndTodo(t *testing.T) {
+	chdirForDetailTest(t)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("tokart", "note_art", "Artifact Meeting"))
+	reg.Register(detailArtifactsStub("tokart", ""))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokart", "--summary", "--todo", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	minutes, _ := data["minutes"].([]any)
+	if len(minutes) != 1 {
+		t.Fatalf("expected 1 minute, got %d", len(minutes))
+	}
+	m, _ := minutes[0].(map[string]any)
+	if m["note_id"] != "note_art" {
+		t.Errorf("note_id = %v, want note_art", m["note_id"])
+	}
+	arts, _ := m["artifacts"].(map[string]any)
+	if arts == nil {
+		t.Fatal("expected artifacts to be present")
+	}
+	if _, ok := arts["summary"]; !ok {
+		t.Error("expected summary in artifacts")
+	}
+	if _, ok := arts["todos"]; !ok {
+		t.Error("expected todos in artifacts")
+	}
+	// chapter and keywords should NOT be present since flags not set
+	if _, ok := arts["chapters"]; ok {
+		t.Error("chapters should not be present when --chapter not set")
+	}
+	if _, ok := arts["keywords"]; ok {
+		t.Error("keywords should not be present when --keyword not set")
+	}
+}
+
+func TestDetail_Execute_NoArtifactFlags(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("toknoart", "", "No Artifacts"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "toknoart", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	minutes, _ := data["minutes"].([]any)
+	if len(minutes) != 1 {
+		t.Fatalf("expected 1 minute, got %d", len(minutes))
+	}
+	m, _ := minutes[0].(map[string]any)
+	if _, ok := m["artifacts"]; ok {
+		t.Error("artifacts should not be present when no artifact flags set")
+	}
+}
+
+func TestDetail_Execute_Transcript(t *testing.T) {
+	chdirForDetailTest(t)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("toktrans", "", "Transcript Meeting"))
+	reg.Register(detailArtifactsStub("toktrans", "speaker1: hello world\n"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "toktrans", "--transcript", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Check transcript file was saved
+	wantPath := "minutes/toktrans/transcript.txt"
+	data, err := os.ReadFile(wantPath)
+	if err != nil {
+		t.Fatalf("expected file at %s: %v", wantPath, err)
+	}
+	if string(data) != "speaker1: hello world\n" {
+		t.Errorf("content mismatch: %q", string(data))
+	}
+}
+
+func TestDetail_Execute_MinuteNotFound(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/minutes/v1/minutes/tokbad",
+		Body:   map[string]interface{}{"code": 2091004, "msg": "not found"},
+	})
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokbad", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Pure function tests
+// ---------------------------------------------------------------------------
+
+func TestValidMinuteTokenDetail(t *testing.T) {
+	tests := []struct {
+		token string
+		valid bool
+	}{
+		{"abc123", true},
+		{"obcnmgn1429t5xt9j82i1p3h", true},
+		{"INVALID!", false},
+		{"has-space", false},
+		{"", false},
+	}
+	for _, tt := range tests {
+		got := validMinuteTokenDetail.MatchString(tt.token)
+		if got != tt.valid {
+			t.Errorf("validMinuteTokenDetail(%q) = %v, want %v", tt.token, got, tt.valid)
+		}
+	}
+}
+
+// chdirForDetailTest switches cwd to a temp dir for the test.
+func chdirForDetailTest(t *testing.T) string {
+	t.Helper()
+	orig, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	dir := t.TempDir()
+	if err := os.Chdir(dir); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+	t.Cleanup(func() { os.Chdir(orig) })
+	return dir
+}

shortcuts/minutes/minutes_search.go

@@ -184,12 +184,6 @@ func minuteSearchAppLink(item map[string]interface{}) string {
 	return common.GetString(meta, "app_link")
 }
 
-// minuteSearchAvatar extracts the avatar URL from a search result item.
-func minuteSearchAvatar(item map[string]interface{}) string {
-	meta := common.GetMap(item, "meta_data")
-	return common.GetString(meta, "avatar")
-}
-
 // buildMinuteSearchRows converts API items into pretty output rows.
 func buildMinuteSearchRows(items []interface{}) []map[string]interface{} {
 	rows := make([]map[string]interface{}, 0, len(items))
@@ -203,12 +197,27 @@ func buildMinuteSearchRows(items []interface{}) []map[string]interface{} {
 			"display_info": common.TruncateStr(minuteSearchDisplayInfo(item), 40),
 			"description":  common.TruncateStr(minuteSearchDescription(item), 40),
 			"app_link":     common.TruncateStr(minuteSearchAppLink(item), 80),
-			"avatar":       common.TruncateStr(minuteSearchAvatar(item), 80),
 		})
 	}
 	return rows
 }
 
+// stripAvatarFromItems removes meta_data.avatar from each search item in place
+// so the structured output does not surface avatars to AI agents.
+func stripAvatarFromItems(items []interface{}) {
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		if item == nil {
+			continue
+		}
+		meta, _ := item["meta_data"].(map[string]interface{})
+		if meta == nil {
+			continue
+		}
+		delete(meta, "avatar")
+	}
+}
+
 // MinutesSearch searches minutes by keyword, owners, participants, and time range.
 var MinutesSearch = common.Shortcut{
 	Service:     "minutes",
@@ -298,13 +307,13 @@ var MinutesSearch = common.Shortcut{
 		}
 
 		items := minuteSearchItems(data)
+		stripAvatarFromItems(items)
 		hasMore, _ := data["has_more"].(bool)
 		pageToken, _ := data["page_token"].(string)
 		rows := buildMinuteSearchRows(items)
 
 		outData := map[string]interface{}{
 			"items":      items,
-			"total":      data["total"],
 			"has_more":   data["has_more"],
 			"page_token": data["page_token"],
 		}

shortcuts/minutes/minutes_search_test.go

@@ -526,7 +526,7 @@ func TestMinutesSearchExecuteRendersRowsAndMoreHint(t *testing.T) {
 	}
 
 	out := stdout.String()
-	for _, want := range []string{"minute_1", "周会摘要", "周会纪要", "https://meetings.feishu.cn/minutes/obcn123", "https://p3-lark-file.byteimg.com/img/xxxx.jpg", "next_token", "more available"} {
+	for _, want := range []string{"minute_1", "周会摘要", "周会纪要", "https://meetings.feishu.cn/minutes/obcn123", "next_token", "more available"} {
 		if !strings.Contains(out, want) {
 			t.Fatalf("output missing %q, got: %s", want, out)
 		}
@@ -663,7 +663,6 @@ func TestMinuteSearchFieldExtractors(t *testing.T) {
 		"meta_data": map[string]interface{}{
 			"description": "周会纪要",
 			"app_link":    "https://meetings.feishu.cn/minutes/obcn123",
-			"avatar":      "https://p3-lark-file.byteimg.com/img/xxxx.jpg",
 		},
 	}
 
@@ -679,9 +678,6 @@ func TestMinuteSearchFieldExtractors(t *testing.T) {
 	if got := minuteSearchAppLink(item); got != "https://meetings.feishu.cn/minutes/obcn123" {
 		t.Fatalf("minuteSearchAppLink() = %q", got)
 	}
-	if got := minuteSearchAvatar(item); got != "https://p3-lark-file.byteimg.com/img/xxxx.jpg" {
-		t.Fatalf("minuteSearchAvatar() = %q", got)
-	}
 }
 
 // TestMinuteSearchFieldExtractorsFallbacks verifies extractors keep working for alternate sample data.
@@ -694,7 +690,6 @@ func TestMinuteSearchFieldExtractorsFallbacks(t *testing.T) {
 		"meta_data": map[string]interface{}{
 			"description": "回退纪要",
 			"app_link":    "https://meetings.feishu.cn/minutes/fallback",
-			"avatar":      "https://p3-lark-file.byteimg.com/img/fallback.jpg",
 		},
 	}
 
@@ -707,9 +702,6 @@ func TestMinuteSearchFieldExtractorsFallbacks(t *testing.T) {
 	if got := minuteSearchAppLink(item); got != "https://meetings.feishu.cn/minutes/fallback" {
 		t.Fatalf("minuteSearchAppLink() = %q", got)
 	}
-	if got := minuteSearchAvatar(item); got != "https://p3-lark-file.byteimg.com/img/fallback.jpg" {
-		t.Fatalf("minuteSearchAvatar() = %q", got)
-	}
 }
 
 // TestMinuteSearchFieldExtractorsMissingMetaData verifies extractors fall back to empty values without metadata.
@@ -730,7 +722,32 @@ func TestMinuteSearchFieldExtractorsMissingMetaData(t *testing.T) {
 	if got := minuteSearchAppLink(item); got != "" {
 		t.Fatalf("minuteSearchAppLink() = %q, want empty", got)
 	}
-	if got := minuteSearchAvatar(item); got != "" {
-		t.Fatalf("minuteSearchAvatar() = %q, want empty", got)
+}
+
+// TestStripAvatarFromItems verifies the avatar field is removed from items in place.
+func TestStripAvatarFromItems(t *testing.T) {
+	t.Parallel()
+
+	items := []interface{}{
+		map[string]interface{}{
+			"token": "minute_1",
+			"meta_data": map[string]interface{}{
+				"description": "周会纪要",
+				"avatar":      "https://p3-lark-file.byteimg.com/img/xxxx.jpg",
+			},
+		},
+		nil,
+		map[string]interface{}{"token": "minute_no_meta"},
+	}
+
+	stripAvatarFromItems(items)
+
+	first, _ := items[0].(map[string]interface{})
+	meta, _ := first["meta_data"].(map[string]interface{})
+	if _, ok := meta["avatar"]; ok {
+		t.Fatalf("avatar should be stripped, got meta = %v", meta)
+	}
+	if meta["description"] != "周会纪要" {
+		t.Fatalf("description should be preserved, got %v", meta["description"])
 	}
 }

shortcuts/minutes/shortcuts.go

@@ -16,5 +16,6 @@ func Shortcuts() []common.Shortcut {
 		MinutesTodo,
 		MinutesSpeakerReplace,
 		MinutesWordReplace,
+		MinutesDetail,
 	}
 }

shortcuts/register.go

@@ -78,6 +78,7 @@ func init() {
 	allShortcuts = append(allShortcuts, markdown.Shortcuts()...)
 	allShortcuts = append(allShortcuts, slides.Shortcuts()...)
 	allShortcuts = append(allShortcuts, minutes.Shortcuts()...)
+	allShortcuts = append(allShortcuts, note.Shortcuts()...)
 	allShortcuts = append(allShortcuts, task.Shortcuts()...)
 	allShortcuts = append(allShortcuts, vc.Shortcuts()...)
 	allShortcuts = append(allShortcuts, note.Shortcuts()...)

shortcuts/vc/shortcuts.go

@@ -11,6 +11,7 @@ func Shortcuts() []common.Shortcut {
 		VCSearch,
 		VCNotes,
 		VCRecording,
+		VCDetail,
 		VCMeetingJoin,
 		VCMeetingLeave,
 		VCMeetingEvents,

shortcuts/vc/vc_detail.go

@@ -0,0 +1,216 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// vc +detail — get meeting details including note_id and minute_token
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const detailLogPrefix = "[vc +detail]"
+
+var scopesDetailMeetingIDs = []string{
+	"vc:meeting.meetingevent:read",
+	"vc:record:readonly",
+}
+
+// meetingDetailItem represents a single meeting detail result.
+type meetingDetailItem struct {
+	MeetingID   string `json:"meeting_id"`
+	MeetingNo   string `json:"meeting_no,omitempty"`
+	Topic       string `json:"topic"`
+	StartTime   string `json:"start_time,omitempty"`
+	EndTime     string `json:"end_time,omitempty"`
+	NoteID      string `json:"note_id,omitempty"`
+	MinuteToken string `json:"minute_token,omitempty"`
+	Error       string `json:"error,omitempty"`
+	Hint        string `json:"hint,omitempty"`
+}
+
+// fetchMeetingDetail queries meeting.get and recording API to return a
+// consolidated view of meeting metadata, note_id, and minute_token.
+// Error is only set when an API call actually fails; note_id and minute_token
+// are always present (empty string when not available).
+func fetchMeetingDetail(ctx context.Context, runtime *common.RuntimeContext, meetingID string) *meetingDetailItem {
+	result := &meetingDetailItem{MeetingID: meetingID}
+
+	// Step 1: query meeting detail
+	data, err := runtime.CallAPITyped(http.MethodGet,
+		fmt.Sprintf("/open-apis/vc/v1/meetings/%s", validate.EncodePathSegment(meetingID)),
+		map[string]interface{}{"with_participants": "false", "query_mode": "0"}, nil)
+	if err != nil {
+		result.Error = fmt.Sprintf("failed to query meeting detail: %v", err)
+		return result
+	}
+
+	meeting, _ := data["meeting"].(map[string]any)
+	if meeting == nil {
+		result.Error = "meeting not found in response"
+		return result
+	}
+
+	if v, ok := meeting["meeting_no"].(string); ok {
+		result.MeetingNo = v
+	}
+	if v, ok := meeting["topic"].(string); ok {
+		result.Topic = v
+	}
+	if v := common.FormatTime(meeting["start_time"]); v != "" {
+		result.StartTime = v
+	}
+	if v := common.FormatTime(meeting["end_time"]); v != "" {
+		result.EndTime = v
+	}
+	if v, ok := meeting["note_id"].(string); ok && v != "" {
+		result.NoteID = v
+	}
+
+	// Step 2: query minute_token via recording API
+	minuteToken, minuteHint, minuteErr := fetchMeetingMinuteToken(runtime, meetingID)
+	if minuteErr != nil {
+		// Recording API failed — surface the error but keep data from step 1
+		result.Error = fmt.Sprintf("failed to query minutes: %v", minuteErr)
+		minuteHint = ""
+	}
+	if minuteToken != "" {
+		result.MinuteToken = minuteToken
+	}
+
+	// Add hints for empty resources (not errors, just informational)
+	var emptyFields []string
+	if result.NoteID == "" {
+		emptyFields = append(emptyFields, "note_id")
+	}
+	if result.MinuteToken == "" && minuteErr == nil && minuteHint == "" {
+		emptyFields = append(emptyFields, "minute_token")
+	}
+	if len(emptyFields) > 0 {
+		result.Hint = fmt.Sprintf("%s not found for this meeting", strings.Join(emptyFields, ", "))
+	}
+	if minuteHint != "" {
+		if result.Hint != "" {
+			result.Hint += "; " + minuteHint
+		} else {
+			result.Hint = minuteHint
+		}
+	}
+
+	return result
+}
+
+// VCDetail gets meeting details including note_id and minute_token.
+var VCDetail = common.Shortcut{
+	Service:     "vc",
+	Command:     "+detail",
+	Description: "Get meeting details including note_id and minute_token by meeting IDs",
+	Risk:        "read",
+	Scopes:      []string{"vc:meeting.meetingevent:read", "vc:record:readonly"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "meeting-ids", Desc: "meeting IDs, comma-separated for batch", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ids := common.SplitCSV(runtime.Str("meeting-ids"))
+		const maxBatchSize = 50
+		if len(ids) > maxBatchSize {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--meeting-ids: too many IDs (%d), maximum is %d", len(ids), maxBatchSize).WithParam("--meeting-ids")
+		}
+		// dynamic scope check
+		result, err := runtime.Factory.Credential.ResolveToken(ctx, credential.NewTokenSpec(runtime.As(), runtime.Config.AppID))
+		if err == nil && result != nil && result.Scopes != "" {
+			if missing := auth.MissingScopes(result.Scopes, scopesDetailMeetingIDs); len(missing) > 0 {
+				return errs.NewPermissionError(errs.SubtypeMissingScope,
+					"missing required scope(s): %s", strings.Join(missing, ", ")).
+					WithHint("run `lark-cli auth login --scope %q` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(missing, " ")).
+					WithMissingScopes(missing...).
+					WithIdentity(string(runtime.As()))
+			}
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ids := runtime.Str("meeting-ids")
+		return common.NewDryRunAPI().
+			GET("/open-apis/vc/v1/meetings/{meeting_id}").
+			GET("/open-apis/vc/v1/meetings/{meeting_id}/recording").
+			Set("meeting_ids", common.SplitCSV(ids)).
+			Set("steps", "meeting.get → note_id + recording API → minute_token")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		errOut := runtime.IO().ErrOut
+		meetingIDs := common.SplitCSV(runtime.Str("meeting-ids"))
+		results := make([]*meetingDetailItem, 0, len(meetingIDs))
+
+		const batchDelay = 100 * time.Millisecond
+		fmt.Fprintf(errOut, "%s querying %d meeting_id(s)\n", detailLogPrefix, len(meetingIDs))
+		for i, id := range meetingIDs {
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+			if i > 0 {
+				time.Sleep(batchDelay)
+			}
+			fmt.Fprintf(errOut, "%s querying meeting_id=%s ...\n", detailLogPrefix, sanitizeLogValue(id))
+			results = append(results, fetchMeetingDetail(ctx, runtime, id))
+		}
+
+		successCount := 0
+		for _, r := range results {
+			if r.Error == "" {
+				successCount++
+			}
+		}
+		fmt.Fprintf(errOut, "%s done: %d total, %d succeeded, %d failed\n", detailLogPrefix, len(results), successCount, len(results)-successCount)
+
+		if successCount == 0 && len(results) > 0 {
+			return runtime.OutPartialFailure(map[string]any{"meetings": results}, &output.Meta{Count: len(results)})
+		}
+
+		outData := map[string]any{"meetings": results}
+		runtime.OutFormat(outData, &output.Meta{Count: len(results)}, func(w io.Writer) {
+			if len(results) == 0 {
+				fmt.Fprintln(w, "No meetings.")
+				return
+			}
+			var rows []map[string]interface{}
+			for _, r := range results {
+				row := map[string]interface{}{"meeting_id": r.MeetingID}
+				if r.Error != "" {
+					row["status"] = "FAIL"
+					row["error"] = r.Error
+				} else {
+					row["status"] = "OK"
+				}
+				if r.NoteID != "" {
+					row["note_id"] = r.NoteID
+				}
+				if r.MinuteToken != "" {
+					row["minute_token"] = r.MinuteToken
+				}
+				row["topic"] = r.Topic
+				if r.Hint != "" {
+					row["hint"] = r.Hint
+				}
+				rows = append(rows, row)
+			}
+			output.PrintTable(w, rows)
+			fmt.Fprintf(w, "\n%d meeting(s), %d succeeded, %d failed\n", len(results), successCount, len(results)-successCount)
+		})
+		return nil
+	},
+}

shortcuts/vc/vc_detail_test.go

@@ -0,0 +1,282 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ---------------------------------------------------------------------------
+// Validation tests
+// ---------------------------------------------------------------------------
+
+func TestDetail_Validation_MissingMeetingIDs(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for missing --meeting-ids")
+	}
+	if !strings.Contains(err.Error(), "meeting-ids") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestDetail_Validation_BatchLimit(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	ids := make([]string, 51)
+	for i := range ids {
+		ids[i] = fmt.Sprintf("m%d", i)
+	}
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", strings.Join(ids, ","), "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected batch limit error")
+	}
+	if !strings.Contains(err.Error(), "too many IDs") {
+		t.Errorf("expected 'too many IDs' error, 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 {
+		t.Errorf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// DryRun tests
+// ---------------------------------------------------------------------------
+
+func TestDetail_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m001", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "/open-apis/vc/v1/meetings/") {
+		t.Errorf("dry-run should show meeting API path, got: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), "recording") {
+		t.Errorf("dry-run should show recording API path, got: %s", stdout.String())
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execute tests with mocked HTTP
+// ---------------------------------------------------------------------------
+
+func TestDetail_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_detail1", "note_001"))
+	reg.Register(recordingOKStub("m_detail1", "https://meetings.feishu.cn/minutes/obc_detail1"))
+
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m_detail1", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	if len(meetings) != 1 {
+		t.Fatalf("expected 1 meeting, got %d", len(meetings))
+	}
+	m, _ := meetings[0].(map[string]any)
+	if m["meeting_id"] != "m_detail1" {
+		t.Errorf("meeting_id = %v, want m_detail1", m["meeting_id"])
+	}
+	if m["note_id"] != "note_001" {
+		t.Errorf("note_id = %v, want note_001", m["note_id"])
+	}
+	if m["minute_token"] != "obc_detail1" {
+		t.Errorf("minute_token = %v, want obc_detail1", m["minute_token"])
+	}
+}
+
+func TestDetail_Execute_NoNoteNoMinute(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_nonote", ""))
+	reg.Register(recordingErrStub("m_nonote", 121004, "not found"))
+
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m_nonote", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Verify hint is present for empty note_id and missing recording
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	m, _ := meetings[0].(map[string]any)
+	if hint, _ := m["hint"].(string); !strings.Contains(hint, "note_id") || !strings.Contains(hint, "no minute file for this meeting") {
+		t.Errorf("hint should mention note_id and minute file missing, got: %v", hint)
+	}
+	if errMsg, _ := m["error"].(string); errMsg != "" {
+		t.Errorf("error should be empty, got: %v", errMsg)
+	}
+}
+
+func TestDetail_Execute_MeetingNotFound(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/meetings/m_bad",
+		Body:   map[string]interface{}{"code": 121004, "msg": "data not found"},
+	})
+
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m_bad", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+}
+
+func TestDetail_Execute_Batch(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	// m1 succeeds with note and minute
+	reg.Register(meetingGetStub("m_batch1", "note_b1"))
+	reg.Register(recordingOKStub("m_batch1", "https://meetings.feishu.cn/minutes/obc_b1"))
+	// m2 has no note_id but has minute
+	reg.Register(meetingGetStub("m_batch2", ""))
+	reg.Register(recordingOKStub("m_batch2", "https://meetings.feishu.cn/minutes/obc_b2"))
+
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m_batch1,m_batch2", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	if len(meetings) != 2 {
+		t.Fatalf("expected 2 meetings, got %d", len(meetings))
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Pure function tests
+// ---------------------------------------------------------------------------
+
+func TestFetchMeetingDetail_MeetingWithNoteAndMinute(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_fn", "note_fn"))
+	reg.Register(recordingOKStub("m_fn", "https://meetings.feishu.cn/minutes/obc_fn"))
+
+	if err := botExec(t, "detail-fn", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		result := fetchMeetingDetail(context.Background(), rctx, "m_fn")
+		if result.MeetingID != "m_fn" {
+			t.Errorf("meeting_id = %v, want m_fn", result.MeetingID)
+		}
+		if result.NoteID != "note_fn" {
+			t.Errorf("note_id = %v, want note_fn", result.NoteID)
+		}
+		if result.MinuteToken != "obc_fn" {
+			t.Errorf("minute_token = %v, want obc_fn", result.MinuteToken)
+		}
+		if result.Error != "" {
+			t.Errorf("unexpected error: %v", result.Error)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFetchMeetingDetail_MeetingNotFound(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/meetings/m_nf",
+		Body:   map[string]interface{}{"code": 121004, "msg": "data not found"},
+	})
+
+	if err := botExec(t, "detail-nf", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		result := fetchMeetingDetail(context.Background(), rctx, "m_nf")
+		if result.Error == "" {
+			t.Error("expected error for meeting not found")
+		}
+		// note_id and minute_token should still be present (empty)
+		if result.NoteID != "" {
+			t.Errorf("note_id = %q, want empty", result.NoteID)
+		}
+		if result.MinuteToken != "" {
+			t.Errorf("minute_token = %q, want empty", result.MinuteToken)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFetchMeetingDetail_RecordingFailsButNoteOK(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_partial", "note_partial"))
+	reg.Register(recordingErrStub("m_partial", 121004, "not found"))
+
+	if err := botExec(t, "detail-partial", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		result := fetchMeetingDetail(context.Background(), rctx, "m_partial")
+		if result.NoteID != "note_partial" {
+			t.Errorf("note_id = %v, want note_partial", result.NoteID)
+		}
+		if result.MinuteToken != "" {
+			t.Errorf("minute_token = %q, want empty", result.MinuteToken)
+		}
+		if result.Error != "" {
+			t.Errorf("error = %q, want empty", result.Error)
+		}
+		if !strings.Contains(result.Hint, "no minute file for this meeting") {
+			t.Errorf("hint = %q, want contains 'no minute file for this meeting'", result.Hint)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFetchMeetingDetail_RecordingAPIErrorButNoteOK(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_api_err", "note_apierr"))
+	reg.Register(recordingErrStub("m_api_err", 99999, "weird API error"))
+
+	if err := botExec(t, "detail-apierr", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		result := fetchMeetingDetail(context.Background(), rctx, "m_api_err")
+		if result.NoteID != "note_apierr" {
+			t.Errorf("note_id = %v, want note_apierr", result.NoteID)
+		}
+		if result.MinuteToken != "" {
+			t.Errorf("minute_token = %q, want empty", result.MinuteToken)
+		}
+		if !strings.Contains(result.Error, "failed to query minutes") || !strings.Contains(result.Error, "weird API error") {
+			t.Errorf("error = %q, want contains 'failed to query minutes' and 'weird API error'", result.Error)
+		}
+		if strings.Contains(result.Hint, "minute_token") {
+			t.Errorf("hint = %q, should not mention minute_token when there is an error", result.Hint)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}

shortcuts/vc/vc_meeting_events_test.go

@@ -818,7 +818,7 @@ func TestVCShortcuts_RegistersMeetingAgentCommands(t *testing.T) {
 	for _, shortcut := range got {
 		commands = append(commands, shortcut.Command)
 	}
-	want := []string{"+search", "+notes", "+recording", "+meeting-join", "+meeting-leave", "+meeting-events"}
+	want := []string{"+search", "+notes", "+recording", "+detail", "+meeting-join", "+meeting-leave", "+meeting-events"}
 	if !reflect.DeepEqual(commands, want) {
 		t.Fatalf("shortcut commands = %#v, want %#v", commands, want)
 	}

shortcuts/vc/vc_notes.go

@@ -263,42 +263,35 @@ func asStringSlice(v any) []string {
 }
 
 // fetchMeetingMinuteToken queries the recording API of a meeting and returns
-// the associated minute_token (parsed from the recording URL) and an
-// optional human-friendly error message. On success token is non-empty and
-// errMsg is empty; on failure token is empty and errMsg describes the cause:
-//   - 121004: meeting has no minute file
-//   - 121005: caller has no permission for the meeting recording
-//   - 124002: recording / minute file is still being generated
-//
-// Other failures fall back to the raw API error description so Agents can
-// still parse the underlying cause.
-func fetchMeetingMinuteToken(runtime *common.RuntimeContext, meetingID string) (token, errMsg string) {
-	data, err := runtime.CallAPITyped(http.MethodGet,
+// the associated minute_token (parsed from the recording URL), an optional
+// hint for expected missing states, and an error for unexpected failures.
+func fetchMeetingMinuteToken(runtime *common.RuntimeContext, meetingID string) (token, hint string, err error) {
+	data, apiErr := runtime.CallAPITyped(http.MethodGet,
 		fmt.Sprintf("/open-apis/vc/v1/meetings/%s/recording", validate.EncodePathSegment(meetingID)),
 		nil, nil)
-	if err != nil {
-		if p, ok := errs.ProblemOf(err); ok {
+	if apiErr != nil {
+		if p, ok := errs.ProblemOf(apiErr); ok {
 			switch p.Code {
 			case recordingNotFoundCode:
-				return "", "no minute file for this meeting"
+				return "", "no minute file for this meeting", nil
 			case recordingNoPermissionCode:
-				return "", "no permission to access this meeting's minute; ask the meeting owner to share the minute"
+				return "", "no permission to access this meeting's minute; ask the meeting owner to share the minute", nil
 			case recordingGeneratingCode:
-				return "", "minute file is still being generated; please retry later"
+				return "", "minute file is still being generated; please retry later", nil
 			}
 		}
-		return "", fmt.Sprintf("failed to query recording: %v", err)
+		return "", "", apiErr
 	}
 
 	recording, _ := data["recording"].(map[string]any)
 	if recording == nil {
-		return "", "no recording available for this meeting"
+		return "", "no recording available for this meeting", nil
 	}
 	recordingURL, _ := recording["url"].(string)
 	if t := extractMinuteToken(recordingURL); t != "" {
-		return t, ""
+		return t, "", nil
 	}
-	return "", "no minute_token found in recording URL"
+	return "", "no minute_token found in recording URL", nil
 }
 
 // fetchNoteByMeetingID queries notes via meeting_id and additionally fetches
@@ -321,7 +314,7 @@ func fetchNoteByMeetingID(ctx context.Context, runtime *common.RuntimeContext, m
 	// Always attempt to query the meeting's minute_token via the recording API,
 	// regardless of whether the meeting has a note_id, so callers always see
 	// minute state for follow-up calls (e.g. `vc +notes --minute-tokens=...`).
-	minuteToken, minuteErr := fetchMeetingMinuteToken(runtime, meetingID)
+	minuteToken, minuteHint, minuteErr := fetchMeetingMinuteToken(runtime, meetingID)
 
 	var result map[string]any
 	var noteErr string
@@ -340,7 +333,13 @@ func fetchNoteByMeetingID(ctx context.Context, runtime *common.RuntimeContext, m
 	if minuteToken != "" {
 		result["minute_token"] = minuteToken
 	}
-	if combined := joinErrors(noteErr, minuteErr); combined != "" {
+	var minuteErrMsg string
+	if minuteHint != "" {
+		minuteErrMsg = minuteHint
+	} else if minuteErr != nil {
+		minuteErrMsg = minuteErr.Error()
+	}
+	if combined := joinErrors(noteErr, minuteErrMsg); combined != "" {
 		result["error"] = combined
 	}
 	return result
@@ -538,6 +537,7 @@ var VCNotes = common.Shortcut{
 	Risk:        "read",
 	Scopes:      []string{"vc:note:read"}, // minimum scope; additional per-flag scopes checked in Validate
 	AuthTypes:   []string{"user"},
+	Hidden:      true, // hidden from --help; prefer vc +detail, minutes +detail, or note +detail
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "meeting-ids", Desc: "meeting IDs, comma-separated for batch"},

shortcuts/vc/vc_notes_test.go

@@ -792,12 +792,15 @@ func TestFetchMeetingMinuteToken_Success(t *testing.T) {
 	reg.Register(recordingOKStub("m_ok", "https://meetings.feishu.cn/minutes/obctoken_ok"))
 
 	if err := botExec(t, "fmmt-ok", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		token, msg := fetchMeetingMinuteToken(rctx, "m_ok")
+		token, hint, err := fetchMeetingMinuteToken(rctx, "m_ok")
 		if token != "obctoken_ok" {
 			t.Errorf("token = %q, want obctoken_ok", token)
 		}
-		if msg != "" {
-			t.Errorf("errMsg = %q, want empty", msg)
+		if hint != "" {
+			t.Errorf("hint = %q, want empty", hint)
+		}
+		if err != nil {
+			t.Errorf("err = %v, want nil", err)
 		}
 		return nil
 	}); err != nil {
@@ -823,12 +826,15 @@ func TestFetchMeetingMinuteToken_KnownErrorCodes(t *testing.T) {
 			reg.Register(recordingErrStub(tt.meetingID, tt.code, "err"))
 
 			if err := botExec(t, "fmmt-"+tt.meetingID, f, func(_ context.Context, rctx *common.RuntimeContext) error {
-				token, msg := fetchMeetingMinuteToken(rctx, tt.meetingID)
+				token, hint, err := fetchMeetingMinuteToken(rctx, tt.meetingID)
 				if token != "" {
 					t.Errorf("token = %q, want empty on error", token)
 				}
-				if !strings.Contains(msg, tt.wantMsg) {
-					t.Errorf("errMsg = %q, want contains %q", msg, tt.wantMsg)
+				if !strings.Contains(hint, tt.wantMsg) {
+					t.Errorf("hint = %q, want contains %q", hint, tt.wantMsg)
+				}
+				if err != nil {
+					t.Errorf("err = %v, want nil", err)
 				}
 				return nil
 			}); err != nil {
@@ -844,12 +850,15 @@ func TestFetchMeetingMinuteToken_GenericAPIError(t *testing.T) {
 	reg.Register(recordingErrStub("m_other", 99999, "weird"))
 
 	if err := botExec(t, "fmmt-generic", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		token, msg := fetchMeetingMinuteToken(rctx, "m_other")
+		token, hint, err := fetchMeetingMinuteToken(rctx, "m_other")
 		if token != "" {
 			t.Errorf("token = %q, want empty", token)
 		}
-		if !strings.Contains(msg, "failed to query recording") {
-			t.Errorf("errMsg = %q, want contains 'failed to query recording'", msg)
+		if hint != "" {
+			t.Errorf("hint = %q, want empty", hint)
+		}
+		if err == nil || !strings.Contains(err.Error(), "weird") {
+			t.Errorf("err = %v, want contains 'weird'", err)
 		}
 		return nil
 	}); err != nil {
@@ -866,12 +875,15 @@ func TestFetchMeetingMinuteToken_NoRecording(t *testing.T) {
 	}))
 
 	if err := botExec(t, "fmmt-norec", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		token, msg := fetchMeetingMinuteToken(rctx, "m_norec")
+		token, hint, err := fetchMeetingMinuteToken(rctx, "m_norec")
 		if token != "" {
 			t.Errorf("token = %q, want empty", token)
 		}
-		if !strings.Contains(msg, "no recording available") {
-			t.Errorf("errMsg = %q, want contains 'no recording available'", msg)
+		if err != nil {
+			t.Errorf("err = %v, want nil", err)
+		}
+		if !strings.Contains(hint, "no recording available") {
+			t.Errorf("hint = %q, want contains 'no recording available'", hint)
 		}
 		return nil
 	}); err != nil {
@@ -885,12 +897,15 @@ func TestFetchMeetingMinuteToken_URLWithoutToken(t *testing.T) {
 	reg.Register(recordingOKStub("m_notok", "https://example.com/no/minute/path"))
 
 	if err := botExec(t, "fmmt-notok", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		token, msg := fetchMeetingMinuteToken(rctx, "m_notok")
+		token, hint, err := fetchMeetingMinuteToken(rctx, "m_notok")
 		if token != "" {
 			t.Errorf("token = %q, want empty", token)
 		}
-		if !strings.Contains(msg, "no minute_token found") {
-			t.Errorf("errMsg = %q, want contains 'no minute_token found'", msg)
+		if err != nil {
+			t.Errorf("err = %v, want nil", err)
+		}
+		if !strings.Contains(hint, "no minute_token found") {
+			t.Errorf("hint = %q, want contains 'no minute_token found'", hint)
 		}
 		return nil
 	}); err != nil {
@@ -983,7 +998,7 @@ func TestNotes_MeetingPath_OnlyMinuteFails_PartialSuccess(t *testing.T) {
 		t.Errorf("note_doc_token = %v, want doc_main", got)
 	}
 	assertNoteFieldAbsent(t, note, "minute_token")
-	assertNoteError(t, note, "no permission to access this meeting's minute")
+	assertNoteError(t, note, "no permission to access this meeting's minute; ask the meeting owner to share the minute")
 }
 
 func TestNotes_MeetingPath_NoNote_ButMinuteOK(t *testing.T) {
@@ -1068,6 +1083,7 @@ func TestNotes_MeetingPath_NoteNoPermission_FriendlyHint(t *testing.T) {
 	assertNoteError(t, note,
 		"[121005]",
 		"no read permission for this meeting note",
+		"no permission to access this meeting's minute",
 		"; ", // note + minute causes joined with semicolon
 	)
 }

shortcuts/vc/vc_search.go

@@ -230,9 +230,16 @@ var VCSearch = common.Shortcut{
 			data = map[string]interface{}{}
 		}
 		items := common.GetSlice(data, "items")
+		// Strip avatar from meta_data — not useful for AI agents.
+		for _, raw := range items {
+			if m, ok := raw.(map[string]interface{}); ok {
+				if meta, ok := m["meta_data"].(map[string]interface{}); ok {
+					delete(meta, "avatar")
+				}
+			}
+		}
 		outData := map[string]interface{}{
 			"items":      items,
-			"total":      data["total"],
 			"has_more":   data["has_more"],
 			"page_token": data["page_token"],
 		}

skill-template/domains/im.md

@@ -1,46 +1,71 @@
 ## Core Concepts
 
-- **Message** `message_id` (om_xxx) · **Chat** `chat_id` (oc_xxx, group or P2P) · **Thread** `thread_id` (om_xxx / omt_xxx).
-- **Flag** — bookmark on a message/thread (two layers, see below).
-- **Feed Shortcut** `feed_card_id` (oc_xxx) — a chat pinned to the user's feed sidebar.
-- **Feed Group** `feed_group_id` (ofg_xxx) — a tag grouping feed cards (`feed_id`+`feed_type`); `normal` (explicit) / `rule` (auto-derived).
+- **Message**: A single message in a chat, identified by `message_id` (om_xxx). Supports types: text, post, image, file, audio, video, sticker, interactive (card), share_chat, share_user, merge_forward, etc.
+- **Chat**: A group chat or P2P conversation, identified by `chat_id` (oc_xxx).
+- **Thread**: A reply thread under a message, identified by `thread_id` (om_xxx or omt_xxx).
+- **Reaction**: An emoji reaction on a message.
+- **Flag**: A bookmark on a message or thread.
+- **Feed Shortcut**: A chat pinned to the current user's feed sidebar, identified by `feed_card_id` (an `oc_xxx` open_chat_id for CHAT type).
+- **Feed Group**: A tag that groups feed cards in the feed list, identified by `feed_group_id` (ofg_xxx). Members are feed cards, each identified by `feed_id` + `feed_type`. Two types: `normal` (members managed explicitly) and `rule` (members auto-derived from rules).
+
+## Resource Relationships
+
+```
+Chat (oc_xxx)
+├── Message (om_xxx)
+│   ├── Thread (reply thread)
+│   ├── Reaction (emoji)
+│   └── Resource (image / file / video / audio)
+└── Member (user / bot)
+```
 
 ## Important Notes
 
-### Identity (user vs bot)
+### Identity and Token Mapping
 
-- `--as user` (`user_access_token`): runs as the authorized user; permission = app scopes + that user's own access to the target.
-- `--as bot` (`tenant_access_token`): runs as the app bot; depends on bot's chat membership, app visibility range, bot scopes.
-- When an API supports both, the token decides *who* operates — owner/admin, membership, tenant, visibility are checked against the caller, so the same API can pass on one identity and fail on the other.
+- `--as user` means **user identity** and uses `user_access_token`. Calls run as the authorized end user, so permissions depend on both the app scopes and that user's own access to the target chat/message/resource.
+- `--as bot` means **bot identity** and uses `tenant_access_token`. Calls run as the app bot, so behavior depends on the bot's membership, app visibility, availability range, and bot-specific scopes.
+- If an IM API says it supports both `user` and `bot`, the token type changes who the operator is. The same API can succeed with one identity and fail with the other because owner/admin status, chat membership, tenant boundary, or app availability are checked against the current caller.
 
-### Sender name resolution
+### Sender Name Resolution with Bot Identity
 
-As **bot**, the sender may show as `open_id` (bot visibility range doesn't cover it); `--as user` gives real names.
+When using bot identity (`--as bot`) to fetch messages (e.g. `+chat-messages-list`, `+threads-messages-list`, `+messages-mget`), sender names may not be resolved (shown as open_id instead of display name). This happens when the bot cannot access the user's contact info.
 
-```bash
-lark-cli im +chat-messages-list --chat-id oc_xxx --as bot   # BAD: sender = open_id
-lark-cli im +chat-messages-list --chat-id oc_xxx --as user  # GOOD: sender = real name
-```
+**Root cause**: The bot's app visibility settings do not include the message sender, so the contact API returns no name.
 
-### Default message enrichment
+**Solution**: Check the app's visibility settings in the Lark Developer Console — ensure the app's visible range covers the users whose names need to be resolved. Alternatively, use `--as user` to fetch messages with user identity, which typically has broader contact access.
 
-The four message-pulling shortcuts auto-attach `reactions` (+ `update_time` for edited messages) — no separate `reactions.batch_query` (needs `im:message.reactions:read`); `--no-reactions` opts out. `+chat-messages-list` / `+messages-mget` / `+threads-messages-list` also accept `--download-resources` (off by default) to download image/file/audio/video/media (stickers excluded) into `./lark-im-resources/`, adding a `resources` array per message; one-off via [`+messages-resources-download`](references/lark-im-messages-resources-download.md). Contract: [`references/lark-im-message-enrichment.md`](references/lark-im-message-enrichment.md).
+### Default message enrichment (reactions / update_time)
+
+The four message-pulling shortcuts (`+messages-mget`, `+chat-messages-list`, `+messages-search`, `+threads-messages-list`) automatically attach a `reactions` block and (for edited messages) `update_time` to each returned message — no separate `im.reactions.batch_query` call is needed. Pass `--no-reactions` to opt out. For the full contract (output shape, the `im:message.reactions:read` scope requirement, and the "missing field ≠ fetch failure" data rules), read [`references/lark-im-message-enrichment.md`](references/lark-im-message-enrichment.md).
+
+### Opt-in resource auto-download (`--download-resources`)
+
+`+chat-messages-list`, `+messages-mget`, and `+threads-messages-list` accept `--download-resources` (**off by default** — no `resources` block and no extra requests when omitted). When set, eligible message resources (image/file/audio/video/media + post-embedded; **stickers excluded**) are downloaded into `./lark-im-resources/` and each message gains a `resources` array of `{message_id, key, type, local_path, size_bytes}`. Downloads are deduped by `(message_id, file_key)`, run with bounded concurrency, and isolate single-resource failures (`error: true` + stderr warning). **Scope:** requires `im:message:readonly` (already declared by the listing commands — no extra scope); works under both user and bot identity. For one-off downloads use [`+messages-resources-download`](references/lark-im-messages-resources-download.md). Full contract: [`references/lark-im-message-enrichment.md`](references/lark-im-message-enrichment.md).
+
+### Card Messages (Interactive)
+
+Card messages (`interactive` type) are not yet supported for compact conversion in event subscriptions. The raw event data will be returned instead, with a hint printed to stderr.
 
 ### Flag Types
 
-Two layers (item_type auto-detected from chat mode — rarely set by hand):
-- **Message-layer** `(ItemTypeDefault, FlagTypeMessage)` — regular message bookmark.
-- **Feed-layer** `(ItemType{Thread|MsgThread}, FlagTypeFeed)` — thread bookmarked at feed level:
-  - **ItemTypeThread** (4) = a topic in a topic-style chat (an entry in the group's Thread tab).
-  - **ItemTypeMsgThread** (11) = a reply thread under a single message in a regular group.
+Flags support two layers:
+
+- **Message-layer flag**: `(ItemTypeDefault, FlagTypeMessage)` — regular message bookmark
+- **Feed-layer flag**: `(ItemTypeThread/ItemTypeMsgThread, FlagTypeFeed)` — thread as feed-layer bookmark
+
+Item types for feed-layer flags:
+- **ItemTypeThread** (4) = thread in a topic-style chat
+- **ItemTypeMsgThread** (11) = thread in a regular chat
 
 ### Feed Shortcut
 
-Pins a chat to the **current user's** feed sidebar. Limits: **CHAT-type only** (oc_xxx); **user-identity only**; **10 per call** for create/remove; list uses opaque `page_token`.
+Feed shortcuts add chats to the **current user's** feed sidebar. They are distinct from flags:
 
-## 不在本 skill 范围
+- **Flag** = bookmark on a message/thread, scoped to the user's bookmark list.
+- **Feed shortcut** = entry in the user's feed sidebar (currently only chats).
 
-- 邮件 → [`lark-mail`](../lark-mail/SKILL.md)｜日程/会议 → [`lark-calendar`](../lark-calendar/SKILL.md)｜会议回放/纪要 → [`lark-vc`](../lark-vc/SKILL.md)
-- 文档评论 → [`lark-drive`](../lark-drive/SKILL.md)｜IM 事件订阅 → [`lark-event`](../lark-event/SKILL.md)｜姓名解析 open_id → [`lark-contact`](../lark-contact/SKILL.md)
-
-群禁言 / 管理员 / 角色 / 解散 / 转让 / 群设置 等群治理 lark-cli im 暂无命令：如实告知“暂不支持”、勿臆造，引导用户到飞书客户端群设置手动操作（高风险写操作，勿擅自走原生 API 代执行）。
+Key limits:
+- Only **CHAT-type** (`feed_card_id` is `oc_xxx`) is exposed via OpenAPI; doc/app/subscription shortcuts exist internally but are not yet whitelisted.
+- All three operations (create/remove/list) are **user-identity only** — they sign with `user_access_token`.
+- Batch size is **10 per call** for create/remove; list is a one-page wrapper with opaque `page_token` pagination.

skill-template/skill-template.md

@@ -30,8 +30,12 @@ lark-cli schema {{service}}.<resource>.<method>   # 调用 API 前必须先查
 lark-cli {{service}} <resource> <method> [flags] # 调用 API
 ```
 
-{{schema_note_block}}
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
 
 {{resource_sections}}
-{{permission_block}}
+## 权限表
+
+| 方法 | 所需 scope |
+|------|-----------|
+{{permission_rows}}
 {{/actions}}

skills/lark-base/SKILL.md

@@ -35,44 +35,16 @@ metadata:
 - Base 命令必须先有 `base_token` 或可解析出的 Base URL。没有 token 时：用户要新建就用 `+base-create`；用户给标题/关键词就搜 `lark-cli drive +search --query "<base title>" --doc-types bitable --only-title --as user`；仍无法定位时，反问用户具体是哪一个 Base。
 - 认证、初始化、scope、身份切换、权限不足恢复属于 `lark-shared`；Base 文档只保留会影响 Base 路径选择的权限规则。
 
-## 名词与概念
-
-| 名词 | 含义 |
-|---|---|
-| Base / 多维表格 / Bitable | 同一个东西：`/base/{token}` 链接对应的整个文档容器，token 即 `--base-token`；Bitable 是曾用名，只出现在历史 API 和返回字段里 |
-| Table（数据表） | Base 内的一张数据表，ID `tbl` 开头；列是 field，行是 record |
-| Field（字段）/ Record（记录） | 表的列与行；字段 ID `fld` 开头，记录 ID `rec` 开头 |
-| View（视图） | 同一张 table 的一种展示配置（筛选/排序/分组等），ID `viw` 开头 |
-| Form（表单） | 收集数据的入口，提交结果写入对应 table 的记录 |
-| Workflow（工作流） | Base 内的自动化流程，ID `wkf` 开头，由 steps（trigger + action）组成 |
-| Dashboard（仪表盘） | 数据可视化容器，ID `blk` 开头(因为它本身是 Base 资源目录里的一个 block，见下方歧义说明) |
-| Chart（图表/组件） | 又叫Dashboard block, 是 dashboard 内的单个可视化组件（柱状图/饼图/指标卡等）, ID `cht` 开头 |
-| Base block （`+base-block-*`）| Base 资源目录里的节点，table/docx/dashboard/workflow/folder 在目录层面统称 block。 “这个 Base 里有哪些东西” → `+base-block-list`|
-
-**`block` 是易混淆词，同名不同义，按命令域区分：base-block 和 dashboard-block**
-
-### Base 心智模型
-
-- `base-block` 只负责资源目录管理，包括创建资源、移动到 folder、重命名和删除；具体资源内容仍走 table/dashboard/workflow 命令。
-- 新建 Base 时，强烈推荐一次性执行 `lark-cli base +base-create --name "<base>" --table-name "<table>" --fields '<field-json-array>'`，同时配置新 Base 里唯一一个初始数据表的 name 和 schema；使用 `--fields` 前先读 [lark-base-field-json.md](references/lark-base-field-json.md) 或复用 `+field-create` 的字段 JSON 形状，不要猜字段属性。
-- `+base-create` 不传 `--table-name` 和 `--fields` 时，会创建一个默认 schema 的初始数据表。
-- 表、字段、视图、workflow、dashboard block 的名称和 ID 必须来自真实返回，不要凭用户口述猜。
-- 存储字段可写；系统字段、`formula`、`lookup` 只读；附件字段走专用 attachment 命令。
-- 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`；需要长期显示在表中时，才新增 `formula` / `lookup` 字段。
-- `formula` 适合常规计算、条件判断、文本/日期处理和长期派生指标；`lookup` 适合明确的跨表查找、筛选后取值或聚合引用。
-- 写入、分析、公式、lookup、workflow、dashboard 前，先读取真实结构：表、字段、视图、关联表和 dashboard block 名称都以命令返回为准。
-- 跨表场景必须读取目标表结构；link 单元格中的关联 `record_id` 只是连接键，最终回答要回查并展示用户可读字段。
-
 ## 快速路由
 
 | 用户目标 | 优先命令 | 何时读 reference |
 |---|---|---|
 | 查 Base 本体 | `+base-get` | 用返回确认 Base 名称、owner、权限和可继续操作的 token |
 | 创建/复制 Base | `+base-create` / `+base-copy` | 新建时强烈推荐用 `--table-name` + `--fields` 同时配置新 Base 里唯一一个初始数据表的 name 和 schema；写入后报告新 Base 标识和 `permission_grant` |
-| 查看 Base 内资源目录 | `+base-block-list` | 先判断 Base 里有什么（table/docx/dashboard/workflow/folder），再决定走哪类命令 |
+| 查看 Base 内资源目录 | `+base-block-list` | 想先了解一个 Base 里有哪些 table/docx/dashboard/workflow/folder 时优先用它；返回 ID 关系和 fewshot 看 `--help` |
 | 管理 Base 内资源目录 | `+base-block-create/move/rename/delete` | 创建或整理 Base 直接管理的 folder/table/docx/dashboard/workflow；资源内容继续用对应命令 |
 | 管理数据表 | `+table-list/get/create/update/delete` | 处理 table 的列出、详情、创建、重命名和删除 |
-| 列/查/删字段 | `+field-list/get/delete/search-options` | 字段发现默认用 `+field-list --compact`；需要 formula/lookup 细节或完整字段 JSON 再用 `+field-get` / 不带 compact 的 list；多表结构用 `+field-list-batch --compact --table-id <表1> --table-id <表2>` 一次取齐，不要逐表调用 |
+| 列/查/删字段 | `+field-list/get/delete/search-options` | 写入前用 list/get 确认字段类型、选项、ID；删除前确认目标字段 |
 | 创建/更新字段 | `+field-create` / `+field-update` | 必读 [lark-base-field-json.md](references/lark-base-field-json.md)；公式读 [formula-field-guide.md](references/formula-field-guide.md)；lookup 读 [lookup-field-guide.md](references/lookup-field-guide.md)；命令细节读 [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md) |
 | 读记录明细 | `+record-get` / `+record-list` / `+record-search` | 涉及筛选、排序、Top/Bottom N、聚合、多表关联、全局结论时读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) |
 | 写记录 | `+record-upsert` / `+record-batch-create` / `+record-batch-update` | 必读 [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) 和 [lark-base-cell-value.md](references/lark-base-cell-value.md) |
@@ -86,34 +58,24 @@ metadata:
 | 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md) |
 | 其他表单管理 | `+form-list/get/detail/create/update/delete` / `+form-questions-list/delete` | `+form-detail` 读 [lark-base-form-detail.md](references/lark-base-form-detail.md)；删除前确认目标表单 |
 | 仪表盘与组件 | `+dashboard-*` / `+dashboard-block-*` | 提到图表/看板/block 时先读 [lark-base-dashboard.md](references/lark-base-dashboard.md)；组件 `data_config` 读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)；读取图表计算结果用 `+dashboard-block-get-data` |
-| Workflow | `+workflow-*` | 先读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md)：它包含查询/启停/创建/修改的最短路径和常见 step 组合；只有创建/更新复杂 steps 时才继续读 schema 小文件；list/get/enable/disable 不读 schema |
-| 高级权限与角色 | `+advperm-*` / `+role-*` | 先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)（含安全边界）；权限 JSON 再读 [role-config.md](references/role-config.md) |
+| Workflow | `+workflow-*` | 创建/更新或理解 steps 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；list/get/enable/disable 只处理 workflow ID 与启停状态 |
+| 高级权限与角色 | `+advperm-*` / `+role-*` | 角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)；角色 create/update 或解读完整配置再读权限 JSON SSOT [role-config.md](references/role-config.md)；系统角色不可删除；关闭高级权限会影响自定义角色 |
 
-## 注意事项
+## Base 心智模型
 
-### 批量执行
+- Base 曾用名 Bitable；返回字段、错误或旧文档里的 `bitable` 多为历史兼容，不代表应改走裸 API 或另一套命令。
+- `+base-block-list` 是查看一个 Base 内资源目录的新入口：它列出这个 Base 直接管理的 `folder/table/docx/dashboard/workflow`，适合先判断 Base 里有什么，再决定走 table、dashboard、workflow 或 docx 命令。
+- `base-block` 只负责资源目录管理，包括创建资源、移动到 folder、重命名和删除；具体资源内容仍走 table/dashboard/workflow 命令。
+- 新建 Base 时，强烈推荐一次性执行 `lark-cli base +base-create --name "<base>" --table-name "<table>" --fields '<field-json-array>'`，同时配置新 Base 里唯一一个初始数据表的 name 和 schema；使用 `--fields` 前先读 [lark-base-field-json.md](references/lark-base-field-json.md) 或复用 `+field-create` 的字段 JSON 形状，不要猜字段属性。
+- `+base-create` 不传 `--table-name` 和 `--fields` 时，会创建一个默认 schema 的初始数据表。
+- 表、字段、视图、workflow、dashboard block 的名称和 ID 必须来自真实返回，不要凭用户口述猜。
+- 存储字段可写；系统字段、`formula`、`lookup` 只读；附件字段走专用 attachment 命令。
+- 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`；需要长期显示在表中时，才新增 `formula` / `lookup` 字段。
+- `formula` 适合常规计算、条件判断、文本/日期处理和长期派生指标；`lookup` 适合明确的跨表查找、筛选后取值或聚合引用。
+- 写入、分析、公式、lookup、workflow、dashboard 前，先读取真实结构：表、字段、视图、关联表和 dashboard block 名称都以命令返回为准。
+- 跨表场景必须读取目标表结构；link 单元格中的关联 `record_id` 只是连接键，最终回答要回查并展示用户可读字段。
 
-能批量的操作尽量批量，不要一轮对话只处理一个对象。
-
-- 优先用原生批量能力：多表字段 `+field-list-batch`；批量写记录 `+record-batch-create` / `+record-batch-update`；部分命令参数本身支持多值（如 `+record-delete --record-id` 可重复传、`+record-share-link-create --record-ids`），先看 `--help`。
-- 没有原生批量命令时，对多个对象做同类操作在**一条 Bash 命令**里用 shell 循环完成。
-- 只读命令可用 `--jq` 收窄输出，避免无关字段灌入上下文。脚本输出只打印计数、ID 和失败项，不要回显完整 payload 或原始返回
-
-示例——一次取多个视图的配置：
-
-```bash
-for v in vewAAA vewBBB vewCCC; do
-  echo "== $v"
-  lark-cli base +view-get --base-token <base_token> --table-id <table_id> --view-id "$v" --as user
-done
-```
-
-### 善用 help
-
-- 参数不确定、要构造复杂 JSON、或命令带批量/隐藏选项时，先看对应reference或 `--help`，不要猜参数名或 JSON 结构；`+table-list` / `+base-create` 这类参数显而易见的简单命令直接执行，报参数错误再查 help，不要为它单花一轮。
-- 需要看多个命令的 help 时，合并在一条 Bash 命令里一次看完。
-
-### 身份与权限降级
+## 身份与权限降级
 
 - 默认显式使用 `--as user` 操作用户资源；只有用户明确要求应用身份时，才直接用 `--as bot`。
 - user 身份报 scope/授权不足，或错误中包含 `permission_violations` / `hint`，先转 `lark-shared` 做用户授权恢复，不要直接降级 bot。
@@ -121,27 +83,35 @@ done
 - `91403` 或明确不可访问错误不要循环换身份重试。
 - `+base-create` / `+base-copy` 若用 bot 身份执行，关注返回中的 `permission_grant`，并把用户是否可打开新 Base 告知用户。
 
-### 查询与统计
+## 查询与统计规则
 
-- 涉及筛选、排序、Top/Bottom N、聚合、分组、多表关联或任何全局结论时，先读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) 并按其 Hard Rules 执行。
-- 两条红线随时生效：能由 Base 云端表达的筛选/排序/聚合不要拉原始记录到本地手工处理；`has_more=true` 等分页信号未消除前，不能基于当前页下全局结论。
+涉及查询、统计或判断结论时，先阅读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md)，并遵守：
 
-### 写入前置
+1. `+record-list` 的默认页、固定 `--limit` 和本地 `jq` 只能证明已读取范围内的事实，不能直接支撑全局最值、全量计数、Top/Bottom N、异常识别或分组结论。
+2. 能由 Base 表达的筛选、排序、投影、聚合、分组和限制，应在 Base 云端查询能力中执行；不要先拉原始记录到本地上下文再手工筛选排序。
+3. `has_more=true` 或等价分页信号表示当前结果不是全量；除非用户只要样例/前 N 条，不能基于该页回答全局问题。
+4. 多表查询必须先确认关系字段和连接键；link 单元格里的 `record_id` 是关系键，不是用户可读答案。
+5. 最终答案必须能追溯到真实表、真实字段、查询范围、筛选/排序/聚合条件和必要的连接键。
+6. 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`；要把结果长期显示在表里，才考虑新增 `formula` / `lookup` 字段。
+7. `+data-query` 可返回聚合结果或维度字段行，但维度行按字段组合去重且不返回 `record_id`；需要逐条记录、记录定位或完整行级字段时，再用 `+record-list` / `+record-search` / `+record-get` 回查。
 
-- 写记录/字段前先读真实结构；表名、字段名、视图名必须来自真实返回，跨表场景还要读目标表结构。
-- 复杂 JSON 按快速路由读对应 reference：字段读 [lark-base-field-json.md](references/lark-base-field-json.md)，记录读 [lark-base-cell-value.md](references/lark-base-cell-value.md)（写入红线：只写存储字段、批量上限、并发冲突等，见其顶层规则）。
-- 删除、角色更新、字段更新等高风险操作遵循 CLI 的 confirmation gate；目标不明确先用 get/list 消歧；workflow/role 等复杂写操作创建后用 get 回读确认，必要时先 `--dry-run` 预演。
+## 写入前置规则
 
-### 表单与视图
+- 写记录前先读字段结构；只写存储字段。系统字段、附件字段、`formula`、`lookup` 不作为普通记录写入目标。
+- 附件上传、下载、删除走专用 `+record-*-attachment` 命令。
+- 写字段前先读 [lark-base-field-json.md](references/lark-base-field-json.md)；涉及 `formula` / `lookup` 时必须读 [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)。
+- 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回；跨表场景还要读取目标表结构。
+- 删除、角色更新、字段更新等高风险操作遵循 CLI 的 confirmation gate；目标不明确时先用 get/list 消歧。
+- 批量写入单批最多 200 条；连续写同一表时串行执行，遇到 `1254291` 按短暂等待后重试处理。
+- `+record-batch-update` 是“同值批量更新”：同一份 patch 应用到全部 `record_id_list`，不要拿它做逐行不同值映射。
+- select/multiselect 写入未知选项可能触发平台新增选项；不是要新增时，先用 `+field-list` 或 `+field-search-options` 确认可选值。
 
-- `+form-submit` 前必须先 `+form-detail`；提交规则（filter 隐藏题不填、附件写在 `attachments` 并带 `--base-token`）见 [lark-base-form-submit.md](references/lark-base-form-submit.md)。
-- 视图配置先用对应 get 命令读现状，只替换要变更的部分；一次性筛选/排序先用 `+record-list` / `+record-search` 验证，再按需沉淀为持久视图。
+## 表单与视图细节
 
-### Dashboard / Workflow / Role
-
-- Dashboard 的复杂点是 block 的 `data_config`：创建/更新 block 前读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)，组件串行创建；布局/换图表类型/删除具名图表等操作要点见 [lark-base-dashboard.md](references/lark-base-dashboard.md) 的「执行要点」。`+dashboard-block-get-data` 只返回图表数据，元数据用 `+dashboard-block-get`。
-- Workflow 的复杂点是 `steps`：先读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md)，用其中的最短路径和场景表完成查询/启停/常见创建修改；需要具体 step 字段再按需读 schema 小文件；创建后 `+workflow-get` 回读验证。
-- Role 的复杂点是权限 JSON：先读 [lark-base-role-guide.md](references/lark-base-role-guide.md)（含安全边界），权限 JSON SSOT 读 [role-config.md](references/role-config.md)；删除角色、关闭高级权限前确认目标和影响。
+- `+form-submit` 前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
+- 表单附件不要写进 `fields`，放在 `--json.attachments`；提交附件时必须同时传表单所属 Base 的 `--base-token`。
+- `+view-set-filter` 是唯一保留的 view reference；sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状，保留未修改字段，只替换用户要求变更的配置。
+- 视图适合持久化、共享和 UI 复用；一次性筛选/排序可先用 `+record-list` / `+record-search` 的 filter/sort 验证结果，再按需要沉淀为持久视图。
 
 ## Token 与链接
 
@@ -152,10 +122,19 @@ done
 | `/base/{token}?table={id}` | `table` 参数用于定位 Base 内对象：`tbl` 开头是数据表 `--table-id`；`blk` 开头是 dashboard ID；`wkf` 开头是 workflow ID |
 | `/base/{token}?view={id}` | `view` 参数用于定位表视图，提取为 `--view-id`；通常还需要确认 `table` 参数或先查表结构 |
 | `/share/base/form/{shareToken}` | 表单分享链接；这是表单 share token，走 `+form-detail` / `+form-submit --share-token <shareToken>` |
-| `/share/base/view/...` / `/share/base/dashboard/...` / `/record/...` / `/base/workspace/...` | 分享链接与 workspace 链接，暂不支持用 CLI 直接访问，引导用户在飞书客户端打开；要生成记录分享链接用 `+record-share-link-create` |
+| `/share/base/view/{shareToken}` | 视图分享链接；具有分享权限语义，暂不支持用 CLI 直接访问，引导用户在浏览器或飞书客户端打开 |
+| `/share/base/dashboard/{shareToken}` | 仪表盘分享链接；具有分享权限语义，暂不支持用 CLI 直接访问，引导用户在浏览器或飞书客户端打开 |
+| `/record/{shareToken}` | 记录分享链接；暂不支持用 CLI 直接访问，引导用户在浏览器或飞书客户端打开。若用户想生成现有记录的分享链接，用 `+record-share-link-create --base-token <base_token> --table-id <table_id> --record-ids <record_id>` |
+| `/base/workspace/{token}` | BaseApp / workspace 链接；暂不支持用 CLI 直接访问 |
 
 `wiki +node-get` 返回非 `bitable` 时，不继续使用 Base 命令：`docx` 转文档，`sheet` 转表格，其他云空间对象转对应 skill 或 drive。
 
+## Dashboard / Workflow / Role
+
+- Dashboard 的复杂点是 block 的 `data_config`，不是 list/get/create/delete 命令参数。创建或更新 block 前先读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)，组件必须串行创建；`+dashboard-arrange` 是服务端智能布局，只在用户明确要求重排/美化时执行。`+dashboard-block-get-data` 读取图表最终计算结果，不返回 block 名称、类型、布局或 `data_config`；需要元数据先用 `+dashboard-block-get`。
+- Workflow 的复杂点是 `steps` 结构。创建、更新或解释完整 workflow 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；enable/disable/list 只需确认 workflow ID、当前启停状态和用户意图。
+- Role 的复杂点是权限 JSON。角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)；`+role-create` 只支持自定义角色；`+role-update` 是 delta merge；角色 create/update 或解读完整配置时读权限 JSON SSOT [role-config.md](references/role-config.md)。`+role-delete` 只适用于自定义角色，系统角色不可删除；删除角色和关闭高级权限前必须确认目标和影响。
+
 ## 常见恢复
 
 | 错误 / 现象 | 恢复动作 |
@@ -170,3 +149,18 @@ done
 | `1254104` | 批量超过 200，分批调用 |
 | `1254291` | 并发写冲突，串行写入并在批次间短暂等待 |
 | `91403` | 无权限访问该 Base，按 `lark-shared` 权限流程处理，不要盲目重试 |
+
+## 保留 Reference
+
+- [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md)：查询/统计/全局结论的选路 SOP
+- [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md) / [lark-base-data-query.md](references/lark-base-data-query.md)：聚合查询入口 fewshot 与 DSL SSOT
+- [lark-base-cell-value.md](references/lark-base-cell-value.md)：记录 CellValue 构造
+- [lark-base-field-json.md](references/lark-base-field-json.md)：字段 JSON 构造
+- [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)：公式与 lookup 字段
+- [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md)：字段创建/更新命令级补充
+- [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) / [lark-base-record-history-list.md](references/lark-base-record-history-list.md)：记录写入 JSON 与历史返回解释
+- [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)：视图筛选 JSON
+- [lark-base-form-detail.md](references/lark-base-form-detail.md) / [lark-base-form-submit.md](references/lark-base-form-submit.md) / [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)：表单详情、提交和复杂 JSON
+- [lark-base-dashboard.md](references/lark-base-dashboard.md) / [dashboard-block-data-config.md](references/dashboard-block-data-config.md) / [lark-base-dashboard-block-get-data.md](references/lark-base-dashboard-block-get-data.md)：仪表盘、组件配置与图表结果协议
+- [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) / [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)：workflow 入口与 steps JSON SSOT
+- [lark-base-role-guide.md](references/lark-base-role-guide.md) / [role-config.md](references/role-config.md)：角色入口与权限 JSON SSOT

skills/lark-base/references/dashboard-block-data-config.md

@@ -2,8 +2,6 @@
 
 Block 的 `data_config` 字段因 `type` 不同而变化。本文档是 dashboard block `data_config` 的单一事实来源（SSOT），包含组件类型、字段结构、筛选格式、约束和可复制模板。
 
-`data_config` 是 dashboard block 的数据源配置。先用 `+table-list` 拿表，再用 `+field-list-batch --table-id <表1> --table-id <表2>` **一次批量**拿到相关表字段（不要逐表多次 `+field-list`，每次多余调用都拉高 token）；表用 **name**，不是 table_id；字段用 **field_name**。
-
 ## 支持的组件类型（`type` 枚举）
 
 | type 值 | 说明 |

skills/lark-base/references/formula-examples.md

@@ -1,115 +0,0 @@
-# Base Formula Examples and Requirement Translation
-
-> 本文件是 [formula-field-guide.md](formula-field-guide.md) 的按需补充：完整示例与"自然语言需求 → 公式"的翻译规则。
-
-## Section 13: Complete Examples
-
-### Example 1: Employee sales summary
-
-**Table structure** (from `+table-get`):
-
-- Employees: EmployeeID (Text), Name (Text), Department (Text)
-- Sales: ContractID (Number), SalespersonID (Text), Quantity (Number), Total (Number)
-
-**Current table**: Employees
-
-**Requirement**: For each employee, output "Sold XX orders" if they have sales records, otherwise "No sales records".
-
-**Formula**:
-
-```
-IF(
-  [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) >= 1,
-  "Sold " & [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) & " orders",
-  "No sales records"
-)
-```
-
-**Field JSON**:
-
-```json
-{
-  "type": "formula",
-  "name": "Sales Summary",
-  "expression": "IF([Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) >= 1, \"Sold \" & [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) & \" orders\", \"No sales records\")"
-}
-```
-
-**Explanation**: `[Sales].COUNTIF(...)` uses the entire Sales table as data range. CurrentValue represents each row in Sales, accessing `CurrentValue.[SalespersonID]` for that row's salesperson. `[EmployeeID]` refers to the current row in the Employees table (where the formula lives).
-
-### Example 2: Chained cross-table access via link fields
-
-**Table structure**:
-
-- Orders: ID (`auto_number`), OrderItems (`link` [target: OrderItems, foreign key: ID])
-- OrderItems: ID (`auto_number`), Product (`link` [target: Products, foreign key: ID])
-- Products: ID (`auto_number`), ProductName (`text`)
-
-**Current table**: Orders
-
-**Requirement**: Deduplicate and comma-join all product names from linked order items.
-
-**Formula**:
-
-```
-[OrderItems].[Product].[ProductName].UNIQUE().ARRAYJOIN(",")
-```
-
-**Field JSON**:
-
-```json
-{
-  "type": "formula",
-  "name": "Product List",
-  "expression": "[OrderItems].[Product].[ProductName].UNIQUE().ARRAYJOIN(\",\")"
-}
-```
-
-**Explanation**: `[OrderItems]` gets linked order item records, `.[Product]` expands to each item's linked product, `.[ProductName]` gets all product names, `.UNIQUE()` deduplicates, `.ARRAYJOIN(",")` joins with commas.
-
-### Example 3: Cross-table filter + sort
-
-**Table structure**:
-
-- Projects: ProjectName (Text), Status (Text), Owner (Text)
-- Tasks: TaskName (Text), Project (Text), Priority (Number), DueDate (Date)
-
-**Current table**: Projects
-
-**Requirement**: Find the highest-priority (lowest number) task name for the current project.
-
-**Formula**:
-
-```
-FIRST(
-  [Tasks].FILTER(CurrentValue.[Project] = [ProjectName]).SORTBY([Tasks].[Priority], TRUE).[TaskName]
-)
-```
-
-**Field JSON**:
-
-```json
-{
-  "type": "formula",
-  "name": "Top Priority Task",
-  "expression": "FIRST([Tasks].FILTER(CurrentValue.[Project] = [ProjectName]).SORTBY([Tasks].[Priority], TRUE).[TaskName])"
-}
-```
-
-**Explanation**: `[Tasks].FILTER(CurrentValue.[Project] = [ProjectName])` filters tasks belonging to the current project. `.SORTBY([Tasks].[Priority], TRUE)` sorts by priority ascending. `.[TaskName]` extracts task names. `FIRST(...)` gets the first one (highest priority).
-
----
-
-## Section 14: Translating User Requirements to Formulas
-
-When the user describes their formula need in natural language, follow these rules to convert it into a precise expression:
-
-1. **Numbers must use precise values**: "less than 80%" → field value less than `0.8`. "above 1000" → `>= 1000`.
-2. **Interval boundaries**: "above/below/within" = closed (inclusive); "less than/more than/outside" = open (exclusive).
-3. **Branching logic** must be organized as an ordered list with a fallback branch. Each branch has a condition and output.
-   - Example: "return risk level for 1-3" → `IFS([Value] = 1, "low", [Value] = 2, "medium", [Value] = 3, "high")` with an `IFERROR` or trailing empty-string fallback.
-4. **Multi-level branches must be flattened** to a single level. Nested if-else chains → flat IFS.
-5. **Branch conditions must be mutually exclusive**. If the user's conditions overlap, rewrite to eliminate ambiguity.
-6. **Reorder branches by logical priority** if the user's order is illogical (e.g., check specific conditions before catch-all).
-
----

skills/lark-base/references/formula-field-guide.md

@@ -34,11 +34,11 @@ When creating a formula field, the Agent should:
 
 This is the foundation of formula logic. You must determine this before writing any formula.
 
-| Syntax | Meaning | Return type | Example |
-|---|---|---|---|
-| `[Field]` | Value of this field in the current row | Scalar (single value) | `[Name]` → `"Alice"` |
+| Syntax                | Meaning                                      | Return type            | Example                                      |
+| --------------------- | -------------------------------------------- | ---------------------- | -------------------------------------------- |
+| `[Field]`             | Value of this field in the current row       | Scalar (single value)  | `[Name]` → `"Alice"`                         |
 | `[TableName].[Field]` | All values of this field in the target table | List (multiple values) | `[Employees].[Name]` → `["Alice","Bob",...]` |
-| `[TableName]` | The target table (entire table) | Table reference | Used as data range for FILTER/COUNTIF etc. |
+| `[TableName]`         | The target table (entire table)              | Table reference        | Used as data range for FILTER/COUNTIF etc.   |
 
 **Rules**:
 
@@ -59,7 +59,7 @@ This is the foundation of formula logic. You must determine this before writing
 ### Field storage types
 
 | Type | Description | Supported operations |
-|---|---|---|
+|------|-------------|----------------------|
 | `number` | Stored as numeric value | Math operations, comparisons, auto-converts to string for concatenation |
 | `text` | Stored as string | String operations; can participate in math if content is numeric, otherwise errors |
 | `datetime` | Date object | Date functions, add/subtract with numbers; auto-converts to default format string when using `&` — use TEXT to format first for controlled output |
@@ -69,13 +69,13 @@ This is the foundation of formula logic. You must determine this before writing
 
 ### Implicit type conversion
 
-| Scenario | Conversion rule |
-|---|---|
-| Number + Float | → Float |
-| Date + Number | → Date (adds/subtracts days). Use `+`/`-` for whole days, use `DURATION()` for hour/minute/second precision |
-| Date - Date | → Duration |
-| Boolean compared with Number | Boolean auto-converts to number (TRUE=1, FALSE=0) |
-| `&` concatenation | Both sides auto-convert to string |
+| Scenario                     | Conversion rule                                                                                             |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Number + Float               | → Float                                                                                                     |
+| Date + Number                | → Date (adds/subtracts days). Use `+`/`-` for whole days, use `DURATION()` for hour/minute/second precision |
+| Date - Date                  | → Duration                                                                                                  |
+| Boolean compared with Number | Boolean auto-converts to number (TRUE=1, FALSE=0)                                                           |
+| `&` concatenation            | Both sides auto-convert to string                                                                           |
 
 ### Type consistency in comparisons
 
@@ -97,12 +97,12 @@ When using comparison operators (`>`, `>=`, `<`, `<=`, `=`, `!=`), **both sides
 
 ### CurrentValue meaning in different contexts
 
-| Data range type | CurrentValue represents | Access pattern | Example |
-|---|---|---|---|
-| Entire table `[TableName]` | A row in the table | `CurrentValue.[FieldName]` | `[Orders].FILTER(CurrentValue.[Amount] > 100).[Customer]` |
-| Column `[TableName].[Field]` | A single field value | Use `CurrentValue` directly | `[Orders].[Amount].FILTER(CurrentValue > 100)` |
+| Data range type              | CurrentValue represents | Access pattern              | Example                                                   |
+| ---------------------------- | ----------------------- | --------------------------- | --------------------------------------------------------- |
+| Entire table `[TableName]`   | A row in the table      | `CurrentValue.[FieldName]`  | `[Orders].FILTER(CurrentValue.[Amount] > 100).[Customer]` |
+| Column `[TableName].[Field]` | A single field value    | Use `CurrentValue` directly | `[Orders].[Amount].FILTER(CurrentValue > 100)`            |
 | `select` (`multiple=true`) field `[Tags]` | One option | Use `CurrentValue` directly | `[Tags].FILTER(CurrentValue = "Important")` |
-| LIST-generated list | One element | Use `CurrentValue` directly | `LIST(1,2,3).MAP(CurrentValue * 2)` |
+| LIST-generated list          | One element             | Use `CurrentValue` directly | `LIST(1,2,3).MAP(CurrentValue * 2)`                       |
 
 ### Key rules
 
@@ -113,11 +113,11 @@ When using comparison operators (`>`, `>=`, `<`, `<=`, `=`, `!=`), **both sides
 
 ### Anti-patterns
 
-| Wrong | Reason | Correct |
-|---|---|---|
-| `[Table].[Col].FILTER(CurrentValue.[Col] > 0)` | Data range is a column; CurrentValue is a scalar, cannot use `.` to access fields | `[Table].[Col].FILTER(CurrentValue > 0)` |
-| `[Table].FILTER(CurrentValue > 100)` | Data range is a table; CurrentValue is a row, cannot compare directly | `[Table].FILTER(CurrentValue.[Amount] > 100).[Amount]` |
-| `CurrentValue + 1` (at top level) | CurrentValue can only be used inside iteration functions | Use inside MAP/FILTER etc. |
+| Wrong                                          | Reason                                                                            | Correct                                                |
+| ---------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `[Table].[Col].FILTER(CurrentValue.[Col] > 0)` | Data range is a column; CurrentValue is a scalar, cannot use `.` to access fields | `[Table].[Col].FILTER(CurrentValue > 0)`               |
+| `[Table].FILTER(CurrentValue > 100)`           | Data range is a table; CurrentValue is a row, cannot compare directly             | `[Table].FILTER(CurrentValue.[Amount] > 100).[Amount]` |
+| `CurrentValue + 1` (at top level)              | CurrentValue can only be used inside iteration functions                          | Use inside MAP/FILTER etc.                             |
 
 ---
 
@@ -125,12 +125,12 @@ When using comparison operators (`>`, `>=`, `<`, `<=`, `=`, `!=`), **both sides
 
 Base formulas **only allow** the following operators. `like`, `in`, `<>`, `**`, `^` etc. are prohibited.
 
-| Category | Operators | Description |
-|---|---|---|
-| Arithmetic | `+` `-` `*` `/` `%` | Add, subtract, multiply, divide, modulo (`%` is equivalent to `MOD()`) |
-| Comparison | `>` `>=` `<` `<=` `=` `!=` | Greater than, greater or equal, less than, less or equal, equal, not equal |
-| Logical | `&&` `\|\|` | AND, OR |
-| Concatenation | `&` | Text concatenation; non-text values auto-convert to string |
+| Category      | Operators                  | Description                                                                |
+| ------------- | -------------------------- | -------------------------------------------------------------------------- |
+| Arithmetic    | `+` `-` `*` `/` `%`        | Add, subtract, multiply, divide, modulo (`%` is equivalent to `MOD()`)     |
+| Comparison    | `>` `>=` `<` `<=` `=` `!=` | Greater than, greater or equal, less than, less or equal, equal, not equal |
+| Logical       | `&&` `\|\|`                | AND, OR                                                                    |
+| Concatenation | `&`                        | Text concatenation; non-text values auto-convert to string                 |
 
 **Important**:
 
@@ -174,10 +174,10 @@ Retrieves the target field values for all linked records as a list. Supports con
 
 ### Two calling styles
 
-| Style | Format | Description |
-|---|---|---|
-| Functional | `FUNC(arg1, arg2)` | Works for all functions |
-| Chained | `arg1.FUNC(arg2)` | Moves the first argument before `.` |
+| Style      | Format             | Description                         |
+| ---------- | ------------------ | ----------------------------------- |
+| Functional | `FUNC(arg1, arg2)` | Works for all functions             |
+| Chained    | `arg1.FUNC(arg2)`  | Moves the first argument before `.` |
 
 **Rules**:
 
@@ -228,139 +228,175 @@ After the result column, it's recommended to flatten with `.LISTCOMBINE()` first
 
 ---
 
-## Section 8: Function Reference (common functions)
-
-> 本表覆盖常用函数（含评测与真实负载中 100% 出现过的函数）。三角/双曲/随机数/进制转换等罕见函数的签名在 [formula-functions-extended.md](formula-functions-extended.md)，仅当用户明确要求这些函数时再读。
+## Section 8: Complete Function Reference
 
 ### 8.1 Logic functions
 
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| IF | `IF(condition, true_val, [false_val])` | Matches branch type | Returns true_val when TRUE, false_val otherwise; omitting false_val returns false (not null) |
-| IFS | `IFS(cond1, val1, cond2, val2, ...)` | Matches branch type | Multi-condition branching; returns value for the first TRUE condition |
-| SWITCH | `SWITCH(expr, match1, result1, [match2, result2, ...], [default])` | Matches branch type | Matches expression value and returns corresponding result |
-| IFERROR | `IFERROR(expr, fallback)` | Matches branch type | Returns fallback when expression errors |
-| IFBLANK | `IFBLANK(expr, fallback)` | Matches branch type | Returns fallback when expression is blank (blank = NULL/empty string/empty list) |
-| AND | `AND(cond1, cond2, ...)` | Boolean | TRUE when all conditions are TRUE |
-| OR | `OR(cond1, cond2, ...)` | Boolean | TRUE when any condition is TRUE |
-| NOT | `NOT(condition)` | Boolean | Logical negation |
-| ISBLANK | `ISBLANK(value)` | Boolean | Tests if blank (NULL/empty string/empty list are blank; 0 and FALSE are not) |
-| ISNULL | `ISNULL(value)` | Boolean | Tests if NULL (only NULL is true; empty string is not) |
-| CONTAIN | `CONTAIN(search_range, value, ...)` | Boolean | Tests if a list or `select` (`multiple=true`) contains the value; **does NOT do text substring matching** |
-| RECORD_ID | `RECORD_ID()` | Text | Returns the current row's record ID |
+| Function      | Signature                                                          | Return type          | Description                                                                                  |
+| ------------- | ------------------------------------------------------------------ | -------------------- | -------------------------------------------------------------------------------------------- |
+| IF            | `IF(condition, true_val, [false_val])`                             | Matches branch type  | Returns true_val when TRUE, false_val otherwise; omitting false_val returns false (not null) |
+| IFS           | `IFS(cond1, val1, cond2, val2, ...)`                               | Matches branch type  | Multi-condition branching; returns value for the first TRUE condition                        |
+| SWITCH        | `SWITCH(expr, match1, result1, [match2, result2, ...], [default])` | Matches branch type  | Matches expression value and returns corresponding result                                    |
+| IFERROR       | `IFERROR(expr, fallback)`                                          | Matches branch type  | Returns fallback when expression errors                                                      |
+| IFBLANK       | `IFBLANK(expr, fallback)`                                          | Matches branch type  | Returns fallback when expression is blank (blank = NULL/empty string/empty list)             |
+| AND           | `AND(cond1, cond2, ...)`                                           | Boolean              | TRUE when all conditions are TRUE                                                            |
+| OR            | `OR(cond1, cond2, ...)`                                            | Boolean              | TRUE when any condition is TRUE                                                              |
+| NOT           | `NOT(condition)`                                                   | Boolean              | Logical negation                                                                             |
+| ISBLANK       | `ISBLANK(value)`                                                   | Boolean              | Tests if blank (NULL/empty string/empty list are blank; 0 and FALSE are not)                 |
+| ISNULL        | `ISNULL(value)`                                                    | Boolean              | Tests if NULL (only NULL is true; empty string is not)                                       |
+| ISERROR       | `ISERROR(expr)`                                                    | Boolean              | Tests if expression errors                                                                   |
+| ISNUMBER      | `ISNUMBER(value)`                                                  | Boolean              | Tests if value is a number                                                                   |
+| CONTAIN       | `CONTAIN(search_range, value, ...)`                                | Boolean              | Tests if a list or `select` (`multiple=true`) contains the value; **does NOT do text substring matching** |
+| CONTAINSALL   | `CONTAINSALL(search_range, value, ...)`                            | Boolean              | Tests if a list or `select` (`multiple=true`) contains all specified values |
+| CONTAINSONLY  | `CONTAINSONLY(search_range, value, ...)`                           | Boolean              | Tests if a list or `select` (`multiple=true`) contains only the specified values |
+| TRUE          | `TRUE()`                                                           | Boolean              | Returns TRUE                                                                                 |
+| FALSE         | `FALSE()`                                                          | Boolean              | Returns FALSE                                                                                |
+| RECORD_ID     | `RECORD_ID()`                                                      | Text                 | Returns the current row's record ID                                                          |
+| RANDOMBETWEEN | `RANDOMBETWEEN(min_int, max_int, [keep_updating])`                 | Number               | Random integer in the specified range                                                        |
+| RANDOMITEM    | `RANDOMITEM(list, [keep_updating])`                                | Matches element type | Randomly picks one element from a list                                                       |
 
 ### 8.2 Numeric functions
 
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| SUM | `SUM(val1, val2, ...)` | Number | Sum; accepts multiple values or a list |
-| AVERAGE | `AVERAGE(val1, val2, ...)` | Number | Average |
-| MAX | `MAX(val1, val2, ...)` | Number | Maximum |
-| MIN | `MIN(val1, val2, ...)` | Number | Minimum |
-| COUNTA | `COUNTA(val1, val2, ...)` | Number | Count of non-blank values |
-| COUNTIF | `COUNTIF(data_range, condition)` | Number | Count matching items. Data range can be a **table** (CurrentValue is a row, use `CurrentValue.[Field]`) or a **column** (CurrentValue is a scalar value) |
-| SUMIF | `SUMIF(data_range, condition)` | Number | Sum matching values. Data range **must be a numeric column** (e.g. `[Table].[NumField]`); CurrentValue is each value in that column (scalar), cannot use `CurrentValue.[Field]` to access other fields. For cross-field conditions, use FILTER+SUM instead |
-| ROUND | `ROUND(number, digits)` | Number | Round. digits: 1=one decimal, 0=integer, -1=tens place |
-| ABS | `ABS(number)` | Number | Absolute value |
-| INT | `INT(number)` | Integer | Truncate to integer |
-| MOD | `MOD(dividend, divisor)` | Number | Modulo |
-| VALUE | `VALUE(text)` | Number | Convert text to number |
+| Function                                                          | Signature                                | Return type | Description                                                                                                                                                                                                                                                |
+| --- | --- | --- | --- |
+| SUM                                                               | `SUM(val1, val2, ...)`                   | Number      | Sum; accepts multiple values or a list                                                                                                                                                                                                                     |
+| AVERAGE                                                           | `AVERAGE(val1, val2, ...)`               | Number      | Average                                                                                                                                                                                                                                                    |
+| MAX                                                               | `MAX(val1, val2, ...)`                   | Number      | Maximum                                                                                                                                                                                                                                                    |
+| MIN                                                               | `MIN(val1, val2, ...)`                   | Number      | Minimum                                                                                                                                                                                                                                                    |
+| MEDIAN                                                            | `MEDIAN(val1, val2, ...)`                | Number      | Median                                                                                                                                                                                                                                                     |
+| COUNTA                                                            | `COUNTA(val1, val2, ...)`                | Number      | Count of non-blank values                                                                                                                                                                                                                                  |
+| COUNTIF                                                           | `COUNTIF(data_range, condition)`         | Number      | Count matching items. Data range can be a **table** (CurrentValue is a row, use `CurrentValue.[Field]`) or a **column** (CurrentValue is a scalar value)                                                                                                   |
+| SUMIF                                                             | `SUMIF(data_range, condition)`           | Number      | Sum matching values. Data range **must be a numeric column** (e.g. `[Table].[NumField]`); CurrentValue is each value in that column (scalar), cannot use `CurrentValue.[Field]` to access other fields. For cross-field conditions, use FILTER+SUM instead |
+| ROUND                                                             | `ROUND(number, digits)`                  | Number      | Round. digits: 1=one decimal, 0=integer, -1=tens place                                                                                                                                                                                                     |
+| ROUNDUP                                                           | `ROUNDUP(number, digits)`                | Number      | Round away from zero. Same digits semantics as ROUND                                                                                                                                                                                                       |
+| ROUNDDOWN                                                         | `ROUNDDOWN(number, digits)`              | Number      | Round toward zero. Same digits semantics as ROUND                                                                                                                                                                                                          |
+| FLOOR                                                             | `FLOOR(number, [base])`                  | Number      | Round down to nearest multiple of base (default 1)                                                                                                                                                                                                         |
+| CEILING                                                           | `CEILING(number, [base])`                | Number      | Round up to nearest multiple of base (default 1)                                                                                                                                                                                                           |
+| ABS                                                               | `ABS(number)`                            | Number      | Absolute value                                                                                                                                                                                                                                             |
+| INT                                                               | `INT(number)`                            | Integer     | Truncate to integer                                                                                                                                                                                                                                        |
+| MOD                                                               | `MOD(dividend, divisor)`                 | Number      | Modulo                                                                                                                                                                                                                                                     |
+| POWER                                                             | `POWER(base, exponent)`                  | Number      | Exponentiation                                                                                                                                                                                                                                             |
+| QUOTIENT                                                          | `QUOTIENT(dividend, divisor)`            | Number      | Integer division                                                                                                                                                                                                                                           |
+| VALUE                                                             | `VALUE(text)`                            | Number      | Convert text to number                                                                                                                                                                                                                                     |
+| ISODD                                                             | `ISODD(number)`                          | Boolean     | Tests if number is odd                                                                                                                                                                                                                                     |
+| RANK                                                              | `RANK(value, search_range, [ascending])` | Number      | Rank of value in range; default descending                                                                                                                                                                                                                 |
+| SEQUENCE                                                          | `SEQUENCE(start, end, [step])`           | List        | Generate number sequence                                                                                                                                                                                                                                   |
+| PI                                                                | `PI()`                                   | Number      | Pi constant                                                                                                                                                                                                                                                |
+| SIN/COS/TAN/ASIN/ACOS/ATAN/ATAN2/SINH/COSH/TANH/ASINH/ACOSH/ATANH | `func(radians_or_value)`                 | Number      | Trigonometric and hyperbolic functions; arguments in radians                                                                                                                                                                                               |
 
 ### 8.3 Text functions
 
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| CONCATENATE | `CONCATENATE(text1, text2, ...)` | Text | Concatenate multiple texts; supports lists as input |
-| LEN | `LEN(text)` | Number | Character count |
-| LEFT | `LEFT(text, [count])` | Text | Extract from left; default 1 |
-| RIGHT | `RIGHT(text, [count])` | Text | Extract from right; default 1 |
-| MID | `MID(text, start, count)` | Text | Extract from middle |
-| REPLACE | `REPLACE(text, start, count, new_text)` | Text | Replace by position |
-| SUBSTITUTE | `SUBSTITUTE(text, old_text, new_text, [occurrence])` | Text | Replace by content; can specify which occurrence |
-| UPPER | `UPPER(text)` | Text | Convert to uppercase |
-| LOWER | `LOWER(text)` | Text | Convert to lowercase |
-| TRIM | `TRIM(text)` | Text | Remove leading/trailing spaces |
-| TEXT | `TEXT(value, format)` | Text | Format output. Date formats: `"YYYY-MM-DD"`, `"YYYY/MM/DD hh:mm:ss"`; number formats: `"00"`, `"000.00"` |
-| CONTAINTEXT | `CONTAINTEXT(text, search_text)` | Boolean | Tests if text contains substring (text substring matching) |
-| SPLIT | `SPLIT(text, delimiter)` | List | Split text by delimiter |
+| Function        | Signature                                            | Return type | Description                                                                                              |
+| --------------- | ---------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
+| CONCATENATE     | `CONCATENATE(text1, text2, ...)`                     | Text        | Concatenate multiple texts; supports lists as input                                                      |
+| LEN             | `LEN(text)`                                          | Number      | Character count                                                                                          |
+| LEFT            | `LEFT(text, [count])`                                | Text        | Extract from left; default 1                                                                             |
+| RIGHT           | `RIGHT(text, [count])`                               | Text        | Extract from right; default 1                                                                            |
+| MID             | `MID(text, start, count)`                            | Text        | Extract from middle                                                                                      |
+| FIND            | `FIND(search_val, search_range, [start])`            | Number      | Find substring position (case-sensitive); returns -1 if not found                                        |
+| REPLACE         | `REPLACE(text, start, count, new_text)`              | Text        | Replace by position                                                                                      |
+| SUBSTITUTE      | `SUBSTITUTE(text, old_text, new_text, [occurrence])` | Text        | Replace by content; can specify which occurrence                                                         |
+| UPPER           | `UPPER(text)`                                        | Text        | Convert to uppercase                                                                                     |
+| LOWER           | `LOWER(text)`                                        | Text        | Convert to lowercase                                                                                     |
+| TRIM            | `TRIM(text)`                                         | Text        | Remove leading/trailing spaces                                                                           |
+| TEXT            | `TEXT(value, format)`                                | Text        | Format output. Date formats: `"YYYY-MM-DD"`, `"YYYY/MM/DD hh:mm:ss"`; number formats: `"00"`, `"000.00"` |
+| CONTAINTEXT     | `CONTAINTEXT(text, search_text)`                     | Boolean     | Tests if text contains substring (text substring matching)                                               |
+| SPLIT           | `SPLIT(text, delimiter)`                             | List        | Split text by delimiter                                                                                  |
+| TODATE          | `TODATE(value)`                                      | Date        | Convert date string to date type                                                                         |
+| CHAR            | `CHAR(number)`                                       | Text        | ASCII code to character                                                                                  |
+| FORMAT          | `FORMAT(template, [val1, val2, ...])`                | Text        | Template string formatting; use `{1}`, `{2}` as placeholders                                             |
+| HYPERLINK       | `HYPERLINK(url, [display_text])`                     | Hyperlink   | Create a hyperlink                                                                                       |
+| ENCODEURL       | `ENCODEURL(text)`                                    | Text        | URL encode                                                                                               |
+| REGEXMATCH      | `REGEXMATCH(text, regex)`                            | Boolean     | Regex match test                                                                                         |
+| REGEXEXTRACT    | `REGEXEXTRACT(text, regex)`                          | List        | Extract first match's capture groups                                                                     |
+| REGEXEXTRACTALL | `REGEXEXTRACTALL(text, regex)`                       | 2D List     | Extract all matches                                                                                      |
+| REGEXREPLACE    | `REGEXREPLACE(text, regex, replacement)`             | Text        | Regex replace                                                                                            |
 
 ### 8.4 Date functions
 
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| NOW | `NOW()` | Date | Current date and time |
-| TODAY | `TODAY()` | Date | Current date (midnight) |
-| DATE | `DATE(year, month, day)` | Date | Construct a date |
-| YEAR | `YEAR(date)` | Number | Extract year |
-| MONTH | `MONTH(date)` | Number | Extract month |
-| DAY | `DAY(date)` | Number | Extract day |
-| HOUR | `HOUR(date)` | Number | Extract hour |
-| MINUTE | `MINUTE(date)` | Number | Extract minute |
-| SECOND | `SECOND(date)` | Number | Extract second |
-| WEEKDAY | `WEEKDAY(date, [type])` | Number | Day of week |
-| WEEKNUM | `WEEKNUM(date, [type])` | Number | Week number |
-| DAYS | `DAYS(end_date, start_date)` | Number | Days between two dates (end - start), includes decimals. **Note parameter order: end date comes first** |
-| DATEDIF | `DATEDIF(start_date, end_date, [unit])` | Number | Whole days/months/years between dates. Unit: `"D"`(default)/`"M"`/`"Y"`. **Start must be before end** |
-| NETWORKDAYS | `NETWORKDAYS(start_date, end_date, [holidays])` | Number | Workdays between dates (inclusive) |
+| Function    | Signature                                       | Return type | Description                                                                                             |
+| ----------- | ----------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
+| NOW         | `NOW()`                                         | Date        | Current date and time                                                                                   |
+| TODAY       | `TODAY()`                                       | Date        | Current date (midnight)                                                                                 |
+| DATE        | `DATE(year, month, day)`                        | Date        | Construct a date                                                                                        |
+| YEAR        | `YEAR(date)`                                    | Number      | Extract year                                                                                            |
+| MONTH       | `MONTH(date)`                                   | Number      | Extract month                                                                                           |
+| DAY         | `DAY(date)`                                     | Number      | Extract day                                                                                             |
+| HOUR        | `HOUR(date)`                                    | Number      | Extract hour                                                                                            |
+| MINUTE      | `MINUTE(date)`                                  | Number      | Extract minute                                                                                          |
+| SECOND      | `SECOND(date)`                                  | Number      | Extract second                                                                                          |
+| WEEKDAY     | `WEEKDAY(date, [type])`                         | Number      | Day of week                                                                                             |
+| WEEKNUM     | `WEEKNUM(date, [type])`                         | Number      | Week number                                                                                             |
+| DAYS        | `DAYS(end_date, start_date)`                    | Number      | Days between two dates (end - start), includes decimals. **Note parameter order: end date comes first** |
+| DATEDIF     | `DATEDIF(start_date, end_date, [unit])`         | Number      | Whole days/months/years between dates. Unit: `"D"`(default)/`"M"`/`"Y"`. **Start must be before end**   |
+| DURATION    | `DURATION(days, [hours], [minutes], [seconds])` | Duration    | Create a duration for date arithmetic                                                                   |
+| EDATE       | `EDATE(date, months)`                           | Date        | Date N months later                                                                                     |
+| EOMONTH     | `EOMONTH(date, [months])`                       | Date        | End of month N months later; months default 0                                                           |
+| WORKDAY     | `WORKDAY(start_date, days, [holidays])`         | Date        | Date N workdays later (skips weekends and holidays)                                                     |
+| NETWORKDAYS | `NETWORKDAYS(start_date, end_date, [holidays])` | Number      | Workdays between dates (inclusive)                                                                      |
 
 ### 8.5 List functions
 
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| FIRST | `FIRST(list)` | Scalar | First element |
-| LAST | `LAST(list)` | Scalar | Last element |
-| FILTER | `[Table].FILTER(condition).[ResultCol]` or `[Table].[Col].FILTER(condition)` | List | Filter by condition. When data range is a table, result column is **required**; when it's a column/list, it's not needed. Use CurrentValue in conditions. Add `.LISTCOMBINE()` when result column is multi-value |
-| MAP | `data_range.MAP(mapping_expr)` | List | Apply mapping to each element. Use CurrentValue in mapping |
-| SORT | `SORT(list, [ascending])` | List | Sort; default ascending (TRUE) |
-| SORTBY | `[Table].SORTBY([Table].[SortCol], [ascending]).[OutputCol]` | List | Sort by column then extract output column. **Chain-only, must include output column** |
-| UNIQUE | `UNIQUE(list)` | List | Deduplicate |
-| ARRAYJOIN | `ARRAYJOIN(list, [delimiter])` | Text | Join list elements as text; default comma-separated |
-| LISTCOMBINE | `LISTCOMBINE(val1, [val2, ...])` or `list.LISTCOMBINE()` | List | Two uses: (1) merge values/lists into one list; (2) chained call to flatten 2D array (commonly used when FILTER result column is a multi-value field) |
+| Function    | Signature                                                                    | Return type | Description                                                                                                                                                                                                      |
+| --- | --- | --- | --- |
+| LIST        | `LIST(val1, val2, ...)`                                                      | List        | Create a list                                                                                                                                                                                                    |
+| FIRST       | `FIRST(list)`                                                                | Scalar      | First element                                                                                                                                                                                                    |
+| LAST        | `LAST(list)`                                                                 | Scalar      | Last element                                                                                                                                                                                                     |
+| NTH         | `NTH(list, index)`                                                           | Scalar      | Nth element (1-based)                                                                                                                                                                                            |
+| FILTER      | `[Table].FILTER(condition).[ResultCol]` or `[Table].[Col].FILTER(condition)` | List        | Filter by condition. When data range is a table, result column is **required**; when it's a column/list, it's not needed. Use CurrentValue in conditions. Add `.LISTCOMBINE()` when result column is multi-value |
+| MAP         | `data_range.MAP(mapping_expr)`                                               | List        | Apply mapping to each element. Use CurrentValue in mapping                                                                                                                                                       |
+| SORT        | `SORT(list, [ascending])`                                                    | List        | Sort; default ascending (TRUE)                                                                                                                                                                                   |
+| SORTBY      | `[Table].SORTBY([Table].[SortCol], [ascending]).[OutputCol]`                 | List        | Sort by column then extract output column. **Chain-only, must include output column**                                                                                                                            |
+| UNIQUE      | `UNIQUE(list)`                                                               | List        | Deduplicate                                                                                                                                                                                                      |
+| ARRAYJOIN   | `ARRAYJOIN(list, [delimiter])`                                               | Text        | Join list elements as text; default comma-separated                                                                                                                                                              |
+| LISTCOMBINE | `LISTCOMBINE(val1, [val2, ...])` or `list.LISTCOMBINE()`                     | List        | Two uses: (1) merge values/lists into one list; (2) chained call to flatten 2D array (commonly used when FILTER result column is a multi-value field)                                                            |
+| DISTANCE    | `DISTANCE(location1, location2)`                                             | Number      | Distance between two geographic locations (km)                                                                                                                                                                   |
 
 ---
+
 ## Section 9: Commonly Confused Functions
 
 ### CONTAIN vs CONTAINTEXT
 
-| | CONTAIN | CONTAINTEXT |
-|---|---|---|
-| Purpose | Tests if a **list / `select` (`multiple=true`)** contains a value | Tests if **text** contains a substring |
-| Example | `[Tags].CONTAIN("Urgent")` | `[Notes].CONTAINTEXT("completed")` |
+|             | CONTAIN                                                        | CONTAINTEXT                                                |
+| ----------- | -------------------------------------------------------------- | ---------------------------------------------------------- |
+| Purpose     | Tests if a **list / `select` (`multiple=true`)** contains a value | Tests if **text** contains a substring                     |
+| Example     | `[Tags].CONTAIN("Urgent")`                                     | `[Notes].CONTAINTEXT("completed")`                         |
 | Wrong usage | `CONTAIN([Notes], "completed")` — cannot do substring matching | `CONTAINTEXT([Tags], "Urgent")` — Tags is a list, not text |
 
 ### ISBLANK vs ISNULL
 
-| | ISBLANK | ISNULL |
-|---|---|---|
-| NULL | TRUE | TRUE |
-| `""` empty string | TRUE | FALSE |
-| Empty list `[]` | TRUE | FALSE |
-| `0` | FALSE | FALSE |
-| `FALSE` | FALSE | FALSE |
+|                   | ISBLANK | ISNULL |
+| ----------------- | ------- | ------ |
+| NULL              | TRUE    | TRUE   |
+| `""` empty string | TRUE    | FALSE  |
+| Empty list `[]`   | TRUE    | FALSE  |
+| `0`               | FALSE   | FALSE  |
+| `FALSE`           | FALSE   | FALSE  |
 
 ### DAYS vs DATEDIF
 
-| | DAYS | DATEDIF |
-|---|---|---|
-| Parameter order | `DAYS(end, start)` — end first | `DATEDIF(start, end, unit)` — start first |
-| Precision | Includes decimals (hours/minutes/seconds as fractional days) | Integer only (whole days/months/years) |
-| Negative values | Returns negative when start is after end | **Errors** when start is after end |
+|                 | DAYS                                                         | DATEDIF                                   |
+| --------------- | ------------------------------------------------------------ | ----------------------------------------- |
+| Parameter order | `DAYS(end, start)` — end first                               | `DATEDIF(start, end, unit)` — start first |
+| Precision       | Includes decimals (hours/minutes/seconds as fractional days) | Integer only (whole days/months/years)    |
+| Negative values | Returns negative when start is after end                     | **Errors** when start is after end        |
 
 ### SUM vs SUMIF
 
-| | SUM | SUMIF |
-|---|---|---|
-| Purpose | Sum all values | Sum values **matching a condition** |
-| Arguments | `SUM(val1, val2, ...)` or `SUM([Table].[Col])` | `SUMIF(data_range, condition)` with CurrentValue in condition |
-| Example | `SUM([Orders].[Amount])` — sum all | `SUMIF([Orders].[Amount], CurrentValue > 100)` — sum only >100 |
+|           | SUM                                            | SUMIF                                                          |
+| --------- | ---------------------------------------------- | -------------------------------------------------------------- |
+| Purpose   | Sum all values                                 | Sum values **matching a condition**                            |
+| Arguments | `SUM(val1, val2, ...)` or `SUM([Table].[Col])` | `SUMIF(data_range, condition)` with CurrentValue in condition  |
+| Example   | `SUM([Orders].[Amount])` — sum all             | `SUMIF([Orders].[Amount], CurrentValue > 100)` — sum only >100 |
 
 ### FILTER+aggregation vs COUNTIF/SUMIF
 
-| | FILTER+aggregation | COUNTIF/SUMIF |
-|---|---|---|
-| Nature | Filter then aggregate (two steps) | One-step (syntactic sugar) |
-| Equivalence | `[Table].FILTER(cond).[Col].LISTCOMBINE().SUM()` | `SUMIF([Table].[Col], cond)` (only when condition involves only column values) |
-| When to use | Conditions span multiple fields, or multi-step needed | Conditions only involve column values (e.g. `CurrentValue > 100`) |
+|             | FILTER+aggregation                                    | COUNTIF/SUMIF                                                                  |
+| ----------- | ----------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Nature      | Filter then aggregate (two steps)                     | One-step (syntactic sugar)                                                     |
+| Equivalence | `[Table].FILTER(cond).[Col].LISTCOMBINE().SUM()`      | `SUMIF([Table].[Col], cond)` (only when condition involves only column values) |
+| When to use | Conditions span multiple fields, or multi-step needed | Conditions only involve column values (e.g. `CurrentValue > 100`)              |
 
 ---
 
@@ -576,11 +612,119 @@ Reason: NOW, TODAY, PI and other zero-argument functions must include parenthese
 
 ---
 
-## Section 13: Examples
+## Section 13: Complete Examples
 
-完整示例与"自然语言需求 → 公式"翻译规则按需读 [formula-examples.md](formula-examples.md)。
+### Example 1: Employee sales summary
 
-## Section 14: Constraint Summary
+**Table structure** (from `+table-get`):
+
+- Employees: EmployeeID (Text), Name (Text), Department (Text)
+- Sales: ContractID (Number), SalespersonID (Text), Quantity (Number), Total (Number)
+
+**Current table**: Employees
+
+**Requirement**: For each employee, output "Sold XX orders" if they have sales records, otherwise "No sales records".
+
+**Formula**:
+
+```
+IF(
+  [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) >= 1,
+  "Sold " & [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) & " orders",
+  "No sales records"
+)
+```
+
+**Field JSON**:
+
+```json
+{
+  "type": "formula",
+  "name": "Sales Summary",
+  "expression": "IF([Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) >= 1, \"Sold \" & [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) & \" orders\", \"No sales records\")"
+}
+```
+
+**Explanation**: `[Sales].COUNTIF(...)` uses the entire Sales table as data range. CurrentValue represents each row in Sales, accessing `CurrentValue.[SalespersonID]` for that row's salesperson. `[EmployeeID]` refers to the current row in the Employees table (where the formula lives).
+
+### Example 2: Chained cross-table access via link fields
+
+**Table structure**:
+
+- Orders: ID (`auto_number`), OrderItems (`link` [target: OrderItems, foreign key: ID])
+- OrderItems: ID (`auto_number`), Product (`link` [target: Products, foreign key: ID])
+- Products: ID (`auto_number`), ProductName (`text`)
+
+**Current table**: Orders
+
+**Requirement**: Deduplicate and comma-join all product names from linked order items.
+
+**Formula**:
+
+```
+[OrderItems].[Product].[ProductName].UNIQUE().ARRAYJOIN(",")
+```
+
+**Field JSON**:
+
+```json
+{
+  "type": "formula",
+  "name": "Product List",
+  "expression": "[OrderItems].[Product].[ProductName].UNIQUE().ARRAYJOIN(\",\")"
+}
+```
+
+**Explanation**: `[OrderItems]` gets linked order item records, `.[Product]` expands to each item's linked product, `.[ProductName]` gets all product names, `.UNIQUE()` deduplicates, `.ARRAYJOIN(",")` joins with commas.
+
+### Example 3: Cross-table filter + sort
+
+**Table structure**:
+
+- Projects: ProjectName (Text), Status (Text), Owner (Text)
+- Tasks: TaskName (Text), Project (Text), Priority (Number), DueDate (Date)
+
+**Current table**: Projects
+
+**Requirement**: Find the highest-priority (lowest number) task name for the current project.
+
+**Formula**:
+
+```
+FIRST(
+  [Tasks].FILTER(CurrentValue.[Project] = [ProjectName]).SORTBY([Tasks].[Priority], TRUE).[TaskName]
+)
+```
+
+**Field JSON**:
+
+```json
+{
+  "type": "formula",
+  "name": "Top Priority Task",
+  "expression": "FIRST([Tasks].FILTER(CurrentValue.[Project] = [ProjectName]).SORTBY([Tasks].[Priority], TRUE).[TaskName])"
+}
+```
+
+**Explanation**: `[Tasks].FILTER(CurrentValue.[Project] = [ProjectName])` filters tasks belonging to the current project. `.SORTBY([Tasks].[Priority], TRUE)` sorts by priority ascending. `.[TaskName]` extracts task names. `FIRST(...)` gets the first one (highest priority).
+
+---
+
+## Section 14: Translating User Requirements to Formulas
+
+When the user describes their formula need in natural language, follow these rules to convert it into a precise expression:
+
+1. **Numbers must use precise values**: "less than 80%" → field value less than `0.8`. "above 1000" → `>= 1000`.
+2. **Interval boundaries**: "above/below/within" = closed (inclusive); "less than/more than/outside" = open (exclusive).
+3. **Branching logic** must be organized as an ordered list with a fallback branch. Each branch has a condition and output.
+   - Example: "return risk level for 1-3" → `IFS([Value] = 1, "low", [Value] = 2, "medium", [Value] = 3, "high")` with an `IFERROR` or trailing empty-string fallback.
+4. **Multi-level branches must be flattened** to a single level. Nested if-else chains → flat IFS.
+5. **Branch conditions must be mutually exclusive**. If the user's conditions overlap, rewrite to eliminate ambiguity.
+6. **Reorder branches by logical priority** if the user's order is illogical (e.g., check specific conditions before catch-all).
+
+---
+
+## Section 15: Constraint Summary
 
 - Request body must include `"type": "formula"` — this field is required
 - Only use functions and operators listed in this document

skills/lark-base/references/formula-functions-extended.md

@@ -1,66 +0,0 @@
-# Base Formula Functions — Extended (rare functions)
-
-> 本文件是 [formula-field-guide.md](formula-field-guide.md) Section 8 的长尾补充：三角/双曲/随机数/进制/统计扩展等罕见函数。
-> 表格列含义与主文档一致：Function | Signature | Return type | Description。
-
-## 8.1 Logic functions (extended)
-
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| ISERROR | `ISERROR(expr)` | Boolean | Tests if expression errors |
-| ISNUMBER | `ISNUMBER(value)` | Boolean | Tests if value is a number |
-| CONTAINSALL | `CONTAINSALL(search_range, value, ...)` | Boolean | Tests if a list or `select` (`multiple=true`) contains all specified values |
-| CONTAINSONLY | `CONTAINSONLY(search_range, value, ...)` | Boolean | Tests if a list or `select` (`multiple=true`) contains only the specified values |
-| TRUE | `TRUE()` | Boolean | Returns TRUE |
-| FALSE | `FALSE()` | Boolean | Returns FALSE |
-| RANDOMBETWEEN | `RANDOMBETWEEN(min_int, max_int, [keep_updating])` | Number | Random integer in the specified range |
-| RANDOMITEM | `RANDOMITEM(list, [keep_updating])` | Matches element type | Randomly picks one element from a list |
-
-## 8.2 Numeric functions (extended)
-
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| MEDIAN | `MEDIAN(val1, val2, ...)` | Number | Median |
-| ROUNDUP | `ROUNDUP(number, digits)` | Number | Round away from zero. Same digits semantics as ROUND |
-| ROUNDDOWN | `ROUNDDOWN(number, digits)` | Number | Round toward zero. Same digits semantics as ROUND |
-| FLOOR | `FLOOR(number, [base])` | Number | Round down to nearest multiple of base (default 1) |
-| CEILING | `CEILING(number, [base])` | Number | Round up to nearest multiple of base (default 1) |
-| POWER | `POWER(base, exponent)` | Number | Exponentiation |
-| QUOTIENT | `QUOTIENT(dividend, divisor)` | Number | Integer division |
-| ISODD | `ISODD(number)` | Boolean | Tests if number is odd |
-| RANK | `RANK(value, search_range, [ascending])` | Number | Rank of value in range; default descending |
-| SEQUENCE | `SEQUENCE(start, end, [step])` | List | Generate number sequence |
-| PI | `PI()` | Number | Pi constant |
-| SIN/COS/TAN/ASIN/ACOS/ATAN/ATAN2/SINH/COSH/TANH/ASINH/ACOSH/ATANH | `func(radians_or_value)` | Number | Trigonometric and hyperbolic functions; arguments in radians |
-
-## 8.3 Text functions (extended)
-
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| FIND | `FIND(search_val, search_range, [start])` | Number | Find substring position (case-sensitive); returns -1 if not found |
-| TODATE | `TODATE(value)` | Date | Convert date string to date type |
-| CHAR | `CHAR(number)` | Text | ASCII code to character |
-| FORMAT | `FORMAT(template, [val1, val2, ...])` | Text | Template string formatting; use `{1}`, `{2}` as placeholders |
-| HYPERLINK | `HYPERLINK(url, [display_text])` | Hyperlink | Create a hyperlink |
-| ENCODEURL | `ENCODEURL(text)` | Text | URL encode |
-| REGEXMATCH | `REGEXMATCH(text, regex)` | Boolean | Regex match test |
-| REGEXEXTRACT | `REGEXEXTRACT(text, regex)` | List | Extract first match's capture groups |
-| REGEXEXTRACTALL | `REGEXEXTRACTALL(text, regex)` | 2D List | Extract all matches |
-| REGEXREPLACE | `REGEXREPLACE(text, regex, replacement)` | Text | Regex replace |
-
-## 8.4 Date functions (extended)
-
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| DURATION | `DURATION(days, [hours], [minutes], [seconds])` | Duration | Create a duration for date arithmetic |
-| EDATE | `EDATE(date, months)` | Date | Date N months later |
-| EOMONTH | `EOMONTH(date, [months])` | Date | End of month N months later; months default 0 |
-| WORKDAY | `WORKDAY(start_date, days, [holidays])` | Date | Date N workdays later (skips weekends and holidays) |
-
-## 8.5 List functions (extended)
-
-| Function | Signature | Return type | Description |
-|---|---|---|---|
-| LIST | `LIST(val1, val2, ...)` | List | Create a list |
-| NTH | `NTH(list, index)` | Scalar | Nth element (1-based) |
-| DISTANCE | `DISTANCE(location1, location2)` | Number | Distance between two geographic locations (km) |

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

@@ -13,9 +13,6 @@
 - 一次 payload 里同一字段只用一种 key（字段名或字段 ID），不要重复。
 - 写入前先 `+field-list` 获取字段 `type/style/multiple`，再构造值。
 - 需要清空字段时优先传 `null`（字段允许清空时）。
-- 只写存储字段：系统字段、`formula`、`lookup` 只读；附件字段不走 CellValue，用 `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment`。
-- 批量写入单批最多 200 条（超出报 `1254104`）；同一张表串行写，遇 `1254291` 并发冲突短暂等待后重试。
-- select/multiselect 写入未知选项会触发平台新增该选项；不是要新增时，先用 `+field-list` 或 `+field-search-options` 确认可选值。
 
 ## 2. 各类型 CellValue
 

skills/lark-base/references/lark-base-dashboard-usecase.md

@@ -1,238 +0,0 @@
-# Dashboard（仪表盘/数据看板）模块指引
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**组件**（图表、指标卡等）进行展示。
-
-## 核心概念
-
-- **Dashboard（仪表盘）**：容器，包含多个组件
-- **Block（组件）**：仪表盘中的单个可视化元素（柱状图、折线图、饼图、指标卡等）
-- **data_config**：组件的数据源配置（表名、字段、分组等）
-
-## 能力速览
-
-| 你想做什么 | 用这些命令 | 关键文档 |
-|------|-----------|---------|
-| 创建/删除/改名称 | `+dashboard-create/delete/update` | 本页下方「仪表盘管理」 |
-| 在仪表盘里添加组件 | `+dashboard-block-create` | 先用 `+table-list` 拿表，再用 `+field-list-batch --table-id <表1> --table-id <表2>` 批量拿字段，再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 构造 `data_config` |
-| 修改组件 | `+dashboard-block-update` | 先读 block 现状，再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 决定替换哪些顶层 key |
-| 查看仪表盘有哪些组件 | `+dashboard-get` 或 `+dashboard-block-list` | 本页下方「查看仪表盘」 |
-| 读取图表计算结果 | `+dashboard-block-get-data` | 返回图表最终数据协议；需要 block 元数据先用 `+dashboard-block-get` |
-| 智能重排组件布局 | `+dashboard-arrange` | 只在用户明确要求重排时执行；无法指定精确位置 |
-
-## 典型场景工作流
-
-### 场景 1：从 0 到 1 创建仪表盘
-
-示例：搭建一个销售数据分析仪表盘
-
-```bash
-# 第 1 步：创建空白仪表盘
-lark-cli base +dashboard-create --base-token xxx --name "销售数据分析"
-# 记录返回的 dashboard_id
-
-# 第 2 步：获取数据源信息
-lark-cli base +table-list --base-token xxx  # 先拿表名/table_id
-lark-cli base +field-list-batch --base-token xxx --table-id tbl_a --table-id tbl_b  # 再一次批量拿相关表字段
-
-# 第 3 步：规划应该创建哪些组件（根据用户需求确定组件类型和数量）
-# 例如：总销售额（指标卡）、月度趋势（折线图）、品类占比（饼图）
-
-# 第 4 步：顺序创建每个组件（必须串行执行，不能并发）
-# 重要：创建组件前，先确定 dashboard_id、组件 name/type 和真实表字段
-# 再阅读 dashboard-block-data-config.md 了解 data_config 结构、组件类型和 filter 规则
-
-# 第 1 个组件
-lark-cli base +dashboard-block-create \
-  --base-token xxx \
-  --dashboard-id blk_xxx \
-  --name "总销售额" \
-  --type statistics \
-  --data-config '{"table_name":"订单表","series":[{"field_name":"金额","rollup":"SUM"}]}'
-
-# 第 2 个组件（等上一个完成后再执行）
-lark-cli base +dashboard-block-create \
-  --base-token xxx \
-  --dashboard-id blk_xxx \
-  --name "月度趋势" \
-  --type line \
-  --data-config '{"table_name":"订单表","series":[{"field_name":"金额","rollup":"SUM"}],"group_by":[{"field_name":"月份","mode":"integrated"}]}'
-
-# 继续创建其他组件...
-
-# 第 5 步：组件创建完成后，使用 arrange 命令智能重排布局（可选但推荐）
-# 默认布局可能不够美观，arrange 会根据组件数量和类型自动优化布局
-lark-cli base +dashboard-arrange \
-  --base-token xxx \
-  --dashboard-id blk_xxx
-```
-
-### 场景 2：在已有仪表盘上添加新组件
-
-```bash
-# 第 1 步：列出仪表盘，定位到当前仪表盘
-lark-cli base +dashboard-list --base-token xxx
-# 获取目标 dashboard_id
-
-# 第 2 步：根据用户诉求规划组件类型和数据源
-# 建议先查看当前仪表盘已有组件，避免重复创建，或作为参考
-lark-cli base +dashboard-get --base-token xxx --dashboard-id blk_xxx
-
-# 第 3 步：获取数据源信息
-lark-cli base +table-list --base-token xxx  # 先拿表名/table_id
-lark-cli base +field-list-batch --base-token xxx --table-id tbl_a --table-id tbl_b  # 再一次批量拿相关表字段
-
-# 第 4 步：顺序创建每个新组件（必须串行执行，不能并发）
-# 重要：先确定 dashboard_id、组件 name/type 和真实表字段
-# 再阅读 dashboard-block-data-config.md 了解 data_config 结构
-lark-cli base +dashboard-block-create \
-  --base-token xxx \
-  --dashboard-id blk_xxx \
-  --name "新组件名" \
-  --type column \
-  --data-config '{...}'
-```
-
-### 场景 3：编辑已有组件
-
-> [!IMPORTANT]
-> `+dashboard-block-update` **不能修改组件的 `type`**（图表类型），只能更新 `name` 和 `data_config`。
-> 如需更换组件类型，必须先删除再重新创建。
-
-```bash
-# 第 1 步：列出仪表盘，定位到当前仪表盘
-lark-cli base +dashboard-list --base-token xxx
-
-# 第 2 步：列出组件，获取到目标组件
-lark-cli base +dashboard-block-list --base-token xxx --dashboard-id blk_xxx
-# 获取目标 block_id
-# 提示：查看已有组件可作为参考，或检查是否重复创建相似组件
-
-# 第 3 步：获取组件当前详情
-lark-cli base +dashboard-block-get --base-token xxx --dashboard-id blk_xxx --block-id chtxxxxxxxx
-
-# 第 4 步：根据用户编辑诉求准备更新
-# 如果编辑诉求涉及数据源变更，需要先获取数据源信息
-lark-cli base +table-list --base-token xxx  # 先拿表名/table_id
-lark-cli base +field-list-batch --base-token xxx --table-id tbl_a --table-id tbl_b  # 再一次批量拿相关表字段
-
-# 第 5 步：执行更新
-# 重要：先读取当前 block 的 name/type/data_config
-# 再阅读 dashboard-block-data-config.md 了解 data_config 更新规则
-lark-cli base +dashboard-block-update \
-  --base-token xxx \
-  --dashboard-id blk_xxx \
-  --block-id chtxxxxxxxx \
-  --data-config '{...}'
-```
-
-### 场景 4：重排仪表盘布局
-
-当用户明确要求对已有仪表盘进行布局重排或美化时使用。
-
-> [!CAUTION]
-> - 排列结果是**服务端智能推荐**，不一定完全符合用户预期
-> - 无法指定具体位置（如"第一排放 A，第二排放 B"），排列逻辑是**自适应**的
-> - **不建议**在已有仪表盘上自动调用，除非用户明确要求
-
-```bash
-# 第 1 步：列出仪表盘，定位到目标仪表盘
-lark-cli base +dashboard-list --base-token xxx
-
-# 第 2 步：执行智能重排
-lark-cli base +dashboard-arrange \
-  --base-token xxx \
-  --dashboard-id blk_xxx
-```
-
-### 场景 5：读取仪表盘或组件现状
-
-**选择查询方式：**
-- 想看仪表盘整体结构（含主题、所有组件名称和类型）→ 用 **方式 A**
-- 只想快速查看有哪些组件 → 用 **方式 B**
-- 想看某个组件的详细 data_config 配置 → 用 **方式 C**
-- 想看某个图表/指标卡实际算出来的数据 → 用 **方式 D**
-
-```bash
-# 第 1 步：列出仪表盘，定位到当前仪表盘
-lark-cli base +dashboard-list --base-token xxx
-
-# 第 2 步：根据用户诉求查看详情
-
-# 方式 A：查看仪表盘整体情况（包含所有组件列表）
-lark-cli base +dashboard-get --base-token xxx --dashboard-id blk_xxx
-
-# 方式 B：列出所有组件
-lark-cli base +dashboard-block-list --base-token xxx --dashboard-id blk_xxx
-
-# 方式 C：查看某个组件的详细配置
-lark-cli base +dashboard-block-get --base-token xxx --dashboard-id blk_xxx --block-id chtxxxxxxxx
-
-# 方式 D：查看某个图表组件的计算结果（AI 友好的 chart protocol）
-lark-cli base +dashboard-block-get-data --base-token xxx --block-id chtxxxxxxxx
-
-# 最后：把获取到的现状信息整理好告诉用户
-```
-
-## 组件类型选择
-
-组件 `type` 决定展示形式：
-
-| 用户想看什么 | 选什么 type | 说明 |
-|-------------|------------|------|
-| 数据趋势（时间变化） | line | 折线图组件 |
-| 类别比较（谁高谁低） | column | 柱状图组件 |
-| 占比分布（各部分比例） | pie | 饼图组件 |
-| 单个关键指标 | statistics | 指标卡组件 |
-| 富文本说明/标题/注释 | text | 文本组件（支持 Markdown） |
-
-详细组件类型和 data_config 完整规则：[dashboard-block-data-config.md](dashboard-block-data-config.md)
-
-## 常见问题
-
-**Q: 创建组件的命令和 data_config 怎么写？**
-A:
-1. 先确定 `dashboard_id`、组件 `name`、组件 `type` 和真实表字段
-2. 再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解：
-   - 全部组件类型的可复制模板
-   - filter 筛选条件格式
-   - 字段类型与操作符对应表
-
-**Q: 为什么组件创建失败了？**
-A: 常见原因：
-- `table_name` 用了 table_id 而不是表名（必须用表名称，如「订单表」）
-- `series` 和 `count_all` 同时存在（必须二选一，互斥）
-- 字段名拼写错误（必须用 `+field-list` 获取的真实字段名，禁止猜测）
-- 组件创建并发执行（必须串行，等上一个完成再执行下一个）
-
-**Q: 可以一次创建多个组件吗？**
-A: 不可以，必须串行执行。等上一个 `+dashboard-block-create` 完成后再执行下一个。
-
-**Q: 组件的 `type` 创建后能改吗？**
-A: 不能。`+dashboard-block-update` 只能修改 `name` 和 `data_config`，不能修改 `type`。
-
-**Q: 更新组件的命令和 data_config 怎么写？**
-A:
-1. 先读取当前 block，确认 `block_id`、当前 `type` 和已有 `data_config`
-2. 再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解 data_config 结构
-
-**data_config 更新策略（顶层 key merge）**：
-- 只传入需要修改的顶层字段（如 `series`、`filter`）
-- 未传的顶层字段（如 `group_by`）自动保留原值
-- 但每个传入的字段内部是**全量替换**（如传新 `filter` 会完整覆盖旧 `filter`）
-
-**Q: 查看已有组件有什么用？**
-A: 在「添加新组件」或「编辑组件」前查看已有组件可以：
-- 了解当前仪表盘已有哪些可视化
-- 避免重复创建相似的组件
-- 参考已有组件的 data_config 结构作为模板
-
-**Q: 我想直接拿图表算好的结果给 AI 分析，应该用什么？**
-A: 用 `+dashboard-block-get-data`。它返回图表协议 JSON（常见字段包括 `dimensions`、`measures`、`main_data`，指标卡可能还有 `comparison_data`、`trend_data`），不返回 block 名称、类型、布局或 `data_config`；需要这些元数据时先用 `+dashboard-block-get`。
-
-## 写入前检查
-
-- 创建 block 前必须知道 `base_token`、`dashboard_id`、组件 `name/type` 和 `data_config`。
-- 更新 block 前必须知道 `base_token`、`dashboard_id`、`block_id`，并读过当前 block。
-- `data_config` 中使用表名和字段名，不使用 table_id / field_id；名称必须来自 `+table-list` / `+field-list` 的真实返回。

skills/lark-base/references/lark-base-dashboard.md

@@ -21,14 +21,6 @@ Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**
 | 读取图表计算结果 | `+dashboard-block-get-data` | 返回图表最终数据协议；需要 block 元数据先用 `+dashboard-block-get` |
 | 智能重排组件布局 | `+dashboard-arrange` | 只在用户明确要求重排时执行；无法指定精确位置 |
 
-## 执行要点
-
-- 创建/改图前先用 `+table-list` 拿表，再用 `+field-list-batch --table-id <表1> --table-id <表2>` 一次取多表字段，不要逐表多次 `+field-list`，多余调用会显著抬高 token。
-- 布局/重排/撑满/排列美观直接用 `+dashboard-arrange`，不要尝试用 `+dashboard-block-update` 修改 layout，layout 不是 `data_config`。
-- block 换图表类型或换数据源表（`table_name`）时，删除旧 block 后用 `+dashboard-block-create` 新建；`+dashboard-block-update` 只适合同一数据源内改 `series/filter/group_by/name`。
-- 删除具名图表：`+dashboard-list` → `+dashboard-block-list` 精确匹配名称 → `+dashboard-block-delete`；长 `block_id` 用变量传参，避免手抄截断。
-- 完整 dashboard 用例（从需求到逐组件落地）按需读 [lark-base-dashboard-usecase.md](lark-base-dashboard-usecase.md)。
-
 ## 典型场景工作流
 
 ### 场景 1：从 0 到 1 创建仪表盘

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

@@ -397,7 +397,6 @@
 
 默认值 / 约束：
 - `style.rules` 是规则数组，数量 `1..9`
-- `+field-update` 修改编号规则时，**默认会把新规则应用到已有记录**
 - 默认规则：
 
 ```json

skills/lark-base/references/lark-base-workflow-guide.md

@@ -1,130 +1,46 @@
 # Workflow guide
 
-本文档是 Workflow 的操作地图：先用它决定最短路径，再按需打开 schema 小文件。Guide 要一次读完后能完成大多数查询、启停和常见创建/修改；schema 才是零件手册。
+本文档是 Workflow 的入口指南，帮助选择步骤组合、理解创建/更新边界，并引导到 steps JSON SSOT。
 
-## 先判断任务类型
+> **配套文档**:
+> - Workflow 的数据结构参考：[lark-base-workflow-schema.md](lark-base-workflow-schema.md)
+> - 创建/更新时重点构造 `title`、`status` 和 `steps`；复杂度集中在 `steps[].type/data/next`
 
-| 目标 | 最短路径 | 是否读 schema |
-|---|---|---|
-| 列出 workflow | `+workflow-list --base-token <base>`；需要筛选启停状态时用 `--status` | 不读 |
-| 查看一个 workflow | 先 `+workflow-list` 后按标题本地匹配 `workflow_id`，再 `+workflow-get --workflow-id <wkf>` | 不读，除非要解释完整 `steps` |
-| 启用/停用 workflow | `+workflow-list --status <enabled|disabled>` 定位，再 `+workflow-enable/disable` | 不读 |
-| 创建简单 workflow | 读本 guide，按下方场景表打开必要 step schema | 只读命中的 step |
-| 修改 workflow | `+workflow-get` 取现状，保留无关字段，只改目标 step；复杂 step 再读 schema | 只读被改的 step |
-| 解释复杂 `steps` | 先用本 guide 的结构速记理解连线，再按 step type 打开 schema | 按需读 |
+---
 
-不要默认看 `--help`。只有命令报错、参数名不确定、或要确认复杂写入参数时，才看当前命令的 help。
+## 快速开始
 
-## 资源发现顺序
+### 最简单的 Workflow
 
-1. 从用户链接提取 `base_token`。
-2. 需要知道文档内资源时用 `+base-block-list` 或 `+table-list`；不要两者都跑，除非一个结果不够。
-3. 字段发现默认用 `+field-list --compact`；只有需要公式、lookup 或完整字段配置时再 `+field-get`。
-4. 多表字段发现用 `+field-list-batch --compact --table-id <id1> --table-id <id2>`。
-5. workflow 定位用 `+workflow-list` 读取列表，再按 `title` 本地匹配；当前命令没有 `--title` flag。
-
-## Workflow 结构速记
+新增记录时发送消息通知：
 
 ```json
 {
-  "client_token": "unique-create-token",
-  "title": "工作流标题",
+  "client_token": "1704067200",
+  "title": "新订单自动通知",
   "steps": [
     {
-      "id": "step_trigger",
+      "id": "trigger_1",
       "type": "AddRecordTrigger",
-      "title": "触发器",
-      "next": "step_action",
-      "data": {}
-    },
-    {
-      "id": "step_action",
-      "type": "LarkMessageAction",
-      "title": "动作",
-      "next": null,
-      "data": {}
-    }
-  ]
-}
-```
-
-- `id` 要稳定、可读，被 `next` 和 `children.links[].to` 引用。
-- 普通 trigger/action 用 `next` 串联；最后一个节点 `next:null`。
-- `IfElseBranch` / `SwitchBranch` / `Loop` 用 `children.links` 表达分支或循环入口。
-- Action 节点不要设置 `children`。
-- `ref` 引用前置 step 的输出，字段下钻通常是 `$.{stepId}.{fieldId}`；循环内当前项常用 `$.{loopStepId}.item.{fieldId}`。
-- `+workflow-create` 需要唯一 `client_token`；新 workflow 创建后默认 disabled，用户需要启用时再调用 `+workflow-enable`。
-- `+workflow-update` 是完整替换；从 `+workflow-get` 返回中保留不想改的 `title/status/steps`。
-
-## Step 选型
-
-创建/修改前先产出一个草图：列出全部节点 `id/type/next/children`，把会用到的 `type` 去重后，再一次性读取对应的 step md 文档。不要“读一个 step、想一轮、再读下一个 step”；这会增加轮次和上下文重放。
-
-| 用户说法 | 选型 |
-|---|---|
-| 新增记录时 | `AddRecordTrigger` |
-| 记录被修改时 | `SetRecordTrigger` |
-| 新增或修改都触发、或拿不准 | `ChangeRecordTrigger` |
-| 每天/每周/每月/固定时间 | `TimerTrigger` |
-| 日期字段到期提醒 | `ReminderTrigger` |
-| 点击按钮 | `ButtonTrigger` |
-| 收到群消息/私聊消息 | `LarkMessageTrigger` |
-| 新增一条记录 | `AddRecordAction` |
-| 更新当前或查找到的记录 | `SetRecordAction` |
-| 查找多条记录再处理 | `FindRecordAction`，多条时接 `Loop` |
-| 分两路判断 | `IfElseBranch` |
-| 多档位/多类别判断 | `SwitchBranch` |
-| 发送飞书消息 | `LarkMessageAction` |
-| 调外部接口 | `HTTPClientAction` |
-| 等待一段时间 | `Delay` |
-| AI 生成文本 | `GenerateAiTextAction` |
-
-用户描述"修改为 X **或** 新增 X 时"这类同条件多来源需求，是单个 `ChangeRecordTrigger` + `condition_list` 的典型场景，一条工作流即可表达，不要拆成 `AddRecordTrigger` 和 `SetRecordTrigger` 两条工作流。
-
-## 常见场景
-
-| 场景 | 推荐步骤 | 需要读的 schema |
-|---|---|---|
-| 新增记录后发通知 | `AddRecordTrigger -> LarkMessageAction` | `trigger-add-record.md`, `action-lark-message.md` |
-| 记录变化后更新同一行字段 | `ChangeRecordTrigger -> SetRecordAction` | `trigger-change-record.md`, `action-set-record.md`; 条件复杂再读 common refs |
-| 金额/状态分档处理 | `AddRecordTrigger -> SwitchBranch -> SetRecordAction...` | `trigger-add-record.md`, `branch-switch.md`, `action-set-record.md`, common conditions |
-| 二选一判断 | `... -> IfElseBranch -> ...` | `branch-if-else.md`, common conditions |
-| 定时汇总并逐人通知 | `TimerTrigger -> FindRecordAction -> Loop -> LarkMessageAction` | `trigger-timer.md`, `action-find-record.md`, `system-loop.md`, `action-lark-message.md`, common refs |
-| 群消息触发后回复 | `LarkMessageTrigger -> FindRecordAction/Loop -> LarkMessageAction` | `trigger-lark-message.md`, `action-find-record.md`, `system-loop.md`, `action-lark-message.md` |
-| 按钮触发外部系统 | `ButtonTrigger -> HTTPClientAction -> AddRecordAction` | `trigger-button.md`, `action-http-client.md`, `action-add-record.md` |
-| 调用 AI 生成内容并写回 | `... -> GenerateAiTextAction -> SetRecordAction` | `action-generate-ai-text.md`, `action-set-record.md`, common refs |
-
-Schema 入口：[lark-base-workflow-schema.md](lark-base-workflow-schema.md)。不要一次性打开所有 step 文件；先确定本次 workflow 的完整 step type 集合，再一次性打开这些文件。只有确定会写 `ref`、条件、字段值或节点输出引用时，才把 `common-types-and-refs.md` 加入同一批读取。
-
-## 最小例子：新增记录后发送消息
-
-只读 `trigger-add-record.md` 和 `action-lark-message.md` 即可。
-
-```json
-{
-  "client_token": "wf-unique-token",
-  "title": "新订单通知",
-  "steps": [
-    {
-      "id": "trig_new_order",
-      "type": "AddRecordTrigger",
-      "title": "新增订单时",
-      "next": "act_notify",
+      "title": "监控新订单",
+      "next": "action_1",
       "data": {
         "table_name": "订单表",
         "watched_field_name": "订单号"
       }
     },
     {
-      "id": "act_notify",
+      "id": "action_1",
       "type": "LarkMessageAction",
       "title": "发送通知",
       "next": null,
       "data": {
-        "receiver": [{ "value_type": "user", "value": { "id": "ou_xxx" } }],
+        "receiver": [{ "value_type": "user", "value": {"id": "ou_xxxx", "name": "张三"} }],
         "send_to_everyone": false,
         "title": [{ "value_type": "text", "value": "新订单提醒" }],
-        "content": [{ "value_type": "text", "value": "收到新订单" }],
+        "content": [
+          { "value_type": "text", "value": "收到新订单" }
+        ],
         "btn_list": []
       }
     }
@@ -132,27 +48,783 @@ Schema 入口：[lark-base-workflow-schema.md](lark-base-workflow-schema.md)。
 }
 ```
 
-## 修改现有 workflow
+---
 
-1. `+workflow-list` 后按标题定位 `workflow_id`。
-2. `+workflow-get --workflow-id <wkf>` 获取完整定义。
-3. 只修改目标 step，保留其他 steps 的 `id/type/title/data/next/children`。
-4. 用 `+workflow-update` 提交完整定义。
-5. 若只启停，不走 update，直接 `+workflow-enable/disable`。
+## 场景速查表
 
-## 常见错误
+| 场景 | 步骤组合 | 示例 |
+|------|---------|------|
+| 新增触发+通知 | AddRecordTrigger → LarkMessageAction | [下方](#示例1-新增记录触发--发送消息) |
+| 按钮点击+调用外部接口+写入日志 | ButtonTrigger → HTTPClientAction → AddRecordAction | [下方](#示例-6-按钮触发--调用外部接口--写入同步日志) |
+| 定时+循环 | TimerTrigger → FindRecordAction → Loop → LarkMessageAction | [下方](#示例2-定时触发--查找记录--循环遍历--发送消息) |
+| 条件判断 | ... → IfElseBranch → 分支处理 | [下方](#示例3-条件分支-ifelsebranch) |
+| 多路分类 | ... → SwitchBranch → 多分支处理 | [下方](#示例4-多路分支-switchbranch) |
+| 复杂组合 | 定时+查找+循环+分支+消息 | [下方](#示例5-组合场景-定时查找循环分支消息) |
 
-| 错误 | 处理 |
-|---|---|
-| 查询/启停也读 schema | 停下，直接用 `+workflow-list/get/enable/disable` |
-| 为多个可能命令批量看 help | 只看当前报错或即将执行的一个命令 |
-| 把字段名当 field ID 写入 ref | 先 `+field-list --compact`，ref 下钻优先用 field ID |
-| 分支/循环没有 `children.links` | 按 branch/loop schema 补 `if_true/if_false/case/loop_start` |
-| SetRecordAction/FindRecordAction 缺定位条件 | 提供 `filter_info` 或 `ref_info` |
-| HTTPClientAction 后续节点引用不到字段 | `response_type: "json"` 时填写 `response_value` 声明输出字段 |
-| Loop 内引用错路径 | 用 `$.{loopStepId}.item.{fieldId}` 和 `$.{loopStepId}.index` |
+---
+
+## 完整示例
+
+### 示例 1: 新增记录触发 + 发送消息
+
+**场景**: 当订单表新增记录时，发送飞书消息通知负责人。
+
+```json
+{
+  "client_token": "1704067201",
+  "title": "新订单自动通知",
+  "steps": [
+    {
+      "id": "step_trigger",
+      "type": "AddRecordTrigger",
+      "title": "新增订单时触发",
+      "next": "step_notify",
+      "data": {
+        "table_name": "订单表",
+        "watched_field_name": "订单号",
+        "condition_list": null
+      }
+    },
+    {
+      "id": "step_notify",
+      "type": "LarkMessageAction",
+      "title": "发送订单通知",
+      "next": null,
+      "data": {
+        "receiver": [{ "value_type": "ref", "value": "$.step_trigger.fldManager" }],
+        "send_to_everyone": false,
+        "title": [{ "value_type": "text", "value": "新订单提醒" }],
+        "content": [
+          { "value_type": "text", "value": "客户 " },
+          { "value_type": "ref", "value": "$.step_trigger.fldCustomer" },
+          { "value_type": "text", "value": " 创建了新订单，金额：¥" },
+          { "value_type": "ref", "value": "$.step_trigger.fldAmount" }
+        ],
+        "btn_list": [
+          {
+            "text": "查看订单",
+            "btn_action": "openLink",
+            "link": [{ "value_type": "ref", "value": "$.step_trigger.recordLink" }]
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+**关键点**:
+- `AddRecordTrigger` 监控 `table_name` 表的 `watched_field_name` 字段
+- 使用 `ref` 引用触发器输出的字段值（注意是 fieldId，不是字段名）
+- `recordLink` 是触发器内置输出，表示记录链接
+
+---
+
+### 示例 2: 定时触发 + 查找记录 + 循环遍历 + 发送消息
+
+**场景**: 每天早上 9 点，查找所有待处理订单，给每个客户发送提醒。
+
+```json
+{
+  "client_token": "1704067202",
+  "title": "每日待处理订单提醒",
+  "steps": [
+    {
+      "id": "step_timer",
+      "type": "TimerTrigger",
+      "title": "每天早上9点触发",
+      "next": "step_find_orders",
+      "data": {
+        "rule": "DAILY",
+        "start_time": "2025-01-01 09:00",
+        "is_never_end": true
+      }
+    },
+    {
+      "id": "step_find_orders",
+      "type": "FindRecordAction",
+      "title": "查找所有待处理订单",
+      "next": "step_loop_customers",
+      "data": {
+        "table_name": "订单表",
+        "field_names": ["客户名称", "订单金额", "客户联系方式"],
+        "should_proceed_when_no_results": false,
+        "filter_info": {
+          "conjunction": "and",
+          "conditions": [
+            {
+              "field_name": "状态",
+              "operator": "is",
+              "value": [{ "value_type": "option", "value": { "name": "待处理" } }]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "step_loop_customers",
+      "type": "Loop",
+      "title": "遍历每个订单",
+      "children": {
+        "links": [
+          { "kind": "loop_start", "to": "step_send_reminder" }
+        ]
+      },
+      "next": null,
+      "data": {
+        "loop_mode": "continue",
+        "max_loop_times": 100,
+        "data": [{
+          "value_type": "ref",
+          "value": "$.step_find_orders.fieldRecords"
+        }]
+      }
+    },
+    {
+      "id": "step_send_reminder",
+      "type": "LarkMessageAction",
+      "title": "发送催办消息",
+      "next": null,
+      "data": {
+        "receiver": [{
+          "value_type": "ref",
+          "value": "$.step_loop_customers.item.fldContact"
+        }],
+        "send_to_everyone": false,
+        "title": [{ "value_type": "text", "value": "订单处理提醒" }],
+        "content": [
+          { "value_type": "text", "value": "您好，您的订单 " },
+          { "value_type": "ref", "value": "$.step_loop_customers.item.fldName" },
+          { "value_type": "text", "value": " 金额 ¥" },
+          { "value_type": "ref", "value": "$.step_loop_customers.item.fldAmount" },
+          { "value_type": "text", "value": " 正在处理中。" }
+        ],
+        "btn_list": []
+      }
+    }
+  ]
+}
+```
+
+**关键点**:
+- `Loop.data` 必须传入 `ref` 类型的数据源（通常是 FindRecordAction 的 `fieldRecords`）
+- `Loop.children.links` 必须包含 `kind: "loop_start"` 的链接指向循环体
+- 循环体内用 `$.{loopStepId}.item.{fieldId}` 引用当前遍历记录的字段
+- `$.{loopStepId}.index` 获取当前索引（从 0 开始）
+
+---
+
+### 示例 3: 条件分支（IfElseBranch）
+
+**场景**: 根据订单金额判断，大额订单通知主管审批，小额订单自动通过。
+
+```json
+{
+  "client_token": "1704067203",
+  "title": "订单金额自动判断",
+  "steps": [
+    {
+      "id": "step_trigger",
+      "type": "AddRecordTrigger",
+      "title": "新增订单时触发",
+      "next": "step_check_amount",
+      "data": {
+        "table_name": "订单表",
+        "watched_field_name": "订单金额"
+      }
+    },
+    {
+      "id": "step_check_amount",
+      "type": "IfElseBranch",
+      "title": "判断是否为大额订单",
+      "children": {
+        "links": [
+          { "kind": "if_true", "to": "step_notify_manager", "label": "high", "desc": "金额>=10000" },
+          { "kind": "if_false", "to": "step_auto_approve", "label": "normal", "desc": "金额<10000" }
+        ]
+      },
+      "next": "step_log",
+      "data": {
+        "condition": {
+          "conjunction": "or",
+          "conditions": [
+            {
+              "conjunction": "and",
+              "conditions": [
+                {
+                  "left_value": { "value_type": "ref", "value": "$.step_trigger.fldAmount" },
+                  "operator": "isGreaterEqual",
+                  "right_value": [{ "value_type": "number", "value": 10000 }]
+                }
+              ]
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "step_notify_manager",
+      "type": "LarkMessageAction",
+      "title": "通知主管审批大额订单",
+      "next": "step_log",
+      "data": {
+        "receiver": [{ "value_type": "user", "value": {"id": "ou_manager", "name": "主管"} }],
+        "send_to_everyone": false,
+        "title": [{ "value_type": "text", "value": "大额订单待审批" }],
+        "content": [
+          { "value_type": "text", "value": "有大额订单 ¥" },
+          { "value_type": "ref", "value": "$.step_trigger.fldAmount" },
+          { "value_type": "text", "value": " 需要您审批" }
+        ],
+        "btn_list": []
+      }
+    },
+    {
+      "id": "step_auto_approve",
+      "type": "SetRecordAction",
+      "title": "自动标记小额订单为已审核",
+      "next": "step_log",
+      "data": {
+        "table_name": "订单表",
+        "ref_info": { "step_id": "step_trigger" },
+        "field_values": [
+          {
+            "field_name": "审批状态",
+            "value": [{ "value_type": "option", "value": { "name": "已自动审核" } }]
+          }
+        ]
+      }
+    },
+    {
+      "id": "step_log",
+      "type": "GenerateAiTextAction",
+      "title": "生成订单处理日志",
+      "next": null,
+      "data": {
+        "prompt": [
+          { "value_type": "text", "value": "请生成订单处理日志，金额：" },
+          { "value_type": "ref", "value": "$.step_trigger.fldAmount" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+**关键点**:
+- `IfElseBranch.children.links` 必须包含 `if_true` 和 `if_false` 两个分支
+- `next` 指向两个分支汇合后的步骤（可选，为 null 则分支结束）
+- `condition` 使用 OrGroup 结构，支持 `(A and B) or (C and D)` 的复杂条件
+- 分支内可以用 `ref_info` 引用触发记录，用 `filter_info` 批量筛选记录
+
+---
+
+### 示例 4: 多路分支（SwitchBranch）
+
+**场景**: 根据订单优先级（P0/P1/P2）执行不同的处理流程。
+
+```json
+{
+  "client_token": "1704067204",
+  "title": "按优先级分类处理订单",
+  "steps": [
+    {
+      "id": "step_trigger",
+      "type": "AddRecordTrigger",
+      "title": "新增订单时触发",
+      "next": "step_classify",
+      "data": {
+        "table_name": "订单表",
+        "watched_field_name": "优先级"
+      }
+    },
+    {
+      "id": "step_classify",
+      "type": "SwitchBranch",
+      "title": "按优先级分类",
+      "children": {
+        "links": [
+          { "kind": "case", "to": "step_p0_handler", "label": "p0", "desc": "P0-紧急" },
+          { "kind": "case", "to": "step_p1_handler", "label": "p1", "desc": "P1-高优先级" },
+          { "kind": "case", "to": "step_p2_handler", "label": "p2", "desc": "P2-普通" },
+          { "kind": "case", "to": "step_other_handler", "label": "other", "desc": "其他" }
+        ]
+      },
+      "next": null,
+      "data": {
+        "mode": "exclusive",
+        "no_match_action": "classifyToOther",
+        "child_branch_list": [
+          {
+            "name": "P0-紧急",
+            "condition": {
+              "conjunction": "or",
+              "conditions": [
+                {
+                  "conjunction": "and",
+                  "conditions": [
+                    {
+                      "left_value": { "value_type": "ref", "value": "$.step_trigger.fldPriority" },
+                      "operator": "is",
+                      "right_value": [{ "value_type": "option", "value": { "name": "P0" } }]
+                    }
+                  ]
+                }
+              ]
+            }
+          },
+          {
+            "name": "P1-高优先级",
+            "condition": {
+              "conjunction": "or",
+              "conditions": [
+                {
+                  "conjunction": "and",
+                  "conditions": [
+                    {
+                      "left_value": { "value_type": "ref", "value": "$.step_trigger.fldPriority" },
+                      "operator": "is",
+                      "right_value": [{ "value_type": "option", "value": { "name": "P1" } }]
+                    }
+                  ]
+                }
+              ]
+            }
+          },
+          {
+            "name": "P2-普通",
+            "condition": {
+              "conjunction": "or",
+              "conditions": [
+                {
+                  "conjunction": "and",
+                  "conditions": [
+                    {
+                      "left_value": { "value_type": "ref", "value": "$.step_trigger.fldPriority" },
+                      "operator": "is",
+                      "right_value": [{ "value_type": "option", "value": { "name": "P2" } }]
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        ]
+      }
+    },
+    {
+      "id": "step_p0_handler",
+      "type": "LarkMessageAction",
+      "title": "P0紧急处理",
+      "next": null,
+      "data": {
+        "receiver": [{ "value_type": "user", "value": {"id": "ou_director", "name": "总监"} }],
+        "send_to_everyone": false,
+        "title": [{ "value_type": "text", "value": "🚨 P0 紧急订单" }],
+        "content": [{ "value_type": "text", "value": "有新的 P0 紧急订单需要立即处理" }],
+        "btn_list": []
+      }
+    },
+    {
+      "id": "step_p1_handler",
+      "type": "SetRecordAction",
+      "title": "标记高优先级",
+      "next": null,
+      "data": {
+        "table_name": "订单表",
+        "ref_info": { "step_id": "step_trigger" },
+        "field_values": [
+          { "field_name": "处理状态", "value": [{ "value_type": "text", "value": "高优先级待处理" }] }
+        ]
+      }
+    },
+    {
+      "id": "step_p2_handler",
+      "type": "Delay",
+      "title": "普通订单延迟处理",
+      "next": null,
+      "data": { "duration": 60 }
+    },
+    {
+      "id": "step_other_handler",
+      "type": "SetRecordAction",
+      "title": "标记其他订单",
+      "next": null,
+      "data": {
+        "table_name": "订单表",
+        "ref_info": { "step_id": "step_trigger" },
+        "field_values": [
+          { "field_name": "处理状态", "value": [{ "value_type": "text", "value": "待分类" }] }
+        ]
+      }
+    }
+  ]
+}
+```
+
+**关键点**:
+- `SwitchBranch` 适合 3 路及以上的分支场景（少于 3 路用 `IfElseBranch` 更简洁）
+- `children.links` 中 `kind: "case"` 的 `label` 对应 `child_branch_list` 中的条件
+- `mode: "exclusive"` 表示排他执行（第一个匹配的分支执行后停止）
+- `no_match_action: "classifyToOther"` 表示无匹配时走最后一个 `case`（兜底分支）
+
+---
+
+### 示例 5: 组合场景（定时+查找+循环+分支+消息）
+
+**场景**: 每天早上 9 点，查找昨天的订单，按金额分级，给不同级别的销售发送不同的通知。
+
+```json
+{
+  "client_token": "1704067205",
+  "title": "每日订单分级通知",
+  "steps": [
+    {
+      "id": "step_timer",
+      "type": "TimerTrigger",
+      "title": "每天早上9点触发",
+      "next": "step_find_orders",
+      "data": {
+        "rule": "DAILY",
+        "start_time": "2025-01-01 09:00",
+        "is_never_end": true
+      }
+    },
+    {
+      "id": "step_find_orders",
+      "type": "FindRecordAction",
+      "title": "查找昨天所有订单",
+      "next": "step_loop",
+      "data": {
+        "table_name": "订单表",
+        "field_names": ["订单号", "客户名称", "金额", "销售负责人"],
+        "should_proceed_when_no_results": false,
+        "filter_info": {
+          "conjunction": "and",
+          "conditions": [
+            { "field_name": "创建时间", "operator": "isGreaterEqual", "value": [{ "value_type": "date", "value": "yesterday" }] }
+          ]
+        }
+      }
+    },
+    {
+      "id": "step_loop",
+      "type": "Loop",
+      "title": "遍历每个订单",
+      "children": {
+        "links": [
+          { "kind": "loop_start", "to": "step_classify" }
+        ]
+      },
+      "next": "step_summary",
+      "data": {
+        "loop_mode": "continue",
+        "max_loop_times": 500,
+        "data": [{ "value_type": "ref", "value": "$.step_find_orders.fieldRecords" }]
+      }
+    },
+    {
+      "id": "step_classify",
+      "type": "SwitchBranch",
+      "title": "按金额分类",
+      "children": {
+        "links": [
+          { "kind": "case", "to": "step_vip_notify", "label": "vip", "desc": "VIP >= 10万" },
+          { "kind": "case", "to": "step_normal_notify", "label": "normal", "desc": "普通 < 10万" }
+        ]
+      },
+      "next": null,
+      "data": {
+        "mode": "exclusive",
+        "no_match_action": "fail",
+        "child_branch_list": [
+          {
+            "name": "VIP订单",
+            "condition": {
+              "conjunction": "or",
+              "conditions": [
+                {
+                  "conjunction": "and",
+                  "conditions": [
+                    {
+                      "left_value": { "value_type": "ref", "value": "$.step_loop.item.fldAmount" },
+                      "operator": "isGreaterEqual",
+                      "right_value": [{ "value_type": "number", "value": 100000 }]
+                    }
+                  ]
+                }
+              ]
+            }
+          },
+          {
+            "name": "普通订单",
+            "condition": {
+              "conjunction": "or",
+              "conditions": [
+                {
+                  "conjunction": "and",
+                  "conditions": [
+                    {
+                      "left_value": { "value_type": "ref", "value": "$.step_loop.item.fldAmount" },
+                      "operator": "isLess",
+                      "right_value": [{ "value_type": "number", "value": 100000 }]
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        ]
+      }
+    },
+    {
+      "id": "step_vip_notify",
+      "type": "LarkMessageAction",
+      "title": "VIP订单通知",
+      "next": null,
+      "data": {
+        "receiver": [{ "value_type": "ref", "value": "$.step_loop.item.fldSales" }],
+        "send_to_everyone": false,
+        "title": [{ "value_type": "text", "value": "🌟 VIP大额订单" }],
+        "content": [
+          { "value_type": "text", "value": "恭喜！您有一笔 VIP 订单 ¥" },
+          { "value_type": "ref", "value": "$.step_loop.item.fldAmount" },
+          { "value_type": "text", "value": "，客户：" },
+          { "value_type": "ref", "value": "$.step_loop.item.fldCustomer" }
+        ],
+        "btn_list": []
+      }
+    },
+    {
+      "id": "step_normal_notify",
+      "type": "LarkMessageAction",
+      "title": "普通订单通知",
+      "next": null,
+      "data": {
+        "receiver": [{ "value_type": "ref", "value": "$.step_loop.item.fldSales" }],
+        "send_to_everyone": false,
+        "title": [{ "value_type": "text", "value": "新订单通知" }],
+        "content": [
+          { "value_type": "text", "value": "您有一笔新订单 ¥" },
+          { "value_type": "ref", "value": "$.step_loop.item.fldAmount" }
+        ],
+        "btn_list": []
+      }
+    },
+    {
+      "id": "step_summary",
+      "type": "GenerateAiTextAction",
+      "title": "生成日报",
+      "next": null,
+      "data": {
+        "prompt": [
+          { "value_type": "text", "value": "请生成昨日订单处理日报" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+---
+
+### 示例 6: 按钮触发 + 调用外部接口 + 写入同步日志
+
+**场景**: 在「客户线索表」里给每条记录配置一个“同步到 CRM”按钮。销售点击按钮后，Workflow 调用外部 CRM 接口同步当前线索，再在「同步日志表」新增一条记录，方便后续审计和排查。
+
+```json
+{
+  "client_token": "1704067206",
+  "title": "线索一键同步到 CRM",
+  "steps": [
+    {
+      "id": "step_button_trigger",
+      "type": "ButtonTrigger",
+      "title": "点击同步到 CRM 按钮时触发",
+      "next": "step_call_crm_api",
+      "data": {
+        "button_type": "buttonField",
+        "table_name": "客户线索表"
+      }
+    },
+    {
+      "id": "step_call_crm_api",
+      "type": "HTTPClientAction",
+      "title": "调用 CRM 同步接口",
+      "next": "step_add_sync_log",
+      "data": {
+        "method": "POST",
+        "url": [
+          { "value_type": "text", "value": "https://api.example-crm.com/v1/leads/sync" }
+        ],
+        "headers": [
+          { "key": "Content-Type", "value": [{ "value_type": "text", "value": "application/json" }] },
+          { "key": "X-System", "value": [{ "value_type": "text", "value": "lark_base_workflow" }] }
+        ],
+        "body_type": "raw",
+        "raw_body": [
+          { "value_type": "text", "value": "{\"lead_name\":\"" },
+          { "value_type": "ref", "value": "$.step_button_trigger.fldLeadName" },
+          { "value_type": "text", "value": "\",\"mobile\":\"" },
+          { "value_type": "ref", "value": "$.step_button_trigger.fldMobile" },
+          { "value_type": "text", "value": "\",\"company\":\"" },
+          { "value_type": "ref", "value": "$.step_button_trigger.fldCompany" },
+          { "value_type": "text", "value": "\",\"owner\":\"" },
+          { "value_type": "ref", "value": "$.step_button_trigger.fldOwner" },
+          { "value_type": "text", "value": "\",\"source_record_id\":\"" },
+          { "value_type": "ref", "value": "$.step_button_trigger.recordId" },
+          { "value_type": "text", "value": "\"}" }
+        ],
+        "response_type": "json",
+        "response_value": "{\"success\":true,\"message\":\"lead synced successfully\"}"
+      }
+    },
+    {
+      "id": "step_add_sync_log",
+      "type": "AddRecordAction",
+      "title": "写入同步日志",
+      "next": null,
+      "data": {
+        "table_name": "同步日志表",
+        "field_values": [
+          {
+            "field_name": "线索名称",
+            "value": [{ "value_type": "ref", "value": "$.step_button_trigger.fldLeadName" }]
+          },
+          {
+            "field_name": "手机号",
+            "value": [{ "value_type": "ref", "value": "$.step_button_trigger.fldMobile" }]
+          },
+          {
+            "field_name": "公司名称",
+            "value": [{ "value_type": "ref", "value": "$.step_button_trigger.fldCompany" }]
+          },
+          {
+            "field_name": "负责人",
+            "value": [{ "value_type": "ref", "value": "$.step_button_trigger.fldOwner" }]
+          },
+          {
+            "field_name": "来源记录ID",
+            "value": [{ "value_type": "ref", "value": "$.step_button_trigger.recordId" }]
+          },
+          {
+            "field_name": "同步状态",
+            "value": [{ "value_type": "text", "value": "已提交 CRM 同步" }]
+          },
+          {
+            "field_name": "同步是否成功",
+            "value": [{ "value_type": "ref", "value": "$.step_call_crm_api.body.success" }]
+          },
+          {
+            "field_name": "同步结果说明",
+            "value": [{ "value_type": "ref", "value": "$.step_call_crm_api.body.message" }]
+          },
+          {
+            "field_name": "备注",
+            "value": [{ "value_type": "text", "value": "由按钮触发自动发起同步请求" }]
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+**关键点**:
+- `ButtonTrigger` 适合“人工确认后再执行”的场景，比如同步 CRM、推送 ERP、发起审批等
+- `button_type: "buttonField"` 表示按钮挂在记录上，因此可以直接引用当前记录的字段和值
+- `HTTPClientAction.raw_body` 可以通过 `text + ref + text` 的方式动态拼接 JSON 请求体
+- `HTTPClientAction` 的输出引用规则是：`response_type=none` 时不可引用；`response_type=text` 时只能用 `$.stepId` 引整个文本；`response_type=json` 时用 `$.stepId.body` 引整个 body、用 `$.stepId.body.字段名` 引 body 中字段，同时 `$.stepId.status_code` 表示 HTTP 返回状态码
+- `HTTPClientAction.response_value` 中声明了哪些字段，后续节点就只能引用这些字段；例如 `$.step_call_crm_api.body.success`、`$.step_call_crm_api.body.message`
+- `AddRecordAction` 常用于写日志表、操作审计表、同步结果表，便于追踪谁在什么时候触发了外部调用
+- 示例里的 `fldLeadName` / `fldMobile` / `fldCompany` / `fldOwner` 只是占位的 fieldId，请以实际表字段 ID 为准
+
+---
+
+## 构造技巧
+
+### Loop 构造要点
+
+1. **数据源**: `Loop.data` 必须传入 `ref` 类型，通常是 `FindRecordAction` 的 `fieldRecords`
+2. **循环体**: `children.links` 必须包含 `kind: "loop_start"` 指向循环体入口
+3. **引用**: 循环体内用 `$.{loopStepId}.item.{fieldId}` 引用当前元素
+4. **索引**: 用 `$.{loopStepId}.index` 获取当前索引（从 0 开始）
+
+### 分支构造要点
+
+1. **IfElseBranch**:
+   - 适合二元判断（是/否、大于/小于）
+   - `children.links` 必须包含 `if_true` 和 `if_false`
+   - 可以用 `next` 指向汇合点
+
+2. **SwitchBranch**:
+   - 适合多路分类（3路及以上）
+   - `label` 对应 `child_branch_list` 中的条件顺序
+   - 建议加一个兜底分支（其他）
+
+### 字段值构造
+
+| 字段类型 | value_type | 示例 |
+|---------|------------|------|
+| 文本 | `text` | `{"value_type": "text", "value": "张三"}` |
+| 数字 | `number` | `{"value_type": "number", "value": 100}` |
+| 单选 | `option` | `{"value_type": "option", "value": {"name": "已完成"}}` |
+| 人员 | `user` | `{"value_type": "user", "value": {"id": "ou_xxxx"}}` |
+| 引用 | `ref` | `{"value_type": "ref", "value": "$.step_1.fldxxx"}` |
+
+---
+
+## 常见错误避免
+
+### Top 10 高频错误
+
+| # | 错误信息 | 原因 | 解决方案 |
+|---|---------|------|---------|
+| 1 | `path "xxx" does not exist in the output path tree` | ref 引用路径错误或 stepId 不存在 | 检查 stepId 是否在 steps 数组中；使用 fieldId 而非字段名；确保路径以 `$.` 开头 |
+| 2 | `recordInfo.conditions must be non-empty` | `condition_list` 为空数组 `[]` | 改用 `null` 或省略该字段 |
+| 3 | `At least one of filter info and ref info is required` | SetRecordAction/FindRecordAction 缺少定位条件 | 必须提供 `filter_info` 或 `ref_info` 之一 |
+| 4 | `client token is empty` | 缺少 `client_token` | 每次请求传入唯一值（时间戳或随机字符串） |
+| 5 | `valueType 'text' not allowed for fieldType '3'` | select 类型字段值格式错误 | 改用 `option` 类型 |
+| 6 | `Undefined Step Type` | 使用了不支持的 StepType | 使用 `AddRecordTrigger` 而非 `CreateRecordTrigger` |
+| 7 | `prompt references an unknown reference from step` | 引用的 stepId 不存在 | 确保引用的 step 在同一 workflow 的 steps 数组中 |
+| 8 | `[2200] Internal Error` | 1. steps[].id 重复 2. next/children.links 引用了不存在的 step | 确保所有 step id 唯一；检查引用关系 |
+| 9 | 工作流结构不完整 | Branch/Loop 节点缺少 `children` | 仅 Branch（IfElseBranch/SwitchBranch）和 Loop 节点需要 `children`，Trigger/Action 节点无需设置 |
+| 10 | 嵌套分支过于复杂 | 多层 IfElseBranch 嵌套 | 3+ 路分支用 SwitchBranch 替代嵌套 IfElseBranch |
+
+### 其他常见错误
+
+**1. condition_list 为空数组**
+```json
+// ❌ 错误
+{ "condition_list": [] }
+
+// ✅ 正确
+{ "condition_list": null }
+// 或省略该字段
+```
+
+**2. filter_info 和 ref_info 同时提供**
+```json
+// ❌ 错误
+{ "filter_info": {...}, "ref_info": {...} }
+
+// ✅ 正确（二选一）
+{ "filter_info": {...}, "ref_info": null }
+{ "filter_info": null, "ref_info": {...} }
+```
+
+**3. 使用字段名而非 fieldId**
+```json
+// ❌ 错误
+{ "value": "$.step_1.客户名称" }
+
+// ✅ 正确
+{ "value": "$.step_1.fldXXXXXXXX" }
+```
+
+---
 
 ## 参考
 
-- [lark-base-workflow-schema.md](lark-base-workflow-schema.md)：step type 路由和基础结构。
-- [workflow-steps/common-types-and-refs.md](workflow-steps/common-types-and-refs.md)：ValueInfo、ref、Condition、节点输出；只有构造这些细节时才读。
+- [lark-base-workflow-schema.md](lark-base-workflow-schema.md) — 字段定义参考
+- 创建/更新前先确认真实表名、字段名和目标 workflow ID；`steps` 结构按 schema 构造，不凭自然语言猜 `type`

skills/lark-base/references/workflow-steps/action-add-record.md

@@ -1,24 +0,0 @@
-# AddRecordAction
-
-```json
-{
-  "table_name": "订单表",
-  "field_values": [
-    { "field_name": "客户名称", "value": [{ "value_type": "text", "value": "张三" }] },
-    { "field_name": "金额", "value": [{ "value_type": "number", "value": 100 }] },
-    { "field_name": "创建人", "value": [{ "value_type": "ref", "value": "$.trigger_1.fieldIdxxx" }] }
-  ]
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `table_name` | 是 | 目标数据表名 |
-| `field_values` | 是 | RecordFieldValue[] |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/action-delay.md

@@ -1,16 +0,0 @@
-# Delay
-
-```json
-{ "duration": 30 }
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `duration` | 是 | 延迟时长（分钟），范围 [1, 120] |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/action-find-record.md

@@ -1,25 +0,0 @@
-# FindRecordAction
-
-```json
-{
-  "table_name": "客户表",
-  "field_names": ["客户名称", "联系方式", "等级"],
-  "should_proceed_when_no_results": true,
-  "filter_info": { /* RecordFilterInfo */ }
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `table_name` | 是 | 目标数据表名 |
-| `field_names` | 是 | 要检索的字段名列表，至少一个 |
-| `should_proceed_when_no_results` | 否 | 无结果时是否继续后续步骤，默认 `true` |
-| `filter_info` | 否* | RecordFilterInfo（与 `ref_info` 互斥） |
-| `ref_info` | 否* | RefInfo（与 `filter_info` 互斥） |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/action-generate-ai-text.md

@@ -1,21 +0,0 @@
-# GenerateAiTextAction
-
-```json
-{
-  "prompt": [
-    { "value_type": "text", "value": "请总结以下内容：" },
-    { "value_type": "ref", "value": "$.step_1.fieldxxx" }
-  ]
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `prompt` | 是 | TextRefItem[] 提示词，支持 `text` / `ref` |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/action-http-client.md

@@ -1,48 +0,0 @@
-# HTTPClientAction
-
-```json
-{
-  "method": "POST",
-  "url": [{ "value_type": "text", "value": "https://api.example.com/webhook" }],
-  "queries": [
-    { "key": "source", "value": [{ "value_type": "text", "value": "workflow" }] }
-  ],
-  "headers": [
-    { "key": "Content-Type", "value": [{ "value_type": "text", "value": "application/json" }] }
-  ],
-  "body_type": "raw",
-  "raw_body": [
-    { "value_type": "text", "value": "{\"record_id\":\"" },
-    { "value_type": "ref", "value": "$.step_1.recordId" },
-    { "value_type": "text", "value": "\"}" }
-  ],
-  "response_type": "json",
-  "response_value": "{\"success\":true,\"message\":\"data fetched successfully\"}"
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|-----|------|
-| `method` | 否 | 请求方法：`GET` / `POST` / `PUT` / `PATCH` / `DELETE`，默认 `POST` |
-| `url` | 是 | ValueInfo[]，请求 URL，支持 `text` / `ref` 拼接 |
-| `queries` | 否 | KeyValue[]，查询参数 |
-| `headers` | 否 | KeyValue[]，请求头 |
-| `body_type` | 否 | 请求体类型：`none` / `raw` / `form-data` / `form-urlencoded`，默认 `raw` |
-| `raw_body` | 否 | ValueInfo[]，原始请求体，仅 `body_type=raw` 时使用 |
-| `form_body` | 否 | KeyValue[]，表单数据，仅 `body_type=form-data` 或 `body_type=form-urlencoded` 时使用 |
-| `response_type` | 否 | 响应类型：`none` / `text` / `json`，默认 `json` |
-| `response_value` | 否 | string，JSON 字符串形式的响应结果示例；仅当 `response_type=json` 时必填 |
-
-`KeyValue`：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `key` | string | 参数名 / 请求头名 |
-| `value` | ValueInfo[] | 参数值 / 请求头值，支持 `text` / `ref` |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/action-lark-message.md

@@ -1,42 +0,0 @@
-# LarkMessageAction
-
-```json
-{
-  "receiver": [{ "value_type": "user", "value": {"id": "ou_xxxx"} }],
-  "send_to_everyone": false,
-  "title": [{ "value_type": "text", "value": "新订单通知" }],
-  "content": [
-    { "value_type": "text", "value": "客户 " },
-    { "value_type": "ref", "value": "$.trigger_1.fldCustomerName" },
-    { "value_type": "text", "value": " 创建了新订单" }
-  ],
-  "btn_list": [
-    { "text": "查看详情", "btn_action": "openLink", "link": [{ "value_type": "text", "value": "https://example.com" }] }
-  ]
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `receiver` | 是 | ValueInfo[] |
-| `send_to_everyone` | 是 | 是否发送给所有人 |
-| `title` | 否 | TextRefItem[] 消息标题 |
-| `content` | 是 | TextRefItem[] 消息内容 |
-| `btn_list` | 是 | 按钮列表，不需要时为空数组 |
-
-`ButtonConfig`：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `text` | string | 按钮文字 |
-| `btn_action` | string | `addRecord` / `setRecord` / `openLink` |
-| `link` | ValueInfo[] | 跳转链接（`openLink` 时使用） |
-| `table_name` | string | 操作表名（`addRecord` 时使用） |
-| `record_values` | RecordFieldValue[] | 记录赋值（`addRecord` / `setRecord` 时使用） |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/action-set-record.md

@@ -1,28 +0,0 @@
-# SetRecordAction
-
-```json
-{
-  "table_name": "订单表",
-  "max_set_record_num": 10,
-  "field_values": [
-    { "field_name": "状态", "value": [{ "value_type": "option", "value": { "id": "opt1", "name": "已完成" } }] }
-  ],
-  "filter_info": { /* RecordFilterInfo */ },
-  "ref_info": { "step_id": "step_trigger" }
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `table_name` | 是 | 目标数据表名 |
-| `max_set_record_num` | 否 | 最大更新记录数，默认 100，范围 1-15000 |
-| `field_values` | 是 | RecordFieldValue[] |
-| `filter_info` | 否* | RecordFilterInfo 过滤条件（与 `ref_info` 互斥） |
-| `ref_info` | 否* | RefInfo 引用前置步骤的记录（与 `filter_info` 互斥） |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/branch-if-else.md

@@ -1,36 +0,0 @@
-# IfElseBranch
-
-`children.links` 包含 `if_true` 和 `if_false` 两条边，`next` 指向两个分支汇合后的后继节点。
-
-**如果涉及到复杂的多分支场景(分支数目 >= 3时)，你应该采用 SwitchBranch，而不是嵌套的 IfElseBranch**
-
-```json
-{
-  "condition": {
-    "conjunction": "or",
-    "conditions": [
-      {
-        "conjunction": "and",
-        "conditions": [
-          {
-            "left_value": { "value_type": "ref", "value": "$.step_1.fieldxxx" },
-            "operator": "isGreater",
-            "right_value": [{ "value_type": "number", "value": 1000 }]
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `condition` | 是 | OrGroup 判断条件，结构为 `(A and B) or (C and D)` |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/branch-switch.md

@@ -1,52 +0,0 @@
-# SwitchBranch
-
-`children.links` 包含多个 `case` 边（`label` 建议用 `branch_1`、`branch_2`，语义写在 `desc`）。
-
-```json
-{
-  "mode": "exclusive",
-  "no_match_action": "classifyToOther",
-  "child_branch_list": [
-    {
-      "name": "高优先级",
-      "condition": {
-        "conjunction": "or",
-        "conditions": [
-          {
-            "conjunction": "and",
-            "conditions": [
-              {
-                "left_value": { "value_type": "ref", "value": "$.step_1.fieldxxx" },
-                "operator": "is",
-                "right_value": [{ "value_type": "text", "value": "P0" }]
-              }
-            ]
-          }
-        ]
-      }
-    }
-  ]
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `mode` | 否 | 分支模式。`exclusive`：排他模式，仅执行一个满足条件的子分支；`parallel`：并行模式，执行所有满足条件的子分支。默认 `exclusive` |
-| `no_match_action` | 否 | `mode=exclusive` 时使用，无匹配时的处理策略。`classifyToOther`：归类到其他分支；`fail`：报错终止。默认 `classifyToOther` |
-| `fail_mode` | 否 | `mode=parallel` 时使用，部分分支出错时策略。`partialSuccess`：部分成功即继续；`fail`：任一失败即终止。默认 `partialSuccess` |
-| `match_mode` | 否 | `mode=parallel` 时使用，所有分支不满足时策略。`noneMatchSkip`：跳过继续；`noneMatchFail`：报错终止。默认 `noneMatchSkip` |
-| `child_branch_list` | 是 | BranchItem[]，1-10 个条件分支 |
-
-`BranchItem`：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `name` | string | 分支名称 |
-| `condition` | OrGroup | 分支条件 |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/common-types-and-refs.md

@@ -1,401 +0,0 @@
-# Workflow common types and refs
-
-### ValueInfo
-
-所有值的基础类型，通过 `value_type` 区分：
-
-| value_type | value 类型 | 说明 | 示例 |
-|------------|-----------|------|------|
-| `text` | string | 文本 | `"张三"` |
-| `number` | number | 数字 | `100` |
-| `boolean` | boolean | 布尔值 | `true` |
-| `date` | string | 日期，可以是具体时间字符串，或者相对时间值 | `"2025/01/01"`、`"2025/01/01 11:00"`、`"now"`、`"now 11:00"`、`"today"`、`"today 11:00"`、`"yesterday"`、`"yesterday 11:00"`、`"lastWeek"`、`"currentMonth"`、`"lastMonth"`、`"theLastWeek"`、`"theNextWeek"`、`"theLastMonth"`、`"theNextMonth"` |
-| `option` | `{ id, name }` | 选项 | `{ "id": "opt1", "name": "已完成" }` |
-| `link` | `{ text, link }` | 链接（含文字和 URL）， 文字和 URL 的格式可以是 ValueInfo 中的 text/ref 类型 | `{ "text": [{ "value_type": "text", "value": "查看详情" }], "link": [{ "value_type": "text", "value": "https://example.com" }] }`、`{ "text": [{ "value_type": "text", "value": "查看详情" }], "link": [{ "value_type": "ref", "value": "$.step_1.fldXXX" }] }` |
-| `user` | `{ id, name }` | 用户 OpenID、名字 | `{ "id": "ou_xxxx", "name": "张三" }` |
-| `group` | `{ id, name }` | 群 Chat ID、名字 | `{ "id": "oc_xxx", "name": "测试群" }` |
-| `ref` | `string` | 引用前置节点输出的路径 | 参考 ref 引用变量详解 章节 |
-
-> ⚠️ **所有涉及用户的 value 中的 id 统一使用 OpenID（`ou_xxxx` 格式）**，由 CLI 层来完成转换
-> ⚠️ **所有涉及群的 value 中的 id 统一使用 ChatID（`oc_xxxx` 格式）**，由 CLI 层来完成转换
-
-### ref 引用变量详解
-
-`ref` 类型是工作流中节点间数据传递的核心机制。当 `value_type` 为 `ref` 时，`value` 指向前置节点的某个输出变量。本节详细描述每个节点可供引用的输出变量定义。
-
-#### 引用路径格式
-
-```
-$.{stepId}
-$.{stepId}.{pathId}
-$.{stepId}.{pathId}.{childPathId}
-$.{stepId}.{pathId}.{childPathId}.{grandChildPathId}
-```
-
-- `{stepId}`：前置节点的 `id`（即 WorkflowStep 中的 `id` 字段）
-- `{pathId}`：节点输出的路径标识符
-- 支持多层下钻，如引用字段的属性：`$.step_1.fldXXX.name`
-
----
-
-#### 触发器节点输出
-
-##### 记录触发器（AddRecordTrigger / ChangeRecordTrigger / SetRecordTrigger / ReminderTrigger）
-
-这 4 个触发器的输出结构完全一致：
-
-| pathId | 说明 | 引用示例 |
-|--------|------|----------|
-| `{fieldId}` | 字段id，从配置表的所有字段或者指定字段id生成，可下钻字段属性 | `$.{stepId}.{fieldId}` |
-| `{fieldId}.fieldId` | 字段id属性 | `$.{stepId}.{fieldId}.fieldId` |
-| `{fieldId}.fieldName` | 字段名属性 | `$.{stepId}.{fieldId}.fieldName` |
-| `startTime` | 触发时间戳 | `$.{stepId}.startTime` |
-| `recordId` | 记录 ID | `$.{stepId}.recordId` |
-| `recordLink` | 记录链接 | `$.{stepId}.recordLink` |
-| `recordCreatedUser` | 记录创建者 | `$.{stepId}.recordCreatedUser` |
-| `recordCreatedTime` | 记录创建时间 | `$.{stepId}.recordCreatedTime` |
-| `recordModifiedUser` | 最后修改者 | `$.{stepId}.recordModifiedUser` |
-| `recordModifiedTime` | 最后修改时间 | `$.{stepId}.recordModifiedTime` |
-
-**动态字段输出规则**：
-
-- 读取触发器所配置的数据表的所有字段
-- 每个字段生成一条输出：`pathId` = fieldId
-- 若字段为关联字段，children 为关联表所有字段（单层下钻，不再递归）
-- 每个字段可下钻特定的字段属性（见「字段属性下钻」）
-
-**recordLink 的 children**：如果配置了数据表，则为该表所有视图的列表，每个视图 `{ pathId: viewId, pathName: viewName, pathType: 'string' }`。引用示例：`$.{stepId}.recordLink.{viewId}`。
-
-##### ButtonTrigger（按钮触发器）
-
-`ButtonTrigger` 的输出取决于 `button_type`：
-
-#### `button_type = buttonField`
-
-| pathId | 说明 | 引用示例 |
-|--------|------|----------|
-| `{fieldId}` | 字段id，从配置表的所有字段或者指定字段id生成，可下钻字段属性 | `$.{stepId}.{fieldId}` |
-| `{fieldId}.fieldId` | 字段id属性 | `$.{stepId}.{fieldId}.fieldId` |
-| `{fieldId}.fieldName` | 字段名属性 | `$.{stepId}.{fieldId}.fieldName` |
-| `recordId` | 记录 ID | `$.{stepId}.recordId` |
-| `recordLink` | 记录链接 | `$.{stepId}.recordLink` |
-| `recordCreatedUser` | 记录创建者 | `$.{stepId}.recordCreatedUser` |
-| `recordModifiedUser` | 最后修改者 | `$.{stepId}.recordModifiedUser` |
-| `recordModifiedTime` | 最后修改时间 | `$.{stepId}.recordModifiedTime` |
-| `time` | 触发时间 | `$.{stepId}.time` |
-| `user` | 触发人 | `$.{stepId}.user` |
-| `buttonName` | 触发的按钮名称 | `$.{stepId}.buttonName` |
-
-#### `button_type = buttonElement`
-
-| pathId | 说明 | 引用示例 |
-|--------|------|----------|
-| `time` | 触发时间 | `$.{stepId}.time` |
-| `user` | 触发人 | `$.{stepId}.user` |
-| `buttonName` | 触发的按钮名称 | `$.{stepId}.buttonName` |
-
-##### TimerTrigger（定时触发器）
-
-| pathId | 说明 | 引用示例 |
-|--------|------|----------|
-| `scheduleTime` | 定时触发时间 | `$.{stepId}.scheduleTime` |
-
-##### LarkMessageTrigger（飞书消息触发器）
-
-| pathId | 说明 | 引用示例 |
-|--------|------|----------|
-| `Sender` | 消息发送者 | `$.{stepId}.Sender` |
-| `AtUser` | 消息中被@的用户 | `$.{stepId}.AtUser` |
-| `SenderGroup` | 消息所在群（仅群聊场景） | `$.{stepId}.SenderGroup` |
-| `MessageSendTime` | 消息发送时间 | `$.{stepId}.MessageSendTime` |
-| `MessageContent` | 消息正文 | `$.{stepId}.MessageContent` |
-| `MessageType` | 消息类型标识 | `$.{stepId}.MessageType` |
-| `MessageID` | 消息唯一标识 | `$.{stepId}.MessageID` |
-| `MessageLink` | 消息链接（仅群聊场景） | `$.{stepId}.MessageLink` |
-| `ParentID` | 回复的消息 ID | `$.{stepId}.ParentID` |
-| `ThreadID` | 所在话题消息 ID | `$.{stepId}.ThreadID` |
-| `Attachments` | 消息中的附件 | `$.{stepId}.Attachments` |
-
-条件限制：
-
-- 若场景为单聊（`receive_scene = "Chat"`），则 `SenderGroup` 和 `MessageLink` 不可用
-
----
-
-#### 操作节点输出
-
-##### FindRecordAction（查找记录）
-
-| pathId | 说明 | 引用示例|
-|--------|------|-------|
-| `fieldRecords` | 所有找到的记录的引用（可用于 Loop 遍历） | `$.{stepId}.fieldRecords`|
-| `firstfieldsRecord` | 第一条匹配记录 | `$.{stepId}.firstfieldsRecord`|
-| `firstfieldsRecord.{fieldId}` | 首条记录的字段值，可下钻字段属性 | `$.{stepId}.firstfieldsRecord.{fieldId}`|
-| `firstfieldsRecord.recordId` | 记录 ID 数组 | `$.{stepId}.firstfieldsRecord.recordId`|
-| `fields` | 查找到的所有记录某列值 | 不支持引用|
-| `fields.{fieldId}` | 用户选择的字段 | `$.{stepId}.fields.{fieldId}`|
-| `fields.{fieldId}.fieldId` | 用户选择的字段id数组 | `$.{stepId}.fields.{fieldId}.fieldId`|
-| `fields.{fieldId}.fieldName` | 用户选择的字段名数组 | `$.{stepId}.fields.{fieldId}.fieldName`|
-| `fields.recordId` | 记录 ID 数组 | `$.{stepId}.fields.recordId`|
-| `recordNum` | 找到记录总数 | `$.{stepId}.recordNum`|
-
-##### AddRecordAction（新增记录）
-
-| pathId | 说明 | 引用示例 |
-|--------|------|----------|
-| `{fieldId}` | 用户配置的字段值，可下钻字段属性 | `$.{stepId}.{fieldId}` |
-| `{fieldId}.fieldId` | 用户配置的字段id | `$.{stepId}.{fieldId}.fieldId` |
-| `{fieldId}.fieldName` | 用户配置的字段名 | `$.{stepId}.{fieldId}.fieldName` |
-| `recordId` | 新增的记录 ID | `$.{stepId}.recordId` |
-| `recordLink` | 新增的记录 URL | `$.{stepId}.recordLink` |
-
-##### SetRecordAction（更新记录）
-
-| pathId | 说明 | 引用示例 |
-|--------|------|----------|
-| `{fieldId}` | 用户配置的字段值，可下钻字段属性 | `$.{stepId}.{fieldId}` |
-| `{fieldId}.fieldId` | 用户配置的字段id | `$.{stepId}.{fieldId}.fieldId` |
-| `{fieldId}.fieldName` | 用户配置的字段名 | `$.{stepId}.{fieldId}.fieldName` |
-| `recordId` | 记录 ID 数组（因可能更新多条记录） | `$.{stepId}.recordId` |
-
-##### HTTPClientAction（HTTP 请求）
-
-HTTPClientAction 的输出取决于 `response_type`：
-
-| response_type | 是否可引用 | 输出说明 | 引用示例 |
-|--------------|-----------|----------|----------|
-| `none` | 否 | 无任何可引用输出 | 不支持引用 |
-| `text` | 是 | 整个响应文本作为节点整体输出 | `$.{stepId}` |
-| `json` | 是 | 响应体整体挂在 `body` 下，同时返回 `status_code`；仅可引用 `response_value` 中声明的字段 | `$.{stepId}.body`、`$.{stepId}.body.success`、`$.{stepId}.body.message`、`$.{stepId}.status_code` |
-
-**补充说明**：
-
-- 当 `response_type = none` 时，后续节点无法引用 HTTPClientAction 的任何输出
-- 当 `response_type = text` 时，`$.{stepId}` 表示整个响应文本
-- 当 `response_type = json` 时，`$.{stepId}.body` 表示整个 JSON body，`$.{stepId}.body.字段名` 表示 body 中某个字段
-- 仅当 `response_type = json` 时，`$.{stepId}.status_code` 表示请求该 HTTP URL 后返回的 HTTP 状态码
-- 仅当 `response_type = json` 时，`response_value` 必填
-- 当 `response_type = json` 时，后续节点只能引用 `response_value` 中声明过的字段
-
-**案例**：
-
-假设某个 `HTTPClientAction` 的配置如下：
-
-```json
-{
-  "id": "step_http_1",
-  "type": "HTTPClientAction",
-  "data": {
-    "response_type": "json",
-    "response_value": "{\"success\":true,\"message\":\"ok\"}"
-  }
-}
-```
-
-则后续节点仅可以引用：
-
-- `$.step_http_1.body`
-- `$.step_http_1.body.success`
-- `$.step_http_1.body.message`
-- `$.step_http_1.status_code`
-
-但**不能**引用未在 `response_value` 中声明的字段，例如：
-
-- `$.step_http_1.body.data`
-- `$.step_http_1.body.request_id`
-
-##### GenerateAiTextAction（AI 生成文本）
-
-| pathId | 说明 | 引用示例 |
-|--------|------|----------|
-| （整体出参） | AI 生成的文本内容（不支持下钻，只能引用 `$.{stepId}`） | `$.{stepId}` |
-
-##### 无输出的操作节点
-
-以下节点不产生任何可引用的输出数据：
-
-- **Delay**（延时等待）
-- **LarkMessageAction**（发送飞书消息）
-
----
-
-#### 分支节点输出
-
-以下分支节点均不产生任何可引用的输出数据：
-
-- **IfElseBranch**（条件分支）
-- **SwitchBranch**（多条件分支）
-
----
-
-#### 系统节点输出
-
-##### Loop（循环）
-
-| pathId | 说明 | 引用示例 |
-|--------|------|----------|
-| `item` | 当前循环元素 | `$.{stepId}.item` |
-| `index` | 从 0 开始的循环索引 | `$.{stepId}.index` |
-
-**`item` 的类型推断规则**（由循环数据源决定）：
-
-**场景一：遍历组合记录** — 数据源为 `record` 类型时（如 FindRecordAction 的 `fieldRecords`），`item` 类型为 `record`，可向下选择具体字段：
-
-| 说明 | 引用示例 |
-|------|----------|
-| 当前遍历的记录（record） | `$.{loopStepId}.item` |
-| 记录的具体字段 | `$.{loopStepId}.item.{fieldId}` |
-| 从 0 开始的索引（number） | `$.{loopStepId}.index` |
-
-**场景二：遍历字段** — 数据源为某个多值类型字段时，比如附件字段、人员字段，`item` 继承该字段的类型并可继续下钻字段属性：
-
-| 说明 | 引用示例 |
-|------|----------|
-| 当前遍历的元素（类型继承数据源字段类型，例如人员字段） | `$.{loopStepId}.item` |
-| 用户姓名 | `$.{loopStepId}.item.name` |
-| 从 0 开始的索引（number） | `$.{loopStepId}.index` |
-
----
-
-#### 字段属性下钻
-
-每个字段变量都可以进一步下钻选择字段的属性。所有字段至少支持 `fieldId` 和 `fieldName` 两个基础属性，部分字段还支持额外属性：
-
-| 字段类型 | 属性名称 | 属性 pathId | 属性 pathType | 说明 |
-|----------|---------|-------------|--------------|------|
-| **所有字段（基础）** | 字段 ID | `fieldId` | `string` | 字段的唯一标识 |
-| | 字段名称 | `fieldName` | `string` | 字段的显示名称 |
-| **人员字段**（`user` / `created_by` / `updated_by`） | 姓名 | `name` | `string` | 用户姓名 |
-| **日期字段**（`datetime` / `created_at` / `updated_at`） | 时间戳 | `timestamp` | `number` | 时间戳数值 |
-| **附件字段**（`attachment`） | 文件名 | `fileName` | `string` | 附件文件名 |
-| | 文件类型 | `fileType` | `string` | MIME 类型 |
-| | 文件大小 | `size` | `number` | 文件字节数 |
-| | 文件 Token | `fileToken` | `string` | 附件 token |
-| **超链接文本字段**（`text` 且 `style.type=url`） | 文本 | `text` | `string` | 链接文本部分 |
-| | 链接 | `link` | `string` | 链接 URL 部分 |
-| **自动编号字段**（`auto_number`） | 序号 | `sequence` | `number` | 编号的纯数字序号 |
-| **关联字段**（`link`） | 字段下钻 | `{fieldId}` | - | 可下钻到关联表的字段 |
-
-> 其他字段类型（如 `text`、`number`、`checkbox`、`select`、`location`、`formula`、`lookup` 等）仅支持 `fieldId` 和 `fieldName` 两个基础属性。
-
-下钻引用示例：
-
-```
-$.{stepId}.{fieldId} → 字段值本身
-$.{stepId}.{fieldId}.fieldId → 字段 ID（string）
-$.{stepId}.{fieldId}.fieldName    → 字段名称（string）
-$.{stepId}.{fieldId}.name → 人员姓名列表（array<string>，仅人员字段）
-$.{stepId}.{fieldId}.unionId → 人员 unionId 列表（array<string>，仅人员字段）
-$.{stepId}.{fieldId}.timestamp    → 时间戳（array<number>，仅日期字段）
-$.{stepId}.{fieldId}.fileName     → 文件名列表（array<string>，仅附件字段）
-$.{stepId}.{fieldId}.fileToken    → 文件 Token 列表（array<string>，仅附件字段）
-```
-
----
-
-#### 节点输出能力总览
-
-| 节点 | 类型 | 有输出 | 输出特性 |
-|------|------|--------|---------|
-| AddRecordTrigger | 触发器 | ✅ | 动态（表字段 + 记录属性） |
-| ChangeRecordTrigger | 触发器 | ✅ | 动态（表字段 + 记录属性） |
-| SetRecordTrigger | 触发器 | ✅ | 动态（表字段 + 记录属性） |
-| ReminderTrigger | 触发器 | ✅ | 动态（表字段 + 记录属性） |
-| ButtonTrigger | 触发器 | ✅ | 动态（表字段 + 记录属性；buttonElement 仅基础触发属性） |
-| TimerTrigger | 触发器 | ✅ | 静态（仅 scheduleTime） |
-| LarkMessageTrigger | 触发器 | ✅ | 静态（消息属性列表） |
-| FindRecordAction | 动作 | ✅ | 动态（用户选择的字段） |
-| AddRecordAction | 动作 | ✅ | 动态（用户配置的字段） |
-| SetRecordAction | 动作 | ✅ | 动态（用户配置的字段） |
-| HTTPClientAction | 动作 | ✅ | 动态（取决于用户配置的 HTTP 响应输出） |
-| GenerateAiTextAction | 动作 | ✅ | 静态（单 string） |
-| Delay | 动作 | ❌ | 无输出 |
-| LarkMessageAction | 动作 | ❌ | 无输出 |
-| IfElseBranch | 分支 | ❌ | 无输出 |
-| SwitchBranch | 分支 | ❌ | 无输出 |
-| Loop | 系统 | ✅ | 动态（取决于数据源） |
-
----
-
-### TextRefItem
-
-文本与引用混排，用于消息内容等动态拼接场景：
-
-```json
-[
-  { "value_type": "text", "value": "客户 " },
-  { "value_type": "ref", "value": "$.step_1.fieldxxx" },
-  { "value_type": "text", "value": " 创建了新订单" }
-]
-```
-
-### RecordFieldValue
-
-```json
-{ "field_name": "客户名称", "value": [{ "value_type": "text", "value": "张三" }] }
-```
-
-### AndCondition（Trigger 过滤条件）
-
-```json
-{
-  "conjunction": "and",
-  "conditions": [
-    { "field_name": "状态", "operator": "is", "value": [{ "value_type": "text", "value": "进行中" }] }
-  ]
-}
-```
-
-### OrGroup（Branch 分支条件）
-
-```json
-{
-  "conjunction": "or",
-  "conditions": [
-    {
-      "conjunction": "and",
-      "conditions": [
-        {
-          "left_value": { "value_type": "ref", "value": "$.step_1.fieldxxx" },
-          "operator": "isGreater",
-          "right_value": [{ "value_type": "number", "value": 1000 }]
-        }
-      ]
-    }
-  ]
-}
-```
-
-**operator 可选值：** `is` / `isNot` / `containsAny` / `doesNotContainAny` / /`containsAll`/ `isEmpty` / `isNotEmpty` / `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual`
-
-### RecordFilterInfo
-** 由于 conjunction 只支持 and，若需要实现 字段X 等于 A 或 B，你可以使用 containsAny
-```json
-{
-  "conjunction": "and",
-  "conditions": [
-    { "field_name": "状态", "operator": "is", "value": [{ "value_type": "text", "value": "进行中" }] }
-  ]
-}
-```
-
-### `select` 字段多值匹配
-
-| 操作 | operator | 正确写法 |
-|------|---------|---------|
-| 等于单个值 | `is` | `[{"value_type": "option", "value": {"name": "L2"}}]` |
-| 匹配多个值（L2 或 L3） | `containsAny` | `[{"value_type": "option", "value": {"name": "L2"}}, {"value_type": "option", "value": {"name": "L3"}}]` |
-
-> ⚠️ 不要用多个 `is` 条件（会被当作 OR，无法实现 AND）。推荐使用 `containsAny` 操作符匹配多个值。
-
-> ⚠️ **Select 字段条件**：`value_type` 必须为 `option`，`value` 对象可只传 `name`（如 `{"name": "L2"}`），无需提供选项 ID。
-
-### RefInfo
-
-```json
-{ "step_id": "step_trigger" }
-```
-
----
-
-返回 [Workflow schema index](../lark-base-workflow-schema.md)。

skills/lark-base/references/workflow-steps/system-loop.md

@@ -1,26 +0,0 @@
-# Loop
-
-`children.links` 包含 `loop_start` 边指向循环体入口，`next` 指向循环结束后的后继节点。
-
-```json
-{
-  "loop_mode": "continue",
-  "max_loop_times": 100,
-  "data": [{ "value_type": "ref", "value": "$.find_record_stepIdxxx.fieldRecords" }]
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `data` | 是 | ValueInfo[]（仅支持 `ref` 类型），循环数据源，只能填一个 |
-| `loop_mode` | 否 | 单次错误时是否继续：`end`（终止）/ `continue`（继续） |
-| `max_loop_times` | 否 | 最大循环次数 |
-
----
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/trigger-add-record.md

@@ -1,24 +0,0 @@
-# AddRecordTrigger
-
-```json
-{
-  "table_name": "订单表",
-  "watched_field_name": "状态",
-  "trigger_control_list": ["pasteUpdate", "automationBatchUpdate"],
-  "condition_list": [] /* AndCondition 数组 */ 
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `table_name` | 是 | 监控的数据表名 |
-| `watched_field_name` | 是 | 监控的字段名 |
-| `trigger_control_list` | 否 | 触发控制，可选值：`pasteUpdate` / `automationBatchUpdate` / `syncUpdate` / `appendImport` / `openAPIBatchUpdate` |
-| `condition_list` | 否 | 过滤条件数组，数组中每个元素为 AndCondition 结构，多个 AndCondition 之间为 OR 关系 |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/trigger-button.md

@@ -1,22 +0,0 @@
-# ButtonTrigger
-
-```json
-{
-  "button_type": "buttonField",
-  "table_name": "审批表"
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `button_type` | 是 | 按钮类型：`buttonField`（表格里的按钮，可操作当前记录数据）/ `buttonElement`（仪表盘、应用页面上的按钮，可执行整体操作） |
-| `table_name` | 否 | 绑定的数据表名，仅 `button_type=buttonField` 时填写 |
-
-> `buttonField` 和 `buttonElement` 的输出能力不同，详见下方「ButtonTrigger（按钮触发器）」输出说明。
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/trigger-change-record.md

@@ -1,24 +0,0 @@
-# ChangeRecordTrigger
-
-记录满足条件时触发，**新增和修改都会触发**。"修改为 X 或新增 X 时执行动作"这类需求用本触发器 + `condition_list`，一条工作流即可表达，不要拆成 AddRecordTrigger 和 SetRecordTrigger 两条。
-
-```json
-{
-  "table_name": "任务表",
-  "trigger_control_list": [],
-  "condition": null
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `table_name` | 是 | 监控的数据表名 |
-| `trigger_control_list` | 否 | 触发控制，可选值：`pasteUpdate` / `automationBatchUpdate` / `syncUpdate` / `appendImport` |
-| `condition_list` | 否 | 过滤条件数组，数组中每个元素为 AndCondition 结构，多个 AndCondition 之间为 OR 关系 |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/trigger-lark-message.md

@@ -1,40 +0,0 @@
-# LarkMessageTrigger
-
-```json
-{
-  "receive_scene": "group",
-  "receiver": [{ "value_type": "group", "value": {"id": "oc_xxxx", "name": "测试群"} }],
-  "scope": "all",
-  "filter": {
-    "conjunction": "and",
-    "content_contains": ["关键词"],
-    "sender_contains": [{ "value_type": "user", "value": {"id": "ou_xxxx", "name": ""} }],
-    "is_new_message": true,
-    "is_message_contain_attachment": false
-  }
-}
-```
-
-| 字段 | 必填 | 说明|
-|------|------|---|
-| `receive_scene` | 是 | 接收场景：`group`（群聊）/ `chat`（单聊）|
-| `receiver` | 是 | 触发来源，支持 `user` / `group` / `ref`。在单聊场景下，该字段指“可以和机器人单聊的用户”；在群聊场景下，该字段指“接收信息的群组”|
-| `scope` | 是 | 触发范围：`at`（@提及）/ `all`（所有消息）。该参数仅在群聊场景有效，单聊场景请勿指定该参数|
-| `filter` | 是 | MessageFilter 消息过滤条件|
-
-`MessageFilter`：
-
-| 字段 | 类型 | 说明 |
-|------|------|----|
-| `conjunction` | string | `and` 满足所有条件 / `or` 任一条件|
-| `content_contains` | string[] | 关键词列表|
-| `sender_contains` | ValueInfo[] | 筛选发送人（仅群聊+群组来源时生效，单聊场景请勿指定该参数）|
-| `is_new_message` | boolean | 仅新话题消息（仅群聊时有效，单聊场景请勿指定该参数）|
-| `is_message_contain_attachment` | boolean | 是否仅附件消息触发|
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/trigger-reminder.md

@@ -1,30 +0,0 @@
-# ReminderTrigger
-
-```json
-{
-  "table_name": "项目表",
-  "field_name": "截止日期",
-  "offset": 1,
-  "unit": "DAY",
-  "hour": 9,
-  "minute": 0,
-  "condition_list": null
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `table_name` | 是 | 数据表名 |
-| `field_name` | 是 | 日期字段名（必须为 `datetime` / `created_at` / `formula` / `lookup` 类型） |
-| `unit` | 是 | 偏移单位：`MINUTE` / `HOUR` / `DAY` / `WEEK` / `MONTH` |
-| `offset` | 是 | 提前/延后的偏移量（正数=提前，负数=延后；范围由 `unit` 决定）：`MINUTE` ∈ {0, 5, 15, 30, -5, -15, -30}；`HOUR` ∈ [-6, -1] ∪ [1, 6]；`DAY` ∈ [-7, 7]；`WEEK` ∈ [-7, -1] ∪ [1, 7]；`MONTH` ∈ [-7, -1] ∪ [1, 7] |
-| `hour` | 是 | 触发小时 (0-23)，默认 9 |
-| `minute` | 是 | 触发分钟 (0-59)，默认 0 |
-| `condition_list` | 否 | 过滤条件数组，数组中每个元素为 AndCondition 结构，多个 AndCondition 之间为 OR 关系  |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/trigger-set-record.md

@@ -1,38 +0,0 @@
-# SetRecordTrigger
-
-```json
-{
-  "table_name": "订单表",
-  "record_watch_conjunction": "and",
-  "record_watch_info": [ /* FieldCondition[] */ ],
-  "field_watch_info": [
-    { "field_name": "状态", "operator": "is", "value": [{ "value_type": "text", "value": "已发货" }] }
-  ],
-  "trigger_control_list": [],
-  "condition_list": null
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|----|------|
-| `table_name` | 是  | 监控的数据表名 |
-| `record_watch_conjunction` | 否  | 记录筛选组合方式：`and` / `or`，默认 `and` |
-| `record_watch_info` | 否  | 记录级过滤条件（修改前值匹配），为空则监听全部 |
-| `field_watch_info` | 是  | 字段级监控条件列表，至少一个 |
-| `trigger_control_list` | 否  | 触发控制，可选值：`pasteUpdate` / `automationBatchUpdate` / `syncUpdate` / `appendImport` |
-| `condition_list` | 否  | 过滤条件数组，数组中每个元素为 AndCondition 结构，多个 AndCondition 之间为 OR 关系 |
-
-`FieldWatchItem`：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `field_name` | string | 监听字段名称 |
-| `operator` | string | 操作符（仅明确要求字段满足条件时填） |
-| `value` | ValueInfo[] | 触发值 |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-base/references/workflow-steps/trigger-timer.md

@@ -1,27 +0,0 @@
-# TimerTrigger
-
-```json
-{
-  "rule": "WEEKLY",
-  "start_time": "2025-01-01 09:00",
-  "sub_unit": [1, 3, 5],
-  "is_never_end": true
-}
-```
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `rule` | 是 | `NO_REPEAT` / `DAILY` / `WEEKLY` / `MONTHLY` / `YEARLY` / `WORKDAY` / `CUSTOM` |
-| `start_time` | 否 | 开始时间，格式 `yyyy-MM-dd HH:mm` |
-| `interval` | 否 | 自定义间隔 [1,30]（仅 CUSTOM） |
-| `unit` | 否 | 自定义单位：`SECOND` / `MINUTE` / `HOUR` / `DAY` / `WEEK` / `MONTH` / `YEAR` |
-| `sub_unit` | 否 | 子单位（`WEEKLY` 时为星期几数组 0-6，`MONTHLY` 时为几号数组 1-31） |
-| `end_time` | 否 | 结束时间 |
-| `is_never_end` | 否 | 是否永不结束 |
-
----
-
-## 相关
-
-- 返回 [Workflow schema index](../lark-base-workflow-schema.md)
-- ValueInfo、ref、Condition、RecordFilterInfo 等公共结构见 [common-types-and-refs.md](common-types-and-refs.md)

skills/lark-calendar/SKILL.md

@@ -31,6 +31,8 @@ lark-cli calendar +agenda --as user
 | Shortcut | 说明 |
 |----------|------|
 | [`+agenda`](references/lark-calendar-agenda.md) | 查看日程安排（默认今天） |
+| [`+search-event`](references/lark-calendar-search-event.md) | 按关键词、时间范围和参会人搜索日程 |
+| [`+meeting`](references/lark-calendar-meeting.md) | 通过日程事件 ID 获取关联的视频会议信息（meeting_id、meeting_note） |
 | [`+create`](references/lark-calendar-create.md) | 创建日程并邀请参会人（ISO 8601 时间） |
 | [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室 |
 | [`+freebusy`](references/lark-calendar-freebusy.md) | 查询用户主日历的忙闲信息和 RSVP 状态 |
@@ -64,6 +66,9 @@ lark-cli calendar +agenda --as user
 |----------|--------|
 | 查询过去的会议（"昨天的会议""上周的会"） | [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md)（会议数据含即时会议，仅查日程会遗漏） |
 | 查询日历/日程或未来时间的会议 | 本 skill |
+| 按关键词搜索日程 | 本 skill（`+search-event`） |
+| 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
+| 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再 [`vc +detail`](../lark-vc/references/lark-vc-detail.md) → [`note +detail`](../lark-note/references/lark-note-detail.md) / [`minutes +detail`](../lark-minutes/references/lark-minutes-detail.md) |
 | 预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
 
 ## 任务类型分流

skills/lark-calendar/references/lark-calendar-meeting.md

@@ -0,0 +1,40 @@
+
+# calendar +meeting
+
+通过日程 ID（`event_id`） 获取关联的视频会议信息（`meeting_id`、`meeting_note`）。只读。
+
+## 命令
+
+```bash
+# 单个 / 批量（逗号分隔，最多 50 个）
+lark-cli calendar +meeting --event-ids <event_id1>,<event_id2>
+
+# 默认使用主日历，需要时显式传 --calendar-id
+lark-cli calendar +meeting --event-ids <event_id> --calendar-id <calendar_id>
+```
+
+## 输出字段
+
+| 字段 | 说明 |
+|------|------|
+| `event_id` | 日程 ID |
+| `meeting_id` | 关联的视频会议 ID |
+| `meeting_note` | 用户主动绑定到日程的纪要文档 Token（`MeetingNotes`，由用户在日程页手动添加；）。**与会中产生的 AI 智能纪要 `note_doc_token` 是两份不同文档**，要拿 AI 纪要请继续走 `vc +detail` → `note +detail`。 |
+
+## 下游链路
+
+`calendar +meeting` 只把日程 ID 翻译为 `meeting_id` / `meeting_note`，要拿会中产生的产物（AI 智能纪要、逐字稿、妙记）需继续调用：
+
+```bash
+# 1. meeting_id → note_id + minute_token（同一会议两份产物，可能各自为空）
+lark-cli vc +detail --meeting-ids <meeting_id>
+
+# 2a. note_id → 纪要文档 token（note_doc_token / verbatim_doc_token / shared_doc_tokens）
+lark-cli note +detail --note-id <note_id>
+
+# 2b. minute_token → 妙记 AI 产物（按需获取，不传不返回任何 AI 内容）
+lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --keyword --transcript
+
+# 3. 任意文档 token（meeting_note / note_doc_token / verbatim_doc_token / shared_doc_token）→ 正文
+lark-cli docs +fetch --api-version v2 --doc <doc_token> --doc-format markdown
+```

skills/lark-calendar/references/lark-calendar-search-event.md

@@ -0,0 +1,29 @@
+
+# calendar +search-event
+
+按关键词、时间范围和参会人搜索日历日程。只读。
+
+## 命令
+
+```bash
+# 按关键词
+lark-cli calendar +search-event --query "周会"
+
+# 按时间范围（ISO 8601 或 YYYY-MM-DD）
+lark-cli calendar +search-event --start "2026-04-20T00:00:00+08:00" --end "2026-04-27T23:59:59+08:00"
+
+# 按参会人（自动识别 ou_ 用户 / oc_ 群聊 / omm_ 会议室前缀）
+lark-cli calendar +search-event --attendee-ids "ou_user1,oc_chat1,omm_room1"
+
+# 组合
+lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27 --attendee-ids "ou_user1"
+```
+
+## 输出字段
+
+`items` 列表每条返回 `event_id` / `summary` / `start` / `end` / `is_all_day` / `app_link`；外层有 `has_more`、`page_token`。**仅返回基础字段，要拿日程详情用 `calendar events get`。**
+
+## 注意事项
+
+- 分页：`has_more=true` 时持续用 `page_token` 翻页直到 false，不要遗漏；`page-size` 最大 30。
+- 已结束的会议优先用 `vc +search`——日历不收录"即时会议"，只查日程会漏。

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

@@ -48,7 +48,6 @@ lark-cli drive +import --file ./data.csv --type bitable --folder-token <FOLDER_T
 
 # 导入数据到已有的多维表格（不新建，数据挂载到目标多维表格中）
 lark-cli drive +import --file ./data.xlsx --type bitable --target-token <BASE_TOKEN>
-# 成功后验证 <BASE_TOKEN>；不要拿返回中的导入任务 token 当作 Base token 复核
 
 # 预览底层调用链（上传 -> 创建任务 -> 轮询）
 lark-cli drive +import --file ./README.md --type docx --dry-run
@@ -73,7 +72,7 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
   2. 调用 `import_tasks` 接口发起导入任务，自动根据本地文件提取扩展名并构造挂载点（`mount_point`）参数
   3. 自动轮询查询导入任务状态；如果在内置轮询窗口内完成，则直接返回导入结果；如果仍未完成，则返回 `ticket`、当前状态和后续查询命令
 - **默认根目录行为**：不传 `--folder-token` 时，shortcut 会保留空的 `point.mount_key`，Lark Import API 会将其视为"导入到调用者根目录"。
-- **导入到已有 bitable**：当 `--type bitable` 且传了 `--target-token` 时，请求 body 中会增加一个 `token` 字段指向目标多维表格。数据会挂载到该已有多维表格中，而非创建新文档；完成后用输出的 `verification_token`（即传入的 `--target-token`）复核，不要改用返回的导入任务 `token` 做 Base 查询。
+- **导入到已有 bitable**：当 `--type bitable` 且传了 `--target-token` 时，请求 body 中会增加一个 `token` 字段指向目标多维表格的 token，point 挂载点逻辑不变。数据会挂载到该已有多维表格中，而非创建新文档。
 
 ### 支持的文件类型转换
 

skills/lark-event/SKILL.md

@@ -147,7 +147,7 @@ Lark-defined semantic tags (**not** JSON Schema's standard `format`). Common val
 
 | Topic      | Reference                                                                    | Coverage |
 |------------|------------------------------------------------------------------------------|---|
-| IM         | [`references/lark-event-im.md`](references/lark-event-im.md)                 | jq recipes (filter by chat_type / message_type / sender) + payload gotchas (`.content` is pre-rendered text — don't `fromjson`; `sender_id` is open_id; flat vs `.event` envelope) |
-| VC         | [`references/lark-event-vc.md`](references/lark-event-vc.md)                 | jq recipes (meeting-ended / note / transcript) + behavior gotchas (time conversion, note_source meeting-only, recording batches). All VC keys need `--as user` |
-| Minutes    | [`references/lark-event-minutes.md`](references/lark-event-minutes.md)       | jq recipes + enrichment gotcha (`title` may be empty on detail-API failure; `minute_source` meeting-only). `--as user` |
-| Whiteboard | [`references/lark-event-whiteboard.md`](references/lark-event-whiteboard.md) | jq recipes + subscription gotcha (**required** `-p whiteboard_id`, needs manage access or 403). `--as user\|bot` |
+| IM         | [`references/lark-event-im.md`](references/lark-event-im.md)                 | Catalog of 11 IM EventKeys + shape notes (flat vs V2 envelope) + `im.message.receive_v1` field gotchas (`sender_id` is open_id only; `.content` is plain text except for `interactive` cards) + common jq recipes (filter by chat_type / message_type / sender) |
+| VC         | [`references/lark-event-vc.md`](references/lark-event-vc.md)                 | Catalog of 2 VC EventKeys (`vc.meeting.participant_meeting_ended_v1`, `vc.note.generated_v1`) + field reference + source type semantics (meeting only) |
+| Minutes    | [`references/lark-event-minutes.md`](references/lark-event-minutes.md)       | Catalog of 1 Minutes EventKey (`minutes.minute.generated_v1`) + field reference + source type semantics (meeting only) |
+| Whiteboard | [`references/lark-event-whiteboard.md`](references/lark-event-whiteboard.md) | Catalog of 1 Board EventKey (`board.whiteboard.updated_v1`) + per-whiteboard subscription model (requires `-p whiteboard_id=<token>`) + payload field reference (whiteboard_id / operator_ids triple-id) |

skills/lark-event/references/lark-event-im.md

@@ -2,45 +2,85 @@
 
 > **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
 >
-> **The catalog lives in the CLI, not here.** `lark-cli event list` lists all 11 IM EventKeys; `lark-cli event schema <key>` gives any key's fields / types / enums. This file only covers what the schema can't: payload-shape gotchas and ready-to-use jq recipes.
+> **Heads-up for AI agents**: this key's `.content` is **NOT** the raw OAPI payload shape your training data may suggest. `lark-cli` runs a Process hook (`convertlib`) that flattens the V2 envelope and **pre-renders** `.content` to human-readable text for `text` / `post` / `image` / `file` / `audio` / etc. Only `interactive` (cards) keeps the raw JSON string. Don't blindly `fromjson`.
 
-## Shape: flat vs enveloped
+## Key catalog (11)
 
-`im.message.receive_v1` is the only **flat** key (fields at `.xxx`). The other 10 IM keys are **V2-enveloped** — fields live at `.event.xxx` (e.g. `.event.chat_id`). `event schema <key>` confirms it (its Output Schema nests everything under `event`).
+| EventKey | Purpose |
+|---|---|
+| `im.message.receive_v1` | Receive IM messages |
+| `im.message.message_read_v1` | User read a bot's **p2p** message (group messages don't fire this) |
+| `im.message.reaction.created_v1` | Reaction added to a message |
+| `im.message.reaction.deleted_v1` | Reaction removed from a message |
+| `im.chat.updated_v1` | Chat settings changed (owner, avatar, name, permissions, etc.) |
+| `im.chat.disbanded_v1` | Chat disbanded |
+| `im.chat.member.bot.added_v1` | Bot added to a chat |
+| `im.chat.member.bot.deleted_v1` | Bot removed from a chat |
+| `im.chat.member.user.added_v1` | User joined a chat (including topic chats) |
+| `im.chat.member.user.deleted_v1` | User left voluntarily **or** was removed |
+| `im.chat.member.user.withdrawn_v1` | Pending chat invite withdrawn (inviter canceled; user never actually joined) |
 
-## `.content` is pre-rendered — do NOT blindly `fromjson` (`im.message.receive_v1`)
+> **Shape**: `im.message.receive_v1` is the only flat key (fields at `.xxx`); the other 10 are V2-enveloped (fields at `.event.xxx`).
 
-`lark-cli` runs a Process hook that **pre-renders `.content` to human-readable text** for every `message_type` except `interactive` (`@mentions` resolved to display names). Only `interactive` (cards) keeps the raw JSON string.
+## Gotchas (`im.message.receive_v1`)
 
-| message_type | `.content` | How to read |
+**sender_id is open_id only**: the event payload carries no display name. Call the contact API separately if you need the sender's name.
+
+**`.content` shape depends on `message_type`** (this key uses a flat Custom schema; see [`events/im/message_receive.go`](../../../events/im/message_receive.go)):
+
+| message_type | `.content` shape | How to read |
 |---|---|---|
-| everything except `interactive` | plain text | use `.content` directly |
-| `interactive` (card) | raw card JSON string | `.content \| fromjson` |
+| `text` / `post` / `image` / `file` / `audio` / `sticker` / `share_chat` / `share_user` / `media` / `system` | Human-readable text (convertlib-processed; `@mentions` resolved to display names) | Use `.content` directly |
+| `interactive` (card) | Raw card JSON string (structured actions can't be losslessly flattened) | `.content \| fromjson` to get the card object |
 
-Applying `fromjson` to a non-interactive message errors per event (`jq: fromjson cannot be applied to "hello"`) and the consumer **silently drops** it — looks alive, emits nothing.
-
-**`sender_id` is `open_id` only** — the payload carries no display name; resolve via the contact API if you need one.
-
-## jq recipes (`im.message.receive_v1`)
-
-> Default = no `--jq` (stream every message). Use these only when asked to narrow the stream.
+**Do not blindly `fromjson`** — for non-interactive messages it fails with `jq: fromjson cannot be applied to "hello"` because `.content` isn't JSON-encoded.
 
 ```bash
-# group chats only (chat_type enum: p2p | group)
-lark-cli event consume im.message.receive_v1 --as bot \
-  --jq 'select(.chat_type=="group") | {chat: .chat_id, from: .sender_id, msg: .content}'
-
-# text messages only — .content is plain text
+# text: .content is plain text — no fromjson needed
 lark-cli event consume im.message.receive_v1 --as bot \
   --jq 'select(.message_type=="text") | .content'
 
-# interactive cards only — parse the card body
+# interactive: .content is a JSON string — fromjson to parse
 lark-cli event consume im.message.receive_v1 --as bot \
   --jq 'select(.message_type=="interactive") | .content | fromjson'
-
-# one sender's messages only
-lark-cli event consume im.message.receive_v1 --as bot \
-  --jq 'select(.sender_id=="ou_xxxx") | {msg_id: .message_id, text: .content}'
 ```
 
-Get your own open_id via `lark-cli contact +get-user --as user`; others' via `lark-cli contact +search-user`.
+## On-demand filter recipes
+
+> **Default = no `--jq`.** Run `lark-cli event consume im.message.receive_v1 --as bot` to see every message. The recipes below are only for cases where the user has asked to narrow the stream.
+
+### 1. Filter by chat type (p2p vs group)
+
+`chat_type` is an enum with values `p2p` / `group`.
+
+```bash
+# p2p only (direct messages)
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.chat_type=="p2p") | {from: .sender_id, msg: .content}'
+
+# group only
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.chat_type=="group") | {chat: .chat_id, from: .sender_id, msg: .content}'
+```
+
+### 2. Filter by message type
+
+```bash
+# text only — content is plain human-readable text
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="text") | .content'
+
+# interactive (card) only — parse the card body
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="interactive") | .content | fromjson'
+```
+
+### 3. Filter by sender (only one user's messages)
+
+```bash
+# example: only messages from the given open_id
+lark-cli event consume im.message.receive_v1 --as bot\
+  --jq 'select(.sender_id=="ou_xxxxxxxxxxxxxxxxxxxxxxxxxx") | {msg_id: .message_id, text: .content}'
+```
+
+Get your own open_id via `lark-cli contact +get-user --as user`; other users' via `lark-cli contact +search-user`.