feishu-bitable

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 或本地路径

强制流程：

1. 先调用 feishu_bitable_app_table_field.list 获取字段的 type 和 ui_type
2. 根据上表或 record-values.md 构造正确格式
3. 错误码 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 获取