fix(base): unify --json help format with tips and agent hints (#372)

* fix(base): improve --json help examples and group guide

* fix(base): unify --json help tips format

* docs(base): fix view-set-group schema with group_config

* fix(base): remove array wording from view-set-group json help

---------

Co-authored-by: kongenpei <kongenpei@users.noreply.github.com>

shortcuts/base/field_create.go

@@ -22,6 +22,10 @@ var BaseFieldCreate = common.Shortcut{
 		{Name: "json", Desc: "field property JSON object", Required: true},
 		{Name: "i-have-read-guide", Type: "bool", Desc: "set only after you have read the formula/lookup guide for those field types", Hidden: true},
 	},
+	Tips: []string{
+		`Example: --json '{"name":"Status","type":"text"}'`,
+		"Agent hint: use the lark-base skill's field-create guide for usage and limits.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateFieldCreate(runtime)
 	},

shortcuts/base/field_update.go

@@ -23,6 +23,10 @@ var BaseFieldUpdate = common.Shortcut{
 		{Name: "json", Desc: "field property JSON object", Required: true},
 		{Name: "i-have-read-guide", Type: "bool", Desc: "acknowledge reading formula/lookup guide before creating or updating those field types", Hidden: true},
 	},
+	Tips: []string{
+		`Example: --json '{"name":"Status","type":"text"}'`,
+		"Agent hint: use the lark-base skill's field-update guide for usage and limits.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateFieldUpdate(runtime)
 	},

shortcuts/base/record_upsert.go

@@ -22,6 +22,10 @@ var BaseRecordUpsert = common.Shortcut{
 		recordRefFlag(false),
 		{Name: "json", Desc: "record JSON object", Required: true},
 	},
+	Tips: []string{
+		`Example: --json '{"Name":"Alice"}'`,
+		"Agent hint: use the lark-base skill's record-upsert guide for usage and limits.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateRecordJSON(runtime)
 	},

shortcuts/base/view_create.go

@@ -21,6 +21,10 @@ var BaseViewCreate = common.Shortcut{
 		tableRefFlag(true),
 		{Name: "json", Desc: "view JSON object/array", Required: true},
 	},
+	Tips: []string{
+		`Example: --json '{"name":"Main","type":"grid"}'`,
+		"Agent hint: use the lark-base skill's view-create guide for usage and limits.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewCreate(runtime)
 	},

shortcuts/base/view_set_card.go

@@ -22,6 +22,10 @@ var BaseViewSetCard = common.Shortcut{
 		viewRefFlag(true),
 		{Name: "json", Desc: "card JSON object", Required: true},
 	},
+	Tips: []string{
+		`Example: --json '{"cover_field":"fldCover"}'`,
+		"Agent hint: use the lark-base skill's view-set-card guide for usage and limits.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONObject(runtime)
 	},

shortcuts/base/view_set_filter.go

@@ -22,6 +22,10 @@ var BaseViewSetFilter = common.Shortcut{
 		viewRefFlag(true),
 		{Name: "json", Desc: "filter JSON object", Required: true},
 	},
+	Tips: []string{
+		`Example: --json '{"logic":"and","conditions":[["fldStatus","==","Todo"]]}'`,
+		"Agent hint: use the lark-base skill's view-set-filter guide for usage and limits.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONObject(runtime)
 	},

shortcuts/base/view_set_group.go

@@ -20,7 +20,11 @@ var BaseViewSetGroup = common.Shortcut{
 		baseTokenFlag(true),
 		tableRefFlag(true),
 		viewRefFlag(true),
-		{Name: "json", Desc: "group JSON object/array", Required: true},
+		{Name: "json", Desc: "group JSON object", Required: true},
+	},
+	Tips: []string{
+		`Example: --json '{"group_config":[{"field":"fldStatus","desc":false}]}'`,
+		"Agent hint: use the lark-base skill's view-set-group guide for usage and limits.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONValue(runtime)

shortcuts/base/view_set_sort.go

@@ -22,6 +22,10 @@ var BaseViewSetSort = common.Shortcut{
 		viewRefFlag(true),
 		{Name: "json", Desc: "sort JSON object/array", Required: true},
 	},
+	Tips: []string{
+		`Example: --json '[{"field":"fldPriority","desc":true}]'`,
+		"Agent hint: use the lark-base skill's view-set-sort guide for usage and limits.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONValue(runtime)
 	},

shortcuts/base/view_set_timebar.go

@@ -22,6 +22,10 @@ var BaseViewSetTimebar = common.Shortcut{
 		viewRefFlag(true),
 		{Name: "json", Desc: "timebar JSON object", Required: true},
 	},
+	Tips: []string{
+		`Example: --json '{"start_time":"fldStart","end_time":"fldEnd","title":"fldTitle"}'`,
+		"Agent hint: use the lark-base skill's view-set-timebar guide for usage and limits.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateViewJSONObject(runtime)
 	},

skills/lark-base/references/lark-base-view-set-group.md

@@ -11,15 +11,17 @@ lark-cli base +view-set-group \
   --base-token app_xxx \
   --table-id tbl_xxx \
   --view-id viw_xxx \
-  --json [{"field":"fld_status","desc":false}]
+  --json '{"group_config":[{"field":"fldStatus","desc":false}]}'
 ```
 
 ## JSON 结构
 
 ```json
-[
-  { "field": "fld_status", "desc": false }
-]
+{
+  "group_config": [
+    { "field": "fldStatus", "desc": false }
+  ]
+}
 ```
 
 ## 参数
@@ -29,7 +31,7 @@ lark-cli base +view-set-group \
 | `--base-token <token>` | 是 | Base Token |
 | `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
 | `--view-id <id_or_name>` | 是 | 视图 ID 或视图名 |
-| `--json <body>` | 是 | JSON 对象或数组 |
+| `--json <body>` | 是 | JSON 对象 |
 
 ## API 入参详情
 
@@ -49,14 +51,12 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/views/:view_id/group
 - 每项：
   - `field`：字段 id 或字段名，长度 `1..100`
   - `desc`：可选，默认 `false`
-- `--json` 既可传对象 `{"group_config":[...]}`，也可直接传数组 `[...]`
-- 直接传数组时，CLI 会自动包装成 `group_config`
 
 
 ## JSON Schema（原文）
 
 ```json
-{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":100,"description":"Field id or name"},"desc":{"type":"boolean","default":false,"description":"define how to sort group headers"}},"required":["field"],"additionalProperties":false},"minItems":0,"maxItems":3,"$schema":"http://json-schema.org/draft-07/schema#"}
+{"type":"object","properties":{"group_config":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":100,"description":"Field id or name"},"desc":{"type":"boolean","default":false,"description":"define how to sort group headers"}},"required":["field"],"additionalProperties":false},"minItems":0,"maxItems":3}},"required":["group_config"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}
 
 ```