diff --git a/skills/lark-base/references/lark-base-field-create.md b/skills/lark-base/references/lark-base-field-create.md index 75e6b0f9c..398b07324 100644 --- a/skills/lark-base/references/lark-base-field-create.md +++ b/skills/lark-base/references/lark-base-field-create.md @@ -24,6 +24,11 @@ lark-cli base +field-create \ --base-token app_xxx \ --table-id tbl_xxx \ --json '{"name":"状态","type":"select","multiple":false,"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Done","hue":"Green","lightness":"Light"}]}' + +lark-cli base +field-create \ + --base-token app_xxx \ + --table-id tbl_xxx \ + --json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}' ``` ## 参数 @@ -33,7 +38,6 @@ lark-cli base +field-create \ | `--base-token ` | 是 | Base Token | | `--table-id ` | 是 | 表 ID 或表名 | | `--json ` | 是 | 字段属性 JSON 对象 | - ## API 入参详情 **HTTP 方法和路径：** @@ -46,6 +50,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields - `--json` 必须是 **JSON 对象**，顶层直接传字段定义，不要再套一层。 - 顶层最少包含：`name`、`type`。 +- 如需字段说明，直接传 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。 - `type` 不同，必填子字段不同： - `select`：用 `multiple` + `options`（`options` 里只传 `name/hue/lightness`，不要传 `id`）。 - `link`：必须有 `link_table`，可选 `bidirectional`、`bidirectional_link_field_name`。 @@ -66,6 +71,17 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields } ``` +**字段说明示例** + +```json +{ + "name": "负责人", + "type": "user", + "multiple": false, + "description": "用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)" +} +``` + ## 返回重点 - 返回 `field` 和 `created: true`。 @@ -78,7 +94,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields ## 坑点 - ⚠️ 这是写入操作，执行前必须确认。 -- ⚠️ 当 `--json.type` 是 `formula` 或 `lookup` 时，先读对应 guide，再创建。 +- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先读对应 guide，再创建。 ## 参考 diff --git a/skills/lark-base/references/lark-base-field-update.md b/skills/lark-base/references/lark-base-field-update.md index f010738b8..b4c3d0f15 100644 --- a/skills/lark-base/references/lark-base-field-update.md +++ b/skills/lark-base/references/lark-base-field-update.md @@ -12,6 +12,12 @@ lark-cli base +field-update \ --table-id tbl_xxx \ --field-id fld_xxx \ --json '{"name":"状态","type":"select","multiple":false,"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Doing","hue":"Orange","lightness":"Light"},{"name":"Done","hue":"Green","lightness":"Light"}]}' + +lark-cli base +field-update \ + --base-token app_xxx \ + --table-id tbl_xxx \ + --field-id fld_xxx \ + --json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}' ``` ## 参数 @@ -22,7 +28,6 @@ lark-cli base +field-update \ | `--table-id ` | 是 | 表 ID 或表名 | | `--field-id ` | 是 | 字段 ID 或字段名 | | `--json ` | 是 | 字段属性 JSON 对象 | - ## API 入参详情 **HTTP 方法和路径：** @@ -35,6 +40,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id - `--json` 必须是 **JSON 对象**，顶层直接传字段定义。 - 更新语义是 `PUT`（全量字段配置更新），不要只传零散片段；至少显式包含 `name`、`type`，并补齐该类型所需关键配置。 +- 如需字段说明，直接传 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。 - `select` 更新时：`options` 仍按对象数组传，避免混入无效字段。 - `link` 更新限制： - 不能把非 `link` 字段改成 `link`，也不能把 `link` 改成非 `link`。 @@ -55,6 +61,17 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id } ``` +**字段说明示例** + +```json +{ + "name": "负责人", + "type": "user", + "multiple": false, + "description": "用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)" +} +``` + ## 返回重点 - 返回 `field` 和 `updated: true`。 @@ -69,7 +86,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id - ⚠️ 这是全量字段属性更新语义，不是 patch。 - ⚠️ 这是写入操作，执行前必须确认。 -- ⚠️ 当 `--json.type` 是 `formula` 或 `lookup` 时，先阅读对应指南再执行。 +- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先阅读对应指南再执行。 ## 参考 diff --git a/skills/lark-base/references/lark-base-shortcut-field-properties.md b/skills/lark-base/references/lark-base-shortcut-field-properties.md index 8b98ab014..09fbfde55 100644 --- a/skills/lark-base/references/lark-base-shortcut-field-properties.md +++ b/skills/lark-base/references/lark-base-shortcut-field-properties.md @@ -8,15 +8,24 @@ - `--json` 必须是 JSON 对象。 - 顶层统一使用：`type` + `name` + 类型特有字段。 +- 如需字段说明，直接传 `description`；支持纯文本，也支持 Markdown 链接。 - 不要使用旧结构：`field_name`、`property`、`ui_type`、数字枚举 `type`。 - `+field-update` 是 `PUT` 语义，建议先 `+field-get` 再全量提交目标字段配置。 - `type=formula` 或 `type=lookup` 创建时，必须先读对应 guide。 +```json +{ + "type": "text", + "name": "需求背景", + "description": "记录需求背景与已知约束；填写口径可参考[说明模板](https://example.com/spec)" +} +``` + ## 2. 各类型格式与示例 ### 2.1 text -**要求**：`name` 必填；`style.type` 可选，默认 `plain`。 +**要求**：`name` 必填；可选传 `description`；`style.type` 可选，默认 `plain`。 ```json { @@ -36,6 +45,7 @@ "properties": { "type": { "type": "string", "const": "text", "description": "Text field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, + "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "style": { "type": "object", "properties": { "type": { "type": "string", "enum": ["plain", "phone", "url", "email", "barcode"], "description": "Text style type" } }, @@ -101,6 +111,7 @@ "properties": { "type": { "type": "string", "const": "number", "description": "Number field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, + "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "style": { "anyOf": [ { @@ -197,6 +208,7 @@ "properties": { "type": { "type": "string", "const": "select", "description": "Select field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, + "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "multiple": { "type": "boolean", "default": false, "description": "Allow multiple" }, "options": { "type": "array", @@ -250,6 +262,7 @@ "properties": { "type": { "type": "string", "const": "datetime", "description": "Date time type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, + "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "style": { "type": "object", "properties": { "format": { "type": "string", "enum": ["yyyy/MM/dd", "yyyy/MM/dd HH:mm", "yyyy/MM/dd HH:mm Z", "yyyy-MM-dd", "yyyy-MM-dd HH:mm", "yyyy-MM-dd HH:mm Z", "MM-dd", "MM/dd/yyyy", "dd/MM/yyyy"], "default": "yyyy/MM/dd", "description": "Date format" } }, @@ -273,6 +286,7 @@ "properties": { "type": { "type": "string", "const": "created_at", "description": "Created time type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, + "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "style": { "type": "object", "properties": { "format": { "type": "string", "enum": ["yyyy/MM/dd", "yyyy/MM/dd HH:mm", "yyyy/MM/dd HH:mm Z", "yyyy-MM-dd", "yyyy-MM-dd HH:mm", "yyyy-MM-dd HH:mm Z", "MM-dd", "MM/dd/yyyy", "dd/MM/yyyy"], "default": "yyyy/MM/dd", "description": "Date format" } }, @@ -296,6 +310,7 @@ "properties": { "type": { "type": "string", "const": "updated_at", "description": "Modified time type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, + "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "style": { "type": "object", "properties": { "format": { "type": "string", "enum": ["yyyy/MM/dd", "yyyy/MM/dd HH:mm", "yyyy/MM/dd HH:mm Z", "yyyy-MM-dd", "yyyy-MM-dd HH:mm", "yyyy-MM-dd HH:mm Z", "MM-dd", "MM/dd/yyyy", "dd/MM/yyyy"], "default": "yyyy/MM/dd", "description": "Date format" } }, @@ -330,7 +345,7 @@ ```json { "type": "object", - "properties": { "type": { "type": "string", "const": "user", "description": "User field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "multiple": { "type": "boolean", "default": true, "description": "Allow multiple" } }, + "properties": { "type": { "type": "string", "const": "user", "description": "User field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "multiple": { "type": "boolean", "default": true, "description": "Allow multiple" } }, "required": ["type", "name"], "additionalProperties": false, "description": "User field", @@ -343,7 +358,7 @@ ```json { "type": "object", - "properties": { "type": { "type": "string", "const": "created_by", "description": "Created by type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } }, + "properties": { "type": { "type": "string", "const": "created_by", "description": "Created by type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } }, "required": ["type", "name"], "additionalProperties": false, "description": "Created by field", @@ -356,7 +371,7 @@ ```json { "type": "object", - "properties": { "type": { "type": "string", "const": "updated_by", "description": "Modified by type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } }, + "properties": { "type": { "type": "string", "const": "updated_by", "description": "Modified by type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } }, "required": ["type", "name"], "additionalProperties": false, "description": "Modified by field", @@ -386,6 +401,7 @@ "properties": { "type": { "type": "string", "const": "link", "description": "Link field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, + "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "link_table": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Linked table" }, "bidirectional": { "type": "boolean", "default": false, "description": "Bidirectional link" }, "bidirectional_link_field_name": { "$ref": "#/properties/name", "description": "Bidirectional link field name" } @@ -414,7 +430,7 @@ ```json { "type": "object", - "properties": { "type": { "type": "string", "const": "formula", "description": "Formula field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "expression": { "type": "string", "description": "Formula expression" } }, + "properties": { "type": { "type": "string", "const": "formula", "description": "Formula field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "expression": { "type": "string", "description": "Formula expression" } }, "required": ["type", "name", "expression"], "additionalProperties": false, "description": "Formula field", @@ -451,6 +467,7 @@ "properties": { "type": { "type": "string", "const": "lookup", "description": "Lookup field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, + "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "from": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Source data table" }, "select": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Field to aggregate from source table" }, "where": { @@ -545,6 +562,7 @@ "properties": { "type": { "type": "string", "const": "auto_number", "description": "Auto number type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, + "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "style": { "type": "object", "properties": { @@ -620,7 +638,7 @@ ```json { "type": "object", - "properties": { "type": { "type": "string", "const": "attachment", "description": "Attachment field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } }, + "properties": { "type": { "type": "string", "const": "attachment", "description": "Attachment field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } }, "required": ["type", "name"], "additionalProperties": false, "description": "Attachment field", @@ -633,7 +651,7 @@ ```json { "type": "object", - "properties": { "type": { "type": "string", "const": "location", "description": "Location field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } }, + "properties": { "type": { "type": "string", "const": "location", "description": "Location field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } }, "required": ["type", "name"], "additionalProperties": false, "description": "Location field", @@ -646,7 +664,7 @@ ```json { "type": "object", - "properties": { "type": { "type": "string", "const": "checkbox", "description": "Checkbox field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } }, + "properties": { "type": { "type": "string", "const": "checkbox", "description": "Checkbox field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } }, "required": ["type", "name"], "additionalProperties": false, "description": "Checkbox field",