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	フィールド値の形式と型が一致していません	まずフィールドを一覧表示し、型に応じて正しい形式を構成してください
1254104	RecordAddOnceExceedLimit	一括作成が 500 件を超えています	複数回に分けて呼び出し、1 回あたり ≤ 500 件にしてください
1254291	Write conflict	同時書き込みの競合です	逐次呼び出し、0.5〜1 秒の間隔を空けてください
1254303	AttachPermNotAllow	添付ファイルが現在のテーブルにアップロードされていません	先に素材アップロード API を呼び出してください
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（1 回の API 呼び出し）
セルのテキスト	10 万文字
単一選択／複数選択のオプション	20,000（単一のフィールド）
セルの添付ファイル	100
セルのユーザー	1,000

D. その他の制約

• 他のデータソースから同期されたデータテーブルでは、レコードの追加・削除・変更はサポートされていません
• 数式フィールドと参照フィールドは読み取り専用です
• 削除操作は元に戻せません
• ビューのフィルター条件では field_id を使用します。先に field.list を呼び出して取得してください