diff --git a/skills/lark-base/references/lark-base-cell-value.md b/skills/lark-base/references/lark-base-cell-value.md index bb9cd6631d..6c8a2e383a 100644 --- a/skills/lark-base/references/lark-base-cell-value.md +++ b/skills/lark-base/references/lark-base-cell-value.md @@ -16,15 +16,20 @@ ## 2. 各类型 CellValue -### 2.1 text / phone / url +### 2.1 text -用字符串。URL 字段也传 URL 字符串；普通文本里可以保留 Markdown 风格链接文本，平台会按字段类型处理。 +text 字段的 `style.type` 影响单元格检查逻辑： +`type=plain` 传 Markdown 格式的字符串。 +`type=url` 传一个带 title 的 Markdown 格式链接，或单独传一个链接。 +`type=phone` 传合法电话号码。 +`type=email` 传合法邮箱字符串。 ```json { - "标题": "Hello", + "标题": "Hello, [lark-cli](https://github.com/larksuite/cli)", + "官网": "[官网](https://example.com)", "联系电话": "1380000000000", - "官网": "https://example.com" + "邮箱": "owner@example.com" } ``` diff --git a/skills/lark-base/references/lark-base-field-create.md b/skills/lark-base/references/lark-base-field-create.md index 829a03eec0..d935a61b9b 100644 --- a/skills/lark-base/references/lark-base-field-create.md +++ b/skills/lark-base/references/lark-base-field-create.md @@ -23,12 +23,12 @@ lark-cli base +field-create \ lark-cli base +field-create \ --base-token \ --table-id \ - --json '{"name":"状态","type":"select","multiple":false,"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Done","hue":"Green","lightness":"Light"}]}' + --json '{"name":"状态","type":"select","multiple":false,"default_value":["Todo"],"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Done","hue":"Green","lightness":"Light"}]}' lark-cli base +field-create \ --base-token \ --table-id \ - --json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}' + --json '{"name":"负责人","type":"user","multiple":false,"default_value":[{"$slot":"current_user"}],"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}' ``` ## 参数 @@ -51,6 +51,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields - `--json` 必须是 **JSON 对象**，顶层直接传字段定义，不要再套一层。 - 顶层最少包含：`name`、`type`。 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。 +- 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；`datetime` / `user` 的动态填充用 `$slot`。完整规则见 [lark-base-field-json.md](lark-base-field-json.md)。 - `type` 不同，必填子字段不同： - `select`：`multiple` 控制是否多选，`options` 定义静态选项，`dynamic_options_source` 定义动态选项来源。静态与动态选项配置二选一，不能同时传。 - `link`：必须有 `link_table`，可选 `bidirectional`、`bidirectional_link_field_name`。 @@ -64,6 +65,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields "name": "状态", "type": "select", "multiple": false, + "default_value": ["Todo"], "options": [ { "name": "Todo", "hue": "Blue", "lightness": "Lighter" }, { "name": "Done", "hue": "Green", "lightness": "Light" } diff --git a/skills/lark-base/references/lark-base-field-json.md b/skills/lark-base/references/lark-base-field-json.md index 26bf023f79..9f881f9236 100644 --- a/skills/lark-base/references/lark-base-field-json.md +++ b/skills/lark-base/references/lark-base-field-json.md @@ -9,6 +9,7 @@ - `--json` 必须是 JSON 对象。 - 顶层统一使用：`type` + `name` + 类型特有字段。 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。 +- 字段默认值使用 `default_value`，直接传对应 CellValue；支持范围只有 `text`、`number`、静态 `select`、`datetime`、`user`。清空默认值传 `null`；省略表示创建时不设置、更新时不修改。 - 不要使用旧结构：`field_name`、`property`、`ui_type`、数字枚举 `type`。 - `+field-update` 使用同样的字段 JSON 结构，但语义是 `PUT`；这是高风险写入操作，建议先 `+field-get` 再按目标状态全量提交，并带 `--yes`。 - `type=formula` 或 `type=lookup` 创建/更新前，必须先读对应 guide。 @@ -27,12 +28,12 @@ | 类型 | 最小必填字段 | 常见补充字段 | |------|--------------|-------------| -| `text` | `type` `name` | `style.type` | -| `number` | `type` `name` | `style` | -| `select` | `type` `name` | `multiple` + `options`，或 `multiple` + `dynamic_options_source` | -| `datetime` | `type` `name` | `style.format` | +| `text` | `type` `name` | `style.type` `default_value` | +| `number` | `type` `name` | `style` `default_value` | +| `select` | `type` `name` | `multiple` + `options` + 静态 `default_value`，或 `multiple` + `dynamic_options_source` | +| `datetime` | `type` `name` | `style.format` `default_value` | | `created_at` / `updated_at` | `type` `name` | `style.format` | -| `user` / `group_chat` | `type` `name` | `multiple` | +| `user` / `group_chat` | `type` `name` | `multiple`；仅 `user` 支持 `default_value` | | `created_by` / `updated_by` | `type` `name` | 无 | | `link` | `type` `name` `link_table` | `bidirectional` `bidirectional_link_field_name` | | `formula` | `type` `name` `expression` | 无 | @@ -47,31 +48,37 @@ ### 3.1 text 文本字段；电话、超链接、邮箱、条码也都属于 `text`，通过 `style.type` 区分。 +支持 `default_value`：静态 Markdown 文本字符串；`phone` style 必须是合法电话号码；`url` style 传一个 Markdown 链接或裸 URL；`email` style 必须是合法邮箱字符串，不要传 Markdown 链接或 `mailto:`。 最小写法（默认 `style.type` 为 `plain`）： ```json { "type": "text", - "name": "标题" + "name": "标题", + "default_value": "默认标题" } ``` 常用写法： +默认值可以是 Markdown 文本 ```json { "type": "text", "name": "标题", - "description": "主标题字段" + "description": "主标题字段", + "default_value": "未命名" } ``` +`style.type=phone` 时默认值是合法电话号码字符串。 ```json { "type": "text", "name": "联系电话", - "style": { "type": "phone" } + "style": { "type": "phone" }, + "default_value": "+8613800000000" } ``` @@ -79,7 +86,17 @@ { "type": "text", "name": "官网", - "style": { "type": "url" } + "style": { "type": "url" }, + "default_value": "[官网](https://example.com)" +} +``` + +```json +{ + "type": "text", + "name": "邮箱", + "style": { "type": "email" }, + "default_value": "owner@example.com" } ``` @@ -88,13 +105,15 @@ ### 3.2 number 数字字段；货币、进度、评分都属于 `number`，通过 `style.type` 区分。 +支持 `default_value`：静态 JSON number；所有 number style 都按这个规则写。 最小写法（默认 `style.type` 为 `plain`）： ```json { "type": "number", - "name": "工时" + "name": "工时", + "default_value": 8 } ``` @@ -118,7 +137,8 @@ "precision": 2, "percentage": false, "thousands_separator": true - } + }, + "default_value": 8 } ``` @@ -151,7 +171,8 @@ { "type": "number", "name": "完成度", - "style": { "type": "progress", "percentage": true, "color": "Blue" } + "style": { "type": "progress", "percentage": true, "color": "Blue" }, + "default_value": 0.65 } ``` @@ -180,6 +201,7 @@ #### 静态选项 支持字段：`multiple`、`options` +支持 `default_value`：静态选项名数组；即使 `multiple=false` 也写数组，如 `["Todo"]`。 默认值 / 约束： - `multiple` 默认 `false` @@ -189,12 +211,14 @@ - `options[].hue` 可用：`Red`、`Orange`、`Yellow`、`Lime`、`Green`、`Turquoise`、`Wathet`、`Blue`、`Carmine`、`Purple`、`Gray` 缺省值为 `Blue` - `options[].lightness` 可用：`Lighter`、`Light`、`Standard`、`Dark`、`Darker` 缺省值为 `Lighter` - 选项里没有 `id`，只有 `name`。 +- 支持 `default_value` 配置：填选项名数组。 ```json { "type": "select", "name": "状态", "multiple": false, + "default_value": ["Todo"], "options": [ { "name": "Todo", "hue": "Blue", "lightness": "Lighter" }, { "name": "Done", "hue": "Green", "lightness": "Light" } @@ -205,6 +229,7 @@ #### 动态选项 支持字段：`multiple`、`dynamic_options_source` +动态选项不支持 `default_value`。 默认值 / 约束： - `multiple` 默认 `false` @@ -213,6 +238,7 @@ - `dynamic_options_source.field_id` 填来源字段 id 或字段名 - `dynamic_options_source` 仅创建支持；更新已有字段时不要传 - 引用选项条件 / 级联筛选条件：这个功能在 Base 前端支持，属于 UI-only 属性，OpenAPI 里不支持，CLI 不能读取、创建或更新；不要根据接口返回缺失判断未配置 +- 动态选项不支持配置 `default_value`。 ```json { @@ -229,13 +255,15 @@ ### 3.4 datetime 手动填写的日期/时间字段。系统时间用 `created_at` / `updated_at`。 +支持 `default_value`：静态时间字符串，或 `{ "$slot": "record_created_time" }`。`datetime + record_created_time` 是自动填充可编辑单元格；`created_at` 是只读创建时间元信息。 最小写法： ```json { "type": "datetime", - "name": "截止时间" + "name": "截止时间", + "default_value": "2026-03-24 10:00:00" } ``` @@ -251,7 +279,8 @@ { "type": "datetime", "name": "截止时间", - "style": { "format": "yyyy-MM-dd HH:mm" } + "style": { "format": "yyyy-MM-dd HH:mm" }, + "default_value": { "$slot": "record_created_time" } } ``` @@ -276,12 +305,19 @@ ### 3.6 user / group_chat 人员字段和群字段都支持 `multiple`。 +`user` 支持 `default_value`：人员 CellValue 数组，元素可用 `{ "id": "ou_xxx" }` 或 `{ "$slot": "current_user" }`；不要猜用户 ID。`group_chat` 不支持默认值。 默认值 / 约束： - `multiple` 默认 `true` +- `user` 字段支持 `default_value` 配置，`group_chat` 字段不支持 `default_value` 配置。 ```json -{ "type": "user", "name": "负责人", "multiple": true } +{ + "type": "user", + "name": "负责人", + "multiple": true, + "default_value": [{ "$slot": "current_user" }, { "id": "ou_xxx" }] +} ``` ```json @@ -488,3 +524,4 @@ Object（对象字段）、Button（按钮字段）、Stage（流程字段）暂 - `number` 的精度、货币、进度、评分配置都放在 `style` 下，不要写顶层 `precision`。 - `datetime` 是手动日期字段；系统时间请改用 `created_at` / `updated_at`。 - `formula` / `lookup` 没读 guide 前不要直接写。 +- 只有 `text`、`number`、静态 `select`、`datetime`、`user` 支持 `default_value`；清空统一传 `"default_value": null`。其他字段类型不要配置默认值。 diff --git a/skills/lark-base/references/lark-base-field-update.md b/skills/lark-base/references/lark-base-field-update.md index 3cd35cdf22..a8a1f22057 100644 --- a/skills/lark-base/references/lark-base-field-update.md +++ b/skills/lark-base/references/lark-base-field-update.md @@ -11,14 +11,14 @@ lark-cli base +field-update \ --base-token \ --table-id \ --field-id \ - --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"}]}' \ + --json '{"name":"状态","type":"select","multiple":false,"default_value":["Doing"],"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Doing","hue":"Orange","lightness":"Light"},{"name":"Done","hue":"Green","lightness":"Light"}]}' \ --yes lark-cli base +field-update \ --base-token \ --table-id \ --field-id \ - --json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人"}' \ + --json '{"name":"负责人","type":"user","multiple":false,"default_value":null,"description":"用于标记记录的直接负责人"}' \ --yes ``` @@ -47,6 +47,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id - `--json` 必须是 **JSON 对象**，顶层直接传字段定义。 - 更新语义是 `PUT`（全量字段配置更新），不要只传零散片段；至少显式包含 `name`、`type`，并补齐该类型所需关键配置。 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。 +- 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；传 `null` 清空，省略表示不修改现有默认值。完整规则见 [lark-base-field-json.md](lark-base-field-json.md)。 - `select` 更新时：`options` 仍按对象数组传，避免混入无效字段。 - `link` 更新限制： - 不能把非 `link` 字段改成 `link`，也不能把 `link` 改成非 `link`。 @@ -59,6 +60,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id "name": "状态", "type": "select", "multiple": false, + "default_value": ["Doing"], "options": [ { "name": "Todo", "hue": "Blue", "lightness": "Lighter" }, { "name": "Doing", "hue": "Orange", "lightness": "Light" },