fix: reduce base shortcut token overhead (#1426 squashed)

Squashed net diff of PR #1426 (github-base-token-improve): slim
lark-base SKILL.md + formula/workflow references, split the workflow
guide/schema into per-step references, add guess-tolerant flag aliases
and misuse hints for base record shortcuts (with containment-based
suggest), and drive import adjustments.

Combined onto eval/skills-combined alongside #1450 #1389 #1395 #1410.

Change-Id: Iab1f0c4f1a4c93fd9dbd49bc702cb0ef41022bda

internal/suggest/suggest.go

@@ -7,7 +7,10 @@
 // carrying their own copy.
 package suggest
 
-import "sort"
+import (
+	"sort"
+	"strings"
+)
 
 // Levenshtein computes the classic edit distance between two strings. It is
 // rune-aware, so it is correct for multi-byte input.
@@ -51,22 +54,29 @@ 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
-		prefix int
-		dist   int
+		name    string
+		contain bool
+		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)
-		// 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})
+		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})
 		}
 	}
 	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
 		}
@@ -94,6 +104,21 @@ 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/base/base_data_query.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"strings"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -20,6 +21,7 @@ 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{
@@ -28,6 +30,9 @@ 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,6 +73,14 @@ 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,6 +1066,129 @@ 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{
@@ -1434,6 +1557,48 @@ 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()
@@ -1525,20 +1690,29 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
-	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.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.Fatalf("err=%v", err)
 		}
 	})
 
-	t.Run("list legacy fields flag rejected in dry-run", func(t *testing.T) {
+	t.Run("list fields alias works in dry-run", 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", "--dry-run"}, factory, stdout)
-		if err == nil || !strings.Contains(err.Error(), "unknown flag: --fields") {
+		if err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--fields", "Name", "--dry-run"}, factory, stdout); err != nil {
 			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,6 +59,23 @@ 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)
@@ -135,7 +152,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-get", "+field-create", "+field-update", "+field-delete", "+field-search-options",
+		"+field-list", "+field-list-batch", "+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",
@@ -1088,6 +1105,22 @@ 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,6 +19,7 @@ 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,6 +21,7 @@ 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

@@ -0,0 +1,30 @@
+// 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,6 +10,12 @@ 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 {
@@ -23,6 +29,22 @@ 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").
@@ -61,6 +83,7 @@ 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"),
@@ -68,15 +91,15 @@ func dryRunFieldSearchOptions(_ context.Context, runtime *common.RuntimeContext)
 	if params["limit"].(int) <= 0 {
 		params["limit"] = 30
 	}
-	if keyword := strings.TrimSpace(runtime.Str("keyword")); keyword != "" {
+	if keyword := strings.TrimSpace(fieldSearchOptionsKeyword(runtime)); keyword != "" {
 		params["query"] = keyword
 	}
 	return common.NewDryRunAPI().
-		GET("/open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id/options").
+		GET(baseV3Path("bases", runtime.Str("base-token"), "tables", baseTableID(runtime), "fields", fieldRef, "options")).
 		Params(params).
 		Set("base_token", runtime.Str("base-token")).
 		Set("table_id", baseTableID(runtime)).
-		Set("field_id", runtime.Str("field-id"))
+		Set("field_id", fieldRef)
 }
 
 func validateFieldJSON(runtime *common.RuntimeContext) (map[string]interface{}, error) {
@@ -118,17 +141,142 @@ func executeFieldList(runtime *common.RuntimeContext) error {
 		offset = 0
 	}
 	limit := common.ParseIntBounded(runtime, "limit", 1, 200)
-	fields, total, err := listAllFields(runtime, runtime.Str("base-token"), baseTableID(runtime), offset, limit)
+	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)
 	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)
@@ -184,10 +332,25 @@ 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 := runtime.Str("field-id")
+	fieldRef := fieldSearchOptionsRef(runtime)
 	params := map[string]interface{}{
 		"offset": runtime.Int("offset"),
 		"limit":  runtime.Int("limit"),
@@ -195,7 +358,7 @@ func executeFieldSearchOptions(runtime *common.RuntimeContext) error {
 	if params["limit"].(int) <= 0 {
 		params["limit"] = 30
 	}
-	if keyword := strings.TrimSpace(runtime.Str("keyword")); keyword != "" {
+	if keyword := strings.TrimSpace(fieldSearchOptionsKeyword(runtime)); keyword != "" {
 		params["query"] = keyword
 	}
 	data, err := baseV3Call(runtime, "GET", baseV3Path("bases", baseToken, "tables", tableIDValue, "fields", fieldRef, "options"), params, nil)
@@ -210,7 +373,7 @@ func executeFieldSearchOptions(runtime *common.RuntimeContext) error {
 	runtime.Out(map[string]interface{}{
 		"field_id":   fieldRef,
 		"field_name": fieldRef,
-		"keyword":    strings.TrimSpace(runtime.Str("keyword")),
+		"keyword":    fieldSearchOptionsKeyword(runtime),
 		"options":    options,
 		"total":      total,
 	}, nil)

shortcuts/base/field_search_options.go

@@ -5,6 +5,7 @@ package base
 
 import (
 	"context"
+	"strings"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -19,8 +20,10 @@ var BaseFieldSearchOptions = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		tableRefFlag(true),
-		fieldRefFlag(true),
+		fieldRefFlag(false),
+		{Name: "field-name", Hidden: 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"},
 	},
@@ -29,6 +32,15 @@ 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,6 +4,7 @@
 package base
 
 import (
+	"context"
 	"encoding/json"
 	"os"
 	"reflect"
@@ -496,3 +497,61 @@ 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,7 +21,10 @@ 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,6 +5,7 @@ package base
 
 import (
 	"context"
+	"strings"
 
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
@@ -21,9 +22,14 @@ 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(),
@@ -45,6 +51,9 @@ 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,6 +5,7 @@ package base
 
 import (
 	"context"
+	"encoding/json"
 	"net/url"
 	"strconv"
 	"strings"
@@ -45,11 +46,11 @@ func validateRecordSelection(runtime *common.RuntimeContext) error {
 }
 
 func resolveRecordSelection(runtime *common.RuntimeContext) (recordSelection, error) {
-	recordIDs := runtime.StrArray("record-id")
-	fieldIDs := runtime.StrArray("field-id")
+	recordIDs := recordIDFlags(runtime)
+	fieldIDs := recordFieldFlags(runtime)
 	jsonRaw := strings.TrimSpace(runtime.Str("json"))
 	if len(recordIDs) > 0 && jsonRaw != "" {
-		return recordSelection{}, baseFlagErrorf("--record-id and --json are mutually exclusive")
+		return recordSelection{}, baseFlagErrorf("--record-id/--record-ids and --json are mutually exclusive")
 	}
 	if jsonRaw != "" {
 		pc := newParseCtx(runtime)
@@ -145,6 +146,73 @@ 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) {
@@ -375,7 +443,7 @@ func validateRecordJSON(runtime *common.RuntimeContext) error {
 }
 
 func recordListFields(runtime *common.RuntimeContext) []string {
-	return runtime.StrArray("field-id")
+	return recordFieldFlags(runtime)
 }
 
 func executeRecordList(runtime *common.RuntimeContext) error {

shortcuts/base/record_query.go

@@ -26,6 +26,10 @@ 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,
@@ -34,6 +38,10 @@ 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
@@ -43,7 +51,10 @@ func validateRecordQueryOptions(runtime *common.RuntimeContext) error {
 }
 
 func parseRecordFilterFlag(runtime *common.RuntimeContext) (interface{}, error) {
-	filterRaw := strings.TrimSpace(runtime.Str(recordFilterJSONFlag))
+	filterRaw, err := recordQueryFlagValue(runtime, recordFilterJSONFlag, "filter")
+	if err != nil {
+		return nil, err
+	}
 	if filterRaw == "" {
 		return nil, nil
 	}
@@ -52,7 +63,10 @@ func parseRecordFilterFlag(runtime *common.RuntimeContext) (interface{}, error)
 }
 
 func parseRecordSortFlag(runtime *common.RuntimeContext) ([]interface{}, error) {
-	sortRaw := strings.TrimSpace(runtime.Str(recordSortJSONFlag))
+	sortRaw, err := recordQueryFlagValue(runtime, recordSortJSONFlag, "sort")
+	if err != nil {
+		return nil, err
+	}
 	if sortRaw == "" {
 		return nil, nil
 	}
@@ -64,6 +78,18 @@ 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 {
@@ -167,7 +193,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 := strings.TrimSpace(runtime.Str("keyword")); keyword != "" {
+	if keyword := recordSearchKeyword(runtime); keyword != "" {
 		body["keyword"] = keyword
 	}
 	searchFields := runtime.StrArray("search-field")
@@ -217,6 +243,9 @@ 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) {
@@ -225,7 +254,7 @@ func validateRecordSearchFlags(runtime *common.RuntimeContext) error {
 		_, err := recordSearchJSONBody(runtime)
 		return err
 	}
-	if strings.TrimSpace(runtime.Str("keyword")) == "" {
+	if recordSearchKeyword(runtime) == "" {
 		return baseFlagErrorf("--keyword is required unless --json is used")
 	}
 	if len(runtime.StrArray("search-field")) == 0 {
@@ -235,7 +264,7 @@ func validateRecordSearchFlags(runtime *common.RuntimeContext) error {
 }
 
 func recordSearchHasJSONExclusiveFlagInputs(runtime *common.RuntimeContext) bool {
-	return strings.TrimSpace(runtime.Str("keyword")) != "" ||
+	return recordSearchKeyword(runtime) != "" ||
 		len(runtime.StrArray("search-field")) > 0 ||
 		len(recordListFields(runtime)) > 0 ||
 		runtime.Str("view-id") != "" ||
@@ -243,6 +272,13 @@ 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,11 +22,16 @@ 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,6 +19,7 @@ func Shortcuts() []common.Shortcut {
 		BaseTableUpdate,
 		BaseTableDelete,
 		BaseFieldList,
+		BaseFieldListBatch,
 		BaseFieldGet,
 		BaseFieldCreate,
 		BaseFieldUpdate,

shortcuts/base/table_ops.go

@@ -63,7 +63,8 @@ func executeTableList(runtime *common.RuntimeContext) error {
 		offset = 0
 	}
 	limit := common.ParseIntBounded(runtime, "limit", 1, 100)
-	tables, total, err := listAllTables(runtime, runtime.Str("base-token"), offset, limit)
+	baseToken := runtime.Str("base-token")
+	tables, total, err := listAllTables(runtime, baseToken, offset, limit)
 	if err != nil {
 		return err
 	}
@@ -186,6 +187,24 @@ 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/drive/drive_import.go

@@ -31,7 +31,10 @@ 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); when set, data is mounted into this bitable instead of creating a new one"},
+		{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.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateDriveImportSpec(driveImportSpec{
@@ -139,6 +142,14 @@ 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,3 +762,43 @@ 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)
+	}
+}

skills/lark-base/SKILL.md

@@ -35,16 +35,44 @@ 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 时优先用它；返回 ID 关系和 fewshot 看 `--help` |
+| 查看 Base 内资源目录 | `+base-block-list` | 先判断 Base 里有什么（table/docx/dashboard/workflow/folder），再决定走哪类命令 |
 | 管理 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` | 写入前用 list/get 确认字段类型、选项、ID；删除前确认目标字段 |
+| 列/查/删字段 | `+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-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) |
@@ -58,24 +86,34 @@ 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-*` | 创建/更新或理解 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)；系统角色不可删除；关闭高级权限会影响自定义角色 |
+| 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) |
 
-## 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。
@@ -83,35 +121,27 @@ metadata:
 - `91403` 或明确不可访问错误不要循环换身份重试。
 - `+base-create` / `+base-copy` 若用 bot 身份执行，关注返回中的 `permission_grant`，并把用户是否可打开新 Base 告知用户。
 
-## 查询与统计规则
+### 查询与统计
 
-涉及查询、统计或判断结论时，先阅读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md)，并遵守：
+- 涉及筛选、排序、Top/Bottom N、聚合、分组、多表关联或任何全局结论时，先读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) 并按其 Hard Rules 执行。
+- 两条红线随时生效：能由 Base 云端表达的筛选/排序/聚合不要拉原始记录到本地手工处理；`has_more=true` 等分页信号未消除前，不能基于当前页下全局结论。
 
-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` 验证，再按需沉淀为持久视图。
 
-- `+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 验证结果，再按需要沉淀为持久视图。
+### 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)；删除角色、关闭高级权限前确认目标和影响。
 
 ## Token 与链接
 
@@ -122,19 +152,10 @@ metadata:
 | `/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/{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 直接访问 |
+| `/share/base/view/...` / `/share/base/dashboard/...` / `/record/...` / `/base/workspace/...` | 分享链接与 workspace 链接，暂不支持用 CLI 直接访问，引导用户在飞书客户端打开；要生成记录分享链接用 `+record-share-link-create` |
 
 `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` 只适用于自定义角色，系统角色不可删除；删除角色和关闭高级权限前必须确认目标和影响。
-
 ## 常见恢复
 
 | 错误 / 现象 | 恢复动作 |
@@ -149,18 +170,3 @@ metadata:
 | `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,6 +2,8 @@
 
 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

@@ -0,0 +1,115 @@
+# 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,175 +228,139 @@ After the result column, it's recommended to flatten with `.LISTCOMBINE()` first
 
 ---
 
-## Section 8: Complete Function Reference
+## Section 8: Function Reference (common functions)
+
+> 本表覆盖常用函数（含评测与真实负载中 100% 出现过的函数）。三角/双曲/随机数/进制转换等罕见函数的签名在 [formula-functions-extended.md](formula-functions-extended.md)，仅当用户明确要求这些函数时再读。
 
 ### 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)                                       |
-| 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                                                       |
+| 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 |
 
 ### 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                                                                                                                                                                                                                                                    |
-| 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                                                                                                                                                                                               |
+| 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 |
 
 ### 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                                                                                      |
-| 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                                                                                            |
+| 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 |
 
 ### 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**   |
-| 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)                                                                      |
+| 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) |
 
 ### 8.5 List functions
 
-| 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)                                                                                                                                                                   |
+| 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) |
 
 ---
-
 ## 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`) |
 
 ---
 
@@ -612,119 +576,11 @@ Reason: NOW, TODAY, PI and other zero-argument functions must include parenthese
 
 ---
 
-## Section 13: Complete Examples
+## Section 13: Examples
 
-### Example 1: Employee sales summary
+完整示例与"自然语言需求 → 公式"翻译规则按需读 [formula-examples.md](formula-examples.md)。
 
-**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
+## Section 14: 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

@@ -0,0 +1,66 @@
+# 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,6 +13,9 @@
 - 一次 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

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

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

@@ -1,46 +1,130 @@
 # Workflow guide
 
-本文档是 Workflow 的入口指南，帮助选择步骤组合、理解创建/更新边界，并引导到 steps JSON SSOT。
+本文档是 Workflow 的操作地图：先用它决定最短路径，再按需打开 schema 小文件。Guide 要一次读完后能完成大多数查询、启停和常见创建/修改；schema 才是零件手册。
 
-> **配套文档**:
-> - 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": "1704067200",
-  "title": "新订单自动通知",
+  "client_token": "unique-create-token",
+  "title": "工作流标题",
   "steps": [
     {
-      "id": "trigger_1",
+      "id": "step_trigger",
       "type": "AddRecordTrigger",
-      "title": "监控新订单",
-      "next": "action_1",
+      "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",
       "data": {
         "table_name": "订单表",
         "watched_field_name": "订单号"
       }
     },
     {
-      "id": "action_1",
+      "id": "act_notify",
       "type": "LarkMessageAction",
       "title": "发送通知",
       "next": null,
       "data": {
-        "receiver": [{ "value_type": "user", "value": {"id": "ou_xxxx", "name": "张三"} }],
+        "receiver": [{ "value_type": "user", "value": { "id": "ou_xxx" } }],
         "send_to_everyone": false,
         "title": [{ "value_type": "text", "value": "新订单提醒" }],
-        "content": [
-          { "value_type": "text", "value": "收到新订单" }
-        ],
+        "content": [{ "value_type": "text", "value": "收到新订单" }],
         "btn_list": []
       }
     }
@@ -48,783 +132,27 @@
 }
 ```
 
----
+## 修改现有 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-组合场景-定时查找循环分支消息) |
+## 常见错误
 
----
-
-## 完整示例
-
-### 示例 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" }
-```
-
----
+| 错误 | 处理 |
+|---|---|
+| 查询/启停也读 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` |
 
 ## 参考
 
-- [lark-base-workflow-schema.md](lark-base-workflow-schema.md) — 字段定义参考
-- 创建/更新前先确认真实表名、字段名和目标 workflow ID；`steps` 结构按 schema 构造，不凭自然语言猜 `type`
+- [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、节点输出；只有构造这些细节时才读。

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

@@ -0,0 +1,24 @@
+# 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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,21 @@
+# 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

@@ -0,0 +1,48 @@
+# 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

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,28 @@
+# 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

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,52 @@
+# 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

@@ -0,0 +1,401 @@
+# 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

@@ -0,0 +1,26 @@
+# 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

@@ -0,0 +1,24 @@
+# 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

@@ -0,0 +1,22 @@
+# 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

@@ -0,0 +1,24 @@
+# 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

@@ -0,0 +1,40 @@
+# 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

@@ -0,0 +1,30 @@
+# 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

@@ -0,0 +1,38 @@
+# 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

@@ -0,0 +1,27 @@
+# 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-drive/references/lark-drive-import.md

@@ -48,6 +48,7 @@ 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
@@ -72,7 +73,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` 字段指向目标多维表格的 token，point 挂载点逻辑不变。数据会挂载到该已有多维表格中，而非创建新文档。
+- **导入到已有 bitable**：当 `--type bitable` 且传了 `--target-token` 时，请求 body 中会增加一个 `token` 字段指向目标多维表格。数据会挂载到该已有多维表格中，而非创建新文档；完成后用输出的 `verification_token`（即传入的 `--target-token`）复核，不要改用返回的导入任务 `token` 做 Base 查询。
 
 ### 支持的文件类型转换