From aa3bc0a9db0a0959281355555bc6cf205bc12031 Mon Sep 17 00:00:00 2001 From: flyinghanger Date: Sat, 4 Apr 2026 23:14:41 +0800 Subject: [PATCH 1/3] docs(lark-base): add known API pitfalls to skill references Three gotchas verified in production that were not documented: - base-create: default table contains empty records; clean them before writing data to avoid dirty rows - field-update: updating primary field (is_primary) requires explicit `type` in JSON or API returns 99992402; select/multiselect options are fully overwritten on PUT so existing options must be included - field-create: link field is bound to one fixed table per column; different rows cannot point to different tables --- skills/lark-base/references/lark-base-base-create.md | 4 ++++ skills/lark-base/references/lark-base-field-create.md | 2 +- skills/lark-base/references/lark-base-field-update.md | 2 ++ 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/skills/lark-base/references/lark-base-base-create.md b/skills/lark-base/references/lark-base-base-create.md index 6c910ebb..657f39c9 100644 --- a/skills/lark-base/references/lark-base-base-create.md +++ b/skills/lark-base/references/lark-base-base-create.md @@ -67,6 +67,10 @@ POST /open-apis/base/v3/bases 2. `--folder-token`、`--time-zone` 都是可选项；用户没要求时不要为此额外追问。 3. 创建成功后，整理并返回：Base 名称、token，以及响应中已有的可访问链接。 +## 坑点 + +- ⚠️ 创建 Base 时会自动生成一张默认表，表内含有空记录。如需写入数据，应先用 `+record-list` 查出空行的 record_id，再用 `+record-delete --yes` 清理，避免脏数据。 + ## 参考 - [lark-base-workspace.md](lark-base-workspace.md) — base / workspace 索引页 diff --git a/skills/lark-base/references/lark-base-field-create.md b/skills/lark-base/references/lark-base-field-create.md index 75e6b0f9..6390fb3f 100644 --- a/skills/lark-base/references/lark-base-field-create.md +++ b/skills/lark-base/references/lark-base-field-create.md @@ -48,7 +48,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields - 顶层最少包含：`name`、`type`。 - `type` 不同，必填子字段不同： - `select`：用 `multiple` + `options`（`options` 里只传 `name/hue/lightness`，不要传 `id`）。 - - `link`：必须有 `link_table`，可选 `bidirectional`、`bidirectional_link_field_name`。 + - `link`：必须有 `link_table`，可选 `bidirectional`、`bidirectional_link_field_name`。**一个 `link` 字段只能关联一张固定的表**，同一列的不同行无法各自关联到不同的表。若主表的不同记录需要指向不同子表，不要用 `link` 字段，改用命名约定（如用文本字段记录子表名）。 - `formula`：必须有 `expression`；先读 formula guide，再创建。 - `lookup`：必须有 `from`、`select`、`where`；先读 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 f010738b..425667cc 100644 --- a/skills/lark-base/references/lark-base-field-update.md +++ b/skills/lark-base/references/lark-base-field-update.md @@ -70,6 +70,8 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id - ⚠️ 这是全量字段属性更新语义，不是 patch。 - ⚠️ 这是写入操作，执行前必须确认。 - ⚠️ 当 `--json.type` 是 `formula` 或 `lookup` 时，先阅读对应指南再执行。 +- ⚠️ 更新主索引列（`is_primary: true` 的字段）时必须在 `--json` 中显式带上 `type`，否则报 `99992402 field validation failed`。 +- ⚠️ `select` / `multiselect` 类型是全量覆盖：若只想改描述而不动选项，必须先 `+field-get` 拿到完整 `options` 列表一并带回，否则选项会被清空，已有记录的该字段值全部丢失。 ## 参考 From 8432a8c44ce01a3b158a260531535cc19a3e35d2 Mon Sep 17 00:00:00 2001 From: flyinghanger Date: Sat, 4 Apr 2026 23:26:27 +0800 Subject: [PATCH 2/3] docs(lark-base): address review feedback on pitfall discoverability MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - field-create: echo link constraint in 坑点 section (not just inline) - field-update: add inline hint (全量覆盖，漏传即清空) to select spec --- skills/lark-base/references/lark-base-field-create.md | 1 + skills/lark-base/references/lark-base-field-update.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/skills/lark-base/references/lark-base-field-create.md b/skills/lark-base/references/lark-base-field-create.md index 11a45d27..59388b05 100644 --- a/skills/lark-base/references/lark-base-field-create.md +++ b/skills/lark-base/references/lark-base-field-create.md @@ -95,6 +95,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields - ⚠️ 这是写入操作，执行前必须确认。 - ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先读对应 guide，再创建。 +- ⚠️ `link` 字段只能关联一张固定的表，同一列的不同行无法各自关联到不同的表。若需要不同记录指向不同子表，改用文本字段 + 命名约定。 ## 参考 diff --git a/skills/lark-base/references/lark-base-field-update.md b/skills/lark-base/references/lark-base-field-update.md index ac13d86e..f75ab798 100644 --- a/skills/lark-base/references/lark-base-field-update.md +++ b/skills/lark-base/references/lark-base-field-update.md @@ -41,7 +41,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` 仍按对象数组传，避免混入无效字段。 +- `select` 更新时：`options` 仍按对象数组传，避免混入无效字段（全量覆盖，漏传即清空）。 - `link` 更新限制： - 不能把非 `link` 字段改成 `link`，也不能把 `link` 改成非 `link`。 - 现有 `link` 字段的 `bidirectional` 不能改。 From 7b4122e1cbbb087446006eb9a175a15806dc940a Mon Sep 17 00:00:00 2001 From: flyinghanger Date: Tue, 7 Apr 2026 14:30:04 +0800 Subject: [PATCH 3/3] docs(lark-base): remove redundant is_primary type pitfall MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per maintainer feedback: type is required for all field updates and already covered by the existing JSON value spec ("至少显式包含 name、type"), so the is_primary-specific bullet was redundant. --- skills/lark-base/references/lark-base-field-update.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/lark-base/references/lark-base-field-update.md b/skills/lark-base/references/lark-base-field-update.md index f75ab798..64d6316f 100644 --- a/skills/lark-base/references/lark-base-field-update.md +++ b/skills/lark-base/references/lark-base-field-update.md @@ -87,7 +87,6 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id - ⚠️ 这是全量字段属性更新语义，不是 patch。 - ⚠️ 这是写入操作，执行前必须确认。 - ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先阅读对应指南再执行。 -- ⚠️ 更新主索引列（`is_primary: true` 的字段）时必须在 `--json` 中显式带上 `type`，否则报 `99992402 field validation failed`。 - ⚠️ `select` / `multiselect` 类型是全量覆盖：若只想改描述而不动选项，必须先 `+field-get` 拿到完整 `options` 列表一并带回，否则选项会被清空，已有记录的该字段值全部丢失。 ## 参考