Feishu Bitable (多维表格) SKILL
🚨 执行前必读
- ✅ 创建数据表:支持两种模式 — ① 明确需求时,在
create 时通过 table.fields 一次性定义字段(减少 API 调用);② 探索式场景时,使用默认表 + 逐步修改字段(更稳定,易调整)
- ⚠️ 默认表的空行坑:
app.create 自带的默认表中会有空记录(空行)!插入数据前建议先调用 feishu_bitable_app_table_record.list + batch_delete 删除空行,避免数据污染
- ✅ 写记录前:先调用
feishu_bitable_app_table_field.list 获取字段 type/ui_type
- ✅ 人员字段:默认 open_id(ou_...),值必须是
[{id:"ou_xxx"}](数组对象)
- ✅ 日期字段:毫秒时间戳(例如
1674206443000),不是秒
- ✅ 单选字段:字符串(例如
"选项1"),不是数组
- ✅ 多选字段:字符串数组(例如
["选项1", "选项2"])
- ✅ 附件字段:必须先上传到当前多维表格,使用返回的 file_token
- ✅ 批量上限:单次 ≤ 500 条,超过需分批(批量操作是原子性的)
- ✅ 并发限制:同一数据表不支持并发写,需串行调用 + 延迟 0.5-1 秒
📋 快速索引:意图 → 工具 → 必填参数
| 用户意图 |
工具 |
action |
必填参数 |
常用可选 |
| 查表有哪些字段 |
feishu_bitable_app_table_field |
list |
app_token, table_id |
- |
| 查记录 |
feishu_bitable_app_table_record |
list |
app_token, table_id |
filter, sort, field_names |
| 新增一行 |
feishu_bitable_app_table_record |
create |
app_token, table_id, fields |
- |
| 批量导入 |
feishu_bitable_app_table_record |
batch_create |
app_token, table_id, records (≤500) |
- |
| 更新一行 |
feishu_bitable_app_table_record |
update |
app_token, table_id, record_id, fields |
- |
| 批量更新 |
feishu_bitable_app_table_record |
batch_update |
app_token, table_id, records (≤500) |
- |
| 创建多维表格 |
feishu_bitable_app |
create |
name |
folder_token |
| 创建数据表 |
feishu_bitable_app_table |
create |
app_token, name |
fields |
| 创建字段 |
feishu_bitable_app_table_field |
create |
app_token, table_id, field_name, type |
property |
| 创建视图 |
feishu_bitable_app_table_view |
create |
app_token, table_id, view_name, view_type |
- |
🎯 核心约束(Schema 未透露的知识)
📚 详细参考文档
当遇到字段配置、记录值格式问题或需要完整示例时,查阅以下文档:
- 字段 Property 配置详解 - 每种字段类型创建/更新时需要的
property 参数结构(单选的 options、进度的 min/max、关联的 table_id 等)
- 记录值数据结构详解 - 每种字段类型在记录中对应的
fields 值格式(人员字段只传 id、日期是毫秒时间戳、附件需先上传等)
- 使用场景完整示例 - 8 个完整场景示例(创建表模式对比、批量导入、筛选查询、附件处理、关联字段等)
何时查阅:
- 创建/更新字段时收到
125408X 错误码(property 结构错误)→ 查 field-properties.md
- 写入记录时收到
125406X 错误码(字段值转换失败)→ 查 record-values.md
- 需要完整的操作流程和参数示例 → 查 examples.md
1. 字段类型与值格式必须严格匹配
Bitable 最大的坑:不同字段类型对 value 的数据结构要求完全不同。
最易错的字段类型(完整列表见 record-values.md)
| type |
ui_type |
字段类型 |
正确格式 |
❌ 常见错误 |
| 11 |
User |
人员 |
[{id: "ou_xxx"}] |
传字符串 "ou_xxx" 或 [{name: "张三"}] |
| 5 |
DateTime |
日期 |
1674206443000(毫秒) |
传秒时间戳或字符串 |
| 3 |
SingleSelect |
单选 |
"选项名" |
传数组 ["选项名"] |
| 4 |
MultiSelect |
多选 |
["选项1", "选项2"] |
传字符串 "选项1" |
| 15 |
Url |
超链接 |
{link: "...", text: "..."} |
只传字符串 URL |
| 17 |
Attachment |
附件 |
[{file_token: "..."}] |
传外部 URL 或本地路径 |
强制流程:
- 先调用
feishu_bitable_app_table_field.list 获取字段的 type 和 ui_type
- 根据上表或 record-values.md 构造正确格式
- 错误码
125406X 或 1254015 → 检查字段值格式
人员字段特别注意:
- 默认使用 open_id(ou_...),与 calendar/task 一致
- 格式:
[{id: "ou_xxx"}](数组对象)
- 只能传 id 字段,不能传 name/email 等
📌 核心使用场景
完整示例: 查阅 examples.md 了解更多场景(创建表模式对比、空行处理、附件上传、关联字段等)
场景 1: 查字段类型(必做第一步)
{
"action": "list",
"app_token": "S404b...",
"table_id": "tbl..."
}
返回:包含每个字段的 field_id、field_name、type、ui_type、property
场景 2: 批量导入客户数据
{
"action": "batch_create",
"app_token": "S404b...",
"table_id": "tbl...",
"records": [
{
"fields": {
"客户名称": "Bytedance",
"负责人": [{"id": "ou_xxx"}],
"签约日期": 1674206443000,
"状态": "进行中"
}
},
{
"fields": {
"客户名称": "飞书",
"负责人": [{"id": "ou_yyy"}],
"签约日期": 1675416243000,
"状态": "已完成"
}
}
]
}
字段值格式:
- 人员:
[{id: "ou_xxx"}](数组对象)
- 日期:毫秒时间戳
- 单选:字符串
- 多选:字符串数组
限制: 最多 500 条记录
场景 3: 筛选查询(高级筛选)
{
"action": "list",
"app_token": "S404b...",
"table_id": "tbl...",
"filter": {
"conjunction": "and",
"conditions": [
{
"field_name": "状态",
"operator": "is",
"value": ["进行中"]
},
{
"field_name": "截止日期",
"operator": "isLess",
"value": ["ExactDate", "1740441600000"]
}
]
},
"sort": [
{
"field_name": "截止日期",
"desc": false
}
]
}
filter 说明:
- 支持 10 种 operator(is/isNot/contains/isEmpty 等,见附录 C)
- ⚠️ isEmpty/isNotEmpty 必须传
value: [](虽然逻辑上不需要值,但 API 要求必须传空数组)
- 日期筛选可使用
["Today"]、["ExactDate", "时间戳"] 等
sort 可指定多个排序字段
🔍 常见错误与排查
| 错误码 |
错误现象 |
根本原因 |
解决方案 |
| 1254064 |
DatetimeFieldConvFail |
日期字段格式错误 |
必须用毫秒时间戳(如 1772121600000),不能用字符串("2026-02-27"、RFC3339)或秒级时间戳 |
| 1254068 |
URLFieldConvFail |
超链接字段格式错误 |
必须用对象 {text: "显示文本", link: "URL"},不能直接传字符串 URL |
| 1254066 |
UserFieldConvFail |
人员字段格式错误或 ID 类型不匹配 |
必须传 [{id: "ou_xxx"}],确认 user_id_type |
| 1254015 |
Field types do not match |
字段值格式与类型不匹配 |
先 list 字段,按类型构造正确格式 |
| 1254104 |
RecordAddOnceExceedLimit |
批量创建超过 500 条 |
分批调用,每批 ≤ 500 |
| 1254291 |
Write conflict |
并发写冲突 |
串行调用 + 延迟 0.5-1 秒 |
| 1254303 |
AttachPermNotAllow |
附件未上传到当前表格 |
先调用上传素材接口 |
| 1254045 |
FieldNameNotFound |
字段名不存在 |
检查字段名(包括空格、大小写) |
📚 附录:背景知识
A. 资源层级关系
App (多维表格应用)
├── Table (数据表) ×100
│ ├── Record (记录/行) ×20,000
│ ├── Field (字段/列) ×300
│ └── View (视图) ×200
└── Dashboard (仪表盘)
B. 筛选条件 operator 列表
| operator |
含义 |
支持字段 |
value 要求 |
is |
等于 |
所有 |
单个值 |
isNot |
不等于 |
除日期外 |
单个值 |
contains |
包含 |
除日期外 |
可多个值 |
doesNotContain |
不包含 |
除日期外 |
可多个值 |
isEmpty |
为空 |
所有 |
必须为 [] |
isNotEmpty |
不为空 |
所有 |
必须为 [] |
isGreater |
大于 |
数字、日期 |
单个值 |
isGreaterEqual |
大于等于 |
数字(不支持日期) |
单个值 |
isLess |
小于 |
数字、日期 |
单个值 |
isLessEqual |
小于等于 |
数字(不支持日期) |
单个值 |
日期字段特殊值: ["Today"], ["Tomorrow"], ["ExactDate", "时间戳"] 等(完整列表见 examples.md)
C. 使用限制
| 限制项 |
上限 |
| 数据表 + 仪表盘 |
100(单个 App) |
| 记录数 |
20,000(单个数据表) |
| 字段数 |
300(单个数据表) |
| 视图数 |
200(单个数据表) |
| 批量创建/更新/删除 |
500(单次 API 调用) |
| 单元格文本 |
10 万字符 |
| 单选/多选选项 |
20,000(单个字段) |
| 单元格附件 |
100 |
| 单元格人员 |
1,000 |
D. 其他约束
- 从其他数据源同步的数据表,不支持增删改记录
- 公式字段、查看引用字段是只读的
- 删除操作无法恢复
- 视图筛选条件使用
field_id,需先调用 field.list 获取
1---
2name: feishu-bitable
3description: |
4 飞书多维表格(Bitable)的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。
5
6 **当以下情况时使用此 Skill**:
7 (1) 需要创建或管理飞书多维表格 App
8 (2) 需要在多维表格中新增、查询、修改、删除记录(行数据)
9 (3) 需要管理字段(列)、视图、数据表
10 (4) 用户提到"多维表格"、"bitable"、"数据表"、"记录"、"字段"
11 (5) 需要批量导入数据或批量更新多维表格
12tag: office-collab
13icon: Table2
14source: official
15prompt: Help me manage Feishu Bitable databases
16examples:
17 - 帮我创建一个客户管理的多维表格
18 - 查询多维表格中状态为"进行中"的记录
19 - 批量导入数据到多维表格
20requires:
21 plugins:
22 - "@larksuite/openclaw-lark"
23metadata:
24 source: https://skillmd.com/skills/nexu-io/feishu-bitable
25---
26
27# Feishu Bitable (多维表格) SKILL
28
29## 🚨 执行前必读
30
31- ✅ **创建数据表**:支持两种模式 — ① 明确需求时,在 `create` 时通过 `table.fields` 一次性定义字段(减少 API 调用);② 探索式场景时,使用默认表 + 逐步修改字段(更稳定,易调整)
32- ⚠️ **默认表的空行坑**:`app.create` 自带的默认表中会有空记录(空行)!插入数据前建议先调用 `feishu_bitable_app_table_record.list` + `batch_delete` 删除空行,避免数据污染
33- ✅ **写记录前**:先调用 `feishu_bitable_app_table_field.list` 获取字段 type/ui_type
34- ✅ **人员字段**:默认 open_id(ou_...),值必须是 `[{id:"ou_xxx"}]`(数组对象)
35- ✅ **日期字段**:毫秒时间戳(例如 `1674206443000`),不是秒
36- ✅ **单选字段**:字符串(例如 `"选项1"`),不是数组
37- ✅ **多选字段**:字符串数组(例如 `["选项1", "选项2"]`)
38- ✅ **附件字段**:必须先上传到当前多维表格,使用返回的 file_token
39- ✅ **批量上限**:单次 ≤ 500 条,超过需分批(批量操作是原子性的)
40- ✅ **并发限制**:同一数据表不支持并发写,需串行调用 + 延迟 0.5-1 秒
41
42---
43
44## 📋 快速索引:意图 → 工具 → 必填参数
45
46| 用户意图 | 工具 | action | 必填参数 | 常用可选 |
47|---------|------|--------|---------|---------|
48| 查表有哪些字段 | feishu_bitable_app_table_field | list | app_token, table_id | - |
49| 查记录 | feishu_bitable_app_table_record | list | app_token, table_id | filter, sort, field_names |
50| 新增一行 | feishu_bitable_app_table_record | create | app_token, table_id, fields | - |
51| 批量导入 | feishu_bitable_app_table_record | batch_create | app_token, table_id, records (≤500) | - |
52| 更新一行 | feishu_bitable_app_table_record | update | app_token, table_id, record_id, fields | - |
53| 批量更新 | feishu_bitable_app_table_record | batch_update | app_token, table_id, records (≤500) | - |
54| 创建多维表格 | feishu_bitable_app | create | name | folder_token |
55| 创建数据表 | feishu_bitable_app_table | create | app_token, name | fields |
56| 创建字段 | feishu_bitable_app_table_field | create | app_token, table_id, field_name, type | property |
57| 创建视图 | feishu_bitable_app_table_view | create | app_token, table_id, view_name, view_type | - |
58
59---
60
61## 🎯 核心约束(Schema 未透露的知识)
62
63### 📚 详细参考文档
64
65**当遇到字段配置、记录值格式问题或需要完整示例时,查阅以下文档**:
66
67- **[字段 Property 配置详解](references/field-properties.md)** - 每种字段类型创建/更新时需要的 `property` 参数结构(单选的 options、进度的 min/max、关联的 table_id 等)
68- **[记录值数据结构详解](references/record-values.md)** - 每种字段类型在记录中对应的 `fields` 值格式(人员字段只传 id、日期是毫秒时间戳、附件需先上传等)
69- **[使用场景完整示例](references/examples.md)** - 8 个完整场景示例(创建表模式对比、批量导入、筛选查询、附件处理、关联字段等)
70
71**何时查阅**:
72- 创建/更新字段时收到 `125408X` 错误码(property 结构错误)→ 查 field-properties.md
73- 写入记录时收到 `125406X` 错误码(字段值转换失败)→ 查 record-values.md
74- 需要完整的操作流程和参数示例 → 查 examples.md
75
76---
77
78### 1. 字段类型与值格式必须严格匹配
79
80**Bitable 最大的坑**:不同字段类型对 value 的数据结构要求完全不同。
81
82#### 最易错的字段类型(完整列表见 [record-values.md](references/record-values.md))
83
84| type | ui_type | 字段类型 | 正确格式 | ❌ 常见错误 |
85|------|---------|----------|---------|-----------|
86| 11 | User | 人员 | `[{id: "ou_xxx"}]` | 传字符串 `"ou_xxx"` 或 `[{name: "张三"}]` |
87| 5 | DateTime | 日期 | `1674206443000`(毫秒) | 传秒时间戳或字符串 |
88| 3 | SingleSelect | 单选 | `"选项名"` | 传数组 `["选项名"]` |
89| 4 | MultiSelect | 多选 | `["选项1", "选项2"]` | 传字符串 `"选项1"` |
90| 15 | Url | 超链接 | `{link: "...", text: "..."}` | 只传字符串 URL |
91| 17 | Attachment | 附件 | `[{file_token: "..."}]` | 传外部 URL 或本地路径 |
92
93**强制流程**:
941. 先调用 `feishu_bitable_app_table_field.list` 获取字段的 `type` 和 `ui_type`
952. 根据上表或 [record-values.md](references/record-values.md) 构造正确格式
963. 错误码 `125406X` 或 `1254015` → 检查字段值格式
97
98**人员字段特别注意**:
99- 默认使用 open_id(ou_...),与 calendar/task 一致
100- 格式:`[{id: "ou_xxx"}]`(数组对象)
101- **只能传 id 字段**,不能传 name/email 等
102
103
104## 📌 核心使用场景
105
106> **完整示例**: 查阅 [examples.md](references/examples.md) 了解更多场景(创建表模式对比、空行处理、附件上传、关联字段等)
107
108### 场景 1: 查字段类型(必做第一步)
109
110```json
111{
112 "action": "list",
113 "app_token": "S404b...",
114 "table_id": "tbl..."
115}
116```
117
118**返回**:包含每个字段的 `field_id`、`field_name`、`type`、`ui_type`、`property`
119
120### 场景 2: 批量导入客户数据
121
122```json
123{
124 "action": "batch_create",
125 "app_token": "S404b...",
126 "table_id": "tbl...",
127 "records": [
128 {
129 "fields": {
130 "客户名称": "Bytedance",
131 "负责人": [{"id": "ou_xxx"}],
132 "签约日期": 1674206443000,
133 "状态": "进行中"
134 }
135 },
136 {
137 "fields": {
138 "客户名称": "飞书",
139 "负责人": [{"id": "ou_yyy"}],
140 "签约日期": 1675416243000,
141 "状态": "已完成"
142 }
143 }
144 ]
145}
146```
147
148**字段值格式**:
149- 人员:`[{id: "ou_xxx"}]`(数组对象)
150- 日期:毫秒时间戳
151- 单选:字符串
152- 多选:字符串数组
153
154**限制**: 最多 500 条记录
155
156### 场景 3: 筛选查询(高级筛选)
157
158```json
159{
160 "action": "list",
161 "app_token": "S404b...",
162 "table_id": "tbl...",
163 "filter": {
164 "conjunction": "and",
165 "conditions": [
166 {
167 "field_name": "状态",
168 "operator": "is",
169 "value": ["进行中"]
170 },
171 {
172 "field_name": "截止日期",
173 "operator": "isLess",
174 "value": ["ExactDate", "1740441600000"]
175 }
176 ]
177 },
178 "sort": [
179 {
180 "field_name": "截止日期",
181 "desc": false
182 }
183 ]
184}
185```
186
187**filter 说明**:
188- 支持 10 种 operator(is/isNot/contains/isEmpty 等,见附录 C)
189- ⚠️ **isEmpty/isNotEmpty 必须传 `value: []`**(虽然逻辑上不需要值,但 API 要求必须传空数组)
190- 日期筛选可使用 `["Today"]`、`["ExactDate", "时间戳"]` 等
191- `sort` 可指定多个排序字段
192
193---
194
195## 🔍 常见错误与排查
196
197| 错误码 | 错误现象 | 根本原因 | 解决方案 |
198|--------|---------|---------|---------|
199| 1254064 | DatetimeFieldConvFail | 日期字段格式错误 | **必须用毫秒时间戳**(如 `1772121600000`),不能用字符串(`"2026-02-27"`、RFC3339)或秒级时间戳 |
200| 1254068 | URLFieldConvFail | 超链接字段格式错误 | **必须用对象** `{text: "显示文本", link: "URL"}`,不能直接传字符串 URL |
201| 1254066 | UserFieldConvFail | 人员字段格式错误或 ID 类型不匹配 | 必须传 `[{id: "ou_xxx"}]`,确认 `user_id_type` |
202| 1254015 | Field types do not match | 字段值格式与类型不匹配 | 先 list 字段,按类型构造正确格式 |
203| 1254104 | RecordAddOnceExceedLimit | 批量创建超过 500 条 | 分批调用,每批 ≤ 500 |
204| 1254291 | Write conflict | 并发写冲突 | 串行调用 + 延迟 0.5-1 秒 |
205| 1254303 | AttachPermNotAllow | 附件未上传到当前表格 | 先调用上传素材接口 |
206| 1254045 | FieldNameNotFound | 字段名不存在 | 检查字段名(包括空格、大小写) |
207
208---
209
210## 📚 附录:背景知识
211
212### A. 资源层级关系
213
214```
215App (多维表格应用)
216 ├── Table (数据表) ×100
217 │ ├── Record (记录/行) ×20,000
218 │ ├── Field (字段/列) ×300
219 │ └── View (视图) ×200
220 └── Dashboard (仪表盘)
221```
222
223### B. 筛选条件 operator 列表
224
225| operator | 含义 | 支持字段 | value 要求 |
226|----------|------|----------|-----------|
227| `is` | 等于 | 所有 | 单个值 |
228| `isNot` | 不等于 | 除日期外 | 单个值 |
229| `contains` | 包含 | 除日期外 | 可多个值 |
230| `doesNotContain` | 不包含 | 除日期外 | 可多个值 |
231| `isEmpty` | 为空 | 所有 | 必须为 `[]` |
232| `isNotEmpty` | 不为空 | 所有 | 必须为 `[]` |
233| `isGreater` | 大于 | 数字、日期 | 单个值 |
234| `isGreaterEqual` | 大于等于 | 数字(不支持日期) | 单个值 |
235| `isLess` | 小于 | 数字、日期 | 单个值 |
236| `isLessEqual` | 小于等于 | 数字(不支持日期) | 单个值 |
237
238**日期字段特殊值**: `["Today"]`, `["Tomorrow"]`, `["ExactDate", "时间戳"]` 等(完整列表见 [examples.md](references/examples.md#场景-3-筛选查询高级筛选))
239
240### C. 使用限制
241
242| 限制项 | 上限 |
243|--------|------|
244| 数据表 + 仪表盘 | 100(单个 App) |
245| 记录数 | 20,000(单个数据表) |
246| 字段数 | 300(单个数据表) |
247| 视图数 | 200(单个数据表) |
248| 批量创建/更新/删除 | 500(单次 API 调用) |
249| 单元格文本 | 10 万字符 |
250| 单选/多选选项 | 20,000(单个字段) |
251| 单元格附件 | 100 |
252| 单元格人员 | 1,000 |
253
254
255
256### D. 其他约束
257
258- 从其他数据源同步的数据表,**不支持增删改**记录
259- 公式字段、查看引用字段是**只读**的
260- 删除操作**无法恢复**
261- 视图筛选条件使用 `field_id`,需先调用 field.list 获取