Feishu Bitable (多維表格) SKILL

🚨 実行前に必読

• ✅ データテーブルの作成：2 つのモード対応 — ① 要件が明確な場合、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
1 行追加	feishu_bitable_app_table_record	create	app_token, table_id, fields	-
一括インポート	feishu_bitable_app_table_record	batch_create	app_token, table_id, records (≤500)	-
1 行更新	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	-

---

🎯 コア制約（スキーマで開示されていない知識）

📚 詳細参考ドキュメント

フィールド設定、レコード値フォーマット問題に遭遇した場合、または完全な例が必要な場合は、以下のドキュメントを参照してください：

• フィールド Property 設定詳解 - 各フィールドタイプ作成/更新時に必要な property パラメータ構造（単一選択のオプション、進捗状況の 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
    }
  ]
}

フィルター説明：

• 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	添付ファイルが現在のテーブルにアップロードされていない	まずアップロード素材インターフェイスを呼び出し
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 を使用、まずフィールドリストを呼び出して取得が必要