fix(base): improve dashboard shortcut guidance

shortcuts/base/base_dashboard_execute_test.go

@@ -4,9 +4,11 @@
 package base
 
 import (
+	"errors"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/httpmock"
 )
 
@@ -676,6 +678,145 @@ func TestBaseDashboardBlockCreate_InvalidRollup(t *testing.T) {
 	}
 }
 
+// TestBaseDashboardBlockCreate_IllegalSortOrderType guards against a P1 where a
+// non-string sort.order (123 / null / false) was silently coerced to "asc" and
+// created a block with a tampered sort. A present-but-illegal order must now
+// surface a typed validation error, never a silent default.
+func TestBaseDashboardBlockCreate_IllegalSortOrderType(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		order string // raw JSON literal for the order value
+	}{
+		{"number", "123"},
+		{"null", "null"},
+		{"bool", "false"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			factory, stdout, _ := newExecuteFactory(t)
+			dc := `{"table_name":"T","series":[{"field_name":"金额","rollup":"SUM"}],` +
+				`"group_by":[{"field_name":"状态","mode":"integrated","sort":{"type":"group","order":` + tc.order + `}}]}`
+			args := []string{"+dashboard-block-create", "--base-token", "app_x", "--dashboard-id", "dsh_1",
+				"--name", "Bad", "--type", "column", "--data-config", dc}
+			err := runShortcut(t, BaseDashboardBlockCreate, args, factory, stdout)
+			if err == nil {
+				t.Fatalf("expected validation error for order=%s, got nil (stdout=%s)", tc.order, stdout.String())
+			}
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
+			}
+			if ve.Category != errs.CategoryValidation || ve.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("category=%q subtype=%q, want validation/invalid_argument", ve.Category, ve.Subtype)
+			}
+			if ve.Param != "--data-config" {
+				t.Fatalf("param=%q, want --data-config", ve.Param)
+			}
+			if !strings.Contains(ve.Error(), "sort.order") {
+				t.Fatalf("error should name sort.order, got: %v", ve)
+			}
+		})
+	}
+}
+
+// TestBaseDashboardBlockCreate_MissingSortOrder pins the full create-path behavior
+// when sort.order is absent: group/view are normalized to order:"asc" and succeed
+// (matching the documented auto-fill), while value has no safe default and must
+// surface a typed validation error. These run end-to-end (Validate → normalize →
+// validate), so reverting the normalize/validate change flips a case and fails.
+func TestBaseDashboardBlockCreate_MissingSortOrder(t *testing.T) {
+	dc := func(sortType string) string {
+		return `{"table_name":"T","series":[{"field_name":"金额","rollup":"SUM"}],` +
+			`"group_by":[{"field_name":"状态","mode":"integrated","sort":{"type":"` + sortType + `"}}]}`
+	}
+
+	// group / view: absent order is auto-filled with "asc" and the request goes through.
+	for _, sortType := range []string{"group", "view"} {
+		t.Run(sortType+" defaults to asc", func(t *testing.T) {
+			factory, stdout, _ := newExecuteFactory(t)
+			args := []string{"+dashboard-block-create", "--base-token", "app_x", "--dashboard-id", "dsh_1",
+				"--name", "OK", "--type", "column", "--data-config", dc(sortType),
+				"--dry-run", "--format", "pretty"}
+			if err := runShortcut(t, BaseDashboardBlockCreate, args, factory, stdout); err != nil {
+				t.Fatalf("err=%v", err)
+			}
+			if got := stdout.String(); !strings.Contains(got, `"order":"asc"`) {
+				t.Fatalf("expected normalized order:asc for type=%s, stdout=%s", sortType, got)
+			}
+		})
+	}
+
+	// value: no meaningful default direction, so a missing order is a typed error.
+	t.Run("value requires explicit order", func(t *testing.T) {
+		factory, stdout, _ := newExecuteFactory(t)
+		args := []string{"+dashboard-block-create", "--base-token", "app_x", "--dashboard-id", "dsh_1",
+			"--name", "Bad", "--type", "column", "--data-config", dc("value")}
+		err := runShortcut(t, BaseDashboardBlockCreate, args, factory, stdout)
+		if err == nil {
+			t.Fatalf("expected validation error for value sort missing order, got nil (stdout=%s)", stdout.String())
+		}
+		p, ok := errs.ProblemOf(err)
+		if !ok || p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument {
+			t.Fatalf("expected validation/invalid_argument problem, got %T %v", err, err)
+		}
+		var ve *errs.ValidationError
+		if !errors.As(err, &ve) || ve.Param != "--data-config" {
+			t.Fatalf("expected param --data-config, got %T %v", err, err)
+		}
+		if !strings.Contains(ve.Error(), "sort.order 缺失") {
+			t.Fatalf("error should report missing order, got: %v", ve)
+		}
+	})
+}
+
+// TestNormalizeDataConfigSortOrder pins the normalization contract for sort.order:
+// only a truly absent key gets the "asc" default; a present illegal value is left
+// untouched so validation can reject it; a valid string is lower-cased.
+func TestNormalizeDataConfigSortOrder(t *testing.T) {
+	sortOf := func(cfg map[string]interface{}) map[string]interface{} {
+		gb := cfg["group_by"].([]interface{})
+		return gb[0].(map[string]interface{})["sort"].(map[string]interface{})
+	}
+	newCfg := func(sort map[string]interface{}) map[string]interface{} {
+		return map[string]interface{}{
+			"table_name": "T",
+			"series":     []interface{}{map[string]interface{}{"field_name": "v", "rollup": "sum"}},
+			"group_by":   []interface{}{map[string]interface{}{"field_name": "g", "sort": sort}},
+		}
+	}
+
+	t.Run("absent order defaults to asc for group", func(t *testing.T) {
+		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "group"}))
+		if got := sortOf(out)["order"]; got != "asc" {
+			t.Fatalf("order=%v, want asc", got)
+		}
+	})
+	t.Run("absent order not defaulted for value", func(t *testing.T) {
+		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "value"}))
+		if _, has := sortOf(out)["order"]; has {
+			t.Fatalf("value sort must not get a defaulted order: %v", sortOf(out))
+		}
+	})
+	t.Run("valid string lower-cased", func(t *testing.T) {
+		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "group", "order": "DESC"}))
+		if got := sortOf(out)["order"]; got != "desc" {
+			t.Fatalf("order=%v, want desc", got)
+		}
+	})
+	t.Run("illegal number not coerced", func(t *testing.T) {
+		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "group", "order": float64(123)}))
+		if got := sortOf(out)["order"]; got != float64(123) {
+			t.Fatalf("order=%v (type %T), want untouched 123", got, got)
+		}
+	})
+	t.Run("illegal nil not coerced", func(t *testing.T) {
+		out := normalizeDataConfig(newCfg(map[string]interface{}{"type": "view", "order": nil}))
+		got, has := sortOf(out)["order"]
+		if !has || got != nil {
+			t.Fatalf("order=%v has=%v, want present nil (untouched)", got, has)
+		}
+	})
+}
+
 // ── Text Block Tests ────────────────────────────────────────────────
 
 // TestBaseDashboardBlockExecuteCreate_TextType tests creating text blocks with markdown content.

shortcuts/base/base_dryrun_ops_test.go

@@ -117,6 +117,14 @@ func TestDryRunRecordOps(t *testing.T) {
 	)
 	assertDryRunContains(t, dryRunRecordList(ctx, listRT), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/records", "offset=0", "limit=200", "view_id=viw_1", "field_id=Name", "field_id=Age")
 
+	listFieldNamesAliasRT := newBaseTestRuntimeWithSlices(
+		map[string]string{"base-token": "app_x", "table-id": "tbl_1"},
+		map[string][]string{"field-names": {"Name", "Age"}},
+		nil,
+		map[string]int{"limit": 20},
+	)
+	assertDryRunContains(t, dryRunRecordList(ctx, listFieldNamesAliasRT), "GET /open-apis/base/v3/bases/app_x/tables/tbl_1/records", "limit=20", "field_id=Name", "field_id=Age")
+
 	filteredListRT := newBaseTestRuntimeWithArrays(
 		map[string]string{
 			"base-token":  "app_x",

shortcuts/base/base_execute_test.go

@@ -1296,6 +1296,29 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
+	t.Run("list field names alias", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "field_id=Name&field_id=Age&limit=1&offset=0",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"fields":         []interface{}{"Name", "Age"},
+					"record_id_list": []interface{}{"rec_alias"},
+					"data":           []interface{}{[]interface{}{"Alice", 18}},
+					"total":          1,
+				},
+			},
+		})
+		if err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--limit", "1", "--field-names", "Name,Age", "--format", "json"}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if got := stdout.String(); !strings.Contains(got, `"rec_alias"`) || !strings.Contains(got, `"Alice"`) {
+			t.Fatalf("stdout=%s", got)
+		}
+	})
+
 	t.Run("list json format", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
@@ -1320,6 +1343,30 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
+	t.Run("list json alias", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "limit=1&offset=0",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"fields":         []interface{}{"Name"},
+					"field_id_list":  []interface{}{"fld_name"},
+					"record_id_list": []interface{}{"rec_alias"},
+					"data":           []interface{}{[]interface{}{"Carol"}},
+					"total":          1,
+				},
+			},
+		})
+		if err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--limit", "1", "--json"}, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		if got := stdout.String(); !strings.Contains(got, `"record_id_list"`) || !strings.Contains(got, `"Carol"`) || !strings.Contains(got, `"rec_alias"`) {
+			t.Fatalf("stdout=%s", got)
+		}
+	})
+
 	t.Run("list markdown format", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
@@ -1576,6 +1623,14 @@ func TestBaseRecordExecuteReadCreateDelete(t *testing.T) {
 		}
 	})
 
+	t.Run("list field ids and field names alias are mutually exclusive", func(t *testing.T) {
+		factory, stdout, _ := newExecuteFactory(t)
+		err := runShortcut(t, BaseRecordList, []string{"+record-list", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "Name", "--field-names", "Age"}, factory, stdout)
+		if err == nil || !strings.Contains(err.Error(), "--field-id and --field-names are mutually exclusive") {
+			t.Fatalf("err=%v", err)
+		}
+	})
+
 	t.Run("list legacy fields flag rejected 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)

shortcuts/base/base_shortcuts_test.go

@@ -28,13 +28,24 @@ func newBaseTestRuntime(stringFlags map[string]string, boolFlags map[string]bool
 }
 
 func newBaseTestRuntimeWithArrays(stringFlags map[string]string, stringArrayFlags map[string][]string, boolFlags map[string]bool, intFlags map[string]int) *common.RuntimeContext {
+	return newBaseTestRuntimeWithArraysAndSlices(stringFlags, stringArrayFlags, nil, boolFlags, intFlags)
+}
+
+func newBaseTestRuntimeWithSlices(stringFlags map[string]string, stringSliceFlags map[string][]string, boolFlags map[string]bool, intFlags map[string]int) *common.RuntimeContext {
+	return newBaseTestRuntimeWithArraysAndSlices(stringFlags, nil, stringSliceFlags, boolFlags, intFlags)
+}
+
+func newBaseTestRuntimeWithArraysAndSlices(stringFlags map[string]string, stringArrayFlags map[string][]string, stringSliceFlags map[string][]string, boolFlags map[string]bool, intFlags map[string]int) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "test"}
 	for name := range stringFlags {
 		cmd.Flags().String(name, "", "")
 	}
 	for name := range stringArrayFlags {
 		cmd.Flags().StringArray(name, nil, "")
 	}
+	for name := range stringSliceFlags {
+		cmd.Flags().StringSlice(name, nil, "")
+	}
 	for name := range boolFlags {
 		cmd.Flags().Bool(name, false, "")
 	}
@@ -50,6 +61,11 @@ func newBaseTestRuntimeWithArrays(stringFlags map[string]string, stringArrayFlag
 			_ = cmd.Flags().Set(name, value)
 		}
 	}
+	for name, values := range stringSliceFlags {
+		for _, value := range values {
+			_ = cmd.Flags().Set(name, value)
+		}
+	}
 	for name, value := range boolFlags {
 		if value {
 			_ = cmd.Flags().Set(name, "true")
@@ -545,6 +561,8 @@ func TestBaseDashboardHelpGuidesAgents(t *testing.T) {
 				"not table_id or field_id",
 				"dashboard-block-data-config.md as the SSOT",
 				"do not invent data_config from natural language",
+				"set the intended group_by.sort in the initial create request",
+				"do not create first and then issue a second update",
 				"sequentially",
 			},
 		},
@@ -825,6 +843,7 @@ func TestBaseRecordWriteHelpGuidesAgents(t *testing.T) {
 				"may use null for empty cells",
 				"use +field-list to confirm real writable fields",
 				"Batch create supports max 200 rows per call",
+				"do not immediately +record-list the same table",
 				"CellValue happy path: text/phone/url",
 				`ID-based CellValue: user/group/link fields use arrays like [{"id":"ou_xxx"}]`,
 				"lark-base-cell-value.md",

shortcuts/base/dashboard_arrange.go

@@ -23,7 +23,7 @@ var BaseDashboardArrange = common.Shortcut{
 		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
 	},
 	Tips: []string{
-		"Server-side smart layout is not deterministic or position-specific; use only when the user asks to arrange or beautify a dashboard.",
+		"Server-side smart layout is not deterministic or position-specific; use only when the user asks to arrange or beautify a dashboard, or to tidy up a dashboard created from scratch in this session.",
 	},
 	DryRun: dryRunDashboardArrange,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {

shortcuts/base/dashboard_block_create.go

@@ -27,14 +27,15 @@ var BaseDashboardBlockCreate = common.Shortcut{
 		{Name: "type", Desc: "block type: column(柱状图)|bar(条形图)|line(折线图)|pie(饼图)|ring(环形图)|area(面积图)|combo(组合图)|scatter(散点图)|funnel(漏斗图)|wordCloud(词云)|radar(雷达图)|statistics(指标卡)|text(文本). Read dashboard-block-data-config.md before creating.", Required: true},
 		{Name: "data-config", Desc: "data_config JSON object; read dashboard-block-data-config.md for the SSOT"},
 		{Name: "user-id-type", Desc: "user ID type for user fields in filters: open_id / union_id / user_id"},
-		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},
+		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation and normalization; send data_config as-is"},
 	},
 	Tips: []string{
 		`lark-cli base +dashboard-block-create --base-token <base_token> --dashboard-id <dashboard_id> --name "Order Count" --type statistics --data-config '{"table_name":"Orders","count_all":true}'`,
 		`lark-cli base +dashboard-block-create --base-token <base_token> --dashboard-id <dashboard_id> --name "Dashboard Note" --type text --data-config '{"text":"# Sales Dashboard"}'`,
 		"Before creating data-backed blocks, use +table-list and +field-list to confirm real table and field names.",
 		"data_config uses table and field names, not table_id or field_id.",
 		"Read dashboard-block-data-config.md as the SSOT for chart templates, filters, metric rules, and type-specific fields; do not invent data_config from natural language.",
+		"For funnel/stage charts backed by ordered helper data, set the intended group_by.sort in the initial create request; do not create first and then issue a second update just to fix sorting.",
 		"Record the returned block_id; block update/delete/get-data commands need it.",
 		"Create dashboard blocks sequentially; do not parallelize multiple block creates for the same dashboard.",
 	},

shortcuts/base/dashboard_block_get_data.go

@@ -20,6 +20,7 @@ var BaseDashboardBlockGetData = common.Shortcut{
 	Flags: []common.Flag{
 		baseTokenFlag(true),
 		blockIDFlag(true),
+		{Name: "dashboard-id", Desc: "hidden compatibility flag accepted by dashboard block commands; ignored by get-data", Hidden: true},
 	},
 	Tips: []string{
 		"lark-cli base +dashboard-block-get-data --base-token <base_token> --block-id <block_id>",

shortcuts/base/dashboard_block_update.go

@@ -26,7 +26,7 @@ var BaseDashboardBlockUpdate = common.Shortcut{
 		{Name: "name", Desc: "new block name"},
 		{Name: "data-config", Desc: "data_config JSON object; read dashboard-block-data-config.md for the SSOT"},
 		{Name: "user-id-type", Desc: "user ID type for user fields in filters: open_id / union_id / user_id"},
-		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},
+		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation and normalization; send data_config as-is"},
 	},
 	Tips: []string{
 		`lark-cli base +dashboard-block-update --base-token <base_token> --dashboard-id <dashboard_id> --block-id <block_id> --name "Total Sales"`,

shortcuts/base/helpers.go

@@ -1038,11 +1038,23 @@ func normalizeDataConfig(cfg map[string]interface{}) map[string]interface{} {
 					m["mode"] = strings.ToLower(strings.TrimSpace(md))
 				}
 				if sub, ok := m["sort"].(map[string]interface{}); ok {
+					sortType := ""
 					if t, ok := sub["type"].(string); ok {
-						sub["type"] = strings.ToLower(strings.TrimSpace(t))
+						sortType = strings.ToLower(strings.TrimSpace(t))
+						sub["type"] = sortType
 					}
-					if o, ok := sub["order"].(string); ok {
-						sub["order"] = strings.ToLower(strings.TrimSpace(o))
+					// Only lowercase a string order; leave a present-but-non-string
+					// order untouched so validateBlockDataConfig can reject it
+					// instead of it being silently coerced below.
+					_, hasOrderKey := sub["order"]
+					orderStr, orderIsString := sub["order"].(string)
+					if orderIsString {
+						sub["order"] = strings.ToLower(strings.TrimSpace(orderStr))
+					}
+					// Default only when the order key is truly absent. A present
+					// key (even an illegal type/value) must survive to validation.
+					if !hasOrderKey && (sortType == "group" || sortType == "view") {
+						sub["order"] = "asc"
 					}
 					m["sort"] = sub
 				}
@@ -1126,12 +1138,16 @@ func validateBlockDataConfig(blockType string, cfg map[string]interface{}) []str
 			if sub, ok := m["sort"].(map[string]interface{}); ok {
 				t, _ := sub["type"].(string)
 				t = strings.ToLower(strings.TrimSpace(t))
-				o, _ := sub["order"].(string)
-				o = strings.ToLower(strings.TrimSpace(o))
 				if t != "group" && t != "value" && t != "view" {
 					errs = append(errs, fmt.Sprintf("group_by[%d].sort.type 仅支持 group|value|view", i))
 				}
-				if o != "asc" && o != "desc" {
+				orderRaw, hasOrder := sub["order"]
+				o, orderIsString := orderRaw.(string)
+				o = strings.ToLower(strings.TrimSpace(o))
+				switch {
+				case !hasOrder:
+					errs = append(errs, fmt.Sprintf("group_by[%d].sort.order 缺失；sort 存在时必须设置 order 为 asc 或 desc，例如 \"sort\":{\"type\":\"group\",\"order\":\"asc\"}", i))
+				case !orderIsString || (o != "asc" && o != "desc"):
 					errs = append(errs, fmt.Sprintf("group_by[%d].sort.order 仅支持 asc|desc", i))
 				}
 			}
@@ -1178,5 +1194,5 @@ func formatDataConfigErrors(problems []string) error {
 	if len(problems) == 0 {
 		return nil
 	}
-	return errs.NewValidationError(errs.SubtypeInvalidArgument, "data_config 校验失败:\n- %s\n参考: skills/lark-base/references/dashboard-block-data-config.md", strings.Join(problems, "\n- "))
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "data_config 校验失败:\n- %s\n参考: skills/lark-base/references/dashboard-block-data-config.md", strings.Join(problems, "\n- ")).WithParam("--data-config")
 }