feishu-bitable

Feishu Bitable Skill

Must-read before execution

• Before writing records: first call field list to get field type/ui_type, otherwise formatting is very error-prone
• Pitfall of empty rows in the default table：app create The default table included with it contains empty records! Before inserting data, first record list + record batch_delete clear
• Person field: default open_id (ou_...), the value must be [{id:"ou_xxx"}](array of objects)
• Date field: millisecond timestamp (for example 1674206443000), not seconds
• Single select field: string (for example "选项1"), not an array
• Multi select field: array of strings (for example ["选项1", "选项2"]）
• Attachment field: must first be uploaded to the current Bitable, use the returned file_token
• Batch limit: ≤ 500 per call, exceeding requires batching
• Concurrency limit: concurrent writes are not supported for the same data table, calls must be serial

---

Quick index: intent → tool call

⚠️ Actions supported by the CLI(marked ✅) can be called directly with python3 skills/feishu-cli/run.py ; unmarked ones require switching to api raw call.

User intent	module	tool_action	Required parameters	Common optional
✅ Check which fields the table has	bitable	list_fields	app_token, table_id	-
✅ Query records	bitable	list_records	app_token, table_id	filter, sort, field_names
✅ Add a row	bitable	create_record	app_token, table_id, fields	-
✅ Update a row	bitable	update_record	app_token, table_id, record_id, fields	-
✅ Delete records	bitable	delete_record	app_token, table_id, record_id	-
✅ View all tables	bitable	list_tables	app_token	-
🔧 Batch import	api	POST /bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_create	records (≤500)	-
🔧 Batch update	api	PUT /bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_update	records (≤500)	-
🔧 Create Bitable	api	POST /bitable/v1/apps	name	folder_token
🔧 Create data table	api	POST /bitable/v1/apps/{app_token}/tables	name	fields

How to call

python3 skills/feishu-cli/run.py '{"action":"tool","module":"bitable","tool_action":"list_records","app_token":"S404b...","table_id":"tbl..."}'

---

Core constraints (knowledge not revealed by the Schema)

Detailed reference documents

When encountering field configuration or record value format issues, or when complete examples are needed, consult the following documents：

• Detailed explanation of field Property configuration — when creating/updating each field type, the property parameter structure
• Detailed explanation of record value data structure — for each field type in a record, the corresponding fields value format
• Complete examples for usage scenarios — complete scenario examples

When to consult:

• When creating/updating fields and receiving 125408X error code → consult field-properties.md
• When writing records and receiving 125406X error code → consult record-values.md
• When complete operation flows and parameter examples are needed → consult examples.md

---

Field types and value formats must strictly match

type	ui_type	Field type	Correct format	Common errors
11	User	Person	[{id: "ou_xxx"}]	Passing a string or [{name: "张三"}]
5	DateTime	Date	1674206443000(milliseconds)	Passing a second timestamp or string
3	SingleSelect	Single select	"选项名"	Passing an array ["选项名"]
4	MultiSelect	Multi select	["选项1", "选项2"]	Passing a string
15	Url	Hyperlink	{link: "...", text: "..."}	Pass only a string URL
17	Attachment	Attachment	[{file_token: "..."}]	Pass an external URL

Mandatory process：

1. First call list_fields to get the field's type and ui_type
2. Construct the correct format according to the table above or record-values.md
3. Error code 125406X or 1254015 → Check the field value format

---

Filter query (advanced filter)

filter parameter example:

{
  "conjunction": "and",
  "conditions": [
    {"field_name": "状态", "operator": "is", "value": ["进行中"]},
    {"field_name": "截止日期", "operator": "isLess", "value": ["ExactDate", "1740441600000"]}
  ]
}

filter operator list：

operator	Meaning	value requirement
is	equals	single value
isNot	not equals	single value
contains	contains	can be multiple values
doesNotContain	does not contain	can be multiple values
isEmpty	is empty	must be []
isNotEmpty	is not empty	must be []
isGreater	greater than	single value
isLess	less than	single value

Date field special values: ["Today"], ["Tomorrow"], ["ExactDate", "毫秒时间戳"]

---

Common errors and troubleshooting

Error code	Cause	Solution
1254064	Date format error	Must use a millisecond timestamp; cannot use a string or a second timestamp
1254068	Hyperlink format error	Must use {text, link} object
1254066	Person field format error	Must pass [{id: "ou_xxx"}]
1254015	Field value does not match the type	First list_fields, then construct according to the type
1254104	Batch exceeds 500 records	Call in batches
1254291	Concurrent write conflict	Call serially + delay 0.5-1 second
1254045	Field name does not exist	Check the field name (including spaces and capitalization)

---

Resource hierarchy and limits

App (多维表格应用)
 ├── Table (数据表) ×100
 │    ├── Record (记录/行) ×20,000
 │    ├── Field (字段/列) ×300
 │    └── View (视图) ×200
 └── Dashboard (仪表盘)

Limit item	Upper limit
Batch create/update/delete	500 (single request)
Cell text	100,000 characters
Single-select/multi-select options	20,000/field