From e393959e9442db50eb2b22281f8df5310bc51df7 Mon Sep 17 00:00:00 2001 From: kongenpei Date: Thu, 9 Apr 2026 19:56:18 +0800 Subject: [PATCH 1/4] fix(base): improve --json help examples and group guide --- shortcuts/base/field_create.go | 2 +- shortcuts/base/field_update.go | 2 +- shortcuts/base/record_upsert.go | 2 +- shortcuts/base/view_create.go | 2 +- shortcuts/base/view_set_card.go | 2 +- shortcuts/base/view_set_filter.go | 2 +- shortcuts/base/view_set_group.go | 2 +- shortcuts/base/view_set_sort.go | 2 +- shortcuts/base/view_set_timebar.go | 2 +- .../references/lark-base-view-set-group.md | 14 +++++++------- 10 files changed, 16 insertions(+), 16 deletions(-) diff --git a/shortcuts/base/field_create.go b/shortcuts/base/field_create.go index 715b4d7d7..33469b99a 100644 --- a/shortcuts/base/field_create.go +++ b/shortcuts/base/field_create.go @@ -19,7 +19,7 @@ var BaseFieldCreate = common.Shortcut{ Flags: []common.Flag{ baseTokenFlag(true), tableRefFlag(true), - {Name: "json", Desc: "field property JSON object", Required: true}, + {Name: "json", Desc: `field property JSON object, e.g. {"name":"Status","type":"text"}; read skills/lark-base/references/lark-base-field-create.md`, 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}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { diff --git a/shortcuts/base/field_update.go b/shortcuts/base/field_update.go index fd8d755d7..1134dbb82 100644 --- a/shortcuts/base/field_update.go +++ b/shortcuts/base/field_update.go @@ -20,7 +20,7 @@ var BaseFieldUpdate = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), fieldRefFlag(true), - {Name: "json", Desc: "field property JSON object", Required: true}, + {Name: "json", Desc: `field property JSON object, e.g. {"name":"Status","type":"text"}; read skills/lark-base/references/lark-base-field-update.md`, Required: true}, {Name: "i-have-read-guide", Type: "bool", Desc: "acknowledge reading formula/lookup guide before creating or updating those field types", Hidden: true}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { diff --git a/shortcuts/base/record_upsert.go b/shortcuts/base/record_upsert.go index 0ff68309e..0d56da885 100644 --- a/shortcuts/base/record_upsert.go +++ b/shortcuts/base/record_upsert.go @@ -20,7 +20,7 @@ var BaseRecordUpsert = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), recordRefFlag(false), - {Name: "json", Desc: "record JSON object", Required: true}, + {Name: "json", Desc: `record JSON object, e.g. {"Name":"Alice"}; read skills/lark-base/references/lark-base-record-upsert.md`, Required: true}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { return validateRecordJSON(runtime) diff --git a/shortcuts/base/view_create.go b/shortcuts/base/view_create.go index 3722e41d1..beaa7e59f 100644 --- a/shortcuts/base/view_create.go +++ b/shortcuts/base/view_create.go @@ -19,7 +19,7 @@ var BaseViewCreate = common.Shortcut{ Flags: []common.Flag{ baseTokenFlag(true), tableRefFlag(true), - {Name: "json", Desc: "view JSON object/array", Required: true}, + {Name: "json", Desc: `view JSON object/array, e.g. {"name":"Main","type":"grid"}; read skills/lark-base/references/lark-base-view-create.md`, Required: true}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { return validateViewCreate(runtime) diff --git a/shortcuts/base/view_set_card.go b/shortcuts/base/view_set_card.go index 416c674bd..ffcdeb788 100644 --- a/shortcuts/base/view_set_card.go +++ b/shortcuts/base/view_set_card.go @@ -20,7 +20,7 @@ var BaseViewSetCard = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), viewRefFlag(true), - {Name: "json", Desc: "card JSON object", Required: true}, + {Name: "json", Desc: `card JSON object, e.g. {"cover_field":"fldCover"}; read skills/lark-base/references/lark-base-view-set-card.md`, Required: true}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { return validateViewJSONObject(runtime) diff --git a/shortcuts/base/view_set_filter.go b/shortcuts/base/view_set_filter.go index ff065fb56..9cc23d086 100644 --- a/shortcuts/base/view_set_filter.go +++ b/shortcuts/base/view_set_filter.go @@ -20,7 +20,7 @@ var BaseViewSetFilter = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), viewRefFlag(true), - {Name: "json", Desc: "filter JSON object", Required: true}, + {Name: "json", Desc: `filter JSON object, e.g. {"logic":"and","conditions":[["fldStatus","==","Todo"]]}; read skills/lark-base/references/lark-base-view-set-filter.md`, Required: true}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { return validateViewJSONObject(runtime) diff --git a/shortcuts/base/view_set_group.go b/shortcuts/base/view_set_group.go index 9a9f66189..90a08b457 100644 --- a/shortcuts/base/view_set_group.go +++ b/shortcuts/base/view_set_group.go @@ -20,7 +20,7 @@ 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/array, e.g. {"group_config":[{"field":"fldStatus","desc":false}]}; read skills/lark-base/references/lark-base-view-set-group.md`, Required: true}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { return validateViewJSONValue(runtime) diff --git a/shortcuts/base/view_set_sort.go b/shortcuts/base/view_set_sort.go index 874473e64..eef26429f 100644 --- a/shortcuts/base/view_set_sort.go +++ b/shortcuts/base/view_set_sort.go @@ -20,7 +20,7 @@ var BaseViewSetSort = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), viewRefFlag(true), - {Name: "json", Desc: "sort JSON object/array", Required: true}, + {Name: "json", Desc: `sort JSON object/array, e.g. [{"field":"fldPriority","desc":true}]; read skills/lark-base/references/lark-base-view-set-sort.md`, Required: true}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { return validateViewJSONValue(runtime) diff --git a/shortcuts/base/view_set_timebar.go b/shortcuts/base/view_set_timebar.go index d9ba352fe..91fb54ad4 100644 --- a/shortcuts/base/view_set_timebar.go +++ b/shortcuts/base/view_set_timebar.go @@ -20,7 +20,7 @@ var BaseViewSetTimebar = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), viewRefFlag(true), - {Name: "json", Desc: "timebar JSON object", Required: true}, + {Name: "json", Desc: `timebar JSON object, e.g. {"start_time":"fldStart","end_time":"fldEnd","title":"fldTitle"}; read skills/lark-base/references/lark-base-view-set-timebar.md`, Required: true}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { return validateViewJSONObject(runtime) diff --git a/skills/lark-base/references/lark-base-view-set-group.md b/skills/lark-base/references/lark-base-view-set-group.md index 835f6b70d..7cc219a92 100644 --- a/skills/lark-base/references/lark-base-view-set-group.md +++ b/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 ` | 是 | Base Token | | `--table-id ` | 是 | 表 ID 或表名 | | `--view-id ` | 是 | 视图 ID 或视图名 | -| `--json ` | 是 | JSON 对象或数组 | +| `--json ` | 是 | JSON 对象 | ## API 入参详情 @@ -49,8 +51,6 @@ 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（原文） From 72becdf869066f442ed7c5db84f54738c583f62c Mon Sep 17 00:00:00 2001 From: kongenpei Date: Thu, 9 Apr 2026 20:56:13 +0800 Subject: [PATCH 2/4] fix(base): unify --json help tips format --- shortcuts/base/field_create.go | 6 +++++- shortcuts/base/field_update.go | 6 +++++- shortcuts/base/record_upsert.go | 6 +++++- shortcuts/base/view_create.go | 6 +++++- shortcuts/base/view_set_card.go | 6 +++++- shortcuts/base/view_set_filter.go | 6 +++++- shortcuts/base/view_set_group.go | 6 +++++- shortcuts/base/view_set_sort.go | 6 +++++- shortcuts/base/view_set_timebar.go | 6 +++++- 9 files changed, 45 insertions(+), 9 deletions(-) diff --git a/shortcuts/base/field_create.go b/shortcuts/base/field_create.go index 33469b99a..f2f342c1c 100644 --- a/shortcuts/base/field_create.go +++ b/shortcuts/base/field_create.go @@ -19,9 +19,13 @@ var BaseFieldCreate = common.Shortcut{ Flags: []common.Flag{ baseTokenFlag(true), tableRefFlag(true), - {Name: "json", Desc: `field property JSON object, e.g. {"name":"Status","type":"text"}; read skills/lark-base/references/lark-base-field-create.md`, Required: true}, + {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) }, diff --git a/shortcuts/base/field_update.go b/shortcuts/base/field_update.go index 1134dbb82..05e9e873f 100644 --- a/shortcuts/base/field_update.go +++ b/shortcuts/base/field_update.go @@ -20,9 +20,13 @@ var BaseFieldUpdate = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), fieldRefFlag(true), - {Name: "json", Desc: `field property JSON object, e.g. {"name":"Status","type":"text"}; read skills/lark-base/references/lark-base-field-update.md`, Required: true}, + {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) }, diff --git a/shortcuts/base/record_upsert.go b/shortcuts/base/record_upsert.go index 0d56da885..13045a4d6 100644 --- a/shortcuts/base/record_upsert.go +++ b/shortcuts/base/record_upsert.go @@ -20,7 +20,11 @@ var BaseRecordUpsert = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), recordRefFlag(false), - {Name: "json", Desc: `record JSON object, e.g. {"Name":"Alice"}; read skills/lark-base/references/lark-base-record-upsert.md`, Required: true}, + {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) diff --git a/shortcuts/base/view_create.go b/shortcuts/base/view_create.go index beaa7e59f..6e38b0453 100644 --- a/shortcuts/base/view_create.go +++ b/shortcuts/base/view_create.go @@ -19,7 +19,11 @@ var BaseViewCreate = common.Shortcut{ Flags: []common.Flag{ baseTokenFlag(true), tableRefFlag(true), - {Name: "json", Desc: `view JSON object/array, e.g. {"name":"Main","type":"grid"}; read skills/lark-base/references/lark-base-view-create.md`, Required: 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) diff --git a/shortcuts/base/view_set_card.go b/shortcuts/base/view_set_card.go index ffcdeb788..410a9b46e 100644 --- a/shortcuts/base/view_set_card.go +++ b/shortcuts/base/view_set_card.go @@ -20,7 +20,11 @@ var BaseViewSetCard = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), viewRefFlag(true), - {Name: "json", Desc: `card JSON object, e.g. {"cover_field":"fldCover"}; read skills/lark-base/references/lark-base-view-set-card.md`, Required: 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) diff --git a/shortcuts/base/view_set_filter.go b/shortcuts/base/view_set_filter.go index 9cc23d086..721129e06 100644 --- a/shortcuts/base/view_set_filter.go +++ b/shortcuts/base/view_set_filter.go @@ -20,7 +20,11 @@ var BaseViewSetFilter = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), viewRefFlag(true), - {Name: "json", Desc: `filter JSON object, e.g. {"logic":"and","conditions":[["fldStatus","==","Todo"]]}; read skills/lark-base/references/lark-base-view-set-filter.md`, Required: 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) diff --git a/shortcuts/base/view_set_group.go b/shortcuts/base/view_set_group.go index 90a08b457..dd42fcdf1 100644 --- a/shortcuts/base/view_set_group.go +++ b/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, e.g. {"group_config":[{"field":"fldStatus","desc":false}]}; read skills/lark-base/references/lark-base-view-set-group.md`, Required: true}, + {Name: "json", Desc: "group JSON object/array", 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) diff --git a/shortcuts/base/view_set_sort.go b/shortcuts/base/view_set_sort.go index eef26429f..e5591c790 100644 --- a/shortcuts/base/view_set_sort.go +++ b/shortcuts/base/view_set_sort.go @@ -20,7 +20,11 @@ var BaseViewSetSort = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), viewRefFlag(true), - {Name: "json", Desc: `sort JSON object/array, e.g. [{"field":"fldPriority","desc":true}]; read skills/lark-base/references/lark-base-view-set-sort.md`, Required: 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) diff --git a/shortcuts/base/view_set_timebar.go b/shortcuts/base/view_set_timebar.go index 91fb54ad4..88f23a936 100644 --- a/shortcuts/base/view_set_timebar.go +++ b/shortcuts/base/view_set_timebar.go @@ -20,7 +20,11 @@ var BaseViewSetTimebar = common.Shortcut{ baseTokenFlag(true), tableRefFlag(true), viewRefFlag(true), - {Name: "json", Desc: `timebar JSON object, e.g. {"start_time":"fldStart","end_time":"fldEnd","title":"fldTitle"}; read skills/lark-base/references/lark-base-view-set-timebar.md`, Required: 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) From f93a665551b9f8296b75e531804f5d7c3ad68a3a Mon Sep 17 00:00:00 2001 From: kongenpei Date: Thu, 9 Apr 2026 21:01:47 +0800 Subject: [PATCH 3/4] docs(base): fix view-set-group schema with group_config --- skills/lark-base/references/lark-base-view-set-group.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/lark-base/references/lark-base-view-set-group.md b/skills/lark-base/references/lark-base-view-set-group.md index 7cc219a92..4689a8aea 100644 --- a/skills/lark-base/references/lark-base-view-set-group.md +++ b/skills/lark-base/references/lark-base-view-set-group.md @@ -56,7 +56,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/views/:view_id/group ## 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#"} ``` From 1d40188b9ca928d8973f60bff7af67aa13185e09 Mon Sep 17 00:00:00 2001 From: kongenpei Date: Thu, 9 Apr 2026 21:02:55 +0800 Subject: [PATCH 4/4] fix(base): remove array wording from view-set-group json help --- shortcuts/base/view_set_group.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shortcuts/base/view_set_group.go b/shortcuts/base/view_set_group.go index dd42fcdf1..3599398ef 100644 --- a/shortcuts/base/view_set_group.go +++ b/shortcuts/base/view_set_group.go @@ -20,7 +20,7 @@ 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}]}'`,