Skip to content

docs(lark-base): add known API pitfalls to skill references #266

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

Open
flyinghanger wants to merge 4 commits into
base: main
Choose a base branch
from
+8 −2
Open

docs(lark-base): add known API pitfalls to skill references #266

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
aa3bc0a
docs(lark-base): add known API pitfalls to skill references
flyinghanger Apr 4, 2026
49d8af8
merge: resolve conflict with origin/main, keep upstream wording fix
flyinghanger Apr 4, 2026
8432a8c
docs(lark-base): address review feedback on pitfall discoverability
flyinghanger Apr 4, 2026
7b4122e
docs(lark-base): remove redundant is_primary type pitfall
flyinghanger Apr 7, 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
4 changes: 4 additions & 0 deletions skills/lark-base/references/lark-base-base-create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 索引页
Expand Down
3 changes: 2 additions & 1 deletion 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 @@ -53,7 +53,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
- 如需字段说明，直接传 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。
- `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，再创建。

Expand Down Expand Up @@ -95,6 +95,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields

- ⚠️ 这是写入操作，执行前必须确认。
- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先读对应 guide，再创建。
- ⚠️ `link` 字段只能关联一张固定的表，同一列的不同行无法各自关联到不同的表。若需要不同记录指向不同子表，改用文本字段 + 命名约定。

## 参考

Expand Down
3 changes: 2 additions & 1 deletion 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 @@ -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` 不能改。
Expand Down Expand Up @@ -87,6 +87,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
- ⚠️ 这是全量字段属性更新语义，不是 patch。
- ⚠️ 这是写入操作，执行前必须确认。
- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先阅读对应指南再执行。
- ⚠️ `select` / `multiselect` 类型是全量覆盖：若只想改描述而不动选项，必须先 `+field-get` 拿到完整 `options` 列表一并带回，否则选项会被清空，已有记录的该字段值全部丢失。

## 参考

Expand Down
Loading