docs(base): clarify field description usage in json (#90)

* docs(base): clarify field description usage in json * chore(base docs): clarify field description usage * docs(base): add description to field schema
2026-07-07 00:55:53 +08:00 · 2026-03-31 16:46:40 +08:00
parent 634adfc745
commit c8341bbd7c
3 changed files with 63 additions and 12 deletions
--- 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 <token>` | 是 | Base Token |
 | `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
 | `--json <body>` | 是 | 字段属性 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，再创建。

 ## 参考

--- 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_or_name>` | 是 | 表 ID 或表名 |
 | `--field-id <id_or_name>` | 是 | 字段 ID 或字段名 |
 | `--json <body>` | 是 | 字段属性 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` 时，先阅读对应指南再执行。

 ## 参考

--- 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",