Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zgz2048 merged 3 commits into from
Mar 31, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
65cbdbd
docs(base): clarify field description usage in json
zgz2048 Mar 30, 2026
c476090
chore(base docs): clarify field description usage
zgz2048 Mar 30, 2026
ec3c6b2
docs(base): add description to field schema
zgz2048 Mar 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions skills/lark-base/references/lark-base-field-create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)"}'
```

## 参数
Expand All @@ -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 方法和路径：**
Expand All @@ -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`。
Expand All @@ -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`。
Expand All @@ -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，再创建。

## 参考

Expand Down
21 changes: 19 additions & 2 deletions skills/lark-base/references/lark-base-field-update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)"}'
```

## 参数
Expand All @@ -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 方法和路径：**
Expand All @@ -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`。
Expand All @@ -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`。
Expand All @@ -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` 时，先阅读对应指南再执行。

## 参考

Expand Down
34 changes: 26 additions & 8 deletions skills/lark-base/references/lark-base-shortcut-field-properties.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand All @@ -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" } },
Expand Down Expand Up @@ -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": [
{
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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" } },
Expand All @@ -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" } },
Expand All @@ -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" } },
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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" }
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand Down