Files

Ap_Tx 6a295f9a7a feat：移除了弹窗，服务器添加sls

2026-09-08 22:39:45 +08:00

15 KiB

Raw Permalink Blame History

Base field JSON SSOT

适用命令：lark-cli base +field-create、lark-cli base +field-update

本文档定义 +field-create / +field-update 写字段时 --json 的推荐格式，是字段类型与字段 JSON 结构的 source of truth。目标不是复刻完整 schema，而是让 agent 稳定产出正确 payload。

1. 顶层规则（必须遵守）

--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。

推荐示例：

{
  "type": "text",
  "name": "需求背景",
  "description": "记录需求背景与已知约束"
}

2. 字段速查

类型	最小必填字段	常见补充字段
`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` 支持 `default_value`
`created_by` / `updated_by`	`type` `name`	无
`link`	`type` `name` `link_table`	`bidirectional` `bidirectional_link_field_name`
`formula`	`type` `name` `expression`	无
`lookup`	`type` `name` `from` `select` `where`	`aggregate`
`auto_number`	`type` `name`	`style.rules`
`attachment` / `location` / `checkbox`	`type` `name`	无

所有类型都可额外传 description；上表的“常见补充字段”只列类型特有配置。

3. 各类型写法

3.1 text

文本字段；电话、超链接、邮箱、条码也都属于 text，通过 style.type 区分。支持 default_value：静态 Markdown 文本字符串；phone style 必须是合法电话号码；url style 传一个 Markdown 链接或裸 URL；email style 必须是合法邮箱字符串，不要传 Markdown 链接或 mailto:。

最小写法（默认 style.type 为 plain）：

{
  "type": "text",
  "name": "标题",
  "default_value": "默认标题"
}

常用写法：

默认值可以是 Markdown 文本

{
  "type": "text",
  "name": "标题",
  "description": "主标题字段",
  "default_value": "未命名"
}

style.type=phone 时默认值是合法电话号码字符串。

{
  "type": "text",
  "name": "联系电话",
  "style": { "type": "phone" },
  "default_value": "+8613800000000"
}

{
  "type": "text",
  "name": "官网",
  "style": { "type": "url" },
  "default_value": "[官网](https://example.com)"
}

{
  "type": "text",
  "name": "邮箱",
  "style": { "type": "email" },
  "default_value": "owner@example.com"
}

常用 style.type：plain（默认）、phone、url、email、barcode。

3.2 number

数字字段；货币、进度、评分都属于 number，通过 style.type 区分。支持 default_value：静态 JSON number；所有 number style 都按这个规则写。

最小写法（默认 style.type 为 plain）：

{
  "type": "number",
  "name": "工时",
  "default_value": 8
}

style 是按 type 区分的对象；不同 style.type 的内部字段不一样，不要混传。

`plain`

支持字段：precision、percentage、thousands_separator

默认值 / 约束：

precision 取值 0..4，默认 2
percentage 默认 false
thousands_separator 默认 false

{
  "type": "number",
  "name": "工时",
  "style": {
    "type": "plain",
    "precision": 2,
    "percentage": false,
    "thousands_separator": true
  },
  "default_value": 8
}

`currency`

支持字段：precision、currency_code

默认值 / 约束：

precision 取值 0..4，默认 2
currency_code 必填，如 CNY、USD、EUR

{
  "type": "number",
  "name": "预算",
  "style": { "type": "currency", "precision": 2, "currency_code": "CNY" }
}

`progress`

支持字段：percentage、color

默认值 / 约束：

percentage 默认 true
color 必填
color 可用：Blue、Purple、DarkGreen、Green、Cyan、Orange、Red、Gray、WhiteToBlueGradient、WhiteToPurpleGradient、WhiteToOrangeGradient、GreenToRedGradient、RedToGreenGradient、BlueToPinkGradient、PinkToBlueGradient、SpectralGradient

{
  "type": "number",
  "name": "完成度",
  "style": { "type": "progress", "percentage": true, "color": "Blue" },
  "default_value": 0.65
}

`rating`

支持字段：icon、min、max

默认值 / 已知平台范围：

icon 默认 star
icon 可用：star、heart、thumbsup、fire、smile、lightning、flower、number
min 取值 0..1，默认 1
max 默认 5；常见或已文档化的范围为 1..10，但 CLI 不强制上限为 10。如果用户明确需要更大评分范围，优先确认平台能力或用 +field-create/update --dry-run 检查请求形状；平台拒绝后再建议改用普通数字或进度字段。

{
  "type": "number",
  "name": "评分",
  "style": { "type": "rating", "icon": "star", "min": 1, "max": 5 }
}

3.3 select

单选和多选都使用 select；用 multiple 区分。multiple 默认 false。静态选项用 options，动态选项用 dynamic_options_source；两者不要同时传。

静态选项

支持字段：multiple、options 支持 default_value：静态选项名数组；即使 multiple=false 也写数组，如 ["Todo"]。

默认值 / 约束：

multiple 默认 false
options 最多 10000 项
options[] 结构是 {name, hue?, lightness?}
options[].name 必填
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 配置：填选项名数组。

{
  "type": "select",
  "name": "状态",
  "multiple": false,
  "default_value": ["Todo"],
  "options": [
    { "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
    { "name": "Done", "hue": "Green", "lightness": "Light" }
  ]
}

动态选项

支持字段：multiple、dynamic_options_source 动态选项不支持 default_value。

默认值 / 约束：

multiple 默认 false
dynamic_options_source 结构是 {table_id, field_id}
dynamic_options_source.table_id 填来源表 id 或表名
dynamic_options_source.field_id 填来源字段 id 或字段名
dynamic_options_source 仅创建支持；更新已有字段时不要传
引用选项条件 / 级联筛选条件：这个功能在 Base 前端支持，属于 UI-only 属性，OpenAPI 里不支持，CLI 不能读取、创建或更新；不要根据接口返回缺失判断未配置
动态选项不支持配置 default_value。

{
  "type": "select",
  "name": "动态状态",
  "multiple": false,
  "dynamic_options_source": {
    "table_id": "选项表",
    "field_id": "候选状态"
  }
}

3.4 datetime

手动填写的日期/时间字段。系统时间用 created_at / updated_at。支持 default_value：静态时间字符串，或 { "$slot": "record_created_time" }。datetime + record_created_time 是自动填充可编辑单元格；created_at 是只读创建时间元信息。

最小写法：

{
  "type": "datetime",
  "name": "截止时间",
  "default_value": "2026-03-24 10:00:00"
}

支持字段：style.format

默认值 / 约束：

style.format 默认 yyyy/MM/dd 可用格式：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
style.format 只控制前端显示格式；当前可配置格式最多显示到分钟，底层时间值仍可保留秒级精度。

常用写法：

{
  "type": "datetime",
  "name": "截止时间",
  "style": { "format": "yyyy-MM-dd HH:mm" },
  "default_value": { "$slot": "record_created_time" }
}

3.5 created_at / updated_at

系统创建时间 / 系统更新时间字段；可配显示格式，但记录写入时应视为只读。

支持字段：style.format

默认值 / 约束：

style.format 默认 yyyy/MM/dd
可用格式：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

{ "type": "created_at", "name": "创建时间" }

{ "type": "updated_at", "name": "更新时间", "style": { "format": "yyyy/MM/dd HH:mm" } }

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 配置。

{
  "type": "user",
  "name": "负责人",
  "multiple": true,
  "default_value": [{ "$slot": "current_user" }, { "id": "ou_xxx" }]
}

{ "type": "group_chat", "name": "负责群", "multiple": true }

3.7 created_by / updated_by

系统创建人 / 系统修改人字段；记录写入时应视为只读。

{ "type": "created_by", "name": "创建人" }

{ "type": "updated_by", "name": "更新人" }

3.8 link

关联字段；link_table 必填。

支持字段：link_table、bidirectional、bidirectional_link_field_name

默认值 / 约束：

link_table 必填
link 字段的单元格表示“当前记录关联到的对侧表记录集合”
bidirectional 默认 false
bidirectional=true 时，会在被关联表自动创建一个反向关联字段。任一侧记录的关联关系发生变更时，另一侧对应记录会自动同步更新
bidirectional_link_field_name 仅在 bidirectional=true 时使用
关联字段筛选：这个功能在 Base 前端支持，属于 UI-only 属性，OpenAPI 里不支持，CLI 不能读取、创建或更新；不要根据接口返回缺失判断未配置

{
  "type": "link",
  "name": "关联任务",
  "link_table": "任务表"
}

双向关联：

{
  "type": "link",
  "name": "关联任务",
  "link_table": "任务表",
  "bidirectional": true,
  "bidirectional_link_field_name": "反向关联"
}

更新时注意：

link 不允许转换为其他类型，其他类型也不能转换为 link。
现有 link 字段的 bidirectional 不能改。

3.9 formula

公式字段；expression 必填。创建/更新前先读 formula-field-guide.md 学习公式语法。

{
  "type": "formula",
  "name": "合计",
  "expression": "1+1"
}

3.10 lookup

查找引用字段；from、select、where 必填，aggregate 可选。创建/更新前先读 lookup-field-guide.md。

支持字段：from、select、where、aggregate

默认值 / 约束：

from、select、where 必填
aggregate 默认 raw_value 代表不进行聚合，直接返回 select 回的原始值
aggregate 可用：raw_value、sum、average、counta、unique_counta、max、min、unique
where.logic 默认 and，仅支持 and / or
where.conditions 至少 1 条
conditions 每项是三元组 [field, op, value?]

{
  "type": "lookup",
  "name": "状态汇总",
  "from": "任务表",
  "select": "状态",
  "where": {
    "logic": "and",
    "conditions": [
      ["负责人", "==", { "type": "field_ref", "field": "当前负责人" }],
      ["状态", "non_empty", null]
    ]
  },
  "aggregate": "raw_value"
}

3.11 auto_number

自动编号字段；创建时不写 style.rules 会使用默认规则：NO.001。更新已有自动编号字段时应显式提交目标 style.rules，因为 +field-update 会把新的编号规则重新应用到已有编号。

最小写法：

{
  "type": "auto_number",
  "name": "编号"
}

支持字段：style.rules

默认值 / 约束：

style.rules 是规则数组，数量 1..9
默认规则：

{
  "style": {
    "rules": [
      { "type": "text", "text": "NO." },
      { "type": "incremental_number", "length": 3 }
    ]
  }
}

`text`

支持字段：text

{ "type": "text", "text": "TASK-" }

`incremental_number`

支持字段：length

默认值 / 约束：

length 取值 1..9

{ "type": "incremental_number", "length": 4 }

`created_time`

支持字段：date_format

默认值 / 约束：

date_format 可用：yyyyMMdd、yyyyMM、yyMM、MMdd、yyyy、MM、dd

{ "type": "created_time", "date_format": "yyyyMMdd" }

自定义规则：

{
  "type": "auto_number",
  "name": "编号",
  "style": {
    "rules": [
      { "type": "text", "text": "TASK-" },
      { "type": "created_time", "date_format": "yyyyMMdd" },
      { "type": "incremental_number", "length": 4 }
    ]
  }
}

3.12 attachment / location / checkbox

{ "type": "attachment", "name": "附件" }

{ "type": "location", "name": "位置" }

写入必须使用 {lng,lat}。location 读回会包含 full_address；筛选和 location -> text 类型转换按 full_address 字符串处理，只有公式能访问坐标。

{ "type": "checkbox", "name": "完成" }

4. 创建与更新

+field-create：按目标字段配置直接构造 --json。
+field-update：使用同样的 JSON 结构，但语义是 PUT；建议先 +field-get，再按目标完整状态提交，并带 --yes。当 type 是 auto_number 时，更新编号规则本身就会把新规则应用到已有编号，无需额外参数，也不要在 JSON 里塞额外的底层实现参数。

5. 暂不支持字段

Object（对象字段）、Button（按钮字段）、Stage（流程字段）暂时都没有被 CLI 支持。这些字段会展示为 not_support 字段并被保护：不允许修改，不允许读取内容。

6. 易错点

select 只有一个类型；不要写 single_select / multi_select，用 multiple 控制是否多选。
number 的精度、货币、进度、评分配置都放在 style 下，不要写顶层 precision。
datetime 是手动日期字段；系统时间请改用 created_at / updated_at。
formula / lookup 没读 guide 前不要直接写。
只有 text、number、静态 select、datetime、user 支持 default_value；清空统一传 "default_value": null。其他字段类型不要配置默认值。

15 KiB Raw Permalink Blame History Unescape Escape

Base field JSON SSOT

1. 顶层规则（必须遵守）

2. 字段速查

3. 各类型写法

3.1 text

3.2 number

plain

currency

progress

rating

3.3 select

静态选项

动态选项

3.4 datetime

3.5 created_at / updated_at

3.6 user / group_chat

3.7 created_by / updated_by

3.8 link

3.9 formula

3.10 lookup

3.11 auto_number

text

incremental_number

created_time

3.12 attachment / location / checkbox

4. 创建与更新

5. 暂不支持字段

6. 易错点

15 KiB

Raw Permalink Blame History

`plain`

`currency`

`progress`

`rating`

`text`

`incremental_number`

`created_time`